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