Merge tag 'pull-qapi-2023-05-09-v2' of https://repo.or.cz/qemu/armbru …

…into staging

QAPI patches patches for 2023-05-09

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmRbUEYSHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTmzEP/3pDpVxpP7xXLevl2vFqkFyHEjc0L3N4
# x//ljgQojAdM6WU3e0qqOfp/NE2ktUg5D3z+QNiVP1/xXv/dtMGATdG+X9AZs0US
# XnhdicYdBng8bGuhlNuNY8QJ/I4ALwUR44LVOYibVohv2RVYWBapGiHowpyTyABq
# sFSHrj/cgvTMUn53yp7veZTo6rWG6RU/D5uUTOMsvKeAoHoOXMyBxV01SCt84t/J
# pcelINcriP6cQVzgfm1B39UNa0IxinGxEx/IIaxz5Ju66G05HTs4CsBFAF6/0QI/
# 3YerGWPt9fF6+qYNn21Gg9CL1fHHppNqTXkcuTeGn/Ohg53bosktti5Ysn73vtpR
# GWsJr6M4KQ1SwEbZIiFZCS3A4VTbRcr7WkXets39pcpxGDlNisi+zfV95kNo09xR
# hxi8SuWgb2OfQpVs/71eunp+PM1ZQsODurcy4x0/rlYJfhk53kQSMRtlfy5Cn6uY
# +weWUgygBSWG/w0qanWWK5TF1DNlRKzbix6cmMuGGKcpyF7EMWE1kqmjmmu7CQvM
# a3aPTqGtUt0LeqBQIhmeq/jEwd3vxQa1R85gd0/0sWxEMHkPXVfVoaryiaWAykye
# 7r+c8o/41c44zs8YxdZrz72su9fqKC/TeVf5soU46ZucmH8D6f7QHy+s1ec2PEjY
# l6cRIXTXHeQe
# =j6cJ
# -----END PGP SIGNATURE-----
# gpg: Signature made Wed 10 May 2023 09:05:26 AM BST
# gpg:                using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg:                issuer "armbru@redhat.com"
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [undefined]
# gpg:                 aka "Markus Armbruster <armbru@pond.sub.org>" [undefined]
# gpg: WARNING: This key is not certified with a trusted signature!
# gpg:          There is no indication that the signature belongs to the owner.
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867  4E5F 3870 B400 EB91 8653

* tag 'pull-qapi-2023-05-09-v2' of https://repo.or.cz/qemu/armbru:
  qapi: Reformat doc comments to conform to current conventions
  qga/qapi-schema: Reformat doc comments to conform to current conventions
  docs/devel/qapi-code-gen: Update doc comment conventions
  qapi: Section parameter @indent is no longer used, drop
  qapi: Relax doc string @name: description indentation rules
  qapi: Rewrite parsing of doc comment section symbols and tags
  qapi: Fix argument description indentation stripping
  tests/qapi-schema/doc-good: Improve argument description tests
  tests/qapi-schema/doc-good: Improve a comment
  qapi/dump: Indent bulleted lists consistently
  qapi: Tidy up a slightly awkward TODO comment
  sphinx/qapidoc: Do not emit TODO sections into user manuals
  Revert "qapi: BlockExportRemoveMode: move comments to TODO"
  meson: Fix to make QAPI generator output depend on main.py
  qapi: Fix crash on stray double quote character
  docs/devel/qapi-code-gen: Turn FIXME admonitions into comments
  docs/devel/qapi-code-gen: Clean up use of quotes a bit

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

docs/devel/qapi-code-gen.rst

@@ -947,6 +947,11 @@ Example::
  #   <- get that
  ##
 
+For legibility, wrap text paragraphs so every line is at most 70
+characters long.
+
+Separate sentences with two spaces.
+
 
 Definition documentation
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -963,57 +968,46 @@ 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.
 
-The description of an argument or feature 'name' starts with
-'\@name:'.  The description text can start on the line following the
-'\@name:', in which case it must not be indented at all.  It can also
-start on the same line as the '\@name:'.  In this case if it spans
-multiple lines then second and subsequent lines must be indented to
-line up with the first character of the first line of the
-description::
-
- # @argone:
- # This is a two line description
- # in the first style.
- #
- # @argtwo: This is a two line description
- #          in the second style.
-
-The number of spaces between the ':' and the text is not significant.
-
-.. admonition:: FIXME
+Descriptions start with '\@name:'.  The description text should be
+indented like this::
 
-   The parser accepts these things in almost any order.
+ # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+ #     do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
-.. admonition:: FIXME
+.. FIXME The parser accepts these things in almost any order.
 
-   union branches should be described, too.
+.. FIXME union branches should be described, too.
 
 Extensions added after the definition was first released carry a
-'(since x.y.z)' comment.
+"(since x.y.z)" comment.
 
 The feature descriptions must be preceded by 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.
 
-The text of a section can start on a new line, in
-which case it must not be indented at all.  It can also start
-on the same line as the 'Note:', 'Returns:', etc tag.  In this
-case if it spans multiple lines then second and subsequent
-lines must be indented to match the first, in the same way as
-multiline argument descriptions.
+The second and subsequent lines of sections other than
+"Example"/"Examples" should be indented like this::
 
-A 'Since: x.y.z' tagged section lists the release that introduced the
+ # Note: Ut enim ad minim veniam, quis nostrud exercitation ullamco
+ #     laboris nisi ut aliquip ex ea commodo consequat.
+ #
+ #     Duis aute irure dolor in reprehenderit in voluptate velit esse
+ #     cillum dolore eu fugiat nulla pariatur.
+
+A "Since: x.y.z" tagged section lists the release that introduced the
 definition.
 
-An 'Example' or 'Examples' section is automatically rendered
-entirely as literal fixed-width text.  In other sections,
-the text is formatted, and rST markup can be used.
+An "Example" or "Examples" section is rendered entirely
+as literal fixed-width text.  "TODO" sections are not rendered at all
+(they are for developers, not users of QMP).  In other sections, the
+text is formatted, and rST markup can be used.
 
 For example::
 
@@ -1023,7 +1017,7 @@ For example::
  # Statistics of a virtual block device or a block backing device.
  #
  # @device: If the stats are for a virtual block device, the name
- #          corresponding to the virtual block device.
+ #     corresponding to the virtual block device.
  #
  # @node-name: The node name of the device. (since 2.3)
  #
@@ -1040,8 +1034,8 @@ 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)
+ # @query-nodes: If true, the command will query all the block nodes
+ #     ... explain, explain ...  (since 2.3)
  #
  # Returns: A list of @BlockStats for each virtual block devices.
  #
@@ -1078,10 +1072,14 @@ Indentation matters.  Bad example::
 
  # @none: None (no memory side cache in this proximity domain,
  #              or cache associativity unknown)
+ #     (since 5.0)
 
-The description is parsed as a definition list with term "None (no
-memory side cache in this proximity domain," and definition "or cache
-associativity unknown)".
+The last line's de-indent is wrong.  The second and subsequent lines
+need to line up with each other, like this::
+
+ # @none: None (no memory side cache in this proximity domain,
+ #     or cache associativity unknown)
+ #     (since 5.0)
 
 Section tags are case-sensitive and end with a colon.  Good example::
 

docs/sphinx/qapidoc.py

@@ -268,6 +268,9 @@ def _nodes_for_sections(self, doc):
         """Return list of doctree nodes for additional sections"""
         nodelist = []
         for section in doc.sections:
+            if section.name and section.name == 'TODO':
+                # Hide TODO: sections
+                continue
             snode = self._make_section(section.name)
             if section.name and section.name.startswith('Example'):
                 snode += self._nodes_for_example(section.text)

meson.build

@@ -2838,12 +2838,12 @@ qapi_gen_depends = [ meson.current_source_dir() / 'scripts/qapi/__init__.py',
                      meson.current_source_dir() / 'scripts/qapi/expr.py',
                      meson.current_source_dir() / 'scripts/qapi/gen.py',
                      meson.current_source_dir() / 'scripts/qapi/introspect.py',
+                     meson.current_source_dir() / 'scripts/qapi/main.py',
                      meson.current_source_dir() / 'scripts/qapi/parser.py',
                      meson.current_source_dir() / 'scripts/qapi/schema.py',
                      meson.current_source_dir() / 'scripts/qapi/source.py',
                      meson.current_source_dir() / 'scripts/qapi/types.py',
                      meson.current_source_dir() / 'scripts/qapi/visit.py',
-                     meson.current_source_dir() / 'scripts/qapi/common.py',
                      meson.current_source_dir() / 'scripts/qapi-gen.py'
 ]
 

qapi/acpi.json

@@ -14,18 +14,19 @@
 #
 # Specify an ACPI table on the command line to load.
 #
-# At most one of @file and @data can be specified. The list of files specified
-# by any one of them is loaded and concatenated in order. If both are omitted,
-# @data is implied.
+# At most one of @file and @data can be specified.  The list of files
+# specified by any one of them is loaded and concatenated in order.
+# If both are omitted, @data is implied.
 #
-# Other fields / optargs can be used to override fields of the generic ACPI
-# table header; refer to the ACPI specification 5.0, section 5.2.6 System
-# Description Table Header. If a header field is not overridden, then the
-# corresponding value from the concatenated blob is used (in case of @file), or
-# it is filled in with a hard-coded value (in case of @data).
+# Other fields / optargs can be used to override fields of the generic
+# ACPI table header; refer to the ACPI specification 5.0, section
+# 5.2.6 System Description Table Header.  If a header field is not
+# overridden, then the corresponding value from the concatenated blob
+# is used (in case of @file), or it is filled in with a hard-coded
+# value (in case of @data).
 #
-# String fields are copied into the matching ACPI member from lowest address
-# upwards, and silently truncated / NUL-padded to length.
+# String fields are copied into the matching ACPI member from lowest
+# address upwards, and silently truncated / NUL-padded to length.
 #
 # @sig: table signature / identifier (4 bytes)
 #
@@ -38,20 +39,20 @@
 # @oem_rev: OEM-supplied revision number (4 bytes)
 #
 # @asl_compiler_id: identifier of the utility that created the table
-#                   (4 bytes)
+#     (4 bytes)
 #
 # @asl_compiler_rev: revision number of the utility that created the
-#                    table (4 bytes)
+#     table (4 bytes)
 #
-# @file: colon (:) separated list of pathnames to load and
-#        concatenate as table data. The resultant binary blob is expected to
-#        have an ACPI table header. At least one file is required. This field
-#        excludes @data.
+# @file: colon (:) separated list of pathnames to load and concatenate
+#     as table data.  The resultant binary blob is expected to have an
+#     ACPI table header.  At least one file is required.  This field
+#     excludes @data.
 #
-# @data: colon (:) separated list of pathnames to load and
-#        concatenate as table data. The resultant binary blob must not have an
-#        ACPI table header. At least one file is required. This field excludes
-#        @file.
+# @data: colon (:) separated list of pathnames to load and concatenate
+#     as table data.  The resultant binary blob must not have an ACPI
+#     table header.  At least one file is required.  This field
+#     excludes @file.
 #
 # Since: 1.5
 ##
@@ -71,16 +72,17 @@
 # @ACPISlotType:
 #
 # @DIMM: memory slot
+#
 # @CPU: logical CPU slot (since 2.7)
 ##
 { 'enum': 'ACPISlotType', 'data': [ 'DIMM', 'CPU' ] }
 
 ##
 # @ACPIOSTInfo:
 #
-# OSPM Status Indication for a device
-# For description of possible values of @source and @status fields
-# see "_OST (OSPM Status Indication)" chapter of ACPI5.0 spec.
+# OSPM Status Indication for a device For description of possible
+# values of @source and @status fields see "_OST (OSPM Status
+# Indication)" chapter of ACPI5.0 spec.
 #
 # @device: device ID associated with slot
 #
@@ -117,7 +119,6 @@
 #                  { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
 #                  { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
 #    ]}
-#
 ##
 { 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] }
 
@@ -136,7 +137,6 @@
 #      "data": { "info": { "device": "d1", "slot": "0",
 #                          "slot-type": "DIMM", "source": 1, "status": 0 } },
 #      "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
-#
 ##
 { 'event': 'ACPI_DEVICE_OST',
      'data': { 'info': 'ACPIOSTInfo' } }