X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=blobdiff_plain;f=AppPkg%2FReadMe.txt;fp=AppPkg%2FReadMe.txt;h=0000000000000000000000000000000000000000;hp=d0e53535d10fbe4d2ea67ee7f6d97591d8efb757;hb=964f432b9b0afe103c41c7613fade3e699118afe;hpb=e2d3a25f1a3135221a9c8061e1b8f90245d727eb diff --git a/AppPkg/ReadMe.txt b/AppPkg/ReadMe.txt deleted file mode 100644 index d0e53535d1..0000000000 --- a/AppPkg/ReadMe.txt +++ /dev/null @@ -1,513 +0,0 @@ - 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. - - Lua A port of the Lua-5.2.3 interpreter for UEFI. This - application is disabled by default. Un-comment the line for - LuaLib.inf in the [LibraryClasses] section and Lua.inf in the - [Components] section of AppPkg.dsc to enable building Lua. - - OrderedCollectionTest A small Standard C Library application that - demonstrates the use of the OrderedCollectionLib library class - (provided by the BaseOrderedCollectionRedBlackTreeLib library - instance in this application), and allows the user to "fuzz" the - library with interactive or scripted API calls. - - 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 . 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 { - - MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL- - } - MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf { - - 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. - - # # #