[libvirt] [PATCH] docs: document <qemu:commandline> xml

[Eric Blake]

Even though we technically don't support <qemu:commandline> (as in,
if you mis-use things, you get to keep the pieces), we should at
least document how to use it.

* docs/drvqemu.html.in (qemucommand): New section.
---

I wrote this in response to an IRC comment lamenting that the only
existing documentation was reading the examples in the testsuite.

 docs/drvqemu.html.in |   61 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 61 insertions(+), 0 deletions(-)

diff --git a/docs/drvqemu.html.in b/docs/drvqemu.html.in
index 4da3817..d6effb5 100644
--- a/docs/drvqemu.html.in
+++ b/docs/drvqemu.html.in
@@ -513,6 +513,67 @@ $ virsh domxml-to-native qemu-argv demo.xml
   -serial none -parallel none -usb
 </pre>

+    <h2><a name="qemucommand">Pass-through of arbitrary qemu
+    commands</a></h2>
+
+    <p>Libvirt provides an optional
+      library <code>libvirt-qemu.so</code> for dealing specifically
+      with qemu.  This library is <b>unsupported</b>, in that it is
+      not guaranteed to have a stable API, and that mis-using the
+      library may result in inconsistent state the crashes libvirtd.
+      However, when used correctly, this library allows testing
+      specific qemu features that have not yet been ported to the
+      generic libvirt XML and API interfaces.
+    </p>
+    <p>The library provides two
+      API: <code>virDomainQemuMonitorCommand</code>, for sending an
+      arbitrary monitor command (in either HMP or QMP format) to a
+      qemu guest (<span class="since">Since 0.8.3</span>),
+      and <code>virDomainQemuAttach</code>, for registering a qemu
+      domain that was manually started so that it can then be managed
+      by libvirtd (<span class="since">Since 0.9.4</span>).
+    </p>
+    <p>Additionally, the following XML additions allow fine-tuning of
+      the command line given to qemu when starting a domain
+      (<span class="since">Since 0.8.3</span>).  In order to use the
+      XML additions, it is necessary to issue an XML namespace request
+      (the special <code>xmlns:<i>name</i></code> attribute) that
+      pulls in <code>http://libirt.org/schemas/domain/qemu/1.0</code>;
+      typically, the namespace is given the name
+      of <code>qemu</code>.  With the namespace in place, it is then
+      possible to add an element <code><qemu:commandline></code>
+      under <code>driver</code>, with the following sub-elements
+      repeated as often as needed:
+      <dl>
+        <dt><code>qemu:arg</code></dt>
+        <dd>Add an additional command-line argument to the qemu
+          process when starting the domain, given by the value of the
+          attribute <code>value</code>.
+        </dd>
+        <dt><code>qemu:env</code></dt>
+        <dd>Add an additional environment variable to the qemu
+          process when starting the domain, given with the name-value
+          pair recorded in the attributes <code>name</code>
+          and <code>value</code>.</dd>
+      </dl>
+
+      <p>Example:</p><pre>
+<domain type='qemu' xmlns:qemu='http://libirt.org/schemas/domain/qemu/1.0'>
+  <name>QEmu-fedora-i686</name>
+  <memory>219200</memory>
+  <os>
+    <type arch='i686' machine='pc'>hvm</type>
+  </os>
+  <devices>
+    <emulator>/usr/bin/qemu-system-x86_64</emulator>
+  </devices>
+  <qemu:commandline>
+    <qemu:arg value='-newarg'/>
+    <qemu:env name='QEMU_ENV' value='VAL'/>
+  </qemu:commandline>
+</domain>
+</pre>
+
     <h2><a name="xmlconfig">Example domain XML config</a></h2>

     <h3>QEMU emulated guest on x86_64</h3>
-- 
1.7.7.4