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