| Message ID | 20210223105146.6695-1-alex.bennee@linaro.org |
|---|---|
| State | New |
| Headers | show |
| Series | [RFC] docs/devel: re-organise the developers guide into sections | expand |
On Tue, 23 Feb 2021 at 10:51, Alex Bennée <alex.bennee@linaro.org> wrote: > > The list of sub-sections was getting a bit long and sporadically > organised. Let's try and impose some order on this hairball of > documentation. Yeah, the 'devel' section has always been just a grab-bag of whatever docs we had to hand. On the other hand, to my mind it is the area of the documentation that is least in need of much effort, because it's only for developers, not for the much wider group of end-users. Anyways, a bit more structure certainly doesn't hurt. > [AJB: RFC because I wonder if we should make a more concerted effort > to move bits of the wiki into a canonical maintained document. There > is also probably a need for a quickbuild or tldr section of the > build-system for users who just want to build something.] 'How to build' is in README.rst. We don't want that in the devel/ section, because we describe 'devel' as "You only need to read it if you are interested in reading or modifying QEMU’s source code". > diff --git a/docs/devel/section-apis.rst b/docs/devel/section-apis.rst > new file mode 100644 > index 0000000000..ab1f6bed60 > --- /dev/null > +++ b/docs/devel/section-apis.rst > @@ -0,0 +1,16 @@ > +********* > +QEMU APIs > +********* > + > +There are a number of APIs in QEMU and the following sections document > +some of the most important ones. For tose that aren't documented here > +you can also find notes on usage in the header definitions. "those" -- PMM
On Tue, Feb 23, 2021 at 10:51:46AM +0000, Alex Bennée wrote: > The list of sub-sections was getting a bit long and sporadically > organised. Let's try and impose some order on this hairball of > documentation. > > [AJB: RFC because I wonder if we should make a more concerted effort > to move bits of the wiki into a canonical maintained document. There > is also probably a need for a quickbuild or tldr section of the > build-system for users who just want to build something.] > > Based-on: 20210223095931.16908-1-alex.bennee@linaro.org > Signed-off-by: Alex Bennée <alex.bennee@linaro.org> > --- > docs/devel/index.rst | 32 ++++++---------------------- > docs/devel/multi-thread-tcg.rst | 5 +++-- > docs/devel/section-apis.rst | 16 ++++++++++++++ > docs/devel/section-building.rst | 13 +++++++++++ > docs/devel/section-concepts.rst | 21 ++++++++++++++++++ > docs/devel/section-process.rst | 11 ++++++++++ > docs/devel/section-tcg-emulation.rst | 19 +++++++++++++++++ > docs/devel/section-testing.rst | 20 +++++++++++++++++ > docs/devel/tcg-icount.rst | 6 +++--- > docs/devel/testing.rst | 6 +++--- > 10 files changed, 115 insertions(+), 34 deletions(-) > create mode 100644 docs/devel/section-apis.rst > create mode 100644 docs/devel/section-building.rst > create mode 100644 docs/devel/section-concepts.rst > create mode 100644 docs/devel/section-process.rst > create mode 100644 docs/devel/section-tcg-emulation.rst > create mode 100644 docs/devel/section-testing.rst Acked-by: Stefan Hajnoczi <stefanha@redhat.com>
Hi, On 2/23/21 7:51 AM, Alex Bennée wrote: > The list of sub-sections was getting a bit long and sporadically > organised. Let's try and impose some order on this hairball of > documentation. > > [AJB: RFC because I wonder if we should make a more concerted effort > to move bits of the wiki into a canonical maintained document. There > is also probably a need for a quickbuild or tldr section of the > build-system for users who just want to build something.] > > Based-on: 20210223095931.16908-1-alex.bennee@linaro.org > Signed-off-by: Alex Bennée <alex.bennee@linaro.org> > --- > docs/devel/index.rst | 32 ++++++---------------------- > docs/devel/multi-thread-tcg.rst | 5 +++-- > docs/devel/section-apis.rst | 16 ++++++++++++++ > docs/devel/section-building.rst | 13 +++++++++++ > docs/devel/section-concepts.rst | 21 ++++++++++++++++++ > docs/devel/section-process.rst | 11 ++++++++++ > docs/devel/section-tcg-emulation.rst | 19 +++++++++++++++++ > docs/devel/section-testing.rst | 20 +++++++++++++++++ > docs/devel/tcg-icount.rst | 6 +++--- > docs/devel/testing.rst | 6 +++--- > 10 files changed, 115 insertions(+), 34 deletions(-) > create mode 100644 docs/devel/section-apis.rst > create mode 100644 docs/devel/section-building.rst > create mode 100644 docs/devel/section-concepts.rst > create mode 100644 docs/devel/section-process.rst > create mode 100644 docs/devel/section-tcg-emulation.rst > create mode 100644 docs/devel/section-testing.rst > > diff --git a/docs/devel/index.rst b/docs/devel/index.rst > index ae664da00c..2af7bf8736 100644 > --- a/docs/devel/index.rst > +++ b/docs/devel/index.rst > @@ -13,29 +13,9 @@ Contents: > .. toctree:: > :maxdepth: 2 > > - build-system > - style > - kconfig > - testing > - fuzzing > - control-flow-integrity > - loads-stores > - memory > - migration > - atomics > - stable-process > - qtest > - decodetree > - secure-coding-practices > - tcg > - tcg-icount > - tracing > - multi-thread-tcg > - tcg-plugins > - bitops > - reset > - s390-dasd-ipl > - clocks > - qom > - block-coroutine-wrapper > - multi-process > + section-building > + section-testing > + section-concepts > + section-apis > + section-tcg-emulation > + section-process Just a fyi... yesterday I realized that the (current) TOC is not getting rendered on my Firefox (or chrome) browser: https://gitlab.com/qemu-project/qemu/-/tree/master/docs/devel - Wainer > diff --git a/docs/devel/multi-thread-tcg.rst b/docs/devel/multi-thread-tcg.rst > index 92a9eba13c..5b446ee08b 100644 > --- a/docs/devel/multi-thread-tcg.rst > +++ b/docs/devel/multi-thread-tcg.rst > @@ -4,8 +4,9 @@ > This work is licensed under the terms of the GNU GPL, version 2 or > later. See the COPYING file in the top-level directory. > > -Introduction > -============ > +================== > +Multi-threaded TCG > +================== > > This document outlines the design for multi-threaded TCG (a.k.a MTTCG) > system-mode emulation. user-mode emulation has always mirrored the > diff --git a/docs/devel/section-apis.rst b/docs/devel/section-apis.rst > new file mode 100644 > index 0000000000..ab1f6bed60 > --- /dev/null > +++ b/docs/devel/section-apis.rst > @@ -0,0 +1,16 @@ > +********* > +QEMU APIs > +********* > + > +There are a number of APIs in QEMU and the following sections document > +some of the most important ones. For tose that aren't documented here > +you can also find notes on usage in the header definitions. > + > +.. toctree:: > + :maxdepth: 2 > + > + atomics > + bitops > + loads-stores > + memory > + tracing > diff --git a/docs/devel/section-building.rst b/docs/devel/section-building.rst > new file mode 100644 > index 0000000000..e6e9fa1d6a > --- /dev/null > +++ b/docs/devel/section-building.rst > @@ -0,0 +1,13 @@ > +************* > +Building QEMU > +************* > + > +The following sections deal with how the build system works, how it is > +configured and some basic guidance on how code should be written. > + > +.. toctree:: > + :maxdepth: 2 > + > + build-system > + kconfig > + style > diff --git a/docs/devel/section-concepts.rst b/docs/devel/section-concepts.rst > new file mode 100644 > index 0000000000..566c52e90a > --- /dev/null > +++ b/docs/devel/section-concepts.rst > @@ -0,0 +1,21 @@ > +************* > +QEMU Concepts > +************* > + > +There are a number of high level concepts that are useful to > +understand when working with the code base. Perhaps the most pervasive > +is the QEMU Object Model (QOM) which underpins much of the flexibility > +and configurable of the project. The following sections document that > +as well as diving into other concepts that are useful to know if > +working on some areas of the code. > + > +.. toctree:: > + :maxdepth: 2 > + > + qom > + clocks > + reset > + block-coroutine-wrapper > + migration > + multi-process > + s390-dasd-ipl > diff --git a/docs/devel/section-process.rst b/docs/devel/section-process.rst > new file mode 100644 > index 0000000000..3b0ae4f19b > --- /dev/null > +++ b/docs/devel/section-process.rst > @@ -0,0 +1,11 @@ > +=================== > +Development Process > +=================== > + > +The following sections detail aspects of the development process. > + > +.. toctree:: > + :maxdepth: 2 > + > + secure-coding-practices > + stable-process > diff --git a/docs/devel/section-tcg-emulation.rst b/docs/devel/section-tcg-emulation.rst > new file mode 100644 > index 0000000000..81fa131de7 > --- /dev/null > +++ b/docs/devel/section-tcg-emulation.rst > @@ -0,0 +1,19 @@ > +************* > +TCG Emulation > +************* > + > +QEMU was originally built as an emulator capable of running binaries > +for one architecture on another. The following sections describe the > +internals of how the Just In Time (JIT) Tiny Code Generator (TCG) > +works. You only really need to read this if you are interested in > +adding new architectures or fixing existing architecture emulation. > + > + > +.. toctree:: > + :maxdepth: 2 > + > + tcg > + multi-thread-tcg > + tcg-icount > + decodetree > + tcg-plugins > diff --git a/docs/devel/section-testing.rst b/docs/devel/section-testing.rst > new file mode 100644 > index 0000000000..c93ff4c4dd > --- /dev/null > +++ b/docs/devel/section-testing.rst > @@ -0,0 +1,20 @@ > +*************** > +Testing in QEMU > +*************** > + > +QEMU is a large and complex project which can be configured in a > +multitude of ways. As it's impossible for an individual developer to > +manually test all of these we rely on a whole suite of automated > +testing approaches to ensure regressions are kept to a minimum. > + > +The following sections give a broad overview of the testing > +infrastructure as well as some detailed introductions into more > +advanced testing topics. > + > +.. toctree:: > + :maxdepth: 2 > + > + testing > + fuzzing > + control-flow-integrity > + qtest > diff --git a/docs/devel/tcg-icount.rst b/docs/devel/tcg-icount.rst > index 8d67b6c076..eb990b0976 100644 > --- a/docs/devel/tcg-icount.rst > +++ b/docs/devel/tcg-icount.rst > @@ -3,9 +3,9 @@ > Written by Alex Bennée > > > -======================== > -TCG Instruction Counting > -======================== > +================================= > +TCG Instruction Counting (icount) > +================================= > > TCG has long supported a feature known as icount which allows for > instruction counting during execution. This should not be confused > diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst > index 3124ee2470..a69db8ab93 100644 > --- a/docs/devel/testing.rst > +++ b/docs/devel/testing.rst > @@ -1,6 +1,6 @@ > -=============== > -Testing in QEMU > -=============== > +======= > +Testing > +======= > > This document describes the testing infrastructure in QEMU. >
On Wed, 24 Feb 2021 at 12:51, Wainer dos Santos Moschetta <wainersm@redhat.com> wrote: > Just a fyi... yesterday I realized that the (current) TOC is not getting > rendered on my Firefox (or chrome) browser: > > https://gitlab.com/qemu-project/qemu/-/tree/master/docs/devel That's the source code for the docs, isn't it? gitlab is trying to render it as raw rst, but that won't handle all the Sphinx-specific markup, including the TOC. The built-and-rendered docs are elsewhere (the gitlab CI job runs Sphinx and puts the rendered manuals here): https://qemu-project.gitlab.io/qemu/ thanks -- PMM
On 2/24/21 10:15 AM, Peter Maydell wrote: > On Wed, 24 Feb 2021 at 12:51, Wainer dos Santos Moschetta > <wainersm@redhat.com> wrote: >> Just a fyi... yesterday I realized that the (current) TOC is not getting >> rendered on my Firefox (or chrome) browser: >> >> https://gitlab.com/qemu-project/qemu/-/tree/master/docs/devel > That's the source code for the docs, isn't it? gitlab > is trying to render it as raw rst, but that won't handle > all the Sphinx-specific markup, including the TOC. You're right Peter. For one second I thought gitlab was able to render the rst files. > > The built-and-rendered docs are elsewhere (the gitlab CI > job runs Sphinx and puts the rendered manuals here): > https://qemu-project.gitlab.io/qemu/ > > thanks > -- PMM >
diff --git a/docs/devel/index.rst b/docs/devel/index.rst index ae664da00c..2af7bf8736 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -13,29 +13,9 @@ Contents: .. toctree:: :maxdepth: 2 - build-system - style - kconfig - testing - fuzzing - control-flow-integrity - loads-stores - memory - migration - atomics - stable-process - qtest - decodetree - secure-coding-practices - tcg - tcg-icount - tracing - multi-thread-tcg - tcg-plugins - bitops - reset - s390-dasd-ipl - clocks - qom - block-coroutine-wrapper - multi-process + section-building + section-testing + section-concepts + section-apis + section-tcg-emulation + section-process diff --git a/docs/devel/multi-thread-tcg.rst b/docs/devel/multi-thread-tcg.rst index 92a9eba13c..5b446ee08b 100644 --- a/docs/devel/multi-thread-tcg.rst +++ b/docs/devel/multi-thread-tcg.rst @@ -4,8 +4,9 @@ This work is licensed under the terms of the GNU GPL, version 2 or later. See the COPYING file in the top-level directory. -Introduction -============ +================== +Multi-threaded TCG +================== This document outlines the design for multi-threaded TCG (a.k.a MTTCG) system-mode emulation. user-mode emulation has always mirrored the diff --git a/docs/devel/section-apis.rst b/docs/devel/section-apis.rst new file mode 100644 index 0000000000..ab1f6bed60 --- /dev/null +++ b/docs/devel/section-apis.rst @@ -0,0 +1,16 @@ +********* +QEMU APIs +********* + +There are a number of APIs in QEMU and the following sections document +some of the most important ones. For tose that aren't documented here +you can also find notes on usage in the header definitions. + +.. toctree:: + :maxdepth: 2 + + atomics + bitops + loads-stores + memory + tracing diff --git a/docs/devel/section-building.rst b/docs/devel/section-building.rst new file mode 100644 index 0000000000..e6e9fa1d6a --- /dev/null +++ b/docs/devel/section-building.rst @@ -0,0 +1,13 @@ +************* +Building QEMU +************* + +The following sections deal with how the build system works, how it is +configured and some basic guidance on how code should be written. + +.. toctree:: + :maxdepth: 2 + + build-system + kconfig + style diff --git a/docs/devel/section-concepts.rst b/docs/devel/section-concepts.rst new file mode 100644 index 0000000000..566c52e90a --- /dev/null +++ b/docs/devel/section-concepts.rst @@ -0,0 +1,21 @@ +************* +QEMU Concepts +************* + +There are a number of high level concepts that are useful to +understand when working with the code base. Perhaps the most pervasive +is the QEMU Object Model (QOM) which underpins much of the flexibility +and configurable of the project. The following sections document that +as well as diving into other concepts that are useful to know if +working on some areas of the code. + +.. toctree:: + :maxdepth: 2 + + qom + clocks + reset + block-coroutine-wrapper + migration + multi-process + s390-dasd-ipl diff --git a/docs/devel/section-process.rst b/docs/devel/section-process.rst new file mode 100644 index 0000000000..3b0ae4f19b --- /dev/null +++ b/docs/devel/section-process.rst @@ -0,0 +1,11 @@ +=================== +Development Process +=================== + +The following sections detail aspects of the development process. + +.. toctree:: + :maxdepth: 2 + + secure-coding-practices + stable-process diff --git a/docs/devel/section-tcg-emulation.rst b/docs/devel/section-tcg-emulation.rst new file mode 100644 index 0000000000..81fa131de7 --- /dev/null +++ b/docs/devel/section-tcg-emulation.rst @@ -0,0 +1,19 @@ +************* +TCG Emulation +************* + +QEMU was originally built as an emulator capable of running binaries +for one architecture on another. The following sections describe the +internals of how the Just In Time (JIT) Tiny Code Generator (TCG) +works. You only really need to read this if you are interested in +adding new architectures or fixing existing architecture emulation. + + +.. toctree:: + :maxdepth: 2 + + tcg + multi-thread-tcg + tcg-icount + decodetree + tcg-plugins diff --git a/docs/devel/section-testing.rst b/docs/devel/section-testing.rst new file mode 100644 index 0000000000..c93ff4c4dd --- /dev/null +++ b/docs/devel/section-testing.rst @@ -0,0 +1,20 @@ +*************** +Testing in QEMU +*************** + +QEMU is a large and complex project which can be configured in a +multitude of ways. As it's impossible for an individual developer to +manually test all of these we rely on a whole suite of automated +testing approaches to ensure regressions are kept to a minimum. + +The following sections give a broad overview of the testing +infrastructure as well as some detailed introductions into more +advanced testing topics. + +.. toctree:: + :maxdepth: 2 + + testing + fuzzing + control-flow-integrity + qtest diff --git a/docs/devel/tcg-icount.rst b/docs/devel/tcg-icount.rst index 8d67b6c076..eb990b0976 100644 --- a/docs/devel/tcg-icount.rst +++ b/docs/devel/tcg-icount.rst @@ -3,9 +3,9 @@ Written by Alex Bennée -======================== -TCG Instruction Counting -======================== +================================= +TCG Instruction Counting (icount) +================================= TCG has long supported a feature known as icount which allows for instruction counting during execution. This should not be confused diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst index 3124ee2470..a69db8ab93 100644 --- a/docs/devel/testing.rst +++ b/docs/devel/testing.rst @@ -1,6 +1,6 @@ -=============== -Testing in QEMU -=============== +======= +Testing +======= This document describes the testing infrastructure in QEMU.
The list of sub-sections was getting a bit long and sporadically organised. Let's try and impose some order on this hairball of documentation. [AJB: RFC because I wonder if we should make a more concerted effort to move bits of the wiki into a canonical maintained document. There is also probably a need for a quickbuild or tldr section of the build-system for users who just want to build something.] Based-on: 20210223095931.16908-1-alex.bennee@linaro.org Signed-off-by: Alex Bennée <alex.bennee@linaro.org> --- docs/devel/index.rst | 32 ++++++---------------------- docs/devel/multi-thread-tcg.rst | 5 +++-- docs/devel/section-apis.rst | 16 ++++++++++++++ docs/devel/section-building.rst | 13 +++++++++++ docs/devel/section-concepts.rst | 21 ++++++++++++++++++ docs/devel/section-process.rst | 11 ++++++++++ docs/devel/section-tcg-emulation.rst | 19 +++++++++++++++++ docs/devel/section-testing.rst | 20 +++++++++++++++++ docs/devel/tcg-icount.rst | 6 +++--- docs/devel/testing.rst | 6 +++--- 10 files changed, 115 insertions(+), 34 deletions(-) create mode 100644 docs/devel/section-apis.rst create mode 100644 docs/devel/section-building.rst create mode 100644 docs/devel/section-concepts.rst create mode 100644 docs/devel/section-process.rst create mode 100644 docs/devel/section-tcg-emulation.rst create mode 100644 docs/devel/section-testing.rst