[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

[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 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>&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_device_spec.txt";>
+      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>
-- 
1.9.3


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]