[for-2.1] docs: document remaining QMP events

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(-)

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.

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.