Add brief documentation of the Arm 'mainstone' board.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>

Message-id: 20210722175229.29065-2-peter.maydell@linaro.org

---

docs/system/arm/mainstone.rst | 25 +++++++++++++++++++++++++

docs/system/target-arm.rst | 1 +

MAINTAINERS | 1 +

3 files changed, 27 insertions(+)

create mode 100644 docs/system/arm/mainstone.rst

diff --git a/docs/system/arm/mainstone.rst b/docs/system/arm/mainstone.rst

new file mode 100644

index XXXXXXX..XXXXXXX

--- /dev/null

+++ b/docs/system/arm/mainstone.rst

@@ -XXX,XX +XXX,XX @@

+Intel Mainstone II board (``mainstone``)

+========================================

+

+The ``mainstone`` board emulates the Intel Mainstone II development

+board, which uses a PXA270 CPU.

+

+Emulated devices:

+

+- Flash memory

+- Keypad

+- MMC controller

+- 91C111 ethernet

+- PIC

+- Timer

+- DMA

+- GPIO

+- FIR

+- Serial

+- LCD controller

+- SSP

+- USB controller

+- RTC

+- PCMCIA

+- I2C

+- I2S

diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst

index XXXXXXX..XXXXXXX 100644

--- a/docs/system/target-arm.rst

+++ b/docs/system/target-arm.rst

@@ -XXX,XX +XXX,XX @@ undocumented; you can get a complete list by running

arm/highbank

arm/musicpal

arm/gumstix

+ arm/mainstone

arm/nrf

arm/nseries

arm/nuvoton

diff --git a/MAINTAINERS b/MAINTAINERS

index XXXXXXX..XXXXXXX 100644

--- a/MAINTAINERS

+++ b/MAINTAINERS

@@ -XXX,XX +XXX,XX @@ F: include/hw/arm/pxa.h

F: include/hw/arm/sharpsl.h

F: include/hw/display/tc6393xb.h

F: docs/system/arm/xscale.rst

+F: docs/system/arm/mainstone.rst

SABRELITE / i.MX6

M: Peter Maydell <peter.maydell@linaro.org>

--

2.20.1

Add brief documentation of the Arm 'kzm' board.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>

Message-id: 20210722175229.29065-3-peter.maydell@linaro.org

---

docs/system/arm/kzm.rst | 18 ++++++++++++++++++

docs/system/target-arm.rst | 1 +

MAINTAINERS | 1 +

3 files changed, 20 insertions(+)

create mode 100644 docs/system/arm/kzm.rst

diff --git a/docs/system/arm/kzm.rst b/docs/system/arm/kzm.rst

new file mode 100644

index XXXXXXX..XXXXXXX

--- /dev/null

+++ b/docs/system/arm/kzm.rst

@@ -XXX,XX +XXX,XX @@

+Kyoto Microcomputer KZM-ARM11-01 (``kzm``)

+==========================================

+

+The ``kzm`` board emulates the Kyoto Microcomputer KZM-ARM11-01

+evaluation board, which is based on an NXP i.MX32 SoC

+which uses an ARM1136 CPU.

+

+Emulated devices:

+

+- UARTs

+- LAN9118 ethernet

+- AVIC

+- CCM

+- GPT

+- EPIT timers

+- I2C

+- GPIO controllers

+- Watchdog timer

diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst

index XXXXXXX..XXXXXXX 100644

--- a/docs/system/target-arm.rst

+++ b/docs/system/target-arm.rst

@@ -XXX,XX +XXX,XX @@ undocumented; you can get a complete list by running

arm/musicpal

arm/gumstix

arm/mainstone

+ arm/kzm

arm/nrf

arm/nseries

arm/nuvoton

diff --git a/MAINTAINERS b/MAINTAINERS

index XXXXXXX..XXXXXXX 100644

--- a/MAINTAINERS

+++ b/MAINTAINERS

@@ -XXX,XX +XXX,XX @@ F: hw/*/imx_*

F: hw/*/*imx31*

F: include/hw/*/imx_*

F: include/hw/*/*imx31*

+F: docs/system/arm/kzm.rst

Integrator CP

M: Peter Maydell <peter.maydell@linaro.org>

--

2.20.1

Add brief documentation of the Arm 'imx25-pdk' board.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>

Message-id: 20210722175229.29065-4-peter.maydell@linaro.org

---

docs/system/arm/imx25-pdk.rst | 19 +++++++++++++++++++

docs/system/target-arm.rst | 1 +

MAINTAINERS | 1 +

3 files changed, 21 insertions(+)

create mode 100644 docs/system/arm/imx25-pdk.rst

diff --git a/docs/system/arm/imx25-pdk.rst b/docs/system/arm/imx25-pdk.rst

new file mode 100644

index XXXXXXX..XXXXXXX

--- /dev/null

+++ b/docs/system/arm/imx25-pdk.rst

@@ -XXX,XX +XXX,XX @@

+NXP i.MX25 PDK board (``imx25-pdk``)

+====================================

+

+The ``imx25-pdk`` board emulates the NXP i.MX25 Product Development Kit

+board, which is based on an i.MX25 SoC which uses an ARM926 CPU.

+

+Emulated devices:

+

+- SD controller

+- AVIC

+- CCM

+- GPT

+- EPIT timers

+- FEC

+- RNGC

+- I2C

+- GPIO controllers

+- Watchdog timer

+- USB controllers

diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst

index XXXXXXX..XXXXXXX 100644

--- a/docs/system/target-arm.rst

+++ b/docs/system/target-arm.rst

@@ -XXX,XX +XXX,XX @@ undocumented; you can get a complete list by running

arm/nrf

arm/nseries

arm/nuvoton

+ arm/imx25-pdk

arm/orangepi

arm/palm

arm/raspi

diff --git a/MAINTAINERS b/MAINTAINERS

index XXXXXXX..XXXXXXX 100644

--- a/MAINTAINERS

+++ b/MAINTAINERS

@@ -XXX,XX +XXX,XX @@ F: hw/watchdog/wdt_imx2.c

F: include/hw/arm/fsl-imx25.h

F: include/hw/misc/imx25_ccm.h

F: include/hw/watchdog/wdt_imx2.h

+F: docs/system/arm/imx25-pdk.rst

i.MX31 (kzm)

M: Peter Maydell <peter.maydell@linaro.org>

--

2.20.1

Andrzej Zaborowski is listed as an "Odd Fixes" maintainer for the

nSeries, Palm and PXA2XX boards, as well as the "Maintained" status

Arm 32-bit TCG backend.

Andrzej's last email to qemu-devel was back in 2017, and the email

before that was all the way back in 2013. We don't really need to

fill his email up with CCs on QEMU patches any more...

Remove Andrzej from the various boards sections (leaving them still

Odd Fixes with me as the backup patch reviewer). Add Richard

Henderson as the maintainer for the Arm TCG backend, since removing

Andrzej would otherwise leave that section with no M: line at all.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>

Message-id: 20210722180951.29802-1-peter.maydell@linaro.org

---

MAINTAINERS | 5 +----

1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/MAINTAINERS b/MAINTAINERS

index XXXXXXX..XXXXXXX 100644

--- a/MAINTAINERS

+++ b/MAINTAINERS

@@ -XXX,XX +XXX,XX @@ F: roms/vbootrom

F: docs/system/arm/nuvoton.rst

nSeries

-M: Andrzej Zaborowski <balrogg@gmail.com>

M: Peter Maydell <peter.maydell@linaro.org>

L: qemu-arm@nongnu.org

S: Odd Fixes

@@ -XXX,XX +XXX,XX @@ F: tests/acceptance/machine_arm_n8x0.py

F: docs/system/arm/nseries.rst

Palm

-M: Andrzej Zaborowski <balrogg@gmail.com>

M: Peter Maydell <peter.maydell@linaro.org>

L: qemu-arm@nongnu.org

S: Odd Fixes

@@ -XXX,XX +XXX,XX @@ F: include/hw/intc/realview_gic.h

F: docs/system/arm/realview.rst

PXA2XX

-M: Andrzej Zaborowski <balrogg@gmail.com>

M: Peter Maydell <peter.maydell@linaro.org>

L: qemu-arm@nongnu.org

S: Odd Fixes

@@ -XXX,XX +XXX,XX @@ F: disas/arm-a64.cc

F: disas/libvixl/

ARM TCG target

-M: Andrzej Zaborowski <balrogg@gmail.com>

+M: Richard Henderson <richard.henderson@linaro.org>

S: Maintained

L: qemu-arm@nongnu.org

F: tcg/arm/

--

2.20.1

Since commits 13f934e79fa and 3a50c8f3067aaf, our HTML docs include a

footer to all pages stating the license and version. We can

therefore delete the TODO comments suggesting we should do that from

our .rst files.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>

Reviewed-by: Cleber Rosa <crosa@redhat.com>

Reviewed-by: Markus Armbruster <armbru@redhat.com>

Message-id: 20210722192016.24915-2-peter.maydell@linaro.org

---

docs/interop/qemu-ga-ref.rst | 9 ---------

docs/interop/qemu-qmp-ref.rst | 9 ---------

docs/interop/qemu-storage-daemon-qmp-ref.rst | 9 ---------

3 files changed, 27 deletions(-)

diff --git a/docs/interop/qemu-ga-ref.rst b/docs/interop/qemu-ga-ref.rst

index XXXXXXX..XXXXXXX 100644

--- a/docs/interop/qemu-ga-ref.rst

+++ b/docs/interop/qemu-ga-ref.rst

@@ -XXX,XX +XXX,XX @@

QEMU Guest Agent Protocol Reference

===================================

-..

- TODO: the old Texinfo manual used to note that this manual

- is GPL-v2-or-later. We should make that reader-visible

- both here and in our Sphinx manuals more generally.

-

-..

- TODO: display the QEMU version, both here and in our Sphinx manuals

- more generally.

-

.. contents::

:depth: 3

diff --git a/docs/interop/qemu-qmp-ref.rst b/docs/interop/qemu-qmp-ref.rst

index XXXXXXX..XXXXXXX 100644

--- a/docs/interop/qemu-qmp-ref.rst

+++ b/docs/interop/qemu-qmp-ref.rst

@@ -XXX,XX +XXX,XX @@

QEMU QMP Reference Manual

=========================

-..

- TODO: the old Texinfo manual used to note that this manual

- is GPL-v2-or-later. We should make that reader-visible

- both here and in our Sphinx manuals more generally.

-

-..

- TODO: display the QEMU version, both here and in our Sphinx manuals

- more generally.

-

.. contents::

:depth: 3

diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst

index XXXXXXX..XXXXXXX 100644

--- a/docs/interop/qemu-storage-daemon-qmp-ref.rst

+++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst

@@ -XXX,XX +XXX,XX @@

QEMU Storage Daemon QMP Reference Manual

========================================

-..

- TODO: the old Texinfo manual used to note that this manual

- is GPL-v2-or-later. We should make that reader-visible

- both here and in our Sphinx manuals more generally.

-

-..

- TODO: display the QEMU version, both here and in our Sphinx manuals

- more generally.

-

.. contents::

:depth: 3

--

2.20.1

Our built HTML documentation now has a standard footer which

gives the license for QEMU (and its documentation as a whole).

In almost all pages, we either don't bother to state the

copyright/license for the individual rST sources, or we put

it in an rST comment. There are just three pages which render

copyright or license information into the user-visible HTML.

Quoting a specific (different) license for an individual HTML

page within the manual is confusing. Downgrade the license

and copyright info to a comment within the rST source, bringing

these pages in line with the rest of our documents.

Suggested-by: Markus Armbruster <armbru@redhat.com>

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>

Reviewed-by: Cleber Rosa <crosa@redhat.com>

Reviewed-by: Markus Armbruster <armbru@redhat.com>

Acked-by: Michael S. Tsirkin <mst@redhat.com>

Message-id: 20210722192016.24915-3-peter.maydell@linaro.org

---

docs/interop/vhost-user-gpu.rst | 7 ++++---

docs/interop/vhost-user.rst | 12 +++++++-----

docs/system/generic-loader.rst | 4 ++--

3 files changed, 13 insertions(+), 10 deletions(-)

diff --git a/docs/interop/vhost-user-gpu.rst b/docs/interop/vhost-user-gpu.rst

index XXXXXXX..XXXXXXX 100644

--- a/docs/interop/vhost-user-gpu.rst

+++ b/docs/interop/vhost-user-gpu.rst

@@ -XXX,XX +XXX,XX @@

Vhost-user-gpu Protocol

=======================

-:Licence: This work is licensed under the terms of the GNU GPL,

- version 2 or later. See the COPYING file in the top-level

- directory.

+..

+ Licence: This work is licensed under the terms of the GNU GPL,

+ version 2 or later. See the COPYING file in the top-level

+ directory.

.. contents:: Table of Contents

diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst

index XXXXXXX..XXXXXXX 100644

--- a/docs/interop/vhost-user.rst

+++ b/docs/interop/vhost-user.rst

@@ -XXX,XX +XXX,XX @@

===================

Vhost-user Protocol

===================

-:Copyright: 2014 Virtual Open Systems Sarl.

-:Copyright: 2019 Intel Corporation

-:Licence: This work is licensed under the terms of the GNU GPL,

- version 2 or later. See the COPYING file in the top-level

- directory.

+

+..

+ Copyright 2014 Virtual Open Systems Sarl.

+ Copyright 2019 Intel Corporation

+ Licence: This work is licensed under the terms of the GNU GPL,

+ version 2 or later. See the COPYING file in the top-level

+ directory.

.. contents:: Table of Contents

diff --git a/docs/system/generic-loader.rst b/docs/system/generic-loader.rst

index XXXXXXX..XXXXXXX 100644

--- a/docs/system/generic-loader.rst

+++ b/docs/system/generic-loader.rst

@@ -XXX,XX +XXX,XX @@

..

Copyright (c) 2016, Xilinx Inc.

-This work is licensed under the terms of the GNU GPL, version 2 or later. See

-the COPYING file in the top-level directory.

+ This work is licensed under the terms of the GNU GPL, version 2 or later. See

+ the COPYING file in the top-level directory.

Generic Loader

--------------

--

2.20.1

In rST markup, single backticks `like this` represent "interpreted

text", which can be handled as a bunch of different things if tagged

with a specific "role":

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#interpreted-text

(the most common one for us is "reference to a URL, which gets

hyperlinked").

The default "role" if none is specified is "title_reference",

intended for references to book or article titles, and it renders

into the HTML as <cite>...</cite> (usually comes out as italics).

build-system.rst seems to have been written under the mistaken

assumption that single-backticks mark up literal text (function

names, etc) which should be rendered in a fixed-width font.

The rST markup for this is ``double backticks``.

Update all the markup.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>

Message-id: 20210726142338.31872-2-peter.maydell@linaro.org

---

docs/devel/build-system.rst | 156 ++++++++++++++++++------------------

1 file changed, 78 insertions(+), 78 deletions(-)

diff --git a/docs/devel/build-system.rst b/docs/devel/build-system.rst

index XXXXXXX..XXXXXXX 100644

--- a/docs/devel/build-system.rst

+++ b/docs/devel/build-system.rst

@@ -XXX,XX +XXX,XX @@ following tasks:

- Add a Meson build option to meson_options.txt.

- Add support to the command line arg parser to handle any new

- `--enable-XXX`/`--disable-XXX` flags required by the feature.

+ ``--enable-XXX``/``--disable-XXX`` flags required by the feature.

- Add information to the help output message to report on the new

feature flag.

- Add code to perform the actual feature check.

- - Add code to include the feature status in `config-host.h`

+ - Add code to include the feature status in ``config-host.h``

- Add code to print out the feature status in the configure summary

upon completion.

@@ -XXX,XX +XXX,XX @@ Helper functions

The configure script provides a variety of helper functions to assist

developers in checking for system features:

-`do_cc $ARGS...`

+``do_cc $ARGS...``

Attempt to run the system C compiler passing it $ARGS...

-`do_cxx $ARGS...`

+``do_cxx $ARGS...``

Attempt to run the system C++ compiler passing it $ARGS...

-`compile_object $CFLAGS`

+``compile_object $CFLAGS``

Attempt to compile a test program with the system C compiler using

$CFLAGS. The test program must have been previously written to a file

- called $TMPC. The replacement in Meson is the compiler object `cc`,

- which has methods such as `cc.compiles()`,

- `cc.check_header()`, `cc.has_function()`.

+ called $TMPC. The replacement in Meson is the compiler object ``cc``,

+ which has methods such as ``cc.compiles()``,

+ ``cc.check_header()``, ``cc.has_function()``.

-`compile_prog $CFLAGS $LDFLAGS`

+``compile_prog $CFLAGS $LDFLAGS``

Attempt to compile a test program with the system C compiler using

$CFLAGS and link it with the system linker using $LDFLAGS. The test

program must have been previously written to a file called $TMPC.

- The replacement in Meson is `cc.find_library()` and `cc.links()`.

+ The replacement in Meson is ``cc.find_library()`` and ``cc.links()``.

-`has $COMMAND`

+``has $COMMAND``

Determine if $COMMAND exists in the current environment, either as a

shell builtin, or executable binary, returning 0 on success. The

- replacement in Meson is `find_program()`.

+ replacement in Meson is ``find_program()``.

-`check_define $NAME`

+``check_define $NAME``

Determine if the macro $NAME is defined by the system C compiler

-`check_include $NAME`

+``check_include $NAME``

Determine if the include $NAME file is available to the system C

- compiler. The replacement in Meson is `cc.has_header()`.

+ compiler. The replacement in Meson is ``cc.has_header()``.

-`write_c_skeleton`

+``write_c_skeleton``

Write a minimal C program main() function to the temporary file

indicated by $TMPC

-`feature_not_found $NAME $REMEDY`

+``feature_not_found $NAME $REMEDY``

Print a message to stderr that the feature $NAME was not available

on the system, suggesting the user try $REMEDY to address the

problem.

-`error_exit $MESSAGE $MORE...`

+``error_exit $MESSAGE $MORE...``

Print $MESSAGE to stderr, followed by $MORE... and then exit from the

configure script with non-zero status

-`query_pkg_config $ARGS...`

+``query_pkg_config $ARGS...``

Run pkg-config passing it $ARGS. If QEMU is doing a static build,

then --static will be automatically added to $ARGS

@@ -XXX,XX +XXX,XX @@ process for:

4) other data files, such as icons or desktop files

-All executables are built by default, except for some `contrib/`

+All executables are built by default, except for some ``contrib/``

binaries that are known to fail to build on some platforms (for example

32-bit or big-endian platforms). Tests are also built by default,

though that might change in the future.

@@ -XXX,XX +XXX,XX @@ though that might change in the future.

The source code is highly modularized, split across many files to

facilitate building of all of these components with as little duplicated

compilation as possible. Using the Meson "sourceset" functionality,

-`meson.build` files group the source files in rules that are

+``meson.build`` files group the source files in rules that are

enabled according to the available system libraries and to various

configuration symbols. Sourcesets belong to one of four groups:

Subsystem sourcesets:

Various subsystems that are common to both tools and emulators have

- their own sourceset, for example `block_ss` for the block device subsystem,

- `chardev_ss` for the character device subsystem, etc. These sourcesets

+ their own sourceset, for example ``block_ss`` for the block device subsystem,

+ ``chardev_ss`` for the character device subsystem, etc. These sourcesets

are then turned into static libraries as follows::

libchardev = static_library('chardev', chardev_ss.sources(),

@@ -XXX,XX +XXX,XX @@ Subsystem sourcesets:

chardev = declare_dependency(link_whole: libchardev)

- As of Meson 0.55.1, the special `.fa` suffix should be used for everything

- that is used with `link_whole`, to ensure that the link flags are placed

+ As of Meson 0.55.1, the special ``.fa`` suffix should be used for everything

+ that is used with ``link_whole``, to ensure that the link flags are placed

correctly in the command line.

Target-independent emulator sourcesets:

@@ -XXX,XX +XXX,XX @@ Target-independent emulator sourcesets:

This includes error handling infrastructure, standard data structures,

platform portability wrapper functions, etc.

- Target-independent code lives in the `common_ss`, `softmmu_ss` and

- `user_ss` sourcesets. `common_ss` is linked into all emulators,

- `softmmu_ss` only in system emulators, `user_ss` only in user-mode

+ Target-independent code lives in the ``common_ss``, ``softmmu_ss`` and

+ ``user_ss`` sourcesets. ``common_ss`` is linked into all emulators,

+ ``softmmu_ss`` only in system emulators, ``user_ss`` only in user-mode

emulators.

Target-independent sourcesets must exercise particular care when using

- `if_false` rules. The `if_false` rule will be used correctly when linking

+ ``if_false`` rules. The ``if_false`` rule will be used correctly when linking

emulator binaries; however, when *compiling* target-independent files

- into .o files, Meson may need to pick *both* the `if_true` and

- `if_false` sides to cater for targets that want either side. To

+ into .o files, Meson may need to pick *both* the ``if_true`` and

+ ``if_false`` sides to cater for targets that want either side. To

achieve that, you can add a special rule using the ``CONFIG_ALL``

symbol::

@@ -XXX,XX +XXX,XX @@ Target-dependent emulator sourcesets:

In the target-dependent set lives CPU emulation, some device emulation and

much glue code. This sometimes also has to be compiled multiple times,

once for each target being built. Target-dependent files are included

- in the `specific_ss` sourceset.

+ in the ``specific_ss`` sourceset.

- Each emulator also includes sources for files in the `hw/` and `target/`

+ Each emulator also includes sources for files in the ``hw/`` and ``target/``

subdirectories. The subdirectory used for each emulator comes

from the target's definition of ``TARGET_BASE_ARCH`` or (if missing)

- ``TARGET_ARCH``, as found in `default-configs/targets/*.mak`.

+ ``TARGET_ARCH``, as found in ``default-configs/targets/*.mak``.

- Each subdirectory in `hw/` adds one sourceset to the `hw_arch` dictionary,

+ Each subdirectory in ``hw/`` adds one sourceset to the ``hw_arch`` dictionary,

for example::

arm_ss = ss.source_set()

@@ -XXX,XX +XXX,XX @@ Target-dependent emulator sourcesets:

The sourceset is only used for system emulators.

- Each subdirectory in `target/` instead should add one sourceset to each

- of the `target_arch` and `target_softmmu_arch`, which are used respectively

+ Each subdirectory in ``target/`` instead should add one sourceset to each

+ of the ``target_arch`` and ``target_softmmu_arch``, which are used respectively

for all emulators and for system emulators only. For example::

arm_ss = ss.source_set()

@@ -XXX,XX +XXX,XX @@ Target-dependent emulator sourcesets:

target_softmmu_arch += {'arm': arm_softmmu_ss}

Module sourcesets:

- There are two dictionaries for modules: `modules` is used for

- target-independent modules and `target_modules` is used for

- target-dependent modules. When modules are disabled the `module`

- source sets are added to `softmmu_ss` and the `target_modules`

- source sets are added to `specific_ss`.

+ There are two dictionaries for modules: ``modules`` is used for

+ target-independent modules and ``target_modules`` is used for

+ target-dependent modules. When modules are disabled the ``module``

+ source sets are added to ``softmmu_ss`` and the ``target_modules``

+ source sets are added to ``specific_ss``.

Both dictionaries are nested. One dictionary is created per

subdirectory, and these per-subdirectory dictionaries are added to

@@ -XXX,XX +XXX,XX @@ Module sourcesets:

modules += { 'hw-display': hw_display_modules }

Utility sourcesets:

- All binaries link with a static library `libqemuutil.a`. This library

+ All binaries link with a static library ``libqemuutil.a``. This library

is built from several sourcesets; most of them however host generated

- code, and the only two of general interest are `util_ss` and `stub_ss`.

+ code, and the only two of general interest are ``util_ss`` and ``stub_ss``.

The separation between these two is purely for documentation purposes.

- `util_ss` contains generic utility files. Even though this code is only

+ ``util_ss`` contains generic utility files. Even though this code is only

linked in some binaries, sometimes it requires hooks only in some of

these and depend on other functions that are not fully implemented by

- all QEMU binaries. `stub_ss` links dummy stubs that will only be linked

+ all QEMU binaries. ``stub_ss`` links dummy stubs that will only be linked

into the binary if the real implementation is not present. In a way,

the stubs can be thought of as a portable implementation of the weak

symbols concept.

@@ -XXX,XX +XXX,XX @@ Utility sourcesets:

The following files concur in the definition of which files are linked

into each emulator:

-`default-configs/devices/*.mak`

- The files under `default-configs/devices/` control the boards and devices

+``default-configs/devices/*.mak``

+ The files under ``default-configs/devices/`` control the boards and devices

that are built into each QEMU system emulation targets. They merely contain

a list of config variable definitions such as::

@@ -XXX,XX +XXX,XX @@ into each emulator:

CONFIG_XLNX_ZYNQMP_ARM=y

CONFIG_XLNX_VERSAL=y

-`*/Kconfig`

- These files are processed together with `default-configs/devices/*.mak` and

+``*/Kconfig``

+ These files are processed together with ``default-configs/devices/*.mak`` and

describe the dependencies between various features, subsystems and

device models. They are described in :ref:`kconfig`

-`default-configs/targets/*.mak`

- These files mostly define symbols that appear in the `*-config-target.h`

+``default-configs/targets/*.mak``

+ These files mostly define symbols that appear in the ``*-config-target.h``

file for each emulator [#cfgtarget]_. However, the ``TARGET_ARCH``

- and ``TARGET_BASE_ARCH`` will also be used to select the `hw/` and

- `target/` subdirectories that are compiled into each target.

+ and ``TARGET_BASE_ARCH`` will also be used to select the ``hw/`` and

+ ``target/`` subdirectories that are compiled into each target.

-.. [#cfgtarget] This header is included by `qemu/osdep.h` when

+.. [#cfgtarget] This header is included by ``qemu/osdep.h`` when

compiling files from the target-specific sourcesets.

These files rarely need changing unless you are adding a completely

@@ -XXX,XX +XXX,XX @@ Support scripts

---------------

Meson has a special convention for invoking Python scripts: if their

-first line is `#! /usr/bin/env python3` and the file is *not* executable,

+first line is ``#! /usr/bin/env python3`` and the file is *not* executable,

find_program() arranges to invoke the script under the same Python

interpreter that was used to invoke Meson. This is the most common

and preferred way to invoke support scripts from Meson build files,

because it automatically uses the value of configure's --python= option.

-In case the script is not written in Python, use a `#! /usr/bin/env ...`

+In case the script is not written in Python, use a ``#! /usr/bin/env ...``

line and make the script executable.

Scripts written in Python, where it is desirable to make the script

executable (for example for test scripts that developers may want to

invoke from the command line, such as tests/qapi-schema/test-qapi.py),

-should be invoked through the `python` variable in meson.build. For

+should be invoked through the ``python`` variable in meson.build. For

example::

test('QAPI schema regression tests', python,

@@ -XXX,XX +XXX,XX @@ rules and wraps them so that e.g. submodules are built before QEMU.

The resulting build system is largely non-recursive in nature, in

contrast to common practices seen with automake.

-Tests are also ran by the Makefile with the traditional `make check`

-phony target, while benchmarks are run with `make bench`. Meson test

-suites such as `unit` can be ran with `make check-unit` too. It is also

-possible to run tests defined in meson.build with `meson test`.

+Tests are also ran by the Makefile with the traditional ``make check``

+phony target, while benchmarks are run with ``make bench``. Meson test

+suites such as ``unit`` can be ran with ``make check-unit`` too. It is also

+possible to run tests defined in meson.build with ``meson test``.

Important files for the build system

====================================

@@ -XXX,XX +XXX,XX @@ The following key files are statically defined in the source tree, with

the rules needed to build QEMU. Their behaviour is influenced by a

number of dynamically created files listed later.

-`Makefile`

+``Makefile``

The main entry point used when invoking make to build all the components

of QEMU. The default 'all' target will naturally result in the build of

every component. Makefile takes care of recursively building submodules

directly via a non-recursive set of rules.

-`*/meson.build`

+``*/meson.build``

The meson.build file in the root directory is the main entry point for the

Meson build system, and it coordinates the configuration and build of all

executables. Build rules for various subdirectories are included in

other meson.build files spread throughout the QEMU source tree.

-`tests/Makefile.include`

+``tests/Makefile.include``

Rules for external test harnesses. These include the TCG tests,

- `qemu-iotests` and the Avocado-based acceptance tests.

+ ``qemu-iotests`` and the Avocado-based acceptance tests.

-`tests/docker/Makefile.include`

+``tests/docker/Makefile.include``

Rules for Docker tests. Like tests/Makefile, this file is included

directly by the top level Makefile, anything defined in this file will

influence the entire build system.

-`tests/vm/Makefile.include`

+``tests/vm/Makefile.include``

Rules for VM-based tests. Like tests/Makefile, this file is included

directly by the top level Makefile, anything defined in this file will

influence the entire build system.

@@ -XXX,XX +XXX,XX @@ Makefile.

Built by configure:

-`config-host.mak`

+``config-host.mak``

When configure has determined the characteristics of the build host it

will write a long list of variables to config-host.mak file. This

provides the various install directories, compiler / linker flags and a

- variety of `CONFIG_*` variables related to optionally enabled features.

+ variety of ``CONFIG_*`` variables related to optionally enabled features.

This is imported by the top level Makefile and meson.build in order to

tailor the build output.

@@ -XXX,XX +XXX,XX @@ Built by configure:

Built by Meson:

-`${TARGET-NAME}-config-devices.mak`

+``${TARGET-NAME}-config-devices.mak``

TARGET-NAME is again the name of a system or userspace emulator. The

config-devices.mak file is automatically generated by make using the

scripts/make_device_config.sh program, feeding it the

default-configs/$TARGET-NAME file as input.

-`config-host.h`, `$TARGET-NAME/config-target.h`, `$TARGET-NAME/config-devices.h`

+``config-host.h``, ``$TARGET-NAME/config-target.h``, ``$TARGET-NAME/config-devices.h``

These files are used by source code to determine what features

are enabled. They are generated from the contents of the corresponding

- `*.h` files using the scripts/create_config program. This extracts

+ ``*.h`` files using the scripts/create_config program. This extracts

relevant variables and formats them as C preprocessor macros.

-`build.ninja`

+``build.ninja``

The build rules.

Built by Makefile:

-`Makefile.ninja`

+``Makefile.ninja``

A Makefile include that bridges to ninja for the actual build. The

Makefile is mostly a list of targets that Meson included in build.ninja.

-`Makefile.mtest`

+``Makefile.mtest``

The Makefile definitions that let "make check" run tests defined in

meson.build. The rules are produced from Meson's JSON description of

tests (obtained with "meson introspect --tests") through the script

@@ -XXX,XX +XXX,XX @@ Built by Makefile:

Useful make targets

-------------------

-`help`

+``help``

Print a help message for the most common build targets.

-`print-VAR`

+``print-VAR``

Print the value of the variable VAR. Useful for debugging the build

system.

--

2.20.1

One of the example meson.build fragments incorrectly quotes some

symbols as 'CONFIG_FOO`; the correct syntax here is 'CONFIG_FOO'.

(This isn't a rST formatting mistake because the example is displayed

literally; it's just the wrong kind of quote.)

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>

Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>

Message-id: 20210726142338.31872-3-peter.maydell@linaro.org

---

docs/devel/build-system.rst | 4 ++--

1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/devel/build-system.rst b/docs/devel/build-system.rst

index XXXXXXX..XXXXXXX 100644

--- a/docs/devel/build-system.rst

+++ b/docs/devel/build-system.rst

@@ -XXX,XX +XXX,XX @@ Target-independent emulator sourcesets:

symbol::

# Some targets have CONFIG_ACPI, some don't, so this is not enough

- softmmu_ss.add(when: 'CONFIG_ACPI`, if_true: files('acpi.c'),

+ softmmu_ss.add(when: 'CONFIG_ACPI', if_true: files('acpi.c'),

if_false: files('acpi-stub.c'))

# This is required as well:

- softmmu_ss.add(when: 'CONFIG_ALL`, if_true: files('acpi-stub.c'))

+ softmmu_ss.add(when: 'CONFIG_ALL', if_true: files('acpi-stub.c'))

Target-dependent emulator sourcesets:

In the target-dependent set lives CPU emulation, some device emulation and

--

2.20.1

In rST markup, single backticks `like this` represent "interpreted

text", which can be handled as a bunch of different things if tagged

with a specific "role":

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#interpreted-text

(the most common one for us is "reference to a URL, which gets

hyperlinked").

The default "role" if none is specified is "title_reference",

intended for references to book or article titles, and it renders

into the HTML as <cite>...</cite> (usually comes out as italics).

To format a literal (generally rendered as fixed-width font),

double-backticks are required.

ebpf_rss.rst gets this wrong in a few places; correct them.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>

Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>

Message-id: 20210726142338.31872-4-peter.maydell@linaro.org

---

docs/devel/ebpf_rss.rst | 18 +++++++++---------

1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/docs/devel/ebpf_rss.rst b/docs/devel/ebpf_rss.rst

index XXXXXXX..XXXXXXX 100644

--- a/docs/devel/ebpf_rss.rst

+++ b/docs/devel/ebpf_rss.rst

@@ -XXX,XX +XXX,XX @@ eBPF RSS implementation

eBPF RSS loading functionality located in ebpf/ebpf_rss.c and ebpf/ebpf_rss.h.

-The `struct EBPFRSSContext` structure that holds 4 file descriptors:

+The ``struct EBPFRSSContext`` structure that holds 4 file descriptors:

- ctx - pointer of the libbpf context.

- program_fd - file descriptor of the eBPF RSS program.

@@ -XXX,XX +XXX,XX @@ The `struct EBPFRSSContext` structure that holds 4 file descriptors:

- map_toeplitz_key - file descriptor of the 'Toeplitz key' map. One element of the 40byte key prepared for the hashing algorithm.

- map_indirections_table - 128 elements of queue indexes.

-`struct EBPFRSSConfig` fields:

+``struct EBPFRSSConfig`` fields:

-- redirect - "boolean" value, should the hash be calculated, on false - `default_queue` would be used as the final decision.

+- redirect - "boolean" value, should the hash be calculated, on false - ``default_queue`` would be used as the final decision.

- populate_hash - for now, not used. eBPF RSS doesn't support hash reporting.

-- hash_types - binary mask of different hash types. See `VIRTIO_NET_RSS_HASH_TYPE_*` defines. If for packet hash should not be calculated - `default_queue` would be used.

+- hash_types - binary mask of different hash types. See ``VIRTIO_NET_RSS_HASH_TYPE_*`` defines. If for packet hash should not be calculated - ``default_queue`` would be used.

- indirections_len - length of the indirections table, maximum 128.

- default_queue - the queue index that used for packet that shouldn't be hashed. For some packets, the hash can't be calculated(g.e ARP).

Functions:

-- `ebpf_rss_init()` - sets ctx to NULL, which indicates that EBPFRSSContext is not loaded.

-- `ebpf_rss_load()` - creates 3 maps and loads eBPF program from the rss.bpf.skeleton.h. Returns 'true' on success. After that, program_fd can be used to set steering for TAP.

-- `ebpf_rss_set_all()` - sets values for eBPF maps. `indirections_table` length is in EBPFRSSConfig. `toeplitz_key` is VIRTIO_NET_RSS_MAX_KEY_SIZE aka 40 bytes array.

-- `ebpf_rss_unload()` - close all file descriptors and set ctx to NULL.

+- ``ebpf_rss_init()`` - sets ctx to NULL, which indicates that EBPFRSSContext is not loaded.

+- ``ebpf_rss_load()`` - creates 3 maps and loads eBPF program from the rss.bpf.skeleton.h. Returns 'true' on success. After that, program_fd can be used to set steering for TAP.

+- ``ebpf_rss_set_all()`` - sets values for eBPF maps. ``indirections_table`` length is in EBPFRSSConfig. ``toeplitz_key`` is VIRTIO_NET_RSS_MAX_KEY_SIZE aka 40 bytes array.

+- ``ebpf_rss_unload()`` - close all file descriptors and set ctx to NULL.

Simplified eBPF RSS workflow:

@@ -XXX,XX +XXX,XX @@ Simplified eBPF RSS workflow:

NetClientState SetSteeringEBPF()

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-For now, `set_steering_ebpf()` method supported by Linux TAP NetClientState. The method requires an eBPF program file descriptor as an argument.

+For now, ``set_steering_ebpf()`` method supported by Linux TAP NetClientState. The method requires an eBPF program file descriptor as an argument.

--

2.20.1

In rST markup, single backticks `like this` represent "interpreted

text", which can be handled as a bunch of different things if tagged

with a specific "role":

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#interpreted-text

(the most common one for us is "reference to a URL, which gets

hyperlinked").

The default "role" if none is specified is "title_reference",

intended for references to book or article titles, and it renders

into the HTML as <cite>...</cite> (usually comes out as italics).

To format a literal (generally rendered as fixed-width font),

double-backticks are required.

Mostly migration.rst gets this right, but some places incorrectly use

single backticks where double backticks were intended; correct them.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>

Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>

Acked-by: Dr. David Alan Gilbert <dgilbert@redhat.com>

Message-id: 20210726142338.31872-5-peter.maydell@linaro.org

---

docs/devel/migration.rst | 36 ++++++++++++++++++------------------

1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/docs/devel/migration.rst b/docs/devel/migration.rst

index XXXXXXX..XXXXXXX 100644

--- a/docs/devel/migration.rst

+++ b/docs/devel/migration.rst

@@ -XXX,XX +XXX,XX @@ savevm/loadvm functionality.

Debugging

=========

-The migration stream can be analyzed thanks to `scripts/analyze-migration.py`.

+The migration stream can be analyzed thanks to ``scripts/analyze-migration.py``.

Example usage:

@@ -XXX,XX +XXX,XX @@ Common infrastructure

=====================

The files, sockets or fd's that carry the migration stream are abstracted by

-the ``QEMUFile`` type (see `migration/qemu-file.h`). In most cases this

-is connected to a subtype of ``QIOChannel`` (see `io/`).

+the ``QEMUFile`` type (see ``migration/qemu-file.h``). In most cases this

+is connected to a subtype of ``QIOChannel`` (see ``io/``).

Saving the state of one device

@@ -XXX,XX +XXX,XX @@ An example (from hw/input/pckbd.c)

};

We are declaring the state with name "pckbd".

-The `version_id` is 3, and the fields are 4 uint8_t in a KBDState structure.

+The ``version_id`` is 3, and the fields are 4 uint8_t in a KBDState structure.

We registered this with:

.. code:: c

vmstate_register(NULL, 0, &vmstate_kbd, s);

-For devices that are `qdev` based, we can register the device in the class

+For devices that are ``qdev`` based, we can register the device in the class

init function:

.. code:: c

@@ -XXX,XX +XXX,XX @@ another to load the state back.

SaveVMHandlers *ops,

void *opaque);

-Two functions in the ``ops`` structure are the `save_state`

-and `load_state` functions. Notice that `load_state` receives a version_id

-parameter to know what state format is receiving. `save_state` doesn't

+Two functions in the ``ops`` structure are the ``save_state``

+and ``load_state`` functions. Notice that ``load_state`` receives a version_id

+parameter to know what state format is receiving. ``save_state`` doesn't

have a version_id parameter because it always uses the latest version.

Note that because the VMState macros still save the data in a raw

@@ -XXX,XX +XXX,XX @@ migration of a device, and using them breaks backward-migration

compatibility; in general most changes can be made by adding Subsections

(see above) or _TEST macros (see above) which won't break compatibility.

-Each version is associated with a series of fields saved. The `save_state` always saves

-the state as the newer version. But `load_state` sometimes is able to

+Each version is associated with a series of fields saved. The ``save_state`` always saves

+the state as the newer version. But ``load_state`` sometimes is able to

load state from an older version.

You can see that there are several version fields:

-- `version_id`: the maximum version_id supported by VMState for that device.

-- `minimum_version_id`: the minimum version_id that VMState is able to understand

+- ``version_id``: the maximum version_id supported by VMState for that device.

+- ``minimum_version_id``: the minimum version_id that VMState is able to understand

for that device.

-- `minimum_version_id_old`: For devices that were not able to port to vmstate, we can

+- ``minimum_version_id_old``: For devices that were not able to port to vmstate, we can

assign a function that knows how to read this old state. This field is

- ignored if there is no `load_state_old` handler.

+ ignored if there is no ``load_state_old`` handler.

VMState is able to read versions from minimum_version_id to

version_id. And the function ``load_state_old()`` (if present) is able to

@@ -XXX,XX +XXX,XX @@ data and then transferred to the main structure.

If you use memory API functions that update memory layout outside

initialization (i.e., in response to a guest action), this is a strong

-indication that you need to call these functions in a `post_load` callback.