qemu/qapi/control.json
Markus Armbruster a937b6aa73 qapi: Reformat doc comments to conform to current conventions
Change

    # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
    #        do eiusmod tempor incididunt ut labore et dolore magna aliqua.

to

    # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
    #     do eiusmod tempor incididunt ut labore et dolore magna aliqua.

See recent commit "qapi: Relax doc string @name: description
indentation rules" for rationale.

Reflow paragraphs to 70 columns width, and consistently use two spaces
to separate sentences.

To check the generated documentation does not change, I compared the
generated HTML before and after this commit with "wdiff -3".  Finds no
differences.  Comparing with diff is not useful, as the reflown
paragraphs are visible there.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-18-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
Acked-by: Lukas Straub <lukasstraub2@web.de>
[Straightforward conflicts in qapi/audio.json qapi/misc-target.json
qapi/run-state.json resolved]
2023-05-10 10:01:01 +02:00

214 lines
4.6 KiB
Python

# -*- Mode: Python -*-
# vim: filetype=python
#
##
# = QMP monitor control
##
##
# @qmp_capabilities:
#
# Enable QMP capabilities.
#
# Arguments:
#
# @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)
#
# Example:
#
# -> { "execute": "qmp_capabilities",
# "arguments": { "enable": [ "oob" ] } }
# <- { "return": {} }
#
# Notes: This command is valid exactly when first connecting: it must
# be issued before any other command will be accepted, and will
# fail once the monitor is accepting other commands. (see qemu
# docs/interop/qmp-spec.txt)
#
# The QMP client needs to explicitly enable QMP capabilities,
# otherwise all the QMP capabilities will be turned off by
# default.
#
# Since: 0.13
##
{ 'command': 'qmp_capabilities',
'data': { '*enable': [ 'QMPCapability' ] },
'allow-preconfig': true }
##
# @QMPCapability:
#
# Enumeration of capabilities to be advertised during initial client
# connection, used for agreeing on particular QMP extension behaviors.
#
# @oob: QMP ability to support out-of-band requests. (Please refer to
# qmp-spec.txt for more information on OOB)
#
# Since: 2.12
##
{ 'enum': 'QMPCapability',
'data': [ 'oob' ] }
##
# @VersionTriple:
#
# A three-part version number.
#
# @major: The major version number.
#
# @minor: The minor version number.
#
# @micro: The micro version number.
#
# Since: 2.4
##
{ 'struct': 'VersionTriple',
'data': {'major': 'int', 'minor': 'int', 'micro': 'int'} }
##
# @VersionInfo:
#
# A description of QEMU's version.
#
# @qemu: The version of QEMU. By current convention, a micro version
# of 50 signifies a development branch. A micro version greater
# than or equal to 90 signifies a release candidate for the next
# minor version. A micro version of less than 50 signifies a
# stable release.
#
# @package: QEMU will always set this field to an empty string.
# Downstream versions of QEMU should set this to a non-empty
# string. The exact format depends on the downstream however it
# highly recommended that a unique name is used.
#
# Since: 0.14
##
{ 'struct': 'VersionInfo',
'data': {'qemu': 'VersionTriple', 'package': 'str'} }
##
# @query-version:
#
# Returns the current version of QEMU.
#
# Returns: A @VersionInfo object describing the current version of
# QEMU.
#
# Since: 0.14
#
# Example:
#
# -> { "execute": "query-version" }
# <- {
# "return":{
# "qemu":{
# "major":0,
# "minor":11,
# "micro":5
# },
# "package":""
# }
# }
##
{ 'command': 'query-version', 'returns': 'VersionInfo',
'allow-preconfig': true }
##
# @CommandInfo:
#
# Information about a QMP command
#
# @name: The command name
#
# Since: 0.14
##
{ 'struct': 'CommandInfo', 'data': {'name': 'str'} }
##
# @query-commands:
#
# Return a list of supported QMP commands by this server
#
# Returns: A list of @CommandInfo for all supported commands
#
# Since: 0.14
#
# Example:
#
# -> { "execute": "query-commands" }
# <- {
# "return":[
# {
# "name":"query-balloon"
# },
# {
# "name":"system_powerdown"
# }
# ]
# }
#
# Note: This example has been shortened as the real response is too
# long.
##
{ 'command': 'query-commands', 'returns': ['CommandInfo'],
'allow-preconfig': true }
##
# @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.
#
# Since: 0.14
#
# Example:
#
# -> { "execute": "quit" }
# <- { "return": {} }
##
{ 'command': 'quit',
'allow-preconfig': true }
##
# @MonitorMode:
#
# An enumeration of monitor modes.
#
# @readline: HMP monitor (human-oriented command line interface)
#
# @control: QMP monitor (JSON-based machine interface)
#
# Since: 5.0
##
{ 'enum': 'MonitorMode', 'data': [ 'readline', 'control' ] }
##
# @MonitorOptions:
#
# Options to be used for adding a new monitor.
#
# @id: Name of the monitor
#
# @mode: Selects the monitor mode (default: readline in the system
# emulator, control in qemu-storage-daemon)
#
# @pretty: Enables pretty printing (QMP only)
#
# @chardev: Name of a character device to expose the monitor on
#
# Since: 5.0
##
{ 'struct': 'MonitorOptions',
'data': {
'*id': 'str',
'*mode': 'MonitorMode',
'*pretty': 'bool',
'chardev': 'str'
} }