uefi/linaro-edk2/AppPkg/ReadMe.txt

                                     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 <paths.h>.  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 {
      <BuildOptions>
        MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-
    }
    MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf {
      <BuildOptions>
        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.

                            # # #