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