[libvirt] [PATCH v1 1/6] doc: schema: Add documentation for the shmem support

[Maxime Leroy]

This patch documents XML elements used for support of shmem
devices.

Considering there could be other shared memory related devices,
this patch introduces a general device model, called shmem device.
Currenly "ivshmem" is the only shared memory model supported.

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:
http://lists.gnu.org/archive/html/qemu-devel/2014-08/msg01244.html)

In the devices section in the domain XML users may specify:

- For ivshmem device using an ivshmem server:

 <shmem name='shmem0' model='ivshmem'>
   <source file='/tmp/socket-ivshmem0'/>
   <size unit='M'>32</size>
   <msi vectors='32' ioeventfd='on'/>
 </shmem>

- For ivshmem device not using an ivshmem server:

 <shmem name='ivshmem1' model='ivshmem'>
   <size unit='M'>32</size>
 </shmem>

Signed-off-by: Maxime Leroy <maxime.leroy at 6wind.com>
---
 docs/formatdomain.html.in     | 68 +++++++++++++++++++++++++++++++++++++++++++
 docs/schemas/domaincommon.rng | 49 +++++++++++++++++++++++++++++++
 2 files changed, 117 insertions(+)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index ed17389..c7644bc 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -5422,6 +5422,74 @@ qemu-kvm -net nic,model=? /dev/null
     </dd>
   </dl>
 
+    <h4><a name="elementsShmem">Shmem device</a></h4>
+
+    <p>
+      A shmem (i.e. shared memory) device allows to share a memory
+      region between different virtual machines and the host.
+    </p>
+
+<pre>
+  ...
+  <devices>
+    <shmem name='shmem0' model='ivshmem'/>
+    <shmem name='shmem1' model='ivshmem'/>
+  </devices>
+  ...</pre>
+
+    <dl>
+       <dt><code>shmem</code></dt>
+       <dd>
+         The <code>shmem</code> element has one mandatory attribute,
+         <code>name</code> to identify the shared memory. The optional element
+         <code>model</code> specify the type of shared memory. Only one mode of
+         shared-memory is currently supported: <code>ivshmem</code>.
+       </dd>
+    </dl>
+
+    <h5><a name="elementsIvshmem">Ivshmem model</a></h5>
+
+    <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>
+    <shmem name='shmem0' model='ivshmem'>
+      <server path='/tmp/socket-shmem0'/>
+      <size unit='M'>32</size>
+      <msi vectors='32' ioeventfd='on'/>
+    </shmem>
+    <shmem name='shmem1' model='ivshmem'>
+      <size unit='M'>32</size>
+    </shmem>
+  </devices>
+  ...</pre>
+
+  <dl>
+    <dt><code>server</code></dt>
+    <dd>The optional <code>server</code> element can be used to configure an
+      ivshmem device connected to the ivshmem server via a unix socket. The
+      <code>path</code> attribute specifies the path to the unix socket.
+    </dd>
+    <dt><code>size</code></dt>
+    <dd>The optional <code>size</code> element specifies the size of the shared memory.
+    </dd>
+    <dt><code>msi</code></dt>
+    <dd>The optional <code>msi</code> element allows to enable MSI interrupts.
+      This option can only be used with the <code>server</code> attribute.
+      The <code>vectors</code> attribute can be used to specify the number of
+      interrupt vectors. The <code>ioeventd</code> attribute allows to enable
+      ioeventfd.
+    </dd>
+  </dl>
+
     <h3><a name="seclabel">Security label</a></h3>
 
     <p>
diff --git a/docs/schemas/domaincommon.rng b/docs/schemas/domaincommon.rng
index 033f2f6..64abf2b 100644
--- a/docs/schemas/domaincommon.rng
+++ b/docs/schemas/domaincommon.rng
@@ -3221,6 +3221,54 @@
       </optional>
     </element>
   </define>
+
+  <define name="shmem">
+    <element name="shmem">
+      <attribute name="name"/>
+      <optional>
+        <ref name="ivshmem"/>
+      </optional>
+      <optional>
+        <ref name="alias"/>
+      </optional>
+      <optional>
+        <ref name="address"/>
+      </optional>
+    </element>
+  </define>
+
+ <define name="ivshmem">
+   <group>
+     <attribute name="model">
+       <value>ivshmem</value>
+     </attribute>
+     <interleave>
+       <optional>
+         <element name="server">
+           <attribute name="path"/>
+         </element>
+       </optional>
+       <optional>
+         <element name="msi">
+           <optional>
+             <ref name="ioeventfd"/>
+           </optional>
+           <optional>
+             <attribute name="vectors">
+               <ref name="unsignedInt"/>
+             </attribute>
+           </optional>
+         </element>
+       </optional>
+       <optional>
+         <element name="size">
+           <ref name="scaledInteger"/>
+         </element>
+       </optional>
+     </interleave>
+   </group>
+ </define>
+
   <define name="memballoon">
     <element name="memballoon">
       <attribute name="model">
@@ -3807,6 +3855,7 @@
             <ref name="redirfilter"/>
             <ref name="rng"/>
             <ref name="tpm"/>
+            <ref name="shmem"/>
           </choice>
         </zeroOrMore>
         <optional>
-- 
1.9.3