Re: [Qemu-devel] [PATCH 1/2] QMP: Introduce commands doc

[Markus Armbruster]

Luiz Capitulino <address@hidden> writes:

> One of the most important missing feature in QMP today is its
> supported command documentation.
>
> The plan is to make it part of self-description support, however
> self-description is a big task we have been postponing for a
> long time now and still don't know when it's going to be done.
>
> In order not to compromise QMP adoption and make users' life easier,
> this commit adds a simple text documentation which fully describes
> all QMP supported commands.
>
> This is not ideal for a number of reasons (harder to maintain,
> text-only, etc) but is a lot better than the current situation.
>
> Signed-off-by: Luiz Capitulino <address@hidden>
> ---
>  QMP/qmp-commands.txt |  859 
> ++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 859 insertions(+), 0 deletions(-)
>  create mode 100644 QMP/qmp-commands.txt
>
> diff --git a/QMP/qmp-commands.txt b/QMP/qmp-commands.txt
> new file mode 100644
> index 0000000..2f9c448
> --- /dev/null
> +++ b/QMP/qmp-commands.txt
> @@ -0,0 +1,859 @@
> +                        QMP Supported Commands
> +                        ----------------------
> +
> +This document describes all commands currently supported by QMP.
> +
> +Most of the time their usage is exactly the same as in the user Monitor,
> +this means that any other document which also describe commands (the manpage,
> +QEMU's manual, etc) can and should be consulted.
> +
> +QMP has two types of commands: regular and query commands. Regular commands
> +usually change the Virtual Machine's state someway, while query commands just
> +return information. The sections below are divided accordingly.
> +
> +It's also important to observe that the 'example' subsection is different
> +for regular and query commands. For the former, a complete input line as it
> +should be issued by the Client is shown. For the latter, what is shown is
> +the complete Server response, whose members might be in different order when
> +in real protocol usage.
> +
> +Please, refert to the QMP specification (QMP/qmp-spec.txt file) for detailed
> +information on the Server command and response formats.
> +
> +NOTE: This document is temporary and will be replaced soon.
> +
> +1. Regular Commands
> +===================
> +
> +balloon
> +-------
> +
> +Request VM to change its memory allocation (in bytes).
> +
> +Arguments:
> +
> +- "value": New memory allocation (json-int)
> +
> +Example:
> +
> +{ "execute": "balloon", "arguments": { "value": 536870912 } }
> +
> +block_passwd
> +------------
> +
> +Set the password of encrypted block devices.
> +
> +Arguments:
> +
> +- "device": device name (json-string)
> +- "password": password (json-string)
> +
> +Example:
> +
> +{ "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
> +                                            "password": "12345" } }
> +
> +change
> +------
> +
> +Change a removable medium or VNC configuration.
> +
> +Arguments:
> +
> +- "device": device name (json-string)
> +- "target": filename or item (json-string)
> +- "arg": additional argument (json-string, optional)
> +
> +Examples:
> +
> +{ "execute": "change",
> +             "arguments": { "device": "ide1-cd0",
> +                            "target": "/srv/images/Fedora-12-x86_64-DVD.iso" 
> } }
> +
> +{ "execute": "change",
> +             "arguments": { "device": "vnc",
> +                            "target": "password",
> +                            "arg": "foobar1" } }
> +
> +closefd
> +-------
> +
> +Close a file descriptor previously passed via SCM rights.
> +
> +Arguments:
> +
> +- "fdname": file descriptor name (json-string)
> +
> +Example:
> +
> +{ "execute": "closefd", "arguments": { "name": "fd1" } }

Example argument is wrong ("name" instead of "fdname").

> +
> +cont
> +----
> +
> +Resume emulation.
> +
> +Arguments: None.
> +
> +Example:
> +
> +{ "execute": "cont" }
> +
> +cpu
> +---
> +
> +Set the default CPU.
> +
> +Arguments:
> +
> +- "index": the CPU's index (json-int)
> +
> +Example:
> +
> +{ "execute": "cpu", "arguments": { "index": 0 } }
> +
> +Note: CPUs' indexes are obtained with the 'query-cpus' command.
> +
> +device_add
> +----------
> +
> +Add a device.
> +
> +Arguments:
> +
> +- "driver": the name of the new device's driver (json-string)
> +- "bus": the device's parent bus (device tree path, json-string)

"bus" is optional (see your example below).

> +- "id": the device's ID, must be unique (json-string)
> +- device properties
> +
> +Example:
> +
> +{ "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
> +
> +Note: For detailed information about this command, please refer to the
> +      'docs/qdev-device-use.txt' file.

What about pointing to "-device FOO,\?" here?  Lists device properties,
pretty crude, but better than nothing.

> +
> +device_del
> +----------
> +
> +Remove a device.
> +
> +Arguments:
> +
> +- "id": the device's ID (json-string)
> +
> +Example:
> +
> +{ "execute": "device_del", "arguments": { "id": "net1" } }
> +
> +eject
> +-----
> +
> +Eject a removable medium.
> +
> +Arguments: 
> +
> +- force: force ejection (json-bool, optional)
> +- device: device name (json-string)
> +
> +Example:
> +
> +{ "execute": "eject", "arguments": { "device": "ide1-cd0" } }
> +
> +Note: The "force" argument defaults to false.
> +
> +getfd
> +-----
> +
> +Receive a file descriptor via SCM rights and assign it a name.
> +
> +Arguments:
> +
> +- "fdname": file descriptor name (json-string)
> +
> +Example:
> +
> +{ "execute": "getfd", "arguments": { "name": "fd1" } }

Example argument is wrong ("name" instead of "fdname").

> +
> +memsave
> +-------
> +
> +Save to disk virtual memory dump starting at 'val' of size 'size'.
> +
> +Arguments:
> +
> +- "val": the starting address (json-int)
> +- "size": the memory size (json-int)
> +- "filename": file path (json-string)
> +
> +Example:
> +
> +{ "execute": "memsave",
> +             "arguments": { "val": 10,
> +                            "size": 100,
> +                            "filename": "/tmp/virtual-mem-dump" } }
> +
> +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, optional)

I don't think "uri" is optional.

> +
> +Example:
> +
> +{ "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
> +
> +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

Don't they always default to false?

> +(3) The user Monitor's "detach" argument is invalid in QMP and should not
> +    be used

Then why do we accept it?

> +
> +migrate_cancel
> +--------------
> +
> +Cancel the current migration.
> +
> +Arguments: None.
> +
> +Example:
> +
> +{ "execute": "migrate_cancel" }
> +
> +migrate_set_downtime
> +--------------------
> +
> +Set maximum tolerated downtime (in seconds) for migrations.
> +
> +Arguments:
> +
> +- "value": maximum downtime (json-number)
> +
> +Example:
> +
> +{ "execute": "migrate_set_downtime", "arguments": { "value": 60 } }
> +
> +migrate_set_speed
> +-----------------
> +
> +Set maximum speed (in bytes) for migrations.

"bytes" is not a unit of speed.  Same problem in qemu-monitor.hx.  If
it's good enough there...

> +
> +Arguments:
> +
> +- "value": maximum speed (json-number)
> +
> +Example:
> +
> +{ "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
> +
> +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

What about a pointer to device option documentation here?

> +
> +Example:
> +
> +{ "execute": "netdev_add", "arguments": { "type": "user", "id": "netdev1" } }
> +
> +netdev_del
> +----------
> +
> +Remove host network device.
> +
> +Arguments:
> +
> +- "id": the device's ID, must be unique (json-string)
> +
> +Example:
> +
> +{ "execute": "netdev_del", "arguments": { "id": "netdev1" } }
> +
> +pmemsave
> +--------
> +
> +Save to disk physical memory dump starting at 'val' of size 'size'.
> +
> +Arguments:
> +
> +- "val": the starting address (json-int)
> +- "size": the memory size (json-int)
> +- "filename": file path (json-string)
> +
> +Example:
> +
> +{ "execute": "pmemsave",
> +             "arguments": { "val": 10,
> +                            "size": 100,
> +                            "filename": "/tmp/physical-mem-dump" } }
> +
> +qmp_capabilities
> +----------------
> +
> +Enable QMP capabilities.
> +
> +Arguments: None.
> +
> +Note: This command must be issued before issuing any other command.
> +
> +quit
> +----
> +
> +Quit the emulator.
> +
> +Arguments: None.
> +
> +Example:
> +
> +{ "execute": "quit" }
> +
> +screendump
> +----------
> +
> +Save screen into PPM image.
> +
> +Arguments:
> +
> +- "filename": file path (json-string)
> +
> +Example:
> +
> +{ "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
> +
> +set_link
> +--------
> +
> +Change the link status of a network adapter.
> +
> +Arguments:
> +
> +- "name": network device name (json-string)
> +- "up": status is up (json-bool)
> +
> +Example:
> +
> +{ "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
> +
> +stop
> +----
> +
> +Stop the emulator.
> +
> +Arguments: None.
> +
> +Example:
> +
> +{ "execute": "stop" }
> +
> +system_powerdown
> +----------------
> +
> +Send system power down event.
> +
> +Arguments: None.
> +
> +Example:
> +
> +{ "execute": "system_powerdown" }
> +
> +system_reset
> +------------
> +
> +Reset the system.
> +
> +Arguments: None.
> +
> +Example:
> +
> +{ "execute": "system_reset" }
[...]

I'll review the rest later.