| Message ID | 20210305092328.31792-2-alex.bennee@linaro.org |
|---|---|
| State | New |
| Headers | show |
| Series | testing/next (docs, hexagon, cfi, docker) | expand |
On 3/5/21 10:23 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 ^ IMO this hint for git bots should be removed from git history. > 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
Philippe Mathieu-Daudé <f4bug@amsat.org> writes: > On 3/5/21 10:23 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 > > ^ IMO this hint for git bots should be removed from git history. I'll add a check for that in my patch scripts. > >> 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 -- Alex Bennée
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 1434a50cc4..af98efec8c 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 -- 2.20.1