diff options
| -rw-r--r-- | docs/devel/qapi-code-gen.rst | 62 | ||||
| -rw-r--r-- | docs/interop/firmware.json | 6 | ||||
| -rw-r--r-- | qapi/block-core.json | 82 | ||||
| -rw-r--r-- | qapi/block-export.json | 7 | ||||
| -rw-r--r-- | qapi/block.json | 2 | ||||
| -rw-r--r-- | qapi/char.json | 4 | ||||
| -rw-r--r-- | qapi/control.json | 2 | ||||
| -rw-r--r-- | qapi/cryptodev.json | 4 | ||||
| -rw-r--r-- | qapi/job.json | 4 | ||||
| -rw-r--r-- | qapi/machine-target.json | 2 | ||||
| -rw-r--r-- | qapi/machine.json | 30 | ||||
| -rw-r--r-- | qapi/migration.json | 37 | ||||
| -rw-r--r-- | qapi/misc.json | 13 | ||||
| -rw-r--r-- | qapi/net.json | 27 | ||||
| -rw-r--r-- | qapi/qapi-schema.json | 24 | ||||
| -rw-r--r-- | qapi/qdev.json | 2 | ||||
| -rw-r--r-- | qapi/qom.json | 4 | ||||
| -rw-r--r-- | qapi/rdma.json | 2 | ||||
| -rw-r--r-- | qapi/replay.json | 3 | ||||
| -rw-r--r-- | qapi/run-state.json | 11 | ||||
| -rw-r--r-- | qapi/stats.json | 3 | ||||
| -rw-r--r-- | qapi/tpm.json | 3 | ||||
| -rw-r--r-- | qapi/trace.json | 1 | ||||
| -rw-r--r-- | qapi/ui.json | 12 | ||||
| -rw-r--r-- | qapi/yank.json | 21 | ||||
| -rw-r--r-- | qga/qapi-schema.json | 10 | ||||
| -rw-r--r-- | storage-daemon/qapi/qapi-schema.json | 20 |
27 files changed, 230 insertions, 168 deletions
diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 879a649e8c..af1986f33e 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -924,14 +924,17 @@ first character of the first line. The usual ****strong****, *\*emphasized\** and ````literal```` markup should be used. If you need a single literal ``*``, you will need to -backslash-escape it. As an extension beyond the usual rST syntax, you -can also use ``@foo`` to reference a name in the schema; this is rendered -the same way as ````foo````. +backslash-escape it. + +Use ``@foo`` to reference a name in the schema. This is an rST +extension. It is rendered the same way as ````foo````, but carries +additional meaning. Example:: ## # Some text foo with **bold** and *emphasis* + # # 1. with a list # 2. like that # @@ -1057,6 +1060,59 @@ For example:: 'returns': ['BlockStats'] } +Markup pitfalls +~~~~~~~~~~~~~~~ + +A blank line is required between list items and paragraphs. Without +it, the list may not be recognized, resulting in garbled output. Good +example:: + + # An event's state is modified if: + # + # - its name matches the @name pattern, and + # - if @vcpu is given, the event has the "vcpu" property. + +Without the blank line this would be a single paragraph. + +Indentation matters. Bad example:: + + # @none: None (no memory side cache in this proximity domain, + # or cache associativity unknown) + +The description is parsed as a definition list with term "None (no +memory side cache in this proximity domain," and definition "or cache +associativity unknown)". + +Section tags are case-sensitive and end with a colon. Good example:: + + # Since: 7.1 + +Bad examples (all ordinary paragraphs):: + + # since: 7.1 + + # Since 7.1 + + # Since : 7.1 + +Likewise, member descriptions require a colon. Good example:: + + # @interface-id: Interface ID + +Bad examples (all ordinary paragraphs):: + + # @interface-id Interface ID + + # @interface-id : Interface ID + +Undocumented members are not flagged, yet. Instead, the generated +documentation describes them as "Not documented". Think twice before +adding more undocumented members. + +When you change documentation comments, please check the generated +documentation comes out as intended! + + Client JSON Protocol introspection ================================== diff --git a/docs/interop/firmware.json b/docs/interop/firmware.json index 56814f02b3..cc8f869186 100644 --- a/docs/interop/firmware.json +++ b/docs/interop/firmware.json @@ -258,7 +258,7 @@ # # @mode: Describes how the firmware build handles code versus variable # storage. If not present, it must be treated as if it was -# configured with value ``split``. Since: 7.0.0 +# configured with value @split. Since: 7.0.0 # # @executable: Identifies the firmware executable. The @mode # indicates whether there will be an associated @@ -267,13 +267,13 @@ # -drive if=none,id=pflash0,readonly=on,file=@executable.@filename,format=@executable.@format # -machine pflash0=pflash0 # or equivalent -blockdev instead of -drive. When -# @mode is ``combined`` the executable must be +# @mode is @combined the executable must be # cloned before use and configured with readonly=off. # With QEMU versions older than 4.0, you have to use # -drive if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format # # @nvram-template: Identifies the NVRAM template compatible with -# @executable, when @mode is set to ``split``, +# @executable, when @mode is set to @split, # otherwise it should not be present. # Management software instantiates an # individual copy -- a specific NVRAM file -- from diff --git a/qapi/block-core.json b/qapi/block-core.json index c05ad0c07e..b57978957f 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -488,41 +488,41 @@ # # @image: the info of image used (since: 1.6) # -# @bps_max: total throughput limit during bursts, -# in bytes (Since 1.7) +# @bps_max: total throughput limit during bursts, in bytes +# (Since 1.7) # -# @bps_rd_max: read throughput limit during bursts, -# in bytes (Since 1.7) +# @bps_rd_max: read throughput limit during bursts, in bytes +# (Since 1.7) # -# @bps_wr_max: write throughput limit during bursts, -# in bytes (Since 1.7) +# @bps_wr_max: write throughput limit during bursts, in bytes +# (Since 1.7) # -# @iops_max: total I/O operations per second during bursts, -# in bytes (Since 1.7) +# @iops_max: total I/O operations per second during bursts, in bytes +# (Since 1.7) # -# @iops_rd_max: read I/O operations per second during bursts, -# in bytes (Since 1.7) +# @iops_rd_max: read I/O operations per second during bursts, in bytes +# (Since 1.7) # -# @iops_wr_max: write I/O operations per second during bursts, -# in bytes (Since 1.7) +# @iops_wr_max: write I/O operations per second during bursts, in +# bytes (Since 1.7) # -# @bps_max_length: maximum length of the @bps_max burst -# period, in seconds. (Since 2.6) +# @bps_max_length: maximum length of the @bps_max burst period, in +# seconds. (Since 2.6) # -# @bps_rd_max_length: maximum length of the @bps_rd_max -# burst period, in seconds. (Since 2.6) +# @bps_rd_max_length: maximum length of the @bps_rd_max burst period, +# in seconds. (Since 2.6) # -# @bps_wr_max_length: maximum length of the @bps_wr_max -# burst period, in seconds. (Since 2.6) +# @bps_wr_max_length: maximum length of the @bps_wr_max burst period, +# in seconds. (Since 2.6) # -# @iops_max_length: maximum length of the @iops burst -# period, in seconds. (Since 2.6) +# @iops_max_length: maximum length of the @iops burst period, in +# seconds. (Since 2.6) # -# @iops_rd_max_length: maximum length of the @iops_rd_max -# burst period, in seconds. (Since 2.6) +# @iops_rd_max_length: maximum length of the @iops_rd_max burst +# period, in seconds. (Since 2.6) # -# @iops_wr_max_length: maximum length of the @iops_wr_max -# burst period, in seconds. (Since 2.6) +# @iops_wr_max_length: maximum length of the @iops_wr_max burst +# period, in seconds. (Since 2.6) # # @iops_size: an I/O size in bytes (Since 1.7) # @@ -582,11 +582,11 @@ # @granularity: granularity of the dirty bitmap in bytes (since 1.4) # # @recording: true if the bitmap is recording new writes from the guest. -# Replaces ``active`` and ``disabled`` statuses. (since 4.0) +# (since 4.0) # # @busy: true if the bitmap is in-use by some operation (NBD or jobs) # and cannot be modified via QMP or used by another operation. -# Replaces ``locked`` and ``frozen`` statuses. (since 4.0) +# (since 4.0) # # @persistent: true if the bitmap was stored on disk, is scheduled to be stored # on disk, or both. (since 4.0) @@ -948,7 +948,7 @@ # by the device (Since 4.2) # # @invalid_rd_operations: The number of invalid read operations -# performed by the device (Since 2.5) +# performed by the device (Since 2.5) # # @invalid_wr_operations: The number of invalid write operations # performed by the device (Since 2.5) @@ -1318,10 +1318,10 @@ # value is monotonically increasing. # # @busy: false if the job is known to be in a quiescent state, with -# no pending I/O. Since 1.3. +# no pending I/O. (Since 1.3) # # @paused: whether the job is paused or, if @busy is true, will -# pause itself as soon as possible. Since 1.3. +# pause itself as soon as possible. (Since 1.3) # # @speed: the rate limit, bytes per second # @@ -2741,7 +2741,7 @@ # # @on-error: the action to take on an error (default report). # 'stop' and 'enospc' can only be used if the block device -# supports io-status (see BlockInfo). Since 1.3. +# supports io-status (see BlockInfo). (Since 1.3) # # @filter-node-name: the node name that should be assigned to the # filter driver that the stream job inserts into the graph @@ -3735,7 +3735,7 @@ # Driver specific block device options for Quorum # # @blkverify: true if the driver must print content mismatch -# set to false by default +# set to false by default # # @children: the children block devices to use # @@ -4574,9 +4574,8 @@ # # Since: 2.9 # -# Example: +# Examples: # -# 1. # -> { "execute": "blockdev-add", # "arguments": { # "driver": "qcow2", @@ -4589,7 +4588,6 @@ # } # <- { "return": {} } # -# 2. # -> { "execute": "blockdev-add", # "arguments": { # "driver": "qcow2", @@ -5157,7 +5155,7 @@ # Driver specific image amend options for qcow2. # For now, only encryption options can be amended # -# @encrypt Encryption options to be amended +# @encrypt: Encryption options to be amended # # Since: 5.1 ## @@ -5596,7 +5594,7 @@ # # Since: 2.7 # -# Example: +# Examples: # # 1. Add a new node to a quorum # -> { "execute": "blockdev-add", @@ -5646,7 +5644,7 @@ # # Since: 2.12 # -# Example: +# Examples: # # 1. Move a node into an IOThread # -> { "execute": "x-blockdev-set-iothread", @@ -5731,18 +5729,18 @@ # # Since: 2.0 # -# Example: +# Examples: # # 1. Read operation # -# { "event": "QUORUM_REPORT_BAD", +# <- { "event": "QUORUM_REPORT_BAD", # "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5, # "type": "read" }, # "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } # # 2. Flush operation # -# { "event": "QUORUM_REPORT_BAD", +# <- { "event": "QUORUM_REPORT_BAD", # "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120, # "type": "flush", "error": "Broken pipe" }, # "timestamp": { "seconds": 1456406829, "microseconds": 291763 } } @@ -5784,7 +5782,7 @@ # - If any snapshot matching @name exists, or @name is empty, # GenericError # - If the format of the image used does not support it, -# BlockFormatFeatureNotSupported +# GenericError # # Since: 1.7 # @@ -5820,7 +5818,7 @@ # - If @device is not a valid block device, GenericError # - If snapshot not found, GenericError # - If the format of the image used does not support it, -# BlockFormatFeatureNotSupported +# GenericError # - If @id and @name are both not specified, GenericError # # Since: 1.7 diff --git a/qapi/block-export.json b/qapi/block-export.json index 4627bbc4e6..3be3de357f 100644 --- a/qapi/block-export.json +++ b/qapi/block-export.json @@ -275,9 +275,10 @@ # @deprecated: This command is deprecated. Use @block-export-del instead. # # Returns: error if -# - the server is not running -# - export is not found -# - mode is 'safe' and there are existing connections +# +# - the server is not running +# - export is not found +# - mode is 'safe' and there are existing connections # # Since: 2.12 ## diff --git a/qapi/block.json b/qapi/block.json index 5fe068f903..94339a1761 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -457,7 +457,7 @@ # # Since: 1.1 # -# Example: +# Examples: # # -> { "execute": "block_set_io_throttle", # "arguments": { "id": "virtio-blk-pci0/virtio-backend", diff --git a/qapi/char.json b/qapi/char.json index 923dc5056d..c9431dd0a7 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -637,7 +637,7 @@ # # Since: 1.4 # -# Example: +# Examples: # # -> { "execute" : "chardev-add", # "arguments" : { "id" : "foo", @@ -673,7 +673,7 @@ # # Since: 2.10 # -# Example: +# Examples: # # -> { "execute" : "chardev-change", # "arguments" : { "id" : "baz", diff --git a/qapi/control.json b/qapi/control.json index afca2043af..f83499280a 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -195,7 +195,7 @@ # @id: Name of the monitor # # @mode: Selects the monitor mode (default: readline in the system -# emulator, control in qemu-storage-daemon) +# emulator, control in qemu-storage-daemon) # # @pretty: Enables pretty printing (QMP only) # diff --git a/qapi/cryptodev.json b/qapi/cryptodev.json index f33f96a692..cf960ea81f 100644 --- a/qapi/cryptodev.json +++ b/qapi/cryptodev.json @@ -5,6 +5,10 @@ # See the COPYING file in the top-level directory. ## +# = Cryptography devices +## + +## # @QCryptodevBackendAlgType: # # The supported algorithm types of a crypto device. diff --git a/qapi/job.json b/qapi/job.json index d5f84e9615..9e29a796c5 100644 --- a/qapi/job.json +++ b/qapi/job.json @@ -2,7 +2,7 @@ # vim: filetype=python ## -# == Background jobs +# = Background jobs ## ## @@ -148,7 +148,7 @@ # This command returns immediately after resuming a paused job. Resuming an # already running job is an error. # -# @id : The job identifier. +# @id: The job identifier. # # Since: 3.0 ## diff --git a/qapi/machine-target.json b/qapi/machine-target.json index 2e267fa458..b94fbdb65e 100644 --- a/qapi/machine-target.json +++ b/qapi/machine-target.json @@ -331,7 +331,7 @@ # # Return a list of supported virtual CPU definitions # -# Returns: a list of CpuDefInfo +# Returns: a list of CpuDefinitionInfo # # Since: 1.2 ## diff --git a/qapi/machine.json b/qapi/machine.json index 604b686e59..fcd69965e5 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -457,7 +457,7 @@ # @nodeid: NUMA node ID (increase by 1 from 0 if omitted) # # @cpus: VCPUs belonging to this node (assign VCPUS round-robin -# if omitted) +# if omitted) # # @mem: memory size of this node; mutually exclusive with @memdev. # Equally divide total memory among nodes if both @mem and @memdev are @@ -517,7 +517,7 @@ # @targets: Target root bridge IDs from -device ...,id=<ID> for each root # bridge. # -# Since 7.1 +# Since: 7.1 ## { 'struct': 'CXLFixedMemoryWindowOptions', 'data': { @@ -532,7 +532,7 @@ # # @cxl-fmw: List of CXLFixedMemoryWindowOptions # -# Since 7.1 +# Since: 7.1 ## { 'struct' : 'CXLFMWProperties', 'data': { 'cxl-fmw': ['CXLFixedMemoryWindowOptions'] } @@ -690,7 +690,7 @@ # 5.2.27.5: Table 5-147 of ACPI 6.3 spec. # # @none: None (no memory side cache in this proximity domain, -# or cache associativity unknown) +# or cache associativity unknown) # # @direct: Direct Mapped # @@ -954,7 +954,7 @@ # # Since: 2.7 # -# Example: +# Examples: # # For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8: # @@ -1029,7 +1029,7 @@ # # Returns: - Nothing on success # - If the balloon driver is enabled but not functional because the KVM -# kernel module cannot support it, KvmMissingCap +# kernel module cannot support it, KVMMissingCap # - If no balloon device is present, DeviceNotActive # # Notes: This command just issues a request to the guest. When it returns, @@ -1067,7 +1067,7 @@ # # Returns: - @BalloonInfo on success # - If the balloon driver is enabled but not functional because the KVM -# kernel module cannot support it, KvmMissingCap +# kernel module cannot support it, KVMMissingCap # - If no balloon device is present, DeviceNotActive # # Since: 0.14 @@ -1260,6 +1260,14 @@ ## # @MemoryDeviceInfoKind: # +# @nvdimm: since 2.12 +# +# @virtio-pmem: since 4.1 +# +# @virtio-mem: since 5.1 +# +# @sgx-epc: since 6.2. +# # Since: 2.1 ## { 'enum': 'MemoryDeviceInfoKind', @@ -1302,9 +1310,6 @@ # # Union containing information about a memory device # -# nvdimm is included since 2.12. virtio-pmem is included since 4.1. -# virtio-mem is included since 5.1. sgx-epc is included since 6.2. -# # Since: 2.1 ## { 'union': 'MemoryDeviceInfo', @@ -1677,8 +1682,9 @@ # Since: 7.2 # # Example: -# {"execute": "dumpdtb"} -# "arguments": { "filename": "fdt.dtb" } } +# -> { "execute": "dumpdtb" } +# "arguments": { "filename": "fdt.dtb" } } +# <- { "return": {} } # ## { 'command': 'dumpdtb', diff --git a/qapi/migration.json b/qapi/migration.json index 2c35b7b9cf..82000adce4 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -273,7 +273,7 @@ # # Since: 0.14 # -# Example: +# Examples: # # 1. Before the first migration # @@ -521,6 +521,7 @@ # # -> { "execute": "migrate-set-capabilities" , "arguments": # { "capabilities": [ { "capability": "xbzrle", "state": true } ] } } +# <- { "return": {} } # ## { 'command': 'migrate-set-capabilities', @@ -531,7 +532,7 @@ # # Returns information about the current migration capabilities status # -# Returns: @MigrationCapabilitiesStatus +# Returns: @MigrationCapabilityStatus # # Since: 1.2 # @@ -989,6 +990,7 @@ # # -> { "execute": "migrate-set-parameters" , # "arguments": { "compress-level": 1 } } +# <- { "return": {} } # ## { 'command': 'migrate-set-parameters', 'boxed': true, @@ -1251,8 +1253,8 @@ # # Example: # -# { "timestamp": {"seconds": 1449669631, "microseconds": 239225}, -# "event": "MIGRATION_PASS", "data": {"pass": 2} } +# <- { "timestamp": {"seconds": 1449669631, "microseconds": 239225}, +# "event": "MIGRATION_PASS", "data": {"pass": 2} } # ## { 'event': 'MIGRATION_PASS', @@ -1833,8 +1835,9 @@ # # Example: # -# {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, -# 'sample-pages': 512} } +# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, +# 'sample-pages': 512} } +# <- { "return": {} } # ## { 'command': 'calc-dirty-rate', 'data': {'calc-time': 'int64', @@ -1886,9 +1889,11 @@ # Since: 7.1 # # Example: -# {"execute": "set-vcpu-dirty-limit"} -# "arguments": { "dirty-rate": 200, -# "cpu-index": 1 } } +# +# -> {"execute": "set-vcpu-dirty-limit"} +# "arguments": { "dirty-rate": 200, +# "cpu-index": 1 } } +# <- { "return": {} } # ## { 'command': 'set-vcpu-dirty-limit', @@ -1909,8 +1914,10 @@ # Since: 7.1 # # Example: -# {"execute": "cancel-vcpu-dirty-limit"} -# "arguments": { "cpu-index": 1 } } +# +# -> {"execute": "cancel-vcpu-dirty-limit"}, +# "arguments": { "cpu-index": 1 } } +# <- { "return": {} } # ## { 'command': 'cancel-vcpu-dirty-limit', @@ -1924,7 +1931,11 @@ # Since: 7.1 # # Example: -# {"execute": "query-vcpu-dirty-limit"} +# +# -> {"execute": "query-vcpu-dirty-limit"} +# <- {"return": [ +# { "limit-rate": 60, "current-rate": 3, "cpu-index": 0}, +# { "limit-rate": 60, "current-rate": 3, "cpu-index": 1}]} # ## { 'command': 'query-vcpu-dirty-limit', @@ -1952,7 +1963,7 @@ # # data: migration thread name # -# returns: information about migration threads +# Returns: information about migration threads # # Since: 7.2 ## diff --git a/qapi/misc.json b/qapi/misc.json index 6ddd16ea28..4afaee7fe7 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -349,8 +349,8 @@ # @opaque: A free-form string that can be used to describe the fd. # # Returns: - @AddfdInfo on success -# - If file descriptor was not received, FdNotSupplied -# - If @fdset-id is a negative value, InvalidParameterValue +# - If file descriptor was not received, GenericError +# - If @fdset-id is a negative value, GenericError # # Notes: The list of fd sets is shared by all monitor connections. # @@ -379,7 +379,7 @@ # @fd: The file descriptor that is to be removed. # # Returns: - Nothing on success -# - If @fdset-id or @fd is not found, FdNotFound +# - If @fdset-id or @fd is not found, GenericError # # Since: 1.2 # @@ -580,10 +580,9 @@ # # Example: # -# <- { "event": "RTC_CHANGE", -# "data": { "offset": 78 }, -# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } -# +# <- { "event": "RTC_CHANGE", +# "data": { "offset": 78 }, +# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } ## { 'event': 'RTC_CHANGE', 'data': { 'offset': 'int', 'qom-path': 'str' } } diff --git a/qapi/net.json b/qapi/net.json index d6eb30008b..3606d9d27f 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -533,7 +533,7 @@ # Must be specified along with @start-address and @subnet-mask. # # @subnet-mask: The IPv4 subnet mask to use on the interface. Must -# be specified along with @start-address and @subnet-mask. +# be specified along with @start-address and @subnet-mask. # # @isolated: Enable isolation for this interface. Interface isolation # ensures that vmnet interface is not able to communicate @@ -641,14 +641,15 @@ # # Available netdev drivers. # -# Since: 2.7 +# @l2tpv3: since 2.1 +# @vhost-vdpa: since 5.1 +# @vmnet-host: since 7.1 +# @vmnet-shared: since 7.1 +# @vmnet-bridged: since 7.1 +# @stream: since 7.2 +# @dgram: since 7.2 # -# @vhost-vdpa since 5.1 -# @vmnet-host since 7.1 -# @vmnet-shared since 7.1 -# @vmnet-bridged since 7.1 -# @stream since 7.2 -# @dgram since 7.2 +# Since: 2.7 ## { 'enum': 'NetClientDriver', 'data': [ 'none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'stream', @@ -669,12 +670,6 @@ # # Since: 1.2 # -# 'l2tpv3' - since 2.1 -# 'vmnet-host' - since 7.1 -# 'vmnet-shared' - since 7.1 -# 'vmnet-bridged' - since 7.1 -# 'stream' since 7.2 -# 'dgram' since 7.2 ## { 'union': 'Netdev', 'base': { 'id': 'str', 'type': 'NetClientDriver' }, @@ -914,7 +909,7 @@ # # Since: 7.2 # -# Example: +# Examples: # # <- { "event": "NETDEV_STREAM_CONNECTED", # "data": { "netdev-id": "netdev0", @@ -922,8 +917,6 @@ # "host": "::1", "type": "inet" } }, # "timestamp": { "seconds": 1666269863, "microseconds": 311222 } } # -# or -# # <- { "event": "NETDEV_STREAM_CONNECTED", # "data": { "netdev-id": "netdev0", # "addr": { "path": "/tmp/qemu0", "type": "unix" } }, diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index 7c09af5cc8..bb7217da26 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -28,28 +28,6 @@ # # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for # detailed information on the Server command and response formats. -# -# = Stability Considerations -# -# The current QMP command set (described in this file) may be useful for a -# number of use cases, however it's limited and several commands have bad -# defined semantics, specially with regard to command completion. -# -# These problems are going to be solved incrementally in the next QEMU releases -# and we're going to establish a deprecation policy for badly defined commands. -# -# If you're planning to adopt QMP, please observe the following: -# -# 1. The deprecation policy will take effect and be documented soon, please -# check the documentation of each used command as soon as a new release of -# QEMU is available -# -# 2. DO NOT rely on anything which is not explicit documented -# -# 3. Errors, in special, are not documented. Applications should NOT check -# for specific errors classes or data (it's strongly recommended to only -# check for the "error" key) -# ## { 'include': 'pragma.json' } @@ -65,11 +43,11 @@ { 'include': 'sockets.json' } { 'include': 'run-state.json' } { 'include': 'crypto.json' } +{ 'include': 'job.json' } { 'include': 'block.json' } { 'include': 'block-export.json' } { 'include': 'char.json' } { 'include': 'dump.json' } -{ 'include': 'job.json' } { 'include': 'net.json' } { 'include': 'rdma.json' } { 'include': 'rocker.json' } diff --git a/qapi/qdev.json b/qapi/qdev.json index 2708fb4e99..f309facf8d 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -100,7 +100,7 @@ # # Since: 0.14 # -# Example: +# Examples: # # -> { "execute": "device_del", # "arguments": { "id": "net1" } } diff --git a/qapi/qom.json b/qapi/qom.json index a877b879b9..2a3891e3cb 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -103,7 +103,7 @@ # # Since: 1.2 # -# Example: +# Examples: # # 1. Use absolute path # @@ -637,7 +637,7 @@ # # @discard-data: if true, the file contents can be destroyed when QEMU exits, # to avoid unnecessarily flushing data to the backing file. Note -# that ``discard-data`` is only an optimization, and QEMU might +# that @discard-data is only an optimization, and QEMU might # not discard file contents if it aborts unexpectedly or is # terminated using SIGKILL. (default: false) # diff --git a/qapi/rdma.json b/qapi/rdma.json index a1d2175a8b..5b6b66afa4 100644 --- a/qapi/rdma.json +++ b/qapi/rdma.json @@ -17,7 +17,7 @@ # # @subnet-prefix: Subnet Prefix # -# @interface-id : Interface ID +# @interface-id: Interface ID # # Since: 4.0 # diff --git a/qapi/replay.json b/qapi/replay.json index 729470300d..fcbf10e237 100644 --- a/qapi/replay.json +++ b/qapi/replay.json @@ -81,6 +81,7 @@ # Example: # # -> { "execute": "replay-break", "arguments": { "icount": 220414 } } +# <- { "return": {} } # ## { 'command': 'replay-break', 'data': { 'icount': 'int' } } @@ -96,6 +97,7 @@ # Example: # # -> { "execute": "replay-delete-break" } +# <- { "return": {} } # ## { 'command': 'replay-delete-break' } @@ -117,5 +119,6 @@ # Example: # # -> { "execute": "replay-seek", "arguments": { "icount": 220414 } } +# <- { "return": {} } ## { 'command': 'replay-seek', 'data': { 'icount': 'int' } } diff --git a/qapi/run-state.json b/qapi/run-state.json index 419c188dd1..e5f5d31395 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -258,9 +258,8 @@ # # Example: # -# <- { "event": "SUSPEND_DISK", -# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } } -# +# <- { "event": "SUSPEND_DISK", +# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } } ## { 'event': 'SUSPEND_DISK' } @@ -468,7 +467,11 @@ # # @pause: system pauses # -# Since: 2.1 (poweroff since 2.8, run since 5.0) +# @poweroff: system powers off (since 2.8) +# +# @run: system continues to run (since 5.0) +# +# Since: 2.1 ## { 'enum': 'GuestPanicAction', 'data': [ 'pause', 'poweroff', 'run' ] } diff --git a/qapi/stats.json b/qapi/stats.json index 1f5d3c59ab..36d5f4dc94 100644 --- a/qapi/stats.json +++ b/qapi/stats.json @@ -69,7 +69,7 @@ # # @vcpu: statistics that apply to a single virtual CPU. # -# @cryptodev: statistics that apply to a crypto device. since 8.0 +# @cryptodev: statistics that apply to a crypto device (since 8.0) # # Since: 7.1 ## @@ -107,6 +107,7 @@ # The arguments to the query-stats command; specifies a target for which to # request statistics and optionally the required subset of information for # that target: +# # - which vCPUs to request statistics for # - which providers to request statistics from # - which named values to return within each provider diff --git a/qapi/tpm.json b/qapi/tpm.json index 4e2ea9756a..eac87d30b2 100644 --- a/qapi/tpm.json +++ b/qapi/tpm.json @@ -44,8 +44,7 @@ # An enumeration of TPM types # # @passthrough: TPM passthrough type -# @emulator: Software Emulator TPM type -# Since: 2.11 +# @emulator: Software Emulator TPM type (since 2.11) # # Since: 1.5 ## diff --git a/qapi/trace.json b/qapi/trace.json index 6c6982a587..f425d10764 100644 --- a/qapi/trace.json +++ b/qapi/trace.json @@ -87,6 +87,7 @@ # @vcpu: The vCPU to act upon (all by default; since 2.7). # # An event's state is modified if: +# # - its name matches the @name pattern, and # - if @vcpu is given, the event has the "vcpu" property. # diff --git a/qapi/ui.json b/qapi/ui.json index 7ddd27a932..b5650974fc 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -985,7 +985,7 @@ # to 100 # # Returns: - Nothing on success -# - If key is unknown or redundant, InvalidParameter +# - If key is unknown or redundant, GenericError # # Since: 1.3 # @@ -1153,7 +1153,7 @@ # so it is possible to map which console belongs to which device and # display. # -# Example: +# Examples: # # 1. Press left mouse button. # @@ -1207,13 +1207,13 @@ # window resizes (virtio-gpu) this will default to "on", # assuming the guest will resize the display to match # the window size then. Otherwise it defaults to "off". -# Since 3.1 +# (Since 3.1) # @show-tabs: Display the tab bar for switching between the various graphical # interfaces (e.g. VGA and virtual console character devices) # by default. -# Since 7.1 +# (Since 7.1) # @show-menubar: Display the main window menubar. Defaults to "on". -# Since 8.0 +# (Since 8.0) # # Since: 2.12 ## @@ -1247,7 +1247,7 @@ # available node on the host. # # @p2p: Whether to use peer-to-peer connections (accepted through -# ``add_client``). +# @add_client). # # @audiodev: Use the specified DBus audiodev to export audio. # diff --git a/qapi/yank.json b/qapi/yank.json index 167a775594..1639744ada 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -50,16 +50,17 @@ # hanging QEMU. # # Currently implemented yank instances: -# - nbd block device: -# Yanking it will shut down the connection to the nbd server without -# attempting to reconnect. -# - socket chardev: -# Yanking it will shut down the connected socket. -# - migration: -# Yanking it will shut down all migration connections. Unlike -# @migrate_cancel, it will not notify the migration process, so migration -# will go into @failed state, instead of @cancelled state. @yank should be -# used to recover from hangs. +# +# - nbd block device: +# Yanking it will shut down the connection to the nbd server without +# attempting to reconnect. +# - socket chardev: +# Yanking it will shut down the connected socket. +# - migration: +# Yanking it will shut down all migration connections. Unlike +# @migrate_cancel, it will not notify the migration process, so migration +# will go into @failed state, instead of @cancelled state. @yank should be +# used to recover from hangs. # # Since: 6.0 ## diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 796434ed34..6a20eeb297 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -420,7 +420,7 @@ ## # @guest-fsfreeze-status: # -# Get guest fsfreeze state. error state indicates +# Get guest fsfreeze state. # # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below) # @@ -722,7 +722,7 @@ # Get list of guest IP addresses, MAC addresses # and netmasks. # -# Returns: List of GuestNetworkInfo on success. +# Returns: List of GuestNetworkInterface on success. # # Since: 1.1 ## @@ -1553,11 +1553,11 @@ ## # @GuestDiskStatsInfo: # -# @name disk name +# @name: disk name # -# @major major device number of disk +# @major: major device number of disk # -# @minor minor device number of disk +# @minor: minor device number of disk ## { 'struct': 'GuestDiskStatsInfo', 'data': {'name': 'str', diff --git a/storage-daemon/qapi/qapi-schema.json b/storage-daemon/qapi/qapi-schema.json index 67749d1101..f10c949490 100644 --- a/storage-daemon/qapi/qapi-schema.json +++ b/storage-daemon/qapi/qapi-schema.json @@ -15,18 +15,26 @@ { 'include': '../../qapi/pragma.json' } +# Documentation generated with qapi-gen.py is in source order, with +# included sub-schemas inserted at the first include directive +# (subsequent include directives have no effect). To get a sane and +# stable order, it's best to include each sub-schema just once, or +# include it first right here. + +{ 'include': '../../qapi/common.json' } +{ 'include': '../../qapi/sockets.json' } +{ 'include': '../../qapi/crypto.json' } +{ 'include': '../../qapi/job.json' } + ## # = Block devices ## { 'include': '../../qapi/block-core.json' } { 'include': '../../qapi/block-export.json' } + { 'include': '../../qapi/char.json' } -{ 'include': '../../qapi/common.json' } +{ 'include': '../../qapi/authz.json' } +{ 'include': '../../qapi/transaction.json' } { 'include': '../../qapi/control.json' } -{ 'include': '../../qapi/crypto.json' } { 'include': '../../qapi/introspect.json' } -{ 'include': '../../qapi/job.json' } -{ 'include': '../../qapi/authz.json' } { 'include': '../../qapi/qom.json' } -{ 'include': '../../qapi/sockets.json' } -{ 'include': '../../qapi/transaction.json' } |