[libvirt] [PATCH libvirt-virshcmdref] Add blockpull and blockjob commands

[Stefan Hajnoczi]

The blockpull and blockjob commands have been present since 0.9.4.  This
patch adds basic usage examples and command syntax.

Signed-off-by: Stefan Hajnoczi <stefanha at linux.vnet.ibm.com>
---
 common.sh            |    8 ++--
 source/blockjob.xml  |   79 +++++++++++++++++++++++++++++++++++++++
 source/blockpull.xml |  101 ++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 184 insertions(+), 4 deletions(-)
 create mode 100644 source/blockjob.xml
 create mode 100644 source/blockpull.xml

diff --git a/common.sh b/common.sh
index 9da1b13..7e3a3a0 100755
--- a/common.sh
+++ b/common.sh
@@ -1,9 +1,9 @@
 # List of source files
 DOMAIN_COMMANDS="attach-device attach-disk attach-interface autostart
-  blkiotune console cpu-baseline cpu-compare create define destroy
-  detach-device detach-disk detach-interface domid domjobabort domjobinfo
-  domname domuuid domxml-from-native domxml-to-native dump dumpxml echo
-  edit freecell hostname inject-nmi managedsave managedsave-remove
+  blkiotune blockjob blockpull console cpu-baseline cpu-compare create define
+  destroy detach-device detach-disk detach-interface domid domjobabort
+  domjobinfo domname domuuid domxml-from-native domxml-to-native dump dumpxml
+  echo edit freecell hostname inject-nmi managedsave managedsave-remove
   maxvcpus memtune migrate migrate-setmaxdowntime migrate-getspeed
   migrate-setspeed reboot restore resume save schedinfo send-key
   setmaxmem setmem setvcpus shutdown start suspend ttyconsole undefine
diff --git a/source/blockjob.xml b/source/blockjob.xml
new file mode 100644
index 0000000..0c34bae
--- /dev/null
+++ b/source/blockjob.xml
@@ -0,0 +1,79 @@
+<?xml version='1.0' encoding='utf-8' ?>
+
+<command>
+  <name>blockjob</name>
+
+  <description>
+    <text>
+      Manage active block operations
+    </text>
+  </description>
+
+  <options>
+    <parameter requirement="required">
+      <value type="string" requirement="required">domain</value>
+      <description>
+        The name of the domain on which to act.
+      </description>
+    </parameter>
+    <parameter requirement="required">
+      <value type="string" requirement="required">path</value>
+      <description>
+        The fully-qualified path of the disk.  See "domblklist" for listing these names.
+      </description>
+    </parameter>
+    <parameter requirement="optional">
+      <keyword requirement="required">--abort</keyword>
+      <description>
+        Abort the active job on the specified disk.
+      </description>
+    </parameter>
+    <parameter requirement="optional">
+      <keyword requirement="required">--async</keyword>
+      <description>
+        Return immediately instead of waiting for cancelation to complete, when specified together with "--abort".
+      </description>
+    </parameter>
+    <parameter requirement="optional">
+      <keyword requirement="required">--pivot</keyword>
+    </parameter>
+    <parameter requirement="optional">
+      <keyword requirement="required">--info</keyword>
+      <description>
+        Print information about any active block operation.
+      </description>
+    </parameter>
+  </options>
+
+  <availability from="0.9.4" />
+
+  <notes />
+
+  <examples type="usage">
+    <example>
+      <terminal>virsh # <bold>blockjob</bold> <value>example-domain</value> <value>vda</value> <italic>--info</italic></terminal>
+      <text>
+        Prints information about any active block operation on <value>vda</value> from <value>example-domain</value>.
+      </text>
+    </example>
+    <example>
+      <terminal>virsh # <bold>blockjob</bold> <value>example-domain</value> <value>vda</value> <italic>--abort</italic></terminal>
+      <text>
+        Cancels the active block operation on <value>vda</value> from <value>example-domain</value>.
+      </text>
+    </example>
+  </examples>
+
+  <examples type="fullcontext" />
+
+  <reference type="seealso">
+    <item>
+      <link type="internal" href="blockpull" />
+      <name>blockpull</name>
+      <description>
+        populate a disk from its backing image chain
+      </description>
+    </item>
+  </reference>
+
+</command>
diff --git a/source/blockpull.xml b/source/blockpull.xml
new file mode 100644
index 0000000..81b58da
--- /dev/null
+++ b/source/blockpull.xml
@@ -0,0 +1,101 @@
+<?xml version='1.0' encoding='utf-8' ?>
+
+<command>
+  <name>blockpull</name>
+
+  <description>
+    <text>
+      Populate a disk from its backing image chain
+    </text>
+  </description>
+
+  <options>
+    <parameter requirement="required">
+      <value type="string" requirement="required">domain</value>
+      <description>
+        The name of the domain on which to act.
+      </description>
+    </parameter>
+    <parameter requirement="required">
+      <value type="string" requirement="required">path</value>
+      <description>
+        The fully-qualified path of the disk.  See "domblklist" for listing these names.
+      </description>
+    </parameter>
+    <parameter requirement="optional">
+      <value type="number" requirement="required">bandwidth</value>
+      <description>
+        Copying bandwidth limit in MiB/s.
+      </description>
+    </parameter>
+    <parameter requirement="optional">
+      <value type="string" requirement="required">base</value>
+      <description>
+        Stop at a specific backing image instead of flattening the entire chain.
+      </description>
+    </parameter>
+    <parameter requirement="optional">
+      <keyword requirement="required">--wait</keyword>
+      <description>
+	Block until the operation completes instead of returning as soon as possible while the operation runs in the background.
+      </description>
+    </parameter>
+    <parameter requirement="optional">
+      <keyword requirement="required">--verbose</keyword>
+      <description>
+        Print periodic status updates when used together with "--wait".
+      </description>
+    </parameter>
+    <parameter requirement="optional">
+      <keyword requirement="required">--timeout</keyword>
+      <value type="number" requirement="required">seconds</value>
+      <description>
+        Cancel the operation if the timeout elapses.  Use together with "--wait".
+      </description>
+    </parameter>
+    <parameter requirement="optional">
+      <keyword requirement="required">--async</keyword>
+      <description>
+        Return as soon as possible.
+      </description>
+    </parameter>
+  </options>
+
+  <availability from="0.9.4" />
+
+  <notes />
+
+  <examples type="usage">
+    <example>
+      <terminal>virsh # <bold>blockpull</bold> <value>example-domain</value> <value>vda</value></terminal>
+      <text>
+        Start populating <value>vda</value> from its backing image chain and return immediately.
+      </text>
+    </example>
+    <example>
+      <terminal>virsh # <bold>blockpull</bold> <value>example-domain</value> <value>vda</value> <value>--wait</value></terminal>
+      <text>
+        Populate <value>vda</value> from its backing image chain and wait for the operation to complete.
+      </text>
+    </example>
+    <example>
+      <terminal>virsh # <bold>blockpull</bold> <value>example-domain</value> <value>vda</value> <value>0</value> <value>/path/to/backing.img</value></terminal>
+      <text>
+        Start populating <value>vda</value> from its backing image chain up to <value>/path/to/backing.img</value> and return immediately.  <value>/path/to/backing.img</value> and its backing images will not be flattened.  Note that the <value>0</value> means unlimited bandwidth and is necessary because <value>bandwidth</value> and <value>base</value> are positional arguments.
+      </text>
+    </example>
+  </examples>
+
+  <examples type="fullcontext" />
+
+  <reference type="seealso">
+    <item>
+      <link type="internal" href="blockjob" />
+      <name>blockjob</name>
+      <description>
+        manage active block operations
+      </description>
+    </item>
+  </reference>
+
+</command>
-- 
1.7.10.4