diff options
49 files changed, 658 insertions, 556 deletions
diff --git a/README.rst b/README.rst index 21df79ef43..b120a1f69e 100644 --- a/README.rst +++ b/README.rst @@ -82,7 +82,7 @@ guidelines set out in the `style section the Developers Guide. Additional information on submitting patches can be found online via -the QEMU website +the QEMU website: * `<https://wiki.qemu.org/Contribute/SubmitAPatch>`_ * `<https://wiki.qemu.org/Contribute/TrivialPatches>`_ @@ -102,7 +102,7 @@ requires a working 'git send-email' setup, and by default doesn't automate everything, so you may want to go through the above steps manually for once. -For installation instructions, please go to +For installation instructions, please go to: * `<https://github.com/stefanha/git-publish>`_ @@ -159,7 +159,7 @@ Contact ======= The QEMU community can be contacted in a number of ways, with the two -main methods being email and IRC +main methods being email and IRC: * `<mailto:qemu-devel@nongnu.org>`_ * `<https://lists.nongnu.org/mailman/listinfo/qemu-devel>`_ diff --git a/accel/kvm/kvm-all.c b/accel/kvm/kvm-all.c index 2b4ab89679..64bf47a033 100644 --- a/accel/kvm/kvm-all.c +++ b/accel/kvm/kvm-all.c @@ -3878,7 +3878,7 @@ static StatsList *add_kvmstat_entry(struct kvm_stats_desc *pdesc, /* Alloc and populate data list */ stats = g_new0(Stats, 1); stats->name = g_strdup(pdesc->name); - stats->value = g_new0(StatsValue, 1);; + stats->value = g_new0(StatsValue, 1); if ((pdesc->flags & KVM_STATS_UNIT_MASK) == KVM_STATS_UNIT_BOOLEAN) { stats->value->u.boolean = *stats_data; diff --git a/backends/hostmem-epc.c b/backends/hostmem-epc.c index f58fcf00a1..6c024d6217 100644 --- a/backends/hostmem-epc.c +++ b/backends/hostmem-epc.c @@ -29,10 +29,8 @@ sgx_epc_backend_memory_alloc(HostMemoryBackend *backend, Error **errp) return false; } - fd = qemu_open_old("/dev/sgx_vepc", O_RDWR); + fd = qemu_open("/dev/sgx_vepc", O_RDWR, errp); if (fd < 0) { - error_setg_errno(errp, errno, - "failed to open /dev/sgx_vepc to alloc SGX EPC"); return false; } diff --git a/backends/iommufd.c b/backends/iommufd.c index 84fefbc9ee..cabd1b5002 100644 --- a/backends/iommufd.c +++ b/backends/iommufd.c @@ -77,9 +77,8 @@ bool iommufd_backend_connect(IOMMUFDBackend *be, Error **errp) int fd; if (be->owned && !be->users) { - fd = qemu_open_old("/dev/iommu", O_RDWR); + fd = qemu_open("/dev/iommu", O_RDWR, errp); if (fd < 0) { - error_setg_errno(errp, errno, "/dev/iommu opening failed"); return false; } be->fd = fd; diff --git a/backends/rng-random.c b/backends/rng-random.c index 80eb5be138..489c0917f0 100644 --- a/backends/rng-random.c +++ b/backends/rng-random.c @@ -75,10 +75,7 @@ static void rng_random_opened(RngBackend *b, Error **errp) error_setg(errp, QERR_INVALID_PARAMETER_VALUE, "filename", "a valid filename"); } else { - s->fd = qemu_open_old(s->filename, O_RDONLY | O_NONBLOCK); - if (s->fd == -1) { - error_setg_file_open(errp, errno, s->filename); - } + s->fd = qemu_open(s->filename, O_RDONLY | O_NONBLOCK, errp); } } diff --git a/block/curl.c b/block/curl.c index ef5252d00b..0fdb6d39ac 100644 --- a/block/curl.c +++ b/block/curl.c @@ -210,37 +210,29 @@ static size_t curl_header_cb(void *ptr, size_t size, size_t nmemb, void *opaque) { BDRVCURLState *s = opaque; size_t realsize = size * nmemb; - const char *header = (char *)ptr; - const char *end = header + realsize; - const char *accept_ranges = "accept-ranges:"; - const char *bytes = "bytes"; + const char *p = ptr; + const char *end = p + realsize; + const char *t = "accept-ranges : bytes "; /* A lowercase template */ - if (realsize >= strlen(accept_ranges) - && g_ascii_strncasecmp(header, accept_ranges, - strlen(accept_ranges)) == 0) { - - char *p = strchr(header, ':') + 1; - - /* Skip whitespace between the header name and value. */ - while (p < end && *p && g_ascii_isspace(*p)) { - p++; - } - - if (end - p >= strlen(bytes) - && strncmp(p, bytes, strlen(bytes)) == 0) { - - /* Check that there is nothing but whitespace after the value. */ - p += strlen(bytes); - while (p < end && *p && g_ascii_isspace(*p)) { - p++; - } - - if (p == end || !*p) { - s->accept_range = true; + /* check if header matches the "t" template */ + for (;;) { + if (*t == ' ') { /* space in t matches any amount of isspace in p */ + if (p < end && g_ascii_isspace(*p)) { + ++p; + } else { + ++t; } + } else if (*t && p < end && *t == g_ascii_tolower(*p)) { + ++p, ++t; + } else { + break; } } + if (!*t && p == end) { /* if we managed to reach ends of both strings */ + s->accept_range = true; + } + return realsize; } diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index ae97b335cb..583207a8ec 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -899,7 +899,7 @@ Documentation markup ~~~~~~~~~~~~~~~~~~~~ Documentation comments can use most rST markup. In particular, -a ``::`` literal block can be used for examples:: +a ``::`` literal block can be used for pre-formatted text:: # :: # @@ -995,8 +995,8 @@ line "Features:", like this:: # @feature: Description text A tagged section begins with a paragraph that starts with one of the -following words: "Since:", "Example:"/"Examples:", "Returns:", -"Errors:", "TODO:". It ends with the start of a new section. +following words: "Since:", "Returns:", "Errors:", "TODO:". It ends with +the start of a new section. The second and subsequent lines of tagged sections must be indented like this:: @@ -1020,13 +1020,53 @@ detailing a relevant error condition. For example:: A "Since: x.y.z" tagged section lists the release that introduced the definition. -An "Example" or "Examples" section is rendered entirely -as literal fixed-width text. "TODO" sections are not rendered at all -(they are for developers, not users of QMP). In other sections, the -text is formatted, and rST markup can be used. +"TODO" sections are not rendered (they are for developers, not users of +QMP). In other sections, the text is formatted, and rST markup can be +used. + +QMP Examples can be added by using the ``.. qmp-example::`` +directive. In its simplest form, this can be used to contain a single +QMP code block which accepts standard JSON syntax with additional server +directionality indicators (``->`` and ``<-``), and elisions (``...``). + +Optionally, a plaintext title may be provided by using the ``:title:`` +directive option. If the title is omitted, the example title will +default to "Example:". + +A simple QMP example:: + + # .. qmp-example:: + # :title: Using query-block + # + # -> { "execute": "query-block" } + # <- { ... } + +More complex or multi-step examples where exposition is needed before or +between QMP code blocks can be created by using the ``:annotated:`` +directive option. When using this option, nested QMP code blocks must be +entered explicitly with rST's ``::`` syntax. + +Highlighting in non-QMP languages can be accomplished by using the +``.. code-block:: lang`` directive, and non-highlighted text can be +achieved by omitting the language argument. For example:: + # .. qmp-example:: + # :annotated: + # :title: A more complex demonstration + # + # This is a more complex example that can use + # ``arbitrary rST syntax`` in its exposition:: + # + # -> { "execute": "query-block" } + # <- { ... } + # + # Above, lengthy output has been omitted for brevity. + + +Examples of complete definition documentation:: + ## # @BlockStats: # @@ -1058,11 +1098,11 @@ For example:: # # Since: 0.14 # - # Example: + # .. qmp-example:: # # -> { "execute": "query-blockstats" } # <- { - # ... lots of output ... + # ... # } ## { 'command': 'query-blockstats', diff --git a/docs/sphinx-static/theme_overrides.css b/docs/sphinx-static/theme_overrides.css index c70ef95128..965ecac54f 100644 --- a/docs/sphinx-static/theme_overrides.css +++ b/docs/sphinx-static/theme_overrides.css @@ -87,6 +87,55 @@ div[class^="highlight"] pre { padding-bottom: 1px; } +/* qmp-example directive styling */ + +.rst-content .admonition-example { + /* do not apply the standard admonition background */ + background-color: transparent; + border: solid #ffd2ed 1px; +} + +.rst-content .admonition-example > .admonition-title:before { + content: "▷"; +} + +.rst-content .admonition-example > .admonition-title { + background-color: #5980a6; +} + +.rst-content .admonition-example > div[class^="highlight"] { + /* make code boxes take up the full width of the admonition w/o margin */ + margin-left: -12px; + margin-right: -12px; + + border-top: 1px solid #ffd2ed; + border-bottom: 1px solid #ffd2ed; + border-left: 0px; + border-right: 0px; +} + +.rst-content .admonition-example > div[class^="highlight"]:nth-child(2) { + /* If a code box is the second element in an example admonition, + * it is the first child after the title. let it sit flush against + * the title. */ + margin-top: -12px; + border-top: 0px; +} + +.rst-content .admonition-example > div[class^="highlight"]:last-child { + /* If a code box is the final element in an example admonition, don't + * render margin below it; let it sit flush with the end of the + * admonition box */ + margin-bottom: -12px; + border-bottom: 0px; +} + +.rst-content .admonition-example .highlight { + background-color: #fffafd; +} + +/* end qmp-example styling */ + @media screen { /* content column diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 62b39833ca..738b2450fb 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -26,7 +26,9 @@ https://www.sphinx-doc.org/en/master/development/index.html import os import re +import sys import textwrap +from typing import List from docutils import nodes from docutils.parsers.rst import Directive, directives @@ -35,6 +37,8 @@ from qapi.error import QAPIError, QAPISemError from qapi.gen import QAPISchemaVisitor from qapi.schema import QAPISchema +from sphinx import addnodes +from sphinx.directives.code import CodeBlock from sphinx.errors import ExtensionError from sphinx.util.docutils import switch_source_input from sphinx.util.nodes import nested_parse_with_titles @@ -481,7 +485,25 @@ class QAPISchemaGenDepVisitor(QAPISchemaVisitor): super().visit_module(name) -class QAPIDocDirective(Directive): +class NestedDirective(Directive): + def run(self): + raise NotImplementedError + + def do_parse(self, rstlist, node): + """ + Parse rST source lines and add them to the specified node + + Take the list of rST source lines rstlist, parse them as + rST, and add the resulting docutils nodes as children of node. + The nodes are parsed in a way that allows them to include + subheadings (titles) without confusing the rendering of + anything else. + """ + with switch_source_input(self.state, rstlist): + nested_parse_with_titles(self.state, rstlist, node) + + +class QAPIDocDirective(NestedDirective): """Extract documentation from the specified QAPI .json file""" required_argument = 1 @@ -519,23 +541,107 @@ class QAPIDocDirective(Directive): # so they are displayed nicely to the user raise ExtensionError(str(err)) from err - def do_parse(self, rstlist, node): - """Parse rST source lines and add them to the specified node - Take the list of rST source lines rstlist, parse them as - rST, and add the resulting docutils nodes as children of node. - The nodes are parsed in a way that allows them to include - subheadings (titles) without confusing the rendering of - anything else. - """ - with switch_source_input(self.state, rstlist): - nested_parse_with_titles(self.state, rstlist, node) +class QMPExample(CodeBlock, NestedDirective): + """ + Custom admonition for QMP code examples. + + When the :annotated: option is present, the body of this directive + is parsed as normal rST, but with any '::' code blocks set to use + the QMP lexer. Code blocks must be explicitly written by the user, + but this allows for intermingling explanatory paragraphs with + arbitrary rST syntax and code blocks for more involved examples. + + When :annotated: is absent, the directive body is treated as a + simple standalone QMP code block literal. + """ + + required_argument = 0 + optional_arguments = 0 + has_content = True + option_spec = { + "annotated": directives.flag, + "title": directives.unchanged, + } + + def _highlightlang(self) -> addnodes.highlightlang: + """Return the current highlightlang setting for the document""" + node = None + doc = self.state.document + + if hasattr(doc, "findall"): + # docutils >= 0.18.1 + for node in doc.findall(addnodes.highlightlang): + pass + else: + for elem in doc.traverse(): + if isinstance(elem, addnodes.highlightlang): + node = elem + + if node: + return node + + # No explicit directive found, use defaults + node = addnodes.highlightlang( + lang=self.env.config.highlight_language, + force=False, + # Yes, Sphinx uses this value to effectively disable line + # numbers and not 0 or None or -1 or something. ¯\_(ツ)_/¯ + linenothreshold=sys.maxsize, + ) + return node + + def admonition_wrap(self, *content) -> List[nodes.Node]: + title = "Example:" + if "title" in self.options: + title = f"{title} {self.options['title']}" + + admon = nodes.admonition( + "", + nodes.title("", title), + *content, + classes=["admonition", "admonition-example"], + ) + return [admon] + + def run_annotated(self) -> List[nodes.Node]: + lang_node = self._highlightlang() + + content_node: nodes.Element = nodes.section() + + # Configure QMP highlighting for "::" blocks, if needed + if lang_node["lang"] != "QMP": + content_node += addnodes.highlightlang( + lang="QMP", + force=False, # "True" ignores lexing errors + linenothreshold=lang_node["linenothreshold"], + ) + + self.do_parse(self.content, content_node) + + # Restore prior language highlighting, if needed + if lang_node["lang"] != "QMP": + content_node += addnodes.highlightlang(**lang_node.attributes) + + return content_node.children + + def run(self) -> List[nodes.Node]: + annotated = "annotated" in self.options + + if annotated: + content_nodes = self.run_annotated() + else: + self.arguments = ["QMP"] + content_nodes = super().run() + + return self.admonition_wrap(*content_nodes) def setup(app): """Register qapi-doc directive with Sphinx""" app.add_config_value("qapidoc_srctree", None, "env") app.add_directive("qapi-doc", QAPIDocDirective) + app.add_directive("qmp-example", QMPExample) return { "version": __version__, diff --git a/hw/i386/sgx.c b/hw/i386/sgx.c index de76397bcf..a14a84bc6f 100644 --- a/hw/i386/sgx.c +++ b/hw/i386/sgx.c @@ -157,10 +157,12 @@ SGXInfo *qmp_query_sgx_capabilities(Error **errp) { SGXInfo *info = NULL; uint32_t eax, ebx, ecx, edx; + Error *local_err = NULL; - int fd = qemu_open_old("/dev/sgx_vepc", O_RDWR); + int fd = qemu_open("/dev/sgx_vepc", O_RDWR, &local_err); if (fd < 0) { - error_setg(errp, "SGX is not enabled in KVM"); + error_append_hint(&local_err, "SGX is not enabled in KVM"); + error_propagate(errp, local_err); return NULL; } diff --git a/hw/i386/x86.c b/hw/i386/x86.c index a4aa8e0810..01fc5e6562 100644 --- a/hw/i386/x86.c +++ b/hw/i386/x86.c @@ -242,7 +242,7 @@ static void x86_machine_get_pit(Object *obj, Visitor *v, const char *name, static void x86_machine_set_pit(Object *obj, Visitor *v, const char *name, void *opaque, Error **errp) { - X86MachineState *x86ms = X86_MACHINE(obj);; + X86MachineState *x86ms = X86_MACHINE(obj); visit_type_OnOffAuto(v, name, &x86ms->pit, errp); } diff --git a/hw/usb/host-libusb.c b/hw/usb/host-libusb.c index 80122b4125..691bc881fb 100644 --- a/hw/usb/host-libusb.c +++ b/hw/usb/host-libusb.c @@ -1212,9 +1212,8 @@ static void usb_host_realize(USBDevice *udev, Error **errp) if (s->hostdevice) { int fd; s->needs_autoscan = false; - fd = qemu_open_old(s->hostdevice, O_RDWR); + fd = qemu_open(s->hostdevice, O_RDWR, errp); if (fd < 0) { - error_setg_errno(errp, errno, "failed to open %s", s->hostdevice); return; } rc = usb_host_open(s, NULL, fd); diff --git a/hw/usb/u2f-passthru.c b/hw/usb/u2f-passthru.c index b7025d303d..c4a783d128 100644 --- a/hw/usb/u2f-passthru.c +++ b/hw/usb/u2f-passthru.c @@ -482,10 +482,8 @@ static void u2f_passthru_realize(U2FKeyState *base, Error **errp) return; #endif } else { - fd = qemu_open_old(key->hidraw, O_RDWR); + fd = qemu_open(key->hidraw, O_RDWR, errp); if (fd < 0) { - error_setg(errp, "%s: Failed to open %s", TYPE_U2F_PASSTHRU, - key->hidraw); return; } diff --git a/hw/vfio/container.c b/hw/vfio/container.c index 425db1a14c..38a9df3496 100644 --- a/hw/vfio/container.c +++ b/hw/vfio/container.c @@ -600,9 +600,8 @@ static bool vfio_connect_container(VFIOGroup *group, AddressSpace *as, } } - fd = qemu_open_old("/dev/vfio/vfio", O_RDWR); + fd = qemu_open("/dev/vfio/vfio", O_RDWR, errp); if (fd < 0) { - error_setg_errno(errp, errno, "failed to open /dev/vfio/vfio"); goto put_space_exit; } @@ -743,9 +742,8 @@ static VFIOGroup *vfio_get_group(int groupid, AddressSpace *as, Error **errp) group = g_malloc0(sizeof(*group)); snprintf(path, sizeof(path), "/dev/vfio/%d", groupid); - group->fd = qemu_open_old(path, O_RDWR); + group->fd = qemu_open(path, O_RDWR, errp); if (group->fd < 0) { - error_setg_errno(errp, errno, "failed to open %s", path); goto free_group_exit; } diff --git a/qapi/acpi.json b/qapi/acpi.json index aa4dbe5794..045dab6228 100644 --- a/qapi/acpi.json +++ b/qapi/acpi.json @@ -111,7 +111,7 @@ # # Since: 2.1 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-acpi-ospm-status" } # <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0}, @@ -131,7 +131,7 @@ # # Since: 2.1 # -# Example: +# .. qmp-example:: # # <- { "event": "ACPI_DEVICE_OST", # "data": { "info": { "device": "d1", "slot": "0", diff --git a/qapi/block-core.json b/qapi/block-core.json index 096bdbe0aa..f400b334c8 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -764,7 +764,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-block" } # <- { @@ -1168,7 +1168,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-blockstats" } # <- { @@ -1461,7 +1461,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "block_resize", # "arguments": { "device": "scratch", "size": 1073741824 } } @@ -1680,7 +1680,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "blockdev-snapshot-sync", # "arguments": { "device": "ide-hd0", @@ -1711,7 +1711,7 @@ # # Since: 2.5 # -# Example: +# .. qmp-example:: # # -> { "execute": "blockdev-add", # "arguments": { "driver": "qcow2", @@ -1857,7 +1857,7 @@ # # Since: 1.3 # -# Example: +# .. qmp-example:: # # -> { "execute": "block-commit", # "arguments": { "device": "virtio0", @@ -1895,7 +1895,7 @@ # # Since: 1.6 # -# Example: +# .. qmp-example:: # # -> { "execute": "drive-backup", # "arguments": { "device": "drive0", @@ -1921,7 +1921,7 @@ # # Since: 2.3 # -# Example: +# .. qmp-example:: # # -> { "execute": "blockdev-backup", # "arguments": { "device": "src-id", @@ -1945,7 +1945,7 @@ # # Since: 2.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-named-block-nodes" } # <- { "return": [ { "ro":false, @@ -2126,7 +2126,7 @@ # # Since: 1.3 # -# Example: +# .. qmp-example:: # # -> { "execute": "drive-mirror", # "arguments": { "device": "ide-hd0", @@ -2303,7 +2303,7 @@ # # Since: 2.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "block-dirty-bitmap-add", # "arguments": { "node": "drive0", "name": "bitmap0" } } @@ -2327,7 +2327,7 @@ # # Since: 2.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "block-dirty-bitmap-remove", # "arguments": { "node": "drive0", "name": "bitmap0" } } @@ -2350,7 +2350,7 @@ # # Since: 2.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "block-dirty-bitmap-clear", # "arguments": { "node": "drive0", "name": "bitmap0" } } @@ -2371,7 +2371,7 @@ # # Since: 4.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "block-dirty-bitmap-enable", # "arguments": { "node": "drive0", "name": "bitmap0" } } @@ -2392,7 +2392,7 @@ # # Since: 4.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "block-dirty-bitmap-disable", # "arguments": { "node": "drive0", "name": "bitmap0" } } @@ -2424,7 +2424,7 @@ # # Since: 4.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "block-dirty-bitmap-merge", # "arguments": { "node": "drive0", "target": "bitmap0", @@ -2533,7 +2533,7 @@ # # Since: 2.6 # -# Example: +# .. qmp-example:: # # -> { "execute": "blockdev-mirror", # "arguments": { "device": "ide-hd0", @@ -2858,7 +2858,7 @@ # # Since: 1.1 # -# Example: +# .. qmp-example:: # # -> { "execute": "block-stream", # "arguments": { "device": "virtio0", @@ -4797,7 +4797,7 @@ # # Since: 2.9 # -# Examples: +# .. qmp-example:: # # -> { "execute": "blockdev-add", # "arguments": { @@ -4811,6 +4811,8 @@ # } # <- { "return": {} } # +# .. qmp-example:: +# # -> { "execute": "blockdev-add", # "arguments": { # "driver": "qcow2", @@ -4895,7 +4897,7 @@ # # Since: 2.9 # -# Example: +# .. qmp-example:: # # -> { "execute": "blockdev-add", # "arguments": { @@ -5544,7 +5546,7 @@ # .. note:: If action is "stop", a STOP event will eventually follow the # BLOCK_IO_ERROR event. # -# Example: +# .. qmp-example:: # # <- { "event": "BLOCK_IMAGE_CORRUPTED", # "data": { "device": "", "node-name": "drive", "fatal": false, @@ -5593,7 +5595,7 @@ # # Since: 0.13 # -# Example: +# .. qmp-example:: # # <- { "event": "BLOCK_IO_ERROR", # "data": { "device": "ide0-hd1", @@ -5633,7 +5635,7 @@ # # Since: 1.1 # -# Example: +# .. qmp-example:: # # <- { "event": "BLOCK_JOB_COMPLETED", # "data": { "type": "stream", "device": "virtio-disk0", @@ -5668,7 +5670,7 @@ # # Since: 1.1 # -# Example: +# .. qmp-example:: # # <- { "event": "BLOCK_JOB_CANCELLED", # "data": { "type": "stream", "device": "virtio-disk0", @@ -5697,7 +5699,7 @@ # # Since: 1.3 # -# Example: +# .. qmp-example:: # # <- { "event": "BLOCK_JOB_ERROR", # "data": { "device": "ide0-hd1", @@ -5732,7 +5734,7 @@ # # Since: 1.3 # -# Example: +# .. qmp-example:: # # <- { "event": "BLOCK_JOB_READY", # "data": { "device": "drive0", "type": "mirror", "speed": 0, @@ -5760,7 +5762,7 @@ # # Since: 2.12 # -# Example: +# .. qmp-example:: # # <- { "event": "BLOCK_JOB_PENDING", # "data": { "type": "mirror", "id": "backup_1" }, @@ -5834,7 +5836,7 @@ # # Since: 2.3 # -# Example: +# .. qmp-example:: # # -> { "execute": "block-set-write-threshold", # "arguments": { "node-name": "mydev", @@ -5879,9 +5881,8 @@ # # Since: 2.7 # -# Examples: -# -# 1. Add a new node to a quorum +# .. qmp-example:: +# :title: Add a new node to a quorum # # -> { "execute": "blockdev-add", # "arguments": { @@ -5895,7 +5896,8 @@ # "node": "new_node" } } # <- { "return": {} } # -# 2. Delete a quorum's node +# .. qmp-example:: +# :title: Delete a quorum's node # # -> { "execute": "x-blockdev-change", # "arguments": { "parent": "disk1", @@ -5931,16 +5933,16 @@ # # Since: 2.12 # -# Examples: -# -# 1. Move a node into an IOThread +# .. qmp-example:: +# :title: Move a node into an IOThread # # -> { "execute": "x-blockdev-set-iothread", # "arguments": { "node-name": "disk1", # "iothread": "iothread0" } } # <- { "return": {} } # -# 2. Move a node into the main loop +# .. qmp-example:: +# :title: Move a node into the main loop # # -> { "execute": "x-blockdev-set-iothread", # "arguments": { "node-name": "disk1", @@ -5985,7 +5987,7 @@ # # Since: 2.0 # -# Example: +# .. qmp-example:: # # <- { "event": "QUORUM_FAILURE", # "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 }, @@ -6016,16 +6018,16 @@ # # Since: 2.0 # -# Examples: -# -# 1. Read operation +# .. qmp-example:: +# :title: Read operation # # <- { "event": "QUORUM_REPORT_BAD", # "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5, # "type": "read" }, # "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } # -# 2. Flush operation +# .. qmp-example:: +# :title: Flush operation # # <- { "event": "QUORUM_REPORT_BAD", # "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120, @@ -6070,7 +6072,7 @@ # # Since: 1.7 # -# Example: +# .. qmp-example:: # # -> { "execute": "blockdev-snapshot-internal-sync", # "arguments": { "device": "ide-hd0", @@ -6109,7 +6111,7 @@ # # Since: 1.7 # -# Example: +# .. qmp-example:: # # -> { "execute": "blockdev-snapshot-delete-internal-sync", # "arguments": { "device": "ide-hd0", diff --git a/qapi/block.json b/qapi/block.json index ea81d9e192..ce9490a367 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -117,7 +117,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } } # <- { "return": {} } @@ -161,7 +161,7 @@ # # Since: 2.5 # -# Example: +# .. qmp-example:: # # -> { "execute": "blockdev-open-tray", # "arguments": { "id": "ide0-1-0" } } @@ -199,7 +199,7 @@ # # Since: 2.5 # -# Example: +# .. qmp-example:: # # -> { "execute": "blockdev-close-tray", # "arguments": { "id": "ide0-1-0" } } @@ -231,7 +231,7 @@ # # Since: 2.12 # -# Example: +# .. qmp-example:: # # -> { "execute": "blockdev-remove-medium", # "arguments": { "id": "ide0-1-0" } } @@ -272,7 +272,7 @@ # # Since: 2.12 # -# Example: +# .. qmp-example:: # # -> { "execute": "blockdev-add", # "arguments": { @@ -342,9 +342,8 @@ # # Since: 2.5 # -# Examples: -# -# 1. Change a removable medium +# .. qmp-example:: +# :title: Change a removable medium # # -> { "execute": "blockdev-change-medium", # "arguments": { "id": "ide0-1-0", @@ -352,7 +351,8 @@ # "format": "raw" } } # <- { "return": {} } # -# 2. Load a read-only medium into a writable drive +# .. qmp-example:: +# :title: Load a read-only medium into a writable drive # # -> { "execute": "blockdev-change-medium", # "arguments": { "id": "floppyA", @@ -397,7 +397,7 @@ # # Since: 1.1 # -# Example: +# .. qmp-example:: # # <- { "event": "DEVICE_TRAY_MOVED", # "data": { "device": "ide1-cd0", @@ -421,7 +421,7 @@ # # Since: 3.0 # -# Example: +# .. qmp-example:: # # <- { "event": "PR_MANAGER_STATUS_CHANGED", # "data": { "id": "pr-helper0", @@ -463,7 +463,7 @@ # # Since: 1.1 # -# Examples: +# .. qmp-example:: # # -> { "execute": "block_set_io_throttle", # "arguments": { "id": "virtio-blk-pci0/virtio-backend", @@ -483,6 +483,8 @@ # "iops_size": 0 } } # <- { "return": {} } # +# .. qmp-example:: +# # -> { "execute": "block_set_io_throttle", # "arguments": { "id": "ide0-1-0", # "bps": 1000000, @@ -543,31 +545,37 @@ # # Since: 4.0 # -# Example: +# .. qmp-example:: +# :annotated: # -# Set new histograms for all io types with intervals -# [0, 10), [10, 50), [50, 100), [100, +inf): +# Set new histograms for all io types with intervals +# [0, 10), [10, 50), [50, 100), [100, +inf):: # # -> { "execute": "block-latency-histogram-set", # "arguments": { "id": "drive0", # "boundaries": [10, 50, 100] } } # <- { "return": {} } # -# Example: +# .. qmp-example:: +# :annotated: # -# Set new histogram only for write, other histograms will remain -# not changed (or not created): +# Set new histogram only for write, other histograms will remain +# not changed (or not created):: # # -> { "execute": "block-latency-histogram-set", # "arguments": { "id": "drive0", # "boundaries-write": [10, 50, 100] } } # <- { "return": {} } # -# Example: +# .. qmp-example:: +# :annotated: +# +# Set new histograms with the following intervals: +# +# - read, flush: [0, 10), [10, 50), [50, 100), [100, +inf) +# - write: [0, 1000), [1000, 5000), [5000, +inf) # -# Set new histograms with the following intervals: -# read, flush: [0, 10), [10, 50), [50, 100), [100, +inf) -# write: [0, 1000), [1000, 5000), [5000, +inf) +# :: # # -> { "execute": "block-latency-histogram-set", # "arguments": { "id": "drive0", @@ -575,9 +583,10 @@ # "boundaries-write": [1000, 5000] } } # <- { "return": {} } # -# Example: +# .. qmp-example:: +# :annotated: # -# Remove all latency histograms: +# Remove all latency histograms:: # # -> { "execute": "block-latency-histogram-set", # "arguments": { "id": "drive0" } } diff --git a/qapi/char.json b/qapi/char.json index 5eabf8e764..5e4aeb9799 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -40,7 +40,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-chardev" } # <- { @@ -86,7 +86,7 @@ # # Since: 2.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-chardev-backends" } # <- { @@ -141,7 +141,7 @@ # # Since: 1.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "ringbuf-write", # "arguments": { "device": "foo", @@ -177,7 +177,7 @@ # # Since: 1.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "ringbuf-read", # "arguments": { "device": "foo", @@ -699,19 +699,23 @@ # # Since: 1.4 # -# Examples: +# .. qmp-example:: # # -> { "execute" : "chardev-add", # "arguments" : { "id" : "foo", # "backend" : { "type" : "null", "data" : {} } } } # <- { "return": {} } # +# .. qmp-example:: +# # -> { "execute" : "chardev-add", # "arguments" : { "id" : "bar", # "backend" : { "type" : "file", # "data" : { "out" : "/tmp/bar.log" } } } } # <- { "return": {} } # +# .. qmp-example:: +# # -> { "execute" : "chardev-add", # "arguments" : { "id" : "baz", # "backend" : { "type" : "pty", "data" : {} } } } @@ -735,13 +739,15 @@ # # Since: 2.10 # -# Examples: +# .. qmp-example:: # # -> { "execute" : "chardev-change", # "arguments" : { "id" : "baz", # "backend" : { "type" : "pty", "data" : {} } } } # <- { "return": { "pty" : "/dev/pty/42" } } # +# .. qmp-example:: +# # -> {"execute" : "chardev-change", # "arguments" : { # "id" : "charchannel2", @@ -772,7 +778,7 @@ # # Since: 1.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } } # <- { "return": {} } @@ -789,7 +795,7 @@ # # Since: 2.10 # -# Example: +# .. qmp-example:: # # -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } } # <- { "return": {} } @@ -810,7 +816,7 @@ # # Since: 2.1 # -# Example: +# .. qmp-example:: # # <- { "event": "VSERPORT_CHANGE", # "data": { "id": "channel0", "open": true }, diff --git a/qapi/control.json b/qapi/control.json index fe2af45120..950443df9d 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -16,7 +16,7 @@ # the QMP greeting message. If the field is not provided, it # means no QMP capabilities will be enabled. (since 2.12) # -# Example: +# .. qmp-example:: # # -> { "execute": "qmp_capabilities", # "arguments": { "enable": [ "oob" ] } } @@ -97,7 +97,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-version" } # <- { @@ -134,7 +134,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-commands" } # <- { @@ -165,7 +165,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "quit" } # <- { "return": {} } diff --git a/qapi/dump.json b/qapi/dump.json index f9aee7ea1d..d8145dad97 100644 --- a/qapi/dump.json +++ b/qapi/dump.json @@ -94,7 +94,7 @@ # # Since: 1.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "dump-guest-memory", # "arguments": { "paging": false, "protocol": "fd:dump" } } @@ -150,7 +150,7 @@ # # Since: 2.6 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-dump" } # <- { "return": { "status": "active", "completed": 1024000, @@ -171,7 +171,7 @@ # # Since: 2.6 # -# Example: +# .. qmp-example:: # # <- { "event": "DUMP_COMPLETED", # "data": { "result": { "total": 1090650112, "status": "completed", @@ -202,7 +202,7 @@ # # Since: 2.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-dump-guest-memory-capability" } # <- { "return": { "formats": diff --git a/qapi/machine-target.json b/qapi/machine-target.json index a8d9ec87f5..7edb876b5c 100644 --- a/qapi/machine-target.json +++ b/qapi/machine-target.json @@ -475,7 +475,7 @@ # # Since: 8.2 # -# Example: +# .. qmp-example:: # # <- { "event": "CPU_POLARIZATION_CHANGE", # "data": { "polarization": "horizontal" }, diff --git a/qapi/machine.json b/qapi/machine.json index f15ad1b43e..f9ea6b3e97 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -104,7 +104,7 @@ # # Since: 2.12 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-cpus-fast" } # <- { "return": [ @@ -221,7 +221,7 @@ # # Since: 1.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-machines", "arguments": { "compat-props": true } } # <- { "return": [ @@ -305,9 +305,8 @@ # # Since: 0.14 # -# .. note:: If no UUID was specified for the guest, a null UUID is -# returned. -# +# .. note:: If no UUID was specified for the guest, the nil UUID (all +# zeroes) is returned. ## { 'struct': 'UuidInfo', 'data': {'UUID': 'str'} } @@ -320,7 +319,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-uuid" } # <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } } @@ -354,7 +353,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "system_reset" } # <- { "return": {} } @@ -373,7 +372,7 @@ # request or that it has shut down. Many guests will respond to this # command by prompting the user in some way. # -# Example: +# .. qmp-example:: # # -> { "execute": "system_powerdown" } # <- { "return": {} } @@ -393,7 +392,7 @@ # .. note:: Prior to 4.0, this command does nothing in case the guest # isn't suspended. # -# Example: +# .. qmp-example:: # # -> { "execute": "system_wakeup" } # <- { "return": {} } @@ -444,7 +443,7 @@ # .. note:: Prior to 2.1, this command was only supported for x86 and # s390 VMs. # -# Example: +# .. qmp-example:: # # -> { "execute": "inject-nmi" } # <- { "return": {} } @@ -473,7 +472,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-kvm" } # <- { "return": { "enabled": true, "present": true } } @@ -842,7 +841,7 @@ # # .. caution:: Errors were not reliably returned until 1.1. # -# Example: +# .. qmp-example:: # # -> { "execute": "memsave", # "arguments": { "val": 10, @@ -868,7 +867,7 @@ # # .. caution:: Errors were not reliably returned until 1.1. # -# Example: +# .. qmp-example:: # # -> { "execute": "pmemsave", # "arguments": { "val": 10, @@ -929,7 +928,7 @@ # # Since: 2.1 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-memdev" } # <- { "return": [ @@ -960,9 +959,7 @@ ## # @CpuInstanceProperties: # -# List of properties to be used for hotplugging a CPU instance, it -# should be passed by management with device_add command when a CPU is -# being hotplugged. +# Properties identifying a CPU. # # Which members are optional and which mandatory depends on the # architecture and board. @@ -996,9 +993,6 @@ # # @thread-id: thread number within the core the CPU belongs to # -# .. note:: Management should be prepared to pass through additional -# properties with device_add. -# # Since: 2.7 ## { 'struct': 'CpuInstanceProperties', @@ -1020,7 +1014,8 @@ # # @type: CPU object type for usage with device_add command # -# @props: list of properties to be used for hotplugging CPU +# @props: list of properties to pass for hotplugging a CPU with +# device_add # # @vcpus-count: number of logical VCPU threads @HotpluggableCPU # provides @@ -1028,6 +1023,9 @@ # @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. +# # Since: 2.7 ## { 'struct': 'HotpluggableCPU', @@ -1047,10 +1045,11 @@ # # Since: 2.7 # -# Examples: +# .. qmp-example:: +# :annotated: # -# For pseries machine type started with -smp 2,cores=2,maxcpus=4 -# -cpu POWER8: +# For pseries machine type started with +# ``-smp 2,cores=2,maxcpus=4 -cpu POWER8``:: # # -> { "execute": "query-hotpluggable-cpus" } # <- {"return": [ @@ -1060,7 +1059,10 @@ # "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"} # ]} # -# For pc machine type started with -smp 1,maxcpus=2: +# .. qmp-example:: +# :annotated: +# +# For pc machine type started with ``-smp 1,maxcpus=2``:: # # -> { "execute": "query-hotpluggable-cpus" } # <- {"return": [ @@ -1075,8 +1077,11 @@ # } # ]} # -# For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -# -cpu qemu (Since: 2.11): +# .. qmp-example:: +# :annotated: +# +# For s390x-virtio-ccw machine type started with +# ``-smp 1,maxcpus=2 -cpu qemu`` (Since: 2.11):: # # -> { "execute": "query-hotpluggable-cpus" } # <- {"return": [ @@ -1130,12 +1135,15 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: +# :annotated: # -# -> { "execute": "balloon", "arguments": { "value": 536870912 } } -# <- { "return": {} } +# :: +# +# -> { "execute": "balloon", "arguments": { "value": 536870912 } } +# <- { "return": {} } # -# With a 2.5GiB guest this command inflated the ballon to 3GiB. +# With a 2.5GiB guest this command inflated the ballon to 3GiB. ## { 'command': 'balloon', 'data': {'value': 'int'} } @@ -1166,7 +1174,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-balloon" } # <- { "return": { @@ -1190,7 +1198,7 @@ # # Since: 1.2 # -# Example: +# .. qmp-example:: # # <- { "event": "BALLOON_CHANGE", # "data": { "actual": 944766976 }, @@ -1232,7 +1240,7 @@ # # Since: 8.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-hv-balloon-status-report" } # <- { "return": { @@ -1253,7 +1261,7 @@ # # Since: 8.2 # -# Example: +# .. qmp-example:: # # <- { "event": "HV_BALLOON_STATUS_REPORT", # "data": { "committed": 816640000, "available": 3333054464 }, @@ -1285,7 +1293,7 @@ # Return the amount of initially allocated and present hotpluggable # (if enabled) memory in bytes. # -# Example: +# .. qmp-example:: # # -> { "execute": "query-memory-size-summary" } # <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } } @@ -1564,7 +1572,7 @@ # # Since: 2.1 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-memory-devices" } # <- { "return": [ { "data": @@ -1598,7 +1606,7 @@ # # Since: 5.1 # -# Example: +# .. qmp-example:: # # <- { "event": "MEMORY_DEVICE_SIZE_CHANGE", # "data": { "id": "vm0", "size": 1073741824, @@ -1856,7 +1864,7 @@ # # Since: 7.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "dumpdtb" } # "arguments": { "filename": "fdt.dtb" } } diff --git a/qapi/migration.json b/qapi/migration.json index 1234bef888..073b67c052 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -287,14 +287,14 @@ # # Since: 0.14 # -# Examples: -# -# 1. Before the first migration +# .. qmp-example:: +# :title: Before the first migration # # -> { "execute": "query-migrate" } # <- { "return": {} } # -# 2. Migration is done and has succeeded +# .. qmp-example:: +# :title: Migration is done and has succeeded # # -> { "execute": "query-migrate" } # <- { "return": { @@ -314,12 +314,14 @@ # } # } # -# 3. Migration is done and has failed +# .. qmp-example:: +# :title: Migration is done and has failed # # -> { "execute": "query-migrate" } # <- { "return": { "status": "failed" } } # -# 4. Migration is being performed: +# .. qmp-example:: +# :title: Migration is being performed # # -> { "execute": "query-migrate" } # <- { @@ -340,7 +342,8 @@ # } # } # -# 5. Migration is being performed and XBZRLE is active: +# .. qmp-example:: +# :title: Migration is being performed and XBZRLE is active # # -> { "execute": "query-migrate" } # <- { @@ -514,7 +517,7 @@ # # Since: 1.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "migrate-set-capabilities" , "arguments": # { "capabilities": [ { "capability": "xbzrle", "state": true } ] } } @@ -532,7 +535,7 @@ # # Since: 1.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-migrate-capabilities" } # <- { "return": [ @@ -1053,7 +1056,7 @@ # # Since: 2.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "migrate-set-parameters" , # "arguments": { "multifd-channels": 5 } } @@ -1256,7 +1259,7 @@ # # Since: 2.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-migrate-parameters" } # <- { "return": { @@ -1280,7 +1283,7 @@ # # Since: 2.5 # -# Example: +# .. qmp-example:: # # -> { "execute": "migrate-start-postcopy" } # <- { "return": {} } @@ -1296,7 +1299,7 @@ # # Since: 2.4 # -# Example: +# .. qmp-example:: # # <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001}, # "event": "MIGRATION", @@ -1315,7 +1318,7 @@ # # Since: 2.6 # -# Example: +# .. qmp-example:: # # <- { "timestamp": {"seconds": 1449669631, "microseconds": 239225}, # "event": "MIGRATION_PASS", "data": {"pass": 2} } @@ -1399,7 +1402,7 @@ # # Since: 3.1 # -# Example: +# .. qmp-example:: # # <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172}, # "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } } @@ -1442,7 +1445,7 @@ # # Since: 2.8 # -# Example: +# .. qmp-example:: # # -> { "execute": "x-colo-lost-heartbeat" } # <- { "return": {} } @@ -1461,7 +1464,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "migrate_cancel" } # <- { "return": {} } @@ -1477,7 +1480,7 @@ # # Since: 2.11 # -# Example: +# .. qmp-example:: # # -> { "execute": "migrate-continue" , "arguments": # { "state": "pre-switchover" } } @@ -1610,7 +1613,7 @@ # 6. The 'uri' and 'channels' arguments are mutually exclusive; # exactly one of the two should be present. # -# Example: +# .. qmp-example:: # # -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } } # <- { "return": {} } @@ -1689,7 +1692,7 @@ # 5. The 'uri' and 'channels' arguments are mutually exclusive; # exactly one of the two should be present. # -# Example: +# .. qmp-example:: # # -> { "execute": "migrate-incoming", # "arguments": { "uri": "tcp:0:4446" } } @@ -1740,7 +1743,7 @@ # # Since: 1.1 # -# Example: +# .. qmp-example:: # # -> { "execute": "xen-save-devices-state", # "arguments": { "filename": "/tmp/save" } } @@ -1758,7 +1761,7 @@ # # Since: 1.3 # -# Example: +# .. qmp-example:: # # -> { "execute": "xen-set-global-dirty-log", # "arguments": { "enable": true } } @@ -1778,7 +1781,7 @@ # # Since: 2.7 # -# Example: +# .. qmp-example:: # # -> { "execute": "xen-load-devices-state", # "arguments": { "filename": "/tmp/resume" } } @@ -1798,7 +1801,7 @@ # @failover: true to do failover, false to stop. Cannot be specified # if 'enable' is true. Default value is false. # -# Example: +# .. qmp-example:: # # -> { "execute": "xen-set-replication", # "arguments": {"enable": true, "primary": false} } @@ -1833,7 +1836,7 @@ # # Returns: A @ReplicationStatus object showing the status. # -# Example: +# .. qmp-example:: # # -> { "execute": "query-xen-replication-status" } # <- { "return": { "error": false } } @@ -1849,7 +1852,7 @@ # # Xen uses this command to notify replication to trigger a checkpoint. # -# Example: +# .. qmp-example:: # # -> { "execute": "xen-colo-do-checkpoint" } # <- { "return": {} } @@ -1887,7 +1890,7 @@ # # Returns: A @COLOStatus object showing the status. # -# Example: +# .. qmp-example:: # # -> { "execute": "query-colo-status" } # <- { "return": { "mode": "primary", "last-mode": "none", "reason": "request" } } @@ -1905,7 +1908,7 @@ # # @uri: the URI to be used for the recovery of migration stream. # -# Example: +# .. qmp-example:: # # -> { "execute": "migrate-recover", # "arguments": { "uri": "tcp:192.168.1.200:12345" } } @@ -1922,7 +1925,7 @@ # # Pause a migration. Currently it only supports postcopy. # -# Example: +# .. qmp-example:: # # -> { "execute": "migrate-pause" } # <- { "return": {} } @@ -1943,7 +1946,7 @@ # # Since: 4.2 # -# Example: +# .. qmp-example:: # # <- { "event": "UNPLUG_PRIMARY", # "data": { "device-id": "hostdev0" }, @@ -2103,13 +2106,16 @@ # # Since: 5.2 # -# Example: +# .. qmp-example:: # # -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, # "sample-pages": 512} } # <- { "return": {} } # -# Measure dirty rate using dirty bitmap for 500 milliseconds: +# .. qmp-example:: +# :annotated: +# +# Measure dirty rate using dirty bitmap for 500 milliseconds:: # # -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 500, # "calc-time-unit": "millisecond", "mode": "dirty-bitmap"} } @@ -2131,15 +2137,15 @@ # # Since: 5.2 # -# Examples: -# -# 1. Measurement is in progress: +# .. qmp-example:: +# :title: Measurement is in progress # # <- {"status": "measuring", "sample-pages": 512, # "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10, # "calc-time-unit": "second"} # -# 2. Measurement has been completed: +# .. qmp-example:: +# :title: Measurement has been completed # # <- {"status": "measured", "sample-pages": 512, "dirty-rate": 108, # "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10, @@ -2182,7 +2188,7 @@ # # Since: 7.1 # -# Example: +# .. qmp-example:: # # -> {"execute": "set-vcpu-dirty-limit"} # "arguments": { "dirty-rate": 200, @@ -2206,7 +2212,7 @@ # # Since: 7.1 # -# Example: +# .. qmp-example:: # # -> {"execute": "cancel-vcpu-dirty-limit"}, # "arguments": { "cpu-index": 1 } } @@ -2223,7 +2229,7 @@ # # Since: 7.1 # -# Example: +# .. qmp-example:: # # -> {"execute": "query-vcpu-dirty-limit"} # <- {"return": [ @@ -2287,7 +2293,7 @@ # # If @tag already exists, an error will be reported # -# Example: +# .. qmp-example:: # # -> { "execute": "snapshot-save", # "arguments": { @@ -2357,7 +2363,7 @@ # device nodes that can have changed since the original @snapshot-save # command execution. # -# Example: +# .. qmp-example:: # # -> { "execute": "snapshot-load", # "arguments": { @@ -2418,7 +2424,7 @@ # to determine completion and to fetch details of any errors that # arise. # -# Example: +# .. qmp-example:: # # -> { "execute": "snapshot-delete", # "arguments": { diff --git a/qapi/misc-target.json b/qapi/misc-target.json index 2d7d4d89bd..8d70bd24d8 100644 --- a/qapi/misc-target.json +++ b/qapi/misc-target.json @@ -11,7 +11,7 @@ # # Since: 2.1 # -# Example: +# .. qmp-example:: # # -> { "execute": "rtc-reset-reinjection" } # <- { "return": {} } @@ -133,7 +133,7 @@ # # Since: 2.12 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-sev" } # <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0, @@ -164,7 +164,7 @@ # # Since: 2.12 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-sev-launch-measure" } # <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } } @@ -209,7 +209,7 @@ # # Since: 2.12 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-sev-capabilities" } # <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE", @@ -263,7 +263,7 @@ # # Since: 6.1 # -# Example: +# .. qmp-example:: # # -> { "execute" : "query-sev-attestation-report", # "arguments": { "mnonce": "aaaaaaa" } } @@ -283,7 +283,7 @@ # # Since: 2.5 # -# Example: +# .. qmp-example:: # # -> { "execute": "dump-skeys", # "arguments": { "filename": "/tmp/skeys" } } @@ -328,7 +328,7 @@ # # Since: 2.6 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-gic-capabilities" } # <- { "return": [{ "version": 2, "emulated": true, "kernel": false }, @@ -386,7 +386,7 @@ # # Since: 6.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-sgx" } # <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true, @@ -405,7 +405,7 @@ # # Since: 6.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-sgx-capabilities" } # <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true, @@ -480,7 +480,7 @@ # # Since: 8.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "xen-event-list" } # <- { "return": [ @@ -518,7 +518,7 @@ # # Since: 8.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "xen-event-inject", "arguments": { "port": 1 } } # <- { "return": { } } diff --git a/qapi/misc.json b/qapi/misc.json index b04efbadec..4a6f3baeae 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -30,7 +30,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "add_client", "arguments": { "protocol": "vnc", # "fdname": "myclient" } } @@ -60,7 +60,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-name" } # <- { "return": { "name": "qemu-name" } } @@ -111,7 +111,7 @@ # # Since: 2.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-iothreads" } # <- { "return": [ @@ -144,7 +144,7 @@ # In the "suspended" state, it will completely stop the VM and cause # a transition to the "paused" state. (Since 9.0) # -# Example: +# .. qmp-example:: # # -> { "execute": "stop" } # <- { "return": {} } @@ -168,7 +168,7 @@ # this command will transition back to the "suspended" state. (Since # 9.0) # -# Example: +# .. qmp-example:: # # -> { "execute": "cont" } # <- { "return": {} } @@ -192,7 +192,7 @@ # # Since: 3.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "x-exit-preconfig" } # <- { "return": {} } @@ -232,7 +232,7 @@ # # * Commands that prompt the user for data don't currently work. # -# Example: +# .. qmp-example:: # # -> { "execute": "human-monitor-command", # "arguments": { "command-line": "info kvm" } } @@ -258,7 +258,7 @@ # The 'closefd' command can be used to explicitly close the file # descriptor when it is no longer needed. # -# Example: +# .. qmp-example:: # # -> { "execute": "getfd", "arguments": { "fdname": "fd1" } } # <- { "return": {} } @@ -285,7 +285,7 @@ # The 'closefd' command can be used to explicitly close the file # descriptor when it is no longer needed. # -# Example: +# .. qmp-example:: # # -> { "execute": "get-win32-socket", # "arguments": { "info": "abcd123..", "fdname": "skclient" } } @@ -302,7 +302,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "closefd", "arguments": { "fdname": "fd1" } } # <- { "return": {} } @@ -345,7 +345,7 @@ # # Since: 1.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } } # <- { "return": { "fdset-id": 1, "fd": 3 } } @@ -374,7 +374,7 @@ # .. note:: If @fd is not specified, all file descriptors in @fdset-id # will be removed. # -# Example: +# .. qmp-example:: # # -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } } # <- { "return": {} } @@ -420,7 +420,7 @@ # # .. note:: The list of fd sets is shared by all monitor connections. # -# Example: +# .. qmp-example:: # # -> { "execute": "query-fdsets" } # <- { "return": [ @@ -523,7 +523,7 @@ # # Since: 1.5 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-command-line-options", # "arguments": { "option": "option-rom" } } @@ -565,7 +565,7 @@ # # Since: 0.13 # -# Example: +# .. qmp-example:: # # <- { "event": "RTC_CHANGE", # "data": { "offset": 78 }, @@ -592,7 +592,7 @@ # # Since: 7.1 # -# Example: +# .. qmp-example:: # # <- { "event": "VFU_CLIENT_HANGUP", # "data": { "vfu-id": "vfu1", diff --git a/qapi/net.json b/qapi/net.json index dd6c365c34..31b3417d65 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -26,7 +26,7 @@ # command will succeed even if the network adapter does not support # link status notification. # -# Example: +# .. qmp-example:: # # -> { "execute": "set_link", # "arguments": { "name": "e1000.0", "up": false } } @@ -46,7 +46,7 @@ # Errors: # - If @type is not a valid network backend, DeviceNotFound # -# Example: +# .. qmp-example:: # # -> { "execute": "netdev_add", # "arguments": { "type": "user", "id": "netdev1", @@ -68,7 +68,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } } # <- { "return": {} } @@ -836,7 +836,7 @@ # # Since: 1.6 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } } # <- { "return": [ @@ -881,7 +881,7 @@ # # Since: 1.6 # -# Example: +# .. qmp-example:: # # <- { "event": "NIC_RX_FILTER_CHANGED", # "data": { "name": "vnet0", @@ -930,7 +930,9 @@ # switches. This can be useful when network bonds fail-over the # active slave. # -# Example: +# TODO: This line is a hack to separate the example from the body +# +# .. qmp-example:: # # -> { "execute": "announce-self", # "arguments": { @@ -955,7 +957,7 @@ # # Since: 4.2 # -# Example: +# .. qmp-example:: # # <- { "event": "FAILOVER_NEGOTIATED", # "data": { "device-id": "net1" }, @@ -975,7 +977,7 @@ # # Since: 7.2 # -# Examples: +# .. qmp-example:: # # <- { "event": "NETDEV_STREAM_CONNECTED", # "data": { "netdev-id": "netdev0", @@ -983,6 +985,8 @@ # "host": "::1", "type": "inet" } }, # "timestamp": { "seconds": 1666269863, "microseconds": 311222 } } # +# .. qmp-example:: +# # <- { "event": "NETDEV_STREAM_CONNECTED", # "data": { "netdev-id": "netdev0", # "addr": { "path": "/tmp/qemu0", "type": "unix" } }, @@ -1001,7 +1005,7 @@ # # Since: 7.2 # -# Example: +# .. qmp-example:: # # <- { "event": "NETDEV_STREAM_DISCONNECTED", # "data": {"netdev-id": "netdev0"}, diff --git a/qapi/pci.json b/qapi/pci.json index 8287d15dd0..ec28f1d9b4 100644 --- a/qapi/pci.json +++ b/qapi/pci.json @@ -93,7 +93,8 @@ # # Information about the Class of a PCI device # -# @desc: a string description of the device's class +# @desc: a string description of the device's class (not stable, and +# should only be treated as informational) # # @class: the class code of the device # @@ -146,9 +147,6 @@ # # @regions: a list of the PCI I/O regions associated with the device # -# .. note:: The contents of @class_info.desc are not stable and should -# only be treated as informational. -# # Since: 0.14 ## { 'struct': 'PciDeviceInfo', @@ -182,7 +180,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-pci" } # <- { "return": [ diff --git a/qapi/qdev.json b/qapi/qdev.json index d031fc3590..e91ca0309d 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -62,7 +62,7 @@ # the ``-device DEVICE,help`` command-line argument, where DEVICE # is the device's name. # -# Example: +# .. qmp-example:: # # -> { "execute": "device_add", # "arguments": { "driver": "e1000", "id": "net1", @@ -104,12 +104,14 @@ # # Since: 0.14 # -# Examples: +# .. qmp-example:: # # -> { "execute": "device_del", # "arguments": { "id": "net1" } } # <- { "return": {} } # +# .. qmp-example:: +# # -> { "execute": "device_del", # "arguments": { "id": "/machine/peripheral-anon/device[0]" } } # <- { "return": {} } @@ -130,7 +132,7 @@ # # Since: 1.5 # -# Example: +# .. qmp-example:: # # <- { "event": "DEVICE_DELETED", # "data": { "device": "virtio-net-pci-0", @@ -152,7 +154,7 @@ # # Since: 6.2 # -# Example: +# .. qmp-example:: # # <- { "event": "DEVICE_UNPLUG_GUEST_ERROR", # "data": { "device": "core1", diff --git a/qapi/qom.json b/qapi/qom.json index 7eccd2e14e..7e780e1791 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -59,7 +59,7 @@ # # Since: 1.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "qom-list", # "arguments": { "path": "/chardevs" } } @@ -104,16 +104,16 @@ # # Since: 1.2 # -# Examples: -# -# 1. Use absolute path +# .. qmp-example:: +# :title: Use absolute path # # -> { "execute": "qom-get", # "arguments": { "path": "/machine/unattached/device[0]", # "property": "hotplugged" } } # <- { "return": false } # -# 2. Use partial path +# .. qmp-example:: +# :title: Use partial path # # -> { "execute": "qom-get", # "arguments": { "path": "unattached/sysbus", @@ -139,7 +139,7 @@ # # Since: 1.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "qom-set", # "arguments": { "path": "/machine", @@ -1028,7 +1028,8 @@ # # Features: # -# @unstable: Member @x-remote-object is experimental. +# @unstable: Members @x-remote-object and @x-vfio-user-server are +# experimental. # # Since: 6.0 ## @@ -1175,7 +1176,7 @@ # # Since: 2.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "object-add", # "arguments": { "qom-type": "rng-random", "id": "rng1", @@ -1197,7 +1198,7 @@ # # Since: 2.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "object-del", "arguments": { "id": "rng1" } } # <- { "return": {} } diff --git a/qapi/replay.json b/qapi/replay.json index d3559f9c8f..35e0c4a692 100644 --- a/qapi/replay.json +++ b/qapi/replay.json @@ -54,7 +54,7 @@ # # Since: 5.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-replay" } # <- { "return": { "mode": "play", "filename": "log.rr", "icount": 220414 } } @@ -76,7 +76,7 @@ # # Since: 5.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "replay-break", "arguments": { "icount": 220414 } } # <- { "return": {} } @@ -91,7 +91,7 @@ # # Since: 5.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "replay-delete-break" } # <- { "return": {} } @@ -112,7 +112,7 @@ # # Since: 5.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "replay-seek", "arguments": { "icount": 220414 } } # <- { "return": {} } diff --git a/qapi/rocker.json b/qapi/rocker.json index 9f95e63830..2e63dcb3d6 100644 --- a/qapi/rocker.json +++ b/qapi/rocker.json @@ -30,7 +30,7 @@ # # Since: 2.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-rocker", "arguments": { "name": "sw1" } } # <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}} @@ -98,7 +98,7 @@ # # Since: 2.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } } # <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1", @@ -240,7 +240,7 @@ # # Since: 2.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-rocker-of-dpa-flows", # "arguments": { "name": "sw1" } } @@ -315,7 +315,7 @@ # # Since: 2.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-rocker-of-dpa-groups", # "arguments": { "name": "sw1" } } diff --git a/qapi/run-state.json b/qapi/run-state.json index 4d40c88876..287691ca0e 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -123,7 +123,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-status" } # <- { "return": { "running": true, @@ -152,7 +152,7 @@ # # Since: 0.12 # -# Example: +# .. qmp-example:: # # <- { "event": "SHUTDOWN", # "data": { "guest": true, "reason": "guest-shutdown" }, @@ -168,7 +168,7 @@ # # Since: 0.12 # -# Example: +# .. qmp-example:: # # <- { "event": "POWERDOWN", # "timestamp": { "seconds": 1267040730, "microseconds": 682951 } } @@ -189,7 +189,7 @@ # # Since: 0.12 # -# Example: +# .. qmp-example:: # # <- { "event": "RESET", # "data": { "guest": false, "reason": "guest-reset" }, @@ -204,7 +204,7 @@ # # Since: 0.12 # -# Example: +# .. qmp-example:: # # <- { "event": "STOP", # "timestamp": { "seconds": 1267041730, "microseconds": 281295 } } @@ -218,7 +218,7 @@ # # Since: 0.12 # -# Example: +# .. qmp-example:: # # <- { "event": "RESUME", # "timestamp": { "seconds": 1271770767, "microseconds": 582542 } } @@ -233,7 +233,7 @@ # # Since: 1.1 # -# Example: +# .. qmp-example:: # # <- { "event": "SUSPEND", # "timestamp": { "seconds": 1344456160, "microseconds": 309119 } } @@ -252,7 +252,7 @@ # # Since: 1.2 # -# Example: +# .. qmp-example:: # # <- { "event": "SUSPEND_DISK", # "timestamp": { "seconds": 1344456160, "microseconds": 309119 } } @@ -267,7 +267,7 @@ # # Since: 1.1 # -# Example: +# .. qmp-example:: # # <- { "event": "WAKEUP", # "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } @@ -289,7 +289,7 @@ # # Since: 0.13 # -# Example: +# .. qmp-example:: # # <- { "event": "WATCHDOG", # "data": { "action": "reset" }, @@ -382,7 +382,7 @@ # # Since: 2.11 # -# Example: +# .. qmp-example:: # # -> { "execute": "watchdog-set-action", # "arguments": { "action": "inject-nmi" } } @@ -406,7 +406,7 @@ # # Since: 6.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "set-action", # "arguments": { "reboot": "shutdown", @@ -433,7 +433,7 @@ # # Since: 1.5 # -# Example: +# .. qmp-example:: # # <- { "event": "GUEST_PANICKED", # "data": { "action": "pause" }, @@ -453,7 +453,7 @@ # # Since: 5.0 # -# Example: +# .. qmp-example:: # # <- { "event": "GUEST_CRASHLOADED", # "data": { "action": "run" }, @@ -469,7 +469,7 @@ # # Since: 9.1 # -# Example: +# .. qmp-example:: # # <- { "event": "GUEST_PVSHUTDOWN", # "timestamp": { "seconds": 1648245259, "microseconds": 893771 } } @@ -611,7 +611,7 @@ # # Since: 5.2 # -# Example: +# .. qmp-example:: # # <- { "event": "MEMORY_FAILURE", # "data": { "recipient": "hypervisor", diff --git a/qapi/sockets.json b/qapi/sockets.json index 4d78d2ccb7..e76fdb9925 100644 --- a/qapi/sockets.json +++ b/qapi/sockets.json @@ -179,10 +179,6 @@ # # @type: Transport type # -# .. note:: This type is deprecated in favor of SocketAddress. The -# difference between SocketAddressLegacy and SocketAddress is that -# the latter has fewer ``{}`` on the wire. -# # Since: 1.3 ## { 'union': 'SocketAddressLegacy', @@ -193,6 +189,9 @@ 'unix': 'UnixSocketAddressWrapper', 'vsock': 'VsockSocketAddressWrapper', 'fd': 'FdSocketAddressWrapper' } } +# 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: diff --git a/qapi/tpm.json b/qapi/tpm.json index 1577b5c259..a16a72edb9 100644 --- a/qapi/tpm.json +++ b/qapi/tpm.json @@ -31,7 +31,7 @@ # # Since: 1.5 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-tpm-models" } # <- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] } @@ -62,7 +62,7 @@ # # Since: 1.5 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-tpm-types" } # <- { "return": [ "passthrough", "emulator" ] } @@ -168,7 +168,7 @@ # # Since: 1.5 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-tpm" } # <- { "return": diff --git a/qapi/trace.json b/qapi/trace.json index 9ebb6d9eaf..eb5f63f513 100644 --- a/qapi/trace.json +++ b/qapi/trace.json @@ -51,7 +51,7 @@ # # Since: 2.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "trace-event-get-state", # "arguments": { "name": "qemu_memalign" } } @@ -74,7 +74,7 @@ # # Since: 2.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "trace-event-set-state", # "arguments": { "name": "qemu_memalign", "enable": true } } diff --git a/qapi/transaction.json b/qapi/transaction.json index bcb05fdedd..b0ae3437eb 100644 --- a/qapi/transaction.json +++ b/qapi/transaction.json @@ -244,7 +244,7 @@ # # Since: 1.1 # -# Example: +# .. qmp-example:: # # -> { "execute": "transaction", # "arguments": { "actions": [ diff --git a/qapi/ui.json b/qapi/ui.json index 5bcccbfc93..5daca5168c 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -83,7 +83,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "set_password", "arguments": { "protocol": "vnc", # "password": "secret" } } @@ -144,7 +144,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "expire_password", "arguments": { "protocol": "vnc", # "time": "+60" } } @@ -186,7 +186,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "screendump", # "arguments": { "filename": "/tmp/image" } } @@ -273,8 +273,6 @@ # @unknown: No information is available about mouse mode used by the # spice server. # -# .. note:: spice/enums.h has a SpiceMouseMode already, hence the name. -# # Since: 1.1 ## { 'enum': 'SpiceQueryMouseMode', @@ -330,7 +328,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-spice" } # <- { "return": { @@ -379,7 +377,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707}, # "event": "SPICE_CONNECTED", @@ -405,7 +403,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172}, # "event": "SPICE_INITIALIZED", @@ -432,7 +430,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707}, # "event": "SPICE_DISCONNECTED", @@ -453,7 +451,7 @@ # # Since: 1.3 # -# Example: +# .. qmp-example:: # # <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172}, # "event": "SPICE_MIGRATE_COMPLETED" } @@ -661,7 +659,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-vnc" } # <- { "return": { @@ -726,7 +724,7 @@ # # Since: 0.13 # -# Example: +# .. qmp-example:: # # <- { "event": "VNC_CONNECTED", # "data": { @@ -753,7 +751,7 @@ # # Since: 0.13 # -# Example: +# .. qmp-example:: # # <- { "event": "VNC_INITIALIZED", # "data": { @@ -779,7 +777,7 @@ # # Since: 0.13 # -# Example: +# .. qmp-example:: # # <- { "event": "VNC_DISCONNECTED", # "data": { @@ -827,7 +825,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-mice" } # <- { "return": [ @@ -1036,7 +1034,7 @@ # # Since: 1.3 # -# Example: +# .. qmp-example:: # # -> { "execute": "send-key", # "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" }, @@ -1272,9 +1270,8 @@ # property, so it is possible to map which console belongs to which # device and display. # -# Examples: -# -# 1. Press left mouse button. +# .. qmp-example:: +# :title: Press left mouse button # # -> { "execute": "input-send-event", # "arguments": { "device": "video0", @@ -1288,7 +1285,8 @@ # "data" : { "down": false, "button": "left" } } ] } } # <- { "return": {} } # -# 2. Press ctrl-alt-del. +# .. qmp-example:: +# :title: Press ctrl-alt-del # # -> { "execute": "input-send-event", # "arguments": { "events": [ @@ -1300,7 +1298,8 @@ # "key": {"type": "qcode", "data": "delete" } } } ] } } # <- { "return": {} } # -# 3. Move mouse pointer to absolute coordinates (20000, 400). +# .. qmp-example:: +# :title: Move mouse pointer to absolute coordinates # # -> { "execute": "input-send-event" , # "arguments": { "events": [ @@ -1615,7 +1614,7 @@ # # Since: 6.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "display-reload", # "arguments": { "type": "vnc", "tls-certs": true } } @@ -1672,7 +1671,7 @@ # # Since: 7.1 # -# Example: +# .. qmp-example:: # # -> { "execute": "display-update", # "arguments": { "type": "vnc", "addresses": @@ -1703,7 +1702,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "client_migrate_info", # "arguments": { "protocol": "spice", diff --git a/qapi/vfio.json b/qapi/vfio.json index a0e5013188..40cbcde02e 100644 --- a/qapi/vfio.json +++ b/qapi/vfio.json @@ -50,7 +50,7 @@ # # Since: 9.1 # -# Example: +# .. qmp-example:: # # <- { "timestamp": { "seconds": 1713771323, "microseconds": 212268 }, # "event": "VFIO_MIGRATION", diff --git a/qapi/virtio.json b/qapi/virtio.json index b91f3cdd0d..26df8b3064 100644 --- a/qapi/virtio.json +++ b/qapi/virtio.json @@ -34,7 +34,7 @@ # # Since: 7.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "x-query-virtio" } # <- { "return": [ @@ -203,9 +203,11 @@ # # Since: 7.2 # -# Examples: +# .. qmp-example:: +# :annotated: # -# 1. Poll for the status of virtio-crypto (no vhost-crypto active) +# Poll for the status of virtio-crypto (no vhost-crypto active) +# :: # # -> { "execute": "x-query-virtio-status", # "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend" } @@ -261,7 +263,11 @@ # } # } # -# 2. Poll for the status of virtio-net (vhost-net is active) +# .. qmp-example:: +# :annotated: +# +# Poll for the status of virtio-net (vhost-net is active) +# :: # # -> { "execute": "x-query-virtio-status", # "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend" } @@ -568,9 +574,11 @@ # # Since: 7.2 # -# Examples: +# .. qmp-example:: +# :annotated: # -# 1. Get VirtQueueStatus for virtio-vsock (vhost-vsock running) +# Get VirtQueueStatus for virtio-vsock (vhost-vsock running) +# :: # # -> { "execute": "x-query-virtio-queue-status", # "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend", @@ -593,7 +601,11 @@ # } # } # -# 2. Get VirtQueueStatus for virtio-serial (no vhost) +# .. qmp-example:: +# :annotated: +# +# Get VirtQueueStatus for virtio-serial (no vhost) +# :: # # -> { "execute": "x-query-virtio-queue-status", # "arguments": { "path": "/machine/peripheral-anon/device[0]/virtio-backend", @@ -690,9 +702,8 @@ # # Since: 7.2 # -# Examples: -# -# 1. Get vhost_virtqueue status for vhost-crypto +# .. qmp-example:: +# :title: Get vhost_virtqueue status for vhost-crypto # # -> { "execute": "x-query-virtio-vhost-queue-status", # "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend", @@ -715,7 +726,8 @@ # } # } # -# 2. Get vhost_virtqueue status for vhost-vsock +# .. qmp-example:: +# :title: Get vhost_virtqueue status for vhost-vsock # # -> { "execute": "x-query-virtio-vhost-queue-status", # "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend", @@ -839,9 +851,8 @@ # # Since: 7.2 # -# Examples: -# -# 1. Introspect on virtio-net's VirtQueue 0 at index 5 +# .. qmp-example:: +# :title: Introspect on virtio-net's VirtQueue 0 at index 5 # # -> { "execute": "x-query-virtio-queue-element", # "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend", @@ -870,7 +881,8 @@ # } # } # -# 2. Introspect on virtio-crypto's VirtQueue 1 at head +# .. qmp-example:: +# :title: Introspect on virtio-crypto's VirtQueue 1 at head # # -> { "execute": "x-query-virtio-queue-element", # "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend", @@ -898,7 +910,8 @@ # } # } # -# 3. Introspect on virtio-scsi's VirtQueue 2 at head +# .. qmp-example:: +# :title: Introspect on virtio-scsi's VirtQueue 2 at head # # -> { "execute": "x-query-virtio-queue-element", # "arguments": { "path": "/machine/peripheral-anon/device[2]/virtio-backend", diff --git a/qapi/yank.json b/qapi/yank.json index 89f2f4d199..30f46c97c9 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -81,7 +81,7 @@ # Errors: # - If any of the YankInstances doesn't exist, DeviceNotFound # -# Example: +# .. qmp-example:: # # -> { "execute": "yank", # "arguments": { @@ -104,7 +104,7 @@ # # Returns: list of @YankInstance # -# Example: +# .. qmp-example:: # # -> { "execute": "query-yank" } # <- { "return": [ diff --git a/qemu-options.hx b/qemu-options.hx index 694fa37f28..369ae81d7c 100644 --- a/qemu-options.hx +++ b/qemu-options.hx @@ -3353,7 +3353,7 @@ SRST -device e1000,netdev=n1,mac=52:54:00:12:34:56 \\ -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4 -``-netdev l2tpv3,id=id,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport],txsession=txsession[,rxsession=rxsession][,ipv6=on|off][,udp=on|off][,cookie64][,counter][,pincounter][,txcookie=txcookie][,rxcookie=rxcookie][,offset=offset]`` +``-netdev l2tpv3,id=id,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport],txsession=txsession[,rxsession=rxsession][,ipv6=on|off][,udp=on|off][,cookie64=on|off][,counter=on|off][,pincounter=on|off][,txcookie=txcookie][,rxcookie=rxcookie][,offset=offset]`` Configure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3931) is a popular protocol to transport Ethernet (and other Layer 2) data frames between two systems. It is present in routers, firewalls and @@ -3368,7 +3368,7 @@ SRST ``dst=dstaddr`` destination address (mandatory) - ``udp`` + ``udp=on`` select udp encapsulation (default is ip). ``srcport=srcport`` @@ -3377,7 +3377,7 @@ SRST ``dstport=dstport`` destination udp port. - ``ipv6`` + ``ipv6=on`` force v6, otherwise defaults to v4. ``rxcookie=rxcookie``; \ ``txcookie=txcookie`` @@ -3385,7 +3385,7 @@ SRST Their function is mostly to prevent misconfiguration. By default they are 32 bit. - ``cookie64`` + ``cookie64=on`` Set cookie size to 64 bit instead of the default 32 ``counter=off`` @@ -3419,7 +3419,7 @@ SRST # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter |qemu_system| linux.img -device e1000,netdev=n1 \\ - -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter + -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp=on,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter=on ``-netdev vde,id=id[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]`` Configure VDE backend to connect to PORT n of a vde switch running diff --git a/scripts/meson-buildoptions.sh b/scripts/meson-buildoptions.sh index cfadb5ea86..c97079a38c 100644 --- a/scripts/meson-buildoptions.sh +++ b/scripts/meson-buildoptions.sh @@ -83,7 +83,7 @@ meson_options_help() { printf "%s\n" ' (can be empty) [qemu]' printf "%s\n" ' --with-trace-file=VALUE Trace file prefix for simple backend [trace]' printf "%s\n" ' --x86-version=CHOICE tweak required x86_64 architecture version beyond' - printf "%s\n" ' compiler default [1] (choices: 0/1/2/3)' + printf "%s\n" ' compiler default [1] (choices: 0/1/2/3/4)' printf "%s\n" '' printf "%s\n" 'Optional features, enabled with --enable-FEATURE and' printf "%s\n" 'disabled with --disable-FEATURE, default is enabled if available' @@ -166,6 +166,7 @@ meson_options_help() { printf "%s\n" ' qcow1 qcow1 image format support' printf "%s\n" ' qed qed image format support' printf "%s\n" ' qga-vss build QGA VSS support (broken with MinGW)' + printf "%s\n" ' qpl Query Processing Library support' printf "%s\n" ' rbd Ceph block device driver' printf "%s\n" ' rdma Enable RDMA-based migration' printf "%s\n" ' replication replication support' @@ -187,6 +188,7 @@ meson_options_help() { printf "%s\n" ' tools build support utilities that come with QEMU' printf "%s\n" ' tpm TPM support' printf "%s\n" ' u2f U2F emulation support' + printf "%s\n" ' uadk UADK Library support' printf "%s\n" ' usb-redir libusbredir support' printf "%s\n" ' vde vde network backend support' printf "%s\n" ' vdi vdi image format support' @@ -221,8 +223,6 @@ meson_options_help() { printf "%s\n" ' Xen PCI passthrough support' printf "%s\n" ' xkbcommon xkbcommon support' printf "%s\n" ' zstd zstd compression support' - printf "%s\n" ' qpl Query Processing Library support' - printf "%s\n" ' uadk UADK Library support' } _meson_option_parse() { case $1 in @@ -440,6 +440,8 @@ _meson_option_parse() { --disable-qga-vss) printf "%s" -Dqga_vss=disabled ;; --enable-qom-cast-debug) printf "%s" -Dqom_cast_debug=true ;; --disable-qom-cast-debug) printf "%s" -Dqom_cast_debug=false ;; + --enable-qpl) printf "%s" -Dqpl=enabled ;; + --disable-qpl) printf "%s" -Dqpl=disabled ;; --enable-rbd) printf "%s" -Drbd=enabled ;; --disable-rbd) printf "%s" -Drbd=disabled ;; --enable-rdma) printf "%s" -Drdma=enabled ;; @@ -501,6 +503,8 @@ _meson_option_parse() { --disable-tsan) printf "%s" -Dtsan=false ;; --enable-u2f) printf "%s" -Du2f=enabled ;; --disable-u2f) printf "%s" -Du2f=disabled ;; + --enable-uadk) printf "%s" -Duadk=enabled ;; + --disable-uadk) printf "%s" -Duadk=disabled ;; --enable-usb-redir) printf "%s" -Dusb_redir=enabled ;; --disable-usb-redir) printf "%s" -Dusb_redir=disabled ;; --enable-vde) printf "%s" -Dvde=enabled ;; @@ -560,10 +564,6 @@ _meson_option_parse() { --disable-xkbcommon) printf "%s" -Dxkbcommon=disabled ;; --enable-zstd) printf "%s" -Dzstd=enabled ;; --disable-zstd) printf "%s" -Dzstd=disabled ;; - --enable-qpl) printf "%s" -Dqpl=enabled ;; - --disable-qpl) printf "%s" -Dqpl=disabled ;; - --enable-uadk) printf "%s" -Duadk=enabled ;; - --disable-uadk) printf "%s" -Duadk=disabled ;; *) return 1 ;; esac } diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 6ad5663e54..adc85b5b39 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -553,7 +553,7 @@ class QAPISchemaParser: # Note: "sections" with two colons are left alone as # rST markup and not interpreted as a section heading. - # TODO: Remove this error sometime in 2025 or so + # TODO: Remove these errors sometime in 2025 or so # after we've fully transitioned to the new qapidoc # generator. @@ -567,6 +567,14 @@ class QAPISchemaParser: ) raise QAPIParseError(self, emsg) + if 'Example' in match.group(1): + emsg = ( + f"The '{match.group(1)}' section is no longer " + "supported. Please use the '.. qmp-example::' " + "directive, or other suitable markup instead." + ) + raise QAPIParseError(self, emsg) + doc.new_tagged_section(self.info, match.group(1)) text = line[match.end():] if text: diff --git a/target/hexagon/imported/mmvec/ext.idef b/target/hexagon/imported/mmvec/ext.idef index 98daabfb07..03d31f6181 100644 --- a/target/hexagon/imported/mmvec/ext.idef +++ b/target/hexagon/imported/mmvec/ext.idef @@ -2855,7 +2855,7 @@ EXTINSN(V6_vscattermhw_add, "vscatter(Rt32,Mu2,Vvv32.w).h+=Vw32", ATTRIBS(A_EXT fVALIGN(RtV, element_size); fVFOREACH(32, i) { for(j = 0; j < 2; j++) { - EA = RtV + fVALIGN(VvvV.v[j].uw[i],ALIGNMENT);; + EA = RtV + fVALIGN(VvvV.v[j].uw[i],ALIGNMENT); fVLOG_VTCM_HALFWORD_INCREMENT_DV(EA,VvvV.v[j].uw[i],VwV,(2*i+j),i,j,ALIGNMENT,MuV); } } diff --git a/tests/avocado/virtio_check_params.py b/tests/avocado/virtio_check_params.py deleted file mode 100644 index 5fe370a179..0000000000 --- a/tests/avocado/virtio_check_params.py +++ /dev/null @@ -1,143 +0,0 @@ -# -# Test virtio-scsi and virtio-blk queue settings for all machine types -# -# Copyright (c) 2019 Virtuozzo International GmbH -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program. If not, see <http://www.gnu.org/licenses/>. -# - -import sys -import os -import re -import logging - -from qemu.machine import QEMUMachine -from avocado_qemu import QemuSystemTest -from avocado import skip - -#list of machine types and virtqueue properties to test -VIRTIO_SCSI_PROPS = {'seg_max_adjust': 'seg_max_adjust'} -VIRTIO_BLK_PROPS = {'seg_max_adjust': 'seg-max-adjust'} - -DEV_TYPES = {'virtio-scsi-pci': VIRTIO_SCSI_PROPS, - 'virtio-blk-pci': VIRTIO_BLK_PROPS} - -VM_DEV_PARAMS = {'virtio-scsi-pci': ['-device', 'virtio-scsi-pci,id=scsi0'], - 'virtio-blk-pci': ['-device', - 'virtio-blk-pci,id=scsi0,drive=drive0', - '-drive', - 'driver=null-co,id=drive0,if=none']} - - -class VirtioMaxSegSettingsCheck(QemuSystemTest): - @staticmethod - def make_pattern(props): - pattern_items = [r'{0} = \w+'.format(prop) for prop in props] - return '|'.join(pattern_items) - - def query_virtqueue(self, vm, dev_type_name): - query_ok = False - error = None - props = None - - output = vm.cmd('human-monitor-command', - command_line = 'info qtree') - props_list = DEV_TYPES[dev_type_name].values(); - pattern = self.make_pattern(props_list) - res = re.findall(pattern, output) - - if len(res) != len(props_list): - props_list = set(props_list) - res = set(res) - not_found = props_list.difference(res) - not_found = ', '.join(not_found) - error = '({0}): The following properties not found: {1}'\ - .format(dev_type_name, not_found) - else: - query_ok = True - props = dict() - for prop in res: - p = prop.split(' = ') - props[p[0]] = p[1] - return query_ok, props, error - - def check_mt(self, mt, dev_type_name): - mt['device'] = dev_type_name # Only for the debug() call. - logger = logging.getLogger('machine') - logger.debug(mt) - with QEMUMachine(self.qemu_bin) as vm: - vm.set_machine(mt["name"]) - vm.add_args('-nodefaults') - for s in VM_DEV_PARAMS[dev_type_name]: - vm.add_args(s) - try: - vm.launch() - query_ok, props, error = self.query_virtqueue(vm, dev_type_name) - except: - query_ok = False - error = sys.exc_info()[0] - - if not query_ok: - self.fail('machine type {0}: {1}'.format(mt['name'], error)) - - for prop_name, prop_val in props.items(): - expected_val = mt[prop_name] - self.assertEqual(expected_val, prop_val) - - @staticmethod - def seg_max_adjust_enabled(mt): - # machine types >= 5.0 should have seg_max_adjust = true - # others seg_max_adjust = false - mt = mt.split("-") - - # machine types with one line name and name like pc-x.x - if len(mt) <= 2: - return False - - # machine types like pc-<chip_name>-x.x[.x] - ver = mt[2] - ver = ver.split("."); - - # versions >= 5.0 goes with seg_max_adjust enabled - major = int(ver[0]) - - if major >= 5: - return True - return False - - @skip("break multi-arch CI") - def test_machine_types(self): - # collect all machine types except 'none', 'isapc', 'microvm' - with QEMUMachine(self.qemu_bin) as vm: - vm.launch() - machines = [m['name'] for m in vm.cmd('query-machines')] - vm.shutdown() - machines.remove('none') - machines.remove('isapc') - machines.remove('microvm') - - for dev_type in DEV_TYPES: - # create the list of machine types and their parameters. - mtypes = list() - for m in machines: - if self.seg_max_adjust_enabled(m): - enabled = 'true' - else: - enabled = 'false' - mtypes.append({'name': m, - DEV_TYPES[dev_type]['seg_max_adjust']: enabled}) - - # test each machine type for a device type - for mt in mtypes: - self.check_mt(mt, dev_type) diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index b565895858..f64bf38d85 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -172,12 +172,17 @@ # # Duis aute irure dolor # -# Example: +# .. qmp-example:: +# :title: Ideal fast-food burger situation # -# -> in -# <- out +# -> "in" +# <- "out" # -# Examples: +# Examples:: +# +# - Not a QMP code block +# - Merely a preformatted code block literal +# It isn't even an rST list. # - *verbatim* # - {braces} # @@ -199,11 +204,11 @@ # @cmd-feat1: a feature # @cmd-feat2: another feature # -# Example: +# .. qmp-example:: # -# -> in +# -> "this example" # -# <- out +# <- "has no title" ## { 'command': 'cmd-boxed', 'boxed': true, 'data': 'Object', diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index a8e9456f60..6d24f1127b 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -184,13 +184,21 @@ frobnicate - Ut enim ad minim veniam Duis aute irure dolor - section=Example - -> in - <- out - section=Examples + +.. qmp-example:: + :title: Ideal fast-food burger situation + + -> "in" + <- "out" + +Examples:: + + - Not a QMP code block + - Merely a preformatted code block literal + It isn't even an rST list. - *verbatim* - {braces} - section=None + Note:: Ceci n'est pas une note section=Since @@ -202,10 +210,12 @@ If you're bored enough to read this, go see a video of boxed cats a feature feature=cmd-feat2 another feature - section=Example - -> in + section=None +.. qmp-example:: + + -> "this example" - <- out + <- "has no title" doc symbol=EVT_BOXED body= diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt index 30d457e548..cb37db606a 100644 --- a/tests/qapi-schema/doc-good.txt +++ b/tests/qapi-schema/doc-good.txt @@ -217,17 +217,16 @@ Notes: Duis aute irure dolor +Example: Ideal fast-food burger situation: -Example -~~~~~~~ - - -> in - <- out - + -> "in" + <- "out" -Examples -~~~~~~~~ +Examples: + - Not a QMP code block + - Merely a preformatted code block literal + It isn't even an rST list. - *verbatim* - {braces} @@ -261,13 +260,11 @@ Features "cmd-feat2" another feature +Example:: -Example -~~~~~~~ - - -> in + -> "this example" - <- out + <- "has no title" "EVT_BOXED" (Event) diff --git a/util/oslib-posix.c b/util/oslib-posix.c index e76441695b..b090fe0eed 100644 --- a/util/oslib-posix.c +++ b/util/oslib-posix.c @@ -263,7 +263,7 @@ int qemu_socketpair(int domain, int type, int protocol, int sv[2]) return ret; } #endif - ret = socketpair(domain, type, protocol, sv);; + ret = socketpair(domain, type, protocol, sv); if (ret == 0) { qemu_set_cloexec(sv[0]); qemu_set_cloexec(sv[1]); |