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  --+            |