Add plain-text ReadMe files and delete the PDF version.
[mirror_edk2.git] / StdLibPrivateInternalFiles / ReadMe.txt
1 EDK II Standard Libraries
2 ReadMe
3 Beta Release
4 4:03 PM 8/2/2011
5
6
7 OVERVIEW
8 ========
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
11 Kit, EADK.
12
13 The EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateInternalFiles.
14
15 AppPkg This package contains applications which demonstrate use of the
16 Standard C Library.
17 These applications reside in AppPkg/Applications.
18
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.
24
25 Hello This is a very simple EDK II native application that doesn't use
26 any features of the Standard C Library.
27
28 Main This application is functionally identical to Hello, except that
29 it uses the Standard C Library to provide a main() entry point.
30
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.
35
36 Sockets A collection of applications demonstrating use of the
37 EDK II Socket Libraries. These applications include:
38
39 * DataSink
40 * DataSource
41 * GetHostByAddr
42 * GetHostByDns
43 * GetHostByName
44 * GetNetByAddr
45 * GetNetByName
46 * GetServByName
47 * GetServByPort
48 * RecvDgram
49 * SetHostName
50 * SetSockOpt
51 * TftpServer
52 * WebServer
53
54 StdLib The StdLib package contains the standard header files as well as
55 implementations of the standard libraries.
56
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.
62
63
64 RELEASE NOTES
65 =============
66 This release of the EADK has some restrictions, as described below.
67
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.
71
72 2. The target machine must be running firmware which provides the
73 UEFI 2.3 HII protocol.
74
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.
78
79 4. Applications must be launched from within the EFI Shell.
80
81 5. All file paths must use the forward slash, '/', as the separator
82 character.
83
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.
88
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.
92
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.
96
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
103 C:\Source\Edk2.
104
105
106 INSTALLATION
107 ============
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.
113
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.
120
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.
124
125
126 BUILDING
127 ========
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:
133
134 > cd C:\Source\Edk2
135 > .\edksetup.bat
136 > build ?a X64 ?p AppPkg\AppPkg.dsc
137
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.
143
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
148 libraries.
149
150
151 USAGE
152 =====
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.
159
160 Library
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
168 macros
169 LibStdLib stdlib.h General Utilities for numeric conversion, random
170 num., etc.
171 LibString string.h String copying, concatenation, comparison,
172 & search
173 LibSignal signal.h Functions and types for handling run-time
174 conditions
175 LibTime time.h Time and Date types, macros, and functions
176 LibUefi sys/EfiSysCall.h Provides the UEFI system interface and
177 "System Calls"
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
191 DSC file.
192
193 Table 1: Standard Libraries
194 ============================
195
196
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.
203
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.
207
208
209 CONFIGURATION
210 =============
211 DSC Files
212 ---------
213
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.
220
221 Each affected section of the DSC file is described below.
222
223 [LibraryClasses]
224 #
225 # Common Libraries
226 #
227 BaseLib|MdePkg/Library/BaseLib/BaseLib.inf
228 BaseMemoryLib|MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf
229
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
234
235 #
236 # C Standard Libraries
237 #
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
251
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
258
259 Figure 1: Library Class Descriptions
260 ====================================
261
262
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.
266
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
272 of the application.
273
274 [Components]
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.
279 #
280 MdePkg/Library/BaseLib/BaseLib.inf {
281 <BuildOptions>
282 MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-
283 }
284 MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf {
285 <BuildOptions>
286 MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-
287 }
288
289 Figure 2: Package Component Descriptions
290 ========================================
291
292
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.
297
298 The "boilerplate" text in StdLib.inc will automatically adjust which Timer
299 Library is instantiated based upon whether the $(EMULATE) macro has been
300 defined, or not.
301
302 ###
303 # Select the correct TimerLib instance depending upon whether running under
304 # an emulation environment, or not.
305 !ifndef $(EMULATE)
306 # Not running in an Emulation Environment
307 [LibraryClasses.IA32.UEFI_APPLICATION]
308 TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf
309
310 [LibraryClasses.X64.UEFI_APPLICATION]
311 TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf
312
313 [LibraryClasses.IPF.UEFI_APPLICATION]
314 PalLib|MdePkg/Library/UefiPalLib/UefiPalLib.inf
315 TimerLib|MdePkg/Library/SecPeiDxeTimerLibCpu/SecPeiDxeTimerLibCpu.inf
316
317 !else
318 # Use this instance if Running in an Emulation Environment.
319 [LibraryClasses.Common.UEFI_APPLICATION]
320 TimerLib|MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf
321 !endif
322
323 Figure 3: Timer Library Selection
324 =================================
325
326
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.
332
333 [BuildOptions]
334 INTEL:*_*_IA32_CC_FLAGS = /Qfreestanding
335 MSFT:*_*_IA32_CC_FLAGS = /X /Zc:wchar_t
336 GCC:*_*_IA32_CC_FLAGS = /ffreestanding ?nostdinc ?nostdlib
337
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.
343
344 # INTEL:*_*_IA32_CC_FLAGS = /D NT32dvm
345 # MSFT:*_*_IA32_CC_FLAGS = /D NT32dvm
346 # GCC:*_*_IA32_CC_FLAGS = -DNT32dvm
347
348 Figure 4: Package Build Options
349 ===============================
350
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:
354
355 # Include Boilerplate text required for building with the Standard Libraries.
356 #
357 #############################################################################
358 !include StdLib/StdLib.inc
359
360 Figure 5: "Boilerplate" Inclusion
361 =================================
362
363
364 INF Files
365 =========
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
368 below.
369
370 [LibraryClasses]
371 UefiLib
372 LibC
373 LibString
374 LibStdio
375 DevShell
376
377 Figure 6: Module Library Classes
378 ================================
379
380
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.
384
385 [BuildOptions]
386 INTEL:*_*_*_CC_FLAGS = /Qdiag-disable:181,186
387 MSFT:*_*_*_CC_FLAGS = /Oi- /wd4018 /wd4131
388 GCC:*_*_IPF_SYMRENAME_FLAGS = --redefine-syms=Rename.txt
389
390 Figure 7: Module Build Options
391 ==============================
392
393
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.
399
400
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
408 and characteristics.
409
410 UINT64 INT64 UINT32 INT32 UINT16 CHAR16
411 INT16 BOOLEAN UINT8 CHAR8 INT8
412 UINTN INTN PHYSICALADDRESS
413
414 There are similar types declared in sys/types.h and related files.
415
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.
419
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.
426
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.
430
431 close dup dup2 fcntl
432 fstat getcwd ioctl isatty
433 lseek lstat mkdir open
434 poll read rename rmdir
435 stat unlink write
436
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.
442
443