[Qemu-devel] [PATCH v2 for-2.1 0/5] docs: document remaining QMP events

[Qemu-devel] [PATCH v2 for-2.1 0/5] docs: document remaining QMP events

[Eric Blake]

diff from v1:
 split into series [Markus]
 fix SPICE_MIGRATE_COMPLETE typo [Markus]

Eric Blake (5):
  docs: grammar fixes to qmp-events
  docs: split SPICE_* event docs
  docs: document missing SPICE_MIGRATE_COMPLETED event
  docs: document missing POWERDOWN event
  docs: document missing VSERPORT_CHANGE event

 docs/qmp/qmp-events.txt | 80 +++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 74 insertions(+), 6 deletions(-)

-- 
1.9.3

[Qemu-devel] [PATCH v2 for-2.1 1/5] docs: grammar fixes to qmp-events

[Eric Blake]

When converting to qmp events, commits 7cfadb6b and a6330785
fixed some grammar as part of moving text between files.  But
since dfab4892 later restored this file to the state prior to
qmp events, we have to do it again.

* docs/qmp/qmp-events.txt (RESET, SPICE_INITIALIZED): Tweak.

Signed-off-by: Eric Blake <eblake@redhat.com>
---
 docs/qmp/qmp-events.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/qmp/qmp-events.txt b/docs/qmp/qmp-events.txt
index 4a6c2a2..524eadf 100644
--- a/docs/qmp/qmp-events.txt
+++ b/docs/qmp/qmp-events.txt
@@ -285,7 +285,7 @@ Example:
 RESET
 -----

-Emitted when the Virtual Machine is reseted.
+Emitted when the Virtual Machine is reset.

 Data: None.

@@ -366,7 +366,7 @@ SPICE_INITIALIZED
 -----------------

 Emitted after initial handshake and authentication takes place (if any)
-and the SPICE channel is up'n'running
+and the SPICE channel is up and running

 Data:

-- 
1.9.3

[Qemu-devel] [PATCH v2 for-2.1 2/5] docs: split SPICE_* event docs

[Eric Blake]

For consistency with the rest of this file, every event should be
listed in isolation.  Compare how commit 7cfadb6b split
SPICE_CONNECTED and SPICE_DISCONNECTED into separate qmp events.

* docs/qmp/qmp-events.txt (SPICE_CONNECTED, SPICE_DISCONNECTED):
Split.

Signed-off-by: Eric Blake <eblake@redhat.com>
---
 docs/qmp/qmp-events.txt | 31 ++++++++++++++++++++++++++++---
 1 file changed, 28 insertions(+), 3 deletions(-)

diff --git a/docs/qmp/qmp-events.txt b/docs/qmp/qmp-events.txt
index 524eadf..9b7ee7c 100644
--- a/docs/qmp/qmp-events.txt
+++ b/docs/qmp/qmp-events.txt
@@ -337,10 +337,10 @@ Example:
 Note: If the command-line option "-no-shutdown" has been specified, a STOP
 event will eventually follow the SHUTDOWN event.

-SPICE_CONNECTED, SPICE_DISCONNECTED
------------------------------------
+SPICE_CONNECTED
+---------------

-Emitted when a SPICE client connects or disconnects.
+Emitted when a SPICE client connects.

 Data:

@@ -362,6 +362,31 @@ Example:
     "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
 }}

+SPICE_DISCONNECTED
+------------------
+
+Emitted when a SPICE client disconnects.
+
+Data:
+
+- "server": Server information (json-object)
+  - "host": IP address (json-string)
+  - "port": port number (json-string)
+  - "family": address family (json-string, "ipv4" or "ipv6")
+- "client": Client information (json-object)
+  - "host": IP address (json-string)
+  - "port": port number (json-string)
+  - "family": address family (json-string, "ipv4" or "ipv6")
+
+Example:
+
+{ "timestamp": {"seconds": 1290688046, "microseconds": 388707},
+  "event": "SPICE_DISCONNECTED",
+  "data": {
+    "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
+    "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
+}}
+
 SPICE_INITIALIZED
 -----------------

-- 
1.9.3

[Qemu-devel] [PATCH v2 for-2.1 3/5] docs: document missing SPICE_MIGRATE_COMPLETED event

[Eric Blake]

The SPICE_MIGRATE_COMPLETED event was first documented in
7cfadb6b.  But since dfab4892 later restored this flie to the
state prior to qmp events, and we never documented it in the
past, anyone using this file instead of qapi will miss out on
this event.

* docs/qmp/qmp-events.txt (SPICE_MIGRATE_COMPLETED): Add.

Signed-off-by: Eric Blake <eblake@redhat.com>
---
 docs/qmp/qmp-events.txt | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/docs/qmp/qmp-events.txt b/docs/qmp/qmp-events.txt
index 9b7ee7c..22d552f 100644
--- a/docs/qmp/qmp-events.txt
+++ b/docs/qmp/qmp-events.txt
@@ -424,6 +424,19 @@ Example:
                       "channel-id": 0, "tls": true}
 }}

+SPICE_MIGRATE_COMPLETED
+-----------------------
+
+Emitted when SPICE migration has completed
+
+Data: None.
+
+Example:
+
+{ "timestamp": {"seconds": 1290688046, "microseconds": 417172},
+  "event": "SPICE_MIGRATE_COMPLETED" }
+
+
 STOP
 ----

-- 
1.9.3

[Qemu-devel] [PATCH v2 for-2.1 4/5] docs: document missing POWERDOWN event

[Eric Blake]

The POWERDOWN event was first documented in 0aab9ec3.  But since
dfab4892 later restored this file to the state prior to qmp events,
and we never documented it in the past, anyone using this file
instead of qapi will miss out on this event.  Tweak the existing
wording of SHUTDOWN to match 84321831, and make the difference
between the two events apparent.

* docs/qmp/qmp-events.txt (POWERDOWN): Add.
(SHUTDOWN): Tweak.

Signed-off-by: Eric Blake <eblake@redhat.com>
---
 docs/qmp/qmp-events.txt | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/docs/qmp/qmp-events.txt b/docs/qmp/qmp-events.txt
index 22d552f..9d7439e 100644
--- a/docs/qmp/qmp-events.txt
+++ b/docs/qmp/qmp-events.txt
@@ -243,6 +243,19 @@ Data:
   "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
 }

+POWERDOWN
+---------
+
+Emitted when the Virtual Machine is powered down through the power
+control system, such as via ACPI.
+
+Data: None.
+
+Example:
+
+{ "event": "POWERDOWN",
+    "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
+
 QUORUM_FAILURE
 --------------

@@ -325,7 +338,8 @@ Example:
 SHUTDOWN
 --------

-Emitted when the Virtual Machine is powered down.
+Emitted when the Virtual Machine has shut down, indicating that qemu
+is about to exit.

 Data: None.

-- 
1.9.3

[Qemu-devel] [PATCH v2 for-2.1 5/5] docs: document missing VSERPORT_CHANGE event

[Eric Blake]

The VSERPORT_CHANGE event was added in e2ae6159.  The patch for
this event was prepared at a time when this file was gone, even
though it got applied immediately after dfab4892 restored this
file.  Duplicate the documentation into this file, so that
anyone using this file instead of qapi will not miss out on this
new event.

* docs/qmp/qmp-events.txt (VSERPORT_CHANGE): Add.

Signed-off-by: Eric Blake <eblake@redhat.com>
---
 docs/qmp/qmp-events.txt | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/docs/qmp/qmp-events.txt b/docs/qmp/qmp-events.txt
index 9d7439e..d759d19 100644
--- a/docs/qmp/qmp-events.txt
+++ b/docs/qmp/qmp-events.txt
@@ -579,6 +579,22 @@ Example:
                     "host": "127.0.0.1", "sasl_username": "luiz" } },
         "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }

+VSERPORT_CHANGE
+---------------
+
+Emitted when the guest opens or closes a virtio-serial port.
+
+Data:
+
+- "id": device identifier of the virtio-serial port (json-string)
+- "open": true if the guest has opened the virtio-serial port (json-bool)
+
+Example:
+
+{ "event": "VSERPORT_CHANGE",
+    "data": { "id": "channel0", "open": true },
+    "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
+
 WAKEUP
 ------

-- 
1.9.3

Re: [Qemu-devel] [PATCH v2 for-2.1 3/5] docs: document missing SPICE_MIGRATE_COMPLETED event

[Markus Armbruster]

Eric Blake <eblake@redhat.com> writes:

> The SPICE_MIGRATE_COMPLETED event was first documented in
> 7cfadb6b.  But since dfab4892 later restored this flie to the

"this file"

> state prior to qmp events, and we never documented it in the
> past, anyone using this file instead of qapi will miss out on
> this event.
>
> * docs/qmp/qmp-events.txt (SPICE_MIGRATE_COMPLETED): Add.
>
> Signed-off-by: Eric Blake <eblake@redhat.com>

Patch is fine.

Re: [Qemu-devel] [PATCH v2 for-2.1 0/5] docs: document remaining QMP events

[Markus Armbruster]

Eric Blake <eblake@redhat.com> writes:

> diff from v1:
>  split into series [Markus]
>  fix SPICE_MIGRATE_COMPLETE typo [Markus]
>
> Eric Blake (5):
>   docs: grammar fixes to qmp-events
>   docs: split SPICE_* event docs
>   docs: document missing SPICE_MIGRATE_COMPLETED event
>   docs: document missing POWERDOWN event
>   docs: document missing VSERPORT_CHANGE event
>
>  docs/qmp/qmp-events.txt | 80 +++++++++++++++++++++++++++++++++++++++++++++----
>  1 file changed, 74 insertions(+), 6 deletions(-)

Reviewed-by: Markus Armbruster <armbru@redhat.com>

Re: [Qemu-devel] [PATCH v2 for-2.1 4/5] docs: document missing POWERDOWN event

[Wenchao Xia]

于 2014/7/23 20:26, Eric Blake 写道:
> The POWERDOWN event was first documented in 0aab9ec3.  But since
> dfab4892 later restored this file to the state prior to qmp events,
> and we never documented it in the past, anyone using this file
> instead of qapi will miss out on this event.  Tweak the existing
> wording of SHUTDOWN to match 84321831, and make the difference
> between the two events apparent.
> 
> * docs/qmp/qmp-events.txt (POWERDOWN): Add.
> (SHUTDOWN): Tweak.
> 
> Signed-off-by: Eric Blake <eblake@redhat.com>
> ---
>   docs/qmp/qmp-events.txt | 16 +++++++++++++++-
>   1 file changed, 15 insertions(+), 1 deletion(-)
> 
> diff --git a/docs/qmp/qmp-events.txt b/docs/qmp/qmp-events.txt
> index 22d552f..9d7439e 100644
> --- a/docs/qmp/qmp-events.txt
> +++ b/docs/qmp/qmp-events.txt
> @@ -243,6 +243,19 @@ Data:
>     "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
>   }
> 
> +POWERDOWN
> +---------
> +
> +Emitted when the Virtual Machine is powered down through the power
> +control system, such as via ACPI.
> +
> +Data: None.
> +
> +Example:
> +
> +{ "event": "POWERDOWN",
> +    "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
> +
>   QUORUM_FAILURE
>   --------------
> 
> @@ -325,7 +338,8 @@ Example:
>   SHUTDOWN
>   --------
> 
> -Emitted when the Virtual Machine is powered down.
> +Emitted when the Virtual Machine has shut down, indicating that qemu
> +is about to exit.
> 
>   Data: None.
> 
  Nice to have explantion about the difference.

Re: [Qemu-devel] [PATCH v2 for-2.1 0/5] docs: document remaining QMP events

[Wenchao Xia]

Reviewed-by: Wenchao Xia <wenchaoqemu@gmail.com>