[libvirt] [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 | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index 499879e..a35316e 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -174,6 +174,18 @@ elements are mutually exclusive. <span class="since">Since 0.1.3, per-device boot since 0.8.8</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". -- 2.0.5
On 01/06/15 13:08, Michal Privoznik wrote:
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 | 12 ++++++++++++ 1 file changed, 12 insertions(+)
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index 499879e..a35316e 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -174,6 +174,18 @@ elements are mutually exclusive. <span class="since">Since 0.1.3, per-device boot since 0.8.8</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".
Thanks -- I think I would have liked to see something like this. I'm sure libvirt folks will have a few comments, but the text seems OK to me. One nit though: <smbios> is different. Its effects are not limited to firmware behavior; the full-blown guest-OS (and processes running on it) consume SMBIOS tables too. Exposing SMBIOS to guests *does* require firmware support, but I think it's reasonable to expect that support from practically all firmwares. (OVMF does support it.) So, please move the smbios section above the new warning. --*-- Also, since people will undoubtedly ask about specific knobs (despite the imperative not to document them in detail for the domain XML): - <bootmenu enable='yes' timeout='3000'/>: Currently unsupported by OVMF, but I have a WIP patch. The timeout will be rounded up to full seconds. The "boot menu" means the Intel BDS setup utility in this context. (Basically, "setup screens".) - <bios useserial='yes' rebootTimeout='0'/> edk2-based UEFI firmwares for virtual machines (OVMF for x86, ArmVirtualizationQemu for ARM) always split terminal I/O to all graphics and serial devices. In case of OVMF this means that you'll get firmware terminal IO in the graphical window and on the serial port, and for ArmVirtualizationQemu (where's no video display yet) you get serial communication. (If there were no serial communication you couldn't talk to the firmware at all.) In short, spelling out "useserial" makes no difference, and the behavior always matches useserial='yes'. "rebootTimeout" makes no sense for UEFI and will not be supported. (If nothing can be booted then the setup screens are entered again.) Thanks! Laszlo
participants (2)
-
Laszlo Ersek -
Michal Privoznik