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