diff options
Diffstat (limited to 'docs/devel')
| -rw-r--r-- | docs/devel/ci-jobs.rst.inc | 2 | ||||
| -rw-r--r-- | docs/devel/docs.rst | 14 | ||||
| -rw-r--r-- | docs/devel/migration/main.rst | 6 | ||||
| -rw-r--r-- | docs/devel/qapi-code-gen.rst | 49 | ||||
| -rw-r--r-- | docs/devel/tcg-ops.rst | 2 | ||||
| -rw-r--r-- | docs/devel/testing.rst | 13 | ||||
| -rw-r--r-- | docs/devel/writing-monitor-commands.rst | 4 |
7 files changed, 60 insertions, 30 deletions
diff --git a/docs/devel/ci-jobs.rst.inc b/docs/devel/ci-jobs.rst.inc index 4c39cdb2d9..ec33e6ee2b 100644 --- a/docs/devel/ci-jobs.rst.inc +++ b/docs/devel/ci-jobs.rst.inc @@ -147,7 +147,7 @@ Set this variable to 1 to create the pipelines, but leave all the jobs to be manually started from the UI Set this variable to 2 to create the pipelines and run all -the jobs immediately, as was historicaly behaviour +the jobs immediately, as was the historical behaviour QEMU_CI_AVOCADO_TESTING ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/devel/docs.rst b/docs/devel/docs.rst index 7da067905b..a7768b5311 100644 --- a/docs/devel/docs.rst +++ b/docs/devel/docs.rst @@ -21,7 +21,7 @@ are processed in two ways: The syntax of these ``.hx`` files is simple. It is broadly an alternation of C code put into the C output and rST format text -put into the documention. A few special directives are recognised; +put into the documentation. A few special directives are recognised; these are all-caps and must be at the beginning of the line. ``HXCOMM`` is the comment marker. The line, including any arbitrary @@ -30,6 +30,13 @@ nor the documentation output. ``SRST`` starts a reStructuredText section. Following lines are put into the documentation verbatim, and discarded from the C output. +The alternative form ``SRST()`` is used to define a label which can be +referenced from elsewhere in the rST documentation. The label will take +the form ``<DOCNAME-HXFILE-LABEL>``, where ``DOCNAME`` is the name of the +top level rST file, ``HXFILE`` is the filename of the .hx file without +the ``.hx`` extension, and ``LABEL`` is the text provided within the +``SRST()`` directive. For example, +``<system/invocation-qemu-options-initrd>``. ``ERST`` ends the documentation section started with ``SRST``, and switches back to a C code section. @@ -53,8 +60,9 @@ text, but in ``hmp-commands.hx`` the C code sections are elements of an array of structs of type ``HMPCommand`` which define the name, behaviour and help text for each monitor command. -In the file ``qemu-options.hx``, do not try to define a +In the file ``qemu-options.hx``, do not try to explicitly define a reStructuredText label within a documentation section. This file is included into two separate Sphinx documents, and some versions of Sphinx will complain about the duplicate label -that results. +that results. Use the ``SRST()`` directive documented above, to +emit an unambiguous label. diff --git a/docs/devel/migration/main.rst b/docs/devel/migration/main.rst index 00b9c3d32f..331252a92c 100644 --- a/docs/devel/migration/main.rst +++ b/docs/devel/migration/main.rst @@ -431,10 +431,10 @@ data doesn't match the stored device data well; it allows an intermediate temporary structure to be populated with migration data and then transferred to the main structure. -If you use memory API functions that update memory layout outside +If you use memory or portio_list 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. -Examples of such memory API functions are: +Examples of such API functions are: - memory_region_add_subregion() - memory_region_del_subregion() @@ -443,6 +443,8 @@ Examples of such memory API functions are: - memory_region_set_enabled() - memory_region_set_address() - memory_region_set_alias_offset() + - portio_list_set_address() + - portio_list_set_enabled() Iterative device migration -------------------------- diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index ea8228518c..6804a4b596 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -167,6 +167,7 @@ Syntax:: '*doc-required': BOOL, '*command-name-exceptions': [ STRING, ... ], '*command-returns-exceptions': [ STRING, ... ], + '*documentation-exceptions': [ STRING, ... ], '*member-name-exceptions': [ STRING, ... ] } } The pragma directive lets you control optional generator behavior. @@ -183,6 +184,10 @@ may contain ``"_"`` instead of ``"-"``. Default is none. Pragma 'command-returns-exceptions' takes a list of commands that may violate the rules on permitted return types. Default is none. +Pragma 'documentation-exceptions' takes a list of types, commands, and +events whose members / arguments need not be documented. Default is +none. + Pragma 'member-name-exceptions' takes a list of types whose member names may contain uppercase letters, and ``"_"`` instead of ``"-"``. Default is none. @@ -737,9 +742,8 @@ Types, commands, and events share a common namespace. Therefore, generally speaking, type definitions should always use CamelCase for user-defined type names, while built-in types are lowercase. -Type names ending with ``Kind`` or ``List`` are reserved for the -generator, which uses them for implicit union enums and array types, -respectively. +Type names ending with ``List`` are reserved for the generator, which +uses them for array types. Command names, member names within a type, and feature names should be all lower case with words separated by a hyphen. However, some @@ -969,7 +973,7 @@ commands and events), member (for structs and unions), branch (for alternates), or value (for enums), a description of each feature (if any), and finally optional tagged sections. -Descriptions start with '\@name:'. The description text should be +Descriptions start with '\@name:'. The description text must be indented like this:: # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed @@ -982,19 +986,20 @@ indented like this:: Extensions added after the definition was first released carry a "(since x.y.z)" comment. -The feature descriptions must be preceded by a line "Features:", like -this:: +The feature descriptions must be preceded by a blank line and then a +line "Features:", like this:: + # # Features: # # @feature: Description text -A tagged section starts with one of the following words: -"Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:". -The section ends with the start of a new section. +A tagged section begins with a paragraph that starts with one of the +following words: "Note:"/"Notes:", "Since:", "Example:"/"Examples:", +"Returns:", "TODO:". It ends with the start of a new section. -The second and subsequent lines of sections other than -"Example"/"Examples" should be indented like this:: +The second and subsequent lines of tagged sections must be indented +like this:: # Note: Ut enim ad minim veniam, quis nostrud exercitation ullamco # laboris nisi ut aliquip ex ea commodo consequat. @@ -1020,11 +1025,11 @@ For example:: # @device: If the stats are for a virtual block device, the name # corresponding to the virtual block device. # - # @node-name: The node name of the device. (since 2.3) + # @node-name: The node name of the device. (Since 2.3) # # ... more members ... # - # Since: 0.14.0 + # Since: 0.14 ## { 'struct': 'BlockStats', 'data': {'*device': 'str', '*node-name': 'str', @@ -1036,19 +1041,19 @@ For example:: # Query the @BlockStats for all virtual block devices. # # @query-nodes: If true, the command will query all the block nodes - # ... explain, explain ... (since 2.3) + # ... explain, explain ... + # (Since 2.3) # # Returns: A list of @BlockStats for each virtual block devices. # - # Since: 0.14.0 + # Since: 0.14 # # Example: # - # -> { "execute": "query-blockstats" } - # <- { - # ... lots of output ... - # } - # + # -> { "execute": "query-blockstats" } + # <- { + # ... lots of output ... + # } ## { 'command': 'query-blockstats', 'data': { '*query-nodes': 'bool' }, @@ -1082,8 +1087,10 @@ need to line up with each other, like this:: # or cache associativity unknown) # (since 5.0) -Section tags are case-sensitive and end with a colon. Good example:: +Section tags are case-sensitive and end with a colon. They are only +recognized after a blank line. Good example:: + # # Since: 7.1 Bad examples (all ordinary paragraphs):: diff --git a/docs/devel/tcg-ops.rst b/docs/devel/tcg-ops.rst index 8ae59ea02b..d46b625e0e 100644 --- a/docs/devel/tcg-ops.rst +++ b/docs/devel/tcg-ops.rst @@ -253,6 +253,8 @@ Jumps/Labels | ``TCG_COND_GEU /* unsigned */`` | ``TCG_COND_LEU /* unsigned */`` | ``TCG_COND_GTU /* unsigned */`` + | ``TCG_COND_TSTEQ /* t1 & t2 == 0 */`` + | ``TCG_COND_TSTNE /* t1 & t2 != 0 */`` Arithmetic ---------- diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst index bd132306c1..fa28e3ecb2 100644 --- a/docs/devel/testing.rst +++ b/docs/devel/testing.rst @@ -728,7 +728,7 @@ For example to setup the HPPA ports builds of Debian:: EXECUTABLE=(pwd)/qemu-hppa V=1 The ``DEB_`` variables are substitutions used by -``debian-boostrap.pre`` which is called to do the initial debootstrap +``debian-bootstrap.pre`` which is called to do the initial debootstrap of the rootfs before it is copied into the container. The second stage is run as part of the build. The final image will be tagged as ``qemu/debian-sid-hppa``. @@ -1346,6 +1346,17 @@ the environment. The definition of *large* is a bit arbitrary here, but it usually means an asset which occupies at least 1GB of size on disk when uncompressed. +SPEED +^^^^^ +Tests which have a long runtime will not be run unless ``SPEED=slow`` is +exported on the environment. + +The definition of *long* is a bit arbitrary here, and it depends on the +usefulness of the test too. A unique test is worth spending more time on, +small variations on existing tests perhaps less so. As a rough guide, +a test or set of similar tests which take more than 100 seconds to +complete. + AVOCADO_ALLOW_UNTRUSTED_CODE ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ There are tests which will boot a kernel image or firmware that can be diff --git a/docs/devel/writing-monitor-commands.rst b/docs/devel/writing-monitor-commands.rst index 2c11e71665..b6ee4fa063 100644 --- a/docs/devel/writing-monitor-commands.rst +++ b/docs/devel/writing-monitor-commands.rst @@ -8,8 +8,8 @@ This document doesn't discuss QMP protocol level details, nor does it dive into the QAPI framework implementation. For an in-depth introduction to the QAPI framework, please refer to -docs/devel/qapi-code-gen.txt. For documentation about the QMP protocol, -start with docs/interop/qmp-intro.txt. +:doc:`qapi-code-gen`. For the QMP protocol, see the +:doc:`/interop/qmp-spec`. New commands may be implemented in QMP only. New HMP commands should be implemented on top of QMP. The typical HMP command wraps around an |