514 lines
24 KiB
Plaintext
514 lines
24 KiB
Plaintext
EADK
|
|
EDK II Standard Libraries and Applications
|
|
ReadMe
|
|
Version 1.02
|
|
21 Dec. 2012
|
|
|
|
|
|
OVERVIEW
|
|
========
|
|
The EADK (uEfi Application Development Kit) provides a set of standards-based
|
|
libraries, along with utility and demonstration applications, intended to
|
|
ease development of UEFI applications based upon the EDK II Open-Source
|
|
distribution.
|
|
|
|
At this time, applications developed with the EADK are intended to reside
|
|
on, and be loaded from, storage separate from the core firmware. This is
|
|
primarily due to size and environmental requirements.
|
|
|
|
This release of the EADK should only be used to produce UEFI Applications. Due to the execution
|
|
environment built by the StdLib component, execution as a UEFI driver can cause system stability
|
|
issues.
|
|
|
|
This document describes the EDK II specific aspects of installing, building,
|
|
and using the Standard C Library component of the EDK II Application
|
|
Development Kit, EADK.
|
|
|
|
The EADK is comprised of three packages:
|
|
AppPkg, StdLib, and StdLibPrivateInternalFiles.
|
|
|
|
AppPkg This package contains applications which demonstrate use of the
|
|
Standard C and Sockets Libraries.
|
|
These applications reside in AppPkg/Applications.
|
|
|
|
Enquire This is a program that determines many properties of the
|
|
C compiler and the target machine that Enquire is run on. The
|
|
only changes required to port this 1990s era Unix program to
|
|
EDK II were the addition of eight pragmas to enquire.c in
|
|
order to disable some Microsoft VC++ specific warnings.
|
|
|
|
Hello This is a very simple EDK II native application that doesn't use
|
|
any features of the Standard C Library.
|
|
|
|
Main This application is functionally identical to Hello, except that
|
|
it uses the Standard C Library to provide a main() entry point.
|
|
|
|
Python A port of the Python-2.7.2 interpreter for UEFI. Building this
|
|
application is disabled by default.
|
|
See the PythonReadMe.txt file, in the Python directory,
|
|
for information on configuring and building Python.
|
|
|
|
Lua A port of the Lua-5.2.3 interpreter for UEFI. This
|
|
application is disabled by default. Un-comment the line for
|
|
LuaLib.inf in the [LibraryClasses] section and Lua.inf in the
|
|
[Components] section of AppPkg.dsc to enable building Lua.
|
|
|
|
OrderedCollectionTest A small Standard C Library application that
|
|
demonstrates the use of the OrderedCollectionLib library class
|
|
(provided by the BaseOrderedCollectionRedBlackTreeLib library
|
|
instance in this application), and allows the user to "fuzz" the
|
|
library with interactive or scripted API calls.
|
|
|
|
Sockets A collection of applications demonstrating use of the
|
|
EDK II Socket Libraries. These applications include:
|
|
|
|
* DataSink * DataSource
|
|
* GetAddrInfo * GetHostByAddr
|
|
* GetHostByDns * GetHostByName
|
|
* GetNetByAddr * GetNetByName
|
|
* GetServByName * GetServByPort
|
|
* OobRx * OobTx
|
|
* RawIp4Rx * RawIp4Tx
|
|
* RecvDgram * SetHostName
|
|
* SetSockOpt * TftpServer
|
|
* WebServer
|
|
|
|
StdLib The StdLib package contains the standard header files as well as
|
|
implementations of other standards-based libraries.
|
|
|
|
* BsdSocketLib
|
|
Support routines above the sockets layer and C interface for
|
|
the UEFI socket library.
|
|
* Efi
|
|
Template contents for the target system's
|
|
\Efi\StdLib\etc directory.
|
|
* EfiSocketLib
|
|
UEFI socket implementation, may be linked into an
|
|
application or run as a driver.
|
|
* Include
|
|
Standard include files.
|
|
* LibC
|
|
C Standard Library implementation as per
|
|
ISO/IEC 9899:199409 (C95).
|
|
* PosixLib
|
|
Selected functions from the "Single Unix v4" specification.
|
|
* SocketDxe
|
|
UEFI sockets driver, includes EfiSocketLib.
|
|
* UseSocketDxe
|
|
Alternate linkage for applications that get built into the
|
|
firmware. Cause application to use a common instance of the
|
|
sockets driver instead of including all of sockets into the
|
|
application.
|
|
|
|
StdLibPrivateInternalFiles The contents of this package are for the
|
|
exclusive use of the library implementations in StdLib. Please do
|
|
not use anything from this package in your application or else
|
|
unexpected behavior may occur.
|
|
This package may be removed in a future release.
|
|
|
|
|
|
RELEASE NOTES
|
|
=============
|
|
Fixes and Additions
|
|
-------------------
|
|
Beginning with release 1.01, applications built with the StdLib package
|
|
no longer have a dependency on the TimerLib.
|
|
|
|
Known Issues
|
|
-----------------
|
|
This release of the EADK has some restrictions, as described below.
|
|
|
|
1. The target machine must be running firmware which provides the
|
|
UEFI 2.3 HII protocol.
|
|
|
|
2. Applications must be launched from within the EFI Shell.
|
|
|
|
3. Absolute file paths may optionally be prefixed by a volume specifier
|
|
such as "FS0:". The volume specifier is separated from the remainder
|
|
of the path by a single colon ':'. The volume specifier must be one of
|
|
the Shell's mapped volume names as shown by the "map" command.
|
|
|
|
4. Absolute file paths that don't begin with a volume specifier;
|
|
e.g. paths that begin with "/", are relative to the currently selected
|
|
volume. When the EFI Shell first starts, there is NO selected volume.
|
|
|
|
5. The tmpfile(), and related, functions require that the current volume
|
|
have a temporary directory as specified in <paths.h>. This directory
|
|
is specified by macro _PATH_TMP as /Efi/StdLib/tmp.
|
|
|
|
The Standard C Library provided by this package is a "hosted" implementation
|
|
conforming to the ISO/IEC 9899-1990 C Language Standard with Addendum 1. This
|
|
is commonly referred to as the "C 95" specification or ISO/IEC 9899:199409.
|
|
The following instructions assume that you have an existing EDK II or UDK 2010
|
|
source tree that has been configured to build with your tool chain. For
|
|
convenience, it is assumed that your EDK II source tree is located at
|
|
C:\Source\Edk2.
|
|
|
|
|
|
EADK INSTALLATION
|
|
=================
|
|
The EADK is integrated within the EDK II source tree and is included with
|
|
current EDK II check-outs. If they are missing from your tree, they may be
|
|
installed by extracting, downloading or copying them to the root of your EDK II
|
|
source tree. The three package directories should be peers to the Conf,
|
|
MdePkg, Nt32Pkg, etc. directories.
|
|
|
|
There are some boiler-plate declarations and definitions that need to be
|
|
included in your application's INF and DSC build files. These are described
|
|
in the CONFIGURATION section, below.
|
|
|
|
A subset of the Python 2.7.2 distribution is included as part of AppPkg. If desired,
|
|
the full Python 2.7.2 distribution may be downloaded from python.org and used instead.
|
|
Delete or rename the existing Python-2.7.2 directory then extract the downloaded
|
|
Python-2.7.2.tgz file into the AppPkg\Applications\Python directory. This will produce a
|
|
Python-2.7.2 directory containing the full Python distribution. Python files that had to be
|
|
modified for EDK II are in the AppPkg\Applications\Python\PyMod-2.7.2 directory. These
|
|
files need to be copied into the corresponding directories within the extracted Python-2.7.2
|
|
directory before Python can be built.
|
|
|
|
|
|
BUILDING
|
|
========
|
|
It is not necessary to build the libraries separately from the target
|
|
application(s). If the application references the libraries, as described in
|
|
USAGE, below; the required libraries will be built as needed.
|
|
To build the applications included in AppPkg, one would execute the following
|
|
commands within the "Visual Studio Command Prompt" window:
|
|
|
|
> cd C:\Source\Edk2
|
|
> .\edksetup.bat
|
|
> build -a X64 -p AppPkg\AppPkg.dsc
|
|
|
|
This will produce the application executables: Enquire.efi, Hello.efi, and
|
|
Main.efi in the C:\Source\Edk2\Build\AppPkg\DEBUG_VS2008\X64 directory; with
|
|
the DEBUG_VS2008 component being replaced with the actual tool chain and build
|
|
type you have selected in Conf\Tools_def.txt. These executables can now be
|
|
loaded onto the target platform and executed.
|
|
|
|
If you examine the AppPkg.dsc file, you will notice that the StdLib package is
|
|
referenced in order to resolve the library classes comprising the Standard
|
|
C Library. This, plus referencing the StdLib package in your application's
|
|
.inf file is all that is needed to link your application to the standard
|
|
libraries.
|
|
|
|
Unless explicitly stated as allowed, EADK components should not be added as
|
|
components of a DSC file which builds a platform's core firmware. There are
|
|
incompatibilities in build flags and requirements that will conflict with the
|
|
requirements of the core firmware. EADK components should be built using a
|
|
separate DSC file then, if absolutely necessary, included as binary components
|
|
of other DSC files.
|
|
|
|
USAGE
|
|
=====
|
|
This implementation of the Standard C Library is comprised of 16 separate
|
|
libraries in addition to the standard header files. Nine of the libraries are
|
|
associated with use of one of the standard headers; thus, if the header is used
|
|
in an application, it must be linked with the associated library. Three
|
|
libraries are used to provide the Console and File-system device abstractions.
|
|
The libraries and associated header files are described in the following table.
|
|
|
|
Library
|
|
Class Header File(s) Notes
|
|
---------- ---------------- -------------------------------------------------
|
|
LibC -- Use Always -- This library is always required.
|
|
LibCtype ctype.h, wctype.h Character classification and mapping
|
|
LibLocale locale.h Localization types, macros, and functions
|
|
LibMath math.h Mathematical functions, types, and macros
|
|
LibStdio stdio.h Standard Input and Output functions, types, and
|
|
macros
|
|
LibStdLib stdlib.h General Utilities for numeric conversion, random
|
|
num., etc.
|
|
LibString string.h String copying, concatenation, comparison,
|
|
& search
|
|
LibSignal signal.h Functions and types for handling run-time
|
|
conditions
|
|
LibTime time.h Time and Date types, macros, and functions
|
|
LibUefi sys/EfiSysCall.h Provides the UEFI system interface and
|
|
"System Calls"
|
|
LibWchar wchar.h Extended multibyte and wide character utilities
|
|
LibNetUtil Network address and number manipulation utilities
|
|
DevConsole Automatically provided File I/O abstractions for
|
|
the UEFI Console device. No need to list this
|
|
library class in your INF file(s).
|
|
DevShell Add if desired File I/O abstractions using UEFI shell
|
|
facilities. Add this to the application's main
|
|
INF file if file-system access needed.
|
|
DevUtility -- Do Not Use -- Utility functions used internally by the Device abstractions
|
|
LibGdtoa -- Do Not Use -- This library is used internally and should not
|
|
need to be explicitly specified by an
|
|
application. It must be defined as one of the
|
|
available library classes in the application's
|
|
DSC file.
|
|
|
|
Table 1: Standard Libraries
|
|
============================
|
|
|
|
The DevConsole and DevShell libraries provide device I/O functionality and are treated
|
|
specially. DevConsole is automatically included so there is no need to reference it in your
|
|
application's DSC or INF files. DevShell must be listed, in your application's INF file in the
|
|
[LibraryClasses] section, if your application does file I/O.
|
|
|
|
These libraries must be fully described in the [LibraryClasses] section of the
|
|
application package's DSC file. Then, each individual application needs to
|
|
specify which libraries to link to by specifying the Library Class, from the
|
|
above table, in the [LibraryClasses] section of the application's INF file. The
|
|
AppPkg.dsc, StdLib.dsc, and Enquire.inf files provide good examples of this.
|
|
More details are in the CONFIGURATION section, below.
|
|
|
|
In order to simplify this process, the [LibraryClasses] definitions, and others, are
|
|
specified in the StdLib.inc file. If this file is included in the DSC file, usually at the
|
|
end, then other DSC file changes or additions are unnecessary. This is further described in
|
|
the CONFIGURATION section, below.
|
|
|
|
Within the source files of the application, use of the Standard headers and
|
|
library functions follow standard C programming practices as formalized by
|
|
ISO/IEC 9899:1990, with Addendum 1, (C 95) C language specification.
|
|
|
|
|
|
BUILD CONFIGURATION
|
|
===================
|
|
DSC Files
|
|
---------
|
|
|
|
All EDK II packages which build applications that use the standard libraries
|
|
must include some "boilerplate" text in the package's .dsc file. To make it
|
|
easier, and to reduce cut-and-paste errors, the "boilerplate" text has been
|
|
consolidated into a single file, StdLib/StdLib.inc, which can be included in
|
|
your .dsc file using the !include directive. The provided AppPkg.dsc and
|
|
StdLib.dsc files do this on their last line.
|
|
|
|
The "boilerplate" text can be included using a !include directive in the
|
|
package's .dsc file. The provided AppPkg.dsc and StdLib.dsc files include
|
|
the following "boilerplate" text:
|
|
|
|
##############################################################################
|
|
#
|
|
# Specify whether we are running in an emulation environment, or not.
|
|
# Define EMULATE if we are, else keep the DEFINE commented out.
|
|
#
|
|
# DEFINE EMULATE = 1
|
|
|
|
##############################################################################
|
|
#
|
|
# Include Boilerplate text required for building with the Standard Libraries.
|
|
#
|
|
##############################################################################
|
|
!include StdLib/StdLib.inc
|
|
|
|
Figure 1: "Boilerplate" Inclusion
|
|
=================================
|
|
|
|
The EMULATE macro must be defined if one desires to do source-level debugging within one of
|
|
the emulated environments such as NT32Pkg or UnixPkg.
|
|
|
|
The final boilerplate line, in Figure 1, includes the StdLib.inc file.
|
|
Each section of StdLib/StdLib.inc is described below.
|
|
|
|
If desired, all of the Socket applications, in AppPkg, can be built by including Sockets.inc:
|
|
|
|
!include AppPkg/Applications/Sockets/Sockets.inc
|
|
|
|
Figure 2: Socket Applications "Boilerplate" Inclusion
|
|
=====================================================
|
|
|
|
|
|
Descriptions of the Library Classes comprising the Standard Libraries,
|
|
as shown in Figure 3: Library Class Descriptions, are provided.
|
|
|
|
[LibraryClasses]
|
|
#
|
|
# C Standard Libraries
|
|
#
|
|
LibC|StdLib/LibC/LibC.inf
|
|
LibCType|StdLib/LibC/Ctype/Ctype.inf
|
|
LibLocale|StdLib/LibC/Locale/Locale.inf
|
|
LibMath|StdLib/LibC/Math/Math.inf
|
|
LibSignal|StdLib/LibC/Signal/Signal.inf
|
|
LibStdio|StdLib/LibC/Stdio/Stdio.inf
|
|
LibStdLib|StdLib/LibC/StdLib/StdLib.inf
|
|
LibString|StdLib/LibC/String/String.inf
|
|
LibTime|StdLib/LibC/Time/Time.inf
|
|
LibUefi|StdLib/LibC/Uefi/Uefi.inf
|
|
LibWchar|StdLib/LibC/Wchar/Wchar.inf
|
|
|
|
# Common Utilities for Networking Libraries
|
|
LibNetUtil|StdLib/LibC/NetUtil/NetUtil.inf
|
|
|
|
# Additional libraries for POSIX functionality.
|
|
LibErr|StdLib/PosixLib/Err/LibErr.inf
|
|
LibGen|StdLib/PosixLib/Gen/LibGen.inf
|
|
LibGlob|StdLib/PosixLib/Glob/LibGlob.inf
|
|
LibStringlist|StdLib/PosixLib/Stringlist/LibStringlist.inf
|
|
|
|
# Libraries for device abstractions within the Standard C Library
|
|
# Applications should not directly access any functions defined in these libraries.
|
|
LibGdtoa|StdLib/LibC/gdtoa/gdtoa.inf
|
|
DevConsole|StdLib/LibC/Uefi/Devices/daConsole.inf
|
|
DevShell|StdLib/LibC/Uefi/Devices/daShell.inf
|
|
DevUtility|StdLib/LibC/Uefi/Devices/daUtility.inf
|
|
|
|
[LibraryClasses.ARM.UEFI_APPLICATION]
|
|
NULL|ArmPkg/Library/CompilerIntrinsicsLib/CompilerIntrinsicsLib.inf
|
|
|
|
Figure 3: Library Class Descriptions
|
|
====================================
|
|
|
|
|
|
The directives in Figure 4: Package Component Descriptions will create
|
|
instances of the BaseLib and BaseMemoryLib library classes that are built
|
|
with Link-time-Code-Generation disabled. This is necessary when using the
|
|
Microsoft tool chains in order to allow the library's functions to be
|
|
resolved during the second pass of the linker during Link-Time-Code-Generation
|
|
of the application.
|
|
|
|
A DXE driver version of the Socket library is also built.
|
|
|
|
[Components]
|
|
# BaseLib and BaseMemoryLib need to be built with the /GL- switch
|
|
# when using the Microsoft tool chains. This is required so that
|
|
# the library functions can be resolved during the second pass of
|
|
# the linker during link-time-code-generation.
|
|
#
|
|
MdePkg/Library/BaseLib/BaseLib.inf {
|
|
<BuildOptions>
|
|
MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-
|
|
}
|
|
MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf {
|
|
<BuildOptions>
|
|
MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-
|
|
}
|
|
|
|
##########
|
|
# Socket Layer
|
|
##########
|
|
StdLib/SocketDxe/SocketDxe.inf
|
|
|
|
Figure 4: Package Component Descriptions
|
|
========================================
|
|
|
|
|
|
Each compiler assumes, by default, that it will be used with standard libraries
|
|
and headers provided by the compiler vendor. Many of these assumptions are
|
|
incorrect for the UEFI environment. By including a BuildOptions section, as
|
|
shown in Figure 5: Package Build Options, these assumptions can be
|
|
tailored for compatibility with UEFI and the EDK II Standard Libraries.
|
|
|
|
Note that the set of BuildOptions used is determined by the state of the EMULATE macro.
|
|
|
|
[BuildOptions]
|
|
!ifndef $(EMULATE)
|
|
# These Build Options are used when building the Standard Libraries to be run
|
|
# on real hardware.
|
|
INTEL:*_*_IA32_CC_FLAGS = /Qfreestanding
|
|
MSFT:*_*_IA32_CC_FLAGS = /X /Zc:wchar_t
|
|
GCC:*_*_IA32_CC_FLAGS = -nostdinc -nostdlib
|
|
|
|
!else
|
|
# The Build Options, below, are only used when building the Standard Libraries
|
|
# to be run under an emulation environment.
|
|
# They disable optimization which facillitates debugging under the Emulation environment.
|
|
INTEL:*_*_IA32_CC_FLAGS = /Od
|
|
MSFT:*_*_IA32_CC_FLAGS = /Od
|
|
GCC:*_*_IA32_CC_FLAGS = -O0
|
|
|
|
Figure 5: Package Build Options
|
|
===============================
|
|
|
|
|
|
INF Files
|
|
=========
|
|
The INF files for most modules will not require special directives in order to
|
|
support the Standard Libraries. The two sections which require attention: LibraryClasses
|
|
and BuildOptions, are described below.
|
|
|
|
[LibraryClasses]
|
|
UefiLib
|
|
LibC
|
|
LibString
|
|
LibStdio
|
|
DevShell
|
|
|
|
Figure 6: Module Library Classes
|
|
================================
|
|
|
|
|
|
Modules of type UEFI_APPLICATION that perform file I/O must include library
|
|
class DevShell. Including this library class will allow file operations to be
|
|
handled by the UEFI Shell. Without this class, only Console I/O is supported.
|
|
|
|
|
|
An application's INF file might need to include a [BuildOptions] section
|
|
specifying additional compiler and linker flags necessary to allow the
|
|
application to be built. Usually, this section is not needed. When building
|
|
code from external sources, though, it may be necessary to disable some
|
|
warnings or enable/disable some compiler features.
|
|
|
|
[BuildOptions]
|
|
INTEL:*_*_*_CC_FLAGS = /Qdiag-disable:181,186
|
|
MSFT:*_*_*_CC_FLAGS = /Oi- /wd4018 /wd4131
|
|
GCC:*_*_IPF_SYMRENAME_FLAGS = --redefine-syms=Rename.txt
|
|
|
|
Figure 7: Module Build Options
|
|
==============================
|
|
|
|
|
|
TARGET-SYSTEM INSTALLATION
|
|
==========================
|
|
Applications that use file system features or the Socket library depend upon
|
|
the existence of a specific directory tree structure on the same volume that
|
|
the application was loaded from. This tree structure is described below:
|
|
|
|
/EFI Root of the UEFI system area.
|
|
|- /Tools Directory containing applications.
|
|
|- /Boot UEFI specified Boot directory.
|
|
|- /StdLib Root of the Standard Libraries sub-tree.
|
|
|- /etc Configuration files used by libraries.
|
|
|- /tmp Temporary files created by tmpfile(), etc.
|
|
|
|
|
|
The /Efi/StdLib/etc directory must be manually populated from the StdLib/Efi/etc source
|
|
directory.
|
|
|
|
IMPLEMENTATION-Specific Features
|
|
================================
|
|
It is very strongly recommended that applications not use the long or
|
|
unsigned long types. The size of these types varies between compilers and is one
|
|
of the less portable aspects of C. Instead, one should use the UEFI defined
|
|
types whenever possible. Use of these types, listed below for reference,
|
|
ensures that the declared objects have unambiguous, explicitly declared, sizes
|
|
and characteristics.
|
|
|
|
UINT64 INT64 UINT32 INT32 UINT16 CHAR16
|
|
INT16 BOOLEAN UINT8 CHAR8 INT8
|
|
UINTN INTN PHYSICALADDRESS
|
|
|
|
There are similar types declared in sys/types.h and related files.
|
|
|
|
The types UINTN and INTN have the native width of the target processor
|
|
architecture. Thus, INTN on IA32 has a width of 32 bits while INTN on X64 and
|
|
IPF has a width of 64 bits.
|
|
|
|
For maximum portability, data objects intended to hold addresses should be
|
|
declared with type intptr_t or uintptr_t. These types, declared in
|
|
sys/stdint.h, can be used to create objects capable of holding pointers. Note
|
|
that these types will generate different sized objects on different processor
|
|
architectures. If a constant size across all processors and compilers is
|
|
needed, use type PHYSICAL_ADDRESS.
|
|
|
|
Though not specifically required by the ISO/IEC 9899 standard, this
|
|
implementation of the Standard C Library provides the following system calls
|
|
which are declared in sys/EfiSysCall.h and/or unistd.h.
|
|
|
|
close creat chmod dup dup2
|
|
fcntl fstat getcwd ioctl isatty
|
|
lseek lstat mkdir open poll
|
|
read rename rmdir stat unlink write
|
|
|
|
The open function will accept file names of "stdin:", "stdout:", and "stderr:"
|
|
which cause the respective streams specified in the UEFI System Table to be
|
|
opened. Normally, these are associated with the console device. When the
|
|
application is first started, these streams are automatically opened on File
|
|
Descriptors 0, 1, and 2 respectively.
|
|
|
|
# # #
|