================================================================================ Intel(R) Platform Developer's UEFI Emulation (DUET) Dec 28th, 2006 ================================================================================ ================================================================================ CONTENTS ================================================================================ * Overview * How to build DUET image * How to create bootable disk * Overview of DUET bootflow * Known limitations * Known issue * Symbols ================================================================================ OVERVIEW ================================================================================ DUET provides an EFI/UEFI IA32/X64 Development environment on existing hardware to aid in the development and debug of native EFI/UEFI drivers. It can create boot disk and boot to EFI/UEFI shell from legacy interfaces (Legacy BIOS or Framework BIOS with CSM). The processor must be capable of 64 bit support, if one wishes to develop 64 bit drivers. Since the system has to complete an entire Legacy Boot and UEFI load and install, this is not a product solution for UEFI, but it does make a good hardware test bed for developers wanting to test and evaluate their UEFI drivers and applications on real hardware. DUET was originally code named as UoL, the name was changed to better define the functionality of the feature. ================================================================================ HOW TO BUILD DUET ================================================================================ 1. Tools preparation To build DUET image, following tools are required: 1). *Visual Studio 2003* or *Visual Studio 2005* Assume installed at , e.g.: C:\Program Files\Microsoft Visual Studio .NET 2003. 2). WinDDK Assume installed at , e.g.: C:\WINDDK\3790.1830. 3). MASM Assume installed at , e.g.: C:\Masm611. 2. Source preparation 1). Extract Edk-Dev-Snapshot-20061228.zip (or later) to a directory, for example, C:\. The EDK source is under C:\Edk. We mark this directory as . 2). Extract EnhancedFat-Dev-Snapshot-20061228.zip (corresponding to the EDK version)to \Other\Maintained\Universal\Disk\FileSystem. The enhanced fat driver is under: \Other\Maintained\Universal\Disk\FileSystem\EnhancedFat, for example, C:\Edk\Other\Maintained\Universal\Disk\FileSystem\EnhancedFat. 3. Build steps 3.1. [Visual Studio 2003] 1). Run "Visual Studio .NET 2003 Command Prompt" to open a command line window. 2). Set other environment variable by running following commands: set EDK_SOURCE= set WIN_DDK_PATH= set MASMPATH= is where Edk root directory puts, e.g.: C:\Edk. In the meanwhile, DUET should be under C:\Edk\Sample\Platform. If WIN_DDK_PATH and MASMPATH are not set, DUET building process will use "C:\WINDDK\3790.1830" as default value of WIN_DDK_PATH, and "C:\Masm611" as default value of MASMPATH. 4). Change current directory to \Sample\Platform\DUET 5). Run "nmake " to build specified image, where can be one of the four values: efi32, uefi32, efi64, uefi64. 3.2. [Visual Studio 2005] Two changes based on the step using *Visual Studio 2003* need to make: 1). In step 1), Run "Visual Studio 2005 Command Prompt" to open a command line 2). Before running "nmake ", open \Sample\Platform\DUET\Config.env. Replace the line "USE_VC8 = NO" with "USE_VC8 = YES". 4. Clean steps In command line, under \Sample\Platform\DUET: 1). Running "nmake clean" can remove all files generated by corresponding "nmake ". E.g.: "nmake efi32clean" can remove all files generated by "nmake efi32". 2). Running "nmake clean" can remove all files generated by any "nmake " command, which is equivalent to running "nmake efi32clean & nmake uefi32clean & nmake efi64clean & nmake uefi64clean". ================================================================================ HOW TO CREATE BOOTABLE DISK ================================================================================ After the image builds successfully, change current directory to directory, e.g.: cd \Sample\Platform\DUET\efi32. Following steps can let us create DUET bootable disk for corresponding storage media. 1. Create Bootable Floppy 1). Set EFI_BOOT_DISK environment variable by running following command: set EFI_BOOT_DISK=: Where is the floppy volume, e.g.: set EFI_BOOT_DISK=A:. If EFI_BOOT_DISK is not set, "A:" will be used as its default value. Please do not forget to append a *COLON* after the volume letter. 2). Run command "nmake createfloppy & nmake floppy", which will create the bootable floppy disk. 2. Create Bootable USB 1). Please make sure the USB disk can boot to DOS first. 2). Set EFI_BOOT_DISK environment variable by running following command: set EFI_BOOT_DISK=: Where is the USB disk volume, e.g.: set EFI_BOOT_DISK=H:. Please do not forget to append a *COLON* after the volume letter. 3). Run command "nmake createusb", and *RE-PLUG* the USB disk after that. Then run command "nmake usb". The two commands will create the bootable USB disk. The bootable USB disk can also be created by "nmake createusb32" and "nmake usb32", which will create the disk with Fat32 type. Please *DO NOT* forget to *RE-PLUG* the USB disk between the two commands. ================================================================================ Overview of DUET bootflow ================================================================================ Here means the partition type of volume: FAT12, FAT16, FAT32; means the type of platform: IA32, X64 1). Legacy boot: Load Boot Sector Jump to it. 2). Boot Sector: Load Start Jump to it. 3). Start (real mode): Eflldr is loaded into memory Prepare E820 table Load GDT, IDT, Page Table(for X64), Enter 32bits protect mode, or 64bits long mode Jump to Efi 4). Efi: Prepare stack Install Interrupt Handler Relocate Efildr to low memory Jump to Efildr 5). Efildr Get E820 memory Load BFV, relocate DxeCore, relocate DxeIpl, jump to DxeIpl 6). DxeIpl Generate Hob Prepare PPI needed by DXE Get DxeCore entry point, jump to it ================================================================================ KNOWN LIMITATIONS ================================================================================ 1. Booting from floppy is slower than booting from USB disk. This is because of the low speed of floppy drive. DUET needs to access floppy when: 1). Loading Efildr in the beginning of booting. 2). Enumerating Shell in every removable media, which happens when we enter into BootManager in FrontPage. 3). Loading Shell from floppy. 4). Updating non-volatile Variables. 2. DUET Non-Volatile Storage DUET uses FSVariable driver to provide non-volatile storage which depends on SimpleFileSystem driver. Before SimpleFileSystem is started, FSVariable uses memory as a temporary non-volatile storage. And when SimpleFileSystem is started, FSVariable will use a special file on the bootable disk as non-volatile storage. So, before SimpleFileSystem is started, we shouldn't depend on the results of calling FSVariable service. We can use EmuVariable driver instead of FSVariable driver for better performance. Open \Sample\Platform\DUET\Build\DUET.dsc, and replace "Sample\Universal\Variable\RuntimeDxe\FS\FSVariable.inf" with "Sample\Universal\Variable\RuntimeDxe\Emu\EmuVariable.inf". But non-volatile storage will not be available when using EmuVariable driver. ================================================================================ KNOWN ISSUES ================================================================================ 1. USB bootable disk cannot boot on some PCs because different BIOS may have different implementation for USB boot. 2. USB hotplug may not work on some PCs. We can run shell command "reconnect -r" to force DUET to re-connect all devices (including USB devices). 3. GetNextMonotonicCount() and GetNextHighMonotonicCount() don't return correct monotonic count. ================================================================================ SYMBOLS ================================================================================ This section lists symbols referenced by above sections. Installation path of *Visual Studio*. Installation path of Win DDK. Installation path of Masm. Path of root directory of Edk. Build target name of DUET. It can be one of the following four values: efi32 : provides an IA32 environment following EFI 1.10 Spec, uefi32 : provides an IA32 environment following UEFI 2.0 Spec, efi64 : provides an X64 environment following EFI 1.10 Spec, uefi64 : provides an X64 environment following UEFI 2.0 Spec. Volume letter of floppy disk, e.g.: A. Volume letter of USB disk, e.g.: H.