[libvirt] [PATCH] docs: document <sysinfo> and <symbios> elements

[Eric Blake]

* docs/formatdomain.html.in: Talk about <sysinfo> throughout.
---

More in the vein of adding missing documentation.

 docs/formatdomain.html.in |   79 ++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 78 insertions(+), 1 deletions(-)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 8d6b69e..9719346 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -48,7 +48,10 @@
         a globally unique identifier for the virtual machine.
         The format must be RFC 4122 compliant, eg <code>3e3fce45-4f53-4fa7-bb32-11f34168b82b</code>.
         If omitted when defining/creating a new machine, a random
-        UUID is generated. <span class="since">Since 0.0.1</span></dd>
+        UUID is generated. It is also possible to provide the UUID
+        via a <a href="#elementsSysinfo"><code>sysinfo</code></a>
+        specification. <span class="since">Since 0.0.1, sysinfo
+        since 0.8.7</span></dd>

       <dt><code>description</code></dt>
       <dd>The content of the <code>description</code> element provides a
@@ -81,6 +84,7 @@
     <boot dev='hd'/>
     <boot dev='cdrom'/>
     <bootmenu enable='yes'/>
+    <smbios mode='sysinfo'/>
   </os>
   ...</pre>

@@ -115,6 +119,16 @@
       If not specified, the hypervisor default is used. <span class="since">
       Since 0.8.3</span>
       </dd>
+      <dt><code>smbios</code></dt>
+      <dd>How to populate SMBIOS information visible in the guest.
+      The <code>mode</code> attribute must be specified, and is either
+      "emulate" (let the hypervisor generate all values), "host" (copy
+      all of Block 0 and Block 1, except for the UUID, from the host's
+      SMBIOS values), or "sysinfo" (use the values in
+      the <a href="#elementsSysinfo">sysinfo</a> element).  If not
+      specified, the hypervisor default is used. <span class="since">
+      Since 0.8.7</span>
+      </dd>
     </dl>

     <h4><a name="elementsOSBootloader">Host bootloader</a></h4>
@@ -188,6 +202,69 @@
         installation media source / kickstart file</dd>
     </dl>

+    <h3><a name="elementsSysinfo">SMBIOS System Information</a></h3>
+
+    <p>
+      Some hypervisors allow control over what system information is
+      presented to the guest (for example, SMBIOS fields can be
+      populated by a hypervisor and inspected via
+      the <code>dmidecode</code> command in the guest).  The
+      optional <code>sysinfo</code> element covers all such categories
+      of information. <span class="since">Since 0.8.7</span>
       +    </p>
+
+<pre>
+  ...
+  <os>
+    <smbios mode='sysinfo'/>
+    ...
+  </os>
+  <sysinfo type='smbios'>
+    <bios>
+      <entry name='vendor'>LENOVO</entry>
+    </bios>
+    <system>
+      <entry name='manufacturer'>Fedora</entry>
+      <entry name='vendor'>Virt-Manager</entry>
+    </system>
+  </sysinfo>
+  ...</pre>
+
+    <p>
+      The <code>sysinfo</code> element has a mandatory
+      attribute <code>type</code> that determine the layout of
+      sub-elements, with supported values of:
+    </p>
+
+    <dl>
+      <dt><code>smbios</code></dt>
+      <dd>Sub-elements call out specific SMBIOS values, which will
+      affect the guest if used in conjunction with
+      the <code>smbios</code> sub-element of
+      the <a href="#elementsOS"><code>os</code></a> element.  Each
+      sub-element of <code>sysinfo</code> names a SMBIOS block, and
+      within those elements can be a list of <code>entry</code>
+      elements that describe a field within the block.  The following
+      blocks and entries are recognized:
+        <dl>
+          <dt><code>bios</code></dt>
+          <dd>
+            This is block 0 of SMBIOS, with entry names drawn from
+            "vendor", "version", "date", and "release".
+          </dd>
+          <dt><code>system</code></dt>
+          <dd>
+            This is block 1 of SMBIOS, with entry names drawn from
+            "manufacturer", "product", "version", "serial", "uuid",
+            "sku", and "family".  If a "uuid" entry is provided
+            alongside a
+            top-level <a href="#elementsMetadata"><code>uuid</code>
+            element</a>, the two values must match.
+          </dd>
+        </dl>
+      </dd>
+    </dl>
+
     <h3><a name="elementsResources">Basic resources</a></h3>

 <pre>
-- 
1.7.3.4