diff options
Diffstat (limited to 'OvmfPkg/README')
| -rw-r--r-- | OvmfPkg/README | 107 |
1 files changed, 79 insertions, 28 deletions
diff --git a/OvmfPkg/README b/OvmfPkg/README index 0c0a81a67..13058eae4 100644 --- a/OvmfPkg/README +++ b/OvmfPkg/README @@ -66,13 +66,30 @@ http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=How_to_build_OVM (qemu-system-x86_64 works for the IA32 firmware as well, of course.)
* Use the QEMU -L parameter to specify the directory where the bios.bin
file is located.
-* Optionally you can use the QEMU -serial command to capture the
- OVMF debug messages. For example: -serial file:serial.log
* 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 ===
@@ -86,36 +103,70 @@ $ 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 serial messages using GCC 4.5:
+To build a 32-bit OVMF without debug messages using GCC 4.5:
$ OvmfPkg/build.sh -a IA32 -b RELEASE -t GCC45
=== Network Support ===
-To add network drivers to OVMF:
-
-* 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 drivers in OVMF during the build:
- - Add '-D NETWORK_ENABLE' to your build command
- - For example: build -D NETWORK_ENABLE
-
-* Use the QEMU -net parameter to enable NIC support.
- - QEMU does not support UEFI DHCP or UEFI PXE Boot, so long timeouts will
- occur when NICs are enabled. The long timeouts can be avoided by
- interrupts the boot sequence by pressing a key when the logo appears.
- - Example: Enable e1000 NIC with a DHCP server and restrict packet
- forwarding:
- -net nic,model=e1000 -net user,restrict=yes -net user,dhcpstart=10.0.2.10
- - Example: Enable e1000 NIC with a DHCP server, restrict packet forwarding,
- and generate PCAP file:
- -net nic,model=e1000 -net user,restrict=yes -net user,dhcpstart=10.0.2.10
- -net dump,file=a.pcap
- - Example: Enable 2 e1000 NICs with a DHCP server and restrict
- packet forwarding:
- -net nic,model=e1000,addr=3 -net nic,model=e1000,addr=4
- -net user,restrict=yes -net user,dhcpstart=10.0.2.10
+OVMF provides a generic UEFI network stack by default, with the lowest level
+driver (the NIC driver) missing in the default build. In order to complete the
+stack and make eg. DHCP, PXE Boot, and 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).
+
+* 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 drivers are available from the default
+ qemu installation to OVMF without further settings.
+
+* 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 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, Intel's proprietary E1000 NIC driver
+ can be embedded in the OVMF image at build time, as an alternative guest
+ driver for "-device e1000":
+
+ - 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".
=== UNIXGCC Debug ===
|