Virtualization
/
edk2
mirror of https://gitlab.com/qemu-project/edk2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

StdLib, AppPkg: Update ReadMe files. 

Signed-off-by: darylm503
Reviewed-by: jcarsey
Reviewed-by: michaelkrau
Reviewed-by: laurie0131


git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@13046 6f19259b-4bc3-4df7-8a09-765794883524
This commit is contained in:
darylm503 2012-02-28 02:30:19 +00:00
parent 1902252160
commit eb15a11ea1
3 changed files with 501 additions and 357 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

286
AppPkg/ReadMe.txt
View File

@ -1,16 +1,31 @@
EDK II Standard Libraries EADK
EDK II Standard Libraries and Applications
ReadMe ReadMe
Beta Release Beta-1 Release
4:03 PM 8/2/2011 27 Jan. 2012
DRAFT
OVERVIEW OVERVIEW
======== ========
This document describes the EDK II specific aspects of installing, building, and The EADK (uEfi Application Development Kit) provides a set of standards-based
using the Standard C Library component of the EDK II Application Development libraries, along with utility and demonstration applications, intended to
Kit, EADK. ease development of UEFI applications based upon the EDK II Open-Source
distribution.
The EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateInternalFiles. 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.
Some components of the EADK can be built as drivers. These will be identified
explicitly in their documentation.
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 AppPkg This package contains applications which demonstrate use of the
Standard C Library. Standard C Library.
@ -28,16 +43,17 @@ The EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateIntern
Main This application is functionally identical to Hello, except that Main This application is functionally identical to Hello, except that
it uses the Standard C Library to provide a main() entry point. it uses the Standard C Library to provide a main() entry point.
Python A port of the Python-2.7.1 interpreter for UEFI. This Python A port of the Python-2.7.2 interpreter for UEFI. This
application is disabled by default. Un-comment the line for application is disabled by default.
PythonCore.inf in the [Components] section of AppPkg.dsc to See the PythonReadMe.txt file, in the Python directory,
enable building Python. for information on configuring and building Python.
Sockets A collection of applications demonstrating use of the Sockets A collection of applications demonstrating use of the
EDK II Socket Libraries. These applications include: EDK II Socket Libraries. These applications include:
* DataSink * DataSink
* DataSource * DataSource
* GetAddrInfo
* GetHostByAddr * GetHostByAddr
* GetHostByDns * GetHostByDns
* GetHostByName * GetHostByName
@ -45,6 +61,10 @@ The EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateIntern
* GetNetByName * GetNetByName
* GetServByName * GetServByName
* GetServByPort * GetServByPort
* OobRx
* OobTx
* RawIp4Rx
* RawIp4Tx
* RecvDgram * RecvDgram
* SetHostName * SetHostName
* SetSockOpt * SetSockOpt
@ -52,7 +72,31 @@ The EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateIntern
* WebServer * WebServer
StdLib The StdLib package contains the standard header files as well as StdLib The StdLib package contains the standard header files as well as
implementations of the standard libraries. implementations of 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 StdLibPrivateInternalFiles The contents of this package are for the
exclusive use of the library implementations in StdLib. Please do exclusive use of the library implementations in StdLib. Please do
@ -63,36 +107,45 @@ The EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateIntern
RELEASE NOTES RELEASE NOTES
============= =============
Fixes and Additions
-------------------
Beginning with this release, 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. This release of the EADK has some restrictions, as described below.
1. Only the Microsoft VS2005 and VS2008, Intel C Compiler 10.1 (or later), 1. Only the Microsoft VS2005 and VS2008, Intel C Compiler 10.1 (or later),
GCC 4.3 (mingw32), GCC 4.4, and GCC 4.5 C compilers are supported for GCC 4.3 (mingw32), GCC 4.4, and GCC 4.5 C compilers are supported for
Ia32 or X64 CPU architectures. Ia32 or X64 CPU architectures. Others may work but have not been tested.
2. The target machine must be running firmware which provides the 2. The target machine must be running firmware which provides the
UEFI 2.3 HII protocol. UEFI 2.3 HII protocol.
3. The EADK has not been through Intel's Quality Assurance process. This 3. The EADK has not been through Intel's Quality Assurance process. This
means that specified standards compliance has not been validated, nor means that specified standards compliance has not been validated, nor
has it undergone formal functionality testing. has it undergone formal functionality testing.
4. Applications must be launched from within the EFI Shell. 4. Applications must be launched from within the EFI Shell.
5. All file paths must use the forward slash, '/', as the separator 6. Absolute file paths may optionally be prefixed by a volume specifier
character.
6. Absolute file paths may optionally be prefixed by a volume specifier
such as "FS0:". The volume specifier is separated from the remainder 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 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. the Shell's mapped volume names as shown by the "map" command.
7. Absolute file paths that don't begin with a volume specifier; 7. Absolute file paths that don't begin with a volume specifier;
e.g. paths that begin with "/", are relative to the currently selected e.g. paths that begin with "/", are relative to the currently selected
volume. When the EFI Shell starts, there is NO selected volume. volume. When the EFI Shell first starts, there is NO selected volume.
8. The tmpfile(), and related, functions require that the current volume 8. The tmpfile(), and related, functions require that the current volume
have a temporary directory as specified in <paths.h>. This directory have a temporary directory as specified in <paths.h>. This directory
is specified by macro _PATH_TMP. is specified by macro _PATH_TMP as /Efi/StdLib/tmp.
9. Input line editing is not supported. Backspacing, deleting, or
otherwise attempting to modify interactive input will result in a
syntax error since the editing characters are interpreted the
same as any other character.
The Standard C Library provided by this package is a "hosted" implementation 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 conforming to the ISO/IEC 9899-1990 C Language Standard with Addendum 1. This
@ -103,20 +156,24 @@ convenience, it is assumed that your EDK II source tree is located at
C:\Source\Edk2. C:\Source\Edk2.
INSTALLATION EADK INSTALLATION
============ =================
The EADK is integrated within the EDK II source tree and is included with 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 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 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, source tree. The three package directories should be peers to the Conf,
MdePkg, Nt32Pkg, etc. directories. MdePkg, Nt32Pkg, etc. directories.
The Python 2.7.1 distribution must be downloaded from python.org before the The Python 2.7.2 distribution must be downloaded from python.org before the
Python application can be built. Extracting Python-2.7.1.tgz into the Python application can be built. Extracting Python-2.7.2.tgz into the
AppPkg\Applications\Python directory will produce a Python-2.7.1 directory AppPkg\Applications\Python directory will produce a Python-2.7.2 directory
containing the Python distribution. Python files that had to be modified for containing the Python distribution. Python files that had to be modified for
EDK II are in the AppPkg\Applications\Python\PyMod-2.7.1 directory. These EDK II are in the AppPkg\Applications\Python\PyMod-2.7.2 directory. These
files need to be copied into the corresponding directories within Python-2.7.1. files need to be copied into the corresponding directories within Python-2.7.2.
The Python 2.7.1 port was superseded before it was completed. The PyMod-2.7.1
directory tree will be deleted in the near future. Use the Python 2.7.2 port,
as described above.
There are some boiler-plate declarations and definitions that need to be 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 included in your application's INF and DSC build files. These are described
@ -133,7 +190,7 @@ commands within the "Visual Studio Command Prompt" window:
> cd C:\Source\Edk2 > cd C:\Source\Edk2
> .\edksetup.bat > .\edksetup.bat
> build ?a X64 ?p AppPkg\AppPkg.dsc > build -a X64 -p AppPkg\AppPkg.dsc
This will produce the application executables: Enquire.efi, Hello.efi, and 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 Main.efi in the C:\Source\Edk2\Build\AppPkg\DEBUG_VS2008\X64 directory; with
@ -147,6 +204,12 @@ 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 .inf file is all that is needed to link your application to the standard
libraries. 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 USAGE
===== =====
@ -206,8 +269,8 @@ library functions follow standard C programming practices as formalized by
ISO/IEC 9899:1990, with Addendum 1, (C 95) C language specification. ISO/IEC 9899:1990, with Addendum 1, (C 95) C language specification.
CONFIGURATION BUILD CONFIGURATION
============= ===================
DSC Files DSC Files
--------- ---------
@ -218,51 +281,49 @@ 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 your .dsc file using the !include directive. The provided AppPkg.dsc and
StdLib.dsc files do this on their last line. StdLib.dsc files do this on their last line.
Each affected section of the DSC file is described below. Each section of StdLib/StdLib.inc is described below.
[LibraryClasses] [LibraryClasses]
#
# Common Libraries
#
BaseLib|MdePkg/Library/BaseLib/BaseLib.inf
BaseMemoryLib|MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf
TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf
# To run in an emulation environment, such as NT32, comment out
# the TimerLib description above and un-comment the line below.
# TimerLib| MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf
# #
# C Standard Libraries # C Standard Libraries
# #
LibC|StdLib/LibC/LibC.inf LibC|StdLib/LibC/LibC.inf
LibStdLib|StdLib/LibC/StdLib/StdLib.inf
LibString|StdLib/LibC/String/String.inf
LibWchar|StdLib/LibC/Wchar/Wchar.inf
LibCType|StdLib/LibC/Ctype/Ctype.inf LibCType|StdLib/LibC/Ctype/Ctype.inf
LibTime|StdLib/LibC/Time/Time.inf
LibStdio|StdLib/LibC/Stdio/Stdio.inf
LibGdtoa|StdLib/LibC/gdtoa/gdtoa.inf
LibLocale|StdLib/LibC/Locale/Locale.inf LibLocale|StdLib/LibC/Locale/Locale.inf
LibUefi|StdLib/LibC/Uefi/Uefi.inf
LibMath|StdLib/LibC/Math/Math.inf LibMath|StdLib/LibC/Math/Math.inf
LibSignal|StdLib/LibC/Signal/Signal.inf LibSignal|StdLib/LibC/Signal/Signal.inf
LibNetUtil|StdLib/LibC/LibGcc/LibGcc.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
# Libraries for device abstractions within the Standard C Library. # Common Utilities for Networking Libraries
# Applications should not directly access any functions defined LibNetUtil|StdLib/LibC/NetUtil/NetUtil.inf
# in these libraries.
DevUtility|StdLib/LibC/Uefi/Devices/daUtility.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 DevConsole|StdLib/LibC/Uefi/Devices/daConsole.inf
DevShell|StdLib/LibC/Uefi/Devices/daShell.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 1: Library Class Descriptions Figure 1: Library Class Descriptions
==================================== ====================================
Descriptions of the Library Classes comprising the Standard Libraries must be Descriptions of the Library Classes comprising the Standard Libraries,
included in your application package's DSC file, as shown in Figure 1: Library as shown above in Figure 1: Library Class Descriptions, are provided.
Class Descriptions, above.
The directives in Figure 2: Package Component Descriptions will create The directives in Figure 2: Package Component Descriptions will create
instances of the BaseLib and BaseMemoryLib library classes that are built instances of the BaseLib and BaseMemoryLib library classes that are built
@ -271,6 +332,8 @@ 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 resolved during the second pass of the linker during Link-Time-Code-Generation
of the application. of the application.
A DXE driver version of the Socket library is also built.
[Components] [Components]
# BaseLib and BaseMemoryLib need to be built with the /GL- switch # BaseLib and BaseMemoryLib need to be built with the /GL- switch
# when using the Microsoft tool chains. This is required so that # when using the Microsoft tool chains. This is required so that
@ -286,44 +349,15 @@ of the application.
MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL- MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-
} }
##########
# Socket Layer
##########
StdLib/SocketDxe/SocketDxe.inf
Figure 2: Package Component Descriptions Figure 2: Package Component Descriptions
======================================== ========================================
The NULL TimerLib instance must be selected if you desire to run your
application under an emulation environment -- unless there is a supported
TimerLib for that environment. For example, the InOsEmuPkg provides a
DxeTimerLib which can be used for the TimerLib instance.
The "boilerplate" text in StdLib.inc will automatically adjust which Timer
Library is instantiated based upon whether the $(EMULATE) macro has been
defined, or not.
###
# Select the correct TimerLib instance depending upon whether running under
# an emulation environment, or not.
!ifndef $(EMULATE)
# Not running in an Emulation Environment
[LibraryClasses.IA32.UEFI_APPLICATION]
TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf
[LibraryClasses.X64.UEFI_APPLICATION]
TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf
[LibraryClasses.IPF.UEFI_APPLICATION]
PalLib|MdePkg/Library/UefiPalLib/UefiPalLib.inf
TimerLib|MdePkg/Library/SecPeiDxeTimerLibCpu/SecPeiDxeTimerLibCpu.inf
!else
# Use this instance if Running in an Emulation Environment.
[LibraryClasses.Common.UEFI_APPLICATION]
TimerLib|MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf
!endif
Figure 3: Timer Library Selection
=================================
Each compiler assumes, by default, that it will be used with standard libraries 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 and headers provided by the compiler vendor. Many of these assumptions are
incorrect for the UEFI environment. By including a BuildOptions section, as incorrect for the UEFI environment. By including a BuildOptions section, as
@ -333,17 +367,15 @@ tailored for compatibility with UEFI and the EDK II Standard Libraries.
[BuildOptions] [BuildOptions]
INTEL:*_*_IA32_CC_FLAGS = /Qfreestanding INTEL:*_*_IA32_CC_FLAGS = /Qfreestanding
MSFT:*_*_IA32_CC_FLAGS = /X /Zc:wchar_t MSFT:*_*_IA32_CC_FLAGS = /X /Zc:wchar_t
GCC:*_*_IA32_CC_FLAGS = /ffreestanding ?nostdinc ?nostdlib GCC:*_*_IA32_CC_FLAGS = -nostdinc -nostdlib
# The Build Options, below, are only used when building the C library # The Build Options, below, are only used when building the C library
# to be run under an emulation environment. The clock() system call # to be run under an emulation environment. They disable optimization
# is modified to return -1 indicating that it is unsupported. # which facillitates debugging under the Emulation environment.
# Just un-comment the lines below and select the correct
# TimerLib instance, above.
# INTEL:*_*_IA32_CC_FLAGS = /D NT32dvm # INTEL:*_*_IA32_CC_FLAGS = /Od
# MSFT:*_*_IA32_CC_FLAGS = /D NT32dvm # MSFT:*_*_IA32_CC_FLAGS = /Od
# GCC:*_*_IA32_CC_FLAGS = -DNT32dvm # GCC:*_*_IA32_CC_FLAGS = -O0
Figure 4: Package Build Options Figure 4: Package Build Options
=============================== ===============================
@ -373,7 +405,7 @@ below.
LibString LibString
LibStdio LibStdio
DevShell DevShell
Figure 6: Module Library Classes Figure 6: Module Library Classes
================================ ================================
@ -386,7 +418,7 @@ handled by the UEFI Shell. Without this class, only Console I/O is permitted.
INTEL:*_*_*_CC_FLAGS = /Qdiag-disable:181,186 INTEL:*_*_*_CC_FLAGS = /Qdiag-disable:181,186
MSFT:*_*_*_CC_FLAGS = /Oi- /wd4018 /wd4131 MSFT:*_*_*_CC_FLAGS = /Oi- /wd4018 /wd4131
GCC:*_*_IPF_SYMRENAME_FLAGS = --redefine-syms=Rename.txt GCC:*_*_IPF_SYMRENAME_FLAGS = --redefine-syms=Rename.txt
Figure 7: Module Build Options Figure 7: Module Build Options
============================== ==============================
@ -398,6 +430,23 @@ code from external sources, though, it may be necessary to disable some
warnings or enable/disable some compiler features. warnings or enable/disable some compiler features.
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 is populated from the StdLib/Efi/etc source
directory.
IMPLEMENTATION-Specific Features IMPLEMENTATION-Specific Features
================================ ================================
It is very strongly recommended that applications not use the long or It is very strongly recommended that applications not use the long or
@ -426,13 +475,12 @@ needed, use type PHYSICAL_ADDRESS.
Though not specifically required by the ISO/IEC 9899 standard, this Though not specifically required by the ISO/IEC 9899 standard, this
implementation of the Standard C Library provides the following system calls implementation of the Standard C Library provides the following system calls
which are declared in sys/EfiSysCall.h. which are declared in sys/EfiSysCall.h and/or unistd.h.
close dup dup2 fcntl close creat chmod dup dup2
fstat getcwd ioctl isatty fcntl fstat getcwd ioctl isatty
lseek lstat mkdir open lseek lstat mkdir open poll
poll read rename rmdir read rename rmdir stat unlink write
stat unlink write
The open function will accept file names of "stdin:", "stdout:", and "stderr:" 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 which cause the respective streams specified in the UEFI System Table to be
@ -440,4 +488,4 @@ opened. Normally, these are associated with the console device. When the
application is first started, these streams are automatically opened on File application is first started, these streams are automatically opened on File
Descriptors 0, 1, and 2 respectively. Descriptors 0, 1, and 2 respectively.
# # #

286
StdLib/ReadMe.txt
View File

@ -1,16 +1,31 @@
EDK II Standard Libraries EADK
EDK II Standard Libraries and Applications
ReadMe ReadMe
Beta Release Beta-1 Release
4:03 PM 8/2/2011 27 Jan. 2012
DRAFT
OVERVIEW OVERVIEW
======== ========
This document describes the EDK II specific aspects of installing, building, and The EADK (uEfi Application Development Kit) provides a set of standards-based
using the Standard C Library component of the EDK II Application Development libraries, along with utility and demonstration applications, intended to
Kit, EADK. ease development of UEFI applications based upon the EDK II Open-Source
distribution.
The EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateInternalFiles. 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.
Some components of the EADK can be built as drivers. These will be identified
explicitly in their documentation.
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 AppPkg This package contains applications which demonstrate use of the
Standard C Library. Standard C Library.
@ -28,16 +43,17 @@ The EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateIntern
Main This application is functionally identical to Hello, except that Main This application is functionally identical to Hello, except that
it uses the Standard C Library to provide a main() entry point. it uses the Standard C Library to provide a main() entry point.
Python A port of the Python-2.7.1 interpreter for UEFI. This Python A port of the Python-2.7.2 interpreter for UEFI. This
application is disabled by default. Un-comment the line for application is disabled by default.
PythonCore.inf in the [Components] section of AppPkg.dsc to See the PythonReadMe.txt file, in the Python directory,
enable building Python. for information on configuring and building Python.
Sockets A collection of applications demonstrating use of the Sockets A collection of applications demonstrating use of the
EDK II Socket Libraries. These applications include: EDK II Socket Libraries. These applications include:
* DataSink * DataSink
* DataSource * DataSource
* GetAddrInfo
* GetHostByAddr * GetHostByAddr
* GetHostByDns * GetHostByDns
* GetHostByName * GetHostByName
@ -45,6 +61,10 @@ The EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateIntern
* GetNetByName * GetNetByName
* GetServByName * GetServByName
* GetServByPort * GetServByPort
* OobRx
* OobTx
* RawIp4Rx
* RawIp4Tx
* RecvDgram * RecvDgram
* SetHostName * SetHostName
* SetSockOpt * SetSockOpt
@ -52,7 +72,31 @@ The EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateIntern
* WebServer * WebServer
StdLib The StdLib package contains the standard header files as well as StdLib The StdLib package contains the standard header files as well as
implementations of the standard libraries. implementations of 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 StdLibPrivateInternalFiles The contents of this package are for the
exclusive use of the library implementations in StdLib. Please do exclusive use of the library implementations in StdLib. Please do
@ -63,36 +107,45 @@ The EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateIntern
RELEASE NOTES RELEASE NOTES
============= =============
Fixes and Additions
-------------------
Beginning with this release, 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. This release of the EADK has some restrictions, as described below.
1. Only the Microsoft VS2005 and VS2008, Intel C Compiler 10.1 (or later), 1. Only the Microsoft VS2005 and VS2008, Intel C Compiler 10.1 (or later),
GCC 4.3 (mingw32), GCC 4.4, and GCC 4.5 C compilers are supported for GCC 4.3 (mingw32), GCC 4.4, and GCC 4.5 C compilers are supported for
Ia32 or X64 CPU architectures. Ia32 or X64 CPU architectures. Others may work but have not been tested.
2. The target machine must be running firmware which provides the 2. The target machine must be running firmware which provides the
UEFI 2.3 HII protocol. UEFI 2.3 HII protocol.
3. The EADK has not been through Intel's Quality Assurance process. This 3. The EADK has not been through Intel's Quality Assurance process. This
means that specified standards compliance has not been validated, nor means that specified standards compliance has not been validated, nor
has it undergone formal functionality testing. has it undergone formal functionality testing.
4. Applications must be launched from within the EFI Shell. 4. Applications must be launched from within the EFI Shell.
5. All file paths must use the forward slash, '/', as the separator 6. Absolute file paths may optionally be prefixed by a volume specifier
character.
6. Absolute file paths may optionally be prefixed by a volume specifier
such as "FS0:". The volume specifier is separated from the remainder 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 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. the Shell's mapped volume names as shown by the "map" command.
7. Absolute file paths that don't begin with a volume specifier; 7. Absolute file paths that don't begin with a volume specifier;
e.g. paths that begin with "/", are relative to the currently selected e.g. paths that begin with "/", are relative to the currently selected
volume. When the EFI Shell starts, there is NO selected volume. volume. When the EFI Shell first starts, there is NO selected volume.
8. The tmpfile(), and related, functions require that the current volume 8. The tmpfile(), and related, functions require that the current volume
have a temporary directory as specified in <paths.h>. This directory have a temporary directory as specified in <paths.h>. This directory
is specified by macro _PATH_TMP. is specified by macro _PATH_TMP as /Efi/StdLib/tmp.
9. Input line editing is not supported. Backspacing, deleting, or
otherwise attempting to modify interactive input will result in a
syntax error since the editing characters are interpreted the
same as any other character.
The Standard C Library provided by this package is a "hosted" implementation 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 conforming to the ISO/IEC 9899-1990 C Language Standard with Addendum 1. This
@ -103,20 +156,24 @@ convenience, it is assumed that your EDK II source tree is located at
C:\Source\Edk2. C:\Source\Edk2.
INSTALLATION EADK INSTALLATION
============ =================
The EADK is integrated within the EDK II source tree and is included with 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 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 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, source tree. The three package directories should be peers to the Conf,
MdePkg, Nt32Pkg, etc. directories. MdePkg, Nt32Pkg, etc. directories.
The Python 2.7.1 distribution must be downloaded from python.org before the The Python 2.7.2 distribution must be downloaded from python.org before the
Python application can be built. Extracting Python-2.7.1.tgz into the Python application can be built. Extracting Python-2.7.2.tgz into the
AppPkg\Applications\Python directory will produce a Python-2.7.1 directory AppPkg\Applications\Python directory will produce a Python-2.7.2 directory
containing the Python distribution. Python files that had to be modified for containing the Python distribution. Python files that had to be modified for
EDK II are in the AppPkg\Applications\Python\PyMod-2.7.1 directory. These EDK II are in the AppPkg\Applications\Python\PyMod-2.7.2 directory. These
files need to be copied into the corresponding directories within Python-2.7.1. files need to be copied into the corresponding directories within Python-2.7.2.
The Python 2.7.1 port was superseded before it was completed. The PyMod-2.7.1
directory tree will be deleted in the near future. Use the Python 2.7.2 port,
as described above.
There are some boiler-plate declarations and definitions that need to be 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 included in your application's INF and DSC build files. These are described
@ -133,7 +190,7 @@ commands within the "Visual Studio Command Prompt" window:
> cd C:\Source\Edk2 > cd C:\Source\Edk2
> .\edksetup.bat > .\edksetup.bat
> build ?a X64 ?p AppPkg\AppPkg.dsc > build -a X64 -p AppPkg\AppPkg.dsc
This will produce the application executables: Enquire.efi, Hello.efi, and 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 Main.efi in the C:\Source\Edk2\Build\AppPkg\DEBUG_VS2008\X64 directory; with
@ -147,6 +204,12 @@ 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 .inf file is all that is needed to link your application to the standard
libraries. 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 USAGE
===== =====
@ -206,8 +269,8 @@ library functions follow standard C programming practices as formalized by
ISO/IEC 9899:1990, with Addendum 1, (C 95) C language specification. ISO/IEC 9899:1990, with Addendum 1, (C 95) C language specification.
CONFIGURATION BUILD CONFIGURATION
============= ===================
DSC Files DSC Files
--------- ---------
@ -218,51 +281,49 @@ 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 your .dsc file using the !include directive. The provided AppPkg.dsc and
StdLib.dsc files do this on their last line. StdLib.dsc files do this on their last line.
Each affected section of the DSC file is described below. Each section of StdLib/StdLib.inc is described below.
[LibraryClasses] [LibraryClasses]
#
# Common Libraries
#
BaseLib|MdePkg/Library/BaseLib/BaseLib.inf
BaseMemoryLib|MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf
TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf
# To run in an emulation environment, such as NT32, comment out
# the TimerLib description above and un-comment the line below.
# TimerLib| MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf
# #
# C Standard Libraries # C Standard Libraries
# #
LibC|StdLib/LibC/LibC.inf LibC|StdLib/LibC/LibC.inf
LibStdLib|StdLib/LibC/StdLib/StdLib.inf
LibString|StdLib/LibC/String/String.inf
LibWchar|StdLib/LibC/Wchar/Wchar.inf
LibCType|StdLib/LibC/Ctype/Ctype.inf LibCType|StdLib/LibC/Ctype/Ctype.inf
LibTime|StdLib/LibC/Time/Time.inf
LibStdio|StdLib/LibC/Stdio/Stdio.inf
LibGdtoa|StdLib/LibC/gdtoa/gdtoa.inf
LibLocale|StdLib/LibC/Locale/Locale.inf LibLocale|StdLib/LibC/Locale/Locale.inf
LibUefi|StdLib/LibC/Uefi/Uefi.inf
LibMath|StdLib/LibC/Math/Math.inf LibMath|StdLib/LibC/Math/Math.inf
LibSignal|StdLib/LibC/Signal/Signal.inf LibSignal|StdLib/LibC/Signal/Signal.inf
LibNetUtil|StdLib/LibC/LibGcc/LibGcc.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
# Libraries for device abstractions within the Standard C Library. # Common Utilities for Networking Libraries
# Applications should not directly access any functions defined LibNetUtil|StdLib/LibC/NetUtil/NetUtil.inf
# in these libraries.
DevUtility|StdLib/LibC/Uefi/Devices/daUtility.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 DevConsole|StdLib/LibC/Uefi/Devices/daConsole.inf
DevShell|StdLib/LibC/Uefi/Devices/daShell.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 1: Library Class Descriptions Figure 1: Library Class Descriptions
==================================== ====================================
Descriptions of the Library Classes comprising the Standard Libraries must be Descriptions of the Library Classes comprising the Standard Libraries,
included in your application package's DSC file, as shown in Figure 1: Library as shown above in Figure 1: Library Class Descriptions, are provided.
Class Descriptions, above.
The directives in Figure 2: Package Component Descriptions will create The directives in Figure 2: Package Component Descriptions will create
instances of the BaseLib and BaseMemoryLib library classes that are built instances of the BaseLib and BaseMemoryLib library classes that are built
@ -271,6 +332,8 @@ 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 resolved during the second pass of the linker during Link-Time-Code-Generation
of the application. of the application.
A DXE driver version of the Socket library is also built.
[Components] [Components]
# BaseLib and BaseMemoryLib need to be built with the /GL- switch # BaseLib and BaseMemoryLib need to be built with the /GL- switch
# when using the Microsoft tool chains. This is required so that # when using the Microsoft tool chains. This is required so that
@ -286,44 +349,15 @@ of the application.
MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL- MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-
} }
##########
# Socket Layer
##########
StdLib/SocketDxe/SocketDxe.inf
Figure 2: Package Component Descriptions Figure 2: Package Component Descriptions
======================================== ========================================
The NULL TimerLib instance must be selected if you desire to run your
application under an emulation environment -- unless there is a supported
TimerLib for that environment. For example, the InOsEmuPkg provides a
DxeTimerLib which can be used for the TimerLib instance.
The "boilerplate" text in StdLib.inc will automatically adjust which Timer
Library is instantiated based upon whether the $(EMULATE) macro has been
defined, or not.
###
# Select the correct TimerLib instance depending upon whether running under
# an emulation environment, or not.
!ifndef $(EMULATE)
# Not running in an Emulation Environment
[LibraryClasses.IA32.UEFI_APPLICATION]
TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf
[LibraryClasses.X64.UEFI_APPLICATION]
TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf
[LibraryClasses.IPF.UEFI_APPLICATION]
PalLib|MdePkg/Library/UefiPalLib/UefiPalLib.inf
TimerLib|MdePkg/Library/SecPeiDxeTimerLibCpu/SecPeiDxeTimerLibCpu.inf
!else
# Use this instance if Running in an Emulation Environment.
[LibraryClasses.Common.UEFI_APPLICATION]
TimerLib|MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf
!endif
Figure 3: Timer Library Selection
=================================
Each compiler assumes, by default, that it will be used with standard libraries 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 and headers provided by the compiler vendor. Many of these assumptions are
incorrect for the UEFI environment. By including a BuildOptions section, as incorrect for the UEFI environment. By including a BuildOptions section, as
@ -333,17 +367,15 @@ tailored for compatibility with UEFI and the EDK II Standard Libraries.
[BuildOptions] [BuildOptions]
INTEL:*_*_IA32_CC_FLAGS = /Qfreestanding INTEL:*_*_IA32_CC_FLAGS = /Qfreestanding
MSFT:*_*_IA32_CC_FLAGS = /X /Zc:wchar_t MSFT:*_*_IA32_CC_FLAGS = /X /Zc:wchar_t
GCC:*_*_IA32_CC_FLAGS = /ffreestanding ?nostdinc ?nostdlib GCC:*_*_IA32_CC_FLAGS = -nostdinc -nostdlib
# The Build Options, below, are only used when building the C library # The Build Options, below, are only used when building the C library
# to be run under an emulation environment. The clock() system call # to be run under an emulation environment. They disable optimization
# is modified to return -1 indicating that it is unsupported. # which facillitates debugging under the Emulation environment.
# Just un-comment the lines below and select the correct
# TimerLib instance, above.
# INTEL:*_*_IA32_CC_FLAGS = /D NT32dvm # INTEL:*_*_IA32_CC_FLAGS = /Od
# MSFT:*_*_IA32_CC_FLAGS = /D NT32dvm # MSFT:*_*_IA32_CC_FLAGS = /Od
# GCC:*_*_IA32_CC_FLAGS = -DNT32dvm # GCC:*_*_IA32_CC_FLAGS = -O0
Figure 4: Package Build Options Figure 4: Package Build Options
=============================== ===============================
@ -373,7 +405,7 @@ below.
LibString LibString
LibStdio LibStdio
DevShell DevShell
Figure 6: Module Library Classes Figure 6: Module Library Classes
================================ ================================
@ -386,7 +418,7 @@ handled by the UEFI Shell. Without this class, only Console I/O is permitted.
INTEL:*_*_*_CC_FLAGS = /Qdiag-disable:181,186 INTEL:*_*_*_CC_FLAGS = /Qdiag-disable:181,186
MSFT:*_*_*_CC_FLAGS = /Oi- /wd4018 /wd4131 MSFT:*_*_*_CC_FLAGS = /Oi- /wd4018 /wd4131
GCC:*_*_IPF_SYMRENAME_FLAGS = --redefine-syms=Rename.txt GCC:*_*_IPF_SYMRENAME_FLAGS = --redefine-syms=Rename.txt
Figure 7: Module Build Options Figure 7: Module Build Options
============================== ==============================
@ -398,6 +430,23 @@ code from external sources, though, it may be necessary to disable some
warnings or enable/disable some compiler features. warnings or enable/disable some compiler features.
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 is populated from the StdLib/Efi/etc source
directory.
IMPLEMENTATION-Specific Features IMPLEMENTATION-Specific Features
================================ ================================
It is very strongly recommended that applications not use the long or It is very strongly recommended that applications not use the long or
@ -426,13 +475,12 @@ needed, use type PHYSICAL_ADDRESS.
Though not specifically required by the ISO/IEC 9899 standard, this Though not specifically required by the ISO/IEC 9899 standard, this
implementation of the Standard C Library provides the following system calls implementation of the Standard C Library provides the following system calls
which are declared in sys/EfiSysCall.h. which are declared in sys/EfiSysCall.h and/or unistd.h.
close dup dup2 fcntl close creat chmod dup dup2
fstat getcwd ioctl isatty fcntl fstat getcwd ioctl isatty
lseek lstat mkdir open lseek lstat mkdir open poll
poll read rename rmdir read rename rmdir stat unlink write
stat unlink write
The open function will accept file names of "stdin:", "stdout:", and "stderr:" 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 which cause the respective streams specified in the UEFI System Table to be
@ -440,4 +488,4 @@ opened. Normally, these are associated with the console device. When the
application is first started, these streams are automatically opened on File application is first started, these streams are automatically opened on File
Descriptors 0, 1, and 2 respectively. Descriptors 0, 1, and 2 respectively.
# # #

286
StdLibPrivateInternalFiles/ReadMe.txt
View File

@ -1,16 +1,31 @@
EDK II Standard Libraries EADK
EDK II Standard Libraries and Applications
ReadMe ReadMe
Beta Release Beta-1 Release
4:03 PM 8/2/2011 27 Jan. 2012
DRAFT
OVERVIEW OVERVIEW
======== ========
This document describes the EDK II specific aspects of installing, building, and The EADK (uEfi Application Development Kit) provides a set of standards-based
using the Standard C Library component of the EDK II Application Development libraries, along with utility and demonstration applications, intended to
Kit, EADK. ease development of UEFI applications based upon the EDK II Open-Source
distribution.
The EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateInternalFiles. 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.
Some components of the EADK can be built as drivers. These will be identified
explicitly in their documentation.
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 AppPkg This package contains applications which demonstrate use of the
Standard C Library. Standard C Library.
@ -28,16 +43,17 @@ The EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateIntern
Main This application is functionally identical to Hello, except that Main This application is functionally identical to Hello, except that
it uses the Standard C Library to provide a main() entry point. it uses the Standard C Library to provide a main() entry point.
Python A port of the Python-2.7.1 interpreter for UEFI. This Python A port of the Python-2.7.2 interpreter for UEFI. This
application is disabled by default. Un-comment the line for application is disabled by default.
PythonCore.inf in the [Components] section of AppPkg.dsc to See the PythonReadMe.txt file, in the Python directory,
enable building Python. for information on configuring and building Python.
Sockets A collection of applications demonstrating use of the Sockets A collection of applications demonstrating use of the
EDK II Socket Libraries. These applications include: EDK II Socket Libraries. These applications include:
* DataSink * DataSink
* DataSource * DataSource
* GetAddrInfo
* GetHostByAddr * GetHostByAddr
* GetHostByDns * GetHostByDns
* GetHostByName * GetHostByName
@ -45,6 +61,10 @@ The EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateIntern
* GetNetByName * GetNetByName
* GetServByName * GetServByName
* GetServByPort * GetServByPort
* OobRx
* OobTx
* RawIp4Rx
* RawIp4Tx
* RecvDgram * RecvDgram
* SetHostName * SetHostName
* SetSockOpt * SetSockOpt
@ -52,7 +72,31 @@ The EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateIntern
* WebServer * WebServer
StdLib The StdLib package contains the standard header files as well as StdLib The StdLib package contains the standard header files as well as
implementations of the standard libraries. implementations of 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 StdLibPrivateInternalFiles The contents of this package are for the
exclusive use of the library implementations in StdLib. Please do exclusive use of the library implementations in StdLib. Please do
@ -63,36 +107,45 @@ The EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateIntern
RELEASE NOTES RELEASE NOTES
============= =============
Fixes and Additions
-------------------
Beginning with this release, 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. This release of the EADK has some restrictions, as described below.
1. Only the Microsoft VS2005 and VS2008, Intel C Compiler 10.1 (or later), 1. Only the Microsoft VS2005 and VS2008, Intel C Compiler 10.1 (or later),
GCC 4.3 (mingw32), GCC 4.4, and GCC 4.5 C compilers are supported for GCC 4.3 (mingw32), GCC 4.4, and GCC 4.5 C compilers are supported for
Ia32 or X64 CPU architectures. Ia32 or X64 CPU architectures. Others may work but have not been tested.
2. The target machine must be running firmware which provides the 2. The target machine must be running firmware which provides the
UEFI 2.3 HII protocol. UEFI 2.3 HII protocol.
3. The EADK has not been through Intel's Quality Assurance process. This 3. The EADK has not been through Intel's Quality Assurance process. This
means that specified standards compliance has not been validated, nor means that specified standards compliance has not been validated, nor
has it undergone formal functionality testing. has it undergone formal functionality testing.
4. Applications must be launched from within the EFI Shell. 4. Applications must be launched from within the EFI Shell.
5. All file paths must use the forward slash, '/', as the separator 6. Absolute file paths may optionally be prefixed by a volume specifier
character.
6. Absolute file paths may optionally be prefixed by a volume specifier
such as "FS0:". The volume specifier is separated from the remainder 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 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. the Shell's mapped volume names as shown by the "map" command.
7. Absolute file paths that don't begin with a volume specifier; 7. Absolute file paths that don't begin with a volume specifier;
e.g. paths that begin with "/", are relative to the currently selected e.g. paths that begin with "/", are relative to the currently selected
volume. When the EFI Shell starts, there is NO selected volume. volume. When the EFI Shell first starts, there is NO selected volume.
8. The tmpfile(), and related, functions require that the current volume 8. The tmpfile(), and related, functions require that the current volume
have a temporary directory as specified in <paths.h>. This directory have a temporary directory as specified in <paths.h>. This directory
is specified by macro _PATH_TMP. is specified by macro _PATH_TMP as /Efi/StdLib/tmp.
9. Input line editing is not supported. Backspacing, deleting, or
otherwise attempting to modify interactive input will result in a
syntax error since the editing characters are interpreted the
same as any other character.
The Standard C Library provided by this package is a "hosted" implementation 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 conforming to the ISO/IEC 9899-1990 C Language Standard with Addendum 1. This
@ -103,20 +156,24 @@ convenience, it is assumed that your EDK II source tree is located at
C:\Source\Edk2. C:\Source\Edk2.
INSTALLATION EADK INSTALLATION
============ =================
The EADK is integrated within the EDK II source tree and is included with 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 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 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, source tree. The three package directories should be peers to the Conf,
MdePkg, Nt32Pkg, etc. directories. MdePkg, Nt32Pkg, etc. directories.
The Python 2.7.1 distribution must be downloaded from python.org before the The Python 2.7.2 distribution must be downloaded from python.org before the
Python application can be built. Extracting Python-2.7.1.tgz into the Python application can be built. Extracting Python-2.7.2.tgz into the
AppPkg\Applications\Python directory will produce a Python-2.7.1 directory AppPkg\Applications\Python directory will produce a Python-2.7.2 directory
containing the Python distribution. Python files that had to be modified for containing the Python distribution. Python files that had to be modified for
EDK II are in the AppPkg\Applications\Python\PyMod-2.7.1 directory. These EDK II are in the AppPkg\Applications\Python\PyMod-2.7.2 directory. These
files need to be copied into the corresponding directories within Python-2.7.1. files need to be copied into the corresponding directories within Python-2.7.2.
The Python 2.7.1 port was superseded before it was completed. The PyMod-2.7.1
directory tree will be deleted in the near future. Use the Python 2.7.2 port,
as described above.
There are some boiler-plate declarations and definitions that need to be 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 included in your application's INF and DSC build files. These are described
@ -133,7 +190,7 @@ commands within the "Visual Studio Command Prompt" window:
> cd C:\Source\Edk2 > cd C:\Source\Edk2
> .\edksetup.bat > .\edksetup.bat
> build ?a X64 ?p AppPkg\AppPkg.dsc > build -a X64 -p AppPkg\AppPkg.dsc
This will produce the application executables: Enquire.efi, Hello.efi, and 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 Main.efi in the C:\Source\Edk2\Build\AppPkg\DEBUG_VS2008\X64 directory; with
@ -147,6 +204,12 @@ 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 .inf file is all that is needed to link your application to the standard
libraries. 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 USAGE
===== =====
@ -206,8 +269,8 @@ library functions follow standard C programming practices as formalized by
ISO/IEC 9899:1990, with Addendum 1, (C 95) C language specification. ISO/IEC 9899:1990, with Addendum 1, (C 95) C language specification.
CONFIGURATION BUILD CONFIGURATION
============= ===================
DSC Files DSC Files
--------- ---------
@ -218,51 +281,49 @@ 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 your .dsc file using the !include directive. The provided AppPkg.dsc and
StdLib.dsc files do this on their last line. StdLib.dsc files do this on their last line.
Each affected section of the DSC file is described below. Each section of StdLib/StdLib.inc is described below.
[LibraryClasses] [LibraryClasses]
#
# Common Libraries
#
BaseLib|MdePkg/Library/BaseLib/BaseLib.inf
BaseMemoryLib|MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf
TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf
# To run in an emulation environment, such as NT32, comment out
# the TimerLib description above and un-comment the line below.
# TimerLib| MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf
# #
# C Standard Libraries # C Standard Libraries
# #
LibC|StdLib/LibC/LibC.inf LibC|StdLib/LibC/LibC.inf
LibStdLib|StdLib/LibC/StdLib/StdLib.inf
LibString|StdLib/LibC/String/String.inf
LibWchar|StdLib/LibC/Wchar/Wchar.inf
LibCType|StdLib/LibC/Ctype/Ctype.inf LibCType|StdLib/LibC/Ctype/Ctype.inf
LibTime|StdLib/LibC/Time/Time.inf
LibStdio|StdLib/LibC/Stdio/Stdio.inf
LibGdtoa|StdLib/LibC/gdtoa/gdtoa.inf
LibLocale|StdLib/LibC/Locale/Locale.inf LibLocale|StdLib/LibC/Locale/Locale.inf
LibUefi|StdLib/LibC/Uefi/Uefi.inf
LibMath|StdLib/LibC/Math/Math.inf LibMath|StdLib/LibC/Math/Math.inf
LibSignal|StdLib/LibC/Signal/Signal.inf LibSignal|StdLib/LibC/Signal/Signal.inf
LibNetUtil|StdLib/LibC/LibGcc/LibGcc.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
# Libraries for device abstractions within the Standard C Library. # Common Utilities for Networking Libraries
# Applications should not directly access any functions defined LibNetUtil|StdLib/LibC/NetUtil/NetUtil.inf
# in these libraries.
DevUtility|StdLib/LibC/Uefi/Devices/daUtility.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 DevConsole|StdLib/LibC/Uefi/Devices/daConsole.inf
DevShell|StdLib/LibC/Uefi/Devices/daShell.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 1: Library Class Descriptions Figure 1: Library Class Descriptions
==================================== ====================================
Descriptions of the Library Classes comprising the Standard Libraries must be Descriptions of the Library Classes comprising the Standard Libraries,
included in your application package's DSC file, as shown in Figure 1: Library as shown above in Figure 1: Library Class Descriptions, are provided.
Class Descriptions, above.
The directives in Figure 2: Package Component Descriptions will create The directives in Figure 2: Package Component Descriptions will create
instances of the BaseLib and BaseMemoryLib library classes that are built instances of the BaseLib and BaseMemoryLib library classes that are built
@ -271,6 +332,8 @@ 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 resolved during the second pass of the linker during Link-Time-Code-Generation
of the application. of the application.
A DXE driver version of the Socket library is also built.
[Components] [Components]
# BaseLib and BaseMemoryLib need to be built with the /GL- switch # BaseLib and BaseMemoryLib need to be built with the /GL- switch
# when using the Microsoft tool chains. This is required so that # when using the Microsoft tool chains. This is required so that
@ -286,44 +349,15 @@ of the application.
MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL- MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-
} }
##########
# Socket Layer
##########
StdLib/SocketDxe/SocketDxe.inf
Figure 2: Package Component Descriptions Figure 2: Package Component Descriptions
======================================== ========================================
The NULL TimerLib instance must be selected if you desire to run your
application under an emulation environment -- unless there is a supported
TimerLib for that environment. For example, the InOsEmuPkg provides a
DxeTimerLib which can be used for the TimerLib instance.
The "boilerplate" text in StdLib.inc will automatically adjust which Timer
Library is instantiated based upon whether the $(EMULATE) macro has been
defined, or not.
###
# Select the correct TimerLib instance depending upon whether running under
# an emulation environment, or not.
!ifndef $(EMULATE)
# Not running in an Emulation Environment
[LibraryClasses.IA32.UEFI_APPLICATION]
TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf
[LibraryClasses.X64.UEFI_APPLICATION]
TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf
[LibraryClasses.IPF.UEFI_APPLICATION]
PalLib|MdePkg/Library/UefiPalLib/UefiPalLib.inf
TimerLib|MdePkg/Library/SecPeiDxeTimerLibCpu/SecPeiDxeTimerLibCpu.inf
!else
# Use this instance if Running in an Emulation Environment.
[LibraryClasses.Common.UEFI_APPLICATION]
TimerLib|MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf
!endif
Figure 3: Timer Library Selection
=================================
Each compiler assumes, by default, that it will be used with standard libraries 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 and headers provided by the compiler vendor. Many of these assumptions are
incorrect for the UEFI environment. By including a BuildOptions section, as incorrect for the UEFI environment. By including a BuildOptions section, as
@ -333,17 +367,15 @@ tailored for compatibility with UEFI and the EDK II Standard Libraries.
[BuildOptions] [BuildOptions]
INTEL:*_*_IA32_CC_FLAGS = /Qfreestanding INTEL:*_*_IA32_CC_FLAGS = /Qfreestanding
MSFT:*_*_IA32_CC_FLAGS = /X /Zc:wchar_t MSFT:*_*_IA32_CC_FLAGS = /X /Zc:wchar_t
GCC:*_*_IA32_CC_FLAGS = /ffreestanding ?nostdinc ?nostdlib GCC:*_*_IA32_CC_FLAGS = -nostdinc -nostdlib
# The Build Options, below, are only used when building the C library # The Build Options, below, are only used when building the C library
# to be run under an emulation environment. The clock() system call # to be run under an emulation environment. They disable optimization
# is modified to return -1 indicating that it is unsupported. # which facillitates debugging under the Emulation environment.
# Just un-comment the lines below and select the correct
# TimerLib instance, above.
# INTEL:*_*_IA32_CC_FLAGS = /D NT32dvm # INTEL:*_*_IA32_CC_FLAGS = /Od
# MSFT:*_*_IA32_CC_FLAGS = /D NT32dvm # MSFT:*_*_IA32_CC_FLAGS = /Od
# GCC:*_*_IA32_CC_FLAGS = -DNT32dvm # GCC:*_*_IA32_CC_FLAGS = -O0
Figure 4: Package Build Options Figure 4: Package Build Options
=============================== ===============================
@ -373,7 +405,7 @@ below.
LibString LibString
LibStdio LibStdio
DevShell DevShell
Figure 6: Module Library Classes Figure 6: Module Library Classes
================================ ================================
@ -386,7 +418,7 @@ handled by the UEFI Shell. Without this class, only Console I/O is permitted.
INTEL:*_*_*_CC_FLAGS = /Qdiag-disable:181,186 INTEL:*_*_*_CC_FLAGS = /Qdiag-disable:181,186
MSFT:*_*_*_CC_FLAGS = /Oi- /wd4018 /wd4131 MSFT:*_*_*_CC_FLAGS = /Oi- /wd4018 /wd4131
GCC:*_*_IPF_SYMRENAME_FLAGS = --redefine-syms=Rename.txt GCC:*_*_IPF_SYMRENAME_FLAGS = --redefine-syms=Rename.txt
Figure 7: Module Build Options Figure 7: Module Build Options
============================== ==============================
@ -398,6 +430,23 @@ code from external sources, though, it may be necessary to disable some
warnings or enable/disable some compiler features. warnings or enable/disable some compiler features.
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 is populated from the StdLib/Efi/etc source
directory.
IMPLEMENTATION-Specific Features IMPLEMENTATION-Specific Features
================================ ================================
It is very strongly recommended that applications not use the long or It is very strongly recommended that applications not use the long or
@ -426,13 +475,12 @@ needed, use type PHYSICAL_ADDRESS.
Though not specifically required by the ISO/IEC 9899 standard, this Though not specifically required by the ISO/IEC 9899 standard, this
implementation of the Standard C Library provides the following system calls implementation of the Standard C Library provides the following system calls
which are declared in sys/EfiSysCall.h. which are declared in sys/EfiSysCall.h and/or unistd.h.
close dup dup2 fcntl close creat chmod dup dup2
fstat getcwd ioctl isatty fcntl fstat getcwd ioctl isatty
lseek lstat mkdir open lseek lstat mkdir open poll
poll read rename rmdir read rename rmdir stat unlink write
stat unlink write
The open function will accept file names of "stdin:", "stdout:", and "stderr:" 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 which cause the respective streams specified in the UEFI System Table to be
@ -440,4 +488,4 @@ opened. Normally, these are associated with the console device. When the
application is first started, these streams are automatically opened on File application is first started, these streams are automatically opened on File
Descriptors 0, 1, and 2 respectively. Descriptors 0, 1, and 2 respectively.
# # #