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