SYS-OSS/FRET-qemu
4
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

QAPI patches patches for 2025-04-08

Browse Source 
-----BEGIN PGP SIGNATURE-----
 
 iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmf0y3ESHGFybWJydUBy
 ZWRoYXQuY29tAAoJEDhwtADrkYZTSXgP/iSQ0F/8GFqdX9+k5WJ7Sd+IzxJPkPM2
 UnjhT2viBP7pC2/Ok2NFfUnigXBCNFyLX/TNcWAK1RMfxuj9GWSJqAMxrMlTPgp0
 Oef3RdE4gQ0h/8/hA8VwdAHza9ItAdZDmpOYO1JGq1B+FVb0P8HPtwKYFhf+gMGa
 YcEuwD6DkilbPGnSEBmN7t78V7yp/pQ6SL/38O97aVyEmrVGtqAD1KiV2Va7JjVF
 GoOYivejTyqJeaY9dvPxxfWi/3HAPFN+q2giNZe+dOPuyYQ6oeryIyJM+sM1/8xG
 PTJayBnV7f8tXPvWrJVyiMC8vWropZ3ExY2/YJ2WNmhJIvrhj9pVxiCUgD18Akgf
 McvDjExVilIMNQCBnRLdrXDFWcc8Y+/GlVMB386a0X9OS+be3Am6b34MDG3UMjvy
 6SL4fyOyfBkBNxrsJnngcMZgUf/VcwdLBGMGfpS9kjsXEQtlV9SfB3TbBnRMfh+t
 DWSLnEFh5AaYOnmGcC6+JG9sttM93+Boyq/tqi8n+38TDQswOB8q/XtSdHYd0f6L
 dEfD0kRmaOCOrWjakeRKvDJ0IvZbWl/iBmYDfSbe6cFIeMC82cR8sud7WYhZLk+D
 /Q0hMp7u7954ASxdM+P6iuPE17586edtWkk442uH/vKKkwYoPFyBN6+LSNAJEREX
 4SHZhLuHCNNN
 =X7db
 -----END PGP SIGNATURE-----

Merge tag 'pull-qapi-2025-04-08' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2025-04-08

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmf0y3ESHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTSXgP/iSQ0F/8GFqdX9+k5WJ7Sd+IzxJPkPM2
# UnjhT2viBP7pC2/Ok2NFfUnigXBCNFyLX/TNcWAK1RMfxuj9GWSJqAMxrMlTPgp0
# Oef3RdE4gQ0h/8/hA8VwdAHza9ItAdZDmpOYO1JGq1B+FVb0P8HPtwKYFhf+gMGa
# YcEuwD6DkilbPGnSEBmN7t78V7yp/pQ6SL/38O97aVyEmrVGtqAD1KiV2Va7JjVF
# GoOYivejTyqJeaY9dvPxxfWi/3HAPFN+q2giNZe+dOPuyYQ6oeryIyJM+sM1/8xG
# PTJayBnV7f8tXPvWrJVyiMC8vWropZ3ExY2/YJ2WNmhJIvrhj9pVxiCUgD18Akgf
# McvDjExVilIMNQCBnRLdrXDFWcc8Y+/GlVMB386a0X9OS+be3Am6b34MDG3UMjvy
# 6SL4fyOyfBkBNxrsJnngcMZgUf/VcwdLBGMGfpS9kjsXEQtlV9SfB3TbBnRMfh+t
# DWSLnEFh5AaYOnmGcC6+JG9sttM93+Boyq/tqi8n+38TDQswOB8q/XtSdHYd0f6L
# dEfD0kRmaOCOrWjakeRKvDJ0IvZbWl/iBmYDfSbe6cFIeMC82cR8sud7WYhZLk+D
# /Q0hMp7u7954ASxdM+P6iuPE17586edtWkk442uH/vKKkwYoPFyBN6+LSNAJEREX
# 4SHZhLuHCNNN
# =X7db
# -----END PGP SIGNATURE-----
# gpg: Signature made Tue 08 Apr 2025 03:08:33 EDT
# 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]
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867  4E5F 3870 B400 EB91 8653

* tag 'pull-qapi-2025-04-08' of https://repo.or.cz/qemu/armbru:
  qga/qapi-schema: Add a proper introduction
  storage-daemon/qapi/qapi-schema: Add a proper introduction
  qapi/qapi-schema: Address the introduction's bit rot
  qapi/qapi-schema: Update introduction for example notation
  docs/sphinx/qmp_lexer: Highlight elisions like comments, not prompts
  docs/sphinx/qmp_lexer: Generalize elision syntax
  docs/devel/qapi-code-gen: Improve the part on qmp-example directive
  docs/interop: Sanitize QMP reference manuals TOC
  docs/interop: Delete "QEMU Guest Agent Protocol Reference" TOC
  qapi/rocker: Tidy up query-rocker-of-dpa-flows example
  docs/devel/qapi-code-gen: Tidy up whitespace

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
This commit is contained in:
Stefan Hajnoczi 2025-04-08 09:12:40 -04:00
commit cd9e18641b
12 changed files with 83 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
docs/devel/qapi-code-gen.rst
View File

@ -763,8 +763,8 @@ Names beginning with ``x-`` used to signify "experimental". This
convention has been replaced by special feature "unstable".
Pragmas ``command-name-exceptions`` and ``member-name-exceptions`` let
you violate naming rules. Use for new code is strongly discouraged. See
`Pragma directives`_ for details.
you violate naming rules. Use for new code is strongly discouraged.
See `Pragma directives`_ for details.
Downstream extensions
@ -1013,7 +1013,7 @@ like this::
document the success and the error response, respectively.
"Errors" sections should be formatted as an rST list, each entry
detailing a relevant error condition. For example::
detailing a relevant error condition. For example::
# Errors:
# - If @device does not exist, DeviceNotFound
@ -1026,31 +1026,28 @@ definition.
QMP). In other sections, the text is formatted, and rST markup can be
used.
QMP Examples can be added by using the ``.. qmp-example::``
directive. In its simplest form, this can be used to contain a single
QMP code block which accepts standard JSON syntax with additional server
directionality indicators (``->`` and ``<-``), and elisions (``...``).
QMP Examples can be added by using the ``.. qmp-example::`` directive.
In its simplest form, this can be used to contain a single QMP code
block which accepts standard JSON syntax with additional server
directionality indicators (``->`` and ``<-``), and elisions. An
elision is commonly ``...``, but it can also be or a pair of ``...``
with text in between.
Optionally, a plaintext title may be provided by using the ``:title:``
directive option. If the title is omitted, the example title will
directive option. If the title is omitted, the example title will
default to "Example:".
A simple QMP example::
# .. qmp-example::
# :title: Using query-block
#
# -> { "execute": "query-block" }
# <- { ... }
# -> { "execute": "query-name" }
# <- { "return": { "name": "Fred" } }
More complex or multi-step examples where exposition is needed before or
between QMP code blocks can be created by using the ``:annotated:``
directive option. When using this option, nested QMP code blocks must be
entered explicitly with rST's ``::`` syntax.
Highlighting in non-QMP languages can be accomplished by using the
``.. code-block:: lang`` directive, and non-highlighted text can be
achieved by omitting the language argument.
More complex or multi-step examples where exposition is needed before
or between QMP code blocks can be created by using the ``:annotated:``
directive option. When using this option, nested QMP code blocks must
be entered explicitly with rST's ``::`` syntax.
For example::
@ -1061,11 +1058,21 @@ For example::
# This is a more complex example that can use
# ``arbitrary rST syntax`` in its exposition::
#
# -> { "execute": "query-block" }
# <- { ... }
# -> { "execute": "query-block" }
# <- { "return": [
# {
# "device": "ide0-hd0",
# ...
# }
# ... more ...
# ] }
#
# Above, lengthy output has been omitted for brevity.
Highlighting in non-QMP languages can be accomplished by using the
``.. code-block:: lang`` directive, and non-highlighted text can be
achieved by omitting the language argument.
Examples of complete definition documentation::
@ -1466,7 +1473,9 @@ As an example, we'll use the following schema, which describes a
single complex user-defined type, along with command which takes a
list of that type as a parameter, and returns a single element of that
type. The user is responsible for writing the implementation of
qmp_my_command(); everything else is produced by the generator. ::
qmp_my_command(); everything else is produced by the generator.
::
$ cat example-schema.json
{ 'struct': 'UserDefOne',

3
docs/interop/qemu-ga-ref.rst
View File

@ -1,9 +1,6 @@
QEMU Guest Agent Protocol Reference
===================================
.. contents::
:depth: 3
.. qapi-doc:: qga/qapi-schema.json
:transmogrify:
:namespace: QGA

2
docs/interop/qemu-qmp-ref.rst
View File

@ -4,7 +4,7 @@ QEMU QMP Reference Manual
=========================
.. contents::
:depth: 3
:local:
.. qapi-doc:: qapi/qapi-schema.json
:transmogrify:

2
docs/interop/qemu-storage-daemon-qmp-ref.rst
View File

@ -2,7 +2,7 @@ QEMU Storage Daemon QMP Reference Manual
========================================
.. contents::
:depth: 3
:local:
.. qapi-doc:: storage-daemon/qapi/qapi-schema.json
:transmogrify:

2
docs/sphinx/qmp_lexer.py
View File

@ -24,7 +24,7 @@ class QMPExampleMarkersLexer(RegexLexer):
'root': [
(r'-> ', token.Generic.Prompt),
(r'<- ', token.Generic.Prompt),
(r' ?\.{3} ?', token.Generic.Prompt),
(r'\.{3}( .* \.{3})?', token.Comment.Multiline),
]
}

31
qapi/qapi-schema.json
View File

@ -3,37 +3,24 @@
##
# = Introduction
#
# This document describes all commands currently supported by QMP.
# This manual describes the commands and events supported by the QEMU
# Monitor Protocol (QMP).
#
# For locating a particular item, please see the `qapi-qmp-index`.
#
# Most of the time their usage is exactly the same as in the user
# Monitor, this means that any other document which also describe
# commands (the manpage, QEMU's manual, etc) can and should be
# consulted.
# The following notation is used in examples:
#
# QMP has two types of commands: regular and query commands. Regular
# commands usually change the Virtual Machine's state someway, while
# query commands just return information. The sections below are
# divided accordingly.
# .. qmp-example::
#
# It's important to observe that all communication examples are
# formatted in a reader-friendly way, so that they're easier to
# understand. However, in real protocol usage, they're emitted as a
# single line.
# -> ... text sent by client (commands) ...
# <- ... text sent by server (command responses and events) ...
#
# Also, the following notation is used to denote data flow:
#
# Example:
#
# ::
#
# -> data issued by the Client
# <- Server data response
# Example text is formatted for readability. However, in real
# protocol usage, its commonly emitted as a single line.
#
# Please refer to the
# :doc:`QEMU Machine Protocol Specification </interop/qmp-spec>`
# for detailed information on the Server command and response formats.
# for the general format of commands, responses, and events.
##
{ 'include': 'pragma.json' }

2
qapi/rocker.json
View File

@ -254,7 +254,7 @@
# "action": {"goto-tbl": 10},
# "mask": {"in-pport": 4294901760}
# },
# {...},
# ...
# ]}
##
{ 'command': 'query-rocker-of-dpa-flows',

20
qga/qapi-schema.json
View File

@ -2,10 +2,24 @@
# vim: filetype=python
##
# = QEMU guest agent protocol commands and structs
# This manual describes the commands supported by the QEMU Guest
# Agent Protocol.
#
# For a concise listing of all commands, events, and types in the QEMU
# guest agent, please consult the `qapi-qga-index`.
# For locating a particular item, please see the `qapi-qga-index`.
#
# The following notation is used in examples:
#
# .. qmp-example::
#
# -> ... text sent by client (commands) ...
# <- ... text sent by server (command responses and events) ...
#
# Example text is formatted for readability. However, in real
# protocol usage, its commonly emitted as a single line.
#
# Please refer to the
# :doc:`QEMU Machine Protocol Specification </interop/qmp-spec>`
# for the general format of commands, responses, and events.
##
{ 'pragma': { 'doc-required': true } }

22
storage-daemon/qapi/qapi-schema.json
View File

@ -14,10 +14,26 @@
# storage daemon.
##
# = QEMU storage daemon protocol commands and structs
# = Introduction
#
# For a concise listing of all commands, events, and types in the QEMU
# storage daemon, please consult the `qapi-qsd-index`.
# This manual describes the commands and events supported by the QEMU
# storage daemon QMP.
#
# For locating a particular item, please see the `qapi-qsd-index`.
#
# The following notation is used in examples:
#
# .. qmp-example::
#
# -> ... text sent by client (commands) ...
# <- ... text sent by server (command responses and events) ...
#
# Example text is formatted for readability. However, in real
# protocol usage, its commonly emitted as a single line.
#
# Please refer to the
# :doc:`QEMU Machine Protocol Specification </interop/qmp-spec>`
# for the general format of commands, responses, and events.
##

2
tests/qapi-schema/doc-good.json
View File

@ -212,7 +212,7 @@
#
# -> "this example"
#
# <- "has no title"
# <- ... has no title ...
##
{ 'command': 'cmd-boxed', 'boxed': true,
'data': 'Object',

2
tests/qapi-schema/doc-good.out
View File

@ -217,7 +217,7 @@ another feature
-> "this example"
<- "has no title"
<- ... has no title ...
doc symbol=EVT_BOXED
body=

2
tests/qapi-schema/doc-good.txt
View File

@ -264,7 +264,7 @@ Example::
-> "this example"
<- "has no title"
<- ... has no title ...
"EVT_BOXED" (Event)