2 EDK II Standard Libraries and Applications
11 The EADK (uEfi Application Development Kit) provides a set of standards-based
12 libraries, along with utility and demonstration applications, intended to
13 ease development of UEFI applications based upon the EDK II Open-Source
16 At this time, applications developed with the EADK are intended to reside
17 on, and be loaded from, storage separate from the core firmware. This is
18 primarily due to size and environmental requirements.
20 Some components of the EADK can be built as drivers. These will be identified
21 explicitly in their documentation.
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.
27 The EADK is comprised of three packages:
28 AppPkg, StdLib, and StdLibPrivateInternalFiles.
30 AppPkg This package contains applications which demonstrate use of the
32 These applications reside in AppPkg/Applications.
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.
40 Hello This is a very simple EDK II native application that doesn't use
41 any features of the Standard C Library.
43 Main This application is functionally identical to Hello, except that
44 it uses the Standard C Library to provide a main() entry point.
46 Python A port of the Python-2.7.2 interpreter for UEFI. 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.
51 Sockets A collection of applications demonstrating use of the
52 EDK II Socket Libraries. These applications include:
74 StdLib The StdLib package contains the standard header files as well as
75 implementations of standards based libraries.
78 Support routines above the sockets layer and C interface for
79 the UEFI socket library.
81 Template contents for the target system's
82 \Efi\StdLib\etc directory.
84 UEFI socket implementation, may be linked into an
85 application or run as a driver.
87 Standard include files.
89 C Standard Library implementation as per
90 ISO/IEC 9899:199409 (C95).
92 Selected functions from the "Single Unix v4" specification.
94 UEFI sockets driver, includes EfiSocketLib.
96 Alternate linkage for applications that get built into the
97 firmware. Cause application to use a common instance of the
98 sockets driver instead of including all of sockets into the
101 StdLibPrivateInternalFiles The contents of this package are for the
102 exclusive use of the library implementations in StdLib. Please do
103 not use anything from this package in your application or else
104 unexpected behavior may occur.
105 This package may be removed in a future release.
112 Beginning with this release, applications built with the StdLib package
113 no longer have a dependency on the TimerLib.
117 This release of the EADK has some restrictions, as described below.
119 1. Only the Microsoft VS2005 and VS2008, Intel C Compiler 10.1 (or later),
120 GCC 4.3 (mingw32), GCC 4.4, and GCC 4.5 C compilers are supported for
121 Ia32 or X64 CPU architectures. Others may work but have not been tested.
123 2. The target machine must be running firmware which provides the
124 UEFI 2.3 HII protocol.
126 3. The EADK has not been through Intel's Quality Assurance process. This
127 means that specified standards compliance has not been validated, nor
128 has it undergone formal functionality testing.
130 4. Applications must be launched from within the EFI Shell.
132 6. Absolute file paths may optionally be prefixed by a volume specifier
133 such as "FS0:". The volume specifier is separated from the remainder
134 of the path by a single colon ':'. The volume specifier must be one of
135 the Shell's mapped volume names as shown by the "map" command.
137 7. Absolute file paths that don't begin with a volume specifier;
138 e.g. paths that begin with "/", are relative to the currently selected
139 volume. When the EFI Shell first starts, there is NO selected volume.
141 8. The tmpfile(), and related, functions require that the current volume
142 have a temporary directory as specified in <paths.h>. This directory
143 is specified by macro _PATH_TMP as /Efi/StdLib/tmp.
145 9. Input line editing is not supported. Backspacing, deleting, or
146 otherwise attempting to modify interactive input will result in a
147 syntax error since the editing characters are interpreted the
148 same as any other character.
150 The Standard C Library provided by this package is a "hosted" implementation
151 conforming to the ISO/IEC 9899-1990 C Language Standard with Addendum 1. This
152 is commonly referred to as the "C 95" specification or ISO/IEC 9899:199409.
153 The following instructions assume that you have an existing EDK II or UDK 2010
154 source tree that has been configured to build with your tool chain. For
155 convenience, it is assumed that your EDK II source tree is located at
161 The EADK is integrated within the EDK II source tree and is included with
162 current EDK II check-outs. If they are missing from your tree, they may be
163 installed by extracting, downloading or copying them to the root of your EDK II
164 source tree. The three package directories should be peers to the Conf,
165 MdePkg, Nt32Pkg, etc. directories.
167 The Python 2.7.2 distribution must be downloaded from python.org before the
168 Python application can be built. Extracting Python-2.7.2.tgz into the
169 AppPkg\Applications\Python directory will produce a Python-2.7.2 directory
170 containing the Python distribution. Python files that had to be modified for
171 EDK II are in the AppPkg\Applications\Python\PyMod-2.7.2 directory. These
172 files need to be copied into the corresponding directories within Python-2.7.2.
174 The Python 2.7.1 port was superseded before it was completed. The PyMod-2.7.1
175 directory tree will be deleted in the near future. Use the Python 2.7.2 port,
178 There are some boiler-plate declarations and definitions that need to be
179 included in your application's INF and DSC build files. These are described
180 in the CONFIGURATION section, below.
185 It is not necessary to build the libraries separately from the target
186 application(s). If the application references the libraries, as described in
187 USAGE, below; the required libraries will be built as needed.
188 To build the applications included in AppPkg, one would execute the following
189 commands within the "Visual Studio Command Prompt" window:
193 > build -a X64 -p AppPkg\AppPkg.dsc
195 This will produce the application executables: Enquire.efi, Hello.efi, and
196 Main.efi in the C:\Source\Edk2\Build\AppPkg\DEBUG_VS2008\X64 directory; with
197 the DEBUG_VS2008 component being replaced with the actual tool chain and build
198 type you have selected in Conf\Tools_def.txt. These executables can now be
199 loaded onto the target platform and executed.
201 If you examine the AppPkg.dsc file, you will notice that the StdLib package is
202 referenced in order to resolve the library classes comprising the Standard
203 C Library. This, plus referencing the StdLib package in your application's
204 .inf file is all that is needed to link your application to the standard
207 Unless explicitly stated as allowed, EADK components should not be added as
208 components of a DSC file which builds a platform's core firmware. There are
209 incompatibilities in build flags and requirements that will conflict with the
210 requirements of the core firmware. EADK components should be built using a
211 separate DSC file then, if absolutely necessary, included as binary components
216 This implementation of the Standard C Library is comprised of 16 separate
217 libraries in addition to the standard header files. Nine of the libraries are
218 associated with use of one of the standard headers; thus, if the header is used
219 in an application, it must be linked with the associated library. Three
220 libraries are used to provide the Console and File-system device abstractions.
221 The libraries and associated header files are described in the following table.
224 Class Header File(s) Notes
225 ---------- ---------------- -------------------------------------------------
226 LibC -- Use Always -- This library is always required.
227 LibCtype ctype.h, wctype.h Character classification and mapping
228 LibLocale locale.h Localization types, macros, and functions
229 LibMath math.h Mathematical functions, types, and macros
230 LibStdio stdio.h Standard Input and Output functions, types, and
232 LibStdLib stdlib.h General Utilities for numeric conversion, random
234 LibString string.h String copying, concatenation, comparison,
236 LibSignal signal.h Functions and types for handling run-time
238 LibTime time.h Time and Date types, macros, and functions
239 LibUefi sys/EfiSysCall.h Provides the UEFI system interface and
241 LibWchar wchar.h Extended multibyte and wide character utilities
242 LibNetUtil Network address and number manipulation utilities
243 DevConsole Automatically provided File I/O abstractions for
244 the UEFI Console device. No need to list this
245 library class in your INF file(s).
246 DevShell Add if desired File I/O abstractions using UEFI shell
247 facilities. Add this to the application's main
248 INF file if file-system access needed.
249 DevUtility -- Do Not Use -- Utility functions used by the Device abstractions
250 LibGdtoa -- Do Not Use -- This library is used internally and should not
251 need to be explicitly specified by an
252 application. It must be defined as one of the
253 available library classes in the application's
256 Table 1: Standard Libraries
257 ============================
260 These libraries must be fully described in the [LibraryClasses] section of the
261 application package's DSC file. Then, each individual application needs to
262 specify which libraries to link to by specifying the Library Class, from the
263 above table, in the [LibraryClasses] section of the application's INF file. The
264 AppPkg.dsc, StdLib.dsc, and Enquire.inf files provide good examples of this.
265 More details are in the CONFIGURATION section, below.
267 Within the source files of the application, use of the Standard headers and
268 library functions follow standard C programming practices as formalized by
269 ISO/IEC 9899:1990, with Addendum 1, (C 95) C language specification.
277 All EDK II packages which build applications that use the standard libraries
278 must include some "boilerplate" text in the package's .dsc file. To make it
279 easier, and to reduce cut-and-paste errors, the "boilerplate" text has been
280 consolidated into a single file, StdLib/StdLib.inc, which can be included in
281 your .dsc file using the !include directive. The provided AppPkg.dsc and
282 StdLib.dsc files do this on their last line.
284 Each section of StdLib/StdLib.inc is described below.
288 # C Standard Libraries
290 LibC|StdLib/LibC/LibC.inf
291 LibCType|StdLib/LibC/Ctype/Ctype.inf
292 LibLocale|StdLib/LibC/Locale/Locale.inf
293 LibMath|StdLib/LibC/Math/Math.inf
294 LibSignal|StdLib/LibC/Signal/Signal.inf
295 LibStdio|StdLib/LibC/Stdio/Stdio.inf
296 LibStdLib|StdLib/LibC/StdLib/StdLib.inf
297 LibString|StdLib/LibC/String/String.inf
298 LibTime|StdLib/LibC/Time/Time.inf
299 LibUefi|StdLib/LibC/Uefi/Uefi.inf
300 LibWchar|StdLib/LibC/Wchar/Wchar.inf
302 # Common Utilities for Networking Libraries
303 LibNetUtil|StdLib/LibC/NetUtil/NetUtil.inf
305 # Additional libraries for POSIX functionality.
306 LibErr|StdLib/PosixLib/Err/LibErr.inf
307 LibGen|StdLib/PosixLib/Gen/LibGen.inf
308 LibGlob|StdLib/PosixLib/Glob/LibGlob.inf
309 LibStringlist|StdLib/PosixLib/Stringlist/LibStringlist.inf
311 # Libraries for device abstractions within the Standard C Library
312 # Applications should not directly access any functions defined in these libraries.
313 LibGdtoa|StdLib/LibC/gdtoa/gdtoa.inf
314 DevConsole|StdLib/LibC/Uefi/Devices/daConsole.inf
315 DevShell|StdLib/LibC/Uefi/Devices/daShell.inf
316 DevUtility|StdLib/LibC/Uefi/Devices/daUtility.inf
318 [LibraryClasses.ARM.UEFI_APPLICATION]
319 NULL|ArmPkg/Library/CompilerIntrinsicsLib/CompilerIntrinsicsLib.inf
321 Figure 1: Library Class Descriptions
322 ====================================
325 Descriptions of the Library Classes comprising the Standard Libraries,
326 as shown above in Figure 1: Library Class Descriptions, are provided.
328 The directives in Figure 2: Package Component Descriptions will create
329 instances of the BaseLib and BaseMemoryLib library classes that are built
330 with Link-time-Code-Generation disabled. This is necessary when using the
331 Microsoft tool chains in order to allow the library's functions to be
332 resolved during the second pass of the linker during Link-Time-Code-Generation
335 A DXE driver version of the Socket library is also built.
338 # BaseLib and BaseMemoryLib need to be built with the /GL- switch
339 # when using the Microsoft tool chains. This is required so that
340 # the library functions can be resolved during the second pass of
341 # the linker during link-time-code-generation.
343 MdePkg/Library/BaseLib/BaseLib.inf {
345 MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-
347 MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf {
349 MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-
355 StdLib/SocketDxe/SocketDxe.inf
357 Figure 2: Package Component Descriptions
358 ========================================
361 Each compiler assumes, by default, that it will be used with standard libraries
362 and headers provided by the compiler vendor. Many of these assumptions are
363 incorrect for the UEFI environment. By including a BuildOptions section, as
364 shown in Figure 3: Package Build Options, these assumptions can be
365 tailored for compatibility with UEFI and the EDK II Standard Libraries.
368 INTEL:*_*_IA32_CC_FLAGS = /Qfreestanding
369 MSFT:*_*_IA32_CC_FLAGS = /X /Zc:wchar_t
370 GCC:*_*_IA32_CC_FLAGS = -nostdinc -nostdlib
372 # The Build Options, below, are only used when building the C library
373 # to be run under an emulation environment. They disable optimization
374 # which facillitates debugging under the Emulation environment.
376 # INTEL:*_*_IA32_CC_FLAGS = /Od
377 # MSFT:*_*_IA32_CC_FLAGS = /Od
378 # GCC:*_*_IA32_CC_FLAGS = -O0
380 Figure 4: Package Build Options
381 ===============================
383 The "boilerplate" text can be included using a !include directive in the
384 package's .dsc file. The provided AppPkg.dsc and StdLib.dsc files include
385 the "boilerplate" text as follows:
387 # Include Boilerplate text required for building with the Standard Libraries.
389 #############################################################################
390 !include StdLib/StdLib.inc
392 Figure 5: "Boilerplate" Inclusion
393 =================================
398 The INF files for most modules will not require special directives in order to
399 support the Standard Libraries. The two cases which could occur are described
409 Figure 6: Module Library Classes
410 ================================
413 Modules of type UEFI_APPLICATION that perform file I/O should include library
414 class DevShell. Including this library class will allow file operations to be
415 handled by the UEFI Shell. Without this class, only Console I/O is permitted.
418 INTEL:*_*_*_CC_FLAGS = /Qdiag-disable:181,186
419 MSFT:*_*_*_CC_FLAGS = /Oi- /wd4018 /wd4131
420 GCC:*_*_IPF_SYMRENAME_FLAGS = --redefine-syms=Rename.txt
422 Figure 7: Module Build Options
423 ==============================
426 An application's INF file may need to include a [BuildOptions] section
427 specifying additional compiler and linker flags necessary to allow the
428 application to be built. Usually, this section is not needed. When building
429 code from external sources, though, it may be necessary to disable some
430 warnings or enable/disable some compiler features.
433 TARGET-SYSTEM INSTALLATION
434 ==========================
435 Applications that use file system features or the Socket library depend upon
436 the existence of a specific directory tree structure on the same volume that
437 the application was loaded from. This tree structure is described below:
439 /EFI Root of the UEFI system area.
440 |- /Tools Directory containing applications.
441 |- /Boot UEFI specified Boot directory.
442 |- /StdLib Root of the Standard Libraries sub-tree.
443 |- /etc Configuration files used by libraries.
444 |- /tmp Temporary files created by tmpfile(), etc.
447 The /Efi/StdLib/etc directory is populated from the StdLib/Efi/etc source
450 IMPLEMENTATION-Specific Features
451 ================================
452 It is very strongly recommended that applications not use the long or
453 unsigned long types. The size of this type varies between compilers and is one
454 of the less portable aspects of C. Instead, one should use the UEFI defined
455 types whenever possible. Use of these types, listed below for reference,
456 ensures that the declared objects have unambiguous, explicitly declared, sizes
459 UINT64 INT64 UINT32 INT32 UINT16 CHAR16
460 INT16 BOOLEAN UINT8 CHAR8 INT8
461 UINTN INTN PHYSICALADDRESS
463 There are similar types declared in sys/types.h and related files.
465 The types UINTN and INTN have the native width of the target processor
466 architecture. Thus, INTN on IA32 has a width of 32 bits while INTN on X64 and
467 IPF has a width of 64 bits.
469 For maximum portability, data objects intended to hold addresses should be
470 declared with type intptr_t or uintptr_t. These types, declared in
471 sys/stdint.h, can be used to create objects capable of holding pointers. Note
472 that these types will generate different sized objects on different processor
473 architectures. If a constant size across all processors and compilers is
474 needed, use type PHYSICAL_ADDRESS.
476 Though not specifically required by the ISO/IEC 9899 standard, this
477 implementation of the Standard C Library provides the following system calls
478 which are declared in sys/EfiSysCall.h and/or unistd.h.
480 close creat chmod dup dup2
481 fcntl fstat getcwd ioctl isatty
482 lseek lstat mkdir open poll
483 read rename rmdir stat unlink write
485 The open function will accept file names of "stdin:", "stdout:", and "stderr:"
486 which cause the respective streams specified in the UEFI System Table to be
487 opened. Normally, these are associated with the console device. When the
488 application is first started, these streams are automatically opened on File
489 Descriptors 0, 1, and 2 respectively.
projects / mirror_edk2.git / blob