Merge tag 'pull-qapi-2023-05-17-v2' of https://repo.or.cz/qemu/armbru into staging
QAPI patches patches for 2023-05-17
# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmRrTcgSHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTMycP/3sP6/U4kwOKMGGcB+n2pHJeioQS4xgF
# 94NCW+KpewxApP0XzIC2nDGjUe/rPcUfQmBNUumvYbqHO91tq91wFwkllBv2UR0q
# 6qfRji+e8+9H9hMDeVzzSNjlZZg/tSdIJlhkJDw1u4/3fpjfAmzVx6DO3wepSQ9Q
# m5Af/+uhVZWyUXMZqcKr2Zq8qur6ZFEBNpXpPvT60Tvy2heuQ+vcoE3tl2ZRQbmj
# b/jhtCu+NPjgOHtg9Gr2BPXqQiZBR4vFA7WBsB8wCf2xxULfTwHJvFz/e0vx5fUC
# q0Fsyybf4USo2PRMsRFv2v4dEuVGHb3E1RIJY4NTAxQMqqm4zfOyK0BzOGNDkxCn
# owNP4vKly0e/CfYDY74FHaPId295xyeo6S4Cj5ib9W23AAWUNt6f6vbjlDOLCLON
# c7yXP/aJwhTb2w1t0mLTmsKum3DpLlrudPudTylVlmYfwchkvUGsWYbaxu6H6XWk
# 49Ox/QPVwqG6elXNn3kTY4QqTAppXhE7QcPbioX9WOThVPf6aJCLdZSHEHu4HXkZ
# 4FRu73Z2wcPNB789xOrQoXs24GdKmWXQ6K01KC4v7WNJQBXccec52yGxvktQRZBm
# GL3zYdOOJEL+Y/8JrXTIo26M8HP/4kxV2VqB6KOuaGygMsW9w9jbG+ygLyjqUDQg
# 3APV3hdmVOht
# =6anf
# -----END PGP SIGNATURE-----
# gpg: Signature made Mon 22 May 2023 04:11:04 AM PDT
# gpg: using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg: issuer "armbru@redhat.com"
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [undefined]
# gpg: aka "Markus Armbruster <armbru@pond.sub.org>" [undefined]
# gpg: WARNING: This key is not certified with a trusted signature!
# gpg: There is no indication that the signature belongs to the owner.
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867 4E5F 3870 B400 EB91 8653
* tag 'pull-qapi-2023-05-17-v2' of https://repo.or.cz/qemu/armbru:
docs/interop: Delete qmp-intro.txt
docs/interop/qmp-spec: Update error description for parsing errors
docs/interop: Convert qmp-spec.txt to rST
qapi: Improve error message for description following section
Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index 5618a80..7f78183 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -545,7 +545,8 @@
{ 'command': 'migrate_recover',
'data': { 'uri': 'str' }, 'allow-oob': true }
-See qmp-spec.txt for out-of-band execution syntax and semantics.
+See the :doc:`/interop/qmp-spec` for out-of-band execution syntax
+and semantics.
Commands supporting out-of-band execution can still be executed
in-band.
diff --git a/docs/interop/index.rst b/docs/interop/index.rst
index 6351ff9..ed65395 100644
--- a/docs/interop/index.rst
+++ b/docs/interop/index.rst
@@ -15,6 +15,7 @@
dbus-display
live-block-operations
pr-helper
+ qmp-spec
qemu-ga
qemu-ga-ref
qemu-qmp-ref
diff --git a/docs/interop/qmp-intro.txt b/docs/interop/qmp-intro.txt
deleted file mode 100644
index 1c745a7..0000000
--- a/docs/interop/qmp-intro.txt
+++ /dev/null
@@ -1,88 +0,0 @@
- QEMU Machine Protocol
- =====================
-
-Introduction
-------------
-
-The QEMU Machine Protocol (QMP) allows applications to operate a
-QEMU instance.
-
-QMP is JSON[1] based and features the following:
-
-- Lightweight, text-based, easy to parse data format
-- Asynchronous messages support (ie. events)
-- Capabilities Negotiation
-
-For detailed information on QMP's usage, please, refer to the following files:
-
-o qmp-spec.txt QEMU Machine Protocol current specification
-o qemu-qmp-ref.html QEMU QMP commands and events (auto-generated at build-time)
-
-[1] https://www.json.org
-
-Usage
------
-
-You can use the -qmp option to enable QMP. For example, the following
-makes QMP available on localhost port 4444:
-
-$ qemu [...] -qmp tcp:localhost:4444,server=on,wait=off
-
-However, for more flexibility and to make use of more options, the -mon
-command-line option should be used. For instance, the following example
-creates one HMP instance (human monitor) on stdio and one QMP instance
-on localhost port 4444:
-
-$ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
- -chardev socket,id=mon1,host=localhost,port=4444,server=on,wait=off \
- -mon chardev=mon1,mode=control,pretty=on
-
-Please, refer to QEMU's manpage for more information.
-
-Simple Testing
---------------
-
-To manually test QMP one can connect with telnet and issue commands by hand:
-
-$ telnet localhost 4444
-Trying 127.0.0.1...
-Connected to localhost.
-Escape character is '^]'.
-{
- "QMP": {
- "version": {
- "qemu": {
- "micro": 0,
- "minor": 0,
- "major": 3
- },
- "package": "v3.0.0"
- },
- "capabilities": [
- "oob"
- ]
- }
-}
-
-{ "execute": "qmp_capabilities" }
-{
- "return": {
- }
-}
-
-{ "execute": "query-status" }
-{
- "return": {
- "status": "prelaunch",
- "singlestep": false,
- "running": false
- }
-}
-
-Please refer to docs/interop/qemu-qmp-ref.* for a complete command
-reference, generated from qapi/qapi-schema.json.
-
-QMP wiki page
--------------
-
-https://wiki.qemu.org/QMP
diff --git a/docs/interop/qmp-spec.rst b/docs/interop/qmp-spec.rst
new file mode 100644
index 0000000..5633441
--- /dev/null
+++ b/docs/interop/qmp-spec.rst
@@ -0,0 +1,439 @@
+..
+ Copyright (C) 2009-2016 Red Hat, Inc.
+
+ This work is licensed under the terms of the GNU GPL, version 2 or
+ later. See the COPYING file in the top-level directory.
+
+
+===================================
+QEMU Machine Protocol Specification
+===================================
+
+The QEMU Machine Protocol (QMP) is a JSON-based
+protocol which is available for applications to operate QEMU at the
+machine-level. It is also in use by the QEMU Guest Agent (QGA), which
+is available for host applications to interact with the guest
+operating system. This page specifies the general format of
+the protocol; details of the commands and data structures can
+be found in the :doc:`qemu-qmp-ref` and the :doc:`qemu-ga-ref`.
+
+.. contents::
+
+Protocol Specification
+======================
+
+This section details the protocol format. For the purpose of this
+document, "Server" is either QEMU or the QEMU Guest Agent, and
+"Client" is any application communicating with it via QMP.
+
+JSON data structures, when mentioned in this document, are always in the
+following format:
+
+ json-DATA-STRUCTURE-NAME
+
+Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined
+by the `JSON standard <http://www.ietf.org/rfc/rfc8259.txt>`_.
+
+The server expects its input to be encoded in UTF-8, and sends its
+output encoded in ASCII.
+
+For convenience, json-object members mentioned in this document will
+be in a certain order. However, in real protocol usage they can be in
+ANY order, thus no particular order should be assumed. On the other
+hand, use of json-array elements presumes that preserving order is
+important unless specifically documented otherwise. Repeating a key
+within a json-object gives unpredictable results.
+
+Also for convenience, the server will accept an extension of
+``'single-quoted'`` strings in place of the usual ``"double-quoted"``
+json-string, and both input forms of strings understand an additional
+escape sequence of ``\'`` for a single quote. The server will only use
+double quoting on output.
+
+General Definitions
+-------------------
+
+All interactions transmitted by the Server are json-objects, always
+terminating with CRLF.
+
+All json-objects members are mandatory when not specified otherwise.
+
+Server Greeting
+---------------
+
+Right when connected the Server will issue a greeting message, which signals
+that the connection has been successfully established and that the Server is
+ready for capabilities negotiation (for more information refer to section
+`Capabilities Negotiation`_).
+
+The greeting message format is:
+
+::
+
+ { "QMP": { "version": json-object, "capabilities": json-array } }
+
+Where:
+
+- The ``version`` member contains the Server's version information (the format
+ is the same as for the query-version command).
+- The ``capabilities`` member specifies the availability of features beyond the
+ baseline specification; the order of elements in this array has no
+ particular significance.
+
+Capabilities
+------------
+
+Currently supported capabilities are:
+
+``oob``
+ the QMP server supports "out-of-band" (OOB) command
+ execution, as described in section `Out-of-band execution`_.
+
+Issuing Commands
+----------------
+
+The format for command execution is:
+
+::
+
+ { "execute": json-string, "arguments": json-object, "id": json-value }
+
+or
+
+::
+
+ { "exec-oob": json-string, "arguments": json-object, "id": json-value }
+
+Where:
+
+- The ``execute`` or ``exec-oob`` member identifies the command to be
+ executed by the server. The latter requests out-of-band execution.
+- The ``arguments`` member is used to pass any arguments required for the
+ execution of the command, it is optional when no arguments are
+ required. Each command documents what contents will be considered
+ valid when handling the json-argument.
+- The ``id`` member is a transaction identification associated with the
+ command execution, it is optional and will be part of the response
+ if provided. The ``id`` member can be any json-value. A json-number
+ incremented for each successive command works fine.
+
+The actual commands are documented in the :doc:`qemu-qmp-ref`.
+
+Out-of-band execution
+---------------------
+
+The server normally reads, executes and responds to one command after
+the other. The client therefore receives command responses in issue
+order.
+
+With out-of-band execution enabled via `capabilities negotiation`_,
+the server reads and queues commands as they arrive. It executes
+commands from the queue one after the other. Commands executed
+out-of-band jump the queue: the command get executed right away,
+possibly overtaking prior in-band commands. The client may therefore
+receive such a command's response before responses from prior in-band
+commands.
+
+To be able to match responses back to their commands, the client needs
+to pass ``id`` with out-of-band commands. Passing it with all commands
+is recommended for clients that accept capability ``oob``.
+
+If the client sends in-band commands faster than the server can
+execute them, the server will stop reading requests until the request
+queue length is reduced to an acceptable range.
+
+To ensure commands to be executed out-of-band get read and executed,
+the client should have at most eight in-band commands in flight.
+
+Only a few commands support out-of-band execution. The ones that do
+have ``"allow-oob": true`` in the output of ``query-qmp-schema``.
+
+Commands Responses
+------------------
+
+There are two possible responses which the Server will issue as the result
+of a command execution: success or error.
+
+As long as the commands were issued with a proper ``id`` field, then the
+same ``id`` field will be attached in the corresponding response message
+so that requests and responses can match. Clients should drop all the
+responses that have an unknown ``id`` field.
+
+Success
+-------
+
+The format of a success response is:
+
+::
+
+ { "return": json-value, "id": json-value }
+
+Where:
+
+- The ``return`` member contains the data returned by the command, which
+ is defined on a per-command basis (usually a json-object or
+ json-array of json-objects, but sometimes a json-number, json-string,
+ or json-array of json-strings); it is an empty json-object if the
+ command does not return data.
+- The ``id`` member contains the transaction identification associated
+ with the command execution if issued by the Client.
+
+Error
+-----
+
+The format of an error response is:
+
+::
+
+ { "error": { "class": json-string, "desc": json-string }, "id": json-value }
+
+Where:
+
+- The ``class`` member contains the error class name (eg. ``"GenericError"``).
+- The ``desc`` member is a human-readable error message. Clients should
+ not attempt to parse this message.
+- The ``id`` member contains the transaction identification associated with
+ the command execution if issued by the Client.
+
+NOTE: Some errors can occur before the Server is able to read the ``id`` member;
+in these cases the ``id`` member will not be part of the error response, even
+if provided by the client.
+
+Asynchronous events
+-------------------
+
+As a result of state changes, the Server may send messages unilaterally
+to the Client at any time, when not in the middle of any other
+response. They are called "asynchronous events".
+
+The format of asynchronous events is:
+
+::
+
+ { "event": json-string, "data": json-object,
+ "timestamp": { "seconds": json-number, "microseconds": json-number } }
+
+Where:
+
+- The ``event`` member contains the event's name.
+- The ``data`` member contains event specific data, which is defined in a
+ per-event basis. It is optional.
+- The ``timestamp`` member contains the exact time of when the event
+ occurred in the Server. It is a fixed json-object with time in
+ seconds and microseconds relative to the Unix Epoch (1 Jan 1970); if
+ there is a failure to retrieve host time, both members of the
+ timestamp will be set to -1.
+
+The actual asynchronous events are documented in the :doc:`qemu-qmp-ref`.
+
+Some events are rate-limited to at most one per second. If additional
+"similar" events arrive within one second, all but the last one are
+dropped, and the last one is delayed. "Similar" normally means same
+event type.
+
+Forcing the JSON parser into known-good state
+---------------------------------------------
+
+Incomplete or invalid input can leave the server's JSON parser in a
+state where it can't parse additional commands. To get it back into
+known-good state, the client should provoke a lexical error.
+
+The cleanest way to do that is sending an ASCII control character
+other than ``\t`` (horizontal tab), ``\r`` (carriage return), or
+``\n`` (new line).
+
+Sadly, older versions of QEMU can fail to flag this as an error. If a
+client needs to deal with them, it should send a 0xFF byte.
+
+QGA Synchronization
+-------------------
+
+When a client connects to QGA over a transport lacking proper
+connection semantics such as virtio-serial, QGA may have read partial
+input from a previous client. The client needs to force QGA's parser
+into known-good state using the previous section's technique.
+Moreover, the client may receive output a previous client didn't read.
+To help with skipping that output, QGA provides the
+``guest-sync-delimited`` command. Refer to its documentation for
+details.
+
+
+QMP Examples
+============
+
+This section provides some examples of real QMP usage, in all of them
+``->`` marks text sent by the Client and ``<-`` marks replies by the Server.
+
+.. admonition:: Example
+
+ Server greeting
+
+ .. code-block:: QMP
+
+ <- { "QMP": {"version": {"qemu": {"micro": 0, "minor": 0, "major": 3},
+ "package": "v3.0.0"}, "capabilities": ["oob"] } }
+
+.. admonition:: Example
+
+ Capabilities negotiation
+
+ .. code-block:: QMP
+
+ -> { "execute": "qmp_capabilities", "arguments": { "enable": ["oob"] } }
+ <- { "return": {}}
+
+.. admonition:: Example
+
+ Simple 'stop' execution
+
+ .. code-block:: QMP
+
+ -> { "execute": "stop" }
+ <- { "return": {} }
+
+.. admonition:: Example
+
+ KVM information
+
+ .. code-block:: QMP
+
+ -> { "execute": "query-kvm", "id": "example" }
+ <- { "return": { "enabled": true, "present": true }, "id": "example"}
+
+.. admonition:: Example
+
+ Parsing error
+
+ .. code-block:: QMP
+
+ -> { "execute": }
+ <- { "error": { "class": "GenericError", "desc": "JSON parse error, expecting value" } }
+
+.. admonition:: Example
+
+ Powerdown event
+
+ .. code-block:: QMP
+
+ <- { "timestamp": { "seconds": 1258551470, "microseconds": 802384 },
+ "event": "POWERDOWN" }
+
+.. admonition:: Example
+
+ Out-of-band execution
+
+ .. code-block:: QMP
+
+ -> { "exec-oob": "migrate-pause", "id": 42 }
+ <- { "id": 42,
+ "error": { "class": "GenericError",
+ "desc": "migrate-pause is currently only supported during postcopy-active state" } }
+
+
+Capabilities Negotiation
+========================
+
+When a Client successfully establishes a connection, the Server is in
+Capabilities Negotiation mode.
+
+In this mode only the ``qmp_capabilities`` command is allowed to run; all
+other commands will return the ``CommandNotFound`` error. Asynchronous
+messages are not delivered either.
+
+Clients should use the ``qmp_capabilities`` command to enable capabilities
+advertised in the `Server Greeting`_ which they support.
+
+When the ``qmp_capabilities`` command is issued, and if it does not return an
+error, the Server enters Command mode where capabilities changes take
+effect, all commands (except ``qmp_capabilities``) are allowed and asynchronous
+messages are delivered.
+
+Compatibility Considerations
+============================
+
+All protocol changes or new features which modify the protocol format in an
+incompatible way are disabled by default and will be advertised by the
+capabilities array (in the `Server Greeting`_). Thus, Clients can check
+that array and enable the capabilities they support.
+
+The QMP Server performs a type check on the arguments to a command. It
+generates an error if a value does not have the expected type for its
+key, or if it does not understand a key that the Client included. The
+strictness of the Server catches wrong assumptions of Clients about
+the Server's schema. Clients can assume that, when such validation
+errors occur, they will be reported before the command generated any
+side effect.
+
+However, Clients must not assume any particular:
+
+- Length of json-arrays
+- Size of json-objects; in particular, future versions of QEMU may add
+ new keys and Clients should be able to ignore them
+- Order of json-object members or json-array elements
+- Amount of errors generated by a command, that is, new errors can be added
+ to any existing command in newer versions of the Server
+
+Any command or member name beginning with ``x-`` is deemed experimental,
+and may be withdrawn or changed in an incompatible manner in a future
+release.
+
+Of course, the Server does guarantee to send valid JSON. But apart from
+this, a Client should be "conservative in what they send, and liberal in
+what they accept".
+
+Downstream extension of QMP
+===========================
+
+We recommend that downstream consumers of QEMU do *not* modify QMP.
+Management tools should be able to support both upstream and downstream
+versions of QMP without special logic, and downstream extensions are
+inherently at odds with that.
+
+However, we recognize that it is sometimes impossible for downstreams to
+avoid modifying QMP. Both upstream and downstream need to take care to
+preserve long-term compatibility and interoperability.
+
+To help with that, QMP reserves JSON object member names beginning with
+``__`` (double underscore) for downstream use ("downstream names"). This
+means upstream will never use any downstream names for its commands,
+arguments, errors, asynchronous events, and so forth.
+
+Any new names downstream wishes to add must begin with ``__``. To
+ensure compatibility with other downstreams, it is strongly
+recommended that you prefix your downstream names with ``__RFQDN_`` where
+RFQDN is a valid, reverse fully qualified domain name which you
+control. For example, a qemu-kvm specific monitor command would be:
+
+::
+
+ (qemu) __org.linux-kvm_enable_irqchip
+
+Downstream must not change the `server greeting`_ other than
+to offer additional capabilities. But see below for why even that is
+discouraged.
+
+The section `Compatibility Considerations`_ applies to downstream as well
+as to upstream, obviously. It follows that downstream must behave
+exactly like upstream for any input not containing members with
+downstream names ("downstream members"), except it may add members
+with downstream names to its output.
+
+Thus, a client should not be able to distinguish downstream from
+upstream as long as it doesn't send input with downstream members, and
+properly ignores any downstream members in the output it receives.
+
+Advice on downstream modifications:
+
+1. Introducing new commands is okay. If you want to extend an existing
+ command, consider introducing a new one with the new behaviour
+ instead.
+
+2. Introducing new asynchronous messages is okay. If you want to extend
+ an existing message, consider adding a new one instead.
+
+3. Introducing new errors for use in new commands is okay. Adding new
+ errors to existing commands counts as extension, so 1. applies.
+
+4. New capabilities are strongly discouraged. Capabilities are for
+ evolving the basic protocol, and multiple diverging basic protocol
+ dialects are most undesirable.
diff --git a/docs/interop/qmp-spec.txt b/docs/interop/qmp-spec.txt
deleted file mode 100644
index b0e8351..0000000
--- a/docs/interop/qmp-spec.txt
+++ /dev/null
@@ -1,406 +0,0 @@
- QEMU Machine Protocol Specification
-
-0. About This Document
-======================
-
-Copyright (C) 2009-2016 Red Hat, Inc.
-
-This work is licensed under the terms of the GNU GPL, version 2 or
-later. See the COPYING file in the top-level directory.
-
-1. Introduction
-===============
-
-This document specifies the QEMU Machine Protocol (QMP), a JSON-based
-protocol which is available for applications to operate QEMU at the
-machine-level. It is also in use by the QEMU Guest Agent (QGA), which
-is available for host applications to interact with the guest
-operating system.
-
-2. Protocol Specification
-=========================
-
-This section details the protocol format. For the purpose of this
-document, "Server" is either QEMU or the QEMU Guest Agent, and
-"Client" is any application communicating with it via QMP.
-
-JSON data structures, when mentioned in this document, are always in the
-following format:
-
- json-DATA-STRUCTURE-NAME
-
-Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined
-by the JSON standard:
-
-http://www.ietf.org/rfc/rfc8259.txt
-
-The server expects its input to be encoded in UTF-8, and sends its
-output encoded in ASCII.
-
-For convenience, json-object members mentioned in this document will
-be in a certain order. However, in real protocol usage they can be in
-ANY order, thus no particular order should be assumed. On the other
-hand, use of json-array elements presumes that preserving order is
-important unless specifically documented otherwise. Repeating a key
-within a json-object gives unpredictable results.
-
-Also for convenience, the server will accept an extension of
-'single-quoted' strings in place of the usual "double-quoted"
-json-string, and both input forms of strings understand an additional
-escape sequence of "\'" for a single quote. The server will only use
-double quoting on output.
-
-2.1 General Definitions
------------------------
-
-2.1.1 All interactions transmitted by the Server are json-objects, always
- terminating with CRLF
-
-2.1.2 All json-objects members are mandatory when not specified otherwise
-
-2.2 Server Greeting
--------------------
-
-Right when connected the Server will issue a greeting message, which signals
-that the connection has been successfully established and that the Server is
-ready for capabilities negotiation (for more information refer to section
-'4. Capabilities Negotiation').
-
-The greeting message format is:
-
-{ "QMP": { "version": json-object, "capabilities": json-array } }
-
- Where,
-
-- The "version" member contains the Server's version information (the format
- is the same of the query-version command)
-- The "capabilities" member specify the availability of features beyond the
- baseline specification; the order of elements in this array has no
- particular significance.
-
-2.2.1 Capabilities
-------------------
-
-Currently supported capabilities are:
-
-- "oob": the QMP server supports "out-of-band" (OOB) command
- execution, as described in section "2.3.1 Out-of-band execution".
-
-2.3 Issuing Commands
---------------------
-
-The format for command execution is:
-
-{ "execute": json-string, "arguments": json-object, "id": json-value }
-
-or
-
-{ "exec-oob": json-string, "arguments": json-object, "id": json-value }
-
- Where,
-
-- The "execute" or "exec-oob" member identifies the command to be
- executed by the server. The latter requests out-of-band execution.
-- The "arguments" member is used to pass any arguments required for the
- execution of the command, it is optional when no arguments are
- required. Each command documents what contents will be considered
- valid when handling the json-argument
-- The "id" member is a transaction identification associated with the
- command execution, it is optional and will be part of the response
- if provided. The "id" member can be any json-value. A json-number
- incremented for each successive command works fine.
-
-The actual commands are documented in the QEMU QMP reference manual
-docs/interop/qemu-qmp-ref.{7,html,info,pdf,txt}.
-
-2.3.1 Out-of-band execution
----------------------------
-
-The server normally reads, executes and responds to one command after
-the other. The client therefore receives command responses in issue
-order.
-
-With out-of-band execution enabled via capability negotiation (section
-4.), the server reads and queues commands as they arrive. It executes
-commands from the queue one after the other. Commands executed
-out-of-band jump the queue: the command get executed right away,
-possibly overtaking prior in-band commands. The client may therefore
-receive such a command's response before responses from prior in-band
-commands.
-
-To be able to match responses back to their commands, the client needs
-to pass "id" with out-of-band commands. Passing it with all commands
-is recommended for clients that accept capability "oob".
-
-If the client sends in-band commands faster than the server can
-execute them, the server will stop reading requests until the request
-queue length is reduced to an acceptable range.
-
-To ensure commands to be executed out-of-band get read and executed,
-the client should have at most eight in-band commands in flight.
-
-Only a few commands support out-of-band execution. The ones that do
-have "allow-oob": true in output of query-qmp-schema.
-
-2.4 Commands Responses
-----------------------
-
-There are two possible responses which the Server will issue as the result
-of a command execution: success or error.
-
-As long as the commands were issued with a proper "id" field, then the
-same "id" field will be attached in the corresponding response message
-so that requests and responses can match. Clients should drop all the
-responses that have an unknown "id" field.
-
-2.4.1 success
--------------
-
-The format of a success response is:
-
-{ "return": json-value, "id": json-value }
-
- Where,
-
-- The "return" member contains the data returned by the command, which
- is defined on a per-command basis (usually a json-object or
- json-array of json-objects, but sometimes a json-number, json-string,
- or json-array of json-strings); it is an empty json-object if the
- command does not return data
-- The "id" member contains the transaction identification associated
- with the command execution if issued by the Client
-
-2.4.2 error
------------
-
-The format of an error response is:
-
-{ "error": { "class": json-string, "desc": json-string }, "id": json-value }
-
- Where,
-
-- The "class" member contains the error class name (eg. "GenericError")
-- The "desc" member is a human-readable error message. Clients should
- not attempt to parse this message.
-- The "id" member contains the transaction identification associated with
- the command execution if issued by the Client
-
-NOTE: Some errors can occur before the Server is able to read the "id" member,
-in these cases the "id" member will not be part of the error response, even
-if provided by the client.
-
-2.5 Asynchronous events
------------------------
-
-As a result of state changes, the Server may send messages unilaterally
-to the Client at any time, when not in the middle of any other
-response. They are called "asynchronous events".
-
-The format of asynchronous events is:
-
-{ "event": json-string, "data": json-object,
- "timestamp": { "seconds": json-number, "microseconds": json-number } }
-
- Where,
-
-- The "event" member contains the event's name
-- The "data" member contains event specific data, which is defined in a
- per-event basis, it is optional
-- The "timestamp" member contains the exact time of when the event
- occurred in the Server. It is a fixed json-object with time in
- seconds and microseconds relative to the Unix Epoch (1 Jan 1970); if
- there is a failure to retrieve host time, both members of the
- timestamp will be set to -1.
-
-The actual asynchronous events are documented in the QEMU QMP
-reference manual docs/interop/qemu-qmp-ref.{7,html,info,pdf,txt}.
-
-Some events are rate-limited to at most one per second. If additional
-"similar" events arrive within one second, all but the last one are
-dropped, and the last one is delayed. "Similar" normally means same
-event type.
-
-2.6 Forcing the JSON parser into known-good state
--------------------------------------------------
-
-Incomplete or invalid input can leave the server's JSON parser in a
-state where it can't parse additional commands. To get it back into
-known-good state, the client should provoke a lexical error.
-
-The cleanest way to do that is sending an ASCII control character
-other than '\t' (horizontal tab), '\r' (carriage return), or '\n' (new
-line).
-
-Sadly, older versions of QEMU can fail to flag this as an error. If a
-client needs to deal with them, it should send a 0xFF byte.
-
-2.7 QGA Synchronization
------------------------
-
-When a client connects to QGA over a transport lacking proper
-connection semantics such as virtio-serial, QGA may have read partial
-input from a previous client. The client needs to force QGA's parser
-into known-good state using the previous section's technique.
-Moreover, the client may receive output a previous client didn't read.
-To help with skipping that output, QGA provides the
-'guest-sync-delimited' command. Refer to its documentation for
-details.
-
-
-3. QMP Examples
-===============
-
-This section provides some examples of real QMP usage, in all of them
-"C" stands for "Client" and "S" stands for "Server".
-
-3.1 Server greeting
--------------------
-
-S: { "QMP": {"version": {"qemu": {"micro": 0, "minor": 0, "major": 3},
- "package": "v3.0.0"}, "capabilities": ["oob"] } }
-
-3.2 Capabilities negotiation
-----------------------------
-
-C: { "execute": "qmp_capabilities", "arguments": { "enable": ["oob"] } }
-S: { "return": {}}
-
-3.3 Simple 'stop' execution
----------------------------
-
-C: { "execute": "stop" }
-S: { "return": {} }
-
-3.4 KVM information
--------------------
-
-C: { "execute": "query-kvm", "id": "example" }
-S: { "return": { "enabled": true, "present": true }, "id": "example"}
-
-3.5 Parsing error
-------------------
-
-C: { "execute": }
-S: { "error": { "class": "GenericError", "desc": "Invalid JSON syntax" } }
-
-3.6 Powerdown event
--------------------
-
-S: { "timestamp": { "seconds": 1258551470, "microseconds": 802384 },
- "event": "POWERDOWN" }
-
-3.7 Out-of-band execution
--------------------------
-
-C: { "exec-oob": "migrate-pause", "id": 42 }
-S: { "id": 42,
- "error": { "class": "GenericError",
- "desc": "migrate-pause is currently only supported during postcopy-active state" } }
-
-
-4. Capabilities Negotiation
-===========================
-
-When a Client successfully establishes a connection, the Server is in
-Capabilities Negotiation mode.
-
-In this mode only the qmp_capabilities command is allowed to run, all
-other commands will return the CommandNotFound error. Asynchronous
-messages are not delivered either.
-
-Clients should use the qmp_capabilities command to enable capabilities
-advertised in the Server's greeting (section '2.2 Server Greeting') they
-support.
-
-When the qmp_capabilities command is issued, and if it does not return an
-error, the Server enters in Command mode where capabilities changes take
-effect, all commands (except qmp_capabilities) are allowed and asynchronous
-messages are delivered.
-
-5 Compatibility Considerations
-==============================
-
-All protocol changes or new features which modify the protocol format in an
-incompatible way are disabled by default and will be advertised by the
-capabilities array (section '2.2 Server Greeting'). Thus, Clients can check
-that array and enable the capabilities they support.
-
-The QMP Server performs a type check on the arguments to a command. It
-generates an error if a value does not have the expected type for its
-key, or if it does not understand a key that the Client included. The
-strictness of the Server catches wrong assumptions of Clients about
-the Server's schema. Clients can assume that, when such validation
-errors occur, they will be reported before the command generated any
-side effect.
-
-However, Clients must not assume any particular:
-
-- Length of json-arrays
-- Size of json-objects; in particular, future versions of QEMU may add
- new keys and Clients should be able to ignore them.
-- Order of json-object members or json-array elements
-- Amount of errors generated by a command, that is, new errors can be added
- to any existing command in newer versions of the Server
-
-Any command or member name beginning with "x-" is deemed experimental,
-and may be withdrawn or changed in an incompatible manner in a future
-release.
-
-Of course, the Server does guarantee to send valid JSON. But apart from
-this, a Client should be "conservative in what they send, and liberal in
-what they accept".
-
-6. Downstream extension of QMP
-==============================
-
-We recommend that downstream consumers of QEMU do *not* modify QMP.
-Management tools should be able to support both upstream and downstream
-versions of QMP without special logic, and downstream extensions are
-inherently at odds with that.
-
-However, we recognize that it is sometimes impossible for downstreams to
-avoid modifying QMP. Both upstream and downstream need to take care to
-preserve long-term compatibility and interoperability.
-
-To help with that, QMP reserves JSON object member names beginning with
-'__' (double underscore) for downstream use ("downstream names"). This
-means upstream will never use any downstream names for its commands,
-arguments, errors, asynchronous events, and so forth.
-
-Any new names downstream wishes to add must begin with '__'. To
-ensure compatibility with other downstreams, it is strongly
-recommended that you prefix your downstream names with '__RFQDN_' where
-RFQDN is a valid, reverse fully qualified domain name which you
-control. For example, a qemu-kvm specific monitor command would be:
-
- (qemu) __org.linux-kvm_enable_irqchip
-
-Downstream must not change the server greeting (section 2.2) other than
-to offer additional capabilities. But see below for why even that is
-discouraged.
-
-Section '5 Compatibility Considerations' applies to downstream as well
-as to upstream, obviously. It follows that downstream must behave
-exactly like upstream for any input not containing members with
-downstream names ("downstream members"), except it may add members
-with downstream names to its output.
-
-Thus, a client should not be able to distinguish downstream from
-upstream as long as it doesn't send input with downstream members, and
-properly ignores any downstream members in the output it receives.
-
-Advice on downstream modifications:
-
-1. Introducing new commands is okay. If you want to extend an existing
- command, consider introducing a new one with the new behaviour
- instead.
-
-2. Introducing new asynchronous messages is okay. If you want to extend
- an existing message, consider adding a new one instead.
-
-3. Introducing new errors for use in new commands is okay. Adding new
- errors to existing commands counts as extension, so 1. applies.
-
-4. New capabilities are strongly discouraged. Capabilities are for
- evolving the basic protocol, and multiple diverging basic protocol
- dialects are most undesirable.
diff --git a/python/qemu/qmp/models.py b/python/qemu/qmp/models.py
index de87f87..da52848 100644
--- a/python/qemu/qmp/models.py
+++ b/python/qemu/qmp/models.py
@@ -54,7 +54,7 @@
class Greeting(Model):
"""
- Defined in qmp-spec.txt, section 2.2, "Server Greeting".
+ Defined in qmp-spec.rst, section "Server Greeting".
:param raw: The raw Greeting object.
:raise KeyError: If any required fields are absent.
@@ -82,7 +82,7 @@
class QMPGreeting(Model):
"""
- Defined in qmp-spec.txt, section 2.2, "Server Greeting".
+ Defined in qmp-spec.rst, section "Server Greeting".
:param raw: The raw QMPGreeting object.
:raise KeyError: If any required fields are absent.
@@ -104,7 +104,7 @@
class ErrorResponse(Model):
"""
- Defined in qmp-spec.txt, section 2.4.2, "error".
+ Defined in qmp-spec.rst, section "Error".
:param raw: The raw ErrorResponse object.
:raise KeyError: If any required fields are absent.
@@ -126,7 +126,7 @@
class ErrorInfo(Model):
"""
- Defined in qmp-spec.txt, section 2.4.2, "error".
+ Defined in qmp-spec.rst, section "Error".
:param raw: The raw ErrorInfo object.
:raise KeyError: If any required fields are absent.
diff --git a/python/qemu/qmp/qmp_client.py b/python/qemu/qmp/qmp_client.py
index 9d73ae6..2a817f9 100644
--- a/python/qemu/qmp/qmp_client.py
+++ b/python/qemu/qmp/qmp_client.py
@@ -369,7 +369,7 @@
# This is very likely a server parsing error.
# It doesn't inherently belong to any pending execution.
# Instead of performing clever recovery, just terminate.
- # See "NOTE" in qmp-spec.txt, section 2.4.2
+ # See "NOTE" in qmp-spec.rst, section "Error".
raise ServerParseError(
("Server sent an error response without an ID, "
"but there are no ID-less executions pending. "
@@ -377,7 +377,7 @@
msg
)
- # qmp-spec.txt, section 2.4:
+ # qmp-spec.rst, section "Commands Responses":
# 'Clients should drop all the responses
# that have an unknown "id" field.'
self.logger.log(
diff --git a/qapi/control.json b/qapi/control.json
index 6a7c5af..a91fa33 100644
--- a/qapi/control.json
+++ b/qapi/control.json
@@ -27,7 +27,7 @@
# 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)
+# docs/interop/qmp-spec.rst)
#
# The QMP client needs to explicitly enable QMP capabilities,
# otherwise all the QMP capabilities will be turned off by
@@ -46,7 +46,7 @@
# 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)
+# qmp-spec.rst for more information on OOB)
#
# Since: 2.12
##
diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json
index 31e0b36..6594afb 100644
--- a/qapi/qapi-schema.json
+++ b/qapi/qapi-schema.json
@@ -29,7 +29,8 @@
# -> data issued by the Client
# <- Server data response
#
-# Please, refer to the QMP specification (docs/interop/qmp-spec.txt)
+# Please refer to the
+# :doc:`QEMU Machine Protocol Specification </interop/qmp-spec>`
# for detailed information on the Server command and response formats.
##
diff --git a/qemu-options.hx b/qemu-options.hx
index 30690d9..e456614 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -4170,26 +4170,42 @@
QEMU_ARCH_ALL)
SRST
``-qmp dev``
- Like -monitor but opens in 'control' mode.
+ Like ``-monitor`` but opens in 'control' mode. For example, to make
+ QMP available on localhost port 4444::
+
+ -qmp tcp:localhost:4444,server=on,wait=off
+
+ Not all options are configurable via this syntax; for maximum
+ flexibility use the ``-mon`` option and an accompanying ``-chardev``.
+
ERST
DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \
"-qmp-pretty dev like -qmp but uses pretty JSON formatting\n",
QEMU_ARCH_ALL)
SRST
``-qmp-pretty dev``
- Like -qmp but uses pretty JSON formatting.
+ Like ``-qmp`` but uses pretty JSON formatting.
ERST
DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
"-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL)
SRST
``-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]``
- Setup monitor on chardev name. ``mode=control`` configures
- a QMP monitor (a JSON RPC-style protocol) and it is not the
- same as HMP, the human monitor that has a "(qemu)" prompt.
- ``pretty`` is only valid when ``mode=control``,
+ Set up a monitor connected to the chardev ``name``.
+ QEMU supports two monitors: the Human Monitor Protocol
+ (HMP; for human interaction), and the QEMU Monitor Protocol
+ (QMP; a JSON RPC-style protocol).
+ The default is HMP; ``mode=control`` selects QMP instead.
+ ``pretty`` is only valid when ``mode=control``,
turning on JSON pretty printing to ease
human reading and debugging.
+
+ For example::
+
+ -chardev socket,id=mon1,host=localhost,port=4444,server=on,wait=off \
+ -mon chardev=mon1,mode=control,pretty=on
+
+ enables the QMP monitor on localhost port 4444 with pretty-printing.
ERST
DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
diff --git a/qobject/json-lexer.c b/qobject/json-lexer.c
index 632320d..51341d9 100644
--- a/qobject/json-lexer.c
+++ b/qobject/json-lexer.c
@@ -139,7 +139,7 @@
* bytes '\xFE', '\xFF'. Structural characters and line
* endings are promising resynchronization points. Clients
* may use the others to force the JSON parser into known-good
- * state; see docs/interop/qmp-spec.txt.
+ * state; see docs/interop/qmp-spec.rst.
*/
[0 ... 0x1F] = IN_START | LOOKAHEAD,
[0x20 ... 0xFD] = IN_RECOVERY,
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index 1ff334e..22e7bcc 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -675,8 +675,8 @@
match = self._match_at_name_colon(line)
if match:
raise QAPIParseError(self._parser,
- "'@%s:' can't follow '%s' section"
- % (match.group(1), self.sections[0].name))
+ "description of '@%s:' follows a section"
+ % match.group(1))
match = self._match_section_tag(line)
if match:
line = line[match.end():]
diff --git a/tests/qapi-schema/doc-interleaved-section.err b/tests/qapi-schema/doc-interleaved-section.err
index 715d58c..e5d1ef5 100644
--- a/tests/qapi-schema/doc-interleaved-section.err
+++ b/tests/qapi-schema/doc-interleaved-section.err
@@ -1 +1 @@
-doc-interleaved-section.json:15:1: '@foobar:' can't follow 'Note' section
+doc-interleaved-section.json:15:1: description of '@foobar:' follows a section
