Merge remote-tracking branch 'luiz/queue/qmp' into staging
# By Luiz Capitulino # Via Luiz Capitulino * luiz/queue/qmp: QMP: qmp-events.txt: alphabetical order fix and other minor changes QMP: Update qmp-spec.txt QMP: Update README file QMP: QMP/ -> docs/qmp/ QMP: fix qmp-commands.txt generation path QMP: add scripts/qmp Message-id: 1379509422-29115-1-git-send-email-lcapitulino@redhat.com
This commit is contained in:
Anthony Liguori
commit
f54c49e218
6
Makefile
6
Makefile
|
|
@ -65,7 +65,7 @@ LIBS+=-lz $(LIBS_TOOLS)
|
|||
HELPERS-$(CONFIG_LINUX) = qemu-bridge-helper$(EXESUF)
|
||||
|
||||
ifdef BUILD_DOCS
|
||||
DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 QMP/qmp-commands.txt
|
||||
DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 qmp-commands.txt
|
||||
ifdef CONFIG_VIRTFS
|
||||
DOCS+=fsdev/virtfs-proxy-helper.1
|
||||
endif
|
||||
|
|
@ -304,7 +304,7 @@ endif
|
|||
install-doc: $(DOCS)
|
||||
$(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
|
||||
$(INSTALL_DATA) qemu-doc.html qemu-tech.html "$(DESTDIR)$(qemu_docdir)"
|
||||
$(INSTALL_DATA) QMP/qmp-commands.txt "$(DESTDIR)$(qemu_docdir)"
|
||||
$(INSTALL_DATA) qmp-commands.txt "$(DESTDIR)$(qemu_docdir)"
|
||||
ifdef CONFIG_POSIX
|
||||
$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
|
||||
$(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1"
|
||||
|
|
@ -398,7 +398,7 @@ qemu-options.texi: $(SRC_PATH)/qemu-options.hx
|
|||
qemu-monitor.texi: $(SRC_PATH)/hmp-commands.hx
|
||||
$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@," GEN $@")
|
||||
|
||||
QMP/qmp-commands.txt: $(SRC_PATH)/qmp-commands.hx
|
||||
qmp-commands.txt: $(SRC_PATH)/qmp-commands.hx
|
||||
$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -q < $< > $@," GEN $@")
|
||||
|
||||
qemu-img-cmds.texi: $(SRC_PATH)/qemu-img-cmds.hx
|
||||
|
|
|
|||
88
QMP/README
88
QMP/README
|
|
@ -1,88 +0,0 @@
|
|||
QEMU Monitor Protocol
|
||||
=====================
|
||||
|
||||
Introduction
|
||||
-------------
|
||||
|
||||
The QEMU Monitor Protocol (QMP) allows applications to communicate with
|
||||
QEMU's Monitor.
|
||||
|
||||
QMP is JSON[1] based and currently has the following features:
|
||||
|
||||
- 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 Monitor Protocol current specification
|
||||
o qmp-commands.txt QMP supported commands (auto-generated at build-time)
|
||||
o qmp-events.txt List of available asynchronous events
|
||||
|
||||
There is also a simple Python script called 'qmp-shell' available.
|
||||
|
||||
IMPORTANT: It's strongly recommended to read the 'Stability Considerations'
|
||||
section in the qmp-commands.txt file before making any serious use of QMP.
|
||||
|
||||
|
||||
[1] http://www.json.org
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
To enable QMP, you need a QEMU monitor instance in "control mode". There are
|
||||
two ways of doing this.
|
||||
|
||||
The simplest one is using the '-qmp' command-line option. The following
|
||||
example makes QMP available on localhost port 4444:
|
||||
|
||||
$ qemu [...] -qmp tcp:localhost:4444,server
|
||||
|
||||
However, in order to have more complex combinations, like multiple monitors,
|
||||
the '-mon' command-line option should be used along with the '-chardev' one.
|
||||
For instance, the following example creates one user monitor on stdio and one
|
||||
QMP monitor on localhost port 4444.
|
||||
|
||||
$ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
|
||||
-chardev socket,id=mon1,host=localhost,port=4444,server \
|
||||
-mon chardev=mon1,mode=control
|
||||
|
||||
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": 50, "minor": 13, "major": 0}, "package": ""}, "capabilities": []}}
|
||||
{ "execute": "qmp_capabilities" }
|
||||
{"return": {}}
|
||||
{ "execute": "query-version" }
|
||||
{"return": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}}
|
||||
|
||||
Development Process
|
||||
-------------------
|
||||
|
||||
When changing QMP's interface (by adding new commands, events or modifying
|
||||
existing ones) it's mandatory to update the relevant documentation, which is
|
||||
one (or more) of the files listed in the 'Introduction' section*.
|
||||
|
||||
Also, it's strongly recommended to send the documentation patch first, before
|
||||
doing any code change. This is so because:
|
||||
|
||||
1. Avoids the code dictating the interface
|
||||
|
||||
2. Review can improve your interface. Letting that happen before
|
||||
you implement it can save you work.
|
||||
|
||||
* The qmp-commands.txt file is generated from the qmp-commands.hx one, which
|
||||
is the file that should be edited.
|
||||
|
||||
Homepage
|
||||
--------
|
||||
|
||||
http://wiki.qemu.org/QMP
|
||||
87
docs/qmp/README
Normal file
87
docs/qmp/README
Normal file
|
|
@ -0,0 +1,87 @@
|
|||
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 qmp-commands.txt QMP supported commands (auto-generated at build-time)
|
||||
o qmp-events.txt List of available asynchronous events
|
||||
|
||||
[1] http://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,nowait
|
||||
|
||||
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,nowait \
|
||||
-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": 50,
|
||||
"minor": 6,
|
||||
"major": 1
|
||||
},
|
||||
"package": ""
|
||||
},
|
||||
"capabilities": [
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
{ "execute": "qmp_capabilities" }
|
||||
{
|
||||
"return": {
|
||||
}
|
||||
}
|
||||
|
||||
{ "execute": "query-status" }
|
||||
{
|
||||
"return": {
|
||||
"status": "prelaunch",
|
||||
"singlestep": false,
|
||||
"running": false
|
||||
}
|
||||
}
|
||||
|
||||
Please, refer to the qapi-schema.json file for a complete command reference.
|
||||
|
||||
QMP wiki page
|
||||
-------------
|
||||
|
||||
http://wiki.qemu.org/QMP
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
QEMU Monitor Protocol Events
|
||||
QEMU Machine Protocol Events
|
||||
============================
|
||||
|
||||
BALLOON_CHANGE
|
||||
|
|
@ -159,7 +159,7 @@ Note: The "ready to complete" status is always reset by a BLOCK_JOB_ERROR
|
|||
event.
|
||||
|
||||
DEVICE_DELETED
|
||||
-----------------
|
||||
--------------
|
||||
|
||||
Emitted whenever the device removal completion is acknowledged
|
||||
by the guest.
|
||||
|
|
@ -194,8 +194,22 @@ Data:
|
|||
},
|
||||
"timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
|
||||
|
||||
GUEST_PANICKED
|
||||
--------------
|
||||
|
||||
Emitted when guest OS panic is detected.
|
||||
|
||||
Data:
|
||||
|
||||
- "action": Action that has been taken (json-string, currently always "pause").
|
||||
|
||||
Example:
|
||||
|
||||
{ "event": "GUEST_PANICKED",
|
||||
"data": { "action": "pause" } }
|
||||
|
||||
NIC_RX_FILTER_CHANGED
|
||||
-----------------
|
||||
---------------------
|
||||
|
||||
The event is emitted once until the query command is executed,
|
||||
the first event will always be emitted.
|
||||
|
|
@ -486,17 +500,3 @@ Example:
|
|||
|
||||
Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event is
|
||||
followed respectively by the RESET, SHUTDOWN, or STOP events.
|
||||
|
||||
GUEST_PANICKED
|
||||
--------------
|
||||
|
||||
Emitted when guest OS panic is detected.
|
||||
|
||||
Data:
|
||||
|
||||
- "action": Action that has been taken (json-string, currently always "pause").
|
||||
|
||||
Example:
|
||||
|
||||
{ "event": "GUEST_PANICKED",
|
||||
"data": { "action": "pause" } }
|
||||
|
|
@ -1,21 +1,17 @@
|
|||
QEMU Monitor Protocol Specification - Version 0.1
|
||||
QEMU Machine Protocol Specification
|
||||
|
||||
1. Introduction
|
||||
===============
|
||||
|
||||
This document specifies the QEMU Monitor Protocol (QMP), a JSON-based protocol
|
||||
which is available for applications to control 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.
|
||||
This document specifies the QEMU Machine Protocol (QMP), a JSON-based protocol
|
||||
which is available for applications to operate QEMU at the machine-level.
|
||||
|
||||
2. Protocol Specification
|
||||
=========================
|
||||
|
||||
This section details the protocol format. For the purpose of this document
|
||||
"Client" is any application which is communicating with QEMU in control mode,
|
||||
and "Server" is QEMU itself.
|
||||
"Client" is any application which is using QMP to communicate with QEMU and
|
||||
"Server" is QEMU itself.
|
||||
|
||||
JSON data structures, when mentioned in this document, are always in the
|
||||
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
|
||||
'4. Capabilities Negotiation').
|
||||
|
||||
The format is:
|
||||
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)
|
||||
is the same of the query-version command)
|
||||
- The "capabilities" member specify the availability of features beyond the
|
||||
baseline specification
|
||||
|
||||
|
|
@ -83,10 +79,7 @@ of a command execution: success or error.
|
|||
2.4.1 success
|
||||
-------------
|
||||
|
||||
The success response is issued when the command execution has finished
|
||||
without errors.
|
||||
|
||||
The format is:
|
||||
The format of a success response is:
|
||||
|
||||
{ "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
|
||||
return data
|
||||
- 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
|
||||
-----------
|
||||
|
||||
The error response is issued when the command execution could not be
|
||||
completed because of an error condition.
|
||||
|
||||
The format is:
|
||||
The format of an error response is:
|
||||
|
||||
{ "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
|
||||
not attempt to parse this message.
|
||||
- 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,
|
||||
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
|
||||
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,
|
||||
"timestamp": { "seconds": json-number, "microseconds": json-number } }
|
||||
|
|
@ -147,36 +137,37 @@ qmp-events.txt file.
|
|||
===============
|
||||
|
||||
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
|
||||
-------------------
|
||||
|
||||
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
|
||||
---------------------------
|
||||
|
||||
C: { "execute": "stop" }
|
||||
S: {"return": {}}
|
||||
S: { "return": {} }
|
||||
|
||||
3.3 KVM information
|
||||
-------------------
|
||||
|
||||
C: { "execute": "query-kvm", "id": "example" }
|
||||
S: {"return": {"enabled": true, "present": true}, "id": "example"}
|
||||
S: { "return": { "enabled": true, "present": true }, "id": "example"}
|
||||
|
||||
3.4 Parsing error
|
||||
------------------
|
||||
|
||||
C: { "execute": }
|
||||
S: {"error": {"class": "GenericError", "desc": "Invalid JSON syntax" } }
|
||||
S: { "error": { "class": "GenericError", "desc": "Invalid JSON syntax" } }
|
||||
|
||||
3.5 Powerdown event
|
||||
-------------------
|
||||
|
||||
S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
|
||||
"POWERDOWN"}
|
||||
S: { "timestamp": { "seconds": 1258551470, "microseconds": 802384 },
|
||||
"event": "POWERDOWN" }
|
||||
|
||||
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
|
||||
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.
|
||||
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
|
||||
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
|
||||
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
|
||||
effect, all commands (except qmp_capabilities) are allowed and asynchronous
|
||||
messages are delivered.
|
||||
|
||||
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
|
||||
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
|
||||
control. For example, a qemu-kvm specific monitor command would be:
|
||||
|
||||
|
|
@ -91,7 +91,7 @@ class QMPShell(qmp.QEMUMonitorProtocol):
|
|||
"""
|
||||
Build a QMP input object from a user provided command-line in the
|
||||
following format:
|
||||
|
||||
|
||||
< command-name > [ arg-name1=arg1 ] ... [ arg-nameN=argN ]
|
||||
"""
|
||||
cmdargs = cmdline.split()
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
# QEMU Monitor Protocol Python class
|
||||
#
|
||||
#
|
||||
# Copyright (C) 2009, 2010 Red Hat Inc.
|
||||
#
|
||||
# Authors:
|
||||
Loading…
Reference in a new issue