[Qemu-devel] [PATCH for-2.1] docs: document remaining QMP events

[Qemu-devel] [PATCH for-2.1] docs: document remaining QMP events

[Eric Blake]

Commit dfab4892 restored this file, but did not address any of the
grammar problems that had been fixed in passing when moving events
out of this file.  There are also a couple events that were
undocumented since introduction, and one that had been added only
in the time that this file was temporarily deleted.

* docs/qmp/qmp-events.txt (POWERDOWN, SPICE_MIGRATE_COMPLETED)
(VSERPORT_CHANGE): Add.
(RESET, SPICE_INITIALIZED): Fix grammar.
(SPICE_CONNECTED, SPICE_DISCONNECTED): Split.

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

diff --git a/docs/qmp/qmp-events.txt b/docs/qmp/qmp-events.txt
index 4a6c2a2..78dd76a 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
 --------------

@@ -285,7 +298,7 @@ Example:
 RESET
 -----

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

 Data: None.

@@ -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.

@@ -337,10 +351,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,11 +376,36 @@ 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
 -----------------

 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:

@@ -399,6 +438,19 @@ Example:
                       "channel-id": 0, "tls": true}
 }}

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

@@ -527,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 for-2.1] docs: document remaining QMP events

[Markus Armbruster]

Eric Blake <eblake@redhat.com> writes:

> Commit dfab4892 restored this file, but did not address any of the
> grammar problems that had been fixed in passing when moving events
> out of this file.  There are also a couple events that were
> undocumented since introduction, and one that had been added only
> in the time that this file was temporarily deleted.
>
> * docs/qmp/qmp-events.txt (POWERDOWN, SPICE_MIGRATE_COMPLETED)
> (VSERPORT_CHANGE): Add.
> (RESET, SPICE_INITIALIZED): Fix grammar.
> (SPICE_CONNECTED, SPICE_DISCONNECTED): Split.

GNU ChangeLog style, unusual in QEMU commit messages.  Not that I mind.

> Signed-off-by: Eric Blake <eblake@redhat.com>
> ---
>  docs/qmp/qmp-events.txt | 80 +++++++++++++++++++++++++++++++++++++++++++++----
>  1 file changed, 74 insertions(+), 6 deletions(-)
>
> diff --git a/docs/qmp/qmp-events.txt b/docs/qmp/qmp-events.txt
> index 4a6c2a2..78dd76a 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
>  --------------
>
> @@ -285,7 +298,7 @@ Example:
>  RESET
>  -----
>
> -Emitted when the Virtual Machine is reseted.
> +Emitted when the Virtual Machine is reset.
>
>  Data: None.
>
> @@ -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.
>
> @@ -337,10 +351,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.

Wording doesn't match qapi-event.json exactly.  I doubt we care.

>
>  Data:
>
> @@ -362,11 +376,36 @@ 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
>  -----------------
>
>  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:
>
> @@ -399,6 +438,19 @@ Example:
>                        "channel-id": 0, "tls": true}
>  }}
>
> +SPICE_INITIALIZED

Another SPICE_INITIALIZED?  Do you mean SPICE_MIGRATE_COMPLETED?

> +-----------------
> +
> +Emitted when SPICE migration has completed
> +
> +Data: None.
> +
> +Example:
> +
> +{ "timestamp": {"seconds": 1290688046, "microseconds": 417172},
> +  "event": "SPICE_MIGRATE_COMPLETED" }
> +
> +
>  STOP
>  ----
>
> @@ -527,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
>  ------

Assuming you do mean SPICE_MIGRATE_COMPLETED: list is complete now.

Would you mind splitting this patch?

* Either one patch per undocumented event (if you want to be nice to
  downstreams cherry-picking events), or one patch for all of them.

* One patch for the rest.  Or if you feel generous, two: one for the
  grammar fixes, one for the spice split.

Re: [Qemu-devel] [PATCH for-2.1] docs: document remaining QMP events

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 1505 bytes --]

On 07/23/2014 01:25 AM, Markus Armbruster wrote:
> Eric Blake <eblake@redhat.com> writes:
> 
>> Commit dfab4892 restored this file, but did not address any of the
>> grammar problems that had been fixed in passing when moving events
>> out of this file.  There are also a couple events that were
>> undocumented since introduction, and one that had been added only
>> in the time that this file was temporarily deleted.

>> -SPICE_CONNECTED, SPICE_DISCONNECTED
>> ------------------------------------
>> +SPICE_CONNECTED
>> +---------------
>>
>> -Emitted when a SPICE client connects or disconnects.
>> +Emitted when a SPICE client connects.
> 
> Wording doesn't match qapi-event.json exactly.  I doubt we care.

Not the only place where they don't match.  And I personally don't care :)


>>
>> +SPICE_INITIALIZED
> 
> Another SPICE_INITIALIZED?  Do you mean SPICE_MIGRATE_COMPLETED?
> 

Copy-and-paste strikes again. Yes, I'll fix that.


> 
> Assuming you do mean SPICE_MIGRATE_COMPLETED: list is complete now.
> 
> Would you mind splitting this patch?
> 
> * Either one patch per undocumented event (if you want to be nice to
>   downstreams cherry-picking events), or one patch for all of them.
> 
> * One patch for the rest.  Or if you feel generous, two: one for the
>   grammar fixes, one for the spice split.

v2 coming up as a full series.

-- 
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: 604 bytes --]