[Qemu-devel] [CFR 0/10] QMP specification review (Part 2)

[Qemu-devel] [CFR 0/10] QMP specification review (Part 2)

[Stefan Hajnoczi]

This is the second set of commands as part of the QMP specification review.
Please comment on the individual commands specifications and Anthony and I will
try to fold the comments back into the command documentation.

[Qemu-devel] [CFR 1/10] qmp: getfd command

[Stefan Hajnoczi]

getfd
-----

Receive a file descriptor via SCM rights and assign it a name.

Arguments:

- "fdname": file descriptor name (json-string)

Example:

-> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
<- { "return": {} }

[Qemu-devel] [CFR 2/10] qmp: memsave command

[Stefan Hajnoczi]

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)

Example:

-> { "execute": "memsave",
             "arguments": { "val": 10,
                            "size": 100,
                            "filename": "/tmp/virtual-mem-dump" } }
<- { "return": {} }

Note: Depends on the current CPU.

[Qemu-devel] [CFR 3/10] qmp: migrate_cancel command

[Stefan Hajnoczi]

migrate_cancel
--------------

Cancel the current migration.

Arguments: None.

Example:

-> { "execute": "migrate_cancel" }
<- { "return": {} }

[Qemu-devel] [CFR 4/10] qmp: migrate_set_downtime command

[Stefan Hajnoczi]

migrate_set_downtime
--------------------

Set maximum tolerated downtime (in seconds) for migrations.

Arguments:

- "value": maximum downtime (json-number)

Example:

-> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
<- { "return": {} }

[Qemu-devel] [CFR 5/10] qmp: migrate_set_speed command

[Stefan Hajnoczi]

migrate_set_speed
-----------------

Set maximum speed for migrations.

Arguments:

- "value": maximum speed, in bytes per second (json-number)

Example:

-> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
<- { "return": {} }

[Qemu-devel] [CFR 6/10] qmp: migrate command

[Stefan Hajnoczi]

migrate
-------

Migrate to URI.

Arguments:

- "blk": block migration, full disk copy (json-bool, optional)
- "inc": incremental disk copy (json-bool, optional)
- "uri": Destination URI (json-string)

Example:

-> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
<- { "return": {} }

Notes:

(1) The 'query-migrate' command should be used to check migration's progress
    and final result (this information is provided by the 'status' member)
(2) All boolean arguments default to false
(3) The user Monitor's "detach" argument is invalid in QMP and should not
    be used

[Qemu-devel] [CFR 7/10] qmp: netdev_add command

[Stefan Hajnoczi]

netdev_add
----------

Add host network device.

Arguments:

- "type": the device type, "tap", "user", ... (json-string)
- "id": the device's ID, must be unique (json-string)
- device options

Example:

-> { "execute": "netdev_add", "arguments": { "type": "user", "id": "netdev1" } }
<- { "return": {} }

Note: The supported device options are the same ones supported by the '-net'
      command-line argument, which are listed in the '-help' output or QEMU's
      manual

[Qemu-devel] [CFR 8/10] qmp: netdev_del command

[Stefan Hajnoczi]

netdev_del
----------

Remove host network device.

Arguments:

- "id": the device's ID, must be unique (json-string)

Example:

-> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
<- { "return": {} }

[Qemu-devel] [CFR 9/10] qmp: pmemsave command

[Stefan Hajnoczi]

pmemsave
--------

Save to disk physical 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)

Example:

-> { "execute": "pmemsave",
             "arguments": { "val": 10,
                            "size": 100,
                            "filename": "/tmp/physical-mem-dump" } }
<- { "return": {} }

[Qemu-devel] [CFR 10/10] qmp: query_balloon command

[Stefan Hajnoczi]

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)
- "mem_swapped_in": Amount of memory swapped in bytes (json-int, optional)
- "mem_swapped_out": Amount of memory swapped out in bytes (json-int, optional)
- "major_page_faults": Number of major faults (json-int, optional)
- "minor_page_faults": Number of minor faults (json-int, optional)
- "free_mem": Total amount of free and unused memory in
              bytes (json-int, optional)
- "total_mem": Total amount of available memory in bytes (json-int, optional)

Example:

-> { "execute": "query-balloon" }
<- {
      "return":{
         "actual":1073741824,
         "mem_swapped_in":0,
         "mem_swapped_out":0,
         "major_page_faults":142,
         "minor_page_faults":239245,
         "free_mem":1014185984,
         "total_mem":1044668416
      }
   }

Re: [Qemu-devel] [CFR 0/10] QMP specification review (Part 2)

[Blue Swirl]

On Wed, Jun 16, 2010 at 3:45 PM, Stefan Hajnoczi
<stefanha@linux.vnet.ibm.com> wrote:
> This is the second set of commands as part of the QMP specification review.
> Please comment on the individual commands specifications and Anthony and I will
> try to fold the comments back into the command documentation.

Should the specification also list possible errors?

Are there any return values?

[Qemu-devel] Re: [CFR 1/10] qmp: getfd command

[Anthony Liguori]

On 06/16/2010 10:45 AM, Stefan Hajnoczi wrote:
> getfd
> -----
>
> Receive a file descriptor via SCM rights and assign it a name.
>    

As with the sendfd command, I think we should make this a QMP top-level 
operation.  It's very transport specific.

Luiz/Markus, any thoughts on this?

Regards,

Anthony Liguori

> Arguments:
>
> - "fdname": file descriptor name (json-string)
>
> Example:
>
> ->  { "execute": "getfd", "arguments": { "fdname": "fd1" } }
> <- { "return": {} }
>
>    

[Qemu-devel] Re: [CFR 2/10] qmp: memsave command

[Anthony Liguori]

On 06/16/2010 10:45 AM, Stefan Hajnoczi wrote:
> memsave
> -------
>
> Save to disk virtual memory dump starting at 'val' of size 'size'.
>
> Arguments:
>
> - "val": the starting address (json-int)
>    

s/val/address/

> - "size": the memory size, in bytes (json-int)
>    

The number of bytes to dump.

> - "filename": file path (json-string)
>    

We really ought to return this memory as a Base64 encoded blob.

> Example:
>
> ->  { "execute": "memsave",
>               "arguments": { "val": 10,
>                              "size": 100,
>                              "filename": "/tmp/virtual-mem-dump" } }
> <- { "return": {} }
>
> Note: Depends on the current CPU.
>    

Ought to take a cpu_id and avoid the silliness of current CPU.

What happens if the virtual address range is non-existent?  What if it's 
only partially mapped?

Regards,

Anthony Liguori

[Qemu-devel] Re: [CFR 3/10] qmp: migrate_cancel command

[Anthony Liguori]

On 06/16/2010 10:45 AM, Stefan Hajnoczi wrote:
> migrate_cancel
> --------------
>
> Cancel the current migration.
>    

What if there is no pending migration?

Regards,

Anthony Liguori

> Arguments: None.
>
> Example:
>
> ->  { "execute": "migrate_cancel" }
> <- { "return": {} }
>    

[Qemu-devel] Re: [CFR 4/10] qmp: migrate_set_downtime command

[Anthony Liguori]

On 06/16/2010 10:45 AM, Stefan Hajnoczi wrote:
> migrate_set_downtime
> --------------------
>
> Set maximum tolerated downtime (in seconds) for migrations.
>    

We should clarify that this is a downtime target but not a hard guarantee.

> Arguments:
>
> - "value": maximum downtime (json-number)
>    

s/value/seconds/

Regards,

Anthony Liguori

> Example:
>
> ->  { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
> <- { "return": {} }
>
>    

[Qemu-devel] Re: [CFR 5/10] qmp: migrate_set_speed command

[Anthony Liguori]

On 06/16/2010 10:45 AM, Stefan Hajnoczi wrote:
> migrate_set_speed
> -----------------
>
> Set maximum speed for migrations.
>    

Sets the target bandwidth usage for migration.  We should mention that 
this command can be used during a live migration and that the default 
value is 32MB/sec.  We should also mention that during the final stage 
of migration, the bandwidth limit is not respected in order to meet 
downtime requirements.

> Arguments:
>
> - "value": maximum speed, in bytes per second (json-number)
>    

s/value/bandwidth/

Regards,

Anthony Liguori

> Example:
>
> ->  { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
> <- { "return": {} }
>    

[Qemu-devel] Re: [CFR 6/10] qmp: migrate command

[Anthony Liguori]

On 06/16/2010 10:45 AM, Stefan Hajnoczi wrote:
> migrate
> -------
>
> Migrate to URI.
>    

This command will not be compatible with 0.14.

Regards,

Anthony Liguori

> Arguments:
>
> - "blk": block migration, full disk copy (json-bool, optional)
> - "inc": incremental disk copy (json-bool, optional)
> - "uri": Destination URI (json-string)
>
> Example:
>
> ->  { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
> <- { "return": {} }
>
> Notes:
>
> (1) The 'query-migrate' command should be used to check migration's progress
>      and final result (this information is provided by the 'status' member)
> (2) All boolean arguments default to false
> (3) The user Monitor's "detach" argument is invalid in QMP and should not
>      be used
>    

[Qemu-devel] Re: [CFR 7/10] qmp: netdev_add command

[Anthony Liguori]

On 06/16/2010 10:45 AM, Stefan Hajnoczi wrote:
> netdev_add
> ----------
>
> Add host network device.
>
> Arguments:
>
> - "type": the device type, "tap", "user", ... (json-string)
> - "id": the device's ID, must be unique (json-string)
> - device options
>    

I'd like to see those options enumerated in the spec.

We need to enumerate all of the failure conditions too.

Regards,

Anthony Liguori

> Example:
>
> ->  { "execute": "netdev_add", "arguments": { "type": "user", "id": "netdev1" } }
> <- { "return": {} }
>
> Note: The supported device options are the same ones supported by the '-net'
>        command-line argument, which are listed in the '-help' output or QEMU's
>        manual
>
>    

[Qemu-devel] Re: [CFR 8/10] qmp: netdev_del command

[Anthony Liguori]

On 06/16/2010 10:45 AM, Stefan Hajnoczi wrote:
> netdev_del
> ----------
>
> Remove host network device.
>
> Arguments:
>
> - "id": the device's ID, must be unique (json-string)
>    

Missing failure conditions.

Regards,

Anthony Liguori

> Example:
>
> ->  { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
> <- { "return": {} }
>
>    

[Qemu-devel] Re: [CFR 9/10] qmp: pmemsave command

[Anthony Liguori]

On 06/16/2010 10:45 AM, Stefan Hajnoczi wrote:
> pmemsave
> --------
>
> Save to disk physical memory dump starting at 'val' of size 'size'.
>    

Same feedback as for memsave.

Regards,

Anthony Liguori

> Arguments:
>
> - "val": the starting address (json-int)
> - "size": the memory size, in bytes (json-int)
> - "filename": file path (json-string)
>
> Example:
>
> ->  { "execute": "pmemsave",
>               "arguments": { "val": 10,
>                              "size": 100,
>                              "filename": "/tmp/physical-mem-dump" } }
> <- { "return": {} }
>
>    

[Qemu-devel] Re: [CFR 10/10] qmp: query_balloon command

[Anthony Liguori]

On 06/16/2010 10:46 AM, Stefan Hajnoczi wrote:
> query-balloon
> -------------
>
> Show balloon information.
>
> Make an asynchronous request for balloon info.

s/asynchronous//.  All requests are asynchronous.

>   When the request completes a
> json-object will be returned containing the following data:
>
> - "actual": current balloon value in bytes (json-int)
> - "mem_swapped_in": Amount of memory swapped in bytes (json-int, optional)
> - "mem_swapped_out": Amount of memory swapped out in bytes (json-int, optional)
> - "major_page_faults": Number of major faults (json-int, optional)
> - "minor_page_faults": Number of minor faults (json-int, optional)
> - "free_mem": Total amount of free and unused memory in
>                bytes (json-int, optional)
> - "total_mem": Total amount of available memory in bytes (json-int, optional)
>    

Should mention the behavior when a timeout occurs.

Regards,

Anthony Liguori

> Example:
>
> ->  { "execute": "query-balloon" }
> <- {
>        "return":{
>           "actual":1073741824,
>           "mem_swapped_in":0,
>           "mem_swapped_out":0,
>           "major_page_faults":142,
>           "minor_page_faults":239245,
>           "free_mem":1014185984,
>           "total_mem":1044668416
>        }
>     }
>
>    

Re: [Qemu-devel] [CFR 1/10] qmp: getfd command

[Stefan Hajnoczi]

It is unclear how getfd works.  Do you send the SCM_CREDENTIALS
ancillary data together with the getfd QMP command?

Would be nice to have this documented.

Stefan

Re: [Qemu-devel] [CFR 2/10] qmp: memsave command

[Stefan Hajnoczi]

On Wed, Jun 16, 2010 at 4:45 PM, Stefan Hajnoczi
<stefanha@linux.vnet.ibm.com> wrote:
> 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)
>
> Example:
>
> -> { "execute": "memsave",
>             "arguments": { "val": 10,
>                            "size": 100,
>                            "filename": "/tmp/virtual-mem-dump" } }
> <- { "return": {} }
>
> Note: Depends on the current CPU.

Is the guest paused during memsave?  This should be documented.

Stefan

Re: [Qemu-devel] [CFR 4/10] qmp: migrate_set_downtime command

[Stefan Hajnoczi]

On Wed, Jun 16, 2010 at 4:45 PM, Stefan Hajnoczi
<stefanha@linux.vnet.ibm.com> wrote:
> migrate_set_downtime
> --------------------
>
> Set maximum tolerated downtime (in seconds) for migrations.
>
> Arguments:
>
> - "value": maximum downtime (json-number)
>
> Example:
>
> -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
> <- { "return": {} }

What are the semantics of this value?  I imagine it has to do with the rate of
transferring dirty pages and deciding when to suspend the machine to perform
the final steps of migration.

Is there a need to query this value, too?  The ability to set the value is
probably enough, I can't think of a situation where you need to query it rather
than just setting a new value.

Can this value be changed once migration is in progress?

Stefan

Re: [Qemu-devel] [CFR 5/10] qmp: migrate_set_speed command

[Stefan Hajnoczi]

On Wed, Jun 16, 2010 at 4:45 PM, Stefan Hajnoczi
<stefanha@linux.vnet.ibm.com> wrote:
> migrate_set_speed
> -----------------
>
> Set maximum speed for migrations.
>
> Arguments:
>
> - "value": maximum speed, in bytes per second (json-number)
>
> Example:
>
> -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
> <- { "return": {} }

Can this value be changed during migration?  (Yes)

Stefan

Re: [Qemu-devel] [CFR 8/10] qmp: netdev_del command

[Stefan Hajnoczi]

On Wed, Jun 16, 2010 at 4:45 PM, Stefan Hajnoczi
<stefanha@linux.vnet.ibm.com> wrote:
> netdev_del
> ----------
>
> Remove host network device.
>
> Arguments:
>
> - "id": the device's ID, must be unique (json-string)
>
> Example:
>
> -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
> <- { "return": {} }

What happens to the guest network device?  Does the guest network device need
to be removed first in order for netdev_del to succeed?

Stefan

Re: [Qemu-devel] Re: [CFR 10/10] qmp: query_balloon command

[Stefan Hajnoczi]

On Wed, Jun 16, 2010 at 7:54 PM, Anthony Liguori
<aliguori@linux.vnet.ibm.com> wrote:
> On 06/16/2010 10:46 AM, Stefan Hajnoczi wrote:
>>
>> query-balloon
>> -------------
>>
>> Show balloon information.
>>
>> Make an asynchronous request for balloon info.
>
> s/asynchronous//.  All requests are asynchronous.

It would be helpful to indicate that this command requires guest
cooperation and is therefore not guaranteed to complete quickly.

Stefan