StdLib/Include/paths.h: Update paths to reflect new base of \Efi\StdLib.

[mirror_edk2.git] / StdLibPrivateInternalFiles / ReadMe.txt

                           EDK II Standard Libraries\r
                                    ReadMe\r
                                 Beta Release\r
                               4:03 PM 8/2/2011\r
\r
\r
OVERVIEW\r
========\r
This document describes the EDK II specific aspects of installing, building, and\r
using the Standard C Library component of the EDK II Application Development\r
Kit, EADK.\r
\r
The EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateInternalFiles.\r
\r
  AppPkg   This package contains applications which demonstrate use of the\r
           Standard C Library.\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.1 interpreter for UEFI.  This\r
               application is disabled by default.  Un-comment the line for\r
               PythonCore.inf in the [Components] section of AppPkg.dsc to\r
               enable building Python.\r
\r
      Sockets  A collection of applications demonstrating use of the\r
               EDK II Socket Libraries.  These applications include:\r
\r
               *   DataSink\r
               *   DataSource\r
               *   GetHostByAddr\r
               *   GetHostByDns\r
               *   GetHostByName\r
               *   GetNetByAddr\r
               *   GetNetByName\r
               *   GetServByName\r
               *   GetServByPort\r
               *   RecvDgram\r
               *   SetHostName\r
               *   SetSockOpt\r
               *   TftpServer\r
               *   WebServer\r
\r
  StdLib   The StdLib package contains the standard header files as well as\r
           implementations of the standard libraries.\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
This release of the EADK has some restrictions, as described below.\r
\r
    1.	Only the Microsoft VS2005 and VS2008, Intel C Compiler 10.1 (or later),\r
        GCC 4.3 (mingw32), GCC 4.4, and GCC 4.5 C compilers are supported for\r
        Ia32 or X64 CPU architectures.\r
        \r
    2.	The target machine must be running firmware which provides the\r
        UEFI 2.3 HII protocol.\r
        \r
    3.	The EADK has not been through Intel's Quality Assurance process. This\r
        means that specified standards compliance has not been validated, nor\r
        has it undergone formal functionality testing.\r
        \r
    4.	Applications must be launched from within the EFI Shell.\r
    \r
    5.	All file paths must use the forward slash, '/', as the separator\r
        character.\r
        \r
    6.	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
    7.	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 starts, there is NO selected volume.\r
        \r
    8.	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.\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
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
The Python 2.7.1 distribution must be downloaded from python.org before the\r
Python application can be built.  Extracting Python-2.7.1.tgz into the\r
AppPkg\Applications\Python directory will produce a Python-2.7.1 directory\r
containing the Python distribution.  Python files that had to be modified for\r
EDK II are in the AppPkg\Applications\Python\PyMod-2.7.1 directory.  These\r
files need to be copied into the corresponding directories within Python-2.7.1.\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
\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
\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 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
\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
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
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
Each affected section of the DSC file is described below.\r
\r
  [LibraryClasses]\r
    #\r
    # Common Libraries\r
    #\r
    BaseLib|MdePkg/Library/BaseLib/BaseLib.inf\r
    BaseMemoryLib|MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf\r
\r
    TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf\r
    # To run in an emulation environment, such as NT32, comment out\r
    # the TimerLib description above and un-comment the line below.\r
    # TimerLib| MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf\r
\r
    #\r
    # C Standard Libraries\r
    #\r
    LibC|StdLib/LibC/LibC.inf\r
    LibStdLib|StdLib/LibC/StdLib/StdLib.inf\r
    LibString|StdLib/LibC/String/String.inf\r
    LibWchar|StdLib/LibC/Wchar/Wchar.inf\r
    LibCType|StdLib/LibC/Ctype/Ctype.inf\r
    LibTime|StdLib/LibC/Time/Time.inf\r
    LibStdio|StdLib/LibC/Stdio/Stdio.inf\r
    LibGdtoa|StdLib/LibC/gdtoa/gdtoa.inf\r
    LibLocale|StdLib/LibC/Locale/Locale.inf\r
    LibUefi|StdLib/LibC/Uefi/Uefi.inf\r
    LibMath|StdLib/LibC/Math/Math.inf\r
    LibSignal|StdLib/LibC/Signal/Signal.inf\r
    LibNetUtil|StdLib/LibC/LibGcc/LibGcc.inf\r
\r
  # Libraries for device abstractions within the Standard C Library.\r
  # Applications should not directly access any functions defined\r
  # in these libraries.\r
    DevUtility|StdLib/LibC/Uefi/Devices/daUtility.inf\r
    DevConsole|StdLib/LibC/Uefi/Devices/daConsole.inf\r
    DevShell|StdLib/LibC/Uefi/Devices/daShell.inf\r
\r
                     Figure 1: Library Class Descriptions\r
                     ====================================\r
\r
\r
Descriptions of the Library Classes comprising the Standard Libraries must be\r
included in your application package's DSC file, as shown in Figure 1: Library\r
Class Descriptions, above.\r
\r
The directives in Figure 2: 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
  [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
                    Figure 2: Package Component Descriptions\r
                    ========================================\r
\r
\r
The NULL TimerLib instance must be selected if you desire to run your\r
application under an emulation environment -- unless there is a supported\r
TimerLib for that environment.  For example, the InOsEmuPkg provides a\r
DxeTimerLib which can be used for the TimerLib instance.\r
\r
The "boilerplate" text in StdLib.inc will automatically adjust which Timer\r
Library is instantiated based upon whether the $(EMULATE) macro has been\r
defined, or not.\r
\r
  ###\r
  # Select the correct TimerLib instance depending upon whether running under\r
  # an emulation environment, or not.\r
  !ifndef $(EMULATE)\r
    # Not running in an Emulation Environment\r
  [LibraryClasses.IA32.UEFI_APPLICATION]\r
    TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf\r
\r
  [LibraryClasses.X64.UEFI_APPLICATION]\r
    TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf\r
\r
  [LibraryClasses.IPF.UEFI_APPLICATION]\r
    PalLib|MdePkg/Library/UefiPalLib/UefiPalLib.inf\r
    TimerLib|MdePkg/Library/SecPeiDxeTimerLibCpu/SecPeiDxeTimerLibCpu.inf\r
\r
  !else\r
    # Use this instance if Running in an Emulation Environment.\r
  [LibraryClasses.Common.UEFI_APPLICATION]\r
    TimerLib|MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf\r
  !endif\r
\r
                      Figure 3: Timer Library Selection\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 3: Package Build Options, these assumptions can be\r
tailored for compatibility with UEFI and the EDK II Standard Libraries.\r
\r
  [BuildOptions]\r
    INTEL:*_*_IA32_CC_FLAGS  = /Qfreestanding\r
     MSFT:*_*_IA32_CC_FLAGS  = /X /Zc:wchar_t\r
      GCC:*_*_IA32_CC_FLAGS  = /ffreestanding ?nostdinc ?nostdlib\r
\r
  # The Build Options, below, are only used when building the C library\r
  # to be run under an emulation environment.  The clock() system call\r
  # is modified to return -1 indicating that it is unsupported.\r
  # Just un-comment the lines below and select the correct\r
  # TimerLib instance, above.\r
\r
    # INTEL:*_*_IA32_CC_FLAGS  = /D NT32dvm\r
    #  MSFT:*_*_IA32_CC_FLAGS  = /D NT32dvm\r
    #   GCC:*_*_IA32_CC_FLAGS  = -DNT32dvm\r
\r
                        Figure 4: Package Build Options\r
                        ===============================\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 "boilerplate" text as follows:\r
\r
  # Include Boilerplate text required for building with the Standard Libraries.\r
  #\r
  #############################################################################\r
  !include StdLib/StdLib.inc\r
\r
                      Figure 5: "Boilerplate" Inclusion\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 cases which could occur are described\r
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 should 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 permitted.\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
An application's INF file may 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
\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 this type 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.\r
\r
          close   dup      dup2     fcntl\r
          fstat   getcwd   ioctl    isatty\r
          lseek   lstat    mkdir    open\r
          poll    read     rename   rmdir\r
          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