Re: [libvirt] [RFC PATCH 1/5] doc: schema: Add basic documentation for the ivshmem support

This patch documents XML elements used for support of ivshmem devices. About ivshmem, please see the following documentation: http://git.qemu.org/?p=qemu.git;a=blob;f=docs/specs/ivshmem_device_spec.txt (Ivshmem documentation for qemu will be updated soon: https://lists.nongnu.org/archive/html/qemu-devel/2014-07/msg02974.html) In the devices section in the domain XML users may specify: - For ivshmem device using an ivshmem server: <ivshmem use_server='yes' role='master'/> <source file='/tmp/socket-ivshmem0'/>

<size unit='M'>32</size> <msi vectors='32' ioeventfd='on'/> </ivshmem> Note: the ivshmem server needs to be launched before creating the VM. It's not done by libvirt. - For ivshmem device not using an ivshmem server: <ivshmem use_server='no' role='peer'/> <source file='ivshmem1'/> <size unit='M'>32</size> </ivshmem> Note: the ivshmem shm needs to be created before creating the VM. It's not done by libvirt. Signed-off-by: Maxime Leroy <maxime.leroy(a)6wind.com&gt; --- docs/formatdomain.html.in | 72 +++++++++++++++++++++++++++++++++++++++++++ docs/schemas/domaincommon.rng | 57 ++++++++++++++++++++++++++++++++++ 2 files changed, 129 insertions(+) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index e5b1adb..9a9a6fa 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -4035,6 +4035,78 @@ qemu-kvm -net nic,model=? /dev/null <code>&lt;model&gt;</code> element is mandatory. </p> + <h4><a name="elementsIvshmem">Ivshmem device</a></h4> + + <p> + An ivshmem (i.e. Inter-VM shared memory) device allows to share a memory + region (created on the host via the POSIX shared memory API) between + multiple QEMU processes running different guests. + For more information, please see the + <a href="http://git.qemu.org/?p=qemu.git;a=blob;f=docs/specs/ivshmem_de... + ivshmem documentation of qemu</a>. + </p> + +<pre> + ... + &lt;devices&gt; + &lt;ivshmem use_server='yes' role='master'/&gt; + &lt;source file='/tmp/socket-ivshmem0'/&gt; + &lt;size unit='M'&gt;32&lt;/size&gt; + &lt;msi vectors='32' ioeventfd='on'/&gt; + &lt;/ivshmem&gt; + &lt;ivshmem use_server='no' role='peer'/&gt; + &lt;source file='ivshmem1'/&gt; + &lt;size unit='M'&gt;32&lt;/size&gt; + &lt;/ivshmem&gt; + &lt;/devices&gt; + ...</pre> + + <dl> + <dt><code>ivshmem</code></dt> + <dd>The <code>ivshmem</code> element has a mandatory <code>use_server</code> + attribute which takes the value "yes" or "no": + <dl> + <dt><code>"yes"</code></dt> + <dd> + Configure the ivshmen device to connect to the ivshmem server via a unix socket. + </dd> + <dt><code>"no"</code></dt> + <dd> + Configure the ivshmen device with a shared memory file. + </dd> + </dl> + </dd> + <dt><code>role</code></dt> + <dd>The <code>role</code> attribute is optional. It takes the value "master" or "peer": + <dl> + <dt><code>"master"</code></dt> + <dd> + On migration, the guest will copy the shared memory to the destination host. + </dd> + <dt><code>"peer"</code></dt> + <dd> + The device should be detached and then reattached after migration using + the PCI hotplug support. + </dd> + </dl> + Note: PCI hotplug is not supported for ivshmem device in libvirt. + </dd> + <dt><code>size</code></dt> + <dd>The optional <code>size</code> element specifies the size of the shared memory file. + </dd> + <dt><code>source</code></dt> + <dd>The <code>source</code> element is mandatory. + The <code>file</code> attribute specifies the ivshmem server socket file in server mode. + In non server mode, it specifies the shared memory file. + </dd> + <dt><code>msi</code></dt> + <dd>The optional <code>msi</code> element allows to enable MSI interrupts. This option + can only be used in server mode. The <code>vectors</code> attribute + allows to specify the number of interrupt vectors. The <code>ioeventd</code> attribute + allows to enable ioeventfd. + </dd> + </dl> + <h4><a name="elementsInput">Input devices</a></h4> <p> diff --git a/docs/schemas/domaincommon.rng b/docs/schemas/domaincommon.rng index 11f0fd0..8229921 100644 --- a/docs/schemas/domaincommon.rng +++ b/docs/schemas/domaincommon.rng @@ -3220,6 +3220,62 @@ </optional> </element> </define> + + <define name="ivshmem"> + <element name="ivshmem"> + <interleave> + <choice> + <group> + <attribute name="use_server"> + <value>yes</value> + </attribute> + <optional> + <element name="msi"> + <optional> + <ref name="ioeventfd"/> + </optional> + <optional> + <attribute name="vectors"> + <ref name="unsignedInt"/> + </attribute> + </optional> + </element> + </optional> + </group> + <group> + <attribute name="use_server"> + <value>no</value> + </attribute> + </group> + </choice> + <element name="source"> + <attribute name="file"> + <text/> + </attribute> + </element> + <optional> + <attribute name="role"> + <choice> + <value>master</value> + <value>peer</value> + </choice> + </attribute> + </optional> + <optional> + <element name="size"> + <ref name="scaledInteger"/> + </element> + </optional> + <optional> + <ref name="alias"/> + </optional> + <optional> + <ref name="address"/> + </optional> + </interleave> + </element> + </define> + <define name="memballoon"> <element name="memballoon"> <attribute name="model"> @@ -3767,6 +3823,7 @@ <ref name="redirfilter"/> <ref name="rng"/> <ref name="tpm"/> + <ref name="ivshmem"/> </choice> </zeroOrMore> <optional>