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