[Qemu-devel] [PATCH v2] migration: Improve QMP documentation

[Qemu-devel] [PATCH v2] migration: Improve QMP documentation

[Juan Quintela]

v2:
Add Markus sugestions:

Signed-off-by: Juan Quintela <quintela@redhat.com>
---
 qmp-commands.hx | 50 ++++++++++++++++++++++++++++++--------------------
 1 file changed, 30 insertions(+), 20 deletions(-)

diff --git a/qmp-commands.hx b/qmp-commands.hx
index 95022e2..a2c0c6b 100644
--- a/qmp-commands.hx
+++ b/qmp-commands.hx
@@ -644,7 +644,7 @@ EQMP

 SQMP
 migrate-set-cache-size
----------------------
+----------------------

 Set cache size to be used by XBZRLE migration, the cache size will be rounded
 down to the nearest power of 2
@@ -667,7 +667,7 @@ EQMP

 SQMP
 query-migrate-cache-size
----------------------
+------------------------

 Show cache size to be used by XBZRLE migration

@@ -2438,25 +2438,35 @@ The main json-object contains the following:
                 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 (in bytes):
-         - "transferred": amount transferred (json-int)
-         - "remaining": amount remaining (json-int)
-         - "total": total (json-int)
-         - "duplicate": number of duplicated pages (json-int)
-         - "normal" : number of normal pages transferred (json-int)
-         - "normal-bytes" : number of normal bytes transferred (json-int)
+  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.
+         - "normal" : number of whole pages transfered.  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)
 - "disk": only present if "status" is "active" and it is a block migration,
-  it is a json-object with the following disk information (in bytes):
-         - "transferred": amount transferred (json-int)
-         - "remaining": amount remaining (json-int)
-         - "total": total (json-int)
+  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
-         - "bytes": total XBZRLE bytes transferred
+         - "cache-size": XBZRLE cache size in bytes
+         - "bytes": total XBZRLE bytes transferred as xbzrle pages
          - "pages": number of XBZRLE compressed pages
-         - "cache-miss": number of cache misses
-         - "overflow": number of XBZRLE overflows
+         - "cache-miss": number 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
@@ -2567,11 +2577,11 @@ EQMP

 SQMP
 migrate-set-capabilities
--------
+------------------------

 Enable/Disable migration capabilities

-- "xbzrle": xbzrle support
+- "xbzrle": XBZRLE support

 Arguments:

@@ -2590,7 +2600,7 @@ EQMP
     },
 SQMP
 query-migrate-capabilities
--------
+--------------------------

 Query current migration capabilities

-- 
1.8.1.4

Re: [Qemu-devel] [PATCH v2] migration: Improve QMP documentation

[Eric Blake]

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

On 03/06/2013 11:26 AM, Juan Quintela wrote:
> v2:
> Add Markus sugestions:

If you keep this in the commit message, then

s/sugestions/suggestions/

> 
> Signed-off-by: Juan Quintela <quintela@redhat.com>
> ---

But it's better to stick patch changelog (your v2 comment) here, after
the ---, since it is nice for reviewers but useless information in the
git logs.

> +         - "duplicate": number of pages filled entirely with the same
> +            byte (json-int)
> +	    These are sent over the wire much more efficiently.

TAB damage.

Contents look fine, so  once the commit message and whitespace is fixed,
feel free to add:
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: 621 bytes --]

Re: [Qemu-devel] [PATCH v2] migration: Improve QMP documentation

[Markus Armbruster]

Juan Quintela <quintela@redhat.com> writes:

> v2:
> Add Markus sugestions:

This needs to go below the --- line.

> Signed-off-by: Juan Quintela <quintela@redhat.com>
> ---
>  qmp-commands.hx | 50 ++++++++++++++++++++++++++++++--------------------
>  1 file changed, 30 insertions(+), 20 deletions(-)
>
> diff --git a/qmp-commands.hx b/qmp-commands.hx
> index 95022e2..a2c0c6b 100644
> --- a/qmp-commands.hx
> +++ b/qmp-commands.hx
> @@ -644,7 +644,7 @@ EQMP
>
>  SQMP
>  migrate-set-cache-size
> ----------------------
> +----------------------
>
>  Set cache size to be used by XBZRLE migration, the cache size will be rounded
>  down to the nearest power of 2
> @@ -667,7 +667,7 @@ EQMP
>
>  SQMP
>  query-migrate-cache-size
> ----------------------
> +------------------------
>
>  Show cache size to be used by XBZRLE migration
>
> @@ -2438,25 +2438,35 @@ The main json-object contains the following:
>                  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 (in bytes):
> -         - "transferred": amount transferred (json-int)
> -         - "remaining": amount remaining (json-int)
> -         - "total": total (json-int)
> -         - "duplicate": number of duplicated pages (json-int)
> -         - "normal" : number of normal pages transferred (json-int)
> -         - "normal-bytes" : number of normal bytes transferred (json-int)
> +  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.

Tab damage.

> +         - "normal" : number of whole pages transfered.  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)
>  - "disk": only present if "status" is "active" and it is a block migration,
> -  it is a json-object with the following disk information (in bytes):
> -         - "transferred": amount transferred (json-int)
> -         - "remaining": amount remaining (json-int)
> -         - "total": total (json-int)
> +  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
> -         - "bytes": total XBZRLE bytes transferred

Suggest

         - "bytes": number of bytes transferred for XBZRLE compressed pages


> +         - "cache-size": XBZRLE cache size in bytes
> +         - "bytes": total XBZRLE bytes transferred as xbzrle pages
>           - "pages": number of XBZRLE compressed pages
> -         - "cache-miss": number of cache misses
> -         - "overflow": number of XBZRLE overflows
> +         - "cache-miss": number 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
[...]