2423 lines
105 KiB
Plaintext
2423 lines
105 KiB
Plaintext
|
Open Virtual Machine Firmware (OVMF) Status Report
|
||
|
|
July 2014 (with updates in August 2014 - January 2015)
|
||
|
|
|
||
|
|
Author: Laszlo Ersek <lersek@redhat.com>
|
||
|
|
Copyright (C) 2014-2015, Red Hat, Inc.
|
||
|
|
CC BY-SA 4.0 <http://creativecommons.org/licenses/by-sa/4.0/>
|
||
|
|
|
||
|
|
Abstract
|
||
|
|
--------
|
||
|
|
|
||
|
|
The Unified Extensible Firmware Interface (UEFI) is a specification that
|
||
|
|
defines a software interface between an operating system and platform firmware.
|
||
|
|
UEFI is designed to replace the Basic Input/Output System (BIOS) firmware
|
||
|
|
interface.
|
||
|
|
|
||
|
|
Hardware platform vendors have been increasingly adopting the UEFI
|
||
|
|
Specification to govern their boot firmware developments. OVMF (Open Virtual
|
||
|
|
Machine Firmware), a sub-project of Intel's EFI Development Kit II (edk2),
|
||
|
|
enables UEFI support for Ia32 and X64 Virtual Machines.
|
||
|
|
|
||
|
|
This paper reports on the status of the OVMF project, treats features and
|
||
|
|
limitations, gives end-user hints, and examines some areas in-depth.
|
||
|
|
|
||
|
|
Keywords: ACPI, boot options, CSM, edk2, firmware, flash, fw_cfg, KVM, memory
|
||
|
|
map, non-volatile variables, OVMF, PCD, QEMU, reset vector, S3, Secure Boot,
|
||
|
|
Smbios, SMM, TianoCore, UEFI, VBE shim, Virtio
|
||
|
|
|
||
|
|
Table of Contents
|
||
|
|
-----------------
|
||
|
|
|
||
|
|
- Motivation
|
||
|
|
- Scope
|
||
|
|
- Example qemu invocation
|
||
|
|
- Installation of OVMF guests with virt-manager and virt-install
|
||
|
|
- Supported guest operating systems
|
||
|
|
- Compatibility Support Module (CSM)
|
||
|
|
- Phases of the boot process
|
||
|
|
- Project structure
|
||
|
|
- Platform Configuration Database (PCD)
|
||
|
|
- Firmware image structure
|
||
|
|
- S3 (suspend to RAM and resume)
|
||
|
|
- A comprehensive memory map of OVMF
|
||
|
|
- Known Secure Boot limitations
|
||
|
|
- Variable store and LockBox in SMRAM
|
||
|
|
- Select features
|
||
|
|
- X64-specific reset vector for OVMF
|
||
|
|
- Client library for QEMU's firmware configuration interface
|
||
|
|
- Guest ACPI tables
|
||
|
|
- Guest SMBIOS tables
|
||
|
|
- Platform-specific boot policy
|
||
|
|
- Virtio drivers
|
||
|
|
- Platform Driver
|
||
|
|
- Video driver
|
||
|
|
- Afterword
|
||
|
|
|
||
|
|
Motivation
|
||
|
|
----------
|
||
|
|
|
||
|
|
OVMF extends the usual benefits of virtualization to UEFI. Reasons to use OVMF
|
||
|
|
include:
|
||
|
|
|
||
|
|
- Legacy-free guests. A UEFI-based environment eliminates dependencies on
|
||
|
|
legacy address spaces and devices. This is especially beneficial when used
|
||
|
|
with physically assigned devices where the legacy operating mode is
|
||
|
|
troublesome to support, ex. assigned graphics cards operating in legacy-free,
|
||
|
|
non-VGA mode in the guest.
|
||
|
|
|
||
|
|
- Future proof guests. The x86 market is steadily moving towards a legacy-free
|
||
|
|
platform and guest operating systems may eventually require a UEFI
|
||
|
|
environment. OVMF provides that next generation firmware support for such
|
||
|
|
applications.
|
||
|
|
|
||
|
|
- GUID partition tables (GPTs). MBR partition tables represent partition
|
||
|
|
offsets and sizes with 32-bit integers, in units of 512 byte sectors. This
|
||
|
|
limits the addressable portion of the disk to 2 TB. GPT represents logical
|
||
|
|
block addresses with 64 bits.
|
||
|
|
|
||
|
|
- Liberating boot loader binaries from residing in contested and poorly defined
|
||
|
|
space between the partition table and the partitions.
|
||
|
|
|
||
|
|
- Support for booting off disks (eg. pass-through physical SCSI devices) with a
|
||
|
|
4kB physical and logical sector size, i.e. which don't have 512-byte block
|
||
|
|
emulation.
|
||
|
|
|
||
|
|
- Development and testing of Secure Boot-related features in guest operating
|
||
|
|
systems. Although OVMF's Secure Boot implementation is currently not secure
|
||
|
|
against malicious UEFI drivers, UEFI applications, and guest kernels,
|
||
|
|
trusted guest code that only uses standard UEFI interfaces will find a valid
|
||
|
|
Secure Boot environment under OVMF, with working key enrollment and signature
|
||
|
|
validation. This enables development and testing of portable, Secure
|
||
|
|
Boot-related guest code.
|
||
|
|
|
||
|
|
- Presence of non-volatile UEFI variables. This furthers development and
|
||
|
|
testing of OS installers, UEFI boot loaders, and unique, dependent guest OS
|
||
|
|
features. For example, an efivars-backed pstore (persistent storage)
|
||
|
|
file system works under Linux.
|
||
|
|
|
||
|
|
- Altogether, a near production-level UEFI environment for virtual machines
|
||
|
|
when Secure Boot is not required.
|
||
|
|
|
||
|
|
Scope
|
||
|
|
-----
|
||
|
|
|
||
|
|
UEFI and especially Secure Boot have been topics fraught with controversy and
|
||
|
|
political activism. This paper sidesteps these aspects and strives to focus on
|
||
|
|
use cases, hands-on information for end users, and technical details.
|
||
|
|
|
||
|
|
Unless stated otherwise, the expression "X supports Y" means "X is technically
|
||
|
|
compatible with interfaces provided or required by Y". It does not imply
|
||
|
|
support as an activity performed by natural persons or companies.
|
||
|
|
|
||
|
|
We discuss the status of OVMF at a state no earlier than edk2 SVN revision
|
||
|
|
16158. The paper concentrates on upstream projects and communities, but
|
||
|
|
occasionally it pans out about OVMF as it is planned to be shipped (as
|
||
|
|
Technical Preview) in Red Hat Enterprise Linux 7.1. Such digressions are marked
|
||
|
|
with the [RHEL] margin notation.
|
||
|
|
|
||
|
|
Although other VMMs and accelerators are known to support (or plan to support)
|
||
|
|
OVMF to various degrees -- for example, VirtualBox, Xen, BHyVe --, we'll
|
||
|
|
emphasize OVMF on qemu/KVM, because QEMU and KVM have always been Red Hat's
|
||
|
|
focus wrt. OVMF.
|
||
|
|
|
||
|
|
The recommended upstream QEMU version is 2.1+. The recommended host Linux
|
||
|
|
kernel (KVM) version is 3.10+. The recommended QEMU machine type is
|
||
|
|
"qemu-system-x86_64 -M pc-i440fx-2.1" or later.
|
||
|
|
|
||
|
|
The term "TianoCore" is used interchangeably with "edk2" in this paper.
|
||
|
|
|
||
|
|
Example qemu invocation
|
||
|
|
-----------------------
|
||
|
|
|
||
|
|
The following commands give a quick foretaste of installing a UEFI operating
|
||
|
|
system on OVMF, relying only on upstream edk2 and qemu.
|
||
|
|
|
||
|
|
- Clone and build OVMF:
|
||
|
|
|
||
|
|
git clone https://github.com/tianocore/edk2.git
|
||
|
|
cd edk2
|
||
|
|
nice OvmfPkg/build.sh -a X64 -n $(getconf _NPROCESSORS_ONLN)
|
||
|
|
|
||
|
|
(Note that this ad-hoc build will not include the Secure Boot feature.)
|
||
|
|
|
||
|
|
- The build output file, "OVMF.fd", includes not only the executable firmware
|
||
|
|
code, but the non-volatile variable store as well. For this reason, make a
|
||
|
|
VM-specific copy of the build output (the variable store should be private to
|
||
|
|
the virtual machine):
|
||
|
|
|
||
|
|
cp Build/OvmfX64/DEBUG_GCC4?/FV/OVMF.fd fedora.flash
|
||
|
|
|
||
|
|
(The variable store and the firmware executable are also available in the
|
||
|
|
build output as separate files: "OVMF_VARS.fd" and "OVMF_CODE.fd". This
|
||
|
|
enables central management and updates of the firmware executable, while each
|
||
|
|
virtual machine can retain its own variable store.)
|
||
|
|
|
||
|
|
- Download a Fedora LiveCD:
|
||
|
|
|
||
|
|
wget https://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Xfce-x86_64-20-1.iso
|
||
|
|
|
||
|
|
- Create a virtual disk (qcow2 format, 20 GB in size):
|
||
|
|
|
||
|
|
qemu-img create -f qcow2 fedora.img 20G
|
||
|
|
|
||
|
|
- Create the following qemu wrapper script under the name "fedora.sh":
|
||
|
|
|
||
|
|
# Basic virtual machine properties: a recent i440fx machine type, KVM
|
||
|
|
# acceleration, 2048 MB RAM, two VCPUs.
|
||
|
|
OPTS="-M pc-i440fx-2.1 -enable-kvm -m 2048 -smp 2"
|
||
|
|
|
||
|
|
# The OVMF binary, including the non-volatile variable store, appears as a
|
||
|
|
# "normal" qemu drive on the host side, and it is exposed to the guest as a
|
||
|
|
# persistent flash device.
|
||
|
|
OPTS="$OPTS -drive if=pflash,format=raw,file=fedora.flash"
|
||
|
|
|
||
|
|
# The hard disk is exposed to the guest as a virtio-block device. OVMF has a
|
||
|
|
# driver stack that supports such a disk. We specify this disk as first boot
|
||
|
|
# option. OVMF recognizes the boot order specification.
|
||
|
|
OPTS="$OPTS -drive id=disk0,if=none,format=qcow2,file=fedora.img"
|
||
|
|
OPTS="$OPTS -device virtio-blk-pci,drive=disk0,bootindex=0"
|
||
|
|
|
||
|
|
# The Fedora installer disk appears as an IDE CD-ROM in the guest. This is
|
||
|
|
# the 2nd boot option.
|
||
|
|
OPTS="$OPTS -drive id=cd0,if=none,format=raw,readonly"
|
||
|
|
OPTS="$OPTS,file=Fedora-Live-Xfce-x86_64-20-1.iso"
|
||
|
|
OPTS="$OPTS -device ide-cd,bus=ide.1,drive=cd0,bootindex=1"
|
||
|
|
|
||
|
|
# The following setting enables S3 (suspend to RAM). OVMF supports S3
|
||
|
|
# suspend/resume.
|
||
|
|
OPTS="$OPTS -global PIIX4_PM.disable_s3=0"
|
||
|
|
|
||
|
|
# OVMF emits a number of info / debug messages to the QEMU debug console, at
|
||
|
|
# ioport 0x402. We configure qemu so that the debug console is indeed
|
||
|
|
# available at that ioport. We redirect the host side of the debug console to
|
||
|
|
# a file.
|
||
|
|
OPTS="$OPTS -global isa-debugcon.iobase=0x402 -debugcon file:fedora.ovmf.log"
|
||
|
|
|
||
|
|
# QEMU accepts various commands and queries from the user on the monitor
|
||
|
|
# interface. Connect the monitor with the qemu process's standard input and
|
||
|
|
# output.
|
||
|
|
OPTS="$OPTS -monitor stdio"
|
||
|
|
|
||
|
|
# A USB tablet device in the guest allows for accurate pointer tracking
|
||
|
|
# between the host and the guest.
|
||
|
|
OPTS="$OPTS -device piix3-usb-uhci -device usb-tablet"
|
||
|
|
|
||
|
|
# Provide the guest with a virtual network card (virtio-net).
|
||
|
|
#
|
||
|
|
# Normally, qemu provides the guest with a UEFI-conformant network driver
|
||
|
|
# from the iPXE project, in the form of a PCI expansion ROM. For this test,
|
||
|
|
# we disable the expansion ROM and allow OVMF's built-in virtio-net driver to
|
||
|
|
# take effect.
|
||
|
|
#
|
||
|
|
# On the host side, we use the SLIRP ("user") network backend, which has
|
||
|
|
# relatively low performance, but it doesn't require extra privileges from
|
||
|
|
# the user executing qemu.
|
||
|
|
OPTS="$OPTS -netdev id=net0,type=user"
|
||
|
|
OPTS="$OPTS -device virtio-net-pci,netdev=net0,romfile="
|
||
|
|
|
||
|
|
# A Spice QXL GPU is recommended as the primary VGA-compatible display
|
||
|
|
# device. It is a full-featured virtual video card, with great operating
|
||
|
|
# system driver support. OVMF supports it too.
|
||
|
|
OPTS="$OPTS -device qxl-vga"
|
||
|
|
|
||
|
|
qemu-system-x86_64 $OPTS
|
||
|
|
|
||
|
|
- Start the Fedora guest:
|
||
|
|
|
||
|
|
sh fedora.sh
|
||
|
|
|
||
|
|
- The above command can be used for both installation and later boots of the
|
||
|
|
Fedora guest.
|
||
|
|
|
||
|
|
- In order to verify basic OVMF network connectivity:
|
||
|
|
|
||
|
|
- Assuming that the non-privileged user running qemu belongs to group G
|
||
|
|
(where G is a numeric identifier), ensure as root on the host that the
|
||
|
|
group range in file "/proc/sys/net/ipv4/ping_group_range" includes G.
|
||
|
|
|
||
|
|
- As the non-privileged user, boot the guest as usual.
|
||
|
|
|
||
|
|
- On the TianoCore splash screen, press ESC.
|
||
|
|
|
||
|
|
- Navigate to Boot Manager | EFI Internal Shell
|
||
|
|
|
||
|
|
- In the UEFI Shell, issue the following commands:
|
||
|
|
|
||
|
|
ifconfig -s eth0 dhcp
|
||
|
|
ping A.B.C.D
|
||
|
|
|
||
|
|
where A.B.C.D is a public IPv4 address in dotted decimal notation that your
|
||
|
|
host can reach.
|
||
|
|
|
||
|
|
- Type "quit" at the (qemu) monitor prompt.
|
||
|
|
|
||
|
|
Installation of OVMF guests with virt-manager and virt-install
|
||
|
|
--------------------------------------------------------------
|
||
|
|
|
||
|
|
(1) Assuming OVMF has been installed on the host with the following files:
|
||
|
|
- /usr/share/OVMF/OVMF_CODE.fd
|
||
|
|
- /usr/share/OVMF/OVMF_VARS.fd
|
||
|
|
|
||
|
|
locate the "nvram" stanza in "/etc/libvirt/qemu.conf", and edit it as
|
||
|
|
follows:
|
||
|
|
|
||
|
|
nvram = [ "/usr/share/OVMF/OVMF_CODE.fd:/usr/share/OVMF/OVMF_VARS.fd" ]
|
||
|
|
|
||
|
|
(2) Restart libvirtd with your Linux distribution's service management tool;
|
||
|
|
for example,
|
||
|
|
|
||
|
|
systemctl restart libvirtd
|
||
|
|
|
||
|
|
(3) In virt-manager, proceed with the guest installation as usual:
|
||
|
|
- select File | New Virtual Machine,
|
||
|
|
- advance to Step 5 of 5,
|
||
|
|
- in Step 5, check "Customize configuration before install",
|
||
|
|
- click Finish;
|
||
|
|
- in the customization dialog, select Overview | Firmware, and choose UEFI,
|
||
|
|
- click Apply and Begin Installation.
|
||
|
|
|
||
|
|
(4) With virt-install:
|
||
|
|
|
||
|
|
LDR="loader=/usr/share/OVMF/OVMF_CODE.fd,loader_ro=yes,loader_type=pflash"
|
||
|
|
virt-install \
|
||
|
|
--name fedora20 \
|
||
|
|
--memory 2048 \
|
||
|
|
--vcpus 2 \
|
||
|
|
--os-variant fedora20 \
|
||
|
|
--boot hd,cdrom,$LDR \
|
||
|
|
--disk size=20 \
|
||
|
|
--disk path=Fedora-Live-Xfce-x86_64-20-1.iso,device=cdrom,bus=scsi
|
||
|
|
|
||
|
|
(5) A popular, distribution-independent, bleeding-edge OVMF package is
|
||
|
|
available under <https://www.kraxel.org/repos/>, courtesy of Gerd Hoffmann.
|
||
|
|
|
||
|
|
The "edk2.git-ovmf-x64" package provides the following files, among others:
|
||
|
|
- /usr/share/edk2.git/ovmf-x64/OVMF_CODE-pure-efi.fd
|
||
|
|
- /usr/share/edk2.git/ovmf-x64/OVMF_VARS-pure-efi.fd
|
||
|
|
|
||
|
|
When using this package, adapt steps (1) and (4) accordingly.
|
||
|
|
|
||
|
|
(6) Additionally, the "edk2.git-ovmf-x64" package seeks to simplify the
|
||
|
|
enablement of Secure Boot in a virtual machine (strictly for development
|
||
|
|
and testing purposes).
|
||
|
|
|
||
|
|
- Boot the virtual machine off the CD-ROM image called
|
||
|
|
"/usr/share/edk2.git/ovmf-x64/UefiShell.iso"; before or after installing
|
||
|
|
the main guest operating system.
|
||
|
|
|
||
|
|
- When the UEFI shell appears, issue the following commands:
|
||
|
|
|
||
|
|
EnrollDefaultKeys.efi
|
||
|
|
reset -s
|
||
|
|
|
||
|
|
- The EnrollDefaultKeys.efi utility enrolls the following keys:
|
||
|
|
|
||
|
|
- A static example X.509 certificate (CN=TestCommonName) as Platform Key
|
||
|
|
and first Key Exchange Key.
|
||
|
|
|
||
|
|
The private key matching this certificate has been destroyed (but you
|
||
|
|
shouldn't trust this statement).
|
||
|
|
|
||
|
|
- "Microsoft Corporation KEK CA 2011" as second Key Exchange Key
|
||
|
|
(SHA1: 31:59:0b:fd:89:c9:d7:4e:d0:87:df:ac:66:33:4b:39:31:25:4b:30).
|
||
|
|
|
||
|
|
- "Microsoft Windows Production PCA 2011" as first DB entry
|
||
|
|
(SHA1: 58:0a:6f:4c:c4:e4:b6:69:b9:eb:dc:1b:2b:3e:08:7b:80:d0:67:8d).
|
||
|
|
|
||
|
|
- "Microsoft Corporation UEFI CA 2011" as second DB entry
|
||
|
|
(SHA1: 46:de:f6:3b:5c:e6:1c:f8:ba:0d:e2:e6:63:9c:10:19:d0:ed:14:f3).
|
||
|
|
|
||
|
|
These keys suffice to boot released versions of popular Linux
|
||
|
|
distributions (through the shim.efi utility), and Windows 8 and Windows
|
||
|
|
Server 2012 R2, in Secure Boot mode.
|
||
|
|
|
||
|
|
Supported guest operating systems
|
||
|
|
---------------------------------
|
||
|
|
|
||
|
|
Upstream OVMF does not favor some guest operating systems over others for
|
||
|
|
political or ideological reasons. However, some operating systems are harder to
|
||
|
|
obtain and/or technically more difficult to support. The general expectation is
|
||
|
|
that recent UEFI OSes should just work. Please consult the "OvmfPkg/README"
|
||
|
|
file.
|
||
|
|
|
||
|
|
The following guest OSes were tested with OVMF:
|
||
|
|
- Red Hat Enterprise Linux 6
|
||
|
|
- Red Hat Enterprise Linux 7
|
||
|
|
- Fedora 18
|
||
|
|
- Fedora 19
|
||
|
|
- Fedora 20
|
||
|
|
- Windows Server 2008 R2 SP1
|
||
|
|
- Windows Server 2012
|
||
|
|
- Windows 8
|
||
|
|
|
||
|
|
Notes about Windows Server 2008 R2 (paraphrasing the "OvmfPkg/README" file):
|
||
|
|
|
||
|
|
- QEMU should be started with one of the "-device qxl-vga" and "-device VGA"
|
||
|
|
options.
|
||
|
|
|
||
|
|
- Only one video mode, 1024x768x32, is supported at OS runtime.
|
||
|
|
|
||
|
|
Please refer to the section about QemuVideoDxe (OVMF's built-in video driver)
|
||
|
|
for more details on this limitation.
|
||
|
|
|
||
|
|
- The qxl-vga video card is recommended ("-device qxl-vga"). After booting the
|
||
|
|
installed guest OS, select the video card in Device Manager, and upgrade the
|
||
|
|
video driver to the QXL XDDM one.
|
||
|
|
|
||
|
|
The QXL XDDM driver can be downloaded from
|
||
|
|
<http://www.spice-space.org/download.html>, under Guest | Windows binaries.
|
||
|
|
|
||
|
|
This driver enables additional graphics resolutions at OS runtime, and
|
||
|
|
provides S3 (suspend/resume) capability.
|
||
|
|
|
||
|
|
Notes about Windows Server 2012 and Windows 8:
|
||
|
|
|
||
|
|
- QEMU should be started with the "-device qxl-vga,revision=4" option (or a
|
||
|
|
later revision, if available).
|
||
|
|
|
||
|
|
- The guest OS's builtin video driver inherits the video mode / frame buffer
|
||
|
|
from OVMF. There's no way to change the resolution at OS runtime.
|
||
|
|
|
||
|
|
For this reason, a platform driver has been developed for OVMF, which allows
|
||
|
|
users to change the preferred video mode in the firmware. Please refer to the
|
||
|
|
section about PlatformDxe for details.
|
||
|
|
|
||
|
|
- It is recommended to upgrade the guest OS's video driver to the QXL WDDM one,
|
||
|
|
via Device Manager.
|
||
|
|
|
||
|
|
Binaries for the QXL WDDM driver can be found at
|
||
|
|
<http://people.redhat.com/~vrozenfe/qxlwddm> (pick a version greater than or
|
||
|
|
equal to 0.6), while the source code resides at
|
||
|
|
<https://github.com/vrozenfe/qxl-dod>.
|
||
|
|
|
||
|
|
This driver enables additional graphics resolutions at OS runtime, and
|
||
|
|
provides S3 (suspend/resume) capability.
|
||
|
|
|
||
|
|
Compatibility Support Module (CSM)
|
||
|
|
----------------------------------
|
||
|
|
|
||
|
|
Collaboration between SeaBIOS and OVMF developers has enabled SeaBIOS to be
|
||
|
|
built as a Compatibility Support Module, and OVMF to embed and use it.
|
||
|
|
|
||
|
|
Benefits of a SeaBIOS CSM include:
|
||
|
|
|
||
|
|
- The ability to boot legacy (non-UEFI) operating systems, such as legacy Linux
|
||
|
|
systems, Windows 7, OpenBSD 5.2, FreeBSD 8/9, NetBSD, DragonflyBSD, Solaris
|
||
|
|
10/11.
|
||
|
|
|
||
|
|
- Legacy (non-UEFI-compliant) PCI expansion ROMs, such as a VGA BIOS, mapped by
|
||
|
|
QEMU in emulated devices' ROM BARs, are loaded and executed by OVMF.
|
||
|
|
|
||
|
|
For example, this grants the Windows Server 2008 R2 SP1 guest's native,
|
||
|
|
legacy video driver access to all modes of all QEMU video cards.
|
||
|
|
|
||
|
|
Building the CSM target of the SeaBIOS source tree is out of scope for this
|
||
|
|
report. Additionally, upstream OVMF does not enable the CSM by default.
|
||
|
|
|
||
|
|
Interested users and developers should look for OVMF's "-D CSM_ENABLE"
|
||
|
|
build-time option, and check out the <https://www.kraxel.org/repos/> continuous
|
||
|
|
integration repository, which provides CSM-enabled OVMF builds.
|
||
|
|
|
||
|
|
[RHEL] The "OVMF_CODE.fd" firmware image made available on the Red Hat
|
||
|
|
Enterprise Linux 7.1 host does not include a Compatibility Support
|
||
|
|
Module, for the following reasons:
|
||
|
|
|
||
|
|
- Virtual machines running officially supported, legacy guest operating
|
||
|
|
systems should just use the standalone SeaBIOS firmware. Firmware
|
||
|
|
selection is flexible in virtualization, see eg. "Installation of OVMF
|
||
|
|
guests with virt-manager and virt-install" above.
|
||
|
|
|
||
|
|
- The 16-bit thunking interface between OVMF and SeaBIOS is very complex
|
||
|
|
and presents a large debugging and support burden, based on past
|
||
|
|
experience.
|
||
|
|
|
||
|
|
- Secure Boot is incompatible with CSM.
|
||
|
|
|
||
|
|
- Inter-project dependencies should be minimized whenever possible.
|
||
|
|
|
||
|
|
- Using the default QXL video card, the Windows 2008 R2 SP1 guest can be
|
||
|
|
installed with its built-in, legacy video driver. Said driver will
|
||
|
|
select the only available video mode, 1024x768x32. After installation,
|
||
|
|
the video driver can be upgraded to the full-featured QXL XDDM driver.
|
||
|
|
|
||
|
|
Phases of the boot process
|
||
|
|
--------------------------
|
||
|
|
|
||
|
|
The PI and UEFI specifications, and Intel's UEFI and EDK II Learning and
|
||
|
|
Development materials provide ample information on PI and UEFI concepts. The
|
||
|
|
following is an absolutely minimal, rough glossary that is included only to
|
||
|
|
help readers new to PI and UEFI understand references in later, OVMF-specific
|
||
|
|
sections. We defer heavily to the official specifications and the training
|
||
|
|
materials, and frequently quote them below.
|
||
|
|
|
||
|
|
A central concept to mention early is the GUID -- globally unique identifier. A
|
||
|
|
GUID is a 128-bit number, written as XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX,
|
||
|
|
where each X stands for a hexadecimal nibble. GUIDs are used to name everything
|
||
|
|
in PI and in UEFI. Programmers introduce new GUIDs with the "uuidgen" utility,
|
||
|
|
and standards bodies standardize well-known services by positing their GUIDs.
|
||
|
|
|
||
|
|
The boot process is roughly divided in the following phases:
|
||
|
|
|
||
|
|
- Reset vector code.
|
||
|
|
|
||
|
|
- SEC: Security phase. This phase is the root of firmware integrity.
|
||
|
|
|
||
|
|
- PEI: Pre-EFI Initialization. This phase performs "minimal processor, chipset
|
||
|
|
and platform configuration for the purpose of discovering memory". Modules in
|
||
|
|
PEI collectively save their findings about the platform in a list of HOBs
|
||
|
|
(hand-off blocks).
|
||
|
|
|
||
|
|
When developing PEI code, the Platform Initialization (PI) specification
|
||
|
|
should be consulted.
|
||
|
|
|
||
|
|
- DXE: Driver eXecution Environment, pronounced as "Dixie". This "is the phase
|
||
|
|
where the bulk of the booting occurs: devices are enumerated and initialized,
|
||
|
|
UEFI services are supported, and protocols and drivers are implemented. Also,
|
||
|
|
the tables that create the UEFI interface are produced".
|
||
|
|
|
||
|
|
On the PEI/DXE boundary, the HOBs produced by PEI are consumed. For example,
|
||
|
|
this is how the memory space map is configured initially.
|
||
|
|
|
||
|
|
- BDS: Boot Device Selection. It is "responsible for determining how and where
|
||
|
|
you want to boot the operating system".
|
||
|
|
|
||
|
|
When developing DXE and BDS code, it is mainly the UEFI specification that
|
||
|
|
should be consulted. When speaking about DXE, BDS is frequently considered to
|
||
|
|
be a part of it.
|
||
|
|
|
||
|
|
The following concepts are tied to specific boot process phases:
|
||
|
|
|
||
|
|
- PEIM: a PEI Module (pronounced "PIM"). A binary module running in the PEI
|
||
|
|
phase, consuming some PPIs and producing other PPIs, and producing HOBs.
|
||
|
|
|
||
|
|
- PPI: PEIM-to-PEIM interface. A structure of function pointers and related
|
||
|
|
data members that establishes a PEI service, or an instance of a PEI service.
|
||
|
|
PPIs are identified by GUID.
|
||
|
|
|
||
|
|
An example is EFI_PEI_S3_RESUME2_PPI (6D582DBC-DB85-4514-8FCC-5ADF6227B147).
|
||
|
|
|
||
|
|
- DXE driver: a binary module running in the DXE and BDS phases, consuming some
|
||
|
|
protocols and producing other protocols.
|
||
|
|
|
||
|
|
- Protocol: A structure of function pointers and related data members that
|
||
|
|
establishes a DXE service, or an instance of a DXE service. Protocols are
|
||
|
|
identified by GUID.
|
||
|
|
|
||
|
|
An example is EFI_BLOCK_IO_PROTOCOL (964E5B21-6459-11D2-8E39-00A0C969723B).
|
||
|
|
|
||
|
|
- Architectural protocols: a set of standard protocols that are foundational to
|
||
|
|
the working of a UEFI system. Each architectural protocol has at most one
|
||
|
|
instance. Architectural protocols are implemented by a subset of DXE drivers.
|
||
|
|
DXE drivers explicitly list the set of protocols (including architectural
|
||
|
|
protocols) that they need to work. UEFI drivers can only be loaded once all
|
||
|
|
architectural protocols have become available during the DXE phase.
|
||
|
|
|
||
|
|
An example is EFI_VARIABLE_WRITE_ARCH_PROTOCOL
|
||
|
|
(6441F818-6362-4E44-B570-7DBA31DD2453).
|
||
|
|
|
||
|
|
Project structure
|
||
|
|
-----------------
|
||
|
|
|
||
|
|
The term "OVMF" usually denotes the project (community and development effort)
|
||
|
|
that provide and maintain the subject matter UEFI firmware for virtual
|
||
|
|
machines. However the term is also frequently applied to the firmware binary
|
||
|
|
proper that a virtual machine executes.
|
||
|
|
|
||
|
|
OVMF emerges as a compilation of several modules from the edk2 source
|
||
|
|
repository. "edk2" stands for EFI Development Kit II; it is a "modern,
|
||
|
|
feature-rich, cross-platform firmware development environment for the UEFI and
|
||
|
|
PI specifications".
|
||
|
|
|
||
|
|
The composition of OVMF is dictated by the following build control files:
|
||
|
|
|
||
|
|
OvmfPkg/OvmfPkgIa32.dsc
|
||
|
|
OvmfPkg/OvmfPkgIa32.fdf
|
||
|
|
|
||
|
|
OvmfPkg/OvmfPkgIa32X64.dsc
|
||
|
|
OvmfPkg/OvmfPkgIa32X64.fdf
|
||
|
|
|
||
|
|
OvmfPkg/OvmfPkgX64.dsc
|
||
|
|
OvmfPkg/OvmfPkgX64.fdf
|
||
|
|
|
||
|
|
The format of these files is described in the edk2 DSC and FDF specifications.
|
||
|
|
Roughly, the DSC file determines:
|
||
|
|
- library instance resolutions for library class requirements presented by the
|
||
|
|
modules to be compiled,
|
||
|
|
- the set of modules to compile.
|
||
|
|
|
||
|
|
The FDF file roughly determines:
|
||
|
|
- what binary modules (compilation output files, precompiled binaries, graphics
|
||
|
|
image files, verbatim binary sections) to include in the firmware image,
|
||
|
|
- how to lay out the firmware image.
|
||
|
|
|
||
|
|
The Ia32 flavor of these files builds a firmware where both PEI and DXE phases
|
||
|
|
are 32-bit. The Ia32X64 flavor builds a firmware where the PEI phase consists
|
||
|
|
of 32-bit modules, and the DXE phase is 64-bit. The X64 flavor builds a purely
|
||
|
|
64-bit firmware.
|
||
|
|
|
||
|
|
The word size of the DXE phase must match the word size of the runtime OS -- a
|
||
|
|
32-bit DXE can't cooperate with a 64-bit OS, and a 64-bit DXE can't work a
|
||
|
|
32-bit OS.
|
||
|
|
|
||
|
|
OVMF pulls together modules from across the edk2 tree. For example:
|
||
|
|
|
||
|
|
- common drivers and libraries that are platform independent are usually
|
||
|
|
located under MdeModulePkg and MdePkg,
|
||
|
|
|
||
|
|
- common but hardware-specific drivers and libraries that match QEMU's
|
||
|
|
pc-i440fx-* machine type are pulled in from IntelFrameworkModulePkg,
|
||
|
|
PcAtChipsetPkg and UefiCpuPkg,
|
||
|
|
|
||
|
|
- the platform independent UEFI Shell is built from ShellPkg,
|
||
|
|
|
||
|
|
- OvmfPkg includes drivers and libraries that are useful for virtual machines
|
||
|
|
and may or may not be specific to QEMU's pc-i440fx-* machine type.
|
||
|
|
|
||
|
|
Platform Configuration Database (PCD)
|
||
|
|
-------------------------------------
|
||
|
|
|
||
|
|
Like the "Phases of the boot process" section, this one introduces a concept in
|
||
|
|
very raw form. We defer to the PCD related edk2 specifications, and we won't
|
||
|
|
discuss implementation details here. Our purpose is only to offer the reader a
|
||
|
|
usable (albeit possibly inaccurate) definition, so that we can refer to PCDs
|
||
|
|
later on.
|
||
|
|
|
||
|
|
Colloquially, when we say "PCD", we actually mean "PCD entry"; that is, an
|
||
|
|
entry stored in the Platform Configuration Database.
|
||
|
|
|
||
|
|
The Platform Configuration Database is
|
||
|
|
- a firmware-wide
|
||
|
|
- name-value store
|
||
|
|
- of scalars and buffers
|
||
|
|
- where each entry may be
|
||
|
|
- build-time constant, or
|
||
|
|
- run-time dynamic, or
|
||
|
|
- theoretically, a middle option: patchable in the firmware file itself,
|
||
|
|
using a dedicated tool. (OVMF does not utilize externally patchable
|
||
|
|
entries.)
|
||
|
|
|
||
|
|
A PCD entry is declared in the DEC file of the edk2 top-level Package directory
|
||
|
|
whose modules (drivers and libraries) are the primary consumers of the PCD
|
||
|
|
entry. (See for example OvmfPkg/OvmfPkg.dec). Basically, a PCD in a DEC file
|
||
|
|
exposes a simple customization point.
|
||
|
|
|
||
|
|
Interest in a PCD entry is communicated to the build system by naming the PCD
|
||
|
|
entry in the INF file of the interested module (application, driver or
|
||
|
|
library). The module may read and -- dependent on the PCD entry's category --
|
||
|
|
write the PCD entry.
|
||
|
|
|
||
|
|
Let's investigate the characteristics of the Database and the PCD entries.
|
||
|
|
|
||
|
|
- Firmware-wide: technically, all modules may access all entries they are
|
||
|
|
interested in, assuming they advertise their interest in their INF files.
|
||
|
|
With careful design, PCDs enable inter-driver propagation of (simple) system
|
||
|
|
configuration. PCDs are available in both PEI and DXE.
|
||
|
|
|
||
|
|
(UEFI drivers meant to be portable (ie. from third party vendors) are not
|
||
|
|
supposed to use PCDs, since PCDs qualify internal to the specific edk2
|
||
|
|
firmware in question.)
|
||
|
|
|
||
|
|
- Name-value store of scalars and buffers: each PCD has a symbolic name, and a
|
||
|
|
fixed scalar type (UINT16, UINT32 etc), or VOID* for buffers. Each PCD entry
|
||
|
|
belongs to a namespace, where a namespace is (obviously) a GUID, defined in
|
||
|
|
the DEC file.
|
||
|
|
|
||
|
|
- A DEC file can permit several categories for a PCD:
|
||
|
|
- build-time constant ("FixedAtBuild"),
|
||
|
|
- patchable in the firmware image ("PatchableInModule", unused in OVMF),
|
||
|
|
- runtime modifiable ("Dynamic").
|
||
|
|
|
||
|
|
The platform description file (DSC) of a top-level Package directory may choose
|
||
|
|
the exact category for a given PCD entry that its modules wish to use, and
|
||
|
|
assign a default (or constant) initial value to it.
|
||
|
|
|
||
|
|
In addition, the edk2 build system too can initialize PCD entries to values
|
||
|
|
that it calculates while laying out the flash device image. Such PCD
|
||
|
|
assignments are described in the FDF control file.
|
||
|
|
|
||
|
|
Firmware image structure
|
||
|
|
------------------------
|
||
|
|
|
||
|
|
(We assume the common X64 choice for both PEI and DXE, and the default DEBUG
|
||
|
|
build target.)
|
||
|
|
|
||
|
|
The OvmfPkg/OvmfPkgX64.fdf file defines the following layout for the flash
|
||
|
|
device image "OVMF.fd":
|
||
|
|
|
||
|
|
Description Compression type Size
|
||
|
|
------------------------------ ---------------------- -------
|
||
|
|
Non-volatile data storage open-coded binary data 128 KB
|
||
|
|
Variable store 56 KB
|
||
|
|
Event log 4 KB
|
||
|
|
Working block 4 KB
|
||
|
|
Spare area 64 KB
|
||
|
|
|
||
|
|
FVMAIN_COMPACT uncompressed 1712 KB
|
||
|
|
FV Firmware File System file LZMA compressed
|
||
|
|
PEIFV uncompressed 896 KB
|
||
|
|
individual PEI modules uncompressed
|
||
|
|
DXEFV uncompressed 8192 KB
|
||
|
|
individual DXE modules uncompressed
|
||
|
|
|
||
|
|
SECFV uncompressed 208 KB
|
||
|
|
SEC driver
|
||
|
|
reset vector code
|
||
|
|
|
||
|
|
The top-level image consists of three regions (three firmware volumes):
|
||
|
|
- non-volatile data store (128 KB),
|
||
|
|
- main firmware volume (FVMAIN_COMPACT, 1712 KB),
|
||
|
|
- firmware volume containing the reset vector code and the SEC phase code (208
|
||
|
|
KB).
|
||
|
|
|
||
|
|
In total, the OVMF.fd file has size 128 KB + 1712 KB + 208 KB == 2 MB.
|
||
|
|
|
||
|
|
(1) The firmware volume with non-volatile data store (128 KB) has the following
|
||
|
|
internal structure, in blocks of 4 KB:
|
||
|
|
|
||
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ L: event log
|
||
|
|
LIVE | varstore |L|W| W: working block
|
||
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||
|
|
|
||
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||
|
|
SPARE | |
|
||
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||
|
|
|
||
|
|
The first half of this firmware volume is "live", while the second half is
|
||
|
|
"spare". The spare half is important when the variable driver reclaims
|
||
|
|
unused storage and reorganizes the variable store.
|
||
|
|
|
||
|
|
The live half dedicates 14 blocks (56 KB) to the variable store itself. On
|
||
|
|
top of those, one block is set aside for an event log, and one block is
|
||
|
|
used as the working block of the fault tolerant write protocol. Fault
|
||
|
|
tolerant writes are used to recover from an occasional (virtual) power loss
|
||
|
|
during variable updates.
|
||
|
|
|
||
|
|
The blocks in this firmware volume are accessed, in stacking order from
|
||
|
|
least abstract to most abstract, by:
|
||
|
|
|
||
|
|
- EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL (provided by
|
||
|
|
OvmfPkg/QemuFlashFvbServicesRuntimeDxe),
|
||
|
|
|
||
|
|
- EFI_FAULT_TOLERANT_WRITE_PROTOCOL (provided by
|
||
|
|
MdeModulePkg/Universal/FaultTolerantWriteDxe),
|
||
|
|
|
||
|
|
- architectural protocols instrumental to the runtime UEFI variable
|
||
|
|
services:
|
||
|
|
- EFI_VARIABLE_ARCH_PROTOCOL,
|
||
|
|
- EFI_VARIABLE_WRITE_ARCH_PROTOCOL.
|
||
|
|
|
||
|
|
In a non-secure boot build, the DXE driver providing these architectural
|
||
|
|
protocols is MdeModulePkg/Universal/Variable/RuntimeDxe. In a secure boot
|
||
|
|
build, where authenticated variables are available, the DXE driver
|
||
|
|
offering these protocols is SecurityPkg/VariableAuthenticated/RuntimeDxe.
|
||
|
|
|
||
|
|
(2) The main firmware volume (FVMAIN_COMPACT, 1712 KB) embeds further firmware
|
||
|
|
volumes. The outermost layer is a Firmware File System (FFS), carrying a
|
||
|
|
single file. This file holds an LZMA-compressed section, which embeds two
|
||
|
|
firmware volumes: PEIFV (896 KB) with PEIMs, and DXEFV (8192 KB) with DXE
|
||
|
|
and UEFI drivers.
|
||
|
|
|
||
|
|
This scheme enables us to build 896 KB worth of PEI drivers and 8192 KB
|
||
|
|
worth of DXE and UEFI drivers, compress them all with LZMA in one go, and
|
||
|
|
store the compressed result in 1712 KB, saving room in the flash device.
|
||
|
|
|
||
|
|
(3) The SECFV firmware volume (208 KB) is not compressed. It carries the
|
||
|
|
"volume top file" with the reset vector code, to end at 4 GB in
|
||
|
|
guest-physical address space, and the SEC phase driver (OvmfPkg/Sec).
|
||
|
|
|
||
|
|
The last 16 bytes of the volume top file (mapped directly under 4 GB)
|
||
|
|
contain a NOP slide and a jump instruction. This is where QEMU starts
|
||
|
|
executing the firmware, at address 0xFFFF_FFF0. The reset vector and the
|
||
|
|
SEC driver run from flash directly.
|
||
|
|
|
||
|
|
The SEC driver locates FVMAIN_COMPACT in the flash, and decompresses the
|
||
|
|
main firmware image to RAM. The rest of OVMF (PEI, DXE, BDS phases) run
|
||
|
|
from RAM.
|
||
|
|
|
||
|
|
As already mentioned, the OVMF.fd file is mapped by qemu's
|
||
|
|
"hw/block/pflash_cfi01.c" device just under 4 GB in guest-physical address
|
||
|
|
space, according to the command line option
|
||
|
|
|
||
|
|
-drive if=pflash,format=raw,file=fedora.flash
|
||
|
|
|
||
|
|
(refer to the Example qemu invocation). This is a "ROMD device", which can
|
||
|
|
switch out of "ROMD mode" and back into it.
|
||
|
|
|
||
|
|
Namely, in the default ROMD mode, the guest-physical address range backed by
|
||
|
|
the flash device reads and executes as ROM (it does not trap from KVM to QEMU).
|
||
|
|
The first write access in this mode traps to QEMU, and flips the device out of
|
||
|
|
ROMD mode.
|
||
|
|
|
||
|
|
In non-ROMD mode, the flash chip is programmed by storing CFI (Common Flash
|
||
|
|
Interface) command values at the flash-covered addresses; both reads and writes
|
||
|
|
trap to QEMU, and the flash contents are modified and synchronized to the
|
||
|
|
host-side file. A special CFI command flips the flash device back to ROMD mode.
|
||
|
|
|
||
|
|
Qemu implements the above based on the KVM_CAP_READONLY_MEM / KVM_MEM_READONLY
|
||
|
|
KVM features, and OVMF puts it to use in its EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
|
||
|
|
implementation, under "OvmfPkg/QemuFlashFvbServicesRuntimeDxe".
|
||
|
|
|
||
|
|
IMPORTANT: Never pass OVMF.fd to qemu with the -bios option. That option maps
|
||
|
|
the firmware image as ROM into the guest's address space, and forces OVMF to
|
||
|
|
emulate non-volatile variables with a fallback driver that is bound to have
|
||
|
|
insufficient and confusing semantics.
|
||
|
|
|
||
|
|
The 128 KB firmware volume with the variable store, discussed under (1), is
|
||
|
|
also built as a separate host-side file, named "OVMF_VARS.fd". The "rest" is
|
||
|
|
built into a third file, "OVMF_CODE.fd", which is only 1920 KB in size. The
|
||
|
|
variable store is mapped into its usual location, at 4 GB - 2 MB = 0xFFE0_0000,
|
||
|
|
through the following qemu options:
|
||
|
|
|
||
|
|
-drive if=pflash,format=raw,readonly,file=OVMF_CODE.fd \
|
||
|
|
-drive if=pflash,format=raw,file=fedora.varstore.fd
|
||
|
|
|
||
|
|
This way qemu configures two flash chips consecutively, with start addresses
|
||
|
|
growing downwards, which is transparent to OVMF.
|
||
|
|
|
||
|
|
[RHEL] Red Hat Enterprise Linux 7.1 ships a Secure Boot-enabled, X64, DEBUG
|
||
|
|
firmware only. Furthermore, only the split files ("OVMF_VARS.fd" and
|
||
|
|
"OVMF_CODE.fd") are available.
|
||
|
|
|
||
|
|
S3 (suspend to RAM and resume)
|
||
|
|
------------------------------
|
||
|
|
|
||
|
|
As noted in Example qemu invocation, the
|
||
|
|
|
||
|
|
-global PIIX4_PM.disable_s3=0
|
||
|
|
|
||
|
|
command line option tells qemu and OVMF if the user would like to enable S3
|
||
|
|
support. (This is corresponds to the /domain/pm/suspend-to-mem/@enabled libvirt
|
||
|
|
domain XML attribute.)
|
||
|
|
|
||
|
|
Implementing / orchestrating S3 was a considerable community effort in OVMF. A
|
||
|
|
detailed description exceeds the scope of this report; we only make a few
|
||
|
|
statements.
|
||
|
|
|
||
|
|
(1) S3-related PPIs and protocols are well documented in the PI specification.
|
||
|
|
|
||
|
|
(2) Edk2 contains most modules that are needed to implement S3 on a given
|
||
|
|
platform. One abstraction that is central to the porting / extending of the
|
||
|
|
S3-related modules to a new platform is the LockBox library interface,
|
||
|
|
which a specific platform can fill in by implementing its own LockBox
|
||
|
|
library instance.
|
||
|
|
|
||
|
|
The LockBox library provides a privileged name-value store (to be addressed
|
||
|
|
by GUIDs). The privilege separation stretches between the firmware and the
|
||
|
|
operating system. That is, the S3-related machinery of the firmware saves
|
||
|
|
some items in the LockBox securely, under well-known GUIDs, before booting
|
||
|
|
the operating system. During resume (which is a form of warm reset), the
|
||
|
|
firmware is activated again, and retrieves items from the LockBox. Before
|
||
|
|
jumping to the OS's resume vector, the LockBox is secured again.
|
||
|
|
|
||
|
|
We'll return to this later when we separately discuss SMRAM and SMM.
|
||
|
|
|
||
|
|
(3) During resume, the DXE and later phases are never reached; only the reset
|
||
|
|
vector, and the SEC and PEI phases of the firmware run. The platform is
|
||
|
|
supposed to detect a resume in progress during PEI, and to store that fact
|
||
|
|
in the BootMode field of the Phase Handoff Information Table (PHIT) HOB.
|
||
|
|
OVMF keys this off the CMOS, see OvmfPkg/PlatformPei.
|
||
|
|
|
||
|
|
At the end of PEI, the DXE IPL PEIM (Initial Program Load PEI Module, see
|
||
|
|
MdeModulePkg/Core/DxeIplPeim) examines the Boot Mode, and if it says "S3
|
||
|
|
resume in progress", then the IPL branches to the PEIM that exports
|
||
|
|
EFI_PEI_S3_RESUME2_PPI (provided by UefiCpuPkg/Universal/Acpi/S3Resume2Pei)
|
||
|
|
rather than loading the DXE core.
|
||
|
|
|
||
|
|
S3Resume2Pei executes the technical steps of the resumption, relying on the
|
||
|
|
contents of the LockBox.
|
||
|
|
|
||
|
|
(4) During first boot (or after a normal platform reset), when DXE does run,
|
||
|
|
hardware drivers in the DXE phase are encouraged to "stash" their hardware
|
||
|
|
configuration steps (eg. accesses to PCI config space, I/O ports, memory
|
||
|
|
mapped addresses, and so on) in a centrally maintained, so called "S3 boot
|
||
|
|
script". Hardware accesses are represented with opcodes of a special binary
|
||
|
|
script language.
|
||
|
|
|
||
|
|
This boot script is to be replayed during resume, by S3Resume2Pei. The
|
||
|
|
general goal is to bring back hardware devices -- which have been powered
|
||
|
|
off during suspend -- to their original after-first-boot state, and in
|
||
|
|
particular, to do so quickly.
|
||
|
|
|
||
|
|
At the moment, OVMF saves only one opcode in the S3 resume boot script: an
|
||
|
|
INFORMATION opcode, with contents 0xDEADBEEF (in network byte order). The
|
||
|
|
consensus between Linux developers seems to be that boot firmware is only
|
||
|
|
responsible for restoring basic chipset state, which OVMF does during PEI
|
||
|
|
anyway, independently of S3 vs. normal reset. (One example is the power
|
||
|
|
management registers of the i440fx chipset.) Device and peripheral state is
|
||
|
|
the responsibility of the runtime operating system.
|
||
|
|
|
||
|
|
Although an experimental OVMF S3 boot script was at one point captured for
|
||
|
|
the virtual Cirrus VGA card, such a boot script cannot follow eg. video
|
||
|
|
mode changes effected by the OS. Hence the operating system can never avoid
|
||
|
|
restoring device state, and most Linux display drivers (eg. stdvga, QXL)
|
||
|
|
already cover S3 resume fully.
|
||
|
|
|
||
|
|
The XDDM and WDDM driver models used under Windows OSes seem to recognize
|
||
|
|
this notion of runtime OS responsibility as well. (See the list of OSes
|
||
|
|
supported by OVMF in a separate section.)
|
||
|
|
|
||
|
|
(5) The S3 suspend/resume data flow in OVMF is included here tersely, for
|
||
|
|
interested developers.
|
||
|
|
|
||
|
|
(a) BdsLibBootViaBootOption()
|
||
|
|
EFI_ACPI_S3_SAVE_PROTOCOL [AcpiS3SaveDxe]
|
||
|
|
- saves ACPI S3 Context to LockBox ---------------------+
|
||
|
|
(including FACS address -- FACS ACPI table |
|
||
|
|
contains OS waking vector) |
|
||
|
|
|
|
||
|
|
- prepares boot script: |
|
||
|
|
EFI_S3_SAVE_STATE_PROTOCOL.Write() [S3SaveStateDxe] |
|
||
|
|
S3BootScriptLib [PiDxeS3BootScriptLib] |
|
||
|
|
- opcodes & arguments are saved in NVS. --+ |
|
||
|
|
| |
|
||
|
|
- issues a notification by installing | |
|
||
|
|
EFI_DXE_SMM_READY_TO_LOCK_PROTOCOL | |
|
||
|
|
| |
|
||
|
|
(b) EFI_S3_SAVE_STATE_PROTOCOL [S3SaveStateDxe] | |
|
||
|
|
S3BootScriptLib [PiDxeS3BootScriptLib] | |
|
||
|
|
- closes script with special opcode <---------+ |
|
||
|
|
- script is available in non-volatile memory |
|
||
|
|
via PcdS3BootScriptTablePrivateDataPtr --+ |
|
||
|
|
| |
|
||
|
|
BootScriptExecutorDxe | |
|
||
|
|
S3BootScriptLib [PiDxeS3BootScriptLib] | |
|
||
|
|
- Knows about boot script location by <----+ |
|
||
|
|
synchronizing with the other library |
|
||
|
|
instance via |
|
||
|
|
PcdS3BootScriptTablePrivateDataPtr. |
|
||
|
|
- Copies relocated image of itself to |
|
||
|
|
reserved memory. --------------------------------+ |
|
||
|
|
- Saved image contains pointer to boot script. ---|--+ |
|
||
|
|
| | |
|
||
|
|
Runtime: | | |
|
||
|
|
| | |
|
||
|
|
(c) OS is booted, writes OS waking vector to FACS, | | |
|
||
|
|
suspends machine | | |
|
||
|
|
| | |
|
||
|
|
S3 Resume (PEI): | | |
|
||
|
|
| | |
|
||
|
|
(d) PlatformPei sets S3 Boot Mode based on CMOS | | |
|
||
|
|
| | |
|
||
|
|
(e) DXE core is skipped and EFI_PEI_S3_RESUME2 is | | |
|
||
|
|
called as last step of PEI | | |
|
||
|
|
| | |
|
||
|
|
(f) S3Resume2Pei retrieves from LockBox: | | |
|
||
|
|
- ACPI S3 Context (path to FACS) <------------------|--|--+
|
||
|
|
| | |
|
||
|
|
+------------------|--|--+
|
||
|
|
- Boot Script Executor Image <----------------------+ | |
|
||
|
|
| |
|
||
|
|
(g) BootScriptExecutorDxe | |
|
||
|
|
S3BootScriptLib [PiDxeS3BootScriptLib] | |
|
||
|
|
- executes boot script <-----------------------------+ |
|
||
|
|
|
|
||
|
|
(h) OS waking vector available from ACPI S3 Context / FACS <--+
|
||
|
|
is called
|
||
|
|
|
||
|
|
A comprehensive memory map of OVMF
|
||
|
|
----------------------------------
|
||
|
|
|
||
|
|
The following section gives a detailed analysis of memory ranges below 4 GB
|
||
|
|
that OVMF statically uses.
|
||
|
|
|
||
|
|
In the rightmost column, the PCD entry is identified by which the source refers
|
||
|
|
to the address or size in question.
|
||
|
|
|
||
|
|
The flash-covered range has been discussed previously in "Firmware image
|
||
|
|
structure", therefore we include it only for completeness. Due to the fact that
|
||
|
|
this range is always backed by a memory mapped device (and never RAM), it is
|
||
|
|
unaffected by S3 (suspend to RAM and resume).
|
||
|
|
|
||
|
|
+--------------------------+ 4194304 KB
|
||
|
|
| |
|
||
|
|
| SECFV | size: 208 KB
|
||
|
|
| |
|
||
|
|
+--------------------------+ 4194096 KB
|
||
|
|
| |
|
||
|
|
| FVMAIN_COMPACT | size: 1712 KB
|
||
|
|
| |
|
||
|
|
+--------------------------+ 4192384 KB
|
||
|
|
| |
|
||
|
|
| variable store | size: 64 KB PcdFlashNvStorageFtwSpareSize
|
||
|
|
| spare area |
|
||
|
|
| |
|
||
|
|
+--------------------------+ 4192320 KB PcdOvmfFlashNvStorageFtwSpareBase
|
||
|
|
| |
|
||
|
|
| FTW working block | size: 4 KB PcdFlashNvStorageFtwWorkingSize
|
||
|
|
| |
|
||
|
|
+--------------------------+ 4192316 KB PcdOvmfFlashNvStorageFtwWorkingBase
|
||
|
|
| |
|
||
|
|
| Event log of | size: 4 KB PcdOvmfFlashNvStorageEventLogSize
|
||
|
|
| non-volatile storage |
|
||
|
|
| |
|
||
|
|
+--------------------------+ 4192312 KB PcdOvmfFlashNvStorageEventLogBase
|
||
|
|
| |
|
||
|
|
| variable store | size: 56 KB PcdFlashNvStorageVariableSize
|
||
|
|
| |
|
||
|
|
+--------------------------+ 4192256 KB PcdOvmfFlashNvStorageVariableBase
|
||
|
|
|
||
|
|
The flash-mapped image of OVMF.fd covers the entire structure above (2048 KB).
|
||
|
|
|
||
|
|
When using the split files, the address 4192384 KB
|
||
|
|
(PcdOvmfFlashNvStorageFtwSpareBase + PcdFlashNvStorageFtwSpareSize) is the
|
||
|
|
boundary between the mapped images of OVMF_VARS.fd (56 KB + 4 KB + 4 KB + 64 KB
|
||
|
|
= 128 KB) and OVMF_CODE.fd (1712 KB + 208 KB = 1920 KB).
|
||
|
|
|
||
|
|
With regard to RAM that is statically used by OVMF, S3 (suspend to RAM and
|
||
|
|
resume) complicates matters. Many ranges have been introduced only to support
|
||
|
|
S3, hence for all ranges below, the following questions will be audited:
|
||
|
|
|
||
|
|
(a) when and how a given range is initialized after first boot of the VM,
|
||
|
|
(b) how it is protected from memory allocations during DXE,
|
||
|
|
(c) how it is protected from the OS,
|
||
|
|
(d) how it is accessed on the S3 resume path,
|
||
|
|
(e) how it is accessed on the warm reset path.
|
||
|
|
|
||
|
|
Importantly, the term "protected" is meant as protection against inadvertent
|
||
|
|
reallocations and overwrites by co-operating DXE and OS modules. It does not
|
||
|
|
imply security against malicious code.
|
||
|
|
|
||
|
|
+--------------------------+ 17408 KB
|
||
|
|
| |
|
||
|
|
|DXEFV from FVMAIN_COMPACT | size: 8192 KB PcdOvmfDxeMemFvSize
|
||
|
|
| decompressed firmware |
|
||
|
|
| volume with DXE modules |
|
||
|
|
| |
|
||
|
|
+--------------------------+ 9216 KB PcdOvmfDxeMemFvBase
|
||
|
|
| |
|
||
|
|
|PEIFV from FVMAIN_COMPACT | size: 896 KB PcdOvmfPeiMemFvSize
|
||
|
|
| decompressed firmware |
|
||
|
|
| volume with PEI modules |
|
||
|
|
| |
|
||
|
|
+--------------------------+ 8320 KB PcdOvmfPeiMemFvBase
|
||
|
|
| |
|
||
|
|
| permanent PEI memory for | size: 32 KB PcdS3AcpiReservedMemorySize
|
||
|
|
| the S3 resume path |
|
||
|
|
| |
|
||
|
|
+--------------------------+ 8288 KB PcdS3AcpiReservedMemoryBase
|
||
|
|
| |
|
||
|
|
| temporary SEC/PEI heap | size: 32 KB PcdOvmfSecPeiTempRamSize
|
||
|
|
| and stack |
|
||
|
|
| |
|
||
|
|
+--------------------------+ 8256 KB PcdOvmfSecPeiTempRamBase
|
||
|
|
| |
|
||
|
|
| unused | size: 32 KB
|
||
|
|
| |
|
||
|
|
+--------------------------+ 8224 KB
|
||
|
|
| |
|
||
|
|
| SEC's table of | size: 4 KB PcdGuidedExtractHandlerTableSize
|
||
|
|
| GUIDed section handlers |
|
||
|
|
| |
|
||
|
|
+--------------------------+ 8220 KB PcdGuidedExtractHandlerTableAddress
|
||
|
|
| |
|
||
|
|
| LockBox storage | size: 4 KB PcdOvmfLockBoxStorageSize
|
||
|
|
| |
|
||
|
|
+--------------------------+ 8216 KB PcdOvmfLockBoxStorageBase
|
||
|
|
| |
|
||
|
|
| early page tables on X64 | size: 24 KB PcdOvmfSecPageTablesSize
|
||
|
|
| |
|
||
|
|
+--------------------------+ 8192 KB PcdOvmfSecPageTablesBase
|
||
|
|
|
||
|
|
(1) Early page tables on X64:
|
||
|
|
|
||
|
|
(a) when and how it is initialized after first boot of the VM
|
||
|
|
|
||
|
|
The range is filled in during the SEC phase
|
||
|
|
[OvmfPkg/ResetVector/Ia32/PageTables64.asm]. The CR3 register is verified
|
||
|
|
against the base address in SecCoreStartupWithStack()
|
||
|
|
[OvmfPkg/Sec/SecMain.c].
|
||
|
|
|
||
|
|
(b) how it is protected from memory allocations during DXE
|
||
|
|
|
||
|
|
If S3 was enabled on the QEMU command line (see "-global
|
||
|
|
PIIX4_PM.disable_s3=0" earlier), then InitializeRamRegions()
|
||
|
|
[OvmfPkg/PlatformPei/MemDetect.c] protects the range with an AcpiNVS memory
|
||
|
|
allocation HOB, in PEI.
|
||
|
|
|
||
|
|
If S3 was disabled, then this range is not protected. DXE's own page tables
|
||
|
|
are first built while still in PEI (see HandOffToDxeCore()
|
||
|
|
[MdeModulePkg/Core/DxeIplPeim/X64/DxeLoadFunc.c]). Those tables are located
|
||
|
|
in permanent PEI memory. After CR3 is switched over to them (which occurs
|
||
|
|
before jumping to the DXE core entry point), we don't have to preserve the
|
||
|
|
initial tables.
|
||
|
|
|
||
|
|
(c) how it is protected from the OS
|
||
|
|
|
||
|
|
If S3 is enabled, then (1b) reserves it from the OS too.
|
||
|
|
|
||
|
|
If S3 is disabled, then the range needs no protection.
|
||
|
|
|
||
|
|
(d) how it is accessed on the S3 resume path
|
||
|
|
|
||
|
|
It is rewritten same as in (1a), which is fine because (1c) reserved it.
|
||
|
|
|
||
|
|
(e) how it is accessed on the warm reset path
|
||
|
|
|
||
|
|
It is rewritten same as in (1a).
|
||
|
|
|
||
|
|
(2) LockBox storage:
|
||
|
|
|
||
|
|
(a) when and how it is initialized after first boot of the VM
|
||
|
|
|
||
|
|
InitializeRamRegions() [OvmfPkg/PlatformPei/MemDetect.c] zeroes out the
|
||
|
|
area during PEI. This is correct but not strictly necessary, since on first
|
||
|
|
boot the area is zero-filled anyway.
|
||
|
|
|
||
|
|
The LockBox signature of the area is filled in by the PEI module or DXE
|
||
|
|
driver that has been linked against OVMF's LockBoxLib and is run first. The
|
||
|
|
signature is written in LockBoxLibInitialize()
|
||
|
|
[OvmfPkg/Library/LockBoxLib/LockBoxLib.c].
|
||
|
|
|
||
|
|
Any module calling SaveLockBox() [OvmfPkg/Library/LockBoxLib/LockBoxLib.c]
|
||
|
|
will co-populate this area.
|
||
|
|
|
||
|
|
(b) how it is protected from memory allocations during DXE
|
||
|
|
|
||
|
|
If S3 is enabled, then InitializeRamRegions()
|
||
|
|
[OvmfPkg/PlatformPei/MemDetect.c] protects the range as AcpiNVS.
|
||
|
|
|
||
|
|
Otherwise, the range is covered with a BootServicesData memory allocation
|
||
|
|
HOB.
|
||
|
|
|
||
|
|
(c) how it is protected from the OS
|
||
|
|
|
||
|
|
If S3 is enabled, then (2b) protects it sufficiently.
|
||
|
|
|
||
|
|
Otherwise the range requires no runtime protection, and the
|
||
|
|
BootServicesData allocation type from (2b) ensures that the range will be
|
||
|
|
released to the OS.
|
||
|
|
|
||
|
|
(d) how it is accessed on the S3 resume path
|
||
|
|
|
||
|
|
The S3 Resume PEIM restores data from the LockBox, which has been correctly
|
||
|
|
protected in (2c).
|
||
|
|
|
||
|
|
(e) how it is accessed on the warm reset path
|
||
|
|
|
||
|
|
InitializeRamRegions() [OvmfPkg/PlatformPei/MemDetect.c] zeroes out the
|
||
|
|
range during PEI, effectively emptying the LockBox. Modules will
|
||
|
|
re-populate the LockBox as described in (2a).
|
||
|
|
|
||
|
|
(3) SEC's table of GUIDed section handlers
|
||
|
|
|
||
|
|
(a) when and how it is initialized after first boot of the VM
|
||
|
|
|
||
|
|
The following two library instances are linked into SecMain:
|
||
|
|
- IntelFrameworkModulePkg/Library/LzmaCustomDecompressLib,
|
||
|
|
- MdePkg/Library/BaseExtractGuidedSectionLib.
|
||
|
|
|
||
|
|
The first library registers its LZMA decompressor plugin (which is a called
|
||
|
|
a "section handler") by calling the second library:
|
||
|
|
|
||
|
|
LzmaDecompressLibConstructor() [GuidedSectionExtraction.c]
|
||
|
|
ExtractGuidedSectionRegisterHandlers() [BaseExtractGuidedSectionLib.c]
|
||
|
|
|
||
|
|
The second library maintains its table of registered "section handlers", to
|
||
|
|
be indexed by GUID, in this fixed memory area, independently of S3
|
||
|
|
enablement.
|
||
|
|
|
||
|
|
(The decompression of FVMAIN_COMPACT's FFS file section that contains the
|
||
|
|
PEIFV and DXEFV firmware volumes occurs with the LZMA decompressor
|
||
|
|
registered above. See (6) and (7) below.)
|
||
|
|
|
||
|
|
(b) how it is protected from memory allocations during DXE
|
||
|
|
|
||
|
|
There is no need to protect this area from DXE: because nothing else in
|
||
|
|
OVMF links against BaseExtractGuidedSectionLib, the area loses its
|
||
|
|
significance as soon as OVMF progresses from SEC to PEI, therefore DXE is
|
||
|
|
allowed to overwrite the region.
|
||
|
|
|
||
|
|
(c) how it is protected from the OS
|
||
|
|
|
||
|
|
When S3 is enabled, we cover the range with an AcpiNVS memory allocation
|
||
|
|
HOB in InitializeRamRegions().
|
||
|
|
|
||
|
|
When S3 is disabled, the range is not protected.
|
||
|
|
|
||
|
|
(d) how it is accessed on the S3 resume path
|
||
|
|
|
||
|
|
The table of registered section handlers is again managed by
|
||
|
|
BaseExtractGuidedSectionLib linked into SecMain exclusively. Section
|
||
|
|
handler registrations update the table in-place (based on GUID matches).
|
||
|
|
|
||
|
|
(e) how it is accessed on the warm reset path
|
||
|
|
|
||
|
|
If S3 is enabled, then the OS won't damage the table (due to (3c)), thus
|
||
|
|
see (3d).
|
||
|
|
|
||
|
|
If S3 is disabled, then the OS has most probably overwritten the range with
|
||
|
|
its own data, hence (3a) -- complete reinitialization -- will come into
|
||
|
|
effect, based on the table signature check in BaseExtractGuidedSectionLib.
|
||
|
|
|
||
|
|
(4) temporary SEC/PEI heap and stack
|
||
|
|
|
||
|
|
(a) when and how it is initialized after first boot of the VM
|
||
|
|
|
||
|
|
The range is configured in [OvmfPkg/Sec/X64/SecEntry.S] and
|
||
|
|
SecCoreStartupWithStack() [OvmfPkg/Sec/SecMain.c]. The stack half is read &
|
||
|
|
written by the CPU transparently. The heap half is used for memory
|
||
|
|
allocations during PEI.
|
||
|
|
|
||
|
|
Data is migrated out (to permanent PEI stack & memory) in (or soon after)
|
||
|
|
PublishPeiMemory() [OvmfPkg/PlatformPei/MemDetect.c].
|
||
|
|
|
||
|
|
(b) how it is protected from memory allocations during DXE
|
||
|
|
|
||
|
|
It is not necessary to protect this range during DXE because its use ends
|
||
|
|
still in PEI.
|
||
|
|
|
||
|
|
(c) how it is protected from the OS
|
||
|
|
|
||
|
|
If S3 is enabled, then InitializeRamRegions()
|
||
|
|
[OvmfPkg/PlatformPei/MemDetect.c] reserves it as AcpiNVS.
|
||
|
|
|
||
|
|
If S3 is disabled, then the range doesn't require protection.
|
||
|
|
|
||
|
|
(d) how it is accessed on the S3 resume path
|
||
|
|
|
||
|
|
Same as in (4a), except the target area of the migration triggered by
|
||
|
|
PublishPeiMemory() [OvmfPkg/PlatformPei/MemDetect.c] is different -- see
|
||
|
|
(5).
|
||
|
|
|
||
|
|
(e) how it is accessed on the warm reset path
|
||
|
|
|
||
|
|
Same as in (4a). The stack and heap halves both may contain garbage, but it
|
||
|
|
doesn't matter.
|
||
|
|
|
||
|
|
(5) permanent PEI memory for the S3 resume path
|
||
|
|
|
||
|
|
(a) when and how it is initialized after first boot of the VM
|
||
|
|
|
||
|
|
No particular initialization or use.
|
||
|
|
|
||
|
|
(b) how it is protected from memory allocations during DXE
|
||
|
|
|
||
|
|
We don't need to protect this area during DXE.
|
||
|
|
|
||
|
|
(c) how it is protected from the OS
|
||
|
|
|
||
|
|
When S3 is enabled, InitializeRamRegions()
|
||
|
|
[OvmfPkg/PlatformPei/MemDetect.c] makes sure the OS stays away by covering
|
||
|
|
the range with an AcpiNVS memory allocation HOB.
|
||
|
|
|
||
|
|
When S3 is disabled, the range needs no protection.
|
||
|
|
|
||
|
|
(d) how it is accessed on the S3 resume path
|
||
|
|
|
||
|
|
PublishPeiMemory() installs the range as permanent RAM for PEI. The range
|
||
|
|
will serve as stack and will satisfy allocation requests during the rest of
|
||
|
|
PEI. OS data won't overlap due to (5c).
|
||
|
|
|
||
|
|
(e) how it is accessed on the warm reset path
|
||
|
|
|
||
|
|
Same as (5a).
|
||
|
|
|
||
|
|
(6) PEIFV -- decompressed firmware volume with PEI modules
|
||
|
|
|
||
|
|
(a) when and how it is initialized after first boot of the VM
|
||
|
|
|
||
|
|
DecompressMemFvs() [OvmfPkg/Sec/SecMain.c] populates the area, by
|
||
|
|
decompressing the flash-mapped FVMAIN_COMPACT volume's contents. (Refer to
|
||
|
|
"Firmware image structure".)
|
||
|
|
|
||
|
|
(b) how it is protected from memory allocations during DXE
|
||
|
|
|
||
|
|
When S3 is disabled, PeiFvInitialization() [OvmfPkg/PlatformPei/Fv.c]
|
||
|
|
covers the range with a BootServicesData memory allocation HOB.
|
||
|
|
|
||
|
|
When S3 is enabled, the same is coverage is ensured, just with the stronger
|
||
|
|
AcpiNVS memory allocation type.
|
||
|
|
|
||
|
|
(c) how it is protected from the OS
|
||
|
|
|
||
|
|
When S3 is disabled, it is not necessary to keep the range from the OS.
|
||
|
|
|
||
|
|
Otherwise the AcpiNVS type allocation from (6b) provides coverage.
|
||
|
|
|
||
|
|
(d) how it is accessed on the S3 resume path
|
||
|
|
|
||
|
|
Rather than decompressing it again from FVMAIN_COMPACT, GetS3ResumePeiFv()
|
||
|
|
[OvmfPkg/Sec/SecMain.c] reuses the protected area for parsing / execution
|
||
|
|
from (6c).
|
||
|
|
|
||
|
|
(e) how it is accessed on the warm reset path
|
||
|
|
|
||
|
|
Same as (6a).
|
||
|
|
|
||
|
|
(7) DXEFV -- decompressed firmware volume with DXE modules
|
||
|
|
|
||
|
|
(a) when and how it is initialized after first boot of the VM
|
||
|
|
|
||
|
|
Same as (6a).
|
||
|
|
|
||
|
|
(b) how it is protected from memory allocations during DXE
|
||
|
|
|
||
|
|
PeiFvInitialization() [OvmfPkg/PlatformPei/Fv.c] covers the range with a
|
||
|
|
BootServicesData memory allocation HOB.
|
||
|
|
|
||
|
|
(c) how it is protected from the OS
|
||
|
|
|
||
|
|
The OS is allowed to release and reuse this range.
|
||
|
|
|
||
|
|
(d) how it is accessed on the S3 resume path
|
||
|
|
|
||
|
|
It's not; DXE never runs during S3 resume.
|
||
|
|
|
||
|
|
(e) how it is accessed on the warm reset path
|
||
|
|
|
||
|
|
Same as in (7a).
|
||
|
|
|
||
|
|
Known Secure Boot limitations
|
||
|
|
-----------------------------
|
||
|
|
|
||
|
|
Under "Motivation" we've mentioned that OVMF's Secure Boot implementation is
|
||
|
|
not suitable for production use yet -- it's only good for development and
|
||
|
|
testing of standards-conformant, non-malicious guest code (UEFI and operating
|
||
|
|
system alike).
|
||
|
|
|
||
|
|
Now that we've examined the persistent flash device, the workings of S3, and
|
||
|
|
the memory map, we can discuss two currently known shortcomings of OVMF's
|
||
|
|
Secure Boot that in fact make it insecure. (Clearly problems other than these
|
||
|
|
two might exist; the set of issues considered here is not meant to be
|
||
|
|
exhaustive.)
|
||
|
|
|
||
|
|
One trait of Secure Boot is tamper-evidence. Secure Boot may not prevent
|
||
|
|
malicious modification of software components (for example, operating system
|
||
|
|
drivers), but by being the root of integrity on a platform, it can catch (or
|
||
|
|
indirectly contribute to catching) unauthorized changes, by way of signature
|
||
|
|
and certificate checks at the earliest phases of boot.
|
||
|
|
|
||
|
|
If an attacker can tamper with key material stored in authenticated and/or
|
||
|
|
boot-time only persistent variables (for example, PK, KEK, db, dbt, dbx), then
|
||
|
|
the intended security of this scheme is compromised. The UEFI 2.4A
|
||
|
|
specification says
|
||
|
|
|
||
|
|
- in section 28.3.4:
|
||
|
|
|
||
|
|
Platform Keys:
|
||
|
|
|
||
|
|
The public key must be stored in non-volatile storage which is tamper and
|
||
|
|
delete resistant.
|
||
|
|
|
||
|
|
Key Exchange Keys:
|
||
|
|
|
||
|
|
The public key must be stored in non-volatile storage which is tamper
|
||
|
|
resistant.
|
||
|
|
|
||
|
|
- in section 28.6.1:
|
||
|
|
|
||
|
|
The signature database variables db, dbt, and dbx must be stored in
|
||
|
|
tamper-resistant non-volatile storage.
|
||
|
|
|
||
|
|
(1) The combination of QEMU, KVM, and OVMF does not provide this kind of
|
||
|
|
resistance. The variable store in the emulated flash chip is directly
|
||
|
|
accessible to, and reprogrammable by, UEFI drivers, applications, and
|
||
|
|
operating systems.
|
||
|
|
|
||
|
|
(2) Under "S3 (suspend to RAM and resume)" we pointed out that the LockBox
|
||
|
|
storage must be similarly secure and tamper-resistant.
|
||
|
|
|
||
|
|
On the S3 resume path, the PEIM providing EFI_PEI_S3_RESUME2_PPI
|
||
|
|
(UefiCpuPkg/Universal/Acpi/S3Resume2Pei) restores and interprets data from
|
||
|
|
the LockBox that has been saved there during boot. This PEIM, being part of
|
||
|
|
the firmware, has full access to the platform. If an operating system can
|
||
|
|
tamper with the contents of the LockBox, then at the next resume the
|
||
|
|
platform's integrity might be subverted.
|
||
|
|
|
||
|
|
OVMF stores the LockBox in normal guest RAM (refer to the memory map
|
||
|
|
section above). Operating systems and third party UEFI drivers and UEFI
|
||
|
|
applications that respect the UEFI memory map will not inadvertently
|
||
|
|
overwrite the LockBox storage, but there's nothing to prevent eg. a
|
||
|
|
malicious kernel from modifying the LockBox.
|
||
|
|
|
||
|
|
One means to address these issues is SMM and SMRAM (System Management Mode and
|
||
|
|
System Management RAM).
|
||
|
|
|
||
|
|
During boot and resume, the firmware can enter and leave SMM and access SMRAM.
|
||
|
|
Before the DXE phase is left, and control is transferred to the BDS phase (when
|
||
|
|
third party UEFI drivers and applications can be loaded, and an operating
|
||
|
|
system can be loaded), SMRAM is locked in hardware, and subsequent modules
|
||
|
|
cannot access it directly. (See EFI_DXE_SMM_READY_TO_LOCK_PROTOCOL.)
|
||
|
|
|
||
|
|
Once SMRAM has been locked, UEFI drivers and the operating system can enter SMM
|
||
|
|
by raising a System Management Interrupt (SMI), at which point trusted code
|
||
|
|
(part of the platform firmware) takes control. SMRAM is also unlocked by
|
||
|
|
platform reset, at which point the boot firmware takes control again.
|
||
|
|
|
||
|
|
Variable store and LockBox in SMRAM
|
||
|
|
-----------------------------------
|
||
|
|
|
||
|
|
Edk2 provides almost all components to implement the variable store and the
|
||
|
|
LockBox in SMRAM. In this section we summarize ideas for utilizing those
|
||
|
|
facilities.
|
||
|
|
|
||
|
|
The SMRAM and SMM infrastructure in edk2 is built up as follows:
|
||
|
|
|
||
|
|
(1) The platform hardware provides SMM / SMI / SMRAM.
|
||
|
|
|
||
|
|
Qemu/KVM doesn't support these features currently and should implement them
|
||
|
|
in the longer term.
|
||
|
|
|
||
|
|
(2) The platform vendor (in this case, OVMF developers) implement device
|
||
|
|
drivers for the platform's System Management Mode:
|
||
|
|
|
||
|
|
- EFI_SMM_CONTROL2_PROTOCOL: for raising a synchronous (and/or) periodic
|
||
|
|
SMI(s); that is, for entering SMM.
|
||
|
|
|
||
|
|
- EFI_SMM_ACCESS2_PROTOCOL: for describing and accessing SMRAM.
|
||
|
|
|
||
|
|
These protocols are documented in the PI Specification, Volume 4.
|
||
|
|
|
||
|
|
(3) The platform DSC file is to include the following platform-independent
|
||
|
|
modules:
|
||
|
|
|
||
|
|
- MdeModulePkg/Core/PiSmmCore/PiSmmIpl.inf: SMM Initial Program Load
|
||
|
|
- MdeModulePkg/Core/PiSmmCore/PiSmmCore.inf: SMM Core
|
||
|
|
|
||
|
|
(4) At this point, modules of type DXE_SMM_DRIVER can be loaded.
|
||
|
|
|
||
|
|
Such drivers are privileged. They run in SMM, have access to SMRAM, and are
|
||
|
|
separated and switched from other drivers through SMIs. Secure
|
||
|
|
communication between unprivileged (non-SMM) and privileged (SMM) drivers
|
||
|
|
happens through EFI_SMM_COMMUNICATION_PROTOCOL (implemented by the SMM
|
||
|
|
Core, see (3)).
|
||
|
|
|
||
|
|
DXE_SMM_DRIVER modules must sanitize their input (coming from unprivileged
|
||
|
|
drivers) carefully.
|
||
|
|
|
||
|
|
(5) The authenticated runtime variable services driver (for Secure Boot builds)
|
||
|
|
is located under "SecurityPkg/VariableAuthenticated/RuntimeDxe". OVMF
|
||
|
|
currently builds the driver (a DXE_RUNTIME_DRIVER module) with the
|
||
|
|
"VariableRuntimeDxe.inf" control file (refer to "OvmfPkg/OvmfPkgX64.dsc"),
|
||
|
|
which does not use SMM.
|
||
|
|
|
||
|
|
The directory includes two more INF files:
|
||
|
|
|
||
|
|
- VariableSmm.inf -- module type: DXE_SMM_DRIVER. A privileged driver that
|
||
|
|
runs in SMM and has access to SMRAM.
|
||
|
|
|
||
|
|
- VariableSmmRuntimeDxe.inf -- module type: DXE_RUNTIME_DRIVER. A
|
||
|
|
non-privileged driver that implements the variable runtime services
|
||
|
|
(replacing the current "VariableRuntimeDxe.inf" file) by communicating
|
||
|
|
with the above privileged SMM half via EFI_SMM_COMMUNICATION_PROTOCOL.
|
||
|
|
|
||
|
|
(6) An SMRAM-based LockBox implementation needs to be discussed in two parts,
|
||
|
|
because the LockBox is accessed in both PEI and DXE.
|
||
|
|
|
||
|
|
(a) During DXE, drivers save data in the LockBox. A save operation is
|
||
|
|
layered as follows:
|
||
|
|
|
||
|
|
- The unprivileged driver wishing to store data in the LockBox links
|
||
|
|
against the "MdeModulePkg/Library/SmmLockBoxLib/SmmLockBoxDxeLib.inf"
|
||
|
|
library instance.
|
||
|
|
|
||
|
|
The library allows the unprivileged driver to format requests for the
|
||
|
|
privileged SMM LockBox driver (see below), and to parse responses.
|
||
|
|
|
||
|
|
- The privileged SMM LockBox driver is built from
|
||
|
|
"MdeModulePkg/Universal/LockBox/SmmLockBox/SmmLockBox.inf". This
|
||
|
|
driver has module type DXE_SMM_DRIVER and can access SMRAM.
|
||
|
|
|
||
|
|
The driver delegates command parsing and response formatting to
|
||
|
|
"MdeModulePkg/Library/SmmLockBoxLib/SmmLockBoxSmmLib.inf".
|
||
|
|
|
||
|
|
- The above two halves (unprivileged and privileged) mirror what we've
|
||
|
|
seen in case of the variable service drivers, under (5).
|
||
|
|
|
||
|
|
(b) In PEI, the S3 Resume PEIM (UefiCpuPkg/Universal/Acpi/S3Resume2Pei)
|
||
|
|
retrieves data from the LockBox.
|
||
|
|
|
||
|
|
Presumably, S3Resume2Pei should be considered an "unprivileged PEIM",
|
||
|
|
and the SMRAM access should be layered as seen in DXE. Unfortunately,
|
||
|
|
edk2 does not implement all of the layers in PEI -- the code either
|
||
|
|
doesn't exist, or it is not open source:
|
||
|
|
|
||
|
|
role | DXE: protocol/module | PEI: PPI/module
|
||
|
|
-------------+--------------------------------+------------------------------
|
||
|
|
unprivileged | any | S3Resume2Pei.inf
|
||
|
|
driver | |
|
||
|
|
-------------+--------------------------------+------------------------------
|
||
|
|
command | LIBRARY_CLASS = LockBoxLib | LIBRARY_CLASS = LockBoxLib
|
||
|
|
formatting | |
|
||
|
|
and response | SmmLockBoxDxeLib.inf | SmmLockBoxPeiLib.inf
|
||
|
|
parsing | |
|
||
|
|
-------------+--------------------------------+------------------------------
|
||
|
|
privilege | EFI_SMM_COMMUNICATION_PROTOCOL | EFI_PEI_SMM_COMMUNICATION_PPI
|
||
|
|
separation | |
|
||
|
|
| PiSmmCore.inf | missing!
|
||
|
|
-------------+--------------------------------+------------------------------
|
||
|
|
platform SMM | EFI_SMM_CONTROL2_PROTOCOL | PEI_SMM_CONTROL_PPI
|
||
|
|
and SMRAM | EFI_SMM_ACCESS2_PROTOCOL | PEI_SMM_ACCESS_PPI
|
||
|
|
access | |
|
||
|
|
| to be done in OVMF | to be done in OVMF
|
||
|
|
-------------+--------------------------------+------------------------------
|
||
|
|
command | LIBRARY_CLASS = LockBoxLib | LIBRARY_CLASS = LockBoxLib
|
||
|
|
parsing and | |
|
||
|
|
response | SmmLockBoxSmmLib.inf | missing!
|
||
|
|
formatting | |
|
||
|
|
-------------+--------------------------------+------------------------------
|
||
|
|
privileged | SmmLockBox.inf | missing!
|
||
|
|
LockBox | |
|
||
|
|
driver | |
|
||
|
|
|
||
|
|
Alternatively, in the future OVMF might be able to provide a LockBoxLib
|
||
|
|
instance (an SmmLockBoxPeiLib substitute) for S3Resume2Pei that
|
||
|
|
accesses SMRAM directly, eliminating the need for deeper layers in the
|
||
|
|
stack (that is, EFI_PEI_SMM_COMMUNICATION_PPI and deeper).
|
||
|
|
|
||
|
|
In fact, a "thin" EFI_PEI_SMM_COMMUNICATION_PPI implementation whose
|
||
|
|
sole Communicate() member invariably returns EFI_NOT_STARTED would
|
||
|
|
cause the current SmmLockBoxPeiLib library instance to directly perform
|
||
|
|
full-depth SMRAM access and LockBox search, obviating the "missing"
|
||
|
|
cells. (With reference to A Tour Beyond BIOS: Implementing S3 Resume
|
||
|
|
with EDK2, by Jiewen Yao and Vincent Zimmer, October 2014.)
|
||
|
|
|
||
|
|
Select features
|
||
|
|
---------------
|
||
|
|
|
||
|
|
In this section we'll browse the top-level "OvmfPkg" package directory, and
|
||
|
|
discuss the more interesting drivers and libraries that have not been mentioned
|
||
|
|
thus far.
|
||
|
|
|
||
|
|
X64-specific reset vector for OVMF
|
||
|
|
..................................
|
||
|
|
|
||
|
|
The "OvmfPkg/ResetVector" directory customizes the reset vector (found in
|
||
|
|
"UefiCpuPkg/ResetVector/Vtf0") for "OvmfPkgX64.fdf", that is, when the SEC/PEI
|
||
|
|
phases run in 64-bit (ie. long) mode.
|
||
|
|
|
||
|
|
The reset vector's control flow looks roughly like:
|
||
|
|
|
||
|
|
resetVector [Ia16/ResetVectorVtf0.asm]
|
||
|
|
EarlyBspInitReal16 [Ia16/Init16.asm]
|
||
|
|
Main16 [Main.asm]
|
||
|
|
EarlyInit16 [Ia16/Init16.asm]
|
||
|
|
|
||
|
|
; Transition the processor from
|
||
|
|
; 16-bit real mode to 32-bit flat mode
|
||
|
|
TransitionFromReal16To32BitFlat [Ia16/Real16ToFlat32.asm]
|
||
|
|
|
||
|
|
; Search for the
|
||
|
|
; Boot Firmware Volume (BFV)
|
||
|
|
Flat32SearchForBfvBase [Ia32/SearchForBfvBase.asm]
|
||
|
|
|
||
|
|
; Search for the SEC entry point
|
||
|
|
Flat32SearchForSecEntryPoint [Ia32/SearchForSecEntry.asm]
|
||
|
|
|
||
|
|
%ifdef ARCH_IA32
|
||
|
|
; Jump to the 32-bit SEC entry point
|
||
|
|
%else
|
||
|
|
; Transition the processor
|
||
|
|
; from 32-bit flat mode
|
||
|
|
; to 64-bit flat mode
|
||
|
|
Transition32FlatTo64Flat [Ia32/Flat32ToFlat64.asm]
|
||
|
|
|
||
|
|
SetCr3ForPageTables64 [Ia32/PageTables64.asm]
|
||
|
|
; set CR3 to page tables
|
||
|
|
; built into the ROM image
|
||
|
|
|
||
|
|
; enable PAE
|
||
|
|
; set LME
|
||
|
|
; enable paging
|
||
|
|
|
||
|
|
; Jump to the 64-bit SEC entry point
|
||
|
|
%endif
|
||
|
|
|
||
|
|
On physical platforms, the initial page tables referenced by
|
||
|
|
SetCr3ForPageTables64 are built statically into the flash device image, and are
|
||
|
|
present in ROM at runtime. This is fine on physical platforms because the
|
||
|
|
pre-built page table entries have the Accessed and Dirty bits set from the
|
||
|
|
start.
|
||
|
|
|
||
|
|
Accordingly, for OVMF running in long mode on qemu/KVM, the initial page tables
|
||
|
|
were mapped as a KVM_MEM_READONLY slot, as part of QEMU's pflash device (refer
|
||
|
|
to "Firmware image structure" above).
|
||
|
|
|
||
|
|
In spite of the Accessed and Dirty bits being pre-set in the read-only,
|
||
|
|
in-flash PTEs, in a virtual machine attempts are made to update said PTE bits,
|
||
|
|
differently from physical hardware. The component attempting to update the
|
||
|
|
read-only PTEs can be one of the following:
|
||
|
|
|
||
|
|
- The processor itself, if it supports nested paging, and the user enables that
|
||
|
|
processor feature,
|
||
|
|
|
||
|
|
- KVM code implementing shadow paging, otherwise.
|
||
|
|
|
||
|
|
The first case presents no user-visible symptoms, but the second case (KVM,
|
||
|
|
shadow paging) used to cause a triple fault, prior to Linux commit ba6a354
|
||
|
|
("KVM: mmu: allow page tables to be in read-only slots").
|
||
|
|
|
||
|
|
For compatibility with earlier KVM versions, the OvmfPkg/ResetVector directory
|
||
|
|
adapts the generic reset vector code as follows:
|
||
|
|
|
||
|
|
Transition32FlatTo64Flat [UefiCpuPkg/.../Ia32/Flat32ToFlat64.asm]
|
||
|
|
|
||
|
|
SetCr3ForPageTables64 [OvmfPkg/ResetVector/Ia32/PageTables64.asm]
|
||
|
|
|
||
|
|
; dynamically build the initial page tables in RAM, at address
|
||
|
|
; PcdOvmfSecPageTablesBase (refer to the memory map above),
|
||
|
|
; identity-mapping the first 4 GB of address space
|
||
|
|
|
||
|
|
; set CR3 to PcdOvmfSecPageTablesBase
|
||
|
|
|
||
|
|
; enable PAE
|
||
|
|
; set LME
|
||
|
|
; enable paging
|
||
|
|
|
||
|
|
This way the PTEs that earlier KVM versions try to update (during shadow
|
||
|
|
paging) are located in a read-write memory slot, and the write attempts
|
||
|
|
succeed.
|
||
|
|
|
||
|
|
Client library for QEMU's firmware configuration interface
|
||
|
|
..........................................................
|
||
|
|
|
||
|
|
QEMU provides a write-only, 16-bit wide control port, and a read-write, 8-bit
|
||
|
|
wide data port for exchanging configuration elements with the firmware.
|
||
|
|
|
||
|
|
The firmware writes a selector (a key) to the control port (0x510), and then
|
||
|
|
reads the corresponding configuration data (produced by QEMU) from the data
|
||
|
|
port (0x511).
|
||
|
|
|
||
|
|
If the selected entry is writable, the firmware may overwrite it. If QEMU has
|
||
|
|
associated a callback with the entry, then when the entry is completely
|
||
|
|
rewritten, QEMU runs the callback. (OVMF does not rewrite any entries at the
|
||
|
|
moment.)
|
||
|
|
|
||
|
|
A number of selector values (keys) are predefined. In particular, key 0x19
|
||
|
|
selects (returns) a directory of { name, selector, size } triplets, roughly
|
||
|
|
speaking.
|
||
|
|
|
||
|
|
The firmware can request configuration elements by well-known name as well, by
|
||
|
|
looking up the selector value first in the directory, by name, and then writing
|
||
|
|
the selector to the control port. The number of bytes to read subsequently from
|
||
|
|
the data port is known from the directory entry's "size" field.
|
||
|
|
|
||
|
|
By convention, directory entries (well-known symbolic names of configuration
|
||
|
|
elements) are formatted as POSIX pathnames. For example, the array selected by
|
||
|
|
the "etc/system-states" name indicates (among other things) whether the user
|
||
|
|
enabled S3 support in QEMU.
|
||
|
|
|
||
|
|
The above interface is called "fw_cfg".
|
||
|
|
|
||
|
|
The binary data associated with a symbolic name is called an "fw_cfg file".
|
||
|
|
|
||
|
|
OVMF's fw_cfg client library is found in "OvmfPkg/Library/QemuFwCfgLib". OVMF
|
||
|
|
discovers many aspects of the virtual system with it; we refer to a few
|
||
|
|
examples below.
|
||
|
|
|
||
|
|
Guest ACPI tables
|
||
|
|
.................
|
||
|
|
|
||
|
|
An operating system discovers a good amount of its hardware by parsing ACPI
|
||
|
|
tables, and by interpreting ACPI objects and methods. On physical hardware, the
|
||
|
|
platform vendor's firmware installs ACPI tables in memory that match both the
|
||
|
|
hardware present in the system and the user's firmware configuration ("BIOS
|
||
|
|
setup").
|
||
|
|
|
||
|
|
Under qemu/KVM, the owner of the (virtual) hardware configuration is QEMU.
|
||
|
|
Hardware can easily be reconfigured on the command line. Furthermore, features
|
||
|
|
like CPU hotplug, PCI hotplug, memory hotplug are continuously developed for
|
||
|
|
QEMU, and operating systems need direct ACPI support to exploit these features.
|
||
|
|
|
||
|
|
For this reason, QEMU builds its own ACPI tables dynamically, in a
|
||
|
|
self-descriptive manner, and exports them to the firmware through a complex,
|
||
|
|
multi-file fw_cfg interface. It is rooted in the "etc/table-loader" fw_cfg
|
||
|
|
file. (Further details of this interface are out of scope for this report.)
|
||
|
|
|
||
|
|
OVMF's AcpiPlatformDxe driver fetches the ACPI tables, and installs them for
|
||
|
|
the guest OS with the EFI_ACPI_TABLE_PROTOCOL (which is in turn provided by the
|
||
|
|
generic "MdeModulePkg/Universal/Acpi/AcpiTableDxe" driver).
|
||
|
|
|
||
|
|
For earlier QEMU versions and machine types (which we generally don't recommend
|
||
|
|
for OVMF; see "Scope"), the "OvmfPkg/AcpiTables" directory contains a few
|
||
|
|
static ACPI table templates. When the "etc/table-loader" fw_cfg file is
|
||
|
|
unavailable, AcpiPlatformDxe installs these default tables (with a little bit
|
||
|
|
of dynamic patching).
|
||
|
|
|
||
|
|
When OVMF runs in a Xen domU, AcpiTableDxe also installs ACPI tables that
|
||
|
|
originate from the hypervisor's environment.
|
||
|
|
|
||
|
|
Guest SMBIOS tables
|
||
|
|
...................
|
||
|
|
|
||
|
|
Quoting the SMBIOS Reference Specification,
|
||
|
|
|
||
|
|
[...] the System Management BIOS Reference Specification addresses how
|
||
|
|
motherboard and system vendors present management information about their
|
||
|
|
products in a standard format [...]
|
||
|
|
|
||
|
|
In practice SMBIOS tables are just another set of tables that the platform
|
||
|
|
vendor's firmware installs in RAM for the operating system, and, importantly,
|
||
|
|
for management applications running on the OS. Without rehashing the "Guest
|
||
|
|
ACPI tables" section in full, let's map the OVMF roles seen there from ACPI to
|
||
|
|
SMBIOS:
|
||
|
|
|
||
|
|
role | ACPI | SMBIOS
|
||
|
|
-------------------------+-------------------------+-------------------------
|
||
|
|
fw_cfg file | etc/table-loader | etc/smbios/smbios-tables
|
||
|
|
-------------------------+-------------------------+-------------------------
|
||
|
|
OVMF driver | AcpiPlatformDxe | SmbiosPlatformDxe
|
||
|
|
under "OvmfPkg" | |
|
||
|
|
-------------------------+-------------------------+-------------------------
|
||
|
|
Underlying protocol, | EFI_ACPI_TABLE_PROTOCOL | EFI_SMBIOS_PROTOCOL
|
||
|
|
implemented by generic | |
|
||
|
|
driver under | Acpi/AcpiTableDxe | SmbiosDxe
|
||
|
|
"MdeModulePkg/Universal" | |
|
||
|
|
-------------------------+-------------------------+-------------------------
|
||
|
|
default tables available | yes | [RHEL] yes, Type0 and
|
||
|
|
for earlier QEMU machine | | Type1 tables
|
||
|
|
types, with hot-patching | |
|
||
|
|
-------------------------+-------------------------+-------------------------
|
||
|
|
tables fetched in Xen | yes | yes
|
||
|
|
domUs | |
|
||
|
|
|
||
|
|
Platform-specific boot policy
|
||
|
|
.............................
|
||
|
|
|
||
|
|
OVMF's BDS (Boot Device Selection) phase is implemented by
|
||
|
|
IntelFrameworkModulePkg/Universal/BdsDxe. Roughly speaking, this large driver:
|
||
|
|
|
||
|
|
- provides the EFI BDS architectural protocol (which DXE transfers control to
|
||
|
|
after dispatching all DXE drivers),
|
||
|
|
|
||
|
|
- connects drivers to devices,
|
||
|
|
|
||
|
|
- enumerates boot devices,
|
||
|
|
|
||
|
|
- auto-generates boot options,
|
||
|
|
|
||
|
|
- provides "BIOS setup" screens, such as:
|
||
|
|
|
||
|
|
- Boot Manager, for booting an option,
|
||
|
|
|
||
|
|
- Boot Maintenance Manager, for adding, deleting, and reordering boot
|
||
|
|
options, changing console properties etc,
|
||
|
|
|
||
|
|
- Device Manager, where devices can register configuration forms, including
|
||
|
|
|
||
|
|
- Secure Boot configuration forms,
|
||
|
|
|
||
|
|
- OVMF's Platform Driver form (see under PlatformDxe).
|
||
|
|
|
||
|
|
Firmware that includes the "IntelFrameworkModulePkg/Universal/BdsDxe" driver
|
||
|
|
can customize its behavior by providing an instance of the PlatformBdsLib
|
||
|
|
library class. The driver links against this platform library, and the
|
||
|
|
platform library can call Intel's BDS utility functions from
|
||
|
|
"IntelFrameworkModulePkg/Library/GenericBdsLib".
|
||
|
|
|
||
|
|
OVMF's PlatformBdsLib instance can be found in
|
||
|
|
"OvmfPkg/Library/PlatformBdsLib". The main function where the BdsDxe driver
|
||
|
|
enters the library is PlatformBdsPolicyBehavior(). We mention two OVMF
|
||
|
|
particulars here.
|
||
|
|
|
||
|
|
(1) OVMF is capable of loading kernel images directly from fw_cfg, matching
|
||
|
|
QEMU's -kernel, -initrd, and -append command line options. This feature is
|
||
|
|
useful for rapid, repeated Linux kernel testing, and is implemented in the
|
||
|
|
following call tree:
|
||
|
|
|
||
|
|
PlatformBdsPolicyBehavior() [OvmfPkg/Library/PlatformBdsLib/BdsPlatform.c]
|
||
|
|
TryRunningQemuKernel() [OvmfPkg/Library/PlatformBdsLib/QemuKernel.c]
|
||
|
|
LoadLinux*() [OvmfPkg/Library/LoadLinuxLib/Linux.c]
|
||
|
|
|
||
|
|
OvmfPkg/Library/LoadLinuxLib ports the efilinux bootloader project into
|
||
|
|
OvmfPkg.
|
||
|
|
|
||
|
|
(2) OVMF seeks to comply with the boot order specification passed down by QEMU
|
||
|
|
over fw_cfg.
|
||
|
|
|
||
|
|
(a) About Boot Modes
|
||
|
|
|
||
|
|
During the PEI phase, OVMF determines and stores the Boot Mode in the
|
||
|
|
PHIT HOB (already mentioned in "S3 (suspend to RAM and resume)"). The
|
||
|
|
boot mode is supposed to influence the rest of the system, for example it
|
||
|
|
distinguishes S3 resume (BOOT_ON_S3_RESUME) from a "normal" boot.
|
||
|
|
|
||
|
|
In general, "normal" boots can be further differentiated from each other;
|
||
|
|
for example for speed reasons. When the firmware can tell during PEI that
|
||
|
|
the chassis has not been opened since last power-up, then it might want
|
||
|
|
to save time by not connecting all devices and not enumerating all boot
|
||
|
|
options from scratch; it could just rely on the stored results of the
|
||
|
|
last enumeration. The matching BootMode value, to be set during PEI,
|
||
|
|
would be BOOT_ASSUMING_NO_CONFIGURATION_CHANGES.
|
||
|
|
|
||
|
|
OVMF only sets one of the following two boot modes, based on CMOS
|
||
|
|
contents:
|
||
|
|
- BOOT_ON_S3_RESUME,
|
||
|
|
- BOOT_WITH_FULL_CONFIGURATION.
|
||
|
|
|
||
|
|
For BOOT_ON_S3_RESUME, please refer to "S3 (suspend to RAM and resume)".
|
||
|
|
The other boot mode supported by OVMF, BOOT_WITH_FULL_CONFIGURATION, is
|
||
|
|
an appropriate "catch-all" for a virtual machine, where hardware can
|
||
|
|
easily change from boot to boot.
|
||
|
|
|
||
|
|
(b) Auto-generation of boot options
|
||
|
|
|
||
|
|
Accordingly, when not resuming from S3 sleep (*), OVMF always connects
|
||
|
|
all devices, and enumerates all bootable devices as new boot options
|
||
|
|
(non-volatile variables called Boot####).
|
||
|
|
|
||
|
|
(*) During S3 resume, DXE is not reached, hence BDS isn't either.
|
||
|
|
|
||
|
|
The auto-enumerated boot options are stored in the BootOrder non-volatile
|
||
|
|
variable after any preexistent options. (Boot options may exist before
|
||
|
|
auto-enumeration eg. because the user added them manually with the Boot
|
||
|
|
Maintenance Manager or the efibootmgr utility. They could also originate
|
||
|
|
from an earlier auto-enumeration.)
|
||
|
|
|
||
|
|
PlatformBdsPolicyBehavior() [OvmfPkg/.../BdsPlatform.c]
|
||
|
|
TryRunningQemuKernel() [OvmfPkg/.../QemuKernel.c]
|
||
|
|
BdsLibConnectAll() [IntelFrameworkModulePkg/.../BdsConnect.c]
|
||
|
|
BdsLibEnumerateAllBootOption() [IntelFrameworkModulePkg/.../BdsBoot.c]
|
||
|
|
BdsLibBuildOptionFromHandle() [IntelFrameworkModulePkg/.../BdsBoot.c]
|
||
|
|
BdsLibRegisterNewOption() [IntelFrameworkModulePkg/.../BdsMisc.c]
|
||
|
|
//
|
||
|
|
// Append the new option number to the original option order
|
||
|
|
//
|
||
|
|
|
||
|
|
(c) Relative UEFI device paths in boot options
|
||
|
|
|
||
|
|
The handling of relative ("short-form") UEFI device paths is best
|
||
|
|
demonstrated through an example, and by quoting the UEFI 2.4A
|
||
|
|
specification.
|
||
|
|
|
||
|
|
A short-form hard drive UEFI device path could be (displaying each device
|
||
|
|
path node on a separate line for readability):
|
||
|
|
|
||
|
|
HD(1,GPT,14DD1CC5-D576-4BBF-8858-BAF877C8DF61,0x800,0x64000)/
|
||
|
|
\EFI\fedora\shim.efi
|
||
|
|
|
||
|
|
This device path lacks prefix nodes (eg. hardware or messaging type
|
||
|
|
nodes) that would lead to the hard drive. During load option processing,
|
||
|
|
the above short-form or relative device path could be matched against the
|
||
|
|
following absolute device path:
|
||
|
|
|
||
|
|
PciRoot(0x0)/
|
||
|
|
Pci(0x4,0x0)/
|
||
|
|
HD(1,GPT,14DD1CC5-D576-4BBF-8858-BAF877C8DF61,0x800,0x64000)/
|
||
|
|
\EFI\fedora\shim.efi
|
||
|
|
|
||
|
|
The motivation for this type of device path matching / completion is to
|
||
|
|
allow the user to move around the hard drive (for example, to plug a
|
||
|
|
controller in a different PCI slot, or to expose the block device on a
|
||
|
|
different iSCSI path) and still enable the firmware to find the hard
|
||
|
|
drive.
|
||
|
|
|
||
|
|
The UEFI specification says,
|
||
|
|
|
||
|
|
9.3.6 Media Device Path
|
||
|
|
9.3.6.1 Hard Drive
|
||
|
|
|
||
|
|
[...] Section 3.1.2 defines special rules for processing the Hard
|
||
|
|
Drive Media Device Path. These special rules enable a disk's location
|
||
|
|
to change and still have the system boot from the disk. [...]
|
||
|
|
|
||
|
|
3.1.2 Load Option Processing
|
||
|
|
|
||
|
|
[...] The boot manager must [...] support booting from a short-form
|
||
|
|
device path that starts with the first element being a hard drive
|
||
|
|
media device path [...]. The boot manager must use the GUID or
|
||
|
|
signature and partition number in the hard drive device path to match
|
||
|
|
it to a device in the system. If the drive supports the GPT
|
||
|
|
partitioning scheme the GUID in the hard drive media device path is
|
||
|
|
compared with the UniquePartitionGuid field of the GUID Partition
|
||
|
|
Entry [...]. If the drive supports the PC-AT MBR scheme the signature
|
||
|
|
in the hard drive media device path is compared with the
|
||
|
|
UniqueMBRSignature in the Legacy Master Boot Record [...]. If a
|
||
|
|
signature match is made, then the partition number must also be
|
||
|
|
matched. The hard drive device path can be appended to the matching
|
||
|
|
hardware device path and normal boot behavior can then be used. If
|
||
|
|
more than one device matches the hard drive device path, the boot
|
||
|
|
manager will pick one arbitrarily. Thus the operating system must
|
||
|
|
ensure the uniqueness of the signatures on hard drives to guarantee
|
||
|
|
deterministic boot behavior.
|
||
|
|
|
||
|
|
Edk2 implements and exposes the device path completion logic in the
|
||
|
|
already referenced "IntelFrameworkModulePkg/Library/GenericBdsLib"
|
||
|
|
library, in the BdsExpandPartitionPartialDevicePathToFull() function.
|
||
|
|
|
||
|
|
(d) Filtering and reordering the boot options based on fw_cfg
|
||
|
|
|
||
|
|
Once we have an "all-inclusive", partly preexistent, partly freshly
|
||
|
|
auto-generated boot option list from bullet (b), OVMF loads QEMU's
|
||
|
|
requested boot order from fw_cfg, and filters and reorders the list from
|
||
|
|
(b) with it:
|
||
|
|
|
||
|
|
PlatformBdsPolicyBehavior() [OvmfPkg/.../BdsPlatform.c]
|
||
|
|
TryRunningQemuKernel() [OvmfPkg/.../QemuKernel.c]
|
||
|
|
BdsLibConnectAll() [IntelFrameworkModulePkg/.../BdsConnect.c]
|
||
|
|
BdsLibEnumerateAllBootOption() [IntelFrameworkModulePkg/.../BdsBoot.c]
|
||
|
|
SetBootOrderFromQemu() [OvmfPkg/.../QemuBootOrder.c]
|
||
|
|
|
||
|
|
According to the (preferred) "-device ...,bootindex=N" and the (legacy)
|
||
|
|
'-boot order=drives' command line options, QEMU requests a boot order
|
||
|
|
from the firmware through the "bootorder" fw_cfg file. (For a bootindex
|
||
|
|
example, refer to the "Example qemu invocation" section.)
|
||
|
|
|
||
|
|
This fw_cfg file consists of OpenFirmware (OFW) device paths -- note: not
|
||
|
|
UEFI device paths! --, one per line. An example list is:
|
||
|
|
|
||
|
|
/pci@i0cf8/scsi@4/disk@0,0
|
||
|
|
/pci@i0cf8/ide@1,1/drive@1/disk@0
|
||
|
|
/pci@i0cf8/ethernet@3/ethernet-phy@0
|
||
|
|
|
||
|
|
OVMF filters and reorders the boot option list from bullet (b) with the
|
||
|
|
following nested loops algorithm:
|
||
|
|
|
||
|
|
new_uefi_order := <empty>
|
||
|
|
for each qemu_ofw_path in QEMU's OpenFirmware device path list:
|
||
|
|
qemu_uefi_path_prefix := translate(qemu_ofw_path)
|
||
|
|
|
||
|
|
for each boot_option in current_uefi_order:
|
||
|
|
full_boot_option := complete(boot_option)
|
||
|
|
|
||
|
|
if match(qemu_uefi_path_prefix, full_boot_option):
|
||
|
|
append(new_uefi_order, boot_option)
|
||
|
|
break
|
||
|
|
|
||
|
|
for each unmatched boot_option in current_uefi_order:
|
||
|
|
if survives(boot_option):
|
||
|
|
append(new_uefi_order, boot_option)
|
||
|
|
|
||
|
|
current_uefi_order := new_uefi_order
|
||
|
|
|
||
|
|
OVMF iterates over QEMU's OFW device paths in order, translates each to a
|
||
|
|
UEFI device path prefix, tries to match the translated prefix against the
|
||
|
|
UEFI boot options (which are completed from relative form to absolute
|
||
|
|
form for the purpose of prefix matching), and if there's a match, the
|
||
|
|
matching boot option is appended to the new boot order (which starts out
|
||
|
|
empty).
|
||
|
|
|
||
|
|
(We elaborate on the translate() function under bullet (e). The
|
||
|
|
complete() function has been explained in bullet (c).)
|
||
|
|
|
||
|
|
In addition, UEFI boot options that remain unmatched after filtering and
|
||
|
|
reordering are post-processed, and some of them "survive". Due to the
|
||
|
|
fact that OpenFirmware device paths have less expressive power than their
|
||
|
|
UEFI counterparts, some UEFI boot options are simply inexpressible (hence
|
||
|
|
unmatchable) by the nested loops algorithm.
|
||
|
|
|
||
|
|
An important example is the memory-mapped UEFI shell, whose UEFI device
|
||
|
|
path is inexpressible by QEMU's OFW device paths:
|
||
|
|
|
||
|
|
MemoryMapped(0xB,0x900000,0x10FFFFF)/
|
||
|
|
FvFile(7C04A583-9E3E-4F1C-AD65-E05268D0B4D1)
|
||
|
|
|
||
|
|
(Side remark: notice that the address range visible in the MemoryMapped()
|
||
|
|
node corresponds to DXEFV under "comprehensive memory map of OVMF"! In
|
||
|
|
addition, the FvFile() node's GUID originates from the FILE_GUID entry of
|
||
|
|
"ShellPkg/Application/Shell/Shell.inf".)
|
||
|
|
|
||
|
|
The UEFI shell can be booted by pressing ESC in OVMF on the TianoCore
|
||
|
|
splash screen, and navigating to Boot Manager | EFI Internal Shell. If
|
||
|
|
the "survival policy" was not implemented, the UEFI shell's boot option
|
||
|
|
would always be filtered out.
|
||
|
|
|
||
|
|
The current "survival policy" preserves all boot options that start with
|
||
|
|
neither PciRoot() nor HD().
|
||
|
|
|
||
|
|
(e) Translating QEMU's OpenFirmware device paths to UEFI device path
|
||
|
|
prefixes
|
||
|
|
|
||
|
|
In this section we list the (strictly heuristical) mappings currently
|
||
|
|
performed by OVMF.
|
||
|
|
|
||
|
|
The "prefix only" nature of the translation output is rooted minimally in
|
||
|
|
the fact that QEMU's OpenFirmware device paths cannot carry pathnames
|
||
|
|
within filesystems. There's no way to specify eg.
|
||
|
|
|
||
|
|
\EFI\fedora\shim.efi
|
||
|
|
|
||
|
|
in an OFW device path, therefore a UEFI device path translated from an
|
||
|
|
OFW device path can at best be a prefix (not a full match) of a UEFI
|
||
|
|
device path that ends with "\EFI\fedora\shim.efi".
|
||
|
|
|
||
|
|
- IDE disk, IDE CD-ROM:
|
||
|
|
|
||
|
|
OpenFirmware device path:
|
||
|
|
|
||
|
|
/pci@i0cf8/ide@1,1/drive@0/disk@0
|
||
|
|
^ ^ ^ ^ ^
|
||
|
|
| | | | master or slave
|
||
|
|
| | | primary or secondary
|
||
|
|
| PCI slot & function holding IDE controller
|
||
|
|
PCI root at system bus port, PIO
|
||
|
|
|
||
|
|
UEFI device path prefix:
|
||
|
|
|
||
|
|
PciRoot(0x0)/Pci(0x1,0x1)/Ata(Primary,Master,0x0)
|
||
|
|
^
|
||
|
|
fixed LUN
|
||
|
|
|
||
|
|
- Floppy disk:
|
||
|
|
|
||
|
|
OpenFirmware device path:
|
||
|
|
|
||
|
|
/pci@i0cf8/isa@1/fdc@03f0/floppy@0
|
||
|
|
^ ^ ^ ^
|
||
|
|
| | | A: or B:
|
||
|
|
| | ISA controller io-port (hex)
|
||
|
|
| PCI slot holding ISA controller
|
||
|
|
PCI root at system bus port, PIO
|
||
|
|
|
||
|
|
UEFI device path prefix:
|
||
|
|
|
||
|
|
PciRoot(0x0)/Pci(0x1,0x0)/Floppy(0x0)
|
||
|
|
^
|
||
|
|
ACPI UID (A: or B:)
|
||
|
|
|
||
|
|
- Virtio-block disk:
|
||
|
|
|
||
|
|
OpenFirmware device path:
|
||
|
|
|
||
|
|
/pci@i0cf8/scsi@6[,3]/disk@0,0
|
||
|
|
^ ^ ^ ^ ^
|
||
|
|
| | | fixed
|
||
|
|
| | PCI function corresponding to disk (optional)
|
||
|
|
| PCI slot holding disk
|
||
|
|
PCI root at system bus port, PIO
|
||
|
|
|
||
|
|
UEFI device path prefixes (dependent on the presence of a nonzero PCI
|
||
|
|
function in the OFW device path):
|
||
|
|
|
||
|
|
PciRoot(0x0)/Pci(0x6,0x0)/HD(
|
||
|
|
PciRoot(0x0)/Pci(0x6,0x3)/HD(
|
||
|
|
|
||
|
|
- Virtio-scsi disk and virtio-scsi passthrough:
|
||
|
|
|
||
|
|
OpenFirmware device path:
|
||
|
|
|
||
|
|
/pci@i0cf8/scsi@7[,3]/channel@0/disk@2,3
|
||
|
|
^ ^ ^ ^ ^
|
||
|
|
| | | | LUN
|
||
|
|
| | | target
|
||
|
|
| | channel (unused, fixed 0)
|
||
|
|
| PCI slot[, function] holding SCSI controller
|
||
|
|
PCI root at system bus port, PIO
|
||
|
|
|
||
|
|
UEFI device path prefixes (dependent on the presence of a nonzero PCI
|
||
|
|
function in the OFW device path):
|
||
|
|
|
||
|
|
PciRoot(0x0)/Pci(0x7,0x0)/Scsi(0x2,0x3)
|
||
|
|
PciRoot(0x0)/Pci(0x7,0x3)/Scsi(0x2,0x3)
|
||
|
|
|
||
|
|
- Emulated and passed-through (physical) network cards:
|
||
|
|
|
||
|
|
OpenFirmware device path:
|
||
|
|
|
||
|
|
/pci@i0cf8/ethernet@3[,2]
|
||
|
|
^ ^
|
||
|
|
| PCI slot[, function] holding Ethernet card
|
||
|
|
PCI root at system bus port, PIO
|
||
|
|
|
||
|
|
UEFI device path prefixes (dependent on the presence of a nonzero PCI
|
||
|
|
function in the OFW device path):
|
||
|
|
|
||
|
|
PciRoot(0x0)/Pci(0x3,0x0)
|
||
|
|
PciRoot(0x0)/Pci(0x3,0x2)
|
||
|
|
|
||
|
|
Virtio drivers
|
||
|
|
..............
|
||
|
|
|
||
|
|
UEFI abstracts various types of hardware resources into protocols, and allows
|
||
|
|
firmware developers to implement those protocols in device drivers. The Virtio
|
||
|
|
Specification defines various types of virtual hardware for virtual machines.
|
||
|
|
Connecting the two specifications, OVMF provides UEFI drivers for QEMU's
|
||
|
|
virtio-block, virtio-scsi, and virtio-net devices.
|
||
|
|
|
||
|
|
The following diagram presents the protocol and driver stack related to Virtio
|
||
|
|
devices in edk2 and OVMF. Each node in the graph identifies a protocol and/or
|
||
|
|
the edk2 driver that produces it. Nodes on the top are more abstract.
|
||
|
|
|
||
|
|
EFI_BLOCK_IO_PROTOCOL EFI_SIMPLE_NETWORK_PROTOCOL
|
||
|
|
[OvmfPkg/VirtioBlkDxe] [OvmfPkg/VirtioNetDxe]
|
||
|
|
| |
|
||
|
|
| EFI_EXT_SCSI_PASS_THRU_PROTOCOL |
|
||
|
|
| [OvmfPkg/VirtioScsiDxe] |
|
||
|
|
| | |
|
||
|
|
+------------------------+--------------------------+
|
||
|
|
|
|
||
|
|
VIRTIO_DEVICE_PROTOCOL
|
||
|
|
|
|
||
|
|
+---------------------+---------------------+
|
||
|
|
| |
|
||
|
|
[OvmfPkg/VirtioPciDeviceDxe] [custom platform drivers]
|
||
|
|
| |
|
||
|
|
| |
|
||
|
|
EFI_PCI_IO_PROTOCOL [OvmfPkg/Library/VirtioMmioDeviceLib]
|
||
|
|
[MdeModulePkg/Bus/Pci/PciBusDxe] direct MMIO register access
|
||
|
|
|
||
|
|
The top three drivers produce standard UEFI abstractions: the Block IO
|
||
|
|
Protocol, the Extended SCSI Pass Thru Protocol, and the Simple Network
|
||
|
|
Protocol, for virtio-block, virtio-scsi, and virtio-net devices, respectively.
|
||
|
|
|
||
|
|
Comparing these device-specific virtio drivers to each other, we can determine:
|
||
|
|
|
||
|
|
- They all conform to the UEFI Driver Model. This means that their entry point
|
||
|
|
functions don't immediately start to search for devices and to drive them,
|
||
|
|
they only register instances of the EFI_DRIVER_BINDING_PROTOCOL. The UEFI
|
||
|
|
Driver Model then enumerates devices and chains matching drivers
|
||
|
|
automatically.
|
||
|
|
|
||
|
|
- They are as minimal as possible, while remaining correct (refer to source
|
||
|
|
code comments for details). For example, VirtioBlkDxe and VirtioScsiDxe both
|
||
|
|
support only one request in flight.
|
||
|
|
|
||
|
|
In theory, VirtioBlkDxe could implement EFI_BLOCK_IO2_PROTOCOL, which allows
|
||
|
|
queueing. Similarly, VirtioScsiDxe does not support the non-blocking mode of
|
||
|
|
EFI_EXT_SCSI_PASS_THRU_PROTOCOL.PassThru(). (Which is permitted by the UEFI
|
||
|
|
specification.) Both VirtioBlkDxe and VirtioScsiDxe delegate synchronous
|
||
|
|
request handling to "OvmfPkg/Library/VirtioLib". This limitation helps keep
|
||
|
|
the implementation simple, and testing thus far seems to imply satisfactory
|
||
|
|
performance, for a virtual boot firmware.
|
||
|
|
|
||
|
|
VirtioNetDxe cannot avoid queueing, because EFI_SIMPLE_NETWORK_PROTOCOL
|
||
|
|
requires it on the interface level. Consequently, VirtioNetDxe is
|
||
|
|
significantly more complex than VirtioBlkDxe and VirtioScsiDxe. Technical
|
||
|
|
notes are provided in "OvmfPkg/VirtioNetDxe/TechNotes.txt".
|
||
|
|
|
||
|
|
- None of these drivers access hardware directly. Instead, the Virtio Device
|
||
|
|
Protocol (OvmfPkg/Include/Protocol/VirtioDevice.h) collects / extracts virtio
|
||
|
|
operations defined in the Virtio Specification, and these backend-independent
|
||
|
|
virtio device drivers go through the abstract VIRTIO_DEVICE_PROTOCOL.
|
||
|
|
|
||
|
|
IMPORTANT: the VIRTIO_DEVICE_PROTOCOL is not a standard UEFI protocol. It is
|
||
|
|
internal to edk2 and not described in the UEFI specification. It should only
|
||
|
|
be used by drivers and applications that live inside the edk2 source tree.
|
||
|
|
|
||
|
|
Currently two providers exist for VIRTIO_DEVICE_PROTOCOL:
|
||
|
|
|
||
|
|
- The first one is the "more traditional" virtio-pci backend, implemented by
|
||
|
|
OvmfPkg/VirtioPciDeviceDxe. This driver also complies with the UEFI Driver
|
||
|
|
Model. It consumes an instance of the EFI_PCI_IO_PROTOCOL, and, if the PCI
|
||
|
|
device/function under probing appears to be a virtio device, it produces a
|
||
|
|
Virtio Device Protocol instance for it. The driver translates abstract virtio
|
||
|
|
operations to PCI accesses.
|
||
|
|
|
||
|
|
- The second provider, the virtio-mmio backend, is a library, not a driver,
|
||
|
|
living in OvmfPkg/Library/VirtioMmioDeviceLib. This library translates
|
||
|
|
abstract virtio operations to MMIO accesses.
|
||
|
|
|
||
|
|
The virtio-mmio backend is only a library -- rather than a standalone, UEFI
|
||
|
|
Driver Model-compliant driver -- because the type of resource it consumes, an
|
||
|
|
MMIO register block base address, is not enumerable.
|
||
|
|
|
||
|
|
In other words, while the PCI root bridge driver and the PCI bus driver
|
||
|
|
produce instances of EFI_PCI_IO_PROTOCOL automatically, thereby enabling the
|
||
|
|
UEFI Driver Model to probe devices and stack up drivers automatically, no
|
||
|
|
such enumeration exists for MMIO register blocks.
|
||
|
|
|
||
|
|
For this reason, VirtioMmioDeviceLib needs to be linked into thin, custom
|
||
|
|
platform drivers that dispose over this kind of information. As soon as a
|
||
|
|
driver knows about the MMIO register block base addresses, it can pass each
|
||
|
|
to the library, and then the VIRTIO_DEVICE_PROTOCOL will be instantiated
|
||
|
|
(assuming a valid virtio-mmio register block of course). From that point on
|
||
|
|
the UEFI Driver Model again takes care of the chaining.
|
||
|
|
|
||
|
|
Typically, such a custom driver does not conform to the UEFI Driver Model
|
||
|
|
(because that would presuppose auto-enumeration for MMIO register blocks).
|
||
|
|
Hence it has the following responsibilities:
|
||
|
|
|
||
|
|
- it shall behave as a "wrapper" UEFI driver around the library,
|
||
|
|
|
||
|
|
- it shall know virtio-mmio base addresses,
|
||
|
|
|
||
|
|
- in its entry point function, it shall create a new UEFI handle with an
|
||
|
|
instance of the EFI_DEVICE_PATH_PROTOCOL for each virtio-mmio device it
|
||
|
|
knows the base address for,
|
||
|
|
|
||
|
|
- it shall call VirtioMmioInstallDevice() on those handles, with the
|
||
|
|
corresponding base addresses.
|
||
|
|
|
||
|
|
OVMF itself does not employ VirtioMmioDeviceLib. However, the library is used
|
||
|
|
(or has been tested as Proof-of-Concept) in the following 64-bit and 32-bit
|
||
|
|
ARM emulator setups:
|
||
|
|
|
||
|
|
- in "RTSM_VE_FOUNDATIONV8_EFI.fd" and "FVP_AARCH64_EFI.fd", on ARM Holdings'
|
||
|
|
ARM(R) v8-A Foundation Model and ARM(R) AEMv8-A Base Platform FVP
|
||
|
|
emulators, respectively:
|
||
|
|
|
||
|
|
EFI_BLOCK_IO_PROTOCOL
|
||
|
|
[OvmfPkg/VirtioBlkDxe]
|
||
|
|
|
|
||
|
|
VIRTIO_DEVICE_PROTOCOL
|
||
|
|
[ArmPlatformPkg/ArmVExpressPkg/ArmVExpressDxe/ArmFvpDxe.inf]
|
||
|
|
|
|
||
|
|
[OvmfPkg/Library/VirtioMmioDeviceLib]
|
||
|
|
direct MMIO register access
|
||
|
|
|
||
|
|
- in "RTSM_VE_CORTEX-A15_EFI.fd" and "RTSM_VE_CORTEX-A15_MPCORE_EFI.fd", on
|
||
|
|
"qemu-system-arm -M vexpress-a15":
|
||
|
|
|
||
|
|
EFI_BLOCK_IO_PROTOCOL EFI_SIMPLE_NETWORK_PROTOCOL
|
||
|
|
[OvmfPkg/VirtioBlkDxe] [OvmfPkg/VirtioNetDxe]
|
||
|
|
| |
|
||
|
|
+------------------+---------------+
|
||
|
|
|
|
||
|
|
VIRTIO_DEVICE_PROTOCOL
|
||
|
|
[ArmPlatformPkg/ArmVExpressPkg/ArmVExpressDxe/ArmFvpDxe.inf]
|
||
|
|
|
|
||
|
|
[OvmfPkg/Library/VirtioMmioDeviceLib]
|
||
|
|
direct MMIO register access
|
||
|
|
|
||
|
|
In the above ARM / VirtioMmioDeviceLib configurations, VirtioBlkDxe was
|
||
|
|
tested with booting Linux distributions, while VirtioNetDxe was tested with
|
||
|
|
pinging public IPv4 addresses from the UEFI shell.
|
||
|
|
|
||
|
|
Platform Driver
|
||
|
|
...............
|
||
|
|
|
||
|
|
Sometimes, elements of persistent firmware configuration are best exposed to
|
||
|
|
the user in a friendly way. OVMF's platform driver (OvmfPkg/PlatformDxe)
|
||
|
|
presents such settings on the "OVMF Platform Configuration" dialog:
|
||
|
|
|
||
|
|
- Press ESC on the TianoCore splash screen,
|
||
|
|
- Navigate to Device Manager | OVMF Platform Configuration.
|
||
|
|
|
||
|
|
At the moment, OVMF's platform driver handles only one setting: the preferred
|
||
|
|
graphics resolution. This is useful for two purposes:
|
||
|
|
|
||
|
|
- Some UEFI shell commands, like DRIVERS and DEVICES, benefit from a wide
|
||
|
|
display. Using the MODE shell command, the user can switch to a larger text
|
||
|
|
resolution (limited by the graphics resolution), and see the command output
|
||
|
|
in a more easily consumable way.
|
||
|
|
|
||
|
|
[RHEL] The list of text modes available to the MODE command is also limited
|
||
|
|
by ConSplitterDxe (found under MdeModulePkg/Universal/Console).
|
||
|
|
ConSplitterDxe builds an intersection of text modes that are
|
||
|
|
simultaneously supported by all consoles that ConSplitterDxe
|
||
|
|
multiplexes console output to.
|
||
|
|
|
||
|
|
In practice, the strongest text mode restriction comes from
|
||
|
|
TerminalDxe, which provides console I/O on serial ports. TerminalDxe
|
||
|
|
has a very limited built-in list of text modes, heavily pruning the
|
||
|
|
intersection built by ConSplitterDxe, and made available to the MODE
|
||
|
|
command.
|
||
|
|
|
||
|
|
On the Red Hat Enterprise Linux 7.1 host, TerminalDxe's list of modes
|
||
|
|
has been extended with text resolutions that match the Spice QXL GPU's
|
||
|
|
common graphics resolutions. This way a "full screen" text mode should
|
||
|
|
always be available in the MODE command.
|
||
|
|
|
||
|
|
- The other advantage of controlling the graphics resolution lies with UEFI
|
||
|
|
operating systems that don't (yet) have a native driver for QEMU's virtual
|
||
|
|
video cards -- eg. the Spice QXL GPU. Such OSes may choose to inherit the
|
||
|
|
properties of OVMF's EFI_GRAPHICS_OUTPUT_PROTOCOL (provided by
|
||
|
|
OvmfPkg/QemuVideoDxe, see later).
|
||
|
|
|
||
|
|
Although the display can be used at runtime in such cases, by direct
|
||
|
|
framebuffer access, its properties, for example, the resolution, cannot be
|
||
|
|
modified. The platform driver allows the user to select the preferred GOP
|
||
|
|
resolution, reboot, and let the guest OS inherit that preferred resolution.
|
||
|
|
|
||
|
|
The platform driver has three access points: the "normal" driver entry point, a
|
||
|
|
set of HII callbacks, and a GOP installation callback.
|
||
|
|
|
||
|
|
(1) Driver entry point: the PlatformInit() function.
|
||
|
|
|
||
|
|
(a) First, this function loads any available settings, and makes them take
|
||
|
|
effect. For the preferred graphics resolution in particular, this means
|
||
|
|
setting the following PCDs:
|
||
|
|
|
||
|
|
gEfiMdeModulePkgTokenSpaceGuid.PcdVideoHorizontalResolution
|
||
|
|
gEfiMdeModulePkgTokenSpaceGuid.PcdVideoVerticalResolution
|
||
|
|
|
||
|
|
These PCDs influence the GraphicsConsoleDxe driver (located under
|
||
|
|
MdeModulePkg/Universal/Console), which switches to the preferred
|
||
|
|
graphics mode, and produces EFI_SIMPLE_TEXT_OUTPUT_PROTOCOLs on GOPs:
|
||
|
|
|
||
|
|
EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL
|
||
|
|
[MdeModulePkg/Universal/Console/GraphicsConsoleDxe]
|
||
|
|
|
|
||
|
|
EFI_GRAPHICS_OUTPUT_PROTOCOL
|
||
|
|
[OvmfPkg/QemuVideoDxe]
|
||
|
|
|
|
||
|
|
EFI_PCI_IO_PROTOCOL
|
||
|
|
[MdeModulePkg/Bus/Pci/PciBusDxe]
|
||
|
|
|
||
|
|
(b) Second, the driver entry point registers the user interface, including
|
||
|
|
HII callbacks.
|
||
|
|
|
||
|
|
(c) Third, the driver entry point registers a GOP installation callback.
|
||
|
|
|
||
|
|
(2) HII callbacks and the user interface.
|
||
|
|
|
||
|
|
The Human Interface Infrastructure (HII) "is a set of protocols that allow
|
||
|
|
a UEFI driver to provide the ability to register user interface and
|
||
|
|
configuration content with the platform firmware".
|
||
|
|
|
||
|
|
OVMF's platform driver:
|
||
|
|
|
||
|
|
- provides a static, basic, visual form (PlatformForms.vfr), written in the
|
||
|
|
Visual Forms Representation language,
|
||
|
|
|
||
|
|
- includes a UCS-16 encoded message catalog (Platform.uni),
|
||
|
|
|
||
|
|
- includes source code that dynamically populates parts of the form, with
|
||
|
|
the help of MdeModulePkg/Library/UefiHiiLib -- this library simplifies
|
||
|
|
the handling of IFR (Internal Forms Representation) opcodes,
|
||
|
|
|
||
|
|
- processes form actions that the user takes (Callback() function),
|
||
|
|
|
||
|
|
- loads and saves platform configuration in a private, non-volatile
|
||
|
|
variable (ExtractConfig() and RouteConfig() functions).
|
||
|
|
|
||
|
|
The ExtractConfig() HII callback implements the following stack of
|
||
|
|
conversions, for loading configuration and presenting it to the user:
|
||
|
|
|
||
|
|
MultiConfigAltResp -- form engine / HII communication
|
||
|
|
^
|
||
|
|
|
|
||
|
|
[BlockToConfig]
|
||
|
|
|
|
||
|
|
MAIN_FORM_STATE -- binary representation of form/widget
|
||
|
|
^ state
|
||
|
|
|
|
||
|
|
[PlatformConfigToFormState]
|
||
|
|
|
|
||
|
|
PLATFORM_CONFIG -- accessible to DXE and UEFI drivers
|
||
|
|
^
|
||
|
|
|
|
||
|
|
[PlatformConfigLoad]
|
||
|
|
|
|
||
|
|
UEFI non-volatile variable -- accessible to external utilities
|
||
|
|
|
||
|
|
The layers are very similar for the reverse direction, ie. when taking
|
||
|
|
input from the user, and saving the configuration (RouteConfig() HII
|
||
|
|
callback):
|
||
|
|
|
||
|
|
ConfigResp -- form engine / HII communication
|
||
|
|
|
|
||
|
|
[ConfigToBlock]
|
||
|
|
|
|
||
|
|
v
|
||
|
|
MAIN_FORM_STATE -- binary representation of form/widget
|
||
|
|
| state
|
||
|
|
[FormStateToPlatformConfig]
|
||
|
|
|
|
||
|
|
v
|
||
|
|
PLATFORM_CONFIG -- accessible to DXE and UEFI drivers
|
||
|
|
|
|
||
|
|
[PlatformConfigSave]
|
||
|
|
|
|
||
|
|
v
|
||
|
|
UEFI non-volatile variable -- accessible to external utilities
|
||
|
|
|
||
|
|
(3) When the platform driver starts, a GOP may not be available yet. Thus the
|
||
|
|
driver entry point registers a callback (the GopInstalled() function) for
|
||
|
|
GOP installations.
|
||
|
|
|
||
|
|
When the first GOP is produced (usually by QemuVideoDxe, or potentially by
|
||
|
|
a third party video driver), PlatformDxe retrieves the list of graphics
|
||
|
|
modes the GOP supports, and dynamically populates the drop-down list of
|
||
|
|
available resolutions on the form. The GOP installation callback is then
|
||
|
|
removed.
|
||
|
|
|
||
|
|
Video driver
|
||
|
|
............
|
||
|
|
|
||
|
|
OvmfPkg/QemuVideoDxe is OVMF's built-in video driver. We can divide its
|
||
|
|
services in two parts: graphics output protocol (primary), and Int10h (VBE)
|
||
|
|
shim (secondary).
|
||
|
|
|
||
|
|
(1) QemuVideoDxe conforms to the UEFI Driver Model; it produces an instance of
|
||
|
|
the EFI_GRAPHICS_OUTPUT_PROTOCOL (GOP) on each PCI display that it supports
|
||
|
|
and is connected to:
|
||
|
|
|
||
|
|
EFI_GRAPHICS_OUTPUT_PROTOCOL
|
||
|
|
[OvmfPkg/QemuVideoDxe]
|
||
|
|
|
|
||
|
|
EFI_PCI_IO_PROTOCOL
|
||
|
|
[MdeModulePkg/Bus/Pci/PciBusDxe]
|
||
|
|
|
||
|
|
It supports the following QEMU video cards:
|
||
|
|
|
||
|
|
- Cirrus 5430 ("-device cirrus-vga"),
|
||
|
|
- Standard VGA ("-device VGA"),
|
||
|
|
- QXL VGA ("-device qxl-vga", "-device qxl").
|
||
|
|
|
||
|
|
For Cirrus the following resolutions and color depths are available:
|
||
|
|
640x480x32, 800x600x32, 1024x768x24. On stdvga and QXL a long list of
|
||
|
|
resolutions is available. The list is filtered against the frame buffer
|
||
|
|
size during initialization.
|
||
|
|
|
||
|
|
The size of the QXL VGA compatibility framebuffer can be changed with the
|
||
|
|
|
||
|
|
-device qxl-vga,vgamem_mb=$NUM_MB
|
||
|
|
|
||
|
|
QEMU option. If $NUM_MB exceeds 32, then the following is necessary
|
||
|
|
instead:
|
||
|
|
|
||
|
|
-device qxl-vga,vgamem_mb=$NUM_MB,ram_size_mb=$((NUM_MB*2))
|
||
|
|
|
||
|
|
because the compatibility framebuffer can't cover more than half of PCI BAR
|
||
|
|
#0. The latter defaults to 64MB in size, and is controlled by the
|
||
|
|
"ram_size_mb" property.
|
||
|
|
|
||
|
|
(2) When QemuVideoDxe binds the first Standard VGA or QXL VGA device, and there
|
||
|
|
is no real VGA BIOS present in the C to F segments (which could originate
|
||
|
|
from a legacy PCI option ROM -- refer to "Compatibility Support Module
|
||
|
|
(CSM)"), then QemuVideoDxe installs a minimal, "fake" VGA BIOS -- an Int10h
|
||
|
|
(VBE) "shim".
|
||
|
|
|
||
|
|
The shim is implemented in 16-bit assembly in
|
||
|
|
"OvmfPkg/QemuVideoDxe/VbeShim.asm". The "VbeShim.sh" shell script assembles
|
||
|
|
it and formats it as a C array ("VbeShim.h") with the help of the "nasm"
|
||
|
|
utility. The driver's InstallVbeShim() function copies the shim in place
|
||
|
|
(the C segment), and fills in the VBE Info and VBE Mode Info structures.
|
||
|
|
The real-mode 10h interrupt vector is pointed to the shim's handler.
|
||
|
|
|
||
|
|
The shim is (correctly) irrelevant and invisible for all UEFI operating
|
||
|
|
systems we know about -- except Windows Server 2008 R2 and other Windows
|
||
|
|
operating systems in that family.
|
||
|
|
|
||
|
|
Namely, the Windows 2008 R2 SP1 (and Windows 7) UEFI guest's default video
|
||
|
|
driver dereferences the real mode Int10h vector, loads the pointed-to
|
||
|
|
handler code, and executes what it thinks to be VGA BIOS services in an
|
||
|
|
internal real-mode emulator. Consequently, video mode switching used not to
|
||
|
|
work in Windows 2008 R2 SP1 when it ran on the "pure UEFI" build of OVMF,
|
||
|
|
making the guest uninstallable. Hence the (otherwise optional, non-default)
|
||
|
|
Compatibility Support Module (CSM) ended up a requirement for running such
|
||
|
|
guests.
|
||
|
|
|
||
|
|
The hard dependency on the sophisticated SeaBIOS CSM and the complex
|
||
|
|
supporting edk2 infrastructure, for enabling this family of guests, was
|
||
|
|
considered suboptimal by some members of the upstream community,
|
||
|
|
|
||
|
|
[RHEL] and was certainly considered a serious maintenance disadvantage for
|
||
|
|
Red Hat Enterprise Linux 7.1 hosts.
|
||
|
|
|
||
|
|
Thus, the shim has been collaboratively developed for the Windows 7 /
|
||
|
|
Windows Server 2008 R2 family. The shim provides a real stdvga / QXL
|
||
|
|
implementation for the few services that are in fact necessary for the
|
||
|
|
Windows 2008 R2 SP1 (and Windows 7) UEFI guest, plus some "fakes" that the
|
||
|
|
guest invokes but whose effect is not important. The only supported mode is
|
||
|
|
1024x768x32, which is enough to install the guest and then upgrade its
|
||
|
|
video driver to the full-featured QXL XDDM one.
|
||
|
|
|
||
|
|
The C segment is not present in the UEFI memory map prepared by OVMF.
|
||
|
|
Memory space that would cover it is never added (either in PEI, in the form
|
||
|
|
of memory resource descriptor HOBs, or in DXE, via gDS->AddMemorySpace()).
|
||
|
|
This way the handler body is invisible to all other UEFI guests, and the
|
||
|
|
rest of edk2.
|
||
|
|
|
||
|
|
The Int10h real-mode IVT entry is covered with a Boot Services Code page,
|
||
|
|
making that too inaccessible to the rest of edk2. Due to the allocation
|
||
|
|
type, UEFI guest OSes different from the Windows Server 2008 family can
|
||
|
|
reclaim the page at zero. (The Windows 2008 family accesses that page
|
||
|
|
regardless of the allocation type.)
|
||
|
|
|
||
|
|
Afterword
|
||
|
|
---------
|
||
|
|
|
||
|
|
After the bulk of this document was written in July 2014, OVMF development has
|
||
|
|
not stopped. To name two significant code contributions from the community: in
|
||
|
|
January 2015, OVMF runs on the "q35" machine type of QEMU, and it features a
|
||
|
|
driver for Xen paravirtual block devices (and another for the underlying Xen
|
||
|
|
bus).
|
||
|
|
|
||
|
|
Furthermore, a dedicated virtualization platform has been contributed to
|
||
|
|
ArmPlatformPkg that plays a role parallel to OvmfPkg's. It targets the "virt"
|
||
|
|
machine type of qemu-system-arm and qemu-system-aarch64. Parts of OvmfPkg are
|
||
|
|
being refactored and modularized so they can be reused in
|
||
|
|
"ArmPlatformPkg/ArmVirtualizationPkg/ArmVirtualizationQemu.dsc".
|