[Qemu-devel] [PATCH 00/30] Move qapi documentation to schema (part 1/5)

[Qemu-devel] [PATCH 00/30] Move qapi documentation to schema (part 1/5)

[Marc-André Lureau]

Hi,

The QAPI documentation is currently done in two places, the json
schema and a more human-friendly text file. The goal is to avoid
duplication and to generate friendly versions from the schema (pdf,
man etc).  Thus, all documentation should be moved to the schema.

In order to facilitate the review, the documentation move has been
splitted, and is going to sent by chunks of ~30 patches. This way it
should take about 5 series to complete (~150 patches). I suggest that
the qapi maintainers (Markus/Eric) compile the reviewed patches in a
branch and merge upstream in one go (either merging move commits or
not) when the series complete and the documentation is finally
generated to avoid an in-between state.

The wip branch with all the pending patches:
https://github.com/elmarco/qemu/commits/qapi-doc

And a sneak peek of the generated pdf documentation:
https://fedorapeople.org/~elmarco/qemu-qapi.pdf

The series is currently based on Markus qapi-next branch.

Marc-André Lureau (30):
  qmp-commands: move 'add_client' doc to schema
  qmp-commands: move 'query-name' doc to schema
  qmp-commands: move 'query-kvm' doc to schema
  qmp-commands: move 'query-status' doc to schema
  qmp-commands: move 'query-uuid' doc to schema
  qmp-commands: move 'query-chardev' doc to schema
  qmp-commands: move 'query-chardev-backends' doc to schema
  qmp-commands: move 'ringbuf-write' doc to schema
  qmp-commands: move 'ringbuf-read' doc to schema
  qmp-commands: move 'query-events' doc to schema
  qmp-commands: move 'query-migrate' doc to schema
  qmp-commands: move 'migrate-set-capabilities' doc to schema
  qmp-commands: move 'query-migrate-capabilities' doc to schema
  qmp-commands: move 'migrate-set-parameters' doc to schema
  qmp-commands: move 'query-migrate-parameters' doc to schema
  qmp-commands: move 'client_migrate_info' doc to schema
  qmp-commands: move 'migrate-start-postcopy' doc to schema
  qmp-commands: move 'query-mice' doc to schema
  qmp-commands: move 'query-cpus' doc to schema
  qmp-commands: move 'query-iothreads' doc to schema
  qmp-commands: move 'query-vnc' doc to schema
  qmp-commands: move 'query-spice' doc to schema
  qmp-commands: move 'query-balloon' doc to schema
  qmp-commands: move 'query-pci' doc to schema
  qmp-commands: move 'quit' doc to schema
  qmp-commands: move 'stop' doc to schema
  qmp-commands: move 'system_reset' doc to schema
  qmp-commands: move 'system_powerdown' doc to schema
  qmp-commands: move 'cpu-add' doc to schema
  qmp-commands: move 'memsave' doc to schema

 docs/qmp-commands.txt | 1075 -------------------------------------------------
 qapi-schema.json      |  620 +++++++++++++++++++++++++++-
 2 files changed, 601 insertions(+), 1094 deletions(-)

-- 
2.10.0

[Qemu-devel] [PATCH 01/30] qmp-commands: move 'add_client' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 18 ------------------
 qapi-schema.json      |  8 ++++++++
 2 files changed, 8 insertions(+), 18 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index acebeb3..2d65f24 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -1531,24 +1531,6 @@ Example:
                                                   "time": "+60" } }
 <- { "return": {} }
 
-add_client
-----------
-
-Add a graphics client
-
-Arguments:
-
-- "protocol": protocol name (json-string)
-- "fdname": file descriptor name (json-string)
-- "skipauth": whether to skip authentication (json-bool, optional)
-- "tls": whether to perform TLS (json-bool, optional)
-
-Example:
-
--> { "execute": "add_client", "arguments": { "protocol": "vnc",
-                                             "fdname": "myclient" } }
-<- { "return": {} }
-
 qmp_capabilities
 ----------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 55f825d..f0e2d2c 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -65,6 +65,7 @@
 { 'enum': 'LostTickPolicy',
   'data': ['discard', 'delay', 'merge', 'slew' ] }
 
+##
 # @add_client
 #
 # Allow client connections for VNC, Spice and socket based
@@ -84,6 +85,13 @@
 # Returns: nothing on success.
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# -> { "execute": "add_client", "arguments": { "protocol": "vnc",
+#                                              "fdname": "myclient" } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'add_client',
   'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool',
-- 
2.10.0

Re: [Qemu-devel] [PATCH 01/30] qmp-commands: move 'add_client' doc to schema

[Eric Blake]

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

On 09/13/2016 08:01 AM, Marc-André Lureau wrote:
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> ---
>  docs/qmp-commands.txt | 18 ------------------
>  qapi-schema.json      |  8 ++++++++
>  2 files changed, 8 insertions(+), 18 deletions(-)
> 
> diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt

We're trimming off more than we move; but the trimmed stuff is duplicate
once it is all in one file in one location.  I'm liking the overall
theme of the consolidation.  This series will probably conflict with
other pending changes in the tree, so we should probably get it in
sooner rather than later.

Reviewed-by: Eric Blake <eblake@redhat.com>

For the next few patches, I'll probably just do a bulk R-b unless
specific issues pop out while I read through them.

-- 
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 --]

[Qemu-devel] [PATCH 02/30] qmp-commands: move 'query-name' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 14 --------------
 qapi-schema.json      | 12 +++++++++---
 2 files changed, 9 insertions(+), 17 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 2d65f24..4c9ccfb 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -2590,20 +2590,6 @@ Example:
       }
    }
 
-query-name
-----------
-
-Show VM name.
-
-Return a json-object with the following information:
-
-- "name": VM's name (json-string, optional)
-
-Example:
-
--> { "execute": "query-name" }
-<- { "return": { "name": "qemu-name" } }
-
 query-uuid
 ----------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index f0e2d2c..accb28b 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -102,9 +102,9 @@
 #
 # Guest name information.
 #
-# @name: #optional The name of the guest
+# @name: #optional the name of the guest
 #
-# Since 0.14.0
+# Since: 0.14.0
 ##
 { 'struct': 'NameInfo', 'data': {'*name': 'str'} }
 
@@ -115,7 +115,13 @@
 #
 # Returns: @NameInfo of the guest
 #
-# Since 0.14.0
+# Since: 0.14.0
+#
+# Example:
+#
+# -> { "execute": "query-name" }
+# <- { "return": { "name": "qemu-name" } }
+#
 ##
 { 'command': 'query-name', 'returns': 'NameInfo' }
 
-- 
2.10.0

Re: [Qemu-devel] [PATCH 02/30] qmp-commands: move 'query-name' doc to schema

[Eric Blake]

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

On 09/13/2016 08:01 AM, Marc-André Lureau wrote:
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> ---
>  docs/qmp-commands.txt | 14 --------------
>  qapi-schema.json      | 12 +++++++++---
>  2 files changed, 9 insertions(+), 17 deletions(-)
> 

> +++ b/qapi-schema.json
> @@ -102,9 +102,9 @@
>  #
>  # Guest name information.
>  #
> -# @name: #optional The name of the guest
> +# @name: #optional the name of the guest
>  #
> -# Since 0.14.0
> +# Since: 0.14.0

You are doing more than just moving documentation; you are also
normalizing how the existing documentation is presented. Might be worth
mentioning that in various commit messages along the series, or to
rebase things to do the cleanups (uncontroversially safe to do now)
separately from the doc motion (motion is easier to review when there
are no other changes thrown in the mix, and we already know that we are
at risk of merge conflicts causing either you or other developers some
rebase churn, where we have to be careful we don't lose contents).

Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
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 --]

[Qemu-devel] [PATCH 03/30] qmp-commands: move 'query-kvm' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 15 ---------------
 qapi-schema.json      | 10 ++++++++--
 2 files changed, 8 insertions(+), 17 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 4c9ccfb..2e78d60 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -2388,21 +2388,6 @@ Example:
 
 Note: This example has been shortened as the real response is too long.
 
-query-kvm
----------
-
-Show KVM information.
-
-Return a json-object with the following information:
-
-- "enabled": true if KVM support is enabled, false otherwise (json-bool)
-- "present": true if QEMU has KVM support, false otherwise (json-bool)
-
-Example:
-
--> { "execute": "query-kvm" }
-<- { "return": { "enabled": true, "present": true } }
-
 query-status
 ------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index accb28b..b013b39 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -128,7 +128,7 @@
 ##
 # @KvmInfo:
 #
-# Information about support for KVM acceleration
+# Information about support for KVM acceleration.
 #
 # @enabled: true if KVM acceleration is active
 #
@@ -141,11 +141,17 @@
 ##
 # @query-kvm:
 #
-# Returns information about KVM acceleration
+# Returns information about KVM acceleration.
 #
 # Returns: @KvmInfo
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# -> { "execute": "query-kvm" }
+# <- { "return": { "enabled": true, "present": true } }
+#
 ##
 { 'command': 'query-kvm', 'returns': 'KvmInfo' }
 
-- 
2.10.0

[Qemu-devel] [PATCH 04/30] qmp-commands: move 'query-status' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 31 -------------------------------
 qapi-schema.json      | 10 ++++++++--
 2 files changed, 8 insertions(+), 33 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 2e78d60..6f6db87 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -2388,37 +2388,6 @@ Example:
 
 Note: This example has been shortened as the real response is too long.
 
-query-status
-------------
-
-Return a json-object with the following information:
-
-- "running": true if the VM is running, or false if it is paused (json-bool)
-- "singlestep": true if the VM is in single step mode,
-                false otherwise (json-bool)
-- "status": one of the following values (json-string)
-    "debug" - QEMU is running on a debugger
-    "inmigrate" - guest is paused waiting for an incoming migration
-    "internal-error" - An internal error that prevents further guest
-    execution has occurred
-    "io-error" - the last IOP has failed and the device is configured
-    to pause on I/O errors
-    "paused" - guest has been paused via the 'stop' command
-    "postmigrate" - guest is paused following a successful 'migrate'
-    "prelaunch" - QEMU was started with -S and guest has not started
-    "finish-migrate" - guest is paused to finish the migration process
-    "restore-vm" - guest is paused to restore VM state
-    "running" - guest is actively running
-    "save-vm" - guest is paused to save the VM state
-    "shutdown" - guest is shut down (and -no-shutdown is in use)
-    "watchdog" - the watchdog action is configured to pause and
-     has been triggered
-
-Example:
-
--> { "execute": "query-status" }
-<- { "return": { "running": true, "singlestep": false, "status": "running" } }
-
 query-mice
 ----------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index b013b39..008a7f9 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -205,7 +205,7 @@
 ##
 # @StatusInfo:
 #
-# Information about VCPU run state
+# Information about VCPU run state.
 #
 # @running: true if all VCPUs are runnable, false if not runnable
 #
@@ -223,11 +223,17 @@
 ##
 # @query-status:
 #
-# Query the run status of all VCPUs
+# Query the run status of all VCPUs.
 #
 # Returns: @StatusInfo reflecting all VCPUs
 #
 # Since:  0.14.0
+#
+# Example:
+#
+# -> { "execute": "query-status" }
+# <- { "return": { "running": true, "singlestep": false, "status": "running" } }
+#
 ##
 { 'command': 'query-status', 'returns': 'StatusInfo' }
 
-- 
2.10.0

[Qemu-devel] [PATCH 05/30] qmp-commands: move 'query-uuid' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 14 --------------
 qapi-schema.json      |  8 +++++++-
 2 files changed, 7 insertions(+), 15 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 6f6db87..6814bd5 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -2544,20 +2544,6 @@ Example:
       }
    }
 
-query-uuid
-----------
-
-Show VM UUID.
-
-Return a json-object with the following information:
-
-- "UUID": Universally Unique Identifier (json-string)
-
-Example:
-
--> { "execute": "query-uuid" }
-<- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
-
 query-command-line-options
 --------------------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 008a7f9..60007f1 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -240,7 +240,7 @@
 ##
 # @UuidInfo:
 #
-# Guest UUID information.
+# Guest UUID information (Universally Unique Identifier).
 #
 # @UUID: the UUID of the guest
 #
@@ -258,6 +258,12 @@
 # Returns: The @UuidInfo for the guest
 #
 # Since 0.14.0
+#
+# Example:
+#
+# -> { "execute": "query-uuid" }
+# <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
+#
 ##
 { 'command': 'query-uuid', 'returns': 'UuidInfo' }
 
-- 
2.10.0

[Qemu-devel] [PATCH 06/30] qmp-commands: move 'query-chardev' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 36 ------------------------------------
 qapi-schema.json      | 24 ++++++++++++++++++++++++
 2 files changed, 24 insertions(+), 36 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 6814bd5..f3da6f2 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -1673,42 +1673,6 @@ named schema entities.  Entities are commands, events and various
 types.  See docs/qapi-code-gen.txt for information on their structure
 and intended use.
 
-query-chardev
--------------
-
-Each device is represented by a json-object. The returned value is a json-array
-of all devices.
-
-Each json-object contain the following:
-
-- "label": device's label (json-string)
-- "filename": device's file (json-string)
-- "frontend-open": open/closed state of the frontend device attached to this
-                   backend (json-bool)
-
-Example:
-
--> { "execute": "query-chardev" }
-<- {
-      "return": [
-         {
-            "label": "charchannel0",
-            "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server",
-            "frontend-open": false
-         },
-         {
-            "label": "charmonitor",
-            "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server",
-            "frontend-open": true
-         },
-         {
-            "label": "charserial0",
-            "filename": "pty:/dev/pts/2",
-            "frontend-open": true
-         }
-      ]
-   }
-
 query-chardev-backends
 -------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 60007f1..f015e61 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -297,6 +297,30 @@
 # Returns: a list of @ChardevInfo
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# -> { "execute": "query-chardev" }
+# <- {
+#       "return": [
+#          {
+#             "label": "charchannel0",
+#             "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server",
+#             "frontend-open": false
+#          },
+#          {
+#             "label": "charmonitor",
+#             "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server",
+#             "frontend-open": true
+#          },
+#          {
+#             "label": "charserial0",
+#             "filename": "pty:/dev/pts/2",
+#             "frontend-open": true
+#          }
+#       ]
+#    }
+#
 ##
 { 'command': 'query-chardev', 'returns': ['ChardevInfo'] }
 
-- 
2.10.0

[Qemu-devel] [PATCH 07/30] qmp-commands: move 'query-chardev-backends' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 32 --------------------------------
 qapi-schema.json      | 25 +++++++++++++++++++++++--
 2 files changed, 23 insertions(+), 34 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index f3da6f2..0dae7fa 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -1673,38 +1673,6 @@ named schema entities.  Entities are commands, events and various
 types.  See docs/qapi-code-gen.txt for information on their structure
 and intended use.
 
-query-chardev-backends
--------------
-
-List available character device backends.
-
-Each backend is represented by a json-object, the returned value is a json-array
-of all backends.
-
-Each json-object contains:
-
-- "name": backend name (json-string)
-
-Example:
-
--> { "execute": "query-chardev-backends" }
-<- {
-      "return":[
-         {
-            "name":"udp"
-         },
-         {
-            "name":"tcp"
-         },
-         {
-            "name":"unix"
-         },
-         {
-            "name":"spiceport"
-         }
-      ]
-   }
-
 query-block
 -----------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index f015e61..ae96abe 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -327,7 +327,7 @@
 ##
 # @ChardevBackendInfo:
 #
-# Information about a character device backend
+# Information about a character device backend.
 #
 # @name: The backend name
 #
@@ -338,11 +338,32 @@
 ##
 # @query-chardev-backends:
 #
-# Returns information about character device backends.
+# Returns information about available character device backends.
 #
 # Returns: a list of @ChardevBackendInfo
 #
 # Since: 2.0
+#
+# Example:
+#
+# -> { "execute": "query-chardev-backends" }
+# <- {
+#       "return":[
+#          {
+#             "name":"udp"
+#          },
+#          {
+#             "name":"tcp"
+#          },
+#          {
+#             "name":"unix"
+#          },
+#          {
+#             "name":"spiceport"
+#          }
+#       ]
+#    }
+#
 ##
 { 'command': 'query-chardev-backends', 'returns': ['ChardevBackendInfo'] }
 
-- 
2.10.0

[Qemu-devel] [PATCH 08/30] qmp-commands: move 'ringbuf-write' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 20 --------------------
 qapi-schema.json      |  9 +++++++++
 2 files changed, 9 insertions(+), 20 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 0dae7fa..44a7632 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -332,26 +332,6 @@ Example:
 
 Note: inject-nmi fails when the guest doesn't support injecting.
 
-ringbuf-write
--------------
-
-Write to a ring buffer character device.
-
-Arguments:
-
-- "device": ring buffer character device name (json-string)
-- "data": data to write (json-string)
-- "format": data format (json-string, optional)
-          - Possible values: "utf8" (default), "base64"
-
-Example:
-
--> { "execute": "ringbuf-write",
-                "arguments": { "device": "foo",
-                               "data": "abcdefgh",
-                               "format": "utf8" } }
-<- { "return": {} }
-
 ringbuf-read
 -------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index ae96abe..c23c0cb 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -400,6 +400,15 @@
 # Returns: Nothing on success
 #
 # Since: 1.4
+#
+# Example:
+#
+# -> { "execute": "ringbuf-write",
+#                 "arguments": { "device": "foo",
+#                                "data": "abcdefgh",
+#                                "format": "utf8" } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'ringbuf-write',
   'data': {'device': 'str', 'data': 'str',
-- 
2.10.0

[Qemu-devel] [PATCH 09/30] qmp-commands: move 'ringbuf-read' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 27 ---------------------------
 qapi-schema.json      |  9 +++++++++
 2 files changed, 9 insertions(+), 27 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 44a7632..4d1907a 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -332,33 +332,6 @@ Example:
 
 Note: inject-nmi fails when the guest doesn't support injecting.
 
-ringbuf-read
--------------
-
-Read from a ring buffer character device.
-
-Arguments:
-
-- "device": ring buffer character device name (json-string)
-- "size": how many bytes to read at most (json-int)
-          - Number of data bytes, not number of characters in encoded data
-- "format": data format (json-string, optional)
-          - Possible values: "utf8" (default), "base64"
-          - Naturally, format "utf8" works only when the ring buffer
-            contains valid UTF-8 text.  Invalid UTF-8 sequences get
-            replaced.  Bug: replacement doesn't work.  Bug: can screw
-            up on encountering NUL characters, after the ring buffer
-            lost data, and when reading stops because the size limit
-            is reached.
-
-Example:
-
--> { "execute": "ringbuf-read",
-                "arguments": { "device": "foo",
-                               "size": 1000,
-                               "format": "utf8" } }
-<- {"return": "abcdefgh"}
-
 xen-save-devices-state
 -------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index c23c0cb..45aa6b8 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -436,6 +436,15 @@
 # Returns: data read from the device
 #
 # Since: 1.4
+#
+# Example:
+#
+# -> { "execute": "ringbuf-read",
+#                 "arguments": { "device": "foo",
+#                                "size": 1000,
+#                                "format": "utf8" } }
+# <- {"return": "abcdefgh"}
+#
 ##
 { 'command': 'ringbuf-read',
   'data': {'device': 'str', 'size': 'int', '*format': 'DataFormat'},
-- 
2.10.0

[Qemu-devel] [PATCH 10/30] qmp-commands: move 'query-events' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 28 ----------------------------
 qapi-schema.json      | 19 ++++++++++++++++++-
 2 files changed, 18 insertions(+), 29 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 4d1907a..1daa4ed 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -1590,34 +1590,6 @@ Example:
 
 Note: This example has been shortened as the real response is too long.
 
-query-events
---------------
-
-List QMP available events.
-
-Each event is represented by a json-object, the returned value is a json-array
-of all events.
-
-Each json-object contains:
-
-- "name": event's name (json-string)
-
-Example:
-
--> { "execute": "query-events" }
-<- {
-      "return":[
-         {
-            "name":"SHUTDOWN"
-         },
-         {
-            "name":"RESET"
-         }
-      ]
-   }
-
-Note: This example has been shortened as the real response is too long.
-
 query-qmp-schema
 ----------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 45aa6b8..15354b0 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -464,11 +464,28 @@
 ##
 # @query-events:
 #
-# Return a list of supported QMP events by this server
+# Return a list of supported QMP events by this server.
 #
 # Returns: A list of @EventInfo for all supported events
 #
 # Since: 1.2.0
+#
+# Example:
+#
+# -> { "execute": "query-events" }
+# <- {
+#       "return":[
+#          {
+#             "name":"SHUTDOWN"
+#          },
+#          {
+#             "name":"RESET"
+#          }
+#       ]
+#    }
+#
+# Note: This example has been shortened as the real response is too long.
+#
 ##
 { 'command': 'query-events', 'returns': ['EventInfo'] }
 
-- 
2.10.0

Re: [Qemu-devel] [PATCH 10/30] qmp-commands: move 'query-events' doc to schema

[Eric Blake]

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

On 09/13/2016 08:01 AM, Marc-André Lureau wrote:
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> ---
>  docs/qmp-commands.txt | 28 ----------------------------
>  qapi-schema.json      | 19 ++++++++++++++++++-
>  2 files changed, 18 insertions(+), 29 deletions(-)

Through patch 10,
Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
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 --]

[Qemu-devel] [PATCH 11/30] qmp-commands: move 'query-migrate' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 169 --------------------------------------------------
 qapi-schema.json      | 115 +++++++++++++++++++++++++++++++++-
 2 files changed, 114 insertions(+), 170 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 1daa4ed..e9a38d6 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -2441,175 +2441,6 @@ Example:
      ]
    }
 
-query-migrate
--------------
-
-Migration status.
-
-Return a json-object. If migration is active there will be another json-object
-with RAM migration status and if block migration is active another one with
-block migration status.
-
-The main json-object contains the following:
-
-- "status": migration status (json-string)
-     - Possible values: "setup", "active", "completed", "failed", "cancelled"
-- "total-time": total amount of ms since migration started.  If
-                migration has ended, it returns the total migration
-                time (json-int)
-- "setup-time" amount of setup time in milliseconds _before_ the
-               iterations begin but _after_ the QMP command is issued.
-               This is designed to provide an accounting of any activities
-               (such as RDMA pinning) which may be expensive, but do not
-               actually occur during the iterative migration rounds
-               themselves. (json-int)
-- "downtime": only present when migration has finished correctly
-              total amount in ms for downtime that happened (json-int)
-- "expected-downtime": only present while migration is active
-                total amount in ms for downtime that was calculated on
-                the last bitmap round (json-int)
-- "ram": only present if "status" is "active", it is a json-object with the
-  following RAM information:
-         - "transferred": amount transferred in bytes (json-int)
-         - "remaining": amount remaining to transfer in bytes (json-int)
-         - "total": total amount of memory in bytes (json-int)
-         - "duplicate": number of pages filled entirely with the same
-            byte (json-int)
-            These are sent over the wire much more efficiently.
-         - "skipped": number of skipped zero pages (json-int)
-         - "normal" : number of whole pages transferred.  I.e. they
-            were not sent as duplicate or xbzrle pages (json-int)
-         - "normal-bytes" : number of bytes transferred in whole
-            pages. This is just normal pages times size of one page,
-            but this way upper levels don't need to care about page
-            size (json-int)
-         - "dirty-sync-count": times that dirty ram was synchronized (json-int)
-- "disk": only present if "status" is "active" and it is a block migration,
-  it is a json-object with the following disk information:
-         - "transferred": amount transferred in bytes (json-int)
-         - "remaining": amount remaining to transfer in bytes json-int)
-         - "total": total disk size in bytes (json-int)
-- "xbzrle-cache": only present if XBZRLE is active.
-  It is a json-object with the following XBZRLE information:
-         - "cache-size": XBZRLE cache size in bytes
-         - "bytes": number of bytes transferred for XBZRLE compressed pages
-         - "pages": number of XBZRLE compressed pages
-         - "cache-miss": number of XBRZRLE page cache misses
-         - "cache-miss-rate": rate of XBRZRLE page cache misses
-         - "overflow": number of times XBZRLE overflows.  This means
-           that the XBZRLE encoding was bigger than just sent the
-           whole page, and then we sent the whole page instead (as as
-           normal page).
-
-Examples:
-
-1. Before the first migration
-
--> { "execute": "query-migrate" }
-<- { "return": {} }
-
-2. Migration is done and has succeeded
-
--> { "execute": "query-migrate" }
-<- { "return": {
-        "status": "completed",
-        "ram":{
-          "transferred":123,
-          "remaining":123,
-          "total":246,
-          "total-time":12345,
-          "setup-time":12345,
-          "downtime":12345,
-          "duplicate":123,
-          "normal":123,
-          "normal-bytes":123456,
-          "dirty-sync-count":15
-        }
-     }
-   }
-
-3. Migration is done and has failed
-
--> { "execute": "query-migrate" }
-<- { "return": { "status": "failed" } }
-
-4. Migration is being performed and is not a block migration:
-
--> { "execute": "query-migrate" }
-<- {
-      "return":{
-         "status":"active",
-         "ram":{
-            "transferred":123,
-            "remaining":123,
-            "total":246,
-            "total-time":12345,
-            "setup-time":12345,
-            "expected-downtime":12345,
-            "duplicate":123,
-            "normal":123,
-            "normal-bytes":123456,
-            "dirty-sync-count":15
-         }
-      }
-   }
-
-5. Migration is being performed and is a block migration:
-
--> { "execute": "query-migrate" }
-<- {
-      "return":{
-         "status":"active",
-         "ram":{
-            "total":1057024,
-            "remaining":1053304,
-            "transferred":3720,
-            "total-time":12345,
-            "setup-time":12345,
-            "expected-downtime":12345,
-            "duplicate":123,
-            "normal":123,
-            "normal-bytes":123456,
-            "dirty-sync-count":15
-         },
-         "disk":{
-            "total":20971520,
-            "remaining":20880384,
-            "transferred":91136
-         }
-      }
-   }
-
-6. Migration is being performed and XBZRLE is active:
-
--> { "execute": "query-migrate" }
-<- {
-      "return":{
-         "status":"active",
-         "capabilities" : [ { "capability": "xbzrle", "state" : true } ],
-         "ram":{
-            "total":1057024,
-            "remaining":1053304,
-            "transferred":3720,
-            "total-time":12345,
-            "setup-time":12345,
-            "expected-downtime":12345,
-            "duplicate":10,
-            "normal":3333,
-            "normal-bytes":3412992,
-            "dirty-sync-count":15
-         },
-         "xbzrle-cache":{
-            "cache-size":67108864,
-            "bytes":20971520,
-            "pages":2444343,
-            "cache-miss":2244,
-            "cache-miss-rate":0.123,
-            "overflow":34434
-         }
-      }
-   }
-
 migrate-set-capabilities
 ------------------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 15354b0..aaff9a9 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -641,11 +641,124 @@
 ##
 # @query-migrate
 #
-# Returns information about current migration process.
+# Returns information about current migration process.  If migration
+# is active there will be another json-object with RAM migration
+# status and if block migration is active another one with block
+# migration status.
 #
 # Returns: @MigrationInfo
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# 1. Before the first migration
+#
+# -> { "execute": "query-migrate" }
+# <- { "return": {} }
+#
+# 2. Migration is done and has succeeded
+#
+# -> { "execute": "query-migrate" }
+# <- { "return": {
+#         "status": "completed",
+#         "ram":{
+#           "transferred":123,
+#           "remaining":123,
+#           "total":246,
+#           "total-time":12345,
+#           "setup-time":12345,
+#           "downtime":12345,
+#           "duplicate":123,
+#           "normal":123,
+#           "normal-bytes":123456,
+#           "dirty-sync-count":15
+#         }
+#      }
+#    }
+#
+# 3. Migration is done and has failed
+#
+# -> { "execute": "query-migrate" }
+# <- { "return": { "status": "failed" } }
+#
+# 4. Migration is being performed and is not a block migration:
+#
+# -> { "execute": "query-migrate" }
+# <- {
+#       "return":{
+#          "status":"active",
+#          "ram":{
+#             "transferred":123,
+#             "remaining":123,
+#             "total":246,
+#             "total-time":12345,
+#             "setup-time":12345,
+#             "expected-downtime":12345,
+#             "duplicate":123,
+#             "normal":123,
+#             "normal-bytes":123456,
+#             "dirty-sync-count":15
+#          }
+#       }
+#    }
+#
+# 5. Migration is being performed and is a block migration:
+#
+# -> { "execute": "query-migrate" }
+# <- {
+#       "return":{
+#          "status":"active",
+#          "ram":{
+#             "total":1057024,
+#             "remaining":1053304,
+#             "transferred":3720,
+#             "total-time":12345,
+#             "setup-time":12345,
+#             "expected-downtime":12345,
+#             "duplicate":123,
+#             "normal":123,
+#             "normal-bytes":123456,
+#             "dirty-sync-count":15
+#          },
+#          "disk":{
+#             "total":20971520,
+#             "remaining":20880384,
+#             "transferred":91136
+#          }
+#       }
+#    }
+#
+# 6. Migration is being performed and XBZRLE is active:
+#
+# -> { "execute": "query-migrate" }
+# <- {
+#       "return":{
+#          "status":"active",
+#          "capabilities" : [ { "capability": "xbzrle", "state" : true } ],
+#          "ram":{
+#             "total":1057024,
+#             "remaining":1053304,
+#             "transferred":3720,
+#             "total-time":12345,
+#             "setup-time":12345,
+#             "expected-downtime":12345,
+#             "duplicate":10,
+#             "normal":3333,
+#             "normal-bytes":3412992,
+#             "dirty-sync-count":15
+#          },
+#          "xbzrle-cache":{
+#             "cache-size":67108864,
+#             "bytes":20971520,
+#             "pages":2444343,
+#             "cache-miss":2244,
+#             "cache-miss-rate":0.123,
+#             "overflow":34434
+#          }
+#       }
+#    }
+#
 ##
 { 'command': 'query-migrate', 'returns': 'MigrationInfo' }
 
-- 
2.10.0

[Qemu-devel] [PATCH 12/30] qmp-commands: move 'migrate-set-capabilities' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 20 --------------------
 qapi-schema.json      |  6 ++++++
 2 files changed, 6 insertions(+), 20 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index e9a38d6..ca57cdb 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -2441,26 +2441,6 @@ Example:
      ]
    }
 
-migrate-set-capabilities
-------------------------
-
-Enable/Disable migration capabilities
-
-- "xbzrle": XBZRLE support
-- "rdma-pin-all": pin all pages when using RDMA during migration
-- "auto-converge": throttle down guest to help convergence of migration
-- "zero-blocks": compress zero blocks during block migration
-- "compress": use multiple compression threads to accelerate live migration
-- "events": generate events for each migration state change
-- "postcopy-ram": postcopy mode for live migration
-
-Arguments:
-
-Example:
-
--> { "execute": "migrate-set-capabilities" , "arguments":
-     { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
-
 query-migrate-capabilities
 --------------------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index aaff9a9..82b2100 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -827,6 +827,12 @@
 # @capabilities: json array of capability modifications to make
 #
 # Since: 1.2
+#
+# Example:
+#
+# -> { "execute": "migrate-set-capabilities" , "arguments":
+#      { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
+#
 ##
 { 'command': 'migrate-set-capabilities',
   'data': { 'capabilities': ['MigrationCapabilityStatus'] } }
-- 
2.10.0

[Qemu-devel] [PATCH 13/30] qmp-commands: move 'query-migrate-capabilities' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 29 -----------------------------
 qapi-schema.json      | 14 ++++++++++++++
 2 files changed, 14 insertions(+), 29 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index ca57cdb..c7a0712 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -2441,35 +2441,6 @@ Example:
      ]
    }
 
-query-migrate-capabilities
---------------------------
-
-Query current migration capabilities
-
-- "capabilities": migration capabilities state
-         - "xbzrle" : XBZRLE state (json-bool)
-         - "rdma-pin-all" : RDMA Pin Page state (json-bool)
-         - "auto-converge" : Auto Converge state (json-bool)
-         - "zero-blocks" : Zero Blocks state (json-bool)
-         - "compress": Multiple compression threads state (json-bool)
-         - "events": Migration state change event state (json-bool)
-         - "postcopy-ram": postcopy ram state (json-bool)
-
-Arguments:
-
-Example:
-
--> { "execute": "query-migrate-capabilities" }
-<- {"return": [
-     {"state": false, "capability": "xbzrle"},
-     {"state": false, "capability": "rdma-pin-all"},
-     {"state": false, "capability": "auto-converge"},
-     {"state": false, "capability": "zero-blocks"},
-     {"state": false, "capability": "compress"},
-     {"state": true, "capability": "events"},
-     {"state": false, "capability": "postcopy-ram"}
-   ]}
-
 migrate-set-parameters
 ----------------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 82b2100..1599d8b 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -845,6 +845,20 @@
 # Returns: @MigrationCapabilitiesStatus
 #
 # Since: 1.2
+#
+# Example:
+#
+# -> { "execute": "query-migrate-capabilities" }
+# <- { "return": [
+#       {"state": false, "capability": "xbzrle"},
+#       {"state": false, "capability": "rdma-pin-all"},
+#       {"state": false, "capability": "auto-converge"},
+#       {"state": false, "capability": "zero-blocks"},
+#       {"state": false, "capability": "compress"},
+#       {"state": true, "capability": "events"},
+#       {"state": false, "capability": "postcopy-ram"}
+#    ]}
+#
 ##
 { 'command': 'query-migrate-capabilities', 'returns':   ['MigrationCapabilityStatus']}
 
-- 
2.10.0

[Qemu-devel] [PATCH 14/30] qmp-commands: move 'migrate-set-parameters' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 20 --------------------
 qapi-schema.json      |  6 ++++++
 2 files changed, 6 insertions(+), 20 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index c7a0712..fc6f054 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -2441,26 +2441,6 @@ Example:
      ]
    }
 
-migrate-set-parameters
-----------------------
-
-Set migration parameters
-
-- "compress-level": set compression level during migration (json-int)
-- "compress-threads": set compression thread count for migration (json-int)
-- "decompress-threads": set decompression thread count for migration (json-int)
-- "cpu-throttle-initial": set initial percentage of time guest cpus are
-                          throttled for auto-converge (json-int)
-- "cpu-throttle-increment": set throttle increasing percentage for
-                            auto-converge (json-int)
-
-Arguments:
-
-Example:
-
--> { "execute": "migrate-set-parameters" , "arguments":
-      { "compress-level": 1 } }
-
 query-migrate-parameters
 ------------------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 1599d8b..df83457 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -945,6 +945,12 @@
 #                certificate identity can be validated. (Since 2.7)
 #
 # Since: 2.4
+#
+# Example:
+#
+# -> { "execute": "migrate-set-parameters" ,
+#      "arguments": { "compress-level": 1 } }
+#
 ##
 { 'command': 'migrate-set-parameters',
   'data': { '*compress-level': 'int',
-- 
2.10.0

[Qemu-devel] [PATCH 15/30] qmp-commands: move 'query-migrate-parameters' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 29 -----------------------------
 qapi-schema.json      | 13 +++++++++++++
 2 files changed, 13 insertions(+), 29 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index fc6f054..d96dd27 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -2441,35 +2441,6 @@ Example:
      ]
    }
 
-query-migrate-parameters
-------------------------
-
-Query current migration parameters
-
-- "parameters": migration parameters value
-         - "compress-level" : compression level value (json-int)
-         - "compress-threads" : compression thread count value (json-int)
-         - "decompress-threads" : decompression thread count value (json-int)
-         - "cpu-throttle-initial" : initial percentage of time guest cpus are
-                                    throttled (json-int)
-         - "cpu-throttle-increment" : throttle increasing percentage for
-                                      auto-converge (json-int)
-
-Arguments:
-
-Example:
-
--> { "execute": "query-migrate-parameters" }
-<- {
-      "return": {
-         "decompress-threads": 2,
-         "cpu-throttle-increment": 10,
-         "compress-threads": 8,
-         "compress-level": 1,
-         "cpu-throttle-initial": 20
-      }
-   }
-
 query-balloon
 -------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index df83457..e57f223 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -1011,6 +1011,19 @@
 # Returns: @MigrationParameters
 #
 # Since: 2.4
+#
+# Example:
+#
+# -> { "execute": "query-migrate-parameters" }
+# <- { "return": {
+#          "decompress-threads": 2,
+#          "cpu-throttle-increment": 10,
+#          "compress-threads": 8,
+#          "compress-level": 1,
+#          "cpu-throttle-initial": 20
+#       }
+#    }
+#
 ##
 { 'command': 'query-migrate-parameters',
   'returns': 'MigrationParameters' }
-- 
2.10.0

Re: [Qemu-devel] [PATCH 15/30] qmp-commands: move 'query-migrate-parameters' doc to schema

[Eric Blake]

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

On 09/13/2016 08:01 AM, Marc-André Lureau wrote:
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> ---
>  docs/qmp-commands.txt | 29 -----------------------------
>  qapi-schema.json      | 13 +++++++++++++
>  2 files changed, 13 insertions(+), 29 deletions(-)
> 

> +++ b/qapi-schema.json
> @@ -1011,6 +1011,19 @@
>  # Returns: @MigrationParameters
>  #
>  # Since: 2.4
> +#
> +# Example:
> +#
> +# -> { "execute": "query-migrate-parameters" }
> +# <- { "return": {
> +#          "decompress-threads": 2,
> +#          "cpu-throttle-increment": 10,
> +#          "compress-threads": 8,
> +#          "compress-level": 1,
> +#          "cpu-throttle-initial": 20
> +#       }
> +#    }
> +#
>  ##
>  { 'command': 'query-migrate-parameters',
>    'returns': 'MigrationParameters' }

The example lacks 'cpu-throttle-increment', 'tls-creds', and
'tls-hostname'; do we want to take this opportunity to touch it up?
Meanwhile, I have a series that touches this code, and will obviously
create a merge conflict for whoever gets in second:

https://lists.gnu.org/archive/html/qemu-devel/2016-09/msg01946.html

At any rate, 11-15 are
Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
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 --]

Re: [Qemu-devel] [PATCH 15/30] qmp-commands: move 'query-migrate-parameters' doc to schema

[Marc-André Lureau]

Hi

----- Original Message -----
> On 09/13/2016 08:01 AM, Marc-André Lureau wrote:
> > Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> > ---
> >  docs/qmp-commands.txt | 29 -----------------------------
> >  qapi-schema.json      | 13 +++++++++++++
> >  2 files changed, 13 insertions(+), 29 deletions(-)
> > 
> 
> > +++ b/qapi-schema.json
> > @@ -1011,6 +1011,19 @@
> >  # Returns: @MigrationParameters
> >  #
> >  # Since: 2.4
> > +#
> > +# Example:
> > +#
> > +# -> { "execute": "query-migrate-parameters" }
> > +# <- { "return": {
> > +#          "decompress-threads": 2,
> > +#          "cpu-throttle-increment": 10,
> > +#          "compress-threads": 8,
> > +#          "compress-level": 1,
> > +#          "cpu-throttle-initial": 20
> > +#       }
> > +#    }
> > +#
> >  ##
> >  { 'command': 'query-migrate-parameters',
> >    'returns': 'MigrationParameters' }
> 
> The example lacks 'cpu-throttle-increment', 'tls-creds', and
> 'tls-hostname'; do we want to take this opportunity to touch it up?

I suggest to put a [...] in the returned example, as this example could grow again, and there isn't much to learn from that query.
 
> Meanwhile, I have a series that touches this code, and will obviously
> create a merge conflict for whoever gets in second:
> https://lists.gnu.org/archive/html/qemu-devel/2016-09/msg01946.html

Yes, the more we wait to review the series, the more conflicts we will get. There is still over 100 patches to go, I'll send the next 30.

> At any rate, 11-15 are
> Reviewed-by: Eric Blake <eblake@redhat.com>

thanks

Re: [Qemu-devel] [PATCH 15/30] qmp-commands: move 'query-migrate-parameters' doc to schema

[Markus Armbruster]

Marc-André Lureau <mlureau@redhat.com> writes:

> Hi
>
> ----- Original Message -----
>> On 09/13/2016 08:01 AM, Marc-André Lureau wrote:
>> > Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
>> > ---
>> >  docs/qmp-commands.txt | 29 -----------------------------
>> >  qapi-schema.json      | 13 +++++++++++++
>> >  2 files changed, 13 insertions(+), 29 deletions(-)
>> > 
>> 
>> > +++ b/qapi-schema.json
>> > @@ -1011,6 +1011,19 @@
>> >  # Returns: @MigrationParameters
>> >  #
>> >  # Since: 2.4
>> > +#
>> > +# Example:
>> > +#
>> > +# -> { "execute": "query-migrate-parameters" }
>> > +# <- { "return": {
>> > +#          "decompress-threads": 2,
>> > +#          "cpu-throttle-increment": 10,
>> > +#          "compress-threads": 8,
>> > +#          "compress-level": 1,
>> > +#          "cpu-throttle-initial": 20
>> > +#       }
>> > +#    }
>> > +#
>> >  ##
>> >  { 'command': 'query-migrate-parameters',
>> >    'returns': 'MigrationParameters' }
>> 
>> The example lacks 'cpu-throttle-increment', 'tls-creds', and
>> 'tls-hostname'; do we want to take this opportunity to touch it up?
>
> I suggest to put a [...] in the returned example, as this example could grow again, and there isn't much to learn from that query.
>  
>> Meanwhile, I have a series that touches this code, and will obviously
>> create a merge conflict for whoever gets in second:
>> https://lists.gnu.org/archive/html/qemu-devel/2016-09/msg01946.html
>
> Yes, the more we wait to review the series, the more conflicts we will get. There is still over 100 patches to go, I'll send the next 30.

We suggested restructuring the series, and you liked the idea with the
alternative step (3b), not (3a).  Would it make sense to repost the
beginning of the multi-part monster in that form before moving on to the
next part?

[...]

Re: [Qemu-devel] [PATCH 15/30] qmp-commands: move 'query-migrate-parameters' doc to schema

[Marc-André Lureau]

Hi

----- Original Message -----
> Marc-André Lureau <mlureau@redhat.com> writes:
> 
> > Hi
> >
> > ----- Original Message -----
> >> On 09/13/2016 08:01 AM, Marc-André Lureau wrote:
> >> > Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> >> > ---
> >> >  docs/qmp-commands.txt | 29 -----------------------------
> >> >  qapi-schema.json      | 13 +++++++++++++
> >> >  2 files changed, 13 insertions(+), 29 deletions(-)
> >> > 
> >> 
> >> > +++ b/qapi-schema.json
> >> > @@ -1011,6 +1011,19 @@
> >> >  # Returns: @MigrationParameters
> >> >  #
> >> >  # Since: 2.4
> >> > +#
> >> > +# Example:
> >> > +#
> >> > +# -> { "execute": "query-migrate-parameters" }
> >> > +# <- { "return": {
> >> > +#          "decompress-threads": 2,
> >> > +#          "cpu-throttle-increment": 10,
> >> > +#          "compress-threads": 8,
> >> > +#          "compress-level": 1,
> >> > +#          "cpu-throttle-initial": 20
> >> > +#       }
> >> > +#    }
> >> > +#
> >> >  ##
> >> >  { 'command': 'query-migrate-parameters',
> >> >    'returns': 'MigrationParameters' }
> >> 
> >> The example lacks 'cpu-throttle-increment', 'tls-creds', and
> >> 'tls-hostname'; do we want to take this opportunity to touch it up?
> >
> > I suggest to put a [...] in the returned example, as this example could
> > grow again, and there isn't much to learn from that query.
> >  
> >> Meanwhile, I have a series that touches this code, and will obviously
> >> create a merge conflict for whoever gets in second:
> >> https://lists.gnu.org/archive/html/qemu-devel/2016-09/msg01946.html
> >
> > Yes, the more we wait to review the series, the more conflicts we will get.
> > There is still over 100 patches to go, I'll send the next 30.
> 
> We suggested restructuring the series, and you liked the idea with the
> alternative step (3b), not (3a).  Would it make sense to repost the
> beginning of the multi-part monster in that form before moving on to the
> next part?

 3. Merge qmp-commands.txt into QAPI schema comments, step by step

   (b) If you delete qmp-commands.txt section as you cover them in the
   QAPI schema, command documentation regresses temporarily.  Tolerable,
   but needs to be explained in commit messages.  Your choice.

Isn't that what this series is doing? it moves the remaining doc from qmp-commands.txt to the schema.

Re: [Qemu-devel] [PATCH 15/30] qmp-commands: move 'query-migrate-parameters' doc to schema

[Markus Armbruster]

Marc-André Lureau <mlureau@redhat.com> writes:

> Hi
>
> ----- Original Message -----
>> Marc-André Lureau <mlureau@redhat.com> writes:
>> 
>> > Hi
>> >
>> > ----- Original Message -----
>> >> On 09/13/2016 08:01 AM, Marc-André Lureau wrote:
>> >> > Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
>> >> > ---
>> >> >  docs/qmp-commands.txt | 29 -----------------------------
>> >> >  qapi-schema.json      | 13 +++++++++++++
>> >> >  2 files changed, 13 insertions(+), 29 deletions(-)
>> >> > 
>> >> 
>> >> > +++ b/qapi-schema.json
>> >> > @@ -1011,6 +1011,19 @@
>> >> >  # Returns: @MigrationParameters
>> >> >  #
>> >> >  # Since: 2.4
>> >> > +#
>> >> > +# Example:
>> >> > +#
>> >> > +# -> { "execute": "query-migrate-parameters" }
>> >> > +# <- { "return": {
>> >> > +#          "decompress-threads": 2,
>> >> > +#          "cpu-throttle-increment": 10,
>> >> > +#          "compress-threads": 8,
>> >> > +#          "compress-level": 1,
>> >> > +#          "cpu-throttle-initial": 20
>> >> > +#       }
>> >> > +#    }
>> >> > +#
>> >> >  ##
>> >> >  { 'command': 'query-migrate-parameters',
>> >> >    'returns': 'MigrationParameters' }
>> >> 
>> >> The example lacks 'cpu-throttle-increment', 'tls-creds', and
>> >> 'tls-hostname'; do we want to take this opportunity to touch it up?
>> >
>> > I suggest to put a [...] in the returned example, as this example could
>> > grow again, and there isn't much to learn from that query.
>> >  
>> >> Meanwhile, I have a series that touches this code, and will obviously
>> >> create a merge conflict for whoever gets in second:
>> >> https://lists.gnu.org/archive/html/qemu-devel/2016-09/msg01946.html
>> >
>> > Yes, the more we wait to review the series, the more conflicts we will get.
>> > There is still over 100 patches to go, I'll send the next 30.
>> 
>> We suggested restructuring the series, and you liked the idea with the
>> alternative step (3b), not (3a).  Would it make sense to repost the
>> beginning of the multi-part monster in that form before moving on to the
>> next part?
>
>  3. Merge qmp-commands.txt into QAPI schema comments, step by step
>
>    (b) If you delete qmp-commands.txt section as you cover them in the
>    QAPI schema, command documentation regresses temporarily.  Tolerable,
>    but needs to be explained in commit messages.  Your choice.
>
> Isn't that what this series is doing? it moves the remaining doc from qmp-commands.txt to the schema.

Misunderstanding?  Step (3b) is one step of a reordered series.  Let me
repeat the order I proposed:

1. Fix existing issues in QAPI schema comments

2. Generate documentation from it (not a replacement for
   qmp-commands.txt, yet)

3. Merge qmp-commands.txt into QAPI schema comments, step by step

   (a) If you only update the QAPI schema comments, qmp-commands.txt
   stays intact throughout this work.

   (b) If you delete qmp-commands.txt section as you cover them in the
   QAPI schema, command documentation regresses temporarily.  Tolerable,
   but needs to be explained in commit messages.  Your choice.

4. Generated documentation now contains everything qmp-commands.txt
   contains; delete qmp-commands.txt

This way, the first part contains everything that's really interesting:
step 1, 2 and some of 3a or 3b, depending on which alternative you pick.
The remaining parts are just more of 3a or 3b, plus the trivial step 4
in the last one.

I proposed this to get the interesting review of step 2 out of the way
early, and before we tire ourselves out on the not-so-interesting but
necessary review of step 3.

Re: [Qemu-devel] [PATCH 15/30] qmp-commands: move 'query-migrate-parameters' doc to schema

[Marc-André Lureau]

Hi

----- Original Message -----
> Marc-André Lureau <mlureau@redhat.com> writes:
> 
> > Hi
> >
> > ----- Original Message -----
> >> Marc-André Lureau <mlureau@redhat.com> writes:
> >> 
> >> > Hi
> >> >
> >> > ----- Original Message -----
> >> >> On 09/13/2016 08:01 AM, Marc-André Lureau wrote:
> >> >> > Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> >> >> > ---
> >> >> >  docs/qmp-commands.txt | 29 -----------------------------
> >> >> >  qapi-schema.json      | 13 +++++++++++++
> >> >> >  2 files changed, 13 insertions(+), 29 deletions(-)
> >> >> > 
> >> >> 
> >> >> > +++ b/qapi-schema.json
> >> >> > @@ -1011,6 +1011,19 @@
> >> >> >  # Returns: @MigrationParameters
> >> >> >  #
> >> >> >  # Since: 2.4
> >> >> > +#
> >> >> > +# Example:
> >> >> > +#
> >> >> > +# -> { "execute": "query-migrate-parameters" }
> >> >> > +# <- { "return": {
> >> >> > +#          "decompress-threads": 2,
> >> >> > +#          "cpu-throttle-increment": 10,
> >> >> > +#          "compress-threads": 8,
> >> >> > +#          "compress-level": 1,
> >> >> > +#          "cpu-throttle-initial": 20
> >> >> > +#       }
> >> >> > +#    }
> >> >> > +#
> >> >> >  ##
> >> >> >  { 'command': 'query-migrate-parameters',
> >> >> >    'returns': 'MigrationParameters' }
> >> >> 
> >> >> The example lacks 'cpu-throttle-increment', 'tls-creds', and
> >> >> 'tls-hostname'; do we want to take this opportunity to touch it up?
> >> >
> >> > I suggest to put a [...] in the returned example, as this example could
> >> > grow again, and there isn't much to learn from that query.
> >> >  
> >> >> Meanwhile, I have a series that touches this code, and will obviously
> >> >> create a merge conflict for whoever gets in second:
> >> >> https://lists.gnu.org/archive/html/qemu-devel/2016-09/msg01946.html
> >> >
> >> > Yes, the more we wait to review the series, the more conflicts we will
> >> > get.
> >> > There is still over 100 patches to go, I'll send the next 30.
> >> 
> >> We suggested restructuring the series, and you liked the idea with the
> >> alternative step (3b), not (3a).  Would it make sense to repost the
> >> beginning of the multi-part monster in that form before moving on to the
> >> next part?
> >
> >  3. Merge qmp-commands.txt into QAPI schema comments, step by step
> >
> >    (b) If you delete qmp-commands.txt section as you cover them in the
> >    QAPI schema, command documentation regresses temporarily.  Tolerable,
> >    but needs to be explained in commit messages.  Your choice.
> >
> > Isn't that what this series is doing? it moves the remaining doc from
> > qmp-commands.txt to the schema.
> 
> Misunderstanding?  Step (3b) is one step of a reordered series.  Let me
> repeat the order I proposed:
> 
> 1. Fix existing issues in QAPI schema comments
> 
> 2. Generate documentation from it (not a replacement for
>    qmp-commands.txt, yet)
> 
> 3. Merge qmp-commands.txt into QAPI schema comments, step by step
> 
>    (a) If you only update the QAPI schema comments, qmp-commands.txt
>    stays intact throughout this work.
> 
>    (b) If you delete qmp-commands.txt section as you cover them in the
>    QAPI schema, command documentation regresses temporarily.  Tolerable,
>    but needs to be explained in commit messages.  Your choice.
> 
> 4. Generated documentation now contains everything qmp-commands.txt
>    contains; delete qmp-commands.txt
> 
> This way, the first part contains everything that's really interesting:
> step 1, 2 and some of 3a or 3b, depending on which alternative you pick.
> The remaining parts are just more of 3a or 3b, plus the trivial step 4
> in the last one.
> 
> I proposed this to get the interesting review of step 2 out of the way
> early, and before we tire ourselves out on the not-so-interesting but
> necessary review of step 3.
> 

It would have been easier to keep the discussion on the original thread. I disagreed with this plan:

 Generating the documentation before the end of 3(b) will also lead to temporarily incomplete generated doc, and will conflict with existing qmp-commands.txt.
 That's why I think the best solution is to go through 3(b) now, collect the move in a branch and push it in one go when qmp-commands.txt is empty and the doc is generated.

Re: [Qemu-devel] [PATCH 15/30] qmp-commands: move 'query-migrate-parameters' doc to schema

[Markus Armbruster]

Marc-André Lureau <mlureau@redhat.com> writes:

> Hi
>
> ----- Original Message -----
>> Marc-André Lureau <mlureau@redhat.com> writes:
>> 
>> > Hi
>> >
>> > ----- Original Message -----
>> >> Marc-André Lureau <mlureau@redhat.com> writes:
>> >> 
>> >> > Hi
>> >> >
>> >> > ----- Original Message -----
>> >> >> On 09/13/2016 08:01 AM, Marc-André Lureau wrote:
>> >> >> > Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
>> >> >> > ---
>> >> >> >  docs/qmp-commands.txt | 29 -----------------------------
>> >> >> >  qapi-schema.json      | 13 +++++++++++++
>> >> >> >  2 files changed, 13 insertions(+), 29 deletions(-)
>> >> >> > 
>> >> >> 
>> >> >> > +++ b/qapi-schema.json
>> >> >> > @@ -1011,6 +1011,19 @@
>> >> >> >  # Returns: @MigrationParameters
>> >> >> >  #
>> >> >> >  # Since: 2.4
>> >> >> > +#
>> >> >> > +# Example:
>> >> >> > +#
>> >> >> > +# -> { "execute": "query-migrate-parameters" }
>> >> >> > +# <- { "return": {
>> >> >> > +#          "decompress-threads": 2,
>> >> >> > +#          "cpu-throttle-increment": 10,
>> >> >> > +#          "compress-threads": 8,
>> >> >> > +#          "compress-level": 1,
>> >> >> > +#          "cpu-throttle-initial": 20
>> >> >> > +#       }
>> >> >> > +#    }
>> >> >> > +#
>> >> >> >  ##
>> >> >> >  { 'command': 'query-migrate-parameters',
>> >> >> >    'returns': 'MigrationParameters' }
>> >> >> 
>> >> >> The example lacks 'cpu-throttle-increment', 'tls-creds', and
>> >> >> 'tls-hostname'; do we want to take this opportunity to touch it up?
>> >> >
>> >> > I suggest to put a [...] in the returned example, as this example could
>> >> > grow again, and there isn't much to learn from that query.
>> >> >  
>> >> >> Meanwhile, I have a series that touches this code, and will obviously
>> >> >> create a merge conflict for whoever gets in second:
>> >> >> https://lists.gnu.org/archive/html/qemu-devel/2016-09/msg01946.html
>> >> >
>> >> > Yes, the more we wait to review the series, the more conflicts we will
>> >> > get.
>> >> > There is still over 100 patches to go, I'll send the next 30.
>> >> 
>> >> We suggested restructuring the series, and you liked the idea with the
>> >> alternative step (3b), not (3a).  Would it make sense to repost the
>> >> beginning of the multi-part monster in that form before moving on to the
>> >> next part?
>> >
>> >  3. Merge qmp-commands.txt into QAPI schema comments, step by step
>> >
>> >    (b) If you delete qmp-commands.txt section as you cover them in the
>> >    QAPI schema, command documentation regresses temporarily.  Tolerable,
>> >    but needs to be explained in commit messages.  Your choice.
>> >
>> > Isn't that what this series is doing? it moves the remaining doc from
>> > qmp-commands.txt to the schema.
>> 
>> Misunderstanding?  Step (3b) is one step of a reordered series.  Let me
>> repeat the order I proposed:
>> 
>> 1. Fix existing issues in QAPI schema comments
>> 
>> 2. Generate documentation from it (not a replacement for
>>    qmp-commands.txt, yet)
>> 
>> 3. Merge qmp-commands.txt into QAPI schema comments, step by step
>> 
>>    (a) If you only update the QAPI schema comments, qmp-commands.txt
>>    stays intact throughout this work.
>> 
>>    (b) If you delete qmp-commands.txt section as you cover them in the
>>    QAPI schema, command documentation regresses temporarily.  Tolerable,
>>    but needs to be explained in commit messages.  Your choice.
>> 
>> 4. Generated documentation now contains everything qmp-commands.txt
>>    contains; delete qmp-commands.txt
>> 
>> This way, the first part contains everything that's really interesting:
>> step 1, 2 and some of 3a or 3b, depending on which alternative you pick.
>> The remaining parts are just more of 3a or 3b, plus the trivial step 4
>> in the last one.
>> 
>> I proposed this to get the interesting review of step 2 out of the way
>> early, and before we tire ourselves out on the not-so-interesting but
>> necessary review of step 3.
>> 
>
> It would have been easier to keep the discussion on the original thread. I disagreed with this plan:
>
>  Generating the documentation before the end of 3(b) will also lead to temporarily incomplete generated doc, and will conflict with existing qmp-commands.txt.

Having incomplete new documentation (getting less incomplete in each
commit) conflict with incomplete old documentation (getting more
incomplete) is no worse than having old documentation getting more
incomplete.  In both cases, we go through an intermediate state with
flawed documentation.

>  That's why I think the best solution is to go through 3(b) now, collect the move in a branch and push it in one go when qmp-commands.txt is empty and the doc is generated.

If you prefer to do it this way, I suggest to post everything at once,
because I won't bother reviewing any of step 3 before step 2 for the
reasons I explained above.  I don't want to see review of the step 2
invalidate all our review work on step 3.

Re: [Qemu-devel] [PATCH 15/30] qmp-commands: move 'query-migrate-parameters' doc to schema

[Marc-André Lureau]

Hi

----- Original Message -----
> Marc-André Lureau <mlureau@redhat.com> writes:
> 
> > Hi
> >
> > ----- Original Message -----
> >> Marc-André Lureau <mlureau@redhat.com> writes:
> >> 
> >> > Hi
> >> >
> >> > ----- Original Message -----
> >> >> Marc-André Lureau <mlureau@redhat.com> writes:
> >> >> 
> >> >> > Hi
> >> >> >
> >> >> > ----- Original Message -----
> >> >> >> On 09/13/2016 08:01 AM, Marc-André Lureau wrote:
> >> >> >> > Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> >> >> >> > ---
> >> >> >> >  docs/qmp-commands.txt | 29 -----------------------------
> >> >> >> >  qapi-schema.json      | 13 +++++++++++++
> >> >> >> >  2 files changed, 13 insertions(+), 29 deletions(-)
> >> >> >> > 
> >> >> >> 
> >> >> >> > +++ b/qapi-schema.json
> >> >> >> > @@ -1011,6 +1011,19 @@
> >> >> >> >  # Returns: @MigrationParameters
> >> >> >> >  #
> >> >> >> >  # Since: 2.4
> >> >> >> > +#
> >> >> >> > +# Example:
> >> >> >> > +#
> >> >> >> > +# -> { "execute": "query-migrate-parameters" }
> >> >> >> > +# <- { "return": {
> >> >> >> > +#          "decompress-threads": 2,
> >> >> >> > +#          "cpu-throttle-increment": 10,
> >> >> >> > +#          "compress-threads": 8,
> >> >> >> > +#          "compress-level": 1,
> >> >> >> > +#          "cpu-throttle-initial": 20
> >> >> >> > +#       }
> >> >> >> > +#    }
> >> >> >> > +#
> >> >> >> >  ##
> >> >> >> >  { 'command': 'query-migrate-parameters',
> >> >> >> >    'returns': 'MigrationParameters' }
> >> >> >> 
> >> >> >> The example lacks 'cpu-throttle-increment', 'tls-creds', and
> >> >> >> 'tls-hostname'; do we want to take this opportunity to touch it up?
> >> >> >
> >> >> > I suggest to put a [...] in the returned example, as this example
> >> >> > could
> >> >> > grow again, and there isn't much to learn from that query.
> >> >> >  
> >> >> >> Meanwhile, I have a series that touches this code, and will
> >> >> >> obviously
> >> >> >> create a merge conflict for whoever gets in second:
> >> >> >> https://lists.gnu.org/archive/html/qemu-devel/2016-09/msg01946.html
> >> >> >
> >> >> > Yes, the more we wait to review the series, the more conflicts we
> >> >> > will
> >> >> > get.
> >> >> > There is still over 100 patches to go, I'll send the next 30.
> >> >> 
> >> >> We suggested restructuring the series, and you liked the idea with the
> >> >> alternative step (3b), not (3a).  Would it make sense to repost the
> >> >> beginning of the multi-part monster in that form before moving on to
> >> >> the
> >> >> next part?
> >> >
> >> >  3. Merge qmp-commands.txt into QAPI schema comments, step by step
> >> >
> >> >    (b) If you delete qmp-commands.txt section as you cover them in the
> >> >    QAPI schema, command documentation regresses temporarily.  Tolerable,
> >> >    but needs to be explained in commit messages.  Your choice.
> >> >
> >> > Isn't that what this series is doing? it moves the remaining doc from
> >> > qmp-commands.txt to the schema.
> >> 
> >> Misunderstanding?  Step (3b) is one step of a reordered series.  Let me
> >> repeat the order I proposed:
> >> 
> >> 1. Fix existing issues in QAPI schema comments
> >> 
> >> 2. Generate documentation from it (not a replacement for
> >>    qmp-commands.txt, yet)
> >> 
> >> 3. Merge qmp-commands.txt into QAPI schema comments, step by step
> >> 
> >>    (a) If you only update the QAPI schema comments, qmp-commands.txt
> >>    stays intact throughout this work.
> >> 
> >>    (b) If you delete qmp-commands.txt section as you cover them in the
> >>    QAPI schema, command documentation regresses temporarily.  Tolerable,
> >>    but needs to be explained in commit messages.  Your choice.
> >> 
> >> 4. Generated documentation now contains everything qmp-commands.txt
> >>    contains; delete qmp-commands.txt
> >> 
> >> This way, the first part contains everything that's really interesting:
> >> step 1, 2 and some of 3a or 3b, depending on which alternative you pick.
> >> The remaining parts are just more of 3a or 3b, plus the trivial step 4
> >> in the last one.
> >> 
> >> I proposed this to get the interesting review of step 2 out of the way
> >> early, and before we tire ourselves out on the not-so-interesting but
> >> necessary review of step 3.
> >> 
> >
> > It would have been easier to keep the discussion on the original thread. I
> > disagreed with this plan:
> >
> >  Generating the documentation before the end of 3(b) will also lead to
> >  temporarily incomplete generated doc, and will conflict with existing
> >  qmp-commands.txt.
> 
> Having incomplete new documentation (getting less incomplete in each
> commit) conflict with incomplete old documentation (getting more
> incomplete) is no worse than having old documentation getting more
> incomplete.  In both cases, we go through an intermediate state with
> flawed documentation.

Not if we merge the move in one go, as I propose.

Don't you think it's cleaner if we first move the documentation in one place before we generate yet another incomplete doc?

> 
> >  That's why I think the best solution is to go through 3(b) now, collect
> >  the move in a branch and push it in one go when qmp-commands.txt is empty
> >  and the doc is generated.
> 
> If you prefer to do it this way, I suggest to post everything at once,
> because I won't bother reviewing any of step 3 before step 2 for the
> reasons I explained above.  I don't want to see review of the step 2
> invalidate all our review work on step 3.

I fail to see how generating the doc could invalidate moving the documentation in the schema.

Indeed, we may want to tweak the documentation style for some reason, but that's irrelevant for now, all we should focus on is having the doc in one place before doing further work with it. 

Re: [Qemu-devel] [PATCH 15/30] qmp-commands: move 'query-migrate-parameters' doc to schema

[Markus Armbruster]

Marc-André Lureau <mlureau@redhat.com> writes:

> Hi
>
> ----- Original Message -----
>> Marc-André Lureau <mlureau@redhat.com> writes:
>> 
>> > Hi
>> >
>> > ----- Original Message -----
>> >> Marc-André Lureau <mlureau@redhat.com> writes:
>> >> 
>> >> > Hi
>> >> >
>> >> > ----- Original Message -----
>> >> >> Marc-André Lureau <mlureau@redhat.com> writes:
>> >> >> 
>> >> >> > Hi
>> >> >> >
>> >> >> > ----- Original Message -----
>> >> >> >> On 09/13/2016 08:01 AM, Marc-André Lureau wrote:
>> >> >> >> > Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
[...]
>> >> >> >> Meanwhile, I have a series that touches this code, and will
>> >> >> >> obviously
>> >> >> >> create a merge conflict for whoever gets in second:
>> >> >> >> https://lists.gnu.org/archive/html/qemu-devel/2016-09/msg01946.html
>> >> >> >
>> >> >> > Yes, the more we wait to review the series, the more conflicts we
>> >> >> > will
>> >> >> > get.
>> >> >> > There is still over 100 patches to go, I'll send the next 30.
>> >> >> 
>> >> >> We suggested restructuring the series, and you liked the idea with the
>> >> >> alternative step (3b), not (3a).  Would it make sense to repost the
>> >> >> beginning of the multi-part monster in that form before moving on to
>> >> >> the
>> >> >> next part?
>> >> >
>> >> >  3. Merge qmp-commands.txt into QAPI schema comments, step by step
>> >> >
>> >> >    (b) If you delete qmp-commands.txt section as you cover them in the
>> >> >    QAPI schema, command documentation regresses temporarily.  Tolerable,
>> >> >    but needs to be explained in commit messages.  Your choice.
>> >> >
>> >> > Isn't that what this series is doing? it moves the remaining doc from
>> >> > qmp-commands.txt to the schema.
>> >> 
>> >> Misunderstanding?  Step (3b) is one step of a reordered series.  Let me
>> >> repeat the order I proposed:
>> >> 
>> >> 1. Fix existing issues in QAPI schema comments
>> >> 
>> >> 2. Generate documentation from it (not a replacement for
>> >>    qmp-commands.txt, yet)
>> >> 
>> >> 3. Merge qmp-commands.txt into QAPI schema comments, step by step
>> >> 
>> >>    (a) If you only update the QAPI schema comments, qmp-commands.txt
>> >>    stays intact throughout this work.
>> >> 
>> >>    (b) If you delete qmp-commands.txt section as you cover them in the
>> >>    QAPI schema, command documentation regresses temporarily.  Tolerable,
>> >>    but needs to be explained in commit messages.  Your choice.
>> >> 
>> >> 4. Generated documentation now contains everything qmp-commands.txt
>> >>    contains; delete qmp-commands.txt
>> >> 
>> >> This way, the first part contains everything that's really interesting:
>> >> step 1, 2 and some of 3a or 3b, depending on which alternative you pick.
>> >> The remaining parts are just more of 3a or 3b, plus the trivial step 4
>> >> in the last one.
>> >> 
>> >> I proposed this to get the interesting review of step 2 out of the way
>> >> early, and before we tire ourselves out on the not-so-interesting but
>> >> necessary review of step 3.
>> >> 
>> >
>> > It would have been easier to keep the discussion on the original thread. I
>> > disagreed with this plan:
>> >
>> >  Generating the documentation before the end of 3(b) will also lead to
>> >  temporarily incomplete generated doc, and will conflict with existing
>> >  qmp-commands.txt.
>> 
>> Having incomplete new documentation (getting less incomplete in each
>> commit) conflict with incomplete old documentation (getting more
>> incomplete) is no worse than having old documentation getting more
>> incomplete.  In both cases, we go through an intermediate state with
>> flawed documentation.
>
> Not if we merge the move in one go, as I propose.
>
> Don't you think it's cleaner if we first move the documentation in one place before we generate yet another incomplete doc?

At this time, I'm 100% focused on ease of review and saving your and
your reviewers' time.  Once we got review under control, I'm happy to
talk about whether another order or some squashing makes more sense for
the permanent Git record.

>> >  That's why I think the best solution is to go through 3(b) now, collect
>> >  the move in a branch and push it in one go when qmp-commands.txt is empty
>> >  and the doc is generated.
>> 
>> If you prefer to do it this way, I suggest to post everything at once,
>> because I won't bother reviewing any of step 3 before step 2 for the
>> reasons I explained above.  I don't want to see review of the step 2
>> invalidate all our review work on step 3.
>
> I fail to see how generating the doc could invalidate moving the
> documentation in the schema.
>
> Indeed, we may want to tweak the documentation style for some reason,
> but that's irrelevant for now, all we should focus on is having the
> doc in one place before doing further work with it.

Arguing further about the perfect order feels like a waste of time.

You're free to post this in the order you feel is right.  If it differs
from the order that I feel is right for my review, then please post the
whole thing, so I can review it effectively.

Re: [Qemu-devel] [PATCH 15/30] qmp-commands: move 'query-migrate-parameters' doc to schema

[Marc-André Lureau]

Hi

----- Original Message -----
> Arguing further about the perfect order feels like a waste of time.
> 
> You're free to post this in the order you feel is right.  If it differs
> from the order that I feel is right for my review, then please post the
> whole thing, so I can review it effectively.

Since only you and Eric are actually reviewing this, and you both prefer to review the parser/generator first, I sent it yesterday: http://patchew.org/QEMU/20160922155808.8504-1-marcandre.lureau%40redhat.com/

Re: [Qemu-devel] [PATCH 15/30] qmp-commands: move 'query-migrate-parameters' doc to schema

[Eric Blake]

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

On 09/22/2016 06:54 AM, Marc-André Lureau wrote:

>> 3. Merge qmp-commands.txt into QAPI schema comments, step by step
>>
>>    (a) If you only update the QAPI schema comments, qmp-commands.txt
>>    stays intact throughout this work.
>>
>>    (b) If you delete qmp-commands.txt section as you cover them in the
>>    QAPI schema, command documentation regresses temporarily.  Tolerable,
>>    but needs to be explained in commit messages.  Your choice.
>>

> 
>  Generating the documentation before the end of 3(b) will also lead to temporarily incomplete generated doc, and will conflict with existing qmp-commands.txt.

Incomplete generated doc is fine, if the commit message calls it out
that upcoming patches will fix the gaps (after all, that's what 3(b)
says to do).  And I tend to agree with Markus that reviewing the
generator first, rather than after we've burned ourself out looking over
lots of individual commands, will give us a chance to make sure the
generator is sane (and may even have some minor impacts to HOW we move
documentation over, if we end up tweaking the .json files to make the
generator easier to manage).

>  That's why I think the best solution is to go through 3(b) now, collect the move in a branch and push it in one go when qmp-commands.txt is empty and the doc is generated.

As it is, I already made comments about the first batch where you were
mixing in fixes (step 1) with doc motion, but failed to mention it in
the commit message.  And where Markus has already argued that making
those fixes on their own as a prerequisite is a bit cleaner than forcing
the review of step 3 to be more complex.

-- 
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 --]

[Qemu-devel] [PATCH 16/30] qmp-commands: move 'client_migrate_info' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 22 ----------------------
 qapi-schema.json      | 13 +++++++++++++
 2 files changed, 13 insertions(+), 22 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index d96dd27..53e06d2 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -505,28 +505,6 @@ Example:
 -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
 <- { "return": {} }
 
-client_migrate_info
--------------------
-
-Set migration information for remote display.  This makes the server
-ask the client to automatically reconnect using the new parameters
-once migration finished successfully.  Only implemented for SPICE.
-
-Arguments:
-
-- "protocol":     must be "spice" (json-string)
-- "hostname":     migration target hostname (json-string)
-- "port":         spice tcp port for plaintext channels (json-int, optional)
-- "tls-port":     spice tcp port for tls-secured channels (json-int, optional)
-- "cert-subject": server certificate subject (json-string, optional)
-
-Example:
-
--> { "execute": "client_migrate_info",
-     "arguments": { "protocol": "spice",
-                    "hostname": "virt42.lab.kraxel.org",
-                    "port": 1234 } }
-<- { "return": {} }
 
 dump
 
diff --git a/qapi-schema.json b/qapi-schema.json
index e57f223..4bf088c 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -1036,12 +1036,25 @@
 # once migration finished successfully.  Only implemented for SPICE.
 #
 # @protocol:     must be "spice"
+#
 # @hostname:     migration target hostname
+#
 # @port:         #optional spice tcp port for plaintext channels
+#
 # @tls-port:     #optional spice tcp port for tls-secured channels
+#
 # @cert-subject: #optional server certificate subject
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# -> { "execute": "client_migrate_info",
+#      "arguments": { "protocol": "spice",
+#                     "hostname": "virt42.lab.kraxel.org",
+#                     "port": 1234 } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'client_migrate_info',
   'data': { 'protocol': 'str', 'hostname': 'str', '*port': 'int',
-- 
2.10.0

[Qemu-devel] [PATCH 17/30] qmp-commands: move 'migrate-start-postcopy' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 10 ----------
 qapi-schema.json      |  7 +++++++
 2 files changed, 7 insertions(+), 10 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 53e06d2..f2b7369 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -454,16 +454,6 @@ Example:
 -> { "execute": "migrate-set-cache-size", "arguments": { "value": 536870912 } }
 <- { "return": {} }
 
-migrate-start-postcopy
-----------------------
-
-Switch an in-progress migration to postcopy mode. Ignored after the end of
-migration (or once already in postcopy).
-
-Example:
--> { "execute": "migrate-start-postcopy" }
-<- { "return": {} }
-
 query-migrate-cache-size
 ------------------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 4bf088c..ea554bf 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -1068,6 +1068,13 @@
 # command.
 #
 # Since: 2.5
+#
+# Example:
+#
+# -> { "execute": "migrate-start-postcopy" }
+# <- { "return": {} }
+#
+##
 { 'command': 'migrate-start-postcopy' }
 
 ##
-- 
2.10.0

[Qemu-devel] [PATCH 18/30] qmp-commands: move 'query-mice' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 35 -----------------------------------
 qapi-schema.json      | 20 ++++++++++++++++++++
 2 files changed, 20 insertions(+), 35 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index f2b7369..c066833 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -2213,41 +2213,6 @@ Example:
 
 Note: This example has been shortened as the real response is too long.
 
-query-mice
-----------
-
-Show VM mice information.
-
-Each mouse is represented by a json-object, the returned value is a json-array
-of all mice.
-
-The mouse json-object contains the following:
-
-- "name": mouse's name (json-string)
-- "index": mouse's index (json-int)
-- "current": true if this mouse is receiving events, false otherwise (json-bool)
-- "absolute": true if the mouse generates absolute input events (json-bool)
-
-Example:
-
--> { "execute": "query-mice" }
-<- {
-      "return":[
-         {
-            "name":"QEMU Microsoft Mouse",
-            "index":0,
-            "current":false,
-            "absolute":false
-         },
-         {
-            "name":"QEMU PS/2 Mouse",
-            "index":1,
-            "current":true,
-            "absolute":true
-         }
-      ]
-   }
-
 query-vnc
 ---------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index ea554bf..d9e45dc 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -1104,6 +1104,26 @@
 # Returns: a list of @MouseInfo for each device
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# -> { "execute": "query-mice" }
+# <- { "return": [
+#          {
+#             "name":"QEMU Microsoft Mouse",
+#             "index":0,
+#             "current":false,
+#             "absolute":false
+#          },
+#          {
+#             "name":"QEMU PS/2 Mouse",
+#             "index":1,
+#             "current":true,
+#             "absolute":true
+#          }
+#       ]
+#    }
+#
 ##
 { 'command': 'query-mice', 'returns': ['MouseInfo'] }
 
-- 
2.10.0

[Qemu-devel] [PATCH 19/30] qmp-commands: move 'query-cpus' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 46 ----------------------------------------------
 qapi-schema.json      | 26 ++++++++++++++++++++++++++
 2 files changed, 26 insertions(+), 46 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index c066833..3f44375 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -1929,52 +1929,6 @@ Example:
       ]
    }
 
-query-cpus
-----------
-
-Show CPU information.
-
-Return a json-array. Each CPU is represented by a json-object, which contains:
-
-- "CPU": CPU index (json-int)
-- "current": true if this is the current CPU, false otherwise (json-bool)
-- "halted": true if the cpu is halted, false otherwise (json-bool)
-- "qom_path": path to the CPU object in the QOM tree (json-str)
-- "arch": architecture of the cpu, which determines what additional
-          keys will be present (json-str)
-- Current program counter. The key's name depends on the architecture:
-     "pc": i386/x86_64 (json-int)
-     "nip": PPC (json-int)
-     "pc" and "npc": sparc (json-int)
-     "PC": mips (json-int)
-- "thread_id": ID of the underlying host thread (json-int)
-
-Example:
-
--> { "execute": "query-cpus" }
-<- {
-      "return":[
-         {
-            "CPU":0,
-            "current":true,
-            "halted":false,
-            "qom_path":"/machine/unattached/device[0]",
-            "arch":"x86",
-            "pc":3227107138,
-            "thread_id":3134
-         },
-         {
-            "CPU":1,
-            "current":false,
-            "halted":true,
-            "qom_path":"/machine/unattached/device[2]",
-            "arch":"x86",
-            "pc":7108165,
-            "thread_id":3135
-         }
-      ]
-   }
-
 query-iothreads
 ---------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index d9e45dc..c1183d0 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -1248,6 +1248,32 @@
 # Returns: a list of @CpuInfo for each virtual CPU
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# -> { "execute": "query-cpus" }
+# <- { "return": [
+#          {
+#             "CPU":0,
+#             "current":true,
+#             "halted":false,
+#             "qom_path":"/machine/unattached/device[0]",
+#             "arch":"x86",
+#             "pc":3227107138,
+#             "thread_id":3134
+#          },
+#          {
+#             "CPU":1,
+#             "current":false,
+#             "halted":true,
+#             "qom_path":"/machine/unattached/device[2]",
+#             "arch":"x86",
+#             "pc":7108165,
+#             "thread_id":3135
+#          }
+#       ]
+#    }
+#
 ##
 { 'command': 'query-cpus', 'returns': ['CpuInfo'] }
 
-- 
2.10.0

[Qemu-devel] [PATCH 20/30] qmp-commands: move 'query-iothreads' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 30 ------------------------------
 qapi-schema.json      | 16 ++++++++++++++++
 2 files changed, 16 insertions(+), 30 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 3f44375..bd0d6c1 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -1929,36 +1929,6 @@ Example:
       ]
    }
 
-query-iothreads
----------------
-
-Returns a list of information about each iothread.
-
-Note this list excludes the QEMU main loop thread, which is not declared
-using the -object iothread command-line option.  It is always the main thread
-of the process.
-
-Return a json-array. Each iothread is represented by a json-object, which contains:
-
-- "id": name of iothread (json-str)
-- "thread-id": ID of the underlying host thread (json-int)
-
-Example:
-
--> { "execute": "query-iothreads" }
-<- {
-      "return":[
-         {
-            "id":"iothread0",
-            "thread-id":3134
-         },
-         {
-            "id":"iothread1",
-            "thread-id":3135
-         }
-      ]
-   }
-
 query-pci
 ---------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index c1183d0..a7872c4 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -1303,6 +1303,22 @@
 # Returns: a list of @IOThreadInfo for each iothread
 #
 # Since: 2.0
+#
+# Example:
+#
+# -> { "execute": "query-iothreads" }
+# <- { "return": [
+#          {
+#             "id":"iothread0",
+#             "thread-id":3134
+#          },
+#          {
+#             "id":"iothread1",
+#             "thread-id":3135
+#          }
+#       ]
+#    }
+#
 ##
 { 'command': 'query-iothreads', 'returns': ['IOThreadInfo'] }
 
-- 
2.10.0

[Qemu-devel] [PATCH 21/30] qmp-commands: move 'query-vnc' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 54 ---------------------------------------------------
 qapi-schema.json      | 22 ++++++++++++++++++++-
 2 files changed, 21 insertions(+), 55 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index bd0d6c1..ca75716 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -2137,60 +2137,6 @@ Example:
 
 Note: This example has been shortened as the real response is too long.
 
-query-vnc
----------
-
-Show VNC server information.
-
-Return a json-object with server information. Connected clients are returned
-as a json-array of json-objects.
-
-The main json-object contains the following:
-
-- "enabled": true or false (json-bool)
-- "host": server's IP address (json-string)
-- "family": address family (json-string)
-         - Possible values: "ipv4", "ipv6", "unix", "unknown"
-- "service": server's port number (json-string)
-- "auth": authentication method (json-string)
-         - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
-                            "tls", "ultra", "unknown", "vencrypt", "vencrypt",
-                            "vencrypt+plain", "vencrypt+tls+none",
-                            "vencrypt+tls+plain", "vencrypt+tls+sasl",
-                            "vencrypt+tls+vnc", "vencrypt+x509+none",
-                            "vencrypt+x509+plain", "vencrypt+x509+sasl",
-                            "vencrypt+x509+vnc", "vnc"
-- "clients": a json-array of all connected clients
-
-Clients are described by a json-object, each one contain the following:
-
-- "host": client's IP address (json-string)
-- "family": address family (json-string)
-         - Possible values: "ipv4", "ipv6", "unix", "unknown"
-- "service": client's port number (json-string)
-- "x509_dname": TLS dname (json-string, optional)
-- "sasl_username": SASL username (json-string, optional)
-
-Example:
-
--> { "execute": "query-vnc" }
-<- {
-      "return":{
-         "enabled":true,
-         "host":"0.0.0.0",
-         "service":"50402",
-         "auth":"vnc",
-         "family":"ipv4",
-         "clients":[
-            {
-               "host":"127.0.0.1",
-               "service":"50401",
-               "family":"ipv4"
-            }
-         ]
-      }
-   }
-
 query-spice
 -----------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index a7872c4..f169b08 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -1494,11 +1494,31 @@
 ##
 # @query-vnc:
 #
-# Returns information about the current VNC server
+# Returns information about the current VNC server.
 #
 # Returns: @VncInfo
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# -> { "execute": "query-vnc" }
+# <- { "return": {
+#          "enabled":true,
+#          "host":"0.0.0.0",
+#          "service":"50402",
+#          "auth":"vnc",
+#          "family":"ipv4",
+#          "clients":[
+#             {
+#                "host":"127.0.0.1",
+#                "service":"50401",
+#                "family":"ipv4"
+#             }
+#          ]
+#       }
+#    }
+#
 ##
 { 'command': 'query-vnc', 'returns': 'VncInfo' }
 
-- 
2.10.0

[Qemu-devel] [PATCH 22/30] qmp-commands: move 'query-spice' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 67 ---------------------------------------------------
 qapi-schema.json      | 42 ++++++++++++++++++++++++++++----
 2 files changed, 37 insertions(+), 72 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index ca75716..3b7af3b 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -2137,73 +2137,6 @@ Example:
 
 Note: This example has been shortened as the real response is too long.
 
-query-spice
------------
-
-Show SPICE server information.
-
-Return a json-object with server information. Connected clients are returned
-as a json-array of json-objects.
-
-The main json-object contains the following:
-
-- "enabled": true or false (json-bool)
-- "host": server's IP address (json-string)
-- "port": server's port number (json-int, optional)
-- "tls-port": server's port number (json-int, optional)
-- "auth": authentication method (json-string)
-         - Possible values: "none", "spice"
-- "channels": a json-array of all active channels clients
-
-Channels are described by a json-object, each one contain the following:
-
-- "host": client's IP address (json-string)
-- "family": address family (json-string)
-         - Possible values: "ipv4", "ipv6", "unix", "unknown"
-- "port": client's port number (json-string)
-- "connection-id": spice connection id.  All channels with the same id
-                   belong to the same spice session (json-int)
-- "channel-type": channel type.  "1" is the main control channel, filter for
-                  this one if you want track spice sessions only (json-int)
-- "channel-id": channel id.  Usually "0", might be different needed when
-                multiple channels of the same type exist, such as multiple
-                display channels in a multihead setup (json-int)
-- "tls": whether the channel is encrypted (json-bool)
-
-Example:
-
--> { "execute": "query-spice" }
-<- {
-      "return": {
-         "enabled": true,
-         "auth": "spice",
-         "port": 5920,
-         "tls-port": 5921,
-         "host": "0.0.0.0",
-         "channels": [
-            {
-               "port": "54924",
-               "family": "ipv4",
-               "channel-type": 1,
-               "connection-id": 1804289383,
-               "host": "127.0.0.1",
-               "channel-id": 0,
-               "tls": true
-            },
-            {
-               "port": "36710",
-               "family": "ipv4",
-               "channel-type": 4,
-               "connection-id": 1804289383,
-               "host": "127.0.0.1",
-               "channel-id": 0,
-               "tls": false
-            },
-            [ ... more channels follow ... ]
-         ]
-      }
-   }
-
 query-command-line-options
 --------------------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index f169b08..389eb9a 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -1616,7 +1616,7 @@
 # @enabled: true if the SPICE server is enabled, false otherwise
 #
 # @migrated: true if the last guest migration completed and spice
-#            migration had completed as well. false otherwise.
+#            migration had completed as well. false otherwise. (since 1.4)
 #
 # @host: #optional The hostname the SPICE server is bound to.  This depends on
 #        the name resolution on the host and may be an IP address.
@@ -1634,9 +1634,7 @@
 #
 # @mouse-mode: The mode in which the mouse cursor is displayed currently. Can
 #              be determined by the client or the server, or unknown if spice
-#              server doesn't provide this information.
-#
-#              Since: 1.1
+#              server doesn't provide this information. (since: 1.1)
 #
 # @channels: a list of @SpiceChannel for each active spice channel
 #
@@ -1650,11 +1648,45 @@
 ##
 # @query-spice
 #
-# Returns information about the current SPICE server
+# Returns information about the current SPICE server.
 #
 # Returns: @SpiceInfo
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# -> { "execute": "query-spice" }
+# <- { "return": {
+#          "enabled": true,
+#          "auth": "spice",
+#          "port": 5920,
+#          "tls-port": 5921,
+#          "host": "0.0.0.0",
+#          "channels": [
+#             {
+#                "port": "54924",
+#                "family": "ipv4",
+#                "channel-type": 1,
+#                "connection-id": 1804289383,
+#                "host": "127.0.0.1",
+#                "channel-id": 0,
+#                "tls": true
+#             },
+#             {
+#                "port": "36710",
+#                "family": "ipv4",
+#                "channel-type": 4,
+#                "connection-id": 1804289383,
+#                "host": "127.0.0.1",
+#                "channel-id": 0,
+#                "tls": false
+#             },
+#             [ ... more channels follow ... ]
+#          ]
+#       }
+#    }
+#
 ##
 { 'command': 'query-spice', 'returns': 'SpiceInfo' }
 
-- 
2.10.0

[Qemu-devel] [PATCH 23/30] qmp-commands: move 'query-balloon' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 19 -------------------
 qapi-schema.json      | 11 +++++++++++
 2 files changed, 11 insertions(+), 19 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 3b7af3b..0b69f3d 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -2177,25 +2177,6 @@ Example:
      ]
    }
 
-query-balloon
--------------
-
-Show balloon information.
-
-Make an asynchronous request for balloon info. When the request completes a
-json-object will be returned containing the following data:
-
-- "actual": current balloon value in bytes (json-int)
-
-Example:
-
--> { "execute": "query-balloon" }
-<- {
-      "return":{
-         "actual":1073741824,
-      }
-   }
-
 query-tpm
 ---------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 389eb9a..4b66a36 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -1708,11 +1708,22 @@
 # Return information about the balloon device.
 #
 # Returns: @BalloonInfo on success
+#
 #          If the balloon driver is enabled but not functional because the KVM
 #          kernel module cannot support it, KvmMissingCap
+#
 #          If no balloon device is present, DeviceNotActive
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# -> { "execute": "query-balloon" }
+# <- { "return": {
+#          "actual": 1073741824,
+#       }
+#    }
+#
 ##
 { 'command': 'query-balloon', 'returns': 'BalloonInfo' }
 
-- 
2.10.0

[Qemu-devel] [PATCH 24/30] qmp-commands: move 'query-pci' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 208 --------------------------------------------------
 qapi-schema.json      | 139 ++++++++++++++++++++++++++++++++-
 2 files changed, 138 insertions(+), 209 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 0b69f3d..0050067 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -1929,214 +1929,6 @@ Example:
       ]
    }
 
-query-pci
----------
-
-PCI buses and devices information.
-
-The returned value is a json-array of all buses. Each bus is represented by
-a json-object, which has a key with a json-array of all PCI devices attached
-to it. Each device is represented by a json-object.
-
-The bus json-object contains the following:
-
-- "bus": bus number (json-int)
-- "devices": a json-array of json-objects, each json-object represents a
-             PCI device
-
-The PCI device json-object contains the following:
-
-- "bus": identical to the parent's bus number (json-int)
-- "slot": slot number (json-int)
-- "function": function number (json-int)
-- "class_info": a json-object containing:
-     - "desc": device class description (json-string, optional)
-     - "class": device class number (json-int)
-- "id": a json-object containing:
-     - "device": device ID (json-int)
-     - "vendor": vendor ID (json-int)
-- "irq": device's IRQ if assigned (json-int, optional)
-- "qdev_id": qdev id string (json-string)
-- "pci_bridge": It's a json-object, only present if this device is a
-                PCI bridge, contains:
-     - "bus": bus number (json-int)
-     - "secondary": secondary bus number (json-int)
-     - "subordinate": subordinate bus number (json-int)
-     - "io_range": I/O memory range information, a json-object with the
-                   following members:
-                 - "base": base address, in bytes (json-int)
-                 - "limit": limit address, in bytes (json-int)
-     - "memory_range": memory range information, a json-object with the
-                       following members:
-                 - "base": base address, in bytes (json-int)
-                 - "limit": limit address, in bytes (json-int)
-     - "prefetchable_range": Prefetchable memory range information, a
-                             json-object with the following members:
-                 - "base": base address, in bytes (json-int)
-                 - "limit": limit address, in bytes (json-int)
-     - "devices": a json-array of PCI devices if there's any attached, each
-                  each element is represented by a json-object, which contains
-                  the same members of the 'PCI device json-object' described
-                  above (optional)
-- "regions": a json-array of json-objects, each json-object represents a
-             memory region of this device
-
-The memory range json-object contains the following:
-
-- "base": base memory address (json-int)
-- "limit": limit value (json-int)
-
-The region json-object can be an I/O region or a memory region, an I/O region
-json-object contains the following:
-
-- "type": "io" (json-string, fixed)
-- "bar": BAR number (json-int)
-- "address": memory address (json-int)
-- "size": memory size (json-int)
-
-A memory region json-object contains the following:
-
-- "type": "memory" (json-string, fixed)
-- "bar": BAR number (json-int)
-- "address": memory address (json-int)
-- "size": memory size (json-int)
-- "mem_type_64": true or false (json-bool)
-- "prefetch": true or false (json-bool)
-
-Example:
-
--> { "execute": "query-pci" }
-<- {
-      "return":[
-         {
-            "bus":0,
-            "devices":[
-               {
-                  "bus":0,
-                  "qdev_id":"",
-                  "slot":0,
-                  "class_info":{
-                     "class":1536,
-                     "desc":"Host bridge"
-                  },
-                  "id":{
-                     "device":32902,
-                     "vendor":4663
-                  },
-                  "function":0,
-                  "regions":[
-
-                  ]
-               },
-               {
-                  "bus":0,
-                  "qdev_id":"",
-                  "slot":1,
-                  "class_info":{
-                     "class":1537,
-                     "desc":"ISA bridge"
-                  },
-                  "id":{
-                     "device":32902,
-                     "vendor":28672
-                  },
-                  "function":0,
-                  "regions":[
-
-                  ]
-               },
-               {
-                  "bus":0,
-                  "qdev_id":"",
-                  "slot":1,
-                  "class_info":{
-                     "class":257,
-                     "desc":"IDE controller"
-                  },
-                  "id":{
-                     "device":32902,
-                     "vendor":28688
-                  },
-                  "function":1,
-                  "regions":[
-                     {
-                        "bar":4,
-                        "size":16,
-                        "address":49152,
-                        "type":"io"
-                     }
-                  ]
-               },
-               {
-                  "bus":0,
-                  "qdev_id":"",
-                  "slot":2,
-                  "class_info":{
-                     "class":768,
-                     "desc":"VGA controller"
-                  },
-                  "id":{
-                     "device":4115,
-                     "vendor":184
-                  },
-                  "function":0,
-                  "regions":[
-                     {
-                        "prefetch":true,
-                        "mem_type_64":false,
-                        "bar":0,
-                        "size":33554432,
-                        "address":4026531840,
-                        "type":"memory"
-                     },
-                     {
-                        "prefetch":false,
-                        "mem_type_64":false,
-                        "bar":1,
-                        "size":4096,
-                        "address":4060086272,
-                        "type":"memory"
-                     },
-                     {
-                        "prefetch":false,
-                        "mem_type_64":false,
-                        "bar":6,
-                        "size":65536,
-                        "address":-1,
-                        "type":"memory"
-                     }
-                  ]
-               },
-               {
-                  "bus":0,
-                  "qdev_id":"",
-                  "irq":11,
-                  "slot":4,
-                  "class_info":{
-                     "class":1280,
-                     "desc":"RAM controller"
-                  },
-                  "id":{
-                     "device":6900,
-                     "vendor":4098
-                  },
-                  "function":0,
-                  "regions":[
-                     {
-                        "bar":0,
-                        "size":32,
-                        "address":49280,
-                        "type":"io"
-                     }
-                  ]
-               }
-            ]
-         }
-      ]
-   }
-
-Note: This example has been shortened as the real response is too long.
-
 query-command-line-options
 --------------------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 4b66a36..71eb9a4 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -1750,6 +1750,8 @@
 # @type: 'io' if the region is a PIO region
 #        'memory' if the region is a MMIO region
 #
+# @size: memory size
+#
 # @prefetch: #optional if @type is 'memory', true if the memory is prefetchable
 #
 # @mem_type_64: #optional if @type is 'memory', true if the BAR is 64-bit
@@ -1883,9 +1885,144 @@
 #
 # Return information about the PCI bus topology of the guest.
 #
-# Returns: a list of @PciInfo for each PCI bus
+# Returns: a list of @PciInfo for each PCI bus. Each bus is
+# represented by a json-object, which has a key with a json-array of
+# all PCI devices attached to it. Each device is represented by a
+# json-object.
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# -> { "execute": "query-pci" }
+# <- { "return": [
+#          {
+#             "bus": 0,
+#             "devices": [
+#                {
+#                   "bus": 0,
+#                   "qdev_id": "",
+#                   "slot": 0,
+#                   "class_info": {
+#                      "class": 1536,
+#                      "desc": "Host bridge"
+#                   },
+#                   "id": {
+#                      "device": 32902,
+#                      "vendor": 4663
+#                   },
+#                   "function": 0,
+#                   "regions": [
+#                   ]
+#                },
+#                {
+#                   "bus": 0,
+#                   "qdev_id": "",
+#                   "slot": 1,
+#                   "class_info": {
+#                      "class": 1537,
+#                      "desc": "ISA bridge"
+#                   },
+#                   "id": {
+#                      "device": 32902,
+#                      "vendor": 28672
+#                   },
+#                   "function": 0,
+#                   "regions": [
+#                   ]
+#                },
+#                {
+#                   "bus": 0,
+#                   "qdev_id": "",
+#                   "slot": 1,
+#                   "class_info": {
+#                      "class": 257,
+#                      "desc": "IDE controller"
+#                   },
+#                   "id": {
+#                      "device": 32902,
+#                      "vendor": 28688
+#                   },
+#                   "function": 1,
+#                   "regions": [
+#                      {
+#                         "bar": 4,
+#                         "size": 16,
+#                         "address": 49152,
+#                         "type": "io"
+#                      }
+#                   ]
+#                },
+#                {
+#                   "bus": 0,
+#                   "qdev_id": "",
+#                   "slot": 2,
+#                   "class_info": {
+#                      "class": 768,
+#                      "desc": "VGA controller"
+#                   },
+#                   "id": {
+#                      "device": 4115,
+#                      "vendor": 184
+#                   },
+#                   "function": 0,
+#                   "regions": [
+#                      {
+#                         "prefetch": true,
+#                         "mem_type_64": false,
+#                         "bar": 0,
+#                         "size": 33554432,
+#                         "address": 4026531840,
+#                         "type": "memory"
+#                      },
+#                      {
+#                         "prefetch": false,
+#                         "mem_type_64": false,
+#                         "bar": 1,
+#                         "size": 4096,
+#                         "address": 4060086272,
+#                         "type": "memory"
+#                      },
+#                      {
+#                         "prefetch": false,
+#                         "mem_type_64": false,
+#                         "bar": 6,
+#                         "size": 65536,
+#                         "address": -1,
+#                         "type": "memory"
+#                      }
+#                   ]
+#                },
+#                {
+#                   "bus": 0,
+#                   "qdev_id": "",
+#                   "irq": 11,
+#                   "slot": 4,
+#                   "class_info": {
+#                      "class": 1280,
+#                      "desc": "RAM controller"
+#                   },
+#                   "id": {
+#                      "device": 6900,
+#                      "vendor": 4098
+#                   },
+#                   "function": 0,
+#                   "regions": [
+#                      {
+#                         "bar": 0,
+#                         "size": 32,
+#                         "address": 49280,
+#                         "type": "io"
+#                      }
+#                   ]
+#                }
+#             ]
+#          }
+#       ]
+#    }
+#
+# Note: This example has been shortened as the real response is too long.
+#
 ##
 { 'command': 'query-pci', 'returns': ['PciInfo'] }
 
-- 
2.10.0

[Qemu-devel] [PATCH 25/30] qmp-commands: move 'quit' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 12 ------------
 qapi-schema.json      |  5 +++++
 2 files changed, 5 insertions(+), 12 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 0050067..3110f36 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -53,18 +53,6 @@ If you're planning to adopt QMP, please observe the following:
 Server's responses in the examples below are always a success response, please
 refer to the QMP specification for more details on error responses.
 
-quit
-----
-
-Quit the emulator.
-
-Arguments: None.
-
-Example:
-
--> { "execute": "quit" }
-<- { "return": {} }
-
 eject
 -----
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 71eb9a4..b159b86 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2035,6 +2035,11 @@
 # unexpected.
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# -> { "execute": "quit" }
+# <- { "return": {} }
 ##
 { 'command': 'quit' }
 
-- 
2.10.0

[Qemu-devel] [PATCH 26/30] qmp-commands: move 'stop' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 12 ------------
 qapi-schema.json      |  6 ++++++
 2 files changed, 6 insertions(+), 12 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 3110f36..bb3a5ea 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -111,18 +111,6 @@ Example:
 -> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
 <- { "return": {} }
 
-stop
-----
-
-Stop the emulator.
-
-Arguments: None.
-
-Example:
-
--> { "execute": "stop" }
-<- { "return": {} }
-
 cont
 ----
 
diff --git a/qapi-schema.json b/qapi-schema.json
index b159b86..0fbff1e 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2054,6 +2054,12 @@
 #         state.  In "inmigrate" state, it will ensure that the guest
 #         remains paused once migration finishes, as if the -S option was
 #         passed on the command line.
+#
+# Example:
+#
+# -> { "execute": "stop" }
+# <- { "return": {} }
+#
 ##
 { 'command': 'stop' }
 
-- 
2.10.0

[Qemu-devel] [PATCH 27/30] qmp-commands: move 'system_reset' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 12 ------------
 qapi-schema.json      |  6 ++++++
 2 files changed, 6 insertions(+), 12 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index bb3a5ea..9bd5afa 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -135,18 +135,6 @@ Example:
 -> { "execute": "system_wakeup" }
 <- { "return": {} }
 
-system_reset
-------------
-
-Reset the system.
-
-Arguments: None.
-
-Example:
-
--> { "execute": "system_reset" }
-<- { "return": {} }
-
 system_powerdown
 ----------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 0fbff1e..cb90e9e 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2069,6 +2069,12 @@
 # Performs a hard reset of a guest.
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# -> { "execute": "system_reset" }
+# <- { "return": {} }
+#
 ##
 { 'command': 'system_reset' }
 
-- 
2.10.0

[Qemu-devel] [PATCH 28/30] qmp-commands: move 'system_powerdown' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 12 ------------
 qapi-schema.json      |  5 +++++
 2 files changed, 5 insertions(+), 12 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 9bd5afa..5b562df 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -135,18 +135,6 @@ Example:
 -> { "execute": "system_wakeup" }
 <- { "return": {} }
 
-system_powerdown
-----------------
-
-Send system power down event.
-
-Arguments: None.
-
-Example:
-
--> { "execute": "system_powerdown" }
-<- { "return": {} }
-
 device_add
 ----------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index cb90e9e..13a1417 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2089,6 +2089,11 @@
 #        returning does not indicate that a guest has accepted the request or
 #        that it has shut down.  Many guests will respond to this command by
 #        prompting the user in some way.
+# Example:
+#
+# -> { "execute": "system_powerdown" }
+# <- { "return": {} }
+#
 ##
 { 'command': 'system_powerdown' }
 
-- 
2.10.0

[Qemu-devel] [PATCH 29/30] qmp-commands: move 'cpu-add' doc to schema

[Marc-André Lureau]

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 14 --------------
 qapi-schema.json      |  5 +++++
 2 files changed, 5 insertions(+), 14 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 5b562df..2a47041 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -217,20 +217,6 @@ Example:
 
 Note: CPUs' indexes are obtained with the 'query-cpus' command.
 
-cpu-add
--------
-
-Adds virtual cpu
-
-Arguments:
-
-- "id": cpu id (json-int)
-
-Example:
-
--> { "execute": "cpu-add", "arguments": { "id": 2 } }
-<- { "return": {} }
-
 memsave
 -------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 13a1417..4a8c5d7 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2118,6 +2118,11 @@
 # Returns: Nothing on success
 #
 # Since 1.5
+#
+# Example:
+#
+# -> { "execute": "cpu-add", "arguments": { "id": 2 } }
+# <- { "return": {} }
 ##
 { 'command': 'cpu-add', 'data': {'id': 'int'} }
 
-- 
2.10.0

[Qemu-devel] [PATCH 30/30] qmp-commands: move 'memsave' doc to schema

[Marc-André Lureau]

Notice that "cpu" argument is actually "cpu-index" in the json.

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/qmp-commands.txt | 20 --------------------
 qapi-schema.json      |  9 +++++++++
 2 files changed, 9 insertions(+), 20 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 2a47041..280e337 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -217,26 +217,6 @@ Example:
 
 Note: CPUs' indexes are obtained with the 'query-cpus' command.
 
-memsave
--------
-
-Save to disk virtual memory dump starting at 'val' of size 'size'.
-
-Arguments:
-
-- "val": the starting address (json-int)
-- "size": the memory size, in bytes (json-int)
-- "filename": file path (json-string)
-- "cpu": virtual CPU index (json-int, optional)
-
-Example:
-
--> { "execute": "memsave",
-             "arguments": { "val": 10,
-                            "size": 100,
-                            "filename": "/tmp/virtual-mem-dump" } }
-<- { "return": {} }
-
 pmemsave
 --------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 4a8c5d7..1ea8903 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2145,6 +2145,15 @@
 # Since: 0.14.0
 #
 # Notes: Errors were not reliably returned until 1.1
+#
+# Example:
+#
+# -> { "execute": "memsave",
+#      "arguments": { "val": 10,
+#                     "size": 100,
+#                     "filename": "/tmp/virtual-mem-dump" } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'memsave',
   'data': {'val': 'int', 'size': 'int', 'filename': 'str', '*cpu-index': 'int'} }
-- 
2.10.0

Re: [Qemu-devel] [PATCH 30/30] qmp-commands: move 'memsave' doc to schema

[Eric Blake]

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

On 09/13/2016 08:02 AM, Marc-André Lureau wrote:
> Notice that "cpu" argument is actually "cpu-index" in the json.

Indeed; proof that the duplication hasn't always been faithful, and that
getting rid of it is a good thing.

> 
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> ---
>  docs/qmp-commands.txt | 20 --------------------
>  qapi-schema.json      |  9 +++++++++
>  2 files changed, 9 insertions(+), 20 deletions(-)
> 

For the remaining patches in this series,
Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
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 --]

Re: [Qemu-devel] [PATCH 00/30] Move qapi documentation to schema (part 1/5)

[Markus Armbruster]

Marc-André Lureau <marcandre.lureau@redhat.com> writes:

> Hi,
>
> The QAPI documentation is currently done in two places, the json
> schema and a more human-friendly text file. The goal is to avoid
> duplication and to generate friendly versions from the schema (pdf,
> man etc).  Thus, all documentation should be moved to the schema.
>
> In order to facilitate the review, the documentation move has been
> splitted, and is going to sent by chunks of ~30 patches. This way it
> should take about 5 series to complete (~150 patches). I suggest that
> the qapi maintainers (Markus/Eric) compile the reviewed patches in a
> branch and merge upstream in one go (either merging move commits or
> not) when the series complete and the documentation is finally
> generated to avoid an in-between state.
>
> The wip branch with all the pending patches:
> https://github.com/elmarco/qemu/commits/qapi-doc

Ah, now I understand why you asked whether to post everything!  The
"move FOO doc to schema" patches make no sense until the very end of the
full branch, when you actually generate documentation from the schema.

Perhaps you could structure like this:

1. Fix existing issues in QAPI schema comments

2. Generate documentation from it (not a replacement for
   qmp-commands.txt, yet)

3. Merge qmp-commands.txt into QAPI schema comments, step by step

   (a) If you only update the QAPI schema comments, qmp-commands.txt
   stays intact throughout this work.

   (b) If you delete qmp-commands.txt section as you cover them in the
   QAPI schema, command documentation regresses temporarily.  Tolerable,
   but needs to be explained in commit messages.  Your choice.

4. Generated documentation now contains everything qmp-commands.txt
   contains; delete qmp-commands.txt

Getting to this structure with option (3b) could be as simple as
reordering your branch.

> And a sneak peek of the generated pdf documentation:
> https://fedorapeople.org/~elmarco/qemu-qapi.pdf

Looks slick :)

> The series is currently based on Markus qapi-next branch.

Re: [Qemu-devel] [PATCH 00/30] Move qapi documentation to schema (part 1/5)

[Marc-André Lureau]

Hi

----- Original Message -----
> Marc-André Lureau <marcandre.lureau@redhat.com> writes:
> 
> > Hi,
> >
> > The QAPI documentation is currently done in two places, the json
> > schema and a more human-friendly text file. The goal is to avoid
> > duplication and to generate friendly versions from the schema (pdf,
> > man etc).  Thus, all documentation should be moved to the schema.
> >
> > In order to facilitate the review, the documentation move has been
> > splitted, and is going to sent by chunks of ~30 patches. This way it
> > should take about 5 series to complete (~150 patches). I suggest that
> > the qapi maintainers (Markus/Eric) compile the reviewed patches in a
> > branch and merge upstream in one go (either merging move commits or
> > not) when the series complete and the documentation is finally
> > generated to avoid an in-between state.
> >
> > The wip branch with all the pending patches:
> > https://github.com/elmarco/qemu/commits/qapi-doc
> 
> Ah, now I understand why you asked whether to post everything!  The
> "move FOO doc to schema" patches make no sense until the very end of the
> full branch, when you actually generate documentation from the schema.
> 
> Perhaps you could structure like this:
> 
> 1. Fix existing issues in QAPI schema comments
> 
> 2. Generate documentation from it (not a replacement for
>    qmp-commands.txt, yet)
> 
> 3. Merge qmp-commands.txt into QAPI schema comments, step by step
> 
>    (a) If you only update the QAPI schema comments, qmp-commands.txt
>    stays intact throughout this work.
> 
>    (b) If you delete qmp-commands.txt section as you cover them in the
>    QAPI schema, command documentation regresses temporarily.  Tolerable,
>    but needs to be explained in commit messages.  Your choice.
> 
> 4. Generated documentation now contains everything qmp-commands.txt
>    contains; delete qmp-commands.txt
> 
> Getting to this structure with option (3b) could be as simple as
> reordering your branch.

3(a) makes it hard to check that everything has been moved properly, while removing 3(b) makes it clear what is removed and adjusted in the corresponding schema doc, and by the end of 3(b) it's clear that nothing has been left behind.

Generating the documentation before the end of 3(b) will also lead to temporarily incomplete generated doc, and will conflict with existing qmp-commands.txt.

That's why I think the best solution is to go through 3(b) now, collect the move in a branch and push it in one go when qmp-commands.txt is empty and the doc is generated.