system/qemu
system/qemu
1
0
Fork 0
mirror of https://gitlab.com/qemu-project/qemu synced 2024-11-05 20:35:44 +00:00
Code Issues Projects Releases Packages Wiki Activity

QAPI patches patches for 2023-05-17

Browse source 
-----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-----

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>
This commit is contained in:
Richard Henderson 2023-05-22 15:54:21 -07:00
commit 886c0453cb
12 changed files with 224 additions and 260 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
docs/devel/qapi-code-gen.rst
View file

@ -545,7 +545,8 @@ Member 'allow-oob' declares whether the command supports out-of-band
{ '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.

1
docs/interop/index.rst
View file

@ -15,6 +15,7 @@ are useful for making QEMU interoperate with other software.
dbus-display
live-block-operations
pr-helper
qmp-spec
qemu-ga
qemu-ga-ref
qemu-qmp-ref

88
docs/interop/qmp-intro.txt
View file

@ -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

337
docs/interop/qmp-spec.txt → docs/interop/qmp-spec.rst
View file

@ -1,24 +1,26 @@
QEMU Machine Protocol Specification
..
Copyright (C) 2009-2016 Red Hat, Inc.
0. About This Document
======================
This work is licensed under the terms of the GNU GPL, version 2 or
later. See the COPYING file in the top-level directory.
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
===================================
1. Introduction
===============
This document specifies the QEMU Machine Protocol (QMP), a JSON-based
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.
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`.
2. Protocol Specification
=========================
.. 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
@ -30,9 +32,7 @@ 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
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.
@ -45,83 +45,89 @@ 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"
``'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
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
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
'4. Capabilities Negotiation').
`Capabilities Negotiation`_).
The greeting message format is:
{ "QMP": { "version": json-object, "capabilities": json-array } }
::
Where,
{ "QMP": { "version": json-object, "capabilities": json-array } }
- 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
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.
2.2.1 Capabilities
------------------
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".
``oob``
the QMP server supports "out-of-band" (OOB) command
execution, as described in section `Out-of-band execution`_.
2.3 Issuing Commands
--------------------
Issuing Commands
----------------
The format for command execution is:
{ "execute": json-string, "arguments": json-object, "id": json-value }
::
{ "execute": json-string, "arguments": json-object, "id": json-value }
or
{ "exec-oob": json-string, "arguments": json-object, "id": json-value }
::
Where,
{ "exec-oob": json-string, "arguments": json-object, "id": json-value }
- The "execute" or "exec-oob" member identifies the command to be
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
- 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
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
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}.
The actual commands are documented in the :doc:`qemu-qmp-ref`.
2.3.1 Out-of-band execution
---------------------------
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
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
@ -129,8 +135,8 @@ 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".
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
@ -140,57 +146,61 @@ 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.
have ``"allow-oob": true`` in the output of ``query-qmp-schema``.
2.4 Commands Responses
----------------------
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
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.
responses that have an unknown ``id`` field.
2.4.1 success
-------------
Success
-------
The format of a success response is:
{ "return": json-value, "id": json-value }
::
Where,
{ "return": json-value, "id": json-value }
- The "return" member contains the data returned by the command, which
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
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
-----------
Error
-----
The format of an error response is:
{ "error": { "class": json-string, "desc": json-string }, "id": json-value }
::
Where,
{ "error": { "class": json-string, "desc": json-string }, "id": json-value }
- The "class" member contains the error class name (eg. "GenericError")
- The "desc" member is a human-readable error message. Clients should
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
- 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
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
-----------------------
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
@ -198,44 +208,45 @@ 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,
{ "event": json-string, "data": json-object,
"timestamp": { "seconds": json-number, "microseconds": json-number } }
- 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
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}.
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.
2.6 Forcing the JSON parser into known-good state
-------------------------------------------------
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).
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
-----------------------
QGA Synchronization
-------------------
When a client connects to QGA over a transport lacking proper
connection semantics such as virtio-serial, QGA may have read partial
@ -243,86 +254,106 @@ 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
``guest-sync-delimited`` command. Refer to its documentation for
details.
3. QMP Examples
===============
QMP Examples
============
This section provides some examples of real QMP usage, in all of them
"C" stands for "Client" and "S" stands for "Server".
``->`` marks text sent by the Client and ``<-`` marks replies by the Server.
3.1 Server greeting
-------------------
.. admonition:: Example
S: { "QMP": {"version": {"qemu": {"micro": 0, "minor": 0, "major": 3},
"package": "v3.0.0"}, "capabilities": ["oob"] } }
Server greeting
3.2 Capabilities negotiation
----------------------------
.. code-block:: QMP
C: { "execute": "qmp_capabilities", "arguments": { "enable": ["oob"] } }
S: { "return": {}}
<- { "QMP": {"version": {"qemu": {"micro": 0, "minor": 0, "major": 3},
"package": "v3.0.0"}, "capabilities": ["oob"] } }
3.3 Simple 'stop' execution
---------------------------
.. admonition:: Example
C: { "execute": "stop" }
S: { "return": {} }
Capabilities negotiation
3.4 KVM information
-------------------
.. code-block:: QMP
C: { "execute": "query-kvm", "id": "example" }
S: { "return": { "enabled": true, "present": true }, "id": "example"}
-> { "execute": "qmp_capabilities", "arguments": { "enable": ["oob"] } }
<- { "return": {}}
3.5 Parsing error
------------------
.. admonition:: Example
C: { "execute": }
S: { "error": { "class": "GenericError", "desc": "Invalid JSON syntax" } }
Simple 'stop' execution
3.6 Powerdown event
-------------------
.. code-block:: QMP
S: { "timestamp": { "seconds": 1258551470, "microseconds": 802384 },
"event": "POWERDOWN" }
-> { "execute": "stop" }
<- { "return": {} }
3.7 Out-of-band execution
-------------------------
.. admonition:: Example
C: { "exec-oob": "migrate-pause", "id": 42 }
S: { "id": 42,
"error": { "class": "GenericError",
"desc": "migrate-pause is currently only supported during postcopy-active state" } }
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" } }
4. Capabilities Negotiation
===========================
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
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.
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 in Command mode where capabilities changes take
effect, all commands (except qmp_capabilities) are allowed and asynchronous
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.
5 Compatibility Considerations
==============================
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
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
@ -337,12 +368,12 @@ 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.
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,
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.
@ -350,8 +381,8 @@ 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
==============================
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
@ -363,23 +394,25 @@ 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
``__`` (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
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
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
Downstream must not change the `server greeting`_ other than
to offer additional capabilities. But see below for why even that is
discouraged.
Section '5 Compatibility Considerations' applies to downstream as well
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

8
python/qemu/qmp/models.py
View file

@ -54,7 +54,7 @@ def __repr__(self) -> str:
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 @@ def _asdict(self) -> Dict[str, object]:
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 @@ def __init__(self, raw: Mapping[str, Any]):
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 @@ def __init__(self, raw: Mapping[str, Any]):
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.

4
python/qemu/qmp/qmp_client.py
View file

@ -369,7 +369,7 @@ async def _on_message(self, msg: Message) -> None:
# 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 @@ async def _on_message(self, msg: Message) -> None:
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(

4
qapi/control.json
View file

@ -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
##

3
qapi/qapi-schema.json
View file

@ -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.
##

28
qemu-options.hx
View file

@ -4170,26 +4170,42 @@ DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
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, \

2
qobject/json-lexer.c
View file

@ -139,7 +139,7 @@ static const uint8_t json_lexer[][256] = {
* 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,

4
scripts/qapi/parser.py
View file

@ -675,8 +675,8 @@ def _append_various_line(self, line: str) -> None:
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():]

2
tests/qapi-schema/doc-interleaved-section.err
View file

@ -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