QAPI patches patches for 2024-01-26
# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmWzT/QSHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTznQQALpsbanZR+gfTDOI/kvFuoLtOdhibtxW
# /5IwAP68Hdj2unHyHRBaNQIwyAfnHlyks1ywNyv0JCAqoyLuoa/ertir3zKc/1xP
# hOer7C76jrWiL2Gg4EMxl1oWussyHLq7XtQQEmL4aLV+EnnoytUfnosUpO0Ee5Pg
# Fz1EwJi74LEfYtrZjfX/YXZrX+3PJpYywtSWlyDluER0xfjh5d3JAsrjpgcPHZKc
# fwD2W7myxnW8IRyHdIgbu6Spv0vcM39PMrIK0ZlnVKgUz+/YcMgeK0eSXd6y+FjX
# Wehd7Ik5YE8el+SvGDPEMSTCkA2CP7dEnKt9Fk1pn+N8YhPGnQxDSBQOIae5Tnbf
# rrlOrCWXqW2a5FtbG/E4SwtXZlOo1BjkSy6+xP86YwXr23DSafVaeJp4CUls+ABZ
# LX6vR0p6bxPxOwVhoYeqxv+TpdA206g0yhN7bknoIp42DG4oj81toD5Ki3fedfwC
# pPl2sxniBm4MaO57YXxFgSN0lrur5vCcPadRppGbrGEO8XaX7F+9c5OWsPh+jt1x
# /l+A7RakrTg39NR2X46D1clPj3NQHwMVNIoSJek4+nCnM7eKVhMSm9YjpQEPupt0
# Aa+5QdiKcgjYEoSljE6ZsYJIrxd0OoaSpP1BWl4P+NcjgyUGcUkQ2X3AEL8Xkm6H
# wLv5U6ob99eL
# =nXml
# -----END PGP SIGNATURE-----
# gpg: Signature made Fri 26 Jan 2024 06:23:48 GMT
# gpg: using RSA key
354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg: issuer "armbru@redhat.com"
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [full]
# gpg: aka "Markus Armbruster <armbru@pond.sub.org>" [full]
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867 4E5F 3870 B400 EB91 8653
* tag 'pull-qapi-2024-01-26' of https://repo.or.cz/qemu/armbru:
qapi: Fix malformed "Since:" section tags (again)
qapi: Indent tagged doc comment sections properly
qapi: Fix mangled "Returns" sections in documentation
docs/interop/bitmaps: Clean up a reference to qemu-qmp-ref
qapi: Fix dangling references to docs/devel/qapi-code-gen.txt
docs: Replace dangling references to docs/interop/qmp-intro.txt
docs/devel/qapi-code-gen: Fix missing ':' in tagged section docs
docs/devel/qapi-code-gen: Don't reserve types ending with 'Kind'
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
generally speaking, type definitions should always use CamelCase for
user-defined type names, while built-in types are lowercase.
-Type names ending with ``Kind`` or ``List`` are reserved for the
-generator, which uses them for implicit union enums and array types,
-respectively.
+Type names ending with ``List`` are reserved for the generator, which
+uses them for array types.
Command names, member names within a type, and feature names should be
all lower case with words separated by a hyphen. However, some
# @feature: Description text
A tagged section starts with one of the following words:
-"Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:".
-The section ends with the start of a new section.
+"Note:"/"Notes:", "Since:", "Example:"/"Examples:", "Returns:",
+"TODO:". The section ends with the start of a new section.
The second and subsequent lines of sections other than
"Example"/"Examples" should be indented like this::
into the QAPI framework implementation.
For an in-depth introduction to the QAPI framework, please refer to
-docs/devel/qapi-code-gen.txt. For documentation about the QMP protocol,
-start with docs/interop/qmp-intro.txt.
+:doc:`qapi-code-gen`. For the QMP protocol, see the
+:doc:`/interop/qmp-spec`.
New commands may be implemented in QMP only. New HMP commands should be
implemented on top of QMP. The typical HMP command wraps around an
---------------
The primary interface to manipulating bitmap objects is via the QMP
-interface. If you are not familiar, see docs/interop/qmp-intro.txt for a broad
-overview, and `qemu-qmp-ref <qemu-qmp-ref.html>`_ for a full reference of all
-QMP commands.
+interface. If you are not familiar, see the :doc:`qmp-spec` for the
+protocol, and :doc:`qemu-qmp-ref` for a full reference of all QMP
+commands.
Supported Commands
~~~~~~~~~~~~~~~~~~
* limitations; see the documentation for each visitor for more
* details on what it supports. Also, see visitor-impl.h for the
* callback contracts implemented by each visitor, and
- * docs/devel/qapi-code-gen.txt for more about the QAPI code
+ * docs/devel/qapi-code-gen.rst for more about the QAPI code
* generator.
*
* All of the visitors are created via:
* yank_register_function: Register a yank function
*
* This registers a yank function. All limitations of qmp oob commands apply
- * to the yank function as well. See docs/devel/qapi-code-gen.txt under
+ * to the yank function as well. See docs/devel/qapi-code-gen.rst under
* "An OOB-capable command handler must satisfy the following conditions".
*
* This function is thread-safe.
# target, i.e. same data and new writes are done synchronously to
# both.
#
-# Since 8.2
+# Since: 8.2
##
{ 'struct': 'BlockJobInfoMirror',
'data': { 'actively-synced': 'bool' } }
#
# @type: The job type
#
-# Since 8.2
+# Since: 8.2
##
{ 'union': 'BlockJobChangeOptions',
'base': { 'id': 'str', 'type': 'JobType' },
# @rows: console height, in chars
#
# Note: the options are only effective when the VNC or SDL graphical
-# display backend is active. They are ignored with the GTK, Spice, VNC
-# and D-Bus display backends.
+# display backend is active. They are ignored with the GTK,
+# Spice, VNC and D-Bus display backends.
#
# Since: 1.5
##
#
# @members: the alternate type's members, in no particular order. The
# members' wire encoding is distinct, see
-# docs/devel/qapi-code-gen.txt section Alternate types.
+# :doc:`/devel/qapi-code-gen` section Alternate types.
#
# On the wire, this can be any of the members.
#
# From it we have: balloon_size = vm_ram_size - @value
#
# Returns:
-# - Nothing on success
-# - If the balloon driver is enabled but not functional because the
-# KVM kernel module cannot support it, KVMMissingCap
-# - If no balloon device is present, DeviceNotActive
+# - Nothing on success
+# - If the balloon driver is enabled but not functional because
+# the KVM kernel module cannot support it, KVMMissingCap
+# - If no balloon device is present, DeviceNotActive
#
# Notes: This command just issues a request to the guest. When it
# returns, the balloon size may not have changed. A guest can
# Return information about the balloon device.
#
# Returns:
-# - @BalloonInfo on success
-# - If the balloon driver is enabled but not functional because the
-# KVM kernel module cannot support it, KVMMissingCap
-# - If no balloon device is present, DeviceNotActive
+# - @BalloonInfo on success
+# - If the balloon driver is enabled but not functional because
+# the KVM kernel module cannot support it, KVMMissingCap
+# - If no balloon device is present, DeviceNotActive
#
# Since: 0.14
#
# message from the guest.
#
# Returns:
-# - @HvBalloonInfo on success
-# - If no hv-balloon device is present, guest memory status reporting
-# is not enabled or no guest memory status report received yet,
-# GenericError
+# - @HvBalloonInfo on success
+# - If no hv-balloon device is present, guest memory status
+# reporting is not enabled or no guest memory status report
+# received yet, GenericError
#
# Since: 8.2
#
#
# @file: Direct the migration stream to a file.
#
-# Since 8.2
+# Since: 8.2
##
{ 'enum': 'MigrationAddressType',
'data': [ 'socket', 'exec', 'rdma', 'file' ] }
#
# @offset: The file offset where the migration stream will start
#
-# Since 8.2
+# Since: 8.2
##
{ 'struct': 'FileMigrationArgs',
'data': { 'filename': 'str',
#
# @args: command (list head) and arguments to execute.
#
-# Since 8.2
+# Since: 8.2
##
{ 'struct': 'MigrationExecCommand',
'data': {'args': [ 'str' ] } }
#
# Migration endpoint configuration.
#
-# Since 8.2
+# Since: 8.2
##
{ 'union': 'MigrationAddress',
'base': { 'transport' : 'MigrationAddressType'},
#
# @main: Main outbound migration channel.
#
-# Since 8.1
+# Since: 8.1
##
{ 'enum': 'MigrationChannelType',
'data': [ 'main' ] }
#
# @addr: Migration endpoint configuration on destination interface.
#
-# Since 8.1
+# Since: 8.1
##
{ 'struct': 'MigrationChannel',
'data': {
#
# @millisecond: value is in milliseconds
#
-# Since 8.2
+# Since: 8.2
#
##
{ 'enum': 'TimeUnit',
# @port: The port number
#
# Returns:
-# - Nothing on success.
+# - Nothing on success.
#
# Since: 8.0
#
# @opaque: A free-form string that can be used to describe the fd.
#
# Returns:
-# - @AddfdInfo on success
-# - If file descriptor was not received, GenericError
-# - If @fdset-id is a negative value, GenericError
+# - @AddfdInfo on success
+# - If file descriptor was not received, GenericError
+# - If @fdset-id is a negative value, GenericError
#
# Notes: The list of fd sets is shared by all monitor connections.
#
# @fd: The file descriptor that is to be removed.
#
# Returns:
-# - Nothing on success
-# - If @fdset-id or @fd is not found, GenericError
+# - Nothing on success
+# - If @fdset-id or @fd is not found, GenericError
#
# Since: 1.2
#
#
# @up: true to set the link status to be up
#
-# Returns: Nothing on success If @name is not a valid network device,
-# DeviceNotFound
+# Returns:
+# - Nothing on success
+# - If @name is not a valid network device, DeviceNotFound
#
# Since: 0.14
#
#
# Since: 0.14
#
-# Returns: Nothing on success If @type is not a valid network backend,
-# DeviceNotFound
+# Returns:
+# - Nothing on success
+# - If @type is not a valid network backend, DeviceNotFound
#
# Example:
#
#
# @id: the name of the network backend to remove
#
-# Returns: Nothing on success If @id is not a valid network backend,
-# DeviceNotFound
+# Returns:
+# - Nothing on success
+# - If @id is not a valid network backend, DeviceNotFound
#
# Since: 0.14
#
* It may be prefixed by __RFQDN_ (downstream extension), where RFQDN
* may contain only letters, digits, hyphen and period.
* The special exception for enumeration names is not implemented.
- * See docs/devel/qapi-code-gen.txt for more on QAPI naming rules.
+ * See docs/devel/qapi-code-gen.rst for more on QAPI naming rules.
* Keep this consistent with scripts/qapi-gen.py!
* If @complete, the parse fails unless it consumes @str completely.
* Return its length on success, -1 on failure.
#
# @id: the device's ID or QOM path
#
-# Returns: Nothing on success If @id is not a valid device,
-# DeviceNotFound
+# Returns:
+# - Nothing on success
+# - If @id is not a valid device, DeviceNotFound
#
# Notes: When this command completes, the device may not be removed
# from the guest. Hot removal is an operation that requires guest
#
# Create a QOM object.
#
-# Returns: Nothing on success Error if @qom-type is not a valid class
-# name
+# Returns:
+# - Nothing on success
+# - Error if @qom-type is not a valid class name
#
# Since: 2.0
#
#
# @id: the name of the QOM object to remove
#
-# Returns: Nothing on success Error if @id is not a valid id for a QOM
-# object
+# Returns:
+# - Nothing on success
+# - Error if @id is not a valid id for a QOM object
#
# Since: 2.0
#
# Takes a list of @YankInstance as argument.
#
# Returns:
-# - Nothing on success
-# - @DeviceNotFound error, if any of the YankInstances doesn't exist
+# - Nothing on success
+# - @DeviceNotFound error, if any of the YankInstances doesn't exist
#
# Example:
#
Parse QAPI schema source.
Parse a JSON-esque schema file and process directives. See
- qapi-code-gen.txt section "Schema Syntax" for the exact syntax.
+ qapi-code-gen.rst section "Schema Syntax" for the exact syntax.
Grammatical validation is handled later by `expr.check_exprs()`.
:param fname: Source file name.
/*
* This lock protects the yank_instance_list below. Because it's taken by
* OOB-capable commands, it must be "fast", i.e. it may only be held for a
- * bounded, short time. See docs/devel/qapi-code-gen.txt for additional
+ * bounded, short time. See docs/devel/qapi-code-gen.rst for additional
* information.
*/
static QemuMutex yank_lock;
projects / mirror_qemu.git / commitdiff