AppPkg: introduce OrderedCollectionTest
[mirror_edk2.git] / AppPkg / ReadMe.txt
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 # # #