StdLib/ReadMe.txt

   1                                      EADK
   2                   EDK II Standard Libraries and Applications
   3                                     ReadMe
   4                                  Version 1.02
   5                                  21 Dec. 2012
   6
   7
   8 OVERVIEW
   9 ========
  10 The EADK (uEfi Application Development Kit) provides a set of standards-based
  11 libraries, along with utility and demonstration applications, intended to
  12 ease development of UEFI applications based upon the EDK II Open-Source
  13 distribution.
  14
  15 At this time, applications developed with the EADK are intended to reside
  16 on, and be loaded from, storage separate from the core firmware.  This is
  17 primarily due to size and environmental requirements.
  18
  19 This release of the EADK should only be used to produce UEFI Applications.  Due to the execution
  20 environment built by the StdLib component, execution as a UEFI driver can cause system stability
  21 issues.
  22
  23 This document describes the EDK II specific aspects of installing, building,
  24 and using the Standard C Library component of the EDK II Application
  25 Development Kit, EADK.
  26
  27 The EADK is comprised of three packages:
  28         AppPkg, StdLib, and StdLibPrivateInternalFiles.
  29
  30   AppPkg   This package contains applications which demonstrate use of the
  31            Standard C and Sockets Libraries.
  32            These applications reside in AppPkg/Applications.
  33
  34       Enquire  This is a program that determines many properties of the
  35                C compiler and the target machine that Enquire is run on.  The
  36                only changes required to port this 1990s era Unix program to
  37                EDK II were the addition of eight pragmas to enquire.c in
  38                order to disable some Microsoft VC++ specific warnings.
  39
  40       Hello    This is a very simple EDK II native application that doesn't use
  41                any features of the Standard C Library.
  42
  43       Main     This application is functionally identical to Hello, except that
  44                it uses the Standard C Library to provide a main() entry point.
  45
  46       Python   A port of the Python-2.7.2 interpreter for UEFI.  Building this
  47                application is disabled by default.
  48                See the PythonReadMe.txt file, in the Python directory,
  49                for information on configuring and building Python.
  50
  51       Sockets  A collection of applications demonstrating use of the
  52                EDK II Socket Libraries.  These applications include:
  53
  54                *   DataSink                     *   DataSource
  55                *   GetAddrInfo                  *   GetHostByAddr
  56                *   GetHostByDns                 *   GetHostByName
  57                *   GetNetByAddr                 *   GetNetByName
  58                *   GetServByName                *   GetServByPort
  59                *   OobRx                        *   OobTx
  60                *   RawIp4Rx                     *   RawIp4Tx
  61                *   RecvDgram                    *   SetHostName
  62                *   SetSockOpt                   *   TftpServer
  63                *   WebServer
  64
  65   StdLib   The StdLib package contains the standard header files as well as
  66            implementations of other standards-based libraries.
  67
  68            *   BsdSocketLib
  69                   Support routines above the sockets layer and C interface for
  70                   the UEFI socket library.
  71            *   Efi
  72                   Template contents for the target system's
  73                   \Efi\StdLib\etc directory.
  74            *   EfiSocketLib
  75                   UEFI socket implementation, may be linked into an
  76                   application or run as a driver.
  77            *   Include
  78                   Standard include files.
  79            *   LibC
  80                   C Standard Library implementation as per
  81                   ISO/IEC 9899:199409 (C95).
  82            *   PosixLib
  83                   Selected functions from the "Single Unix v4" specification.
  84            *   SocketDxe
  85                   UEFI sockets driver, includes EfiSocketLib.
  86            *   UseSocketDxe
  87                   Alternate linkage for applications that get built into the
  88                   firmware.  Cause application to use a common instance of the
  89                   sockets driver instead of including all of sockets into the
  90                   application.
  91
  92   StdLibPrivateInternalFiles  The contents of this package are for the
  93            exclusive use of the library implementations in StdLib.  Please do
  94            not use anything from this package in your application or else
  95            unexpected behavior may occur.
  96            This package may be removed in a future release.
  97
  98
  99 RELEASE NOTES
 100 =============
 101   Fixes and Additions
 102   -------------------
 103 Beginning with release 1.01, applications built with the StdLib package
 104 no longer have a dependency on the TimerLib.
 105
 106   Known Issues
 107   -----------------
 108 This release of the EADK has some restrictions, as described below.
 109
 110     1.  The target machine must be running firmware which provides the
 111         UEFI 2.3 HII protocol.
 112
 113     2.  Applications must be launched from within the EFI Shell.
 114
 115     3.  Absolute file paths may optionally be prefixed by a volume specifier
 116         such as "FS0:".  The volume specifier is separated from the remainder
 117         of the path by a single colon ':'.  The volume specifier must be one of
 118         the Shell's mapped volume names as shown by the "map" command.
 119
 120     4.  Absolute file paths that don't begin with a volume specifier;
 121         e.g. paths that begin with "/", are relative to the currently selected
 122         volume.  When the EFI Shell first starts, there is NO selected volume.
 123
 124     5.  The tmpfile(), and related, functions require that the current volume
 125         have a temporary directory as specified in <paths.h>.  This directory
 126         is specified by macro _PATH_TMP as /Efi/StdLib/tmp.
 127
 128 The Standard C Library provided by this package is a "hosted" implementation
 129 conforming to the ISO/IEC 9899-1990 C Language Standard with Addendum 1. This
 130 is commonly referred to as the "C 95" specification or ISO/IEC 9899:199409.
 131 The following instructions assume that you have an existing EDK II or UDK 2010
 132 source tree that has been configured to build with your tool chain.  For
 133 convenience, it is assumed that your EDK II source tree is located at
 134 C:\Source\Edk2.
 135
 136
 137 EADK INSTALLATION
 138 =================
 139 The EADK is integrated within the EDK II source tree and is included with
 140 current EDK II check-outs.  If they are missing from your tree, they may be
 141 installed by extracting, downloading or copying them to the root of your EDK II
 142 source tree.  The three package directories should be peers to the Conf,
 143 MdePkg, Nt32Pkg, etc. directories.
 144
 145 There are some boiler-plate declarations and definitions that need to be
 146 included in your application's INF and DSC build files.  These are described
 147 in the CONFIGURATION section, below.
 148
 149 A subset of the Python 2.7.2 distribution is included as part of AppPkg.  If desired,
 150 the full Python 2.7.2 distribution may be downloaded from python.org and used instead.
 151 Delete or rename the existing Python-2.7.2 directory then extract the downloaded
 152 Python-2.7.2.tgz file into the AppPkg\Applications\Python directory.  This will produce a
 153 Python-2.7.2 directory containing the full Python distribution.  Python files that had to be
 154 modified for EDK II are in the AppPkg\Applications\Python\PyMod-2.7.2 directory.  These
 155 files need to be copied into the corresponding directories within the extracted Python-2.7.2
 156 directory before Python can be built.
 157
 158
 159 BUILDING
 160 ========
 161 It is not necessary to build the libraries separately from the target
 162 application(s). If the application references the libraries, as described in
 163 USAGE, below; the required libraries will be built as needed.
 164 To build the applications included in AppPkg, one would execute the following
 165 commands within the "Visual Studio Command Prompt" window:
 166
 167     > cd C:\Source\Edk2
 168     > .\edksetup.bat
 169     > build -a X64 -p AppPkg\AppPkg.dsc
 170
 171 This will produce the application executables: Enquire.efi, Hello.efi, and
 172 Main.efi in the C:\Source\Edk2\Build\AppPkg\DEBUG_VS2008\X64 directory; with
 173 the DEBUG_VS2008 component being replaced with the actual tool chain and build
 174 type you have selected in Conf\Tools_def.txt. These executables can now be
 175 loaded onto the target platform and executed.
 176
 177 If you examine the AppPkg.dsc file, you will notice that the StdLib package is
 178 referenced in order to resolve the library classes comprising the Standard
 179 C Library.  This, plus referencing the StdLib package in your application's
 180 .inf file is all that is needed to link your application to the standard
 181 libraries.
 182
 183 Unless explicitly stated as allowed, EADK components should not be added as
 184 components of a DSC file which builds a platform's core firmware.  There are
 185 incompatibilities in build flags and requirements that will conflict with the
 186 requirements of the core firmware.  EADK components should be built using a
 187 separate DSC file then, if absolutely necessary, included as binary components
 188 of other DSC files.
 189
 190 USAGE
 191 =====
 192 This implementation of the Standard C Library is comprised of 16 separate
 193 libraries in addition to the standard header files. Nine of the libraries are
 194 associated with use of one of the standard headers; thus, if the header is used
 195 in an application, it must be linked with the associated library.  Three
 196 libraries are used to provide the Console and File-system device abstractions.
 197 The libraries and associated header files are described in the following table.
 198
 199  Library
 200   Class      Header File(s)    Notes
 201 ----------  ----------------  -------------------------------------------------
 202 LibC        -- Use Always --  This library is always required.
 203 LibCtype    ctype.h, wctype.h Character classification and mapping
 204 LibLocale   locale.h          Localization types, macros, and functions
 205 LibMath     math.h            Mathematical functions, types, and macros
 206 LibStdio    stdio.h           Standard Input and Output functions, types, and
 207                               macros
 208 LibStdLib   stdlib.h          General Utilities for numeric conversion, random
 209                               num., etc.
 210 LibString   string.h          String copying, concatenation, comparison,
 211                               & search
 212 LibSignal   signal.h          Functions and types for handling run-time
 213                               conditions
 214 LibTime     time.h            Time and Date types, macros, and functions
 215 LibUefi     sys/EfiSysCall.h  Provides the UEFI system interface and
 216                               "System Calls"
 217 LibWchar    wchar.h           Extended multibyte and wide character utilities
 218 LibNetUtil                    Network address and number manipulation utilities
 219 DevConsole                    Automatically provided File I/O abstractions for
 220                               the UEFI Console device.  No need to list this
 221                               library class in your INF file(s).
 222 DevShell    Add if desired    File I/O abstractions using UEFI shell
 223                               facilities.  Add this to the application's main
 224                               INF file if file-system access needed.
 225 DevUtility  -- Do Not Use --  Utility functions used internally by the Device abstractions
 226 LibGdtoa    -- Do Not Use --  This library is used internally and should not
 227                               need to be explicitly specified by an
 228                               application.  It must be defined as one of the
 229                               available library classes in the application's
 230                               DSC file.
 231
 232                          Table 1:  Standard Libraries
 233                          ============================
 234
 235 The DevConsole and DevShell libraries provide device I/O functionality and are treated
 236 specially.  DevConsole is automatically included so there is no need to reference it in your
 237 application's DSC or INF files.  DevShell must be listed, in your application's INF file in the
 238 [LibraryClasses] section, if your application does file I/O.
 239
 240 These libraries must be fully described in the [LibraryClasses] section of the
 241 application package's DSC file. Then, each individual application needs to
 242 specify which libraries to link to by specifying the Library Class, from the
 243 above table, in the [LibraryClasses] section of the application's INF file. The
 244 AppPkg.dsc, StdLib.dsc, and Enquire.inf files provide good examples of this.
 245 More details are in the CONFIGURATION section, below.
 246
 247 In order to simplify this process, the [LibraryClasses] definitions, and others, are
 248 specified in the StdLib.inc file.  If this file is included in the DSC file, usually at the
 249 end, then other DSC file changes or additions are unnecessary.  This is further described in
 250 the CONFIGURATION section, below.
 251
 252 Within the source files of the application, use of the Standard headers and
 253 library functions follow standard C programming practices as formalized by
 254 ISO/IEC 9899:1990, with Addendum 1, (C 95) C language specification.
 255
 256
 257 BUILD CONFIGURATION
 258 ===================
 259 DSC Files
 260 ---------
 261
 262 All EDK II packages which build applications that use the standard libraries
 263 must include some "boilerplate" text in the package's .dsc file.  To make it
 264 easier, and to reduce cut-and-paste errors, the "boilerplate" text has been
 265 consolidated into a single file, StdLib/StdLib.inc, which can be included in
 266 your .dsc file using the !include directive.  The provided AppPkg.dsc and
 267 StdLib.dsc files do this on their last line.
 268
 269 The "boilerplate" text can be included using a !include directive in the
 270 package's .dsc file.  The provided AppPkg.dsc and StdLib.dsc files include
 271 the following "boilerplate" text:
 272
 273   ##############################################################################
 274   #
 275   # Specify whether we are running in an emulation environment, or not.
 276   # Define EMULATE if we are, else keep the DEFINE commented out.
 277   #
 278   # DEFINE  EMULATE = 1
 279
 280   ##############################################################################
 281   #
 282   #  Include Boilerplate text required for building with the Standard Libraries.
 283   #
 284   ##############################################################################
 285   !include StdLib/StdLib.inc
 286
 287                       Figure 1: "Boilerplate" Inclusion
 288                       =================================
 289
 290 The EMULATE macro must be defined if one desires to do source-level debugging within one of
 291 the emulated environments such as NT32Pkg or UnixPkg.
 292
 293 The final boilerplate line, in Figure 1, includes the StdLib.inc file.
 294 Each section of StdLib/StdLib.inc is described below.
 295
 296 If desired, all of the Socket applications, in AppPkg, can be built by including Sockets.inc:
 297
 298   !include AppPkg/Applications/Sockets/Sockets.inc
 299
 300               Figure 2: Socket Applications "Boilerplate" Inclusion
 301               =====================================================
 302
 303
 304 Descriptions of the Library Classes comprising the Standard Libraries,
 305 as shown in Figure 3: Library Class Descriptions, are provided.
 306
 307   [LibraryClasses]
 308     #
 309     # C Standard Libraries
 310     #
 311     LibC|StdLib/LibC/LibC.inf
 312     LibCType|StdLib/LibC/Ctype/Ctype.inf
 313     LibLocale|StdLib/LibC/Locale/Locale.inf
 314     LibMath|StdLib/LibC/Math/Math.inf
 315     LibSignal|StdLib/LibC/Signal/Signal.inf
 316     LibStdio|StdLib/LibC/Stdio/Stdio.inf
 317     LibStdLib|StdLib/LibC/StdLib/StdLib.inf
 318     LibString|StdLib/LibC/String/String.inf
 319     LibTime|StdLib/LibC/Time/Time.inf
 320     LibUefi|StdLib/LibC/Uefi/Uefi.inf
 321     LibWchar|StdLib/LibC/Wchar/Wchar.inf
 322
 323   # Common Utilities for Networking Libraries
 324     LibNetUtil|StdLib/LibC/NetUtil/NetUtil.inf
 325
 326   # Additional libraries for POSIX functionality.
 327     LibErr|StdLib/PosixLib/Err/LibErr.inf
 328     LibGen|StdLib/PosixLib/Gen/LibGen.inf
 329     LibGlob|StdLib/PosixLib/Glob/LibGlob.inf
 330     LibStringlist|StdLib/PosixLib/Stringlist/LibStringlist.inf
 331
 332   # Libraries for device abstractions within the Standard C Library
 333   # Applications should not directly access any functions defined in these libraries.
 334     LibGdtoa|StdLib/LibC/gdtoa/gdtoa.inf
 335     DevConsole|StdLib/LibC/Uefi/Devices/daConsole.inf
 336     DevShell|StdLib/LibC/Uefi/Devices/daShell.inf
 337     DevUtility|StdLib/LibC/Uefi/Devices/daUtility.inf
 338
 339   [LibraryClasses.ARM.UEFI_APPLICATION]
 340     NULL|ArmPkg/Library/CompilerIntrinsicsLib/CompilerIntrinsicsLib.inf
 341
 342                      Figure 3: Library Class Descriptions
 343                      ====================================
 344
 345
 346 The directives in Figure 4: Package Component Descriptions will create
 347 instances of the BaseLib and BaseMemoryLib library classes that are built
 348 with Link-time-Code-Generation disabled.  This is necessary when using the
 349 Microsoft tool chains in order to allow the library's functions to be
 350 resolved during the second pass of the linker during Link-Time-Code-Generation
 351 of the application.
 352
 353 A DXE driver version of the Socket library is also built.
 354
 355   [Components]
 356   # BaseLib and BaseMemoryLib need to be built with the /GL- switch
 357   # when using the Microsoft tool chains.  This is required so that
 358   # the library functions can be resolved during the second pass of
 359   # the linker during link-time-code-generation.
 360   #
 361     MdePkg/Library/BaseLib/BaseLib.inf {
 362       <BuildOptions>
 363         MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-
 364     }
 365     MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf {
 366       <BuildOptions>
 367         MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-
 368     }
 369
 370   ##########
 371   #  Socket Layer
 372   ##########
 373     StdLib/SocketDxe/SocketDxe.inf
 374
 375                     Figure 4: Package Component Descriptions
 376                     ========================================
 377
 378
 379 Each compiler assumes, by default, that it will be used with standard libraries
 380 and headers provided by the compiler vendor.  Many of these assumptions are
 381 incorrect for the UEFI environment.  By including a BuildOptions section, as
 382 shown in Figure 5: Package Build Options, these assumptions can be
 383 tailored for compatibility with UEFI and the EDK II Standard Libraries.
 384
 385 Note that the set of BuildOptions used is determined by the state of the EMULATE macro.
 386
 387   [BuildOptions]
 388   !ifndef $(EMULATE)
 389     # These Build Options are used when building the Standard Libraries to be run
 390     # on real hardware.
 391     INTEL:*_*_IA32_CC_FLAGS  = /Qfreestanding
 392      MSFT:*_*_IA32_CC_FLAGS  = /X /Zc:wchar_t
 393       GCC:*_*_IA32_CC_FLAGS  = -nostdinc -nostdlib
 394
 395   !else
 396     # The Build Options, below, are only used when building the Standard Libraries
 397     # to be run under an emulation environment.
 398     # They disable optimization which facillitates debugging under the Emulation environment.
 399     INTEL:*_*_IA32_CC_FLAGS  = /Od
 400      MSFT:*_*_IA32_CC_FLAGS  = /Od
 401       GCC:*_*_IA32_CC_FLAGS  = -O0
 402
 403                         Figure 5: Package Build Options
 404                         ===============================
 405
 406
 407 INF Files
 408 =========
 409 The INF files for most modules will not require special directives in order to
 410 support the Standard Libraries.  The two sections which require attention: LibraryClasses
 411 and BuildOptions, are described below.
 412
 413   [LibraryClasses]
 414     UefiLib
 415     LibC
 416     LibString
 417     LibStdio
 418     DevShell
 419
 420                       Figure 6: Module Library Classes
 421                       ================================
 422
 423
 424 Modules of type UEFI_APPLICATION that perform file I/O must include library
 425 class DevShell.  Including this library class will allow file operations to be
 426 handled by the UEFI Shell.  Without this class, only Console I/O is supported.
 427
 428
 429 An application's INF file might need to include a [BuildOptions] section
 430 specifying additional compiler and linker flags necessary to allow the
 431 application to be built. Usually, this section is not needed.  When building
 432 code from external sources, though, it may be necessary to disable some
 433 warnings or enable/disable some compiler features.
 434
 435  [BuildOptions]
 436   INTEL:*_*_*_CC_FLAGS          = /Qdiag-disable:181,186
 437    MSFT:*_*_*_CC_FLAGS          = /Oi- /wd4018 /wd4131
 438     GCC:*_*_IPF_SYMRENAME_FLAGS = --redefine-syms=Rename.txt
 439
 440                         Figure 7: Module Build Options
 441                         ==============================
 442
 443
 444 TARGET-SYSTEM INSTALLATION
 445 ==========================
 446 Applications that use file system features or the Socket library depend upon
 447 the existence of a specific directory tree structure on the same volume that
 448 the application was loaded from.  This tree structure is described below:
 449
 450     /EFI                      Root of the UEFI system area.
 451      |- /Tools                Directory containing applications.
 452      |- /Boot                 UEFI specified Boot directory.
 453      |- /StdLib               Root of the Standard Libraries sub-tree.
 454          |- /etc              Configuration files used by libraries.
 455          |- /tmp              Temporary files created by tmpfile(), etc.
 456
 457
 458 The /Efi/StdLib/etc directory must be manually populated from the StdLib/Efi/etc source
 459 directory.
 460
 461 IMPLEMENTATION-Specific Features
 462 ================================
 463 It is very strongly recommended that applications not use the long or
 464 unsigned long types. The size of these types varies between compilers and is one
 465 of the less portable aspects of C. Instead, one should use the UEFI defined
 466 types whenever possible. Use of these types, listed below for reference,
 467 ensures that the declared objects have unambiguous, explicitly declared, sizes
 468 and characteristics.
 469
 470         UINT64   INT64     UINT32   INT32   UINT16   CHAR16
 471         INT16    BOOLEAN   UINT8    CHAR8   INT8
 472         UINTN    INTN                       PHYSICALADDRESS
 473
 474 There are similar types declared in sys/types.h and related files.
 475
 476 The types UINTN and INTN have the native width of the target processor
 477 architecture. Thus, INTN on IA32 has a width of 32 bits while INTN on X64 and
 478 IPF has a width of 64 bits.
 479
 480 For maximum portability, data objects intended to hold addresses should be
 481 declared with type intptr_t or uintptr_t. These types, declared in
 482 sys/stdint.h, can be used to create objects capable of holding pointers. Note
 483 that these types will generate different sized objects on different processor
 484 architectures.  If a constant size across all processors and compilers is
 485 needed, use type PHYSICAL_ADDRESS.
 486
 487 Though not specifically required by the ISO/IEC 9899 standard, this
 488 implementation of the Standard C Library provides the following system calls
 489 which are declared in sys/EfiSysCall.h and/or unistd.h.
 490
 491           close   creat    chmod    dup      dup2
 492           fcntl   fstat    getcwd   ioctl    isatty
 493           lseek   lstat    mkdir    open     poll
 494           read    rename   rmdir    stat     unlink   write
 495
 496 The open function will accept file names of "stdin:", "stdout:", and "stderr:"
 497 which cause the respective streams specified in the UEFI System Table to be
 498 opened.  Normally, these are associated with the console device.  When the
 499 application is first started, these streams are automatically opened on File
 500 Descriptors 0, 1, and 2 respectively.
 501
 502                             # # #