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

[Qemu-devel] [PATCH 00/30] Move qapi documentation to schema (part 2/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 'pmemsave' doc to schema
  qmp-commands: move 'cont' doc to schema
  qmp-commands: move 'system_wakeup' doc to schema
  qmp-commands: move 'inject-nmi' doc to schema
  qmp-commands: move 'set_link' doc to schema
  qmp-commands: move 'balloon' doc to schema
  qmp-commands: move 'transaction' doc to schema
  qmp-commands: move 'human-monitor-command' doc to schema
  qmp-commands: move 'migrate_cancel' doc to schema
  qmp-commands: move 'migrate_set_downtime' doc to schema
  qmp-commands: move 'migrate_set_speed' doc to schema
  qmp-commands: move 'query-migrate-cache-size' doc to schema
  qmp-commands: move 'set_password' doc to schema
  qmp-commands: move 'expire_password' doc to schema
  qmp-commands: move 'change' doc to schema
  qmp-commands: move 'migrate' doc to schema
  qmp-commands: move 'migrate-incoming' doc to schema
  qmp-commands: move 'xen-save-devices-state' doc to schema
  qmp-commands: move 'xen-set-global-dirty-log' doc to schema
  qmp-commands: move 'device_del' doc to schema
  qmp-commands: move 'dump-guest-memory' doc to schema
  qmp-commands: move 'query-dump-guest-memory-capability' doc to schema
  qmp-commands: move 'dump-skeys' doc to schema
  qmp-commands: move 'netdev_add' doc to schema
  qmp-commands: move 'netdev_del' doc to schema
  qmp-commands: move 'object-add' doc to schema
  qmp-commands: move 'object-del' doc to schema
  qmp-commands: move 'getfd' doc to schema
  qmp-commands: move 'closefd' doc to schema
  qmp-commands: move 'add-fd' doc to schema

 docs/qmp-commands.txt | 603 --------------------------------------------------
 qapi-schema.json      | 292 +++++++++++++++++++++++-
 2 files changed, 283 insertions(+), 612 deletions(-)

-- 
2.10.0

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

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 280e337..5a91d77 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -217,25 +217,6 @@ Example:
 
 Note: CPUs' indexes are obtained with the 'query-cpus' command.
 
-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": {} }
-
 inject-nmi
 ----------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 5115b17..7aa742e 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2174,6 +2174,15 @@
 # Since: 0.14.0
 #
 # Notes: Errors were not reliably returned until 1.1
+#
+# Example:
+#
+# -> { "execute": "pmemsave",
+#      "arguments": { "val": 10,
+#                     "size": 100,
+#                     "filename": "/tmp/physical-mem-dump" } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'pmemsave',
   'data': {'val': 'int', 'size': 'int', 'filename': 'str'} }
-- 
2.10.0

[Qemu-devel] [PATCH 02/30] qmp-commands: move 'cont' 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 5a91d77..c97dcb5 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -111,18 +111,6 @@ Example:
 -> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
 <- { "return": {} }
 
-cont
-----
-
-Resume emulation.
-
-Arguments: None.
-
-Example:
-
--> { "execute": "cont" }
-<- { "return": {} }
-
 system_wakeup
 -------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 7aa742e..9de5214 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2203,6 +2203,12 @@
 #         this case, the effect of the command is to make sure the guest
 #         starts once migration finishes, removing the effect of the -S
 #         command line option if it was passed.
+#
+# Example:
+#
+# -> { "execute": "cont" }
+# <- { "return": {} }
+#
 ##
 { 'command': 'cont' }
 
-- 
2.10.0

[Qemu-devel] [PATCH 03/30] qmp-commands: move 'system_wakeup' 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 c97dcb5..1c3e69f 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -111,18 +111,6 @@ Example:
 -> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
 <- { "return": {} }
 
-system_wakeup
--------------
-
-Wakeup guest from suspend.
-
-Arguments: None.
-
-Example:
-
--> { "execute": "system_wakeup" }
-<- { "return": {} }
-
 device_add
 ----------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 9de5214..0eddc72 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2220,6 +2220,12 @@
 # Since:  1.1
 #
 # Returns:  nothing.
+#
+# Example:
+#
+# -> { "execute": "system_wakeup" }
+# <- { "return": {} }
+#
 ##
 { 'command': 'system_wakeup' }
 
-- 
2.10.0

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

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 1c3e69f..c4caf9c 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -193,20 +193,6 @@ Example:
 
 Note: CPUs' indexes are obtained with the 'query-cpus' command.
 
-inject-nmi
-----------
-
-Inject an NMI on the default CPU (x86/s390) or all CPUs (ppc64).
-
-Arguments: None.
-
-Example:
-
--> { "execute": "inject-nmi" }
-<- { "return": {} }
-
-Note: inject-nmi fails when the guest doesn't support injecting.
-
 xen-save-devices-state
 -------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 0eddc72..e8d6975 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2233,12 +2233,19 @@
 # @inject-nmi:
 #
 # Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all CPUs (ppc64).
+# The command fails when the guest doesn't support injecting.
 #
 # Returns:  If successful, nothing
 #
 # Since:  0.14.0
 #
 # Note: prior to 2.1, this command was only supported for x86 and s390 VMs
+#
+# Example:
+#
+# -> { "execute": "inject-nmi" }
+# <- { "return": {} }
+#
 ##
 { 'command': 'inject-nmi' }
 
-- 
2.10.0

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

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index c4caf9c..18a15dc 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -1074,21 +1074,6 @@ Example:
 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
 <- { "return": {} }
 
-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 } }
-<- { "return": {} }
-
 getfd
 -----
 
diff --git a/qapi-schema.json b/qapi-schema.json
index e8d6975..958b097 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2266,6 +2266,12 @@
 # Notes: Not all network adapters support setting link status.  This command
 #        will succeed even if the network adapter does not support link status
 #        notification.
+#
+# Example:
+#
+# -> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'set_link', 'data': {'name': 'str', 'up': 'bool'} }
 
-- 
2.10.0

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

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 18a15dc..dadcc20 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -1060,20 +1060,6 @@ Arguments:
 Returns: Nothing on success
          If "device" does not exist or cannot be determined, DeviceNotFound
 
-balloon
--------
-
-Request VM to change its memory allocation (in bytes).
-
-Arguments:
-
-- "value": New memory allocation (json-int)
-
-Example:
-
--> { "execute": "balloon", "arguments": { "value": 536870912 } }
-<- { "return": {} }
-
 getfd
 -----
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 958b097..a8383bf 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2292,6 +2292,12 @@
 #        size independent of this command.
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# -> { "execute": "balloon", "arguments": { "value": 536870912 } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'balloon', 'data': {'value': 'int'} }
 
-- 
2.10.0

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

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index dadcc20..6d43415 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -685,92 +685,6 @@ Example:
                                                   "target": "tgt-id" } }
 <- { "return": {} }
 
-transaction
------------
-
-Atomically operate on one or more block devices.  Operations that are
-currently supported:
-
-    - drive-backup
-    - blockdev-backup
-    - blockdev-snapshot-sync
-    - blockdev-snapshot-internal-sync
-    - abort
-    - block-dirty-bitmap-add
-    - block-dirty-bitmap-clear
-
-Refer to the qemu/qapi-schema.json file for minimum required QEMU
-versions for these operations.  A list of dictionaries is accepted,
-that contains the actions to be performed.  If there is any failure
-performing any of the operations, all operations for the group are
-abandoned.
-
-For external snapshots, the dictionary contains the device, the file to use for
-the new snapshot, and the format.  The default format, if not specified, is
-qcow2.
-
-Each new snapshot defaults to being created by QEMU (wiping any
-contents if the file already exists), but it is also possible to reuse
-an externally-created file.  In the latter case, you should ensure that
-the new image file has the same contents as the current one; QEMU cannot
-perform any meaningful check.  Typically this is achieved by using the
-current image file as the backing file for the new image.
-
-On failure, the original disks pre-snapshot attempt will be used.
-
-For internal snapshots, the dictionary contains the device and the snapshot's
-name.  If an internal snapshot matching name already exists, the request will
-be rejected.  Only some image formats support it, for example, qcow2, rbd,
-and sheepdog.
-
-On failure, qemu will try delete the newly created internal snapshot in the
-transaction.  When an I/O error occurs during deletion, the user needs to fix
-it later with qemu-img or other command.
-
-Arguments:
-
-actions array:
-    - "type": the operation to perform (json-string).  Possible
-              values: "drive-backup", "blockdev-backup",
-                      "blockdev-snapshot-sync",
-                      "blockdev-snapshot-internal-sync",
-                      "abort", "block-dirty-bitmap-add",
-                      "block-dirty-bitmap-clear"
-    - "data": a dictionary.  The contents depend on the value
-      of "type".  When "type" is "blockdev-snapshot-sync":
-      - "device": device name to snapshot (json-string)
-      - "node-name": graph node name to snapshot (json-string)
-      - "snapshot-file": name of new image file (json-string)
-      - "snapshot-node-name": graph node name of the new snapshot (json-string)
-      - "format": format of new image (json-string, optional)
-      - "mode": whether and how QEMU should create the snapshot file
-        (NewImageMode, optional, default "absolute-paths")
-      When "type" is "blockdev-snapshot-internal-sync":
-      - "device": the device name or node-name of a root node to snapshot
-                  (json-string)
-      - "name": name of the new snapshot (json-string)
-
-Example:
-
--> { "execute": "transaction",
-     "arguments": { "actions": [
-         { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
-                                         "snapshot-file": "/some/place/my-image",
-                                         "format": "qcow2" } },
-         { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
-                                         "snapshot-file": "/some/place/my-image2",
-                                         "snapshot-node-name": "node3432",
-                                         "mode": "existing",
-                                         "format": "qcow2" } },
-         { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
-                                         "snapshot-file": "/some/place/my-image2",
-                                         "mode": "existing",
-                                         "format": "qcow2" } },
-         { "type": "blockdev-snapshot-internal-sync", "data" : {
-                                         "device": "ide-hd2",
-                                         "name": "snapshot0" } } ] } }
-<- { "return": {} }
-
 block-dirty-bitmap-add
 ----------------------
 Since 2.4
diff --git a/qapi-schema.json b/qapi-schema.json
index a8383bf..b2d00dc 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2383,6 +2383,28 @@
 # operation fails, then the entire set of actions will be abandoned and the
 # appropriate error returned.
 #
+# For external snapshots, the dictionary contains the device, the file to use for
+# the new snapshot, and the format.  The default format, if not specified, is
+# qcow2.
+#
+# Each new snapshot defaults to being created by QEMU (wiping any
+# contents if the file already exists), but it is also possible to reuse
+# an externally-created file.  In the latter case, you should ensure that
+# the new image file has the same contents as the current one; QEMU cannot
+# perform any meaningful check.  Typically this is achieved by using the
+# current image file as the backing file for the new image.
+#
+# On failure, the original disks pre-snapshot attempt will be used.
+#
+# For internal snapshots, the dictionary contains the device and the snapshot's
+# name.  If an internal snapshot matching name already exists, the request will
+# be rejected.  Only some image formats support it, for example, qcow2, rbd,
+# and sheepdog.
+#
+# On failure, qemu will try delete the newly created internal snapshot in the
+# transaction.  When an I/O error occurs during deletion, the user needs to fix
+# it later with qemu-img or other command.
+#
 # @actions: List of @TransactionAction;
 #           information needed for the respective operations.
 #
@@ -2391,6 +2413,7 @@
 #              for additional detail.
 #
 # Returns: nothing on success
+#
 #          Errors depend on the operations of the transaction
 #
 # Note: The transaction aborts on the first failure.  Therefore, there will be
@@ -2398,6 +2421,28 @@
 # subsequent actions will not have been attempted.
 #
 # Since 1.1
+#
+# Example:
+#
+# -> { "execute": "transaction",
+#      "arguments": { "actions": [
+#          { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
+#                                      "snapshot-file": "/some/place/my-image",
+#                                      "format": "qcow2" } },
+#          { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
+#                                      "snapshot-file": "/some/place/my-image2",
+#                                      "snapshot-node-name": "node3432",
+#                                      "mode": "existing",
+#                                      "format": "qcow2" } },
+#          { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
+#                                      "snapshot-file": "/some/place/my-image2",
+#                                      "mode": "existing",
+#                                      "format": "qcow2" } },
+#          { "type": "blockdev-snapshot-internal-sync", "data" : {
+#                                      "device": "ide-hd2",
+#                                      "name": "snapshot0" } } ] } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'transaction',
   'data': { 'actions': [ 'TransactionAction' ],
-- 
2.10.0

[Qemu-devel] [PATCH 08/30] qmp-commands: move 'human-monitor-command' doc to schema

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 6d43415..c3b813f 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -1212,39 +1212,6 @@ Example:
 
 Note: This command must be issued before issuing any other command.
 
-human-monitor-command
----------------------
-
-Execute a Human Monitor command.
-
-Arguments:
-
-- command-line: the command name and its arguments, just like the
-                Human Monitor's shell (json-string)
-- cpu-index: select the CPU number to be used by commands which access CPU
-             data, like 'info registers'. The Monitor selects CPU 0 if this
-             argument is not provided (json-int, optional)
-
-Example:
-
--> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } }
-<- { "return": "kvm support: enabled\r\n" }
-
-Notes:
-
-(1) The Human Monitor is NOT an stable interface, this means that command
-    names, arguments and responses can change or be removed at ANY time.
-    Applications that rely on long term stability guarantees should NOT
-    use this command
-
-(2) Limitations:
-
-    o This command is stateless, this means that commands that depend
-      on state information (such as getfd) might not work
-
-    o Commands that prompt the user for data (eg. 'cont' when the block
-      device is encrypted) don't currently work
-
 3. Query Commands
 =================
 
diff --git a/qapi-schema.json b/qapi-schema.json
index b2d00dc..5142818 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2464,15 +2464,26 @@
 # Since: 0.14.0
 #
 # Notes: This command only exists as a stop-gap.  Its use is highly
-#        discouraged.  The semantics of this command are not guaranteed.
+#        discouraged.  The semantics of this command are not
+#        guaranteed: this means that command names, arguments and
+#        responses can change or be removed at ANY time.  Applications
+#        that rely on long term stability guarantees should NOT
+#        use this command.
 #
 #        Known limitations:
 #
 #        o This command is stateless, this means that commands that depend
 #          on state information (such as getfd) might not work
 #
-#       o Commands that prompt the user for data (eg. 'cont' when the block
-#         device is encrypted) don't currently work
+#        o Commands that prompt the user for data (eg. 'cont' when the block
+#          device is encrypted) don't currently work
+#
+# Example:
+#
+# -> { "execute": "human-monitor-command",
+#      "arguments": { "command-line": "info kvm" } }
+# <- { "return": "kvm support: enabled\r\n" }
+#
 ##
 { 'command': 'human-monitor-command',
   'data': {'command-line': 'str', '*cpu-index': 'int'},
-- 
2.10.0

[Qemu-devel] [PATCH 09/30] qmp-commands: move 'migrate_cancel' 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 c3b813f..158dcbd 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -268,18 +268,6 @@ Notes:
 (3) The user Monitor's "detach" argument is invalid in QMP and should not
     be used
 
-migrate_cancel
---------------
-
-Cancel the current migration.
-
-Arguments: None.
-
-Example:
-
--> { "execute": "migrate_cancel" }
-<- { "return": {} }
-
 migrate-incoming
 ----------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 5142818..335be2d 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2499,6 +2499,12 @@
 # Notes: This command succeeds even if there is no migration process running.
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# -> { "execute": "migrate_cancel" }
+# <- { "return": {} }
+#
 ##
 { 'command': 'migrate_cancel' }
 
-- 
2.10.0

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

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 158dcbd..b73bcac 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -330,21 +330,6 @@ Example:
 -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
 <- { "return": {} }
 
-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": {} }
-
-
 dump
 
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 335be2d..65ddfc6 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2518,6 +2518,12 @@
 # Returns: nothing on success
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'migrate_set_downtime', 'data': {'value': 'number'} }
 
-- 
2.10.0

[Qemu-devel] [PATCH 11/30] qmp-commands: move 'migrate_set_speed' 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 b73bcac..9ef6ce1 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -316,20 +316,6 @@ Example:
 -> { "execute": "query-migrate-cache-size" }
 <- { "return": 67108864 }
 
-migrate_set_speed
------------------
-
-Set maximum speed for migrations.
-
-Arguments:
-
-- "value": maximum speed, in bytes per second (json-int)
-
-Example:
-
--> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
-<- { "return": {} }
-
 dump
 
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 65ddfc6..864927d 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2532,13 +2532,19 @@
 #
 # Set maximum speed for migration.
 #
-# @value: maximum speed in bytes.
+# @value: maximum speed in bytes per second.
 #
 # Returns: nothing on success
 #
 # Notes: A value lesser than zero will be automatically round up to zero.
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'migrate_set_speed', 'data': {'value': 'int'} }
 
-- 
2.10.0

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

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 9ef6ce1..b829dc1 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -303,19 +303,6 @@ Example:
 -> { "execute": "migrate-set-cache-size", "arguments": { "value": 536870912 } }
 <- { "return": {} }
 
-query-migrate-cache-size
-------------------------
-
-Show cache size to be used by XBZRLE migration
-
-returns a json-object with the following information:
-- "size" : json-int
-
-Example:
-
--> { "execute": "query-migrate-cache-size" }
-<- { "return": 67108864 }
-
 dump
 
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 864927d..582fbfd 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2567,11 +2567,17 @@
 ##
 # @query-migrate-cache-size
 #
-# query XBZRLE cache size
+# Query migration XBZRLE cache size
 #
 # Returns: XBZRLE cache size in bytes
 #
 # Since: 1.2
+#
+# Example:
+#
+# -> { "execute": "query-migrate-cache-size" }
+# <- { "return": 67108864 }
+#
 ##
 { 'command': 'query-migrate-cache-size', 'returns': 'int' }
 
-- 
2.10.0

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

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index b829dc1..724c3a9 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -1111,23 +1111,6 @@ Example:
                                                "iops_size": 0 } }
 <- { "return": {} }
 
-set_password
-------------
-
-Set the password for vnc/spice protocols.
-
-Arguments:
-
-- "protocol": protocol name (json-string)
-- "password": password (json-string)
-- "connected": [ keep | disconnect | fail ] (json-string, optional)
-
-Example:
-
--> { "execute": "set_password", "arguments": { "protocol": "vnc",
-                                               "password": "secret" } }
-<- { "return": {} }
-
 expire_password
 ---------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 582fbfd..758dd07 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2694,6 +2694,13 @@
 #          If Spice is not enabled, DeviceNotFound
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# -> { "execute": "set_password", "arguments": { "protocol": "vnc",
+#                                                "password": "secret" } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'set_password',
   'data': {'protocol': 'str', 'password': 'str', '*connected': 'str'} }
-- 
2.10.0

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

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 724c3a9..0082101 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -1111,22 +1111,6 @@ Example:
                                                "iops_size": 0 } }
 <- { "return": {} }
 
-expire_password
----------------
-
-Set the password expire time for vnc/spice protocols.
-
-Arguments:
-
-- "protocol": protocol name (json-string)
-- "time": [ now | never | +secs | secs ] (json-string)
-
-Example:
-
--> { "execute": "expire_password", "arguments": { "protocol": "vnc",
-                                                  "time": "+60" } }
-<- { "return": {} }
-
 qmp_capabilities
 ----------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 758dd07..9d78854 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2727,6 +2727,13 @@
 #        coordinate server time with client time.  It is not recommended to
 #        use the absolute time version of the @time parameter unless you're
 #        sure you are on the same machine as the QEMU instance.
+#
+# Example:
+#
+# -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
+#                                                   "time": "+60" } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'expire_password', 'data': {'protocol': 'str', 'time': 'str'} }
 
-- 
2.10.0

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

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 0082101..d5ad1de 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -70,33 +70,6 @@ Example:
 
 Note: The "force" argument defaults to false.
 
-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:
-
-1. Change a removable medium
-
--> { "execute": "change",
-             "arguments": { "device": "ide1-cd0",
-                            "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
-<- { "return": {} }
-
-2. Change VNC password
-
--> { "execute": "change",
-             "arguments": { "device": "vnc", "target": "password",
-                            "arg": "foobar1" } }
-<- { "return": {} }
-
 screendump
 ----------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 9d78854..5529e4a 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2784,6 +2784,23 @@
 #         change-vnc-password.
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# 1. Change a removable medium
+#
+# -> { "execute": "change",
+#      "arguments": { "device": "ide1-cd0",
+#                     "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
+# <- { "return": {} }
+#
+# 2. Change VNC password
+#
+# -> { "execute": "change",
+#      "arguments": { "device": "vnc", "target": "password",
+#                     "arg": "foobar1" } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'change',
   'data': {'device': 'str', 'target': 'str', '*arg': 'str'} }
-- 
2.10.0

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

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index d5ad1de..799ac72 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -217,30 +217,6 @@ Example:
      "arguments": { "enable": true } }
 <- { "return": {} }
 
-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
-
 migrate-incoming
 ----------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 5529e4a..d9f4b1e 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2883,6 +2883,22 @@
 # Returns: nothing on success
 #
 # Since: 0.14.0
+#
+# 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
+#
+# Example:
+#
+# -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'migrate',
   'data': {'uri': 'str', '*blk': 'bool', '*inc': 'bool', '*detach': 'bool' } }
-- 
2.10.0

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

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 799ac72..32e5b0a 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -217,26 +217,6 @@ Example:
      "arguments": { "enable": true } }
 <- { "return": {} }
 
-migrate-incoming
-----------------
-
-Continue an incoming migration
-
-Arguments:
-
-- "uri": Source/listening URI (json-string)
-
-Example:
-
--> { "execute": "migrate-incoming", "arguments": { "uri": "tcp::4446" } }
-<- { "return": {} }
-
-Notes:
-
-(1) QEMU must be started with -incoming defer to allow migrate-incoming to
-    be used
-(2) The uri format is the same as for -incoming
-
 migrate-set-cache-size
 ----------------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index d9f4b1e..cd77264 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2915,9 +2915,23 @@
 # Returns: nothing on success
 #
 # Since: 2.3
-# Note: It's a bad idea to use a string for the uri, but it needs to stay
-# compatible with -incoming and the format of the uri is already exposed
-# above libvirt
+#
+# Notes:
+#
+# 1. It's a bad idea to use a string for the uri, but it needs to stay
+#    compatible with -incoming and the format of the uri is already exposed
+#    above libvirt.
+#
+# 2. QEMU must be started with -incoming defer to allow migrate-incoming to
+#    be used.
+#
+# 3. The uri format is the same as for -incoming
+#
+# Example:
+#
+# -> { "execute": "migrate-incoming", "arguments": { "uri": "tcp::4446" } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'migrate-incoming', 'data': {'uri': 'str' } }
 
-- 
2.10.0

[Qemu-devel] [PATCH 18/30] qmp-commands: move 'xen-save-devices-state' 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 32e5b0a..cc90d57 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -166,24 +166,6 @@ Example:
 
 Note: CPUs' indexes are obtained with the 'query-cpus' command.
 
-xen-save-devices-state
--------
-
-Save the state of all devices to file. The RAM and the block devices
-of the VM are not saved by this command.
-
-Arguments:
-
-- "filename": the file to save the state of the devices to as binary
-data. See xen-save-devices-state.txt for a description of the binary
-format.
-
-Example:
-
--> { "execute": "xen-save-devices-state",
-     "arguments": { "filename": "/tmp/save" } }
-<- { "return": {} }
-
 xen-load-devices-state
 ----------------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index cd77264..93322a9 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2935,6 +2935,7 @@
 ##
 { 'command': 'migrate-incoming', 'data': {'uri': 'str' } }
 
+##
 # @xen-save-devices-state:
 #
 # Save the state of all devices to file. The RAM and the block devices
@@ -2947,6 +2948,13 @@
 # Returns: Nothing on success
 #
 # Since: 1.1
+#
+# Example:
+#
+# -> { "execute": "xen-save-devices-state",
+#      "arguments": { "filename": "/tmp/save" } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'xen-save-devices-state', 'data': {'filename': 'str'} }
 
-- 
2.10.0

[Qemu-devel] [PATCH 19/30] qmp-commands: move 'xen-set-global-dirty-log' doc to schema

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index cc90d57..dc7c2f11 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -184,21 +184,6 @@ Example:
      "arguments": { "filename": "/tmp/resume" } }
 <- { "return": {} }
 
-xen-set-global-dirty-log
--------
-
-Enable or disable the global dirty log mode.
-
-Arguments:
-
-- "enable": Enable it or disable it.
-
-Example:
-
--> { "execute": "xen-set-global-dirty-log",
-     "arguments": { "enable": true } }
-<- { "return": {} }
-
 migrate-set-cache-size
 ----------------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 93322a9..59a5e41 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2968,6 +2968,13 @@
 # Returns: nothing
 #
 # Since: 1.3
+#
+# Example:
+#
+# -> { "execute": "xen-set-global-dirty-log",
+#      "arguments": { "enable": true } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } }
 
-- 
2.10.0

[Qemu-devel] [PATCH 20/30] qmp-commands: move 'device_del' 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, 10 insertions(+), 20 deletions(-)

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index dc7c2f11..0359516 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -109,25 +109,6 @@ Notes:
 (2) It's possible to list device properties by running QEMU with the
     "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
 
-device_del
-----------
-
-Remove a device.
-
-Arguments:
-
-- "id": the device's ID or QOM path (json-string)
-
-Example:
-
--> { "execute": "device_del", "arguments": { "id": "net1" } }
-<- { "return": {} }
-
-Example:
-
--> { "execute": "device_del", "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
-<- { "return": {} }
-
 send-key
 ----------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 59a5e41..19bb04d 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -3023,7 +3023,7 @@
 #
 # Remove a device from a guest
 #
-# @id: the name or QOM path of the device
+# @id: the device's ID or QOM path
 #
 # Returns: Nothing on success
 #          If @id is not a valid device, DeviceNotFound
@@ -3036,6 +3036,15 @@
 #        for all devices.
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# -> { "execute": "device_del", "arguments": { "id": "net1" } }
+# <- { "return": {} }
+#
+# -> { "execute": "device_del", "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'device_del', 'data': {'id': 'str'} }
 
-- 
2.10.0

[Qemu-devel] [PATCH 21/30] qmp-commands: move 'dump-guest-memory' doc to schema

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 0359516..0fc4cde 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -180,36 +180,6 @@ Example:
 -> { "execute": "migrate-set-cache-size", "arguments": { "value": 536870912 } }
 <- { "return": {} }
 
-dump
-
-
-Dump guest memory to file. The file can be processed with crash or gdb.
-
-Arguments:
-
-- "paging": do paging to get guest's memory mapping (json-bool)
-- "protocol": destination file(started with "file:") or destination file
-              descriptor (started with "fd:") (json-string)
-- "detach": if specified, command will return immediately, without waiting
-            for the dump to finish. The user can track progress using
-            "query-dump". (json-bool)
-- "begin": the starting physical address. It's optional, and should be specified
-           with length together (json-int)
-- "length": the memory size, in bytes. It's optional, and should be specified
-            with begin together (json-int)
-- "format": the format of guest memory dump. It's optional, and can be
-            elf|kdump-zlib|kdump-lzo|kdump-snappy, but non-elf formats will
-            conflict with paging and filter, ie. begin and length (json-string)
-
-Example:
-
--> { "execute": "dump-guest-memory", "arguments": { "protocol": "fd:dump" } }
-<- { "return": {} }
-
-Notes:
-
-(1) All boolean arguments default to false
-
 query-dump-guest-memory-capability
 ----------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 19bb04d..3c292d1 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -3111,9 +3111,17 @@
 #          @length is not allowed to be specified with non-elf @format at the
 #          same time (since 2.0)
 #
+# Note: All boolean arguments default to false
+#
 # Returns: nothing on success
 #
 # Since: 1.2
+#
+# Example:
+#
+# -> { "execute": "dump-guest-memory", "arguments": { "protocol": "fd:dump" } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'dump-guest-memory',
   'data': { 'paging': 'bool', 'protocol': 'str', '*detach': 'bool',
-- 
2.10.0

[Qemu-devel] [PATCH 22/30] qmp-commands: move 'query-dump-guest-memory-capability' doc to schema

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 0fc4cde..b84446f 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -180,17 +180,6 @@ Example:
 -> { "execute": "migrate-set-cache-size", "arguments": { "value": 536870912 } }
 <- { "return": {} }
 
-query-dump-guest-memory-capability
-----------
-
-Show available formats for 'dump-guest-memory'
-
-Example:
-
--> { "execute": "query-dump-guest-memory-capability" }
-<- { "return": { "formats":
-                    ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
-
 query-dump
 ----------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 3c292d1..ee15044 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -3195,6 +3195,13 @@
 #           dump-guest-memory
 #
 # Since: 2.0
+#
+# Example:
+#
+# -> { "execute": "query-dump-guest-memory-capability" }
+# <- { "return": { "formats":
+#                  ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
+#
 ##
 { 'command': 'query-dump-guest-memory-capability',
   'returns': 'DumpGuestMemoryCapability' }
-- 
2.10.0

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

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index b84446f..051bbfd 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -193,20 +193,6 @@ Example:
 <- { "return": { "status": "active", "completed": 1024000,
                  "total": 2048000 } }
 
-dump-skeys
-----------
-
-Save guest storage keys to file.
-
-Arguments:
-
-- "filename": file path (json-string)
-
-Example:
-
--> { "execute": "dump-skeys", "arguments": { "filename": "/tmp/skeys" } }
-<- { "return": {} }
-
 netdev_add
 ----------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index ee15044..381454e 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -3216,6 +3216,12 @@
 # This command is only supported on s390 architecture.
 #
 # Since: 2.5
+#
+# Example:
+#
+# -> { "execute": "dump-skeys", "arguments": { "filename": "/tmp/skeys" } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'dump-skeys',
   'data': { 'filename': 'str' } }
-- 
2.10.0

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

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 051bbfd..d41a60a 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -193,28 +193,6 @@ Example:
 <- { "return": { "status": "active", "completed": 1024000,
                  "total": 2048000 } }
 
-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",
-                    "dnssearch": "example.org" } }
-<- { "return": {} }
-
-Note: The supported device options are the same ones supported by the '-netdev'
-      command-line argument, which are listed in the '-help' output or QEMU's
-      manual
-
 netdev_del
 ----------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 381454e..37df72b 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -3247,6 +3247,14 @@
 #
 # Returns: Nothing on success
 #          If @type is not a valid network backend, DeviceNotFound
+#
+# Example:
+#
+# -> { "execute": "netdev_add",
+#      "arguments": { "type": "user", "id": "netdev1",
+#                     "dnssearch": "example.org" } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'netdev_add',
   'data': {'type': 'str', 'id': 'str'},
-- 
2.10.0

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

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index d41a60a..0bc2b1a 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -193,21 +193,6 @@ Example:
 <- { "return": { "status": "active", "completed": 1024000,
                  "total": 2048000 } }
 
-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": {} }
-
-
 object-add
 ----------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 37df72b..23da2d9 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -3271,6 +3271,12 @@
 #          If @id is not a valid network backend, DeviceNotFound
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'netdev_del', 'data': {'id': 'str'} }
 
-- 
2.10.0

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

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 0bc2b1a..ff83ea2 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -193,23 +193,6 @@ Example:
 <- { "return": { "status": "active", "completed": 1024000,
                  "total": 2048000 } }
 
-object-add
-----------
-
-Create QOM object.
-
-Arguments:
-
-- "qom-type": the object's QOM type, i.e. the class name (json-string)
-- "id": the object's ID, must be unique (json-string)
-- "props": a dictionary of object property values (optional, json-dict)
-
-Example:
-
--> { "execute": "object-add", "arguments": { "qom-type": "rng-random", "id": "rng1",
-     "props": { "filename": "/dev/hwrng" } } }
-<- { "return": {} }
-
 object-del
 ----------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 23da2d9..f9528eb 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -3295,6 +3295,13 @@
 #          Error if @qom-type is not a valid class name
 #
 # Since: 2.0
+#
+# Example:
+#
+# -> { "execute": "object-add", "arguments": { "qom-type": "rng-random", "id": "rng1",
+#      "props": { "filename": "/dev/hwrng" } } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'object-add',
   'data': {'qom-type': 'str', 'id': 'str', '*props': 'any'} }
-- 
2.10.0

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

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index ff83ea2..03d8c54 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -193,21 +193,6 @@ Example:
 <- { "return": { "status": "active", "completed": 1024000,
                  "total": 2048000 } }
 
-object-del
-----------
-
-Remove QOM object.
-
-Arguments:
-
-- "id": the object's ID (json-string)
-
-Example:
-
--> { "execute": "object-del", "arguments": { "id": "rng1" } }
-<- { "return": {} }
-
-
 block_resize
 ------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index f9528eb..b552378 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -3317,6 +3317,12 @@
 #          Error if @id is not a valid id for a QOM object
 #
 # Since: 2.0
+#
+# Example:
+#
+# -> { "execute": "object-del", "arguments": { "id": "rng1" } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'object-del', 'data': {'id': 'str'} }
 
-- 
2.10.0

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

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 03d8c54..37ff37d 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -673,28 +673,6 @@ Arguments:
 Returns: Nothing on success
          If "device" does not exist or cannot be determined, DeviceNotFound
 
-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": {} }
-
-Notes:
-
-(1) If the name specified by the "fdname" argument already exists,
-    the file descriptor assigned to it will be closed and replaced
-    by the received file descriptor.
-(2) The 'closefd' command can be used to explicitly close the file
-    descriptor when it is no longer needed.
-
 closefd
 -------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index b552378..58cb15f 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -3875,8 +3875,15 @@
 # Notes: If @fdname already exists, the file descriptor assigned to
 #        it will be closed and replaced by the received file
 #        descriptor.
+#
 #        The 'closefd' command can be used to explicitly close the
 #        file descriptor when it is no longer needed.
+#
+# Example:
+#
+# -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'getfd', 'data': {'fdname': 'str'} }
 
-- 
2.10.0

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

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 37ff37d..52bec44 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -673,20 +673,6 @@ Arguments:
 Returns: Nothing on success
          If "device" does not exist or cannot be determined, DeviceNotFound
 
-closefd
--------
-
-Close a file descriptor previously passed via SCM rights.
-
-Arguments:
-
-- "fdname": file descriptor name (json-string)
-
-Example:
-
--> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
-<- { "return": {} }
-
 add-fd
 -------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 58cb15f..7607b1a 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -3897,6 +3897,12 @@
 # Returns: Nothing on success
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'closefd', 'data': {'fdname': 'str'} }
 
-- 
2.10.0

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

[Marc-André Lureau]

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

diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 52bec44..93858b2 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -673,34 +673,6 @@ Arguments:
 Returns: Nothing on success
          If "device" does not exist or cannot be determined, DeviceNotFound
 
-add-fd
--------
-
-Add a file descriptor, that was passed via SCM rights, to an fd set.
-
-Arguments:
-
-- "fdset-id": The ID of the fd set to add the file descriptor to.
-              (json-int, optional)
-- "opaque": A free-form string that can be used to describe the fd.
-            (json-string, optional)
-
-Return a json-object with the following information:
-
-- "fdset-id": The ID of the fd set that the fd was added to. (json-int)
-- "fd": The file descriptor that was received via SCM rights and added to the
-        fd set. (json-int)
-
-Example:
-
--> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
-<- { "return": { "fdset-id": 1, "fd": 3 } }
-
-Notes:
-
-(1) The list of fd sets is shared by all monitor connections.
-(2) If "fdset-id" is not specified, a new fd set will be created.
-
 remove-fd
 ---------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 7607b1a..bbbaf5c 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -4230,7 +4230,9 @@
 # @opaque: #optional A free-form string that can be used to describe the fd.
 #
 # Returns: @AddfdInfo on success
+#
 #          If file descriptor was not received, FdNotSupplied
+#
 #          If @fdset-id is a negative value, InvalidParameterValue
 #
 # Notes: The list of fd sets is shared by all monitor connections.
@@ -4238,6 +4240,12 @@
 #        If @fdset-id is not specified, a new fd set will be created.
 #
 # Since: 1.2.0
+#
+# Example:
+#
+# -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
+# <- { "return": { "fdset-id": 1, "fd": 3 } }
+#
 ##
 { 'command': 'add-fd', 'data': {'*fdset-id': 'int', '*opaque': 'str'},
   'returns': 'AddfdInfo' }
-- 
2.10.0

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

[Eric Blake]

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

On 09/22/2016 04:22 AM, Marc-André Lureau wrote:
> 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

s/splitted/split/

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

I don't mind an in-between state, as long as the commit message is clear
that more patches are required to bring the docs back up to quality.  It
doesn't break bisection to have incomplete documentation.

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