diff options
Diffstat (limited to 'OvmfPkg/README')
| -rw-r--r-- | OvmfPkg/README | 259 |
1 files changed, 0 insertions, 259 deletions
diff --git a/OvmfPkg/README b/OvmfPkg/README deleted file mode 100644 index 147e6e0ebf..0000000000 --- a/OvmfPkg/README +++ /dev/null @@ -1,259 +0,0 @@ -
-=== 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.
|