ReadMe.txt 24 KB

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