123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502 |
- EADK
- EDK II Standard Libraries and Applications
- ReadMe
- Version 1.02
- 21 Dec. 2012
- OVERVIEW
- ========
- The EADK (uEfi Application Development Kit) provides a set of standards-based
- libraries, along with utility and demonstration applications, intended to
- ease development of UEFI applications based upon the EDK II Open-Source
- distribution.
- At this time, applications developed with the EADK are intended to reside
- on, and be loaded from, storage separate from the core firmware. This is
- primarily due to size and environmental requirements.
- This release of the EADK should only be used to produce UEFI Applications. Due to the execution
- environment built by the StdLib component, execution as a UEFI driver can cause system stability
- issues.
- This document describes the EDK II specific aspects of installing, building,
- and using the Standard C Library component of the EDK II Application
- Development Kit, EADK.
- The EADK is comprised of three packages:
- AppPkg, StdLib, and StdLibPrivateInternalFiles.
- AppPkg This package contains applications which demonstrate use of the
- Standard C and Sockets Libraries.
- These applications reside in AppPkg/Applications.
- Enquire This is a program that determines many properties of the
- C compiler and the target machine that Enquire is run on. The
- only changes required to port this 1990s era Unix program to
- EDK II were the addition of eight pragmas to enquire.c in
- order to disable some Microsoft VC++ specific warnings.
- Hello This is a very simple EDK II native application that doesn't use
- any features of the Standard C Library.
- Main This application is functionally identical to Hello, except that
- it uses the Standard C Library to provide a main() entry point.
- Python A port of the Python-2.7.2 interpreter for UEFI. Building this
- application is disabled by default.
- See the PythonReadMe.txt file, in the Python directory,
- for information on configuring and building Python.
- Sockets A collection of applications demonstrating use of the
- EDK II Socket Libraries. These applications include:
- * DataSink * DataSource
- * GetAddrInfo * GetHostByAddr
- * GetHostByDns * GetHostByName
- * GetNetByAddr * GetNetByName
- * GetServByName * GetServByPort
- * OobRx * OobTx
- * RawIp4Rx * RawIp4Tx
- * RecvDgram * SetHostName
- * SetSockOpt * TftpServer
- * WebServer
- StdLib The StdLib package contains the standard header files as well as
- implementations of other standards-based libraries.
- * BsdSocketLib
- Support routines above the sockets layer and C interface for
- the UEFI socket library.
- * Efi
- Template contents for the target system's
- \Efi\StdLib\etc directory.
- * EfiSocketLib
- UEFI socket implementation, may be linked into an
- application or run as a driver.
- * Include
- Standard include files.
- * LibC
- C Standard Library implementation as per
- ISO/IEC 9899:199409 (C95).
- * PosixLib
- Selected functions from the "Single Unix v4" specification.
- * SocketDxe
- UEFI sockets driver, includes EfiSocketLib.
- * UseSocketDxe
- Alternate linkage for applications that get built into the
- firmware. Cause application to use a common instance of the
- sockets driver instead of including all of sockets into the
- application.
- StdLibPrivateInternalFiles The contents of this package are for the
- exclusive use of the library implementations in StdLib. Please do
- not use anything from this package in your application or else
- unexpected behavior may occur.
- This package may be removed in a future release.
- RELEASE NOTES
- =============
- Fixes and Additions
- -------------------
- Beginning with release 1.01, applications built with the StdLib package
- no longer have a dependency on the TimerLib.
- Known Issues
- -----------------
- This release of the EADK has some restrictions, as described below.
- 1. The target machine must be running firmware which provides the
- UEFI 2.3 HII protocol.
- 2. Applications must be launched from within the EFI Shell.
- 3. Absolute file paths may optionally be prefixed by a volume specifier
- such as "FS0:". The volume specifier is separated from the remainder
- of the path by a single colon ':'. The volume specifier must be one of
- the Shell's mapped volume names as shown by the "map" command.
- 4. Absolute file paths that don't begin with a volume specifier;
- e.g. paths that begin with "/", are relative to the currently selected
- volume. When the EFI Shell first starts, there is NO selected volume.
- 5. The tmpfile(), and related, functions require that the current volume
- have a temporary directory as specified in <paths.h>. This directory
- is specified by macro _PATH_TMP as /Efi/StdLib/tmp.
- The Standard C Library provided by this package is a "hosted" implementation
- conforming to the ISO/IEC 9899-1990 C Language Standard with Addendum 1. This
- is commonly referred to as the "C 95" specification or ISO/IEC 9899:199409.
- The following instructions assume that you have an existing EDK II or UDK 2010
- source tree that has been configured to build with your tool chain. For
- convenience, it is assumed that your EDK II source tree is located at
- C:\Source\Edk2.
- EADK INSTALLATION
- =================
- The EADK is integrated within the EDK II source tree and is included with
- current EDK II check-outs. If they are missing from your tree, they may be
- installed by extracting, downloading or copying them to the root of your EDK II
- source tree. The three package directories should be peers to the Conf,
- MdePkg, Nt32Pkg, etc. directories.
- There are some boiler-plate declarations and definitions that need to be
- included in your application's INF and DSC build files. These are described
- in the CONFIGURATION section, below.
- A subset of the Python 2.7.2 distribution is included as part of AppPkg. If desired,
- the full Python 2.7.2 distribution may be downloaded from python.org and used instead.
- Delete or rename the existing Python-2.7.2 directory then extract the downloaded
- Python-2.7.2.tgz file into the AppPkg\Applications\Python directory. This will produce a
- Python-2.7.2 directory containing the full Python distribution. Python files that had to be
- modified for EDK II are in the AppPkg\Applications\Python\PyMod-2.7.2 directory. These
- files need to be copied into the corresponding directories within the extracted Python-2.7.2
- directory before Python can be built.
- BUILDING
- ========
- It is not necessary to build the libraries separately from the target
- application(s). If the application references the libraries, as described in
- USAGE, below; the required libraries will be built as needed.
- To build the applications included in AppPkg, one would execute the following
- commands within the "Visual Studio Command Prompt" window:
- > cd C:\Source\Edk2
- > .\edksetup.bat
- > build -a X64 -p AppPkg\AppPkg.dsc
- This will produce the application executables: Enquire.efi, Hello.efi, and
- Main.efi in the C:\Source\Edk2\Build\AppPkg\DEBUG_VS2008\X64 directory; with
- the DEBUG_VS2008 component being replaced with the actual tool chain and build
- type you have selected in Conf\Tools_def.txt. These executables can now be
- loaded onto the target platform and executed.
- If you examine the AppPkg.dsc file, you will notice that the StdLib package is
- referenced in order to resolve the library classes comprising the Standard
- C Library. This, plus referencing the StdLib package in your application's
- .inf file is all that is needed to link your application to the standard
- libraries.
- Unless explicitly stated as allowed, EADK components should not be added as
- components of a DSC file which builds a platform's core firmware. There are
- incompatibilities in build flags and requirements that will conflict with the
- requirements of the core firmware. EADK components should be built using a
- separate DSC file then, if absolutely necessary, included as binary components
- of other DSC files.
- USAGE
- =====
- This implementation of the Standard C Library is comprised of 16 separate
- libraries in addition to the standard header files. Nine of the libraries are
- associated with use of one of the standard headers; thus, if the header is used
- in an application, it must be linked with the associated library. Three
- libraries are used to provide the Console and File-system device abstractions.
- The libraries and associated header files are described in the following table.
- Library
- Class Header File(s) Notes
- ---------- ---------------- -------------------------------------------------
- LibC -- Use Always -- This library is always required.
- LibCtype ctype.h, wctype.h Character classification and mapping
- LibLocale locale.h Localization types, macros, and functions
- LibMath math.h Mathematical functions, types, and macros
- LibStdio stdio.h Standard Input and Output functions, types, and
- macros
- LibStdLib stdlib.h General Utilities for numeric conversion, random
- num., etc.
- LibString string.h String copying, concatenation, comparison,
- & search
- LibSignal signal.h Functions and types for handling run-time
- conditions
- LibTime time.h Time and Date types, macros, and functions
- LibUefi sys/EfiSysCall.h Provides the UEFI system interface and
- "System Calls"
- LibWchar wchar.h Extended multibyte and wide character utilities
- LibNetUtil Network address and number manipulation utilities
- DevConsole Automatically provided File I/O abstractions for
- the UEFI Console device. No need to list this
- library class in your INF file(s).
- DevShell Add if desired File I/O abstractions using UEFI shell
- facilities. Add this to the application's main
- INF file if file-system access needed.
- DevUtility -- Do Not Use -- Utility functions used internally by the Device abstractions
- LibGdtoa -- Do Not Use -- This library is used internally and should not
- need to be explicitly specified by an
- application. It must be defined as one of the
- available library classes in the application's
- DSC file.
- Table 1: Standard Libraries
- ============================
- The DevConsole and DevShell libraries provide device I/O functionality and are treated
- specially. DevConsole is automatically included so there is no need to reference it in your
- application's DSC or INF files. DevShell must be listed, in your application's INF file in the
- [LibraryClasses] section, if your application does file I/O.
- These libraries must be fully described in the [LibraryClasses] section of the
- application package's DSC file. Then, each individual application needs to
- specify which libraries to link to by specifying the Library Class, from the
- above table, in the [LibraryClasses] section of the application's INF file. The
- AppPkg.dsc, StdLib.dsc, and Enquire.inf files provide good examples of this.
- More details are in the CONFIGURATION section, below.
- In order to simplify this process, the [LibraryClasses] definitions, and others, are
- specified in the StdLib.inc file. If this file is included in the DSC file, usually at the
- end, then other DSC file changes or additions are unnecessary. This is further described in
- the CONFIGURATION section, below.
- Within the source files of the application, use of the Standard headers and
- library functions follow standard C programming practices as formalized by
- ISO/IEC 9899:1990, with Addendum 1, (C 95) C language specification.
- BUILD CONFIGURATION
- ===================
- DSC Files
- ---------
- All EDK II packages which build applications that use the standard libraries
- must include some "boilerplate" text in the package's .dsc file. To make it
- easier, and to reduce cut-and-paste errors, the "boilerplate" text has been
- consolidated into a single file, StdLib/StdLib.inc, which can be included in
- your .dsc file using the !include directive. The provided AppPkg.dsc and
- StdLib.dsc files do this on their last line.
- The "boilerplate" text can be included using a !include directive in the
- package's .dsc file. The provided AppPkg.dsc and StdLib.dsc files include
- the following "boilerplate" text:
- ##############################################################################
- #
- # Specify whether we are running in an emulation environment, or not.
- # Define EMULATE if we are, else keep the DEFINE commented out.
- #
- # DEFINE EMULATE = 1
- ##############################################################################
- #
- # Include Boilerplate text required for building with the Standard Libraries.
- #
- ##############################################################################
- !include StdLib/StdLib.inc
- Figure 1: "Boilerplate" Inclusion
- =================================
- The EMULATE macro must be defined if one desires to do source-level debugging within one of
- the emulated environments such as NT32Pkg or UnixPkg.
- The final boilerplate line, in Figure 1, includes the StdLib.inc file.
- Each section of StdLib/StdLib.inc is described below.
- If desired, all of the Socket applications, in AppPkg, can be built by including Sockets.inc:
- !include AppPkg/Applications/Sockets/Sockets.inc
- Figure 2: Socket Applications "Boilerplate" Inclusion
- =====================================================
- Descriptions of the Library Classes comprising the Standard Libraries,
- as shown in Figure 3: Library Class Descriptions, are provided.
- [LibraryClasses]
- #
- # C Standard Libraries
- #
- LibC|StdLib/LibC/LibC.inf
- LibCType|StdLib/LibC/Ctype/Ctype.inf
- LibLocale|StdLib/LibC/Locale/Locale.inf
- LibMath|StdLib/LibC/Math/Math.inf
- LibSignal|StdLib/LibC/Signal/Signal.inf
- LibStdio|StdLib/LibC/Stdio/Stdio.inf
- LibStdLib|StdLib/LibC/StdLib/StdLib.inf
- LibString|StdLib/LibC/String/String.inf
- LibTime|StdLib/LibC/Time/Time.inf
- LibUefi|StdLib/LibC/Uefi/Uefi.inf
- LibWchar|StdLib/LibC/Wchar/Wchar.inf
- # Common Utilities for Networking Libraries
- LibNetUtil|StdLib/LibC/NetUtil/NetUtil.inf
- # Additional libraries for POSIX functionality.
- LibErr|StdLib/PosixLib/Err/LibErr.inf
- LibGen|StdLib/PosixLib/Gen/LibGen.inf
- LibGlob|StdLib/PosixLib/Glob/LibGlob.inf
- LibStringlist|StdLib/PosixLib/Stringlist/LibStringlist.inf
- # Libraries for device abstractions within the Standard C Library
- # Applications should not directly access any functions defined in these libraries.
- LibGdtoa|StdLib/LibC/gdtoa/gdtoa.inf
- DevConsole|StdLib/LibC/Uefi/Devices/daConsole.inf
- DevShell|StdLib/LibC/Uefi/Devices/daShell.inf
- DevUtility|StdLib/LibC/Uefi/Devices/daUtility.inf
- [LibraryClasses.ARM.UEFI_APPLICATION]
- NULL|ArmPkg/Library/CompilerIntrinsicsLib/CompilerIntrinsicsLib.inf
- Figure 3: Library Class Descriptions
- ====================================
- The directives in Figure 4: Package Component Descriptions will create
- instances of the BaseLib and BaseMemoryLib library classes that are built
- with Link-time-Code-Generation disabled. This is necessary when using the
- Microsoft tool chains in order to allow the library's functions to be
- resolved during the second pass of the linker during Link-Time-Code-Generation
- of the application.
- A DXE driver version of the Socket library is also built.
- [Components]
- # BaseLib and BaseMemoryLib need to be built with the /GL- switch
- # when using the Microsoft tool chains. This is required so that
- # the library functions can be resolved during the second pass of
- # the linker during link-time-code-generation.
- #
- MdePkg/Library/BaseLib/BaseLib.inf {
- <BuildOptions>
- MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-
- }
- MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf {
- <BuildOptions>
- MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-
- }
- ##########
- # Socket Layer
- ##########
- StdLib/SocketDxe/SocketDxe.inf
- Figure 4: Package Component Descriptions
- ========================================
- Each compiler assumes, by default, that it will be used with standard libraries
- and headers provided by the compiler vendor. Many of these assumptions are
- incorrect for the UEFI environment. By including a BuildOptions section, as
- shown in Figure 5: Package Build Options, these assumptions can be
- tailored for compatibility with UEFI and the EDK II Standard Libraries.
- Note that the set of BuildOptions used is determined by the state of the EMULATE macro.
- [BuildOptions]
- !ifndef $(EMULATE)
- # These Build Options are used when building the Standard Libraries to be run
- # on real hardware.
- INTEL:*_*_IA32_CC_FLAGS = /Qfreestanding
- MSFT:*_*_IA32_CC_FLAGS = /X /Zc:wchar_t
- GCC:*_*_IA32_CC_FLAGS = -nostdinc -nostdlib
- !else
- # The Build Options, below, are only used when building the Standard Libraries
- # to be run under an emulation environment.
- # They disable optimization which facillitates debugging under the Emulation environment.
- INTEL:*_*_IA32_CC_FLAGS = /Od
- MSFT:*_*_IA32_CC_FLAGS = /Od
- GCC:*_*_IA32_CC_FLAGS = -O0
- Figure 5: Package Build Options
- ===============================
- INF Files
- =========
- The INF files for most modules will not require special directives in order to
- support the Standard Libraries. The two sections which require attention: LibraryClasses
- and BuildOptions, are described below.
- [LibraryClasses]
- UefiLib
- LibC
- LibString
- LibStdio
- DevShell
- Figure 6: Module Library Classes
- ================================
- Modules of type UEFI_APPLICATION that perform file I/O must include library
- class DevShell. Including this library class will allow file operations to be
- handled by the UEFI Shell. Without this class, only Console I/O is supported.
- An application's INF file might need to include a [BuildOptions] section
- specifying additional compiler and linker flags necessary to allow the
- application to be built. Usually, this section is not needed. When building
- code from external sources, though, it may be necessary to disable some
- warnings or enable/disable some compiler features.
- [BuildOptions]
- INTEL:*_*_*_CC_FLAGS = /Qdiag-disable:181,186
- MSFT:*_*_*_CC_FLAGS = /Oi- /wd4018 /wd4131
- GCC:*_*_IPF_SYMRENAME_FLAGS = --redefine-syms=Rename.txt
- Figure 7: Module Build Options
- ==============================
- TARGET-SYSTEM INSTALLATION
- ==========================
- Applications that use file system features or the Socket library depend upon
- the existence of a specific directory tree structure on the same volume that
- the application was loaded from. This tree structure is described below:
- /EFI Root of the UEFI system area.
- |- /Tools Directory containing applications.
- |- /Boot UEFI specified Boot directory.
- |- /StdLib Root of the Standard Libraries sub-tree.
- |- /etc Configuration files used by libraries.
- |- /tmp Temporary files created by tmpfile(), etc.
- The /Efi/StdLib/etc directory must be manually populated from the StdLib/Efi/etc source
- directory.
- IMPLEMENTATION-Specific Features
- ================================
- It is very strongly recommended that applications not use the long or
- unsigned long types. The size of these types varies between compilers and is one
- of the less portable aspects of C. Instead, one should use the UEFI defined
- types whenever possible. Use of these types, listed below for reference,
- ensures that the declared objects have unambiguous, explicitly declared, sizes
- and characteristics.
- UINT64 INT64 UINT32 INT32 UINT16 CHAR16
- INT16 BOOLEAN UINT8 CHAR8 INT8
- UINTN INTN PHYSICALADDRESS
- There are similar types declared in sys/types.h and related files.
- The types UINTN and INTN have the native width of the target processor
- architecture. Thus, INTN on IA32 has a width of 32 bits while INTN on X64 and
- IPF has a width of 64 bits.
- For maximum portability, data objects intended to hold addresses should be
- declared with type intptr_t or uintptr_t. These types, declared in
- sys/stdint.h, can be used to create objects capable of holding pointers. Note
- that these types will generate different sized objects on different processor
- architectures. If a constant size across all processors and compilers is
- needed, use type PHYSICAL_ADDRESS.
- Though not specifically required by the ISO/IEC 9899 standard, this
- implementation of the Standard C Library provides the following system calls
- which are declared in sys/EfiSysCall.h and/or unistd.h.
- close creat chmod dup dup2
- fcntl fstat getcwd ioctl isatty
- lseek lstat mkdir open poll
- read rename rmdir stat unlink write
- The open function will accept file names of "stdin:", "stdout:", and "stderr:"
- which cause the respective streams specified in the UEFI System Table to be
- opened. Normally, these are associated with the console device. When the
- application is first started, these streams are automatically opened on File
- Descriptors 0, 1, and 2 respectively.
- # # #
|