diff mbox series

[v1,1/9] docs/devel: re-organise the developers guide into sections

Message ID 20210305092328.31792-2-alex.bennee@linaro.org
State New
Headers show
Series testing/next (docs, hexagon, cfi, docker) | expand

Commit Message

Alex Bennée March 5, 2021, 9:23 a.m. UTC
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

Comments

Philippe Mathieu-Daudé March 5, 2021, 9:40 a.m. UTC | #1
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
Alex Bennée March 5, 2021, 1:37 p.m. UTC | #2
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
diff mbox series

Patch

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.