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 # # # 514
