]>
Commit | Line | Data |
---|---|---|
49ba9447 | 1 | \r |
2 | === OVMF OVERVIEW ===\r | |
3 | \r | |
4 | The Open Virtual Machine Firmware (OVMF) project aims\r | |
5 | to support firmware for Virtual Machines using the edk2\r | |
6 | code base. More information can be found at:\r | |
7 | \r | |
c315da0a | 8 | http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=OVMF\r |
49ba9447 | 9 | \r |
10 | === STATUS ===\r | |
11 | \r | |
49ba9447 | 12 | Current capabilities:\r |
13 | * IA32 and X64 architectures\r | |
73f4a1c0 | 14 | * QEMU (0.10.0 or later)\r |
49ba9447 | 15 | - Video, keyboard, IDE, CD-ROM, serial\r |
16 | - Runs UEFI shell\r | |
7416f4eb | 17 | - Optional NIC support. Requires QEMU (0.12.2 or later)\r |
73f4a1c0 | 18 | * UEFI Linux boots\r |
19 | * UEFI Windows 8 boots\r | |
90803342 | 20 | * UEFI Windows 7 & Windows 2008 Server boot (see important notes below!)\r |
49ba9447 | 21 | \r |
22 | === FUTURE PLANS ===\r | |
23 | \r | |
49ba9447 | 24 | * Test/Stabilize UEFI Self-Certification Tests (SCT) results\r |
25 | \r | |
37e97c51 | 26 | === BUILDING OVMF ===\r |
27 | \r | |
28 | Pre-requisites:\r | |
29 | * Build environment capable of build the edk2 MdeModulePkg.\r | |
66325870 | 30 | * A properly configured ASL compiler:\r |
31 | - Intel ASL compiler: Available from http://www.acpica.org\r | |
32 | - Microsoft ASL compiler: Available from http://www.acpi.info\r | |
497cbb53 | 33 | * NASM: http://www.nasm.us/\r |
37e97c51 | 34 | \r |
35 | Update Conf/target.txt ACTIVE_PLATFORM for OVMF:\r | |
36 | PEI arch DXE arch UEFI interfaces\r | |
37 | * OvmfPkg/OvmfPkgIa32.dsc IA32 IA32 IA32\r | |
38 | * OvmfPkg/OvmfPkgIa32X64.dsc IA32 X64 X64\r | |
39 | * OvmfPkg/OvmfPkgX64.dsc X64 X64 X64\r | |
40 | \r | |
2dae09a5 | 41 | Update Conf/target.txt TARGET_ARCH based on the .dsc file:\r |
42 | TARGET_ARCH\r | |
43 | * OvmfPkg/OvmfPkgIa32.dsc IA32\r | |
44 | * OvmfPkg/OvmfPkgIa32X64.dsc IA32 X64\r | |
45 | * OvmfPkg/OvmfPkgX64.dsc X64\r | |
46 | \r | |
47 | Following the edk2 build process, you will find the OVMF binaries\r | |
48 | under the $WORKSPACE/Build/*/*/FV directory. The actual path will\r | |
49 | depend on how your build is configured. You can expect to find\r | |
50 | these binary outputs:\r | |
7416f4eb | 51 | * OVMF.FD\r |
66325870 | 52 | - Please note! This filename has changed. Older releases used OVMF.Fv.\r |
922f593a | 53 | * OvmfVideo.rom\r |
e79095b7 | 54 | - This file is not built separately any longer, starting with svn r13520.\r |
2dae09a5 | 55 | \r |
56 | More information on building OVMF can be found at:\r | |
c315da0a | 57 | \r |
58 | http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=How_to_build_OVMF\r | |
37e97c51 | 59 | \r |
60 | === RUNNING OVMF on QEMU ===\r | |
61 | \r | |
210c880f | 62 | * QEMU 0.12.2 or later is required.\r |
37e97c51 | 63 | * Be sure to use qemu-system-x86_64, if you are using and X64 firmware.\r |
64 | (qemu-system-x86_64 works for the IA32 firmware as well, of course.)\r | |
210c880f JJ |
65 | * Use OVMF for QEMU firmware (3 options available)\r |
66 | - Option 1: QEMU 1.6 or newer; Use QEMU -pflash parameter\r | |
67 | * QEMU/OVMF will use emulated flash, and fully support UEFI variables\r | |
68 | * Run qemu with: -pflash path/to/OVMF.fd\r | |
8714a631 LE |
69 | * Note that this option is required for running SecureBoot-enabled builds\r |
70 | (-D SECURE_BOOT_ENABLE).\r | |
210c880f JJ |
71 | - Option 2: Use QEMU -bios parameter\r |
72 | * Note that UEFI variables will be partially emulated, and non-volatile\r | |
73 | variables may lose their contents after a reboot\r | |
74 | * Run qemu with: -bios path/to/OVMF.fd\r | |
75 | - Option 3: Use QEMU -L parameter\r | |
76 | * Note that UEFI variables will be partially emulated, and non-volatile\r | |
77 | variables may lose their contents after a reboot\r | |
78 | * Either copy, rename or symlink OVMF.fd => bios.bin\r | |
79 | * Use the QEMU -L parameter to specify the directory where the bios.bin\r | |
80 | file is located.\r | |
37e97c51 | 81 | * The EFI shell is built into OVMF builds at this time, so it should\r |
82 | run automatically if a UEFI boot application is not found on the\r | |
83 | removable media.\r | |
aed8e2ec | 84 | * On Linux, newer version of QEMU may enable KVM feature, and this might\r |
85 | cause OVMF to fail to boot. The QEMU '-no-kvm' may allow OVMF to boot.\r | |
bf23b44d | 86 | * Capturing OVMF debug messages on qemu:\r |
87 | - The default OVMF build writes debug messages to IO port 0x402. The\r | |
88 | following qemu command line options save them in the file called\r | |
89 | debug.log: '-debugcon file:debug.log -global isa-debugcon.iobase=0x402'.\r | |
90 | - It is possible to revert to the original behavior, when debug messages were\r | |
91 | written to the emulated serial port (potentially intermixing OVMF debug\r | |
92 | output with UEFI serial console output). For this the\r | |
93 | '-D DEBUG_ON_SERIAL_PORT' option has to be passed to the build command (see\r | |
94 | the next section), and in order to capture the serial output qemu needs to\r | |
95 | be started with eg. '-serial file:serial.log'.\r | |
96 | - Debug messages fall into several categories. Logged vs. suppressed\r | |
97 | categories are controlled at OVMF build time by the\r | |
98 | 'gEfiMdePkgTokenSpaceGuid.PcdDebugPrintErrorLevel' bitmask (an UINT32\r | |
99 | value) in the selected .dsc file. Individual bits of this bitmask are\r | |
100 | defined in <MdePkg/Include/Library/DebugLib.h>. One non-default bit (with\r | |
101 | some performance impact) that is frequently set for debugging is 0x00400000\r | |
102 | (DEBUG_VERBOSE).\r | |
103 | - The RELEASE build target ('-b RELEASE' build option, see below) disables\r | |
104 | all debug messages. The default build target is DEBUG.\r | |
5a9745b9 | 105 | \r |
106 | === Build Scripts ===\r | |
107 | \r | |
66325870 | 108 | On systems with the bash shell you can use OvmfPkg/build.sh to simplify\r |
109 | building and running OVMF.\r | |
5a9745b9 | 110 | \r |
111 | So, for example, to build + run OVMF X64:\r | |
66325870 | 112 | $ OvmfPkg/build.sh -a X64\r |
113 | $ OvmfPkg/build.sh -a X64 qemu\r | |
5a9745b9 | 114 | \r |
115 | And to run a 64-bit UEFI bootable ISO image:\r | |
66325870 | 116 | $ OvmfPkg/build.sh -a X64 qemu -cdrom /path/to/disk-image.iso\r |
117 | \r | |
bf23b44d | 118 | To build a 32-bit OVMF without debug messages using GCC 4.5:\r |
66325870 | 119 | $ OvmfPkg/build.sh -a IA32 -b RELEASE -t GCC45\r |
5a9745b9 | 120 | \r |
aed8e2ec | 121 | === Network Support ===\r |
122 | \r | |
7a1f5947 LE |
123 | OVMF provides a UEFI network stack by default. Its lowest level driver is the\r |
124 | NIC driver, higher levels are generic. In order to make DHCP, PXE Boot, and eg.\r | |
125 | socket test utilities from the StdLib edk2 package work, (1) qemu has to be\r | |
126 | configured to emulate a NIC, (2) a matching UEFI NIC driver must be available\r | |
127 | when OVMF boots.\r | |
7628b0f5 | 128 | \r |
129 | (If a NIC is configured for the virtual machine, and -- dependent on boot order\r | |
130 | -- PXE booting is attempted, but no DHCP server responds to OVMF's DHCP\r | |
131 | DISCOVER message at startup, the boot process may take approx. 3 seconds\r | |
132 | longer.)\r | |
133 | \r | |
134 | * For each NIC emulated by qemu, a GPLv2 licensed UEFI driver is available from\r | |
135 | the iPXE project. The qemu source distribution, starting with version 1.5,\r | |
136 | contains prebuilt binaries of these drivers (and of course allows one to\r | |
7a1f5947 | 137 | rebuild them from source as well). This is the recommended set of drivers.\r |
7628b0f5 | 138 | \r |
139 | * Use the qemu -netdev and -device options, or the legacy -net option, to\r | |
140 | enable NIC support: <http://wiki.qemu.org/Documentation/Networking>.\r | |
141 | \r | |
142 | * For a qemu >= 1.5 binary running *without* any "-M machine" option where\r | |
143 | "machine" would identify a < qemu-1.5 configuration (for example: "-M\r | |
7a1f5947 LE |
144 | pc-i440fx-1.4" or "-M pc-0.13"), the iPXE drivers are automatically available\r |
145 | to and configured for OVMF in the default qemu installation.\r | |
7628b0f5 | 146 | \r |
147 | * For a qemu binary in [0.13, 1.5), or a qemu >= 1.5 binary with an "-M\r | |
148 | machine" option where "machine" selects a < qemu-1.5 configuration:\r | |
149 | \r | |
150 | - download a >= 1.5.0-rc1 source tarball from <http://wiki.qemu.org/Download>,\r | |
151 | \r | |
7a1f5947 LE |
152 | - extract the following iPXE driver files from the tarball and install them\r |
153 | in a location that is accessible to qemu processes (this may depend on your\r | |
7628b0f5 | 154 | SELinux configuration, for example):\r |
155 | \r | |
156 | qemu-VERSION/pc-bios/efi-e1000.rom\r | |
157 | qemu-VERSION/pc-bios/efi-ne2k_pci.rom\r | |
158 | qemu-VERSION/pc-bios/efi-pcnet.rom\r | |
159 | qemu-VERSION/pc-bios/efi-rtl8139.rom\r | |
160 | qemu-VERSION/pc-bios/efi-virtio.rom\r | |
161 | \r | |
162 | - extend the NIC's -device option on the qemu command line with a matching\r | |
163 | "romfile=" optarg:\r | |
164 | \r | |
165 | -device e1000,...,romfile=/full/path/to/efi-e1000.rom\r | |
166 | -device ne2k_pci,...,romfile=/full/path/to/efi-ne2k_pci.rom\r | |
167 | -device pcnet,...,romfile=/full/path/to/efi-pcnet.rom\r | |
168 | -device rtl8139,...,romfile=/full/path/to/efi-rtl8139.rom\r | |
169 | -device virtio-net-pci,...,romfile=/full/path/to/efi-virtio.rom\r | |
170 | \r | |
7a1f5947 LE |
171 | * Independently of the iPXE NIC drivers, the default OVMF build provides a\r |
172 | basic virtio-net driver, located in OvmfPkg/VirtioNetDxe.\r | |
173 | \r | |
174 | * Also independently of the iPXE NIC drivers, Intel's proprietary E1000 NIC\r | |
175 | driver (PROEFI) can be embedded in the OVMF image at build time:\r | |
7628b0f5 | 176 | \r |
177 | - Download UEFI drivers for the e1000 NIC\r | |
178 | - http://downloadcenter.intel.com/Detail_Desc.aspx?agr=Y&DwnldID=17515&lang=eng\r | |
179 | - Install the drivers into a directory called Intel3.5 in your WORKSPACE.\r | |
180 | \r | |
181 | - Include the driver in OVMF during the build:\r | |
182 | - Add "-D E1000_ENABLE -D FD_SIZE_2MB" to your build command,\r | |
183 | - For example: "build -D E1000_ENABLE -D FD_SIZE_2MB".\r | |
aed8e2ec | 184 | \r |
7a1f5947 LE |
185 | * When a matching iPXE driver is configured for a NIC as described above, it\r |
186 | takes priority over other drivers that could possibly drive the card too:\r | |
187 | \r | |
188 | | e1000 ne2k_pci pcnet rtl8139 virtio-net-pci\r | |
189 | -------------+------------------------------------------------\r | |
190 | iPXE | x x x x x\r | |
191 | VirtioNetDxe | x\r | |
192 | Intel PROEFI | x\r | |
193 | \r | |
e58e5bcd JJ |
194 | === OVMF Flash Layout ===\r |
195 | \r | |
196 | Like all current IA32/X64 system designs, OVMF's firmware\r | |
197 | device (rom/flash) appears in QEMU's physical address space\r | |
198 | just below 4GB (0x100000000).\r | |
199 | \r | |
200 | The layout of the firmware device in memory looks like:\r | |
201 | \r | |
202 | +--------------------------------------- 4GB (0x100000000)\r | |
203 | | VTF0 (16-bit reset code) and OVMF SEC\r | |
204 | | (SECFV)\r | |
205 | +--------------------------------------- varies based on flash size\r | |
206 | |\r | |
207 | | Compressed main firmware image\r | |
208 | | (FVMAIN_COMPACT)\r | |
209 | |\r | |
210 | +--------------------------------------- base + 0x20000\r | |
211 | | Fault-tolerant write (FTW)\r | |
212 | | Spare blocks (64KB/0x10000)\r | |
213 | +--------------------------------------- base + 0x10000\r | |
214 | | FTW Work block (4KB/0x1000)\r | |
215 | +--------------------------------------- base + 0x0f000\r | |
216 | | Event log area (4KB/0x1000)\r | |
217 | +--------------------------------------- base + 0x0e000\r | |
218 | | Non-volatile variable storage\r | |
219 | | area (56KB/0xe000)\r | |
220 | +--------------------------------------- base address\r | |
221 | \r | |
222 | OVMF supports building a 1MB or a 2MB flash image. The base address for\r | |
223 | a 1MB image in QEMU physical memory is 0xfff00000. The base address for\r | |
224 | a 2MB image is 0xffe00000.\r | |
225 | \r | |
226 | The code in SECFV locates FVMAIN_COMPACT, and decompresses the\r | |
227 | main firmware (MAINFV) into RAM memory at address 0x800000. The\r | |
228 | remaining OVMF firmware then uses this decompressed firmware\r | |
229 | volume image.\r | |
230 | \r | |
0b5a5022 | 231 | === UNIXGCC Debug ===\r |
232 | \r | |
233 | If you build with the UNIXGCC toolchain, then debugging will be disabled\r | |
234 | due to larger image sizes being produced by the UNIXGCC toolchain. The\r | |
235 | first choice recommendation is to use GCC44 or newer instead.\r | |
236 | \r | |
237 | If you must use UNIXGCC, then you can override the build options for\r | |
238 | particular libraries and modules in the .dsc to re-enable debugging\r | |
239 | selectively. For example:\r | |
240 | [Components]\r | |
241 | OvmfPkg/Library/PlatformBdsLib/PlatformBdsLib.inf {\r | |
242 | <BuildOptions>\r | |
243 | GCC:*_*_*_CC_FLAGS = -UMDEPKG_NDEBUG\r | |
244 | }\r | |
245 | IntelFrameworkModulePkg/Universal/BdsDxe/BdsDxe.inf {\r | |
246 | <BuildOptions>\r | |
247 | GCC:*_*_*_CC_FLAGS = -UMDEPKG_NDEBUG\r | |
248 | }\r | |
249 | \r | |
90803342 LE |
250 | === UEFI Windows 7 & Windows 2008 Server ===\r |
251 | \r | |
252 | * One of the '-vga std' and '-vga qxl' QEMU options should be used.\r | |
253 | * Only one video mode, 1024x768x32, is supported at OS runtime.\r | |
254 | * The '-vga qxl' QEMU option is recommended. After booting the installed\r | |
255 | guest OS, select the video card in Device Manager, and upgrade its driver\r | |
256 | to the QXL XDDM one. Download location:\r | |
257 | <http://www.spice-space.org/download.html>, Guest | Windows binaries.\r | |
258 | This enables further resolutions at OS runtime, and provides S3\r | |
259 | (suspend/resume) capability.\r |