1 EDK II Standard Libraries
9 This document describes the EDK II specific aspects of installing, building, and
10 using the Standard C Library component of the EDK II Application Development
13 The EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateInternalFiles.
15 AppPkg This package contains applications which demonstrate use of the
17 These applications reside in AppPkg/Applications.
19 Enquire This is a program that determines many properties of the
20 C compiler and the target machine that Enquire is run on. The
21 only changes required to port this 1990s era Unix program to
22 EDK II were the addition of eight pragmas to enquire.c in
23 order to disable some Microsoft VC++ specific warnings.
25 Hello This is a very simple EDK II native application that doesn't use
26 any features of the Standard C Library.
28 Main This application is functionally identical to Hello, except that
29 it uses the Standard C Library to provide a main() entry point.
31 Python A port of the Python-2.7.1 interpreter for UEFI. This
32 application is disabled by default. Un-comment the line for
33 PythonCore.inf in the [Components] section of AppPkg.dsc to
34 enable building Python.
36 Sockets A collection of applications demonstrating use of the
37 EDK II Socket Libraries. These applications include:
54 StdLib The StdLib package contains the standard header files as well as
55 implementations of the standard libraries.
57 StdLibPrivateInternalFiles The contents of this package are for the
58 exclusive use of the library implementations in StdLib. Please do
59 not use anything from this package in your application or else
60 unexpected behavior may occur.
61 This package may be removed in a future release.
66 This release of the EADK has some restrictions, as described below.
68 1. Only the Microsoft VS2005 and VS2008, Intel C Compiler 10.1 (or later),
69 GCC 4.3 (mingw32), GCC 4.4, and GCC 4.5 C compilers are supported for
70 Ia32 or X64 CPU architectures.
72 2. The target machine must be running firmware which provides the
73 UEFI 2.3 HII protocol.
75 3. The EADK has not been through Intel's Quality Assurance process. This
76 means that specified standards compliance has not been validated, nor
77 has it undergone formal functionality testing.
79 4. Applications must be launched from within the EFI Shell.
81 5. All file paths must use the forward slash, '/', as the separator
84 6. Absolute file paths may optionally be prefixed by a volume specifier
85 such as "FS0:". The volume specifier is separated from the remainder
86 of the path by a single colon ':'. The volume specifier must be one of
87 the Shell's mapped volume names as shown by the "map" command.
89 7. Absolute file paths that don't begin with a volume specifier;
90 e.g. paths that begin with "/", are relative to the currently selected
91 volume. When the EFI Shell starts, there is NO selected volume.
93 8. The tmpfile(), and related, functions require that the current volume
94 have a temporary directory as specified in <paths.h>. This directory
95 is specified by macro _PATH_TMP.
97 The Standard C Library provided by this package is a "hosted" implementation
98 conforming to the ISO/IEC 9899-1990 C Language Standard with Addendum 1. This
99 is commonly referred to as the "C 95" specification or ISO/IEC 9899:199409.
100 The following instructions assume that you have an existing EDK II or UDK 2010
101 source tree that has been configured to build with your tool chain. For
102 convenience, it is assumed that your EDK II source tree is located at
108 The EADK is integrated within the EDK II source tree and is included with
109 current EDK II check-outs. If they are missing from your tree, they may be
110 installed by extracting, downloading or copying them to the root of your EDK II
111 source tree. The three package directories should be peers to the Conf,
112 MdePkg, Nt32Pkg, etc. directories.
114 The Python 2.7.1 distribution must be downloaded from python.org before the
115 Python application can be built. Extracting Python-2.7.1.tgz into the
116 AppPkg\Applications\Python directory will produce a Python-2.7.1 directory
117 containing the Python distribution. Python files that had to be modified for
118 EDK II are in the AppPkg\Applications\Python\PyMod-2.7.1 directory. These
119 files need to be copied into the corresponding directories within Python-2.7.1.
121 There are some boiler-plate declarations and definitions that need to be
122 included in your application's INF and DSC build files. These are described
123 in the CONFIGURATION section, below.
128 It is not necessary to build the libraries separately from the target
129 application(s). If the application references the libraries, as described in
130 USAGE, below; the required libraries will be built as needed.
131 To build the applications included in AppPkg, one would execute the following
132 commands within the "Visual Studio Command Prompt" window:
136 > build ?a X64 ?p AppPkg\AppPkg.dsc
138 This will produce the application executables: Enquire.efi, Hello.efi, and
139 Main.efi in the C:\Source\Edk2\Build\AppPkg\DEBUG_VS2008\X64 directory; with
140 the DEBUG_VS2008 component being replaced with the actual tool chain and build
141 type you have selected in Conf\Tools_def.txt. These executables can now be
142 loaded onto the target platform and executed.
144 If you examine the AppPkg.dsc file, you will notice that the StdLib package is
145 referenced in order to resolve the library classes comprising the Standard
146 C Library. This, plus referencing the StdLib package in your application's
147 .inf file is all that is needed to link your application to the standard
153 This implementation of the Standard C Library is comprised of 16 separate
154 libraries in addition to the standard header files. Nine of the libraries are
155 associated with use of one of the standard headers; thus, if the header is used
156 in an application, it must be linked with the associated library. Three
157 libraries are used to provide the Console and File-system device abstractions.
158 The libraries and associated header files are described in the following table.
161 Class Header File(s) Notes
162 ---------- ---------------- -------------------------------------------------
163 LibC -- Use Always -- This library is always required.
164 LibCtype ctype.h, wctype.h Character classification and mapping
165 LibLocale locale.h Localization types, macros, and functions
166 LibMath math.h Mathematical functions, types, and macros
167 LibStdio stdio.h Standard Input and Output functions, types, and
169 LibStdLib stdlib.h General Utilities for numeric conversion, random
171 LibString string.h String copying, concatenation, comparison,
173 LibSignal signal.h Functions and types for handling run-time
175 LibTime time.h Time and Date types, macros, and functions
176 LibUefi sys/EfiSysCall.h Provides the UEFI system interface and
178 LibWchar wchar.h Extended multibyte and wide character utilities
179 LibNetUtil Network address and number manipulation utilities
180 DevConsole Automatically provided File I/O abstractions for
181 the UEFI Console device. No need to list this
182 library class in your INF file(s).
183 DevShell Add if desired File I/O abstractions using UEFI shell
184 facilities. Add this to the application's main
185 INF file if file-system access needed.
186 DevUtility -- Do Not Use -- Utility functions used by the Device abstractions
187 LibGdtoa -- Do Not Use -- This library is used internally and should not
188 need to be explicitly specified by an
189 application. It must be defined as one of the
190 available library classes in the application's
193 Table 1: Standard Libraries
194 ============================
197 These libraries must be fully described in the [LibraryClasses] section of the
198 application package's DSC file. Then, each individual application needs to
199 specify which libraries to link to by specifying the Library Class, from the
200 above table, in the [LibraryClasses] section of the application's INF file. The
201 AppPkg.dsc, StdLib.dsc, and Enquire.inf files provide good examples of this.
202 More details are in the CONFIGURATION section, below.
204 Within the source files of the application, use of the Standard headers and
205 library functions follow standard C programming practices as formalized by
206 ISO/IEC 9899:1990, with Addendum 1, (C 95) C language specification.
214 All EDK II packages which build applications that use the standard libraries
215 must include some "boilerplate" text in the package's .dsc file. To make it
216 easier, and to reduce cut-and-paste errors, the "boilerplate" text has been
217 consolidated into a single file, StdLib/StdLib.inc, which can be included in
218 your .dsc file using the !include directive. The provided AppPkg.dsc and
219 StdLib.dsc files do this on their last line.
221 Each affected section of the DSC file is described below.
227 BaseLib|MdePkg/Library/BaseLib/BaseLib.inf
228 BaseMemoryLib|MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf
230 TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf
231 # To run in an emulation environment, such as NT32, comment out
232 # the TimerLib description above and un-comment the line below.
233 # TimerLib| MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf
236 # C Standard Libraries
238 LibC|StdLib/LibC/LibC.inf
239 LibStdLib|StdLib/LibC/StdLib/StdLib.inf
240 LibString|StdLib/LibC/String/String.inf
241 LibWchar|StdLib/LibC/Wchar/Wchar.inf
242 LibCType|StdLib/LibC/Ctype/Ctype.inf
243 LibTime|StdLib/LibC/Time/Time.inf
244 LibStdio|StdLib/LibC/Stdio/Stdio.inf
245 LibGdtoa|StdLib/LibC/gdtoa/gdtoa.inf
246 LibLocale|StdLib/LibC/Locale/Locale.inf
247 LibUefi|StdLib/LibC/Uefi/Uefi.inf
248 LibMath|StdLib/LibC/Math/Math.inf
249 LibSignal|StdLib/LibC/Signal/Signal.inf
250 LibNetUtil|StdLib/LibC/LibGcc/LibGcc.inf
252 # Libraries for device abstractions within the Standard C Library.
253 # Applications should not directly access any functions defined
254 # in these libraries.
255 DevUtility|StdLib/LibC/Uefi/Devices/daUtility.inf
256 DevConsole|StdLib/LibC/Uefi/Devices/daConsole.inf
257 DevShell|StdLib/LibC/Uefi/Devices/daShell.inf
259 Figure 1: Library Class Descriptions
260 ====================================
263 Descriptions of the Library Classes comprising the Standard Libraries must be
264 included in your application package's DSC file, as shown in Figure 1: Library
265 Class Descriptions, above.
267 The directives in Figure 2: Package Component Descriptions will create
268 instances of the BaseLib and BaseMemoryLib library classes that are built
269 with Link-time-Code-Generation disabled. This is necessary when using the
270 Microsoft tool chains in order to allow the library's functions to be
271 resolved during the second pass of the linker during Link-Time-Code-Generation
275 # BaseLib and BaseMemoryLib need to be built with the /GL- switch
276 # when using the Microsoft tool chains. This is required so that
277 # the library functions can be resolved during the second pass of
278 # the linker during link-time-code-generation.
280 MdePkg/Library/BaseLib/BaseLib.inf {
282 MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-
284 MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf {
286 MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-
289 Figure 2: Package Component Descriptions
290 ========================================
293 The NULL TimerLib instance must be selected if you desire to run your
294 application under an emulation environment -- unless there is a supported
295 TimerLib for that environment. For example, the InOsEmuPkg provides a
296 DxeTimerLib which can be used for the TimerLib instance.
298 The "boilerplate" text in StdLib.inc will automatically adjust which Timer
299 Library is instantiated based upon whether the $(EMULATE) macro has been
303 # Select the correct TimerLib instance depending upon whether running under
304 # an emulation environment, or not.
306 # Not running in an Emulation Environment
307 [LibraryClasses.IA32.UEFI_APPLICATION]
308 TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf
310 [LibraryClasses.X64.UEFI_APPLICATION]
311 TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf
313 [LibraryClasses.IPF.UEFI_APPLICATION]
314 PalLib|MdePkg/Library/UefiPalLib/UefiPalLib.inf
315 TimerLib|MdePkg/Library/SecPeiDxeTimerLibCpu/SecPeiDxeTimerLibCpu.inf
318 # Use this instance if Running in an Emulation Environment.
319 [LibraryClasses.Common.UEFI_APPLICATION]
320 TimerLib|MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf
323 Figure 3: Timer Library Selection
324 =================================
327 Each compiler assumes, by default, that it will be used with standard libraries
328 and headers provided by the compiler vendor. Many of these assumptions are
329 incorrect for the UEFI environment. By including a BuildOptions section, as
330 shown in Figure 3: Package Build Options, these assumptions can be
331 tailored for compatibility with UEFI and the EDK II Standard Libraries.
334 INTEL:*_*_IA32_CC_FLAGS = /Qfreestanding
335 MSFT:*_*_IA32_CC_FLAGS = /X /Zc:wchar_t
336 GCC:*_*_IA32_CC_FLAGS = /ffreestanding ?nostdinc ?nostdlib
338 # The Build Options, below, are only used when building the C library
339 # to be run under an emulation environment. The clock() system call
340 # is modified to return -1 indicating that it is unsupported.
341 # Just un-comment the lines below and select the correct
342 # TimerLib instance, above.
344 # INTEL:*_*_IA32_CC_FLAGS = /D NT32dvm
345 # MSFT:*_*_IA32_CC_FLAGS = /D NT32dvm
346 # GCC:*_*_IA32_CC_FLAGS = -DNT32dvm
348 Figure 4: Package Build Options
349 ===============================
351 The "boilerplate" text can be included using a !include directive in the
352 package's .dsc file. The provided AppPkg.dsc and StdLib.dsc files include
353 the "boilerplate" text as follows:
355 # Include Boilerplate text required for building with the Standard Libraries.
357 #############################################################################
358 !include StdLib/StdLib.inc
360 Figure 5: "Boilerplate" Inclusion
361 =================================
366 The INF files for most modules will not require special directives in order to
367 support the Standard Libraries. The two cases which could occur are described
377 Figure 6: Module Library Classes
378 ================================
381 Modules of type UEFI_APPLICATION that perform file I/O should include library
382 class DevShell. Including this library class will allow file operations to be
383 handled by the UEFI Shell. Without this class, only Console I/O is permitted.
386 INTEL:*_*_*_CC_FLAGS = /Qdiag-disable:181,186
387 MSFT:*_*_*_CC_FLAGS = /Oi- /wd4018 /wd4131
388 GCC:*_*_IPF_SYMRENAME_FLAGS = --redefine-syms=Rename.txt
390 Figure 7: Module Build Options
391 ==============================
394 An application's INF file may need to include a [BuildOptions] section
395 specifying additional compiler and linker flags necessary to allow the
396 application to be built. Usually, this section is not needed. When building
397 code from external sources, though, it may be necessary to disable some
398 warnings or enable/disable some compiler features.
401 IMPLEMENTATION-Specific Features
402 ================================
403 It is very strongly recommended that applications not use the long or
404 unsigned long types. The size of this type varies between compilers and is one
405 of the less portable aspects of C. Instead, one should use the UEFI defined
406 types whenever possible. Use of these types, listed below for reference,
407 ensures that the declared objects have unambiguous, explicitly declared, sizes
410 UINT64 INT64 UINT32 INT32 UINT16 CHAR16
411 INT16 BOOLEAN UINT8 CHAR8 INT8
412 UINTN INTN PHYSICALADDRESS
414 There are similar types declared in sys/types.h and related files.
416 The types UINTN and INTN have the native width of the target processor
417 architecture. Thus, INTN on IA32 has a width of 32 bits while INTN on X64 and
418 IPF has a width of 64 bits.
420 For maximum portability, data objects intended to hold addresses should be
421 declared with type intptr_t or uintptr_t. These types, declared in
422 sys/stdint.h, can be used to create objects capable of holding pointers. Note
423 that these types will generate different sized objects on different processor
424 architectures. If a constant size across all processors and compilers is
425 needed, use type PHYSICAL_ADDRESS.
427 Though not specifically required by the ISO/IEC 9899 standard, this
428 implementation of the Standard C Library provides the following system calls
429 which are declared in sys/EfiSysCall.h.
432 fstat getcwd ioctl isatty
433 lseek lstat mkdir open
434 poll read rename rmdir
437 The open function will accept file names of "stdin:", "stdout:", and "stderr:"
438 which cause the respective streams specified in the UEFI System Table to be
439 opened. Normally, these are associated with the console device. When the
440 application is first started, these streams are automatically opened on File
441 Descriptors 0, 1, and 2 respectively.