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