Merge remote-tracking branch 'luiz/queue/qmp' into staging (f54c49e2) · Commits · SUMMER2020 / students / proj-2021291

Makefile

+3 −3

Original line number	Diff line number	Diff line
		@@ -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

QMP/README

deleted100644 → 0

+0 −88

Original line number	Diff line number	Diff line
		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

docs/qmp/README

0 → 100644

+87 −0

Original line number	Diff line number	Diff line
		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

QMP/qmp-events.txt→docs/qmp/qmp-events.txt

+17 −17

Original line number	Diff line number	Diff line
		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" } }

QMP/qmp-spec.txt→docs/qmp/qmp-spec.txt

+28 −37

Original line number	Diff line number	Diff line
		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,12 +137,13 @@ 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
		---------------------------
		@@ -175,8 +166,8 @@ 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: