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