StdLibPrivateInternalFiles/ReadMe.txt

   1                            EDK II Standard Libraries
   2                                     ReadMe
   3                                  Beta Release
   4                                4:03 PM 8/2/2011
   5
   6
   7 OVERVIEW
   8 ========
   9 This document describes the EDK II specific aspects of installing, building, and
  10 using the Standard C Library component of the EDK II Application Development
  11 Kit, EADK.
  12
  13 The EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateInternalFiles.
  14
  15   AppPkg   This package contains applications which demonstrate use of the
  16            Standard C Library.
  17            These applications reside in AppPkg/Applications.
  18
  19       Enquire  This is a program that determines many properties of the
  20                C compiler and the target machine that Enquire is run on.  The
  21                only changes required to port this 1990s era Unix program to
  22                EDK II were the addition of eight pragmas to enquire.c in
  23                order to disable some Microsoft VC++ specific warnings.
  24
  25       Hello    This is a very simple EDK II native application that doesn't use
  26                any features of the Standard C Library.
  27
  28       Main     This application is functionally identical to Hello, except that
  29                it uses the Standard C Library to provide a main() entry point.
  30
  31       Python   A port of the Python-2.7.1 interpreter for UEFI.  This
  32                application is disabled by default.  Un-comment the line for
  33                PythonCore.inf in the [Components] section of AppPkg.dsc to
  34                enable building Python.
  35
  36       Sockets  A collection of applications demonstrating use of the
  37                EDK II Socket Libraries.  These applications include:
  38
  39                *   DataSink
  40                *   DataSource
  41                *   GetHostByAddr
  42                *   GetHostByDns
  43                *   GetHostByName
  44                *   GetNetByAddr
  45                *   GetNetByName
  46                *   GetServByName
  47                *   GetServByPort
  48                *   RecvDgram
  49                *   SetHostName
  50                *   SetSockOpt
  51                *   TftpServer
  52                *   WebServer
  53
  54   StdLib   The StdLib package contains the standard header files as well as
  55            implementations of the standard libraries.
  56
  57   StdLibPrivateInternalFiles  The contents of this package are for the
  58            exclusive use of the library implementations in StdLib.  Please do
  59            not use anything from this package in your application or else
  60            unexpected behavior may occur.
  61            This package may be removed in a future release.
  62
  63
  64 RELEASE NOTES
  65 =============
  66 This release of the EADK has some restrictions, as described below.
  67
  68     1.  Only the Microsoft VS2005 and VS2008, Intel C Compiler 10.1 (or later),
  69         GCC 4.3 (mingw32), GCC 4.4, and GCC 4.5 C compilers are supported for
  70         Ia32 or X64 CPU architectures.
  71
  72     2.  The target machine must be running firmware which provides the
  73         UEFI 2.3 HII protocol.
  74
  75     3.  The EADK has not been through Intel's Quality Assurance process. This
  76         means that specified standards compliance has not been validated, nor
  77         has it undergone formal functionality testing.
  78
  79     4.  Applications must be launched from within the EFI Shell.
  80
  81     5.  All file paths must use the forward slash, '/', as the separator
  82         character.
  83
  84     6.  Absolute file paths may optionally be prefixed by a volume specifier
  85         such as "FS0:".  The volume specifier is separated from the remainder
  86         of the path by a single colon ':'.  The volume specifier must be one of
  87         the Shell's mapped volume names as shown by the "map" command.
  88
  89     7.  Absolute file paths that don't begin with a volume specifier;
  90         e.g. paths that begin with "/", are relative to the currently selected
  91         volume.  When the EFI Shell starts, there is NO selected volume.
  92
  93     8.  The tmpfile(), and related, functions require that the current volume
  94         have a temporary directory as specified in <paths.h>.  This directory
  95         is specified by macro _PATH_TMP.
  96
  97 The Standard C Library provided by this package is a "hosted" implementation
  98 conforming to the ISO/IEC 9899-1990 C Language Standard with Addendum 1. This
  99 is commonly referred to as the "C 95" specification or ISO/IEC 9899:199409.
 100 The following instructions assume that you have an existing EDK II or UDK 2010
 101 source tree that has been configured to build with your tool chain.  For
 102 convenience, it is assumed that your EDK II source tree is located at
 103 C:\Source\Edk2.
 104
 105
 106 INSTALLATION
 107 ============
 108 The EADK is integrated within the EDK II source tree and is included with
 109 current EDK II check-outs.  If they are missing from your tree, they may be
 110 installed by extracting, downloading or copying them to the root of your EDK II
 111 source tree.  The three package directories should be peers to the Conf,
 112 MdePkg, Nt32Pkg, etc. directories.
 113
 114 The Python 2.7.1 distribution must be downloaded from python.org before the
 115 Python application can be built.  Extracting Python-2.7.1.tgz into the
 116 AppPkg\Applications\Python directory will produce a Python-2.7.1 directory
 117 containing the Python distribution.  Python files that had to be modified for
 118 EDK II are in the AppPkg\Applications\Python\PyMod-2.7.1 directory.  These
 119 files need to be copied into the corresponding directories within Python-2.7.1.
 120
 121 There are some boiler-plate declarations and definitions that need to be
 122 included in your application's INF and DSC build files.  These are described
 123 in the CONFIGURATION section, below.
 124
 125
 126 BUILDING
 127 ========
 128 It is not necessary to build the libraries separately from the target
 129 application(s). If the application references the libraries, as described in
 130 USAGE, below; the required libraries will be built as needed.
 131 To build the applications included in AppPkg, one would execute the following
 132 commands within the "Visual Studio Command Prompt" window:
 133
 134     > cd C:\Source\Edk2
 135     > .\edksetup.bat
 136     > build ?a X64 ?p AppPkg\AppPkg.dsc
 137
 138 This will produce the application executables: Enquire.efi, Hello.efi, and
 139 Main.efi in the C:\Source\Edk2\Build\AppPkg\DEBUG_VS2008\X64 directory; with
 140 the DEBUG_VS2008 component being replaced with the actual tool chain and build
 141 type you have selected in Conf\Tools_def.txt. These executables can now be
 142 loaded onto the target platform and executed.
 143
 144 If you examine the AppPkg.dsc file, you will notice that the StdLib package is
 145 referenced in order to resolve the library classes comprising the Standard
 146 C Library.  This, plus referencing the StdLib package in your application's
 147 .inf file is all that is needed to link your application to the standard
 148 libraries.
 149
 150
 151 USAGE
 152 =====
 153 This implementation of the Standard C Library is comprised of 16 separate
 154 libraries in addition to the standard header files. Nine of the libraries are
 155 associated with use of one of the standard headers; thus, if the header is used
 156 in an application, it must be linked with the associated library.  Three
 157 libraries are used to provide the Console and File-system device abstractions.
 158 The libraries and associated header files are described in the following table.
 159
 160  Library
 161   Class      Header File(s)    Notes
 162 ----------  ----------------  -------------------------------------------------
 163 LibC        -- Use Always --  This library is always required.
 164 LibCtype    ctype.h, wctype.h Character classification and mapping
 165 LibLocale   locale.h          Localization types, macros, and functions
 166 LibMath     math.h            Mathematical functions, types, and macros
 167 LibStdio    stdio.h           Standard Input and Output functions, types, and
 168                               macros
 169 LibStdLib   stdlib.h          General Utilities for numeric conversion, random
 170                               num., etc.
 171 LibString   string.h          String copying, concatenation, comparison,
 172                               & search
 173 LibSignal   signal.h          Functions and types for handling run-time
 174                               conditions
 175 LibTime     time.h            Time and Date types, macros, and functions
 176 LibUefi     sys/EfiSysCall.h  Provides the UEFI system interface and
 177                               "System Calls"
 178 LibWchar    wchar.h           Extended multibyte and wide character utilities
 179 LibNetUtil                    Network address and number manipulation utilities
 180 DevConsole                    Automatically provided  File I/O abstractions for
 181                               the UEFI Console device.  No need to list this
 182                               library class in your INF file(s).
 183 DevShell    Add if desired    File I/O abstractions using UEFI shell
 184                               facilities.  Add this to the application's main
 185                               INF file if file-system access needed.
 186 DevUtility  -- Do Not Use --  Utility functions used by the Device abstractions
 187 LibGdtoa    -- Do Not Use --  This library is used internally and should not
 188                               need to be explicitly specified by an
 189                               application.  It must be defined as one of the
 190                               available library classes in the application's
 191                               DSC file.
 192
 193                          Table 1:  Standard Libraries
 194                          ============================
 195
 196
 197 These libraries must be fully described in the [LibraryClasses] section of the
 198 application package's DSC file. Then, each individual application needs to
 199 specify which libraries to link to by specifying the Library Class, from the
 200 above table, in the [LibraryClasses] section of the application's INF file. The
 201 AppPkg.dsc, StdLib.dsc, and Enquire.inf files provide good examples of this.
 202 More details are in the CONFIGURATION section, below.
 203
 204 Within the source files of the application, use of the Standard headers and
 205 library functions follow standard C programming practices as formalized by
 206 ISO/IEC 9899:1990, with Addendum 1, (C 95) C language specification.
 207
 208
 209 CONFIGURATION
 210 =============
 211 DSC Files
 212 ---------
 213
 214 All EDK II packages which build applications that use the standard libraries
 215 must include some "boilerplate" text in the package's .dsc file.  To make it
 216 easier, and to reduce cut-and-paste errors, the "boilerplate" text has been
 217 consolidated into a single file, StdLib/StdLib.inc, which can be included in
 218 your .dsc file using the !include directive.  The provided AppPkg.dsc and
 219 StdLib.dsc files do this on their last line.
 220
 221 Each affected section of the DSC file is described below.
 222
 223   [LibraryClasses]
 224     #
 225     # Common Libraries
 226     #
 227     BaseLib|MdePkg/Library/BaseLib/BaseLib.inf
 228     BaseMemoryLib|MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf
 229
 230     TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf
 231     # To run in an emulation environment, such as NT32, comment out
 232     # the TimerLib description above and un-comment the line below.
 233     # TimerLib| MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf
 234
 235     #
 236     # C Standard Libraries
 237     #
 238     LibC|StdLib/LibC/LibC.inf
 239     LibStdLib|StdLib/LibC/StdLib/StdLib.inf
 240     LibString|StdLib/LibC/String/String.inf
 241     LibWchar|StdLib/LibC/Wchar/Wchar.inf
 242     LibCType|StdLib/LibC/Ctype/Ctype.inf
 243     LibTime|StdLib/LibC/Time/Time.inf
 244     LibStdio|StdLib/LibC/Stdio/Stdio.inf
 245     LibGdtoa|StdLib/LibC/gdtoa/gdtoa.inf
 246     LibLocale|StdLib/LibC/Locale/Locale.inf
 247     LibUefi|StdLib/LibC/Uefi/Uefi.inf
 248     LibMath|StdLib/LibC/Math/Math.inf
 249     LibSignal|StdLib/LibC/Signal/Signal.inf
 250     LibNetUtil|StdLib/LibC/LibGcc/LibGcc.inf
 251
 252   # Libraries for device abstractions within the Standard C Library.
 253   # Applications should not directly access any functions defined
 254   # in these libraries.
 255     DevUtility|StdLib/LibC/Uefi/Devices/daUtility.inf
 256     DevConsole|StdLib/LibC/Uefi/Devices/daConsole.inf
 257     DevShell|StdLib/LibC/Uefi/Devices/daShell.inf
 258
 259                      Figure 1: Library Class Descriptions
 260                      ====================================
 261
 262
 263 Descriptions of the Library Classes comprising the Standard Libraries must be
 264 included in your application package's DSC file, as shown in Figure 1: Library
 265 Class Descriptions, above.
 266
 267 The directives in Figure 2: Package Component Descriptions will create
 268 instances of the BaseLib and BaseMemoryLib library classes that are built
 269 with Link-time-Code-Generation disabled.  This is necessary when using the
 270 Microsoft tool chains in order to allow the library's functions to be
 271 resolved during the second pass of the linker during Link-Time-Code-Generation
 272 of the application.
 273
 274   [Components]
 275   # BaseLib and BaseMemoryLib need to be built with the /GL- switch
 276   # when using the Microsoft tool chains.  This is required so that
 277   # the library functions can be resolved during the second pass of
 278   # the linker during link-time-code-generation.
 279   #
 280     MdePkg/Library/BaseLib/BaseLib.inf {
 281       <BuildOptions>
 282         MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-
 283     }
 284     MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf {
 285       <BuildOptions>
 286         MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-
 287     }
 288
 289                     Figure 2: Package Component Descriptions
 290                     ========================================
 291
 292
 293 The NULL TimerLib instance must be selected if you desire to run your
 294 application under an emulation environment -- unless there is a supported
 295 TimerLib for that environment.  For example, the InOsEmuPkg provides a
 296 DxeTimerLib which can be used for the TimerLib instance.
 297
 298 The "boilerplate" text in StdLib.inc will automatically adjust which Timer
 299 Library is instantiated based upon whether the $(EMULATE) macro has been
 300 defined, or not.
 301
 302   ###
 303   # Select the correct TimerLib instance depending upon whether running under
 304   # an emulation environment, or not.
 305   !ifndef $(EMULATE)
 306     # Not running in an Emulation Environment
 307   [LibraryClasses.IA32.UEFI_APPLICATION]
 308     TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf
 309
 310   [LibraryClasses.X64.UEFI_APPLICATION]
 311     TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf
 312
 313   [LibraryClasses.IPF.UEFI_APPLICATION]
 314     PalLib|MdePkg/Library/UefiPalLib/UefiPalLib.inf
 315     TimerLib|MdePkg/Library/SecPeiDxeTimerLibCpu/SecPeiDxeTimerLibCpu.inf
 316
 317   !else
 318     # Use this instance if Running in an Emulation Environment.
 319   [LibraryClasses.Common.UEFI_APPLICATION]
 320     TimerLib|MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf
 321   !endif
 322
 323                       Figure 3: Timer Library Selection
 324                       =================================
 325
 326
 327 Each compiler assumes, by default, that it will be used with standard libraries
 328 and headers provided by the compiler vendor.  Many of these assumptions are
 329 incorrect for the UEFI environment.  By including a BuildOptions section, as
 330 shown in Figure 3: Package Build Options, these assumptions can be
 331 tailored for compatibility with UEFI and the EDK II Standard Libraries.
 332
 333   [BuildOptions]
 334     INTEL:*_*_IA32_CC_FLAGS  = /Qfreestanding
 335      MSFT:*_*_IA32_CC_FLAGS  = /X /Zc:wchar_t
 336       GCC:*_*_IA32_CC_FLAGS  = /ffreestanding ?nostdinc ?nostdlib
 337
 338   # The Build Options, below, are only used when building the C library
 339   # to be run under an emulation environment.  The clock() system call
 340   # is modified to return -1 indicating that it is unsupported.
 341   # Just un-comment the lines below and select the correct
 342   # TimerLib instance, above.
 343
 344     # INTEL:*_*_IA32_CC_FLAGS  = /D NT32dvm
 345     #  MSFT:*_*_IA32_CC_FLAGS  = /D NT32dvm
 346     #   GCC:*_*_IA32_CC_FLAGS  = -DNT32dvm
 347
 348                         Figure 4: Package Build Options
 349                         ===============================
 350
 351 The "boilerplate" text can be included using a !include directive in the
 352 package's .dsc file.  The provided AppPkg.dsc and StdLib.dsc files include
 353 the "boilerplate" text as follows:
 354
 355   # Include Boilerplate text required for building with the Standard Libraries.
 356   #
 357   #############################################################################
 358   !include StdLib/StdLib.inc
 359
 360                       Figure 5: "Boilerplate" Inclusion
 361                       =================================
 362
 363
 364 INF Files
 365 =========
 366 The INF files for most modules will not require special directives in order to
 367 support the Standard Libraries.  The two cases which could occur are described
 368 below.
 369
 370   [LibraryClasses]
 371     UefiLib
 372     LibC
 373     LibString
 374     LibStdio
 375     DevShell
 376
 377                       Figure 6: Module Library Classes
 378                       ================================
 379
 380
 381 Modules of type UEFI_APPLICATION that perform file I/O should include library
 382 class DevShell.  Including this library class will allow file operations to be
 383 handled by the UEFI Shell.  Without this class, only Console I/O is permitted.
 384
 385  [BuildOptions]
 386   INTEL:*_*_*_CC_FLAGS          = /Qdiag-disable:181,186
 387    MSFT:*_*_*_CC_FLAGS          = /Oi- /wd4018 /wd4131
 388     GCC:*_*_IPF_SYMRENAME_FLAGS = --redefine-syms=Rename.txt
 389
 390                         Figure 7: Module Build Options
 391                         ==============================
 392
 393
 394 An application's INF file may need to include a [BuildOptions] section
 395 specifying additional compiler and linker flags necessary to allow the
 396 application to be built. Usually, this section is not needed.  When building
 397 code from external sources, though, it may be necessary to disable some
 398 warnings or enable/disable some compiler features.
 399
 400
 401 IMPLEMENTATION-Specific Features
 402 ================================
 403 It is very strongly recommended that applications not use the long or
 404 unsigned long types. The size of this type varies between compilers and is one
 405 of the less portable aspects of C. Instead, one should use the UEFI defined
 406 types whenever possible. Use of these types, listed below for reference,
 407 ensures that the declared objects have unambiguous, explicitly declared, sizes
 408 and characteristics.
 409
 410         UINT64   INT64     UINT32   INT32   UINT16   CHAR16
 411         INT16    BOOLEAN   UINT8    CHAR8   INT8
 412         UINTN    INTN                       PHYSICALADDRESS
 413
 414 There are similar types declared in sys/types.h and related files.
 415
 416 The types UINTN and INTN have the native width of the target processor
 417 architecture. Thus, INTN on IA32 has a width of 32 bits while INTN on X64 and
 418 IPF has a width of 64 bits.
 419
 420 For maximum portability, data objects intended to hold addresses should be
 421 declared with type intptr_t or uintptr_t. These types, declared in
 422 sys/stdint.h, can be used to create objects capable of holding pointers. Note
 423 that these types will generate different sized objects on different processor
 424 architectures.  If a constant size across all processors and compilers is
 425 needed, use type PHYSICAL_ADDRESS.
 426
 427 Though not specifically required by the ISO/IEC 9899 standard, this
 428 implementation of the Standard C Library provides the following system calls
 429 which are declared in sys/EfiSysCall.h.
 430
 431           close   dup      dup2     fcntl
 432           fstat   getcwd   ioctl    isatty
 433           lseek   lstat    mkdir    open
 434           poll    read     rename   rmdir
 435           stat    unlink   write
 436
 437 The open function will accept file names of "stdin:", "stdout:", and "stderr:"
 438 which cause the respective streams specified in the UEFI System Table to be
 439 opened.  Normally, these are associated with the console device.  When the
 440 application is first started, these streams are automatically opened on File
 441 Descriptors 0, 1, and 2 respectively.
 442
 443