* [PATCH v2 09/10] qapi: re-order 'since' sections to always be last
2026-04-08 4:55 [PATCH v2 00/10] qapi: enforce section ordering John Snow
` (7 preceding siblings ...)
2026-04-08 4:55 ` [PATCH v2 08/10] qapi: enforce doc block section ordering John Snow
@ 2026-04-08 4:55 ` John Snow
2026-04-08 4:55 ` [PATCH v2 10/10] qapi: enforce strict positioning for "Since:" section John Snow
2026-04-15 9:43 ` [PATCH v2 00/10] qapi: enforce section ordering Markus Armbruster
10 siblings, 0 replies; 12+ messages in thread
From: John Snow @ 2026-04-08 4:55 UTC (permalink / raw)
To: qemu-devel
Cc: Kashyap Chamarthy, Stefan Berger, Mauro Carvalho Chehab,
Michael Roth, Philippe Mathieu-Daudé, qemu-block,
Pierrick Bouvier, Yanan Wang, Hanna Reitz, Peter Xu,
Igor Mammedov, Michael S. Tsirkin, Kevin Wolf,
Marc-André Lureau, Stefano Garzarella,
Daniel P. Berrangé, Lukas Straub, Jason Wang,
Alex Williamson, Paolo Bonzini, Fabiano Rosas, Zhao Liu,
Richard Henderson, Cédric Le Goater, Stefan Hajnoczi,
Peter Maydell, Eric Blake, Alex Bennée, Kostiantyn Kostiuk,
Jiri Pirko, Markus Armbruster, John Snow, Ani Sinha,
Marcel Apfelbaum
Note that with "Since" being moved to the last position, we open up a
good many new cases of ambiguos intro-vs-details text which must be
corrected with "Details:" tags.
These markers are added to this patch in two cases:
(1) Where failing to add it would immediately (i.e. without the future
inliner feature) cause a change to the rendered output
(2) Where failing to add it causes new warning message yelps.
These cases are not presently delineated.
Signed-off-by: John Snow <jsnow@redhat.com>
---
[Review notes: This patch produces no changes to the *.ir files! --js]
Signed-off-by: John Snow <jsnow@redhat.com>
---
docs/interop/firmware.json | 4 +-
docs/interop/vhost-user.json | 3 +-
qapi/accelerator.json | 8 ++-
qapi/acpi.json | 8 ++-
qapi/block-core.json | 136 ++++++++++++++++++-----------------
qapi/block.json | 40 +++++------
qapi/char.json | 36 +++++-----
qapi/control.json | 14 ++--
qapi/dump.json | 16 ++---
qapi/machine-s390x.json | 8 +--
qapi/machine.json | 84 +++++++++++++---------
qapi/migration.json | 94 +++++++++++++-----------
qapi/misc-arm.json | 4 +-
qapi/misc-i386.json | 38 +++++-----
qapi/misc.json | 64 +++++++++--------
qapi/net.json | 40 +++++------
qapi/pci.json | 4 +-
qapi/qdev.json | 12 ++--
qapi/qom.json | 20 +++---
qapi/replay.json | 16 +++--
qapi/rocker.json | 16 ++---
qapi/run-state.json | 66 ++++++++++-------
qapi/tpm.json | 12 +++-
qapi/trace.json | 8 +--
qapi/transaction.json | 4 +-
qapi/ui.json | 76 +++++++++++---------
qapi/vfio.json | 4 +-
qapi/virtio.json | 20 +++---
28 files changed, 472 insertions(+), 383 deletions(-)
diff --git a/docs/interop/firmware.json b/docs/interop/firmware.json
index 421bee0e5ed..bdfb6ccb717 100644
--- a/docs/interop/firmware.json
+++ b/docs/interop/firmware.json
@@ -551,8 +551,6 @@
# debugging purposes only, and management software shall
# explicitly ignore it.
#
-# Since: 3.0
-#
# .. qmp-example::
#
# {
@@ -752,6 +750,8 @@
# "-D DEBUG_PRINT_ERROR_LEVEL=0x80000000"
# ]
# }
+#
+# Since: 3.0
##
{ 'struct' : 'Firmware',
'data' : { 'description' : 'str',
diff --git a/docs/interop/vhost-user.json b/docs/interop/vhost-user.json
index 29c84e86e55..fbcf409838d 100644
--- a/docs/interop/vhost-user.json
+++ b/docs/interop/vhost-user.json
@@ -264,8 +264,6 @@
# development and debugging purposes only, and management software
# shall explicitly ignore it.
#
-# Since: 4.0
-#
# .. qmp-example:
#
# {
@@ -278,6 +276,7 @@
# ]
# }
#
+# Since: 4.0
##
{
'struct' : 'VhostUserBackend',
diff --git a/qapi/accelerator.json b/qapi/accelerator.json
index d333a772384..dfa1288bf3c 100644
--- a/qapi/accelerator.json
+++ b/qapi/accelerator.json
@@ -29,12 +29,14 @@
#
# Return information about KVM acceleration
#
-# Since: 0.14
+# Details:
#
# .. qmp-example::
#
# -> { "execute": "query-kvm" }
# <- { "return": { "enabled": true, "present": true } }
+#
+# Since: 0.14
##
{ 'command': 'query-kvm', 'returns': 'KvmInfo' }
@@ -101,11 +103,11 @@
#
# Returns: @AcceleratorInfo
#
-# Since: 10.2.0
-#
# .. qmp-example::
#
# -> { "execute": "query-accelerators" }
# <- { "return": { "enabled": "mshv", "present": ["kvm", "mshv", "qtest", "tcg"] } }
+#
+# Since: 10.2.0
##
{ 'command': 'query-accelerators', 'returns': 'AcceleratorInfo' }
diff --git a/qapi/acpi.json b/qapi/acpi.json
index 906b3687a55..8dd87fd8f22 100644
--- a/qapi/acpi.json
+++ b/qapi/acpi.json
@@ -111,7 +111,7 @@
# Return a list of `ACPIOSTInfo` for devices that support status
# reporting via ACPI _OST method.
#
-# Since: 2.1
+# Details:
#
# .. qmp-example::
#
@@ -121,6 +121,8 @@
# { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
# { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
# ]}
+#
+# Since: 2.1
##
{ 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] }
@@ -131,14 +133,14 @@
#
# @info: OSPM Status Indication
#
-# Since: 2.1
-#
# .. qmp-example::
#
# <- { "event": "ACPI_DEVICE_OST",
# "data": { "info": { "device": "d1", "slot": "0",
# "slot-type": "DIMM", "source": 1, "status": 0 } },
# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+#
+# Since: 2.1
##
{ 'event': 'ACPI_DEVICE_OST',
'data': { 'info': 'ACPIOSTInfo' } }
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 400ceda9e87..d1f505978c9 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -862,8 +862,6 @@
# Returns: a list describing each virtual block device. Filter nodes
# that were created implicitly are skipped over.
#
-# Since: 0.14
-#
# .. qmp-example::
#
# -> { "execute": "query-block" }
@@ -947,6 +945,8 @@
# }
# ]
# }
+#
+# Since: 0.14
##
{ 'command': 'query-block', 'returns': ['BlockInfo'],
'data': { '*flat': 'bool' },
@@ -1267,8 +1267,6 @@
#
# Returns: A list of statistics for each virtual block device.
#
-# Since: 0.14
-#
# .. qmp-example::
#
# -> { "execute": "query-blockstats" }
@@ -1370,6 +1368,8 @@
# }
# ]
# }
+#
+# Since: 0.14
##
{ 'command': 'query-blockstats',
'data': { '*query-nodes': 'bool' },
@@ -1560,13 +1560,13 @@
# Errors:
# - If @device is not a valid block device, DeviceNotFound
#
-# Since: 0.14
-#
# .. qmp-example::
#
# -> { "execute": "block_resize",
# "arguments": { "device": "scratch", "size": 1073741824 } }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'block_resize',
'data': { '*device': 'str',
@@ -1788,8 +1788,6 @@
# Errors:
# - If @device is not a valid block device, DeviceNotFound
#
-# Since: 0.14
-#
# .. qmp-example::
#
# -> { "execute": "blockdev-snapshot-sync",
@@ -1798,6 +1796,8 @@
# "/some/place/my-image",
# "format": "qcow2" } }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'blockdev-snapshot-sync',
'data': 'BlockdevSnapshotSync',
@@ -1820,8 +1820,6 @@
# backing file of a destination of a `blockdev-mirror`.
# (since 5.0)
#
-# Since: 2.5
-#
# .. qmp-example::
#
# -> { "execute": "blockdev-add",
@@ -1837,6 +1835,8 @@
# "arguments": { "node": "ide-hd0",
# "overlay": "node1534" } }
# <- { "return": {} }
+#
+# Since: 2.5
##
{ 'command': 'blockdev-snapshot',
'data': 'BlockdevSnapshot',
@@ -1963,14 +1963,14 @@
# @deprecated: Members @base and @top are deprecated. Use @base-node
# and @top-node instead.
#
-# Since: 1.3
-#
# .. qmp-example::
#
# -> { "execute": "block-commit",
# "arguments": { "device": "virtio0",
# "top": "/tmp/snap1.qcow2" } }
# <- { "return": {} }
+#
+# Since: 1.3
##
{ 'command': 'block-commit',
'data': { '*job-id': 'str', 'device': 'str', '*base-node': 'str',
@@ -2001,8 +2001,6 @@
# @deprecated: This command is deprecated. Use `blockdev-backup`
# instead.
#
-# Since: 1.6
-#
# .. qmp-example::
#
# -> { "execute": "drive-backup",
@@ -2010,6 +2008,8 @@
# "sync": "full",
# "target": "backup.img" } }
# <- { "return": {} }
+#
+# Since: 1.6
##
{ 'command': 'drive-backup', 'boxed': true,
'data': 'DriveBackup', 'features': ['deprecated'],
@@ -2027,8 +2027,6 @@
# Errors:
# - If @device is not a valid block device, DeviceNotFound
#
-# Since: 2.3
-#
# .. qmp-example::
#
# -> { "execute": "blockdev-backup",
@@ -2036,6 +2034,8 @@
# "sync": "full",
# "target": "tgt-id" } }
# <- { "return": {} }
+#
+# Since: 2.3
##
{ 'command': 'blockdev-backup', 'boxed': true,
'data': 'BlockdevBackup',
@@ -2049,8 +2049,6 @@
# @flat: Omit the nested data about backing image ("backing-image"
# key) if true. Default is false (Since 5.0)
#
-# Since: 2.0
-#
# .. qmp-example::
#
# -> { "execute": "query-named-block-nodes" }
@@ -2099,6 +2097,8 @@
# "virtual-size":2048000
# }
# } } ] }
+#
+# Since: 2.0
##
{ 'command': 'query-named-block-nodes',
'returns': [ 'BlockDeviceInfo' ],
@@ -2230,8 +2230,6 @@
# Errors:
# - If @device is not a valid block device, GenericError
#
-# Since: 1.3
-#
# .. qmp-example::
#
# -> { "execute": "drive-mirror",
@@ -2240,6 +2238,8 @@
# "sync": "full",
# "format": "qcow2" } }
# <- { "return": {} }
+#
+# Since: 1.3
##
{ 'command': 'drive-mirror', 'boxed': true,
'data': 'DriveMirror',
@@ -2407,13 +2407,13 @@
# - If @node is not a valid block device or node, DeviceNotFound
# - If @name is already taken, GenericError
#
-# Since: 2.4
-#
# .. qmp-example::
#
# -> { "execute": "block-dirty-bitmap-add",
# "arguments": { "node": "drive0", "name": "bitmap0" } }
# <- { "return": {} }
+#
+# Since: 2.4
##
{ 'command': 'block-dirty-bitmap-add',
'data': 'BlockDirtyBitmapAdd',
@@ -2431,13 +2431,13 @@
# - If @name is not found, GenericError
# - if @name is frozen by an operation, GenericError
#
-# Since: 2.4
-#
# .. qmp-example::
#
# -> { "execute": "block-dirty-bitmap-remove",
# "arguments": { "node": "drive0", "name": "bitmap0" } }
# <- { "return": {} }
+#
+# Since: 2.4
##
{ 'command': 'block-dirty-bitmap-remove',
'data': 'BlockDirtyBitmap',
@@ -2454,13 +2454,13 @@
# - If @node is not a valid block device, DeviceNotFound
# - If @name is not found, GenericError
#
-# Since: 2.4
-#
# .. qmp-example::
#
# -> { "execute": "block-dirty-bitmap-clear",
# "arguments": { "node": "drive0", "name": "bitmap0" } }
# <- { "return": {} }
+#
+# Since: 2.4
##
{ 'command': 'block-dirty-bitmap-clear',
'data': 'BlockDirtyBitmap',
@@ -2475,13 +2475,13 @@
# - If @node is not a valid block device, DeviceNotFound
# - If @name is not found, GenericError
#
-# Since: 4.0
-#
# .. qmp-example::
#
# -> { "execute": "block-dirty-bitmap-enable",
# "arguments": { "node": "drive0", "name": "bitmap0" } }
# <- { "return": {} }
+#
+# Since: 4.0
##
{ 'command': 'block-dirty-bitmap-enable',
'data': 'BlockDirtyBitmap',
@@ -2496,13 +2496,13 @@
# - If @node is not a valid block device, DeviceNotFound
# - If @name is not found, GenericError
#
-# Since: 4.0
-#
# .. qmp-example::
#
# -> { "execute": "block-dirty-bitmap-disable",
# "arguments": { "node": "drive0", "name": "bitmap0" } }
# <- { "return": {} }
+#
+# Since: 4.0
##
{ 'command': 'block-dirty-bitmap-disable',
'data': 'BlockDirtyBitmap',
@@ -2528,14 +2528,14 @@
# - If any of the bitmaps have different sizes or granularities,
# GenericError
#
-# Since: 4.0
-#
# .. qmp-example::
#
# -> { "execute": "block-dirty-bitmap-merge",
# "arguments": { "node": "drive0", "target": "bitmap0",
# "bitmaps": ["bitmap1"] } }
# <- { "return": {} }
+#
+# Since: 4.0
##
{ 'command': 'block-dirty-bitmap-merge',
'data': 'BlockDirtyBitmapMerge',
@@ -2637,8 +2637,6 @@
# mirror. Setting this to true when the destination is not
# actually all zero can corrupt the destination. (Since 10.1)
#
-# Since: 2.6
-#
# .. qmp-example::
#
# -> { "execute": "blockdev-mirror",
@@ -2646,6 +2644,8 @@
# "target": "target0",
# "sync": "full" } }
# <- { "return": {} }
+#
+# Since: 2.6
##
{ 'command': 'blockdev-mirror',
'data': { '*job-id': 'str', 'device': 'str', 'target': 'str',
@@ -2962,14 +2962,14 @@
# Errors:
# - If @device does not exist, DeviceNotFound.
#
-# Since: 1.1
-#
# .. qmp-example::
#
# -> { "execute": "block-stream",
# "arguments": { "device": "virtio0",
# "base": "/tmp/master.qcow2" } }
# <- { "return": {} }
+#
+# Since: 1.1
##
{ 'command': 'block-stream',
'data': { '*job-id': 'str', 'device': 'str', '*base': 'str',
@@ -4958,7 +4958,7 @@
#
# Creates a new block device.
#
-# Since: 2.9
+# Details:
#
# .. qmp-example::
#
@@ -4999,6 +4999,8 @@
# }
#
# <- { "return": {} }
+#
+# Since: 2.9
##
{ 'command': 'blockdev-add', 'data': 'BlockdevOptions', 'boxed': true,
'allow-preconfig': true }
@@ -5062,8 +5064,6 @@
#
# @node-name: Name of the graph node to delete.
#
-# Since: 2.9
-#
# .. qmp-example::
#
# -> { "execute": "blockdev-add",
@@ -5082,6 +5082,8 @@
# "arguments": { "node-name": "node0" }
# }
# <- { "return": {} }
+#
+# Since: 2.9
##
{ 'command': 'blockdev-del', 'data': { 'node-name': 'str' },
'allow-preconfig': true }
@@ -5102,8 +5104,6 @@
# @active: true if the nodes should be active when the command returns
# success, false if they should be inactive.
#
-# Since: 10.0
-#
# .. qmp-example::
#
# -> { "execute": "blockdev-set-active",
@@ -5113,6 +5113,8 @@
# }
# }
# <- { "return": {} }
+#
+# Since: 10.0
##
{ 'command': 'blockdev-set-active',
'data': { '*node-name': 'str', 'active': 'bool' },
@@ -5796,8 +5798,6 @@
#
# .. note:: This event is rate-limited, except if action is "stop".
#
-# Since: 0.13
-#
# .. qmp-example::
#
# <- { "event": "BLOCK_IO_ERROR",
@@ -5808,6 +5808,8 @@
# "action": "stop",
# "reason": "No space left on device" },
# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+#
+# Since: 0.13
##
{ 'event': 'BLOCK_IO_ERROR',
'data': { 'qom-path': 'str', 'device': 'str', '*node-name': 'str',
@@ -5837,8 +5839,6 @@
# other than that streaming has failed and clients should not try
# to interpret the error string
#
-# Since: 1.1
-#
# .. qmp-example::
#
# <- { "event": "BLOCK_JOB_COMPLETED",
@@ -5846,6 +5846,8 @@
# "len": 10737418240, "offset": 10737418240,
# "speed": 0 },
# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
+#
+# Since: 1.1
##
{ 'event': 'BLOCK_JOB_COMPLETED',
'data': { 'type' : 'JobType',
@@ -5872,8 +5874,6 @@
#
# @speed: rate limit, bytes per second
#
-# Since: 1.1
-#
# .. qmp-example::
#
# <- { "event": "BLOCK_JOB_CANCELLED",
@@ -5881,6 +5881,8 @@
# "len": 10737418240, "offset": 134217728,
# "speed": 0 },
# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
+#
+# Since: 1.1
##
{ 'event': 'BLOCK_JOB_CANCELLED',
'data': { 'type' : 'JobType',
@@ -5901,8 +5903,6 @@
#
# @action: action that has been taken
#
-# Since: 1.3
-#
# .. qmp-example::
#
# <- { "event": "BLOCK_JOB_ERROR",
@@ -5910,6 +5910,8 @@
# "operation": "write",
# "action": "stop" },
# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+#
+# Since: 1.3
##
{ 'event': 'BLOCK_JOB_ERROR',
'data': { 'device' : 'str',
@@ -5936,14 +5938,14 @@
# .. note:: The "ready to complete" status is always reset by a
# `BLOCK_JOB_ERROR` event.
#
-# Since: 1.3
-#
# .. qmp-example::
#
# <- { "event": "BLOCK_JOB_READY",
# "data": { "device": "drive0", "type": "mirror", "speed": 0,
# "len": 2097152, "offset": 2097152 },
# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+#
+# Since: 1.3
##
{ 'event': 'BLOCK_JOB_READY',
'data': { 'type' : 'JobType',
@@ -5964,13 +5966,13 @@
#
# @id: The job identifier.
#
-# Since: 2.12
-#
# .. qmp-example::
#
# <- { "event": "BLOCK_JOB_PENDING",
# "data": { "type": "mirror", "id": "backup_1" },
# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+#
+# Since: 2.12
##
{ 'event': 'BLOCK_JOB_PENDING',
'data': { 'type' : 'JobType',
@@ -6038,14 +6040,14 @@
# @write-threshold: configured threshold for the block device, bytes.
# Use 0 to disable the threshold.
#
-# Since: 2.3
-#
# .. qmp-example::
#
# -> { "execute": "block-set-write-threshold",
# "arguments": { "node-name": "mydev",
# "write-threshold": 17179869184 } }
# <- { "return": {} }
+#
+# Since: 2.3
##
{ 'command': 'block-set-write-threshold',
'data': { 'node-name': 'str', 'write-threshold': 'uint64' },
@@ -6079,8 +6081,6 @@
# 'children' list of `BlockdevOptionsQuorum`, as returned by
# .bdrv_refresh_filename().
#
-# Since: 2.7
-#
# .. qmp-example::
# :title: Add a new node to a quorum
#
@@ -6103,6 +6103,8 @@
# "arguments": { "parent": "disk1",
# "child": "children.1" } }
# <- { "return": {} }
+#
+# Since: 2.7
##
{ 'command': 'x-blockdev-change',
'data' : { 'parent': 'str',
@@ -6131,8 +6133,6 @@
# @unstable: This command is experimental and intended for test cases
# that need control over IOThreads only.
#
-# Since: 2.12
-#
# .. qmp-example::
# :title: Move a node into an IOThread
#
@@ -6148,6 +6148,8 @@
# "arguments": { "node-name": "disk1",
# "iothread": null } }
# <- { "return": {} }
+#
+# Since: 2.12
##
{ 'command': 'x-blockdev-set-iothread',
'data' : { 'node-name': 'str',
@@ -6185,13 +6187,13 @@
#
# .. note:: This event is rate-limited.
#
-# Since: 2.0
-#
# .. qmp-example::
#
# <- { "event": "QUORUM_FAILURE",
# "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
+#
+# Since: 2.0
##
{ 'event': 'QUORUM_FAILURE',
'data': { 'reference': 'str', 'sector-num': 'int', 'sectors-count': 'int' } }
@@ -6216,8 +6218,6 @@
#
# .. note:: This event is rate-limited.
#
-# Since: 2.0
-#
# .. qmp-example::
# :title: Read operation
#
@@ -6233,6 +6233,8 @@
# "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
# "type": "flush", "error": "Broken pipe" },
# "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
+#
+# Since: 2.0
##
{ 'event': 'QUORUM_REPORT_BAD',
'data': { 'type': 'QuorumOpType', '*error': 'str', 'node-name': 'str',
@@ -6269,8 +6271,6 @@
# .. note:: Only some image formats such as qcow2 and rbd support
# internal snapshots.
#
-# Since: 1.7
-#
# .. qmp-example::
#
# -> { "execute": "blockdev-snapshot-internal-sync",
@@ -6278,6 +6278,8 @@
# "name": "snapshot0" }
# }
# <- { "return": {} }
+#
+# Since: 1.7
##
{ 'command': 'blockdev-snapshot-internal-sync',
'data': 'BlockdevSnapshotInternal',
@@ -6305,8 +6307,6 @@
# GenericError
# - If @id and @name are both not specified, GenericError
#
-# Since: 1.7
-#
# .. qmp-example::
#
# -> { "execute": "blockdev-snapshot-delete-internal-sync",
@@ -6324,6 +6324,8 @@
# "icount": 220414
# }
# }
+#
+# Since: 1.7
##
{ 'command': 'blockdev-snapshot-delete-internal-sync',
'data': { 'device': 'str', '*id': 'str', '*name': 'str'},
diff --git a/qapi/block.json b/qapi/block.json
index 54bc0056318..a29907e0be1 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -118,12 +118,12 @@
#
# .. note:: Ejecting a device with no media results in success.
#
-# Since: 0.14
-#
# .. qmp-example::
#
# -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'eject',
'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] },
@@ -162,8 +162,6 @@
#
# @deprecated: Member @device is deprecated. Use @id instead.
#
-# Since: 2.5
-#
# .. qmp-example::
#
# -> { "execute": "blockdev-open-tray",
@@ -177,6 +175,8 @@
# "tray-open": true } }
#
# <- { "return": {} }
+#
+# Since: 2.5
##
{ 'command': 'blockdev-open-tray',
'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] },
@@ -200,8 +200,6 @@
#
# @deprecated: Member @device is deprecated. Use @id instead.
#
-# Since: 2.5
-#
# .. qmp-example::
#
# -> { "execute": "blockdev-close-tray",
@@ -215,6 +213,8 @@
# "tray-open": false } }
#
# <- { "return": {} }
+#
+# Since: 2.5
##
{ 'command': 'blockdev-close-tray',
'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] },
@@ -232,8 +232,6 @@
#
# @id: The name or QOM path of the guest device
#
-# Since: 2.12
-#
# .. qmp-example::
#
# -> { "execute": "blockdev-remove-medium",
@@ -258,6 +256,8 @@
# "arguments": { "id": "ide0-1-0" } }
#
# <- { "return": {} }
+#
+# Since: 2.12
##
{ 'command': 'blockdev-remove-medium',
'data': { 'id': 'str' } }
@@ -273,8 +273,6 @@
#
# @node-name: name of a node in the block driver state graph
#
-# Since: 2.12
-#
# .. qmp-example::
#
# -> { "execute": "blockdev-add",
@@ -290,6 +288,8 @@
# "node-name": "node0" } }
#
# <- { "return": {} }
+#
+# Since: 2.12
##
{ 'command': 'blockdev-insert-medium',
'data': { 'id': 'str',
@@ -343,8 +343,6 @@
#
# @deprecated: Member @device is deprecated. Use @id instead.
#
-# Since: 2.5
-#
# .. qmp-example::
# :title: Change a removable medium
#
@@ -374,6 +372,8 @@
# "read-only-mode": "read-only" } }
#
# <- { "return": {} }
+#
+# Since: 2.5
##
{ 'command': 'blockdev-change-medium',
'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] },
@@ -398,8 +398,6 @@
# @tray-open: true if the tray has been opened or false if it has been
# closed
#
-# Since: 1.1
-#
# .. qmp-example::
#
# <- { "event": "DEVICE_TRAY_MOVED",
@@ -408,6 +406,8 @@
# "tray-open": true
# },
# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+#
+# Since: 1.1
##
{ 'event': 'DEVICE_TRAY_MOVED',
'data': { 'device': 'str', 'id': 'str', 'tray-open': 'bool' } }
@@ -422,8 +422,6 @@
#
# @connected: true if the PR manager is connected to a backend
#
-# Since: 3.0
-#
# .. qmp-example::
#
# <- { "event": "PR_MANAGER_STATUS_CHANGED",
@@ -431,6 +429,8 @@
# "connected": true
# },
# "timestamp": { "seconds": 1519840375, "microseconds": 450486 } }
+#
+# Since: 3.0
##
{ 'event': 'PR_MANAGER_STATUS_CHANGED',
'data': { 'id': 'str', 'connected': 'bool' } }
@@ -464,8 +464,6 @@
# Errors:
# - If @device is not a valid block device, DeviceNotFound
#
-# Since: 1.1
-#
# .. qmp-example::
#
# -> { "execute": "block_set_io_throttle",
@@ -505,6 +503,8 @@
# "bps_max_length": 60,
# "iops_size": 0 } }
# <- { "return": {} }
+#
+# Since: 1.1
##
{ 'command': 'block_set_io_throttle', 'boxed': true,
'data': 'BlockIOThrottle',
@@ -546,8 +546,6 @@
# Errors:
# - if device is not found or any boundary arrays are invalid.
#
-# Since: 4.0
-#
# .. qmp-example::
# :annotated:
#
@@ -594,6 +592,8 @@
# -> { "execute": "block-latency-histogram-set",
# "arguments": { "id": "drive0" } }
# <- { "return": {} }
+#
+# Since: 4.0
##
{ 'command': 'block-latency-histogram-set',
'data': {'id': 'str',
diff --git a/qapi/char.json b/qapi/char.json
index a4abafa6803..4ff980d356b 100644
--- a/qapi/char.json
+++ b/qapi/char.json
@@ -38,7 +38,7 @@
#
# Return information about current character devices.
#
-# Since: 0.14
+# Details:
#
# .. qmp-example::
#
@@ -62,6 +62,8 @@
# }
# ]
# }
+#
+# Since: 0.14
##
{ 'command': 'query-chardev', 'returns': ['ChardevInfo'],
'allow-preconfig': true }
@@ -82,7 +84,7 @@
#
# Return information about character device backends.
#
-# Since: 2.0
+# Details:
#
# .. qmp-example::
#
@@ -103,6 +105,8 @@
# }
# ]
# }
+#
+# Since: 2.0
##
{ 'command': 'query-chardev-backends', 'returns': ['ChardevBackendInfo'] }
@@ -137,8 +141,6 @@
# - data itself is always Unicode regardless of format, like any
# other string.
#
-# Since: 1.4
-#
# .. qmp-example::
#
# -> { "execute": "ringbuf-write",
@@ -146,6 +148,8 @@
# "data": "abcdefgh",
# "format": "utf8" } }
# <- { "return": {} }
+#
+# Since: 1.4
##
{ 'command': 'ringbuf-write',
'data': { 'device': 'str',
@@ -173,8 +177,6 @@
#
# Returns: data read from the device
#
-# Since: 1.4
-#
# .. qmp-example::
#
# -> { "execute": "ringbuf-read",
@@ -182,6 +184,8 @@
# "size": 1000,
# "format": "utf8" } }
# <- { "return": "abcdefgh" }
+#
+# Since: 1.4
##
{ 'command': 'ringbuf-read',
'data': {'device': 'str', 'size': 'int', '*format': 'DataFormat'},
@@ -761,8 +765,6 @@
#
# @backend: backend type and parameters
#
-# Since: 1.4
-#
# .. qmp-example::
#
# -> { "execute" : "chardev-add",
@@ -784,6 +786,8 @@
# "arguments" : { "id" : "baz",
# "backend" : { "type" : "pty", "data" : {} } } }
# <- { "return": { "pty" : "/dev/pty/42" } }
+#
+# Since: 1.4
##
{ 'command': 'chardev-add',
'data': { 'id': 'str',
@@ -799,8 +803,6 @@
#
# @backend: new backend type and parameters
#
-# Since: 2.10
-#
# .. qmp-example::
#
# -> { "execute" : "chardev-change",
@@ -825,6 +827,8 @@
# "server" : true,
# "wait" : false }}}}
# <- {"return": {}}
+#
+# Since: 2.10
##
{ 'command': 'chardev-change',
'data': { 'id': 'str',
@@ -838,12 +842,12 @@
#
# @id: the chardev's ID, must exist and not be in use
#
-# Since: 1.4
-#
# .. qmp-example::
#
# -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
# <- { "return": {} }
+#
+# Since: 1.4
##
{ 'command': 'chardev-remove',
'data': { 'id': 'str' } }
@@ -855,12 +859,12 @@
#
# @id: the chardev's ID, must exist
#
-# Since: 2.10
-#
# .. qmp-example::
#
# -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
# <- { "return": {} }
+#
+# Since: 2.10
##
{ 'command': 'chardev-send-break',
'data': { 'id': 'str' } }
@@ -876,13 +880,13 @@
#
# .. note:: This event is rate-limited.
#
-# Since: 2.1
-#
# .. qmp-example::
#
# <- { "event": "VSERPORT_CHANGE",
# "data": { "id": "channel0", "open": true },
# "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
+#
+# Since: 2.1
##
{ 'event': 'VSERPORT_CHANGE',
'data': { 'id': 'str',
diff --git a/qapi/control.json b/qapi/control.json
index 9a5302193d6..758b176de72 100644
--- a/qapi/control.json
+++ b/qapi/control.json
@@ -97,8 +97,6 @@
#
# Returns: An object describing the current version of QEMU.
#
-# Since: 0.14
-#
# .. qmp-example::
#
# -> { "execute": "query-version" }
@@ -112,6 +110,8 @@
# "package":""
# }
# }
+#
+# Since: 0.14
##
{ 'command': 'query-version', 'returns': 'VersionInfo',
'allow-preconfig': true }
@@ -134,8 +134,6 @@
#
# Returns: A list of all supported commands
#
-# Since: 0.14
-#
# .. qmp-example::
#
# -> { "execute": "query-commands" }
@@ -152,6 +150,8 @@
# }
#
# This example has been shortened as the real response is too long.
+#
+# Since: 0.14
##
{ 'command': 'query-commands', 'returns': ['CommandInfo'],
'allow-preconfig': true }
@@ -161,16 +161,18 @@
#
# Request graceful QEMU process termination.
#
+# Details:
+#
# 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
-#
# .. qmp-example::
#
# -> { "execute": "quit" }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'quit',
'allow-preconfig': true }
diff --git a/qapi/dump.json b/qapi/dump.json
index 726b5208703..bda1c731544 100644
--- a/qapi/dump.json
+++ b/qapi/dump.json
@@ -94,13 +94,13 @@
#
# .. note:: All boolean arguments default to false.
#
-# Since: 1.2
-#
# .. qmp-example::
#
# -> { "execute": "dump-guest-memory",
# "arguments": { "paging": false, "protocol": "fd:dump" } }
# <- { "return": {} }
+#
+# Since: 1.2
##
{ 'command': 'dump-guest-memory',
'data': { 'paging': 'bool', 'protocol': 'str', '*detach': 'bool',
@@ -150,13 +150,13 @@
#
# Returns: An object showing the dump status.
#
-# Since: 2.6
-#
# .. qmp-example::
#
# -> { "execute": "query-dump" }
# <- { "return": { "status": "active", "completed": 1024000,
# "total": 2048000 } }
+#
+# Since: 2.6
##
{ 'command': 'query-dump', 'returns': 'DumpQueryResult' }
@@ -171,14 +171,14 @@
# failed. Only presents on failure. The user should not try to
# interpret the error string.
#
-# Since: 2.6
-#
# .. qmp-example::
#
# <- { "event": "DUMP_COMPLETED",
# "data": { "result": { "total": 1090650112, "status": "completed",
# "completed": 1090650112 } },
# "timestamp": { "seconds": 1648244171, "microseconds": 950316 } }
+#
+# Since: 2.6
##
{ 'event': 'DUMP_COMPLETED' ,
'data': { 'result': 'DumpQueryResult', '*error': 'str' } }
@@ -201,13 +201,13 @@
#
# Returns: An object listing available formats for `dump-guest-memory`
#
-# Since: 2.0
-#
# .. qmp-example::
#
# -> { "execute": "query-dump-guest-memory-capability" }
# <- { "return": { "formats":
# ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] } }
+#
+# Since: 2.0
##
{ 'command': 'query-dump-guest-memory-capability',
'returns': 'DumpGuestMemoryCapability' }
diff --git a/qapi/machine-s390x.json b/qapi/machine-s390x.json
index e67f180a272..adc986418d7 100644
--- a/qapi/machine-s390x.json
+++ b/qapi/machine-s390x.json
@@ -79,13 +79,13 @@
#
# @unstable: This event is experimental.
#
-# Since: 8.2
-#
# .. qmp-example::
#
# <- { "event": "CPU_POLARIZATION_CHANGE",
# "data": { "polarization": "horizontal" },
# "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
+#
+# Since: 8.2
##
{ 'event': 'CPU_POLARIZATION_CHANGE',
'data': { 'polarization': 'S390CpuPolarization' },
@@ -130,12 +130,12 @@
#
# @unstable: This event is experimental.
#
-# Since: 10.2
-#
# .. qmp-example::
#
# <- { "event": "SCLP_CPI_INFO_AVAILABLE",
# "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
+#
+# Since: 10.2
##
{ 'event': 'SCLP_CPI_INFO_AVAILABLE',
'features': [ 'unstable' ]
diff --git a/qapi/machine.json b/qapi/machine.json
index 0a4b758b2d5..2cfa4b9b046 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -108,7 +108,7 @@
#
# Return information about all virtual CPUs.
#
-# Since: 2.12
+# Details:
#
# .. qmp-example::
#
@@ -138,6 +138,8 @@
# }
# ]
# }
+#
+# Since: 2.12
##
{ 'command': 'query-cpus-fast', 'returns': [ 'CpuInfoFast' ] }
@@ -223,8 +225,6 @@
#
# @unstable: Argument @compat-props is experimental.
#
-# Since: 1.2
-#
# .. qmp-example::
#
# -> { "execute": "query-machines", "arguments": { "compat-props": true } }
@@ -247,6 +247,8 @@
# },
# ...
# }
+#
+# Since: 1.2
##
{ 'command': 'query-machines',
'data': { '*compat-props': { 'type': 'bool',
@@ -303,10 +305,10 @@
#
# @UUID: the UUID of the guest
#
-# Since: 0.14
-#
# .. note:: If no UUID was specified for the guest, the nil UUID (all
# zeroes) is returned.
+#
+# Since: 0.14
##
{ 'struct': 'UuidInfo', 'data': {'UUID': 'str'} }
@@ -315,12 +317,14 @@
#
# Query the guest UUID information.
#
-# Since: 0.14
+# Details:
#
# .. qmp-example::
#
# -> { "execute": "query-uuid" }
# <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
+#
+# Since: 0.14
##
{ 'command': 'query-uuid', 'returns': 'UuidInfo', 'allow-preconfig': true }
@@ -349,12 +353,14 @@
#
# Performs a hard reset of a guest.
#
-# Since: 0.14
+# Details:
#
# .. qmp-example::
#
# -> { "execute": "system_reset" }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'system_reset' }
@@ -363,7 +369,7 @@
#
# Requests that a guest perform a powerdown operation.
#
-# Since: 0.14
+# Details:
#
# .. note:: A guest may or may not respond to this command. This
# command returning does not indicate that a guest has accepted the
@@ -374,6 +380,8 @@
#
# -> { "execute": "system_powerdown" }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'system_powerdown' }
@@ -385,7 +393,7 @@
# `query-current-machine`), wake-up guest from suspend if the guest is
# in SUSPENDED state. Return an error otherwise.
#
-# Since: 1.1
+# Details:
#
# .. note:: Prior to 4.0, this command does nothing in case the guest
# isn't suspended.
@@ -394,6 +402,8 @@
#
# -> { "execute": "system_wakeup" }
# <- { "return": {} }
+#
+# Since: 1.1
##
{ 'command': 'system_wakeup' }
@@ -436,7 +446,7 @@
# all CPUs (ppc64). The command fails when the guest doesn't support
# injecting.
#
-# Since: 0.14
+# Details:
#
# .. note:: Prior to 2.1, this command was only supported for x86 and
# s390 VMs.
@@ -445,6 +455,8 @@
#
# -> { "execute": "inject-nmi" }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'inject-nmi' }
@@ -806,8 +818,6 @@
# @cpu-index: the index of the virtual CPU to use for translating the
# virtual address (defaults to CPU 0)
#
-# Since: 0.14
-#
# .. caution:: Errors were not reliably returned until 1.1.
#
# .. qmp-example::
@@ -817,6 +827,8 @@
# "size": 100,
# "filename": "/tmp/virtual-mem-dump" } }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'memsave',
'data': {
@@ -836,8 +848,6 @@
#
# @filename: the file to save the memory to as binary data
#
-# Since: 0.14
-#
# .. caution:: Errors were not reliably returned until 1.1.
#
# .. qmp-example::
@@ -847,6 +857,8 @@
# "size": 100,
# "filename": "/tmp/physical-mem-dump" } }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'pmemsave',
'data': {
@@ -900,7 +912,7 @@
#
# Return information for all memory backends.
#
-# Since: 2.1
+# Details:
#
# .. qmp-example::
#
@@ -927,6 +939,8 @@
# }
# ]
# }
+#
+# Since: 2.1
##
{ 'command': 'query-memdev', 'returns': ['Memdev'], 'allow-preconfig': true }
@@ -1015,8 +1029,6 @@
#
# TODO: Better documentation; currently there is none.
#
-# Since: 2.7
-#
# .. qmp-example::
# :annotated:
#
@@ -1067,6 +1079,8 @@
# "props": { "core-id": 0 }
# }
# ]}
+#
+# Since: 2.7
##
{ 'command': 'query-hotpluggable-cpus', 'returns': ['HotpluggableCPU'],
'allow-preconfig': true }
@@ -1105,8 +1119,6 @@
# returns, the balloon size may not have changed. A guest can
# change the balloon size independent of this command.
#
-# Since: 0.14
-#
# .. qmp-example::
# :annotated:
#
@@ -1116,6 +1128,8 @@
# <- { "return": {} }
#
# With a 2.5GiB guest this command inflated the ballon to 3GiB.
+#
+# Since: 0.14
##
{ 'command': 'balloon', 'data': {'value': 'int'} }
@@ -1141,8 +1155,6 @@
# the KVM kernel module cannot support it, KVMMissingCap
# - If no balloon device is present, DeviceNotActive
#
-# Since: 0.14
-#
# .. qmp-example::
#
# -> { "execute": "query-balloon" }
@@ -1150,6 +1162,8 @@
# "actual": 1073741824
# }
# }
+#
+# Since: 0.14
##
{ 'command': 'query-balloon', 'returns': 'BalloonInfo' }
@@ -1165,13 +1179,13 @@
#
# .. note:: This event is rate-limited.
#
-# Since: 1.2
-#
# .. qmp-example::
#
# <- { "event": "BALLOON_CHANGE",
# "data": { "actual": 944766976 },
# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
+#
+# Since: 1.2
##
{ 'event': 'BALLOON_CHANGE',
'data': { 'actual': 'int' } }
@@ -1204,8 +1218,6 @@
# reporting is not enabled or no guest memory status report
# received yet, GenericError
#
-# Since: 8.2
-#
# .. qmp-example::
#
# -> { "execute": "query-hv-balloon-status-report" }
@@ -1214,6 +1226,8 @@
# "available": 3333054464
# }
# }
+#
+# Since: 8.2
##
{ 'command': 'query-hv-balloon-status-report', 'returns': 'HvBalloonInfo' }
@@ -1227,13 +1241,13 @@
#
# .. note:: This event is rate-limited.
#
-# Since: 8.2
-#
# .. qmp-example::
#
# <- { "event": "HV_BALLOON_STATUS_REPORT",
# "data": { "committed": 816640000, "available": 3333054464 },
# "timestamp": { "seconds": 1600295492, "microseconds": 661044 } }
+#
+# Since: 8.2
##
{ 'event': 'HV_BALLOON_STATUS_REPORT',
'data': 'HvBalloonInfo' }
@@ -1540,7 +1554,7 @@
#
# Lists available memory devices and their state
#
-# Since: 2.1
+# Details:
#
# .. qmp-example::
#
@@ -1556,6 +1570,8 @@
# "slot": 0},
# "type": "dimm"
# } ] }
+#
+# Since: 2.1
##
{ 'command': 'query-memory-devices', 'returns': ['MemoryDeviceInfo'] }
@@ -1574,14 +1590,14 @@
#
# .. note:: This event is rate-limited.
#
-# Since: 5.1
-#
# .. qmp-example::
#
# <- { "event": "MEMORY_DEVICE_SIZE_CHANGE",
# "data": { "id": "vm0", "size": 1073741824,
# "qom-path": "/machine/unattached/device[2]" },
# "timestamp": { "seconds": 1588168529, "microseconds": 201316 } }
+#
+# Since: 5.1
##
{ 'event': 'MEMORY_DEVICE_SIZE_CHANGE',
'data': { '*id': 'str', 'size': 'size', 'qom-path' : 'str'} }
@@ -1814,13 +1830,13 @@
#
# @filename: name of the dtb file to be created
#
-# Since: 7.2
-#
# .. qmp-example::
#
# -> { "execute": "dumpdtb" }
# "arguments": { "filename": "fdt.dtb" } }
# <- { "return": {} }
+#
+# Since: 7.2
##
{ 'command': 'dumpdtb',
'data': { 'filename': 'str' },
@@ -1879,13 +1895,13 @@
#
# @filename: the path to the file to dump to
#
-# Since: 2.5
-#
# .. qmp-example::
#
# -> { "execute": "dump-skeys",
# "arguments": { "filename": "/tmp/skeys" } }
# <- { "return": {} }
+#
+# Since: 2.5
##
{ 'command': 'dump-skeys',
'data': { 'filename': 'str' } }
diff --git a/qapi/migration.json b/qapi/migration.json
index 558b4f145ed..79c24e36958 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -339,7 +339,7 @@
# Return information about current migration process. If migration is
# active there will be another json-object with RAM migration status.
#
-# Since: 0.14
+# Details:
#
# .. qmp-example::
# :title: Before the first migration
@@ -426,6 +426,8 @@
# }
# }
# }
+#
+# Since: 0.14
##
{ 'command': 'query-migrate', 'returns': 'MigrationInfo' }
@@ -562,13 +564,13 @@
#
# @capabilities: json array of capability modifications to make
#
-# Since: 1.2
-#
# .. qmp-example::
#
# -> { "execute": "migrate-set-capabilities" , "arguments":
# { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
# <- { "return": {} }
+#
+# Since: 1.2
##
{ 'command': 'migrate-set-capabilities',
'data': { 'capabilities': ['MigrationCapabilityStatus'] } }
@@ -578,7 +580,7 @@
#
# Return information about the current migration capabilities status
#
-# Since: 1.2
+# Details:
#
# .. qmp-example::
#
@@ -591,6 +593,8 @@
# {"state": false, "capability": "postcopy-ram"},
# {"state": false, "capability": "x-colo"}
# ]}
+#
+# Since: 1.2
##
{ 'command': 'query-migrate-capabilities', 'returns': ['MigrationCapabilityStatus']}
@@ -838,13 +842,15 @@
#
# Set migration parameters. All arguments are optional.
#
-# Since: 2.4
+# Details:
#
# .. qmp-example::
#
# -> { "execute": "migrate-set-parameters" ,
# "arguments": { "multifd-channels": 5 } }
# <- { "return": {} }
+#
+# Since: 2.4
##
{ 'command': 'migrate-set-parameters', 'boxed': true,
'data': 'MigrationParameters' }
@@ -1056,7 +1062,7 @@
# @block-bitmap-mapping, which is only present if it has been
# previously set.
#
-# Since: 2.4
+# Details:
#
# .. qmp-example::
#
@@ -1069,6 +1075,8 @@
# "downtime-limit": 300
# }
# }
+#
+# Since: 2.4
##
{ 'command': 'query-migrate-parameters',
'returns': 'MigrationParameters' }
@@ -1080,12 +1088,14 @@
# mode. The postcopy-ram capability must be set on both source and
# destination before the original migration command.
#
-# Since: 2.5
+# Details:
#
# .. qmp-example::
#
# -> { "execute": "migrate-start-postcopy" }
# <- { "return": {} }
+#
+# Since: 2.5
##
{ 'command': 'migrate-start-postcopy' }
@@ -1096,13 +1106,13 @@
#
# @status: `MigrationStatus` describing the current migration status.
#
-# Since: 2.4
-#
# .. qmp-example::
#
# <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
# "event": "MIGRATION",
# "data": {"status": "completed"} }
+#
+# Since: 2.4
##
{ 'event': 'MIGRATION',
'data': {'status': 'MigrationStatus'}}
@@ -1115,12 +1125,12 @@
#
# @pass: An incrementing count (starting at 1 on the first pass)
#
-# Since: 2.6
-#
# .. qmp-example::
#
# <- { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
# "event": "MIGRATION_PASS", "data": {"pass": 2} }
+#
+# Since: 2.6
##
{ 'event': 'MIGRATION_PASS',
'data': { 'pass': 'int' } }
@@ -1199,12 +1209,12 @@
#
# @reason: describes the reason for the COLO exit.
#
-# Since: 3.1
-#
# .. qmp-example::
#
# <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172},
# "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } }
+#
+# Since: 3.1
##
{ 'event': 'COLO_EXIT',
'data': {'mode': 'COLOMode', 'reason': 'COLOExitReason' } }
@@ -1242,12 +1252,12 @@
#
# @unstable: This command is experimental.
#
-# Since: 2.8
-#
# .. qmp-example::
#
# -> { "execute": "x-colo-lost-heartbeat" }
# <- { "return": {} }
+#
+# Since: 2.8
##
{ 'command': 'x-colo-lost-heartbeat',
'features': [ 'unstable' ],
@@ -1260,15 +1270,17 @@
# migration to be started right after. When postcopy-ram is in use,
# cancelling is not allowed after the postcopy phase has started.
#
+# Details:
+#
# .. note:: This command succeeds even if there is no migration
# process running.
#
-# Since: 0.14
-#
# .. qmp-example::
#
# -> { "execute": "migrate_cancel" }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'migrate_cancel' }
@@ -1279,13 +1291,13 @@
#
# @state: The state the migration is currently expected to be in
#
-# Since: 2.11
-#
# .. qmp-example::
#
# -> { "execute": "migrate-continue" , "arguments":
# { "state": "pre-switchover" } }
# <- { "return": {} }
+#
+# Since: 2.11
##
{ 'command': 'migrate-continue', 'data': {'state': 'MigrationStatus'} }
@@ -1394,8 +1406,6 @@
# will fail unless migration is in "postcopy-paused" state.
# (default: false, since 3.0)
#
-# Since: 0.14
-#
# .. admonition:: Notes
#
# 1. The `query-migrate` command should be used to check
@@ -1449,6 +1459,8 @@
# "filename": "/tmp/migfile",
# "offset": "0x1000" } } ] } }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'migrate',
'data': {'*uri': 'str',
@@ -1472,8 +1484,6 @@
# :qapi:event:`MIGRATION` event, and error details could be
# retrieved with `query-migrate`. (since 9.1)
#
-# Since: 2.3
-#
# .. admonition:: Notes
#
# 1. It's a bad idea to use a string for the uri, but it needs to
@@ -1521,6 +1531,8 @@
# "host": "10.12.34.9",
# "port": "1050" } } ] } }
# <- { "return": {} }
+#
+# Since: 2.3
##
{ 'command': 'migrate-incoming',
'data': {'*uri': 'str',
@@ -1540,13 +1552,13 @@
# @live: Optional argument to ask QEMU to treat this command as part
# of a live migration. Default to true. (since 2.11)
#
-# Since: 1.1
-#
# .. qmp-example::
#
# -> { "execute": "xen-save-devices-state",
# "arguments": { "filename": "/tmp/save" } }
# <- { "return": {} }
+#
+# Since: 1.1
##
{ 'command': 'xen-save-devices-state',
'data': {'filename': 'str', '*live':'bool' } }
@@ -1558,13 +1570,13 @@
#
# @enable: true to enable, false to disable.
#
-# Since: 1.3
-#
# .. qmp-example::
#
# -> { "execute": "xen-set-global-dirty-log",
# "arguments": { "enable": true } }
# <- { "return": {} }
+#
+# Since: 1.3
##
{ 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } }
@@ -1578,13 +1590,13 @@
# data. See `xen-save-devices-state`.txt for a description of the
# binary format.
#
-# Since: 2.7
-#
# .. qmp-example::
#
# -> { "execute": "xen-load-devices-state",
# "arguments": { "filename": "/tmp/resume" } }
# <- { "return": {} }
+#
+# Since: 2.7
##
{ 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} }
@@ -1747,13 +1759,13 @@
#
# @device-id: QEMU device id of the unplugged device
#
-# Since: 4.2
-#
# .. qmp-example::
#
# <- { "event": "UNPLUG_PRIMARY",
# "data": { "device-id": "hostdev0" },
# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+#
+# Since: 4.2
##
{ 'event': 'UNPLUG_PRIMARY',
'data': { 'device-id': 'str' } }
@@ -1907,8 +1919,6 @@
# 'page-sampling'. Others are 'dirty-bitmap' and 'dirty-ring'.
# (Since 6.1)
#
-# Since: 5.2
-#
# .. qmp-example::
#
# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1,
@@ -1924,6 +1934,8 @@
# "calc-time-unit": "millisecond", "mode": "dirty-bitmap"} }
#
# <- { "return": {} }
+#
+# Since: 5.2
##
{ 'command': 'calc-dirty-rate', 'data': {'calc-time': 'int64',
'*calc-time-unit': 'TimeUnit',
@@ -1938,8 +1950,6 @@
# @calc-time-unit: time unit in which to report calculation time.
# By default it is reported in seconds. (Since 8.2)
#
-# Since: 5.2
-#
# .. qmp-example::
# :title: Measurement is in progress
#
@@ -1953,6 +1963,8 @@
# <- {"status": "measured", "sample-pages": 512, "dirty-rate": 108,
# "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10,
# "calc-time-unit": "second"}
+#
+# Since: 5.2
##
{ 'command': 'query-dirty-rate', 'data': {'*calc-time-unit': 'TimeUnit' },
'returns': 'DirtyRateInfo' }
@@ -1989,14 +2001,14 @@
#
# @dirty-rate: upper limit of dirty page rate (MB/s) for virtual CPUs.
#
-# Since: 7.1
-#
# .. qmp-example::
#
# -> {"execute": "set-vcpu-dirty-limit"}
# "arguments": { "dirty-rate": 200,
# "cpu-index": 1 } }
# <- { "return": {} }
+#
+# Since: 7.1
##
{ 'command': 'set-vcpu-dirty-limit',
'data': { '*cpu-index': 'int',
@@ -2013,13 +2025,13 @@
#
# @cpu-index: index of a virtual CPU, default is all.
#
-# Since: 7.1
-#
# .. qmp-example::
#
# -> {"execute": "cancel-vcpu-dirty-limit"},
# "arguments": { "cpu-index": 1 } }
# <- { "return": {} }
+#
+# Since: 7.1
##
{ 'command': 'cancel-vcpu-dirty-limit',
'data': { '*cpu-index': 'int'} }
@@ -2029,7 +2041,7 @@
#
# Return information about virtual CPU dirty page rate limits, if any.
#
-# Since: 7.1
+# Details:
#
# .. qmp-example::
#
@@ -2037,6 +2049,8 @@
# <- {"return": [
# { "limit-rate": 60, "current-rate": 3, "cpu-index": 0},
# { "limit-rate": 60, "current-rate": 3, "cpu-index": 1}]}
+#
+# Since: 7.1
##
{ 'command': 'query-vcpu-dirty-limit',
'returns': [ 'DirtyLimitInfo' ] }
diff --git a/qapi/misc-arm.json b/qapi/misc-arm.json
index 4e3f1a54055..4a2746ee1aa 100644
--- a/qapi/misc-arm.json
+++ b/qapi/misc-arm.json
@@ -38,13 +38,13 @@
# On non-ARM targets this command will report an error as the GIC
# technology is not applicable.
#
-# Since: 2.6
-#
# .. qmp-example::
#
# -> { "execute": "query-gic-capabilities" }
# <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
# { "version": 3, "emulated": false, "kernel": true } ] }
+#
+# Since: 2.6
##
{ 'command': 'query-gic-capabilities', 'returns': ['GICCapability'] }
diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json
index c92853507f3..01cdf8d706e 100644
--- a/qapi/misc-i386.json
+++ b/qapi/misc-i386.json
@@ -10,16 +10,18 @@
# mechanism to synchronize guest time is in effect, for example QEMU
# guest agent's `guest-set-time` command.
#
+# Details:
+#
# Use of this command is only applicable for x86 machines with an RTC,
# and on other machines will silently return without performing any
# action.
#
-# Since: 2.1
-#
# .. qmp-example::
#
# -> { "execute": "rtc-reset-reinjection" }
# <- { "return": {} }
+#
+# Since: 2.1
##
{ 'command': 'rtc-reset-reinjection' }
@@ -133,14 +135,14 @@
# @enabled field is set to 'false' and the state of all other fields
# is unspecified.
#
-# Since: 2.12
-#
# .. qmp-example::
#
# -> { "execute": "query-sev" }
# <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0,
# "build-id" : 0, "policy" : 0, "state" : "running",
# "handle" : 1 } }
+#
+# Since: 2.12
##
{ 'command': 'query-sev', 'returns': 'SevInfo' }
@@ -171,12 +173,12 @@
# invalid guest configuration or if the guest has not reached
# the required SEV state, GenericError
#
-# Since: 2.12
-#
# .. qmp-example::
#
# -> { "execute": "query-sev-launch-measure" }
# <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } }
+#
+# Since: 2.12
##
{ 'command': 'query-sev-launch-measure', 'returns': 'SevLaunchMeasureInfo' }
@@ -216,14 +218,14 @@
# Errors:
# - If SEV is not available on the platform, GenericError
#
-# Since: 2.12
-#
# .. qmp-example::
#
# -> { "execute": "query-sev-capabilities" }
# <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE",
# "cpu0-id": "2lvmGwo+...61iEinw==",
# "cbitpos": 47, "reduced-phys-bits": 1}}
+#
+# Since: 2.12
##
{ 'command': 'query-sev-capabilities', 'returns': 'SevCapability' }
@@ -282,13 +284,13 @@
# invalid guest configuration or because the guest has not
# reached the required SEV state, GenericError
#
-# Since: 6.1
-#
# .. qmp-example::
#
# -> { "execute" : "query-sev-attestation-report",
# "arguments": { "mnonce": "aaaaaaa" } }
# <- { "return" : { "data": "aaaaaaaabbbddddd"} }
+#
+# Since: 6.1
##
{ 'command': 'query-sev-attestation-report',
'data': { 'mnonce': 'str' },
@@ -338,7 +340,7 @@
#
# Return information about configured SGX capabilities of guest
#
-# Since: 6.2
+# Details:
#
# .. qmp-example::
#
@@ -347,6 +349,8 @@
# "flc": true,
# "sections": [{"node": 0, "size": 67108864},
# {"node": 1, "size": 29360128}]} }
+#
+# Since: 6.2
##
{ 'command': 'query-sgx', 'returns': 'SgxInfo' }
@@ -355,7 +359,7 @@
#
# Return information about SGX capabilities of host
#
-# Since: 6.2
+# Details:
#
# .. qmp-example::
#
@@ -364,6 +368,8 @@
# "flc": true,
# "section" : [{"node": 0, "size": 67108864},
# {"node": 1, "size": 29360128}]} }
+#
+# Since: 6.2
##
{ 'command': 'query-sgx-capabilities', 'returns': 'SgxInfo' }
@@ -426,8 +432,6 @@
#
# Returns: list of open event channel ports.
#
-# Since: 8.0
-#
# .. qmp-example::
#
# -> { "execute": "xen-event-list" }
@@ -452,6 +456,8 @@
# }
# ]
# }
+#
+# Since: 8.0
##
{ 'command': 'xen-event-list',
'returns': ['EvtchnInfo'] }
@@ -463,12 +469,12 @@
#
# @port: The port number
#
-# Since: 8.0
-#
# .. qmp-example::
#
# -> { "execute": "xen-event-inject", "arguments": { "port": 1 } }
# <- { "return": { } }
+#
+# Since: 8.0
##
{ 'command': 'xen-event-inject',
'data': { 'port': 'uint32' } }
diff --git a/qapi/misc.json b/qapi/misc.json
index 05866837f09..40f5b9559cb 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -30,13 +30,13 @@
#
# @tls: whether to perform TLS. Only applies to the "spice" protocol
#
-# Since: 0.14
-#
# .. qmp-example::
#
# -> { "execute": "add_client", "arguments": { "protocol": "vnc",
# "fdname": "myclient" } }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'add_client',
'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool',
@@ -58,12 +58,14 @@
#
# Return the name information of a guest.
#
-# Since: 0.14
+# Details:
#
# .. qmp-example::
#
# -> { "execute": "query-name" }
# <- { "return": { "name": "qemu-name" } }
+#
+# Since: 0.14
##
{ 'command': 'query-name', 'returns': 'NameInfo', 'allow-preconfig': true }
@@ -109,8 +111,6 @@
#
# Returns: a list of info for each iothread
#
-# Since: 2.0
-#
# .. qmp-example::
#
# -> { "execute": "query-iothreads" }
@@ -125,6 +125,8 @@
# }
# ]
# }
+#
+# Since: 2.0
##
{ 'command': 'query-iothreads', 'returns': ['IOThreadInfo'],
'allow-preconfig': true }
@@ -134,7 +136,7 @@
#
# Stop guest VM execution.
#
-# Since: 0.14
+# Details:
#
# .. note:: This function will succeed even if the guest is already in
# the stopped state. In "inmigrate" state, it will ensure that the
@@ -148,6 +150,8 @@
#
# -> { "execute": "stop" }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'stop' }
@@ -156,7 +160,7 @@
#
# Resume guest VM execution.
#
-# Since: 0.14
+# Details:
#
# .. note:: This command will succeed if the guest is currently
# running. It will also succeed if the guest is in the "inmigrate"
@@ -172,6 +176,8 @@
#
# -> { "execute": "cont" }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'cont' }
@@ -190,12 +196,12 @@
#
# @unstable: This command is experimental.
#
-# Since: 3.0
-#
# .. qmp-example::
#
# -> { "execute": "x-exit-preconfig" }
# <- { "return": {} }
+#
+# Since: 3.0
##
{ 'command': 'x-exit-preconfig', 'allow-preconfig': true,
'features': [ 'unstable' ] }
@@ -217,8 +223,6 @@
# monitor-owned nodes if they have no parents. This allows the
# use of 'savevm' with -blockdev. (since 4.2)
#
-# Since: 0.14
-#
# .. note:: This command only exists as a stop-gap. Its use is highly
# discouraged. The semantics of this command are not guaranteed:
# this means that command names, arguments and responses can change
@@ -237,6 +241,8 @@
# -> { "execute": "human-monitor-command",
# "arguments": { "command-line": "info kvm" } }
# <- { "return": "kvm support: enabled\r\n" }
+#
+# Since: 0.14
##
{ 'command': 'human-monitor-command',
'data': {'command-line': 'str', '*cpu-index': 'int'},
@@ -250,8 +256,6 @@
#
# @fdname: file descriptor name
#
-# Since: 0.14
-#
# .. note:: If @fdname already exists, the file descriptor assigned to
# it will be closed and replaced by the received file descriptor.
#
@@ -262,6 +266,8 @@
#
# -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'getfd', 'data': {'fdname': 'str'}, 'if': 'CONFIG_POSIX' }
@@ -277,8 +283,6 @@
#
# @fdname: file descriptor name
#
-# Since: 8.0
-#
# .. note:: If @fdname already exists, the file descriptor assigned to
# it will be closed and replaced by the received file descriptor.
#
@@ -290,6 +294,8 @@
# -> { "execute": "get-win32-socket",
# "arguments": { "info": "abcd123..", "fdname": "skclient" } }
# <- { "return": {} }
+#
+# Since: 8.0
##
{ 'command': 'get-win32-socket', 'data': {'info': 'str', 'fdname': 'str'}, 'if': 'CONFIG_WIN32' }
@@ -300,12 +306,12 @@
#
# @fdname: file descriptor name
#
-# Since: 0.14
-#
# .. qmp-example::
#
# -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'closefd', 'data': {'fdname': 'str'} }
@@ -341,12 +347,12 @@
# .. note:: If @fdset-id is not specified, a new fd set will be
# created.
#
-# Since: 1.2
-#
# .. qmp-example::
#
# -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
# <- { "return": { "fdset-id": 1, "fd": 3 } }
+#
+# Since: 1.2
##
{ 'command': 'add-fd',
'data': { '*fdset-id': 'int',
@@ -365,8 +371,6 @@
# Errors:
# - If @fdset-id or @fd is not found, GenericError
#
-# Since: 1.2
-#
# .. note:: The list of fd sets is shared by all monitor connections.
#
# .. note:: If @fd is not specified, all file descriptors in @fdset-id
@@ -376,6 +380,8 @@
#
# -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
# <- { "return": {} }
+#
+# Since: 1.2
##
{ 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} }
@@ -412,7 +418,7 @@
#
# Return information describing all fd sets.
#
-# Since: 1.2
+# Details:
#
# .. note:: The list of fd sets is shared by all monitor connections.
#
@@ -446,6 +452,8 @@
# }
# ]
# }
+#
+# Since: 1.2
##
{ 'command': 'query-fdsets', 'returns': ['FdsetInfo'] }
@@ -516,8 +524,6 @@
# Errors:
# - if the given @option doesn't exist
#
-# Since: 1.5
-#
# .. qmp-example::
#
# -> { "execute": "query-command-line-options",
@@ -538,6 +544,8 @@
# }
# ]
# }
+#
+# Since: 1.5
##
{'command': 'query-command-line-options',
'data': {'*option': 'str'},
@@ -558,13 +566,13 @@
# RTC in the system implements this event, or even that the system
# has an RTC at all.
#
-# Since: 0.13
-#
# .. qmp-example::
#
# <- { "event": "RTC_CHANGE",
# "data": { "offset": 78 },
# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
+#
+# Since: 0.13
##
{ 'event': 'RTC_CHANGE',
'data': { 'offset': 'int', 'qom-path': 'str' } }
@@ -585,8 +593,6 @@
#
# @dev-qom-path: path to attached PCI device in the QOM tree
#
-# Since: 7.1
-#
# .. qmp-example::
#
# <- { "event": "VFU_CLIENT_HANGUP",
@@ -595,6 +601,8 @@
# "dev-id": "sas1",
# "dev-qom-path": "/machine/peripheral/sas1" },
# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+#
+# Since: 7.1
##
{ 'event': 'VFU_CLIENT_HANGUP',
'data': { 'vfu-id': 'str', 'vfu-qom-path': 'str',
diff --git a/qapi/net.json b/qapi/net.json
index c011d6dc1a9..2deb0b6dfdf 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -22,8 +22,6 @@
# Errors:
# - If @name is not a valid network device, DeviceNotFound
#
-# Since: 0.14
-#
# .. note:: Not all network adapters support setting link status.
# This command will succeed even if the network adapter does not
# support link status notification.
@@ -33,6 +31,8 @@
# -> { "execute": "set_link",
# "arguments": { "name": "e1000.0", "up": false } }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'set_link', 'data': {'name': 'str', 'up': 'bool'} }
@@ -43,8 +43,6 @@
#
# Additional arguments depend on the type.
#
-# Since: 0.14
-#
# Errors:
# - If @type is not a valid network backend, DeviceNotFound
#
@@ -54,6 +52,8 @@
# "arguments": { "type": "user", "id": "netdev1",
# "dnssearch": [ { "str": "example.org" } ] } }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'netdev_add', 'data': 'Netdev', 'boxed': true,
'allow-preconfig': true }
@@ -68,12 +68,12 @@
# Errors:
# - If @id is not a valid network backend, DeviceNotFound
#
-# Since: 0.14
-#
# .. qmp-example::
#
# -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'netdev_del', 'data': {'id': 'str'},
'allow-preconfig': true }
@@ -975,8 +975,6 @@
# - if the given NIC doesn't support rx-filter querying
# - if the given net client isn't a NIC
#
-# Since: 1.6
-#
# .. qmp-example::
#
# -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
@@ -1005,6 +1003,8 @@
# }
# ]
# }
+#
+# Since: 1.6
##
{ 'command': 'query-rx-filter',
'data': { '*name': 'str' },
@@ -1020,14 +1020,14 @@
#
# @path: device path
#
-# Since: 1.6
-#
# .. qmp-example::
#
# <- { "event": "NIC_RX_FILTER_CHANGED",
# "data": { "name": "vnet0",
# "path": "/machine/peripheral/vnet0/virtio-backend" },
# "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
+#
+# Since: 1.6
##
{ 'event': 'NIC_RX_FILTER_CHANGED',
'data': { '*name': 'str', 'path': 'str' } }
@@ -1095,13 +1095,13 @@
#
# @device-id: QEMU device id of the unplugged device
#
-# Since: 4.2
-#
# .. qmp-example::
#
# <- { "event": "FAILOVER_NEGOTIATED",
# "data": { "device-id": "net1" },
# "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
+#
+# Since: 4.2
##
{ 'event': 'FAILOVER_NEGOTIATED',
'data': {'device-id': 'str'} }
@@ -1115,8 +1115,6 @@
#
# @addr: The destination address
#
-# Since: 7.2
-#
# .. qmp-example::
#
# <- { "event": "NETDEV_STREAM_CONNECTED",
@@ -1131,6 +1129,8 @@
# "data": { "netdev-id": "netdev0",
# "addr": { "path": "/tmp/qemu0", "type": "unix" } },
# "timestamp": { "seconds": 1666269706, "microseconds": 413651 } }
+#
+# Since: 7.2
##
{ 'event': 'NETDEV_STREAM_CONNECTED',
'data': { 'netdev-id': 'str',
@@ -1143,13 +1143,13 @@
#
# @netdev-id: QEMU netdev id that is disconnected
#
-# Since: 7.2
-#
# .. qmp-example::
#
# <- { "event": "NETDEV_STREAM_DISCONNECTED",
# "data": {"netdev-id": "netdev0"},
# "timestamp": {"seconds": 1663330937, "microseconds": 526695} }
+#
+# Since: 7.2
##
{ 'event': 'NETDEV_STREAM_DISCONNECTED',
'data': { 'netdev-id': 'str' } }
@@ -1163,13 +1163,13 @@
#
# @chardev-id: The character device id used by the QEMU netdev
#
-# Since: 10.0
-#
# .. qmp-example::
#
# <- { "timestamp": {"seconds": 1739538638, "microseconds": 354181 },
# "event": "NETDEV_VHOST_USER_CONNECTED",
# "data": { "netdev-id": "netdev0", "chardev-id": "chr0" } }
+#
+# Since: 10.0
##
{ 'event': 'NETDEV_VHOST_USER_CONNECTED',
'data': { 'netdev-id': 'str', 'chardev-id': 'str' } }
@@ -1181,13 +1181,13 @@
#
# @netdev-id: QEMU netdev id that is disconnected
#
-# Since: 10.0
-#
# .. qmp-example::
#
# <- { "timestamp": { "seconds": 1739538634, "microseconds": 920450 },
# "event": "NETDEV_VHOST_USER_DISCONNECTED",
# "data": { "netdev-id": "netdev0" } }
+#
+# Since: 10.0
##
{ 'event': 'NETDEV_VHOST_USER_DISCONNECTED',
'data': { 'netdev-id': 'str' } }
diff --git a/qapi/pci.json b/qapi/pci.json
index 694c741e420..c36af01a100 100644
--- a/qapi/pci.json
+++ b/qapi/pci.json
@@ -182,8 +182,6 @@
# of all PCI devices attached to it. Each device is represented
# by a json-object.
#
-# Since: 0.14
-#
# .. qmp-example::
#
# -> { "execute": "query-pci" }
@@ -314,5 +312,7 @@
# }
#
# This example has been shortened as the real response is too long.
+#
+# Since: 0.14
##
{ 'command': 'query-pci', 'returns': ['PciInfo'] }
diff --git a/qapi/qdev.json b/qapi/qdev.json
index 974cf9c5830..483bc9eb9cd 100644
--- a/qapi/qdev.json
+++ b/qapi/qdev.json
@@ -103,8 +103,6 @@
# device will not be removed and a `DEVICE_UNPLUG_GUEST_ERROR`
# event is sent. Some errors cannot be detected.
#
-# Since: 0.14
-#
# .. qmp-example::
#
# -> { "execute": "device_del",
@@ -116,6 +114,8 @@
# -> { "execute": "device_del",
# "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'device_del', 'data': {'id': 'str'} }
@@ -131,14 +131,14 @@
#
# @path: the device's QOM path
#
-# Since: 1.5
-#
# .. qmp-example::
#
# <- { "event": "DEVICE_DELETED",
# "data": { "device": "virtio-net-pci-0",
# "path": "/machine/peripheral/virtio-net-pci-0" },
# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+#
+# Since: 1.5
##
{ 'event': 'DEVICE_DELETED',
'data': { '*device': 'str', 'path': 'str' } }
@@ -153,14 +153,14 @@
#
# @path: the device's QOM path
#
-# Since: 6.2
-#
# .. qmp-example::
#
# <- { "event": "DEVICE_UNPLUG_GUEST_ERROR",
# "data": { "device": "core1",
# "path": "/machine/peripheral/core1" },
# "timestamp": { "seconds": 1615570772, "microseconds": 202844 } }
+#
+# Since: 6.2
##
{ 'event': 'DEVICE_UNPLUG_GUEST_ERROR',
'data': { '*device': 'str', 'path': 'str' } }
diff --git a/qapi/qom.json b/qapi/qom.json
index fd88be07e13..9733a815a9b 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -85,8 +85,6 @@
#
# Returns: a list that describe the properties of the object.
#
-# Since: 1.2
-#
# .. qmp-example::
#
# -> { "execute": "qom-list",
@@ -95,6 +93,8 @@
# { "name": "parallel0", "type": "child<chardev-vc>" },
# { "name": "serial0", "type": "child<chardev-vc>" },
# { "name": "mon0", "type": "child<chardev-stdio>" } ] }
+#
+# Since: 1.2
##
{ 'command': 'qom-list',
'data': { 'path': 'str' },
@@ -129,8 +129,6 @@
# child<> and link<> properties are returned as #str pathnames.
# All integer property types (u8, u16, etc) are returned as #int.
#
-# Since: 1.2
-#
# .. qmp-example::
# :title: Use absolute path
#
@@ -146,6 +144,8 @@
# "arguments": { "path": "unattached/sysbus",
# "property": "type" } }
# <- { "return": "System" }
+#
+# Since: 1.2
##
{ 'command': 'qom-get',
'data': { 'path': 'str', 'property': 'str' },
@@ -186,8 +186,6 @@
# @value: a value who's type is appropriate for the property type.
# See `qom-get` for a description of type mapping.
#
-# Since: 1.2
-#
# .. qmp-example::
#
# -> { "execute": "qom-set",
@@ -195,6 +193,8 @@
# "property": "graphics",
# "value": false } }
# <- { "return": {} }
+#
+# Since: 1.2
##
{ 'command': 'qom-set',
'data': { 'path': 'str', 'property': 'str', 'value': 'any' },
@@ -1342,14 +1342,14 @@
# Errors:
# - If @qom-type is not a valid class name
#
-# Since: 2.0
-#
# .. qmp-example::
#
# -> { "execute": "object-add",
# "arguments": { "qom-type": "rng-random", "id": "rng1",
# "filename": "/dev/hwrng" } }
# <- { "return": {} }
+#
+# Since: 2.0
##
{ 'command': 'object-add', 'data': 'ObjectOptions', 'boxed': true,
'allow-preconfig': true }
@@ -1364,12 +1364,12 @@
# Errors:
# - If @id is not a valid id for a QOM object
#
-# Since: 2.0
-#
# .. qmp-example::
#
# -> { "execute": "object-del", "arguments": { "id": "rng1" } }
# <- { "return": {} }
+#
+# Since: 2.0
##
{ 'command': 'object-del', 'data': {'id': 'str'},
'allow-preconfig': true }
diff --git a/qapi/replay.json b/qapi/replay.json
index ccf84da68ef..bdee8e0ecfe 100644
--- a/qapi/replay.json
+++ b/qapi/replay.json
@@ -54,12 +54,12 @@
#
# Returns: record/replay information.
#
-# Since: 5.2
-#
# .. qmp-example::
#
# -> { "execute": "query-replay" }
# <- { "return": { "mode": "play", "filename": "log.rr", "icount": 220414 } }
+#
+# Since: 5.2
##
{ 'command': 'query-replay',
'returns': 'ReplayInfo' }
@@ -76,12 +76,12 @@
#
# @icount: instruction count to stop at
#
-# Since: 5.2
-#
# .. qmp-example::
#
# -> { "execute": "replay-break", "arguments": { "icount": 220414 } }
# <- { "return": {} }
+#
+# Since: 5.2
##
{ 'command': 'replay-break', 'data': { 'icount': 'int' } }
@@ -91,12 +91,14 @@
# Remove replay breakpoint which was set with `replay-break`. The
# command is ignored when there are no replay breakpoints.
#
-# Since: 5.2
+# Details:
#
# .. qmp-example::
#
# -> { "execute": "replay-delete-break" }
# <- { "return": {} }
+#
+# Since: 5.2
##
{ 'command': 'replay-delete-break' }
@@ -112,11 +114,11 @@
#
# @icount: target instruction count
#
-# Since: 5.2
-#
# .. qmp-example::
#
# -> { "execute": "replay-seek", "arguments": { "icount": 220414 } }
# <- { "return": {} }
+#
+# Since: 5.2
##
{ 'command': 'replay-seek', 'data': { 'icount': 'int' } }
diff --git a/qapi/rocker.json b/qapi/rocker.json
index 5d2dbd26034..e8efffc4c9f 100644
--- a/qapi/rocker.json
+++ b/qapi/rocker.json
@@ -30,12 +30,12 @@
#
# @name: switch name
#
-# Since: 2.4
-#
# .. qmp-example::
#
# -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
# <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
+#
+# Since: 2.4
##
{ 'command': 'query-rocker',
'data': { 'name': 'str' },
@@ -98,8 +98,6 @@
#
# @name: port name
#
-# Since: 2.4
-#
# .. qmp-example::
#
# -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
@@ -108,6 +106,8 @@
# {"duplex": "full", "enabled": true, "name": "sw1.2",
# "autoneg": "off", "link-up": true, "speed": 10000}
# ]}
+#
+# Since: 2.4
##
{ 'command': 'query-rocker-ports',
'data': { 'name': 'str' },
@@ -240,8 +240,6 @@
#
# Returns: rocker OF-DPA flow information
#
-# Since: 2.4
-#
# .. qmp-example::
#
# -> { "execute": "query-rocker-of-dpa-flows",
@@ -254,6 +252,8 @@
# },
# ...
# ]}
+#
+# Since: 2.4
##
{ 'command': 'query-rocker-of-dpa-flows',
'data': { 'name': 'str', '*tbl-id': 'uint32' },
@@ -315,8 +315,6 @@
#
# Returns: rocker OF-DPA group information
#
-# Since: 2.4
-#
# .. qmp-example::
#
# -> { "execute": "query-rocker-of-dpa-groups",
@@ -334,6 +332,8 @@
# "pport": 0, "vlan-id": 3840,
# "pop-vlan": 1, "id": 251658240}
# ]}
+#
+# Since: 2.4
##
{ 'command': 'query-rocker-of-dpa-groups',
'data': { 'name': 'str', '*type': 'uint8' },
diff --git a/qapi/run-state.json b/qapi/run-state.json
index a5771ad4681..1bc4e905f00 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -121,13 +121,15 @@
#
# Query the run status of the VM
#
-# Since: 0.14
+# Details:
#
# .. qmp-example::
#
# -> { "execute": "query-status" }
# <- { "return": { "running": true,
# "status": "running" } }
+#
+# Since: 0.14
##
{ 'command': 'query-status', 'returns': 'StatusInfo',
'allow-preconfig': true }
@@ -150,13 +152,13 @@
# specified, QEMU will not exit, and a `STOP` event will eventually
# follow the `SHUTDOWN` event.
#
-# Since: 0.12
-#
# .. qmp-example::
#
# <- { "event": "SHUTDOWN",
# "data": { "guest": true, "reason": "guest-shutdown" },
# "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
+#
+# Since: 0.12
##
{ 'event': 'SHUTDOWN', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } }
@@ -166,12 +168,14 @@
# Emitted when the virtual machine is powered down through the power
# control system, such as via ACPI.
#
-# Since: 0.12
+# Details:
#
# .. qmp-example::
#
# <- { "event": "POWERDOWN",
# "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
+#
+# Since: 0.12
##
{ 'event': 'POWERDOWN' }
@@ -187,13 +191,13 @@
#
# @reason: The `ShutdownCause` of the `RESET`. (since 4.0)
#
-# Since: 0.12
-#
# .. qmp-example::
#
# <- { "event": "RESET",
# "data": { "guest": false, "reason": "guest-reset" },
# "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
+#
+# Since: 0.12
##
{ 'event': 'RESET', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } }
@@ -202,12 +206,14 @@
#
# Emitted when the virtual machine is stopped
#
-# Since: 0.12
+# Details:
#
# .. qmp-example::
#
# <- { "event": "STOP",
# "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
+#
+# Since: 0.12
##
{ 'event': 'STOP' }
@@ -216,12 +222,14 @@
#
# Emitted when the virtual machine resumes execution
#
-# Since: 0.12
+# Details:
#
# .. qmp-example::
#
# <- { "event": "RESUME",
# "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
+#
+# Since: 0.12
##
{ 'event': 'RESUME' }
@@ -231,12 +239,14 @@
# Emitted when guest enters a hardware suspension state, for example,
# S3 state, which is sometimes called standby state
#
-# Since: 1.1
+# Details:
#
# .. qmp-example::
#
# <- { "event": "SUSPEND",
# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
+#
+# Since: 1.1
##
{ 'event': 'SUSPEND' }
@@ -247,15 +257,17 @@
# saved on disk, for example, S4 state, which is sometimes called
# hibernate state
#
+# Details:
+#
# .. note:: QEMU shuts down (similar to event `SHUTDOWN`) when
# entering this state.
#
-# Since: 1.2
-#
# .. qmp-example::
#
# <- { "event": "SUSPEND_DISK",
# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
+#
+# Since: 1.2
##
{ 'event': 'SUSPEND_DISK' }
@@ -265,12 +277,14 @@
# Emitted when the guest has woken up from suspend state and is
# running
#
-# Since: 1.1
+# Details:
#
# .. qmp-example::
#
# <- { "event": "WAKEUP",
# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
+#
+# Since: 1.1
##
{ 'event': 'WAKEUP' }
@@ -287,13 +301,13 @@
#
# .. note:: This event is rate-limited.
#
-# Since: 0.13
-#
# .. qmp-example::
#
# <- { "event": "WATCHDOG",
# "data": { "action": "reset" },
# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
+#
+# Since: 0.13
##
{ 'event': 'WATCHDOG',
'data': { 'action': 'WatchdogAction' } }
@@ -380,13 +394,13 @@
#
# @action: `WatchdogAction` action taken when watchdog timer expires.
#
-# Since: 2.11
-#
# .. qmp-example::
#
# -> { "execute": "watchdog-set-action",
# "arguments": { "action": "inject-nmi" } }
# <- { "return": {} }
+#
+# Since: 2.11
##
{ 'command': 'watchdog-set-action', 'data' : {'action': 'WatchdogAction'} }
@@ -405,8 +419,6 @@
# @watchdog: `WatchdogAction` action taken when watchdog timer
# expires.
#
-# Since: 6.0
-#
# .. qmp-example::
#
# -> { "execute": "set-action",
@@ -415,6 +427,8 @@
# "panic": "pause",
# "watchdog": "inject-nmi" } }
# <- { "return": {} }
+#
+# Since: 6.0
##
{ 'command': 'set-action',
'data': { '*reboot': 'RebootAction',
@@ -432,13 +446,13 @@
#
# @info: information about a panic (since 2.9)
#
-# Since: 1.5
-#
# .. qmp-example::
#
# <- { "event": "GUEST_PANICKED",
# "data": { "action": "pause" },
# "timestamp": { "seconds": 1648245231, "microseconds": 900001 } }
+#
+# Since: 1.5
##
{ 'event': 'GUEST_PANICKED',
'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } }
@@ -452,13 +466,13 @@
#
# @info: information about a panic
#
-# Since: 5.0
-#
# .. qmp-example::
#
# <- { "event": "GUEST_CRASHLOADED",
# "data": { "action": "run" },
# "timestamp": { "seconds": 1648245259, "microseconds": 893771 } }
+#
+# Since: 5.0
##
{ 'event': 'GUEST_CRASHLOADED',
'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } }
@@ -468,12 +482,14 @@
#
# Emitted when guest submits a shutdown request via pvpanic interface
#
-# Since: 9.1
+# Details:
#
# .. qmp-example::
#
# <- { "event": "GUEST_PVSHUTDOWN",
# "timestamp": { "seconds": 1648245259, "microseconds": 893771 } }
+#
+# Since: 9.1
##
{ 'event': 'GUEST_PVSHUTDOWN' }
@@ -655,8 +671,6 @@
#
# @flags: flags for `MemoryFailureAction`.
#
-# Since: 5.2
-#
# .. qmp-example::
#
# <- { "event": "MEMORY_FAILURE",
@@ -665,6 +679,8 @@
# "flags": { "action-required": false,
# "recursive": false } },
# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
+#
+# Since: 5.2
##
{ 'event': 'MEMORY_FAILURE',
'data': { 'recipient': 'MemoryFailureRecipient',
diff --git a/qapi/tpm.json b/qapi/tpm.json
index 3f2850a5733..03c624e1ab8 100644
--- a/qapi/tpm.json
+++ b/qapi/tpm.json
@@ -29,12 +29,14 @@
#
# Return a list of supported TPM models
#
-# Since: 1.5
+# Details:
#
# .. qmp-example::
#
# -> { "execute": "query-tpm-models" }
# <- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] }
+#
+# Since: 1.5
##
{ 'command': 'query-tpm-models', 'returns': ['TpmModel'],
'if': 'CONFIG_TPM' }
@@ -58,12 +60,14 @@
#
# Return a list of supported TPM types
#
-# Since: 1.5
+# Details:
#
# .. qmp-example::
#
# -> { "execute": "query-tpm-types" }
# <- { "return": [ "passthrough", "emulator" ] }
+#
+# Since: 1.5
##
{ 'command': 'query-tpm-types', 'returns': ['TpmType'],
'if': 'CONFIG_TPM' }
@@ -164,7 +168,7 @@
#
# Return information about the TPM device
#
-# Since: 1.5
+# Details:
#
# .. qmp-example::
#
@@ -183,6 +187,8 @@
# }
# ]
# }
+#
+# Since: 1.5
##
{ 'command': 'query-tpm', 'returns': ['TPMInfo'],
'if': 'CONFIG_TPM' }
diff --git a/qapi/trace.json b/qapi/trace.json
index de369dae6b5..63685b3d5ec 100644
--- a/qapi/trace.json
+++ b/qapi/trace.json
@@ -51,13 +51,13 @@
#
# Returns: a list of info for the matching events
#
-# Since: 2.2
-#
# .. qmp-example::
#
# -> { "execute": "trace-event-get-state",
# "arguments": { "name": "qemu_memalign" } }
# <- { "return": [ { "name": "qemu_memalign", "state": "disabled", "vcpu": false } ] }
+#
+# Since: 2.2
##
{ 'command': 'trace-event-get-state',
'data': {'name': 'str' },
@@ -74,13 +74,13 @@
#
# @ignore-unavailable: Do not match unavailable events with @name.
#
-# Since: 2.2
-#
# .. qmp-example::
#
# -> { "execute": "trace-event-set-state",
# "arguments": { "name": "qemu_memalign", "enable": true } }
# <- { "return": {} }
+#
+# Since: 2.2
##
{ 'command': 'trace-event-set-state',
'data': {'name': 'str', 'enable': 'bool', '*ignore-unavailable': 'bool' } }
diff --git a/qapi/transaction.json b/qapi/transaction.json
index 4b4eb09bf38..1e6b5d37980 100644
--- a/qapi/transaction.json
+++ b/qapi/transaction.json
@@ -244,8 +244,6 @@
# in an error condition, and subsequent actions will not have been
# attempted.
#
-# Since: 1.1
-#
# .. qmp-example::
#
# -> { "execute": "transaction",
@@ -266,6 +264,8 @@
# "device": "ide-hd2",
# "name": "snapshot0" } } ] } }
# <- { "return": {} }
+#
+# Since: 1.1
##
{ 'command': 'transaction',
'data': { 'actions': [ 'TransactionAction' ],
diff --git a/qapi/ui.json b/qapi/ui.json
index e3da77632a8..535e329e77c 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -83,13 +83,13 @@
# Errors:
# - If Spice is not enabled, DeviceNotFound
#
-# Since: 0.14
-#
# .. qmp-example::
#
# -> { "execute": "set_password", "arguments": { "protocol": "vnc",
# "password": "secret" } }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'set_password', 'boxed': true, 'data': 'SetPasswordOptions' }
@@ -145,13 +145,13 @@
# - If @protocol is 'spice' and Spice is not active,
# DeviceNotFound
#
-# Since: 0.14
-#
# .. qmp-example::
#
# -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
# "time": "+60" } }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'expire_password', 'boxed': true, 'data': 'ExpirePasswordOptions' }
@@ -187,13 +187,13 @@
#
# @format: image format for `screendump`. (default: ppm) (Since 7.1)
#
-# Since: 0.14
-#
# .. qmp-example::
#
# -> { "execute": "screendump",
# "arguments": { "filename": "/tmp/image" } }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'screendump',
'data': {'filename': 'str', '*device': 'str', '*head': 'int',
@@ -328,7 +328,7 @@
#
# Return information about the current SPICE server
#
-# Since: 0.14
+# Details:
#
# .. qmp-example::
#
@@ -364,6 +364,8 @@
# ]
# }
# }
+#
+# Since: 0.14
##
{ 'command': 'query-spice', 'returns': 'SpiceInfo',
'if': 'CONFIG_SPICE' }
@@ -377,8 +379,6 @@
#
# @client: client information
#
-# Since: 0.14
-#
# .. qmp-example::
#
# <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
@@ -387,6 +387,8 @@
# "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
# "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
# }}
+#
+# Since: 0.14
##
{ 'event': 'SPICE_CONNECTED',
'data': { 'server': 'SpiceBasicInfo',
@@ -403,8 +405,6 @@
#
# @client: client information
#
-# Since: 0.14
-#
# .. qmp-example::
#
# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
@@ -415,6 +415,8 @@
# "connection-id": 1804289383, "host": "127.0.0.1",
# "channel-id": 0, "tls": true}
# }}
+#
+# Since: 0.14
##
{ 'event': 'SPICE_INITIALIZED',
'data': { 'server': 'SpiceServerInfo',
@@ -430,8 +432,6 @@
#
# @client: client information
#
-# Since: 0.14
-#
# .. qmp-example::
#
# <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
@@ -440,6 +440,8 @@
# "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
# "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
# }}
+#
+# Since: 0.14
##
{ 'event': 'SPICE_DISCONNECTED',
'data': { 'server': 'SpiceBasicInfo',
@@ -451,12 +453,14 @@
#
# Emitted when SPICE migration has completed
#
-# Since: 1.3
+# Details:
#
# .. qmp-example::
#
# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
# "event": "SPICE_MIGRATE_COMPLETED" }
+#
+# Since: 1.3
##
{ 'event': 'SPICE_MIGRATE_COMPLETED',
'if': 'CONFIG_SPICE' }
@@ -658,7 +662,7 @@
#
# Return information about the current VNC server
#
-# Since: 0.14
+# Details:
#
# .. qmp-example::
#
@@ -679,6 +683,8 @@
# ]
# }
# }
+#
+# Since: 0.14
##
{ 'command': 'query-vnc', 'returns': 'VncInfo',
'if': 'CONFIG_VNC' }
@@ -700,11 +706,11 @@
#
# @password: the new password to use with VNC authentication
#
-# Since: 1.1
-#
# .. note:: An empty password in this command will set the password to
# the empty string. Existing clients are unaffected by executing
# this command.
+#
+# Since: 1.1
##
{ 'command': 'change-vnc-password',
'data': { 'password': 'str' },
@@ -722,8 +728,6 @@
# .. note:: This event is emitted before any authentication takes
# place, thus the authentication ID is not provided.
#
-# Since: 0.13
-#
# .. qmp-example::
#
# <- { "event": "VNC_CONNECTED",
@@ -733,6 +737,8 @@
# "client": { "family": "ipv4", "service": "58425",
# "host": "127.0.0.1", "websocket": false } },
# "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
+#
+# Since: 0.13
##
{ 'event': 'VNC_CONNECTED',
'data': { 'server': 'VncServerInfo',
@@ -749,8 +755,6 @@
#
# @client: client information
#
-# Since: 0.13
-#
# .. qmp-example::
#
# <- { "event": "VNC_INITIALIZED",
@@ -760,6 +764,8 @@
# "client": { "family": "ipv4", "service": "46089", "websocket": false,
# "host": "127.0.0.1", "sasl_username": "luiz" } },
# "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
+#
+# Since: 0.13
##
{ 'event': 'VNC_INITIALIZED',
'data': { 'server': 'VncServerInfo',
@@ -775,8 +781,6 @@
#
# @client: client information
#
-# Since: 0.13
-#
# .. qmp-example::
#
# <- { "event": "VNC_DISCONNECTED",
@@ -786,6 +790,8 @@
# "client": { "family": "ipv4", "service": "58425", "websocket": false,
# "host": "127.0.0.1", "sasl_username": "luiz" } },
# "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
+#
+# Since: 0.13
##
{ 'event': 'VNC_DISCONNECTED',
'data': { 'server': 'VncServerInfo',
@@ -825,8 +831,6 @@
#
# Returns: a list of info for each device
#
-# Since: 0.14
-#
# .. qmp-example::
#
# -> { "execute": "query-mice" }
@@ -845,6 +849,8 @@
# }
# ]
# }
+#
+# Since: 0.14
##
{ 'command': 'query-mice', 'returns': ['MouseInfo'] }
@@ -1035,8 +1041,6 @@
# Errors:
# - If key is unknown or redundant, GenericError
#
-# Since: 1.3
-#
# .. qmp-example::
#
# -> { "execute": "send-key",
@@ -1044,6 +1048,8 @@
# { "type": "qcode", "data": "alt" },
# { "type": "qcode", "data": "delete" } ] } }
# <- { "return": {} }
+#
+# Since: 1.3
##
{ 'command': 'send-key',
'data': { 'keys': ['KeyValue'], '*hold-time': 'int' } }
@@ -1265,8 +1271,6 @@
#
# @events: List of `InputEvent` union.
#
-# Since: 2.6
-#
# .. note:: The consoles are visible in the qom tree, under
# ``/backend/console[$index]``. They have a device link and head
# property, so it is possible to map which console belongs to which
@@ -1308,6 +1312,8 @@
# { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
# { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
# <- { "return": {} }
+#
+# Since: 2.6
##
{ 'command': 'input-send-event',
'data': { '*device': 'str',
@@ -1620,13 +1626,15 @@
#
# Reload display configuration.
#
-# Since: 6.0
+# Details:
#
# .. qmp-example::
#
# -> { "execute": "display-reload",
# "arguments": { "type": "vnc", "tls-certs": true } }
# <- { "return": {} }
+#
+# Since: 6.0
##
{ 'command': 'display-reload',
'data': 'DisplayReloadOptions',
@@ -1677,7 +1685,7 @@
#
# Update display configuration.
#
-# Since: 7.1
+# Details:
#
# .. qmp-example::
#
@@ -1686,6 +1694,8 @@
# [ { "type": "inet", "host": "0.0.0.0",
# "port": "5901" } ] } }
# <- { "return": {} }
+#
+# Since: 7.1
##
{ 'command': 'display-update',
'data': 'DisplayUpdateOptions',
@@ -1708,8 +1718,6 @@
#
# @cert-subject: server certificate subject
#
-# Since: 0.14
-#
# .. qmp-example::
#
# -> { "execute": "client_migrate_info",
@@ -1717,6 +1725,8 @@
# "hostname": "virt42.lab.kraxel.org",
# "port": 1234 } }
# <- { "return": {} }
+#
+# Since: 0.14
##
{ 'command': 'client_migrate_info',
'data': { 'protocol': 'str', 'hostname': 'str', '*port': 'int',
diff --git a/qapi/vfio.json b/qapi/vfio.json
index 17b60468712..630e2595c82 100644
--- a/qapi/vfio.json
+++ b/qapi/vfio.json
@@ -58,8 +58,6 @@
#
# @device-state: The new changed device migration state.
#
-# Since: 9.1
-#
# .. qmp-example::
#
# <- { "timestamp": { "seconds": 1713771323, "microseconds": 212268 },
@@ -68,6 +66,8 @@
# "device-id": "vfio_dev1",
# "qom-path": "/machine/peripheral/vfio_dev1",
# "device-state": "stop" } }
+#
+# Since: 9.1
##
{ 'event': 'VFIO_MIGRATION',
'data': {
diff --git a/qapi/virtio.json b/qapi/virtio.json
index 447fc182625..ae795e1e852 100644
--- a/qapi/virtio.json
+++ b/qapi/virtio.json
@@ -34,8 +34,6 @@
#
# @unstable: This command is meant for debugging.
#
-# Since: 7.2
-#
# .. qmp-example::
#
# -> { "execute": "x-query-virtio" }
@@ -62,6 +60,8 @@
# }
# ]
# }
+#
+# Since: 7.2
##
{ 'command': 'x-query-virtio',
'returns': [ 'VirtioInfo' ],
@@ -203,8 +203,6 @@
#
# @unstable: This command is meant for debugging.
#
-# Since: 7.2
-#
# .. qmp-example::
# :annotated:
#
@@ -437,6 +435,8 @@
# "use-started": true
# }
# }
+#
+# Since: 7.2
##
{ 'command': 'x-query-virtio-status',
'data': { 'path': 'str' },
@@ -579,8 +579,6 @@
# shadow_avail_idx will not be displayed in the case where the
# selected VirtIODevice has a running vhost device.
#
-# Since: 7.2
-#
# .. qmp-example::
# :annotated:
#
@@ -635,6 +633,8 @@
# "vring-num": 128
# }
# }
+#
+# Since: 7.2
##
{ 'command': 'x-query-virtio-queue-status',
'data': { 'path': 'str', 'queue': 'uint16' },
@@ -707,8 +707,6 @@
#
# @unstable: This command is meant for debugging.
#
-# Since: 7.2
-#
# .. qmp-example::
# :title: Get vhost_virtqueue status for vhost-crypto
#
@@ -756,6 +754,8 @@
# "kick": 0
# }
# }
+#
+# Since: 7.2
##
{ 'command': 'x-query-virtio-vhost-queue-status',
'data': { 'path': 'str', 'queue': 'uint16' },
@@ -854,8 +854,6 @@
#
# @unstable: This command is meant for debugging.
#
-# Since: 7.2
-#
# .. qmp-example::
# :title: Introspect on virtio-net's VirtQueue 0 at index 5
#
@@ -943,6 +941,8 @@
# }
# }
# }
+#
+# Since: 7.2
##
{ 'command': 'x-query-virtio-queue-element',
'data': { 'path': 'str', 'queue': 'uint16', '*index': 'uint16' },
--
2.53.0
^ permalink raw reply related [flat|nested] 12+ messages in thread