* [Qemu-devel] [PATCH 1/6] QMP: add scripts/qmp
2013-09-13 18:11 [Qemu-devel] [PATCH v2 0/6] QMP: re-organize documentation Luiz Capitulino
@ 2013-09-13 18:11 ` Luiz Capitulino
2013-09-13 18:11 ` [Qemu-devel] [PATCH 2/6] QMP: fix qmp-commands.txt generation path Luiz Capitulino
` (5 subsequent siblings)
6 siblings, 0 replies; 12+ messages in thread
From: Luiz Capitulino @ 2013-09-13 18:11 UTC (permalink / raw)
To: qemu-devel; +Cc: armbru
Populate it with all scripts stored in QMP/. Also fixes trailing
whitespaces in qmp-shell and qmp.py.
Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
{QMP => scripts/qmp}/qemu-ga-client | 0
{QMP => scripts/qmp}/qmp | 0
{QMP => scripts/qmp}/qmp-shell | 2 +-
{QMP => scripts/qmp}/qmp.py | 2 +-
{QMP => scripts/qmp}/qom-fuse | 0
{QMP => scripts/qmp}/qom-get | 0
{QMP => scripts/qmp}/qom-list | 0
{QMP => scripts/qmp}/qom-set | 0
8 files changed, 2 insertions(+), 2 deletions(-)
rename {QMP => scripts/qmp}/qemu-ga-client (100%)
rename {QMP => scripts/qmp}/qmp (100%)
rename {QMP => scripts/qmp}/qmp-shell (99%)
rename {QMP => scripts/qmp}/qmp.py (99%)
rename {QMP => scripts/qmp}/qom-fuse (100%)
rename {QMP => scripts/qmp}/qom-get (100%)
rename {QMP => scripts/qmp}/qom-list (100%)
rename {QMP => scripts/qmp}/qom-set (100%)
diff --git a/QMP/qemu-ga-client b/scripts/qmp/qemu-ga-client
similarity index 100%
rename from QMP/qemu-ga-client
rename to scripts/qmp/qemu-ga-client
diff --git a/QMP/qmp b/scripts/qmp/qmp
similarity index 100%
rename from QMP/qmp
rename to scripts/qmp/qmp
diff --git a/QMP/qmp-shell b/scripts/qmp/qmp-shell
similarity index 99%
rename from QMP/qmp-shell
rename to scripts/qmp/qmp-shell
index 73cb3b6..d6b420f 100755
--- a/QMP/qmp-shell
+++ b/scripts/qmp/qmp-shell
@@ -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()
diff --git a/QMP/qmp.py b/scripts/qmp/qmp.py
similarity index 99%
rename from QMP/qmp.py
rename to scripts/qmp/qmp.py
index c551df1..21804f4 100644
--- a/QMP/qmp.py
+++ b/scripts/qmp/qmp.py
@@ -1,5 +1,5 @@
# QEMU Monitor Protocol Python class
-#
+#
# Copyright (C) 2009, 2010 Red Hat Inc.
#
# Authors:
diff --git a/QMP/qom-fuse b/scripts/qmp/qom-fuse
similarity index 100%
rename from QMP/qom-fuse
rename to scripts/qmp/qom-fuse
diff --git a/QMP/qom-get b/scripts/qmp/qom-get
similarity index 100%
rename from QMP/qom-get
rename to scripts/qmp/qom-get
diff --git a/QMP/qom-list b/scripts/qmp/qom-list
similarity index 100%
rename from QMP/qom-list
rename to scripts/qmp/qom-list
diff --git a/QMP/qom-set b/scripts/qmp/qom-set
similarity index 100%
rename from QMP/qom-set
rename to scripts/qmp/qom-set
--
1.8.1.4
^ permalink raw reply related [flat|nested] 12+ messages in thread* [Qemu-devel] [PATCH 2/6] QMP: fix qmp-commands.txt generation path
2013-09-13 18:11 [Qemu-devel] [PATCH v2 0/6] QMP: re-organize documentation Luiz Capitulino
2013-09-13 18:11 ` [Qemu-devel] [PATCH 1/6] QMP: add scripts/qmp Luiz Capitulino
@ 2013-09-13 18:11 ` Luiz Capitulino
2013-09-13 18:11 ` [Qemu-devel] [PATCH 3/6] QMP: QMP/ -> docs/qmp/ Luiz Capitulino
` (4 subsequent siblings)
6 siblings, 0 replies; 12+ messages in thread
From: Luiz Capitulino @ 2013-09-13 18:11 UTC (permalink / raw)
To: qemu-devel; +Cc: armbru
This file should be generated in the BUILD_DIR, as all other docs.
Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
Makefile | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/Makefile b/Makefile
index 362fe3e..aca548d 100644
--- a/Makefile
+++ b/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
--
1.8.1.4
^ permalink raw reply related [flat|nested] 12+ messages in thread* [Qemu-devel] [PATCH 3/6] QMP: QMP/ -> docs/qmp/
2013-09-13 18:11 [Qemu-devel] [PATCH v2 0/6] QMP: re-organize documentation Luiz Capitulino
2013-09-13 18:11 ` [Qemu-devel] [PATCH 1/6] QMP: add scripts/qmp Luiz Capitulino
2013-09-13 18:11 ` [Qemu-devel] [PATCH 2/6] QMP: fix qmp-commands.txt generation path Luiz Capitulino
@ 2013-09-13 18:11 ` Luiz Capitulino
2013-09-13 18:11 ` [Qemu-devel] [PATCH 4/6] QMP: Update README file Luiz Capitulino
` (3 subsequent siblings)
6 siblings, 0 replies; 12+ messages in thread
From: Luiz Capitulino @ 2013-09-13 18:11 UTC (permalink / raw)
To: qemu-devel; +Cc: armbru
Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
{QMP => docs/qmp}/README | 0
{QMP => docs/qmp}/qmp-events.txt | 0
{QMP => docs/qmp}/qmp-spec.txt | 0
3 files changed, 0 insertions(+), 0 deletions(-)
rename {QMP => docs/qmp}/README (100%)
rename {QMP => docs/qmp}/qmp-events.txt (100%)
rename {QMP => docs/qmp}/qmp-spec.txt (100%)
diff --git a/QMP/README b/docs/qmp/README
similarity index 100%
rename from QMP/README
rename to docs/qmp/README
diff --git a/QMP/qmp-events.txt b/docs/qmp/qmp-events.txt
similarity index 100%
rename from QMP/qmp-events.txt
rename to docs/qmp/qmp-events.txt
diff --git a/QMP/qmp-spec.txt b/docs/qmp/qmp-spec.txt
similarity index 100%
rename from QMP/qmp-spec.txt
rename to docs/qmp/qmp-spec.txt
--
1.8.1.4
^ permalink raw reply [flat|nested] 12+ messages in thread* [Qemu-devel] [PATCH 4/6] QMP: Update README file
2013-09-13 18:11 [Qemu-devel] [PATCH v2 0/6] QMP: re-organize documentation Luiz Capitulino
` (2 preceding siblings ...)
2013-09-13 18:11 ` [Qemu-devel] [PATCH 3/6] QMP: QMP/ -> docs/qmp/ Luiz Capitulino
@ 2013-09-13 18:11 ` Luiz Capitulino
2013-09-13 18:11 ` [Qemu-devel] [PATCH 5/6] QMP: Update qmp-spec.txt Luiz Capitulino
` (2 subsequent siblings)
6 siblings, 0 replies; 12+ messages in thread
From: Luiz Capitulino @ 2013-09-13 18:11 UTC (permalink / raw)
To: qemu-devel; +Cc: armbru
Drop unneeded info, fix some of the examples and rename QEMU Monitor
Protocol to QEMU Machine Protocol.
Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
docs/qmp/README | 99 ++++++++++++++++++++++++++++-----------------------------
1 file changed, 49 insertions(+), 50 deletions(-)
diff --git a/docs/qmp/README b/docs/qmp/README
index c95a08c..85c4bc1 100644
--- a/docs/qmp/README
+++ b/docs/qmp/README
@@ -1,13 +1,13 @@
- QEMU Monitor Protocol
+ QEMU Machine Protocol
=====================
Introduction
--------------
+------------
-The QEMU Monitor Protocol (QMP) allows applications to communicate with
-QEMU's Monitor.
+The QEMU Machine Protocol (QMP) allows applications to operate a
+QEMU instance.
-QMP is JSON[1] based and currently has the following features:
+QMP is JSON[1] based and features the following:
- Lightweight, text-based, easy to parse data format
- Asynchronous messages support (ie. events)
@@ -15,37 +15,28 @@ QMP is JSON[1] based and currently has the following features:
For detailed information on QMP's usage, please, refer to the following files:
-o qmp-spec.txt QEMU Monitor Protocol current specification
+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
-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.
+You can use the -qmp option to enable QMP. For example, the following
+makes QMP available on localhost port 4444:
-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,nowait
- $ qemu [...] -qmp tcp:localhost:4444,server
+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:
-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
+$ 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.
@@ -58,31 +49,39 @@ $ 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
--------------------
+{
+ "QMP": {
+ "version": {
+ "qemu": {
+ "micro": 50,
+ "minor": 6,
+ "major": 1
+ },
+ "package": ""
+ },
+ "capabilities": [
+ ]
+ }
+}
-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
---------
+{ "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.8.1.4
^ permalink raw reply related [flat|nested] 12+ messages in thread* [Qemu-devel] [PATCH 5/6] QMP: Update qmp-spec.txt
2013-09-13 18:11 [Qemu-devel] [PATCH v2 0/6] QMP: re-organize documentation Luiz Capitulino
` (3 preceding siblings ...)
2013-09-13 18:11 ` [Qemu-devel] [PATCH 4/6] QMP: Update README file Luiz Capitulino
@ 2013-09-13 18:11 ` Luiz Capitulino
2013-09-13 18:11 ` [Qemu-devel] [PATCH 6/6] QMP: qmp-events.txt: alphabetical order fix and other minor changes Luiz Capitulino
2013-09-13 18:15 ` [Qemu-devel] [PATCH v2 0/6] QMP: re-organize documentation Eric Blake
6 siblings, 0 replies; 12+ messages in thread
From: Luiz Capitulino @ 2013-09-13 18:11 UTC (permalink / raw)
To: qemu-devel; +Cc: armbru
Simplify the text, fix some of the examples.
Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
docs/qmp/qmp-spec.txt | 65 ++++++++++++++++++++++-----------------------------
1 file changed, 28 insertions(+), 37 deletions(-)
diff --git a/docs/qmp/qmp-spec.txt b/docs/qmp/qmp-spec.txt
index a277896..22568c6 100644
--- a/docs/qmp/qmp-spec.txt
+++ b/docs/qmp/qmp-spec.txt
@@ -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:
--
1.8.1.4
^ permalink raw reply related [flat|nested] 12+ messages in thread* [Qemu-devel] [PATCH 6/6] QMP: qmp-events.txt: alphabetical order fix and other minor changes
2013-09-13 18:11 [Qemu-devel] [PATCH v2 0/6] QMP: re-organize documentation Luiz Capitulino
` (4 preceding siblings ...)
2013-09-13 18:11 ` [Qemu-devel] [PATCH 5/6] QMP: Update qmp-spec.txt Luiz Capitulino
@ 2013-09-13 18:11 ` Luiz Capitulino
2013-09-13 18:15 ` [Qemu-devel] [PATCH v2 0/6] QMP: re-organize documentation Eric Blake
6 siblings, 0 replies; 12+ messages in thread
From: Luiz Capitulino @ 2013-09-13 18:11 UTC (permalink / raw)
To: qemu-devel; +Cc: armbru
Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
docs/qmp/qmp-events.txt | 34 +++++++++++++++++-----------------
1 file changed, 17 insertions(+), 17 deletions(-)
diff --git a/docs/qmp/qmp-events.txt b/docs/qmp/qmp-events.txt
index 4b24ec9..6b87e97 100644
--- a/docs/qmp/qmp-events.txt
+++ b/docs/qmp/qmp-events.txt
@@ -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.8.1.4
^ permalink raw reply related [flat|nested] 12+ messages in thread* Re: [Qemu-devel] [PATCH v2 0/6] QMP: re-organize documentation
2013-09-13 18:11 [Qemu-devel] [PATCH v2 0/6] QMP: re-organize documentation Luiz Capitulino
` (5 preceding siblings ...)
2013-09-13 18:11 ` [Qemu-devel] [PATCH 6/6] QMP: qmp-events.txt: alphabetical order fix and other minor changes Luiz Capitulino
@ 2013-09-13 18:15 ` Eric Blake
6 siblings, 0 replies; 12+ messages in thread
From: Eric Blake @ 2013-09-13 18:15 UTC (permalink / raw)
To: Luiz Capitulino; +Cc: qemu-devel, armbru
[-- Attachment #1: Type: text/plain, Size: 731 bytes --]
On 09/13/2013 12:11 PM, Luiz Capitulino wrote:
> The QMP dir is storing QMP docs and scripts. This series moves the scripts to
> scripts/qmp/ and the docs to docs/qmp/. Also, the docs are updated.
>
> v2
>
> - Set git diff.renames to true
> - Fix trailing whitespaces
> - Other minor fixes
>
> Luiz Capitulino (6):
> QMP: add scripts/qmp
> QMP: fix qmp-commands.txt generation path
> QMP: QMP/ -> docs/qmp/
> QMP: Update README file
> QMP: Update qmp-spec.txt
> QMP: qmp-events.txt: alphabetical order fix and other minor changes
Series: Reviewed-by: Eric Blake <eblake@redhat.com>
--
Eric Blake eblake redhat com +1-919-301-3266
Libvirt virtualization library http://libvirt.org
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 621 bytes --]
^ permalink raw reply [flat|nested] 12+ messages in thread
* [Qemu-devel] [PATCH 5/6] QMP: Update qmp-spec.txt
2013-09-11 20:52 [Qemu-devel] [PATCH " Luiz Capitulino
@ 2013-09-11 20:52 ` Luiz Capitulino
2013-09-11 23:27 ` Eric Blake
0 siblings, 1 reply; 12+ messages in thread
From: Luiz Capitulino @ 2013-09-11 20:52 UTC (permalink / raw)
To: qemu-devel; +Cc: armbru
Simplify the text, fix some of the examples.
Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
docs/qmp/qmp-spec.txt | 65 ++++++++++++++++++++++-----------------------------
1 file changed, 28 insertions(+), 37 deletions(-)
diff --git a/docs/qmp/qmp-spec.txt b/docs/qmp/qmp-spec.txt
index a277896..22568c6 100644
--- a/docs/qmp/qmp-spec.txt
+++ b/docs/qmp/qmp-spec.txt
@@ -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:
--
1.8.1.4
^ permalink raw reply related [flat|nested] 12+ messages in thread* Re: [Qemu-devel] [PATCH 5/6] QMP: Update qmp-spec.txt
2013-09-11 20:52 ` [Qemu-devel] [PATCH 5/6] QMP: Update qmp-spec.txt Luiz Capitulino
@ 2013-09-11 23:27 ` Eric Blake
2013-09-13 17:54 ` Luiz Capitulino
0 siblings, 1 reply; 12+ messages in thread
From: Eric Blake @ 2013-09-11 23:27 UTC (permalink / raw)
To: Luiz Capitulino; +Cc: qemu-devel, armbru
[-- Attachment #1: Type: text/plain, Size: 880 bytes --]
On 09/11/2013 02:52 PM, Luiz Capitulino wrote:
> Simplify the text, fix some of the examples.
>
> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> ---
> docs/qmp/qmp-spec.txt | 65 ++++++++++++++++++++++-----------------------------
> 1 file changed, 28 insertions(+), 37 deletions(-)
>
> diff --git a/docs/qmp/qmp-spec.txt b/docs/qmp/qmp-spec.txt
> index a277896..22568c6 100644
> --- a/docs/qmp/qmp-spec.txt
> +++ b/docs/qmp/qmp-spec.txt
> @@ -1,21 +1,17 @@
> - QEMU Monitor Protocol Specification - Version 0.1
> + QEMU Machine Protocol Specification
Do we want a protocol version number? I guess if we ever add
capabilities, we can worry about it then.
Reviewed-by: Eric Blake <eblake@redhat.com>
--
Eric Blake eblake redhat com +1-919-301-3266
Libvirt virtualization library http://libvirt.org
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 621 bytes --]
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [Qemu-devel] [PATCH 5/6] QMP: Update qmp-spec.txt
2013-09-11 23:27 ` Eric Blake
@ 2013-09-13 17:54 ` Luiz Capitulino
2013-09-13 18:00 ` Eric Blake
0 siblings, 1 reply; 12+ messages in thread
From: Luiz Capitulino @ 2013-09-13 17:54 UTC (permalink / raw)
To: Eric Blake; +Cc: qemu-devel, armbru
On Wed, 11 Sep 2013 17:27:58 -0600
Eric Blake <eblake@redhat.com> wrote:
> On 09/11/2013 02:52 PM, Luiz Capitulino wrote:
> > Simplify the text, fix some of the examples.
> >
> > Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> > ---
> > docs/qmp/qmp-spec.txt | 65 ++++++++++++++++++++++-----------------------------
> > 1 file changed, 28 insertions(+), 37 deletions(-)
>
> >
> > diff --git a/docs/qmp/qmp-spec.txt b/docs/qmp/qmp-spec.txt
> > index a277896..22568c6 100644
> > --- a/docs/qmp/qmp-spec.txt
> > +++ b/docs/qmp/qmp-spec.txt
> > @@ -1,21 +1,17 @@
> > - QEMU Monitor Protocol Specification - Version 0.1
> > + QEMU Machine Protocol Specification
>
> Do we want a protocol version number? I guess if we ever add
> capabilities, we can worry about it then.
Yes, but I don't think we want it. This is the sole place where
a version number appears and it's quite meaningless.
>
> Reviewed-by: Eric Blake <eblake@redhat.com>
>
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [Qemu-devel] [PATCH 5/6] QMP: Update qmp-spec.txt
2013-09-13 17:54 ` Luiz Capitulino
@ 2013-09-13 18:00 ` Eric Blake
0 siblings, 0 replies; 12+ messages in thread
From: Eric Blake @ 2013-09-13 18:00 UTC (permalink / raw)
To: Luiz Capitulino; +Cc: qemu-devel, armbru
[-- Attachment #1: Type: text/plain, Size: 1054 bytes --]
On 09/13/2013 11:54 AM, Luiz Capitulino wrote:
> On Wed, 11 Sep 2013 17:27:58 -0600
> Eric Blake <eblake@redhat.com> wrote:
>
>> On 09/11/2013 02:52 PM, Luiz Capitulino wrote:
>>> Simplify the text, fix some of the examples.
>>>
>>> - QEMU Monitor Protocol Specification - Version 0.1
>>> + QEMU Machine Protocol Specification
>>
>> Do we want a protocol version number? I guess if we ever add
>> capabilities, we can worry about it then.
>
> Yes, but I don't think we want it. This is the sole place where
> a version number appears and it's quite meaningless.
Indeed, capabilities are more powerful than version numbers, and since
the initial version already included capabilities, we already have as
much as we need to support any arbitrary future capabilities without
needing to add a version.
>
>>
>> Reviewed-by: Eric Blake <eblake@redhat.com>
Hence this still stands :)
--
Eric Blake eblake redhat com +1-919-301-3266
Libvirt virtualization library http://libvirt.org
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 621 bytes --]
^ permalink raw reply [flat|nested] 12+ messages in thread