[libvirt] [PATCH 1/4] docs: Add documents for memory device

[Osier Yang]

Considering there could be other memory related devices in future,
this introduces a general device model, called memory device,
instead of a specific device like "ivshmem", currently only
"ivshmem" is supported though.

An example of the XML:

  <memory model='ivshmem'>
    <source id='nahanni' path='/tmp/nahanni'/>
    <size unit='M'>512</size>
    <vectors>8</vectors>
    </ioeventfd>
  </memory>

"source id" is required, as QEMU uses it to indentify the
shared memory device.

If "path" for "ivshmem" memory device is specified, it's going
to be setup with interrupts enabled. Otherwise interrupts is
disabled. To be more clear, let's see the QEMU command line
of both cases:

  * With interrupts (/tmp/nahanni is the ivshmem server socket path)

    /* This starts the ivshmem server */
    % ivshmem_server -m 512 -p /tmp/foo

    /* qemu command line */
    -chardev socket,path=/tmp/foo,id=nahanni
    -device ivshmem,chardev=nahanni,size=512m,vectors=8,ioeventfd=on

  * Without interrupts (no ivshmem server is needed)
    -device ivshmem,shm=nahanni,size=512m,vectors=8,ioeventfd=on

Not all ivshmem properties are supported by this patch set, but
let's support the basic ones first.

---
There is nearly no documents for ivshmem, so there might be some places which
are not proper (actually I'm not comfortable with it myself), welcomed to any
advise.
---
 docs/formatdomain.html.in     |   39 +++++++++++++++++++++++++++++++++++++++
 docs/schemas/domaincommon.rng |   38 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 77 insertions(+), 0 deletions(-)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index cc9e871..7f5efce 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -4098,6 +4098,45 @@ qemu-kvm -net nic,model=? /dev/null
       <code>model='none'</code> may be used.
     </p>
 
+    <h4><a name="elementsMemory">Memory devices</a></h4>
+
+    <p>
+      Element <code>memory</code> is used to specify memory related
+      device.  <span class="since">Only QEMU driver supports
+      since 1.0.1</span>
+    </p>
+
+<pre>
+  ...
+  <devices>
+    <memory mode='ivshmem'>
+      <source id='nahanni' path='/tmp/nahanni'/>
+      <size unit='KiB'>10240</size>
+      <ioeventfd/>
+    </memory>
+  </devices>
+  ...</pre>
+
+    <dl>
+      <dt><code>memory</code></dt>
+      <dd>
+        The <code>memory</code> element has one mandatory attribute,
+        <code>model</code>, its value can only be 'ivshmem' currently.
+        The optional element <code>source</code> has two attributes.
+        Attribute <code>id</code> is mandatory, to specify the name of
+        the memory device; Attribute <code>path</code> specifies the socket
+        path of the 'ivshmem' memory server. If <code>path</code> is not
+        specified, the memory device is setup without using interrupts.
+        The element <code>size</code> specifies the memory device size,
+        attribute <code>unit</code> behaves the same as for element
+        <code>memory</code>. Its value must be power of 2 in bytes.
+        The element <code>vectors</code> to specify how many vectors for
+        the 'ivshmem' memory device.
+        The element <code>ioeventfd</code> controls whether or not
+        ioeventfd is turned on for 'ivshmem' memory device.
+      </dd>
+    </dl>
+
     <p>
       Example automatically added device with KVM
     </p>
diff --git a/docs/schemas/domaincommon.rng b/docs/schemas/domaincommon.rng
index ed7d1d0..c55b6a3 100644
--- a/docs/schemas/domaincommon.rng
+++ b/docs/schemas/domaincommon.rng
@@ -2798,6 +2798,43 @@
       </zeroOrMore>
     </element>
   </define>
+  <define name="memory">
+    <element name="memory">
+      <group>
+        <attribute name="model">
+          <value>ivshmem</value>
+        </attribute>
+        <interleave>
+          <element name="source">
+            <attribute name="id">
+              <text/>
+            </attribute>
+            <optional>
+              <attribute name="path">
+                <ref name="absFilePath"/>
+              </attribute>
+            </optional>
+          </element>
+          <element name="size">
+            <ref name="scaledInteger"/>
+          </element>
+          <optional>
+            <element name="vectors">
+              <ref name="unsignedInt"/>
+            </element>
+          </optional>
+          <optional>
+            <element name="ioeventfd">
+              <empty/>
+            </element>
+          </optional>
+          <optional>
+            <ref name="address"/>
+          </optional>
+        </interleave>
+      </group>
+    </element>
+  </define>
   <define name="hostdev">
     <element name="hostdev">
       <optional>
@@ -2965,6 +3002,7 @@
             <ref name="hub"/>
             <ref name="redirdev"/>
             <ref name="redirfilter"/>
+            <ref name="memory"/>
           </choice>
         </zeroOrMore>
         <optional>
-- 
1.7.7.6