QMP: Update qmp-spec.txt
Simplify the text, fix some of the examples. Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
This commit is contained in:
parent
52bbff77c4
commit
715c18600c
|
@ -1,21 +1,17 @@
|
||||||
QEMU Monitor Protocol Specification - Version 0.1
|
QEMU Machine Protocol Specification
|
||||||
|
|
||||||
1. Introduction
|
1. Introduction
|
||||||
===============
|
===============
|
||||||
|
|
||||||
This document specifies the QEMU Monitor Protocol (QMP), a JSON-based protocol
|
This document specifies the QEMU Machine Protocol (QMP), a JSON-based protocol
|
||||||
which is available for applications to control QEMU at the machine-level.
|
which is available for applications to operate QEMU at the machine-level.
|
||||||
|
|
||||||
To enable QMP support, QEMU has to be run in "control mode". This is done by
|
|
||||||
starting QEMU with the appropriate command-line options. Please, refer to the
|
|
||||||
QEMU manual page for more information.
|
|
||||||
|
|
||||||
2. Protocol Specification
|
2. Protocol Specification
|
||||||
=========================
|
=========================
|
||||||
|
|
||||||
This section details the protocol format. For the purpose of this document
|
This section details the protocol format. For the purpose of this document
|
||||||
"Client" is any application which is communicating with QEMU in control mode,
|
"Client" is any application which is using QMP to communicate with QEMU and
|
||||||
and "Server" is QEMU itself.
|
"Server" is QEMU itself.
|
||||||
|
|
||||||
JSON data structures, when mentioned in this document, are always in the
|
JSON data structures, when mentioned in this document, are always in the
|
||||||
following format:
|
following format:
|
||||||
|
@ -47,14 +43,14 @@ that the connection has been successfully established and that the Server is
|
||||||
ready for capabilities negotiation (for more information refer to section
|
ready for capabilities negotiation (for more information refer to section
|
||||||
'4. Capabilities Negotiation').
|
'4. Capabilities Negotiation').
|
||||||
|
|
||||||
The format is:
|
The greeting message format is:
|
||||||
|
|
||||||
{ "QMP": { "version": json-object, "capabilities": json-array } }
|
{ "QMP": { "version": json-object, "capabilities": json-array } }
|
||||||
|
|
||||||
Where,
|
Where,
|
||||||
|
|
||||||
- The "version" member contains the Server's version information (the format
|
- The "version" member contains the Server's version information (the format
|
||||||
is the same of the 'query-version' command)
|
is the same of the query-version command)
|
||||||
- The "capabilities" member specify the availability of features beyond the
|
- The "capabilities" member specify the availability of features beyond the
|
||||||
baseline specification
|
baseline specification
|
||||||
|
|
||||||
|
@ -83,10 +79,7 @@ of a command execution: success or error.
|
||||||
2.4.1 success
|
2.4.1 success
|
||||||
-------------
|
-------------
|
||||||
|
|
||||||
The success response is issued when the command execution has finished
|
The format of a success response is:
|
||||||
without errors.
|
|
||||||
|
|
||||||
The format is:
|
|
||||||
|
|
||||||
{ "return": json-object, "id": json-value }
|
{ "return": json-object, "id": json-value }
|
||||||
|
|
||||||
|
@ -96,15 +89,12 @@ The format is:
|
||||||
in a per-command basis or an empty json-object if the command does not
|
in a per-command basis or an empty json-object if the command does not
|
||||||
return data
|
return data
|
||||||
- The "id" member contains the transaction identification associated
|
- The "id" member contains the transaction identification associated
|
||||||
with the command execution (if issued by the Client)
|
with the command execution if issued by the Client
|
||||||
|
|
||||||
2.4.2 error
|
2.4.2 error
|
||||||
-----------
|
-----------
|
||||||
|
|
||||||
The error response is issued when the command execution could not be
|
The format of an error response is:
|
||||||
completed because of an error condition.
|
|
||||||
|
|
||||||
The format is:
|
|
||||||
|
|
||||||
{ "error": { "class": json-string, "desc": json-string }, "id": json-value }
|
{ "error": { "class": json-string, "desc": json-string }, "id": json-value }
|
||||||
|
|
||||||
|
@ -114,7 +104,7 @@ The format is:
|
||||||
- The "desc" member is a human-readable error message. Clients should
|
- The "desc" member is a human-readable error message. Clients should
|
||||||
not attempt to parse this message.
|
not attempt to parse this message.
|
||||||
- The "id" member contains the transaction identification associated with
|
- The "id" member contains the transaction identification associated with
|
||||||
the command execution (if issued by the Client)
|
the command execution if issued by the Client
|
||||||
|
|
||||||
NOTE: Some errors can occur before the Server is able to read the "id" member,
|
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
|
in these cases the "id" member will not be part of the error response, even
|
||||||
|
@ -124,9 +114,9 @@ if provided by the client.
|
||||||
-----------------------
|
-----------------------
|
||||||
|
|
||||||
As a result of state changes, the Server may send messages unilaterally
|
As a result of state changes, the Server may send messages unilaterally
|
||||||
to the Client at any time. They are called 'asynchronous events'.
|
to the Client at any time. They are called "asynchronous events".
|
||||||
|
|
||||||
The format is:
|
The format of asynchronous events is:
|
||||||
|
|
||||||
{ "event": json-string, "data": json-object,
|
{ "event": json-string, "data": json-object,
|
||||||
"timestamp": { "seconds": json-number, "microseconds": json-number } }
|
"timestamp": { "seconds": json-number, "microseconds": json-number } }
|
||||||
|
@ -147,12 +137,13 @@ qmp-events.txt file.
|
||||||
===============
|
===============
|
||||||
|
|
||||||
This section provides some examples of real QMP usage, in all of them
|
This section provides some examples of real QMP usage, in all of them
|
||||||
'C' stands for 'Client' and 'S' stands for 'Server'.
|
"C" stands for "Client" and "S" stands for "Server".
|
||||||
|
|
||||||
3.1 Server greeting
|
3.1 Server greeting
|
||||||
-------------------
|
-------------------
|
||||||
|
|
||||||
S: {"QMP": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}
|
S: { "QMP": { "version": { "qemu": { "micro": 50, "minor": 6, "major": 1 },
|
||||||
|
"package": ""}, "capabilities": []}}
|
||||||
|
|
||||||
3.2 Simple 'stop' execution
|
3.2 Simple 'stop' execution
|
||||||
---------------------------
|
---------------------------
|
||||||
|
@ -175,8 +166,8 @@ S: {"error": {"class": "GenericError", "desc": "Invalid JSON syntax" } }
|
||||||
3.5 Powerdown event
|
3.5 Powerdown event
|
||||||
-------------------
|
-------------------
|
||||||
|
|
||||||
S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
|
S: { "timestamp": { "seconds": 1258551470, "microseconds": 802384 },
|
||||||
"POWERDOWN"}
|
"event": "POWERDOWN" }
|
||||||
|
|
||||||
4. Capabilities Negotiation
|
4. Capabilities Negotiation
|
||||||
----------------------------
|
----------------------------
|
||||||
|
@ -184,17 +175,17 @@ S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
|
||||||
When a Client successfully establishes a connection, the Server is in
|
When a Client successfully establishes a connection, the Server is in
|
||||||
Capabilities Negotiation mode.
|
Capabilities Negotiation mode.
|
||||||
|
|
||||||
In this mode only the 'qmp_capabilities' command is allowed to run, all
|
In this mode only the qmp_capabilities command is allowed to run, all
|
||||||
other commands will return the CommandNotFound error. Asynchronous messages
|
other commands will return the CommandNotFound error. Asynchronous
|
||||||
are not delivered either.
|
messages are not delivered either.
|
||||||
|
|
||||||
Clients should use the 'qmp_capabilities' command to enable capabilities
|
Clients should use the qmp_capabilities command to enable capabilities
|
||||||
advertised in the Server's greeting (section '2.2 Server Greeting') they
|
advertised in the Server's greeting (section '2.2 Server Greeting') they
|
||||||
support.
|
support.
|
||||||
|
|
||||||
When the 'qmp_capabilities' command is issued, and if it does not return an
|
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
|
error, the Server enters in Command mode where capabilities changes take
|
||||||
effect, all commands (except 'qmp_capabilities') are allowed and asynchronous
|
effect, all commands (except qmp_capabilities) are allowed and asynchronous
|
||||||
messages are delivered.
|
messages are delivered.
|
||||||
|
|
||||||
5 Compatibility Considerations
|
5 Compatibility Considerations
|
||||||
|
@ -245,7 +236,7 @@ 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
|
ensure compatibility with other downstreams, it is strongly
|
||||||
recommended that you prefix your downstram 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
|
RFQDN is a valid, reverse fully qualified domain name which you
|
||||||
control. For example, a qemu-kvm specific monitor command would be:
|
control. For example, a qemu-kvm specific monitor command would be:
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue