ReadMe.txt revision 4fd606d1f5abe38e1f42c38de1d2e895166bd0f4
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync EDK II Standard Libraries
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Beta Release
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync 4:03 PM 8/2/2011
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncThis document describes the EDK II specific aspects of installing, building, and
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncusing the Standard C Library component of the EDK II Application Development
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncThe EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateInternalFiles.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync AppPkg This package contains applications which demonstrate use of the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Standard C Library.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync These applications reside in AppPkg/Applications.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Enquire This is a program that determines many properties of the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync C compiler and the target machine that Enquire is run on. The
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync only changes required to port this 1990s era Unix program to
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync EDK II were the addition of eight pragmas to enquire.c in
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync order to disable some Microsoft VC++ specific warnings.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Hello This is a very simple EDK II native application that doesn't use
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync any features of the Standard C Library.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Main This application is functionally identical to Hello, except that
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync it uses the Standard C Library to provide a main() entry point.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Python A port of the Python-2.7.1 interpreter for UEFI. This
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync application is disabled by default. Un-comment the line for
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync PythonCore.inf in the [Components] section of AppPkg.dsc to
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync enable building Python.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Sockets A collection of applications demonstrating use of the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync EDK II Socket Libraries. These applications include:
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync * DataSource
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync * GetHostByAddr
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync * GetHostByDns
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync * GetHostByName
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync * GetNetByAddr
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync * GetNetByName
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync * GetServByName
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync * GetServByPort
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync * RecvDgram
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync * SetHostName
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync * SetSockOpt
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync * TftpServer
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync * WebServer
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync StdLib The StdLib package contains the standard header files as well as
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync implementations of the standard libraries.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync StdLibPrivateInternalFiles The contents of this package are for the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync exclusive use of the library implementations in StdLib. Please do
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync not use anything from this package in your application or else
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync unexpected behavior may occur.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This package may be removed in a future release.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncRELEASE NOTES
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync=============
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncThis release of the EADK has some restrictions, as described below.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync 1. Only the Microsoft VS2005 and VS2008, Intel C Compiler 10.1 (or later),
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync GCC 4.3 (mingw32), GCC 4.4, and GCC 4.5 C compilers are supported for
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Ia32 or X64 CPU architectures.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync 2. The target machine must be running firmware which provides the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync UEFI 2.3 HII protocol.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync 3. The EADK has not been through Intel's Quality Assurance process. This
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync means that specified standards compliance has not been validated, nor
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync has it undergone formal functionality testing.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync 4. Applications must be launched from within the EFI Shell.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync 5. All file paths must use the forward slash, '/', as the separator
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync 6. Absolute file paths may optionally be prefixed by a volume specifier
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync such as "FS0:". The volume specifier is separated from the remainder
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync of the path by a single colon ':'. The volume specifier must be one of
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync the Shell's mapped volume names as shown by the "map" command.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync 7. Absolute file paths that don't begin with a volume specifier;
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync e.g. paths that begin with "/", are relative to the currently selected
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync volume. When the EFI Shell starts, there is NO selected volume.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync 8. The tmpfile(), and related, functions require that the current volume
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync have a temporary directory as specified in <paths.h>. This directory
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync is specified by macro _PATH_TMP.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncThe Standard C Library provided by this package is a "hosted" implementation
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncconforming to the ISO/IEC 9899-1990 C Language Standard with Addendum 1. This
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncis commonly referred to as the "C 95" specification or ISO/IEC 9899:199409.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncThe following instructions assume that you have an existing EDK II or UDK 2010
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncsource tree that has been configured to build with your tool chain. For
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncconvenience, it is assumed that your EDK II source tree is located at
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncC:\Source\Edk2.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncINSTALLATION
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync============
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncThe EADK is integrated within the EDK II source tree and is included with
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynccurrent EDK II check-outs. If they are missing from your tree, they may be
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncinstalled by extracting, downloading or copying them to the root of your EDK II
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncsource tree. The three package directories should be peers to the Conf,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncMdePkg, Nt32Pkg, etc. directories.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncThe Python 2.7.1 distribution must be downloaded from python.org before the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncPython application can be built. Extracting Python-2.7.1.tgz into the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncAppPkg\Applications\Python directory will produce a Python-2.7.1 directory
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynccontaining the Python distribution. Python files that had to be modified for
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncEDK II are in the AppPkg\Applications\Python\PyMod-2.7.1 directory. These
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncfiles need to be copied into the corresponding directories within Python-2.7.1.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncThere are some boiler-plate declarations and definitions that need to be
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncincluded in your application's INF and DSC build files. These are described
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncin the CONFIGURATION section, below.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncIt is not necessary to build the libraries separately from the target
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncapplication(s). If the application references the libraries, as described in
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncUSAGE, below; the required libraries will be built as needed.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncTo build the applications included in AppPkg, one would execute the following
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynccommands within the "Visual Studio Command Prompt" window:
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync > cd C:\Source\Edk2
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync > build ?a X64 ?p AppPkg\AppPkg.dsc
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncThis will produce the application executables: Enquire.efi, Hello.efi, and
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncMain.efi in the C:\Source\Edk2\Build\AppPkg\DEBUG_VS2008\X64 directory; with
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncthe DEBUG_VS2008 component being replaced with the actual tool chain and build
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynctype you have selected in Conf\Tools_def.txt. These executables can now be
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncloaded onto the target platform and executed.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncIf you examine the AppPkg.dsc file, you will notice that the StdLib package is
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncreferenced in order to resolve the library classes comprising the Standard
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncC Library. This, plus referencing the StdLib package in your application's
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync.inf file is all that is needed to link your application to the standard
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncThis implementation of the Standard C Library is comprised of 16 separate
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynclibraries in addition to the standard header files. Nine of the libraries are
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncassociated with use of one of the standard headers; thus, if the header is used
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncin an application, it must be linked with the associated library. Three
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynclibraries are used to provide the Console and File-system device abstractions.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncThe libraries and associated header files are described in the following table.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Class Header File(s) Notes
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync---------- ---------------- -------------------------------------------------
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncLibC -- Use Always -- This library is always required.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncLibCtype ctype.h, wctype.h Character classification and mapping
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncLibLocale locale.h Localization types, macros, and functions
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncLibMath math.h Mathematical functions, types, and macros
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncLibStdio stdio.h Standard Input and Output functions, types, and
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncLibStdLib stdlib.h General Utilities for numeric conversion, random
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncLibString string.h String copying, concatenation, comparison,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncLibSignal signal.h Functions and types for handling run-time
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncLibTime time.h Time and Date types, macros, and functions
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncLibUefi sys/EfiSysCall.h Provides the UEFI system interface and
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync "System Calls"
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncLibWchar wchar.h Extended multibyte and wide character utilities
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncLibNetUtil Network address and number manipulation utilities
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncDevConsole Automatically provided File I/O abstractions for
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync the UEFI Console device. No need to list this
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync library class in your INF file(s).
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncDevShell Add if desired File I/O abstractions using UEFI shell
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync facilities. Add this to the application's main
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync INF file if file-system access needed.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncDevUtility -- Do Not Use -- Utility functions used by the Device abstractions
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncLibGdtoa -- Do Not Use -- This library is used internally and should not
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync need to be explicitly specified by an
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync application. It must be defined as one of the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync available library classes in the application's
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Table 1: Standard Libraries
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync ============================
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncThese libraries must be fully described in the [LibraryClasses] section of the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncapplication package's DSC file. Then, each individual application needs to
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncspecify which libraries to link to by specifying the Library Class, from the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncabove table, in the [LibraryClasses] section of the application's INF file. The
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncAppPkg.dsc, StdLib.dsc, and Enquire.inf files provide good examples of this.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncMore details are in the CONFIGURATION section, below.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncWithin the source files of the application, use of the Standard headers and
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynclibrary functions follow standard C programming practices as formalized by
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncISO/IEC 9899:1990, with Addendum 1, (C 95) C language specification.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncCONFIGURATION
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync=============
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncAll EDK II packages which build applications that use the standard libraries
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncmust include some "boilerplate" text in the package's .dsc file. To make it
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynceasier, and to reduce cut-and-paste errors, the "boilerplate" text has been
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncconsolidated into a single file, StdLib/StdLib.inc, which can be included in
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncyour .dsc file using the !include directive. The provided AppPkg.dsc and
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncStdLib.dsc files do this on their last line.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncEach affected section of the DSC file is described below.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync [LibraryClasses]
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # Common Libraries
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync BaseMemoryLib|MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # To run in an emulation environment, such as NT32, comment out
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # the TimerLib description above and un-comment the line below.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # TimerLib| MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # C Standard Libraries
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # Libraries for device abstractions within the Standard C Library.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # Applications should not directly access any functions defined
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # in these libraries.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Figure 1: Library Class Descriptions
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync ====================================
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncDescriptions of the Library Classes comprising the Standard Libraries must be
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncincluded in your application package's DSC file, as shown in Figure 1: Library
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncClass Descriptions, above.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncThe directives in Figure 2: Package Component Descriptions will create
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncinstances of the BaseLib and BaseMemoryLib library classes that are built
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncwith Link-time-Code-Generation disabled. This is necessary when using the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncMicrosoft tool chains in order to allow the library's functions to be
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncresolved during the second pass of the linker during Link-Time-Code-Generation
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncof the application.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync [Components]
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # BaseLib and BaseMemoryLib need to be built with the /GL- switch
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # when using the Microsoft tool chains. This is required so that
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # the library functions can be resolved during the second pass of
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # the linker during link-time-code-generation.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync <BuildOptions>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync <BuildOptions>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Figure 2: Package Component Descriptions
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync ========================================
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncThe NULL TimerLib instance must be selected if you desire to run your
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncapplication under an emulation environment -- unless there is a supported
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncTimerLib for that environment. For example, the InOsEmuPkg provides a
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncDxeTimerLib which can be used for the TimerLib instance.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncThe "boilerplate" text in StdLib.inc will automatically adjust which Timer
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncLibrary is instantiated based upon whether the $(EMULATE) macro has been
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncdefined, or not.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # Select the correct TimerLib instance depending upon whether running under
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # an emulation environment, or not.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync !ifndef $(EMULATE)
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # Not running in an Emulation Environment
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync TimerLib|MdePkg/Library/SecPeiDxeTimerLibCpu/SecPeiDxeTimerLibCpu.inf
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # Use this instance if Running in an Emulation Environment.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync TimerLib|MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Figure 3: Timer Library Selection
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync =================================
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncEach compiler assumes, by default, that it will be used with standard libraries
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncand headers provided by the compiler vendor. Many of these assumptions are
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncincorrect for the UEFI environment. By including a BuildOptions section, as
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncshown in Figure 3: Package Build Options, these assumptions can be
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynctailored for compatibility with UEFI and the EDK II Standard Libraries.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync [BuildOptions]
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync INTEL:*_*_IA32_CC_FLAGS = /Qfreestanding
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync MSFT:*_*_IA32_CC_FLAGS = /X /Zc:wchar_t
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync GCC:*_*_IA32_CC_FLAGS = /ffreestanding ?nostdinc ?nostdlib
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # The Build Options, below, are only used when building the C library
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # to be run under an emulation environment. The clock() system call
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # is modified to return -1 indicating that it is unsupported.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # Just un-comment the lines below and select the correct
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # TimerLib instance, above.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # INTEL:*_*_IA32_CC_FLAGS = /D NT32dvm
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # MSFT:*_*_IA32_CC_FLAGS = /D NT32dvm
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # GCC:*_*_IA32_CC_FLAGS = -DNT32dvm
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Figure 4: Package Build Options
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync ===============================
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncThe "boilerplate" text can be included using a !include directive in the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncpackage's .dsc file. The provided AppPkg.dsc and StdLib.dsc files include
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncthe "boilerplate" text as follows:
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync # Include Boilerplate text required for building with the Standard Libraries.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync #############################################################################
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Figure 5: "Boilerplate" Inclusion
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync =================================
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncThe INF files for most modules will not require special directives in order to
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncsupport the Standard Libraries. The two cases which could occur are described
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync [LibraryClasses]
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Figure 6: Module Library Classes
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync ================================
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncModules of type UEFI_APPLICATION that perform file I/O should include library
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncclass DevShell. Including this library class will allow file operations to be
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynchandled by the UEFI Shell. Without this class, only Console I/O is permitted.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync [BuildOptions]
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync INTEL:*_*_*_CC_FLAGS = /Qdiag-disable:181,186
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync MSFT:*_*_*_CC_FLAGS = /Oi- /wd4018 /wd4131
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync GCC:*_*_IPF_SYMRENAME_FLAGS = --redefine-syms=Rename.txt
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Figure 7: Module Build Options
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync ==============================
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncAn application's INF file may need to include a [BuildOptions] section
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncspecifying additional compiler and linker flags necessary to allow the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncapplication to be built. Usually, this section is not needed. When building
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynccode from external sources, though, it may be necessary to disable some
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncwarnings or enable/disable some compiler features.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncIMPLEMENTATION-Specific Features
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync================================
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncIt is very strongly recommended that applications not use the long or
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncunsigned long types. The size of this type varies between compilers and is one
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncof the less portable aspects of C. Instead, one should use the UEFI defined
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynctypes whenever possible. Use of these types, listed below for reference,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncensures that the declared objects have unambiguous, explicitly declared, sizes
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncand characteristics.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync UINT64 INT64 UINT32 INT32 UINT16 CHAR16
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync INT16 BOOLEAN UINT8 CHAR8 INT8
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync UINTN INTN PHYSICALADDRESS
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncThere are similar types declared in sys/types.h and related files.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncThe types UINTN and INTN have the native width of the target processor
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncarchitecture. Thus, INTN on IA32 has a width of 32 bits while INTN on X64 and
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncIPF has a width of 64 bits.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncFor maximum portability, data objects intended to hold addresses should be
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncdeclared with type intptr_t or uintptr_t. These types, declared in
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncsys/stdint.h, can be used to create objects capable of holding pointers. Note
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncthat these types will generate different sized objects on different processor
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncarchitectures. If a constant size across all processors and compilers is
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncneeded, use type PHYSICAL_ADDRESS.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncThough not specifically required by the ISO/IEC 9899 standard, this
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncimplementation of the Standard C Library provides the following system calls
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncwhich are declared in sys/EfiSysCall.h.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync close dup dup2 fcntl
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync fstat getcwd ioctl isatty
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync lseek lstat mkdir open
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync poll read rename rmdir
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync stat unlink write
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncThe open function will accept file names of "stdin:", "stdout:", and "stderr:"
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncwhich cause the respective streams specified in the UEFI System Table to be
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncopened. Normally, these are associated with the console device. When the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncapplication is first started, these streams are automatically opened on File
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncDescriptors 0, 1, and 2 respectively.