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

QAPI patches patches for 2024-07-06

Browse Source 
-----BEGIN PGP SIGNATURE-----
 
 iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmaI6xcSHGFybWJydUBy
 ZWRoYXQuY29tAAoJEDhwtADrkYZTTbQP/AonsqGYQyOPCWae9dfDt+Wy+k2gthoB
 dn/3SRjYnA23avEv2/AGAPxgp5MHkpdhh8eqNjWq9QgqgEUh/m0nJztS/MiLMHsR
 /PENPy4V2QFf7s5XtIutLiKXgGbzwtHxrbwnCNyQZW6dAK67VBTq5hPQSxFwBVga
 FDVm+DS2JehJ7IPMVmPT5gjI2cyDYNc/rxbvcbcb5SqirfJdPFk9nMJUrQ0Qubfs
 c9D6l8Cwzbm4JfSeRThs8v9CsDZ1+OIXnpDgGAP9hr7+yYFsovLSHfiLGFxnFXiN
 gSKLBNRIzXnC9cFsKY4jXuqFoSFblRccqCtPSYb7sAp3OVwKq3kA/XNuPIAPii8S
 cm+bhVJ3lyXUW5/6qruS5tOEkpsTnXC45Uw9nvZDEVXANMn3viZ1qInxKak8Nr+p
 k0bOHGE4NzRKkAvGDaTooUOlhG4iy9M+Q4dTcwKIoXTs1Euo8uOjAL+jGwT2pan5
 fb/P1cIqMgMpwSQjwIs7LoYMk20FF44CPtuwA+m85iLbTiiuUfQ4bTnVNMOQMibq
 3QWIrEDfxwrvwMPsv/u/hcc5d2Tb+5QP9CeVmT9woSXJqU2g4yvKKP9JBf7jUFMC
 fTpNRcHOWsIoz+AgOrUeYe67fLpqUWQii08JhPg5f4ybbEzkzZub0zOKNFLYumG0
 VT3BQlO+8LdW
 =RwDq
 -----END PGP SIGNATURE-----

Merge tag 'pull-qapi-2024-07-06' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2024-07-06

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmaI6xcSHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTTbQP/AonsqGYQyOPCWae9dfDt+Wy+k2gthoB
# dn/3SRjYnA23avEv2/AGAPxgp5MHkpdhh8eqNjWq9QgqgEUh/m0nJztS/MiLMHsR
# /PENPy4V2QFf7s5XtIutLiKXgGbzwtHxrbwnCNyQZW6dAK67VBTq5hPQSxFwBVga
# FDVm+DS2JehJ7IPMVmPT5gjI2cyDYNc/rxbvcbcb5SqirfJdPFk9nMJUrQ0Qubfs
# c9D6l8Cwzbm4JfSeRThs8v9CsDZ1+OIXnpDgGAP9hr7+yYFsovLSHfiLGFxnFXiN
# gSKLBNRIzXnC9cFsKY4jXuqFoSFblRccqCtPSYb7sAp3OVwKq3kA/XNuPIAPii8S
# cm+bhVJ3lyXUW5/6qruS5tOEkpsTnXC45Uw9nvZDEVXANMn3viZ1qInxKak8Nr+p
# k0bOHGE4NzRKkAvGDaTooUOlhG4iy9M+Q4dTcwKIoXTs1Euo8uOjAL+jGwT2pan5
# fb/P1cIqMgMpwSQjwIs7LoYMk20FF44CPtuwA+m85iLbTiiuUfQ4bTnVNMOQMibq
# 3QWIrEDfxwrvwMPsv/u/hcc5d2Tb+5QP9CeVmT9woSXJqU2g4yvKKP9JBf7jUFMC
# fTpNRcHOWsIoz+AgOrUeYe67fLpqUWQii08JhPg5f4ybbEzkzZub0zOKNFLYumG0
# VT3BQlO+8LdW
# =RwDq
# -----END PGP SIGNATURE-----
# gpg: Signature made Fri 05 Jul 2024 11:58:31 PM PDT
# 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-2024-07-06' of https://repo.or.cz/qemu/armbru:
  sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments
  qapi/parser: don't parse rST markup as section headers
  qapi: add markup to note blocks
  qapi: update prose in note blocks
  qapi: convert "Note" sections to plain rST
  qapi: nail down convention that Errors sections are lists
  qapi: fix non-compliant JSON examples
  docs/qapidoc: fix nested parsing under untagged sections
  qapi/parser: fix comment parsing immediately following a doc block
  qapi/parser: preserve indentation in QAPIDoc sections
  docs/qapidoc: delint a tiny portion of the module
  docs/qapidoc: remove unused intersperse function
  qapi: linter fixups

Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
This commit is contained in:
Richard Henderson 2024-07-07 13:23:28 -07:00
commit 44b7329de4
34 changed files with 397 additions and 347 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -995,14 +995,13 @@ line "Features:", like this::
# @feature: Description text # @feature: Description text
A tagged section begins with a paragraph that starts with one of the A tagged section begins with a paragraph that starts with one of the
following words: "Note:"/"Notes:", "Since:", "Example:"/"Examples:", following words: "Since:", "Example:"/"Examples:", "Returns:",
"Returns:", "Errors:", "TODO:". It ends with the start of a new "Errors:", "TODO:". It ends with the start of a new section.
section.
The second and subsequent lines of tagged sections must be indented The second and subsequent lines of tagged sections must be indented
like this:: like this::
# Note: Ut enim ad minim veniam, quis nostrud exercitation ullamco # TODO: Ut enim ad minim veniam, quis nostrud exercitation ullamco
# laboris nisi ut aliquip ex ea commodo consequat. # laboris nisi ut aliquip ex ea commodo consequat.
# #
# Duis aute irure dolor in reprehenderit in voluptate velit esse # Duis aute irure dolor in reprehenderit in voluptate velit esse
@ -1011,6 +1010,13 @@ like this::
"Returns" and "Errors" sections are only valid for commands. They "Returns" and "Errors" sections are only valid for commands. They
document the success and the error response, respectively. 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::
# Errors:
# - If @device does not exist, DeviceNotFound
# - Any other error returns a GenericError.
A "Since: x.y.z" tagged section lists the release that introduced the A "Since: x.y.z" tagged section lists the release that introduced the
definition. definition.

113
docs/sphinx/qapidoc.py
View File

@ -26,38 +26,49 @@ https://www.sphinx-doc.org/en/master/development/index.html
import os import os
import re import re
import textwrap
from docutils import nodes from docutils import nodes
from docutils.parsers.rst import Directive, directives
from docutils.statemachine import ViewList from docutils.statemachine import ViewList
from docutils.parsers.rst import directives, Directive from qapi.error import QAPIError, QAPISemError
from qapi.gen import QAPISchemaVisitor
from qapi.schema import QAPISchema
import sphinx
from sphinx.errors import ExtensionError from sphinx.errors import ExtensionError
from sphinx.util.nodes import nested_parse_with_titles from sphinx.util.nodes import nested_parse_with_titles
import sphinx
from qapi.gen import QAPISchemaVisitor
from qapi.error import QAPIError, QAPISemError
from qapi.schema import QAPISchema
# Sphinx up to 1.6 uses AutodocReporter; 1.7 and later # Sphinx up to 1.6 uses AutodocReporter; 1.7 and later
# use switch_source_input. Check borrowed from kerneldoc.py. # use switch_source_input. Check borrowed from kerneldoc.py.
Use_SSI = sphinx.__version__[:3] >= '1.7' USE_SSI = sphinx.__version__[:3] >= "1.7"
if Use_SSI: if USE_SSI:
from sphinx.util.docutils import switch_source_input from sphinx.util.docutils import switch_source_input
else: else:
from sphinx.ext.autodoc import AutodocReporter from sphinx.ext.autodoc import ( # pylint: disable=no-name-in-module
AutodocReporter,
)
__version__ = '1.0' __version__ = "1.0"
# Function borrowed from pydash, which is under the MIT license def dedent(text: str) -> str:
def intersperse(iterable, separator): # Adjust indentation to make description text parse as paragraph.
"""Yield the members of *iterable* interspersed with *separator*."""
iterable = iter(iterable) lines = text.splitlines(True)
yield next(iterable) if re.match(r"\s+", lines[0]):
for item in iterable: # First line is indented; description started on the line after
yield separator # the name. dedent the whole block.
yield item return textwrap.dedent(text)
# Descr started on same line. Dedent line 2+.
return lines[0] + textwrap.dedent("".join(lines[1:]))
# Disable black auto-formatter until re-enabled:
# fmt: off
class QAPISchemaGenRSTVisitor(QAPISchemaVisitor): class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
@ -167,7 +178,7 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
term = self._nodes_for_one_member(section.member) term = self._nodes_for_one_member(section.member)
# TODO drop fallbacks when undocumented members are outlawed # TODO drop fallbacks when undocumented members are outlawed
if section.text: if section.text:
defn = section.text defn = dedent(section.text)
else: else:
defn = [nodes.Text('Not documented')] defn = [nodes.Text('Not documented')]
@ -205,7 +216,7 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
termtext.extend(self._nodes_for_ifcond(section.member.ifcond)) termtext.extend(self._nodes_for_ifcond(section.member.ifcond))
# TODO drop fallbacks when undocumented members are outlawed # TODO drop fallbacks when undocumented members are outlawed
if section.text: if section.text:
defn = section.text defn = dedent(section.text)
else: else:
defn = [nodes.Text('Not documented')] defn = [nodes.Text('Not documented')]
@ -219,15 +230,15 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
section += dlnode section += dlnode
return [section] return [section]
def _nodes_for_arguments(self, doc, boxed_arg_type): def _nodes_for_arguments(self, doc, arg_type):
"""Return list of doctree nodes for the arguments section""" """Return list of doctree nodes for the arguments section"""
if boxed_arg_type: if arg_type and not arg_type.is_implicit():
assert not doc.args assert not doc.args
section = self._make_section('Arguments') section = self._make_section('Arguments')
dlnode = nodes.definition_list() dlnode = nodes.definition_list()
dlnode += self._make_dlitem( dlnode += self._make_dlitem(
[nodes.Text('The members of '), [nodes.Text('The members of '),
nodes.literal('', boxed_arg_type.name)], nodes.literal('', arg_type.name)],
None) None)
section += dlnode section += dlnode
return [section] return [section]
@ -240,7 +251,7 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
dlnode = nodes.definition_list() dlnode = nodes.definition_list()
for section in doc.features.values(): for section in doc.features.values():
dlnode += self._make_dlitem( dlnode += self._make_dlitem(
[nodes.literal('', section.member.name)], section.text) [nodes.literal('', section.member.name)], dedent(section.text))
seen_item = True seen_item = True
if not seen_item: if not seen_item:
@ -261,11 +272,20 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
if section.tag and section.tag == 'TODO': if section.tag and section.tag == 'TODO':
# Hide TODO: sections # Hide TODO: sections
continue continue
if not section.tag:
# Sphinx cannot handle sectionless titles;
# Instead, just append the results to the prior section.
container = nodes.container()
self._parse_text_into_node(section.text, container)
nodelist += container.children
continue
snode = self._make_section(section.tag) snode = self._make_section(section.tag)
if section.tag and section.tag.startswith('Example'): if section.tag.startswith('Example'):
snode += self._nodes_for_example(section.text) snode += self._nodes_for_example(dedent(section.text))
else: else:
self._parse_text_into_node(section.text, snode) self._parse_text_into_node(dedent(section.text), snode)
nodelist.append(snode) nodelist.append(snode)
return nodelist return nodelist
@ -332,8 +352,7 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
allow_preconfig, coroutine): allow_preconfig, coroutine):
doc = self._cur_doc doc = self._cur_doc
self._add_doc('Command', self._add_doc('Command',
self._nodes_for_arguments(doc, self._nodes_for_arguments(doc, arg_type)
arg_type if boxed else None)
+ self._nodes_for_features(doc) + self._nodes_for_features(doc)
+ self._nodes_for_sections(doc) + self._nodes_for_sections(doc)
+ self._nodes_for_if_section(ifcond)) + self._nodes_for_if_section(ifcond))
@ -341,8 +360,7 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
def visit_event(self, name, info, ifcond, features, arg_type, boxed): def visit_event(self, name, info, ifcond, features, arg_type, boxed):
doc = self._cur_doc doc = self._cur_doc
self._add_doc('Event', self._add_doc('Event',
self._nodes_for_arguments(doc, self._nodes_for_arguments(doc, arg_type)
arg_type if boxed else None)
+ self._nodes_for_features(doc) + self._nodes_for_features(doc)
+ self._nodes_for_sections(doc) + self._nodes_for_sections(doc)
+ self._nodes_for_if_section(ifcond)) + self._nodes_for_if_section(ifcond))
@ -451,6 +469,10 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
return self._top_node.children return self._top_node.children
# Turn the black formatter on for the rest of the file.
# fmt: on
class QAPISchemaGenDepVisitor(QAPISchemaVisitor): class QAPISchemaGenDepVisitor(QAPISchemaVisitor):
"""A QAPI schema visitor which adds Sphinx dependencies each module """A QAPI schema visitor which adds Sphinx dependencies each module
@ -458,34 +480,34 @@ class QAPISchemaGenDepVisitor(QAPISchemaVisitor):
that the generated documentation output depends on the input that the generated documentation output depends on the input
schema file associated with each module in the QAPI input. schema file associated with each module in the QAPI input.
""" """
def __init__(self, env, qapidir): def __init__(self, env, qapidir):
self._env = env self._env = env
self._qapidir = qapidir self._qapidir = qapidir
def visit_module(self, name): def visit_module(self, name):
if name != "./builtin": if name != "./builtin":
qapifile = self._qapidir + '/' + name qapifile = self._qapidir + "/" + name
self._env.note_dependency(os.path.abspath(qapifile)) self._env.note_dependency(os.path.abspath(qapifile))
super().visit_module(name) super().visit_module(name)
class QAPIDocDirective(Directive): class QAPIDocDirective(Directive):
"""Extract documentation from the specified QAPI .json file""" """Extract documentation from the specified QAPI .json file"""
required_argument = 1 required_argument = 1
optional_arguments = 1 optional_arguments = 1
option_spec = { option_spec = {"qapifile": directives.unchanged_required}
'qapifile': directives.unchanged_required
}
has_content = False has_content = False
def new_serialno(self): def new_serialno(self):
"""Return a unique new ID string suitable for use as a node's ID""" """Return a unique new ID string suitable for use as a node's ID"""
env = self.state.document.settings.env env = self.state.document.settings.env
return 'qapidoc-%d' % env.new_serialno('qapidoc') return "qapidoc-%d" % env.new_serialno("qapidoc")
def run(self): def run(self):
env = self.state.document.settings.env env = self.state.document.settings.env
qapifile = env.config.qapidoc_srctree + '/' + self.arguments[0] qapifile = env.config.qapidoc_srctree + "/" + self.arguments[0]
qapidir = os.path.dirname(qapifile) qapidir = os.path.dirname(qapifile)
try: try:
@ -523,13 +545,14 @@ class QAPIDocDirective(Directive):
# plain self.state.nested_parse(), and so we can drop the saving # plain self.state.nested_parse(), and so we can drop the saving
# of title_styles and section_level that kerneldoc.py does, # of title_styles and section_level that kerneldoc.py does,
# because nested_parse_with_titles() does that for us. # because nested_parse_with_titles() does that for us.
if Use_SSI: if USE_SSI:
with switch_source_input(self.state, rstlist): with switch_source_input(self.state, rstlist):
nested_parse_with_titles(self.state, rstlist, node) nested_parse_with_titles(self.state, rstlist, node)
else: else:
save = self.state.memo.reporter save = self.state.memo.reporter
self.state.memo.reporter = AutodocReporter( self.state.memo.reporter = AutodocReporter(
rstlist, self.state.memo.reporter) rstlist, self.state.memo.reporter
)
try: try:
nested_parse_with_titles(self.state, rstlist, node) nested_parse_with_titles(self.state, rstlist, node)
finally: finally:
@ -538,11 +561,11 @@ class QAPIDocDirective(Directive):
def setup(app): def setup(app):
"""Register qapi-doc directive with Sphinx""" """Register qapi-doc directive with Sphinx"""
app.add_config_value('qapidoc_srctree', None, 'env') app.add_config_value("qapidoc_srctree", None, "env")
app.add_directive('qapi-doc', QAPIDocDirective) app.add_directive("qapi-doc", QAPIDocDirective)
return dict( return {
version=__version__, "version": __version__,
parallel_read_safe=True, "parallel_read_safe": True,
parallel_write_safe=True "parallel_write_safe": True,
) }

31
qapi/block-core.json
View File

@ -1619,9 +1619,9 @@
# #
# @unstable: Member @x-perf is experimental. # @unstable: Member @x-perf is experimental.
# #
# Note: @on-source-error and @on-target-error only affect background # .. note:: @on-source-error and @on-target-error only affect background
# I/O. If an error occurs during a guest write request, the # I/O. If an error occurs during a guest write request, the device's
# device's rerror/werror actions will be used. # rerror/werror actions will be used.
# #
# Since: 4.2 # Since: 4.2
## ##
@ -1675,8 +1675,6 @@
# #
# Takes a synchronous snapshot of a block device. # Takes a synchronous snapshot of a block device.
# #
# For the arguments, see the documentation of BlockdevSnapshotSync.
#
# Errors: # Errors:
# - If @device is not a valid block device, DeviceNotFound # - If @device is not a valid block device, DeviceNotFound
# #
@ -1705,8 +1703,6 @@
# device, the block device changes to using 'overlay' as its new # device, the block device changes to using 'overlay' as its new
# active image. # active image.
# #
# For the arguments, see the documentation of BlockdevSnapshot.
#
# Features: # Features:
# #
# @allow-write-only-overlay: If present, the check whether this # @allow-write-only-overlay: If present, the check whether this
@ -5545,7 +5541,7 @@
# after this event and must be repaired (Since 2.2; before, every # after this event and must be repaired (Since 2.2; before, every
# BLOCK_IMAGE_CORRUPTED event was fatal) # BLOCK_IMAGE_CORRUPTED event was fatal)
# #
# Note: If action is "stop", a STOP event will eventually follow the # .. note:: If action is "stop", a STOP event will eventually follow the
# BLOCK_IO_ERROR event. # BLOCK_IO_ERROR event.
# #
# Example: # Example:
@ -5592,8 +5588,8 @@
# field is a debugging aid for humans, it should not be parsed by # field is a debugging aid for humans, it should not be parsed by
# applications) (since: 2.2) # applications) (since: 2.2)
# #
# Note: If action is "stop", a STOP event will eventually follow the # .. note:: If action is "stop", a STOP event will eventually follow the
# BLOCK_IO_ERROR event # BLOCK_IO_ERROR event.
# #
# Since: 0.13 # Since: 0.13
# #
@ -5731,8 +5727,8 @@
# #
# @speed: rate limit, bytes per second # @speed: rate limit, bytes per second
# #
# Note: The "ready to complete" status is always reset by a # .. note:: The "ready to complete" status is always reset by a
# @BLOCK_JOB_ERROR event # @BLOCK_JOB_ERROR event.
# #
# Since: 1.3 # Since: 1.3
# #
@ -5985,7 +5981,7 @@
# #
# @sectors-count: failed read operation sector count # @sectors-count: failed read operation sector count
# #
# Note: This event is rate-limited. # .. note:: This event is rate-limited.
# #
# Since: 2.0 # Since: 2.0
# #
@ -6016,7 +6012,7 @@
# #
# @sectors-count: failed read operation sector count # @sectors-count: failed read operation sector count
# #
# Note: This event is rate-limited. # .. note:: This event is rate-limited.
# #
# Since: 2.0 # Since: 2.0
# #
@ -6048,9 +6044,9 @@
# #
# @name: the name of the internal snapshot to be created # @name: the name of the internal snapshot to be created
# #
# Notes: In transaction, if @name is empty, or any snapshot matching # .. note:: In a transaction, if @name is empty or any snapshot matching
# @name exists, the operation will fail. Only some image formats # @name exists, the operation will fail. Only some image formats
# support it, for example, qcow2, and rbd. # support it; for example, qcow2, and rbd.
# #
# Since: 1.7 # Since: 1.7
## ##
@ -6065,9 +6061,6 @@
# string, or a snapshot with name already exists, the operation will # string, or a snapshot with name already exists, the operation will
# fail. # fail.
# #
# For the arguments, see the documentation of
# BlockdevSnapshotInternal.
#
# Errors: # Errors:
# - If @device is not a valid block device, GenericError # - If @device is not a valid block device, GenericError
# - If any snapshot matching @name exists, or @name is empty, # - If any snapshot matching @name exists, or @name is empty,

2
qapi/block.json
View File

@ -113,7 +113,7 @@
# Errors: # Errors:
# - If @device is not a valid block device, DeviceNotFound # - If @device is not a valid block device, DeviceNotFound
# #
# Notes: Ejecting a device with no media results in success # .. note:: Ejecting a device with no media results in success.
# #
# Since: 0.14 # Since: 0.14
# #

10
qapi/char.json
View File

@ -21,7 +21,7 @@
# backend (e.g. with the chardev=... option) is in open or closed # backend (e.g. with the chardev=... option) is in open or closed
# state (since 2.1) # state (since 2.1)
# #
# Notes: @filename is encoded using the QEMU command line character # .. note:: @filename is encoded using the QEMU command line character
# device encoding. See the QEMU man page for details. # device encoding. See the QEMU man page for details.
# #
# Since: 0.14 # Since: 0.14
@ -388,9 +388,9 @@
# #
# @rows: console height, in chars # @rows: console height, in chars
# #
# Note: the options are only effective when the VNC or SDL graphical # .. note:: The options are only effective when the VNC or SDL graphical
# display backend is active. They are ignored with the GTK, # display backend is active. They are ignored with the GTK, Spice,
# Spice, VNC and D-Bus display backends. # VNC and D-Bus display backends.
# #
# Since: 1.5 # Since: 1.5
## ##
@ -806,7 +806,7 @@
# #
# @open: true if the guest has opened the virtio-serial port # @open: true if the guest has opened the virtio-serial port
# #
# Note: This event is rate-limited. # .. note:: This event is rate-limited.
# #
# Since: 2.1 # Since: 2.1
# #

20
qapi/control.json
View File

@ -22,14 +22,13 @@
# "arguments": { "enable": [ "oob" ] } } # "arguments": { "enable": [ "oob" ] } }
# <- { "return": {} } # <- { "return": {} }
# #
# Notes: This command is valid exactly when first connecting: it must # .. note:: This command is valid exactly when first connecting: it must
# be issued before any other command will be accepted, and will # be issued before any other command will be accepted, and will fail
# fail once the monitor is accepting other commands. (see qemu # once the monitor is accepting other commands.
# docs/interop/qmp-spec.rst) # (see :doc:`/interop/qmp-spec`)
# #
# The QMP client needs to explicitly enable QMP capabilities, # .. note:: The QMP client needs to explicitly enable QMP capabilities,
# otherwise all the QMP capabilities will be turned off by # otherwise all the QMP capabilities will be turned off by default.
# default.
# #
# Since: 0.13 # Since: 0.13
## ##
@ -145,12 +144,13 @@
# }, # },
# { # {
# "name":"system_powerdown" # "name":"system_powerdown"
# } # },
# ...
# ] # ]
# } # }
# #
# Note: This example has been shortened as the real response is too # This example has been shortened as the real response is too long.
# long. #
## ##
{ 'command': 'query-commands', 'returns': ['CommandInfo'], { 'command': 'query-commands', 'returns': ['CommandInfo'],
'allow-preconfig': true } 'allow-preconfig': true }

2
qapi/dump.json
View File

@ -90,7 +90,7 @@
# and @length is not allowed to be specified with non-elf @format # and @length is not allowed to be specified with non-elf @format
# at the same time (since 2.0) # at the same time (since 2.0)
# #
# Note: All boolean arguments default to false # .. note:: All boolean arguments default to false.
# #
# Since: 1.2 # Since: 1.2
# #

6
qapi/introspect.json
View File

@ -41,9 +41,9 @@
# names are guaranteed to be unique (no name will be duplicated # names are guaranteed to be unique (no name will be duplicated
# with different meta-types). # with different meta-types).
# #
# Note: the QAPI schema is also used to help define *internal* # .. note:: The QAPI schema is also used to help define *internal*
# interfaces, by defining QAPI types. These are not part of the # interfaces, by defining QAPI types. These are not part of the QMP
# QMP wire ABI, and therefore not returned by this command. # wire ABI, and therefore not returned by this command.
# #
# Since: 2.5 # Since: 2.5
## ##

24
qapi/machine-target.json
View File

@ -49,15 +49,15 @@
# to be migration-safe, but allows tooling to get an insight and # to be migration-safe, but allows tooling to get an insight and
# work with model details. # work with model details.
# #
# Note: When a non-migration-safe CPU model is expanded in static # .. note:: When a non-migration-safe CPU model is expanded in static
# mode, some features enabled by the CPU model may be omitted, # mode, some features enabled by the CPU model may be omitted,
# because they can't be implemented by a static CPU model # because they can't be implemented by a static CPU model definition
# definition (e.g. cache info passthrough and PMU passthrough in # (e.g. cache info passthrough and PMU passthrough in x86). If you
# x86). If you need an accurate representation of the features # need an accurate representation of the features enabled by a
# enabled by a non-migration-safe CPU model, use @full. If you # non-migration-safe CPU model, use @full. If you need a static
# need a static representation that will keep ABI compatibility # representation that will keep ABI compatibility even when changing
# even when changing QEMU version or machine-type, use @static # QEMU version or machine-type, use @static (but keep in mind that
# (but keep in mind that some features may be omitted). # some features may be omitted).
# #
# Since: 2.8 # Since: 2.8
## ##
@ -175,8 +175,8 @@
# - if a model contains an unknown cpu definition name, unknown # - if a model contains an unknown cpu definition name, unknown
# properties or properties with wrong types. # properties or properties with wrong types.
# #
# Note: this command isn't specific to s390x, but is only implemented # .. note:: This command isn't specific to s390x, but is only
# on this architecture currently. # implemented on this architecture currently.
# #
# Since: 2.8 # Since: 2.8
## ##
@ -229,8 +229,8 @@
# - if a model contains an unknown cpu definition name, unknown # - if a model contains an unknown cpu definition name, unknown
# properties or properties with wrong types. # properties or properties with wrong types.
# #
# Note: this command isn't specific to s390x, but is only implemented # .. note:: This command isn't specific to s390x, but is only
# on this architecture currently. # implemented on this architecture currently.
# #
# Since: 2.8 # Since: 2.8
## ##

43
qapi/machine.json
View File

@ -24,9 +24,9 @@
# #
# @avr: since 5.1 # @avr: since 5.1
# #
# Notes: The resulting QMP strings can be appended to the # .. note:: The resulting QMP strings can be appended to the
# "qemu-system-" prefix to produce the corresponding QEMU # "qemu-system-" prefix to produce the corresponding QEMU executable
# executable name. This is true even for "qemu-system-x86_64". # name. This is true even for "qemu-system-x86_64".
# #
# Since: 3.0 # Since: 3.0
## ##
@ -305,8 +305,9 @@
# #
# Since: 0.14 # Since: 0.14
# #
# Notes: If no UUID was specified for the guest, a null UUID is # .. note:: If no UUID was specified for the guest, a null UUID is
# returned. # returned.
#
## ##
{ 'struct': 'UuidInfo', 'data': {'UUID': 'str'} } { 'struct': 'UuidInfo', 'data': {'UUID': 'str'} }
@ -367,10 +368,10 @@
# #
# Since: 0.14 # Since: 0.14
# #
# Notes: A guest may or may not respond to this command. This command # .. note:: A guest may or may not respond to this command. This
# returning does not indicate that a guest has accepted the # command returning does not indicate that a guest has accepted the
# request or that it has shut down. Many guests will respond to # request or that it has shut down. Many guests will respond to this
# this command by prompting the user in some way. # command by prompting the user in some way.
# #
# Example: # Example:
# #
@ -389,7 +390,7 @@
# #
# Since: 1.1 # Since: 1.1
# #
# Note: prior to 4.0, this command does nothing in case the guest # .. note:: Prior to 4.0, this command does nothing in case the guest
# isn't suspended. # isn't suspended.
# #
# Example: # Example:
@ -440,8 +441,8 @@
# #
# Since: 0.14 # Since: 0.14
# #
# Note: prior to 2.1, this command was only supported for x86 and s390 # .. note:: Prior to 2.1, this command was only supported for x86 and
# VMs # s390 VMs.
# #
# Example: # Example:
# #
@ -839,7 +840,7 @@
# #
# Since: 0.14 # Since: 0.14
# #
# Notes: Errors were not reliably returned until 1.1 # .. caution:: Errors were not reliably returned until 1.1.
# #
# Example: # Example:
# #
@ -865,7 +866,7 @@
# #
# Since: 0.14 # Since: 0.14
# #
# Notes: Errors were not reliably returned until 1.1 # .. caution:: Errors were not reliably returned until 1.1.
# #
# Example: # Example:
# #
@ -995,7 +996,7 @@
# #
# @thread-id: thread number within the core the CPU belongs to # @thread-id: thread number within the core the CPU belongs to
# #
# Note: management should be prepared to pass through additional # .. note:: Management should be prepared to pass through additional
# properties with device_add. # properties with device_add.
# #
# Since: 2.7 # Since: 2.7
@ -1057,7 +1058,7 @@
# "vcpus-count": 1 }, # "vcpus-count": 1 },
# { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core", # { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core",
# "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"} # "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
# ]}' # ]}
# #
# For pc machine type started with -smp 1,maxcpus=2: # For pc machine type started with -smp 1,maxcpus=2:
# #
@ -1123,9 +1124,9 @@
# the KVM kernel module cannot support it, KVMMissingCap # the KVM kernel module cannot support it, KVMMissingCap
# - If no balloon device is present, DeviceNotActive # - If no balloon device is present, DeviceNotActive
# #
# Notes: This command just issues a request to the guest. When it # .. note:: This command just issues a request to the guest. When it
# returns, the balloon size may not have changed. A guest can # returns, the balloon size may not have changed. A guest can change
# change the balloon size independent of this command. # the balloon size independent of this command.
# #
# Since: 0.14 # Since: 0.14
# #
@ -1185,7 +1186,7 @@
# @actual: the logical size of the VM in bytes Formula used: # @actual: the logical size of the VM in bytes Formula used:
# logical_vm_size = vm_ram_size - balloon_size # logical_vm_size = vm_ram_size - balloon_size
# #
# Note: this event is rate-limited. # .. note:: This event is rate-limited.
# #
# Since: 1.2 # Since: 1.2
# #
@ -1248,7 +1249,7 @@
# Emitted when the hv-balloon driver receives a "STATUS" message from # Emitted when the hv-balloon driver receives a "STATUS" message from
# the guest. # the guest.
# #
# Note: this event is rate-limited. # .. note:: This event is rate-limited.
# #
# Since: 8.2 # Since: 8.2
# #
@ -1593,7 +1594,7 @@
# #
# @qom-path: path to the device object in the QOM tree (since 6.2) # @qom-path: path to the device object in the QOM tree (since 6.2)
# #
# Note: this event is rate-limited. # .. note:: This event is rate-limited.
# #
# Since: 5.1 # Since: 5.1
# #

14
qapi/migration.json
View File

@ -1456,7 +1456,7 @@
# #
# Cancel the current executing migration process. # Cancel the current executing migration process.
# #
# Notes: This command succeeds even if there is no migration process # .. note:: This command succeeds even if there is no migration process
# running. # running.
# #
# Since: 0.14 # Since: 0.14
@ -1589,16 +1589,16 @@
# #
# Since: 0.14 # Since: 0.14
# #
# Notes: # .. admonition:: Notes
# #
# 1. The 'query-migrate' command should be used to check # 1. The 'query-migrate' command should be used to check
# migration's progress and final result (this information is # migration's progress and final result (this information is
# provided by the 'status' member) # provided by the 'status' member).
# #
# 2. All boolean arguments default to false # 2. All boolean arguments default to false.
# #
# 3. The user Monitor's "detach" argument is invalid in QMP and # 3. The user Monitor's "detach" argument is invalid in QMP and
# should not be used # should not be used.
# #
# 4. The uri argument should have the Uniform Resource Identifier # 4. The uri argument should have the Uniform Resource Identifier
# of default destination VM. This connection will be bound to # of default destination VM. This connection will be bound to
@ -1672,7 +1672,7 @@
# #
# Since: 2.3 # Since: 2.3
# #
# Notes: # .. admonition:: Notes
# #
# 1. It's a bad idea to use a string for the uri, but it needs to # 1. It's a bad idea to use a string for the uri, but it needs to
# stay compatible with -incoming and the format of the uri is # stay compatible with -incoming and the format of the uri is
@ -2106,7 +2106,7 @@
# Example: # Example:
# #
# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, # -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1,
# 'sample-pages': 512} } # "sample-pages": 512} }
# <- { "return": {} } # <- { "return": {} }
# #
# Measure dirty rate using dirty bitmap for 500 milliseconds: # Measure dirty rate using dirty bitmap for 500 milliseconds:

71
qapi/misc.json
View File

@ -103,8 +103,8 @@
# #
# Returns a list of information about each iothread. # Returns a list of information about each iothread.
# #
# Note: this list excludes the QEMU main loop thread, which is not # .. note:: This list excludes the QEMU main loop thread, which is not
# declared using the -object iothread command-line option. It is # declared using the ``-object iothread`` command-line option. It is
# always the main thread of the process. # always the main thread of the process.
# #
# Returns: a list of @IOThreadInfo for each iothread # Returns: a list of @IOThreadInfo for each iothread
@ -136,13 +136,13 @@
# #
# Since: 0.14 # Since: 0.14
# #
# Notes: This function will succeed even if the guest is already in # .. note:: This function will succeed even if the guest is already in
# the stopped state. In "inmigrate" state, it will ensure that # the stopped state. In "inmigrate" state, it will ensure that the
# the guest remains paused once migration finishes, as if the -S # guest remains paused once migration finishes, as if the ``-S``
# option was passed on the command line. # option was passed on the command line.
# #
# In the "suspended" state, it will completely stop the VM and # In the "suspended" state, it will completely stop the VM and cause
# cause a transition to the "paused" state. (Since 9.0) # a transition to the "paused" state. (Since 9.0)
# #
# Example: # Example:
# #
@ -158,15 +158,15 @@
# #
# Since: 0.14 # Since: 0.14
# #
# Notes: This command will succeed if the guest is currently running. # .. note:: This command will succeed if the guest is currently running.
# It will also succeed if the guest is in the "inmigrate" state; # It will also succeed if the guest is in the "inmigrate" state; in
# in this case, the effect of the command is to make sure the # this case, the effect of the command is to make sure the guest
# guest starts once migration finishes, removing the effect of the # starts once migration finishes, removing the effect of the ``-S``
# -S command line option if it was passed. # command line option if it was passed.
# #
# If the VM was previously suspended, and not been reset or woken, # If the VM was previously suspended, and not been reset or woken,
# this command will transition back to the "suspended" state. # this command will transition back to the "suspended" state. (Since
# (Since 9.0) # 9.0)
# #
# Example: # Example:
# #
@ -219,18 +219,18 @@
# #
# Since: 0.14 # Since: 0.14
# #
# Notes: This command only exists as a stop-gap. Its use is highly # .. note:: This command only exists as a stop-gap. Its use is highly
# discouraged. The semantics of this command are not guaranteed: # discouraged. The semantics of this command are not guaranteed:
# this means that command names, arguments and responses can # this means that command names, arguments and responses can change
# change or be removed at ANY time. Applications that rely on # or be removed at ANY time. Applications that rely on long term
# long term stability guarantees should NOT use this command. # stability guarantees should NOT use this command.
# #
# Known limitations: # Known limitations:
# #
# * This command is stateless, this means that commands that # * This command is stateless, this means that commands that
# depend on state information (such as getfd) might not work # depend on state information (such as getfd) might not work.
# #
# * Commands that prompt the user for data don't currently work # * Commands that prompt the user for data don't currently work.
# #
# Example: # Example:
# #
@ -252,8 +252,8 @@
# #
# Since: 0.14 # Since: 0.14
# #
# Notes: If @fdname already exists, the file descriptor assigned to it # .. note:: If @fdname already exists, the file descriptor assigned to
# will be closed and replaced by the received file descriptor. # it will be closed and replaced by the received file descriptor.
# #
# The 'closefd' command can be used to explicitly close the file # The 'closefd' command can be used to explicitly close the file
# descriptor when it is no longer needed. # descriptor when it is no longer needed.
@ -279,15 +279,16 @@
# #
# Since: 8.0 # Since: 8.0
# #
# Notes: If @fdname already exists, the file descriptor assigned to it # .. note:: If @fdname already exists, the file descriptor assigned to
# will be closed and replaced by the received file descriptor. # it will be closed and replaced by the received file descriptor.
# #
# The 'closefd' command can be used to explicitly close the file # The 'closefd' command can be used to explicitly close the file
# descriptor when it is no longer needed. # descriptor when it is no longer needed.
# #
# Example: # Example:
# #
# -> { "execute": "get-win32-socket", "arguments": { "info": "abcd123..", fdname": "skclient" } } # -> { "execute": "get-win32-socket",
# "arguments": { "info": "abcd123..", "fdname": "skclient" } }
# <- { "return": {} } # <- { "return": {} }
## ##
{ 'command': 'get-win32-socket', 'data': {'info': 'str', 'fdname': 'str'}, 'if': 'CONFIG_WIN32' } { 'command': 'get-win32-socket', 'data': {'info': 'str', 'fdname': 'str'}, 'if': 'CONFIG_WIN32' }
@ -338,10 +339,9 @@
# - If file descriptor was not received, GenericError # - If file descriptor was not received, GenericError
# - If @fdset-id is a negative value, GenericError # - If @fdset-id is a negative value, GenericError
# #
# Notes: # .. note:: The list of fd sets is shared by all monitor connections.
# The list of fd sets is shared by all monitor connections.
# #
# If @fdset-id is not specified, a new fd set will be created. # .. note:: If @fdset-id is not specified, a new fd set will be created.
# #
# Since: 1.2 # Since: 1.2
# #
@ -369,11 +369,10 @@
# #
# Since: 1.2 # Since: 1.2
# #
# Notes: # .. note:: The list of fd sets is shared by all monitor connections.
# The list of fd sets is shared by all monitor connections.
# #
# If @fd is not specified, all file descriptors in @fdset-id will # .. note:: If @fd is not specified, all file descriptors in @fdset-id
# be removed. # will be removed.
# #
# Example: # Example:
# #
@ -419,7 +418,7 @@
# #
# Since: 1.2 # Since: 1.2
# #
# Note: The list of fd sets is shared by all monitor connections. # .. note:: The list of fd sets is shared by all monitor connections.
# #
# Example: # Example:
# #
@ -560,9 +559,9 @@
# #
# @qom-path: path to the RTC object in the QOM tree # @qom-path: path to the RTC object in the QOM tree
# #
# Note: This event is rate-limited. It is not guaranteed that the RTC # .. note:: This event is rate-limited. It is not guaranteed that the
# in the system implements this event, or even that the system has # RTC in the system implements this event, or even that the system
# an RTC at all. # has an RTC at all.
# #
# Since: 0.13 # Since: 0.13
# #

12
qapi/net.json
View File

@ -22,9 +22,9 @@
# #
# Since: 0.14 # Since: 0.14
# #
# Notes: Not all network adapters support setting link status. This # .. note:: Not all network adapters support setting link status. This
# command will succeed even if the network adapter does not # command will succeed even if the network adapter does not support
# support link status notification. # link status notification.
# #
# Example: # Example:
# #
@ -1003,9 +1003,9 @@
# #
# Example: # Example:
# #
# <- { 'event': 'NETDEV_STREAM_DISCONNECTED', # <- { "event": "NETDEV_STREAM_DISCONNECTED",
# 'data': {'netdev-id': 'netdev0'}, # "data": {"netdev-id": "netdev0"},
# 'timestamp': {'seconds': 1663330937, 'microseconds': 526695} } # "timestamp": {"seconds": 1663330937, "microseconds": 526695} }
## ##
{ 'event': 'NETDEV_STREAM_DISCONNECTED', { 'event': 'NETDEV_STREAM_DISCONNECTED',
'data': { 'netdev-id': 'str' } } 'data': { 'netdev-id': 'str' } }

6
qapi/pci.json
View File

@ -146,7 +146,7 @@
# #
# @regions: a list of the PCI I/O regions associated with the device # @regions: a list of the PCI I/O regions associated with the device
# #
# Notes: the contents of @class_info.desc are not stable and should # .. note:: The contents of @class_info.desc are not stable and should
# only be treated as informational. # only be treated as informational.
# #
# Since: 0.14 # Since: 0.14
@ -311,7 +311,7 @@
# ] # ]
# } # }
# #
# Note: This example has been shortened as the real response is too # This example has been shortened as the real response is too long.
# long. #
## ##
{ 'command': 'query-pci', 'returns': ['PciInfo'] } { 'command': 'query-pci', 'returns': ['PciInfo'] }

24
qapi/qdev.json
View File

@ -20,7 +20,7 @@
# Returns: a list of ObjectPropertyInfo describing a devices # Returns: a list of ObjectPropertyInfo describing a devices
# properties # properties
# #
# Note: objects can create properties at runtime, for example to # .. note:: Objects can create properties at runtime, for example to
# describe links between different devices and/or objects. These # describe links between different devices and/or objects. These
# properties are not included in the output of this command. # properties are not included in the output of this command.
# #
@ -51,7 +51,7 @@
# supports JSON syntax without the reference counting leak that # supports JSON syntax without the reference counting leak that
# broke hot-unplug # broke hot-unplug
# #
# Notes: # .. admonition:: Notes
# #
# 1. Additional arguments depend on the type. # 1. Additional arguments depend on the type.
# #
@ -59,8 +59,8 @@
# the 'docs/qdev-device-use.txt' file. # the 'docs/qdev-device-use.txt' file.
# #
# 3. It's possible to list device properties by running QEMU with # 3. It's possible to list device properties by running QEMU with
# the "-device DEVICE,help" command-line argument, where DEVICE # the ``-device DEVICE,help`` command-line argument, where DEVICE
# is the device's name # is the device's name.
# #
# Example: # Example:
# #
@ -92,15 +92,15 @@
# Errors: # Errors:
# - If @id is not a valid device, DeviceNotFound # - If @id is not a valid device, DeviceNotFound
# #
# Notes: When this command completes, the device may not be removed # .. note:: When this command completes, the device may not be removed
# from the guest. Hot removal is an operation that requires guest # from the guest. Hot removal is an operation that requires guest
# cooperation. This command merely requests that the guest begin # cooperation. This command merely requests that the guest begin the
# the hot removal process. Completion of the device removal # hot removal process. Completion of the device removal process is
# process is signaled with a DEVICE_DELETED event. Guest reset # signaled with a DEVICE_DELETED event. Guest reset will
# will automatically complete removal for all devices. If a # automatically complete removal for all devices. If a guest-side
# guest-side error in the hot removal process is detected, the # error in the hot removal process is detected, the device will not
# device will not be removed and a DEVICE_UNPLUG_GUEST_ERROR event # be removed and a DEVICE_UNPLUG_GUEST_ERROR event is sent. Some
# is sent. Some errors cannot be detected. # errors cannot be detected.
# #
# Since: 0.14 # Since: 0.14
# #

11
qapi/qom.json
View File

@ -195,7 +195,7 @@
# #
# @typename: the type name of an object # @typename: the type name of an object
# #
# Note: objects can create properties at runtime, for example to # .. note:: Objects can create properties at runtime, for example to
# describe links between different devices and/or objects. These # describe links between different devices and/or objects. These
# properties are not included in the output of this command. # properties are not included in the output of this command.
# #
@ -614,12 +614,11 @@
# older to allow migration with newer QEMU versions. # older to allow migration with newer QEMU versions.
# (default: false generally, but true for machine types <= 4.0) # (default: false generally, but true for machine types <= 4.0)
# #
# Note: prealloc=true and reserve=false cannot be set at the same # .. note:: prealloc=true and reserve=false cannot be set at the same
# time. With reserve=true, the behavior depends on the operating # time. With reserve=true, the behavior depends on the operating
# system: for example, Linux will not reserve swap space for # system: for example, Linux will not reserve swap space for shared
# shared file mappings -- "not applicable". In contrast, # file mappings -- "not applicable". In contrast, reserve=false will
# reserve=false will bail out if it cannot be configured # bail out if it cannot be configured accordingly.
# accordingly.
# #
# Since: 2.1 # Since: 2.1
## ##

10
qapi/rocker.json
View File

@ -138,7 +138,7 @@
# #
# @ip-dst: IP header destination address # @ip-dst: IP header destination address
# #
# Note: optional members may or may not appear in the flow key # .. note:: Optional members may or may not appear in the flow key
# depending if they're relevant to the flow key. # depending if they're relevant to the flow key.
# #
# Since: 2.4 # Since: 2.4
@ -168,7 +168,7 @@
# #
# @ip-tos: IP header TOS field # @ip-tos: IP header TOS field
# #
# Note: optional members may or may not appear in the flow mask # .. note:: Optional members may or may not appear in the flow mask
# depending if they're relevant to the flow mask. # depending if they're relevant to the flow mask.
# #
# Since: 2.4 # Since: 2.4
@ -195,7 +195,7 @@
# #
# @out-pport: physical output port # @out-pport: physical output port
# #
# Note: optional members may or may not appear in the flow action # .. note:: Optional members may or may not appear in the flow action
# depending if they're relevant to the flow action. # depending if they're relevant to the flow action.
# #
# Since: 2.4 # Since: 2.4
@ -250,7 +250,7 @@
# "action": {"goto-tbl": 10}, # "action": {"goto-tbl": 10},
# "mask": {"in-pport": 4294901760} # "mask": {"in-pport": 4294901760}
# }, # },
# {...more...}, # {...},
# ]} # ]}
## ##
{ 'command': 'query-rocker-of-dpa-flows', { 'command': 'query-rocker-of-dpa-flows',
@ -288,7 +288,7 @@
# #
# @ttl-check: perform TTL check # @ttl-check: perform TTL check
# #
# Note: optional members may or may not appear in the group depending # .. note:: Optional members may or may not appear in the group depending
# if they're relevant to the group type. # if they're relevant to the group type.
# #
# Since: 2.4 # Since: 2.4

16
qapi/run-state.json
View File

@ -146,9 +146,9 @@
# @reason: The @ShutdownCause which resulted in the SHUTDOWN. # @reason: The @ShutdownCause which resulted in the SHUTDOWN.
# (since 4.0) # (since 4.0)
# #
# Note: If the command-line option "-no-shutdown" has been specified, # .. note:: If the command-line option ``-no-shutdown`` has been
# qemu will not exit, and a STOP event will eventually follow the # specified, qemu will not exit, and a STOP event will eventually
# SHUTDOWN event # follow the SHUTDOWN event.
# #
# Since: 0.12 # Since: 0.12
# #
@ -247,8 +247,8 @@
# saved on disk, for example, S4 state, which is sometimes called # saved on disk, for example, S4 state, which is sometimes called
# hibernate state # hibernate state
# #
# Note: QEMU shuts down (similar to event @SHUTDOWN) when entering # .. note:: QEMU shuts down (similar to event @SHUTDOWN) when entering
# this state # this state.
# #
# Since: 1.2 # Since: 1.2
# #
@ -281,11 +281,11 @@
# #
# @action: action that has been taken # @action: action that has been taken
# #
# Note: If action is "reset", "shutdown", or "pause" the WATCHDOG # .. note:: If action is "reset", "shutdown", or "pause" the WATCHDOG
# event is followed respectively by the RESET, SHUTDOWN, or STOP # event is followed respectively by the RESET, SHUTDOWN, or STOP
# events # events.
# #
# Note: This event is rate-limited. # .. note:: This event is rate-limited.
# #
# Since: 0.13 # Since: 0.13
# #

8
qapi/sockets.json
View File

@ -104,8 +104,8 @@
# #
# @port: port # @port: port
# #
# Note: string types are used to allow for possible future hostname or # .. note:: String types are used to allow for possible future hostname
# service resolution support. # or service resolution support.
# #
# Since: 2.8 # Since: 2.8
## ##
@ -179,9 +179,9 @@
# #
# @type: Transport type # @type: Transport type
# #
# Note: This type is deprecated in favor of SocketAddress. The # .. note:: This type is deprecated in favor of SocketAddress. The
# difference between SocketAddressLegacy and SocketAddress is that # difference between SocketAddressLegacy and SocketAddress is that
# the latter has fewer {} on the wire. # the latter has fewer ``{}`` on the wire.
# #
# Since: 1.3 # Since: 1.3
## ##

22
qapi/stats.json
View File

@ -258,17 +258,17 @@
# #
# @provider: a provider to restrict the query to. # @provider: a provider to restrict the query to.
# #
# Note: runtime-collected statistics and their names fall outside # .. note:: Runtime-collected statistics and their names fall outside
# QEMU's usual deprecation policies. QEMU will try to keep the # QEMU's usual deprecation policies. QEMU will try to keep the set
# set of available data stable, together with their names, but # of available data stable, together with their names, but will not
# will not guarantee stability at all costs; the same is true of # guarantee stability at all costs; the same is true of providers
# providers that source statistics externally, e.g. from Linux. # that source statistics externally, e.g. from Linux. For example,
# For example, if the same value is being tracked with different # if the same value is being tracked with different names on
# names on different architectures or by different providers, one # different architectures or by different providers, one of them
# of them might be renamed. A statistic might go away if an # might be renamed. A statistic might go away if an algorithm is
# algorithm is changed or some code is removed; changing a default # changed or some code is removed; changing a default might cause
# might cause previously useful statistics to always report 0. # previously useful statistics to always report 0. Such changes,
# Such changes, however, are expected to be rare. # however, are expected to be rare.
# #
# Since: 7.1 # Since: 7.1
## ##

8
qapi/transaction.json
View File

@ -235,11 +235,11 @@
# additional detail. # additional detail.
# #
# Errors: # Errors:
# Any errors from commands in the transaction # - Any errors from commands in the transaction
# #
# Note: The transaction aborts on the first failure. Therefore, there # .. note:: The transaction aborts on the first failure. Therefore,
# will be information on only one failed operation returned in an # there will be information on only one failed operation returned in
# error condition, and subsequent actions will not have been # an error condition, and subsequent actions will not have been
# attempted. # attempted.
# #
# Since: 1.1 # Since: 1.1

27
qapi/ui.json
View File

@ -107,11 +107,10 @@
# - '+INT' where INT is the number of seconds from now (integer) # - '+INT' where INT is the number of seconds from now (integer)
# - 'INT' where INT is the absolute time in seconds # - 'INT' where INT is the absolute time in seconds
# #
# Notes: Time is relative to the server and currently there is no way # .. note:: Time is relative to the server and currently there is no way
# to coordinate server time with client time. It is not # to coordinate server time with client time. It is not recommended
# recommended to use the absolute time version of the @time # to use the absolute time version of the @time parameter unless
# parameter unless you're sure you are on the same machine as the # you're sure you are on the same machine as the QEMU instance.
# QEMU instance.
# #
# Since: 7.0 # Since: 7.0
## ##
@ -274,7 +273,7 @@
# @unknown: No information is available about mouse mode used by the # @unknown: No information is available about mouse mode used by the
# spice server. # spice server.
# #
# Note: spice/enums.h has a SpiceMouseMode already, hence the name. # .. note:: spice/enums.h has a SpiceMouseMode already, hence the name.
# #
# Since: 1.1 # Since: 1.1
## ##
@ -361,7 +360,7 @@
# "channel-id": 0, # "channel-id": 0,
# "tls": false # "tls": false
# }, # },
# [ ... more channels follow ... ] # ...
# ] # ]
# } # }
# } # }
@ -705,7 +704,7 @@
# #
# Since: 1.1 # Since: 1.1
# #
# Notes: An empty password in this command will set the password to # .. note:: An empty password in this command will set the password to
# the empty string. Existing clients are unaffected by executing # the empty string. Existing clients are unaffected by executing
# this command. # this command.
## ##
@ -722,8 +721,8 @@
# #
# @client: client information # @client: client information
# #
# Note: This event is emitted before any authentication takes place, # .. note:: This event is emitted before any authentication takes place,
# thus the authentication ID is not provided # thus the authentication ID is not provided.
# #
# Since: 0.13 # Since: 0.13
# #
@ -1268,10 +1267,10 @@
# #
# Since: 2.6 # Since: 2.6
# #
# Note: The consoles are visible in the qom tree, under # .. note:: The consoles are visible in the qom tree, under
# /backend/console[$index]. They have a device link and head # ``/backend/console[$index]``. They have a device link and head
# property, so it is possible to map which console belongs to # property, so it is possible to map which console belongs to which
# which device and display. # device and display.
# #
# Examples: # Examples:
# #

8
qapi/virtio.json
View File

@ -559,12 +559,12 @@
# #
# Returns: VirtQueueStatus of the VirtQueue # Returns: VirtQueueStatus of the VirtQueue
# #
# Notes: last_avail_idx will not be displayed in the case where the # .. note:: last_avail_idx will not be displayed in the case where the
# selected VirtIODevice has a running vhost device and the # selected VirtIODevice has a running vhost device and the
# VirtIODevice VirtQueue index (queue) does not exist for the # VirtIODevice VirtQueue index (queue) does not exist for the
# corresponding vhost device vhost_virtqueue. Also, # corresponding vhost device vhost_virtqueue. Also, shadow_avail_idx
# shadow_avail_idx will not be displayed in the case where the # will not be displayed in the case where the selected VirtIODevice
# selected VirtIODevice has a running vhost device. # has a running vhost device.
# #
# Since: 7.2 # Since: 7.2
# #

42
qga/qapi-schema.json
View File

@ -422,8 +422,9 @@
# Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined
# below) # below)
# #
# Note: This may fail to properly report the current state as a result # .. note:: This may fail to properly report the current state as a
# of some other guest processes having issued an fs freeze/thaw. # result of some other guest processes having issued an fs
# freeze/thaw.
# #
# Since: 0.15.0 # Since: 0.15.0
## ##
@ -443,9 +444,9 @@
# #
# Returns: Number of file systems currently frozen. # Returns: Number of file systems currently frozen.
# #
# Note: On Windows, the command is implemented with the help of a # .. note:: On Windows, the command is implemented with the help of a
# Volume Shadow-copy Service DLL helper. The frozen state is # Volume Shadow-copy Service DLL helper. The frozen state is limited
# limited for up to 10 seconds by VSS. # for up to 10 seconds by VSS.
# #
# Since: 0.15.0 # Since: 0.15.0
## ##
@ -479,10 +480,10 @@
# #
# Returns: Number of file systems thawed by this call # Returns: Number of file systems thawed by this call
# #
# Note: if return value does not match the previous call to # .. note:: If the return value does not match the previous call to
# guest-fsfreeze-freeze, this likely means some freezable # guest-fsfreeze-freeze, this likely means some freezable filesystems
# filesystems were unfrozen before this call, and that the # were unfrozen before this call, and that the filesystem state may
# filesystem state may have changed before issuing this command. # have changed before issuing this command.
# #
# Since: 0.15.0 # Since: 0.15.0
## ##
@ -560,8 +561,8 @@
# Errors: # Errors:
# - If suspend to disk is not supported, Unsupported # - If suspend to disk is not supported, Unsupported
# #
# Notes: It's strongly recommended to issue the guest-sync command # .. note:: It's strongly recommended to issue the guest-sync command
# before sending commands when the guest resumes # before sending commands when the guest resumes.
# #
# Since: 1.1 # Since: 1.1
## ##
@ -596,8 +597,8 @@
# Errors: # Errors:
# - If suspend to ram is not supported, Unsupported # - If suspend to ram is not supported, Unsupported
# #
# Notes: It's strongly recommended to issue the guest-sync command # .. note:: It's strongly recommended to issue the guest-sync command
# before sending commands when the guest resumes # before sending commands when the guest resumes.
# #
# Since: 1.1 # Since: 1.1
## ##
@ -631,8 +632,8 @@
# Errors: # Errors:
# - If hybrid suspend is not supported, Unsupported # - If hybrid suspend is not supported, Unsupported
# #
# Notes: It's strongly recommended to issue the guest-sync command # .. note:: It's strongly recommended to issue the guest-sync command
# before sending commands when the guest resumes # before sending commands when the guest resumes.
# #
# Since: 1.1 # Since: 1.1
## ##
@ -1461,13 +1462,12 @@
# * POSIX: as defined by os-release(5) # * POSIX: as defined by os-release(5)
# * Windows: contains string "server" or "client" # * Windows: contains string "server" or "client"
# #
# Notes: On POSIX systems the fields @id, @name, @pretty-name, # .. note:: On POSIX systems the fields @id, @name, @pretty-name,
# @version, @version-id, @variant and @variant-id follow the # @version, @version-id, @variant and @variant-id follow the
# definition specified in os-release(5). Refer to the manual page # definition specified in os-release(5). Refer to the manual page for
# for exact description of the fields. Their values are taken # exact description of the fields. Their values are taken from the
# from the os-release file. If the file is not present in the # os-release file. If the file is not present in the system, or the
# system, or the values are not present in the file, the fields # values are not present in the file, the fields are not included.
# are not included.
# #
# On Windows the values are filled from information gathered from # On Windows the values are filled from information gathered from
# the system. # the system.

8
scripts/qapi/introspect.py
View File

@ -27,8 +27,8 @@ from .gen import QAPISchemaMonolithicCVisitor
from .schema import ( from .schema import (
QAPISchema, QAPISchema,
QAPISchemaAlternatives, QAPISchemaAlternatives,
QAPISchemaBranches,
QAPISchemaArrayType, QAPISchemaArrayType,
QAPISchemaBranches,
QAPISchemaBuiltinType, QAPISchemaBuiltinType,
QAPISchemaEntity, QAPISchemaEntity,
QAPISchemaEnumMember, QAPISchemaEnumMember,
@ -233,9 +233,9 @@ const QLitObject %(c_name)s = %(c_string)s;
typ = type_int typ = type_int
elif (isinstance(typ, QAPISchemaArrayType) and elif (isinstance(typ, QAPISchemaArrayType) and
typ.element_type.json_type() == 'int'): typ.element_type.json_type() == 'int'):
type_intList = self._schema.lookup_type('intList') type_intlist = self._schema.lookup_type('intList')
assert type_intList assert type_intlist
typ = type_intList typ = type_intlist
# Add type to work queue if new # Add type to work queue if new
if typ not in self._used_types: if typ not in self._used_types:
self._used_types.append(typ) self._used_types.append(typ)

30
scripts/qapi/parser.py
View File

@ -448,7 +448,7 @@ class QAPISchemaParser:
indent = must_match(r'\s*', line).end() indent = must_match(r'\s*', line).end()
if not indent: if not indent:
return line return line
doc.append_line(line[indent:]) doc.append_line(line)
prev_line_blank = False prev_line_blank = False
while True: while True:
self.accept(False) self.accept(False)
@ -465,7 +465,7 @@ class QAPISchemaParser:
self, self,
"unexpected de-indent (expected at least %d spaces)" % "unexpected de-indent (expected at least %d spaces)" %
indent) indent)
doc.append_line(line[indent:]) doc.append_line(line)
prev_line_blank = True prev_line_blank = True
def get_doc_paragraph(self, doc: 'QAPIDoc') -> Optional[str]: def get_doc_paragraph(self, doc: 'QAPIDoc') -> Optional[str]:
@ -544,9 +544,29 @@ class QAPISchemaParser:
line = self.get_doc_indented(doc) line = self.get_doc_indented(doc)
no_more_args = True no_more_args = True
elif match := re.match( elif match := re.match(
r'(Returns|Errors|Since|Notes?|Examples?|TODO): *', r'(Returns|Errors|Since|Notes?|Examples?|TODO)'
line): r'(?!::): *',
line,
):
# tagged section # tagged section
# Note: "sections" with two colons are left alone as
# rST markup and not interpreted as a section heading.
# TODO: Remove this error sometime in 2025 or so
# after we've fully transitioned to the new qapidoc
# generator.
# See commit message for more markup suggestions O:-)
if 'Note' in match.group(1):
emsg = (
f"The '{match.group(1)}' section is no longer "
"supported. Please use rST's '.. note::' or "
"'.. admonition:: notes' directives, or another "
"suitable admonition instead."
)
raise QAPIParseError(self, emsg)
doc.new_tagged_section(self.info, match.group(1)) doc.new_tagged_section(self.info, match.group(1))
text = line[match.end():] text = line[match.end():]
if text: if text:
@ -583,7 +603,7 @@ class QAPISchemaParser:
line = self.get_doc_line() line = self.get_doc_line()
first = False first = False
self.accept(False) self.accept()
doc.end() doc.end()
return doc return doc

4
scripts/qapi/schema.py
View File

@ -730,6 +730,7 @@ class QAPISchemaVariants:
for v in self.variants: for v in self.variants:
v.set_defined_in(name) v.set_defined_in(name)
# pylint: disable=unused-argument
def check( def check(
self, schema: QAPISchema, seen: Dict[str, QAPISchemaMember] self, schema: QAPISchema, seen: Dict[str, QAPISchemaMember]
) -> None: ) -> None:
@ -1302,11 +1303,10 @@ class QAPISchema:
name = 'q_obj_%s-%s' % (name, role) name = 'q_obj_%s-%s' % (name, role)
typ = self.lookup_entity(name) typ = self.lookup_entity(name)
if typ: if typ:
assert(isinstance(typ, QAPISchemaObjectType)) assert isinstance(typ, QAPISchemaObjectType)
# The implicit object type has multiple users. This can # The implicit object type has multiple users. This can
# only be a duplicate definition, which will be flagged # only be a duplicate definition, which will be flagged
# later. # later.
pass
else: else:
self._def_definition(QAPISchemaObjectType( self._def_definition(QAPISchemaObjectType(
name, info, None, ifcond, None, None, members, None)) name, info, None, ifcond, None, None, members, None))

3
scripts/qapi/visit.py
View File

@ -280,7 +280,8 @@ bool visit_type_%(c_name)s(Visitor *v, const char *name,
abort(); abort();
default: default:
assert(visit_is_input(v)); assert(visit_is_input(v));
error_setg(errp, "Invalid parameter type for '%%s', expected: %(name)s", error_setg(errp,
"Invalid parameter type for '%%s', expected: %(name)s",
name ? name : "null"); name ? name : "null");
/* Avoid passing invalid *obj to qapi_free_%(c_name)s() */ /* Avoid passing invalid *obj to qapi_free_%(c_name)s() */
g_free(*obj); g_free(*obj);

2
tests/qapi-schema/doc-empty-section.err
View File

@ -1 +1 @@
doc-empty-section.json:6: text required after 'Note:' doc-empty-section.json:6: text required after 'Errors:'

2
tests/qapi-schema/doc-empty-section.json
View File

@ -3,6 +3,6 @@
## ##
# @foo: # @foo:
# #
# Note: # Errors:
## ##
{ 'command': 'foo', 'data': {'a': 'int'} } { 'command': 'foo', 'data': {'a': 'int'} }

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

@ -55,6 +55,8 @@
# - {braces} # - {braces}
## ##
# Not a doc comment
## ##
# @Enum: # @Enum:
# #
@ -155,7 +157,7 @@
# @cmd-feat1: a feature # @cmd-feat1: a feature
# @cmd-feat2: another feature # @cmd-feat2: another feature
# #
# Note: @arg3 is undocumented # .. note:: @arg3 is undocumented
# #
# Returns: @Object # Returns: @Object
# #
@ -163,7 +165,7 @@
# #
# TODO: frobnicate # TODO: frobnicate
# #
# Notes: # .. admonition:: Notes
# #
# - Lorem ipsum dolor sit amet # - Lorem ipsum dolor sit amet
# - Ut enim ad minim veniam # - Ut enim ad minim veniam
@ -179,6 +181,9 @@
# - *verbatim* # - *verbatim*
# - {braces} # - {braces}
# #
# Note::
# Ceci n'est pas une note
#
# Since: 2.10 # Since: 2.10
## ##
{ 'command': 'cmd', { 'command': 'cmd',

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

@ -169,15 +169,17 @@ remainder indented differently
a feature a feature
feature=cmd-feat2 feature=cmd-feat2
another feature another feature
section=Note section=None
@arg3 is undocumented .. note:: @arg3 is undocumented
section=Returns section=Returns
@Object @Object
section=Errors section=Errors
some some
section=TODO section=TODO
frobnicate frobnicate
section=Notes section=None
.. admonition:: Notes
- Lorem ipsum dolor sit amet - Lorem ipsum dolor sit amet
- Ut enim ad minim veniam - Ut enim ad minim veniam
@ -188,6 +190,9 @@ Duis aute irure dolor
section=Examples section=Examples
- *verbatim* - *verbatim*
- {braces} - {braces}
section=None
Note::
Ceci n'est pas une note
section=Since section=Since
2.10 2.10
doc symbol=cmd-boxed doc symbol=cmd-boxed

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

@ -193,9 +193,7 @@ Features
"cmd-feat2" "cmd-feat2"
another feature another feature
Note:
Note
~~~~
"arg3" is undocumented "arg3" is undocumented
@ -211,9 +209,7 @@ Errors
some some
Notes:
Notes
~~~~~
* Lorem ipsum dolor sit amet * Lorem ipsum dolor sit amet
@ -235,6 +231,9 @@ Examples
- *verbatim* - *verbatim*
- {braces} - {braces}
Note::
Ceci n'est pas une note
Since Since
~~~~~ ~~~~~

2
tests/qapi-schema/doc-interleaved-section.json
View File

@ -10,7 +10,7 @@
# #
# bao # bao
# #
# Note: a section. # TODO: a section.
# #
# @foobar: catch this # @foobar: catch this
# #