[PULL 0/3] QAPI patches patches for 2021-11-10

[PULL 0/3] QAPI patches patches for 2021-11-10

[Markus Armbruster]

The following changes since commit 0a70bcf18caf7a61d480f8448723c15209d128ef:

  Update version for v6.2.0-rc0 release (2021-11-09 18:22:57 +0100)

are available in the Git repository at:

  git://repo.or.cz/qemu/armbru.git tags/pull-qapi-2021-11-10

for you to fetch changes up to 8c0bae5a19478db93371570b57164c63392a2d50:

  qapi: Belatedly mark unstable QMP parts with feature 'unstable' (2021-11-10 06:10:11 +0100)

----------------------------------------------------------------
QAPI patches patches for 2021-11-10

----------------------------------------------------------------
Markus Armbruster (3):
      docs/devel/qapi-code-gen: Drop a duplicate paragraph
      docs/devel/qapi-code-gen: Belatedly document feature documentation
      qapi: Belatedly mark unstable QMP parts with feature 'unstable'

 docs/devel/qapi-code-gen.rst | 29 ++++++++++++------------
 qapi/machine.json            | 54 ++++++++++++++++++++++++++++++++++++--------
 2 files changed, 60 insertions(+), 23 deletions(-)

-- 
2.31.1

[PULL 1/3] docs/devel/qapi-code-gen: Drop a duplicate paragraph

[Markus Armbruster]

Commit 55ec69f8b1 "docs/devel/qapi-code-gen.txt: Update to new rST
backend conventions" accidentally duplicated a paragraph.  Drop it.

Cc: Peter Maydell <peter.maydell@linaro.org>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20211026111023.76937-2-armbru@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>
---
 docs/devel/qapi-code-gen.rst | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index 38f2d7aad3..b5761f60cd 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -1000,12 +1000,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.
-- 
2.31.1

[PULL 2/3] docs/devel/qapi-code-gen: Belatedly document feature documentation

[Markus Armbruster]

Commit 6a8c0b5102 "qapi: Add feature flags to struct types" neglected
to document how to document feature flags.  Make up for that.

Cc: Kevin Wolf <kwolf@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20211026111023.76937-3-armbru@redhat.com>
[Editing accident fixed]
---
 docs/devel/qapi-code-gen.rst | 23 +++++++++++++++--------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index b5761f60cd..a3b5473089 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/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.
-- 
2.31.1

[PULL 3/3] qapi: Belatedly mark unstable QMP parts with feature 'unstable'

[Markus Armbruster]

The work in merge commit e86e00a2493 lacks special feature flag
'unstable', because it raced with it.  Add it where it's missing.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20211109145559.2122827-1-armbru@redhat.com>
Reviewed-by: Damien Hedde <damien.hedde@greensocs.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
---
 qapi/machine.json | 54 +++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 45 insertions(+), 9 deletions(-)

diff --git a/qapi/machine.json b/qapi/machine.json
index 17794ef681..067e3f5378 100644
--- a/qapi/machine.json
+++ b/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' ] }
-- 
2.31.1

Re: [PULL 0/3] QAPI patches patches for 2021-11-10

[Richard Henderson]

On 11/10/21 7:18 AM, Markus Armbruster wrote:
> The following changes since commit 0a70bcf18caf7a61d480f8448723c15209d128ef:
> 
>    Update version for v6.2.0-rc0 release (2021-11-09 18:22:57 +0100)
> 
> are available in the Git repository at:
> 
>    git://repo.or.cz/qemu/armbru.git tags/pull-qapi-2021-11-10
> 
> for you to fetch changes up to 8c0bae5a19478db93371570b57164c63392a2d50:
> 
>    qapi: Belatedly mark unstable QMP parts with feature 'unstable' (2021-11-10 06:10:11 +0100)
> 
> ----------------------------------------------------------------
> QAPI patches patches for 2021-11-10
> 
> ----------------------------------------------------------------
> Markus Armbruster (3):
>        docs/devel/qapi-code-gen: Drop a duplicate paragraph
>        docs/devel/qapi-code-gen: Belatedly document feature documentation
>        qapi: Belatedly mark unstable QMP parts with feature 'unstable'
> 
>   docs/devel/qapi-code-gen.rst | 29 ++++++++++++------------
>   qapi/machine.json            | 54 ++++++++++++++++++++++++++++++++++++--------
>   2 files changed, 60 insertions(+), 23 deletions(-)

Applied, thanks.

r~