OvmfPkg/README

   1
   2 === OVMF OVERVIEW ===
   3
   4 The Open Virtual Machine Firmware (OVMF) project aims
   5 to support firmware for Virtual Machines using the edk2
   6 code base.  More information can be found at:
   7
   8 http://www.tianocore.org/ovmf/
   9
  10 === STATUS ===
  11
  12 Current capabilities:
  13 * IA32 and X64 architectures
  14 * QEMU (version 1.7.1 or later, with 1.7 or later machine types)
  15   - Video, keyboard, IDE, CD-ROM, serial
  16   - Runs UEFI shell
  17   - Optional NIC support.
  18 * UEFI Linux boots
  19 * UEFI Windows 8 boots
  20 * UEFI Windows 7 & Windows 2008 Server boot (see important notes below!)
  21
  22 === FUTURE PLANS ===
  23
  24 * Test/Stabilize UEFI Self-Certification Tests (SCT) results
  25
  26 === BUILDING OVMF ===
  27
  28 Pre-requisites:
  29 * Build environment capable of build the edk2 MdeModulePkg.
  30 * A properly configured ASL compiler:
  31   - Intel ASL compiler: Available from http://www.acpica.org
  32   - Microsoft ASL compiler: Available from http://www.acpi.info
  33 * NASM: http://www.nasm.us/
  34
  35 Update Conf/target.txt ACTIVE_PLATFORM for OVMF:
  36                              PEI arch   DXE arch   UEFI interfaces
  37 * OvmfPkg/OvmfPkgIa32.dsc      IA32       IA32           IA32
  38 * OvmfPkg/OvmfPkgIa32X64.dsc   IA32       X64            X64
  39 * OvmfPkg/OvmfPkgX64.dsc       X64        X64            X64
  40
  41 Update Conf/target.txt TARGET_ARCH based on the .dsc file:
  42                              TARGET_ARCH
  43 * OvmfPkg/OvmfPkgIa32.dsc     IA32
  44 * OvmfPkg/OvmfPkgIa32X64.dsc  IA32 X64
  45 * OvmfPkg/OvmfPkgX64.dsc      X64
  46
  47 Following the edk2 build process, you will find the OVMF binaries
  48 under the $WORKSPACE/Build/*/*/FV directory.  The actual path will
  49 depend on how your build is configured.  You can expect to find
  50 these binary outputs:
  51 * OVMF.FD
  52   - Please note!  This filename has changed.  Older releases used OVMF.Fv.
  53 * OvmfVideo.rom
  54   - This file is not built separately any longer, starting with svn r13520.
  55
  56 If you are new to building in edk2 or looking for the latest build
  57 instructions, visit https://github.com/tianocore/tianocore.github.io/wiki/Build-Instructions
  58
  59 More OVMF-specific build information can be found at:
  60
  61 https://github.com/tianocore/tianocore.github.io/wiki/How%20to%20build%20OVMF
  62
  63 === RUNNING OVMF on QEMU ===
  64
  65 * Be sure to use qemu-system-x86_64, if you are using an X64 firmware.
  66   (qemu-system-x86_64 works for the IA32 firmware as well, of course.)
  67 * Use OVMF for QEMU firmware (3 options available)
  68   - Option 1: Use QEMU -pflash parameter
  69     * QEMU/OVMF will use emulated flash, and fully support UEFI variables
  70     * Run qemu with: -pflash path/to/OVMF.fd
  71     * Note that this option is required for running SecureBoot-enabled builds
  72       (-D SECURE_BOOT_ENABLE).
  73   - Option 2: Use QEMU -bios parameter
  74     * Note that UEFI variables will be partially emulated, and non-volatile
  75       variables may lose their contents after a reboot
  76     * Run qemu with: -bios path/to/OVMF.fd
  77   - Option 3: Use QEMU -L parameter
  78     * Note that UEFI variables will be partially emulated, and non-volatile
  79       variables may lose their contents after a reboot
  80     * Either copy, rename or symlink OVMF.fd => bios.bin
  81     * Use the QEMU -L parameter to specify the directory where the bios.bin
  82       file is located.
  83 * The EFI shell is built into OVMF builds at this time, so it should
  84   run automatically if a UEFI boot application is not found on the
  85   removable media.
  86 * On Linux, newer version of QEMU may enable KVM feature, and this might
  87   cause OVMF to fail to boot.  The QEMU '-no-kvm' may allow OVMF to boot.
  88 * Capturing OVMF debug messages on qemu:
  89   - The default OVMF build writes debug messages to IO port 0x402.  The
  90     following qemu command line options save them in the file called
  91     debug.log: '-debugcon file:debug.log -global isa-debugcon.iobase=0x402'.
  92   - It is possible to revert to the original behavior, when debug messages were
  93     written to the emulated serial port (potentially intermixing OVMF debug
  94     output with UEFI serial console output).  For this the
  95     '-D DEBUG_ON_SERIAL_PORT' option has to be passed to the build command (see
  96     the next section), and in order to capture the serial output qemu needs to
  97     be started with eg. '-serial file:serial.log'.
  98   - Debug messages fall into several categories.  Logged vs. suppressed
  99     categories are controlled at OVMF build time by the
 100     'gEfiMdePkgTokenSpaceGuid.PcdDebugPrintErrorLevel' bitmask (an UINT32
 101     value) in the selected .dsc file.  Individual bits of this bitmask are
 102     defined in <MdePkg/Include/Library/DebugLib.h>.  One non-default bit (with
 103     some performance impact) that is frequently set for debugging is 0x00400000
 104     (DEBUG_VERBOSE).
 105   - The RELEASE build target ('-b RELEASE' build option, see below) disables
 106     all debug messages.  The default build target is DEBUG.
 107
 108 === Build Scripts ===
 109
 110 On systems with the bash shell you can use OvmfPkg/build.sh to simplify
 111 building and running OVMF.
 112
 113 So, for example, to build + run OVMF X64:
 114 $ OvmfPkg/build.sh -a X64
 115 $ OvmfPkg/build.sh -a X64 qemu
 116
 117 And to run a 64-bit UEFI bootable ISO image:
 118 $ OvmfPkg/build.sh -a X64 qemu -cdrom /path/to/disk-image.iso
 119
 120 To build a 32-bit OVMF without debug messages using GCC 4.8:
 121 $ OvmfPkg/build.sh -a IA32 -b RELEASE -t GCC48
 122
 123 === SMM support ===
 124
 125 Requirements:
 126 * SMM support requires QEMU 2.5.
 127 * The minimum required QEMU machine type is "pc-q35-2.5".
 128 * SMM with KVM requires Linux 4.4 (host).
 129
 130 OVMF is capable of utilizing SMM if the underlying QEMU or KVM hypervisor
 131 emulates SMM. SMM is put to use in the S3 suspend and resume infrastructure,
 132 and in the UEFI variable driver stack. The purpose is (virtual) hardware
 133 separation between the runtime guest OS and the firmware (OVMF), with the
 134 intent to make Secure Boot actually secure, by preventing the runtime guest OS
 135 from tampering with the variable store and S3 areas.
 136
 137 For SMM support, OVMF must be built with the "-D SMM_REQUIRE" option. The
 138 resultant firmware binary will check if QEMU actually provides SMM emulation;
 139 if it doesn't, then OVMF will log an error and trigger an assertion failure
 140 during boot (even in RELEASE builds). Both the naming of the flag (SMM_REQUIRE,
 141 instead of SMM_ENABLE), and this behavior are consistent with the goal
 142 described above: this is supposed to be a security feature, and fallbacks are
 143 not allowed. Similarly, a pflash-backed variable store is a requirement.
 144
 145 QEMU should be started with the options listed below (in addition to any other
 146 guest-specific flags). The command line should be gradually composed from the
 147 hints below. '\' is used to extend the command line to multiple lines, and '^'
 148 can be used on Windows.
 149
 150 * QEMU binary and options specific to 32-bit guests:
 151
 152   $ qemu-system-i386 -cpu coreduo,-nx \
 153
 154   or
 155
 156   $ qemu-system-x86_64 -cpu <MODEL>,-lm,-nx \
 157
 158 * QEMU binary for running 64-bit guests (no particular options):
 159
 160   $ qemu-system-x86_64 \
 161
 162 * Flags common to all SMM scenarios (only the Q35 machine type is supported):
 163
 164   -machine q35,smm=on,accel=(tcg|kvm) \
 165   -m ... \
 166   -smp ... \
 167   -global driver=cfi.pflash01,property=secure,value=on \
 168   -drive if=pflash,format=raw,unit=0,file=OVMF_CODE.fd,readonly=on \
 169   -drive if=pflash,format=raw,unit=1,file=copy_of_OVMF_VARS.fd \
 170
 171 * In order to disable S3, add:
 172
 173   -global ICH9-LPC.disable_s3=1 \
 174
 175 === Network Support ===
 176
 177 OVMF provides a UEFI network stack by default. Its lowest level driver is the
 178 NIC driver, higher levels are generic. In order to make DHCP, PXE Boot, and eg.
 179 socket test utilities from the StdLib edk2 package work, (1) qemu has to be
 180 configured to emulate a NIC, (2) a matching UEFI NIC driver must be available
 181 when OVMF boots.
 182
 183 (If a NIC is configured for the virtual machine, and -- dependent on boot order
 184 -- PXE booting is attempted, but no DHCP server responds to OVMF's DHCP
 185 DISCOVER message at startup, the boot process may take approx. 3 seconds
 186 longer.)
 187
 188 * For each NIC emulated by qemu, a GPLv2 licensed UEFI driver is available from
 189   the iPXE project. The qemu source distribution contains prebuilt binaries of
 190   these drivers (and of course allows one to rebuild them from source as well).
 191   This is the recommended set of drivers.
 192
 193 * Use the qemu -netdev and -device options, or the legacy -net option, to
 194   enable NIC support: <http://wiki.qemu.org/Documentation/Networking>.
 195
 196 * The iPXE drivers are automatically available to and configured for OVMF in
 197   the default qemu installation.
 198
 199 * Independently of the iPXE NIC drivers, the default OVMF build provides a
 200   basic virtio-net driver, located in OvmfPkg/VirtioNetDxe.
 201
 202 * Also independently of the iPXE NIC drivers, Intel's proprietary E1000 NIC
 203   driver (from the BootUtil distribution) can be embedded in the OVMF image at
 204   build time:
 205
 206   - Download BootUtil:
 207     - Navigate to
 208       https://downloadcenter.intel.com/download/19186/Ethernet-Intel-Ethernet-Connections-Boot-Utility-Preboot-Images-and-EFI-Drivers
 209     - Click the download link for "PREBOOT.EXE".
 210     - Accept the Intel Software License Agreement that appears.
 211     - Unzip "PREBOOT.EXE" into a separate directory (this works with the
 212       "unzip" utility on platforms different from Windows as well).
 213     - Copy the "APPS/EFI/EFIx64/E3522X2.EFI" driver binary to
 214       "Intel3.5/EFIX64/E3522X2.EFI" in your WORKSPACE.
 215     - Intel have stopped distributing an IA32 driver binary (which used to
 216       match the filename pattern "E35??E2.EFI"), thus this method will only
 217       work for the IA32X64 and X64 builds of OVMF.
 218
 219   - Include the driver in OVMF during the build:
 220     - Add "-D E1000_ENABLE" to your build command (only when building
 221       "OvmfPkg/OvmfPkgIa32X64.dsc" or "OvmfPkg/OvmfPkgX64.dsc").
 222     - For example: "build -D E1000_ENABLE".
 223
 224 * When a matching iPXE driver is configured for a NIC as described above, it
 225   takes priority over other drivers that could possibly drive the card too:
 226
 227                          | e1000  ne2k_pci  pcnet  rtl8139  virtio-net-pci
 228     ---------------------+------------------------------------------------
 229     iPXE                 |   x       x        x       x           x
 230     VirtioNetDxe         |                                        x
 231     Intel BootUtil (X64) |   x
 232
 233 === HTTPS Boot ===
 234
 235 HTTPS Boot is an alternative solution to PXE. It replaces the tftp server
 236 with a HTTPS server so the firmware can download the images through a trusted
 237 and encrypted connection.
 238
 239 * To enable HTTPS Boot, you have to build OVMF with -D NETWORK_HTTP_BOOT_ENABLE
 240   and -D NETWORK_TLS_ENABLE. The former brings in the HTTP stack from
 241   NetworkPkg while the latter enables TLS support in both NetworkPkg and
 242   CryptoPkg.
 243
 244   If you want to exclude the unsecured HTTP connection completely, OVMF has to
 245   be built with -D NETWORK_ALLOW_HTTP_CONNECTIONS=FALSE so that only the HTTPS
 246   connections will be accepted.
 247
 248 * By default, there is no trusted certificate. The user has to import the
 249   certificates either manually with "Tls Auth Configuration" utility in the
 250   firmware UI or through the fw_cfg entry, etc/edk2/https/cacerts.
 251
 252   -fw_cfg name=etc/edk2/https/cacerts,file=<certdb>
 253
 254   The blob for etc/edk2/https/cacerts has to be in the format of Signature
 255   Database(*1). You can use p11-kit(*2) or efisiglit(*3) to create the
 256   certificate list.
 257
 258   If you want to create the certificate list based on the CA certificates
 259   in your local host, p11-kit will be a good choice. Here is the command to
 260   create the list:
 261
 262   p11-kit extract --format=edk2-cacerts --filter=ca-anchors \
 263     --overwrite --purpose=server-auth <certdb>
 264
 265   If you only want to import one certificate, efisiglist is the tool for you:
 266
 267   efisiglist -a <cert file> -o <certdb>
 268
 269   Please note that the certificate has to be in the DER format.
 270
 271   You can also append a certificate to the existing list with the following
 272   command:
 273
 274   efisiglist -i <old certdb> -a <cert file> -o <new certdb>
 275
 276   NOTE: You may need the patch to make efisiglist generate the correct header.
 277   (https://github.com/rhboot/pesign/pull/40)
 278
 279 * Besides the trusted certificates, it's also possible to configure the trusted
 280   cipher suites for HTTPS through another fw_cfg entry: etc/edk2/https/ciphers.
 281
 282   OVMF expects a binary UINT16 array which comprises the cipher suites HEX
 283   IDs(*4). If the cipher suite list is given, OVMF will choose the cipher
 284   suite from the intersection of the given list and the built-in cipher
 285   suites. Otherwise, OVMF just chooses whatever proper cipher suites from the
 286   built-in ones.
 287
 288   - Using QEMU 5.2 or later, QEMU can expose the ordered list of permitted TLS
 289     cipher suites from the host side to OVMF:
 290
 291   -object tls-cipher-suites,id=mysuite0,priority=@SYSTEM \
 292   -fw_cfg name=etc/edk2/https/ciphers,gen_id=mysuite0
 293
 294   (Refer to the QEMU manual and to
 295   <https://gnutls.org/manual/html_node/Priority-Strings.html> for more
 296   information on the "priority" property.)
 297
 298   - Using QEMU 5.1 or earlier, the array has to be passed from a file:
 299
 300   -fw_cfg name=etc/edk2/https/ciphers,file=<cipher suites>
 301
 302   whose contents can be generated with the following script, for example:
 303
 304   export LC_ALL=C
 305   openssl ciphers -V \
 306   | sed -r -n \
 307      -e 's/^ *0x([0-9A-F]{2}),0x([0-9A-F]{2}) - .*$/\\\\x\1 \\\\x\2/p' \
 308   | xargs -r -- printf -- '%b' > ciphers.bin
 309
 310   This script creates ciphers.bin that contains all the cipher suite IDs
 311   supported by openssl according to the local host configuration.
 312
 313   You may want to enable only a limited set of cipher suites. Then, you
 314   should check the validity of your list first:
 315
 316   openssl ciphers -V <cipher list>
 317
 318   If all the cipher suites in your list map to the proper HEX IDs, go ahead
 319   to modify the script and execute it:
 320
 321   export LC_ALL=C
 322   openssl ciphers -V <cipher list> \
 323   | sed -r -n \
 324      -e 's/^ *0x([0-9A-F]{2}),0x([0-9A-F]{2}) - .*$/\\\\x\1 \\\\x\2/p' \
 325   | xargs -r -- printf -- '%b' > ciphers.bin
 326
 327 (*1) See "31.4.1 Signature Database" in UEFI specification 2.7 errata A.
 328 (*2) p11-kit: https://github.com/p11-glue/p11-kit/
 329 (*3) efisiglist: https://github.com/rhboot/pesign/blob/master/src/efisiglist.c
 330 (*4) https://wiki.mozilla.org/Security/Server_Side_TLS#Cipher_names_correspondence_table
 331
 332 === OVMF Flash Layout ===
 333
 334 Like all current IA32/X64 system designs, OVMF's firmware device (rom/flash)
 335 appears in QEMU's physical address space just below 4GB (0x100000000).
 336
 337 OVMF supports building a 1MB, 2MB or 4MB flash image (see the DSC files for the
 338 FD_SIZE_1MB, FD_SIZE_2MB, FD_SIZE_4MB build defines). The base address for the
 339 1MB image in QEMU physical memory is 0xfff00000. The base address for the 2MB
 340 image is 0xffe00000. The base address for the 4MB image is 0xffc00000.
 341
 342 Using the 1MB or 2MB image, the layout of the firmware device in memory looks
 343 like:
 344
 345 +--------------------------------------- 4GB (0x100000000)
 346 | VTF0 (16-bit reset code) and OVMF SEC
 347 | (SECFV, 208KB/0x34000)
 348 +--------------------------------------- varies based on flash size
 349 |
 350 | Compressed main firmware image
 351 | (FVMAIN_COMPACT)
 352 |
 353 +--------------------------------------- base + 0x20000
 354 | Fault-tolerant write (FTW)
 355 | Spare blocks (64KB/0x10000)
 356 +--------------------------------------- base + 0x10000
 357 | FTW Work block (4KB/0x1000)
 358 +--------------------------------------- base + 0x0f000
 359 | Event log area (4KB/0x1000)
 360 +--------------------------------------- base + 0x0e000
 361 | Non-volatile variable storage
 362 | area (56KB/0xe000)
 363 +--------------------------------------- base address
 364
 365 Using the 4MB image, the layout of the firmware device in memory looks like:
 366
 367 +--------------------------------------- base + 0x400000 (4GB/0x100000000)
 368 | VTF0 (16-bit reset code) and OVMF SEC
 369 | (SECFV, 208KB/0x34000)
 370 +--------------------------------------- base + 0x3cc000
 371 |
 372 | Compressed main firmware image
 373 | (FVMAIN_COMPACT, 3360KB/0x348000)
 374 |
 375 +--------------------------------------- base + 0x84000
 376 | Fault-tolerant write (FTW)
 377 | Spare blocks (264KB/0x42000)
 378 +--------------------------------------- base + 0x42000
 379 | FTW Work block (4KB/0x1000)
 380 +--------------------------------------- base + 0x41000
 381 | Event log area (4KB/0x1000)
 382 +--------------------------------------- base + 0x40000
 383 | Non-volatile variable storage
 384 | area (256KB/0x40000)
 385 +--------------------------------------- base address (0xffc00000)
 386
 387 The code in SECFV locates FVMAIN_COMPACT, and decompresses the
 388 main firmware (MAINFV) into RAM memory at address 0x800000. The
 389 remaining OVMF firmware then uses this decompressed firmware
 390 volume image.
 391
 392 === UEFI Windows 7 & Windows 2008 Server ===
 393
 394 * One of the '-vga std' and '-vga qxl' QEMU options should be used.
 395 * Only one video mode, 1024x768x32, is supported at OS runtime.
 396 * The '-vga qxl' QEMU option is recommended. After booting the installed
 397   guest OS, select the video card in Device Manager, and upgrade its driver
 398   to the QXL XDDM one. Download location:
 399   <http://www.spice-space.org/download.html>, Guest | Windows binaries.
 400   This enables further resolutions at OS runtime, and provides S3
 401   (suspend/resume) capability.