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

[Daniel P. Berrange]

On Mon, Dec 19, 2011 at 12:12:31PM -0700, Eric Blake wrote:
> 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.

Co-incidentally I also blogged about it today

http://berrange.com/posts/2011/12/19/using-command-line-arg-monitor-command-passthrough-with-libvirt-and-kvm/


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

ACK

Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org       -o-       http://live.gnome.org/gtk-vnc :|