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