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
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.