diff options
Diffstat (limited to 'qapi')
43 files changed, 720 insertions, 553 deletions
diff --git a/qapi/accelerator.json b/qapi/accelerator.json index 6029e7307a..28d5ff4c49 100644 --- a/qapi/accelerator.json +++ b/qapi/accelerator.json @@ -27,8 +27,6 @@ # # Return information about KVM acceleration # -# Returns: @KvmInfo -# # Since: 0.14 # # .. qmp-example:: diff --git a/qapi/acpi.json b/qapi/acpi.json index 2d53b82365..906b3687a5 100644 --- a/qapi/acpi.json +++ b/qapi/acpi.json @@ -6,7 +6,9 @@ # SPDX-License-Identifier: GPL-2.0-or-later ## -# = ACPI +# **** +# ACPI +# **** ## ## @@ -106,7 +108,7 @@ ## # @query-acpi-ospm-status: # -# Return a list of ACPIOSTInfo for devices that support status +# Return a list of `ACPIOSTInfo` for devices that support status # reporting via ACPI _OST method. # # Since: 2.1 diff --git a/qapi/audio.json b/qapi/audio.json index 16de231f6d..53142080f7 100644 --- a/qapi/audio.json +++ b/qapi/audio.json @@ -7,7 +7,9 @@ # See the COPYING file in the top-level directory. ## -# = Audio +# ***** +# Audio +# ***** ## ## @@ -535,8 +537,6 @@ # # Return information about audiodev configuration # -# Returns: array of @Audiodev -# # Since: 8.0 ## { 'command': 'query-audiodevs', diff --git a/qapi/authz.json b/qapi/authz.json index 7fc6e3032e..bc1123cc05 100644 --- a/qapi/authz.json +++ b/qapi/authz.json @@ -2,7 +2,9 @@ # vim: filetype=python ## -# = User authorization +# ****************** +# User authorization +# ****************** ## ## @@ -75,7 +77,7 @@ # Properties for authz-listfile objects. # # @filename: File name to load the configuration from. The file must -# contain valid JSON for AuthZListProperties. +# contain valid JSON for `AuthZListProperties`. # # @refresh: If true, inotify is used to monitor the file, # automatically reloading changes. If an error occurs during diff --git a/qapi/block-core.json b/qapi/block-core.json index 1df6644f0d..ebbe95b3d8 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -2,7 +2,8 @@ # vim: filetype=python ## -# == Block core (VM unrelated) +# Block core (VM unrelated) +# ========================= ## { 'include': 'common.json' } @@ -31,7 +32,7 @@ # @icount: Current instruction count. Appears when execution # record/replay is enabled. Used for "time-traveling" to match # the moment in the recorded execution with the snapshots. This -# counter may be obtained through @query-replay command +# counter may be obtained through `query-replay` command # (since 5.2) # # Since: 1.3 @@ -223,7 +224,7 @@ { 'struct': 'ImageInfoSpecificLUKSWrapper', 'data': { 'data': 'QCryptoBlockInfoLUKS' } } # If we need to add block driver specific parameters for -# LUKS in future, then we'll subclass QCryptoBlockInfoLUKS +# LUKS in future, then we'll subclass `QCryptoBlockInfoLUKS` # to define a ImageInfoSpecificLUKS ## @@ -332,7 +333,7 @@ # node, annotated with information about that node in relation to its # parent. # -# @name: Child name of the root node in the BlockGraphInfo struct, in +# @name: Child name of the root node in the `BlockGraphInfo` struct, in # its role as the child of some undescribed parent node # # @info: Block graph information starting at this node @@ -349,7 +350,7 @@ # @BlockGraphInfo: # # Information about all nodes in a block (sub)graph in the form of -# BlockNodeInfo data. The base BlockNodeInfo struct contains the +# `BlockNodeInfo` data. The base `BlockNodeInfo` struct contains the # information for the (sub)graph's root node. # # @children: Array of links to this node's child nodes' information @@ -462,6 +463,19 @@ 'no-flush': 'bool' } } ## +# @BlockdevChild: +# +# @child: The name of the child, for example 'file' or 'backing'. +# +# @node-name: The name of the child's block driver node. +# +# Since: 10.1 +## +{ 'struct': 'BlockdevChild', + 'data': { 'child': 'str', + 'node-name': 'str' } } + +## # @BlockDeviceInfo: # # Information about the backing device for a block device. @@ -486,6 +500,8 @@ # @backing_file_depth: number of files in the backing file chain # (since: 1.2) # +# @children: Information about child block nodes. (since: 10.1) +# # @active: true if the backend is active; typical cases for inactive backends # are on the migration source instance after migration completes and on the # destination before it completes. (since: 10.0) @@ -558,8 +574,9 @@ # Since: 0.14 ## { 'struct': 'BlockDeviceInfo', - 'data': { 'file': 'str', '*node-name': 'str', 'ro': 'bool', 'drv': 'str', + 'data': { 'file': 'str', 'node-name': 'str', 'ro': 'bool', 'drv': 'str', '*backing_file': 'str', 'backing_file_depth': 'int', + 'children': ['BlockdevChild'], 'active': 'bool', 'encrypted': 'bool', 'detect_zeroes': 'BlockdevDetectZeroesOptions', 'bps': 'int', 'bps_rd': 'int', 'bps_wr': 'int', @@ -614,7 +631,7 @@ # @inconsistent: true if this is a persistent bitmap that was # improperly stored. Implies @persistent to be true; @recording # and @busy to be false. This bitmap cannot be used. To remove -# it, use @block-dirty-bitmap-remove. (Since 4.0) +# it, use `block-dirty-bitmap-remove`. (Since 4.0) # # Since: 1.3 ## @@ -709,12 +726,12 @@ # @tray_open: True if the device's tray is open (only present if it # has a tray) # -# @io-status: @BlockDeviceIoStatus. Only present if the device +# @io-status: `BlockDeviceIoStatus`. Only present if the device # supports it and the VM is configured to stop on errors # (supported device models: virtio-blk, IDE, SCSI except # scsi-generic) # -# @inserted: @BlockDeviceInfo describing the device if media is +# @inserted: `BlockDeviceInfo` describing the device if media is # present # # Since: 0.14 @@ -761,9 +778,9 @@ ## # @query-block: # -# Get a list of BlockInfo for all virtual block devices. +# Get a list of `BlockInfo` for all virtual block devices. # -# Returns: a list of @BlockInfo describing each virtual block device. +# Returns: a list describing each virtual block device. # Filter nodes that were created implicitly are skipped over. # # Since: 0.14 @@ -1026,14 +1043,14 @@ # @timed_stats: Statistics specific to the set of previously defined # intervals of time (Since 2.5) # -# @rd_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0) +# @rd_latency_histogram: `BlockLatencyHistogramInfo`. (Since 4.0) # -# @wr_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0) +# @wr_latency_histogram: `BlockLatencyHistogramInfo`. (Since 4.0) # -# @zone_append_latency_histogram: @BlockLatencyHistogramInfo. +# @zone_append_latency_histogram: `BlockLatencyHistogramInfo`. # (since 8.1) # -# @flush_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0) +# @flush_latency_histogram: `BlockLatencyHistogramInfo`. (Since 4.0) # # Since: 0.14 ## @@ -1134,7 +1151,7 @@ # @qdev: The qdev ID, or if no ID is assigned, the QOM path of the # block device. (since 3.0) # -# @stats: A @BlockDeviceStats for the device. +# @stats: A `BlockDeviceStats` for the device. # # @driver-specific: Optional driver-specific stats. (Since 4.2) # @@ -1158,7 +1175,7 @@ ## # @query-blockstats: # -# Query the @BlockStats for all virtual block devices. +# Query the `BlockStats` for all virtual block devices. # # @query-nodes: If true, the command will query all the block nodes # that have a node name, in a list which will include "parent" @@ -1168,7 +1185,7 @@ # nodes that were created implicitly are skipped over in this # mode. (Since 2.3) # -# Returns: A list of @BlockStats for each virtual block devices. +# Returns: A list of statistics for each virtual block device. # # Since: 0.14 # @@ -1289,8 +1306,8 @@ # @report: for guest operations, report the error to the guest; for # jobs, cancel the job # -# @ignore: ignore the error, only report a QMP event (BLOCK_IO_ERROR -# or BLOCK_JOB_ERROR). The backup, mirror and commit block jobs +# @ignore: ignore the error, only report a QMP event (`BLOCK_IO_ERROR` +# or `BLOCK_JOB_ERROR`). The backup, mirror and commit block jobs # retry the failing request later and may still complete # successfully. The stream block job continues to stream and will # complete with an error. @@ -1323,7 +1340,7 @@ # (since: 2.4) # # @bitmap: only copy data described by the dirty bitmap. Behavior on -# completion is determined by the BitmapSyncMode. (since: 4.2) +# completion is determined by the `BitmapSyncMode`. (since: 4.2) # # Since: 1.3 ## @@ -1440,7 +1457,7 @@ # # Return information about long-running block device operations. # -# Returns: a list of @BlockJobInfo for each active block job +# Returns: a list of job info for each active block job # # Since: 1.1 ## @@ -1530,7 +1547,7 @@ # @overlay: reference to the existing block device that will become # the overlay of @node, as part of taking the snapshot. It must # not have a current backing file (this can be achieved by passing -# "backing": null to blockdev-add). +# "backing": null to `blockdev-add`). # # Since: 2.5 ## @@ -1585,7 +1602,7 @@ # @bitmap: The name of a dirty bitmap to use. Must be present if sync # is "bitmap" or "incremental". Can be present if sync is "full" # or "top". Must not be present otherwise. -# (Since 2.4 (drive-backup), 3.1 (blockdev-backup)) +# (Since 2.4 (`drive-backup`), 3.1 (`blockdev-backup`)) # # @bitmap-mode: Specifies the type of data the bitmap should contain # after the operation concludes. Must be present if a bitmap was @@ -1596,7 +1613,7 @@ # # @on-source-error: the action to take on an error on the source, # default 'report'. 'stop' and 'enospc' can only be used if the -# block device supports io-status (see BlockInfo). +# block device supports io-status (see `BlockInfo`). # # @on-target-error: the action to take on an error on the target, # default 'report' (no limitations, since this applies to a @@ -1606,14 +1623,14 @@ # copy-before-write jobs; defaults to break-guest-write. (Since 10.1) # # @auto-finalize: When false, this job will wait in a PENDING state -# after it has finished its work, waiting for @job-finalize before +# after it has finished its work, waiting for `job-finalize` before # making any block graph changes. When true, this job will # automatically perform its abort or commit actions. Defaults to # true. (Since 2.12) # # @auto-dismiss: When false, this job will wait in a CONCLUDED state # after it has completely ceased all work, and awaits -# @job-dismiss. When true, this job will automatically disappear +# `job-dismiss`. When true, this job will automatically disappear # without user intervention. Defaults to true. (Since 2.12) # # @filter-node-name: the node name that should be assigned to the @@ -1719,7 +1736,7 @@ # # @allow-write-only-overlay: If present, the check whether this # operation is safe was relaxed so that it can be used to change -# backing file of a destination of a blockdev-mirror. (since 5.0) +# backing file of a destination of a `blockdev-mirror`. (since 5.0) # # Since: 2.5 # @@ -1784,7 +1801,7 @@ # If top == base, that is an error. If top has no overlays on top of # it, or if it is in use by a writer, the job will not be completed by # itself. The user needs to complete the job with the -# job-complete command after getting the ready event. (Since 2.0) +# `job-complete` command after getting the ready event. (Since 2.0) # # If the base image is smaller than top, then the base image will be # resized to be the same size as top. If top is smaller than the base @@ -1846,14 +1863,14 @@ # autogenerated. (Since: 2.9) # # @auto-finalize: When false, this job will wait in a PENDING state -# after it has finished its work, waiting for @job-finalize before +# after it has finished its work, waiting for `job-finalize` before # making any block graph changes. When true, this job will # automatically perform its abort or commit actions. Defaults to # true. (Since 3.1) # # @auto-dismiss: When false, this job will wait in a CONCLUDED state # after it has completely ceased all work, and awaits -# @job-dismiss. When true, this job will automatically disappear +# `job-dismiss`. When true, this job will automatically disappear # without user intervention. Defaults to true. (Since 3.1) # # Features: @@ -1889,14 +1906,14 @@ # @drive-backup: # # Start a point-in-time copy of a block device to a new destination. -# The status of ongoing drive-backup operations can be checked with -# query-block-jobs where the BlockJobInfo.type field has the value +# The status of ongoing `drive-backup` operations can be checked with +# `query-block-jobs` where the `BlockJobInfo`.type field has the value # 'backup'. The operation can be stopped before it has completed -# using the job-cancel or block-job-cancel command. +# using the `job-cancel` or `block-job-cancel` command. # # Features: # -# @deprecated: This command is deprecated. Use @blockdev-backup +# @deprecated: This command is deprecated. Use `blockdev-backup` # instead. # # Errors: @@ -1920,10 +1937,10 @@ # @blockdev-backup: # # Start a point-in-time copy of a block device to a new destination. -# The status of ongoing blockdev-backup operations can be checked with -# query-block-jobs where the BlockJobInfo.type field has the value +# The status of ongoing `blockdev-backup` operations can be checked with +# `query-block-jobs` where the `BlockJobInfo`.type field has the value # 'backup'. The operation can be stopped before it has completed -# using the job-cancel or block-job-cancel command. +# using the `job-cancel` or `block-job-cancel` command. # # Errors: # - If @device is not a valid block device, DeviceNotFound @@ -1950,8 +1967,6 @@ # @flat: Omit the nested data about backing image ("backing-image" # key) if true. Default is false (Since 5.0) # -# Returns: the list of BlockDeviceInfo -# # Since: 2.0 # # .. qmp-example:: @@ -2026,7 +2041,7 @@ # @XDbgBlockGraphNode: # # @id: Block graph node identifier. This @id is generated only for -# x-debug-query-block-graph and does not relate to any other +# `x-debug-query-block-graph` and does not relate to any other # identifiers in QEMU. # # @type: Type of graph node. Can be one of block-backend, block-job @@ -2075,7 +2090,7 @@ ## # @XDbgBlockGraphEdge: # -# Block Graph edge description for x-debug-query-block-graph. +# Block Graph edge description for `x-debug-query-block-graph`. # # @parent: parent id # @@ -2193,7 +2208,7 @@ # # @on-source-error: the action to take on an error on the source, # default 'report'. 'stop' and 'enospc' can only be used if the -# block device supports io-status (see BlockInfo). +# block device supports io-status (see `BlockInfo`). # # @on-target-error: the action to take on an error on the target, # default 'report' (no limitations, since this applies to a @@ -2209,14 +2224,14 @@ # 'background' (Since: 3.0) # # @auto-finalize: When false, this job will wait in a PENDING state -# after it has finished its work, waiting for @job-finalize before +# after it has finished its work, waiting for `job-finalize` before # making any block graph changes. When true, this job will # automatically perform its abort or commit actions. Defaults to # true. (Since 3.1) # # @auto-dismiss: When false, this job will wait in a CONCLUDED state # after it has completely ceased all work, and awaits -# @job-dismiss. When true, this job will automatically disappear +# `job-dismiss`. When true, this job will automatically disappear # without user intervention. Defaults to true. (Since 3.1) # # Since: 1.3 @@ -2251,16 +2266,16 @@ # @name: name of the dirty bitmap (must be less than 1024 bytes) # # @granularity: the bitmap granularity, default is 64k for -# block-dirty-bitmap-add +# `block-dirty-bitmap-add` # # @persistent: the bitmap is persistent, i.e. it will be saved to the # corresponding block device image file on its close. For now # only Qcow2 disks support persistent bitmaps. Default is false -# for block-dirty-bitmap-add. (Since: 2.10) +# for `block-dirty-bitmap-add`. (Since: 2.10) # # @disabled: the bitmap is created in the disabled state, which means # that it will not track drive changes. The bitmap may be enabled -# with block-dirty-bitmap-enable. Default is false. (Since: 4.0) +# with `block-dirty-bitmap-enable`. Default is false. (Since: 4.0) # # Since: 2.4 ## @@ -2290,7 +2305,7 @@ # @target: name of the destination dirty bitmap # # @bitmaps: name(s) of the source dirty bitmap(s) at @node and/or -# fully specified BlockDirtyBitmap elements. The latter are +# fully specified `BlockDirtyBitmap` elements. The latter are # supported since 4.1. # # Since: 4.0 @@ -2325,7 +2340,7 @@ # @block-dirty-bitmap-remove: # # Stop write tracking and remove the dirty bitmap that was created -# with block-dirty-bitmap-add. If the bitmap is persistent, remove it +# with `block-dirty-bitmap-add`. If the bitmap is persistent, remove it # from its storage too. # # Errors: @@ -2464,9 +2479,6 @@ # # @unstable: This command is meant for debugging. # -# Returns: -# BlockDirtyBitmapSha256 -# # Errors: # - If @node is not a valid block device, DeviceNotFound # - If @name is not found or if hashing has failed, GenericError @@ -2512,7 +2524,7 @@ # # @on-source-error: the action to take on an error on the source, # default 'report'. 'stop' and 'enospc' can only be used if the -# block device supports io-status (see BlockInfo). +# block device supports io-status (see `BlockInfo`). # # @on-target-error: the action to take on an error on the target, # default 'report' (no limitations, since this applies to a @@ -2527,14 +2539,14 @@ # 'background' (Since: 3.0) # # @auto-finalize: When false, this job will wait in a PENDING state -# after it has finished its work, waiting for @job-finalize before +# after it has finished its work, waiting for `job-finalize` before # making any block graph changes. When true, this job will # automatically perform its abort or commit actions. Defaults to # true. (Since 3.1) # # @auto-dismiss: When false, this job will wait in a CONCLUDED state # after it has completely ceased all work, and awaits -# @job-dismiss. When true, this job will automatically disappear +# `job-dismiss`. When true, this job will automatically disappear # without user intervention. Defaults to true. (Since 3.1) # # @target-is-zero: Assume the destination reads as all zeroes before @@ -2782,9 +2794,9 @@ # The block streaming operation is performed in the background until # the entire backing file has been copied. This command returns # immediately once streaming has started. The status of ongoing block -# streaming operations can be checked with query-block-jobs. The +# streaming operations can be checked with `query-block-jobs`. The # operation can be stopped before it has completed using the -# job-cancel or block-job-cancel command. +# `job-cancel` or `block-job-cancel` command. # # The node that receives the data is called the top image, can be # located in any part of the chain (but always above the base image; @@ -2803,9 +2815,9 @@ # will be the new backing file. # # On successful completion the image file is updated to drop the -# backing file and the BLOCK_JOB_COMPLETED event is emitted. +# backing file and the `BLOCK_JOB_COMPLETED` event is emitted. # -# In case @device is a filter node, block-stream modifies the first +# In case @device is a filter node, `block-stream` modifies the first # non-filter overlay node below it to point to the new backing node # instead of modifying @device itself. # @@ -2846,7 +2858,7 @@ # # @on-error: the action to take on an error (default report). 'stop' # and 'enospc' can only be used if the block device supports -# io-status (see BlockInfo). (Since 1.3) +# io-status (see `BlockInfo`). (Since 1.3) # # @filter-node-name: the node name that should be assigned to the # filter driver that the stream job inserts into the graph above @@ -2854,14 +2866,14 @@ # autogenerated. (Since: 6.0) # # @auto-finalize: When false, this job will wait in a PENDING state -# after it has finished its work, waiting for @job-finalize before +# after it has finished its work, waiting for `job-finalize` before # making any block graph changes. When true, this job will # automatically perform its abort or commit actions. Defaults to # true. (Since 3.1) # # @auto-dismiss: When false, this job will wait in a CONCLUDED state # after it has completely ceased all work, and awaits -# @job-dismiss. When true, this job will automatically disappear +# `job-dismiss`. When true, this job will automatically disappear # without user intervention. Defaults to true. (Since 3.1) # # Errors: @@ -2922,13 +2934,13 @@ # command if no operation is in progress. # # The operation will cancel as soon as possible and then emit the -# BLOCK_JOB_CANCELLED event. Before that happens the job is still -# visible when enumerated using query-block-jobs. +# `BLOCK_JOB_CANCELLED` event. Before that happens the job is still +# visible when enumerated using `query-block-jobs`. # -# Note that if you issue 'block-job-cancel' after 'drive-mirror' has -# indicated (via the event BLOCK_JOB_READY) that the source and +# Note that if you issue `block-job-cancel` after `drive-mirror` has +# indicated (via the event `BLOCK_JOB_READY`) that the source and # destination are synchronized, then the event triggered by this -# command changes to BLOCK_JOB_COMPLETED, to indicate that the +# command changes to `BLOCK_JOB_COMPLETED`, to indicate that the # mirroring has ended and the destination now has a point-in-time copy # tied to the time of the cancellation. # @@ -2942,7 +2954,7 @@ # values. # # @force: If true, and the job has already emitted the event -# BLOCK_JOB_READY, abandon the job immediately (even if it is +# `BLOCK_JOB_READY`, abandon the job immediately (even if it is # paused) instead of waiting for the destination to complete its # final synchronization (since 1.3) # @@ -2965,7 +2977,7 @@ # # The job will pause as soon as possible, which means transitioning # into the PAUSED state if it was RUNNING, or into STANDBY if it was -# READY. The corresponding JOB_STATUS_CHANGE event will be emitted. +# READY. The corresponding `JOB_STATUS_CHANGE` event will be emitted. # # Cancelling a paused job automatically resumes it. # @@ -2975,7 +2987,7 @@ # # Features: # -# @deprecated: This command is deprecated. Use @job-pause +# @deprecated: This command is deprecated. Use `job-pause` # instead. # # Errors: @@ -3004,7 +3016,7 @@ # # Features: # -# @deprecated: This command is deprecated. Use @job-resume +# @deprecated: This command is deprecated. Use `job-resume` # instead. # # Errors: @@ -3025,14 +3037,14 @@ # # This is supported only for drive mirroring, where it also switches # the device to write to the target path only. Note that drive -# mirroring includes drive-mirror, blockdev-mirror and block-commit +# mirroring includes `drive-mirror`, `blockdev-mirror` and `block-commit` # job (only in case of "active commit", when the node being commited # is used by the guest). The ability to complete is signaled with a -# BLOCK_JOB_READY event. +# `BLOCK_JOB_READY` event. # # This command completes an active background block operation # synchronously. The ordering of this command's return with the -# BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error +# `BLOCK_JOB_COMPLETED` event is not defined. Note that if an I/O error # occurs during the processing of this command: 1) the command itself # will fail; 2) the error will be processed according to the # rerror/werror arguments that were specified when starting the @@ -3044,7 +3056,7 @@ # # Features: # -# @deprecated: This command is deprecated. Use @job-complete +# @deprecated: This command is deprecated. Use `job-complete` # instead. # # Errors: @@ -3063,21 +3075,21 @@ # Deletes a job that is in the CONCLUDED state. This command only # needs to be run explicitly for jobs that don't have automatic # dismiss enabled. In turn, automatic dismiss may be enabled only -# for jobs that have @auto-dismiss option, which are drive-backup, -# blockdev-backup, drive-mirror, blockdev-mirror, block-commit and -# block-stream. @auto-dismiss is enabled by default for these +# for jobs that have @auto-dismiss option, which are `drive-backup`, +# `blockdev-backup`, `drive-mirror`, `blockdev-mirror`, `block-commit` and +# `block-stream`. @auto-dismiss is enabled by default for these # jobs. # # This command will refuse to operate on any job that has not yet # reached its terminal state, CONCLUDED. For jobs that make use of -# the BLOCK_JOB_READY event, job-cancel, block-job-cancel or -# job-complete will still need to be used as appropriate. +# the `BLOCK_JOB_READY` event, `job-cancel`, `block-job-cancel` or +# `job-complete` will still need to be used as appropriate. # # @id: The job identifier. # # Features: # -# @deprecated: This command is deprecated. Use @job-dismiss +# @deprecated: This command is deprecated. Use `job-dismiss` # instead. # # Since: 2.12 @@ -3105,7 +3117,7 @@ # # Features: # -# @deprecated: This command is deprecated. Use @job-finalize +# @deprecated: This command is deprecated. Use `job-finalize` # instead. # # Since: 2.12 @@ -3177,7 +3189,7 @@ # @on: Enabled # # @unmap: Enabled and even try to unmap blocks if possible. This -# requires also that @BlockdevDiscardOptions is set to unmap for +# requires also that `BlockdevDiscardOptions` is set to unmap for # this device. # # Since: 2.1 @@ -4719,7 +4731,7 @@ # @driver: block driver name # # @node-name: the node name of the new node. This option is required -# on the top level of blockdev-add. Valid node names start with +# on the top level of `blockdev-add`. Valid node names start with # an alphabetic character and may contain only alphanumeric # characters, '-', '.' and '_'. Their maximum length is 31 # characters. (Since 2.0) @@ -4923,7 +4935,7 @@ # cancelled. # # The command receives a list of block devices to reopen. For each -# one of them, the top-level @node-name option (from BlockdevOptions) +# one of them, the top-level @node-name option (from `BlockdevOptions`) # must be specified and is used to select the block device to be # reopened. Other @node-name options must be either omitted or set to # the current name of the appropriate node. This command won't change @@ -4932,7 +4944,7 @@ # In the case of options that refer to child nodes, the behavior of # this command depends on the value: # -# 1) A set of options (BlockdevOptions): the child is reopened with +# 1) A set of options (`BlockdevOptions`): the child is reopened with # the specified set of options. # # 2) A reference to the current child: the child is reopened using @@ -4946,7 +4958,7 @@ # Options (1) and (2) are supported in all cases. Option (3) is # supported for @file and @backing, and option (4) for @backing only. # -# Unlike with blockdev-add, the @backing option must always be present +# Unlike with `blockdev-add`, the @backing option must always be present # unless the node being reopened does not have a backing file and its # image does not have a default backing file name as part of its # metadata. @@ -4960,7 +4972,7 @@ ## # @blockdev-del: # -# Deletes a block device that has been added using blockdev-add. The +# Deletes a block device that has been added using `blockdev-add`. The # command will fail if the node is attached to a device or is # otherwise being used. # @@ -5515,7 +5527,7 @@ # @blockdev-create: # # Starts a job to create an image format on a given node. The job is -# automatically finalized, but a manual job-dismiss is required. +# automatically finalized, but a manual `job-dismiss` is required. # # @job-id: Identifier for the newly created job. # @@ -5575,7 +5587,7 @@ # # Starts a job to amend format specific options of an existing open # block device. The job is automatically finalized, but a manual -# job-dismiss is required. +# `job-dismiss` is required. # # @job-id: Identifier for the newly created job. # @@ -5644,10 +5656,10 @@ # # @fatal: if set, the image is marked corrupt and therefore unusable # after this event and must be repaired (Since 2.2; before, every -# BLOCK_IMAGE_CORRUPTED event was fatal) +# `BLOCK_IMAGE_CORRUPTED` event was fatal) # -# .. note:: If action is "stop", a STOP event will eventually follow -# the BLOCK_IO_ERROR event. +# .. note:: If action is "stop", a `STOP` event will eventually follow +# the `BLOCK_IO_ERROR` event. # # .. qmp-example:: # @@ -5688,15 +5700,15 @@ # # @nospace: true if I/O error was caused due to a no-space condition. # This key is only present if query-block's io-status is present, -# please see query-block documentation for more information +# please see `query-block` documentation for more information # (since: 2.2) # # @reason: human readable string describing the error cause. (This # field is a debugging aid for humans, it should not be parsed by # applications) (since: 2.2) # -# .. note:: If action is "stop", a STOP event will eventually follow -# the BLOCK_IO_ERROR event. +# .. note:: If action is "stop", a `STOP` event will eventually follow +# the `BLOCK_IO_ERROR` event. # # .. note:: This event is rate-limited. # @@ -5838,7 +5850,7 @@ # @speed: rate limit, bytes per second # # .. note:: The "ready to complete" status is always reset by a -# @BLOCK_JOB_ERROR event. +# `BLOCK_JOB_ERROR` event. # # Since: 1.3 # @@ -5860,7 +5872,7 @@ # @BLOCK_JOB_PENDING: # # Emitted when a block job is awaiting explicit authorization to -# finalize graph changes via @job-finalize. If this job is part +# finalize graph changes via `job-finalize`. If this job is part # of a transaction, it will not emit this event until the transaction # has converged first. # @@ -5909,7 +5921,7 @@ # configured write threshold. For thin-provisioned devices, this # means the device should be extended to avoid pausing for disk # exhaustion. The event is one shot. Once triggered, it needs to be -# re-registered with another block-set-write-threshold command. +# re-registered with another `block-set-write-threshold` command. # # @node-name: graph node name on which the threshold was exceeded. # @@ -5980,7 +5992,7 @@ # # TODO: Removing children from a quorum node means introducing # gaps in the child indices. This cannot be represented in the -# 'children' list of BlockdevOptionsQuorum, as returned by +# 'children' list of `BlockdevOptionsQuorum`, as returned by # .bdrv_refresh_filename(). # # Since: 2.7 @@ -6193,7 +6205,7 @@ # Synchronously delete an internal snapshot of a block device, when # the format of the image used support it. The snapshot is identified # by name or id or both. One of the name or id is required. Return -# SnapshotInfo for the successfully deleted snapshot. +# `SnapshotInfo` for the successfully deleted snapshot. # # @device: the device name or node-name of a root node to delete the # snapshot from @@ -6202,9 +6214,6 @@ # # @name: optional the snapshot's name to be deleted # -# Returns: -# SnapshotInfo -# # Errors: # - If @device is not a valid block device, GenericError # - If snapshot not found, GenericError diff --git a/qapi/block-export.json b/qapi/block-export.json index ed4deb54db..6878b89dcf 100644 --- a/qapi/block-export.json +++ b/qapi/block-export.json @@ -2,7 +2,8 @@ # vim: filetype=python ## -# == Block device exports +# Block device exports +# ==================== ## { 'include': 'sockets.json' } @@ -37,9 +38,9 @@ ## # @NbdServerOptions: # -# Keep this type consistent with the NbdServerOptionsLegacy type. The -# only intended difference is using SocketAddress instead of -# SocketAddressLegacy. +# Keep this type consistent with the `NbdServerOptionsLegacy` type. The +# only intended difference is using `SocketAddress` instead of +# `SocketAddressLegacy`. # # @addr: Address on which to listen (since 4.2). ## @@ -50,9 +51,9 @@ ## # @NbdServerOptionsLegacy: # -# Keep this type consistent with the NbdServerOptions type. The only -# intended difference is using SocketAddressLegacy instead of -# SocketAddress. +# Keep this type consistent with the `NbdServerOptions` type. The only +# intended difference is using `SocketAddressLegacy` instead of +# `SocketAddress`. # # @addr: Address on which to listen (since 1.3). ## @@ -64,7 +65,7 @@ # @nbd-server-start: # # Start an NBD server listening on the given host and port. Block -# devices can then be exported using @nbd-server-add. The NBD server +# devices can then be exported using `nbd-server-add`. The NBD server # will present them as named exports; for example, another QEMU # instance could refer to them as "nbd:HOST:PORT:exportname=NAME". # @@ -80,8 +81,8 @@ ## # @BlockExportOptionsNbdBase: # -# An NBD block export (common options shared between nbd-server-add -# and the NBD branch of block-export-add). +# An NBD block export (common options shared between `nbd-server-add` +# and the NBD branch of `block-export-add`). # # @name: Export name. If unspecified, the @device parameter is used # as the export name. (Since 2.12) @@ -98,7 +99,7 @@ # @BlockExportOptionsNbd: # # An NBD block export (distinct options used in the NBD branch of -# block-export-add). +# `block-export-add`). # # @bitmaps: Also export each of the named dirty bitmaps reachable from # @device, so the NBD client can use NBD_OPT_SET_META_CONTEXT with @@ -124,7 +125,7 @@ # A vhost-user-blk block export. # # @addr: The vhost-user socket on which to listen. Both 'unix' and -# 'fd' SocketAddress types are supported. Passed fds must be UNIX +# 'fd' `SocketAddress` types are supported. Passed fds must be UNIX # domain sockets. # # @logical-block-size: Logical block size in bytes. Defaults to 512 @@ -216,7 +217,7 @@ ## # @NbdServerAddOptions: # -# An NBD block export, per legacy nbd-server-add command. +# An NBD block export, per legacy `nbd-server-add` command. # # @device: The device name or node name of the node to be exported # @@ -245,7 +246,7 @@ # # Features: # -# @deprecated: This command is deprecated. Use @block-export-add +# @deprecated: This command is deprecated. Use `block-export-add` # instead. # # Errors: @@ -288,12 +289,12 @@ # # @name: Block export id. # -# @mode: Mode of command operation. See @BlockExportRemoveMode +# @mode: Mode of command operation. See `BlockExportRemoveMode` # description. Default is 'safe'. # # Features: # -# @deprecated: This command is deprecated. Use @block-export-del +# @deprecated: This command is deprecated. Use `block-export-del` # instead. # # Errors: @@ -312,7 +313,7 @@ # @nbd-server-stop: # # Stop QEMU's embedded NBD server, and unregister all devices -# previously added via @nbd-server-add. +# previously added via `nbd-server-add`. # # Since: 1.3 ## @@ -421,7 +422,7 @@ # # @id: Block export id. # -# @mode: Mode of command operation. See @BlockExportRemoveMode +# @mode: Mode of command operation. See `BlockExportRemoveMode` # description. Default is 'safe'. # # Errors: @@ -459,7 +460,7 @@ # @node-name: The node name of the block node that is exported # # @shutting-down: True if the export is shutting down (e.g. after a -# block-export-del command, but before the shutdown has completed) +# `block-export-del` command, but before the shutdown has completed) # # Since: 5.2 ## @@ -472,7 +473,7 @@ ## # @query-block-exports: # -# Returns: A list of BlockExportInfo describing all block exports +# Returns: A list describing all block exports # # Since: 5.2 ## diff --git a/qapi/block.json b/qapi/block.json index 1490a1a17f..46955bbb3e 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -2,13 +2,16 @@ # vim: filetype=python ## -# = Block devices +# ************* +# Block devices +# ************* ## { 'include': 'block-core.json' } ## -# == Additional block stuff (VM related) +# Additional block stuff (VM related) +# =================================== ## ## @@ -86,7 +89,7 @@ # Return a list of information about each persistent reservation # manager. # -# Returns: a list of @PRManagerInfo for each persistent reservation +# Returns: a list of manager info for each persistent reservation # manager # # Since: 3.0 @@ -137,7 +140,7 @@ # # If the tray was already open before, this will be a no-op. # -# Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There +# Once the tray opens, a `DEVICE_TRAY_MOVED` event is emitted. There # are cases in which no such event will be generated, these include: # # - if the guest has locked the tray, @force is false and the guest @@ -296,7 +299,7 @@ # @BlockdevChangeReadOnlyMode: # # Specifies the new read-only mode of a block device subject to the -# @blockdev-change-medium command. +# `blockdev-change-medium` command. # # @retain: Retains the current read-only mode # @@ -314,9 +317,9 @@ # # Changes the medium inserted into a block device by ejecting the # current medium and loading a new image file which is inserted as the -# new medium (this command combines blockdev-open-tray, -# blockdev-remove-medium, blockdev-insert-medium and -# blockdev-close-tray). +# new medium (this command combines `blockdev-open-tray`, +# `blockdev-remove-medium`, `blockdev-insert-medium` and +# `blockdev-close-tray`). # # @device: Block device name # @@ -331,7 +334,7 @@ # to 'retain' # # @force: if false (the default), an eject request through -# blockdev-open-tray will be sent to the guest if it has locked +# `blockdev-open-tray` will be sent to the guest if it has locked # the tray (and the tray will not be opened immediately); if true, # the tray will be opened regardless of whether it is locked. # (since 7.1) @@ -519,7 +522,7 @@ # @id: The name or QOM path of the guest device. # # @boundaries: list of interval boundary values (see description in -# BlockLatencyHistogramInfo definition). If specified, all +# `BlockLatencyHistogramInfo` definition). If specified, all # latency histograms are removed, and empty ones created for all # io types with intervals corresponding to @boundaries (except for # io types, for which specific boundaries are set through the diff --git a/qapi/char.json b/qapi/char.json index df6e325e2e..f0a53f742c 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -3,7 +3,9 @@ # ## -# = Character devices +# ***************** +# Character devices +# ***************** ## { 'include': 'sockets.json' } @@ -36,8 +38,6 @@ # # Return information about current character devices. # -# Returns: a list of @ChardevInfo -# # Since: 0.14 # # .. qmp-example:: @@ -82,8 +82,6 @@ # # Return information about character device backends. # -# Returns: a list of @ChardevBackendInfo -# # Since: 2.0 # # .. qmp-example:: @@ -772,8 +770,6 @@ # # @backend: backend type and parameters # -# Returns: ChardevReturn. -# # Since: 1.4 # # .. qmp-example:: @@ -812,8 +808,6 @@ # # @backend: new backend type and parameters # -# Returns: ChardevReturn. -# # Since: 2.10 # # .. qmp-example:: diff --git a/qapi/common.json b/qapi/common.json index 0e3a0bbbfb..af7e3d618a 100644 --- a/qapi/common.json +++ b/qapi/common.json @@ -2,7 +2,9 @@ # vim: filetype=python ## -# = Common data types +# ***************** +# Common data types +# ***************** ## ## diff --git a/qapi/compat.json b/qapi/compat.json index 42034d9368..90b8d51cf2 100644 --- a/qapi/compat.json +++ b/qapi/compat.json @@ -2,7 +2,9 @@ # vim: filetype=python ## -# = Compatibility policy +# ******************** +# Compatibility policy +# ******************** ## ## diff --git a/qapi/control.json b/qapi/control.json index 34b733f63b..9a5302193d 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -3,7 +3,9 @@ # ## -# = QMP monitor control +# ******************* +# QMP monitor control +# ******************* ## ## @@ -11,7 +13,7 @@ # # Enable QMP capabilities. # -# @enable: An optional list of QMPCapability values to enable. The +# @enable: An optional list of `QMPCapability` values to enable. The # client must not enable any capability that is not mentioned in # the QMP greeting message. If the field is not provided, it # means no QMP capabilities will be enabled. (since 2.12) @@ -93,8 +95,7 @@ # # Return the current version of QEMU. # -# Returns: A @VersionInfo object describing the current version of -# QEMU. +# Returns: An object describing the current version of QEMU. # # Since: 0.14 # @@ -131,7 +132,7 @@ # # Return a list of supported QMP commands by this server # -# Returns: A list of @CommandInfo for all supported commands +# Returns: A list of all supported commands # # Since: 0.14 # @@ -158,10 +159,11 @@ ## # @quit: # -# This command will cause the QEMU process to exit gracefully. While -# every attempt is made to send the QMP response before terminating, -# this is not guaranteed. When using this interface, a premature EOF -# would not be unexpected. +# Request graceful QEMU process termination. +# +# While every attempt is made to send the QMP response before +# terminating, this is not guaranteed. When using this interface, a +# premature EOF would not be unexpected. # # Since: 0.14 # diff --git a/qapi/crypto.json b/qapi/crypto.json index 9ec6301e18..ab6eda4c2f 100644 --- a/qapi/crypto.json +++ b/qapi/crypto.json @@ -3,7 +3,9 @@ # ## -# = Cryptography +# ************ +# Cryptography +# ************ ## ## @@ -589,9 +591,9 @@ # # Specific parameters for RSA algorithm. # -# @hash-alg: QCryptoHashAlgo +# @hash-alg: `QCryptoHashAlgo` # -# @padding-alg: QCryptoRSAPaddingAlgo +# @padding-alg: `QCryptoRSAPaddingAlgo` # # Since: 7.1 ## diff --git a/qapi/cryptodev.json b/qapi/cryptodev.json index b13db26403..eb309c22f8 100644 --- a/qapi/cryptodev.json +++ b/qapi/cryptodev.json @@ -5,7 +5,9 @@ # See the COPYING file in the top-level directory. ## -# = Cryptography devices +# ******************** +# Cryptography devices +# ******************** ## ## @@ -96,8 +98,6 @@ # # Return information about current crypto devices. # -# Returns: a list of @QCryptodevInfo -# # Since: 8.0 ## { 'command': 'query-cryptodev', 'returns': ['QCryptodevInfo']} diff --git a/qapi/cxl.json b/qapi/cxl.json index 8f2e9237b1..52cc5d4f33 100644 --- a/qapi/cxl.json +++ b/qapi/cxl.json @@ -2,7 +2,9 @@ # vim: filetype=python ## -# = CXL devices +# *********** +# CXL devices +# *********** ## ## diff --git a/qapi/dump.json b/qapi/dump.json index d0ba1f0596..32c8c1f06e 100644 --- a/qapi/dump.json +++ b/qapi/dump.json @@ -5,7 +5,9 @@ # See the COPYING file in the top-level directory. ## -# = Dump guest memory +# ***************** +# Dump guest memory +# ***************** ## ## @@ -110,7 +112,7 @@ # # Describe the status of a long-running background guest memory dump. # -# @none: no dump-guest-memory has started yet. +# @none: no `dump-guest-memory` has started yet. # # @active: there is one dump running in background. # @@ -126,9 +128,9 @@ ## # @DumpQueryResult: # -# The result format for 'query-dump'. +# The result format for `query-dump`. # -# @status: enum of @DumpStatus, which shows current dump status +# @status: enum of `DumpStatus`, which shows current dump status # # @completed: bytes written in latest dump (uncompressed) # @@ -146,7 +148,7 @@ # # Query latest dump status. # -# Returns: A @DumpStatus object showing the dump status. +# Returns: An object showing the dump status. # # Since: 2.6 # @@ -184,7 +186,7 @@ ## # @DumpGuestMemoryCapability: # -# @formats: the available formats for dump-guest-memory +# @formats: the available formats for `dump-guest-memory` # # Since: 2.0 ## @@ -195,10 +197,9 @@ ## # @query-dump-guest-memory-capability: # -# Return the available formats for dump-guest-memory +# Return the available formats for `dump-guest-memory` # -# Returns: A @DumpGuestMemoryCapability object listing available -# formats for dump-guest-memory +# Returns: An object listing available formats for `dump-guest-memory` # # Since: 2.0 # diff --git a/qapi/ebpf.json b/qapi/ebpf.json index db19ae850f..f0257955fa 100644 --- a/qapi/ebpf.json +++ b/qapi/ebpf.json @@ -5,7 +5,9 @@ # See the COPYING file in the top-level directory. ## -# = eBPF Objects +# ************ +# eBPF Objects +# ************ # # eBPF object is an ELF binary that contains the eBPF program and eBPF # map description(BTF). Overall, eBPF object should contain the @@ -32,7 +34,7 @@ ## # @EbpfProgramID: # -# The eBPF programs that can be gotten with request-ebpf. +# The eBPF programs that can be gotten with `request-ebpf`. # # @rss: Receive side scaling, technology that allows steering traffic # between queues by calculation hash. Users may set up diff --git a/qapi/error.json b/qapi/error.json index 135c1e8231..54cb02fb88 100644 --- a/qapi/error.json +++ b/qapi/error.json @@ -2,7 +2,9 @@ # vim: filetype=python ## -# = QMP errors +# ********** +# QMP errors +# ********** ## ## diff --git a/qapi/introspect.json b/qapi/introspect.json index e9e0297282..53100714a8 100644 --- a/qapi/introspect.json +++ b/qapi/introspect.json @@ -10,17 +10,19 @@ # See the COPYING file in the top-level directory. ## -# = QMP introspection +# ***************** +# QMP introspection +# ***************** ## ## # @query-qmp-schema: # -# Command query-qmp-schema exposes the QMP wire ABI as an array of -# SchemaInfo. This lets QMP clients figure out what commands and +# Command `query-qmp-schema` exposes the QMP wire ABI as an array of +# `SchemaInfo`. This lets QMP clients figure out what commands and # events are available in this QEMU, and their parameters and results. # -# However, the SchemaInfo can't reflect all the rules and restrictions +# However, the `SchemaInfo` can't reflect all the rules and restrictions # that apply to QMP. It's interface introspection (figuring out # what's there), not interface specification. The specification is in # the QAPI schema. @@ -34,10 +36,10 @@ # string into a specific enum or from one specific type into an # alternate that includes the original type alongside something else. # -# Returns: array of @SchemaInfo, where each element describes an -# entity in the ABI: command, event, type, ... +# Returns: an array where each element describes an entity in the ABI: +# command, event, type, ... # -# The order of the various SchemaInfo is unspecified; however, all +# The order of the various elements is unspecified; however, all # names are guaranteed to be unique (no name will be duplicated # with different meta-types). # @@ -54,7 +56,7 @@ ## # @SchemaMetaType: # -# This is a @SchemaInfo's meta type, i.e. the kind of entity it +# This is a `SchemaInfo`'s meta type, i.e. the kind of entity it # describes. # # @builtin: a predefined type such as 'int' or 'bool'. @@ -80,7 +82,7 @@ ## # @SchemaInfo: # -# @name: the entity's name, inherited from @base. The SchemaInfo is +# @name: the entity's name, inherited from @base. The `SchemaInfo` is # always referenced by this name. Commands and events have the # name defined in the QAPI schema. Unlike command and event # names, type names are not part of the wire ABI. Consequently, @@ -111,7 +113,7 @@ ## # @SchemaInfoBuiltin: # -# Additional SchemaInfo members for meta-type 'builtin'. +# Additional `SchemaInfo` members for meta-type 'builtin'. # # @json-type: the JSON type used for this type on the wire. # @@ -152,7 +154,7 @@ ## # @SchemaInfoEnum: # -# Additional SchemaInfo members for meta-type 'enum'. +# Additional `SchemaInfo` members for meta-type 'enum'. # # @members: the enum type's members, in no particular order. # (since 6.2) @@ -192,7 +194,7 @@ ## # @SchemaInfoArray: # -# Additional SchemaInfo members for meta-type 'array'. +# Additional `SchemaInfo` members for meta-type 'array'. # # @element-type: the array type's element type. # @@ -206,7 +208,7 @@ ## # @SchemaInfoObject: # -# Additional SchemaInfo members for meta-type 'object'. +# Additional `SchemaInfo` members for meta-type 'object'. # # @members: the object type's (non-variant) members, in no particular # order. @@ -271,7 +273,7 @@ ## # @SchemaInfoAlternate: # -# Additional SchemaInfo members for meta-type 'alternate'. +# Additional `SchemaInfo` members for meta-type 'alternate'. # # @members: the alternate type's members, in no particular order. The # members' wire encoding is distinct, see @@ -299,7 +301,7 @@ ## # @SchemaInfoCommand: # -# Additional SchemaInfo members for meta-type 'command'. +# Additional `SchemaInfo` members for meta-type 'command'. # # @arg-type: the name of the object type that provides the command's # parameters. @@ -321,7 +323,7 @@ ## # @SchemaInfoEvent: # -# Additional SchemaInfo members for meta-type 'event'. +# Additional `SchemaInfo` members for meta-type 'event'. # # @arg-type: the name of the object type that provides the event's # parameters. diff --git a/qapi/job.json b/qapi/job.json index 126fa5ce60..8b08350af2 100644 --- a/qapi/job.json +++ b/qapi/job.json @@ -2,7 +2,9 @@ # vim: filetype=python ## -# = Background jobs +# *************** +# Background jobs +# *************** ## ## @@ -10,26 +12,26 @@ # # Type of a background job. # -# @commit: block commit job type, see "block-commit" +# @commit: block commit job type, see `block-commit` # -# @stream: block stream job type, see "block-stream" +# @stream: block stream job type, see `block-stream` # -# @mirror: drive mirror job type, see "drive-mirror" +# @mirror: drive mirror job type, see `drive-mirror` # -# @backup: drive backup job type, see "drive-backup" +# @backup: drive backup job type, see `drive-backup` # -# @create: image creation job type, see "blockdev-create" (since 3.0) +# @create: image creation job type, see `blockdev-create` (since 3.0) # -# @amend: image options amend job type, see "x-blockdev-amend" +# @amend: image options amend job type, see `x-blockdev-amend` # (since 5.1) # -# @snapshot-load: snapshot load job type, see "snapshot-load" +# @snapshot-load: snapshot load job type, see `snapshot-load` # (since 6.0) # -# @snapshot-save: snapshot save job type, see "snapshot-save" +# @snapshot-save: snapshot save job type, see `snapshot-save` # (since 6.0) # -# @snapshot-delete: snapshot delete job type, see "snapshot-delete" +# @snapshot-delete: snapshot delete job type, see `snapshot-delete` # (since 6.0) # # Since: 1.7 @@ -65,7 +67,7 @@ # # @pending: The job has finished its work, but has finalization steps # that it needs to make prior to completing. These changes will -# require manual intervention via @job-finalize if auto-finalize +# require manual intervention via `job-finalize` if auto-finalize # was set to false. These pending changes may still fail. # # @aborting: The job is in the process of being aborted, and will @@ -75,7 +77,7 @@ # # @concluded: The job has finished all work. If auto-dismiss was set # to false, the job will remain in this state until it is -# dismissed via @job-dismiss. +# dismissed via `job-dismiss`. # # @null: The job is in the process of being dismantled. This state # should not ever be visible externally. @@ -91,21 +93,21 @@ # # Represents command verbs that can be applied to a job. # -# @cancel: see @job-cancel +# @cancel: see `job-cancel` # -# @pause: see @job-pause +# @pause: see `job-pause` # -# @resume: see @job-resume +# @resume: see `job-resume` # -# @set-speed: see @block-job-set-speed +# @set-speed: see `block-job-set-speed` # -# @complete: see @job-complete +# @complete: see `job-complete` # -# @dismiss: see @job-dismiss +# @dismiss: see `job-dismiss` # -# @finalize: see @job-finalize +# @finalize: see `job-finalize` # -# @change: see @block-job-change (since 8.2) +# @change: see `block-job-change` (since 8.2) # # Since: 2.12 ## @@ -138,7 +140,7 @@ # # The job will pause as soon as possible, which means transitioning # into the PAUSED state if it was RUNNING, or into STANDBY if it was -# READY. The corresponding JOB_STATUS_CHANGE event will be emitted. +# READY. The corresponding `JOB_STATUS_CHANGE` event will be emitted. # # Cancelling a paused job automatically resumes it. # @@ -173,7 +175,7 @@ # cancellation. # # The job will cancel as soon as possible and then emit a -# JOB_STATUS_CHANGE event. Usually, the status will change to +# `JOB_STATUS_CHANGE` event. Usually, the status will change to # ABORTING, but it is possible that a job successfully completes (e.g. # because it was almost done and there was no opportunity to cancel # earlier than completing the job) and transitions to PENDING instead. @@ -192,14 +194,14 @@ # # This is supported only for drive mirroring, where it also switches # the device to write to the target path only. Note that drive -# mirroring includes drive-mirror, blockdev-mirror and block-commit +# mirroring includes `drive-mirror`, `blockdev-mirror` and `block-commit` # job (only in case of "active commit", when the node being commited # is used by the guest). The ability to complete is signaled with a -# BLOCK_JOB_READY event. +# `BLOCK_JOB_READY` event. # # This command completes an active background block operation # synchronously. The ordering of this command's return with the -# BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error +# `BLOCK_JOB_COMPLETED` event is not defined. Note that if an I/O error # occurs during the processing of this command: 1) the command itself # will fail; 2) the error will be processed according to the # rerror/werror arguments that were specified when starting the @@ -217,14 +219,14 @@ # Deletes a job that is in the CONCLUDED state. This command only # needs to be run explicitly for jobs that don't have automatic # dismiss enabled. In turn, automatic dismiss may be enabled only -# for jobs that have @auto-dismiss option, which are drive-backup, -# blockdev-backup, drive-mirror, blockdev-mirror, block-commit and -# block-stream. @auto-dismiss is enabled by default for these +# for jobs that have @auto-dismiss option, which are `drive-backup`, +# `blockdev-backup`, `drive-mirror`, `blockdev-mirror`, `block-commit` and +# `block-stream`. @auto-dismiss is enabled by default for these # jobs. # # This command will refuse to operate on any job that has not yet # reached its terminal state, CONCLUDED. For jobs that make use of -# the JOB_READY event, job-cancel or job-complete will still need to +# the JOB_READY event, `job-cancel` or `job-complete` will still need to # be used as appropriate. # # @id: The job identifier. @@ -295,7 +297,7 @@ # # Return information about jobs. # -# Returns: a list with a @JobInfo for each active job +# Returns: a list with info for each active job # # Since: 3.0 ## diff --git a/qapi/machine-common.json b/qapi/machine-common.json index 298e51f373..ed3d20a2fb 100644 --- a/qapi/machine-common.json +++ b/qapi/machine-common.json @@ -5,7 +5,9 @@ # See the COPYING file in the top-level directory. ## -# = Common machine types +# ******************** +# Common machine types +# ******************** ## ## @@ -26,29 +28,29 @@ # # @thread: thread level, which would also be called SMT level or # logical processor level. The @threads option in -# SMPConfiguration is used to configure the topology of this +# `SMPConfiguration` is used to configure the topology of this # level. # -# @core: core level. The @cores option in SMPConfiguration is used +# @core: core level. The @cores option in `SMPConfiguration` is used # to configure the topology of this level. # -# @module: module level. The @modules option in SMPConfiguration is +# @module: module level. The @modules option in `SMPConfiguration` is # used to configure the topology of this level. # -# @cluster: cluster level. The @clusters option in SMPConfiguration +# @cluster: cluster level. The @clusters option in `SMPConfiguration` # is used to configure the topology of this level. # -# @die: die level. The @dies option in SMPConfiguration is used to +# @die: die level. The @dies option in `SMPConfiguration` is used to # configure the topology of this level. # # @socket: socket level, which would also be called package level. -# The @sockets option in SMPConfiguration is used to configure +# The @sockets option in `SMPConfiguration` is used to configure # the topology of this level. # -# @book: book level. The @books option in SMPConfiguration is used +# @book: book level. The @books option in `SMPConfiguration` is used # to configure the topology of this level. # -# @drawer: drawer level. The @drawers option in SMPConfiguration is +# @drawer: drawer level. The @drawers option in `SMPConfiguration` is # used to configure the topology of this level. # # @default: default level. Some architectures will have default @@ -102,9 +104,9 @@ ## # @SmpCachePropertiesWrapper: # -# List wrapper of SmpCacheProperties. +# List wrapper of `SmpCacheProperties`. # -# @caches: the list of SmpCacheProperties. +# @caches: the list of `SmpCacheProperties`. # # Since 9.2 ## diff --git a/qapi/machine.json b/qapi/machine.json index 6d3a480bea..6f59f70ca6 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -5,7 +5,9 @@ # See the COPYING file in the top-level directory. ## -# = Machines +# ******** +# Machines +# ******** ## { 'include': 'common.json' } @@ -104,8 +106,6 @@ # # Return information about all virtual CPUs. # -# Returns: list of @CpuInfoFast -# # Since: 2.12 # # .. qmp-example:: @@ -191,7 +191,7 @@ # @acpi: machine type supports ACPI (since 8.0) # # @compat-props: The machine type's compatibility properties. Only -# present when query-machines argument @compat-props is true. +# present when `query-machines` argument @compat-props is true. # (since 9.1) # # Features: @@ -221,8 +221,6 @@ # # @unstable: Argument @compat-props is experimental. # -# Returns: a list of MachineInfo -# # Since: 1.2 # # .. qmp-example:: @@ -271,8 +269,6 @@ # # Return information on the current virtual machine. # -# Returns: CurrentMachineParams -# # Since: 4.0 ## { 'command': 'query-current-machine', 'returns': 'CurrentMachineParams' } @@ -294,8 +290,6 @@ # # Return information about the target for this QEMU # -# Returns: QemuTargetInfo -# # Since: 1.2 ## { 'command': 'query-target', 'returns': 'QemuTargetInfo' } @@ -319,8 +313,6 @@ # # Query the guest UUID information. # -# Returns: The @UuidInfo for the guest -# # Since: 0.14 # # .. qmp-example:: @@ -388,7 +380,7 @@ # # Wake up guest from suspend. If the guest has wake-up from suspend # support enabled (wakeup-suspend-support flag from -# query-current-machine), wake-up guest from suspend if the guest is +# `query-current-machine`), wake-up guest from suspend if the guest is # in SUSPENDED state. Return an error otherwise. # # Since: 1.1 @@ -573,7 +565,7 @@ # # List of CXL Fixed Memory Windows. # -# @cxl-fmw: List of CXLFixedMemoryWindowOptions +# @cxl-fmw: List of `CXLFixedMemoryWindowOptions` # # Since: 7.1 ## @@ -628,10 +620,10 @@ ## # @NumaCpuOptions: # -# Option "-numa cpu" overrides default cpu to node mapping. It -# accepts the same set of cpu properties as returned by -# query-hotpluggable-cpus[].props, where node-id could be used to -# override default node mapping. +# Option "-numa cpu" overrides default cpu to node mapping. It accepts +# the same set of cpu properties as returned by +# `query-hotpluggable-cpus[].props <query-hotpluggable-cpus>`, where +# node-id could be used to override default node mapping. # # Since: 2.10 ## @@ -645,7 +637,7 @@ # The memory hierarchy in the System Locality Latency and Bandwidth # Information Structure of HMAT (Heterogeneous Memory Attribute Table) # -# For more information about @HmatLBMemoryHierarchy, see chapter +# For more information about `HmatLBMemoryHierarchy`, see chapter # 5.2.27.4: Table 5-146: Field "Flags" of ACPI 6.3 spec. # # @memory: the structure represents the memory performance @@ -667,7 +659,7 @@ # Data type in the System Locality Latency and Bandwidth Information # Structure of HMAT (Heterogeneous Memory Attribute Table) # -# For more information about @HmatLBDataType, see chapter 5.2.27.4: +# For more information about `HmatLBDataType`, see chapter 5.2.27.4: # Table 5-146: Field "Data Type" of ACPI 6.3 spec. # # @access-latency: access latency (nanoseconds) @@ -694,7 +686,7 @@ # Set the system locality latency and bandwidth information between # Initiator and Target proximity Domains. # -# For more information about @NumaHmatLBOptions, see chapter 5.2.27.4: +# For more information about `NumaHmatLBOptions`, see chapter 5.2.27.4: # Table 5-146 of ACPI 6.3 spec. # # @initiator: the Initiator Proximity Domain. @@ -730,7 +722,7 @@ # Cache associativity in the Memory Side Cache Information Structure # of HMAT # -# For more information of @HmatCacheAssociativity, see chapter +# For more information of `HmatCacheAssociativity`, see chapter # 5.2.27.5: Table 5-147 of ACPI 6.3 spec. # # @none: None (no memory side cache in this proximity domain, or cache @@ -751,7 +743,7 @@ # Cache write policy in the Memory Side Cache Information Structure of # HMAT # -# For more information of @HmatCacheWritePolicy, see chapter 5.2.27.5: +# For more information of `HmatCacheWritePolicy`, see chapter 5.2.27.5: # Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec. # # @none: None (no memory side cache in this proximity domain, or cache @@ -771,7 +763,7 @@ # # Set the memory side cache information for a given memory domain. # -# For more information of @NumaHmatCacheOptions, see chapter 5.2.27.5: +# For more information of `NumaHmatCacheOptions`, see chapter 5.2.27.5: # Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec. # # @node-id: the memory proximity domain to which the memory belongs. @@ -906,8 +898,6 @@ # # Return information for all memory backends. # -# Returns: a list of @Memdev. -# # Since: 2.1 # # .. qmp-example:: @@ -950,7 +940,7 @@ # # The ids other than the node-id specify the position of the CPU # within the CPU topology (as defined by the machine property "smp", -# thus see also type @SMPConfiguration) +# thus see also type `SMPConfiguration`) # # @node-id: NUMA node ID the CPU belongs to # @@ -978,7 +968,7 @@ # Since: 2.7 ## { 'struct': 'CpuInstanceProperties', - # Keep these in sync with the properties device_add accepts + # Keep these in sync with the properties `device_add` accepts 'data': { '*node-id': 'int', '*drawer-id': 'int', '*book-id': 'int', @@ -994,19 +984,19 @@ ## # @HotpluggableCPU: # -# @type: CPU object type for usage with device_add command +# @type: CPU object type for usage with `device_add` command # # @props: list of properties to pass for hotplugging a CPU with -# device_add +# `device_add` # -# @vcpus-count: number of logical VCPU threads @HotpluggableCPU +# @vcpus-count: number of logical VCPU threads `HotpluggableCPU` # provides # # @qom-path: link to existing CPU object if CPU is present or omitted # if CPU is not present. # # .. note:: Management should be prepared to pass through additional -# properties with device_add. +# properties with `device_add`. # # Since: 2.7 ## @@ -1023,8 +1013,6 @@ # # TODO: Better documentation; currently there is none. # -# Returns: a list of HotpluggableCPU objects. -# # Since: 2.7 # # .. qmp-example:: @@ -1146,9 +1134,6 @@ # # Return information about the balloon device. # -# Returns: -# @BalloonInfo -# # Errors: # - If the balloon driver is enabled but not functional because # the KVM kernel module cannot support it, KVMMissingCap @@ -1170,7 +1155,7 @@ # @BALLOON_CHANGE: # # Emitted when the guest changes the actual BALLOON level. This value -# is equivalent to the @actual field return by the 'query-balloon' +# is equivalent to the @actual field return by the `query-balloon` # command # # @actual: the logical size of the VM in bytes. Formula used: @@ -1212,9 +1197,6 @@ # Return the hv-balloon driver data contained in the last received # "STATUS" message from the guest. # -# Returns: -# @HvBalloonInfo -# # Errors: # - If no hv-balloon device is present, guest memory status # reporting is not enabled or no guest memory status report @@ -1275,6 +1257,8 @@ # Return the amount of initially allocated and present hotpluggable # (if enabled) memory in bytes. # +# TODO: This line is a hack to separate the example from the body +# # .. qmp-example:: # # -> { "execute": "query-memory-size-summary" } @@ -1957,7 +1941,7 @@ # # The result of a CPU model baseline. # -# @model: the baselined CpuModelInfo. +# @model: the baselined `CpuModelInfo`. # # Since: 2.8 ## @@ -2006,28 +1990,28 @@ # # * QEMU version: CPU models may look different depending on the QEMU # version. (Except for CPU models reported as "static" in -# query-cpu-definitions.) +# `query-cpu-definitions`.) # * machine-type: CPU model may look different depending on the # machine-type. (Except for CPU models reported as "static" in -# query-cpu-definitions.) +# `query-cpu-definitions`.) # * machine options (including accelerator): in some architectures, # CPU models may look different depending on machine and accelerator # options. (Except for CPU models reported as "static" in -# query-cpu-definitions.) +# `query-cpu-definitions`.) # * "-cpu" arguments and global properties: arguments to the -cpu # option and global properties may affect expansion of CPU models. -# Using query-cpu-model-expansion while using these is not advised. +# Using `query-cpu-model-expansion` while using these is not advised. # # Some architectures may not support comparing CPU models. s390x # supports comparing CPU models. # # @modela: description of the first CPU model to compare, referred to -# as "model A" in CpuModelCompareResult +# as "model A" in `CpuModelCompareResult` # # @modelb: description of the second CPU model to compare, referred to -# as "model B" in CpuModelCompareResult +# as "model B" in `CpuModelCompareResult` # -# Returns: a CpuModelCompareInfo describing how both CPU models +# Returns: a `CpuModelCompareInfo` describing how both CPU models # compare # # Errors: @@ -2060,17 +2044,17 @@ # # * QEMU version: CPU models may look different depending on the QEMU # version. (Except for CPU models reported as "static" in -# query-cpu-definitions.) +# `query-cpu-definitions`.) # * machine-type: CPU model may look different depending on the # machine-type. (Except for CPU models reported as "static" in -# query-cpu-definitions.) +# `query-cpu-definitions`.) # * machine options (including accelerator): in some architectures, # CPU models may look different depending on machine and accelerator # options. (Except for CPU models reported as "static" in -# query-cpu-definitions.) +# `query-cpu-definitions`.) # * "-cpu" arguments and global properties: arguments to the -cpu # option and global properties may affect expansion of CPU models. -# Using query-cpu-model-expansion while using these is not advised. +# Using `query-cpu-model-expansion` while using these is not advised. # # Some architectures may not support baselining CPU models. s390x # supports baselining CPU models. @@ -2079,7 +2063,7 @@ # # @modelb: description of the second CPU model to baseline # -# Returns: a CpuModelBaselineInfo describing the baselined CPU model +# Returns: a `CpuModelBaselineInfo` describing the baselined CPU model # # Errors: # - if baselining CPU models is not supported by the target @@ -2099,7 +2083,7 @@ # # The result of a cpu model expansion. # -# @model: the expanded CpuModelInfo. +# @model: the expanded `CpuModelInfo`. # # @deprecated-props: an optional list of properties that are flagged as # deprecated by the CPU vendor. The list depends on the @@ -2128,17 +2112,17 @@ # # * QEMU version: CPU models may look different depending on the QEMU # version. (Except for CPU models reported as "static" in -# query-cpu-definitions.) +# `query-cpu-definitions`.) # * machine-type: CPU model may look different depending on the # machine-type. (Except for CPU models reported as "static" in -# query-cpu-definitions.) +# `query-cpu-definitions`.) # * machine options (including accelerator): in some architectures, # CPU models may look different depending on machine and accelerator # options. (Except for CPU models reported as "static" in -# query-cpu-definitions.) +# `query-cpu-definitions`.) # * "-cpu" arguments and global properties: arguments to the -cpu # option and global properties may affect expansion of CPU models. -# Using query-cpu-model-expansion while using these is not advised. +# Using `query-cpu-model-expansion` while using these is not advised. # # Some architectures may not support all expansion types. s390x # supports "full" and "static". Arm only supports "full". @@ -2147,7 +2131,7 @@ # # @type: expansion type, specifying how to expand the CPU model # -# Returns: a CpuModelExpansionInfo describing the expanded CPU model +# Returns: a `CpuModelExpansionInfo` describing the expanded CPU model # # Errors: # - if expanding CPU models is not supported @@ -2186,7 +2170,7 @@ # from running in the current host. (since 2.8) # # @typename: Type name that can be used as argument to -# @device-list-properties, to introspect properties configurable +# `device-list-properties`, to introspect properties configurable # using -cpu or -global. (since 2.9) # # @alias-of: Name of CPU model this model is an alias for. The target @@ -2230,8 +2214,6 @@ # # Return a list of supported virtual CPU definitions # -# Returns: a list of CpuDefinitionInfo -# # Since: 1.2 ## { 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'] } diff --git a/qapi/migration.json b/qapi/migration.json index 2d39a8f748..e08a99bb82 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -3,7 +3,9 @@ # ## -# = Migration +# ********* +# Migration +# ********* ## { 'include': 'common.json' } @@ -193,14 +195,14 @@ # # Information about current migration process. # -# @status: @MigrationStatus describing the current migration status. +# @status: `MigrationStatus` describing the current migration status. # If this field is not returned, no migration process has been # initiated # -# @ram: @MigrationStats containing detailed migration status, only +# @ram: `MigrationStats` containing detailed migration status, only # returned if status is 'active' or 'completed'(since 1.2) # -# @xbzrle-cache: @XBZRLECacheStats containing detailed XBZRLE +# @xbzrle-cache: `XBZRLECacheStats` containing detailed XBZRLE # migration statistics, only returned if XBZRLE feature is on and # status is 'active' or 'completed' (since 1.2) # @@ -264,7 +266,7 @@ # @socket-address: Only used for tcp, to know what the real port is # (Since 4.0) # -# @vfio: @VfioStats containing detailed VFIO devices migration +# @vfio: `VfioStats` containing detailed VFIO devices migration # statistics, only returned if VFIO device is present, migration # is supported by all VFIO devices and status is 'active' or # 'completed' (since 5.2) @@ -275,7 +277,7 @@ # # @dirty-limit-throttle-time-per-round: Maximum throttle time (in # microseconds) of virtual CPUs each dirty ring full round, which -# shows how MigrationCapability dirty-limit affects the guest +# shows how `MigrationCapability` dirty-limit affects the guest # during live migration. (Since 8.1) # # @dirty-limit-ring-full-time: Estimated average dirty ring full time @@ -324,8 +326,6 @@ # is active there will be another json-object with RAM migration # status. # -# Returns: @MigrationInfo -# # Since: 0.14 # # .. qmp-example:: @@ -575,8 +575,6 @@ # # Return information about the current migration capabilities status # -# Returns: @MigrationCapabilityStatus -# # Since: 1.2 # # .. qmp-example:: @@ -629,7 +627,7 @@ # # @normal: the original form of migration. (since 8.2) # -# @cpr-reboot: The migrate command stops the VM and saves state to the +# @cpr-reboot: The `migrate` command stops the VM and saves state to the # URI. After quitting QEMU, the user resumes by running QEMU # -incoming. # @@ -679,7 +677,7 @@ # # New QEMU reads the CPR channel before opening a monitor, hence # the CPR channel cannot be specified in the list of channels for -# a migrate-incoming command. It may only be specified on the +# a `migrate-incoming` command. It may only be specified on the # command line. # # The main channel address cannot be a file type, and for an @@ -690,10 +688,10 @@ # memory-backend-epc is not supported. The VM must be started # with the '-machine aux-ram-share=on' option. # -# When using -incoming defer, you must issue the migrate command +# When using -incoming defer, you must issue the `migrate` command # to old QEMU before issuing any monitor commands to new QEMU. # However, new QEMU does not open and read the migration stream -# until you issue the migrate incoming command. +# until you issue the `migrate-incoming` command. # # (since 10.0) ## @@ -915,11 +913,11 @@ # @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. # Defaults to 1. (Since 8.1) # -# @mode: Migration mode. See description in @MigMode. Default is +# @mode: Migration mode. See description in `MigMode`. Default is # 'normal'. (Since 8.2) # # @zero-page-detection: Whether and how to detect zero pages. -# See description in @ZeroPageDetection. Default is 'multifd'. +# See description in `ZeroPageDetection`. Default is 'multifd'. # (since 9.0) # # @direct-io: Open migration files with O_DIRECT when possible. This @@ -1096,11 +1094,11 @@ # @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. # Defaults to 1. (Since 8.1) # -# @mode: Migration mode. See description in @MigMode. Default is +# @mode: Migration mode. See description in `MigMode`. Default is # 'normal'. (Since 8.2) # # @zero-page-detection: Whether and how to detect zero pages. -# See description in @ZeroPageDetection. Default is 'multifd'. +# See description in `ZeroPageDetection`. Default is 'multifd'. # (since 9.0) # # @direct-io: Open migration files with O_DIRECT when possible. This @@ -1112,8 +1110,8 @@ # @unstable: Members @x-checkpoint-delay and # @x-vcpu-dirty-limit-period are experimental. # -# TODO: either fuse back into MigrationParameters, or make -# MigrationParameters members mandatory +# TODO: either fuse back into `MigrationParameters`, or make +# `MigrationParameters` members mandatory # # Since: 2.4 ## @@ -1306,11 +1304,11 @@ # @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. # Defaults to 1. (Since 8.1) # -# @mode: Migration mode. See description in @MigMode. Default is +# @mode: Migration mode. See description in `MigMode`. Default is # 'normal'. (Since 8.2) # # @zero-page-detection: Whether and how to detect zero pages. -# See description in @ZeroPageDetection. Default is 'multifd'. +# See description in `ZeroPageDetection`. Default is 'multifd'. # (since 9.0) # # @direct-io: Open migration files with O_DIRECT when possible. This @@ -1362,8 +1360,6 @@ # # Return information about the current migration parameters # -# Returns: @MigrationParameters -# # Since: 2.4 # # .. qmp-example:: @@ -1402,7 +1398,7 @@ # # Emitted when a migration event happens # -# @status: @MigrationStatus describing the current migration status. +# @status: `MigrationStatus` describing the current migration status. # # Since: 2.4 # @@ -1523,8 +1519,8 @@ # The reason for a COLO exit. # # @none: failover has never happened. This state does not occur in -# the COLO_EXIT event, and is only visible in the result of -# query-colo-status. +# the `COLO_EXIT` event, and is only visible in the result of +# `query-colo-status`. # # @request: COLO exit is due to an external request. # @@ -1779,8 +1775,8 @@ # list connected to a destination interface endpoint. # # @exit-on-error: Exit on incoming migration failure. Default true. -# When set to false, the failure triggers a MIGRATION event, and -# error details could be retrieved with query-migrate. +# When set to false, the failure triggers a :qapi:event:`MIGRATION` +# event, and error details could be retrieved with `query-migrate`. # (since 9.1) # # Since: 2.3 @@ -1792,7 +1788,7 @@ # already exposed above libvirt. # # 2. QEMU must be started with -incoming defer to allow -# migrate-incoming to be used. +# `migrate-incoming` to be used. # # 3. The uri format is the same as for -incoming # @@ -1845,7 +1841,7 @@ # devices of the VM are not saved by this command. # # @filename: the file to save the state of the devices to as binary -# data. See xen-save-devices-state.txt for a description of the +# data. See `xen-save-devices-state`.txt for a description of the # binary format. # # @live: Optional argument to ask QEMU to treat this command as part @@ -1886,7 +1882,7 @@ # devices of the VM are not loaded by this command. # # @filename: the file to load the state of the devices from as binary -# data. See xen-save-devices-state.txt for a description of the +# data. See `xen-save-devices-state`.txt for a description of the # binary format. # # Since: 2.7 @@ -1926,7 +1922,7 @@ ## # @ReplicationStatus: # -# The result format for 'query-xen-replication-status'. +# The result format for `query-xen-replication-status`. # # @error: true if an error happened, false if replication is normal. # @@ -1944,7 +1940,7 @@ # # Query replication status while the vm is running. # -# Returns: A @ReplicationStatus object showing the status. +# TODO: This line is a hack to separate the example from the body # # .. qmp-example:: # @@ -1975,7 +1971,7 @@ ## # @COLOStatus: # -# The result format for 'query-colo-status'. +# The result format for `query-colo-status`. # # @mode: COLO running mode. If COLO is running, this field will # return 'primary' or 'secondary'. @@ -1998,7 +1994,7 @@ # # Query COLO status while the vm is running. # -# Returns: A @COLOStatus object showing the status. +# TODO: This line is a hack to separate the example from the body # # .. qmp-example:: # @@ -2099,7 +2095,7 @@ # @DirtyRateMeasureMode: # # Method used to measure dirty page rate. Differences between -# available methods are explained in @calc-dirty-rate. +# available methods are explained in `calc-dirty-rate`. # # @page-sampling: use page sampling # @@ -2167,7 +2163,7 @@ # @calc-dirty-rate: # # Start measuring dirty page rate of the VM. Results can be retrieved -# with @query-dirty-rate after measurements are completed. +# with `query-dirty-rate` after measurements are completed. # # Dirty page rate is the number of pages changed in a given time # period expressed in MiB/s. The following methods of calculation are @@ -2240,7 +2236,7 @@ ## # @query-dirty-rate: # -# Query results of the most recent invocation of @calc-dirty-rate. +# Query results of the most recent invocation of `calc-dirty-rate`. # # @calc-time-unit: time unit in which to report calculation time. # By default it is reported in seconds. (Since 8.2) @@ -2290,7 +2286,7 @@ # # Requires KVM with accelerator property "dirty-ring-size" set. A # virtual CPU's dirty page rate is a measure of its memory load. To -# observe dirty page rates, use @calc-dirty-rate. +# observe dirty page rates, use `calc-dirty-rate`. # # @cpu-index: index of a virtual CPU, default is all. # @@ -2315,8 +2311,8 @@ # Cancel the upper limit of dirty page rate for virtual CPUs. # # Cancel the dirty page limit for the vCPU which has been set with -# set-vcpu-dirty-limit command. Note that this command requires -# support from dirty ring, same as the "set-vcpu-dirty-limit". +# `set-vcpu-dirty-limit` command. Note that this command requires +# support from dirty ring, same as the `set-vcpu-dirty-limit`. # # @cpu-index: index of a virtual CPU, default is all. # @@ -2373,8 +2369,6 @@ # # @deprecated: This command is deprecated with no replacement yet. # -# Returns: @MigrationThreadInfo -# # Since: 7.2 ## { 'command': 'query-migrationthreads', @@ -2475,7 +2469,7 @@ # time it takes to load the snapshot. # # It is strongly recommended that @devices contain all writable block -# device nodes that can have changed since the original @snapshot-save +# device nodes that can have changed since the original `snapshot-save` # command execution. # # .. qmp-example:: diff --git a/qapi/misc-arm.json b/qapi/misc-arm.json index f5341372f5..f921d740f1 100644 --- a/qapi/misc-arm.json +++ b/qapi/misc-arm.json @@ -30,14 +30,12 @@ ## # @query-gic-capabilities: # -# It will return a list of GICCapability objects that describe its +# It will return a list of `GICCapability` objects that describe its # capability bits. # # On non-ARM targets this command will report an error as the GIC # technology is not applicable. # -# Returns: a list of GICCapability objects. -# # Since: 2.6 # # .. qmp-example:: diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json index 5fefa0a484..c8c91a241c 100644 --- a/qapi/misc-i386.json +++ b/qapi/misc-i386.json @@ -6,9 +6,9 @@ ## # @rtc-reset-reinjection: # -# This command will reset the RTC interrupt reinjection backlog. Can -# be used if another mechanism to synchronize guest time is in effect, -# for example QEMU guest agent's guest-set-time command. +# Reset the RTC interrupt reinjection backlog. Can be used if another +# mechanism to synchronize guest time is in effect, for example QEMU +# guest agent's guest-set-time command. # # Use of this command is only applicable for x86 machines with an RTC, # and on other machines will silently return without performing any @@ -26,7 +26,7 @@ ## # @SevState: # -# An enumeration of SEV state information used during @query-sev. +# An enumeration of SEV state information used during `query-sev`. # # @uninit: The guest is uninitialized. # @@ -132,8 +132,6 @@ # @enabled field is set to 'false' and the state of all other fields # is unspecified. # -# Returns: @SevInfo -# # Since: 2.12 # # .. qmp-example:: @@ -165,7 +163,7 @@ # 'sev-guest' confidential virtualization object. The launch # measurement for SEV-SNP guests is only available within the guest. # -# Returns: The @SevLaunchMeasureInfo for the guest +# Returns: The guest's SEV guest launch measurement info # # Errors: # - If the launch measurement is unavailable, either due to an @@ -214,8 +212,6 @@ # # This is only supported on AMD X86 platforms with KVM enabled. # -# Returns: SevCapability objects. -# # Errors: # - If SEV is not available on the platform, GenericError # @@ -233,8 +229,7 @@ ## # @sev-inject-launch-secret: # -# This command injects a secret blob into memory of a SEV/SEV-ES -# guest. +# Inject a secret blob into a SEV/SEV-ES guest's memory. # # This is only valid on x86 machines configured with KVM and the # 'sev-guest' confidential virtualization object. SEV-SNP guests do @@ -272,7 +267,7 @@ ## # @query-sev-attestation-report: # -# This command is used to get the SEV attestation report. +# Get the SEV attestation report. # # This is only valid on x86 machines configured with KVM and the # 'sev-guest' confidential virtualization object. The attestation @@ -281,13 +276,10 @@ # @mnonce: a random 16 bytes value encoded in base64 (it will be # included in report) # -# Returns: SevAttestationReport objects. -# # Errors: -# - This will return an error if the attestation report is -# unavailable, either due to an invalid guest configuration -# or if the guest has not reached the required SEV state, -# GenericError +# - If the attestation report is unavailable, either due to an +# invalid guest configuration or because the guest has not +# reached the required SEV state, GenericError # # Since: 6.1 # @@ -345,8 +337,6 @@ # # Return information about configured SGX capabilities of guest # -# Returns: @SgxInfo -# # Since: 6.2 # # .. qmp-example:: @@ -364,8 +354,6 @@ # # Return information about SGX capabilities of host # -# Returns: @SgxInfo -# # Since: 6.2 # # .. qmp-example:: diff --git a/qapi/misc.json b/qapi/misc.json index 4b9e601cfa..28c641fe2f 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -3,7 +3,9 @@ # ## -# = Miscellanea +# *********** +# Miscellanea +# *********** ## { 'include': 'common.json' } @@ -21,7 +23,7 @@ # "@dbus-display" or the name of a character device (e.g. from # -chardev id=XXXX) # -# @fdname: file descriptor name previously passed via 'getfd' command +# @fdname: file descriptor name previously passed via `getfd` command # # @skipauth: whether to skip authentication. Only applies to "vnc" # and "spice" protocols @@ -56,8 +58,6 @@ # # Return the name information of a guest. # -# Returns: @NameInfo of the guest -# # Since: 0.14 # # .. qmp-example:: @@ -107,7 +107,7 @@ # declared using the ``-object iothread`` command-line option. It # is always the main thread of the process. # -# Returns: a list of @IOThreadInfo for each iothread +# Returns: a list of info for each iothread # # Since: 2.0 # @@ -228,7 +228,7 @@ # Known limitations: # # * This command is stateless, this means that commands that depend -# on state information (such as getfd) might not work. +# on state information (such as `getfd`) might not work. # # * Commands that prompt the user for data don't currently work. # @@ -255,7 +255,7 @@ # .. note:: If @fdname already exists, the file descriptor assigned to # it will be closed and replaced by the received file descriptor. # -# The 'closefd' command can be used to explicitly close the file +# The `closefd` command can be used to explicitly close the file # descriptor when it is no longer needed. # # .. qmp-example:: @@ -282,7 +282,7 @@ # .. note:: If @fdname already exists, the file descriptor assigned to # it will be closed and replaced by the received file descriptor. # -# The 'closefd' command can be used to explicitly close the file +# The `closefd` command can be used to explicitly close the file # descriptor when it is no longer needed. # # .. qmp-example:: @@ -332,9 +332,6 @@ # # @opaque: A free-form string that can be used to describe the fd. # -# Returns: -# @AddfdInfo -# # Errors: # - If file descriptor was not received, GenericError # - If @fdset-id is a negative value, GenericError @@ -415,8 +412,6 @@ # # Return information describing all fd sets. # -# Returns: A list of @FdsetInfo -# # Since: 1.2 # # .. note:: The list of fd sets is shared by all monitor connections. @@ -480,7 +475,7 @@ # # @name: parameter name # -# @type: parameter @CommandLineParameterType +# @type: parameter `CommandLineParameterType` # # @help: human readable text string, not suitable for parsing. # @@ -502,7 +497,7 @@ # # @option: option name # -# @parameters: an array of @CommandLineParameterInfo +# @parameters: an array of `CommandLineParameterInfo` # # Since: 1.5 ## @@ -516,8 +511,7 @@ # # @option: option name # -# Returns: list of @CommandLineOptionInfo for all options (or for the -# given @option). +# Returns: list of objects for all options (or for the given @option). # # Errors: # - if the given @option doesn't exist diff --git a/qapi/net.json b/qapi/net.json index 97ea183981..78bcc9871e 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -3,7 +3,9 @@ # ## -# = Net devices +# *********** +# Net devices +# *********** ## { 'include': 'sockets.json' } @@ -113,6 +115,119 @@ 'str': 'str' } } ## +# @NetDevPasstOptions: +# +# Unprivileged user-mode network connectivity using passt +# +# @path: Filename of the passt program to run (by default 'passt', and use PATH) +# +# @quiet: don't print informational messages (default, passed as '--quiet') +# +# @vhost-user: enable vhost-user +# +# @mtu: assign MTU via DHCP/NDP +# +# @address: IPv4 or IPv6 address +# +# @netmask: IPv4 mask +# +# @mac: source MAC address +# +# @gateway: IPv4 or IPv6 address as gateway +# +# @interface: interface for addresses and routes +# +# @outbound: bind to address as outbound source +# +# @outbound-if4: bind to outbound interface for IPv4 +# +# @outbound-if6: bind to outbound interface for IPv6 +# +# @dns: IPv4 or IPv6 address as DNS +# +# @search: search domains +# +# @fqdn: FQDN to configure client with +# +# @dhcp-dns: enable/disable DNS list in DHCP/DHCPv6/NDP +# +# @dhcp-search: enable/disable list in DHCP/DHCPv6/NDP +# +# @map-host-loopback: addresse to refer to host +# +# @map-guest-addr: addr to translate to guest's address +# +# @dns-forward: forward DNS queries sent to +# +# @dns-host: host nameserver to direct queries to +# +# @tcp: enable/disable TCP +# +# @udp: enable/disable UDP +# +# @icmp: enable/disable ICMP +# +# @dhcp: enable/disable DHCP +# +# @ndp: enable/disable NDP +# +# @dhcpv6: enable/disable DHCPv6 +# +# @ra: enable/disable route advertisements +# +# @freebind: bind to any address for forwarding +# +# @ipv4: enable/disable IPv4 +# +# @ipv6: enable/disable IPv6 +# +# @tcp-ports: TCP ports to forward +# +# @udp-ports: UDP ports to forward +# +# @param: parameter to pass to passt command +# +# Since: 10.1 +## +{ 'struct': 'NetDevPasstOptions', + 'data': { + '*path': 'str', + '*quiet': 'bool', + '*vhost-user': 'bool', + '*mtu': 'int', + '*address': 'str', + '*netmask': 'str', + '*mac': 'str', + '*gateway': 'str', + '*interface': 'str', + '*outbound': 'str', + '*outbound-if4': 'str', + '*outbound-if6': 'str', + '*dns': 'str', + '*search': ['String'], + '*fqdn': 'str', + '*dhcp-dns': 'bool', + '*dhcp-search': 'bool', + '*map-host-loopback': 'str', + '*map-guest-addr': 'str', + '*dns-forward': 'str', + '*dns-host': 'str', + '*tcp': 'bool', + '*udp': 'bool', + '*icmp': 'bool', + '*dhcp': 'bool', + '*ndp': 'bool', + '*dhcpv6': 'bool', + '*ra': 'bool', + '*freebind': 'bool', + '*ipv4': 'bool', + '*ipv6': 'bool', + '*tcp-ports': ['String'], + '*udp-ports': ['String'], + '*param': ['String'] }, + 'if': 'CONFIG_PASST' } + +## # @NetdevUserOptions: # # Use the user mode network stack which requires no administrator @@ -454,25 +569,34 @@ # (default: 0). # # @inhibit: Don't load a default XDP program, use one already loaded -# to the interface (default: false). Requires @sock-fds. +# to the interface (default: false). Requires @sock-fds or @map-path. # # @sock-fds: A colon (:) separated list of file descriptors for # already open but not bound AF_XDP sockets in the queue order. # One fd per queue. These descriptors should already be added -# into XDP socket map for corresponding queues. Requires -# @inhibit. +# into XDP socket map for corresponding queues. @sock-fds and +# @map-path are mutually exclusive. Requires @inhibit. +# +# @map-path: The path to a pinned xsk map to push file descriptors +# for bound AF_XDP sockets into. @map-path and @sock-fds are +# mutually exclusive. Requires @inhibit. (Since 10.1) +# +# @map-start-index: Use @map-path to insert xsk sockets starting from +# this index number (default: 0). Requires @map-path. (Since 10.1) # # Since: 8.2 ## { 'struct': 'NetdevAFXDPOptions', 'data': { - 'ifname': 'str', - '*mode': 'AFXDPMode', - '*force-copy': 'bool', - '*queues': 'int', - '*start-queue': 'int', - '*inhibit': 'bool', - '*sock-fds': 'str' }, + 'ifname': 'str', + '*mode': 'AFXDPMode', + '*force-copy': 'bool', + '*queues': 'int', + '*start-queue': 'int', + '*inhibit': 'bool', + '*sock-fds': 'str', + '*map-path': 'str', + '*map-start-index': 'int32' }, 'if': 'CONFIG_AF_XDP' } ## @@ -655,7 +779,7 @@ # this to zero disables this function. This member is mutually # exclusive with @reconnect. (default: 0) (Since: 9.2) # -# Only SocketAddress types 'unix', 'inet' and 'fd' are supported. +# Only `SocketAddress` types 'unix', 'inet' and 'fd' are supported. # # Features: # @@ -680,7 +804,7 @@ # # @local: local address # -# Only SocketAddress types 'unix', 'inet' and 'fd' are supported. +# Only `SocketAddress` types 'unix', 'inet' and 'fd' are supported. # # If remote address is present and it's a multicast address, local # address is optional. Otherwise local address is required and remote @@ -729,12 +853,15 @@ # # @af-xdp: since 8.2 # +# @passt: since 10.1 +# # Since: 2.7 ## { 'enum': 'NetClientDriver', 'data': [ 'none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'stream', 'dgram', 'vde', 'bridge', 'hubport', 'netmap', 'vhost-user', 'vhost-vdpa', + { 'name': 'passt', 'if': 'CONFIG_PASST' }, { 'name': 'af-xdp', 'if': 'CONFIG_AF_XDP' }, { 'name': 'vmnet-host', 'if': 'CONFIG_VMNET' }, { 'name': 'vmnet-shared', 'if': 'CONFIG_VMNET' }, @@ -756,6 +883,8 @@ 'discriminator': 'type', 'data': { 'nic': 'NetLegacyNicOptions', + 'passt': { 'type': 'NetDevPasstOptions', + 'if': 'CONFIG_PASST' }, 'user': 'NetdevUserOptions', 'tap': 'NetdevTapOptions', 'l2tpv3': 'NetdevL2TPv3Options', @@ -845,7 +974,7 @@ # # @name: net client name # -# Returns: list of @RxFilterInfo for all NICs (or for the given NIC). +# Returns: list of info for all NICs (or for the given NIC). # # Errors: # - if the given @name doesn't exist @@ -890,7 +1019,7 @@ ## # @NIC_RX_FILTER_CHANGED: # -# Emitted once until the 'query-rx-filter' command is executed, the +# Emitted once until the `query-rx-filter` command is executed, the # first event will always be emitted # # @name: net client name diff --git a/qapi/pci.json b/qapi/pci.json index dc85a41d28..694c741e42 100644 --- a/qapi/pci.json +++ b/qapi/pci.json @@ -6,7 +6,9 @@ # SPDX-License-Identifier: GPL-2.0-or-later ## -# = PCI +# *** +# PCI +# *** ## ## @@ -83,7 +85,7 @@ # # @bus: information about the bus the device resides on # -# @devices: a list of @PciDeviceInfo for each device on this bridge +# @devices: a list of `PciDeviceInfo` for each device on this bridge # # Since: 0.14 ## @@ -175,7 +177,7 @@ # # Return information about the PCI bus topology of the guest. # -# Returns: a list of @PciInfo for each PCI bus. Each bus is +# Returns: a list of info for each PCI bus. Each bus is # represented by a json-object, which has a key with a json-array # of all PCI devices attached to it. Each device is represented # by a json-object. diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index 0477696ff0..82f111ba06 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -1,7 +1,9 @@ # -*- Mode: Python -*- # vim: filetype=python ## -# = Introduction +# ************ +# Introduction +# ************ # # This manual describes the commands and events supported by the QEMU # Monitor Protocol (QMP). diff --git a/qapi/qdev.json b/qapi/qdev.json index 32c7d10046..e14a0c9259 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -5,7 +5,9 @@ # See the COPYING file in the top-level directory. ## -# = Device infrastructure (qdev) +# **************************** +# Device infrastructure (qdev) +# **************************** ## { 'include': 'qom.json' } @@ -17,8 +19,7 @@ # # @typename: the type name of a device # -# Returns: a list of ObjectPropertyInfo describing a devices -# properties +# Returns: a list describing a devices properties # # .. note:: Objects can create properties at runtime, for example to # describe links between different devices and/or objects. These @@ -96,10 +97,10 @@ # from the guest. Hot removal is an operation that requires guest # cooperation. This command merely requests that the guest begin # the hot removal process. Completion of the device removal -# process is signaled with a DEVICE_DELETED event. Guest reset +# process is signaled with a `DEVICE_DELETED` event. Guest reset # will automatically complete removal for all devices. If a # guest-side error in the hot removal process is detected, the -# device will not be removed and a DEVICE_UNPLUG_GUEST_ERROR event +# device will not be removed and a `DEVICE_UNPLUG_GUEST_ERROR` event # is sent. Some errors cannot be detected. # # Since: 0.14 diff --git a/qapi/qom.json b/qapi/qom.json index b133b06447..96d56df6cd 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -10,7 +10,9 @@ { 'include': 'crypto.json' } ## -# = QEMU Object Model (QOM) +# *********************** +# QEMU Object Model (QOM) +# *********************** ## ## @@ -48,14 +50,12 @@ ## # @qom-list: # -# This command will list any properties of a object given a path in -# the object model. +# List properties of a object given a path in the object model. # -# @path: the path within the object model. See @qom-get for a +# @path: the path within the object model. See `qom-get` for a # description of this parameter. # -# Returns: a list of @ObjectPropertyInfo that describe the properties -# of the object. +# Returns: a list that describe the properties of the object. # # Since: 1.2 # @@ -76,8 +76,7 @@ ## # @qom-get: # -# This command will get a property from a object model path and return -# the value. +# Get a property value. # # @path: The path within the object model. There are two forms of # supported paths--absolute and partial paths. @@ -128,14 +127,14 @@ ## # @qom-set: # -# This command will set a property from a object model path. +# Set a property value. # -# @path: see @qom-get for a description of this parameter +# @path: see `qom-get` for a description of this parameter # # @property: the property name to set # # @value: a value who's type is appropriate for the property type. -# See @qom-get for a description of type mapping. +# See `qom-get` for a description of type mapping. # # Since: 1.2 # @@ -154,7 +153,7 @@ ## # @ObjectTypeInfo: # -# This structure describes a search result from @qom-list-types +# This structure describes a search result from `qom-list-types` # # @name: the type name found in the search # @@ -171,15 +170,14 @@ ## # @qom-list-types: # -# This command will return a list of types given search parameters +# Return a list of types given search parameters. # # @implements: if specified, only return types that implement this # type name # # @abstract: if true, include abstract types in the results # -# Returns: a list of @ObjectTypeInfo or an empty list if no results -# are found +# Returns: a list of types, or an empty list if no results are found # # Since: 1.1 ## @@ -195,11 +193,12 @@ # # @typename: the type name of an object # +# # .. note:: Objects can create properties at runtime, for example to # describe links between different devices and/or objects. These # properties are not included in the output of this command. # -# Returns: a list of ObjectPropertyInfo describing object properties +# Returns: a list describing object properties # # Since: 2.12 ## @@ -789,7 +788,7 @@ # # Properties for x-remote-object objects. # -# @fd: file descriptor name previously passed via 'getfd' command +# @fd: file descriptor name previously passed via `getfd` command # # @devid: the id of the device to be associated with the file # descriptor @@ -818,7 +817,7 @@ # # Properties for iommufd objects. # -# @fd: file descriptor name previously passed via 'getfd' command, +# @fd: file descriptor name previously passed via `getfd` command, # which represents a pre-opened /dev/iommu. This allows the # iommufd object to be shared across several subsystems (VFIO, # VDPA, ...), and the file descriptor to be shared with other @@ -933,6 +932,19 @@ 'if': 'CONFIG_POSIX' } ## +# @IgvmCfgProperties: +# +# Properties common to objects that handle IGVM files. +# +# @file: IGVM file to use to configure guest +# +# Since: 10.1 +## +{ 'struct': 'IgvmCfgProperties', + 'if': 'CONFIG_IGVM', + 'data': { 'file': 'str' } } + +## # @SevCommonProperties: # # Properties common to objects that are derivatives of sev-common. @@ -1142,6 +1154,8 @@ 'filter-redirector', 'filter-replay', 'filter-rewriter', + { 'name': 'igvm-cfg', + 'if': 'CONFIG_IGVM' }, 'input-barrier', { 'name': 'input-linux', 'if': 'CONFIG_LINUX' }, @@ -1218,6 +1232,8 @@ 'filter-redirector': 'FilterRedirectorProperties', 'filter-replay': 'NetfilterProperties', 'filter-rewriter': 'FilterRewriterProperties', + 'igvm-cfg': { 'type': 'IgvmCfgProperties', + 'if': 'CONFIG_IGVM' }, 'input-barrier': 'InputBarrierProperties', 'input-linux': { 'type': 'InputLinuxProperties', 'if': 'CONFIG_LINUX' }, @@ -1261,7 +1277,7 @@ # Create a QOM object. # # Errors: -# - Error if @qom-type is not a valid class name +# - If @qom-type is not a valid class name # # Since: 2.0 # @@ -1283,7 +1299,7 @@ # @id: the name of the QOM object to remove # # Errors: -# - Error if @id is not a valid id for a QOM object +# - If @id is not a valid id for a QOM object # # Since: 2.0 # diff --git a/qapi/replay.json b/qapi/replay.json index 35e0c4a692..ccf84da68e 100644 --- a/qapi/replay.json +++ b/qapi/replay.json @@ -3,7 +3,9 @@ # ## -# = Record/replay +# ************* +# Record/replay +# ************* ## { 'include': 'common.json' } @@ -47,8 +49,8 @@ # @query-replay: # # Retrieve the record/replay information. It includes current -# instruction count which may be used for @replay-break and -# @replay-seek commands. +# instruction count which may be used for `replay-break` and +# `replay-seek` commands. # # Returns: record/replay information. # @@ -70,7 +72,7 @@ # breakpoint. When breakpoint is set, any prior one is removed. The # breakpoint may be set only in replay mode and only "in the future", # i.e. at instruction counts greater than the current one. The -# current instruction count can be observed with @query-replay. +# current instruction count can be observed with `query-replay`. # # @icount: instruction count to stop at # @@ -86,7 +88,7 @@ ## # @replay-delete-break: # -# Remove replay breakpoint which was set with @replay-break. The +# Remove replay breakpoint which was set with `replay-break`. The # command is ignored when there are no replay breakpoints. # # Since: 5.2 @@ -106,7 +108,7 @@ # snapshot and replays the execution to find the desired instruction. # When there is no preceding snapshot or the execution is not # replayed, then the command fails. Instruction count can be obtained -# with the @query-replay command. +# with the `query-replay` command. # # @icount: target instruction count # diff --git a/qapi/rocker.json b/qapi/rocker.json index 0c7ef1f77c..5d2dbd2603 100644 --- a/qapi/rocker.json +++ b/qapi/rocker.json @@ -2,7 +2,9 @@ # vim: filetype=python ## -# = Rocker switch device +# ******************** +# Rocker switch device +# ******************** ## ## @@ -28,8 +30,6 @@ # # @name: switch name # -# Returns: @Rocker information -# # Since: 2.4 # # .. qmp-example:: @@ -98,8 +98,6 @@ # # @name: port name # -# Returns: a list of @RockerPort information -# # Since: 2.4 # # .. qmp-example:: diff --git a/qapi/run-state.json b/qapi/run-state.json index fd09beb35c..54ba5c9a3f 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -3,7 +3,9 @@ # ## -# = VM run state +# ************ +# VM run state +# ************ ## ## @@ -68,9 +70,9 @@ # # @host-error: An error prevents further use of guest # -# @host-qmp-quit: Reaction to the QMP command 'quit' +# @host-qmp-quit: Reaction to the QMP command `quit` # -# @host-qmp-system-reset: Reaction to the QMP command 'system_reset' +# @host-qmp-system-reset: Reaction to the QMP command `system_reset` # # @host-signal: Reaction to a signal, such as SIGINT # @@ -106,7 +108,7 @@ # # @running: true if all VCPUs are runnable, false if not runnable # -# @status: the virtual machine @RunState +# @status: the virtual machine `RunState` # # Since: 0.14 ## @@ -119,8 +121,6 @@ # # Query the run status of the VM # -# Returns: @StatusInfo reflecting the VM -# # Since: 0.14 # # .. qmp-example:: @@ -143,12 +143,12 @@ # hardware-specific action) rather than a host request (such as # sending QEMU a SIGINT). (since 2.10) # -# @reason: The @ShutdownCause which resulted in the SHUTDOWN. +# @reason: The `ShutdownCause` which resulted in the `SHUTDOWN`. # (since 4.0) # # .. note:: If the command-line option ``-no-shutdown`` has been -# specified, QEMU will not exit, and a STOP event will eventually -# follow the SHUTDOWN event. +# specified, QEMU will not exit, and a `STOP` event will eventually +# follow the `SHUTDOWN` event. # # Since: 0.12 # @@ -183,9 +183,9 @@ # @guest: If true, the reset was triggered by a guest request (such as # a guest-initiated ACPI reboot request or other hardware-specific # action) rather than a host request (such as the QMP command -# system_reset). (since 2.10) +# `system_reset`). (since 2.10) # -# @reason: The @ShutdownCause of the RESET. (since 4.0) +# @reason: The `ShutdownCause` of the `RESET`. (since 4.0) # # Since: 0.12 # @@ -247,7 +247,7 @@ # saved on disk, for example, S4 state, which is sometimes called # hibernate state # -# .. note:: QEMU shuts down (similar to event @SHUTDOWN) when entering +# .. note:: QEMU shuts down (similar to event `SHUTDOWN`) when entering # this state. # # Since: 1.2 @@ -281,8 +281,8 @@ # # @action: action that has been taken # -# .. note:: If action is "reset", "shutdown", or "pause" the WATCHDOG -# event is followed respectively by the RESET, SHUTDOWN, or STOP +# .. note:: If action is "reset", "shutdown", or "pause" the `WATCHDOG` +# event is followed respectively by the `RESET`, `SHUTDOWN`, or `STOP` # events. # # .. note:: This event is rate-limited. @@ -378,7 +378,7 @@ # # Set watchdog action. # -# @action: @WatchdogAction action taken when watchdog timer expires. +# @action: `WatchdogAction` action taken when watchdog timer expires. # # Since: 2.11 # @@ -396,13 +396,13 @@ # Set the actions that will be taken by the emulator in response to # guest events. # -# @reboot: @RebootAction action taken on guest reboot. +# @reboot: `RebootAction` action taken on guest reboot. # -# @shutdown: @ShutdownAction action taken on guest shutdown. +# @shutdown: `ShutdownAction` action taken on guest shutdown. # -# @panic: @PanicAction action taken on guest panic. +# @panic: `PanicAction` action taken on guest panic. # -# @watchdog: @WatchdogAction action taken when watchdog timer expires. +# @watchdog: `WatchdogAction` action taken when watchdog timer expires. # # Since: 6.0 # @@ -529,20 +529,20 @@ # # Hyper-V specific guest panic information (HV crash MSRs) # -# @arg1: for Windows, STOP code for the guest crash. For Linux, +# @arg1: for Windows, `STOP` code for the guest crash. For Linux, # an error code. # -# @arg2: for Windows, first argument of the STOP. For Linux, the +# @arg2: for Windows, first argument of the `STOP`. For Linux, the # guest OS ID, which has the kernel version in bits 16-47 and # 0x8100 in bits 48-63. # -# @arg3: for Windows, second argument of the STOP. For Linux, the +# @arg3: for Windows, second argument of the `STOP`. For Linux, the # program counter of the guest. # -# @arg4: for Windows, third argument of the STOP. For Linux, the +# @arg4: for Windows, third argument of the `STOP`. For Linux, the # RAX register (x86) or the stack pointer (aarch64) of the guest. # -# @arg5: for Windows, fourth argument of the STOP. For x86 Linux, the +# @arg5: for Windows, fourth argument of the `STOP`. For x86 Linux, the # stack pointer of the guest. # # Since: 2.9 @@ -630,11 +630,11 @@ # # Emitted when a memory failure occurs on host side. # -# @recipient: recipient is defined as @MemoryFailureRecipient. +# @recipient: recipient is defined as `MemoryFailureRecipient`. # # @action: action that has been taken. # -# @flags: flags for MemoryFailureAction. +# @flags: flags for `MemoryFailureAction`. # # Since: 5.2 # diff --git a/qapi/sockets.json b/qapi/sockets.json index f9f559daba..82046b0b3a 100644 --- a/qapi/sockets.json +++ b/qapi/sockets.json @@ -2,7 +2,9 @@ # vim: filetype=python ## -# = Socket data types +# ***************** +# Socket data types +# ***************** ## ## @@ -209,14 +211,14 @@ 'unix': 'UnixSocketAddressWrapper', 'vsock': 'VsockSocketAddressWrapper', 'fd': 'FdSocketAddressWrapper' } } -# Note: This type is deprecated in favor of SocketAddress. The -# difference between SocketAddressLegacy and SocketAddress is that the +# Note: This type is deprecated in favor of `SocketAddress`. The +# difference between `SocketAddressLegacy` and `SocketAddress` is that the # latter has fewer ``{}`` on the wire. ## # @SocketAddressType: # -# Available SocketAddress types +# Available `SocketAddress` types # # @inet: Internet address # diff --git a/qapi/stats.json b/qapi/stats.json index 8902ef94e0..151ac43c48 100644 --- a/qapi/stats.json +++ b/qapi/stats.json @@ -9,7 +9,9 @@ # SPDX-License-Identifier: GPL-2.0-or-later ## -# = Statistics +# ********** +# Statistics +# ********** ## ## @@ -87,7 +89,7 @@ # @StatsRequest: # # Indicates a set of statistics that should be returned by -# query-stats. +# `query-stats`. # # @provider: provider for which to return statistics. # @@ -112,7 +114,7 @@ ## # @StatsFilter: # -# The arguments to the query-stats command; specifies a target for +# The arguments to the `query-stats` command; specifies a target for # which to request statistics and optionally the required subset of # information for that target. # @@ -183,10 +185,10 @@ # Return runtime-collected statistics for objects such as the VM or # its vCPUs. # -# The arguments are a StatsFilter and specify the provider and objects +# The arguments are a `StatsFilter` and specify the provider and objects # to return statistics about. # -# Returns: a list of StatsResult, one for each provider and object +# Returns: a list of statistics, one for each provider and object # (e.g., for each vCPU). # # Since: 7.1 @@ -203,7 +205,7 @@ # # @name: name of the statistic; each element of the schema is uniquely # identified by a target, a provider (both available in -# @StatsSchema) and the name. +# `StatsSchema`) and the name. # # @type: kind of statistic. # diff --git a/qapi/tpm.json b/qapi/tpm.json index a16a72edb9..3f2850a573 100644 --- a/qapi/tpm.json +++ b/qapi/tpm.json @@ -3,7 +3,9 @@ # ## -# = TPM (trusted platform module) devices +# ************************************* +# TPM (trusted platform module) devices +# ************************************* ## ## @@ -27,8 +29,6 @@ # # Return a list of supported TPM models # -# Returns: a list of TpmModel -# # Since: 1.5 # # .. qmp-example:: @@ -58,8 +58,6 @@ # # Return a list of supported TPM types # -# Returns: a list of TpmType -# # Since: 1.5 # # .. qmp-example:: diff --git a/qapi/trace.json b/qapi/trace.json index eb5f63f513..de369dae6b 100644 --- a/qapi/trace.json +++ b/qapi/trace.json @@ -7,7 +7,9 @@ # See the COPYING file in the top-level directory. ## -# = Tracing +# ******* +# Tracing +# ******* ## ## @@ -47,7 +49,7 @@ # # @name: Event name pattern (case-sensitive glob). # -# Returns: a list of @TraceEventInfo for the matching events +# Returns: a list of info for the matching events # # Since: 2.2 # diff --git a/qapi/transaction.json b/qapi/transaction.json index 9d9e7af26c..4b4eb09bf3 100644 --- a/qapi/transaction.json +++ b/qapi/transaction.json @@ -3,7 +3,9 @@ # ## -# = Transactions +# ************ +# Transactions +# ************ ## { 'include': 'block-core.json' } @@ -67,8 +69,8 @@ # # Features: # -# @deprecated: Member @drive-backup is deprecated. Use member -# @blockdev-backup instead. +# @deprecated: Member `drive-backup` is deprecated. Use member +# `blockdev-backup` instead. # # Since: 1.1 ## @@ -156,7 +158,7 @@ # @TransactionAction: # # A discriminated record of operations that can be performed with -# @transaction. +# `transaction`. # # @type: the operation to be performed # @@ -187,7 +189,7 @@ # # @completion-mode: Controls how jobs launched asynchronously by # Actions will complete or fail as a group. See -# @ActionCompletionMode for details. +# `ActionCompletionMode` for details. # # Since: 2.5 ## @@ -227,11 +229,11 @@ # in the transaction. When an I/O error occurs during deletion, the # user needs to fix it later with qemu-img or other command. # -# @actions: List of @TransactionAction; information needed for the +# @actions: List of `TransactionAction`; information needed for the # respective operations. # # @properties: structure of additional options to control the -# execution of the transaction. See @TransactionProperties for +# execution of the transaction. See `TransactionProperties` for # additional detail. # # Errors: diff --git a/qapi/uefi.json b/qapi/uefi.json index 6592183d6c..a206c2e953 100644 --- a/qapi/uefi.json +++ b/qapi/uefi.json @@ -3,7 +3,9 @@ # ## -# = UEFI Variable Store +# ******************* +# UEFI Variable Store +# ******************* # # The QEMU efi variable store implementation (hw/uefi/) uses this to # store non-volatile variables in json format on disk. diff --git a/qapi/ui.json b/qapi/ui.json index 514fa159b1..1b2f4a4769 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -3,7 +3,9 @@ # ## -# = Remote desktop +# ************** +# Remote desktop +# ************** ## { 'include': 'common.json' } @@ -39,7 +41,7 @@ ## # @SetPasswordOptions: # -# Options for set_password. +# Options for `set_password`. # # @protocol: # - 'vnc' to modify the VNC server password @@ -63,7 +65,7 @@ ## # @SetPasswordOptionsVnc: # -# Options for set_password specific to the VNC protocol. +# Options for `set_password` specific to the VNC protocol. # # @display: The id of the display where the password should be # changed. Defaults to the first. @@ -94,7 +96,7 @@ ## # @ExpirePasswordOptions: # -# General options for expire_password. +# General options for `expire_password`. # # @protocol: # - 'vnc' to modify the VNC server expiration @@ -124,7 +126,7 @@ ## # @ExpirePasswordOptionsVnc: # -# Options for expire_password specific to the VNC protocol. +# Options for `expire_password` specific to the VNC protocol. # # @display: The id of the display where the expiration should be # changed. Defaults to the first. @@ -183,7 +185,7 @@ # the head can only be specified in conjunction with the device # ID. (Since 2.12) # -# @format: image format for screendump. (default: ppm) (Since 7.1) +# @format: image format for `screendump`. (default: ppm) (Since 7.1) # # Since: 0.14 # @@ -200,7 +202,8 @@ 'if': 'CONFIG_PIXMAN' } ## -# == Spice +# Spice +# ===== ## ## @@ -310,7 +313,7 @@ # unknown if spice server doesn't provide this information. # (since: 1.1) # -# @channels: a list of @SpiceChannel for each active spice channel +# @channels: a list of `SpiceChannel` for each active spice channel # # Since: 0.14 ## @@ -325,8 +328,6 @@ # # Return information about the current SPICE server # -# Returns: @SpiceInfo -# # Since: 0.14 # # .. qmp-example:: @@ -461,7 +462,8 @@ 'if': 'CONFIG_SPICE' } ## -# == VNC +# VNC +# === ## ## @@ -561,7 +563,7 @@ # - 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL # auth # -# @clients: a list of @VncClientInfo of all currently connected +# @clients: a list of `VncClientInfo` of all currently connected # clients # # Since: 0.14 @@ -624,12 +626,12 @@ # # @id: vnc server name. # -# @server: A list of @VncBasincInfo describing all listening sockets. +# @server: A list of `VncBasicInfo` describing all listening sockets. # The list can be empty (in case the vnc server is disabled). It # also may have multiple entries: normal + websocket, possibly # also ipv4 + ipv6 in the future. # -# @clients: A list of @VncClientInfo of all currently connected +# @clients: A list of `VncClientInfo` of all currently connected # clients. The list can be empty, for obvious reasons. # # @auth: The current authentication type used by the non-websockets @@ -656,8 +658,6 @@ # # Return information about the current VNC server # -# Returns: @VncInfo -# # Since: 0.14 # # .. qmp-example:: @@ -687,8 +687,6 @@ # # Return a list of vnc servers. The list can be empty. # -# Returns: a list of @VncInfo2 -# # Since: 2.3 ## { 'command': 'query-vnc-servers', 'returns': ['VncInfo2'], @@ -794,7 +792,9 @@ 'if': 'CONFIG_VNC' } ## -# = Input +# ***** +# Input +# ***** ## ## @@ -822,7 +822,7 @@ # # Return information about each active mouse device # -# Returns: a list of @MouseInfo for each device +# Returns: a list of info for each device # # Since: 0.14 # @@ -852,7 +852,7 @@ # # An enumeration of key name. # -# This is used by the @send-key command. +# This is used by the `send-key` command. # # @unmapped: since 2.0 # @@ -1023,10 +1023,10 @@ # # Send keys to guest. # -# @keys: An array of @KeyValue elements. All @KeyValues in this array -# are simultaneously sent to the guest. A @KeyValue.number value -# is sent directly to the guest, while @KeyValue.qcode must be a -# valid @QKeyCode value +# @keys: An array of `KeyValue` elements. All @KeyValues in this array +# are simultaneously sent to the guest. A `KeyValue`.number value +# is sent directly to the guest, while `KeyValue`.qcode must be a +# valid `QKeyCode` value # # @hold-time: time to delay key up events, milliseconds. Defaults to # 100 @@ -1263,7 +1263,7 @@ # @head: head to send event(s) to, in case the display device supports # multiple scanouts. # -# @events: List of InputEvent union. +# @events: List of `InputEvent` union. # # Since: 2.6 # @@ -1335,13 +1335,20 @@ # @show-menubar: Display the main window menubar. Defaults to "on". # (Since 8.0) # +# @keep-aspect-ratio: Keep width/height aspect ratio of guest content when +# resizing host window. Defaults to "on". (Since 10.1) +# +# @scale: Set preferred scale of the display. Defaults to 1.0. (Since 10.1) +# # Since: 2.12 ## { 'struct' : 'DisplayGTK', - 'data' : { '*grab-on-hover' : 'bool', - '*zoom-to-fit' : 'bool', - '*show-tabs' : 'bool', - '*show-menubar' : 'bool' } } + 'data' : { '*grab-on-hover' : 'bool', + '*zoom-to-fit' : 'bool', + '*show-tabs' : 'bool', + '*show-menubar' : 'bool', + '*keep-aspect-ratio' : 'bool', + '*scale' : 'number' } } ## # @DisplayEGLHeadless: @@ -1367,7 +1374,7 @@ # first available node on the host. # # @p2p: Whether to use peer-to-peer connections (accepted through -# @add_client). +# `add_client`). # # @audiodev: Use the specified DBus audiodev to export audio. # @@ -1526,7 +1533,7 @@ # # Display (user interface) options. # -# @type: Which DisplayType QEMU should use. +# @type: Which `DisplayType` QEMU should use. # # @full-screen: Start user interface in fullscreen mode # (default: off). @@ -1564,8 +1571,6 @@ # # Return information about display configuration # -# Returns: @DisplayOptions -# # Since: 3.1 ## { 'command': 'query-display-options', diff --git a/qapi/vfio.json b/qapi/vfio.json index b53b7caecd..a1a9c5b673 100644 --- a/qapi/vfio.json +++ b/qapi/vfio.json @@ -3,7 +3,9 @@ # ## -# = VFIO devices +# ************ +# VFIO devices +# ************ ## ## diff --git a/qapi/virtio.json b/qapi/virtio.json index 73df718a26..9d652fe4a8 100644 --- a/qapi/virtio.json +++ b/qapi/virtio.json @@ -3,7 +3,9 @@ # ## -# = Virtio devices +# ************** +# Virtio devices +# ************** ## ## @@ -135,7 +137,7 @@ # @num-vqs: VirtIODevice virtqueue count. This is the number of # active virtqueues being used by the VirtIODevice. # -# @status: VirtIODevice configuration status (VirtioDeviceStatus) +# @status: VirtIODevice configuration status (`VirtioDeviceStatus`) # # @isr: VirtIODevice ISR # @@ -199,7 +201,7 @@ # # @unstable: This command is meant for debugging. # -# Returns: VirtioStatus of the virtio device +# Returns: Status of the virtio device # # Since: 7.2 # @@ -563,7 +565,7 @@ # # @unstable: This command is meant for debugging. # -# Returns: VirtQueueStatus of the VirtQueue +# Returns: Status of the queue # # .. note:: last_avail_idx will not be displayed in the case where the # selected VirtIODevice has a running vhost device and the @@ -577,7 +579,7 @@ # .. qmp-example:: # :annotated: # -# Get VirtQueueStatus for virtio-vsock (vhost-vsock running) +# Get `VirtQueueStatus` for virtio-vsock (vhost-vsock running) # :: # # -> { "execute": "x-query-virtio-queue-status", @@ -604,7 +606,7 @@ # .. qmp-example:: # :annotated: # -# Get VirtQueueStatus for virtio-serial (no vhost) +# Get `VirtQueueStatus` for virtio-serial (no vhost) # :: # # -> { "execute": "x-query-virtio-queue-status", @@ -698,7 +700,7 @@ # # @unstable: This command is meant for debugging. # -# Returns: VirtVhostQueueStatus of the vhost_virtqueue +# Returns: Status of the vhost_virtqueue # # Since: 7.2 # @@ -816,7 +818,7 @@ # # @index: Index of the element in the queue # -# @descs: List of descriptors (VirtioRingDesc) +# @descs: List of descriptors (`VirtioRingDesc`) # # @avail: VRingAvail info # @@ -847,8 +849,6 @@ # # @unstable: This command is meant for debugging. # -# Returns: VirtioQueueElement information -# # Since: 7.2 # # .. qmp-example:: @@ -964,16 +964,30 @@ 'data': { 'iothread': 'str', '*vqs': ['uint16'] } } ## +# @VirtIOGPUOutput: +# +# Describes configuration of a VirtIO GPU output. +# +# @name: the name of the output +# +# Since: 10.1 +## + +{ 'struct': 'VirtIOGPUOutput', + 'data': { 'name': 'str' } } + +## # @DummyVirtioForceArrays: # # Not used by QMP; hack to let us use IOThreadVirtQueueMappingList -# internally +# and VirtIOGPUOutputList internally # # Since: 9.0 ## { 'struct': 'DummyVirtioForceArrays', - 'data': { 'unused-iothread-vq-mapping': ['IOThreadVirtQueueMapping'] } } + 'data': { 'unused-iothread-vq-mapping': ['IOThreadVirtQueueMapping'], + 'unused-virtio-gpu-output': ['VirtIOGPUOutput'] } } ## # @GranuleMode: diff --git a/qapi/yank.json b/qapi/yank.json index 30f46c97c9..f3cd5c15d6 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -3,13 +3,15 @@ # ## -# = Yank feature +# ************ +# Yank feature +# ************ ## ## # @YankInstanceType: # -# An enumeration of yank instance types. See @YankInstance for more +# An enumeration of yank instance types. See `YankInstance` for more # information. # # Since: 6.0 @@ -20,7 +22,7 @@ ## # @YankInstanceBlockNode: # -# Specifies which block graph node to yank. See @YankInstance for +# Specifies which block graph node to yank. See `YankInstance` for # more information. # # @node-name: the name of the block graph node @@ -33,7 +35,7 @@ ## # @YankInstanceChardev: # -# Specifies which character device to yank. See @YankInstance for +# Specifies which character device to yank. See `YankInstance` for # more information. # # @id: the chardev's ID @@ -46,7 +48,7 @@ ## # @YankInstance: # -# A yank instance can be yanked with the @yank qmp command to recover +# A yank instance can be yanked with the `yank` qmp command to recover # from a hanging QEMU. # # @type: yank instance type @@ -57,9 +59,9 @@ # nbd server without attempting to reconnect. # - socket chardev: Yanking it will shut down the connected socket. # - migration: Yanking it will shut down all migration connections. -# Unlike @migrate_cancel, it will not notify the migration process, +# Unlike `migrate_cancel`, it will not notify the migration process, # so migration will go into @failed state, instead of @cancelled -# state. @yank should be used to recover from hangs. +# state. `yank` should be used to recover from hangs. # # Since: 6.0 ## @@ -74,7 +76,7 @@ # @yank: # # Try to recover from hanging QEMU by yanking the specified instances. -# See @YankInstance for more information. +# See `YankInstance` for more information. # # @instances: the instances to be yanked # @@ -100,9 +102,9 @@ ## # @query-yank: # -# Query yank instances. See @YankInstance for more information. +# Query yank instances. See `YankInstance` for more information. # -# Returns: list of @YankInstance +# TODO: This line is a hack to separate the example from the body # # .. qmp-example:: # |