[libvirt] [PATCH v2 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>
---
v2:
 * Linewrap to 80 chars except pre-formatted <terminal> tag [Eric]
 * 'path' argument can be <target dev='name'> or <source file='name'> [Eric]
 * s/cancelation/cancellation/ [Eric]
 * Use blockpull --base option to avoid bandwidth 0 positional argument [Eric]
 * Drop blockjob --pivot argument, it doesn't work yet and I didn't document it

 common.sh            |    8 ++--
 source/blockjob.xml  |   81 ++++++++++++++++++++++++++++++++++++
 source/blockpull.xml |  111 ++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 196 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..1763c3c
--- /dev/null
+++ b/source/blockjob.xml
@@ -0,0 +1,81 @@
+<?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>
+	Either the <italic><source file='path'></italic> filename or the
+	<italic><target dev='path'></italic> device name.  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 cancellation to complete,
+	when specified together with "--abort".
+      </description>
+    </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..15014a6
--- /dev/null
+++ b/source/blockpull.xml
@@ -0,0 +1,111 @@
+<?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>
+	Either the <italic><source file='path'></italic> filename or the
+	<italic><target dev='path'></italic> device name.  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> <italic>--wait</italic></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> <italic>--base</italic> <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.
+      </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