Proxmox-Port/qemu
1
0
Fork 0
mirror of https://github.com/qemu/qemu.git synced 2025-08-15 13:47:03 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

QAPI patches patches for 2025-07-14

Browse Source 
-----BEGIN PGP SIGNATURE-----
 
 iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmh19QoSHGFybWJydUBy
 ZWRoYXQuY29tAAoJEDhwtADrkYZThVIP/2v9M9C9k7q3bAku38gO6LqU/TJINKEt
 ZlJt7L3LWRC51rpTmhTs6ZchdErs0wnNs2gCH/HjANDofa8lz9u7mpqUo+hVIW2r
 eUi7uEURIBqsfMgantrQu1uhJg3rbtd9gWtxwTJm3qoFKjwxrWlxhEqOFlNSoqkv
 DpoBD6X7zhUtEq6Z5IIsOBI2zqaXNleSsYWdgxJou8cvHMZkgdcvEyE36nRFsl2k
 JSbnRLzFxsxuxd0bIBSrA3+I1pC9pWYS9ZY1qTnyPIX7MxeVvYupaWdOYlpELxi5
 4zz7stS5wcvUJ+X7+HuobOofBjHljcHVxE06ACr38sQ2Ajqn3jhijQrDrtYdxG5P
 3kCnP+AY+qFa2CN/Ik7q2be5jz6Ws/3kxZrv/4/LrHa5ez1xB/orooQVZId0eKke
 5iQOyA9gNXAdJ2JJYdIAZduBg2b8tY892qtMufBA+XDNA3vGek2OixWC0QY5hZKW
 y3AKjVHP/sProyCvbyT7Fta8sIRLcIVD0IHjzr7pLVd/lp/WzKAJpg6y8J2wvn6z
 cnEUC5CceiYa8SbGOVfswR1yy06IIpJkw6cxoCzB3a2blfkvxGv4mCY6QiZh8K3W
 6xj6u1J539NWRGVkvnQWJ4/7MdFAOEqih4AqRpRLnRXJ+hzDVUkgCeZwtr+v6AVi
 mNVLttTKPpvy
 =2BHn
 -----END PGP SIGNATURE-----

Merge tag 'pull-qapi-2025-07-14-v2' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2025-07-14

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmh19QoSHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZThVIP/2v9M9C9k7q3bAku38gO6LqU/TJINKEt
# ZlJt7L3LWRC51rpTmhTs6ZchdErs0wnNs2gCH/HjANDofa8lz9u7mpqUo+hVIW2r
# eUi7uEURIBqsfMgantrQu1uhJg3rbtd9gWtxwTJm3qoFKjwxrWlxhEqOFlNSoqkv
# DpoBD6X7zhUtEq6Z5IIsOBI2zqaXNleSsYWdgxJou8cvHMZkgdcvEyE36nRFsl2k
# JSbnRLzFxsxuxd0bIBSrA3+I1pC9pWYS9ZY1qTnyPIX7MxeVvYupaWdOYlpELxi5
# 4zz7stS5wcvUJ+X7+HuobOofBjHljcHVxE06ACr38sQ2Ajqn3jhijQrDrtYdxG5P
# 3kCnP+AY+qFa2CN/Ik7q2be5jz6Ws/3kxZrv/4/LrHa5ez1xB/orooQVZId0eKke
# 5iQOyA9gNXAdJ2JJYdIAZduBg2b8tY892qtMufBA+XDNA3vGek2OixWC0QY5hZKW
# y3AKjVHP/sProyCvbyT7Fta8sIRLcIVD0IHjzr7pLVd/lp/WzKAJpg6y8J2wvn6z
# cnEUC5CceiYa8SbGOVfswR1yy06IIpJkw6cxoCzB3a2blfkvxGv4mCY6QiZh8K3W
# 6xj6u1J539NWRGVkvnQWJ4/7MdFAOEqih4AqRpRLnRXJ+hzDVUkgCeZwtr+v6AVi
# mNVLttTKPpvy
# =2BHn
# -----END PGP SIGNATURE-----
# gpg: Signature made Tue 15 Jul 2025 02:28:26 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-07-14-v2' of https://repo.or.cz/qemu/armbru: (29 commits)
  qapi: add cross-references to misc modules
  qapi: add cross-references to yank.json
  qapi: add cross-references to virtio.json
  qapi: add cross-references to ui.json
  qapi: add cross-references to sockets.json
  qapi: add cross-references to run-state.json
  qapi: add cross-references to replay.json
  qapi: add cross-references to QOM
  qapi: add cross-references to pci.json
  qapi: add cross-references to net.json
  qapi: add cross-references to migration.json
  qapi: add cross-references to Machine core
  qapi: add cross-references to job.json
  qapi: add cross-references to dump.json
  qapi: add cross-references to crypto.json
  qapi: add cross-references to block layer
  qapi: add cross-references to authz.json
  qapi: add cross-references to acpi.json
  qapi: rephrase return docs to avoid type name
  qapi: remove trivial "Returns:" sections
  ...

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
This commit is contained in:
Stefan Hajnoczi 2025-07-16 07:07:29 -04:00
commit 504632dcc6
63 changed files with 757 additions and 1282 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -876,25 +876,35 @@ structuring content.
Headings and subheadings
~~~~~~~~~~~~~~~~~~~~~~~~
A free-form documentation comment containing a line which starts with
some ``=`` symbols and then a space defines a section heading::
Free-form documentation does not start with ``@SYMBOL`` and can contain
arbitrary rST markup. Headings can be marked up using the standard rST
syntax::
##
# = This is a top level heading
# *************************
# This is a level 2 heading
# *************************
#
# This is a free-form comment which will go under the
# top level heading.
##
##
# == This is a second level heading
# This is a third level heading
# ==============================
#
# Level 4
# _______
#
# Level 5
# ^^^^^^^
#
# Level 6
# """""""
##
A heading line must be the first line of the documentation
comment block.
Section headings must always be correctly nested, so you can only
define a third-level heading inside a second-level heading, and so on.
Level 1 headings are reserved for use by the generated documentation
page itself, leaving level 2 as the highest level that should be used.
Documentation markup

31
docs/devel/qapi-domain.rst
View File

@ -242,6 +242,37 @@ Example::
}
``:return-nodesc:``
-------------------
Document the return type of a QAPI command, without an accompanying
description.
:availability: This field list is only available in the body of the
Command directive.
:syntax: ``:return-nodesc: type``
:type: `sphinx.util.docfields.Field
<https://pydoc.dev/sphinx/latest/sphinx.util.docfields.Field.html?private=1>`_
Example::
.. qapi:command:: query-replay
:since: 5.2
Retrieve the record/replay information. It includes current
instruction count which may be used for ``replay-break`` and
``replay-seek`` commands.
:return-nodesc: ReplayInfo
.. qmp-example::
-> { "execute": "query-replay" }
<- { "return": {
"mode": "play", "filename": "log.rr", "icount": 220414 }
}
``:value:``
-----------

4
docs/interop/firmware.json
View File

@ -11,7 +11,9 @@
# later. See the COPYING file in the top-level directory.
##
# = Firmware
# ********
# Firmware
# ********
##
{ 'pragma': {

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

@ -2,5 +2,4 @@ QEMU Guest Agent Protocol Reference
===================================
.. qapi-doc:: qga/qapi-schema.json
:transmogrify:
:namespace: QGA

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

@ -7,5 +7,4 @@ QEMU QMP Reference Manual
:local:
.. qapi-doc:: qapi/qapi-schema.json
:transmogrify:
:namespace: QMP

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

@ -5,5 +5,4 @@ QEMU Storage Daemon QMP Reference Manual
:local:
.. qapi-doc:: storage-daemon/qapi/qapi-schema.json
:transmogrify:
:namespace: QSD

4
docs/interop/vhost-user.json
View File

@ -10,7 +10,9 @@
# later. See the COPYING file in the top-level directory.
##
# = vhost user backend discovery & capabilities
# *******************************************
# vhost user backend discovery & capabilities
# *******************************************
##
##

8
docs/sphinx/qapi_domain.py
View File

@ -532,6 +532,14 @@ class QAPICommand(QAPIObject):
names=("return",),
can_collapse=True,
),
# :return-nodesc: TypeName
CompatField(
"returnvalue",
label=_("Return"),
names=("return-nodesc",),
bodyrolename="type",
has_arg=False,
),
]
)

96
docs/sphinx/qapidoc.py
View File

@ -64,8 +64,6 @@
from sphinx.util.docutils import SphinxDirective, switch_source_input
from sphinx.util.nodes import nested_parse_with_titles
from qapidoc_legacy import QAPISchemaGenRSTVisitor # type: ignore
if TYPE_CHECKING:
from typing import (
@ -218,6 +216,11 @@ def generate_field(
typ = self.format_type(member)
self.add_field(kind, member.name, body, info, typ)
@staticmethod
def reformat_arobase(text: str) -> str:
""" reformats @var to ``var`` """
return re.sub(r"@([\w-]+)", r"``\1``", text)
# Transmogrification helpers
def visit_paragraph(self, section: QAPIDoc.Section) -> None:
@ -255,22 +258,28 @@ def visit_feature(self, section: QAPIDoc.ArgSection) -> None:
def visit_returns(self, section: QAPIDoc.Section) -> None:
assert isinstance(self.entity, QAPISchemaCommand)
rtype = self.entity.ret_type
# q_empty can produce None, but we won't be documenting anything
# without an explicit return statement in the doc block, and we
# should not have any such explicit statements when there is no
# return value.
# return statements will not be present (and won't be
# autogenerated) for any command that doesn't return
# *something*, so rtype will always be defined here.
assert rtype
typ = self.format_type(rtype)
assert typ
assert section.text
self.add_field("return", typ, section.text, section.info)
if section.text:
self.add_field("return", typ, section.text, section.info)
else:
self.add_lines(f":return-nodesc: {typ}", section.info)
def visit_errors(self, section: QAPIDoc.Section) -> None:
# FIXME: the formatting for errors may be inconsistent and may
# or may not require different newline placement to ensure
# proper rendering as a nested list.
self.add_lines(f":error:\n{section.text}", section.info)
# If the section text does not start with a space, it means text
# began on the same line as the "Error:" string and we should
# not insert a newline in this case.
if section.text[0].isspace():
text = f":error:\n{section.text}"
else:
text = f":error: {section.text}"
self.add_lines(text, section.info)
def preamble(self, ent: QAPISchemaDefinition) -> None:
"""
@ -357,8 +366,7 @@ def visit_sections(self, ent: QAPISchemaDefinition) -> None:
# Add sections in source order:
for i, section in enumerate(sections):
# @var is translated to ``var``:
section.text = re.sub(r"@([\w-]+)", r"``\1``", section.text)
section.text = self.reformat_arobase(section.text)
if section.kind == QAPIDoc.Kind.PLAIN:
self.visit_paragraph(section)
@ -393,44 +401,9 @@ def visit_module(self, path: str) -> None:
self.ensure_blank_line()
def visit_freeform(self, doc: QAPIDoc) -> None:
# TODO: Once the old qapidoc transformer is deprecated, freeform
# sections can be updated to pure rST, and this transformed removed.
#
# For now, translate our micro-format into rST. Code adapted
# from Peter Maydell's freeform().
assert len(doc.all_sections) == 1, doc.all_sections
body = doc.all_sections[0]
text = body.text
info = doc.info
if re.match(r"=+ ", text):
# Section/subsection heading (if present, will always be the
# first line of the block)
(heading, _, text) = text.partition("\n")
(leader, _, heading) = heading.partition(" ")
# Implicit +1 for heading in the containing .rst doc
level = len(leader) + 1
# https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections
markers = ' #*=_^"'
overline = level <= 2
marker = markers[level]
self.ensure_blank_line()
# This credits all 2 or 3 lines to the single source line.
if overline:
self.add_line(marker * len(heading), info)
self.add_line(heading, info)
self.add_line(marker * len(heading), info)
self.ensure_blank_line()
# Eat blank line(s) and advance info
trimmed = text.lstrip("\n")
text = trimmed
info = info.next_line(len(text) - len(trimmed) + 1)
self.add_lines(text, info)
self.add_lines(self.reformat_arobase(body.text), doc.info)
self.ensure_blank_line()
def visit_entity(self, ent: QAPISchemaDefinition) -> None:
@ -504,15 +477,9 @@ class QAPIDocDirective(NestedDirective):
option_spec = {
"qapifile": directives.unchanged_required,
"namespace": directives.unchanged,
"transmogrify": directives.flag,
}
has_content = False
def new_serialno(self) -> str:
"""Return a unique new ID string suitable for use as a node's ID"""
env = self.state.document.settings.env
return "qapidoc-%d" % env.new_serialno("qapidoc")
def transmogrify(self, schema: QAPISchema) -> nodes.Element:
logger.info("Transmogrifying QAPI to rST ...")
vis = Transmogrifier()
@ -590,21 +557,10 @@ def write_intermediate(self, content: StringList, filename: str) -> None:
outfile.write(f" {rcol}")
outfile.write("\n")
def legacy(self, schema: QAPISchema) -> nodes.Element:
vis = QAPISchemaGenRSTVisitor(self)
vis.visit_begin(schema)
for doc in schema.docs:
if doc.symbol:
vis.symbol(doc, schema.lookup_entity(doc.symbol))
else:
vis.freeform(doc)
return vis.get_document_node() # type: ignore
def run(self) -> Sequence[nodes.Node]:
env = self.state.document.settings.env
qapifile = env.config.qapidoc_srctree + "/" + self.arguments[0]
qapidir = os.path.dirname(qapifile)
transmogrify = "transmogrify" in self.options
try:
schema = QAPISchema(qapifile)
@ -617,11 +573,7 @@ def run(self) -> Sequence[nodes.Node]:
# so they are displayed nicely to the user
raise ExtensionError(str(err)) from err
if transmogrify:
contentnode = self.transmogrify(schema)
else:
contentnode = self.legacy(schema)
contentnode = self.transmogrify(schema)
return contentnode.children

440
docs/sphinx/qapidoc_legacy.py
View File

@ -1,440 +0,0 @@
# coding=utf-8
# type: ignore
#
# QEMU qapidoc QAPI file parsing extension
#
# Copyright (c) 2020 Linaro
#
# This work is licensed under the terms of the GNU GPLv2 or later.
# See the COPYING file in the top-level directory.
"""
qapidoc is a Sphinx extension that implements the qapi-doc directive
The purpose of this extension is to read the documentation comments
in QAPI schema files, and insert them all into the current document.
It implements one new rST directive, "qapi-doc::".
Each qapi-doc:: directive takes one argument, which is the
pathname of the schema file to process, relative to the source tree.
The docs/conf.py file must set the qapidoc_srctree config value to
the root of the QEMU source tree.
The Sphinx documentation on writing extensions is at:
https://www.sphinx-doc.org/en/master/development/index.html
"""
import re
import textwrap
from docutils import nodes
from docutils.statemachine import ViewList
from qapi.error import QAPISemError
from qapi.gen import QAPISchemaVisitor
from qapi.parser import QAPIDoc
def dedent(text: str) -> str:
# Adjust indentation to make description text parse as paragraph.
lines = text.splitlines(True)
if re.match(r"\s+", lines[0]):
# First line is indented; description started on the line after
# the name. dedent the whole block.
return textwrap.dedent(text)
# Descr started on same line. Dedent line 2+.
return lines[0] + textwrap.dedent("".join(lines[1:]))
class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
"""A QAPI schema visitor which generates docutils/Sphinx nodes
This class builds up a tree of docutils/Sphinx nodes corresponding
to documentation for the various QAPI objects. To use it, first
create a QAPISchemaGenRSTVisitor object, and call its
visit_begin() method. Then you can call one of the two methods
'freeform' (to add documentation for a freeform documentation
chunk) or 'symbol' (to add documentation for a QAPI symbol). These
will cause the visitor to build up the tree of document
nodes. Once you've added all the documentation via 'freeform' and
'symbol' method calls, you can call 'get_document_nodes' to get
the final list of document nodes (in a form suitable for returning
from a Sphinx directive's 'run' method).
"""
def __init__(self, sphinx_directive):
self._cur_doc = None
self._sphinx_directive = sphinx_directive
self._top_node = nodes.section()
self._active_headings = [self._top_node]
def _make_dlitem(self, term, defn):
"""Return a dlitem node with the specified term and definition.
term should be a list of Text and literal nodes.
defn should be one of:
- a string, which will be handed to _parse_text_into_node
- a list of Text and literal nodes, which will be put into
a paragraph node
"""
dlitem = nodes.definition_list_item()
dlterm = nodes.term('', '', *term)
dlitem += dlterm
if defn:
dldef = nodes.definition()
if isinstance(defn, list):
dldef += nodes.paragraph('', '', *defn)
else:
self._parse_text_into_node(defn, dldef)
dlitem += dldef
return dlitem
def _make_section(self, title):
"""Return a section node with optional title"""
section = nodes.section(ids=[self._sphinx_directive.new_serialno()])
if title:
section += nodes.title(title, title)
return section
def _nodes_for_ifcond(self, ifcond, with_if=True):
"""Return list of Text, literal nodes for the ifcond
Return a list which gives text like ' (If: condition)'.
If with_if is False, we don't return the "(If: " and ")".
"""
doc = ifcond.docgen()
if not doc:
return []
doc = nodes.literal('', doc)
if not with_if:
return [doc]
nodelist = [nodes.Text(' ('), nodes.strong('', 'If: ')]
nodelist.append(doc)
nodelist.append(nodes.Text(')'))
return nodelist
def _nodes_for_one_member(self, member):
"""Return list of Text, literal nodes for this member
Return a list of doctree nodes which give text like
'name: type (optional) (If: ...)' suitable for use as the
'term' part of a definition list item.
"""
term = [nodes.literal('', member.name)]
if member.type.doc_type():
term.append(nodes.Text(': '))
term.append(nodes.literal('', member.type.doc_type()))
if member.optional:
term.append(nodes.Text(' (optional)'))
if member.ifcond.is_present():
term.extend(self._nodes_for_ifcond(member.ifcond))
return term
def _nodes_for_variant_when(self, branches, variant):
"""Return list of Text, literal nodes for variant 'when' clause
Return a list of doctree nodes which give text like
'when tagname is variant (If: ...)' suitable for use in
the 'branches' part of a definition list.
"""
term = [nodes.Text(' when '),
nodes.literal('', branches.tag_member.name),
nodes.Text(' is '),
nodes.literal('', '"%s"' % variant.name)]
if variant.ifcond.is_present():
term.extend(self._nodes_for_ifcond(variant.ifcond))
return term
def _nodes_for_members(self, doc, what, base=None, branches=None):
"""Return list of doctree nodes for the table of members"""
dlnode = nodes.definition_list()
for section in doc.args.values():
term = self._nodes_for_one_member(section.member)
# TODO drop fallbacks when undocumented members are outlawed
if section.text:
defn = dedent(section.text)
else:
defn = [nodes.Text('Not documented')]
dlnode += self._make_dlitem(term, defn)
if base:
dlnode += self._make_dlitem([nodes.Text('The members of '),
nodes.literal('', base.doc_type())],
None)
if branches:
for v in branches.variants:
if v.type.name == 'q_empty':
continue
assert not v.type.is_implicit()
term = [nodes.Text('The members of '),
nodes.literal('', v.type.doc_type())]
term.extend(self._nodes_for_variant_when(branches, v))
dlnode += self._make_dlitem(term, None)
if not dlnode.children:
return []
section = self._make_section(what)
section += dlnode
return [section]
def _nodes_for_enum_values(self, doc):
"""Return list of doctree nodes for the table of enum values"""
seen_item = False
dlnode = nodes.definition_list()
for section in doc.args.values():
termtext = [nodes.literal('', section.member.name)]
if section.member.ifcond.is_present():
termtext.extend(self._nodes_for_ifcond(section.member.ifcond))
# TODO drop fallbacks when undocumented members are outlawed
if section.text:
defn = dedent(section.text)
else:
defn = [nodes.Text('Not documented')]
dlnode += self._make_dlitem(termtext, defn)
seen_item = True
if not seen_item:
return []
section = self._make_section('Values')
section += dlnode
return [section]
def _nodes_for_arguments(self, doc, arg_type):
"""Return list of doctree nodes for the arguments section"""
if arg_type and not arg_type.is_implicit():
assert not doc.args
section = self._make_section('Arguments')
dlnode = nodes.definition_list()
dlnode += self._make_dlitem(
[nodes.Text('The members of '),
nodes.literal('', arg_type.name)],
None)
section += dlnode
return [section]
return self._nodes_for_members(doc, 'Arguments')
def _nodes_for_features(self, doc):
"""Return list of doctree nodes for the table of features"""
seen_item = False
dlnode = nodes.definition_list()
for section in doc.features.values():
dlnode += self._make_dlitem(
[nodes.literal('', section.member.name)], dedent(section.text))
seen_item = True
if not seen_item:
return []
section = self._make_section('Features')
section += dlnode
return [section]
def _nodes_for_sections(self, doc):
"""Return list of doctree nodes for additional sections"""
nodelist = []
for section in doc.sections:
if section.kind == QAPIDoc.Kind.TODO:
# Hide TODO: sections
continue
if section.kind == QAPIDoc.Kind.PLAIN:
# 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.kind.name.title())
self._parse_text_into_node(dedent(section.text), snode)
nodelist.append(snode)
return nodelist
def _nodes_for_if_section(self, ifcond):
"""Return list of doctree nodes for the "If" section"""
nodelist = []
if ifcond.is_present():
snode = self._make_section('If')
snode += nodes.paragraph(
'', '', *self._nodes_for_ifcond(ifcond, with_if=False)
)
nodelist.append(snode)
return nodelist
def _add_doc(self, typ, sections):
"""Add documentation for a command/object/enum...
We assume we're documenting the thing defined in self._cur_doc.
typ is the type of thing being added ("Command", "Object", etc)
sections is a list of nodes for sections to add to the definition.
"""
doc = self._cur_doc
snode = nodes.section(ids=[self._sphinx_directive.new_serialno()])
snode += nodes.title('', '', *[nodes.literal(doc.symbol, doc.symbol),
nodes.Text(' (' + typ + ')')])
self._parse_text_into_node(doc.body.text, snode)
for s in sections:
if s is not None:
snode += s
self._add_node_to_current_heading(snode)
def visit_enum_type(self, name, info, ifcond, features, members, prefix):
doc = self._cur_doc
self._add_doc('Enum',
self._nodes_for_enum_values(doc)
+ self._nodes_for_features(doc)
+ self._nodes_for_sections(doc)
+ self._nodes_for_if_section(ifcond))
def visit_object_type(self, name, info, ifcond, features,
base, members, branches):
doc = self._cur_doc
if base and base.is_implicit():
base = None
self._add_doc('Object',
self._nodes_for_members(doc, 'Members', base, branches)
+ self._nodes_for_features(doc)
+ self._nodes_for_sections(doc)
+ self._nodes_for_if_section(ifcond))
def visit_alternate_type(self, name, info, ifcond, features,
alternatives):
doc = self._cur_doc
self._add_doc('Alternate',
self._nodes_for_members(doc, 'Members')
+ self._nodes_for_features(doc)
+ self._nodes_for_sections(doc)
+ self._nodes_for_if_section(ifcond))
def visit_command(self, name, info, ifcond, features, arg_type,
ret_type, gen, success_response, boxed, allow_oob,
allow_preconfig, coroutine):
doc = self._cur_doc
self._add_doc('Command',
self._nodes_for_arguments(doc, arg_type)
+ self._nodes_for_features(doc)
+ self._nodes_for_sections(doc)
+ self._nodes_for_if_section(ifcond))
def visit_event(self, name, info, ifcond, features, arg_type, boxed):
doc = self._cur_doc
self._add_doc('Event',
self._nodes_for_arguments(doc, arg_type)
+ self._nodes_for_features(doc)
+ self._nodes_for_sections(doc)
+ self._nodes_for_if_section(ifcond))
def symbol(self, doc, entity):
"""Add documentation for one symbol to the document tree
This is the main entry point which causes us to add documentation
nodes for a symbol (which could be a 'command', 'object', 'event',
etc). We do this by calling 'visit' on the schema entity, which
will then call back into one of our visit_* methods, depending
on what kind of thing this symbol is.
"""
self._cur_doc = doc
entity.visit(self)
self._cur_doc = None
def _start_new_heading(self, heading, level):
"""Start a new heading at the specified heading level
Create a new section whose title is 'heading' and which is placed
in the docutils node tree as a child of the most recent level-1
heading. Subsequent document sections (commands, freeform doc chunks,
etc) will be placed as children of this new heading section.
"""
if len(self._active_headings) < level:
raise QAPISemError(self._cur_doc.info,
'Level %d subheading found outside a '
'level %d heading'
% (level, level - 1))
snode = self._make_section(heading)
self._active_headings[level - 1] += snode
self._active_headings = self._active_headings[:level]
self._active_headings.append(snode)
return snode
def _add_node_to_current_heading(self, node):
"""Add the node to whatever the current active heading is"""
self._active_headings[-1] += node
def freeform(self, doc):
"""Add a piece of 'freeform' documentation to the document tree
A 'freeform' document chunk doesn't relate to any particular
symbol (for instance, it could be an introduction).
If the freeform document starts with a line of the form
'= Heading text', this is a section or subsection heading, with
the heading level indicated by the number of '=' signs.
"""
# QAPIDoc documentation says free-form documentation blocks
# must have only a body section, nothing else.
assert not doc.sections
assert not doc.args
assert not doc.features
self._cur_doc = doc
text = doc.body.text
if re.match(r'=+ ', text):
# Section/subsection heading (if present, will always be
# the first line of the block)
(heading, _, text) = text.partition('\n')
(leader, _, heading) = heading.partition(' ')
node = self._start_new_heading(heading, len(leader))
if text == '':
return
else:
node = nodes.container()
self._parse_text_into_node(text, node)
self._cur_doc = None
def _parse_text_into_node(self, doctext, node):
"""Parse a chunk of QAPI-doc-format text into the node
The doc comment can contain most inline rST markup, including
bulleted and enumerated lists.
As an extra permitted piece of markup, @var will be turned
into ``var``.
"""
# Handle the "@var means ``var`` case
doctext = re.sub(r'@([\w-]+)', r'``\1``', doctext)
rstlist = ViewList()
for line in doctext.splitlines():
# The reported line number will always be that of the start line
# of the doc comment, rather than the actual location of the error.
# Being more precise would require overhaul of the QAPIDoc class
# to track lines more exactly within all the sub-parts of the doc
# comment, as well as counting lines here.
rstlist.append(line, self._cur_doc.info.fname,
self._cur_doc.info.line)
# Append a blank line -- in some cases rST syntax errors get
# attributed to the line after one with actual text, and if there
# isn't anything in the ViewList corresponding to that then Sphinx
# 1.6's AutodocReporter will then misidentify the source/line location
# in the error message (usually attributing it to the top-level
# .rst file rather than the offending .json file). The extra blank
# line won't affect the rendered output.
rstlist.append("", self._cur_doc.info.fname, self._cur_doc.info.line)
self._sphinx_directive.do_parse(rstlist, node)
def get_document_node(self):
"""Return the root docutils node which makes up the document"""
return self._top_node

2
python/tests/qapi-isort.sh
View File

@ -3,6 +3,6 @@
python3 -m isort --sp . -c ../scripts/qapi/
# Force isort to recognize "compat" as a local module and not third-party
python3 -m isort --sp . -c -p compat -p qapidoc_legacy \
python3 -m isort --sp . -c -p compat \
../docs/sphinx/qapi_domain.py \
../docs/sphinx/qapidoc.py

6
qapi/acpi.json
View File

@ -6,7 +6,9 @@
# SPDX-License-Identifier: GPL-2.0-or-later
##
# = ACPI
# ****
# ACPI
# ****
##
##
@ -106,7 +108,7 @@
##
# @query-acpi-ospm-status:
#
# Return a list of ACPIOSTInfo for devices that support status
# Return a list of `ACPIOSTInfo` for devices that support status
# reporting via ACPI _OST method.
#
# Since: 2.1

6
qapi/audio.json
View File

@ -7,7 +7,9 @@
# See the COPYING file in the top-level directory.
##
# = Audio
# *****
# Audio
# *****
##
##
@ -535,8 +537,6 @@
#
# Return information about audiodev configuration
#
# Returns: array of @Audiodev
#
# Since: 8.0
##
{ 'command': 'query-audiodevs',

6
qapi/authz.json
View File

@ -2,7 +2,9 @@
# vim: filetype=python
##
# = User authorization
# ******************
# User authorization
# ******************
##
##
@ -75,7 +77,7 @@
# Properties for authz-listfile objects.
#
# @filename: File name to load the configuration from. The file must
# contain valid JSON for AuthZListProperties.
# contain valid JSON for `AuthZListProperties`.
#
# @refresh: If true, inotify is used to monitor the file,
# automatically reloading changes. If an error occurs during

201
qapi/block-core.json
View File

@ -2,7 +2,8 @@
# vim: filetype=python
##
# == Block core (VM unrelated)
# Block core (VM unrelated)
# =========================
##
{ 'include': 'common.json' }
@ -31,7 +32,7 @@
# @icount: Current instruction count. Appears when execution
# record/replay is enabled. Used for "time-traveling" to match
# the moment in the recorded execution with the snapshots. This
# counter may be obtained through @query-replay command
# counter may be obtained through `query-replay` command
# (since 5.2)
#
# Since: 1.3
@ -223,7 +224,7 @@
{ 'struct': 'ImageInfoSpecificLUKSWrapper',
'data': { 'data': 'QCryptoBlockInfoLUKS' } }
# If we need to add block driver specific parameters for
# LUKS in future, then we'll subclass QCryptoBlockInfoLUKS
# LUKS in future, then we'll subclass `QCryptoBlockInfoLUKS`
# to define a ImageInfoSpecificLUKS
##
@ -332,7 +333,7 @@
# node, annotated with information about that node in relation to its
# parent.
#
# @name: Child name of the root node in the BlockGraphInfo struct, in
# @name: Child name of the root node in the `BlockGraphInfo` struct, in
# its role as the child of some undescribed parent node
#
# @info: Block graph information starting at this node
@ -349,7 +350,7 @@
# @BlockGraphInfo:
#
# Information about all nodes in a block (sub)graph in the form of
# BlockNodeInfo data. The base BlockNodeInfo struct contains the
# `BlockNodeInfo` data. The base `BlockNodeInfo` struct contains the
# information for the (sub)graph's root node.
#
# @children: Array of links to this node's child nodes' information
@ -614,7 +615,7 @@
# @inconsistent: true if this is a persistent bitmap that was
# improperly stored. Implies @persistent to be true; @recording
# and @busy to be false. This bitmap cannot be used. To remove
# it, use @block-dirty-bitmap-remove. (Since 4.0)
# it, use `block-dirty-bitmap-remove`. (Since 4.0)
#
# Since: 1.3
##
@ -709,12 +710,12 @@
# @tray_open: True if the device's tray is open (only present if it
# has a tray)
#
# @io-status: @BlockDeviceIoStatus. Only present if the device
# @io-status: `BlockDeviceIoStatus`. Only present if the device
# supports it and the VM is configured to stop on errors
# (supported device models: virtio-blk, IDE, SCSI except
# scsi-generic)
#
# @inserted: @BlockDeviceInfo describing the device if media is
# @inserted: `BlockDeviceInfo` describing the device if media is
# present
#
# Since: 0.14
@ -761,9 +762,9 @@
##
# @query-block:
#
# Get a list of BlockInfo for all virtual block devices.
# Get a list of `BlockInfo` for all virtual block devices.
#
# Returns: a list of @BlockInfo describing each virtual block device.
# Returns: a list describing each virtual block device.
# Filter nodes that were created implicitly are skipped over.
#
# Since: 0.14
@ -1026,14 +1027,14 @@
# @timed_stats: Statistics specific to the set of previously defined
# intervals of time (Since 2.5)
#
# @rd_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0)
# @rd_latency_histogram: `BlockLatencyHistogramInfo`. (Since 4.0)
#
# @wr_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0)
# @wr_latency_histogram: `BlockLatencyHistogramInfo`. (Since 4.0)
#
# @zone_append_latency_histogram: @BlockLatencyHistogramInfo.
# @zone_append_latency_histogram: `BlockLatencyHistogramInfo`.
# (since 8.1)
#
# @flush_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0)
# @flush_latency_histogram: `BlockLatencyHistogramInfo`. (Since 4.0)
#
# Since: 0.14
##
@ -1134,7 +1135,7 @@
# @qdev: The qdev ID, or if no ID is assigned, the QOM path of the
# block device. (since 3.0)
#
# @stats: A @BlockDeviceStats for the device.
# @stats: A `BlockDeviceStats` for the device.
#
# @driver-specific: Optional driver-specific stats. (Since 4.2)
#
@ -1158,7 +1159,7 @@
##
# @query-blockstats:
#
# Query the @BlockStats for all virtual block devices.
# Query the `BlockStats` for all virtual block devices.
#
# @query-nodes: If true, the command will query all the block nodes
# that have a node name, in a list which will include "parent"
@ -1168,7 +1169,7 @@
# nodes that were created implicitly are skipped over in this
# mode. (Since 2.3)
#
# Returns: A list of @BlockStats for each virtual block devices.
# Returns: A list of statistics for each virtual block device.
#
# Since: 0.14
#
@ -1289,8 +1290,8 @@
# @report: for guest operations, report the error to the guest; for
# jobs, cancel the job
#
# @ignore: ignore the error, only report a QMP event (BLOCK_IO_ERROR
# or BLOCK_JOB_ERROR). The backup, mirror and commit block jobs
# @ignore: ignore the error, only report a QMP event (`BLOCK_IO_ERROR`
# or `BLOCK_JOB_ERROR`). The backup, mirror and commit block jobs
# retry the failing request later and may still complete
# successfully. The stream block job continues to stream and will
# complete with an error.
@ -1323,7 +1324,7 @@
# (since: 2.4)
#
# @bitmap: only copy data described by the dirty bitmap. Behavior on
# completion is determined by the BitmapSyncMode. (since: 4.2)
# completion is determined by the `BitmapSyncMode`. (since: 4.2)
#
# Since: 1.3
##
@ -1440,7 +1441,7 @@
#
# Return information about long-running block device operations.
#
# Returns: a list of @BlockJobInfo for each active block job
# Returns: a list of job info for each active block job
#
# Since: 1.1
##
@ -1530,7 +1531,7 @@
# @overlay: reference to the existing block device that will become
# the overlay of @node, as part of taking the snapshot. It must
# not have a current backing file (this can be achieved by passing
# "backing": null to blockdev-add).
# "backing": null to `blockdev-add`).
#
# Since: 2.5
##
@ -1585,7 +1586,7 @@
# @bitmap: The name of a dirty bitmap to use. Must be present if sync
# is "bitmap" or "incremental". Can be present if sync is "full"
# or "top". Must not be present otherwise.
# (Since 2.4 (drive-backup), 3.1 (blockdev-backup))
# (Since 2.4 (`drive-backup`), 3.1 (`blockdev-backup`))
#
# @bitmap-mode: Specifies the type of data the bitmap should contain
# after the operation concludes. Must be present if a bitmap was
@ -1596,7 +1597,7 @@
#
# @on-source-error: the action to take on an error on the source,
# default 'report'. 'stop' and 'enospc' can only be used if the
# block device supports io-status (see BlockInfo).
# block device supports io-status (see `BlockInfo`).
#
# @on-target-error: the action to take on an error on the target,
# default 'report' (no limitations, since this applies to a
@ -1606,14 +1607,14 @@
# copy-before-write jobs; defaults to break-guest-write. (Since 10.1)
#
# @auto-finalize: When false, this job will wait in a PENDING state
# after it has finished its work, waiting for @job-finalize before
# after it has finished its work, waiting for `job-finalize` before
# making any block graph changes. When true, this job will
# automatically perform its abort or commit actions. Defaults to
# true. (Since 2.12)
#
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
# @job-dismiss. When true, this job will automatically disappear
# `job-dismiss`. When true, this job will automatically disappear
# without user intervention. Defaults to true. (Since 2.12)
#
# @filter-node-name: the node name that should be assigned to the
@ -1719,7 +1720,7 @@
#
# @allow-write-only-overlay: If present, the check whether this
# operation is safe was relaxed so that it can be used to change
# backing file of a destination of a blockdev-mirror. (since 5.0)
# backing file of a destination of a `blockdev-mirror`. (since 5.0)
#
# Since: 2.5
#
@ -1784,7 +1785,7 @@
# If top == base, that is an error. If top has no overlays on top of
# it, or if it is in use by a writer, the job will not be completed by
# itself. The user needs to complete the job with the
# job-complete command after getting the ready event. (Since 2.0)
# `job-complete` command after getting the ready event. (Since 2.0)
#
# If the base image is smaller than top, then the base image will be
# resized to be the same size as top. If top is smaller than the base
@ -1846,14 +1847,14 @@
# autogenerated. (Since: 2.9)
#
# @auto-finalize: When false, this job will wait in a PENDING state
# after it has finished its work, waiting for @job-finalize before
# after it has finished its work, waiting for `job-finalize` before
# making any block graph changes. When true, this job will
# automatically perform its abort or commit actions. Defaults to
# true. (Since 3.1)
#
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
# @job-dismiss. When true, this job will automatically disappear
# `job-dismiss`. When true, this job will automatically disappear
# without user intervention. Defaults to true. (Since 3.1)
#
# Features:
@ -1889,14 +1890,14 @@
# @drive-backup:
#
# Start a point-in-time copy of a block device to a new destination.
# The status of ongoing drive-backup operations can be checked with
# query-block-jobs where the BlockJobInfo.type field has the value
# The status of ongoing `drive-backup` operations can be checked with
# `query-block-jobs` where the `BlockJobInfo`.type field has the value
# 'backup'. The operation can be stopped before it has completed
# using the job-cancel or block-job-cancel command.
# using the `job-cancel` or `block-job-cancel` command.
#
# Features:
#
# @deprecated: This command is deprecated. Use @blockdev-backup
# @deprecated: This command is deprecated. Use `blockdev-backup`
# instead.
#
# Errors:
@ -1920,10 +1921,10 @@
# @blockdev-backup:
#
# Start a point-in-time copy of a block device to a new destination.
# The status of ongoing blockdev-backup operations can be checked with
# query-block-jobs where the BlockJobInfo.type field has the value
# The status of ongoing `blockdev-backup` operations can be checked with
# `query-block-jobs` where the `BlockJobInfo`.type field has the value
# 'backup'. The operation can be stopped before it has completed
# using the job-cancel or block-job-cancel command.
# using the `job-cancel` or `block-job-cancel` command.
#
# Errors:
# - If @device is not a valid block device, DeviceNotFound
@ -1950,8 +1951,6 @@
# @flat: Omit the nested data about backing image ("backing-image"
# key) if true. Default is false (Since 5.0)
#
# Returns: the list of BlockDeviceInfo
#
# Since: 2.0
#
# .. qmp-example::
@ -2026,7 +2025,7 @@
# @XDbgBlockGraphNode:
#
# @id: Block graph node identifier. This @id is generated only for
# x-debug-query-block-graph and does not relate to any other
# `x-debug-query-block-graph` and does not relate to any other
# identifiers in QEMU.
#
# @type: Type of graph node. Can be one of block-backend, block-job
@ -2075,7 +2074,7 @@
##
# @XDbgBlockGraphEdge:
#
# Block Graph edge description for x-debug-query-block-graph.
# Block Graph edge description for `x-debug-query-block-graph`.
#
# @parent: parent id
#
@ -2193,7 +2192,7 @@
#
# @on-source-error: the action to take on an error on the source,
# default 'report'. 'stop' and 'enospc' can only be used if the
# block device supports io-status (see BlockInfo).
# block device supports io-status (see `BlockInfo`).
#
# @on-target-error: the action to take on an error on the target,
# default 'report' (no limitations, since this applies to a
@ -2209,14 +2208,14 @@
# 'background' (Since: 3.0)
#
# @auto-finalize: When false, this job will wait in a PENDING state
# after it has finished its work, waiting for @job-finalize before
# after it has finished its work, waiting for `job-finalize` before
# making any block graph changes. When true, this job will
# automatically perform its abort or commit actions. Defaults to
# true. (Since 3.1)
#
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
# @job-dismiss. When true, this job will automatically disappear
# `job-dismiss`. When true, this job will automatically disappear
# without user intervention. Defaults to true. (Since 3.1)
#
# Since: 1.3
@ -2251,16 +2250,16 @@
# @name: name of the dirty bitmap (must be less than 1024 bytes)
#
# @granularity: the bitmap granularity, default is 64k for
# block-dirty-bitmap-add
# `block-dirty-bitmap-add`
#
# @persistent: the bitmap is persistent, i.e. it will be saved to the
# corresponding block device image file on its close. For now
# only Qcow2 disks support persistent bitmaps. Default is false
# for block-dirty-bitmap-add. (Since: 2.10)
# for `block-dirty-bitmap-add`. (Since: 2.10)
#
# @disabled: the bitmap is created in the disabled state, which means
# that it will not track drive changes. The bitmap may be enabled
# with block-dirty-bitmap-enable. Default is false. (Since: 4.0)
# with `block-dirty-bitmap-enable`. Default is false. (Since: 4.0)
#
# Since: 2.4
##
@ -2290,7 +2289,7 @@
# @target: name of the destination dirty bitmap
#
# @bitmaps: name(s) of the source dirty bitmap(s) at @node and/or
# fully specified BlockDirtyBitmap elements. The latter are
# fully specified `BlockDirtyBitmap` elements. The latter are
# supported since 4.1.
#
# Since: 4.0
@ -2325,7 +2324,7 @@
# @block-dirty-bitmap-remove:
#
# Stop write tracking and remove the dirty bitmap that was created
# with block-dirty-bitmap-add. If the bitmap is persistent, remove it
# with `block-dirty-bitmap-add`. If the bitmap is persistent, remove it
# from its storage too.
#
# Errors:
@ -2464,9 +2463,6 @@
#
# @unstable: This command is meant for debugging.
#
# Returns:
# BlockDirtyBitmapSha256
#
# Errors:
# - If @node is not a valid block device, DeviceNotFound
# - If @name is not found or if hashing has failed, GenericError
@ -2512,7 +2508,7 @@
#
# @on-source-error: the action to take on an error on the source,
# default 'report'. 'stop' and 'enospc' can only be used if the
# block device supports io-status (see BlockInfo).
# block device supports io-status (see `BlockInfo`).
#
# @on-target-error: the action to take on an error on the target,
# default 'report' (no limitations, since this applies to a
@ -2527,14 +2523,14 @@
# 'background' (Since: 3.0)
#
# @auto-finalize: When false, this job will wait in a PENDING state
# after it has finished its work, waiting for @job-finalize before
# after it has finished its work, waiting for `job-finalize` before
# making any block graph changes. When true, this job will
# automatically perform its abort or commit actions. Defaults to
# true. (Since 3.1)
#
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
# @job-dismiss. When true, this job will automatically disappear
# `job-dismiss`. When true, this job will automatically disappear
# without user intervention. Defaults to true. (Since 3.1)
#
# @target-is-zero: Assume the destination reads as all zeroes before
@ -2782,9 +2778,9 @@
# The block streaming operation is performed in the background until
# the entire backing file has been copied. This command returns
# immediately once streaming has started. The status of ongoing block
# streaming operations can be checked with query-block-jobs. The
# streaming operations can be checked with `query-block-jobs`. The
# operation can be stopped before it has completed using the
# job-cancel or block-job-cancel command.
# `job-cancel` or `block-job-cancel` command.
#
# The node that receives the data is called the top image, can be
# located in any part of the chain (but always above the base image;
@ -2803,9 +2799,9 @@
# will be the new backing file.
#
# On successful completion the image file is updated to drop the
# backing file and the BLOCK_JOB_COMPLETED event is emitted.
# backing file and the `BLOCK_JOB_COMPLETED` event is emitted.
#
# In case @device is a filter node, block-stream modifies the first
# In case @device is a filter node, `block-stream` modifies the first
# non-filter overlay node below it to point to the new backing node
# instead of modifying @device itself.
#
@ -2846,7 +2842,7 @@
#
# @on-error: the action to take on an error (default report). 'stop'
# and 'enospc' can only be used if the block device supports
# io-status (see BlockInfo). (Since 1.3)
# io-status (see `BlockInfo`). (Since 1.3)
#
# @filter-node-name: the node name that should be assigned to the
# filter driver that the stream job inserts into the graph above
@ -2854,14 +2850,14 @@
# autogenerated. (Since: 6.0)
#
# @auto-finalize: When false, this job will wait in a PENDING state
# after it has finished its work, waiting for @job-finalize before
# after it has finished its work, waiting for `job-finalize` before
# making any block graph changes. When true, this job will
# automatically perform its abort or commit actions. Defaults to
# true. (Since 3.1)
#
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
# @job-dismiss. When true, this job will automatically disappear
# `job-dismiss`. When true, this job will automatically disappear
# without user intervention. Defaults to true. (Since 3.1)
#
# Errors:
@ -2922,13 +2918,13 @@
# command if no operation is in progress.
#
# The operation will cancel as soon as possible and then emit the
# BLOCK_JOB_CANCELLED event. Before that happens the job is still
# visible when enumerated using query-block-jobs.
# `BLOCK_JOB_CANCELLED` event. Before that happens the job is still
# visible when enumerated using `query-block-jobs`.
#
# Note that if you issue 'block-job-cancel' after 'drive-mirror' has
# indicated (via the event BLOCK_JOB_READY) that the source and
# Note that if you issue `block-job-cancel` after `drive-mirror` has
# indicated (via the event `BLOCK_JOB_READY`) that the source and
# destination are synchronized, then the event triggered by this
# command changes to BLOCK_JOB_COMPLETED, to indicate that the
# command changes to `BLOCK_JOB_COMPLETED`, to indicate that the
# mirroring has ended and the destination now has a point-in-time copy
# tied to the time of the cancellation.
#
@ -2942,7 +2938,7 @@
# values.
#
# @force: If true, and the job has already emitted the event
# BLOCK_JOB_READY, abandon the job immediately (even if it is
# `BLOCK_JOB_READY`, abandon the job immediately (even if it is
# paused) instead of waiting for the destination to complete its
# final synchronization (since 1.3)
#
@ -2965,7 +2961,7 @@
#
# The job will pause as soon as possible, which means transitioning
# into the PAUSED state if it was RUNNING, or into STANDBY if it was
# READY. The corresponding JOB_STATUS_CHANGE event will be emitted.
# READY. The corresponding `JOB_STATUS_CHANGE` event will be emitted.
#
# Cancelling a paused job automatically resumes it.
#
@ -2975,7 +2971,7 @@
#
# Features:
#
# @deprecated: This command is deprecated. Use @job-pause
# @deprecated: This command is deprecated. Use `job-pause`
# instead.
#
# Errors:
@ -3004,7 +3000,7 @@
#
# Features:
#
# @deprecated: This command is deprecated. Use @job-resume
# @deprecated: This command is deprecated. Use `job-resume`
# instead.
#
# Errors:
@ -3025,14 +3021,14 @@
#
# This is supported only for drive mirroring, where it also switches
# the device to write to the target path only. Note that drive
# mirroring includes drive-mirror, blockdev-mirror and block-commit
# mirroring includes `drive-mirror`, `blockdev-mirror` and `block-commit`
# job (only in case of "active commit", when the node being commited
# is used by the guest). The ability to complete is signaled with a
# BLOCK_JOB_READY event.
# `BLOCK_JOB_READY` event.
#
# This command completes an active background block operation
# synchronously. The ordering of this command's return with the
# BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error
# `BLOCK_JOB_COMPLETED` event is not defined. Note that if an I/O error
# occurs during the processing of this command: 1) the command itself
# will fail; 2) the error will be processed according to the
# rerror/werror arguments that were specified when starting the
@ -3044,7 +3040,7 @@
#
# Features:
#
# @deprecated: This command is deprecated. Use @job-complete
# @deprecated: This command is deprecated. Use `job-complete`
# instead.
#
# Errors:
@ -3063,21 +3059,21 @@
# Deletes a job that is in the CONCLUDED state. This command only
# needs to be run explicitly for jobs that don't have automatic
# dismiss enabled. In turn, automatic dismiss may be enabled only
# for jobs that have @auto-dismiss option, which are drive-backup,
# blockdev-backup, drive-mirror, blockdev-mirror, block-commit and
# block-stream. @auto-dismiss is enabled by default for these
# for jobs that have @auto-dismiss option, which are `drive-backup`,
# `blockdev-backup`, `drive-mirror`, `blockdev-mirror`, `block-commit` and
# `block-stream`. @auto-dismiss is enabled by default for these
# jobs.
#
# This command will refuse to operate on any job that has not yet
# reached its terminal state, CONCLUDED. For jobs that make use of
# the BLOCK_JOB_READY event, job-cancel, block-job-cancel or
# job-complete will still need to be used as appropriate.
# the `BLOCK_JOB_READY` event, `job-cancel`, `block-job-cancel` or
# `job-complete` will still need to be used as appropriate.
#
# @id: The job identifier.
#
# Features:
#
# @deprecated: This command is deprecated. Use @job-dismiss
# @deprecated: This command is deprecated. Use `job-dismiss`
# instead.
#
# Since: 2.12
@ -3105,7 +3101,7 @@
#
# Features:
#
# @deprecated: This command is deprecated. Use @job-finalize
# @deprecated: This command is deprecated. Use `job-finalize`
# instead.
#
# Since: 2.12
@ -3177,7 +3173,7 @@
# @on: Enabled
#
# @unmap: Enabled and even try to unmap blocks if possible. This
# requires also that @BlockdevDiscardOptions is set to unmap for
# requires also that `BlockdevDiscardOptions` is set to unmap for
# this device.
#
# Since: 2.1
@ -4719,7 +4715,7 @@
# @driver: block driver name
#
# @node-name: the node name of the new node. This option is required
# on the top level of blockdev-add. Valid node names start with
# on the top level of `blockdev-add`. Valid node names start with
# an alphabetic character and may contain only alphanumeric
# characters, '-', '.' and '_'. Their maximum length is 31
# characters. (Since 2.0)
@ -4923,7 +4919,7 @@
# cancelled.
#
# The command receives a list of block devices to reopen. For each
# one of them, the top-level @node-name option (from BlockdevOptions)
# one of them, the top-level @node-name option (from `BlockdevOptions`)
# must be specified and is used to select the block device to be
# reopened. Other @node-name options must be either omitted or set to
# the current name of the appropriate node. This command won't change
@ -4932,7 +4928,7 @@
# In the case of options that refer to child nodes, the behavior of
# this command depends on the value:
#
# 1) A set of options (BlockdevOptions): the child is reopened with
# 1) A set of options (`BlockdevOptions`): the child is reopened with
# the specified set of options.
#
# 2) A reference to the current child: the child is reopened using
@ -4946,7 +4942,7 @@
# Options (1) and (2) are supported in all cases. Option (3) is
# supported for @file and @backing, and option (4) for @backing only.
#
# Unlike with blockdev-add, the @backing option must always be present
# Unlike with `blockdev-add`, the @backing option must always be present
# unless the node being reopened does not have a backing file and its
# image does not have a default backing file name as part of its
# metadata.
@ -4960,7 +4956,7 @@
##
# @blockdev-del:
#
# Deletes a block device that has been added using blockdev-add. The
# Deletes a block device that has been added using `blockdev-add`. The
# command will fail if the node is attached to a device or is
# otherwise being used.
#
@ -5515,7 +5511,7 @@
# @blockdev-create:
#
# Starts a job to create an image format on a given node. The job is
# automatically finalized, but a manual job-dismiss is required.
# automatically finalized, but a manual `job-dismiss` is required.
#
# @job-id: Identifier for the newly created job.
#
@ -5575,7 +5571,7 @@
#
# Starts a job to amend format specific options of an existing open
# block device. The job is automatically finalized, but a manual
# job-dismiss is required.
# `job-dismiss` is required.
#
# @job-id: Identifier for the newly created job.
#
@ -5644,10 +5640,10 @@
#
# @fatal: if set, the image is marked corrupt and therefore unusable
# 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 BLOCK_IO_ERROR event.
# .. note:: If action is "stop", a `STOP` event will eventually follow
# the `BLOCK_IO_ERROR` event.
#
# .. qmp-example::
#
@ -5688,15 +5684,15 @@
#
# @nospace: true if I/O error was caused due to a no-space condition.
# This key is only present if query-block's io-status is present,
# please see query-block documentation for more information
# please see `query-block` documentation for more information
# (since: 2.2)
#
# @reason: human readable string describing the error cause. (This
# field is a debugging aid for humans, it should not be parsed by
# applications) (since: 2.2)
#
# .. note:: If action is "stop", a STOP event will eventually follow
# the BLOCK_IO_ERROR event.
# .. note:: If action is "stop", a `STOP` event will eventually follow
# the `BLOCK_IO_ERROR` event.
#
# .. note:: This event is rate-limited.
#
@ -5838,7 +5834,7 @@
# @speed: rate limit, bytes per second
#
# .. note:: The "ready to complete" status is always reset by a
# @BLOCK_JOB_ERROR event.
# `BLOCK_JOB_ERROR` event.
#
# Since: 1.3
#
@ -5860,7 +5856,7 @@
# @BLOCK_JOB_PENDING:
#
# Emitted when a block job is awaiting explicit authorization to
# finalize graph changes via @job-finalize. If this job is part
# finalize graph changes via `job-finalize`. If this job is part
# of a transaction, it will not emit this event until the transaction
# has converged first.
#
@ -5909,7 +5905,7 @@
# configured write threshold. For thin-provisioned devices, this
# means the device should be extended to avoid pausing for disk
# exhaustion. The event is one shot. Once triggered, it needs to be
# re-registered with another block-set-write-threshold command.
# re-registered with another `block-set-write-threshold` command.
#
# @node-name: graph node name on which the threshold was exceeded.
#
@ -5980,7 +5976,7 @@
#
# TODO: Removing children from a quorum node means introducing
# gaps in the child indices. This cannot be represented in the
# 'children' list of BlockdevOptionsQuorum, as returned by
# 'children' list of `BlockdevOptionsQuorum`, as returned by
# .bdrv_refresh_filename().
#
# Since: 2.7
@ -6193,7 +6189,7 @@
# Synchronously delete an internal snapshot of a block device, when
# the format of the image used support it. The snapshot is identified
# by name or id or both. One of the name or id is required. Return
# SnapshotInfo for the successfully deleted snapshot.
# `SnapshotInfo` for the successfully deleted snapshot.
#
# @device: the device name or node-name of a root node to delete the
# snapshot from
@ -6202,9 +6198,6 @@
#
# @name: optional the snapshot's name to be deleted
#
# Returns:
# SnapshotInfo
#
# Errors:
# - If @device is not a valid block device, GenericError
# - If snapshot not found, GenericError

41
qapi/block-export.json
View File

@ -2,7 +2,8 @@
# vim: filetype=python
##
# == Block device exports
# Block device exports
# ====================
##
{ 'include': 'sockets.json' }
@ -37,9 +38,9 @@
##
# @NbdServerOptions:
#
# Keep this type consistent with the NbdServerOptionsLegacy type. The
# only intended difference is using SocketAddress instead of
# SocketAddressLegacy.
# Keep this type consistent with the `NbdServerOptionsLegacy` type. The
# only intended difference is using `SocketAddress` instead of
# `SocketAddressLegacy`.
#
# @addr: Address on which to listen (since 4.2).
##
@ -50,9 +51,9 @@
##
# @NbdServerOptionsLegacy:
#
# Keep this type consistent with the NbdServerOptions type. The only
# intended difference is using SocketAddressLegacy instead of
# SocketAddress.
# Keep this type consistent with the `NbdServerOptions` type. The only
# intended difference is using `SocketAddressLegacy` instead of
# `SocketAddress`.
#
# @addr: Address on which to listen (since 1.3).
##
@ -64,7 +65,7 @@
# @nbd-server-start:
#
# Start an NBD server listening on the given host and port. Block
# devices can then be exported using @nbd-server-add. The NBD server
# devices can then be exported using `nbd-server-add`. The NBD server
# will present them as named exports; for example, another QEMU
# instance could refer to them as "nbd:HOST:PORT:exportname=NAME".
#
@ -80,8 +81,8 @@
##
# @BlockExportOptionsNbdBase:
#
# An NBD block export (common options shared between nbd-server-add
# and the NBD branch of block-export-add).
# An NBD block export (common options shared between `nbd-server-add`
# and the NBD branch of `block-export-add`).
#
# @name: Export name. If unspecified, the @device parameter is used
# as the export name. (Since 2.12)
@ -98,7 +99,7 @@
# @BlockExportOptionsNbd:
#
# An NBD block export (distinct options used in the NBD branch of
# block-export-add).
# `block-export-add`).
#
# @bitmaps: Also export each of the named dirty bitmaps reachable from
# @device, so the NBD client can use NBD_OPT_SET_META_CONTEXT with
@ -124,7 +125,7 @@
# A vhost-user-blk block export.
#
# @addr: The vhost-user socket on which to listen. Both 'unix' and
# 'fd' SocketAddress types are supported. Passed fds must be UNIX
# 'fd' `SocketAddress` types are supported. Passed fds must be UNIX
# domain sockets.
#
# @logical-block-size: Logical block size in bytes. Defaults to 512
@ -216,7 +217,7 @@
##
# @NbdServerAddOptions:
#
# An NBD block export, per legacy nbd-server-add command.
# An NBD block export, per legacy `nbd-server-add` command.
#
# @device: The device name or node name of the node to be exported
#
@ -245,7 +246,7 @@
#
# Features:
#
# @deprecated: This command is deprecated. Use @block-export-add
# @deprecated: This command is deprecated. Use `block-export-add`
# instead.
#
# Errors:
@ -288,12 +289,12 @@
#
# @name: Block export id.
#
# @mode: Mode of command operation. See @BlockExportRemoveMode
# @mode: Mode of command operation. See `BlockExportRemoveMode`
# description. Default is 'safe'.
#
# Features:
#
# @deprecated: This command is deprecated. Use @block-export-del
# @deprecated: This command is deprecated. Use `block-export-del`
# instead.
#
# Errors:
@ -312,7 +313,7 @@
# @nbd-server-stop:
#
# Stop QEMU's embedded NBD server, and unregister all devices
# previously added via @nbd-server-add.
# previously added via `nbd-server-add`.
#
# Since: 1.3
##
@ -421,7 +422,7 @@
#
# @id: Block export id.
#
# @mode: Mode of command operation. See @BlockExportRemoveMode
# @mode: Mode of command operation. See `BlockExportRemoveMode`
# description. Default is 'safe'.
#
# Errors:
@ -459,7 +460,7 @@
# @node-name: The node name of the block node that is exported
#
# @shutting-down: True if the export is shutting down (e.g. after a
# block-export-del command, but before the shutdown has completed)
# `block-export-del` command, but before the shutdown has completed)
#
# Since: 5.2
##
@ -472,7 +473,7 @@
##
# @query-block-exports:
#
# Returns: A list of BlockExportInfo describing all block exports
# Returns: A list describing all block exports
#
# Since: 5.2
##

23
qapi/block.json
View File

@ -2,13 +2,16 @@
# vim: filetype=python
##
# = Block devices
# *************
# Block devices
# *************
##
{ 'include': 'block-core.json' }
##
# == Additional block stuff (VM related)
# Additional block stuff (VM related)
# ===================================
##
##
@ -86,7 +89,7 @@
# Return a list of information about each persistent reservation
# manager.
#
# Returns: a list of @PRManagerInfo for each persistent reservation
# Returns: a list of manager info for each persistent reservation
# manager
#
# Since: 3.0
@ -137,7 +140,7 @@
#
# If the tray was already open before, this will be a no-op.
#
# Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There
# Once the tray opens, a `DEVICE_TRAY_MOVED` event is emitted. There
# are cases in which no such event will be generated, these include:
#
# - if the guest has locked the tray, @force is false and the guest
@ -296,7 +299,7 @@
# @BlockdevChangeReadOnlyMode:
#
# Specifies the new read-only mode of a block device subject to the
# @blockdev-change-medium command.
# `blockdev-change-medium` command.
#
# @retain: Retains the current read-only mode
#
@ -314,9 +317,9 @@
#
# Changes the medium inserted into a block device by ejecting the
# current medium and loading a new image file which is inserted as the
# new medium (this command combines blockdev-open-tray,
# blockdev-remove-medium, blockdev-insert-medium and
# blockdev-close-tray).
# new medium (this command combines `blockdev-open-tray`,
# `blockdev-remove-medium`, `blockdev-insert-medium` and
# `blockdev-close-tray`).
#
# @device: Block device name
#
@ -331,7 +334,7 @@
# to 'retain'
#
# @force: if false (the default), an eject request through
# blockdev-open-tray will be sent to the guest if it has locked
# `blockdev-open-tray` will be sent to the guest if it has locked
# the tray (and the tray will not be opened immediately); if true,
# the tray will be opened regardless of whether it is locked.
# (since 7.1)
@ -519,7 +522,7 @@
# @id: The name or QOM path of the guest device.
#
# @boundaries: list of interval boundary values (see description in
# BlockLatencyHistogramInfo definition). If specified, all
# `BlockLatencyHistogramInfo` definition). If specified, all
# latency histograms are removed, and empty ones created for all
# io types with intervals corresponding to @boundaries (except for
# io types, for which specific boundaries are set through the

12
qapi/char.json
View File

@ -3,7 +3,9 @@
#
##
# = Character devices
# *****************
# Character devices
# *****************
##
{ 'include': 'sockets.json' }
@ -36,8 +38,6 @@
#
# Return information about current character devices.
#
# Returns: a list of @ChardevInfo
#
# Since: 0.14
#
# .. qmp-example::
@ -82,8 +82,6 @@
#
# Return information about character device backends.
#
# Returns: a list of @ChardevBackendInfo
#
# Since: 2.0
#
# .. qmp-example::
@ -772,8 +770,6 @@
#
# @backend: backend type and parameters
#
# Returns: ChardevReturn.
#
# Since: 1.4
#
# .. qmp-example::
@ -812,8 +808,6 @@
#
# @backend: new backend type and parameters
#
# Returns: ChardevReturn.
#
# Since: 2.10
#
# .. qmp-example::

4
qapi/common.json
View File

@ -2,7 +2,9 @@
# vim: filetype=python
##
# = Common data types
# *****************
# Common data types
# *****************
##
##

4
qapi/compat.json
View File

@ -2,7 +2,9 @@
# vim: filetype=python
##
# = Compatibility policy
# ********************
# Compatibility policy
# ********************
##
##

20
qapi/control.json
View File

@ -3,7 +3,9 @@
#
##
# = QMP monitor control
# *******************
# QMP monitor control
# *******************
##
##
@ -11,7 +13,7 @@
#
# Enable QMP capabilities.
#
# @enable: An optional list of QMPCapability values to enable. The
# @enable: An optional list of `QMPCapability` values to enable. The
# client must not enable any capability that is not mentioned in
# the QMP greeting message. If the field is not provided, it
# means no QMP capabilities will be enabled. (since 2.12)
@ -93,8 +95,7 @@
#
# Return the current version of QEMU.
#
# Returns: A @VersionInfo object describing the current version of
# QEMU.
# Returns: An object describing the current version of QEMU.
#
# Since: 0.14
#
@ -131,7 +132,7 @@
#
# Return a list of supported QMP commands by this server
#
# Returns: A list of @CommandInfo for all supported commands
# Returns: A list of all supported commands
#
# Since: 0.14
#
@ -158,10 +159,11 @@
##
# @quit:
#
# This command will cause the QEMU process to exit gracefully. While
# every attempt is made to send the QMP response before terminating,
# this is not guaranteed. When using this interface, a premature EOF
# would not be unexpected.
# Request graceful QEMU process termination.
#
# While every attempt is made to send the QMP response before
# terminating, this is not guaranteed. When using this interface, a
# premature EOF would not be unexpected.
#
# Since: 0.14
#

8
qapi/crypto.json
View File

@ -3,7 +3,9 @@
#
##
# = Cryptography
# ************
# Cryptography
# ************
##
##
@ -589,9 +591,9 @@
#
# Specific parameters for RSA algorithm.
#
# @hash-alg: QCryptoHashAlgo
# @hash-alg: `QCryptoHashAlgo`
#
# @padding-alg: QCryptoRSAPaddingAlgo
# @padding-alg: `QCryptoRSAPaddingAlgo`
#
# Since: 7.1
##

6
qapi/cryptodev.json
View File

@ -5,7 +5,9 @@
# See the COPYING file in the top-level directory.
##
# = Cryptography devices
# ********************
# Cryptography devices
# ********************
##
##
@ -96,8 +98,6 @@
#
# Return information about current crypto devices.
#
# Returns: a list of @QCryptodevInfo
#
# Since: 8.0
##
{ 'command': 'query-cryptodev', 'returns': ['QCryptodevInfo']}

4
qapi/cxl.json
View File

@ -2,7 +2,9 @@
# vim: filetype=python
##
# = CXL devices
# ***********
# CXL devices
# ***********
##
##

19
qapi/dump.json
View File

@ -5,7 +5,9 @@
# See the COPYING file in the top-level directory.
##
# = Dump guest memory
# *****************
# Dump guest memory
# *****************
##
##
@ -110,7 +112,7 @@
#
# Describe the status of a long-running background guest memory dump.
#
# @none: no dump-guest-memory has started yet.
# @none: no `dump-guest-memory` has started yet.
#
# @active: there is one dump running in background.
#
@ -126,9 +128,9 @@
##
# @DumpQueryResult:
#
# The result format for 'query-dump'.
# The result format for `query-dump`.
#
# @status: enum of @DumpStatus, which shows current dump status
# @status: enum of `DumpStatus`, which shows current dump status
#
# @completed: bytes written in latest dump (uncompressed)
#
@ -146,7 +148,7 @@
#
# Query latest dump status.
#
# Returns: A @DumpStatus object showing the dump status.
# Returns: An object showing the dump status.
#
# Since: 2.6
#
@ -184,7 +186,7 @@
##
# @DumpGuestMemoryCapability:
#
# @formats: the available formats for dump-guest-memory
# @formats: the available formats for `dump-guest-memory`
#
# Since: 2.0
##
@ -195,10 +197,9 @@
##
# @query-dump-guest-memory-capability:
#
# Return the available formats for dump-guest-memory
# Return the available formats for `dump-guest-memory`
#
# Returns: A @DumpGuestMemoryCapability object listing available
# formats for dump-guest-memory
# Returns: An object listing available formats for `dump-guest-memory`
#
# Since: 2.0
#

6
qapi/ebpf.json
View File

@ -5,7 +5,9 @@
# See the COPYING file in the top-level directory.
##
# = eBPF Objects
# ************
# eBPF Objects
# ************
#
# eBPF object is an ELF binary that contains the eBPF program and eBPF
# map description(BTF). Overall, eBPF object should contain the
@ -32,7 +34,7 @@
##
# @EbpfProgramID:
#
# The eBPF programs that can be gotten with request-ebpf.
# The eBPF programs that can be gotten with `request-ebpf`.
#
# @rss: Receive side scaling, technology that allows steering traffic
# between queues by calculation hash. Users may set up

4
qapi/error.json
View File

@ -2,7 +2,9 @@
# vim: filetype=python
##
# = QMP errors
# **********
# QMP errors
# **********
##
##

34
qapi/introspect.json
View File

@ -10,17 +10,19 @@
# See the COPYING file in the top-level directory.
##
# = QMP introspection
# *****************
# QMP introspection
# *****************
##
##
# @query-qmp-schema:
#
# Command query-qmp-schema exposes the QMP wire ABI as an array of
# SchemaInfo. This lets QMP clients figure out what commands and
# Command `query-qmp-schema` exposes the QMP wire ABI as an array of
# `SchemaInfo`. This lets QMP clients figure out what commands and
# events are available in this QEMU, and their parameters and results.
#
# However, the SchemaInfo can't reflect all the rules and restrictions
# However, the `SchemaInfo` can't reflect all the rules and restrictions
# that apply to QMP. It's interface introspection (figuring out
# what's there), not interface specification. The specification is in
# the QAPI schema.
@ -34,10 +36,10 @@
# string into a specific enum or from one specific type into an
# alternate that includes the original type alongside something else.
#
# Returns: array of @SchemaInfo, where each element describes an
# entity in the ABI: command, event, type, ...
# Returns: an array where each element describes an entity in the ABI:
# command, event, type, ...
#
# The order of the various SchemaInfo is unspecified; however, all
# The order of the various elements is unspecified; however, all
# names are guaranteed to be unique (no name will be duplicated
# with different meta-types).
#
@ -54,7 +56,7 @@
##
# @SchemaMetaType:
#
# This is a @SchemaInfo's meta type, i.e. the kind of entity it
# This is a `SchemaInfo`'s meta type, i.e. the kind of entity it
# describes.
#
# @builtin: a predefined type such as 'int' or 'bool'.
@ -80,7 +82,7 @@
##
# @SchemaInfo:
#
# @name: the entity's name, inherited from @base. The SchemaInfo is
# @name: the entity's name, inherited from @base. The `SchemaInfo` is
# always referenced by this name. Commands and events have the
# name defined in the QAPI schema. Unlike command and event
# names, type names are not part of the wire ABI. Consequently,
@ -111,7 +113,7 @@
##
# @SchemaInfoBuiltin:
#
# Additional SchemaInfo members for meta-type 'builtin'.
# Additional `SchemaInfo` members for meta-type 'builtin'.
#
# @json-type: the JSON type used for this type on the wire.
#
@ -152,7 +154,7 @@
##
# @SchemaInfoEnum:
#
# Additional SchemaInfo members for meta-type 'enum'.
# Additional `SchemaInfo` members for meta-type 'enum'.
#
# @members: the enum type's members, in no particular order.
# (since 6.2)
@ -192,7 +194,7 @@
##
# @SchemaInfoArray:
#
# Additional SchemaInfo members for meta-type 'array'.
# Additional `SchemaInfo` members for meta-type 'array'.
#
# @element-type: the array type's element type.
#
@ -206,7 +208,7 @@
##
# @SchemaInfoObject:
#
# Additional SchemaInfo members for meta-type 'object'.
# Additional `SchemaInfo` members for meta-type 'object'.
#
# @members: the object type's (non-variant) members, in no particular
# order.
@ -271,7 +273,7 @@
##
# @SchemaInfoAlternate:
#
# Additional SchemaInfo members for meta-type 'alternate'.
# Additional `SchemaInfo` members for meta-type 'alternate'.
#
# @members: the alternate type's members, in no particular order. The
# members' wire encoding is distinct, see
@ -299,7 +301,7 @@
##
# @SchemaInfoCommand:
#
# Additional SchemaInfo members for meta-type 'command'.
# Additional `SchemaInfo` members for meta-type 'command'.
#
# @arg-type: the name of the object type that provides the command's
# parameters.
@ -321,7 +323,7 @@
##
# @SchemaInfoEvent:
#
# Additional SchemaInfo members for meta-type 'event'.
# Additional `SchemaInfo` members for meta-type 'event'.
#
# @arg-type: the name of the object type that provides the event's
# parameters.

62
qapi/job.json
View File

@ -2,7 +2,9 @@
# vim: filetype=python
##
# = Background jobs
# ***************
# Background jobs
# ***************
##
##
@ -10,26 +12,26 @@
#
# Type of a background job.
#
# @commit: block commit job type, see "block-commit"
# @commit: block commit job type, see `block-commit`
#
# @stream: block stream job type, see "block-stream"
# @stream: block stream job type, see `block-stream`
#
# @mirror: drive mirror job type, see "drive-mirror"
# @mirror: drive mirror job type, see `drive-mirror`
#
# @backup: drive backup job type, see "drive-backup"
# @backup: drive backup job type, see `drive-backup`
#
# @create: image creation job type, see "blockdev-create" (since 3.0)
# @create: image creation job type, see `blockdev-create` (since 3.0)
#
# @amend: image options amend job type, see "x-blockdev-amend"
# @amend: image options amend job type, see `x-blockdev-amend`
# (since 5.1)
#
# @snapshot-load: snapshot load job type, see "snapshot-load"
# @snapshot-load: snapshot load job type, see `snapshot-load`
# (since 6.0)
#
# @snapshot-save: snapshot save job type, see "snapshot-save"
# @snapshot-save: snapshot save job type, see `snapshot-save`
# (since 6.0)
#
# @snapshot-delete: snapshot delete job type, see "snapshot-delete"
# @snapshot-delete: snapshot delete job type, see `snapshot-delete`
# (since 6.0)
#
# Since: 1.7
@ -65,7 +67,7 @@
#
# @pending: The job has finished its work, but has finalization steps
# that it needs to make prior to completing. These changes will
# require manual intervention via @job-finalize if auto-finalize
# require manual intervention via `job-finalize` if auto-finalize
# was set to false. These pending changes may still fail.
#
# @aborting: The job is in the process of being aborted, and will
@ -75,7 +77,7 @@
#
# @concluded: The job has finished all work. If auto-dismiss was set
# to false, the job will remain in this state until it is
# dismissed via @job-dismiss.
# dismissed via `job-dismiss`.
#
# @null: The job is in the process of being dismantled. This state
# should not ever be visible externally.
@ -91,21 +93,21 @@
#
# Represents command verbs that can be applied to a job.
#
# @cancel: see @job-cancel
# @cancel: see `job-cancel`
#
# @pause: see @job-pause
# @pause: see `job-pause`
#
# @resume: see @job-resume
# @resume: see `job-resume`
#
# @set-speed: see @block-job-set-speed
# @set-speed: see `block-job-set-speed`
#
# @complete: see @job-complete
# @complete: see `job-complete`
#
# @dismiss: see @job-dismiss
# @dismiss: see `job-dismiss`
#
# @finalize: see @job-finalize
# @finalize: see `job-finalize`
#
# @change: see @block-job-change (since 8.2)
# @change: see `block-job-change` (since 8.2)
#
# Since: 2.12
##
@ -138,7 +140,7 @@
#
# The job will pause as soon as possible, which means transitioning
# into the PAUSED state if it was RUNNING, or into STANDBY if it was
# READY. The corresponding JOB_STATUS_CHANGE event will be emitted.
# READY. The corresponding `JOB_STATUS_CHANGE` event will be emitted.
#
# Cancelling a paused job automatically resumes it.
#
@ -173,7 +175,7 @@
# cancellation.
#
# The job will cancel as soon as possible and then emit a
# JOB_STATUS_CHANGE event. Usually, the status will change to
# `JOB_STATUS_CHANGE` event. Usually, the status will change to
# ABORTING, but it is possible that a job successfully completes (e.g.
# because it was almost done and there was no opportunity to cancel
# earlier than completing the job) and transitions to PENDING instead.
@ -192,14 +194,14 @@
#
# This is supported only for drive mirroring, where it also switches
# the device to write to the target path only. Note that drive
# mirroring includes drive-mirror, blockdev-mirror and block-commit
# mirroring includes `drive-mirror`, `blockdev-mirror` and `block-commit`
# job (only in case of "active commit", when the node being commited
# is used by the guest). The ability to complete is signaled with a
# BLOCK_JOB_READY event.
# `BLOCK_JOB_READY` event.
#
# This command completes an active background block operation
# synchronously. The ordering of this command's return with the
# BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error
# `BLOCK_JOB_COMPLETED` event is not defined. Note that if an I/O error
# occurs during the processing of this command: 1) the command itself
# will fail; 2) the error will be processed according to the
# rerror/werror arguments that were specified when starting the
@ -217,14 +219,14 @@
# Deletes a job that is in the CONCLUDED state. This command only
# needs to be run explicitly for jobs that don't have automatic
# dismiss enabled. In turn, automatic dismiss may be enabled only
# for jobs that have @auto-dismiss option, which are drive-backup,
# blockdev-backup, drive-mirror, blockdev-mirror, block-commit and
# block-stream. @auto-dismiss is enabled by default for these
# for jobs that have @auto-dismiss option, which are `drive-backup`,
# `blockdev-backup`, `drive-mirror`, `blockdev-mirror`, `block-commit` and
# `block-stream`. @auto-dismiss is enabled by default for these
# jobs.
#
# This command will refuse to operate on any job that has not yet
# reached its terminal state, CONCLUDED. For jobs that make use of
# the JOB_READY event, job-cancel or job-complete will still need to
# the JOB_READY event, `job-cancel` or `job-complete` will still need to
# be used as appropriate.
#
# @id: The job identifier.
@ -295,7 +297,7 @@
#
# Return information about jobs.
#
# Returns: a list with a @JobInfo for each active job
# Returns: a list with info for each active job
#
# Since: 3.0
##

24
qapi/machine-common.json
View File

@ -5,7 +5,9 @@
# See the COPYING file in the top-level directory.
##
# = Common machine types
# ********************
# Common machine types
# ********************
##
##
@ -26,29 +28,29 @@
#
# @thread: thread level, which would also be called SMT level or
# logical processor level. The @threads option in
# SMPConfiguration is used to configure the topology of this
# `SMPConfiguration` is used to configure the topology of this
# level.
#
# @core: core level. The @cores option in SMPConfiguration is used
# @core: core level. The @cores option in `SMPConfiguration` is used
# to configure the topology of this level.
#
# @module: module level. The @modules option in SMPConfiguration is
# @module: module level. The @modules option in `SMPConfiguration` is
# used to configure the topology of this level.
#
# @cluster: cluster level. The @clusters option in SMPConfiguration
# @cluster: cluster level. The @clusters option in `SMPConfiguration`
# is used to configure the topology of this level.
#
# @die: die level. The @dies option in SMPConfiguration is used to
# @die: die level. The @dies option in `SMPConfiguration` is used to
# configure the topology of this level.
#
# @socket: socket level, which would also be called package level.
# The @sockets option in SMPConfiguration is used to configure
# The @sockets option in `SMPConfiguration` is used to configure
# the topology of this level.
#
# @book: book level. The @books option in SMPConfiguration is used
# @book: book level. The @books option in `SMPConfiguration` is used
# to configure the topology of this level.
#
# @drawer: drawer level. The @drawers option in SMPConfiguration is
# @drawer: drawer level. The @drawers option in `SMPConfiguration` is
# used to configure the topology of this level.
#
# @default: default level. Some architectures will have default
@ -102,9 +104,9 @@
##
# @SmpCachePropertiesWrapper:
#
# List wrapper of SmpCacheProperties.
# List wrapper of `SmpCacheProperties`.
#
# @caches: the list of SmpCacheProperties.
# @caches: the list of `SmpCacheProperties`.
#
# Since 9.2
##

110
qapi/machine.json
View File

@ -5,7 +5,9 @@
# See the COPYING file in the top-level directory.
##
# = Machines
# ********
# Machines
# ********
##
{ 'include': 'common.json' }
@ -101,8 +103,6 @@
#
# Return information about all virtual CPUs.
#
# Returns: list of @CpuInfoFast
#
# Since: 2.12
#
# .. qmp-example::
@ -188,7 +188,7 @@
# @acpi: machine type supports ACPI (since 8.0)
#
# @compat-props: The machine type's compatibility properties. Only
# present when query-machines argument @compat-props is true.
# present when `query-machines` argument @compat-props is true.
# (since 9.1)
#
# Features:
@ -218,8 +218,6 @@
#
# @unstable: Argument @compat-props is experimental.
#
# Returns: a list of MachineInfo
#
# Since: 1.2
#
# .. qmp-example::
@ -268,8 +266,6 @@
#
# Return information on the current virtual machine.
#
# Returns: CurrentMachineParams
#
# Since: 4.0
##
{ 'command': 'query-current-machine', 'returns': 'CurrentMachineParams' }
@ -291,8 +287,6 @@
#
# Return information about the target for this QEMU
#
# Returns: QemuTargetInfo
#
# Since: 1.2
##
{ 'command': 'query-target', 'returns': 'QemuTargetInfo' }
@ -316,8 +310,6 @@
#
# Query the guest UUID information.
#
# Returns: The @UuidInfo for the guest
#
# Since: 0.14
#
# .. qmp-example::
@ -385,7 +377,7 @@
#
# Wake up guest from suspend. If the guest has wake-up from suspend
# support enabled (wakeup-suspend-support flag from
# query-current-machine), wake-up guest from suspend if the guest is
# `query-current-machine`), wake-up guest from suspend if the guest is
# in SUSPENDED state. Return an error otherwise.
#
# Since: 1.1
@ -469,8 +461,6 @@
#
# Return information about KVM acceleration
#
# Returns: @KvmInfo
#
# Since: 0.14
#
# .. qmp-example::
@ -599,7 +589,7 @@
#
# List of CXL Fixed Memory Windows.
#
# @cxl-fmw: List of CXLFixedMemoryWindowOptions
# @cxl-fmw: List of `CXLFixedMemoryWindowOptions`
#
# Since: 7.1
##
@ -654,10 +644,10 @@
##
# @NumaCpuOptions:
#
# Option "-numa cpu" overrides default cpu to node mapping. It
# accepts the same set of cpu properties as returned by
# query-hotpluggable-cpus[].props, where node-id could be used to
# override default node mapping.
# Option "-numa cpu" overrides default cpu to node mapping. It accepts
# the same set of cpu properties as returned by
# `query-hotpluggable-cpus[].props <query-hotpluggable-cpus>`, where
# node-id could be used to override default node mapping.
#
# Since: 2.10
##
@ -671,7 +661,7 @@
# The memory hierarchy in the System Locality Latency and Bandwidth
# Information Structure of HMAT (Heterogeneous Memory Attribute Table)
#
# For more information about @HmatLBMemoryHierarchy, see chapter
# For more information about `HmatLBMemoryHierarchy`, see chapter
# 5.2.27.4: Table 5-146: Field "Flags" of ACPI 6.3 spec.
#
# @memory: the structure represents the memory performance
@ -693,7 +683,7 @@
# Data type in the System Locality Latency and Bandwidth Information
# Structure of HMAT (Heterogeneous Memory Attribute Table)
#
# For more information about @HmatLBDataType, see chapter 5.2.27.4:
# For more information about `HmatLBDataType`, see chapter 5.2.27.4:
# Table 5-146: Field "Data Type" of ACPI 6.3 spec.
#
# @access-latency: access latency (nanoseconds)
@ -720,7 +710,7 @@
# Set the system locality latency and bandwidth information between
# Initiator and Target proximity Domains.
#
# For more information about @NumaHmatLBOptions, see chapter 5.2.27.4:
# For more information about `NumaHmatLBOptions`, see chapter 5.2.27.4:
# Table 5-146 of ACPI 6.3 spec.
#
# @initiator: the Initiator Proximity Domain.
@ -756,7 +746,7 @@
# Cache associativity in the Memory Side Cache Information Structure
# of HMAT
#
# For more information of @HmatCacheAssociativity, see chapter
# For more information of `HmatCacheAssociativity`, see chapter
# 5.2.27.5: Table 5-147 of ACPI 6.3 spec.
#
# @none: None (no memory side cache in this proximity domain, or cache
@ -777,7 +767,7 @@
# Cache write policy in the Memory Side Cache Information Structure of
# HMAT
#
# For more information of @HmatCacheWritePolicy, see chapter 5.2.27.5:
# For more information of `HmatCacheWritePolicy`, see chapter 5.2.27.5:
# Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
#
# @none: None (no memory side cache in this proximity domain, or cache
@ -797,7 +787,7 @@
#
# Set the memory side cache information for a given memory domain.
#
# For more information of @NumaHmatCacheOptions, see chapter 5.2.27.5:
# For more information of `NumaHmatCacheOptions`, see chapter 5.2.27.5:
# Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
#
# @node-id: the memory proximity domain to which the memory belongs.
@ -932,8 +922,6 @@
#
# Return information for all memory backends.
#
# Returns: a list of @Memdev.
#
# Since: 2.1
#
# .. qmp-example::
@ -976,7 +964,7 @@
#
# The ids other than the node-id specify the position of the CPU
# within the CPU topology (as defined by the machine property "smp",
# thus see also type @SMPConfiguration)
# thus see also type `SMPConfiguration`)
#
# @node-id: NUMA node ID the CPU belongs to
#
@ -1004,7 +992,7 @@
# Since: 2.7
##
{ 'struct': 'CpuInstanceProperties',
# Keep these in sync with the properties device_add accepts
# Keep these in sync with the properties `device_add` accepts
'data': { '*node-id': 'int',
'*drawer-id': 'int',
'*book-id': 'int',
@ -1020,19 +1008,19 @@
##
# @HotpluggableCPU:
#
# @type: CPU object type for usage with device_add command
# @type: CPU object type for usage with `device_add` command
#
# @props: list of properties to pass for hotplugging a CPU with
# device_add
# `device_add`
#
# @vcpus-count: number of logical VCPU threads @HotpluggableCPU
# @vcpus-count: number of logical VCPU threads `HotpluggableCPU`
# provides
#
# @qom-path: link to existing CPU object if CPU is present or omitted
# if CPU is not present.
#
# .. note:: Management should be prepared to pass through additional
# properties with device_add.
# properties with `device_add`.
#
# Since: 2.7
##
@ -1049,8 +1037,6 @@
#
# TODO: Better documentation; currently there is none.
#
# Returns: a list of HotpluggableCPU objects.
#
# Since: 2.7
#
# .. qmp-example::
@ -1172,9 +1158,6 @@
#
# Return information about the balloon device.
#
# Returns:
# @BalloonInfo
#
# Errors:
# - If the balloon driver is enabled but not functional because
# the KVM kernel module cannot support it, KVMMissingCap
@ -1196,7 +1179,7 @@
# @BALLOON_CHANGE:
#
# Emitted when the guest changes the actual BALLOON level. This value
# is equivalent to the @actual field return by the 'query-balloon'
# is equivalent to the @actual field return by the `query-balloon`
# command
#
# @actual: the logical size of the VM in bytes. Formula used:
@ -1238,9 +1221,6 @@
# Return the hv-balloon driver data contained in the last received
# "STATUS" message from the guest.
#
# Returns:
# @HvBalloonInfo
#
# Errors:
# - If no hv-balloon device is present, guest memory status
# reporting is not enabled or no guest memory status report
@ -1301,6 +1281,8 @@
# Return the amount of initially allocated and present hotpluggable
# (if enabled) memory in bytes.
#
# TODO: This line is a hack to separate the example from the body
#
# .. qmp-example::
#
# -> { "execute": "query-memory-size-summary" }
@ -1983,7 +1965,7 @@
#
# The result of a CPU model baseline.
#
# @model: the baselined CpuModelInfo.
# @model: the baselined `CpuModelInfo`.
#
# Since: 2.8
##
@ -2032,28 +2014,28 @@
#
# * QEMU version: CPU models may look different depending on the QEMU
# version. (Except for CPU models reported as "static" in
# query-cpu-definitions.)
# `query-cpu-definitions`.)
# * machine-type: CPU model may look different depending on the
# machine-type. (Except for CPU models reported as "static" in
# query-cpu-definitions.)
# `query-cpu-definitions`.)
# * machine options (including accelerator): in some architectures,
# CPU models may look different depending on machine and accelerator
# options. (Except for CPU models reported as "static" in
# query-cpu-definitions.)
# `query-cpu-definitions`.)
# * "-cpu" arguments and global properties: arguments to the -cpu
# option and global properties may affect expansion of CPU models.
# Using query-cpu-model-expansion while using these is not advised.
# Using `query-cpu-model-expansion` while using these is not advised.
#
# Some architectures may not support comparing CPU models. s390x
# supports comparing CPU models.
#
# @modela: description of the first CPU model to compare, referred to
# as "model A" in CpuModelCompareResult
# as "model A" in `CpuModelCompareResult`
#
# @modelb: description of the second CPU model to compare, referred to
# as "model B" in CpuModelCompareResult
# as "model B" in `CpuModelCompareResult`
#
# Returns: a CpuModelCompareInfo describing how both CPU models
# Returns: a `CpuModelCompareInfo` describing how both CPU models
# compare
#
# Errors:
@ -2086,17 +2068,17 @@
#
# * QEMU version: CPU models may look different depending on the QEMU
# version. (Except for CPU models reported as "static" in
# query-cpu-definitions.)
# `query-cpu-definitions`.)
# * machine-type: CPU model may look different depending on the
# machine-type. (Except for CPU models reported as "static" in
# query-cpu-definitions.)
# `query-cpu-definitions`.)
# * machine options (including accelerator): in some architectures,
# CPU models may look different depending on machine and accelerator
# options. (Except for CPU models reported as "static" in
# query-cpu-definitions.)
# `query-cpu-definitions`.)
# * "-cpu" arguments and global properties: arguments to the -cpu
# option and global properties may affect expansion of CPU models.
# Using query-cpu-model-expansion while using these is not advised.
# Using `query-cpu-model-expansion` while using these is not advised.
#
# Some architectures may not support baselining CPU models. s390x
# supports baselining CPU models.
@ -2105,7 +2087,7 @@
#
# @modelb: description of the second CPU model to baseline
#
# Returns: a CpuModelBaselineInfo describing the baselined CPU model
# Returns: a `CpuModelBaselineInfo` describing the baselined CPU model
#
# Errors:
# - if baselining CPU models is not supported by the target
@ -2125,7 +2107,7 @@
#
# The result of a cpu model expansion.
#
# @model: the expanded CpuModelInfo.
# @model: the expanded `CpuModelInfo`.
#
# @deprecated-props: an optional list of properties that are flagged as
# deprecated by the CPU vendor. The list depends on the
@ -2154,17 +2136,17 @@
#
# * QEMU version: CPU models may look different depending on the QEMU
# version. (Except for CPU models reported as "static" in
# query-cpu-definitions.)
# `query-cpu-definitions`.)
# * machine-type: CPU model may look different depending on the
# machine-type. (Except for CPU models reported as "static" in
# query-cpu-definitions.)
# `query-cpu-definitions`.)
# * machine options (including accelerator): in some architectures,
# CPU models may look different depending on machine and accelerator
# options. (Except for CPU models reported as "static" in
# query-cpu-definitions.)
# `query-cpu-definitions`.)
# * "-cpu" arguments and global properties: arguments to the -cpu
# option and global properties may affect expansion of CPU models.
# Using query-cpu-model-expansion while using these is not advised.
# Using `query-cpu-model-expansion` while using these is not advised.
#
# Some architectures may not support all expansion types. s390x
# supports "full" and "static". Arm only supports "full".
@ -2173,7 +2155,7 @@
#
# @type: expansion type, specifying how to expand the CPU model
#
# Returns: a CpuModelExpansionInfo describing the expanded CPU model
# Returns: a `CpuModelExpansionInfo` describing the expanded CPU model
#
# Errors:
# - if expanding CPU models is not supported
@ -2212,7 +2194,7 @@
# from running in the current host. (since 2.8)
#
# @typename: Type name that can be used as argument to
# @device-list-properties, to introspect properties configurable
# `device-list-properties`, to introspect properties configurable
# using -cpu or -global. (since 2.9)
#
# @alias-of: Name of CPU model this model is an alias for. The target
@ -2256,8 +2238,6 @@
#
# Return a list of supported virtual CPU definitions
#
# Returns: a list of CpuDefinitionInfo
#
# Since: 1.2
##
{ 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'] }

84
qapi/migration.json
View File

@ -3,7 +3,9 @@
#
##
# = Migration
# *********
# Migration
# *********
##
{ 'include': 'common.json' }
@ -193,14 +195,14 @@
#
# Information about current migration process.
#
# @status: @MigrationStatus describing the current migration status.
# @status: `MigrationStatus` describing the current migration status.
# If this field is not returned, no migration process has been
# initiated
#
# @ram: @MigrationStats containing detailed migration status, only
# @ram: `MigrationStats` containing detailed migration status, only
# returned if status is 'active' or 'completed'(since 1.2)
#
# @xbzrle-cache: @XBZRLECacheStats containing detailed XBZRLE
# @xbzrle-cache: `XBZRLECacheStats` containing detailed XBZRLE
# migration statistics, only returned if XBZRLE feature is on and
# status is 'active' or 'completed' (since 1.2)
#
@ -264,7 +266,7 @@
# @socket-address: Only used for tcp, to know what the real port is
# (Since 4.0)
#
# @vfio: @VfioStats containing detailed VFIO devices migration
# @vfio: `VfioStats` containing detailed VFIO devices migration
# statistics, only returned if VFIO device is present, migration
# is supported by all VFIO devices and status is 'active' or
# 'completed' (since 5.2)
@ -275,7 +277,7 @@
#
# @dirty-limit-throttle-time-per-round: Maximum throttle time (in
# microseconds) of virtual CPUs each dirty ring full round, which
# shows how MigrationCapability dirty-limit affects the guest
# shows how `MigrationCapability` dirty-limit affects the guest
# during live migration. (Since 8.1)
#
# @dirty-limit-ring-full-time: Estimated average dirty ring full time
@ -324,8 +326,6 @@
# is active there will be another json-object with RAM migration
# status.
#
# Returns: @MigrationInfo
#
# Since: 0.14
#
# .. qmp-example::
@ -575,8 +575,6 @@
#
# Return information about the current migration capabilities status
#
# Returns: @MigrationCapabilityStatus
#
# Since: 1.2
#
# .. qmp-example::
@ -629,7 +627,7 @@
#
# @normal: the original form of migration. (since 8.2)
#
# @cpr-reboot: The migrate command stops the VM and saves state to the
# @cpr-reboot: The `migrate` command stops the VM and saves state to the
# URI. After quitting QEMU, the user resumes by running QEMU
# -incoming.
#
@ -679,7 +677,7 @@
#
# New QEMU reads the CPR channel before opening a monitor, hence
# the CPR channel cannot be specified in the list of channels for
# a migrate-incoming command. It may only be specified on the
# a `migrate-incoming` command. It may only be specified on the
# command line.
#
# The main channel address cannot be a file type, and for an
@ -690,10 +688,10 @@
# memory-backend-epc is not supported. The VM must be started
# with the '-machine aux-ram-share=on' option.
#
# When using -incoming defer, you must issue the migrate command
# When using -incoming defer, you must issue the `migrate` command
# to old QEMU before issuing any monitor commands to new QEMU.
# However, new QEMU does not open and read the migration stream
# until you issue the migrate incoming command.
# until you issue the `migrate-incoming` command.
#
# (since 10.0)
##
@ -915,11 +913,11 @@
# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration.
# Defaults to 1. (Since 8.1)
#
# @mode: Migration mode. See description in @MigMode. Default is
# @mode: Migration mode. See description in `MigMode`. Default is
# 'normal'. (Since 8.2)
#
# @zero-page-detection: Whether and how to detect zero pages.
# See description in @ZeroPageDetection. Default is 'multifd'.
# See description in `ZeroPageDetection`. Default is 'multifd'.
# (since 9.0)
#
# @direct-io: Open migration files with O_DIRECT when possible. This
@ -1096,11 +1094,11 @@
# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration.
# Defaults to 1. (Since 8.1)
#
# @mode: Migration mode. See description in @MigMode. Default is
# @mode: Migration mode. See description in `MigMode`. Default is
# 'normal'. (Since 8.2)
#
# @zero-page-detection: Whether and how to detect zero pages.
# See description in @ZeroPageDetection. Default is 'multifd'.
# See description in `ZeroPageDetection`. Default is 'multifd'.
# (since 9.0)
#
# @direct-io: Open migration files with O_DIRECT when possible. This
@ -1112,8 +1110,8 @@
# @unstable: Members @x-checkpoint-delay and
# @x-vcpu-dirty-limit-period are experimental.
#
# TODO: either fuse back into MigrationParameters, or make
# MigrationParameters members mandatory
# TODO: either fuse back into `MigrationParameters`, or make
# `MigrationParameters` members mandatory
#
# Since: 2.4
##
@ -1306,11 +1304,11 @@
# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration.
# Defaults to 1. (Since 8.1)
#
# @mode: Migration mode. See description in @MigMode. Default is
# @mode: Migration mode. See description in `MigMode`. Default is
# 'normal'. (Since 8.2)
#
# @zero-page-detection: Whether and how to detect zero pages.
# See description in @ZeroPageDetection. Default is 'multifd'.
# See description in `ZeroPageDetection`. Default is 'multifd'.
# (since 9.0)
#
# @direct-io: Open migration files with O_DIRECT when possible. This
@ -1362,8 +1360,6 @@
#
# Return information about the current migration parameters
#
# Returns: @MigrationParameters
#
# Since: 2.4
#
# .. qmp-example::
@ -1402,7 +1398,7 @@
#
# Emitted when a migration event happens
#
# @status: @MigrationStatus describing the current migration status.
# @status: `MigrationStatus` describing the current migration status.
#
# Since: 2.4
#
@ -1523,8 +1519,8 @@
# The reason for a COLO exit.
#
# @none: failover has never happened. This state does not occur in
# the COLO_EXIT event, and is only visible in the result of
# query-colo-status.
# the `COLO_EXIT` event, and is only visible in the result of
# `query-colo-status`.
#
# @request: COLO exit is due to an external request.
#
@ -1779,8 +1775,8 @@
# list connected to a destination interface endpoint.
#
# @exit-on-error: Exit on incoming migration failure. Default true.
# When set to false, the failure triggers a MIGRATION event, and
# error details could be retrieved with query-migrate.
# When set to false, the failure triggers a :qapi:event:`MIGRATION`
# event, and error details could be retrieved with `query-migrate`.
# (since 9.1)
#
# Since: 2.3
@ -1792,7 +1788,7 @@
# already exposed above libvirt.
#
# 2. QEMU must be started with -incoming defer to allow
# migrate-incoming to be used.
# `migrate-incoming` to be used.
#
# 3. The uri format is the same as for -incoming
#
@ -1845,7 +1841,7 @@
# devices of the VM are not saved by this command.
#
# @filename: the file to save the state of the devices to as binary
# data. See xen-save-devices-state.txt for a description of the
# data. See `xen-save-devices-state`.txt for a description of the
# binary format.
#
# @live: Optional argument to ask QEMU to treat this command as part
@ -1886,7 +1882,7 @@
# devices of the VM are not loaded by this command.
#
# @filename: the file to load the state of the devices from as binary
# data. See xen-save-devices-state.txt for a description of the
# data. See `xen-save-devices-state`.txt for a description of the
# binary format.
#
# Since: 2.7
@ -1926,7 +1922,7 @@
##
# @ReplicationStatus:
#
# The result format for 'query-xen-replication-status'.
# The result format for `query-xen-replication-status`.
#
# @error: true if an error happened, false if replication is normal.
#
@ -1944,7 +1940,7 @@
#
# Query replication status while the vm is running.
#
# Returns: A @ReplicationStatus object showing the status.
# TODO: This line is a hack to separate the example from the body
#
# .. qmp-example::
#
@ -1975,7 +1971,7 @@
##
# @COLOStatus:
#
# The result format for 'query-colo-status'.
# The result format for `query-colo-status`.
#
# @mode: COLO running mode. If COLO is running, this field will
# return 'primary' or 'secondary'.
@ -1998,7 +1994,7 @@
#
# Query COLO status while the vm is running.
#
# Returns: A @COLOStatus object showing the status.
# TODO: This line is a hack to separate the example from the body
#
# .. qmp-example::
#
@ -2099,7 +2095,7 @@
# @DirtyRateMeasureMode:
#
# Method used to measure dirty page rate. Differences between
# available methods are explained in @calc-dirty-rate.
# available methods are explained in `calc-dirty-rate`.
#
# @page-sampling: use page sampling
#
@ -2167,7 +2163,7 @@
# @calc-dirty-rate:
#
# Start measuring dirty page rate of the VM. Results can be retrieved
# with @query-dirty-rate after measurements are completed.
# with `query-dirty-rate` after measurements are completed.
#
# Dirty page rate is the number of pages changed in a given time
# period expressed in MiB/s. The following methods of calculation are
@ -2240,7 +2236,7 @@
##
# @query-dirty-rate:
#
# Query results of the most recent invocation of @calc-dirty-rate.
# Query results of the most recent invocation of `calc-dirty-rate`.
#
# @calc-time-unit: time unit in which to report calculation time.
# By default it is reported in seconds. (Since 8.2)
@ -2290,7 +2286,7 @@
#
# Requires KVM with accelerator property "dirty-ring-size" set. A
# virtual CPU's dirty page rate is a measure of its memory load. To
# observe dirty page rates, use @calc-dirty-rate.
# observe dirty page rates, use `calc-dirty-rate`.
#
# @cpu-index: index of a virtual CPU, default is all.
#
@ -2315,8 +2311,8 @@
# Cancel the upper limit of dirty page rate for virtual CPUs.
#
# Cancel the dirty page limit for the vCPU which has been set with
# set-vcpu-dirty-limit command. Note that this command requires
# support from dirty ring, same as the "set-vcpu-dirty-limit".
# `set-vcpu-dirty-limit` command. Note that this command requires
# support from dirty ring, same as the `set-vcpu-dirty-limit`.
#
# @cpu-index: index of a virtual CPU, default is all.
#
@ -2373,8 +2369,6 @@
#
# @deprecated: This command is deprecated with no replacement yet.
#
# Returns: @MigrationThreadInfo
#
# Since: 7.2
##
{ 'command': 'query-migrationthreads',
@ -2475,7 +2469,7 @@
# time it takes to load the snapshot.
#
# It is strongly recommended that @devices contain all writable block
# device nodes that can have changed since the original @snapshot-save
# device nodes that can have changed since the original `snapshot-save`
# command execution.
#
# .. qmp-example::

4
qapi/misc-arm.json
View File

@ -30,14 +30,12 @@
##
# @query-gic-capabilities:
#
# It will return a list of GICCapability objects that describe its
# It will return a list of `GICCapability` objects that describe its
# capability bits.
#
# On non-ARM targets this command will report an error as the GIC
# technology is not applicable.
#
# Returns: a list of GICCapability objects.
#
# Since: 2.6
#
# .. qmp-example::

32
qapi/misc-i386.json
View File

@ -6,9 +6,9 @@
##
# @rtc-reset-reinjection:
#
# This command will reset the RTC interrupt reinjection backlog. Can
# be used if another mechanism to synchronize guest time is in effect,
# for example QEMU guest agent's guest-set-time command.
# Reset the RTC interrupt reinjection backlog. Can be used if another
# mechanism to synchronize guest time is in effect, for example QEMU
# guest agent's guest-set-time command.
#
# Use of this command is only applicable for x86 machines with an RTC,
# and on other machines will silently return without performing any
@ -26,7 +26,7 @@
##
# @SevState:
#
# An enumeration of SEV state information used during @query-sev.
# An enumeration of SEV state information used during `query-sev`.
#
# @uninit: The guest is uninitialized.
#
@ -132,8 +132,6 @@
# @enabled field is set to 'false' and the state of all other fields
# is unspecified.
#
# Returns: @SevInfo
#
# Since: 2.12
#
# .. qmp-example::
@ -165,7 +163,7 @@
# 'sev-guest' confidential virtualization object. The launch
# measurement for SEV-SNP guests is only available within the guest.
#
# Returns: The @SevLaunchMeasureInfo for the guest
# Returns: The guest's SEV guest launch measurement info
#
# Errors:
# - If the launch measurement is unavailable, either due to an
@ -214,8 +212,6 @@
#
# This is only supported on AMD X86 platforms with KVM enabled.
#
# Returns: SevCapability objects.
#
# Errors:
# - If SEV is not available on the platform, GenericError
#
@ -233,8 +229,7 @@
##
# @sev-inject-launch-secret:
#
# This command injects a secret blob into memory of a SEV/SEV-ES
# guest.
# Inject a secret blob into a SEV/SEV-ES guest's memory.
#
# This is only valid on x86 machines configured with KVM and the
# 'sev-guest' confidential virtualization object. SEV-SNP guests do
@ -272,7 +267,7 @@
##
# @query-sev-attestation-report:
#
# This command is used to get the SEV attestation report.
# Get the SEV attestation report.
#
# This is only valid on x86 machines configured with KVM and the
# 'sev-guest' confidential virtualization object. The attestation
@ -281,13 +276,10 @@
# @mnonce: a random 16 bytes value encoded in base64 (it will be
# included in report)
#
# Returns: SevAttestationReport objects.
#
# Errors:
# - This will return an error if the attestation report is
# unavailable, either due to an invalid guest configuration
# or if the guest has not reached the required SEV state,
# GenericError
# - If the attestation report is unavailable, either due to an
# invalid guest configuration or because the guest has not
# reached the required SEV state, GenericError
#
# Since: 6.1
#
@ -345,8 +337,6 @@
#
# Return information about configured SGX capabilities of guest
#
# Returns: @SgxInfo
#
# Since: 6.2
#
# .. qmp-example::
@ -364,8 +354,6 @@
#
# Return information about SGX capabilities of host
#
# Returns: @SgxInfo
#
# Since: 6.2
#
# .. qmp-example::

28
qapi/misc.json
View File

@ -3,7 +3,9 @@
#
##
# = Miscellanea
# ***********
# Miscellanea
# ***********
##
{ 'include': 'common.json' }
@ -21,7 +23,7 @@
# "@dbus-display" or the name of a character device (e.g. from
# -chardev id=XXXX)
#
# @fdname: file descriptor name previously passed via 'getfd' command
# @fdname: file descriptor name previously passed via `getfd` command
#
# @skipauth: whether to skip authentication. Only applies to "vnc"
# and "spice" protocols
@ -56,8 +58,6 @@
#
# Return the name information of a guest.
#
# Returns: @NameInfo of the guest
#
# Since: 0.14
#
# .. qmp-example::
@ -107,7 +107,7 @@
# declared using the ``-object iothread`` command-line option. It
# is always the main thread of the process.
#
# Returns: a list of @IOThreadInfo for each iothread
# Returns: a list of info for each iothread
#
# Since: 2.0
#
@ -228,7 +228,7 @@
# Known limitations:
#
# * This command is stateless, this means that commands that depend
# on state information (such as getfd) might not work.
# on state information (such as `getfd`) might not work.
#
# * Commands that prompt the user for data don't currently work.
#
@ -255,7 +255,7 @@
# .. note:: If @fdname already exists, the file descriptor assigned to
# 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.
#
# .. qmp-example::
@ -282,7 +282,7 @@
# .. note:: If @fdname already exists, the file descriptor assigned to
# 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.
#
# .. qmp-example::
@ -332,9 +332,6 @@
#
# @opaque: A free-form string that can be used to describe the fd.
#
# Returns:
# @AddfdInfo
#
# Errors:
# - If file descriptor was not received, GenericError
# - If @fdset-id is a negative value, GenericError
@ -415,8 +412,6 @@
#
# Return information describing all fd sets.
#
# Returns: A list of @FdsetInfo
#
# Since: 1.2
#
# .. note:: The list of fd sets is shared by all monitor connections.
@ -480,7 +475,7 @@
#
# @name: parameter name
#
# @type: parameter @CommandLineParameterType
# @type: parameter `CommandLineParameterType`
#
# @help: human readable text string, not suitable for parsing.
#
@ -502,7 +497,7 @@
#
# @option: option name
#
# @parameters: an array of @CommandLineParameterInfo
# @parameters: an array of `CommandLineParameterInfo`
#
# Since: 1.5
##
@ -516,8 +511,7 @@
#
# @option: option name
#
# Returns: list of @CommandLineOptionInfo for all options (or for the
# given @option).
# Returns: list of objects for all options (or for the given @option).
#
# Errors:
# - if the given @option doesn't exist

12
qapi/net.json
View File

@ -3,7 +3,9 @@
#
##
# = Net devices
# ***********
# Net devices
# ***********
##
{ 'include': 'sockets.json' }
@ -777,7 +779,7 @@
# this to zero disables this function. This member is mutually
# exclusive with @reconnect. (default: 0) (Since: 9.2)
#
# Only SocketAddress types 'unix', 'inet' and 'fd' are supported.
# Only `SocketAddress` types 'unix', 'inet' and 'fd' are supported.
#
# Features:
#
@ -802,7 +804,7 @@
#
# @local: local address
#
# Only SocketAddress types 'unix', 'inet' and 'fd' are supported.
# Only `SocketAddress` types 'unix', 'inet' and 'fd' are supported.
#
# If remote address is present and it's a multicast address, local
# address is optional. Otherwise local address is required and remote
@ -972,7 +974,7 @@
#
# @name: net client name
#
# Returns: list of @RxFilterInfo for all NICs (or for the given NIC).
# Returns: list of info for all NICs (or for the given NIC).
#
# Errors:
# - if the given @name doesn't exist
@ -1017,7 +1019,7 @@
##
# @NIC_RX_FILTER_CHANGED:
#
# Emitted once until the 'query-rx-filter' command is executed, the
# Emitted once until the `query-rx-filter` command is executed, the
# first event will always be emitted
#
# @name: net client name

8
qapi/pci.json
View File

@ -6,7 +6,9 @@
# SPDX-License-Identifier: GPL-2.0-or-later
##
# = PCI
# ***
# PCI
# ***
##
##
@ -83,7 +85,7 @@
#
# @bus: information about the bus the device resides on
#
# @devices: a list of @PciDeviceInfo for each device on this bridge
# @devices: a list of `PciDeviceInfo` for each device on this bridge
#
# Since: 0.14
##
@ -175,7 +177,7 @@
#
# Return information about the PCI bus topology of the guest.
#
# Returns: a list of @PciInfo for each PCI bus. Each bus is
# Returns: a list of info for each PCI bus. Each bus is
# represented by a json-object, which has a key with a json-array
# of all PCI devices attached to it. Each device is represented
# by a json-object.

4
qapi/qapi-schema.json
View File

@ -1,7 +1,9 @@
# -*- Mode: Python -*-
# vim: filetype=python
##
# = Introduction
# ************
# Introduction
# ************
#
# This manual describes the commands and events supported by the QEMU
# Monitor Protocol (QMP).

11
qapi/qdev.json
View File

@ -5,7 +5,9 @@
# See the COPYING file in the top-level directory.
##
# = Device infrastructure (qdev)
# ****************************
# Device infrastructure (qdev)
# ****************************
##
{ 'include': 'qom.json' }
@ -17,8 +19,7 @@
#
# @typename: the type name of a device
#
# Returns: a list of ObjectPropertyInfo describing a devices
# properties
# Returns: a list describing a devices properties
#
# .. note:: Objects can create properties at runtime, for example to
# describe links between different devices and/or objects. These
@ -96,10 +97,10 @@
# from the guest. Hot removal is an operation that requires guest
# cooperation. This command merely requests that the guest begin
# the hot removal process. Completion of the device removal
# process is signaled with a DEVICE_DELETED event. Guest reset
# process is signaled with a `DEVICE_DELETED` event. Guest reset
# will automatically complete removal for all devices. If a
# guest-side error in the hot removal process is detected, the
# device will not be removed and a DEVICE_UNPLUG_GUEST_ERROR event
# device will not be removed and a `DEVICE_UNPLUG_GUEST_ERROR` event
# is sent. Some errors cannot be detected.
#
# Since: 0.14

39
qapi/qom.json
View File

@ -10,7 +10,9 @@
{ 'include': 'crypto.json' }
##
# = QEMU Object Model (QOM)
# ***********************
# QEMU Object Model (QOM)
# ***********************
##
##
@ -48,14 +50,12 @@
##
# @qom-list:
#
# This command will list any properties of a object given a path in
# the object model.
# List properties of a object given a path in the object model.
#
# @path: the path within the object model. See @qom-get for a
# @path: the path within the object model. See `qom-get` for a
# description of this parameter.
#
# Returns: a list of @ObjectPropertyInfo that describe the properties
# of the object.
# Returns: a list that describe the properties of the object.
#
# Since: 1.2
#
@ -76,8 +76,7 @@
##
# @qom-get:
#
# This command will get a property from a object model path and return
# the value.
# Get a property value.
#
# @path: The path within the object model. There are two forms of
# supported paths--absolute and partial paths.
@ -128,14 +127,14 @@
##
# @qom-set:
#
# This command will set a property from a object model path.
# Set a property value.
#
# @path: see @qom-get for a description of this parameter
# @path: see `qom-get` for a description of this parameter
#
# @property: the property name to set
#
# @value: a value who's type is appropriate for the property type.
# See @qom-get for a description of type mapping.
# See `qom-get` for a description of type mapping.
#
# Since: 1.2
#
@ -154,7 +153,7 @@
##
# @ObjectTypeInfo:
#
# This structure describes a search result from @qom-list-types
# This structure describes a search result from `qom-list-types`
#
# @name: the type name found in the search
#
@ -171,15 +170,14 @@
##
# @qom-list-types:
#
# This command will return a list of types given search parameters
# Return a list of types given search parameters.
#
# @implements: if specified, only return types that implement this
# type name
#
# @abstract: if true, include abstract types in the results
#
# Returns: a list of @ObjectTypeInfo or an empty list if no results
# are found
# Returns: a list of types, or an empty list if no results are found
#
# Since: 1.1
##
@ -195,11 +193,12 @@
#
# @typename: the type name of an object
#
#
# .. note:: Objects can create properties at runtime, for example to
# describe links between different devices and/or objects. These
# properties are not included in the output of this command.
#
# Returns: a list of ObjectPropertyInfo describing object properties
# Returns: a list describing object properties
#
# Since: 2.12
##
@ -789,7 +788,7 @@
#
# Properties for x-remote-object objects.
#
# @fd: file descriptor name previously passed via 'getfd' command
# @fd: file descriptor name previously passed via `getfd` command
#
# @devid: the id of the device to be associated with the file
# descriptor
@ -818,7 +817,7 @@
#
# Properties for iommufd objects.
#
# @fd: file descriptor name previously passed via 'getfd' command,
# @fd: file descriptor name previously passed via `getfd` command,
# which represents a pre-opened /dev/iommu. This allows the
# iommufd object to be shared across several subsystems (VFIO,
# VDPA, ...), and the file descriptor to be shared with other
@ -1278,7 +1277,7 @@
# Create a QOM object.
#
# Errors:
# - Error if @qom-type is not a valid class name
# - If @qom-type is not a valid class name
#
# Since: 2.0
#
@ -1300,7 +1299,7 @@
# @id: the name of the QOM object to remove
#
# Errors:
# - Error if @id is not a valid id for a QOM object
# - If @id is not a valid id for a QOM object
#
# Since: 2.0
#

14
qapi/replay.json
View File

@ -3,7 +3,9 @@
#
##
# = Record/replay
# *************
# Record/replay
# *************
##
{ 'include': 'common.json' }
@ -47,8 +49,8 @@
# @query-replay:
#
# Retrieve the record/replay information. It includes current
# instruction count which may be used for @replay-break and
# @replay-seek commands.
# instruction count which may be used for `replay-break` and
# `replay-seek` commands.
#
# Returns: record/replay information.
#
@ -70,7 +72,7 @@
# breakpoint. When breakpoint is set, any prior one is removed. The
# breakpoint may be set only in replay mode and only "in the future",
# i.e. at instruction counts greater than the current one. The
# current instruction count can be observed with @query-replay.
# current instruction count can be observed with `query-replay`.
#
# @icount: instruction count to stop at
#
@ -86,7 +88,7 @@
##
# @replay-delete-break:
#
# Remove replay breakpoint which was set with @replay-break. The
# Remove replay breakpoint which was set with `replay-break`. The
# command is ignored when there are no replay breakpoints.
#
# Since: 5.2
@ -106,7 +108,7 @@
# snapshot and replays the execution to find the desired instruction.
# When there is no preceding snapshot or the execution is not
# replayed, then the command fails. Instruction count can be obtained
# with the @query-replay command.
# with the `query-replay` command.
#
# @icount: target instruction count
#

8
qapi/rocker.json
View File

@ -2,7 +2,9 @@
# vim: filetype=python
##
# = Rocker switch device
# ********************
# Rocker switch device
# ********************
##
##
@ -28,8 +30,6 @@
#
# @name: switch name
#
# Returns: @Rocker information
#
# Since: 2.4
#
# .. qmp-example::
@ -98,8 +98,6 @@
#
# @name: port name
#
# Returns: a list of @RockerPort information
#
# Since: 2.4
#
# .. qmp-example::

52
qapi/run-state.json
View File

@ -3,7 +3,9 @@
#
##
# = VM run state
# ************
# VM run state
# ************
##
##
@ -68,9 +70,9 @@
#
# @host-error: An error prevents further use of guest
#
# @host-qmp-quit: Reaction to the QMP command 'quit'
# @host-qmp-quit: Reaction to the QMP command `quit`
#
# @host-qmp-system-reset: Reaction to the QMP command 'system_reset'
# @host-qmp-system-reset: Reaction to the QMP command `system_reset`
#
# @host-signal: Reaction to a signal, such as SIGINT
#
@ -106,7 +108,7 @@
#
# @running: true if all VCPUs are runnable, false if not runnable
#
# @status: the virtual machine @RunState
# @status: the virtual machine `RunState`
#
# Since: 0.14
##
@ -119,8 +121,6 @@
#
# Query the run status of the VM
#
# Returns: @StatusInfo reflecting the VM
#
# Since: 0.14
#
# .. qmp-example::
@ -143,12 +143,12 @@
# hardware-specific action) rather than a host request (such as
# sending QEMU a SIGINT). (since 2.10)
#
# @reason: The @ShutdownCause which resulted in the SHUTDOWN.
# @reason: The `ShutdownCause` which resulted in the `SHUTDOWN`.
# (since 4.0)
#
# .. note:: If the command-line option ``-no-shutdown`` has been
# specified, QEMU will not exit, and a STOP event will eventually
# follow the SHUTDOWN event.
# specified, QEMU will not exit, and a `STOP` event will eventually
# follow the `SHUTDOWN` event.
#
# Since: 0.12
#
@ -183,9 +183,9 @@
# @guest: If true, the reset was triggered by a guest request (such as
# a guest-initiated ACPI reboot request or other hardware-specific
# action) rather than a host request (such as the QMP command
# system_reset). (since 2.10)
# `system_reset`). (since 2.10)
#
# @reason: The @ShutdownCause of the RESET. (since 4.0)
# @reason: The `ShutdownCause` of the `RESET`. (since 4.0)
#
# Since: 0.12
#
@ -247,7 +247,7 @@
# saved on disk, for example, S4 state, which is sometimes called
# hibernate state
#
# .. note:: QEMU shuts down (similar to event @SHUTDOWN) when entering
# .. note:: QEMU shuts down (similar to event `SHUTDOWN`) when entering
# this state.
#
# Since: 1.2
@ -281,8 +281,8 @@
#
# @action: action that has been taken
#
# .. note:: If action is "reset", "shutdown", or "pause" the WATCHDOG
# event is followed respectively by the RESET, SHUTDOWN, or STOP
# .. note:: If action is "reset", "shutdown", or "pause" the `WATCHDOG`
# event is followed respectively by the `RESET`, `SHUTDOWN`, or `STOP`
# events.
#
# .. note:: This event is rate-limited.
@ -378,7 +378,7 @@
#
# Set watchdog action.
#
# @action: @WatchdogAction action taken when watchdog timer expires.
# @action: `WatchdogAction` action taken when watchdog timer expires.
#
# Since: 2.11
#
@ -396,13 +396,13 @@
# Set the actions that will be taken by the emulator in response to
# guest events.
#
# @reboot: @RebootAction action taken on guest reboot.
# @reboot: `RebootAction` action taken on guest reboot.
#
# @shutdown: @ShutdownAction action taken on guest shutdown.
# @shutdown: `ShutdownAction` action taken on guest shutdown.
#
# @panic: @PanicAction action taken on guest panic.
# @panic: `PanicAction` action taken on guest panic.
#
# @watchdog: @WatchdogAction action taken when watchdog timer expires.
# @watchdog: `WatchdogAction` action taken when watchdog timer expires.
#
# Since: 6.0
#
@ -529,20 +529,20 @@
#
# Hyper-V specific guest panic information (HV crash MSRs)
#
# @arg1: for Windows, STOP code for the guest crash. For Linux,
# @arg1: for Windows, `STOP` code for the guest crash. For Linux,
# an error code.
#
# @arg2: for Windows, first argument of the STOP. For Linux, the
# @arg2: for Windows, first argument of the `STOP`. For Linux, the
# guest OS ID, which has the kernel version in bits 16-47 and
# 0x8100 in bits 48-63.
#
# @arg3: for Windows, second argument of the STOP. For Linux, the
# @arg3: for Windows, second argument of the `STOP`. For Linux, the
# program counter of the guest.
#
# @arg4: for Windows, third argument of the STOP. For Linux, the
# @arg4: for Windows, third argument of the `STOP`. For Linux, the
# RAX register (x86) or the stack pointer (aarch64) of the guest.
#
# @arg5: for Windows, fourth argument of the STOP. For x86 Linux, the
# @arg5: for Windows, fourth argument of the `STOP`. For x86 Linux, the
# stack pointer of the guest.
#
# Since: 2.9
@ -630,11 +630,11 @@
#
# Emitted when a memory failure occurs on host side.
#
# @recipient: recipient is defined as @MemoryFailureRecipient.
# @recipient: recipient is defined as `MemoryFailureRecipient`.
#
# @action: action that has been taken.
#
# @flags: flags for MemoryFailureAction.
# @flags: flags for `MemoryFailureAction`.
#
# Since: 5.2
#

10
qapi/sockets.json
View File

@ -2,7 +2,9 @@
# vim: filetype=python
##
# = Socket data types
# *****************
# Socket data types
# *****************
##
##
@ -209,14 +211,14 @@
'unix': 'UnixSocketAddressWrapper',
'vsock': 'VsockSocketAddressWrapper',
'fd': 'FdSocketAddressWrapper' } }
# Note: This type is deprecated in favor of SocketAddress. The
# difference between SocketAddressLegacy and SocketAddress is that the
# Note: This type is deprecated in favor of `SocketAddress`. The
# difference between `SocketAddressLegacy` and `SocketAddress` is that the
# latter has fewer ``{}`` on the wire.
##
# @SocketAddressType:
#
# Available SocketAddress types
# Available `SocketAddress` types
#
# @inet: Internet address
#

14
qapi/stats.json
View File

@ -9,7 +9,9 @@
# SPDX-License-Identifier: GPL-2.0-or-later
##
# = Statistics
# **********
# Statistics
# **********
##
##
@ -87,7 +89,7 @@
# @StatsRequest:
#
# Indicates a set of statistics that should be returned by
# query-stats.
# `query-stats`.
#
# @provider: provider for which to return statistics.
#
@ -112,7 +114,7 @@
##
# @StatsFilter:
#
# The arguments to the query-stats command; specifies a target for
# The arguments to the `query-stats` command; specifies a target for
# which to request statistics and optionally the required subset of
# information for that target.
#
@ -183,10 +185,10 @@
# Return runtime-collected statistics for objects such as the VM or
# its vCPUs.
#
# The arguments are a StatsFilter and specify the provider and objects
# The arguments are a `StatsFilter` and specify the provider and objects
# to return statistics about.
#
# Returns: a list of StatsResult, one for each provider and object
# Returns: a list of statistics, one for each provider and object
# (e.g., for each vCPU).
#
# Since: 7.1
@ -203,7 +205,7 @@
#
# @name: name of the statistic; each element of the schema is uniquely
# identified by a target, a provider (both available in
# @StatsSchema) and the name.
# `StatsSchema`) and the name.
#
# @type: kind of statistic.
#

8
qapi/tpm.json
View File

@ -3,7 +3,9 @@
#
##
# = TPM (trusted platform module) devices
# *************************************
# TPM (trusted platform module) devices
# *************************************
##
##
@ -27,8 +29,6 @@
#
# Return a list of supported TPM models
#
# Returns: a list of TpmModel
#
# Since: 1.5
#
# .. qmp-example::
@ -58,8 +58,6 @@
#
# Return a list of supported TPM types
#
# Returns: a list of TpmType
#
# Since: 1.5
#
# .. qmp-example::

6
qapi/trace.json
View File

@ -7,7 +7,9 @@
# See the COPYING file in the top-level directory.
##
# = Tracing
# *******
# Tracing
# *******
##
##
@ -47,7 +49,7 @@
#
# @name: Event name pattern (case-sensitive glob).
#
# Returns: a list of @TraceEventInfo for the matching events
# Returns: a list of info for the matching events
#
# Since: 2.2
#

16
qapi/transaction.json
View File

@ -3,7 +3,9 @@
#
##
# = Transactions
# ************
# Transactions
# ************
##
{ 'include': 'block-core.json' }
@ -67,8 +69,8 @@
#
# Features:
#
# @deprecated: Member @drive-backup is deprecated. Use member
# @blockdev-backup instead.
# @deprecated: Member `drive-backup` is deprecated. Use member
# `blockdev-backup` instead.
#
# Since: 1.1
##
@ -156,7 +158,7 @@
# @TransactionAction:
#
# A discriminated record of operations that can be performed with
# @transaction.
# `transaction`.
#
# @type: the operation to be performed
#
@ -187,7 +189,7 @@
#
# @completion-mode: Controls how jobs launched asynchronously by
# Actions will complete or fail as a group. See
# @ActionCompletionMode for details.
# `ActionCompletionMode` for details.
#
# Since: 2.5
##
@ -227,11 +229,11 @@
# in the transaction. When an I/O error occurs during deletion, the
# user needs to fix it later with qemu-img or other command.
#
# @actions: List of @TransactionAction; information needed for the
# @actions: List of `TransactionAction`; information needed for the
# respective operations.
#
# @properties: structure of additional options to control the
# execution of the transaction. See @TransactionProperties for
# execution of the transaction. See `TransactionProperties` for
# additional detail.
#
# Errors:

4
qapi/uefi.json
View File

@ -3,7 +3,9 @@
#
##
# = UEFI Variable Store
# *******************
# UEFI Variable Store
# *******************
#
# The QEMU efi variable store implementation (hw/uefi/) uses this to
# store non-volatile variables in json format on disk.

58
qapi/ui.json
View File

@ -3,7 +3,9 @@
#
##
# = Remote desktop
# **************
# Remote desktop
# **************
##
{ 'include': 'common.json' }
@ -39,7 +41,7 @@
##
# @SetPasswordOptions:
#
# Options for set_password.
# Options for `set_password`.
#
# @protocol:
# - 'vnc' to modify the VNC server password
@ -63,7 +65,7 @@
##
# @SetPasswordOptionsVnc:
#
# Options for set_password specific to the VNC protocol.
# Options for `set_password` specific to the VNC protocol.
#
# @display: The id of the display where the password should be
# changed. Defaults to the first.
@ -94,7 +96,7 @@
##
# @ExpirePasswordOptions:
#
# General options for expire_password.
# General options for `expire_password`.
#
# @protocol:
# - 'vnc' to modify the VNC server expiration
@ -124,7 +126,7 @@
##
# @ExpirePasswordOptionsVnc:
#
# Options for expire_password specific to the VNC protocol.
# Options for `expire_password` specific to the VNC protocol.
#
# @display: The id of the display where the expiration should be
# changed. Defaults to the first.
@ -183,7 +185,7 @@
# the head can only be specified in conjunction with the device
# ID. (Since 2.12)
#
# @format: image format for screendump. (default: ppm) (Since 7.1)
# @format: image format for `screendump`. (default: ppm) (Since 7.1)
#
# Since: 0.14
#
@ -200,7 +202,8 @@
'if': 'CONFIG_PIXMAN' }
##
# == Spice
# Spice
# =====
##
##
@ -310,7 +313,7 @@
# unknown if spice server doesn't provide this information.
# (since: 1.1)
#
# @channels: a list of @SpiceChannel for each active spice channel
# @channels: a list of `SpiceChannel` for each active spice channel
#
# Since: 0.14
##
@ -325,8 +328,6 @@
#
# Return information about the current SPICE server
#
# Returns: @SpiceInfo
#
# Since: 0.14
#
# .. qmp-example::
@ -461,7 +462,8 @@
'if': 'CONFIG_SPICE' }
##
# == VNC
# VNC
# ===
##
##
@ -561,7 +563,7 @@
# - 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL
# auth
#
# @clients: a list of @VncClientInfo of all currently connected
# @clients: a list of `VncClientInfo` of all currently connected
# clients
#
# Since: 0.14
@ -624,12 +626,12 @@
#
# @id: vnc server name.
#
# @server: A list of @VncBasincInfo describing all listening sockets.
# @server: A list of `VncBasicInfo` describing all listening sockets.
# The list can be empty (in case the vnc server is disabled). It
# also may have multiple entries: normal + websocket, possibly
# also ipv4 + ipv6 in the future.
#
# @clients: A list of @VncClientInfo of all currently connected
# @clients: A list of `VncClientInfo` of all currently connected
# clients. The list can be empty, for obvious reasons.
#
# @auth: The current authentication type used by the non-websockets
@ -656,8 +658,6 @@
#
# Return information about the current VNC server
#
# Returns: @VncInfo
#
# Since: 0.14
#
# .. qmp-example::
@ -687,8 +687,6 @@
#
# Return a list of vnc servers. The list can be empty.
#
# Returns: a list of @VncInfo2
#
# Since: 2.3
##
{ 'command': 'query-vnc-servers', 'returns': ['VncInfo2'],
@ -794,7 +792,9 @@
'if': 'CONFIG_VNC' }
##
# = Input
# *****
# Input
# *****
##
##
@ -822,7 +822,7 @@
#
# Return information about each active mouse device
#
# Returns: a list of @MouseInfo for each device
# Returns: a list of info for each device
#
# Since: 0.14
#
@ -852,7 +852,7 @@
#
# An enumeration of key name.
#
# This is used by the @send-key command.
# This is used by the `send-key` command.
#
# @unmapped: since 2.0
#
@ -1023,10 +1023,10 @@
#
# Send keys to guest.
#
# @keys: An array of @KeyValue elements. All @KeyValues in this array
# are simultaneously sent to the guest. A @KeyValue.number value
# is sent directly to the guest, while @KeyValue.qcode must be a
# valid @QKeyCode value
# @keys: An array of `KeyValue` elements. All @KeyValues in this array
# are simultaneously sent to the guest. A `KeyValue`.number value
# is sent directly to the guest, while `KeyValue`.qcode must be a
# valid `QKeyCode` value
#
# @hold-time: time to delay key up events, milliseconds. Defaults to
# 100
@ -1263,7 +1263,7 @@
# @head: head to send event(s) to, in case the display device supports
# multiple scanouts.
#
# @events: List of InputEvent union.
# @events: List of `InputEvent` union.
#
# Since: 2.6
#
@ -1374,7 +1374,7 @@
# first available node on the host.
#
# @p2p: Whether to use peer-to-peer connections (accepted through
# @add_client).
# `add_client`).
#
# @audiodev: Use the specified DBus audiodev to export audio.
#
@ -1533,7 +1533,7 @@
#
# Display (user interface) options.
#
# @type: Which DisplayType QEMU should use.
# @type: Which `DisplayType` QEMU should use.
#
# @full-screen: Start user interface in fullscreen mode
# (default: off).
@ -1571,8 +1571,6 @@
#
# Return information about display configuration
#
# Returns: @DisplayOptions
#
# Since: 3.1
##
{ 'command': 'query-display-options',

4
qapi/vfio.json
View File

@ -3,7 +3,9 @@
#
##
# = VFIO devices
# ************
# VFIO devices
# ************
##
##

20
qapi/virtio.json
View File

@ -3,7 +3,9 @@
#
##
# = Virtio devices
# **************
# Virtio devices
# **************
##
##
@ -135,7 +137,7 @@
# @num-vqs: VirtIODevice virtqueue count. This is the number of
# active virtqueues being used by the VirtIODevice.
#
# @status: VirtIODevice configuration status (VirtioDeviceStatus)
# @status: VirtIODevice configuration status (`VirtioDeviceStatus`)
#
# @isr: VirtIODevice ISR
#
@ -199,7 +201,7 @@
#
# @unstable: This command is meant for debugging.
#
# Returns: VirtioStatus of the virtio device
# Returns: Status of the virtio device
#
# Since: 7.2
#
@ -563,7 +565,7 @@
#
# @unstable: This command is meant for debugging.
#
# Returns: VirtQueueStatus of the VirtQueue
# Returns: Status of the queue
#
# .. note:: last_avail_idx will not be displayed in the case where the
# selected VirtIODevice has a running vhost device and the
@ -577,7 +579,7 @@
# .. qmp-example::
# :annotated:
#
# Get VirtQueueStatus for virtio-vsock (vhost-vsock running)
# Get `VirtQueueStatus` for virtio-vsock (vhost-vsock running)
# ::
#
# -> { "execute": "x-query-virtio-queue-status",
@ -604,7 +606,7 @@
# .. qmp-example::
# :annotated:
#
# Get VirtQueueStatus for virtio-serial (no vhost)
# Get `VirtQueueStatus` for virtio-serial (no vhost)
# ::
#
# -> { "execute": "x-query-virtio-queue-status",
@ -698,7 +700,7 @@
#
# @unstable: This command is meant for debugging.
#
# Returns: VirtVhostQueueStatus of the vhost_virtqueue
# Returns: Status of the vhost_virtqueue
#
# Since: 7.2
#
@ -816,7 +818,7 @@
#
# @index: Index of the element in the queue
#
# @descs: List of descriptors (VirtioRingDesc)
# @descs: List of descriptors (`VirtioRingDesc`)
#
# @avail: VRingAvail info
#
@ -847,8 +849,6 @@
#
# @unstable: This command is meant for debugging.
#
# Returns: VirtioQueueElement information
#
# Since: 7.2
#
# .. qmp-example::

22
qapi/yank.json
View File

@ -3,13 +3,15 @@
#
##
# = Yank feature
# ************
# Yank feature
# ************
##
##
# @YankInstanceType:
#
# An enumeration of yank instance types. See @YankInstance for more
# An enumeration of yank instance types. See `YankInstance` for more
# information.
#
# Since: 6.0
@ -20,7 +22,7 @@
##
# @YankInstanceBlockNode:
#
# Specifies which block graph node to yank. See @YankInstance for
# Specifies which block graph node to yank. See `YankInstance` for
# more information.
#
# @node-name: the name of the block graph node
@ -33,7 +35,7 @@
##
# @YankInstanceChardev:
#
# Specifies which character device to yank. See @YankInstance for
# Specifies which character device to yank. See `YankInstance` for
# more information.
#
# @id: the chardev's ID
@ -46,7 +48,7 @@
##
# @YankInstance:
#
# A yank instance can be yanked with the @yank qmp command to recover
# A yank instance can be yanked with the `yank` qmp command to recover
# from a hanging QEMU.
#
# @type: yank instance type
@ -57,9 +59,9 @@
# nbd server without attempting to reconnect.
# - socket chardev: Yanking it will shut down the connected socket.
# - migration: Yanking it will shut down all migration connections.
# Unlike @migrate_cancel, it will not notify the migration process,
# Unlike `migrate_cancel`, it will not notify the migration process,
# so migration will go into @failed state, instead of @cancelled
# state. @yank should be used to recover from hangs.
# state. `yank` should be used to recover from hangs.
#
# Since: 6.0
##
@ -74,7 +76,7 @@
# @yank:
#
# Try to recover from hanging QEMU by yanking the specified instances.
# See @YankInstance for more information.
# See `YankInstance` for more information.
#
# @instances: the instances to be yanked
#
@ -100,9 +102,9 @@
##
# @query-yank:
#
# Query yank instances. See @YankInstance for more information.
# Query yank instances. See `YankInstance` for more information.
#
# Returns: list of @YankInstance
# TODO: This line is a hack to separate the example from the body
#
# .. qmp-example::
#

48
scripts/qapi/parser.py
View File

@ -584,10 +584,6 @@ def get_doc(self) -> 'QAPIDoc':
doc.append_line(text)
line = self.get_doc_indented(doc)
no_more_args = True
elif line.startswith('='):
raise QAPIParseError(
self,
"unexpected '=' markup in definition documentation")
else:
# plain paragraph
doc.ensure_untagged_section(self.info)
@ -597,22 +593,15 @@ def get_doc(self) -> 'QAPIDoc':
# Free-form documentation
doc = QAPIDoc(info)
doc.ensure_untagged_section(self.info)
first = True
while line is not None:
if match := self._match_at_name_colon(line):
raise QAPIParseError(
self,
"'@%s:' not allowed in free-form documentation"
% match.group(1))
if line.startswith('='):
if not first:
raise QAPIParseError(
self,
"'=' heading must come first in a comment block")
doc.append_line(line)
self.accept(False)
line = self.get_doc_line()
first = False
self.accept()
doc.end()
@ -815,6 +804,43 @@ def connect_feature(self, feature: 'QAPISchemaFeature') -> None:
% feature.name)
self.features[feature.name].connect(feature)
def ensure_returns(self, info: QAPISourceInfo) -> None:
def _insert_near_kind(
kind: QAPIDoc.Kind,
new_sect: QAPIDoc.Section,
after: bool = False,
) -> bool:
for idx, sect in enumerate(reversed(self.all_sections)):
if sect.kind == kind:
pos = len(self.all_sections) - idx - 1
if after:
pos += 1
self.all_sections.insert(pos, new_sect)
return True
return False
if any(s.kind == QAPIDoc.Kind.RETURNS for s in self.all_sections):
return
# Stub "Returns" section for undocumented returns value
stub = QAPIDoc.Section(info, QAPIDoc.Kind.RETURNS)
if any(_insert_near_kind(kind, stub, after) for kind, after in (
# 1. If arguments, right after those.
(QAPIDoc.Kind.MEMBER, True),
# 2. Elif errors, right *before* those.
(QAPIDoc.Kind.ERRORS, False),
# 3. Elif features, right *before* those.
(QAPIDoc.Kind.FEATURE, False),
)):
return
# Otherwise, it should go right after the intro. The intro
# is always the first section and is always present (even
# when empty), so we can insert directly at index=1 blindly.
self.all_sections.insert(1, stub)
def check_expr(self, expr: QAPIExpression) -> None:
if 'command' in expr:
if self.returns and 'returns' not in expr:

3
scripts/qapi/schema.py
View File

@ -1062,6 +1062,9 @@ def connect_doc(self, doc: Optional[QAPIDoc] = None) -> None:
if self.arg_type and self.arg_type.is_implicit():
self.arg_type.connect_doc(doc)
if self.ret_type and self.info:
doc.ensure_returns(self.info)
def visit(self, visitor: QAPISchemaVisitor) -> None:
super().visit(visitor)
visitor.visit_command(

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

@ -14,7 +14,9 @@
# storage daemon.
##
# = Introduction
# ************
# Introduction
# ************
#
# This manual describes the commands and events supported by the QEMU
# storage daemon QMP.
@ -51,7 +53,9 @@
{ 'include': '../../qapi/job.json' }
##
# = Block devices
# *************
# Block devices
# *************
##
{ 'include': '../../qapi/block-core.json' }
{ 'include': '../../qapi/block-export.json' }

1
tests/qapi-schema/doc-bad-section.err
View File

@ -1 +0,0 @@
doc-bad-section.json:5:1: unexpected '=' markup in definition documentation

10
tests/qapi-schema/doc-bad-section.json
View File

@ -1,10 +0,0 @@
# = section within an expression comment
##
# @Enum:
# == No good here
# @one: The _one_ {and only}
#
# @two is undocumented
##
{ 'enum': 'Enum', 'data': [ 'one', 'two' ] }

0
tests/qapi-schema/doc-bad-section.out
View File

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

@ -8,7 +8,9 @@
'documentation-exceptions': [ 'Enum', 'Variant1', 'Alternate', 'cmd' ] } }
##
# = Section
# *******
# Section
# *******
##
##
@ -16,7 +18,8 @@
##
##
# == Subsection
# Subsection
# ==========
#
# *with emphasis*
# @var {in braces}
@ -144,7 +147,8 @@
'if': { 'not': { 'any': [ 'IFONE', 'IFTWO' ] } } }
##
# == Another subsection
# Another subsection
# ==================
##
##

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

@ -55,13 +55,16 @@ event EVT_BOXED Object
feature feat3
doc freeform
body=
= Section
*******
Section
*******
doc freeform
body=
Just text, no heading.
doc freeform
body=
== Subsection
Subsection
==========
*with emphasis*
@var {in braces}
@ -155,7 +158,8 @@ description starts on the same line
a feature
doc freeform
body=
== Another subsection
Another subsection
==================
doc symbol=cmd
body=

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

@ -1,6 +1,8 @@
Section
*******
Just text, no heading.
Subsection
==========
@ -35,249 +37,145 @@ Example:
-> in <- out Examples: - *verbatim* - {braces}
Enum Enum
*Availability*: "IFCOND"
"Enum" (Enum)
-------------
Values:
* **one** -- The _one_ {and only}, description on the same line
* **two** -- Not documented
Values
~~~~~~
Features:
* **enum-feat** -- Also _one_ {and only}
"one" (**If: **"IFONE")
The _one_ {and only}, description on the same line
* **enum-member-feat** -- a member feature
"two"
Not documented
"two" is undocumented
Object Base
*Availability*: "IFALL1 and IFALL2"
Features
~~~~~~~~
Members:
* **base1** ("Enum") -- description starts on a new line,
minimally indented
"enum-feat"
Also _one_ {and only}
Object Variant1
"enum-member-feat"
a member feature
A paragraph
"two" is undocumented
Another paragraph
"var1" is undocumented
If
~~
Members:
* **var1** ("string") -- Not documented
"IFCOND"
Features:
* **variant1-feat** -- a feature
* **member-feat** -- a member feature
"Base" (Object)
---------------
Object Variant2
Object Object
Members
~~~~~~~
Members:
* The members of "Base".
"base1": "Enum"
description starts on a new line, minimally indented
* When "base1" is "one": The members of "Variant1".
* When "base1" is "two": The members of "Variant2".
If
~~
Features:
* **union-feat1** -- a feature
"IFALL1 and IFALL2"
Alternate Alternate
*Availability*: "not (IFONE or IFTWO)"
Alternatives:
* **i** ("int") -- description starts on the same line remainder
indented the same "b" is undocumented
"Variant1" (Object)
-------------------
* **b** ("boolean") -- Not documented
A paragraph
Another paragraph
"var1" is undocumented
Members
~~~~~~~
"var1": "string" (**If: **"IFSTR")
Not documented
Features
~~~~~~~~
"variant1-feat"
a feature
"member-feat"
a member feature
"Variant2" (Object)
-------------------
"Object" (Object)
-----------------
Members
~~~~~~~
The members of "Base"
The members of "Variant1" when "base1" is ""one""
The members of "Variant2" when "base1" is ""two"" (**If: **"IFONE or
IFTWO")
Features
~~~~~~~~
"union-feat1"
a feature
"Alternate" (Alternate)
-----------------------
Members
~~~~~~~
"i": "int"
description starts on the same line remainder indented the same "b"
is undocumented
"b": "boolean"
Not documented
Features
~~~~~~~~
"alt-feat"
a feature
If
~~
"not (IFONE or IFTWO)"
Features:
* **alt-feat** -- a feature
Another subsection
==================
Command cmd (Since: 2.10)
"cmd" (Command)
---------------
Arguments:
* **arg1** ("int") -- description starts on a new line, indented
* **arg2** ("string", *optional*) -- description starts on the
same line remainder indented differently
Arguments
~~~~~~~~~
* **arg3** ("boolean") -- Not documented
"arg1": "int"
description starts on a new line, indented
Features:
* **cmd-feat1** -- a feature
"arg2": "string" (optional)
description starts on the same line remainder indented differently
* **cmd-feat2** -- another feature
"arg3": "boolean"
Not documented
Note:
"arg3" is undocumented
Features
~~~~~~~~
Return:
"Object" -- "Object"
"cmd-feat1"
a feature
Errors:
some
"cmd-feat2"
another feature
Notes:
Note:
* Lorem ipsum dolor sit amet
"arg3" is undocumented
* Ut enim ad minim veniam
Duis aute irure dolor
Returns
~~~~~~~
Example: Ideal fast-food burger situation:
"Object"
-> "in"
<- "out"
Examples:
Errors
~~~~~~
- Not a QMP code block
- Merely a preformatted code block literal
It isn't even an rST list.
- *verbatim*
- {braces}
some
Note::
Ceci n'est pas une note
Notes:
Command cmd-boxed
* Lorem ipsum dolor sit amet
If you're bored enough to read this, go see a video of boxed cats
* Ut enim ad minim veniam
Arguments:
* The members of "Object".
Duis aute irure dolor
Features:
* **cmd-feat1** -- a feature
Example: Ideal fast-food burger situation:
* **cmd-feat2** -- another feature
-> "in"
<- "out"
Example::
Examples:
-> "this example"
- Not a QMP code block
- Merely a preformatted code block literal
It isn't even an rST list.
- *verbatim*
- {braces}
<- ... has no title ...
Note::
Ceci n'est pas une note
Event EVT_BOXED
Members:
* The members of "Object".
Since
~~~~~
2.10
"cmd-boxed" (Command)
---------------------
If you're bored enough to read this, go see a video of boxed cats
Arguments
~~~~~~~~~
The members of "Object"
Features
~~~~~~~~
"cmd-feat1"
a feature
"cmd-feat2"
another feature
Example::
-> "this example"
<- ... has no title ...
"EVT_BOXED" (Event)
-------------------
Arguments
~~~~~~~~~
The members of "Object"
Features
~~~~~~~~
"feat3"
a feature
Features:
* **feat3** -- a feature

1
tests/qapi-schema/meson.build
View File

@ -61,7 +61,6 @@ schemas = [
'doc-bad-event-arg.json',
'doc-bad-feature.json',
'doc-bad-indent.json',
'doc-bad-section.json',
'doc-bad-symbol.json',
'doc-bad-union-member.json',
'doc-before-include.json',