[libvirt] [PATCH 1/4] doc: schema: Add basic documentation for the virtual RNG device support

[Peter Krempa]

This patch documments XML elements used for (basic) support of virtual
RNG devices.

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

  <devices>
    <rng model='none'/>
  </devices>

and the more useful variant:

  <devices>
    <rng model='virtio'>
      <source type='random'>/dev/urandom</source>
    </rng>
  </devices>
---
 docs/formatdomain.html.in     | 54 +++++++++++++++++++++++++++++++++++++++++++
 docs/schemas/domaincommon.rng | 31 +++++++++++++++++++++++++
 2 files changed, 85 insertions(+)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index bb0b199..7a5f267 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -4260,6 +4260,60 @@ qemu-kvm -net nic,model=? /dev/null
         </ul>
       </dd>
     </dl>
+    <h4><a name="elementsRng">Random number generator device</a></h4>
+
+    <p>
+      The virtual random number generator device allows the host to pass
+      through entropy to guest operating systems.
+      <span class="since">Since 1.0.2</span>
+    </p>
+
+    <p>
+      Example: usage of the RNG device:
+    </p>
+<pre>
+  ...
+  <devices>
+    <rng model='virtio'>
+      <source type='chardev'>/dev/random</source>
+    </rng>
+  </devices>
+  ...
+</pre>
+    <dl>
+      <dt><code>model</code></dt>
+      <dd>
+        <p>
+          The required <code>model</code> attribute specifies what type
+          of RNG device is provided. Valid values are specific to
+          the virtualization platform:
+        </p>
+        <ul>
+          <li>'none' — disable the rng device</li>
+          <li>'virtio' — supported by qemu and virtio-rng kernel module</li>
+        </ul>
+      </dd>
+      <dt><code>source</code></dt>
+      <dd>
+        <p>
+          The <code>source</code> element specifies the source of entropy
+          to be used for the doimain. The source type is configured using the
+          <code>type</code> attribute. Supported source types are:
+        </p>
+        <ul>
+          <li>'none' — no source was configured</li>
+          <li>'random' — /dev/random or similar device as source</li>
+        </ul>
+      </dd>
+      <dt><code>source type='random'</code></dt>
+      <dd>
+        <p>
+          This source type expects a non-blocking character device as input.
+          Examples of such devices are /dev/random and /dev/urandom. The file
+          name is specified as contents of the <code>source</code> element.
+        </p>
+      </dd>
+    </dl>

     <h3><a name="seclabel">Security label</a></h3>

diff --git a/docs/schemas/domaincommon.rng b/docs/schemas/domaincommon.rng
index 67ae864..2c876f8 100644
--- a/docs/schemas/domaincommon.rng
+++ b/docs/schemas/domaincommon.rng
@@ -3095,6 +3095,7 @@
             <ref name="hub"/>
             <ref name="redirdev"/>
             <ref name="redirfilter"/>
+            <ref name="rng"/>
           </choice>
         </zeroOrMore>
         <optional>
@@ -3477,6 +3478,36 @@
     </element>
   </define>

+  <define name="rng">
+    <element name="rng">
+      <attribute name="model">
+        <choice>
+          <value>none</value>
+          <value>virtio</value>
+        </choice>
+      </attribute>
+    </element>
+  </define>
+
+  <define name="rng-source">
+    <element name="source">
+      <choice>
+        <group>
+          <attribute name="type">
+            <value>none</value>
+          </attribute>
+          <empty/>
+        </group>
+        <group>
+          <attribute name="type">
+            <value>random</value>
+          </attribute>
+          <ref name="filePath"/>
+        </group>
+      </choice>
+    </element>
+  </define>
+
   <define name="usbmaster">
     <element name="master">
       <attribute name="startport">
-- 
1.8.1