* [PULL 01/32] docs/sphinx: adjust qapidoc to cope with same-line error sections
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 02/32] docs/sphinx: parse @references in freeform text Markus Armbruster
` (31 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
Without this, the line the new QAPI doc generator chokes on
# Errors: some
in doc-good.json. We still use the old doc generator for the tests,
but we're about to correct that.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250618165353.1980365-2-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Fixes: e9fbf1a0c6c2 (docs/qapidoc: add visit_errors() method)
[Amend commit message to point to reproducer, and add Fixes:]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
docs/sphinx/qapidoc.py | 12 ++++++++----
1 file changed, 8 insertions(+), 4 deletions(-)
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 8011ac9efa..5374dee8fa 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -267,10 +267,14 @@ def visit_returns(self, section: QAPIDoc.Section) -> None:
self.add_field("return", typ, section.text, 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:
"""
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 02/32] docs/sphinx: parse @references in freeform text
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
2025-07-14 13:44 ` [PULL 01/32] docs/sphinx: adjust qapidoc to cope with same-line error sections Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 03/32] docs/sphinx: remove legacy QAPI manual generator Markus Armbruster
` (30 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
Oversight in the new qapidoc transmogrifier: @references in freeform
documentation blocks were not being transformed to literals. This fixes
that, and the next patch ensures that we're testing for this O:-)
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250618165353.1980365-3-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
docs/sphinx/qapidoc.py | 10 +++++++---
1 file changed, 7 insertions(+), 3 deletions(-)
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 5374dee8fa..adc14ade45 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -218,6 +218,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:
@@ -361,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)
@@ -405,7 +409,7 @@ def visit_freeform(self, doc: QAPIDoc) -> None:
assert len(doc.all_sections) == 1, doc.all_sections
body = doc.all_sections[0]
- text = body.text
+ text = self.reformat_arobase(body.text)
info = doc.info
if re.match(r"=+ ", text):
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 03/32] docs/sphinx: remove legacy QAPI manual generator
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
2025-07-14 13:44 ` [PULL 01/32] docs/sphinx: adjust qapidoc to cope with same-line error sections Markus Armbruster
2025-07-14 13:44 ` [PULL 02/32] docs/sphinx: parse @references in freeform text Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 04/32] docs/sphinx: remove special parsing for freeform sections Markus Armbruster
` (29 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
Thanks for your service!
Remove the old qapidoc and the option to enable the transmogrifier,
leaving the "transmogrifier" as the ONLY qapi doc generator. This in
effect also converts the QAPI test to use the new documentation
generator, too.
Update doc-good.txt output to match the new doc generator, which I
should've done exactly when we switched over to the transmogrifier, but,
uhh, oops!
Notes on the new format:
1. per-member IFCOND documentation is missing. Known issue.
2. Freeform documentation without a header is now copied through into
the output. This is a bug fix.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250618165353.1980365-4-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Fixes: b61a4eb3f32 (docs/qapidoc: support header-less freeform sections)
[Tweak commit message to say it's a bug fix, add Fixes:]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
docs/interop/qemu-ga-ref.rst | 1 -
docs/interop/qemu-qmp-ref.rst | 1 -
docs/interop/qemu-storage-daemon-qmp-ref.rst | 1 -
docs/sphinx/qapidoc.py | 25 +-
docs/sphinx/qapidoc_legacy.py | 440 -------------------
python/tests/qapi-isort.sh | 2 +-
tests/qapi-schema/doc-good.txt | 274 ++++--------
7 files changed, 88 insertions(+), 656 deletions(-)
delete mode 100644 docs/sphinx/qapidoc_legacy.py
diff --git a/docs/interop/qemu-ga-ref.rst b/docs/interop/qemu-ga-ref.rst
index 25f6e24b03..ea6652ae43 100644
--- a/docs/interop/qemu-ga-ref.rst
+++ b/docs/interop/qemu-ga-ref.rst
@@ -2,5 +2,4 @@ QEMU Guest Agent Protocol Reference
===================================
.. qapi-doc:: qga/qapi-schema.json
- :transmogrify:
:namespace: QGA
diff --git a/docs/interop/qemu-qmp-ref.rst b/docs/interop/qemu-qmp-ref.rst
index 3bc1ca12b1..f0ce39ad67 100644
--- a/docs/interop/qemu-qmp-ref.rst
+++ b/docs/interop/qemu-qmp-ref.rst
@@ -7,5 +7,4 @@ QEMU QMP Reference Manual
:local:
.. qapi-doc:: qapi/qapi-schema.json
- :transmogrify:
:namespace: QMP
diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst
index dc7bde262a..4dbb6a2cc8 100644
--- a/docs/interop/qemu-storage-daemon-qmp-ref.rst
+++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst
@@ -5,5 +5,4 @@ QEMU Storage Daemon QMP Reference Manual
:local:
.. qapi-doc:: storage-daemon/qapi/qapi-schema.json
- :transmogrify:
:namespace: QSD
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index adc14ade45..d5d2b5eeb5 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -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 (
@@ -512,15 +510,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()
@@ -598,21 +590,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)
@@ -625,11 +606,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
diff --git a/docs/sphinx/qapidoc_legacy.py b/docs/sphinx/qapidoc_legacy.py
deleted file mode 100644
index 13520f4c26..0000000000
--- a/docs/sphinx/qapidoc_legacy.py
+++ /dev/null
@@ -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
diff --git a/python/tests/qapi-isort.sh b/python/tests/qapi-isort.sh
index 78dd947f68..067c16d5d9 100755
--- a/python/tests/qapi-isort.sh
+++ b/python/tests/qapi-isort.sh
@@ -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
diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt
index 17a1d56ef1..74b73681d3 100644
--- a/tests/qapi-schema/doc-good.txt
+++ b/tests/qapi-schema/doc-good.txt
@@ -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
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 04/32] docs/sphinx: remove special parsing for freeform sections
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (2 preceding siblings ...)
2025-07-14 13:44 ` [PULL 03/32] docs/sphinx: remove legacy QAPI manual generator Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 05/32] qapi: lift restriction on using '=' in doc blocks Markus Armbruster
` (28 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
Remove the QAPI doc section heading syntax, use plain rST section
headings instead.
Tests and documentation are updated to match.
Interestingly, Plain rST headings work fine before this patch, except
for over- and underlining with '=', which the doc parser rejected as
invalid QAPI doc section heading in free-form comments.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250618165353.1980365-5-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Add more detail to commit message]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
docs/devel/qapi-code-gen.rst | 28 ++++++++++++++-------
docs/interop/firmware.json | 4 ++-
docs/interop/vhost-user.json | 4 ++-
docs/sphinx/qapidoc.py | 37 +---------------------------
qapi/acpi.json | 4 ++-
qapi/audio.json | 4 ++-
qapi/authz.json | 4 ++-
qapi/block-core.json | 3 ++-
qapi/block-export.json | 3 ++-
qapi/block.json | 7 ++++--
qapi/char.json | 4 ++-
qapi/common.json | 4 ++-
qapi/compat.json | 4 ++-
qapi/control.json | 4 ++-
qapi/crypto.json | 4 ++-
qapi/cryptodev.json | 4 ++-
qapi/cxl.json | 4 ++-
qapi/dump.json | 4 ++-
qapi/ebpf.json | 4 ++-
qapi/error.json | 4 ++-
qapi/introspect.json | 4 ++-
qapi/job.json | 4 ++-
qapi/machine-common.json | 4 ++-
qapi/machine.json | 4 ++-
qapi/migration.json | 4 ++-
qapi/misc.json | 4 ++-
qapi/net.json | 4 ++-
qapi/pci.json | 4 ++-
qapi/qapi-schema.json | 4 ++-
qapi/qdev.json | 4 ++-
qapi/qom.json | 4 ++-
qapi/replay.json | 4 ++-
qapi/rocker.json | 4 ++-
qapi/run-state.json | 4 ++-
qapi/sockets.json | 4 ++-
qapi/stats.json | 4 ++-
qapi/tpm.json | 4 ++-
qapi/trace.json | 4 ++-
qapi/transaction.json | 4 ++-
qapi/uefi.json | 4 ++-
qapi/ui.json | 14 ++++++++---
qapi/vfio.json | 4 ++-
qapi/virtio.json | 4 ++-
qapi/yank.json | 4 ++-
scripts/qapi/parser.py | 7 ------
storage-daemon/qapi/qapi-schema.json | 8 ++++--
tests/qapi-schema/doc-good.json | 10 +++++---
tests/qapi-schema/doc-good.out | 10 +++++---
48 files changed, 173 insertions(+), 106 deletions(-)
diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index 231cc0fecf..dfdbeac5a5 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -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
diff --git a/docs/interop/firmware.json b/docs/interop/firmware.json
index 745d21d822..f46fdedfa8 100644
--- a/docs/interop/firmware.json
+++ b/docs/interop/firmware.json
@@ -11,7 +11,9 @@
# later. See the COPYING file in the top-level directory.
##
-# = Firmware
+# ********
+# Firmware
+# ********
##
{ 'pragma': {
diff --git a/docs/interop/vhost-user.json b/docs/interop/vhost-user.json
index b6ade9e493..095eb99cf7 100644
--- a/docs/interop/vhost-user.json
+++ b/docs/interop/vhost-user.json
@@ -10,7 +10,9 @@
# later. See the COPYING file in the top-level directory.
##
-# = vhost user backend discovery & capabilities
+# *******************************************
+# vhost user backend discovery & capabilities
+# *******************************************
##
##
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index d5d2b5eeb5..b794cde697 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -399,44 +399,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 = self.reformat_arobase(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:
diff --git a/qapi/acpi.json b/qapi/acpi.json
index 2d53b82365..90f8f564fd 100644
--- a/qapi/acpi.json
+++ b/qapi/acpi.json
@@ -6,7 +6,9 @@
# SPDX-License-Identifier: GPL-2.0-or-later
##
-# = ACPI
+# ****
+# ACPI
+# ****
##
##
diff --git a/qapi/audio.json b/qapi/audio.json
index 16de231f6d..6a22ca384a 100644
--- a/qapi/audio.json
+++ b/qapi/audio.json
@@ -7,7 +7,9 @@
# See the COPYING file in the top-level directory.
##
-# = Audio
+# *****
+# Audio
+# *****
##
##
diff --git a/qapi/authz.json b/qapi/authz.json
index 7fc6e3032e..ad1b4b3af0 100644
--- a/qapi/authz.json
+++ b/qapi/authz.json
@@ -2,7 +2,9 @@
# vim: filetype=python
##
-# = User authorization
+# ******************
+# User authorization
+# ******************
##
##
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 1df6644f0d..8b413946ff 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -2,7 +2,8 @@
# vim: filetype=python
##
-# == Block core (VM unrelated)
+# Block core (VM unrelated)
+# =========================
##
{ 'include': 'common.json' }
diff --git a/qapi/block-export.json b/qapi/block-export.json
index ed4deb54db..2241bfecf2 100644
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -2,7 +2,8 @@
# vim: filetype=python
##
-# == Block device exports
+# Block device exports
+# ====================
##
{ 'include': 'sockets.json' }
diff --git a/qapi/block.json b/qapi/block.json
index 1490a1a17f..2d54a81c36 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -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)
+# ===================================
##
##
diff --git a/qapi/char.json b/qapi/char.json
index df6e325e2e..f38d04986d 100644
--- a/qapi/char.json
+++ b/qapi/char.json
@@ -3,7 +3,9 @@
#
##
-# = Character devices
+# *****************
+# Character devices
+# *****************
##
{ 'include': 'sockets.json' }
diff --git a/qapi/common.json b/qapi/common.json
index 0e3a0bbbfb..af7e3d618a 100644
--- a/qapi/common.json
+++ b/qapi/common.json
@@ -2,7 +2,9 @@
# vim: filetype=python
##
-# = Common data types
+# *****************
+# Common data types
+# *****************
##
##
diff --git a/qapi/compat.json b/qapi/compat.json
index 42034d9368..90b8d51cf2 100644
--- a/qapi/compat.json
+++ b/qapi/compat.json
@@ -2,7 +2,9 @@
# vim: filetype=python
##
-# = Compatibility policy
+# ********************
+# Compatibility policy
+# ********************
##
##
diff --git a/qapi/control.json b/qapi/control.json
index 34b733f63b..ab0b3a3bbe 100644
--- a/qapi/control.json
+++ b/qapi/control.json
@@ -3,7 +3,9 @@
#
##
-# = QMP monitor control
+# *******************
+# QMP monitor control
+# *******************
##
##
diff --git a/qapi/crypto.json b/qapi/crypto.json
index 9ec6301e18..21006de36c 100644
--- a/qapi/crypto.json
+++ b/qapi/crypto.json
@@ -3,7 +3,9 @@
#
##
-# = Cryptography
+# ************
+# Cryptography
+# ************
##
##
diff --git a/qapi/cryptodev.json b/qapi/cryptodev.json
index b13db26403..1f49e1822c 100644
--- a/qapi/cryptodev.json
+++ b/qapi/cryptodev.json
@@ -5,7 +5,9 @@
# See the COPYING file in the top-level directory.
##
-# = Cryptography devices
+# ********************
+# Cryptography devices
+# ********************
##
##
diff --git a/qapi/cxl.json b/qapi/cxl.json
index 8f2e9237b1..52cc5d4f33 100644
--- a/qapi/cxl.json
+++ b/qapi/cxl.json
@@ -2,7 +2,9 @@
# vim: filetype=python
##
-# = CXL devices
+# ***********
+# CXL devices
+# ***********
##
##
diff --git a/qapi/dump.json b/qapi/dump.json
index d0ba1f0596..0642ca157b 100644
--- a/qapi/dump.json
+++ b/qapi/dump.json
@@ -5,7 +5,9 @@
# See the COPYING file in the top-level directory.
##
-# = Dump guest memory
+# *****************
+# Dump guest memory
+# *****************
##
##
diff --git a/qapi/ebpf.json b/qapi/ebpf.json
index db19ae850f..d45054e666 100644
--- a/qapi/ebpf.json
+++ b/qapi/ebpf.json
@@ -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
diff --git a/qapi/error.json b/qapi/error.json
index 135c1e8231..54cb02fb88 100644
--- a/qapi/error.json
+++ b/qapi/error.json
@@ -2,7 +2,9 @@
# vim: filetype=python
##
-# = QMP errors
+# **********
+# QMP errors
+# **********
##
##
diff --git a/qapi/introspect.json b/qapi/introspect.json
index e9e0297282..26d8839f19 100644
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -10,7 +10,9 @@
# See the COPYING file in the top-level directory.
##
-# = QMP introspection
+# *****************
+# QMP introspection
+# *****************
##
##
diff --git a/qapi/job.json b/qapi/job.json
index 126fa5ce60..16b280f52f 100644
--- a/qapi/job.json
+++ b/qapi/job.json
@@ -2,7 +2,9 @@
# vim: filetype=python
##
-# = Background jobs
+# ***************
+# Background jobs
+# ***************
##
##
diff --git a/qapi/machine-common.json b/qapi/machine-common.json
index 298e51f373..0f01599130 100644
--- a/qapi/machine-common.json
+++ b/qapi/machine-common.json
@@ -5,7 +5,9 @@
# See the COPYING file in the top-level directory.
##
-# = Common machine types
+# ********************
+# Common machine types
+# ********************
##
##
diff --git a/qapi/machine.json b/qapi/machine.json
index f712e7da6d..af00a20b1f 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -5,7 +5,9 @@
# See the COPYING file in the top-level directory.
##
-# = Machines
+# ********
+# Machines
+# ********
##
{ 'include': 'common.json' }
diff --git a/qapi/migration.json b/qapi/migration.json
index 2d39a8f748..3bf97df5d8 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -3,7 +3,9 @@
#
##
-# = Migration
+# *********
+# Migration
+# *********
##
{ 'include': 'common.json' }
diff --git a/qapi/misc.json b/qapi/misc.json
index 4b9e601cfa..a180c16db2 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -3,7 +3,9 @@
#
##
-# = Miscellanea
+# ***********
+# Miscellanea
+# ***********
##
{ 'include': 'common.json' }
diff --git a/qapi/net.json b/qapi/net.json
index 97ea183981..3b03843c16 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -3,7 +3,9 @@
#
##
-# = Net devices
+# ***********
+# Net devices
+# ***********
##
{ 'include': 'sockets.json' }
diff --git a/qapi/pci.json b/qapi/pci.json
index dc85a41d28..a8671cd9ac 100644
--- a/qapi/pci.json
+++ b/qapi/pci.json
@@ -6,7 +6,9 @@
# SPDX-License-Identifier: GPL-2.0-or-later
##
-# = PCI
+# ***
+# PCI
+# ***
##
##
diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json
index a8f66163cb..49b9a0267d 100644
--- a/qapi/qapi-schema.json
+++ b/qapi/qapi-schema.json
@@ -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).
diff --git a/qapi/qdev.json b/qapi/qdev.json
index 32c7d10046..441ed518b8 100644
--- a/qapi/qdev.json
+++ b/qapi/qdev.json
@@ -5,7 +5,9 @@
# See the COPYING file in the top-level directory.
##
-# = Device infrastructure (qdev)
+# ****************************
+# Device infrastructure (qdev)
+# ****************************
##
{ 'include': 'qom.json' }
diff --git a/qapi/qom.json b/qapi/qom.json
index b133b06447..f68f72fbbc 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -10,7 +10,9 @@
{ 'include': 'crypto.json' }
##
-# = QEMU Object Model (QOM)
+# ***********************
+# QEMU Object Model (QOM)
+# ***********************
##
##
diff --git a/qapi/replay.json b/qapi/replay.json
index 35e0c4a692..e46c5c1d3f 100644
--- a/qapi/replay.json
+++ b/qapi/replay.json
@@ -3,7 +3,9 @@
#
##
-# = Record/replay
+# *************
+# Record/replay
+# *************
##
{ 'include': 'common.json' }
diff --git a/qapi/rocker.json b/qapi/rocker.json
index 0c7ef1f77c..e494964952 100644
--- a/qapi/rocker.json
+++ b/qapi/rocker.json
@@ -2,7 +2,9 @@
# vim: filetype=python
##
-# = Rocker switch device
+# ********************
+# Rocker switch device
+# ********************
##
##
diff --git a/qapi/run-state.json b/qapi/run-state.json
index fd09beb35c..083a3c5eb3 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -3,7 +3,9 @@
#
##
-# = VM run state
+# ************
+# VM run state
+# ************
##
##
diff --git a/qapi/sockets.json b/qapi/sockets.json
index f9f559daba..b5f4a8fecd 100644
--- a/qapi/sockets.json
+++ b/qapi/sockets.json
@@ -2,7 +2,9 @@
# vim: filetype=python
##
-# = Socket data types
+# *****************
+# Socket data types
+# *****************
##
##
diff --git a/qapi/stats.json b/qapi/stats.json
index 8902ef94e0..78b88881ea 100644
--- a/qapi/stats.json
+++ b/qapi/stats.json
@@ -9,7 +9,9 @@
# SPDX-License-Identifier: GPL-2.0-or-later
##
-# = Statistics
+# **********
+# Statistics
+# **********
##
##
diff --git a/qapi/tpm.json b/qapi/tpm.json
index a16a72edb9..e66b107f1d 100644
--- a/qapi/tpm.json
+++ b/qapi/tpm.json
@@ -3,7 +3,9 @@
#
##
-# = TPM (trusted platform module) devices
+# *************************************
+# TPM (trusted platform module) devices
+# *************************************
##
##
diff --git a/qapi/trace.json b/qapi/trace.json
index eb5f63f513..d08c9c6a88 100644
--- a/qapi/trace.json
+++ b/qapi/trace.json
@@ -7,7 +7,9 @@
# See the COPYING file in the top-level directory.
##
-# = Tracing
+# *******
+# Tracing
+# *******
##
##
diff --git a/qapi/transaction.json b/qapi/transaction.json
index 9d9e7af26c..927035f5a7 100644
--- a/qapi/transaction.json
+++ b/qapi/transaction.json
@@ -3,7 +3,9 @@
#
##
-# = Transactions
+# ************
+# Transactions
+# ************
##
{ 'include': 'block-core.json' }
diff --git a/qapi/uefi.json b/qapi/uefi.json
index 6592183d6c..a206c2e953 100644
--- a/qapi/uefi.json
+++ b/qapi/uefi.json
@@ -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.
diff --git a/qapi/ui.json b/qapi/ui.json
index 514fa159b1..f5e77ae19d 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -3,7 +3,9 @@
#
##
-# = Remote desktop
+# **************
+# Remote desktop
+# **************
##
{ 'include': 'common.json' }
@@ -200,7 +202,8 @@
'if': 'CONFIG_PIXMAN' }
##
-# == Spice
+# Spice
+# =====
##
##
@@ -461,7 +464,8 @@
'if': 'CONFIG_SPICE' }
##
-# == VNC
+# VNC
+# ===
##
##
@@ -794,7 +798,9 @@
'if': 'CONFIG_VNC' }
##
-# = Input
+# *****
+# Input
+# *****
##
##
diff --git a/qapi/vfio.json b/qapi/vfio.json
index b53b7caecd..a1a9c5b673 100644
--- a/qapi/vfio.json
+++ b/qapi/vfio.json
@@ -3,7 +3,9 @@
#
##
-# = VFIO devices
+# ************
+# VFIO devices
+# ************
##
##
diff --git a/qapi/virtio.json b/qapi/virtio.json
index 73df718a26..3cac0774f7 100644
--- a/qapi/virtio.json
+++ b/qapi/virtio.json
@@ -3,7 +3,9 @@
#
##
-# = Virtio devices
+# **************
+# Virtio devices
+# **************
##
##
diff --git a/qapi/yank.json b/qapi/yank.json
index 30f46c97c9..d13a8e9117 100644
--- a/qapi/yank.json
+++ b/qapi/yank.json
@@ -3,7 +3,9 @@
#
##
-# = Yank feature
+# ************
+# Yank feature
+# ************
##
##
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index 949d9e8bff..aad7e249f8 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -597,22 +597,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()
diff --git a/storage-daemon/qapi/qapi-schema.json b/storage-daemon/qapi/qapi-schema.json
index 0427594c98..478e7a92b2 100644
--- a/storage-daemon/qapi/qapi-schema.json
+++ b/storage-daemon/qapi/qapi-schema.json
@@ -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' }
diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
index 14b808f909..fac13425b7 100644
--- a/tests/qapi-schema/doc-good.json
+++ b/tests/qapi-schema/doc-good.json
@@ -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
+# ==================
##
##
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index dc8352eed4..04a5507264 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -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=
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 05/32] qapi: lift restriction on using '=' in doc blocks
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (3 preceding siblings ...)
2025-07-14 13:44 ` [PULL 04/32] docs/sphinx: remove special parsing for freeform sections Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 06/32] qapi: Clean up "This command will do ..." command descriptions Markus Armbruster
` (27 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
We reject lines starting with '=' in definition documentation. This
made sense when such lines were headings in free-form documentation,
but not in definition documentation.
Before the previous commit, lines starting with '=' were headings in
free-form documentation, and rejected in definition documentation,
where such headings could not work.
The previous commit dropped the headings feature from free-form
documentation, because we can simply use plain rST headings.
Rejecting them in definition documentation no longer makes sense, so
drop that, too.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250618165353.1980365-6-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Amend commit message to explain why]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
scripts/qapi/parser.py | 4 ----
tests/qapi-schema/doc-bad-section.err | 1 -
tests/qapi-schema/doc-bad-section.json | 10 ----------
tests/qapi-schema/doc-bad-section.out | 0
tests/qapi-schema/meson.build | 1 -
5 files changed, 16 deletions(-)
delete mode 100644 tests/qapi-schema/doc-bad-section.err
delete mode 100644 tests/qapi-schema/doc-bad-section.json
delete mode 100644 tests/qapi-schema/doc-bad-section.out
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index aad7e249f8..d43a123cd7 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -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)
diff --git a/tests/qapi-schema/doc-bad-section.err b/tests/qapi-schema/doc-bad-section.err
deleted file mode 100644
index 785cacc08c..0000000000
--- a/tests/qapi-schema/doc-bad-section.err
+++ /dev/null
@@ -1 +0,0 @@
-doc-bad-section.json:5:1: unexpected '=' markup in definition documentation
diff --git a/tests/qapi-schema/doc-bad-section.json b/tests/qapi-schema/doc-bad-section.json
deleted file mode 100644
index 8175d95867..0000000000
--- a/tests/qapi-schema/doc-bad-section.json
+++ /dev/null
@@ -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' ] }
diff --git a/tests/qapi-schema/doc-bad-section.out b/tests/qapi-schema/doc-bad-section.out
deleted file mode 100644
index e69de29bb2..0000000000
diff --git a/tests/qapi-schema/meson.build b/tests/qapi-schema/meson.build
index 9577178b6f..c47025d16d 100644
--- a/tests/qapi-schema/meson.build
+++ b/tests/qapi-schema/meson.build
@@ -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',
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 06/32] qapi: Clean up "This command will do ..." command descriptions
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (4 preceding siblings ...)
2025-07-14 13:44 ` [PULL 05/32] qapi: lift restriction on using '=' in doc blocks Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 07/32] qapi: Clean up a few Errors: sections Markus Armbruster
` (26 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, Daniel P. Berrangé
Use imperative mood "Do ..." instead.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250708072828.105185-2-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
---
qapi/control.json | 9 +++++----
qapi/misc-i386.json | 11 +++++------
qapi/qom.json | 10 ++++------
3 files changed, 14 insertions(+), 16 deletions(-)
diff --git a/qapi/control.json b/qapi/control.json
index ab0b3a3bbe..5fed0701f8 100644
--- a/qapi/control.json
+++ b/qapi/control.json
@@ -160,10 +160,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
#
diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json
index 5fefa0a484..b53ed39288 100644
--- a/qapi/misc-i386.json
+++ b/qapi/misc-i386.json
@@ -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
@@ -233,8 +233,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 +271,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
diff --git a/qapi/qom.json b/qapi/qom.json
index f68f72fbbc..6c38e865a6 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -50,8 +50,7 @@
##
# @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
# description of this parameter.
@@ -78,8 +77,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.
@@ -130,7 +128,7 @@
##
# @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
#
@@ -173,7 +171,7 @@
##
# @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
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 07/32] qapi: Clean up a few Errors: sections
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (5 preceding siblings ...)
2025-07-14 13:44 ` [PULL 06/32] qapi: Clean up "This command will do ..." command descriptions Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 08/32] docs/qapi-domain: add return-nodesc Markus Armbruster
` (25 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, Daniel P. Berrangé
Use the conventional "- If <error-condition>" phrasing, optionally
with ", <error-class>".
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250708072828.105185-3-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
---
qapi/misc-i386.json | 7 +++----
qapi/qom.json | 4 ++--
2 files changed, 5 insertions(+), 6 deletions(-)
diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json
index b53ed39288..24a2e143f6 100644
--- a/qapi/misc-i386.json
+++ b/qapi/misc-i386.json
@@ -283,10 +283,9 @@
# 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
#
diff --git a/qapi/qom.json b/qapi/qom.json
index 6c38e865a6..fbf94b9e09 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -1261,7 +1261,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
#
@@ -1283,7 +1283,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
#
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 08/32] docs/qapi-domain: add return-nodesc
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (6 preceding siblings ...)
2025-07-14 13:44 ` [PULL 07/32] qapi: Clean up a few Errors: sections Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 09/32] qapi: Fix undocumented return values by generating something Markus Armbruster
` (24 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
This form is used to annotate a return type without an accompanying
description, for when there is no "Returns:" information in the source
doc, but we have a return type we want to generate a cross-reference to.
The syntax is:
:return-nodesc: TypeName
It's primarily necessary because Sphinx always expects both a type and a
description for the prior form and will format it accordingly. To have a
reasonable rendering when the body is missing, we need to use a
different info field list entirely.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711051045.51110-2-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
[Long line wrapped]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
docs/devel/qapi-domain.rst | 31 +++++++++++++++++++++++++++++++
docs/sphinx/qapi_domain.py | 8 ++++++++
2 files changed, 39 insertions(+)
diff --git a/docs/devel/qapi-domain.rst b/docs/devel/qapi-domain.rst
index 11238723c2..b71890f660 100644
--- a/docs/devel/qapi-domain.rst
+++ b/docs/devel/qapi-domain.rst
@@ -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:``
-----------
diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py
index ebc46a72c6..f561dc465f 100644
--- a/docs/sphinx/qapi_domain.py
+++ b/docs/sphinx/qapi_domain.py
@@ -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,
+ ),
]
)
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 09/32] qapi: Fix undocumented return values by generating something
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (7 preceding siblings ...)
2025-07-14 13:44 ` [PULL 08/32] docs/qapi-domain: add return-nodesc Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 10/32] qapi: remove trivial "Returns:" sections Markus Armbruster
` (23 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
Generated command documentation lacks information on return value in
several cases, e.g. query-tpm.
The obvious fix would be to require a Returns: section when a command
returns something.
However, note that many existing Returns: sections are pretty useless:
the description is basically the return type, which then gets rendered
like "Return: <Type> – <basically the return type>". This suggests
that a description is often not really necessary, and requiring one
isn't useful.
Instead, generate the obvious minimal thing when Returns: is absent:
"Return: <Type>".
This auto-generated Return documentation is placed is as follows:
1. If we have arguments, return goes right after them.
2. Else if we have errors, return goes right before them.
3. Else if we have features, return goes right before them.
4. Else return goes right after the intro
To facilitate this algorithm, a "TODO:" hack line is used to separate
the intro from the remainder of the documentation block in cases where
there are no other sections to separate the intro from e.g. examples and
additional detail meant to appear below the key sections of interest.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711051045.51110-3-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[_insert_near_kind() code replaced by something simpler, commit
message amended to explain why we're doing this]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
docs/sphinx/qapidoc.py | 14 ++++++++------
qapi/machine.json | 2 ++
scripts/qapi/parser.py | 37 +++++++++++++++++++++++++++++++++++++
scripts/qapi/schema.py | 3 +++
4 files changed, 50 insertions(+), 6 deletions(-)
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index b794cde697..c2f09bac16 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -258,16 +258,18 @@ 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:
# If the section text does not start with a space, it means text
diff --git a/qapi/machine.json b/qapi/machine.json
index af00a20b1f..2d6a137f21 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -1303,6 +1303,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" }
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index d43a123cd7..2529edf81a 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -804,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:
diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py
index cbe3b5aa91..3abddea352 100644
--- a/scripts/qapi/schema.py
+++ b/scripts/qapi/schema.py
@@ -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(
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 10/32] qapi: remove trivial "Returns:" sections
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (8 preceding siblings ...)
2025-07-14 13:44 ` [PULL 09/32] qapi: Fix undocumented return values by generating something Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 11/32] qapi: rephrase return docs to avoid type name Markus Armbruster
` (22 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
The new qapidoc.py can generate "Returns" statements with type
information just fine, so we can remove it from the source where it
doesn't add anything particularly novel or helpful and just repeats the
type info.
This patch is fairly "gentle" and doesn't aggressively touch other
"Returns" lines that could be rephrased to omit repeating type
information; it only removes lines that appear appropriate to wholly
remove.
To help facilitate auto-generated placement, a few doc blocks have a
"TODO:" line inserted to help the placement algorithm differentiate the
introductory paragraph(s) from the rest of the documentation.
The auto-generated returns are in the exact same spot, except for
query-migrationthreads, query-machines, and
x-query-virtio-queue-element. These auto-generation moves to a better
spot.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711051045.51110-4-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Two more Returns: removed, commit message amended to explain
auto-generated returns generated into a different spot]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/audio.json | 2 --
qapi/block-core.json | 8 --------
qapi/char.json | 8 --------
qapi/cryptodev.json | 2 --
qapi/machine.json | 24 ------------------------
qapi/migration.json | 12 ++----------
qapi/misc-arm.json | 2 --
qapi/misc-i386.json | 10 ----------
qapi/misc.json | 7 -------
qapi/rocker.json | 4 ----
qapi/run-state.json | 2 --
qapi/tpm.json | 4 ----
qapi/ui.json | 8 --------
qapi/virtio.json | 2 --
qapi/yank.json | 2 +-
15 files changed, 3 insertions(+), 94 deletions(-)
diff --git a/qapi/audio.json b/qapi/audio.json
index 6a22ca384a..53142080f7 100644
--- a/qapi/audio.json
+++ b/qapi/audio.json
@@ -537,8 +537,6 @@
#
# Return information about audiodev configuration
#
-# Returns: array of @Audiodev
-#
# Since: 8.0
##
{ 'command': 'query-audiodevs',
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 8b413946ff..01bf41b8b0 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1951,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::
@@ -2465,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
@@ -6203,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
diff --git a/qapi/char.json b/qapi/char.json
index f38d04986d..f0a53f742c 100644
--- a/qapi/char.json
+++ b/qapi/char.json
@@ -38,8 +38,6 @@
#
# Return information about current character devices.
#
-# Returns: a list of @ChardevInfo
-#
# Since: 0.14
#
# .. qmp-example::
@@ -84,8 +82,6 @@
#
# Return information about character device backends.
#
-# Returns: a list of @ChardevBackendInfo
-#
# Since: 2.0
#
# .. qmp-example::
@@ -774,8 +770,6 @@
#
# @backend: backend type and parameters
#
-# Returns: ChardevReturn.
-#
# Since: 1.4
#
# .. qmp-example::
@@ -814,8 +808,6 @@
#
# @backend: new backend type and parameters
#
-# Returns: ChardevReturn.
-#
# Since: 2.10
#
# .. qmp-example::
diff --git a/qapi/cryptodev.json b/qapi/cryptodev.json
index 1f49e1822c..eb309c22f8 100644
--- a/qapi/cryptodev.json
+++ b/qapi/cryptodev.json
@@ -98,8 +98,6 @@
#
# Return information about current crypto devices.
#
-# Returns: a list of @QCryptodevInfo
-#
# Since: 8.0
##
{ 'command': 'query-cryptodev', 'returns': ['QCryptodevInfo']}
diff --git a/qapi/machine.json b/qapi/machine.json
index 2d6a137f21..2364893cba 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -103,8 +103,6 @@
#
# Return information about all virtual CPUs.
#
-# Returns: list of @CpuInfoFast
-#
# Since: 2.12
#
# .. qmp-example::
@@ -220,8 +218,6 @@
#
# @unstable: Argument @compat-props is experimental.
#
-# Returns: a list of MachineInfo
-#
# Since: 1.2
#
# .. qmp-example::
@@ -270,8 +266,6 @@
#
# Return information on the current virtual machine.
#
-# Returns: CurrentMachineParams
-#
# Since: 4.0
##
{ 'command': 'query-current-machine', 'returns': 'CurrentMachineParams' }
@@ -293,8 +287,6 @@
#
# Return information about the target for this QEMU
#
-# Returns: QemuTargetInfo
-#
# Since: 1.2
##
{ 'command': 'query-target', 'returns': 'QemuTargetInfo' }
@@ -318,8 +310,6 @@
#
# Query the guest UUID information.
#
-# Returns: The @UuidInfo for the guest
-#
# Since: 0.14
#
# .. qmp-example::
@@ -471,8 +461,6 @@
#
# Return information about KVM acceleration
#
-# Returns: @KvmInfo
-#
# Since: 0.14
#
# .. qmp-example::
@@ -934,8 +922,6 @@
#
# Return information for all memory backends.
#
-# Returns: a list of @Memdev.
-#
# Since: 2.1
#
# .. qmp-example::
@@ -1051,8 +1037,6 @@
#
# TODO: Better documentation; currently there is none.
#
-# Returns: a list of HotpluggableCPU objects.
-#
# Since: 2.7
#
# .. qmp-example::
@@ -1174,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
@@ -1240,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
@@ -2260,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'] }
diff --git a/qapi/migration.json b/qapi/migration.json
index 3bf97df5d8..57653160eb 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -326,8 +326,6 @@
# is active there will be another json-object with RAM migration
# status.
#
-# Returns: @MigrationInfo
-#
# Since: 0.14
#
# .. qmp-example::
@@ -577,8 +575,6 @@
#
# Return information about the current migration capabilities status
#
-# Returns: @MigrationCapabilityStatus
-#
# Since: 1.2
#
# .. qmp-example::
@@ -1364,8 +1360,6 @@
#
# Return information about the current migration parameters
#
-# Returns: @MigrationParameters
-#
# Since: 2.4
#
# .. qmp-example::
@@ -1946,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::
#
@@ -2000,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::
#
@@ -2375,8 +2369,6 @@
#
# @deprecated: This command is deprecated with no replacement yet.
#
-# Returns: @MigrationThreadInfo
-#
# Since: 7.2
##
{ 'command': 'query-migrationthreads',
diff --git a/qapi/misc-arm.json b/qapi/misc-arm.json
index f5341372f5..f9dd743b52 100644
--- a/qapi/misc-arm.json
+++ b/qapi/misc-arm.json
@@ -36,8 +36,6 @@
# 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::
diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json
index 24a2e143f6..5c3c9a14e0 100644
--- a/qapi/misc-i386.json
+++ b/qapi/misc-i386.json
@@ -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::
@@ -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
#
@@ -280,8 +276,6 @@
# @mnonce: a random 16 bytes value encoded in base64 (it will be
# included in report)
#
-# Returns: SevAttestationReport objects.
-#
# Errors:
# - If the attestation report is unavailable, either due to an
# invalid guest configuration or because the guest has not
@@ -343,8 +337,6 @@
#
# Return information about configured SGX capabilities of guest
#
-# Returns: @SgxInfo
-#
# Since: 6.2
#
# .. qmp-example::
@@ -362,8 +354,6 @@
#
# Return information about SGX capabilities of host
#
-# Returns: @SgxInfo
-#
# Since: 6.2
#
# .. qmp-example::
diff --git a/qapi/misc.json b/qapi/misc.json
index a180c16db2..b19eb08606 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -58,8 +58,6 @@
#
# Return the name information of a guest.
#
-# Returns: @NameInfo of the guest
-#
# Since: 0.14
#
# .. qmp-example::
@@ -334,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
@@ -417,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.
diff --git a/qapi/rocker.json b/qapi/rocker.json
index e494964952..5d2dbd2603 100644
--- a/qapi/rocker.json
+++ b/qapi/rocker.json
@@ -30,8 +30,6 @@
#
# @name: switch name
#
-# Returns: @Rocker information
-#
# Since: 2.4
#
# .. qmp-example::
@@ -100,8 +98,6 @@
#
# @name: port name
#
-# Returns: a list of @RockerPort information
-#
# Since: 2.4
#
# .. qmp-example::
diff --git a/qapi/run-state.json b/qapi/run-state.json
index 083a3c5eb3..76f14569ff 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -121,8 +121,6 @@
#
# Query the run status of the VM
#
-# Returns: @StatusInfo reflecting the VM
-#
# Since: 0.14
#
# .. qmp-example::
diff --git a/qapi/tpm.json b/qapi/tpm.json
index e66b107f1d..3f2850a573 100644
--- a/qapi/tpm.json
+++ b/qapi/tpm.json
@@ -29,8 +29,6 @@
#
# Return a list of supported TPM models
#
-# Returns: a list of TpmModel
-#
# Since: 1.5
#
# .. qmp-example::
@@ -60,8 +58,6 @@
#
# Return a list of supported TPM types
#
-# Returns: a list of TpmType
-#
# Since: 1.5
#
# .. qmp-example::
diff --git a/qapi/ui.json b/qapi/ui.json
index f5e77ae19d..53489ab65f 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -328,8 +328,6 @@
#
# Return information about the current SPICE server
#
-# Returns: @SpiceInfo
-#
# Since: 0.14
#
# .. qmp-example::
@@ -660,8 +658,6 @@
#
# Return information about the current VNC server
#
-# Returns: @VncInfo
-#
# Since: 0.14
#
# .. qmp-example::
@@ -691,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'],
@@ -1570,8 +1564,6 @@
#
# Return information about display configuration
#
-# Returns: @DisplayOptions
-#
# Since: 3.1
##
{ 'command': 'query-display-options',
diff --git a/qapi/virtio.json b/qapi/virtio.json
index 3cac0774f7..f0753cde71 100644
--- a/qapi/virtio.json
+++ b/qapi/virtio.json
@@ -849,8 +849,6 @@
#
# @unstable: This command is meant for debugging.
#
-# Returns: VirtioQueueElement information
-#
# Since: 7.2
#
# .. qmp-example::
diff --git a/qapi/yank.json b/qapi/yank.json
index d13a8e9117..c14de5229e 100644
--- a/qapi/yank.json
+++ b/qapi/yank.json
@@ -104,7 +104,7 @@
#
# 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::
#
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 11/32] qapi: rephrase return docs to avoid type name
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (9 preceding siblings ...)
2025-07-14 13:44 ` [PULL 10/32] qapi: remove trivial "Returns:" sections Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 12/32] qapi: add cross-references to acpi.json Markus Armbruster
` (21 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
"Returns: <description>" is rendered like "Return: <Type> –
<description>". Mentioning the type in the description again is
commonly redundant. Rephrase such descriptions not to.
Well, I tried. Maybe not very hard. Sorry!
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711051045.51110-5-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
[Commit message amended to explain why]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/block-core.json | 6 +++---
qapi/block-export.json | 2 +-
qapi/block.json | 2 +-
qapi/control.json | 5 ++---
qapi/dump.json | 5 ++---
qapi/introspect.json | 6 +++---
qapi/job.json | 2 +-
qapi/misc-i386.json | 2 +-
qapi/misc.json | 5 ++---
qapi/net.json | 2 +-
qapi/pci.json | 2 +-
qapi/qdev.json | 3 +--
qapi/qom.json | 8 +++-----
qapi/stats.json | 2 +-
qapi/trace.json | 2 +-
qapi/ui.json | 2 +-
qapi/virtio.json | 6 +++---
17 files changed, 28 insertions(+), 34 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 01bf41b8b0..848ebaff5a 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -764,7 +764,7 @@
#
# 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
@@ -1169,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
#
@@ -1441,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
##
diff --git a/qapi/block-export.json b/qapi/block-export.json
index 2241bfecf2..fb004e35fd 100644
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -473,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
##
diff --git a/qapi/block.json b/qapi/block.json
index 2d54a81c36..f0436ce871 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -89,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
diff --git a/qapi/control.json b/qapi/control.json
index 5fed0701f8..931a860b30 100644
--- a/qapi/control.json
+++ b/qapi/control.json
@@ -95,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
#
@@ -133,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
#
diff --git a/qapi/dump.json b/qapi/dump.json
index 0642ca157b..dc92b53247 100644
--- a/qapi/dump.json
+++ b/qapi/dump.json
@@ -148,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
#
@@ -199,8 +199,7 @@
#
# 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
#
diff --git a/qapi/introspect.json b/qapi/introspect.json
index 26d8839f19..be8511b067 100644
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -36,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).
#
diff --git a/qapi/job.json b/qapi/job.json
index 16b280f52f..51a57c523e 100644
--- a/qapi/job.json
+++ b/qapi/job.json
@@ -297,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
##
diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json
index 5c3c9a14e0..282bd3627b 100644
--- a/qapi/misc-i386.json
+++ b/qapi/misc-i386.json
@@ -163,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
diff --git a/qapi/misc.json b/qapi/misc.json
index b19eb08606..7dbc29dbd6 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -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
#
@@ -511,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
diff --git a/qapi/net.json b/qapi/net.json
index 3b03843c16..a266c6786e 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -847,7 +847,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
diff --git a/qapi/pci.json b/qapi/pci.json
index a8671cd9ac..418ea4fc93 100644
--- a/qapi/pci.json
+++ b/qapi/pci.json
@@ -177,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.
diff --git a/qapi/qdev.json b/qapi/qdev.json
index 441ed518b8..6441357e00 100644
--- a/qapi/qdev.json
+++ b/qapi/qdev.json
@@ -19,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
diff --git a/qapi/qom.json b/qapi/qom.json
index fbf94b9e09..aa09eddbf9 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -55,8 +55,7 @@
# @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
#
@@ -178,8 +177,7 @@
#
# @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
##
@@ -199,7 +197,7 @@
# 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
##
diff --git a/qapi/stats.json b/qapi/stats.json
index 78b88881ea..b63a7369dd 100644
--- a/qapi/stats.json
+++ b/qapi/stats.json
@@ -188,7 +188,7 @@
# 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
diff --git a/qapi/trace.json b/qapi/trace.json
index d08c9c6a88..de369dae6b 100644
--- a/qapi/trace.json
+++ b/qapi/trace.json
@@ -49,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
#
diff --git a/qapi/ui.json b/qapi/ui.json
index 53489ab65f..b48266c458 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -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
#
diff --git a/qapi/virtio.json b/qapi/virtio.json
index f0753cde71..2e23512085 100644
--- a/qapi/virtio.json
+++ b/qapi/virtio.json
@@ -201,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
#
@@ -565,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
@@ -700,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
#
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 12/32] qapi: add cross-references to acpi.json
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (10 preceding siblings ...)
2025-07-14 13:44 ` [PULL 11/32] qapi: rephrase return docs to avoid type name Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 13/32] qapi: add cross-references to authz.json Markus Armbruster
` (20 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711054005.60969-2-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/acpi.json | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/qapi/acpi.json b/qapi/acpi.json
index 90f8f564fd..906b3687a5 100644
--- a/qapi/acpi.json
+++ b/qapi/acpi.json
@@ -108,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
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 13/32] qapi: add cross-references to authz.json
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (11 preceding siblings ...)
2025-07-14 13:44 ` [PULL 12/32] qapi: add cross-references to acpi.json Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 14/32] qapi: add cross-references to block layer Markus Armbruster
` (19 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711054005.60969-3-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/authz.json | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/qapi/authz.json b/qapi/authz.json
index ad1b4b3af0..bc1123cc05 100644
--- a/qapi/authz.json
+++ b/qapi/authz.json
@@ -77,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
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 14/32] qapi: add cross-references to block layer
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (12 preceding siblings ...)
2025-07-14 13:44 ` [PULL 13/32] qapi: add cross-references to authz.json Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 15/32] qapi: add cross-references to crypto.json Markus Armbruster
` (18 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711054005.60969-4-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Two unwanted cross-references dropped]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/block-core.json | 184 ++++++++++++++++++++---------------------
qapi/block-export.json | 36 ++++----
qapi/block.json | 14 ++--
qapi/transaction.json | 12 +--
4 files changed, 123 insertions(+), 123 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 848ebaff5a..25b57919a7 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -32,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
@@ -224,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
##
@@ -333,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
@@ -350,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
@@ -615,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
##
@@ -710,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
@@ -762,7 +762,7 @@
##
# @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 describing each virtual block device.
# Filter nodes that were created implicitly are skipped over.
@@ -1027,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
##
@@ -1135,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)
#
@@ -1159,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"
@@ -1290,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.
@@ -1324,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
##
@@ -1531,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
##
@@ -1586,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
@@ -1597,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
@@ -1607,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
@@ -1720,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
#
@@ -1785,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
@@ -1847,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:
@@ -1890,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:
@@ -1921,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
@@ -2025,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
@@ -2074,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
#
@@ -2192,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
@@ -2208,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
@@ -2250,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
##
@@ -2289,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
@@ -2324,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:
@@ -2508,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
@@ -2523,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
@@ -2778,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;
@@ -2799,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.
#
@@ -2842,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
@@ -2850,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:
@@ -2918,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.
#
@@ -2938,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)
#
@@ -2961,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.
#
@@ -2971,7 +2971,7 @@
#
# Features:
#
-# @deprecated: This command is deprecated. Use @job-pause
+# @deprecated: This command is deprecated. Use `job-pause`
# instead.
#
# Errors:
@@ -3000,7 +3000,7 @@
#
# Features:
#
-# @deprecated: This command is deprecated. Use @job-resume
+# @deprecated: This command is deprecated. Use `job-resume`
# instead.
#
# Errors:
@@ -3021,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
@@ -3040,7 +3040,7 @@
#
# Features:
#
-# @deprecated: This command is deprecated. Use @job-complete
+# @deprecated: This command is deprecated. Use `job-complete`
# instead.
#
# Errors:
@@ -3059,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
@@ -3101,7 +3101,7 @@
#
# Features:
#
-# @deprecated: This command is deprecated. Use @job-finalize
+# @deprecated: This command is deprecated. Use `job-finalize`
# instead.
#
# Since: 2.12
@@ -3173,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
@@ -4715,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)
@@ -4919,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
@@ -4928,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
@@ -4942,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.
@@ -4956,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.
#
@@ -5511,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.
#
@@ -5571,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.
#
@@ -5640,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::
#
@@ -5684,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.
#
@@ -5834,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
#
@@ -5856,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.
#
@@ -5905,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.
#
@@ -5976,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
@@ -6189,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
diff --git a/qapi/block-export.json b/qapi/block-export.json
index fb004e35fd..6878b89dcf 100644
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -38,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).
##
@@ -51,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).
##
@@ -65,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".
#
@@ -81,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)
@@ -99,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
@@ -125,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
@@ -217,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
#
@@ -246,7 +246,7 @@
#
# Features:
#
-# @deprecated: This command is deprecated. Use @block-export-add
+# @deprecated: This command is deprecated. Use `block-export-add`
# instead.
#
# Errors:
@@ -289,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:
@@ -313,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
##
@@ -422,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:
@@ -460,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
##
diff --git a/qapi/block.json b/qapi/block.json
index f0436ce871..46955bbb3e 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -140,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
@@ -299,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
#
@@ -317,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
#
@@ -334,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)
@@ -522,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
diff --git a/qapi/transaction.json b/qapi/transaction.json
index 927035f5a7..4b4eb09bf3 100644
--- a/qapi/transaction.json
+++ b/qapi/transaction.json
@@ -69,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
##
@@ -158,7 +158,7 @@
# @TransactionAction:
#
# A discriminated record of operations that can be performed with
-# @transaction.
+# `transaction`.
#
# @type: the operation to be performed
#
@@ -189,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
##
@@ -229,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:
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 15/32] qapi: add cross-references to crypto.json
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (13 preceding siblings ...)
2025-07-14 13:44 ` [PULL 14/32] qapi: add cross-references to block layer Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 16/32] qapi: add cross-references to dump.json Markus Armbruster
` (17 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711054005.60969-5-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/crypto.json | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/qapi/crypto.json b/qapi/crypto.json
index 21006de36c..ab6eda4c2f 100644
--- a/qapi/crypto.json
+++ b/qapi/crypto.json
@@ -591,9 +591,9 @@
#
# Specific parameters for RSA algorithm.
#
-# @hash-alg: QCryptoHashAlgo
+# @hash-alg: `QCryptoHashAlgo`
#
-# @padding-alg: QCryptoRSAPaddingAlgo
+# @padding-alg: `QCryptoRSAPaddingAlgo`
#
# Since: 7.1
##
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 16/32] qapi: add cross-references to dump.json
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (14 preceding siblings ...)
2025-07-14 13:44 ` [PULL 15/32] qapi: add cross-references to crypto.json Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 17/32] qapi: add cross-references to job.json Markus Armbruster
` (16 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711054005.60969-6-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/dump.json | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/qapi/dump.json b/qapi/dump.json
index dc92b53247..32c8c1f06e 100644
--- a/qapi/dump.json
+++ b/qapi/dump.json
@@ -112,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.
#
@@ -128,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)
#
@@ -186,7 +186,7 @@
##
# @DumpGuestMemoryCapability:
#
-# @formats: the available formats for dump-guest-memory
+# @formats: the available formats for `dump-guest-memory`
#
# Since: 2.0
##
@@ -197,9 +197,9 @@
##
# @query-dump-guest-memory-capability:
#
-# Return the available formats for dump-guest-memory
+# Return the available formats for `dump-guest-memory`
#
-# Returns: An object listing available formats for dump-guest-memory
+# Returns: An object listing available formats for `dump-guest-memory`
#
# Since: 2.0
#
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 17/32] qapi: add cross-references to job.json
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (15 preceding siblings ...)
2025-07-14 13:44 ` [PULL 16/32] qapi: add cross-references to dump.json Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 18/32] qapi: add cross-references to Machine core Markus Armbruster
` (15 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711054005.60969-7-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Accidental line rewrap and an unwanted cross-refence dropped]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/job.json | 56 +++++++++++++++++++++++++--------------------------
1 file changed, 28 insertions(+), 28 deletions(-)
diff --git a/qapi/job.json b/qapi/job.json
index 51a57c523e..8b08350af2 100644
--- a/qapi/job.json
+++ b/qapi/job.json
@@ -12,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
@@ -67,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
@@ -77,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.
@@ -93,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
##
@@ -140,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.
#
@@ -175,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.
@@ -194,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
@@ -219,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.
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 18/32] qapi: add cross-references to Machine core
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (16 preceding siblings ...)
2025-07-14 13:44 ` [PULL 17/32] qapi: add cross-references to job.json Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 19/32] qapi: add cross-references to migration.json Markus Armbruster
` (14 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711054005.60969-8-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/machine-common.json | 20 +++++-----
qapi/machine.json | 80 ++++++++++++++++++++--------------------
2 files changed, 50 insertions(+), 50 deletions(-)
diff --git a/qapi/machine-common.json b/qapi/machine-common.json
index 0f01599130..ed3d20a2fb 100644
--- a/qapi/machine-common.json
+++ b/qapi/machine-common.json
@@ -28,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
@@ -104,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
##
diff --git a/qapi/machine.json b/qapi/machine.json
index 2364893cba..f9bfda2151 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -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:
@@ -377,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
@@ -589,7 +589,7 @@
#
# List of CXL Fixed Memory Windows.
#
-# @cxl-fmw: List of CXLFixedMemoryWindowOptions
+# @cxl-fmw: List of `CXLFixedMemoryWindowOptions`
#
# Since: 7.1
##
@@ -644,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
##
@@ -661,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
@@ -683,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)
@@ -710,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.
@@ -746,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
@@ -767,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
@@ -787,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.
@@ -964,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
#
@@ -992,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',
@@ -1008,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
##
@@ -1179,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:
@@ -1965,7 +1965,7 @@
#
# The result of a CPU model baseline.
#
-# @model: the baselined CpuModelInfo.
+# @model: the baselined `CpuModelInfo`.
#
# Since: 2.8
##
@@ -2014,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:
@@ -2068,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.
@@ -2087,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
@@ -2107,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
@@ -2136,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".
@@ -2155,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
@@ -2194,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
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 19/32] qapi: add cross-references to migration.json
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (17 preceding siblings ...)
2025-07-14 13:44 ` [PULL 18/32] qapi: add cross-references to Machine core Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 20/32] qapi: add cross-references to net.json Markus Armbruster
` (13 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
Note that a reference to MIGRATION needs to be disambiguated with a
:qapi:event: prefix. Without this, Sphinx complains
more than one target found for 'any' cross-reference 'MIGRATION': could be :std:ref:`Migration framework` or :qapi:event:`QMP:migration.MIGRATION`
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711054005.60969-9-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message amended to explain need for :qapi:event:]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/migration.json | 68 ++++++++++++++++++++++-----------------------
1 file changed, 34 insertions(+), 34 deletions(-)
diff --git a/qapi/migration.json b/qapi/migration.json
index 57653160eb..e08a99bb82 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -195,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)
#
@@ -266,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)
@@ -277,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
@@ -627,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.
#
@@ -677,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
@@ -688,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)
##
@@ -913,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
@@ -1094,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
@@ -1110,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
##
@@ -1304,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
@@ -1398,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
#
@@ -1519,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.
#
@@ -1775,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
@@ -1788,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
#
@@ -1841,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
@@ -1882,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
@@ -1922,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.
#
@@ -1971,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'.
@@ -2095,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
#
@@ -2163,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
@@ -2236,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)
@@ -2286,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.
#
@@ -2311,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.
#
@@ -2469,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::
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 20/32] qapi: add cross-references to net.json
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (18 preceding siblings ...)
2025-07-14 13:44 ` [PULL 19/32] qapi: add cross-references to migration.json Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 21/32] qapi: add cross-references to pci.json Markus Armbruster
` (12 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711054005.60969-10-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/net.json | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/qapi/net.json b/qapi/net.json
index a266c6786e..1dda21fe61 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -657,7 +657,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:
#
@@ -682,7 +682,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
@@ -892,7 +892,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
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 21/32] qapi: add cross-references to pci.json
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (19 preceding siblings ...)
2025-07-14 13:44 ` [PULL 20/32] qapi: add cross-references to net.json Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 22/32] qapi: add cross-references to QOM Markus Armbruster
` (11 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711054005.60969-11-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/pci.json | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/qapi/pci.json b/qapi/pci.json
index 418ea4fc93..694c741e42 100644
--- a/qapi/pci.json
+++ b/qapi/pci.json
@@ -85,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
##
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 22/32] qapi: add cross-references to QOM
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (20 preceding siblings ...)
2025-07-14 13:44 ` [PULL 21/32] qapi: add cross-references to pci.json Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 23/32] qapi: add cross-references to replay.json Markus Armbruster
` (10 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711054005.60969-12-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/qdev.json | 4 ++--
qapi/qom.json | 13 +++++++------
2 files changed, 9 insertions(+), 8 deletions(-)
diff --git a/qapi/qdev.json b/qapi/qdev.json
index 6441357e00..e14a0c9259 100644
--- a/qapi/qdev.json
+++ b/qapi/qdev.json
@@ -97,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
diff --git a/qapi/qom.json b/qapi/qom.json
index aa09eddbf9..4e85baae47 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -52,7 +52,7 @@
#
# 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 that describe the properties of the object.
@@ -129,12 +129,12 @@
#
# 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
#
@@ -153,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
#
@@ -193,6 +193,7 @@
#
# @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.
@@ -787,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
@@ -816,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
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 23/32] qapi: add cross-references to replay.json
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (21 preceding siblings ...)
2025-07-14 13:44 ` [PULL 22/32] qapi: add cross-references to QOM Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 24/32] qapi: add cross-references to run-state.json Markus Armbruster
` (9 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711054005.60969-13-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/replay.json | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/qapi/replay.json b/qapi/replay.json
index e46c5c1d3f..ccf84da68e 100644
--- a/qapi/replay.json
+++ b/qapi/replay.json
@@ -49,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.
#
@@ -72,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
#
@@ -88,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
@@ -108,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
#
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 24/32] qapi: add cross-references to run-state.json
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (22 preceding siblings ...)
2025-07-14 13:44 ` [PULL 23/32] qapi: add cross-references to replay.json Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 25/32] qapi: add cross-references to sockets.json Markus Armbruster
` (8 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711054005.60969-14-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/run-state.json | 46 ++++++++++++++++++++++-----------------------
1 file changed, 23 insertions(+), 23 deletions(-)
diff --git a/qapi/run-state.json b/qapi/run-state.json
index 76f14569ff..54ba5c9a3f 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -70,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
#
@@ -108,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
##
@@ -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
#
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 25/32] qapi: add cross-references to sockets.json
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (23 preceding siblings ...)
2025-07-14 13:44 ` [PULL 24/32] qapi: add cross-references to run-state.json Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 26/32] qapi: add cross-references to ui.json Markus Armbruster
` (7 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow, Eric Blake
From: John Snow <jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-ID: <20250711054005.60969-15-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/sockets.json | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/qapi/sockets.json b/qapi/sockets.json
index b5f4a8fecd..82046b0b3a 100644
--- a/qapi/sockets.json
+++ b/qapi/sockets.json
@@ -211,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
#
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 26/32] qapi: add cross-references to ui.json
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (24 preceding siblings ...)
2025-07-14 13:44 ` [PULL 25/32] qapi: add cross-references to sockets.json Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 27/32] qapi: add cross-references to virtio.json Markus Armbruster
` (6 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711054005.60969-16-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/ui.json | 34 +++++++++++++++++-----------------
1 file changed, 17 insertions(+), 17 deletions(-)
diff --git a/qapi/ui.json b/qapi/ui.json
index b48266c458..c672cf10f9 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -41,7 +41,7 @@
##
# @SetPasswordOptions:
#
-# Options for set_password.
+# Options for `set_password`.
#
# @protocol:
# - 'vnc' to modify the VNC server password
@@ -65,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.
@@ -96,7 +96,7 @@
##
# @ExpirePasswordOptions:
#
-# General options for expire_password.
+# General options for `expire_password`.
#
# @protocol:
# - 'vnc' to modify the VNC server expiration
@@ -126,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.
@@ -185,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
#
@@ -313,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
##
@@ -563,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
@@ -626,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
@@ -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
#
@@ -1367,7 +1367,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.
#
@@ -1526,7 +1526,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).
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 27/32] qapi: add cross-references to virtio.json
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (25 preceding siblings ...)
2025-07-14 13:44 ` [PULL 26/32] qapi: add cross-references to ui.json Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 28/32] qapi: add cross-references to yank.json Markus Armbruster
` (5 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711054005.60969-17-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/virtio.json | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/qapi/virtio.json b/qapi/virtio.json
index 2e23512085..b29c850eaf 100644
--- a/qapi/virtio.json
+++ b/qapi/virtio.json
@@ -137,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
#
@@ -579,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",
@@ -606,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",
@@ -818,7 +818,7 @@
#
# @index: Index of the element in the queue
#
-# @descs: List of descriptors (VirtioRingDesc)
+# @descs: List of descriptors (`VirtioRingDesc`)
#
# @avail: VRingAvail info
#
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 28/32] qapi: add cross-references to yank.json
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (26 preceding siblings ...)
2025-07-14 13:44 ` [PULL 27/32] qapi: add cross-references to virtio.json Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 29/32] qapi: add cross-references to misc modules Markus Armbruster
` (4 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow, Lukas Straub
From: John Snow <jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Acked-by: Lukas Straub <lukasstraub2@web.de>
Message-ID: <20250711054005.60969-18-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/yank.json | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/qapi/yank.json b/qapi/yank.json
index c14de5229e..f3cd5c15d6 100644
--- a/qapi/yank.json
+++ b/qapi/yank.json
@@ -11,7 +11,7 @@
##
# @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
@@ -22,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
@@ -35,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
@@ -48,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
@@ -59,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
##
@@ -76,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
#
@@ -102,7 +102,7 @@
##
# @query-yank:
#
-# Query yank instances. See @YankInstance for more information.
+# Query yank instances. See `YankInstance` for more information.
#
# TODO: This line is a hack to separate the example from the body
#
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 29/32] qapi: add cross-references to misc modules
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (27 preceding siblings ...)
2025-07-14 13:44 ` [PULL 28/32] qapi: add cross-references to yank.json Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 30/32] qom: qom-list-get Markus Armbruster
` (3 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, John Snow
From: John Snow <jsnow@redhat.com>
These modules don't have specific maintainers, so they're lumped in
together here as miscellaneous.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711054005.60969-19-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/control.json | 2 +-
qapi/ebpf.json | 2 +-
qapi/introspect.json | 24 ++++++++++++------------
qapi/misc-arm.json | 2 +-
qapi/misc-i386.json | 2 +-
qapi/misc.json | 12 ++++++------
qapi/stats.json | 8 ++++----
7 files changed, 26 insertions(+), 26 deletions(-)
diff --git a/qapi/control.json b/qapi/control.json
index 931a860b30..9a5302193d 100644
--- a/qapi/control.json
+++ b/qapi/control.json
@@ -13,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)
diff --git a/qapi/ebpf.json b/qapi/ebpf.json
index d45054e666..f0257955fa 100644
--- a/qapi/ebpf.json
+++ b/qapi/ebpf.json
@@ -34,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
diff --git a/qapi/introspect.json b/qapi/introspect.json
index be8511b067..53100714a8 100644
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -18,11 +18,11 @@
##
# @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.
@@ -56,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'.
@@ -82,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,
@@ -113,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.
#
@@ -154,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)
@@ -194,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.
#
@@ -208,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.
@@ -273,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
@@ -301,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.
@@ -323,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.
diff --git a/qapi/misc-arm.json b/qapi/misc-arm.json
index f9dd743b52..f921d740f1 100644
--- a/qapi/misc-arm.json
+++ b/qapi/misc-arm.json
@@ -30,7 +30,7 @@
##
# @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
diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json
index 282bd3627b..c8c91a241c 100644
--- a/qapi/misc-i386.json
+++ b/qapi/misc-i386.json
@@ -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.
#
diff --git a/qapi/misc.json b/qapi/misc.json
index 7dbc29dbd6..28c641fe2f 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -23,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
@@ -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::
@@ -475,7 +475,7 @@
#
# @name: parameter name
#
-# @type: parameter @CommandLineParameterType
+# @type: parameter `CommandLineParameterType`
#
# @help: human readable text string, not suitable for parsing.
#
@@ -497,7 +497,7 @@
#
# @option: option name
#
-# @parameters: an array of @CommandLineParameterInfo
+# @parameters: an array of `CommandLineParameterInfo`
#
# Since: 1.5
##
diff --git a/qapi/stats.json b/qapi/stats.json
index b63a7369dd..151ac43c48 100644
--- a/qapi/stats.json
+++ b/qapi/stats.json
@@ -89,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.
#
@@ -114,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.
#
@@ -185,7 +185,7 @@
# 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 statistics, one for each provider and object
@@ -205,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.
#
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 30/32] qom: qom-list-get
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (28 preceding siblings ...)
2025-07-14 13:44 ` [PULL 29/32] qapi: add cross-references to misc modules Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 31/32] python: use qom-list-get Markus Armbruster
` (2 subsequent siblings)
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, Steve Sistare, Philippe Mathieu-Daudé
From: Steve Sistare <steven.sistare@oracle.com>
Using qom-list and qom-get to get all the nodes and property values in
a QOM tree can take multiple seconds because it requires 1000's of
individual QOM requests. Some managers fetch the entire tree or a
large subset of it when starting a new VM, and this cost is a
substantial fraction of start up time.
Define the qom-list-get command, which fetches all the properties and
values for a list of paths. This can be much faster than qom-list
plus qom-get. When getting an entire QOM tree, I measured a 10x
speedup in elapsed time.
Signed-off-by: Steve Sistare <steven.sistare@oracle.com>
Tested-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <1752248703-217318-2-git-send-email-steven.sistare@oracle.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/qom.json | 50 +++++++++++++++++++++++++++++++++++++++++++
qom/qom-qmp-cmds.c | 53 ++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 103 insertions(+)
diff --git a/qapi/qom.json b/qapi/qom.json
index 4e85baae47..687714e2ef 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -47,6 +47,34 @@
'*description': 'str',
'*default-value': 'any' } }
+##
+# @ObjectPropertyValue:
+#
+# @name: the name of the property.
+#
+# @type: the type of the property, as described in `ObjectPropertyInfo`.
+#
+# @value: the value of the property. Absent when the property cannot
+# be read.
+#
+# Since 10.1
+##
+{ 'struct': 'ObjectPropertyValue',
+ 'data': { 'name': 'str',
+ 'type': 'str',
+ '*value': 'any' } }
+
+##
+# @ObjectPropertiesValues:
+#
+# @properties: a list of properties.
+#
+# Since 10.1
+##
+{ 'struct': 'ObjectPropertiesValues',
+ 'data': { 'properties': [ 'ObjectPropertyValue' ] }}
+
+
##
# @qom-list:
#
@@ -124,6 +152,28 @@
'returns': 'any',
'allow-preconfig': true }
+##
+# @qom-list-get:
+#
+# List properties and their values for each object path in the input
+# list.
+#
+# @paths: The absolute or partial path for each object, as described
+# in `qom-get`.
+#
+# Errors:
+# - If any path is not valid or is ambiguous
+#
+# Returns: A list where each element is the result for the
+# corresponding element of @paths.
+#
+# Since 10.1
+##
+{ 'command': 'qom-list-get',
+ 'data': { 'paths': [ 'str' ] },
+ 'returns': [ 'ObjectPropertiesValues' ],
+ 'allow-preconfig': true }
+
##
# @qom-set:
#
diff --git a/qom/qom-qmp-cmds.c b/qom/qom-qmp-cmds.c
index 293755f409..57f1898cf6 100644
--- a/qom/qom-qmp-cmds.c
+++ b/qom/qom-qmp-cmds.c
@@ -69,6 +69,59 @@ ObjectPropertyInfoList *qmp_qom_list(const char *path, Error **errp)
return props;
}
+static void qom_list_add_property_value(Object *obj, ObjectProperty *prop,
+ ObjectPropertyValueList **props)
+{
+ ObjectPropertyValue *item = g_new0(ObjectPropertyValue, 1);
+
+ QAPI_LIST_PREPEND(*props, item);
+
+ item->name = g_strdup(prop->name);
+ item->type = g_strdup(prop->type);
+ item->value = object_property_get_qobject(obj, prop->name, NULL);
+}
+
+static ObjectPropertyValueList *qom_get_property_value_list(const char *path,
+ Error **errp)
+{
+ Object *obj;
+ ObjectProperty *prop;
+ ObjectPropertyIterator iter;
+ ObjectPropertyValueList *props = NULL;
+
+ obj = qom_resolve_path(path, errp);
+ if (obj == NULL) {
+ return NULL;
+ }
+
+ object_property_iter_init(&iter, obj);
+ while ((prop = object_property_iter_next(&iter))) {
+ qom_list_add_property_value(obj, prop, &props);
+ }
+
+ return props;
+}
+
+ObjectPropertiesValuesList *qmp_qom_list_get(strList *paths, Error **errp)
+{
+ ObjectPropertiesValuesList *head = NULL, **tail = &head;
+ strList *path;
+
+ for (path = paths; path; path = path->next) {
+ ObjectPropertiesValues *item = g_new0(ObjectPropertiesValues, 1);
+
+ QAPI_LIST_APPEND(tail, item);
+
+ item->properties = qom_get_property_value_list(path->value, errp);
+ if (!item->properties) {
+ qapi_free_ObjectPropertiesValuesList(head);
+ return NULL;
+ }
+ }
+
+ return head;
+}
+
void qmp_qom_set(const char *path, const char *property, QObject *value,
Error **errp)
{
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 31/32] python: use qom-list-get
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (29 preceding siblings ...)
2025-07-14 13:44 ` [PULL 30/32] qom: qom-list-get Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-14 13:44 ` [PULL 32/32] tests/qtest/qom-test: unit test for qom-list-get Markus Armbruster
2025-07-15 4:26 ` [PULL 00/32] QAPI patches patches for 2025-07-14 Stefan Hajnoczi
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, Steve Sistare
From: Steve Sistare <steven.sistare@oracle.com>
Use qom-list-get to speed up the qom-tree command.
Signed-off-by: Steve Sistare <steven.sistare@oracle.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <1752248703-217318-3-git-send-email-steven.sistare@oracle.com>
Tested-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
python/qemu/utils/qom.py | 43 +++++++++++++++-----------
python/qemu/utils/qom_common.py | 53 +++++++++++++++++++++++++++++++++
2 files changed, 78 insertions(+), 18 deletions(-)
diff --git a/python/qemu/utils/qom.py b/python/qemu/utils/qom.py
index 426a0f245f..337ae29b8c 100644
--- a/python/qemu/utils/qom.py
+++ b/python/qemu/utils/qom.py
@@ -224,28 +224,35 @@ def __init__(self, args: argparse.Namespace):
super().__init__(args)
self.path = args.path
- def _list_node(self, path: str) -> None:
- print(path)
- items = self.qom_list(path)
- for item in items:
- if item.child:
- continue
- try:
- rsp = self.qmp.cmd('qom-get', path=path,
- property=item.name)
- print(f" {item.name}: {rsp} ({item.type})")
- except ExecuteError as err:
- print(f" {item.name}: <EXCEPTION: {err!s}> ({item.type})")
- print('')
- for item in items:
- if not item.child:
- continue
+ def _list_nodes(self, paths: [str]) -> None:
+ all_paths_props = self.qom_list_get(paths)
+ i = 0
+
+ for props in all_paths_props:
+ path = paths[i]
+ i = i + 1
+ print(path)
if path == '/':
path = ''
- self._list_node(f"{path}/{item.name}")
+ newpaths = []
+
+ for item in props.properties:
+ if item.child:
+ newpaths += [ f"{path}/{item.name}" ]
+ else:
+ value = item.value
+ if value == None:
+ value = f"<EXCEPTION: property could not be read>"
+ print(f" {item.name}: {value} ({item.type})")
+
+ print('')
+
+ if newpaths:
+ self._list_nodes(newpaths)
+
def run(self) -> int:
- self._list_node(self.path)
+ self._list_nodes([self.path])
return 0
diff --git a/python/qemu/utils/qom_common.py b/python/qemu/utils/qom_common.py
index dd2c8b1908..e471f1d2ec 100644
--- a/python/qemu/utils/qom_common.py
+++ b/python/qemu/utils/qom_common.py
@@ -65,6 +65,50 @@ def link(self) -> bool:
return self.type.startswith('link<')
+class ObjectPropertyValue:
+ """
+ Represents a property return from e.g. qom-tree-get
+ """
+ def __init__(self, name: str, type_: str, value: object):
+ self.name = name
+ self.type = type_
+ self.value = value
+
+ @classmethod
+ def make(cls, value: Dict[str, Any]) -> 'ObjectPropertyValue':
+ """
+ Build an ObjectPropertyValue from a Dict with an unknown shape.
+ """
+ assert value.keys() >= {'name', 'type'}
+ assert value.keys() <= {'name', 'type', 'value'}
+ return cls(value['name'], value['type'], value.get('value'))
+
+ @property
+ def child(self) -> bool:
+ """Is this property a child property?"""
+ return self.type.startswith('child<')
+
+
+class ObjectPropertiesValues:
+ """
+ Represents the return type from e.g. qom-list-get
+ """
+ def __init__(self, properties):
+ self.properties = properties
+
+ @classmethod
+ def make(cls, value: Dict[str, Any]) -> 'ObjectPropertiesValues':
+ """
+ Build an ObjectPropertiesValues from a Dict with an unknown shape.
+ """
+ assert value.keys() == {'properties'}
+ props = [ObjectPropertyValue(item['name'],
+ item['type'],
+ item.get('value'))
+ for item in value['properties']]
+ return cls(props)
+
+
CommandT = TypeVar('CommandT', bound='QOMCommand')
@@ -145,6 +189,15 @@ def qom_list(self, path: str) -> List[ObjectPropertyInfo]:
assert isinstance(rsp, list)
return [ObjectPropertyInfo.make(x) for x in rsp]
+ def qom_list_get(self, paths) -> List[ObjectPropertiesValues]:
+ """
+ :return: a strongly typed list from the 'qom-list-get' command.
+ """
+ rsp = self.qmp.cmd('qom-list-get', paths=paths)
+ # qom-list-get returns List[ObjectPropertiesValues]
+ assert isinstance(rsp, list)
+ return [ObjectPropertiesValues.make(x) for x in rsp]
+
@classmethod
def command_runner(
cls: Type[CommandT],
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PULL 32/32] tests/qtest/qom-test: unit test for qom-list-get
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (30 preceding siblings ...)
2025-07-14 13:44 ` [PULL 31/32] python: use qom-list-get Markus Armbruster
@ 2025-07-14 13:44 ` Markus Armbruster
2025-07-15 4:26 ` [PULL 00/32] QAPI patches patches for 2025-07-14 Stefan Hajnoczi
32 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-14 13:44 UTC (permalink / raw)
To: qemu-devel; +Cc: stefanha, Steve Sistare, Philippe Mathieu-Daudé
From: Steve Sistare <steven.sistare@oracle.com>
Add a unit test for qom-list-get.
Signed-off-by: Steve Sistare <steven.sistare@oracle.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <1752248703-217318-4-git-send-email-steven.sistare@oracle.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
tests/qtest/qom-test.c | 116 ++++++++++++++++++++++++++++++++++++++++-
1 file changed, 115 insertions(+), 1 deletion(-)
diff --git a/tests/qtest/qom-test.c b/tests/qtest/qom-test.c
index 27d70bc11c..4ade1c728c 100644
--- a/tests/qtest/qom-test.c
+++ b/tests/qtest/qom-test.c
@@ -11,11 +11,119 @@
#include "qobject/qdict.h"
#include "qobject/qlist.h"
+#include "qobject/qstring.h"
#include "qemu/cutils.h"
#include "libqtest.h"
+#define RAM_NAME "node0"
+#define RAM_SIZE 65536
+
static int verbosity_level;
+/*
+ * Verify that the /object/RAM_NAME 'size' property is RAM_SIZE.
+ */
+static void test_list_get_value(QTestState *qts)
+{
+ QDict *args = qdict_new();
+ g_autoptr(QDict) response = NULL;
+ g_autoptr(QList) paths = qlist_new();
+ QListEntry *entry, *prop_entry;
+ const char *prop_name;
+ QList *properties, *return_list;
+ QDict *obj;
+
+ qlist_append_str(paths, "/objects/" RAM_NAME);
+ qdict_put_obj(args, "paths", QOBJECT(qlist_copy(paths)));
+ response = qtest_qmp(qts, "{ 'execute': 'qom-list-get',"
+ " 'arguments': %p }", args);
+ g_assert(response);
+ g_assert(qdict_haskey(response, "return"));
+ return_list = qobject_to(QList, qdict_get(response, "return"));
+
+ entry = QTAILQ_FIRST(&return_list->head);
+ obj = qobject_to(QDict, qlist_entry_obj(entry));
+ g_assert(qdict_haskey(obj, "properties"));
+ properties = qobject_to(QList, qdict_get(obj, "properties"));
+
+ QLIST_FOREACH_ENTRY(properties, prop_entry) {
+ QDict *prop = qobject_to(QDict, qlist_entry_obj(prop_entry));
+
+ g_assert(qdict_haskey(prop, "name"));
+ g_assert(qdict_haskey(prop, "value"));
+
+ prop_name = qdict_get_str(prop, "name");
+ if (!strcmp(prop_name, "type")) {
+ g_assert_cmpstr(qdict_get_str(prop, "value"), ==,
+ "memory-backend-ram");
+
+ } else if (!strcmp(prop_name, "size")) {
+ g_assert_cmpint(qdict_get_int(prop, "value"), ==, RAM_SIZE);
+ }
+ }
+}
+
+static void test_list_get(QTestState *qts, QList *paths)
+{
+ QListEntry *entry, *prop_entry, *path_entry;
+ g_autoptr(QDict) response = NULL;
+ QDict *args = qdict_new();
+ QDict *prop;
+ QList *return_list;
+
+ if (verbosity_level >= 2) {
+ g_test_message("Obtaining properties for paths:");
+ QLIST_FOREACH_ENTRY(paths, path_entry) {
+ QString *qstr = qobject_to(QString, qlist_entry_obj(path_entry));
+ g_test_message(" %s", qstring_get_str(qstr));
+ }
+ }
+
+ qdict_put_obj(args, "paths", QOBJECT(qlist_copy(paths)));
+ response = qtest_qmp(qts, "{ 'execute': 'qom-list-get',"
+ " 'arguments': %p }", args);
+ g_assert(response);
+ g_assert(qdict_haskey(response, "return"));
+ return_list = qobject_to(QList, qdict_get(response, "return"));
+ g_assert(!qlist_empty(return_list));
+
+ path_entry = QTAILQ_FIRST(&paths->head);
+ QLIST_FOREACH_ENTRY(return_list, entry) {
+ QDict *obj = qobject_to(QDict, qlist_entry_obj(entry));
+ g_assert(qdict_haskey(obj, "properties"));
+ QList *properties = qobject_to(QList, qdict_get(obj, "properties"));
+ bool has_child = false;
+
+ QLIST_FOREACH_ENTRY(properties, prop_entry) {
+ prop = qobject_to(QDict, qlist_entry_obj(prop_entry));
+ g_assert(qdict_haskey(prop, "name"));
+ g_assert(qdict_haskey(prop, "type"));
+ has_child |= strstart(qdict_get_str(prop, "type"), "child<", NULL);
+ }
+
+ if (has_child) {
+ /* build a list of child paths */
+ QString *qstr = qobject_to(QString, qlist_entry_obj(path_entry));
+ const char *path = qstring_get_str(qstr);
+ g_autoptr(QList) child_paths = qlist_new();
+
+ QLIST_FOREACH_ENTRY(properties, prop_entry) {
+ prop = qobject_to(QDict, qlist_entry_obj(prop_entry));
+ if (strstart(qdict_get_str(prop, "type"), "child<", NULL)) {
+ g_autofree char *child_path = g_strdup_printf(
+ "%s/%s", path, qdict_get_str(prop, "name"));
+ qlist_append_str(child_paths, child_path);
+ }
+ }
+
+ /* fetch props for all children with one qom-list-get call */
+ test_list_get(qts, child_paths);
+ }
+
+ path_entry = QTAILQ_NEXT(path_entry, next);
+ }
+}
+
static void test_properties(QTestState *qts, const char *path, bool recurse)
{
char *child_path;
@@ -85,8 +193,10 @@ static void test_machine(gconstpointer data)
const char *machine = data;
QDict *response;
QTestState *qts;
+ g_autoptr(QList) paths = qlist_new();
- qts = qtest_initf("-machine %s", machine);
+ qts = qtest_initf("-machine %s -object memory-backend-ram,id=%s,size=%d",
+ machine, RAM_NAME, RAM_SIZE);
if (g_test_slow()) {
/* Make sure we can get the machine class properties: */
@@ -101,6 +211,10 @@ static void test_machine(gconstpointer data)
test_properties(qts, "/machine", true);
+ qlist_append_str(paths, "/machine");
+ test_list_get(qts, paths);
+ test_list_get_value(qts);
+
response = qtest_qmp(qts, "{ 'execute': 'quit' }");
g_assert(qdict_haskey(response, "return"));
qobject_unref(response);
--
2.49.0
^ permalink raw reply related [flat|nested] 35+ messages in thread* Re: [PULL 00/32] QAPI patches patches for 2025-07-14
2025-07-14 13:44 [PULL 00/32] QAPI patches patches for 2025-07-14 Markus Armbruster
` (31 preceding siblings ...)
2025-07-14 13:44 ` [PULL 32/32] tests/qtest/qom-test: unit test for qom-list-get Markus Armbruster
@ 2025-07-15 4:26 ` Stefan Hajnoczi
2025-07-15 6:30 ` Markus Armbruster
32 siblings, 1 reply; 35+ messages in thread
From: Stefan Hajnoczi @ 2025-07-15 4:26 UTC (permalink / raw)
To: Markus Armbruster, John Snow; +Cc: qemu-devel, stefanha
On Mon, Jul 14, 2025 at 11:14 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> The following changes since commit 9a4e273ddec3927920c5958d2226c6b38b543336:
>
> Merge tag 'pull-tcg-20250711' of https://gitlab.com/rth7680/qemu into staging (2025-07-13 01:46:04 -0400)
>
> are available in the Git repository at:
>
> https://repo.or.cz/qemu/armbru.git tags/pull-qapi-2025-07-14
>
> for you to fetch changes up to 07273ca0ce3af397071f7a6c11abdab649ff25e1:
>
> tests/qtest/qom-test: unit test for qom-list-get (2025-07-14 15:25:12 +0200)
>
> ----------------------------------------------------------------
> QAPI patches patches for 2025-07-14
>
> ----------------------------------------------------------------
> John Snow (27):
> docs/sphinx: adjust qapidoc to cope with same-line error sections
> docs/sphinx: parse @references in freeform text
> docs/sphinx: remove legacy QAPI manual generator
> docs/sphinx: remove special parsing for freeform sections
> qapi: lift restriction on using '=' in doc blocks
> docs/qapi-domain: add return-nodesc
> qapi: Fix undocumented return values by generating something
> qapi: remove trivial "Returns:" sections
> qapi: rephrase return docs to avoid type name
> qapi: add cross-references to acpi.json
> qapi: add cross-references to authz.json
> qapi: add cross-references to block layer
> qapi: add cross-references to crypto.json
> qapi: add cross-references to dump.json
> qapi: add cross-references to job.json
> qapi: add cross-references to Machine core
> qapi: add cross-references to migration.json
> qapi: add cross-references to net.json
> qapi: add cross-references to pci.json
> qapi: add cross-references to QOM
> qapi: add cross-references to replay.json
> qapi: add cross-references to run-state.json
> qapi: add cross-references to sockets.json
> qapi: add cross-references to ui.json
> qapi: add cross-references to virtio.json
> qapi: add cross-references to yank.json
> qapi: add cross-references to misc modules
>
> Markus Armbruster (2):
> qapi: Clean up "This command will do ..." command descriptions
> qapi: Clean up a few Errors: sections
>
> Steve Sistare (3):
> qom: qom-list-get
> python: use qom-list-get
> tests/qtest/qom-test: unit test for qom-list-get
The check-python-minreqs CI job is failing:
qemu/utils/qom.py:35:1: F401 'qemu.qmp.ExecuteError' imported but unused
qemu/utils/qom.py:241:34: E201 whitespace after '['
qemu/utils/qom.py:241:56: E202 whitespace before ']'
qemu/utils/qom.py:244:30: E711 comparison to None should be 'if cond is None:'
qemu/utils/qom.py:245:33: F541 f-string is missing placeholders
qemu/utils/qom.py:254:5: E303 too many blank lines (2)
Log file "stderr" content for test "01-tests/flake8.sh" (FAIL):
Log file "stdout" content for test "05-tests/mypy.sh" (FAIL):
qemu/utils/qom_common.py:96: error: Function is missing a type
annotation [no-untyped-def]
qemu/utils/qom_common.py:192: error: Function is missing a type
annotation for one or more arguments [no-untyped-def]
qemu/utils/qom.py:227: error: Bracketed expression "[...]" is not
valid as a type [valid-type]
qemu/utils/qom.py:227: note: Did you mean "List[...]"?
Found 3 errors in 2 files (checked 22 source files)
Log file "stderr" content for test "05-tests/mypy.sh" (FAIL):
Log file "stdout" content for test "33-tests/pylint.sh" (FAIL):
************* Module /builds/qemu-project/qemu/python/setup.cfg
setup.cfg:1:0: W0012: Unknown option value for '--disable', expected a
valid pylint message and got 'too-many-positional-arguments'
(unknown-option-value)
************* Module utils.qom
qemu/utils/qom.py:244:23: C0121: Comparison 'value == None' should be
'value is None' (singleton-comparison)
qemu/utils/qom.py:245:32: W1309: Using an f-string that does not have
any interpolated variables (f-string-without-interpolation)
qemu/utils/qom.py:35:0: W0611: Unused ExecuteError imported from
qemu.qmp (unused-import)
************* Module utils.qom_common
qemu/utils/qom_common.py:92:0: R0903: Too few public methods (1/2)
(too-few-public-methods)
https://gitlab.com/qemu-project/qemu/-/jobs/10682353448
Please take a look and resend this pull request if fixes are necessary. Thanks!
Stefan
>
> docs/devel/qapi-code-gen.rst | 28 +-
> docs/devel/qapi-domain.rst | 31 ++
> docs/interop/firmware.json | 4 +-
> docs/interop/qemu-ga-ref.rst | 1 -
> docs/interop/qemu-qmp-ref.rst | 1 -
> docs/interop/qemu-storage-daemon-qmp-ref.rst | 1 -
> docs/interop/vhost-user.json | 4 +-
> docs/sphinx/qapi_domain.py | 8 +
> docs/sphinx/qapidoc.py | 96 ++----
> docs/sphinx/qapidoc_legacy.py | 440 ---------------------------
> qapi/acpi.json | 6 +-
> qapi/audio.json | 6 +-
> qapi/authz.json | 6 +-
> qapi/block-core.json | 201 ++++++------
> qapi/block-export.json | 41 +--
> qapi/block.json | 23 +-
> qapi/char.json | 12 +-
> qapi/common.json | 4 +-
> qapi/compat.json | 4 +-
> qapi/control.json | 20 +-
> qapi/crypto.json | 8 +-
> qapi/cryptodev.json | 6 +-
> qapi/cxl.json | 4 +-
> qapi/dump.json | 19 +-
> qapi/ebpf.json | 6 +-
> qapi/error.json | 4 +-
> qapi/introspect.json | 34 ++-
> qapi/job.json | 62 ++--
> qapi/machine-common.json | 24 +-
> qapi/machine.json | 110 +++----
> qapi/migration.json | 84 +++--
> qapi/misc-arm.json | 4 +-
> qapi/misc-i386.json | 32 +-
> qapi/misc.json | 28 +-
> qapi/net.json | 12 +-
> qapi/pci.json | 8 +-
> qapi/qapi-schema.json | 4 +-
> qapi/qdev.json | 11 +-
> qapi/qom.json | 89 ++++--
> qapi/replay.json | 14 +-
> qapi/rocker.json | 8 +-
> qapi/run-state.json | 52 ++--
> qapi/sockets.json | 10 +-
> qapi/stats.json | 14 +-
> qapi/tpm.json | 8 +-
> qapi/trace.json | 6 +-
> qapi/transaction.json | 16 +-
> qapi/uefi.json | 4 +-
> qapi/ui.json | 58 ++--
> qapi/vfio.json | 4 +-
> qapi/virtio.json | 20 +-
> qapi/yank.json | 22 +-
> qom/qom-qmp-cmds.c | 53 ++++
> tests/qtest/qom-test.c | 116 ++++++-
> python/qemu/utils/qom.py | 43 +--
> python/qemu/utils/qom_common.py | 53 ++++
> python/tests/qapi-isort.sh | 2 +-
> scripts/qapi/parser.py | 48 ++-
> scripts/qapi/schema.py | 3 +
> storage-daemon/qapi/qapi-schema.json | 8 +-
> tests/qapi-schema/doc-bad-section.err | 1 -
> tests/qapi-schema/doc-bad-section.json | 10 -
> tests/qapi-schema/doc-bad-section.out | 0
> tests/qapi-schema/doc-good.json | 10 +-
> tests/qapi-schema/doc-good.out | 10 +-
> tests/qapi-schema/doc-good.txt | 274 ++++++-----------
> tests/qapi-schema/meson.build | 1 -
> 67 files changed, 1053 insertions(+), 1301 deletions(-)
> delete mode 100644 docs/sphinx/qapidoc_legacy.py
> delete mode 100644 tests/qapi-schema/doc-bad-section.err
> delete mode 100644 tests/qapi-schema/doc-bad-section.json
> delete mode 100644 tests/qapi-schema/doc-bad-section.out
>
> --
> 2.49.0
>
>
^ permalink raw reply [flat|nested] 35+ messages in thread* Re: [PULL 00/32] QAPI patches patches for 2025-07-14
2025-07-15 4:26 ` [PULL 00/32] QAPI patches patches for 2025-07-14 Stefan Hajnoczi
@ 2025-07-15 6:30 ` Markus Armbruster
0 siblings, 0 replies; 35+ messages in thread
From: Markus Armbruster @ 2025-07-15 6:30 UTC (permalink / raw)
To: Stefan Hajnoczi; +Cc: John Snow, qemu-devel, stefanha
Stefan Hajnoczi <stefanha@gmail.com> writes:
> On Mon, Jul 14, 2025 at 11:14 AM Markus Armbruster <armbru@redhat.com> wrote:
>>
>> The following changes since commit 9a4e273ddec3927920c5958d2226c6b38b543336:
>>
>> Merge tag 'pull-tcg-20250711' of https://gitlab.com/rth7680/qemu into staging (2025-07-13 01:46:04 -0400)
>>
>> are available in the Git repository at:
>>
>> https://repo.or.cz/qemu/armbru.git tags/pull-qapi-2025-07-14
>>
>> for you to fetch changes up to 07273ca0ce3af397071f7a6c11abdab649ff25e1:
>>
>> tests/qtest/qom-test: unit test for qom-list-get (2025-07-14 15:25:12 +0200)
>>
>> ----------------------------------------------------------------
>> QAPI patches patches for 2025-07-14
>>
>> ----------------------------------------------------------------
>> John Snow (27):
>> docs/sphinx: adjust qapidoc to cope with same-line error sections
>> docs/sphinx: parse @references in freeform text
>> docs/sphinx: remove legacy QAPI manual generator
>> docs/sphinx: remove special parsing for freeform sections
>> qapi: lift restriction on using '=' in doc blocks
>> docs/qapi-domain: add return-nodesc
>> qapi: Fix undocumented return values by generating something
>> qapi: remove trivial "Returns:" sections
>> qapi: rephrase return docs to avoid type name
>> qapi: add cross-references to acpi.json
>> qapi: add cross-references to authz.json
>> qapi: add cross-references to block layer
>> qapi: add cross-references to crypto.json
>> qapi: add cross-references to dump.json
>> qapi: add cross-references to job.json
>> qapi: add cross-references to Machine core
>> qapi: add cross-references to migration.json
>> qapi: add cross-references to net.json
>> qapi: add cross-references to pci.json
>> qapi: add cross-references to QOM
>> qapi: add cross-references to replay.json
>> qapi: add cross-references to run-state.json
>> qapi: add cross-references to sockets.json
>> qapi: add cross-references to ui.json
>> qapi: add cross-references to virtio.json
>> qapi: add cross-references to yank.json
>> qapi: add cross-references to misc modules
>>
>> Markus Armbruster (2):
>> qapi: Clean up "This command will do ..." command descriptions
>> qapi: Clean up a few Errors: sections
>>
>> Steve Sistare (3):
>> qom: qom-list-get
>> python: use qom-list-get
>> tests/qtest/qom-test: unit test for qom-list-get
>
> The check-python-minreqs CI job is failing:
>
> qemu/utils/qom.py:35:1: F401 'qemu.qmp.ExecuteError' imported but unused
> qemu/utils/qom.py:241:34: E201 whitespace after '['
> qemu/utils/qom.py:241:56: E202 whitespace before ']'
> qemu/utils/qom.py:244:30: E711 comparison to None should be 'if cond is None:'
> qemu/utils/qom.py:245:33: F541 f-string is missing placeholders
> qemu/utils/qom.py:254:5: E303 too many blank lines (2)
> Log file "stderr" content for test "01-tests/flake8.sh" (FAIL):
> Log file "stdout" content for test "05-tests/mypy.sh" (FAIL):
> qemu/utils/qom_common.py:96: error: Function is missing a type
> annotation [no-untyped-def]
> qemu/utils/qom_common.py:192: error: Function is missing a type
> annotation for one or more arguments [no-untyped-def]
> qemu/utils/qom.py:227: error: Bracketed expression "[...]" is not
> valid as a type [valid-type]
> qemu/utils/qom.py:227: note: Did you mean "List[...]"?
> Found 3 errors in 2 files (checked 22 source files)
> Log file "stderr" content for test "05-tests/mypy.sh" (FAIL):
> Log file "stdout" content for test "33-tests/pylint.sh" (FAIL):
> ************* Module /builds/qemu-project/qemu/python/setup.cfg
> setup.cfg:1:0: W0012: Unknown option value for '--disable', expected a
> valid pylint message and got 'too-many-positional-arguments'
> (unknown-option-value)
> ************* Module utils.qom
> qemu/utils/qom.py:244:23: C0121: Comparison 'value == None' should be
> 'value is None' (singleton-comparison)
> qemu/utils/qom.py:245:32: W1309: Using an f-string that does not have
> any interpolated variables (f-string-without-interpolation)
> qemu/utils/qom.py:35:0: W0611: Unused ExecuteError imported from
> qemu.qmp (unused-import)
> ************* Module utils.qom_common
> qemu/utils/qom_common.py:92:0: R0903: Too few public methods (1/2)
> (too-few-public-methods)
>
> https://gitlab.com/qemu-project/qemu/-/jobs/10682353448
>
> Please take a look and resend this pull request if fixes are necessary. Thanks!
Sorry about that. I'm going to split this pull request: 29 unmodified
patches now, the three remaining as soon as they're ready.
^ permalink raw reply [flat|nested] 35+ messages in thread