[PATCH 26/27] docs/qapi-domain: RFC patch - Add one last sample command

[John Snow]

Just to have a bit more to look at in the generated doc, here's a fairly
complex command with a lot of bells and whistles.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 docs/qapi/index.rst | 67 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/docs/qapi/index.rst b/docs/qapi/index.rst
index 6e85ea5280d..4562e755d21 100644
--- a/docs/qapi/index.rst
+++ b/docs/qapi/index.rst
@@ -267,6 +267,73 @@ Explicit cross-referencing syntax for QAPI modules is 
available with
       :memb str key-secret: ID of a QCryptoSecret object providing a
          passphrase for unlocking the encryption
 
+.. qapi:command:: blockdev-backup
+   :since: 4.2
+
+   Start a point-in-time copy of a block device to a new
+   destination. The status of ongoing blockdev-backup operations can be
+   checked with query-block-jobs where the BlockJobInfo.type field has
+   the value ‘backup’. The operation can be stopped before it has
+   completed using the block-job-cancel command.
+
+   :arg str target:
+      the device name or node-name of the backup target node.
+   :arg str? job-id:
+      identifier for the newly-created block job. If omitted, the device
+      name will be used. (Since 2.7)
+   :arg str device:
+      the device name or node-name of a root node which should be copied.
+   :arg MirrorSyncMode sync:
+      what parts of the disk image should be copied to the destination
+      (all the disk, only the sectors allocated in the topmost image,
+      from a dirty bitmap, or only new I/O).
+   :arg int? speed:
+      the maximum speed, in bytes per second. The default is 0, for unlimited.
+   :arg str? bitmap:
+      The name of a dirty bitmap to use. Must be present if sync is
+      ``bitmap`` or ``incremental``. Can be present if sync is ``full`` or
+      ``top``. Must not be present otherwise. (Since 2.4 (drive-backup),
+      3.1 (blockdev-backup))
+   :arg BitmapSyncMode? bitmap-mode:
+      Specifies the type of data the bitmap should contain after the
+      operation concludes. Must be present if a bitmap was provided,
+      Must NOT be present otherwise. (Since 4.2)
+   :arg bool? compress:
+      true to compress data, if the target format supports it. (default:
+      false) (since 2.8)
+   :arg BlockdevOnError? on-source-error:
+      the action to take on an error on the source, default
+      ``report``. ``stop`` and ``enospc`` can only be used if the block device
+      supports io-status (see BlockInfo).
+   :arg BlockdevOnError? on-target-error:
+      the action to take on an error on the target, default ``report`` (no
+      limitations, since this applies to a different block device than
+      device).
+   :arg bool? auto-finalize:
+      When false, this job will wait in a ``PENDING`` state after it has
+      finished its work, waiting for block-job-finalize before making
+      any block graph changes. When true, this job will automatically
+      perform its abort or commit actions. Defaults to true. (Since
+      2.12)
+   :arg bool? auto-dismiss:
+      When false, this job will wait in a ``CONCLUDED`` state after it has
+      completely ceased all work, and awaits block-job-dismiss. When
+      true, this job will automatically disappear from the query list
+      without user intervention. Defaults to true. (Since 2.12)
+   :arg str? filter-node-name:
+      the node name that should be assigned to the filter driver that
+      the backup job inserts into the graph above node specified by
+      drive. If this option is not given, a node name is
+      autogenerated. (Since: 4.2)
+   :arg BackupPerf? x-perf:
+      Performance options. (Since 6.0)
+   :feat unstable: Member ``x-perf`` is experimental.
+   :error DeviceNotFound: if ``device`` is not a valid block device.
+
+   .. note:: ``on-source-error`` and ``on-target-error only`` affect
+             background I/O. If an error occurs during a guest write
+             request, the device's rerror/werror actions will be used.
+
 .. qapi:command:: x-debug-query-block-graph
    :since: 4.0
    :unstable:
-- 
2.44.0