diff options
Diffstat (limited to 'qapi')
46 files changed, 1863 insertions, 1462 deletions
diff --git a/qapi/accelerator.json b/qapi/accelerator.json new file mode 100644 index 0000000..fb28c8d --- /dev/null +++ b/qapi/accelerator.json @@ -0,0 +1,56 @@ +# -*- Mode: Python -*- +# vim: filetype=python +# +# SPDX-License-Identifier: GPL-2.0-or-later + +## +# ************ +# Accelerators +# ************ +## + +{ 'include': 'common.json' } + +## +# @KvmInfo: +# +# Information about support for KVM acceleration +# +# @enabled: true if KVM acceleration is active +# +# @present: true if KVM acceleration is built into this executable +# +# Since: 0.14 +## +{ 'struct': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} } + +## +# @query-kvm: +# +# Return information about KVM acceleration +# +# Since: 0.14 +# +# .. qmp-example:: +# +# -> { "execute": "query-kvm" } +# <- { "return": { "enabled": true, "present": true } } +## +{ 'command': 'query-kvm', 'returns': 'KvmInfo' } + +## +# @x-accel-stats: +# +# Query accelerator statistics +# +# Features: +# +# @unstable: This command is meant for debugging. +# +# Returns: accelerator statistics +# +# Since: 10.1 +## +{ 'command': 'x-accel-stats', + 'returns': 'HumanReadableText', + 'features': [ 'unstable' ] } diff --git a/qapi/acpi.json b/qapi/acpi.json index 045dab6..906b368 100644 --- a/qapi/acpi.json +++ b/qapi/acpi.json @@ -6,7 +6,9 @@ # SPDX-License-Identifier: GPL-2.0-or-later ## -# = ACPI +# **** +# ACPI +# **** ## ## @@ -80,7 +82,7 @@ ## # @ACPIOSTInfo: # -# OSPM Status Indication for a device For description of possible +# OSPM Status Indication for a device. For description of possible # values of @source and @status fields see "_OST (OSPM Status # Indication)" chapter of ACPI5.0 spec. # @@ -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 dd5a58d..5314208 100644 --- a/qapi/audio.json +++ b/qapi/audio.json @@ -7,7 +7,9 @@ # See the COPYING file in the top-level directory. ## -# = Audio +# ***** +# Audio +# ***** ## ## @@ -96,7 +98,7 @@ # @period-length: the period length in microseconds # # @try-poll: attempt to use poll mode, falling back to non-polling -# access on failure (default true) +# access on failure (default false) # # Since: 4.0 ## @@ -309,9 +311,9 @@ # # @name: name of the sink/source to use # -# @stream-name: name of the PulseAudio stream created by qemu. Can be +# @stream-name: name of the PulseAudio stream created by QEMU. Can be # used to identify the stream in PulseAudio when you create -# multiple PulseAudio devices or run multiple qemu instances +# multiple PulseAudio devices or run multiple QEMU instances # (default: audiodev's id, since 4.2) # # @latency: latency you want PulseAudio to achieve in microseconds @@ -353,9 +355,9 @@ # # @name: name of the sink/source to use # -# @stream-name: name of the PipeWire stream created by qemu. Can be +# @stream-name: name of the PipeWire stream created by QEMU. Can be # used to identify the stream in PipeWire when you create multiple -# PipeWire devices or run multiple qemu instances (default: +# PipeWire devices or run multiple QEMU instances (default: # audiodev's id) # # @latency: latency you want PipeWire to achieve in microseconds @@ -533,9 +535,7 @@ ## # @query-audiodevs: # -# Returns information about audiodev configuration -# -# Returns: array of @Audiodev +# Return information about audiodev configuration # # Since: 8.0 ## diff --git a/qapi/authz.json b/qapi/authz.json index 7fc6e30..bc1123c 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 b193778..ebbe95b 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,8 +32,8 @@ # @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 (since -# 5.2) +# 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,9 +500,11 @@ # @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) +# destination before it completes. (since: 10.0) # # @encrypted: true if the backing device is encrypted # @@ -510,11 +526,11 @@ # # @bps_max: total throughput limit during bursts, in bytes (Since 1.7) # -# @bps_rd_max: read throughput limit during bursts, in bytes (Since -# 1.7) +# @bps_rd_max: read throughput limit during bursts, in bytes +# (Since 1.7) # -# @bps_wr_max: write throughput limit during bursts, in bytes (Since -# 1.7) +# @bps_wr_max: write throughput limit during bursts, in bytes +# (Since 1.7) # # @iops_max: total I/O operations per second during bursts, in bytes # (Since 1.7) @@ -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 @@ -951,11 +968,11 @@ # @unmap_operations: The number of unmap operations performed by the # device (Since 4.2) # -# @rd_total_time_ns: Total time spent on reads in nanoseconds (since -# 0.15). +# @rd_total_time_ns: Total time spent on reads in nanoseconds +# (since 0.15) # -# @wr_total_time_ns: Total time spent on writes in nanoseconds (since -# 0.15). +# @wr_total_time_ns: Total time spent on writes in nanoseconds +# (since 0.15) # # @zone_append_total_time_ns: Total time spent on zone append writes # in nanoseconds (since 8.1) @@ -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. @@ -1322,8 +1339,8 @@ # @incremental: only copy data described by the dirty bitmap. # (since: 2.4) # -# @bitmap: only copy data described by the dirty bitmap. (since: 4.2) -# Behavior on completion is determined by the BitmapSyncMode. +# @bitmap: only copy data described by the dirty bitmap. Behavior on +# completion is determined by the `BitmapSyncMode`. (since: 4.2) # # Since: 1.3 ## @@ -1337,7 +1354,7 @@ # bitmap when used for data copy operations. # # @on-success: The bitmap is only synced when the operation is -# successful. This is the behavior always used for 'INCREMENTAL' +# successful. This is the behavior always used for incremental # backups. # # @never: The bitmap is never synchronized with the operation, and is @@ -1417,8 +1434,8 @@ # @auto-finalize: Job will finalize itself when PENDING, moving to the # CONCLUDED state. (since 2.12) # -# @auto-dismiss: Job will dismiss itself when CONCLUDED, moving to the -# NULL state and disappearing from the query list. (since 2.12) +# @auto-dismiss: Job will dismiss itself when CONCLUDED, and +# disappear. (since 2.12) # # @error: Error information if the job did not complete successfully. # Not set if the job completed successfully. (since 2.12.1) @@ -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 ## @@ -1502,15 +1519,15 @@ # # @device: the name of the device to take a snapshot of. # -# @node-name: graph node name to generate the snapshot from (Since -# 2.0) +# @node-name: graph node name to generate the snapshot from +# (Since 2.0) # # @snapshot-file: the target of the new overlay image. If the file # exists, or if it is a device, the overlay will be created in the # existing file/device. Otherwise, a new file will be created. # -# @snapshot-node-name: the graph node name of the new image (Since -# 2.0) +# @snapshot-node-name: the graph node name of the new image +# (Since 2.0) # # @format: the format of the overlay image, default is 'qcow2'. # @@ -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,34 +1602,36 @@ # @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 -# provided, Must NOT be present otherwise. (Since 4.2) +# provided, must **not** be present otherwise. (Since 4.2) # # @compress: true to compress data, if the target format supports it. # (default: false) (since 2.8) # # @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 # different block device than @device). # +# @on-cbw-error: policy defining behavior on I/O errors in +# 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 @block-job-finalize -# before making any block graph changes. When true, this job will +# 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 -# @block-job-dismiss. When true, this job will automatically -# disappear from the query list without user intervention. -# Defaults to true. (Since 2.12) +# `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 # filter driver that the backup job inserts into the graph above @@ -1641,6 +1660,7 @@ '*compress': 'bool', '*on-source-error': 'BlockdevOnError', '*on-target-error': 'BlockdevOnError', + '*on-cbw-error': 'OnCbwError', '*auto-finalize': 'bool', '*auto-dismiss': 'bool', '*filter-node-name': 'str', '*discard-source': 'bool', @@ -1716,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 # @@ -1781,8 +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 -# block-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 @@ -1836,7 +1855,7 @@ # @speed: the maximum speed, in bytes per second # # @on-error: the action to take on an error. 'ignore' means that the -# request should be retried. (default: report; Since: 5.0) +# request should be retried. (default: report; since: 5.0) # # @filter-node-name: the node name that should be assigned to the # filter driver that the commit job inserts into the graph above @@ -1844,16 +1863,15 @@ # autogenerated. (Since: 2.9) # # @auto-finalize: When false, this job will wait in a PENDING state -# after it has finished its work, waiting for @block-job-finalize -# before making any block graph changes. When true, this job will +# 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 -# @block-job-dismiss. When true, this job will automatically -# disappear from the query list without user intervention. -# Defaults to true. (Since 3.1) +# `job-dismiss`. When true, this job will automatically disappear +# without user intervention. Defaults to true. (Since 3.1) # # Features: # @@ -1888,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 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: @@ -1919,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 block-job-cancel command. +# using the `job-cancel` or `block-job-cancel` command. # # Errors: # - If @device is not a valid block device, DeviceNotFound @@ -1949,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:: @@ -2025,8 +2041,8 @@ # @XDbgBlockGraphNode: # # @id: Block graph node identifier. This @id is generated only for -# x-debug-query-block-graph and does not relate to any other -# identifiers in Qemu. +# `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 # or block-driver-state. @@ -2074,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 # @@ -2165,8 +2181,8 @@ # @format: the format of the new destination, default is to probe if # @mode is 'existing', else the format of the source # -# @node-name: the new block driver state node name in the graph (Since -# 2.1) +# @node-name: the new block driver state node name in the graph +# (Since 2.1) # # @replaces: with sync=full graph node name to be replaced by the new # image when a whole image copy is done. This can be used to @@ -2192,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 @@ -2208,16 +2224,15 @@ # 'background' (Since: 3.0) # # @auto-finalize: When false, this job will wait in a PENDING state -# after it has finished its work, waiting for @block-job-finalize -# before making any block graph changes. When true, this job will +# 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 -# @block-job-dismiss. When true, this job will automatically -# disappear from the query list without user intervention. -# Defaults to true. (Since 3.1) +# `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,16 +2539,20 @@ # 'background' (Since: 3.0) # # @auto-finalize: When false, this job will wait in a PENDING state -# after it has finished its work, waiting for @block-job-finalize -# before making any block graph changes. When true, this job will +# 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 -# @block-job-dismiss. When true, this job will automatically -# disappear from the query list without user intervention. -# Defaults to true. (Since 3.1) +# `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 +# the mirror started. Setting this to true can speed up the +# mirror. Setting this to true when the destination is not +# actually all zero can corrupt the destination. (Since 10.1) # # Since: 2.6 # @@ -2557,7 +2573,8 @@ '*on-target-error': 'BlockdevOnError', '*filter-node-name': 'str', '*copy-mode': 'MirrorCopyMode', - '*auto-finalize': 'bool', '*auto-dismiss': 'bool' }, + '*auto-finalize': 'bool', '*auto-dismiss': 'bool', + '*target-is-zero': 'bool'}, 'allow-preconfig': true } ## @@ -2583,11 +2600,11 @@ # # @bps_max: total throughput limit during bursts, in bytes (Since 1.7) # -# @bps_rd_max: read throughput limit during bursts, in bytes (Since -# 1.7) +# @bps_rd_max: read throughput limit during bursts, in bytes +# (Since 1.7) # -# @bps_wr_max: write throughput limit during bursts, in bytes (Since -# 1.7) +# @bps_wr_max: write throughput limit during bursts, in bytes +# (Since 1.7) # # @iops_max: total I/O operations per second during bursts, in bytes # (Since 1.7) @@ -2657,7 +2674,7 @@ # @iops-total-max: I/O operations burst # # @iops-total-max-length: length of the iops-total-max burst period, -# in seconds It must only be set if @iops-total-max is set as +# in seconds. It must only be set if @iops-total-max is set as # well. # # @iops-read: limit read operations per second @@ -2665,14 +2682,14 @@ # @iops-read-max: I/O operations read burst # # @iops-read-max-length: length of the iops-read-max burst period, in -# seconds It must only be set if @iops-read-max is set as well. +# seconds. It must only be set if @iops-read-max is set as well. # # @iops-write: limit write operations per second # # @iops-write-max: I/O operations write burst # # @iops-write-max-length: length of the iops-write-max burst period, -# in seconds It must only be set if @iops-write-max is set as +# in seconds. It must only be set if @iops-write-max is set as # well. # # @bps-total: limit total bytes per second @@ -2687,14 +2704,14 @@ # @bps-read-max: total bytes read burst # # @bps-read-max-length: length of the bps-read-max burst period, in -# seconds It must only be set if @bps-read-max is set as well. +# seconds. It must only be set if @bps-read-max is set as well. # # @bps-write: limit write bytes per second # # @bps-write-max: total bytes write burst # # @bps-write-max-length: length of the bps-write-max burst period, in -# seconds It must only be set if @bps-write-max is set as well. +# seconds. It must only be set if @bps-write-max is set as well. # # @iops-size: when limiting by iops max size of an I/O in bytes # @@ -2777,14 +2794,14 @@ # 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 -# 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; # see below) and can be specified using its device or node name. -# Earlier qemu versions only allowed 'device' to name the top level +# Earlier QEMU versions only allowed 'device' to name the top level # node; presence of the 'base-node' parameter during introspection can # be used as a witness of the enhanced semantics of 'device'. # @@ -2798,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. # @@ -2841,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 @@ -2849,16 +2866,15 @@ # autogenerated. (Since: 6.0) # # @auto-finalize: When false, this job will wait in a PENDING state -# after it has finished its work, waiting for @block-job-finalize -# before making any block graph changes. When true, this job will +# 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 -# @block-job-dismiss. When true, this job will automatically -# disappear from the query list without user intervention. -# Defaults to true. (Since 3.1) +# `job-dismiss`. When true, this job will automatically disappear +# without user intervention. Defaults to true. (Since 3.1) # # Errors: # - If @device does not exist, DeviceNotFound. @@ -2918,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. # @@ -2938,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) # @@ -2956,18 +2972,24 @@ # # Pause an active background block operation. # -# This command returns immediately after marking the active background -# block operation for pausing. It is an error to call this command if -# no operation is in progress or if the job is already paused. +# This command returns immediately after marking the active job for +# pausing. Pausing an already paused job is an error. +# +# 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. # -# The operation will pause as soon as possible. No event is emitted -# when the operation is actually paused. Cancelling a paused job -# automatically resumes it. +# Cancelling a paused job automatically resumes it. # # @device: The job identifier. This used to be a device name (hence # the name of the parameter), but since QEMU 2.7 it can have other # values. # +# Features: +# +# @deprecated: This command is deprecated. Use `job-pause` +# instead. +# # Errors: # - If no background operation is active on this device, # DeviceNotActive @@ -2975,6 +2997,7 @@ # Since: 1.3 ## { 'command': 'block-job-pause', 'data': { 'device': 'str' }, + 'features': ['deprecated'], 'allow-preconfig': true } ## @@ -2982,9 +3005,8 @@ # # Resume an active background block operation. # -# This command returns immediately after resuming a paused background -# block operation. It is an error to call this command if no -# operation is in progress or if the job is not paused. +# This command returns immediately after resuming a paused job. +# Resuming an already running job is an error. # # This command also clears the error status of the job. # @@ -2992,6 +3014,11 @@ # the name of the parameter), but since QEMU 2.7 it can have other # values. # +# Features: +# +# @deprecated: This command is deprecated. Use `job-resume` +# instead. +# # Errors: # - If no background operation is active on this device, # DeviceNotActive @@ -2999,30 +3026,39 @@ # Since: 1.3 ## { 'command': 'block-job-resume', 'data': { 'device': 'str' }, + 'features': ['deprecated'], 'allow-preconfig': true } ## # @block-job-complete: # -# Manually trigger completion of an active background block operation. -# This is supported for drive mirroring, where it also switches the -# device to write to the target path only. The ability to complete is -# signaled with a BLOCK_JOB_READY event. +# Manually trigger completion of an active job in the READY or STANDBY +# state. Completing the job in any other state is an error. +# +# 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` +# 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. # # 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 # operation. # -# A cancelled or paused job cannot be completed. -# # @device: The job identifier. This used to be a device name (hence # the name of the parameter), but since QEMU 2.7 it can have other # values. # +# Features: +# +# @deprecated: This command is deprecated. Use `job-complete` +# instead. +# # Errors: # - If no background operation is active on this device, # DeviceNotActive @@ -3030,43 +3066,64 @@ # Since: 1.3 ## { 'command': 'block-job-complete', 'data': { 'device': 'str' }, + 'features': ['deprecated'], 'allow-preconfig': true } ## # @block-job-dismiss: # -# For jobs that have already concluded, remove them from the -# block-job-query list. This command only needs to be run for jobs -# which were started with QEMU 2.12+ job lifetime management -# semantics. +# 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 +# jobs. # # This command will refuse to operate on any job that has not yet -# reached its terminal state, JOB_STATUS_CONCLUDED. For jobs that -# make use of the BLOCK_JOB_READY event, block-job-cancel or -# block-job-complete will still need to be used as appropriate. +# 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. # # @id: The job identifier. # +# Features: +# +# @deprecated: This command is deprecated. Use `job-dismiss` +# instead. +# # Since: 2.12 ## { 'command': 'block-job-dismiss', 'data': { 'id': 'str' }, + 'features': ['deprecated'], 'allow-preconfig': true } ## # @block-job-finalize: # -# Once a job that has manual=true reaches the pending state, it can be -# instructed to finalize any graph changes and do any necessary -# cleanup via this command. For jobs in a transaction, instructing -# one job to finalize will force ALL jobs in the transaction to -# finalize, so it is only necessary to instruct a single member job to -# finalize. +# Instructs all jobs in a transaction (or a single job if it is not +# part of any transaction) to finalize any graph changes and do any +# necessary cleanup. This command requires that all involved jobs are +# in the PENDING state. +# +# For jobs in a transaction, instructing one job to finalize will +# force ALL jobs in the transaction to finalize, so it is only +# necessary to instruct a single member job to finalize. +# +# The command is applicable only to jobs which have @auto-finalize option +# and only when this option is set to false. # # @id: The job identifier. # +# Features: +# +# @deprecated: This command is deprecated. Use `job-finalize` +# instead. +# # Since: 2.12 ## { 'command': 'block-job-finalize', 'data': { 'id': 'str' }, + 'features': ['deprecated'], 'allow-preconfig': true } ## @@ -3132,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 @@ -3145,7 +3202,7 @@ # # Selects the AIO backend to handle I/O requests # -# @threads: Use qemu's thread pool +# @threads: Use QEMU's thread pool # # @native: Use native AIO backend (only Linux and Windows) # @@ -3364,8 +3421,8 @@ # Driver specific block device options for LUKS. # # @key-secret: the ID of a QCryptoSecret object providing the -# decryption key (since 2.6). Mandatory except when doing a -# metadata-only probe of the image. +# decryption key. Mandatory except when doing a metadata-only +# probe of the image. (since 2.6) # # @header: block device holding a detached LUKS header. (since 9.0) # @@ -3604,8 +3661,8 @@ # this feature. (since 2.5) # # @encrypt: Image decryption options. Mandatory for encrypted images, -# except when doing a metadata-only probe of the image. (since -# 2.10) +# except when doing a metadata-only probe of the image. +# (since 2.10) # # @data-file: reference to or definition of the external data file. # This may only be specified for images that require an external @@ -4275,8 +4332,8 @@ # @user: Ceph id name. # # @auth-client-required: Acceptable authentication modes. This maps -# to Ceph configuration option "auth_client_required". (Since -# 3.0) +# to Ceph configuration option "auth_client_required". +# (Since 3.0) # # @key-secret: ID of a QCryptoSecret object providing a key for cephx # authentication. This maps to Ceph configuration option "key". @@ -4530,8 +4587,8 @@ # error. During the first @reconnect-delay seconds, all requests # are paused and will be rerun on a successful reconnect. After # that time, any delayed requests and all future requests before a -# successful reconnect will immediately fail. Default 0 (Since -# 4.2) +# successful reconnect will immediately fail. Default 0 +# (Since 4.2) # # @open-timeout: In seconds. If zero, the nbd driver tries the # connection only once, and fails to open if the connection fails. @@ -4673,11 +4730,11 @@ # # @driver: block driver name # -# @node-name: the node name of the new node (Since 2.0). This option -# is required 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. +# @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 +# an alphabetic character and may contain only alphanumeric +# characters, '-', '.' and '_'. Their maximum length is 31 +# characters. (Since 2.0) # # @discard: discard-related options (default: ignore) # @@ -4686,7 +4743,7 @@ # @active: whether the block node should be activated (default: true). # Having inactive block nodes is useful primarily for migration because it # allows opening an image on the destination while the source is still -# holding locks for it. (Since 10.0) +# holding locks for it. (Since 10.0) # # @read-only: whether the block device should be read-only (default: # false). Note that some block drivers support only read-only @@ -4878,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 @@ -4887,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 @@ -4896,12 +4953,12 @@ # 3) A reference to a different node: the current child is replaced # with the specified one. # -# 4) NULL: the current child (if any) is detached. +# 4) null: the current child (if any) is detached. # # 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. @@ -4915,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. # @@ -4948,14 +5005,14 @@ ## # @blockdev-set-active: # -# Activate or inactivate a block device. Use this to manage the handover of +# Activate or inactivate a block device. Use this to manage the handover of # block devices on migration with qemu-storage-daemon. # # Activating a node automatically activates all of its child nodes first. # Inactivating a node automatically inactivates any of its child nodes that are # not in use by a still active node. # -# @node-name: Name of the graph node to activate or inactivate. By default, all +# @node-name: Name of the graph node to activate or inactivate. By default, all # nodes are affected by the operation. # # @active: true if the nodes should be active when the command returns success, @@ -5106,10 +5163,10 @@ ## # @BlockdevQcow2Version: # -# @v2: The original QCOW2 format as introduced in qemu 0.10 (version +# @v2: The original QCOW2 format as introduced in QEMU 0.10 (version # 2) # -# @v3: The extended QCOW2 format as introduced in qemu 1.1 (version 3) +# @v3: The extended QCOW2 format as introduced in QEMU 1.1 (version 3) # # Since: 2.12 ## @@ -5470,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. # @@ -5529,8 +5586,8 @@ # @x-blockdev-amend: # # 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. +# block device. The job is automatically finalized, but a manual +# `job-dismiss` is required. # # @job-id: Identifier for the newly created job. # @@ -5538,7 +5595,7 @@ # # @options: Options (driver specific) # -# @force: Allow unsafe operations, format specific For luks that +# @force: Allow unsafe operations, format specific. For luks that # allows erase of the last active keyslot (permanent loss of # data), and replacement of an active keyslot (possible loss of # data if IO error happens) @@ -5599,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:: # @@ -5643,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. # @@ -5793,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 # @@ -5815,7 +5872,7 @@ # @BLOCK_JOB_PENDING: # # Emitted when a block job is awaiting explicit authorization to -# finalize graph changes via @block-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. # @@ -5864,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. # @@ -5935,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 @@ -6148,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 @@ -6157,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 c783e01..6878b89 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 @@ -169,7 +170,7 @@ # @growable: Whether writes beyond the EOF should grow the block node # accordingly. (default: false) # -# @allow-other: If this is off, only qemu's user is allowed access to +# @allow-other: If this is off, only QEMU's user is allowed access to # this export. That cannot be changed even with chmod or chown. # Enabling this option will allow other users access to the export # with the FUSE mount option "allow_other". Note that using @@ -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 ## @@ -373,9 +374,9 @@ # (since: 5.2) # # @allow-inactive: If true, the export allows the exported node to be inactive. -# If it is created for an inactive block node, the node remains inactive. If +# If it is created for an inactive block node, the node remains inactive. If # the export type doesn't support running on an inactive node, an error is -# returned. If false, inactive block nodes are automatically activated before +# returned. If false, inactive block nodes are automatically activated before # creating the export and trying to inactivate them later fails. # (since: 10.0; default: false) # @@ -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 e66666f..46955bb 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) +# =================================== ## ## @@ -48,7 +51,7 @@ ## # @FloppyDriveType: # -# Type of Floppy drive to be emulated by the Floppy Disk Controller. +# Type of floppy drive to be emulated by the Floppy Disk Controller. # # @144: 1.44MB 3.5" drive # @@ -83,10 +86,10 @@ ## # @query-pr-managers: # -# Returns a list of information about each persistent reservation +# 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 dde2f95..f0a53f7 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -3,7 +3,9 @@ # ## -# = Character devices +# ***************** +# Character devices +# ***************** ## { 'include': 'sockets.json' } @@ -34,9 +36,7 @@ ## # @query-chardev: # -# Returns information about current character devices. -# -# Returns: a list of @ChardevInfo +# Return information about current character devices. # # Since: 0.14 # @@ -80,9 +80,7 @@ ## # @query-chardev-backends: # -# Returns information about character device backends. -# -# Returns: a list of @ChardevBackendInfo +# Return information about character device backends. # # Since: 2.0 # @@ -274,7 +272,7 @@ # @reconnect: For a client socket, if a socket is disconnected, then # attempt a reconnect after the given number of seconds. Setting # this to zero disables this function. The use of this member is -# deprecated, use @reconnect-ms instead. (default: 0) (Since: 2.2) +# deprecated, use @reconnect-ms instead. (default: 0) (Since: 2.2) # # @reconnect-ms: For a client socket, if a socket is disconnected, # then attempt a reconnect after the given number of milliseconds. @@ -351,7 +349,7 @@ # Configuration info for stdio chardevs. # # @signal: Allow signals (such as SIGINT triggered by ^C) be delivered -# to qemu. Default: true. +# to QEMU. Default: true. # # Since: 1.5 ## @@ -443,7 +441,7 @@ ## # @ChardevQemuVDAgent: # -# Configuration info for qemu vdagent implementation. +# Configuration info for QEMU vdagent implementation. # # @mouse: enable/disable mouse, default is enabled. # @@ -656,7 +654,7 @@ ## # @ChardevQemuVDAgentWrapper: # -# @data: Configuration info for qemu vdagent implementation +# @data: Configuration info for QEMU vdagent implementation # # Since: 6.1 ## @@ -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 0e3a0bb..af7e3d6 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 42034d9..90b8d51 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 336386f..9a53021 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) @@ -91,10 +93,9 @@ ## # @query-version: # -# Returns the current version of QEMU. +# 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 c9d967d..ab6eda4 100644 --- a/qapi/crypto.json +++ b/qapi/crypto.json @@ -3,7 +3,9 @@ # ## -# = Cryptography +# ************ +# Cryptography +# ************ ## ## @@ -55,7 +57,8 @@ # @sha512: SHA-512. (since 2.7) # # @ripemd160: RIPEMD-160. (since 2.7) -# @sm3: SM3. (since 9.2.0) +# +# @sm3: SM3. (since 9.2.0) # # Since: 2.6 ## @@ -202,19 +205,19 @@ # # The options that apply to LUKS encryption format initialization # -# @cipher-alg: the cipher algorithm for data encryption Currently +# @cipher-alg: the cipher algorithm for data encryption. Currently # defaults to 'aes-256'. # -# @cipher-mode: the cipher mode for data encryption Currently defaults -# to 'xts' +# @cipher-mode: the cipher mode for data encryption. Currently +# defaults to 'xts' # -# @ivgen-alg: the initialization vector generator Currently defaults +# @ivgen-alg: the initialization vector generator. Currently defaults # to 'plain64' # -# @ivgen-hash-alg: the initialization vector generator hash Currently -# defaults to 'sha256' +# @ivgen-hash-alg: the initialization vector generator hash. +# Currently defaults to 'sha256' # -# @hash-alg: the master key hash algorithm Currently defaults to +# @hash-alg: the master key hash algorithm. Currently defaults to # 'sha256' # # @iter-time: number of milliseconds to spend in PBKDF passphrase @@ -370,11 +373,11 @@ # @new-secret: The ID of a QCryptoSecret object providing the password # to be written into added active keyslots # -# @old-secret: Optional (for deactivation only) If given will +# @old-secret: Optional (for deactivation only). If given will # deactivate all keyslots that match password located in # QCryptoSecret with this ID # -# @iter-time: Optional (for activation only) Number of milliseconds to +# @iter-time: Optional (for activation only). Number of milliseconds to # spend in PBKDF passphrase processing for the newly activated # keyslot. Currently defaults to 2000. # @@ -588,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 04d0e21..eb309c2 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 +# ******************** ## ## @@ -15,7 +17,7 @@ # # @sym: symmetric encryption # -# @asym: asymmetric Encryption +# @asym: asymmetric encryption # # Since: 8.0 ## @@ -94,9 +96,7 @@ ## # @query-cryptodev: # -# Returns information about current crypto devices. -# -# Returns: a list of @QCryptodevInfo +# Return information about current crypto devices. # # Since: 8.0 ## diff --git a/qapi/cxl.json b/qapi/cxl.json index dd947d3..52cc5d4 100644 --- a/qapi/cxl.json +++ b/qapi/cxl.json @@ -2,7 +2,9 @@ # vim: filetype=python ## -# = CXL devices +# *********** +# CXL devices +# *********** ## ## @@ -117,7 +119,7 @@ # @nibble-mask: Identifies one or more nibbles that the error affects # # @bank-group: Bank group of the memory event location, incorporating -# a number of Banks. +# a number of banks. # # @bank: Bank of the memory event location. A single bank is accessed # per read or write of the memory. diff --git a/qapi/dump.json b/qapi/dump.json index d7826c0..726b520 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 +# ***************** ## ## @@ -54,9 +56,9 @@ # @paging: if true, do paging to get guest's memory mapping. This # allows using gdb to process the core file. # -# IMPORTANT: this option can make QEMU allocate several gigabytes -# of RAM. This can happen for a large guest, or a malicious guest -# pretending to be large. +# **Important**: this option can make QEMU allocate several +# gigabytes of RAM. This can happen for a large guest, or a +# malicious guest pretending to be large. # # Also, paging=true has the following limitations: # @@ -77,7 +79,7 @@ # # @detach: if true, QMP will return immediately rather than waiting # for the dump to finish. The user can track progress using -# "query-dump". (since 2.6). +# `query-dump`. (since 2.6). # # @begin: if specified, the starting physical address. # @@ -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: # -# Returns 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 db19ae8..f025795 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 135c1e8..54cb02f 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 01bb242..5310071 100644 --- a/qapi/introspect.json +++ b/qapi/introspect.json @@ -10,34 +10,36 @@ # 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. # # Furthermore, while we strive to keep the QMP wire format -# backwards-compatible across qemu versions, the introspection output +# backwards-compatible across QEMU versions, the introspection output # is not guaranteed to have the same stability. For example, one -# version of qemu may list an object member as an optional +# version of QEMU may list an object member as an optional # non-variant, while another lists the same member only through the # object's variants; or the type of a member may change from a generic # 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,10 +154,10 @@ ## # @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). +# @members: the enum type's members, in no particular order. +# (since 6.2) # # @values: the enumeration type's member names, in no particular # order. Redundant with @members. Just for backward @@ -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 cfc3bee..8b08350 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" (since -# 5.1) +# @amend: image options amend job type, see `x-blockdev-amend` +# (since 5.1) # -# @snapshot-load: snapshot load job type, see "snapshot-load" (since -# 6.0) +# @snapshot-load: snapshot load job type, see `snapshot-load` +# (since 6.0) # -# @snapshot-save: snapshot save job type, see "snapshot-save" (since -# 6.0) +# @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 @@ -74,8 +76,8 @@ # process. # # @concluded: The job has finished all work. If auto-dismiss was set -# to false, the job will remain in the query list until it is -# dismissed via @job-dismiss. +# to false, the job will remain in this state until it is +# 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. # @@ -156,6 +158,9 @@ # This command returns immediately after resuming a paused job. # Resuming an already running job is an error. # +# This command also clears the error status for block-jobs (stream, +# commit, mirror, backup). +# # @id: The job identifier. # # Since: 3.0 @@ -170,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. @@ -184,7 +189,23 @@ ## # @job-complete: # -# Manually trigger completion of an active job in the READY state. +# Manually trigger completion of an active job in the READY or STANDBY +# state. Completing the job in any other state is an error. +# +# 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` +# 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. +# +# 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 +# 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 +# operation. # # @id: The job identifier. # @@ -197,12 +218,16 @@ # # 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. +# 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 +# jobs. # # This command will refuse to operate on any job that has not yet -# reached its terminal state, JOB_STATUS_CONCLUDED. For jobs that -# make use of JOB_READY event, job-cancel or job-complete will still -# need to be used as appropriate. +# reached its terminal state, CONCLUDED. For jobs that make use of +# the JOB_READY event, `job-cancel` or `job-complete` will still need to +# be used as appropriate. # # @id: The job identifier. # @@ -222,6 +247,9 @@ # force ALL jobs in the transaction to finalize, so it is only # necessary to instruct a single member job to finalize. # +# The command is applicable only to jobs which have @auto-finalize option +# and only when this option is set to false. +# # @id: The identifier of any job in the transaction, or of a job that # is not part of any transaction. # @@ -269,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 298e51f..ed3d20a 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-s390x.json b/qapi/machine-s390x.json new file mode 100644 index 0000000..966dbd6 --- /dev/null +++ b/qapi/machine-s390x.json @@ -0,0 +1,121 @@ +# -*- Mode: Python -*- +# vim: filetype=python +# +# SPDX-License-Identifier: GPL-2.0-or-later +# This work is licensed under the terms of the GNU GPL, version 2 or later. +# See the COPYING file in the top-level directory. + +{ 'include': 'machine-common.json' } + +## +# @S390CpuPolarization: +# +# An enumeration of CPU polarization that can be assumed by a virtual +# S390 CPU +# +# Since: 8.2 +## +{ 'enum': 'S390CpuPolarization', + 'data': [ 'horizontal', 'vertical' ] +} + +## +# @set-cpu-topology: +# +# Modify the topology by moving the CPU inside the topology tree, or +# by changing a modifier attribute of a CPU. Absent values will not +# be modified. +# +# @core-id: the vCPU ID to be moved +# +# @socket-id: destination socket to move the vCPU to +# +# @book-id: destination book to move the vCPU to +# +# @drawer-id: destination drawer to move the vCPU to +# +# @entitlement: entitlement to set +# +# @dedicated: whether the provisioning of real to virtual CPU is +# dedicated +# +# Features: +# +# @unstable: This command is experimental. +# +# Since: 8.2 +## +{ 'command': 'set-cpu-topology', + 'data': { + 'core-id': 'uint16', + '*socket-id': 'uint16', + '*book-id': 'uint16', + '*drawer-id': 'uint16', + '*entitlement': 'S390CpuEntitlement', + '*dedicated': 'bool' + }, + 'features': [ 'unstable' ] +} + +## +# @CPU_POLARIZATION_CHANGE: +# +# Emitted when the guest asks to change the polarization. +# +# The guest can tell the host (via the PTF instruction) whether the +# CPUs should be provisioned using horizontal or vertical +# polarization. +# +# On horizontal polarization the host is expected to provision all +# vCPUs equally. +# +# On vertical polarization the host can provision each vCPU +# differently. The guest will get information on the details of the +# provisioning the next time it uses the STSI(15) instruction. +# +# @polarization: polarization specified by the guest +# +# Features: +# +# @unstable: This event is experimental. +# +# Since: 8.2 +# +# .. qmp-example:: +# +# <- { "event": "CPU_POLARIZATION_CHANGE", +# "data": { "polarization": "horizontal" }, +# "timestamp": { "seconds": 1401385907, "microseconds": 422329 } } +## +{ 'event': 'CPU_POLARIZATION_CHANGE', + 'data': { 'polarization': 'S390CpuPolarization' }, + 'features': [ 'unstable' ] +} + +## +# @CpuPolarizationInfo: +# +# The result of a CPU polarization query. +# +# @polarization: the CPU polarization +# +# Since: 8.2 +## +{ 'struct': 'CpuPolarizationInfo', + 'data': { 'polarization': 'S390CpuPolarization' } +} + +## +# @query-s390x-cpu-polarization: +# +# Features: +# +# @unstable: This command is experimental. +# +# Returns: the machine's CPU polarization +# +# Since: 8.2 +## +{ 'command': 'query-s390x-cpu-polarization', 'returns': 'CpuPolarizationInfo', + 'features': [ 'unstable' ] +} diff --git a/qapi/machine-target.json b/qapi/machine-target.json deleted file mode 100644 index 541f93e..0000000 --- a/qapi/machine-target.json +++ /dev/null @@ -1,523 +0,0 @@ -# -*- Mode: Python -*- -# vim: filetype=python -# -# This work is licensed under the terms of the GNU GPL, version 2 or later. -# See the COPYING file in the top-level directory. - -{ 'include': 'machine-common.json' } - -## -# @CpuModelInfo: -# -# Virtual CPU model. -# -# A CPU model consists of the name of a CPU definition, to which delta -# changes are applied (e.g. features added/removed). Most magic -# values that an architecture might require should be hidden behind -# the name. However, if required, architectures can expose relevant -# properties. -# -# @name: the name of the CPU definition the model is based on -# -# @props: a dictionary of QOM properties to be applied -# -# Since: 2.8 -## -{ 'struct': 'CpuModelInfo', - 'data': { 'name': 'str', - '*props': 'any' } } - -## -# @CpuModelExpansionType: -# -# An enumeration of CPU model expansion types. -# -# @static: Expand to a static CPU model, a combination of a static -# base model name and property delta changes. As the static base -# model will never change, the expanded CPU model will be the -# same, independent of QEMU version, machine type, machine -# options, and accelerator options. Therefore, the resulting -# model can be used by tooling without having to specify a -# compatibility machine - e.g. when displaying the "host" model. -# The @static CPU models are migration-safe. -# -# @full: Expand all properties. The produced model is not guaranteed -# to be migration-safe, but allows tooling to get an insight and -# work with model details. -# -# .. note:: When a non-migration-safe CPU model is expanded in static -# mode, some features enabled by the CPU model may be omitted, -# because they can't be implemented by a static CPU model -# definition (e.g. cache info passthrough and PMU passthrough in -# x86). If you need an accurate representation of the features -# enabled by a non-migration-safe CPU model, use @full. If you -# need a static representation that will keep ABI compatibility -# even when changing QEMU version or machine-type, use @static (but -# keep in mind that some features may be omitted). -# -# Since: 2.8 -## -{ 'enum': 'CpuModelExpansionType', - 'data': [ 'static', 'full' ] } - -## -# @CpuModelCompareResult: -# -# An enumeration of CPU model comparison results. The result is -# usually calculated using e.g. CPU features or CPU generations. -# -# @incompatible: If model A is incompatible to model B, model A is not -# guaranteed to run where model B runs and the other way around. -# -# @identical: If model A is identical to model B, model A is -# guaranteed to run where model B runs and the other way around. -# -# @superset: If model A is a superset of model B, model B is -# guaranteed to run where model A runs. There are no guarantees -# about the other way. -# -# @subset: If model A is a subset of model B, model A is guaranteed to -# run where model B runs. There are no guarantees about the other -# way. -# -# Since: 2.8 -## -{ 'enum': 'CpuModelCompareResult', - 'data': [ 'incompatible', 'identical', 'superset', 'subset' ] } - -## -# @CpuModelBaselineInfo: -# -# The result of a CPU model baseline. -# -# @model: the baselined CpuModelInfo. -# -# Since: 2.8 -## -{ 'struct': 'CpuModelBaselineInfo', - 'data': { 'model': 'CpuModelInfo' }, - 'if': 'TARGET_S390X' } - -## -# @CpuModelCompareInfo: -# -# The result of a CPU model comparison. -# -# @result: The result of the compare operation. -# -# @responsible-properties: List of properties that led to the -# comparison result not being identical. -# -# @responsible-properties is a list of QOM property names that led to -# both CPUs not being detected as identical. For identical models, -# this list is empty. If a QOM property is read-only, that means -# there's no known way to make the CPU models identical. If the -# special property name "type" is included, the models are by -# definition not identical and cannot be made identical. -# -# Since: 2.8 -## -{ 'struct': 'CpuModelCompareInfo', - 'data': { 'result': 'CpuModelCompareResult', - 'responsible-properties': ['str'] }, - 'if': 'TARGET_S390X' } - -## -# @query-cpu-model-comparison: -# -# Compares two CPU models, @modela and @modelb, returning how they -# compare in a specific configuration. The results indicates how -# both models compare regarding runnability. This result can be -# used by tooling to make decisions if a certain CPU model will -# run in a certain configuration or if a compatible CPU model has -# to be created by baselining. -# -# Usually, a CPU model is compared against the maximum possible CPU -# model of a certain configuration (e.g. the "host" model for KVM). -# If that CPU model is identical or a subset, it will run in that -# configuration. -# -# The result returned by this command may be affected by: -# -# * QEMU version: CPU models may look different depending on the QEMU -# version. (Except for CPU models reported as "static" in -# 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.) -# * 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.) -# * "-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. -# -# 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 -# -# @modelb: description of the second CPU model to compare, referred to -# as "model B" in CpuModelCompareResult -# -# Returns: a CpuModelCompareInfo describing how both CPU models -# compare -# -# Errors: -# - if comparing CPU models is not supported -# - if a model cannot be used -# - if a model contains an unknown cpu definition name, unknown -# properties or properties with wrong types. -# -# .. note:: This command isn't specific to s390x, but is only -# implemented on this architecture currently. -# -# Since: 2.8 -## -{ 'command': 'query-cpu-model-comparison', - 'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' }, - 'returns': 'CpuModelCompareInfo', - 'if': 'TARGET_S390X' } - -## -# @query-cpu-model-baseline: -# -# Baseline two CPU models, @modela and @modelb, creating a compatible -# third model. The created model will always be a static, -# migration-safe CPU model (see "static" CPU model expansion for -# details). -# -# This interface can be used by tooling to create a compatible CPU -# model out two CPU models. The created CPU model will be identical -# to or a subset of both CPU models when comparing them. Therefore, -# the created CPU model is guaranteed to run where the given CPU -# models run. -# -# The result returned by this command may be affected by: -# -# * QEMU version: CPU models may look different depending on the QEMU -# version. (Except for CPU models reported as "static" in -# 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.) -# * 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.) -# * "-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. -# -# Some architectures may not support baselining CPU models. s390x -# supports baselining CPU models. -# -# @modela: description of the first CPU model to baseline -# -# @modelb: description of the second CPU model to baseline -# -# Returns: a CpuModelBaselineInfo describing the baselined CPU model -# -# Errors: -# - if baselining CPU models is not supported -# - if a model cannot be used -# - if a model contains an unknown cpu definition name, unknown -# properties or properties with wrong types. -# -# .. note:: This command isn't specific to s390x, but is only -# implemented on this architecture currently. -# -# Since: 2.8 -## -{ 'command': 'query-cpu-model-baseline', - 'data': { 'modela': 'CpuModelInfo', - 'modelb': 'CpuModelInfo' }, - 'returns': 'CpuModelBaselineInfo', - 'if': 'TARGET_S390X' } - -## -# @CpuModelExpansionInfo: -# -# The result of a cpu model expansion. -# -# @model: the expanded CpuModelInfo. -# -# @deprecated-props: a list of properties that are flagged as -# deprecated by the CPU vendor. The list depends on the -# CpuModelExpansionType: "static" properties are a subset of the -# enabled-properties for the expanded model; "full" properties are -# a set of properties that are deprecated across all models for -# the architecture. (since: 9.1). -# -# Since: 2.8 -## -{ 'struct': 'CpuModelExpansionInfo', - 'data': { 'model': 'CpuModelInfo', - 'deprecated-props' : { 'type': ['str'], - 'if': 'TARGET_S390X' } }, - 'if': { 'any': [ 'TARGET_S390X', - 'TARGET_I386', - 'TARGET_ARM', - 'TARGET_LOONGARCH64', - 'TARGET_RISCV' ] } } - -## -# @query-cpu-model-expansion: -# -# Expands a given CPU model, @model, (or a combination of CPU model + -# additional options) to different granularities, specified by @type, -# allowing tooling to get an understanding what a specific CPU model -# looks like in QEMU under a certain configuration. -# -# This interface can be used to query the "host" CPU model. -# -# The data returned by this command may be affected by: -# -# * QEMU version: CPU models may look different depending on the QEMU -# version. (Except for CPU models reported as "static" in -# 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.) -# * 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.) -# * "-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. -# -# Some architectures may not support all expansion types. s390x -# supports "full" and "static". Arm only supports "full". -# -# @model: description of the CPU model to expand -# -# @type: expansion type, specifying how to expand the CPU model -# -# Returns: a CpuModelExpansionInfo describing the expanded CPU model -# -# Errors: -# - if expanding CPU models is not supported -# - if the model cannot be expanded -# - if the model contains an unknown CPU definition name, unknown -# properties or properties with a wrong type -# - if an expansion type is not supported -# -# Since: 2.8 -## -{ 'command': 'query-cpu-model-expansion', - 'data': { 'type': 'CpuModelExpansionType', - 'model': 'CpuModelInfo' }, - 'returns': 'CpuModelExpansionInfo', - 'if': { 'any': [ 'TARGET_S390X', - 'TARGET_I386', - 'TARGET_ARM', - 'TARGET_LOONGARCH64', - 'TARGET_RISCV' ] } } - -## -# @CpuDefinitionInfo: -# -# Virtual CPU definition. -# -# @name: the name of the CPU definition -# -# @migration-safe: whether a CPU definition can be safely used for -# migration in combination with a QEMU compatibility machine when -# migrating between different QEMU versions and between hosts with -# different sets of (hardware or software) capabilities. If not -# provided, information is not available and callers should not -# assume the CPU definition to be migration-safe. (since 2.8) -# -# @static: whether a CPU definition is static and will not change -# depending on QEMU version, machine type, machine options and -# accelerator options. A static model is always migration-safe. -# (since 2.8) -# -# @unavailable-features: List of properties that prevent the CPU model -# 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 -# using -cpu or -global. (since 2.9) -# -# @alias-of: Name of CPU model this model is an alias for. The target -# of the CPU model alias may change depending on the machine type. -# Management software is supposed to translate CPU model aliases -# in the VM configuration, because aliases may stop being -# migration-safe in the future (since 4.1) -# -# @deprecated: If true, this CPU model is deprecated and may be -# removed in in some future version of QEMU according to the QEMU -# deprecation policy. (since 5.2) -# -# @unavailable-features is a list of QOM property names that represent -# CPU model attributes that prevent the CPU from running. If the QOM -# property is read-only, that means there's no known way to make the -# CPU model run in the current host. Implementations that choose not -# to provide specific information return the property name "type". If -# the property is read-write, it means that it MAY be possible to run -# the CPU model in the current host if that property is changed. -# Management software can use it as hints to suggest or choose an -# alternative for the user, or just to generate meaningful error -# messages explaining why the CPU model can't be used. If -# @unavailable-features is an empty list, the CPU model is runnable -# using the current host and machine-type. If @unavailable-features -# is not present, runnability information for the CPU is not -# available. -# -# Since: 1.2 -## -{ 'struct': 'CpuDefinitionInfo', - 'data': { 'name': 'str', - '*migration-safe': 'bool', - 'static': 'bool', - '*unavailable-features': [ 'str' ], - 'typename': 'str', - '*alias-of' : 'str', - 'deprecated' : 'bool' }, - 'if': { 'any': [ 'TARGET_PPC', - 'TARGET_ARM', - 'TARGET_I386', - 'TARGET_S390X', - 'TARGET_MIPS', - 'TARGET_LOONGARCH64', - 'TARGET_RISCV' ] } } - -## -# @query-cpu-definitions: -# -# Return a list of supported virtual CPU definitions -# -# Returns: a list of CpuDefinitionInfo -# -# Since: 1.2 -## -{ 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'], - 'if': { 'any': [ 'TARGET_PPC', - 'TARGET_ARM', - 'TARGET_I386', - 'TARGET_S390X', - 'TARGET_MIPS', - 'TARGET_LOONGARCH64', - 'TARGET_RISCV' ] } } - -## -# @S390CpuPolarization: -# -# An enumeration of CPU polarization that can be assumed by a virtual -# S390 CPU -# -# Since: 8.2 -## -{ 'enum': 'S390CpuPolarization', - 'data': [ 'horizontal', 'vertical' ], - 'if': 'TARGET_S390X' -} - -## -# @set-cpu-topology: -# -# Modify the topology by moving the CPU inside the topology tree, or -# by changing a modifier attribute of a CPU. Absent values will not -# be modified. -# -# @core-id: the vCPU ID to be moved -# -# @socket-id: destination socket to move the vCPU to -# -# @book-id: destination book to move the vCPU to -# -# @drawer-id: destination drawer to move the vCPU to -# -# @entitlement: entitlement to set -# -# @dedicated: whether the provisioning of real to virtual CPU is -# dedicated -# -# Features: -# -# @unstable: This command is experimental. -# -# Since: 8.2 -## -{ 'command': 'set-cpu-topology', - 'data': { - 'core-id': 'uint16', - '*socket-id': 'uint16', - '*book-id': 'uint16', - '*drawer-id': 'uint16', - '*entitlement': 'S390CpuEntitlement', - '*dedicated': 'bool' - }, - 'features': [ 'unstable' ], - 'if': { 'all': [ 'TARGET_S390X' , 'CONFIG_KVM' ] } -} - -## -# @CPU_POLARIZATION_CHANGE: -# -# Emitted when the guest asks to change the polarization. -# -# The guest can tell the host (via the PTF instruction) whether the -# CPUs should be provisioned using horizontal or vertical -# polarization. -# -# On horizontal polarization the host is expected to provision all -# vCPUs equally. -# -# On vertical polarization the host can provision each vCPU -# differently. The guest will get information on the details of the -# provisioning the next time it uses the STSI(15) instruction. -# -# @polarization: polarization specified by the guest -# -# Features: -# -# @unstable: This event is experimental. -# -# Since: 8.2 -# -# .. qmp-example:: -# -# <- { "event": "CPU_POLARIZATION_CHANGE", -# "data": { "polarization": "horizontal" }, -# "timestamp": { "seconds": 1401385907, "microseconds": 422329 } } -## -{ 'event': 'CPU_POLARIZATION_CHANGE', - 'data': { 'polarization': 'S390CpuPolarization' }, - 'features': [ 'unstable' ], - 'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] } -} - -## -# @CpuPolarizationInfo: -# -# The result of a CPU polarization query. -# -# @polarization: the CPU polarization -# -# Since: 8.2 -## -{ 'struct': 'CpuPolarizationInfo', - 'data': { 'polarization': 'S390CpuPolarization' }, - 'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] } -} - -## -# @query-s390x-cpu-polarization: -# -# Features: -# -# @unstable: This command is experimental. -# -# Returns: the machine's CPU polarization -# -# Since: 8.2 -## -{ 'command': 'query-s390x-cpu-polarization', 'returns': 'CpuPolarizationInfo', - 'features': [ 'unstable' ], - 'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] } -} diff --git a/qapi/machine.json b/qapi/machine.json index a9ff807..038eab2 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' } @@ -76,6 +78,8 @@ # # @cpu-index: index of the virtual CPU # +# @qom-type: QOM type name of the CPU (since 10.1) +# # @qom-path: path to the CPU object in the QOM tree # # @thread-id: ID of the underlying host thread @@ -89,6 +93,7 @@ ## { 'union' : 'CpuInfoFast', 'base' : { 'cpu-index' : 'int', + 'qom-type' : 'str', 'qom-path' : 'str', 'thread-id' : 'int', '*props' : 'CpuInstanceProperties', @@ -99,9 +104,7 @@ ## # @query-cpus-fast: # -# Returns information about all virtual CPUs. -# -# Returns: list of @CpuInfoFast +# Return information about all virtual CPUs. # # Since: 2.12 # @@ -182,13 +185,13 @@ # @default-cpu-type: default CPU model typename if none is requested # via the -cpu argument. (since 4.2) # -# @default-ram-id: the default ID of initial RAM memory backend (since -# 5.2) +# @default-ram-id: the default ID of initial RAM memory backend +# (since 5.2) # # @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: @@ -218,8 +221,6 @@ # # @unstable: Argument @compat-props is experimental. # -# Returns: a list of MachineInfo -# # Since: 1.2 # # .. qmp-example:: @@ -268,22 +269,20 @@ # # Return information on the current virtual machine. # -# Returns: CurrentMachineParams -# # Since: 4.0 ## { 'command': 'query-current-machine', 'returns': 'CurrentMachineParams' } ## -# @TargetInfo: +# @QemuTargetInfo: # -# Information describing the QEMU target. +# Information on the target configuration built into the QEMU binary. # # @arch: the target architecture # # Since: 1.2 ## -{ 'struct': 'TargetInfo', +{ 'struct': 'QemuTargetInfo', 'data': { 'arch': 'SysEmuTarget' } } ## @@ -291,11 +290,9 @@ # # Return information about the target for this QEMU # -# Returns: TargetInfo -# # Since: 1.2 ## -{ 'command': 'query-target', 'returns': 'TargetInfo' } +{ 'command': 'query-target', 'returns': 'QemuTargetInfo' } ## # @UuidInfo: @@ -316,8 +313,6 @@ # # Query the guest UUID information. # -# Returns: The @UuidInfo for the guest -# # Since: 0.14 # # .. qmp-example:: @@ -385,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 @@ -452,35 +447,6 @@ { 'command': 'inject-nmi' } ## -# @KvmInfo: -# -# Information about support for KVM acceleration -# -# @enabled: true if KVM acceleration is active -# -# @present: true if KVM acceleration is built into this executable -# -# Since: 0.14 -## -{ 'struct': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} } - -## -# @query-kvm: -# -# Returns information about KVM acceleration -# -# Returns: @KvmInfo -# -# Since: 0.14 -# -# .. qmp-example:: -# -# -> { "execute": "query-kvm" } -# <- { "return": { "enabled": true, "present": true } } -## -{ 'command': 'query-kvm', 'returns': 'KvmInfo' } - -## # @NumaOptionsType: # # @node: NUMA nodes configuration @@ -599,7 +565,7 @@ # # List of CXL Fixed Memory Windows. # -# @cxl-fmw: List of CXLFixedMemoryWindowOptions +# @cxl-fmw: List of `CXLFixedMemoryWindowOptions` # # Since: 7.1 ## @@ -654,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 ## @@ -671,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 @@ -693,8 +659,8 @@ # 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: -# Table 5-146: Field "Data Type" of ACPI 6.3 spec. +# 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) # @@ -720,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. @@ -756,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 @@ -777,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 @@ -797,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. @@ -811,7 +777,7 @@ # # @policy: the write policy, none/write-back/write-through. # -# @line: the cache Line size in bytes. +# @line: the cache line size in bytes. # # Since: 5.0 ## @@ -930,9 +896,7 @@ ## # @query-memdev: # -# Returns information for all memory backends. -# -# Returns: a list of @Memdev. +# Return information for all memory backends. # # Since: 2.1 # @@ -976,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 # @@ -1004,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', @@ -1020,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 ## @@ -1049,8 +1013,6 @@ # # TODO: Better documentation; currently there is none. # -# Returns: a list of HotpluggableCPU objects. -# # Since: 2.7 # # .. qmp-example:: @@ -1089,7 +1051,7 @@ # :annotated: # # For s390x-virtio-ccw machine type started with -# ``-smp 1,maxcpus=2 -cpu qemu`` (Since: 2.11):: +# ``-smp 1,maxcpus=2 -cpu qemu``:: # # -> { "execute": "query-hotpluggable-cpus" } # <- {"return": [ @@ -1160,7 +1122,7 @@ # # Information about the guest balloon device. # -# @actual: the logical size of the VM in bytes Formula used: +# @actual: the logical size of the VM in bytes. Formula used: # logical_vm_size = vm_ram_size - balloon_size # # Since: 0.14 @@ -1172,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 @@ -1196,10 +1155,10 @@ # @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: +# @actual: the logical size of the VM in bytes. Formula used: # logical_vm_size = vm_ram_size - balloon_size # # .. note:: This event is rate-limited. @@ -1235,12 +1194,9 @@ ## # @query-hv-balloon-status-report: # -# Returns the hv-balloon driver data contained in the last received +# 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 @@ -1301,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" } @@ -1762,24 +1720,6 @@ 'features': [ 'unstable' ] } ## -# @x-query-opcount: -# -# Query TCG opcode counters -# -# Features: -# -# @unstable: This command is meant for debugging. -# -# Returns: TCG opcode counters -# -# Since: 6.2 -## -{ 'command': 'x-query-opcount', - 'returns': 'HumanReadableText', - 'if': 'CONFIG_TCG', - 'features': [ 'unstable' ] } - -## # @x-query-ramblock: # # Query system ramblock information @@ -1916,3 +1856,364 @@ ## { 'command': 'dump-skeys', 'data': { 'filename': 'str' } } + +## +# @CpuModelInfo: +# +# Virtual CPU model. +# +# A CPU model consists of the name of a CPU definition, to which delta +# changes are applied (e.g. features added/removed). Most magic +# values that an architecture might require should be hidden behind +# the name. However, if required, architectures can expose relevant +# properties. +# +# @name: the name of the CPU definition the model is based on +# +# @props: a dictionary of QOM properties to be applied +# +# Since: 2.8 +## +{ 'struct': 'CpuModelInfo', + 'data': { 'name': 'str', + '*props': 'any' } } + +## +# @CpuModelExpansionType: +# +# An enumeration of CPU model expansion types. +# +# @static: Expand to a static CPU model, a combination of a static +# base model name and property delta changes. As the static base +# model will never change, the expanded CPU model will be the +# same, independent of QEMU version, machine type, machine +# options, and accelerator options. Therefore, the resulting +# model can be used by tooling without having to specify a +# compatibility machine - e.g. when displaying the "host" model. +# The @static CPU models are migration-safe. +# +# @full: Expand all properties. The produced model is not guaranteed +# to be migration-safe, but allows tooling to get an insight and +# work with model details. +# +# .. note:: When a non-migration-safe CPU model is expanded in static +# mode, some features enabled by the CPU model may be omitted, +# because they can't be implemented by a static CPU model +# definition (e.g. cache info passthrough and PMU passthrough in +# x86). If you need an accurate representation of the features +# enabled by a non-migration-safe CPU model, use @full. If you +# need a static representation that will keep ABI compatibility +# even when changing QEMU version or machine-type, use @static (but +# keep in mind that some features may be omitted). +# +# Since: 2.8 +## +{ 'enum': 'CpuModelExpansionType', + 'data': [ 'static', 'full' ] } + +## +# @CpuModelCompareResult: +# +# An enumeration of CPU model comparison results. The result is +# usually calculated using e.g. CPU features or CPU generations. +# +# @incompatible: If model A is incompatible to model B, model A is not +# guaranteed to run where model B runs and the other way around. +# +# @identical: If model A is identical to model B, model A is +# guaranteed to run where model B runs and the other way around. +# +# @superset: If model A is a superset of model B, model B is +# guaranteed to run where model A runs. There are no guarantees +# about the other way. +# +# @subset: If model A is a subset of model B, model A is guaranteed to +# run where model B runs. There are no guarantees about the other +# way. +# +# Since: 2.8 +## +{ 'enum': 'CpuModelCompareResult', + 'data': [ 'incompatible', 'identical', 'superset', 'subset' ] } + +## +# @CpuModelBaselineInfo: +# +# The result of a CPU model baseline. +# +# @model: the baselined `CpuModelInfo`. +# +# Since: 2.8 +## +{ 'struct': 'CpuModelBaselineInfo', + 'data': { 'model': 'CpuModelInfo' } } + +## +# @CpuModelCompareInfo: +# +# The result of a CPU model comparison. +# +# @result: The result of the compare operation. +# +# @responsible-properties: List of properties that led to the +# comparison result not being identical. +# +# @responsible-properties is a list of QOM property names that led to +# both CPUs not being detected as identical. For identical models, +# this list is empty. If a QOM property is read-only, that means +# there's no known way to make the CPU models identical. If the +# special property name "type" is included, the models are by +# definition not identical and cannot be made identical. +# +# Since: 2.8 +## +{ 'struct': 'CpuModelCompareInfo', + 'data': { 'result': 'CpuModelCompareResult', + 'responsible-properties': ['str'] } } + +## +# @query-cpu-model-comparison: +# +# Compares two CPU models, @modela and @modelb, returning how they +# compare in a specific configuration. The results indicates how +# both models compare regarding runnability. This result can be +# used by tooling to make decisions if a certain CPU model will +# run in a certain configuration or if a compatible CPU model has +# to be created by baselining. +# +# Usually, a CPU model is compared against the maximum possible CPU +# model of a certain configuration (e.g. the "host" model for KVM). +# If that CPU model is identical or a subset, it will run in that +# configuration. +# +# The result returned by this command may be affected by: +# +# * QEMU version: CPU models may look different depending on the QEMU +# version. (Except for CPU models reported as "static" in +# `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`.) +# * 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`.) +# * "-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. +# +# 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` +# +# @modelb: description of the second CPU model to compare, referred to +# as "model B" in `CpuModelCompareResult` +# +# Returns: a `CpuModelCompareInfo` describing how both CPU models +# compare +# +# Errors: +# - if comparing CPU models is not supported by the target +# - if a model cannot be used +# - if a model contains an unknown cpu definition name, unknown +# properties or properties with wrong types. +# +# Since: 2.8 +## +{ 'command': 'query-cpu-model-comparison', + 'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' }, + 'returns': 'CpuModelCompareInfo' } + +## +# @query-cpu-model-baseline: +# +# Baseline two CPU models, @modela and @modelb, creating a compatible +# third model. The created model will always be a static, +# migration-safe CPU model (see "static" CPU model expansion for +# details). +# +# This interface can be used by tooling to create a compatible CPU +# model out two CPU models. The created CPU model will be identical +# to or a subset of both CPU models when comparing them. Therefore, +# the created CPU model is guaranteed to run where the given CPU +# models run. +# +# The result returned by this command may be affected by: +# +# * QEMU version: CPU models may look different depending on the QEMU +# version. (Except for CPU models reported as "static" in +# `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`.) +# * 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`.) +# * "-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. +# +# Some architectures may not support baselining CPU models. s390x +# supports baselining CPU models. +# +# @modela: description of the first CPU model to baseline +# +# @modelb: description of the second CPU model to baseline +# +# Returns: a `CpuModelBaselineInfo` describing the baselined CPU model +# +# Errors: +# - if baselining CPU models is not supported by the target +# - if a model cannot be used +# - if a model contains an unknown cpu definition name, unknown +# properties or properties with wrong types. +# +# Since: 2.8 +## +{ 'command': 'query-cpu-model-baseline', + 'data': { 'modela': 'CpuModelInfo', + 'modelb': 'CpuModelInfo' }, + 'returns': 'CpuModelBaselineInfo' } + +## +# @CpuModelExpansionInfo: +# +# The result of a cpu model expansion. +# +# @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 +# `CpuModelExpansionType`: "static" properties are a subset of the +# enabled-properties for the expanded model; "full" properties are +# a set of properties that are deprecated across all models for +# the architecture. (since: 10.1 -- since 9.1 on s390x --). +# +# Since: 2.8 +## +{ 'struct': 'CpuModelExpansionInfo', + 'data': { 'model': 'CpuModelInfo', + '*deprecated-props' : ['str'] } } + +## +# @query-cpu-model-expansion: +# +# Expands a given CPU model, @model, (or a combination of CPU model + +# additional options) to different granularities, specified by @type, +# allowing tooling to get an understanding what a specific CPU model +# looks like in QEMU under a certain configuration. +# +# This interface can be used to query the "host" CPU model. +# +# The data returned by this command may be affected by: +# +# * QEMU version: CPU models may look different depending on the QEMU +# version. (Except for CPU models reported as "static" in +# `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`.) +# * 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`.) +# * "-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. +# +# Some architectures may not support all expansion types. s390x +# supports "full" and "static". Arm only supports "full". +# +# @model: description of the CPU model to expand +# +# @type: expansion type, specifying how to expand the CPU model +# +# Returns: a `CpuModelExpansionInfo` describing the expanded CPU model +# +# Errors: +# - if expanding CPU models is not supported +# - if the model cannot be expanded +# - if the model contains an unknown CPU definition name, unknown +# properties or properties with a wrong type +# - if an expansion type is not supported +# +# Since: 2.8 +## +{ 'command': 'query-cpu-model-expansion', + 'data': { 'type': 'CpuModelExpansionType', + 'model': 'CpuModelInfo' }, + 'returns': 'CpuModelExpansionInfo' } + +## +# @CpuDefinitionInfo: +# +# Virtual CPU definition. +# +# @name: the name of the CPU definition +# +# @migration-safe: whether a CPU definition can be safely used for +# migration in combination with a QEMU compatibility machine when +# migrating between different QEMU versions and between hosts with +# different sets of (hardware or software) capabilities. If not +# provided, information is not available and callers should not +# assume the CPU definition to be migration-safe. (since 2.8) +# +# @static: whether a CPU definition is static and will not change +# depending on QEMU version, machine type, machine options and +# accelerator options. A static model is always migration-safe. +# (since 2.8) +# +# @unavailable-features: List of properties that prevent the CPU model +# 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 +# using -cpu or -global. (since 2.9) +# +# @alias-of: Name of CPU model this model is an alias for. The target +# of the CPU model alias may change depending on the machine type. +# Management software is supposed to translate CPU model aliases +# in the VM configuration, because aliases may stop being +# migration-safe in the future (since 4.1) +# +# @deprecated: If true, this CPU model is deprecated and may be +# removed in some future version of QEMU according to the QEMU +# deprecation policy. (since 5.2) +# +# @unavailable-features is a list of QOM property names that represent +# CPU model attributes that prevent the CPU from running. If the QOM +# property is read-only, that means there's no known way to make the +# CPU model run in the current host. Implementations that choose not +# to provide specific information return the property name "type". If +# the property is read-write, it means that it MAY be possible to run +# the CPU model in the current host if that property is changed. +# Management software can use it as hints to suggest or choose an +# alternative for the user, or just to generate meaningful error +# messages explaining why the CPU model can't be used. If +# @unavailable-features is an empty list, the CPU model is runnable +# using the current host and machine-type. If @unavailable-features +# is not present, runnability information for the CPU is not +# available. +# +# Since: 1.2 +## +{ 'struct': 'CpuDefinitionInfo', + 'data': { 'name': 'str', + '*migration-safe': 'bool', + 'static': 'bool', + '*unavailable-features': [ 'str' ], + 'typename': 'str', + '*alias-of' : 'str', + 'deprecated' : 'bool' } } + +## +# @query-cpu-definitions: +# +# Return a list of supported virtual CPU definitions +# +# Since: 1.2 +## +{ 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'] } diff --git a/qapi/meson.build b/qapi/meson.build index eadde4d..ca6b61a 100644 --- a/qapi/meson.build +++ b/qapi/meson.build @@ -39,10 +39,9 @@ qapi_all_modules = [ 'job', 'machine-common', 'machine', - 'machine-target', + 'machine-s390x', 'migration', 'misc', - 'misc-target', 'net', 'pragma', 'qom', @@ -58,12 +57,15 @@ qapi_all_modules = [ ] if have_system qapi_all_modules += [ + 'accelerator', 'acpi', 'audio', 'cryptodev', 'qdev', 'pci', 'rocker', + 'misc-arm', + 'misc-i386', 'tpm', 'uefi', ] @@ -84,14 +86,12 @@ qapi_nonmodule_outputs = [ 'qapi-emit-events.c', 'qapi-emit-events.h', ] -# First build all sources -qapi_util_outputs = [ +qapi_outputs = qapi_nonmodule_outputs + [ 'qapi-builtin-types.c', 'qapi-builtin-visit.c', 'qapi-builtin-types.h', 'qapi-builtin-visit.h', ] qapi_inputs = [] -qapi_specific_outputs = [] foreach module : qapi_all_modules qapi_inputs += [ files(module + '.json') ] qapi_module_outputs = [ @@ -109,24 +109,17 @@ foreach module : qapi_all_modules 'qapi-commands-@0@.trace-events'.format(module), ] endif - if module.endswith('-target') - qapi_specific_outputs += qapi_module_outputs - else - qapi_util_outputs += qapi_module_outputs - endif + qapi_outputs += qapi_module_outputs endforeach qapi_files = custom_target('shared QAPI source files', - output: qapi_util_outputs + qapi_specific_outputs + qapi_nonmodule_outputs, + output: qapi_outputs, input: [ files('qapi-schema.json') ], command: [ qapi_gen, '-o', 'qapi', '-b', '@INPUT0@' ], depend_files: [ qapi_inputs, qapi_gen_depends ]) -# Now go through all the outputs and add them to the right sourceset. -# These loops must be synchronized with the output of the above custom target. - i = 0 -foreach output : qapi_util_outputs +foreach output : qapi_outputs if output.endswith('.h') genh += qapi_files[i] endif @@ -136,14 +129,3 @@ foreach output : qapi_util_outputs util_ss.add(qapi_files[i]) i = i + 1 endforeach - -foreach output : qapi_specific_outputs + qapi_nonmodule_outputs - if output.endswith('.h') - genh += qapi_files[i] - endif - if output.endswith('.trace-events') - qapi_trace_events += qapi_files[i] - endif - specific_ss.add(when: 'CONFIG_SYSTEM_ONLY', if_true: qapi_files[i]) - i = i + 1 -endforeach diff --git a/qapi/migration.json b/qapi/migration.json index 8b9c535..2387c21 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -3,7 +3,9 @@ # ## -# = Migration +# ********* +# Migration +# ********* ## { 'include': 'common.json' } @@ -57,8 +59,8 @@ # # @dirty-sync-missed-zero-copy: Number of times dirty RAM # synchronization could not avoid copying dirty pages. This is -# between 0 and @dirty-sync-count * @multifd-channels. (since -# 7.1) +# between 0 and @dirty-sync-count * @multifd-channels. +# (since 7.1) # # Since: 0.14 ## @@ -137,16 +139,16 @@ # # @active: in the process of doing migration. # -# @postcopy-active: like active, but now in postcopy mode. (since -# 2.5) +# @postcopy-active: like active, but now in postcopy mode. +# (since 2.5) # # @postcopy-paused: during postcopy but paused. (since 3.0) # # @postcopy-recover-setup: setup phase for a postcopy recovery # process, preparing for a recovery phase to start. (since 9.1) # -# @postcopy-recover: trying to recover from a paused postcopy. (since -# 3.0) +# @postcopy-recover: trying to recover from a paused postcopy. +# (since 3.0) # # @completed: migration is finished. # @@ -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) # @@ -236,10 +238,35 @@ # This is only present when the postcopy-blocktime migration # capability is enabled. (Since 3.0) # +# @postcopy-latency: average remote page fault latency (in ns). Note that +# this doesn't include all faults, but only the ones that require a +# remote page request. So it should be always bigger than the real +# average page fault latency. This is only present when the +# postcopy-blocktime migration capability is enabled. (Since 10.1) +# +# @postcopy-latency-dist: remote page fault latency distributions. Each +# element of the array is the number of faults that fall into the +# bucket period. For the N-th bucket (N>=0), the latency window is +# [2^Nus, 2^(N+1)us). For example, the 8th element stores how many +# remote faults got resolved within [256us, 512us) window. This is only +# present when the postcopy-blocktime migration capability is enabled. +# (Since 10.1) +# +# @postcopy-vcpu-latency: average remote page fault latency per vCPU (in +# ns). It has the same definition of @postcopy-latency, but instead +# this is the per-vCPU statistics. This is only present when the +# postcopy-blocktime migration capability is enabled. (Since 10.1) +# +# @postcopy-non-vcpu-latency: average remote page fault latency for all +# faults happend in non-vCPU threads (in ns). It has the same +# definition of @postcopy-latency but this only provides statistics to +# non-vCPU faults. This is only present when the postcopy-blocktime +# migration capability is enabled. (Since 10.1) +# # @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) @@ -250,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 @@ -260,6 +287,11 @@ # average memory load of the virtual CPU indirectly. Note that # zero means guest doesn't dirty memory. (Since 8.1) # +# Features: +# +# @unstable: Members @postcopy-latency, @postcopy-vcpu-latency, +# @postcopy-latency-dist, @postcopy-non-vcpu-latency are experimental. +# # Since: 0.14 ## { 'struct': 'MigrationInfo', @@ -275,6 +307,14 @@ '*blocked-reasons': ['str'], '*postcopy-blocktime': 'uint32', '*postcopy-vcpu-blocktime': ['uint32'], + '*postcopy-latency': { + 'type': 'uint64', 'features': [ 'unstable' ] }, + '*postcopy-latency-dist': { + 'type': ['uint64'], 'features': [ 'unstable' ] }, + '*postcopy-vcpu-latency': { + 'type': ['uint64'], 'features': [ 'unstable' ] }, + '*postcopy-non-vcpu-latency': { + 'type': 'uint64', 'features': [ 'unstable' ] }, '*socket-address': ['SocketAddress'], '*dirty-limit-throttle-time-per-round': 'uint64', '*dirty-limit-ring-full-time': 'uint64'} } @@ -282,12 +322,10 @@ ## # @query-migrate: # -# Returns information about current migration process. If migration +# Return information about current migration process. If migration # is active there will be another json-object with RAM migration # status. # -# Returns: @MigrationInfo -# # Since: 0.14 # # .. qmp-example:: @@ -407,7 +445,7 @@ # @postcopy-ram: Start executing on the migration target before all of # RAM has been migrated, pulling the remaining pages along as # needed. The capacity must have the same setting on both source -# and target or migration will not even start. NOTE: If the +# and target or migration will not even start. **Note:** if the # migration fails during postcopy the VM will fail. (since 2.6) # # @x-colo: If enabled, migration will never end, and the state of the @@ -415,15 +453,15 @@ # on secondary side, this process is called COarse-Grain LOck # Stepping (COLO) for Non-stop Service. (since 2.8) # -# @release-ram: if enabled, qemu will free the migrated ram pages on +# @release-ram: if enabled, QEMU will free the migrated ram pages on # the source during postcopy-ram migration. (since 2.9) # # @return-path: If enabled, migration will use the return path even # for precopy. (since 2.10) # # @pause-before-switchover: Pause outgoing migration before -# serialising device state and before disabling block IO (since -# 2.11) +# serialising device state and before disabling block IO +# (since 2.11) # # @multifd: Use more than one fd for migration (since 4.0) # @@ -535,9 +573,7 @@ ## # @query-migrate-capabilities: # -# Returns information about the current migration capabilities status -# -# Returns: @MigrationCapabilityStatus +# Return information about the current migration capabilities status # # Since: 1.2 # @@ -591,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. # @@ -605,7 +641,7 @@ # # This mode supports VFIO devices provided the user first puts the # guest in the suspended runstate, such as by issuing -# guest-suspend-ram to the QEMU guest agent. +# `guest-suspend-ram` to the QEMU guest agent. # # Best performance is achieved when the memory backend is shared # and the @x-ignore-shared migration capability is set, but this @@ -620,8 +656,10 @@ # # @cpr-transfer: This mode allows the user to transfer a guest to a # new QEMU instance on the same host with minimal guest pause -# time by preserving guest RAM in place. Devices and their pinned -# pages will also be preserved in a future QEMU release. +# time by preserving guest RAM in place. +# +# Devices and their pinned pages are also preserved for VFIO and +# IOMMUFD. (since 10.1) # # The user starts new QEMU on the same host as old QEMU, with # command-line arguments to create the same machine, plus the @@ -639,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 @@ -650,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) ## @@ -697,8 +735,8 @@ # @alias: An alias name for migration (for example the bitmap name on # the opposite site). # -# @transform: Allows the modification of the migrated bitmap. (since -# 6.0) +# @transform: Allows the modification of the migrated bitmap. +# (since 6.0) # # Since: 5.2 ## @@ -760,9 +798,9 @@ # auto-converge detects that migration is not making progress. # The default value is 10. (Since 2.7) # -# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At -# the tail stage of throttling, the Guest is very sensitive to CPU -# percentage while the @cpu-throttle -increment is excessive +# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage. +# At the tail stage of throttling, the Guest is very sensitive to +# CPU percentage while the @cpu-throttle -increment is excessive # usually at tail stage. If this parameter is true, we will # compute the ideal CPU percentage used by the Guest, which may # exactly make the dirty rate match the dirty rate threshold. @@ -770,8 +808,8 @@ # specified by @cpu-throttle-increment and the one generated by # ideal CPU percentage. Therefore, it is compatible to # traditional throttling, meanwhile the throttle increment won't -# be excessive at tail stage. The default value is false. (Since -# 5.1) +# be excessive at tail stage. The default value is false. +# (Since 5.1) # # @tls-creds: ID of the 'tls-creds' object that provides credentials # for establishing a TLS connection over the migration data @@ -801,10 +839,10 @@ # (Since 2.8) # # @avail-switchover-bandwidth: to set the available bandwidth that -# migration can use during switchover phase. NOTE! This does not -# limit the bandwidth during switchover, but only for calculations -# when making decisions to switchover. By default, this value is -# zero, which means QEMU will estimate the bandwidth +# migration can use during switchover phase. **Note:** this does +# not limit the bandwidth during switchover, but only for +# calculations when making decisions to switchover. By default, +# this value is zero, which means QEMU will estimate the bandwidth # automatically. This can be set when the estimated value is not # accurate, while the user is able to guarantee such bandwidth is # available when switching over. When specified correctly, this @@ -842,9 +880,9 @@ # more CPU. Defaults to 1. (Since 5.0) # # @multifd-qatzip-level: Set the compression level to be used in live -# migration. The level is an integer between 1 and 9, where 1 means +# migration. The level is an integer between 1 and 9, where 1 means # the best compression speed, and 9 means the best compression -# ratio which will consume more CPU. Defaults to 1. (Since 9.2) +# ratio which will consume more CPU. Defaults to 1. (Since 9.2) # # @multifd-zstd-level: Set the compression level to be used in live # migration, the compression level is an integer between 0 and 20, @@ -875,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 @@ -941,9 +979,9 @@ # auto-converge detects that migration is not making progress. # The default value is 10. (Since 2.7) # -# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At -# the tail stage of throttling, the Guest is very sensitive to CPU -# percentage while the @cpu-throttle -increment is excessive +# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage. +# At the tail stage of throttling, the Guest is very sensitive to +# CPU percentage while the @cpu-throttle -increment is excessive # usually at tail stage. If this parameter is true, we will # compute the ideal CPU percentage used by the Guest, which may # exactly make the dirty rate match the dirty rate threshold. @@ -951,8 +989,8 @@ # specified by @cpu-throttle-increment and the one generated by # ideal CPU percentage. Therefore, it is compatible to # traditional throttling, meanwhile the throttle increment won't -# be excessive at tail stage. The default value is false. (Since -# 5.1) +# be excessive at tail stage. The default value is false. +# (Since 5.1) # # @tls-creds: ID of the 'tls-creds' object that provides credentials # for establishing a TLS connection over the migration data @@ -982,10 +1020,10 @@ # (Since 2.8) # # @avail-switchover-bandwidth: to set the available bandwidth that -# migration can use during switchover phase. NOTE! This does not -# limit the bandwidth during switchover, but only for calculations -# when making decisions to switchover. By default, this value is -# zero, which means QEMU will estimate the bandwidth +# migration can use during switchover phase. **Note:** this does +# not limit the bandwidth during switchover, but only for +# calculations when making decisions to switchover. By default, +# this value is zero, which means QEMU will estimate the bandwidth # automatically. This can be set when the estimated value is not # accurate, while the user is able to guarantee such bandwidth is # available when switching over. When specified correctly, this @@ -1023,9 +1061,9 @@ # more CPU. Defaults to 1. (Since 5.0) # # @multifd-qatzip-level: Set the compression level to be used in live -# migration. The level is an integer between 1 and 9, where 1 means +# migration. The level is an integer between 1 and 9, where 1 means # the best compression speed, and 9 means the best compression -# ratio which will consume more CPU. Defaults to 1. (Since 9.2) +# ratio which will consume more CPU. Defaults to 1. (Since 9.2) # # @multifd-zstd-level: Set the compression level to be used in live # migration, the compression level is an integer between 0 and 20, @@ -1056,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 @@ -1072,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 ## @@ -1148,16 +1186,16 @@ # percentage. The default value is 50. (Since 5.0) # # @cpu-throttle-initial: Initial percentage of time guest cpus are -# throttled when migration auto-converge is activated. (Since -# 2.7) +# throttled when migration auto-converge is activated. +# (Since 2.7) # # @cpu-throttle-increment: throttle percentage increase each time # auto-converge detects that migration is not making progress. # (Since 2.7) # -# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At -# the tail stage of throttling, the Guest is very sensitive to CPU -# percentage while the @cpu-throttle -increment is excessive +# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage. +# At the tail stage of throttling, the Guest is very sensitive to +# CPU percentage while the @cpu-throttle -increment is excessive # usually at tail stage. If this parameter is true, we will # compute the ideal CPU percentage used by the Guest, which may # exactly make the dirty rate match the dirty rate threshold. @@ -1165,8 +1203,8 @@ # specified by @cpu-throttle-increment and the one generated by # ideal CPU percentage. Therefore, it is compatible to # traditional throttling, meanwhile the throttle increment won't -# be excessive at tail stage. The default value is false. (Since -# 5.1) +# be excessive at tail stage. The default value is false. +# (Since 5.1) # # @tls-creds: ID of the 'tls-creds' object that provides credentials # for establishing a TLS connection over the migration data @@ -1192,10 +1230,10 @@ # (Since 2.8) # # @avail-switchover-bandwidth: to set the available bandwidth that -# migration can use during switchover phase. NOTE! This does not -# limit the bandwidth during switchover, but only for calculations -# when making decisions to switchover. By default, this value is -# zero, which means QEMU will estimate the bandwidth +# migration can use during switchover phase. **Note:** this does +# not limit the bandwidth during switchover, but only for +# calculations when making decisions to switchover. By default, +# this value is zero, which means QEMU will estimate the bandwidth # automatically. This can be set when the estimated value is not # accurate, while the user is able to guarantee such bandwidth is # available when switching over. When specified correctly, this @@ -1233,9 +1271,9 @@ # more CPU. Defaults to 1. (Since 5.0) # # @multifd-qatzip-level: Set the compression level to be used in live -# migration. The level is an integer between 1 and 9, where 1 means +# migration. The level is an integer between 1 and 9, where 1 means # the best compression speed, and 9 means the best compression -# ratio which will consume more CPU. Defaults to 1. (Since 9.2) +# ratio which will consume more CPU. Defaults to 1. (Since 9.2) # # @multifd-zstd-level: Set the compression level to be used in live # migration, the compression level is an integer between 0 and 20, @@ -1266,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 @@ -1320,9 +1358,7 @@ ## # @query-migrate-parameters: # -# Returns information about the current migration parameters -# -# Returns: @MigrationParameters +# Return information about the current migration parameters # # Since: 2.4 # @@ -1362,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 # @@ -1483,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. # @@ -1500,7 +1536,7 @@ ## # @x-colo-lost-heartbeat: # -# Tell qemu that heartbeat is lost, request it to do takeover +# Tell QEMU that heartbeat is lost, request it to do takeover # procedures. If this command is sent to the PVM, the Primary side # will exit COLO mode. If sent to the Secondary, the Secondary side # will run failover work, then takes over server operation to become @@ -1660,27 +1696,26 @@ # # @resume: resume one paused migration, default "off". (since 3.0) # +# Features: +# +# @deprecated: Argument @detach is deprecated. +# # Since: 0.14 # # .. admonition:: Notes # -# 1. The 'query-migrate' command should be used to check +# 1. The `query-migrate` command should be used to check # migration's progress and final result (this information is # provided by the 'status' member). # -# 2. All boolean arguments default to false. -# -# 3. The user Monitor's "detach" argument is invalid in QMP and -# should not be used. -# -# 4. The uri argument should have the Uniform Resource Identifier +# 2. The uri argument should have the Uniform Resource Identifier # of default destination VM. This connection will be bound to # default network. # -# 5. For now, number of migration streams is restricted to one, +# 3. For now, number of migration streams is restricted to one, # i.e. number of items in 'channels' list is just 1. # -# 6. The 'uri' and 'channels' arguments are mutually exclusive; +# 4. The 'uri' and 'channels' arguments are mutually exclusive; # exactly one of the two should be present. # # .. qmp-example:: @@ -1724,13 +1759,14 @@ { 'command': 'migrate', 'data': {'*uri': 'str', '*channels': [ 'MigrationChannel' ], - '*detach': 'bool', '*resume': 'bool' } } + '*detach': { 'type': 'bool', 'features': [ 'deprecated' ] }, + '*resume': 'bool' } } ## # @migrate-incoming: # -# Start an incoming migration, the qemu must have been started with -# -incoming defer +# Start an incoming migration. QEMU must have been started with +# -incoming defer. # # @uri: The Uniform Resource Identifier identifying the source or # address to listen on @@ -1739,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 @@ -1752,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 # @@ -1805,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 @@ -1846,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 @@ -1886,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. # @@ -1904,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:: # @@ -1935,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'. @@ -1958,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:: # @@ -2059,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 # @@ -2127,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 @@ -2200,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) @@ -2250,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. # @@ -2275,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. # @@ -2294,7 +2330,7 @@ ## # @query-vcpu-dirty-limit: # -# Returns information about virtual CPU dirty page rate limits, if +# Return information about virtual CPU dirty page rate limits, if # any. # # Since: 7.1 @@ -2327,14 +2363,12 @@ ## # @query-migrationthreads: # -# Returns information of migration threads +# Return information of migration threads # # Features: # # @deprecated: This command is deprecated with no replacement yet. # -# Returns: @MigrationThreadInfo -# # Since: 7.2 ## { 'command': 'query-migrationthreads', @@ -2435,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 new file mode 100644 index 0000000..f921d74 --- /dev/null +++ b/qapi/misc-arm.json @@ -0,0 +1,47 @@ +# -*- Mode: Python -*- +# vim: filetype=python +# +# SPDX-License-Identifier: GPL-2.0-or-later + +## +# @GICCapability: +# +# The struct describes capability for a specific GIC (Generic +# Interrupt Controller) version. These bits are not only decided by +# QEMU/KVM software version, but also decided by the hardware that the +# program is running upon. +# +# @version: version of GIC to be described. Currently, only 2 and 3 +# are supported. +# +# @emulated: whether current QEMU/hardware supports emulated GIC +# device in user space. +# +# @kernel: whether current QEMU/hardware supports hardware accelerated +# GIC device in kernel. +# +# Since: 2.6 +## +{ 'struct': 'GICCapability', + 'data': { 'version': 'int', + 'emulated': 'bool', + 'kernel': 'bool' } } + +## +# @query-gic-capabilities: +# +# 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. +# +# Since: 2.6 +# +# .. qmp-example:: +# +# -> { "execute": "query-gic-capabilities" } +# <- { "return": [{ "version": 2, "emulated": true, "kernel": false }, +# { "version": 3, "emulated": false, "kernel": true } ] } +## +{ 'command': 'query-gic-capabilities', 'returns': ['GICCapability'] } diff --git a/qapi/misc-target.json b/qapi/misc-i386.json index 42e4a74..d1ce8ca 100644 --- a/qapi/misc-target.json +++ b/qapi/misc-i386.json @@ -1,13 +1,18 @@ # -*- Mode: Python -*- # vim: filetype=python # +# SPDX-License-Identifier: GPL-2.0-or-later ## # @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 +# action. # # Since: 2.1 # @@ -16,13 +21,12 @@ # -> { "execute": "rtc-reset-reinjection" } # <- { "return": {} } ## -{ 'command': 'rtc-reset-reinjection', - 'if': 'TARGET_I386' } +{ 'command': 'rtc-reset-reinjection' } ## # @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. # @@ -44,8 +48,7 @@ ## { 'enum': 'SevState', 'data': ['uninit', 'launch-update', 'launch-secret', 'running', - 'send-update', 'receive-update' ], - 'if': 'TARGET_I386' } + 'send-update', 'receive-update' ] } ## # @SevGuestType: @@ -59,8 +62,7 @@ # Since: 6.2 ## { 'enum': 'SevGuestType', - 'data': [ 'sev', 'sev-snp' ], - 'if': 'TARGET_I386' } + 'data': [ 'sev', 'sev-snp' ] } ## # @SevGuestInfo: @@ -75,8 +77,7 @@ ## { 'struct': 'SevGuestInfo', 'data': { 'policy': 'uint32', - 'handle': 'uint32' }, - 'if': 'TARGET_I386' } + 'handle': 'uint32' } } ## # @SevSnpGuestInfo: @@ -88,8 +89,7 @@ # Since: 9.1 ## { 'struct': 'SevSnpGuestInfo', - 'data': { 'snp-policy': 'uint64' }, - 'if': 'TARGET_I386' } + 'data': { 'snp-policy': 'uint64' } } ## # @SevInfo: @@ -120,16 +120,17 @@ 'discriminator': 'sev-type', 'data': { 'sev': 'SevGuestInfo', - 'sev-snp': 'SevSnpGuestInfo' }, - 'if': 'TARGET_I386' } + 'sev-snp': 'SevSnpGuestInfo' } } ## # @query-sev: # -# Returns information about SEV +# Return information about SEV/SEV-ES/SEV-SNP. # -# Returns: @SevInfo +# If unavailable due to an incompatible configuration the returned +# @enabled field is set to 'false' and the state of all other fields +# is unspecified. # # Since: 2.12 # @@ -140,8 +141,7 @@ # "build-id" : 0, "policy" : 0, "state" : "running", # "handle" : 1 } } ## -{ 'command': 'query-sev', 'returns': 'SevInfo', - 'if': 'TARGET_I386' } +{ 'command': 'query-sev', 'returns': 'SevInfo' } ## # @SevLaunchMeasureInfo: @@ -152,15 +152,23 @@ # # Since: 2.12 ## -{ 'struct': 'SevLaunchMeasureInfo', 'data': {'data': 'str'}, - 'if': 'TARGET_I386' } +{ 'struct': 'SevLaunchMeasureInfo', 'data': {'data': 'str'} } ## # @query-sev-launch-measure: # -# Query the SEV guest launch information. +# Query the SEV/SEV-ES guest launch information. +# +# This is only valid on x86 machines configured with KVM and the +# '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 +# invalid guest configuration or if the guest has not reached +# the required SEV state, GenericError # # Since: 2.12 # @@ -169,8 +177,7 @@ # -> { "execute": "query-sev-launch-measure" } # <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } } ## -{ 'command': 'query-sev-launch-measure', 'returns': 'SevLaunchMeasureInfo', - 'if': 'TARGET_I386' } +{ 'command': 'query-sev-launch-measure', 'returns': 'SevLaunchMeasureInfo' } ## # @SevCapability: @@ -186,7 +193,7 @@ # # @cbitpos: C-bit location in page table entry # -# @reduced-phys-bits: Number of physical Address bit reduction when +# @reduced-phys-bits: Number of physical address bit reduction when # SEV is enabled # # Since: 2.12 @@ -196,16 +203,17 @@ 'cert-chain': 'str', 'cpu0-id': 'str', 'cbitpos': 'int', - 'reduced-phys-bits': 'int'}, - 'if': 'TARGET_I386' } + 'reduced-phys-bits': 'int'} } ## # @query-sev-capabilities: # -# This command is used to get the SEV capabilities, and is supported -# on AMD X86 platforms only. +# Get SEV capabilities. +# +# This is only supported on AMD X86 platforms with KVM enabled. # -# Returns: SevCapability objects. +# Errors: +# - If SEV is not available on the platform, GenericError # # Since: 2.12 # @@ -216,13 +224,16 @@ # "cpu0-id": "2lvmGwo+...61iEinw==", # "cbitpos": 47, "reduced-phys-bits": 1}} ## -{ 'command': 'query-sev-capabilities', 'returns': 'SevCapability', - 'if': 'TARGET_I386' } +{ 'command': 'query-sev-capabilities', 'returns': 'SevCapability' } ## # @sev-inject-launch-secret: # -# This command injects a secret blob into memory of SEV 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 +# not support launch secret injection. # # @packet-header: the launch secret packet header encoded in base64 # @@ -230,11 +241,15 @@ # # @gpa: the guest physical address where secret will be injected. # +# Errors: +# - If launch secret injection is not possible, either due to +# an invalid guest configuration, or if the guest has not +# reached the required SEV state, GenericError +# # Since: 6.0 ## { 'command': 'sev-inject-launch-secret', - 'data': { 'packet-header': 'str', 'secret': 'str', '*gpa': 'uint64' }, - 'if': 'TARGET_I386' } + 'data': { 'packet-header': 'str', 'secret': 'str', '*gpa': 'uint64' } } ## # @SevAttestationReport: @@ -247,19 +262,24 @@ # Since: 6.1 ## { 'struct': 'SevAttestationReport', - 'data': { 'data': 'str'}, - 'if': 'TARGET_I386' } + 'data': { 'data': 'str'} } ## # @query-sev-attestation-report: # -# This command is used to get the SEV attestation report, and is -# supported on AMD X86 platforms only. +# Get the SEV attestation report. +# +# This is only valid on x86 machines configured with KVM and the +# 'sev-guest' confidential virtualization object. The attestation +# report for SEV-SNP guests is only available within the guest. # # @mnonce: a random 16 bytes value encoded in base64 (it will be # included in report) # -# Returns: SevAttestationReport objects. +# Errors: +# - If the attestation report is unavailable, either due to an +# invalid guest configuration or because the guest has not +# reached the required SEV state, GenericError # # Since: 6.1 # @@ -271,57 +291,12 @@ ## { 'command': 'query-sev-attestation-report', 'data': { 'mnonce': 'str' }, - 'returns': 'SevAttestationReport', - 'if': 'TARGET_I386' } + 'returns': 'SevAttestationReport' } ## -# @GICCapability: +# @SgxEpcSection: # -# The struct describes capability for a specific GIC (Generic -# Interrupt Controller) version. These bits are not only decided by -# QEMU/KVM software version, but also decided by the hardware that the -# program is running upon. -# -# @version: version of GIC to be described. Currently, only 2 and 3 -# are supported. -# -# @emulated: whether current QEMU/hardware supports emulated GIC -# device in user space. -# -# @kernel: whether current QEMU/hardware supports hardware accelerated -# GIC device in kernel. -# -# Since: 2.6 -## -{ 'struct': 'GICCapability', - 'data': { 'version': 'int', - 'emulated': 'bool', - 'kernel': 'bool' }, - 'if': 'TARGET_ARM' } - -## -# @query-gic-capabilities: -# -# This command is ARM-only. It will return a list of GICCapability -# objects that describe its capability bits. -# -# Returns: a list of GICCapability objects. -# -# Since: 2.6 -# -# .. qmp-example:: -# -# -> { "execute": "query-gic-capabilities" } -# <- { "return": [{ "version": 2, "emulated": true, "kernel": false }, -# { "version": 3, "emulated": false, "kernel": true } ] } -## -{ 'command': 'query-gic-capabilities', 'returns': ['GICCapability'], - 'if': 'TARGET_ARM' } - -## -# @SGXEPCSection: -# -# Information about intel SGX EPC section info +# Information about intel SGX EPC section # # @node: the numa node # @@ -329,12 +304,12 @@ # # Since: 7.0 ## -{ 'struct': 'SGXEPCSection', +{ 'struct': 'SgxEpcSection', 'data': { 'node': 'int', 'size': 'uint64'}} ## -# @SGXInfo: +# @SgxInfo: # # Information about intel Safe Guard eXtension (SGX) support # @@ -346,24 +321,21 @@ # # @flc: true if FLC is supported # -# @sections: The EPC sections info for guest (Since: 7.0) +# @sections: The EPC sections information (Since: 7.0) # # Since: 6.2 ## -{ 'struct': 'SGXInfo', +{ 'struct': 'SgxInfo', 'data': { 'sgx': 'bool', 'sgx1': 'bool', 'sgx2': 'bool', 'flc': 'bool', - 'sections': ['SGXEPCSection']}, - 'if': 'TARGET_I386' } + 'sections': ['SgxEpcSection']} } ## # @query-sgx: # -# Returns information about SGX -# -# Returns: @SGXInfo +# Return information about configured SGX capabilities of guest # # Since: 6.2 # @@ -375,14 +347,12 @@ # "sections": [{"node": 0, "size": 67108864}, # {"node": 1, "size": 29360128}]} } ## -{ 'command': 'query-sgx', 'returns': 'SGXInfo', 'if': 'TARGET_I386' } +{ 'command': 'query-sgx', 'returns': 'SgxInfo' } ## # @query-sgx-capabilities: # -# Returns information from host SGX capabilities -# -# Returns: @SGXInfo +# Return information about SGX capabilities of host # # Since: 6.2 # @@ -394,8 +364,7 @@ # "section" : [{"node": 0, "size": 67108864}, # {"node": 1, "size": 29360128}]} } ## -{ 'command': 'query-sgx-capabilities', 'returns': 'SGXInfo', 'if': 'TARGET_I386' } - +{ 'command': 'query-sgx-capabilities', 'returns': 'SgxInfo' } ## # @EvtchnPortType: @@ -417,8 +386,7 @@ # Since: 8.0 ## { 'enum': 'EvtchnPortType', - 'data': ['closed', 'unbound', 'interdomain', 'pirq', 'virq', 'ipi'], - 'if': 'TARGET_I386' } + 'data': ['closed', 'unbound', 'interdomain', 'pirq', 'virq', 'ipi'] } ## # @EvtchnInfo: @@ -448,8 +416,7 @@ 'remote-domain': 'str', 'target': 'uint16', 'pending': 'bool', - 'masked': 'bool'}, - 'if': 'TARGET_I386' } + 'masked': 'bool'} } ## @@ -487,8 +454,7 @@ # } ## { 'command': 'xen-event-list', - 'returns': ['EvtchnInfo'], - 'if': 'TARGET_I386' } + 'returns': ['EvtchnInfo'] } ## # @xen-event-inject: @@ -505,5 +471,4 @@ # <- { "return": { } } ## { 'command': 'xen-event-inject', - 'data': { 'port': 'uint32' }, - 'if': 'TARGET_I386' } + 'data': { 'port': 'uint32' } } diff --git a/qapi/misc.json b/qapi/misc.json index 559b66f..28c641f 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:: @@ -101,13 +101,13 @@ ## # @query-iothreads: # -# Returns a list of information about each iothread. +# Return a list of information about each iothread. # # .. note:: This list excludes the QEMU main loop thread, which is not # 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 # @@ -222,13 +222,13 @@ # .. note:: This command only exists as a stop-gap. Its use is highly # discouraged. The semantics of this command are not guaranteed: # this means that command names, arguments and responses can change -# or be removed at ANY time. Applications that rely on long term -# stability guarantees should NOT use this command. +# or be removed at **any** time. Applications that rely on long +# term stability guarantees should **not** use this command. # # 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 310cc4f..78bcc98 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 @@ -150,12 +265,12 @@ # @domainname: guest-visible domain name of the virtual nameserver # (since 3.0) # -# @ipv6-prefix: IPv6 network prefix (default is fec0::) (since 2.6). -# The network prefix is given in the usual hexadecimal IPv6 -# address notation. +# @ipv6-prefix: IPv6 network prefix (default is fec0::). The network +# prefix is given in the usual hexadecimal IPv6 address notation. +# (since 2.6) # -# @ipv6-prefixlen: IPv6 network prefix length (default is 64) (since -# 2.6) +# @ipv6-prefixlen: IPv6 network prefix length (default is 64) +# (since 2.6) # # @ipv6-host: guest-visible IPv6 address of the host (since 2.6) # @@ -387,8 +502,8 @@ # # @hubid: hub identifier number # -# @netdev: used to connect hub to a netdev instead of a device (since -# 2.12) +# @netdev: used to connect hub to a netdev instead of a device +# (since 2.12) # # Since: 1.2 ## @@ -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' } ## @@ -510,8 +634,8 @@ # @queues: number of queues to be created for multiqueue vhost-vdpa # (default: 1) # -# @x-svq: Start device with (experimental) shadow virtqueue. (Since -# 7.1) (default: false) +# @x-svq: Start device with (experimental) shadow virtqueue. +# (Since 7.1) (default: false) # # Features: # @@ -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 dc85a41..694c741 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 7bc600b..82f111b 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). @@ -37,6 +39,7 @@ { 'include': 'run-state.json' } { 'include': 'crypto.json' } { 'include': 'job.json' } +{ 'include': 'accelerator.json' } { 'include': 'block.json' } { 'include': 'block-export.json' } { 'include': 'char.json' } @@ -57,11 +60,12 @@ { 'include': 'qdev.json' } { 'include': 'machine-common.json' } { 'include': 'machine.json' } -{ 'include': 'machine-target.json' } +{ 'include': 'machine-s390x.json' } { 'include': 'replay.json' } { 'include': 'yank.json' } { 'include': 'misc.json' } -{ 'include': 'misc-target.json' } +{ 'include': 'misc-arm.json' } +{ 'include': 'misc-i386.json' } { 'include': 'audio.json' } { 'include': 'acpi.json' } { 'include': 'pci.json' } diff --git a/qapi/qdev.json b/qapi/qdev.json index 32c7d10..e14a0c9 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 28ce24c..830cb2f 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -10,7 +10,9 @@ { 'include': 'crypto.json' } ## -# = QEMU Object Model (QOM) +# *********************** +# QEMU Object Model (QOM) +# *********************** ## ## @@ -46,16 +48,42 @@ '*default-value': 'any' } } ## +# @ObjectPropertyValue: +# +# @name: the name of the property. +# +# @type: the type of the property, as described in `ObjectPropertyInfo`. +# +# @value: the value of the property. Absent when the property cannot +# be read. +# +# Since 10.1 +## +{ 'struct': 'ObjectPropertyValue', + 'data': { 'name': 'str', + 'type': 'str', + '*value': 'any' } } + +## +# @ObjectPropertiesValues: +# +# @properties: a list of properties. +# +# Since 10.1 +## +{ 'struct': 'ObjectPropertiesValues', + 'data': { 'properties': [ 'ObjectPropertyValue' ] }} + + +## # @qom-list: # -# 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 +104,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. @@ -126,16 +153,38 @@ 'allow-preconfig': true } ## +# @qom-list-get: +# +# List properties and their values for each object path in the input +# list. +# +# @paths: The absolute or partial path for each object, as described +# in `qom-get`. +# +# Errors: +# - If any path is not valid or is ambiguous +# +# Returns: A list where each element is the result for the +# corresponding element of @paths. +# +# Since 10.1 +## +{ 'command': 'qom-list-get', + 'data': { 'paths': [ 'str' ] }, + 'returns': [ 'ObjectPropertiesValues' ], + 'allow-preconfig': true } + +## # @qom-set: # -# 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 +203,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 +220,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 +243,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 +838,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 +867,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 @@ -870,8 +919,8 @@ # information read from devices and switches in conjunction with # link characteristics read from PCIe Configuration space. # To get the full path latency from CPU to CXL attached DRAM -# CXL device: Add the latency from CPU to Generic Port (from -# HMAT indexed via the the node ID in this SRAT structure) to +# CXL device: Add the latency from CPU to Generic Port (from +# HMAT indexed via the node ID in this SRAT structure) to # that for CXL bus links, the latency across intermediate switches # and from the EP port to the actual memory. Bandwidth is more # complex as there may be interleaving across multiple devices @@ -933,6 +982,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. @@ -1048,6 +1110,45 @@ '*vcek-disabled': 'bool' } } ## +# @TdxGuestProperties: +# +# Properties for tdx-guest objects. +# +# @attributes: The 'attributes' of a TD guest that is passed to +# KVM_TDX_INIT_VM +# +# @sept-ve-disable: toggle bit 28 of TD attributes to control disabling +# of EPT violation conversion to #VE on guest TD access of PENDING +# pages. Some guest OS (e.g., Linux TD guest) may require this to +# be set, otherwise they refuse to boot. +# +# @mrconfigid: ID for non-owner-defined configuration of the guest TD, +# e.g., run-time or OS configuration (base64 encoded SHA384 digest). +# Defaults to all zeros. +# +# @mrowner: ID for the guest TD’s owner (base64 encoded SHA384 digest). +# Defaults to all zeros. +# +# @mrownerconfig: ID for owner-defined configuration of the guest TD, +# e.g., specific to the workload rather than the run-time or OS +# (base64 encoded SHA384 digest). Defaults to all zeros. +# +# @quote-generation-socket: socket address for Quote Generation +# Service (QGS). QGS is a daemon running on the host. Without +# it, the guest will not be able to get a TD quote for +# attestation. +# +# Since: 10.1 +## +{ 'struct': 'TdxGuestProperties', + 'data': { '*attributes': 'uint64', + '*sept-ve-disable': 'bool', + '*mrconfigid': 'str', + '*mrowner': 'str', + '*mrownerconfig': 'str', + '*quote-generation-socket': 'SocketAddress' } } + +## # @ThreadContextProperties: # # Properties for thread context objects. @@ -1103,6 +1204,8 @@ 'filter-redirector', 'filter-replay', 'filter-rewriter', + { 'name': 'igvm-cfg', + 'if': 'CONFIG_IGVM' }, 'input-barrier', { 'name': 'input-linux', 'if': 'CONFIG_LINUX' }, @@ -1132,6 +1235,7 @@ 'sev-snp-guest', 'thread-context', 's390-pv-guest', + 'tdx-guest', 'throttle-group', 'tls-creds-anon', 'tls-creds-psk', @@ -1178,6 +1282,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' }, @@ -1204,6 +1310,7 @@ 'if': 'CONFIG_SECRET_KEYRING' }, 'sev-guest': 'SevGuestProperties', 'sev-snp-guest': 'SevSnpGuestProperties', + 'tdx-guest': 'TdxGuestProperties', 'thread-context': 'ThreadContextProperties', 'throttle-group': 'ThrottleGroupProperties', 'tls-creds-anon': 'TlsCredsAnonProperties', @@ -1220,7 +1327,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 # @@ -1242,7 +1349,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 35e0c4a..ccf84da 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 0c7ef1f..5d2dbd2 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 ce95cfa..4757947 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -3,7 +3,9 @@ # ## -# = VM run state +# ************ +# VM run state +# ************ ## ## @@ -18,7 +20,7 @@ # @inmigrate: guest is paused waiting for an incoming migration. Note # that this state does not tell whether the machine will start at # the end of the migration. This depends on the command-line -S -# option and any invocation of 'stop' or 'cont' that has happened +# option and any invocation of `stop` or `cont` that has happened # since QEMU was started. # # @internal-error: An internal error that prevents further guest @@ -62,15 +64,15 @@ ## # @ShutdownCause: # -# An enumeration of reasons for a Shutdown. +# An enumeration of reasons for a shutdown. # # @none: No shutdown request pending # # @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:: @@ -135,20 +135,20 @@ ## # @SHUTDOWN: # -# Emitted when the virtual machine has shut down, indicating that qemu +# Emitted when the virtual machine has shut down, indicating that QEMU # is about to exit. # # @guest: If true, the shutdown was triggered by a guest request (such # as a guest-initiated ACPI shutdown request or other # hardware-specific action) rather than a host request (such as -# sending qemu a SIGINT). (since 2.10) +# 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. @@ -365,8 +365,8 @@ # @shutdown: Shutdown the VM and exit, according to the shutdown # action # -# @exit-failure: Shutdown the VM and exit with nonzero status (since -# 7.1) +# @exit-failure: Shutdown the VM and exit with nonzero status +# (since 7.1) # # Since: 6.0 ## @@ -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 # @@ -501,10 +501,12 @@ # # @s390: s390 guest panic information type (Since: 2.12) # +# @tdx: tdx guest panic information type (Since: 10.1) +# # Since: 2.9 ## { 'enum': 'GuestPanicInformationType', - 'data': [ 'hyper-v', 's390' ] } + 'data': [ 'hyper-v', 's390', 'tdx' ] } ## # @GuestPanicInformation: @@ -519,27 +521,28 @@ 'base': {'type': 'GuestPanicInformationType'}, 'discriminator': 'type', 'data': {'hyper-v': 'GuestPanicInformationHyperV', - 's390': 'GuestPanicInformationS390'}} + 's390': 'GuestPanicInformationS390', + 'tdx' : 'GuestPanicInformationTdx'}} ## # @GuestPanicInformationHyperV: # # 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 @@ -599,15 +602,39 @@ 'reason': 'S390CrashReason'}} ## +# @GuestPanicInformationTdx: +# +# TDX Guest panic information specific to TDX, as specified in the +# "Guest-Hypervisor Communication Interface (GHCI) Specification", +# section TDG.VP.VMCALL<ReportFatalError>. +# +# @error-code: TD-specific error code +# +# @message: Human-readable error message provided by the guest. Not +# to be trusted. +# +# @gpa: guest-physical address of a page that contains more verbose +# error information, as zero-terminated string. Present when the +# "GPA valid" bit (bit 63) is set in @error-code. +# +# +# Since: 10.1 +## +{'struct': 'GuestPanicInformationTdx', + 'data': {'error-code': 'uint32', + 'message': 'str', + '*gpa': 'uint64'}} + +## # @MEMORY_FAILURE: # # 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 6a95023..32fac51 100644 --- a/qapi/sockets.json +++ b/qapi/sockets.json @@ -2,7 +2,9 @@ # vim: filetype=python ## -# = Socket data types +# ***************** +# Socket data types +# ***************** ## ## @@ -56,8 +58,24 @@ # @ipv6: whether to accept IPv6 addresses, default try both IPv4 and # IPv6 # -# @keep-alive: enable keep-alive when connecting to this socket. Not -# supported for passive sockets. (Since 4.2) +# @keep-alive: enable keep-alive when connecting to/listening on this socket. +# (Since 4.2, not supported for listening sockets until 10.1) +# +# @keep-alive-count: number of keep-alive packets sent before the connection is +# closed. Only supported for TCP sockets on systems where TCP_KEEPCNT +# socket option is defined (this includes Linux, Windows, macOS, FreeBSD, +# but not OpenBSD). When set to 0, system setting is used. (Since 10.1) +# +# @keep-alive-idle: time in seconds the connection needs to be idle before +# sending a keepalive packet. Only supported for TCP sockets on systems +# where TCP_KEEPIDLE socket option is defined (this includes Linux, +# Windows, macOS, FreeBSD, but not OpenBSD). When set to 0, system setting +# is used. (Since 10.1) +# +# @keep-alive-interval: time in seconds between keep-alive packets. Only +# supported for TCP sockets on systems where TCP_KEEPINTVL is defined (this +# includes Linux, Windows, macOS, FreeBSD, but not OpenBSD). When set to +# 0, system setting is used. (Since 10.1) # # @mptcp: enable multi-path TCP. (Since 6.1) # @@ -71,6 +89,9 @@ '*ipv4': 'bool', '*ipv6': 'bool', '*keep-alive': 'bool', + '*keep-alive-count': { 'type': 'uint32', 'if': 'HAVE_TCP_KEEPCNT' }, + '*keep-alive-idle': { 'type': 'uint32', 'if': 'HAVE_TCP_KEEPIDLE' }, + '*keep-alive-interval': { 'type': 'uint32', 'if': 'HAVE_TCP_KEEPINTVL' }, '*mptcp': { 'type': 'bool', 'if': 'HAVE_IPPROTO_MPTCP' } } } ## @@ -122,7 +143,7 @@ # # @str: decimal is for file descriptor number, otherwise it's a file # descriptor name. Named file descriptors are permitted in -# monitor commands, in combination with the 'getfd' command. +# monitor commands, in combination with the `getfd` command. # Decimal file descriptors are permitted at startup or other # contexts where no monitor context is active. # @@ -190,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 8902ef9..151ac43 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 a16a72e..3f2850a 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 eb5f63f..de369da 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 021e383..4b4eb09 100644 --- a/qapi/transaction.json +++ b/qapi/transaction.json @@ -3,7 +3,9 @@ # ## -# = Transactions +# ************ +# Transactions +# ************ ## { 'include': 'block-core.json' } @@ -21,7 +23,7 @@ ## # @ActionCompletionMode: # -# An enumeration of Transactional completion modes. +# An enumeration of transactional completion modes. # # @individual: Do not attempt to cancel any other Actions if any # Actions fail after the Transaction request succeeds. All @@ -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 ## @@ -223,15 +225,15 @@ # exists, the request will be rejected. Only some image formats # support it, for example, qcow2, and rbd, # -# On failure, qemu will try delete the newly created internal snapshot +# On failure, QEMU will try delete the newly created internal snapshot # 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 bdfcabe..a206c2e 100644 --- a/qapi/uefi.json +++ b/qapi/uefi.json @@ -3,9 +3,11 @@ # ## -# = UEFI Variable Store +# ******************* +# UEFI Variable Store +# ******************* # -# The qemu efi variable store implementation (hw/uefi/) uses this to +# The QEMU efi variable store implementation (hw/uefi/) uses this to # store non-volatile variables in json format on disk. # # This is an existing format already supported by (at least) two other diff --git a/qapi/ui.json b/qapi/ui.json index c536d4e..1b2f4a4 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. @@ -175,15 +177,15 @@ # @filename: the path of a new file to store the image # # @device: ID of the display device that should be dumped. If this -# parameter is missing, the primary display will be used. (Since -# 2.12) +# parameter is missing, the primary display will be used. +# (Since 2.12) # # @head: head to use in case the device supports multiple heads. If # this parameter is missing, head #0 will be used. Also note that # 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 ## @@ -323,9 +326,7 @@ ## # @query-spice: # -# Returns information about the current SPICE server -# -# Returns: @SpiceInfo +# Return information about the current SPICE server # # Since: 0.14 # @@ -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 @@ -654,9 +656,7 @@ ## # @query-vnc: # -# Returns information about the current VNC server -# -# Returns: @VncInfo +# Return information about the current VNC server # # Since: 0.14 # @@ -685,9 +685,7 @@ ## # @query-vnc-servers: # -# Returns a list of vnc servers. The list can be empty. -# -# Returns: a list of @VncInfo2 +# Return a list of vnc servers. The list can be empty. # # Since: 2.3 ## @@ -794,7 +792,9 @@ 'if': 'CONFIG_VNC' } ## -# = Input +# ***** +# Input +# ***** ## ## @@ -820,9 +820,9 @@ ## # @query-mice: # -# Returns information about each active mouse device +# 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,12 +1533,12 @@ # # 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). # -# @window-close: Allow to quit qemu with window close button +# @window-close: Allow to quit QEMU with window close button # (default: on). # # @show-cursor: Force showing the mouse cursor (default: off). @@ -1562,9 +1569,7 @@ ## # @query-display-options: # -# Returns information about display configuration -# -# Returns: @DisplayOptions +# Return information about display configuration # # Since: 3.1 ## diff --git a/qapi/vfio.json b/qapi/vfio.json index b53b7ca..a1a9c5b 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 d351d21..9d652fe 100644 --- a/qapi/virtio.json +++ b/qapi/virtio.json @@ -3,7 +3,9 @@ # ## -# = Virtio devices +# ************** +# Virtio devices +# ************** ## ## @@ -24,7 +26,7 @@ ## # @x-query-virtio: # -# Returns a list of all realized VirtIODevices +# Return a list of all realized VirtIODevices # # Features: # @@ -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 30f46c9..f3cd5c1 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:: # |