diff --git a/Makefile b/Makefile index 362fe3e66e..aca548dcdf 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 diff --git a/QMP/README b/QMP/README deleted file mode 100644 index c95a08c234..0000000000 --- a/QMP/README +++ /dev/null @@ -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 diff --git a/docs/qmp/README b/docs/qmp/README new file mode 100644 index 0000000000..85c4bc17bf --- /dev/null +++ b/docs/qmp/README @@ -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 diff --git a/QMP/qmp-events.txt b/docs/qmp/qmp-events.txt similarity index 99% rename from QMP/qmp-events.txt rename to docs/qmp/qmp-events.txt index 4b24ec900d..6b87e9786a 100644 --- a/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" } } diff --git a/QMP/qmp-spec.txt b/docs/qmp/qmp-spec.txt similarity index 82% rename from QMP/qmp-spec.txt rename to docs/qmp/qmp-spec.txt index a27789692b..22568c644e 100644 --- a/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: 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 73cb3b6cef..d6b420f18a 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 074f09a063..5c9717594f 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