[libvirt] [RFC PATCH 1/5] doc: schema: Add basic documentation for the ivshmem support
Maxime Leroy
maxime.leroy at 6wind.com
Tue Aug 5 16:48:01 UTC 2014
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 at 6wind.com>
---
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><model></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_device_spec.txt">
+ ivshmem documentation of qemu</a>.
+ </p>
+
+<pre>
+ ...
+ <devices>
+ <ivshmem use_server='yes' role='master'/>
+ <source file='/tmp/socket-ivshmem0'/>
+ <size unit='M'>32</size>
+ <msi vectors='32' ioeventfd='on'/>
+ </ivshmem>
+ <ivshmem use_server='no' role='peer'/>
+ <source file='ivshmem1'/>
+ <size unit='M'>32</size>
+ </ivshmem>
+ </devices>
+ ...</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>
--
1.9.3
More information about the libvir-list
mailing list