Merge tag 'pull-qapi-2021-11-10' of git://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2021-11-10

# gpg: Signature made Wed 10 Nov 2021 06:21:23 AM CET
# gpg:                using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg:                issuer "armbru@redhat.com"
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [full]
# gpg:                 aka "Markus Armbruster <armbru@pond.sub.org>" [full]

* tag 'pull-qapi-2021-11-10' of git://repo.or.cz/qemu/armbru:
  qapi: Belatedly mark unstable QMP parts with feature 'unstable'
  docs/devel/qapi-code-gen: Belatedly document feature documentation
  docs/devel/qapi-code-gen: Drop a duplicate paragraph

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

docs/devel/qapi-code-gen.rst

@@ -956,15 +956,16 @@ definition must have documentation.
 Definition documentation starts with a line naming the definition,
 followed by an optional overview, a description of each argument (for
 commands and events), member (for structs and unions), branch (for
-alternates), or value (for enums), and finally optional tagged
-sections.
+alternates), or value (for enums), a description of each feature (if
+any), and finally optional tagged sections.
 
-Descriptions of arguments can span multiple lines.  The description
-text can start on the line following the '\@argname:', in which case it
-must not be indented at all.  It can also start on the same line as
-the '\@argname:'.  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::
+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
@@ -986,6 +987,12 @@ The number of spaces between the ':' and the text is not significant.
 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::
+
+  # 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.
@@ -1000,12 +1007,6 @@ multiline argument descriptions.
 A 'Since: x.y.z' tagged section lists the release that introduced the
 definition.
 
-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.
-
 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.

qapi/machine.json

@@ -1417,107 +1417,143 @@
 #
 # Query interrupt statistics
 #
+# Features:
+# @unstable: This command is meant for debugging.
+#
 # Returns: interrupt statistics
 #
 # Since: 6.2
 ##
 { 'command': 'x-query-irq',
-  'returns': 'HumanReadableText' }
+  'returns': 'HumanReadableText',
+  'features': [ 'unstable' ] }
 
 ##
 # @x-query-jit:
 #
 # Query TCG compiler statistics
 #
+# Features:
+# @unstable: This command is meant for debugging.
+#
 # Returns: TCG compiler statistics
 #
 # Since: 6.2
 ##
 { 'command': 'x-query-jit',
   'returns': 'HumanReadableText',
-  'if': 'CONFIG_TCG' }
+  'if': 'CONFIG_TCG',
+  'features': [ 'unstable' ] }
 
 ##
 # @x-query-numa:
 #
 # Query NUMA topology information
 #
+# Features:
+# @unstable: This command is meant for debugging.
+#
 # Returns: topology information
 #
 # Since: 6.2
 ##
 { 'command': 'x-query-numa',
-  'returns': 'HumanReadableText' }
+  'returns': 'HumanReadableText',
+  'features': [ 'unstable' ] }
 
 ##
 # @x-query-opcount:
 #
 # Query TCG opcode counters
 #
+# Features:
+# @unstable: This command is meant for debugging.
+#
 # Returns: TCG opcode counters
 #
 # Since: 6.2
 ##
 { 'command': 'x-query-opcount',
   'returns': 'HumanReadableText',
-  'if': 'CONFIG_TCG' }
+  'if': 'CONFIG_TCG',
+  'features': [ 'unstable' ] }
 
 ##
 # @x-query-profile:
 #
 # Query TCG profiling information
 #
+# Features:
+# @unstable: This command is meant for debugging.
+#
 # Returns: profile information
 #
 # Since: 6.2
 ##
 { 'command': 'x-query-profile',
-  'returns': 'HumanReadableText' }
+  'returns': 'HumanReadableText',
+  'features': [ 'unstable' ] }
 
 ##
 # @x-query-ramblock:
 #
 # Query system ramblock information
 #
+# Features:
+# @unstable: This command is meant for debugging.
+#
 # Returns: system ramblock information
 #
 # Since: 6.2
 ##
 { 'command': 'x-query-ramblock',
-  'returns': 'HumanReadableText' }
+  'returns': 'HumanReadableText',
+  'features': [ 'unstable' ] }
 
 ##
 # @x-query-rdma:
 #
 # Query RDMA state
 #
+# Features:
+# @unstable: This command is meant for debugging.
+#
 # Returns: RDMA state
 #
 # Since: 6.2
 ##
 { 'command': 'x-query-rdma',
-  'returns': 'HumanReadableText' }
+  'returns': 'HumanReadableText',
+  'features': [ 'unstable' ] }
 
 ##
 # @x-query-roms:
 #
 # Query information on the registered ROMS
 #
+# Features:
+# @unstable: This command is meant for debugging.
+#
 # Returns: registered ROMs
 #
 # Since: 6.2
 ##
 { 'command': 'x-query-roms',
-  'returns': 'HumanReadableText' }
+  'returns': 'HumanReadableText',
+  'features': [ 'unstable' ] }
 
 ##
 # @x-query-usb:
 #
 # Query information on the USB devices
 #
+# Features:
+# @unstable: This command is meant for debugging.
+#
 # Returns: USB device information
 #
 # Since: 6.2
 ##
 { 'command': 'x-query-usb',
-  'returns': 'HumanReadableText' }
+  'returns': 'HumanReadableText',
+  'features': [ 'unstable' ] }