From 274402de4642937735918e6c756777c40524957d Mon Sep 17 00:00:00 2001 From: darylm503 Date: Tue, 2 Aug 2011 23:09:06 +0000 Subject: Add plain-text ReadMe files and delete the PDF version. Clean up some comments. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@12080 6f19259b-4bc3-4df7-8a09-765794883524 --- AppPkg/ReadMe.txt | 443 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 443 insertions(+) create mode 100644 AppPkg/ReadMe.txt (limited to 'AppPkg/ReadMe.txt') diff --git a/AppPkg/ReadMe.txt b/AppPkg/ReadMe.txt new file mode 100644 index 0000000000..731b18da5b --- /dev/null +++ b/AppPkg/ReadMe.txt @@ -0,0 +1,443 @@ + EDK II Standard Libraries + ReadMe + Beta Release + 4:03 PM 8/2/2011 + + +OVERVIEW +======== +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 Library. + 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.1 interpreter for UEFI. This + application is disabled by default. Un-comment the line for + PythonCore.inf in the [Components] section of AppPkg.dsc to + enable building Python. + + Sockets A collection of applications demonstrating use of the + EDK II Socket Libraries. These applications include: + + * DataSink + * DataSource + * GetHostByAddr + * GetHostByDns + * GetHostByName + * GetNetByAddr + * GetNetByName + * GetServByName + * GetServByPort + * RecvDgram + * SetHostName + * SetSockOpt + * TftpServer + * WebServer + + StdLib The StdLib package contains the standard header files as well as + implementations of the standard libraries. + + 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 +============= +This release of the EADK has some restrictions, as described below. + + 1. Only the Microsoft VS2005 and VS2008, Intel C Compiler 10.1 (or later), + GCC 4.3 (mingw32), GCC 4.4, and GCC 4.5 C compilers are supported for + Ia32 or X64 CPU architectures. + + 2. The target machine must be running firmware which provides the + UEFI 2.3 HII protocol. + + 3. The EADK has not been through Intel's Quality Assurance process. This + means that specified standards compliance has not been validated, nor + has it undergone formal functionality testing. + + 4. Applications must be launched from within the EFI Shell. + + 5. All file paths must use the forward slash, '/', as the separator + character. + + 6. 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. + + 7. 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 starts, there is NO selected volume. + + 8. 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. + +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. + + +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. + +The Python 2.7.1 distribution must be downloaded from python.org before the +Python application can be built. Extracting Python-2.7.1.tgz into the +AppPkg\Applications\Python directory will produce a Python-2.7.1 directory +containing the Python distribution. Python files that had to be modified for +EDK II are in the AppPkg\Applications\Python\PyMod-2.7.1 directory. These +files need to be copied into the corresponding directories within Python-2.7.1. + +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. + + +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. + + +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 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 + ============================ + + +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. + +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. + + +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. + +Each affected section of the DSC file is described below. + + [LibraryClasses] + # + # Common Libraries + # + BaseLib|MdePkg/Library/BaseLib/BaseLib.inf + BaseMemoryLib|MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf + + TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf + # To run in an emulation environment, such as NT32, comment out + # the TimerLib description above and un-comment the line below. + # TimerLib| MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf + + # + # C Standard Libraries + # + LibC|StdLib/LibC/LibC.inf + LibStdLib|StdLib/LibC/StdLib/StdLib.inf + LibString|StdLib/LibC/String/String.inf + LibWchar|StdLib/LibC/Wchar/Wchar.inf + LibCType|StdLib/LibC/Ctype/Ctype.inf + LibTime|StdLib/LibC/Time/Time.inf + LibStdio|StdLib/LibC/Stdio/Stdio.inf + LibGdtoa|StdLib/LibC/gdtoa/gdtoa.inf + LibLocale|StdLib/LibC/Locale/Locale.inf + LibUefi|StdLib/LibC/Uefi/Uefi.inf + LibMath|StdLib/LibC/Math/Math.inf + LibSignal|StdLib/LibC/Signal/Signal.inf + LibNetUtil|StdLib/LibC/LibGcc/LibGcc.inf + + # Libraries for device abstractions within the Standard C Library. + # Applications should not directly access any functions defined + # in these libraries. + DevUtility|StdLib/LibC/Uefi/Devices/daUtility.inf + DevConsole|StdLib/LibC/Uefi/Devices/daConsole.inf + DevShell|StdLib/LibC/Uefi/Devices/daShell.inf + + Figure 1: Library Class Descriptions + ==================================== + + +Descriptions of the Library Classes comprising the Standard Libraries must be +included in your application package's DSC file, as shown in Figure 1: Library +Class Descriptions, above. + +The directives in Figure 2: 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. + + [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- + } + + Figure 2: Package Component Descriptions + ======================================== + + +The NULL TimerLib instance must be selected if you desire to run your +application under an emulation environment -- unless there is a supported +TimerLib for that environment. For example, the InOsEmuPkg provides a +DxeTimerLib which can be used for the TimerLib instance. + +The "boilerplate" text in StdLib.inc will automatically adjust which Timer +Library is instantiated based upon whether the $(EMULATE) macro has been +defined, or not. + + ### + # Select the correct TimerLib instance depending upon whether running under + # an emulation environment, or not. + !ifndef $(EMULATE) + # Not running in an Emulation Environment + [LibraryClasses.IA32.UEFI_APPLICATION] + TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf + + [LibraryClasses.X64.UEFI_APPLICATION] + TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf + + [LibraryClasses.IPF.UEFI_APPLICATION] + PalLib|MdePkg/Library/UefiPalLib/UefiPalLib.inf + TimerLib|MdePkg/Library/SecPeiDxeTimerLibCpu/SecPeiDxeTimerLibCpu.inf + + !else + # Use this instance if Running in an Emulation Environment. + [LibraryClasses.Common.UEFI_APPLICATION] + TimerLib|MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf + !endif + + Figure 3: Timer Library Selection + ================================= + + +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 3: Package Build Options, these assumptions can be +tailored for compatibility with UEFI and the EDK II Standard Libraries. + + [BuildOptions] + INTEL:*_*_IA32_CC_FLAGS = /Qfreestanding + MSFT:*_*_IA32_CC_FLAGS = /X /Zc:wchar_t + GCC:*_*_IA32_CC_FLAGS = /ffreestanding ?nostdinc ?nostdlib + + # The Build Options, below, are only used when building the C library + # to be run under an emulation environment. The clock() system call + # is modified to return -1 indicating that it is unsupported. + # Just un-comment the lines below and select the correct + # TimerLib instance, above. + + # INTEL:*_*_IA32_CC_FLAGS = /D NT32dvm + # MSFT:*_*_IA32_CC_FLAGS = /D NT32dvm + # GCC:*_*_IA32_CC_FLAGS = -DNT32dvm + + Figure 4: Package Build Options + =============================== + +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 "boilerplate" text as follows: + + # Include Boilerplate text required for building with the Standard Libraries. + # + ############################################################################# + !include StdLib/StdLib.inc + + Figure 5: "Boilerplate" Inclusion + ================================= + + +INF Files +========= +The INF files for most modules will not require special directives in order to +support the Standard Libraries. The two cases which could occur are described +below. + + [LibraryClasses] + UefiLib + LibC + LibString + LibStdio + DevShell + + Figure 6: Module Library Classes + ================================ + + +Modules of type UEFI_APPLICATION that perform file I/O should 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 permitted. + + [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 + ============================== + + +An application's INF file may 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. + + +IMPLEMENTATION-Specific Features +================================ +It is very strongly recommended that applications not use the long or +unsigned long types. The size of this type 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. + + close 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. + + -- cgit v1.2.3