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