UnixPkg/readme.txt

   1 Unix Simulation Platform
   2 ========================
   3
   4 UnixPkg is one of platform package which can be built to a platform's firmware from UnixPkg.dsc file.
   5 And this package provide a simulation platform under *INUX environment in IA32 architecture.
   6
   7 - Same points between real platform and simulation platform:
   8   1) Unix simulation platform also run with firmware device image built from UnixPkg
   9   2) The working flow of simulation platform also contains SEC/PEI/DXE phase.
  10
  11 - Different points between real platform and simulation platform:
  12   1) The SEC phase in simulation platform in fact is a *INUX native application which can be run from *INUX shell;
  13   2) The device in simulation platform is not real hardware but simulation component in API level;
  14   3) The ThunkBus driver in simulation platform will get virtual device's desription from PCD and create virtual Device
  15
  16 Build
  17 =====
  18 UnixPkg is built with following command:
  19   build -p UnixPkg/UnixPkg.dsc -a IA32 -t ELFGCC
  20   Notes: ELFGCC is defined in <Workspace>/Conf/tools_def.txt file. This tool chain use native gcc/binutil instead of
  21          cross-compiler like UNIXGCC tool chain.
  22
  23 On Mac OS X you can cd into UnixPkg directory and execute ./build.sh to build. This does not require
  24 setting up the environment like running the build command. Note Snow Leopard or later is required.
  25 This script should also work for any *INUX, but has not been tested.
  26
  27 ./build.sh run will lanuch the emulator in gdb so you can source level debug via gdb.
  28
  29
  30 Notes:
  31 =====
  32 On Mac OS X Snow Leopard you can use Xcode 3.2 as a GUI debugger.
  33 Launch Xcode and open UnixPkg/Xcode/xcode_project/xcode_project.xcodeproj
  34 Under the build menu chose build and debug. shift-cmd-B shows the build results.
  35
  36 Under most *INUX the EFI executables are placed in the emulated EFI memory by the EFI PE/COFF loader
  37 but dlopen() is used to also load the image into the process to support source level debug.
  38 The entry point for the image is moved from the EFI emulator memory into the dlopen() image. This
  39 is not the case for Mac OS X. On Mac OS X a debugger script is used and the real EFI images in
  40 the emulator are the ones being debugged.
  41
  42 Also on Mac OS X the stack alignment requirements for IA-32 are 16 bytes and this is more strict
  43 than the EFI ABI. To work around this gasket code was introduced to ensure the stack is always
  44 16 byte aligned when making any POSIX call on Mac OS X.
  45
  46 To build PE/COFF images with Xcode 3.2 and extra tool call mtoc is required to convert Mach-O
  47 images into PE/COFF images. The tool only supports EFI PE/COFF images and the instructions on
  48 how to download it are on the edk2 website.
  49
  50 FAQ
  51 ===
  52 1, I fail to build UnixPkg due to "X11/extensions/XShm.h: No such file or directory"?
  53    The display adapter in UnixPkg is a virtual device written in X11 API. The library of x11proto-xext-dev is required
  54    for building.
  55
  56 2, I fail to build UnixPkg due to "/usr/bin/ld: cannot find -lXext"?
  57    libxext-dev library is required for building.
  58