From fa16c80f52136371dcc88649052fd9f7adff73eb Mon Sep 17 00:00:00 2001
From: Peter Krempa <pkrempa@redhat.com>
Date: Thu, 20 Dec 2012 12:06:52 +0100
Subject: [PATCH] doc: schema: Add basic documentation for the virtual RNG
 device support

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

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

For the default 'random' backend:
  <devices>
    <rng model='virtio'>
      <backend model='random'>/dev/urandom</backend>
    </rng>
  </devices>

For the slightly more advanced EGD backend:
  <devices>
    <rng model='virtio'>
      <backend model='egd' type='udp'>
        <!-- this is a definition of a character device -->
        <source mode='bind' service='1234'/>
        <source mode='connect' host='1.2.3.4' service='1234'/>
        <!-- or other valid character device configuration -->
      </backend>
    </rng>
  </devices>

For the planned random daemon/pool:
  <devices>
    <rng model='virtio'>
      <backend model='pool' pool='poolname'>class</backend>
    </rng>
  </devices>

to enable the RNG device for guests.
---
 docs/formatdomain.html.in     | 69 +++++++++++++++++++++++++++++++++++
 docs/schemas/domaincommon.rng | 32 ++++++++++++++++
 2 files changed, 101 insertions(+)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index a9003d70d..12c946858 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -4279,6 +4279,75 @@ 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.3</span>
+    </p>
+
+    <p>
+      Example: usage of the RNG device:
+    </p>
+<pre>
+  ...
+  &lt;devices&gt;
+    &lt;rng model='virtio'&gt;
+      &lt;backend model='random'&gt;/dev/random&lt;/backend&gt;
+      &lt;!-- OR --&gt;
+      &lt;backend model='egd' type='udp'&gt;
+        &lt;source mode='bind' service='1234'&gt;
+        &lt;source mode='connect' host='1.2.3.4' service='1234'&gt;
+      &lt;/backend&gt;
+    &lt;/rng&gt;
+  &lt;/devices&gt;
+  ...
+</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>'virtio' &mdash; supported by qemu and virtio-rng kernel module</li>
+        </ul>
+      </dd>
+      <dt><code>backend</code></dt>
+      <dd>
+        <p>
+          The <code>backend</code> element specifies the source of entropy
+          to be used for the domain. The source model is configured using the
+          <code>model</code> attribute. Supported source models are:
+        </p>
+        <ul>
+          <li>'random' &mdash; /dev/random (default) or similar device as source</li>
+          <li>'egd' &mdash; a EGD protocol backend</li>
+        </ul>
+      </dd>
+      <dt><code>backend type='random'</code></dt>
+      <dd>
+        <p>
+          This backend 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>backend</code> element.
+          When no file name is specified the hypervisor default is used.
+        </p>
+      </dd>
+      <dt><code>backend type='egd'</code></dt>
+      <dd>
+        <p>
+          This backend connects to a source using the EGD protocol.
+          The source is specified as a character device. Refer to
+          <a href='#elementsCharHostInterface'>character device host interface</a>
+          for more information.
+        </p>
+      </dd>
+
+    </dl>
 
     <h3><a name="seclabel">Security label</a></h3>
 
diff --git a/docs/schemas/domaincommon.rng b/docs/schemas/domaincommon.rng
index 63be4aaeb..8330a507f 100644
--- a/docs/schemas/domaincommon.rng
+++ b/docs/schemas/domaincommon.rng
@@ -3126,6 +3126,7 @@
             <ref name="hub"/>
             <ref name="redirdev"/>
             <ref name="redirfilter"/>
+            <ref name="rng"/>
           </choice>
         </zeroOrMore>
         <optional>
@@ -3514,6 +3515,37 @@
     </element>
   </define>
 
+  <define name="rng">
+    <element name="rng">
+      <attribute name="model">
+        <choice>
+          <value>virtio</value>
+        </choice>
+      </attribute>
+      <ref name="rng-backend"/>
+    </element>
+  </define>
+
+  <define name="rng-backend">
+    <element name="backend">
+      <choice>
+        <group>
+          <attribute name="model">
+            <value>random</value>
+          </attribute>
+          <ref name="filePath"/>
+        </group>
+        <group>
+          <attribute name="model">
+            <value>egd</value>
+          </attribute>
+          <ref name="qemucdevSrcType"/>
+          <ref name="qemucdevSrcDef"/>
+        </group>
+      </choice>
+    </element>
+  </define>
+
   <define name="usbmaster">
     <element name="master">
       <attribute name="startport">
-- 
2.39.5