260 lines
11 KiB
Plaintext
260 lines
11 KiB
Plaintext
|
|
||
|
|
=== OVMF OVERVIEW ===
|
||
|
|
|
||
|
|
The Open Virtual Machine Firmware (OVMF) project aims
|
||
|
|
to support firmware for Virtual Machines using the edk2
|
||
|
|
code base. More information can be found at:
|
||
|
|
|
||
|
|
http://www.tianocore.org/ovmf/
|
||
|
|
|
||
|
|
=== STATUS ===
|
||
|
|
|
||
|
|
Current capabilities:
|
||
|
|
* IA32 and X64 architectures
|
||
|
|
* QEMU (0.10.0 or later)
|
||
|
|
- Video, keyboard, IDE, CD-ROM, serial
|
||
|
|
- Runs UEFI shell
|
||
|
|
- Optional NIC support. Requires QEMU (0.12.2 or later)
|
||
|
|
* UEFI Linux boots
|
||
|
|
* UEFI Windows 8 boots
|
||
|
|
* UEFI Windows 7 & Windows 2008 Server boot (see important notes below!)
|
||
|
|
|
||
|
|
=== FUTURE PLANS ===
|
||
|
|
|
||
|
|
* Test/Stabilize UEFI Self-Certification Tests (SCT) results
|
||
|
|
|
||
|
|
=== BUILDING OVMF ===
|
||
|
|
|
||
|
|
Pre-requisites:
|
||
|
|
* Build environment capable of build the edk2 MdeModulePkg.
|
||
|
|
* A properly configured ASL compiler:
|
||
|
|
- Intel ASL compiler: Available from http://www.acpica.org
|
||
|
|
- Microsoft ASL compiler: Available from http://www.acpi.info
|
||
|
|
* NASM: http://www.nasm.us/
|
||
|
|
|
||
|
|
Update Conf/target.txt ACTIVE_PLATFORM for OVMF:
|
||
|
|
PEI arch DXE arch UEFI interfaces
|
||
|
|
* OvmfPkg/OvmfPkgIa32.dsc IA32 IA32 IA32
|
||
|
|
* OvmfPkg/OvmfPkgIa32X64.dsc IA32 X64 X64
|
||
|
|
* OvmfPkg/OvmfPkgX64.dsc X64 X64 X64
|
||
|
|
|
||
|
|
Update Conf/target.txt TARGET_ARCH based on the .dsc file:
|
||
|
|
TARGET_ARCH
|
||
|
|
* OvmfPkg/OvmfPkgIa32.dsc IA32
|
||
|
|
* OvmfPkg/OvmfPkgIa32X64.dsc IA32 X64
|
||
|
|
* OvmfPkg/OvmfPkgX64.dsc X64
|
||
|
|
|
||
|
|
Following the edk2 build process, you will find the OVMF binaries
|
||
|
|
under the $WORKSPACE/Build/*/*/FV directory. The actual path will
|
||
|
|
depend on how your build is configured. You can expect to find
|
||
|
|
these binary outputs:
|
||
|
|
* OVMF.FD
|
||
|
|
- Please note! This filename has changed. Older releases used OVMF.Fv.
|
||
|
|
* OvmfVideo.rom
|
||
|
|
- This file is not built separately any longer, starting with svn r13520.
|
||
|
|
|
||
|
|
More information on building OVMF can be found at:
|
||
|
|
|
||
|
|
https://github.com/tianocore/tianocore.github.io/wiki/How%20to%20build%20OVMF
|
||
|
|
|
||
|
|
=== RUNNING OVMF on QEMU ===
|
||
|
|
|
||
|
|
* QEMU 0.12.2 or later is required.
|
||
|
|
* Be sure to use qemu-system-x86_64, if you are using and X64 firmware.
|
||
|
|
(qemu-system-x86_64 works for the IA32 firmware as well, of course.)
|
||
|
|
* Use OVMF for QEMU firmware (3 options available)
|
||
|
|
- Option 1: QEMU 1.6 or newer; Use QEMU -pflash parameter
|
||
|
|
* QEMU/OVMF will use emulated flash, and fully support UEFI variables
|
||
|
|
* Run qemu with: -pflash path/to/OVMF.fd
|
||
|
|
* Note that this option is required for running SecureBoot-enabled builds
|
||
|
|
(-D SECURE_BOOT_ENABLE).
|
||
|
|
- Option 2: Use QEMU -bios parameter
|
||
|
|
* Note that UEFI variables will be partially emulated, and non-volatile
|
||
|
|
variables may lose their contents after a reboot
|
||
|
|
* Run qemu with: -bios path/to/OVMF.fd
|
||
|
|
- Option 3: Use QEMU -L parameter
|
||
|
|
* Note that UEFI variables will be partially emulated, and non-volatile
|
||
|
|
variables may lose their contents after a reboot
|
||
|
|
* Either copy, rename or symlink OVMF.fd => bios.bin
|
||
|
|
* Use the QEMU -L parameter to specify the directory where the bios.bin
|
||
|
|
file is located.
|
||
|
|
* The EFI shell is built into OVMF builds at this time, so it should
|
||
|
|
run automatically if a UEFI boot application is not found on the
|
||
|
|
removable media.
|
||
|
|
* On Linux, newer version of QEMU may enable KVM feature, and this might
|
||
|
|
cause OVMF to fail to boot. The QEMU '-no-kvm' may allow OVMF to boot.
|
||
|
|
* Capturing OVMF debug messages on qemu:
|
||
|
|
- The default OVMF build writes debug messages to IO port 0x402. The
|
||
|
|
following qemu command line options save them in the file called
|
||
|
|
debug.log: '-debugcon file:debug.log -global isa-debugcon.iobase=0x402'.
|
||
|
|
- It is possible to revert to the original behavior, when debug messages were
|
||
|
|
written to the emulated serial port (potentially intermixing OVMF debug
|
||
|
|
output with UEFI serial console output). For this the
|
||
|
|
'-D DEBUG_ON_SERIAL_PORT' option has to be passed to the build command (see
|
||
|
|
the next section), and in order to capture the serial output qemu needs to
|
||
|
|
be started with eg. '-serial file:serial.log'.
|
||
|
|
- Debug messages fall into several categories. Logged vs. suppressed
|
||
|
|
categories are controlled at OVMF build time by the
|
||
|
|
'gEfiMdePkgTokenSpaceGuid.PcdDebugPrintErrorLevel' bitmask (an UINT32
|
||
|
|
value) in the selected .dsc file. Individual bits of this bitmask are
|
||
|
|
defined in <MdePkg/Include/Library/DebugLib.h>. One non-default bit (with
|
||
|
|
some performance impact) that is frequently set for debugging is 0x00400000
|
||
|
|
(DEBUG_VERBOSE).
|
||
|
|
- The RELEASE build target ('-b RELEASE' build option, see below) disables
|
||
|
|
all debug messages. The default build target is DEBUG.
|
||
|
|
|
||
|
|
=== Build Scripts ===
|
||
|
|
|
||
|
|
On systems with the bash shell you can use OvmfPkg/build.sh to simplify
|
||
|
|
building and running OVMF.
|
||
|
|
|
||
|
|
So, for example, to build + run OVMF X64:
|
||
|
|
$ OvmfPkg/build.sh -a X64
|
||
|
|
$ OvmfPkg/build.sh -a X64 qemu
|
||
|
|
|
||
|
|
And to run a 64-bit UEFI bootable ISO image:
|
||
|
|
$ OvmfPkg/build.sh -a X64 qemu -cdrom /path/to/disk-image.iso
|
||
|
|
|
||
|
|
To build a 32-bit OVMF without debug messages using GCC 4.5:
|
||
|
|
$ OvmfPkg/build.sh -a IA32 -b RELEASE -t GCC45
|
||
|
|
|
||
|
|
=== Network Support ===
|
||
|
|
|
||
|
|
OVMF provides a UEFI network stack by default. Its lowest level driver is the
|
||
|
|
NIC driver, higher levels are generic. In order to make DHCP, PXE Boot, and eg.
|
||
|
|
socket test utilities from the StdLib edk2 package work, (1) qemu has to be
|
||
|
|
configured to emulate a NIC, (2) a matching UEFI NIC driver must be available
|
||
|
|
when OVMF boots.
|
||
|
|
|
||
|
|
(If a NIC is configured for the virtual machine, and -- dependent on boot order
|
||
|
|
-- PXE booting is attempted, but no DHCP server responds to OVMF's DHCP
|
||
|
|
DISCOVER message at startup, the boot process may take approx. 3 seconds
|
||
|
|
longer.)
|
||
|
|
|
||
|
|
* For each NIC emulated by qemu, a GPLv2 licensed UEFI driver is available from
|
||
|
|
the iPXE project. The qemu source distribution, starting with version 1.5,
|
||
|
|
contains prebuilt binaries of these drivers (and of course allows one to
|
||
|
|
rebuild them from source as well). This is the recommended set of drivers.
|
||
|
|
|
||
|
|
* Use the qemu -netdev and -device options, or the legacy -net option, to
|
||
|
|
enable NIC support: <http://wiki.qemu.org/Documentation/Networking>.
|
||
|
|
|
||
|
|
* For a qemu >= 1.5 binary running *without* any "-M machine" option where
|
||
|
|
"machine" would identify a < qemu-1.5 configuration (for example: "-M
|
||
|
|
pc-i440fx-1.4" or "-M pc-0.13"), the iPXE drivers are automatically available
|
||
|
|
to and configured for OVMF in the default qemu installation.
|
||
|
|
|
||
|
|
* For a qemu binary in [0.13, 1.5), or a qemu >= 1.5 binary with an "-M
|
||
|
|
machine" option where "machine" selects a < qemu-1.5 configuration:
|
||
|
|
|
||
|
|
- download a >= 1.5.0-rc1 source tarball from <http://wiki.qemu.org/Download>,
|
||
|
|
|
||
|
|
- extract the following iPXE driver files from the tarball and install them
|
||
|
|
in a location that is accessible to qemu processes (this may depend on your
|
||
|
|
SELinux configuration, for example):
|
||
|
|
|
||
|
|
qemu-VERSION/pc-bios/efi-e1000.rom
|
||
|
|
qemu-VERSION/pc-bios/efi-ne2k_pci.rom
|
||
|
|
qemu-VERSION/pc-bios/efi-pcnet.rom
|
||
|
|
qemu-VERSION/pc-bios/efi-rtl8139.rom
|
||
|
|
qemu-VERSION/pc-bios/efi-virtio.rom
|
||
|
|
|
||
|
|
- extend the NIC's -device option on the qemu command line with a matching
|
||
|
|
"romfile=" optarg:
|
||
|
|
|
||
|
|
-device e1000,...,romfile=/full/path/to/efi-e1000.rom
|
||
|
|
-device ne2k_pci,...,romfile=/full/path/to/efi-ne2k_pci.rom
|
||
|
|
-device pcnet,...,romfile=/full/path/to/efi-pcnet.rom
|
||
|
|
-device rtl8139,...,romfile=/full/path/to/efi-rtl8139.rom
|
||
|
|
-device virtio-net-pci,...,romfile=/full/path/to/efi-virtio.rom
|
||
|
|
|
||
|
|
* Independently of the iPXE NIC drivers, the default OVMF build provides a
|
||
|
|
basic virtio-net driver, located in OvmfPkg/VirtioNetDxe.
|
||
|
|
|
||
|
|
* Also independently of the iPXE NIC drivers, Intel's proprietary E1000 NIC
|
||
|
|
driver (PROEFI) can be embedded in the OVMF image at build time:
|
||
|
|
|
||
|
|
- Download UEFI drivers for the e1000 NIC
|
||
|
|
- http://downloadcenter.intel.com/Detail_Desc.aspx?agr=Y&DwnldID=17515&lang=eng
|
||
|
|
- Install the drivers into a directory called Intel3.5 in your WORKSPACE.
|
||
|
|
|
||
|
|
- Include the driver in OVMF during the build:
|
||
|
|
- Add "-D E1000_ENABLE -D FD_SIZE_2MB" to your build command,
|
||
|
|
- For example: "build -D E1000_ENABLE -D FD_SIZE_2MB".
|
||
|
|
|
||
|
|
* When a matching iPXE driver is configured for a NIC as described above, it
|
||
|
|
takes priority over other drivers that could possibly drive the card too:
|
||
|
|
|
||
|
|
| e1000 ne2k_pci pcnet rtl8139 virtio-net-pci
|
||
|
|
-------------+------------------------------------------------
|
||
|
|
iPXE | x x x x x
|
||
|
|
VirtioNetDxe | x
|
||
|
|
Intel PROEFI | x
|
||
|
|
|
||
|
|
=== OVMF Flash Layout ===
|
||
|
|
|
||
|
|
Like all current IA32/X64 system designs, OVMF's firmware
|
||
|
|
device (rom/flash) appears in QEMU's physical address space
|
||
|
|
just below 4GB (0x100000000).
|
||
|
|
|
||
|
|
The layout of the firmware device in memory looks like:
|
||
|
|
|
||
|
|
+--------------------------------------- 4GB (0x100000000)
|
||
|
|
| VTF0 (16-bit reset code) and OVMF SEC
|
||
|
|
| (SECFV)
|
||
|
|
+--------------------------------------- varies based on flash size
|
||
|
|
|
|
||
|
|
| Compressed main firmware image
|
||
|
|
| (FVMAIN_COMPACT)
|
||
|
|
|
|
||
|
|
+--------------------------------------- base + 0x20000
|
||
|
|
| Fault-tolerant write (FTW)
|
||
|
|
| Spare blocks (64KB/0x10000)
|
||
|
|
+--------------------------------------- base + 0x10000
|
||
|
|
| FTW Work block (4KB/0x1000)
|
||
|
|
+--------------------------------------- base + 0x0f000
|
||
|
|
| Event log area (4KB/0x1000)
|
||
|
|
+--------------------------------------- base + 0x0e000
|
||
|
|
| Non-volatile variable storage
|
||
|
|
| area (56KB/0xe000)
|
||
|
|
+--------------------------------------- base address
|
||
|
|
|
||
|
|
OVMF supports building a 1MB or a 2MB flash image. The base address for
|
||
|
|
a 1MB image in QEMU physical memory is 0xfff00000. The base address for
|
||
|
|
a 2MB image is 0xffe00000.
|
||
|
|
|
||
|
|
The code in SECFV locates FVMAIN_COMPACT, and decompresses the
|
||
|
|
main firmware (MAINFV) into RAM memory at address 0x800000. The
|
||
|
|
remaining OVMF firmware then uses this decompressed firmware
|
||
|
|
volume image.
|
||
|
|
|
||
|
|
=== UNIXGCC Debug ===
|
||
|
|
|
||
|
|
If you build with the UNIXGCC toolchain, then debugging will be disabled
|
||
|
|
due to larger image sizes being produced by the UNIXGCC toolchain. The
|
||
|
|
first choice recommendation is to use GCC44 or newer instead.
|
||
|
|
|
||
|
|
If you must use UNIXGCC, then you can override the build options for
|
||
|
|
particular libraries and modules in the .dsc to re-enable debugging
|
||
|
|
selectively. For example:
|
||
|
|
[Components]
|
||
|
|
OvmfPkg/Library/PlatformBdsLib/PlatformBdsLib.inf {
|
||
|
|
<BuildOptions>
|
||
|
|
GCC:*_*_*_CC_FLAGS = -UMDEPKG_NDEBUG
|
||
|
|
}
|
||
|
|
IntelFrameworkModulePkg/Universal/BdsDxe/BdsDxe.inf {
|
||
|
|
<BuildOptions>
|
||
|
|
GCC:*_*_*_CC_FLAGS = -UMDEPKG_NDEBUG
|
||
|
|
}
|
||
|
|
|
||
|
|
=== UEFI Windows 7 & Windows 2008 Server ===
|
||
|
|
|
||
|
|
* One of the '-vga std' and '-vga qxl' QEMU options should be used.
|
||
|
|
* Only one video mode, 1024x768x32, is supported at OS runtime.
|
||
|
|
* The '-vga qxl' QEMU option is recommended. After booting the installed
|
||
|
|
guest OS, select the video card in Device Manager, and upgrade its driver
|
||
|
|
to the QXL XDDM one. Download location:
|
||
|
|
<http://www.spice-space.org/download.html>, Guest | Windows binaries.
|
||
|
|
This enables further resolutions at OS runtime, and provides S3
|
||
|
|
(suspend/resume) capability.
|