1 EADK 2 EDK II Standard Libraries and Applications 3 ReadMe 4 Version 1.02 5 21 Dec. 2012 6 7 8OVERVIEW 9======== 10The EADK (uEfi Application Development Kit) provides a set of standards-based 11libraries, along with utility and demonstration applications, intended to 12ease development of UEFI applications based upon the EDK II Open-Source 13distribution. 14 15At this time, applications developed with the EADK are intended to reside 16on, and be loaded from, storage separate from the core firmware. This is 17primarily due to size and environmental requirements. 18 19This release of the EADK should only be used to produce UEFI Applications. Due to the execution 20environment built by the StdLib component, execution as a UEFI driver can cause system stability 21issues. 22 23This document describes the EDK II specific aspects of installing, building, 24and using the Standard C Library component of the EDK II Application 25Development Kit, EADK. 26 27The 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 99RELEASE NOTES 100============= 101 Fixes and Additions 102 ------------------- 103Beginning with release 1.01, applications built with the StdLib package 104no longer have a dependency on the TimerLib. 105 106 Known Issues 107 ----------------- 108This 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 128The Standard C Library provided by this package is a "hosted" implementation 129conforming to the ISO/IEC 9899-1990 C Language Standard with Addendum 1. This 130is commonly referred to as the "C 95" specification or ISO/IEC 9899:199409. 131The following instructions assume that you have an existing EDK II or UDK 2010 132source tree that has been configured to build with your tool chain. For 133convenience, it is assumed that your EDK II source tree is located at 134C:\Source\Edk2. 135 136 137EADK INSTALLATION 138================= 139The EADK is integrated within the EDK II source tree and is included with 140current EDK II check-outs. If they are missing from your tree, they may be 141installed by extracting, downloading or copying them to the root of your EDK II 142source tree. The three package directories should be peers to the Conf, 143MdePkg, Nt32Pkg, etc. directories. 144 145There are some boiler-plate declarations and definitions that need to be 146included in your application's INF and DSC build files. These are described 147in the CONFIGURATION section, below. 148 149A subset of the Python 2.7.2 distribution is included as part of AppPkg. If desired, 150the full Python 2.7.2 distribution may be downloaded from python.org and used instead. 151Delete or rename the existing Python-2.7.2 directory then extract the downloaded 152Python-2.7.2.tgz file into the AppPkg\Applications\Python directory. This will produce a 153Python-2.7.2 directory containing the full Python distribution. Python files that had to be 154modified for EDK II are in the AppPkg\Applications\Python\PyMod-2.7.2 directory. These 155files need to be copied into the corresponding directories within the extracted Python-2.7.2 156directory before Python can be built. 157 158 159BUILDING 160======== 161It is not necessary to build the libraries separately from the target 162application(s). If the application references the libraries, as described in 163USAGE, below; the required libraries will be built as needed. 164To build the applications included in AppPkg, one would execute the following 165commands 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 171This will produce the application executables: Enquire.efi, Hello.efi, and 172Main.efi in the C:\Source\Edk2\Build\AppPkg\DEBUG_VS2008\X64 directory; with 173the DEBUG_VS2008 component being replaced with the actual tool chain and build 174type you have selected in Conf\Tools_def.txt. These executables can now be 175loaded onto the target platform and executed. 176 177If you examine the AppPkg.dsc file, you will notice that the StdLib package is 178referenced in order to resolve the library classes comprising the Standard 179C 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 181libraries. 182 183Unless explicitly stated as allowed, EADK components should not be added as 184components of a DSC file which builds a platform's core firmware. There are 185incompatibilities in build flags and requirements that will conflict with the 186requirements of the core firmware. EADK components should be built using a 187separate DSC file then, if absolutely necessary, included as binary components 188of other DSC files. 189 190USAGE 191===== 192This implementation of the Standard C Library is comprised of 16 separate 193libraries in addition to the standard header files. Nine of the libraries are 194associated with use of one of the standard headers; thus, if the header is used 195in an application, it must be linked with the associated library. Three 196libraries are used to provide the Console and File-system device abstractions. 197The libraries and associated header files are described in the following table. 198 199 Library 200 Class Header File(s) Notes 201---------- ---------------- ------------------------------------------------- 202LibC -- Use Always -- This library is always required. 203LibCtype ctype.h, wctype.h Character classification and mapping 204LibLocale locale.h Localization types, macros, and functions 205LibMath math.h Mathematical functions, types, and macros 206LibStdio stdio.h Standard Input and Output functions, types, and 207 macros 208LibStdLib stdlib.h General Utilities for numeric conversion, random 209 num., etc. 210LibString string.h String copying, concatenation, comparison, 211 & search 212LibSignal signal.h Functions and types for handling run-time 213 conditions 214LibTime time.h Time and Date types, macros, and functions 215LibUefi sys/EfiSysCall.h Provides the UEFI system interface and 216 "System Calls" 217LibWchar wchar.h Extended multibyte and wide character utilities 218LibNetUtil Network address and number manipulation utilities 219DevConsole 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). 222DevShell 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. 225DevUtility -- Do Not Use -- Utility functions used internally by the Device abstractions 226LibGdtoa -- 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 235The DevConsole and DevShell libraries provide device I/O functionality and are treated 236specially. DevConsole is automatically included so there is no need to reference it in your 237application'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 240These libraries must be fully described in the [LibraryClasses] section of the 241application package's DSC file. Then, each individual application needs to 242specify which libraries to link to by specifying the Library Class, from the 243above table, in the [LibraryClasses] section of the application's INF file. The 244AppPkg.dsc, StdLib.dsc, and Enquire.inf files provide good examples of this. 245More details are in the CONFIGURATION section, below. 246 247In order to simplify this process, the [LibraryClasses] definitions, and others, are 248specified in the StdLib.inc file. If this file is included in the DSC file, usually at the 249end, then other DSC file changes or additions are unnecessary. This is further described in 250the CONFIGURATION section, below. 251 252Within the source files of the application, use of the Standard headers and 253library functions follow standard C programming practices as formalized by 254ISO/IEC 9899:1990, with Addendum 1, (C 95) C language specification. 255 256 257BUILD CONFIGURATION 258=================== 259DSC Files 260--------- 261 262All EDK II packages which build applications that use the standard libraries 263must include some "boilerplate" text in the package's .dsc file. To make it 264easier, and to reduce cut-and-paste errors, the "boilerplate" text has been 265consolidated into a single file, StdLib/StdLib.inc, which can be included in 266your .dsc file using the !include directive. The provided AppPkg.dsc and 267StdLib.dsc files do this on their last line. 268 269The "boilerplate" text can be included using a !include directive in the 270package's .dsc file. The provided AppPkg.dsc and StdLib.dsc files include 271the 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 290The EMULATE macro must be defined if one desires to do source-level debugging within one of 291the emulated environments such as NT32Pkg or UnixPkg. 292 293The final boilerplate line, in Figure 1, includes the StdLib.inc file. 294Each section of StdLib/StdLib.inc is described below. 295 296If 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 304Descriptions of the Library Classes comprising the Standard Libraries, 305as 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 346The directives in Figure 4: Package Component Descriptions will create 347instances of the BaseLib and BaseMemoryLib library classes that are built 348with Link-time-Code-Generation disabled. This is necessary when using the 349Microsoft tool chains in order to allow the library's functions to be 350resolved during the second pass of the linker during Link-Time-Code-Generation 351of the application. 352 353A 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 379Each compiler assumes, by default, that it will be used with standard libraries 380and headers provided by the compiler vendor. Many of these assumptions are 381incorrect for the UEFI environment. By including a BuildOptions section, as 382shown in Figure 5: Package Build Options, these assumptions can be 383tailored for compatibility with UEFI and the EDK II Standard Libraries. 384 385Note 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 407INF Files 408========= 409The INF files for most modules will not require special directives in order to 410support the Standard Libraries. The two sections which require attention: LibraryClasses 411and 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 424Modules of type UEFI_APPLICATION that perform file I/O must include library 425class DevShell. Including this library class will allow file operations to be 426handled by the UEFI Shell. Without this class, only Console I/O is supported. 427 428 429An application's INF file might need to include a [BuildOptions] section 430specifying additional compiler and linker flags necessary to allow the 431application to be built. Usually, this section is not needed. When building 432code from external sources, though, it may be necessary to disable some 433warnings 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 444TARGET-SYSTEM INSTALLATION 445========================== 446Applications that use file system features or the Socket library depend upon 447the existence of a specific directory tree structure on the same volume that 448the 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 458The /Efi/StdLib/etc directory must be manually populated from the StdLib/Efi/etc source 459directory. 460 461IMPLEMENTATION-Specific Features 462================================ 463It is very strongly recommended that applications not use the long or 464unsigned long types. The size of these types varies between compilers and is one 465of the less portable aspects of C. Instead, one should use the UEFI defined 466types whenever possible. Use of these types, listed below for reference, 467ensures that the declared objects have unambiguous, explicitly declared, sizes 468and characteristics. 469 470 UINT64 INT64 UINT32 INT32 UINT16 CHAR16 471 INT16 BOOLEAN UINT8 CHAR8 INT8 472 UINTN INTN PHYSICALADDRESS 473 474There are similar types declared in sys/types.h and related files. 475 476The types UINTN and INTN have the native width of the target processor 477architecture. Thus, INTN on IA32 has a width of 32 bits while INTN on X64 and 478IPF has a width of 64 bits. 479 480For maximum portability, data objects intended to hold addresses should be 481declared with type intptr_t or uintptr_t. These types, declared in 482sys/stdint.h, can be used to create objects capable of holding pointers. Note 483that these types will generate different sized objects on different processor 484architectures. If a constant size across all processors and compilers is 485needed, use type PHYSICAL_ADDRESS. 486 487Though not specifically required by the ISO/IEC 9899 standard, this 488implementation of the Standard C Library provides the following system calls 489which 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 496The open function will accept file names of "stdin:", "stdout:", and "stderr:" 497which cause the respective streams specified in the UEFI System Table to be 498opened. Normally, these are associated with the console device. When the 499application is first started, these streams are automatically opened on File 500Descriptors 0, 1, and 2 respectively. 501 502 # # # 503