From 241ab97d7e1046da64889d18980d40b9e6cc3e18 Mon Sep 17 00:00:00 2001
From: Michal Privoznik <mprivozn@redhat.com>
Date: Tue, 6 Jan 2015 13:04:13 +0100
Subject: [PATCH] docs: Document some -boot option limitations on UEFI

It was brought to my attention that some -boot options may not
work with UEFI. For instance, rebootTimeout is very SeaBIOS
specific,splash logo is not implemented yet on OVMF, and so on.
We should document this limitation at least.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
---
 docs/formatdomain.html.in | 38 +++++++++++++++++++++++++-------------
 1 file changed, 25 insertions(+), 13 deletions(-)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 499879eae9..0df2b76ee4 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -174,6 +174,31 @@
         elements are mutually exclusive. <span class="since">Since 0.1.3,
         per-device boot since 0.8.8</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;
+        the <a href="html/libvirt-libvirt-host.html#virConnectGetSysinfo">
+        <code>virConnectGetSysinfo</code></a> call can be
+        used to see what values are copied), 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>
+      <p>Up till here the BIOS/UEFI configuration knobs are generic enough to
+      be implemented by majority (if not all) firmwares out there. However,
+      from now on not every single setting makes sense to all firmwares. For
+      instance, <code>rebootTimeout</code> doesn't make sense for UEFI,
+      <code>useserial</code> might not be usable with a BIOS firmware that
+      doesn't produce any output onto serial line, etc. Moreover, firmwares
+      don't usually export their capabilities for libvirt (or users) to check.
+      And the set of their capabilities can change with every new release.
+      Hence users are advised to try the settings they use before relying on
+      them in production.</p>
+  <dl>
       <dt><code>bootmenu</code></dt>
       <dd> Whether or not to enable an interactive boot menu prompt on guest
       startup. The <code>enable</code> attribute can be either "yes" or "no".
@@ -184,19 +209,6 @@
       in range [0, 65535] inclusive and it is ignored unless <code>enable</code>
       is set to "yes". <span class="since">Since 1.2.8</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;
-      the <a href="html/libvirt-libvirt-host.html#virConnectGetSysinfo">
-      <code>virConnectGetSysinfo</code></a> call can be
-      used to see what values are copied), 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>
       <dt><code>bios</code></dt>
       <dd>This element has attribute <code>useserial</code> with possible
         values <code>yes</code> or <code>no</code>. It enables or disables