path: root/ovmf-whitepaper-c770f8c.txt

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".