Add plain-text ReadMe files and delete the PDF version.
authordarylm503 <darylm503@6f19259b-4bc3-4df7-8a09-765794883524>
Tue, 2 Aug 2011 23:09:06 +0000 (23:09 +0000)
committerdarylm503 <darylm503@6f19259b-4bc3-4df7-8a09-765794883524>
Tue, 2 Aug 2011 23:09:06 +0000 (23:09 +0000)
Clean up some comments.

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@12080 6f19259b-4bc3-4df7-8a09-765794883524

AppPkg/AppPkg.dsc
AppPkg/ReadMe.pdf [deleted file]
AppPkg/ReadMe.txt [new file with mode: 0644]
StdLib/ReadMe.pdf [deleted file]
StdLib/ReadMe.txt [new file with mode: 0644]
StdLib/StdLib.dsc
StdLib/StdLib.inc
StdLibPrivateInternalFiles/ReadMe.pdf [deleted file]
StdLibPrivateInternalFiles/ReadMe.txt [new file with mode: 0644]

index 59341ec..b1a8108 100644 (file)
       gStdLibTokenSpaceGuid.WebServer_HttpPort|80\r
   }\r
 \r
-###################################################################################################\r
+##############################################################################\r
 #\r
-#       Include Boilerplate text required for building with the Standard Libraries.\r
+#  Include Boilerplate text required for building with the Standard Libraries.\r
 #\r
-###################################################################################################\r
+##############################################################################\r
 !include StdLib/StdLib.inc\r
diff --git a/AppPkg/ReadMe.pdf b/AppPkg/ReadMe.pdf
deleted file mode 100644 (file)
index 2ed6616..0000000
Binary files a/AppPkg/ReadMe.pdf and /dev/null differ
diff --git a/AppPkg/ReadMe.txt b/AppPkg/ReadMe.txt
new file mode 100644 (file)
index 0000000..731b18d
--- /dev/null
@@ -0,0 +1,443 @@
+                           EDK II Standard Libraries\r
+                                    ReadMe\r
+                                 Beta Release\r
+                               4:03 PM 8/2/2011\r
+\r
+\r
+OVERVIEW\r
+========\r
+This document describes the EDK II specific aspects of installing, building, and\r
+using the Standard C Library component of the EDK II Application Development\r
+Kit, EADK.\r
+\r
+The EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateInternalFiles.\r
+\r
+  AppPkg   This package contains applications which demonstrate use of the\r
+           Standard C Library.\r
+           These applications reside in AppPkg/Applications.\r
+\r
+      Enquire  This is a program that determines many properties of the\r
+               C compiler and the target machine that Enquire is run on.  The\r
+               only changes required to port this 1990s era Unix program to\r
+               EDK II were the addition of eight pragmas to enquire.c in\r
+               order to disable some Microsoft VC++ specific warnings.\r
+\r
+      Hello    This is a very simple EDK II native application that doesn't use\r
+               any features of the Standard C Library.\r
+\r
+      Main     This application is functionally identical to Hello, except that\r
+               it uses the Standard C Library to provide a main() entry point.\r
+\r
+      Python   A port of the Python-2.7.1 interpreter for UEFI.  This\r
+               application is disabled by default.  Un-comment the line for\r
+               PythonCore.inf in the [Components] section of AppPkg.dsc to\r
+               enable building Python.\r
+\r
+      Sockets  A collection of applications demonstrating use of the\r
+               EDK II Socket Libraries.  These applications include:\r
+\r
+               *   DataSink\r
+               *   DataSource\r
+               *   GetHostByAddr\r
+               *   GetHostByDns\r
+               *   GetHostByName\r
+               *   GetNetByAddr\r
+               *   GetNetByName\r
+               *   GetServByName\r
+               *   GetServByPort\r
+               *   RecvDgram\r
+               *   SetHostName\r
+               *   SetSockOpt\r
+               *   TftpServer\r
+               *   WebServer\r
+\r
+  StdLib   The StdLib package contains the standard header files as well as\r
+           implementations of the standard libraries.\r
+\r
+  StdLibPrivateInternalFiles  The contents of this package are for the\r
+           exclusive use of the library implementations in StdLib.  Please do\r
+           not use anything from this package in your application or else\r
+           unexpected behavior may occur.\r
+           This package may be removed in a future release.\r
+\r
+\r
+RELEASE NOTES\r
+=============\r
+This release of the EADK has some restrictions, as described below.\r
+\r
+    1. Only the Microsoft VS2005 and VS2008, Intel C Compiler 10.1 (or later),\r
+        GCC 4.3 (mingw32), GCC 4.4, and GCC 4.5 C compilers are supported for\r
+        Ia32 or X64 CPU architectures.\r
+        \r
+    2. The target machine must be running firmware which provides the\r
+        UEFI 2.3 HII protocol.\r
+        \r
+    3. The EADK has not been through Intel's Quality Assurance process. This\r
+        means that specified standards compliance has not been validated, nor\r
+        has it undergone formal functionality testing.\r
+        \r
+    4. Applications must be launched from within the EFI Shell.\r
+    \r
+    5. All file paths must use the forward slash, '/', as the separator\r
+        character.\r
+        \r
+    6. Absolute file paths may optionally be prefixed by a volume specifier\r
+        such as "FS0:".  The volume specifier is separated from the remainder\r
+        of the path by a single colon ':'.  The volume specifier must be one of\r
+        the Shell's mapped volume names as shown by the "map" command.\r
+        \r
+    7. Absolute file paths that don't begin with a volume specifier;\r
+        e.g. paths that begin with "/", are relative to the currently selected\r
+        volume.  When the EFI Shell starts, there is NO selected volume.\r
+        \r
+    8. The tmpfile(), and related, functions require that the current volume\r
+        have a temporary directory as specified in <paths.h>.  This directory\r
+        is specified by macro _PATH_TMP.\r
+\r
+The Standard C Library provided by this package is a "hosted" implementation\r
+conforming to the ISO/IEC 9899-1990 C Language Standard with Addendum 1. This\r
+is commonly referred to as the "C 95" specification or ISO/IEC 9899:199409.\r
+The following instructions assume that you have an existing EDK II or UDK 2010\r
+source tree that has been configured to build with your tool chain.  For\r
+convenience, it is assumed that your EDK II source tree is located at\r
+C:\Source\Edk2.\r
+\r
+\r
+INSTALLATION\r
+============\r
+The EADK is integrated within the EDK II source tree and is included with\r
+current EDK II check-outs.  If they are missing from your tree, they may be\r
+installed by extracting, downloading or copying them to the root of your EDK II\r
+source tree.  The three package directories should be peers to the Conf,\r
+MdePkg, Nt32Pkg, etc. directories.\r
+\r
+The Python 2.7.1 distribution must be downloaded from python.org before the\r
+Python application can be built.  Extracting Python-2.7.1.tgz into the\r
+AppPkg\Applications\Python directory will produce a Python-2.7.1 directory\r
+containing the Python distribution.  Python files that had to be modified for\r
+EDK II are in the AppPkg\Applications\Python\PyMod-2.7.1 directory.  These\r
+files need to be copied into the corresponding directories within Python-2.7.1.\r
+\r
+There are some boiler-plate declarations and definitions that need to be\r
+included in your application's INF and DSC build files.  These are described\r
+in the CONFIGURATION section, below.\r
+\r
+\r
+BUILDING\r
+========\r
+It is not necessary to build the libraries separately from the target\r
+application(s). If the application references the libraries, as described in\r
+USAGE, below; the required libraries will be built as needed.\r
+To build the applications included in AppPkg, one would execute the following\r
+commands within the "Visual Studio Command Prompt" window:\r
+\r
+    > cd C:\Source\Edk2\r
+    > .\edksetup.bat\r
+    > build ?a X64 ?p AppPkg\AppPkg.dsc\r
+\r
+This will produce the application executables: Enquire.efi, Hello.efi, and\r
+Main.efi in the C:\Source\Edk2\Build\AppPkg\DEBUG_VS2008\X64 directory; with\r
+the DEBUG_VS2008 component being replaced with the actual tool chain and build\r
+type you have selected in Conf\Tools_def.txt. These executables can now be\r
+loaded onto the target platform and executed.\r
+\r
+If you examine the AppPkg.dsc file, you will notice that the StdLib package is\r
+referenced in order to resolve the library classes comprising the Standard\r
+C Library.  This, plus referencing the StdLib package in your application's\r
+.inf file is all that is needed to link your application to the standard\r
+libraries.\r
+\r
+\r
+USAGE\r
+=====\r
+This implementation of the Standard C Library is comprised of 16 separate\r
+libraries in addition to the standard header files. Nine of the libraries are\r
+associated with use of one of the standard headers; thus, if the header is used\r
+in an application, it must be linked with the associated library.  Three\r
+libraries are used to provide the Console and File-system device abstractions.\r
+The libraries and associated header files are described in the following table.\r
+\r
+ Library\r
+  Class      Header File(s)    Notes\r
+----------  ----------------  -------------------------------------------------\r
+LibC        -- Use Always --  This library is always required.\r
+LibCtype    ctype.h, wctype.h Character classification and mapping\r
+LibLocale   locale.h          Localization types, macros, and functions\r
+LibMath     math.h            Mathematical functions, types, and macros\r
+LibStdio    stdio.h           Standard Input and Output functions, types, and\r
+                              macros\r
+LibStdLib   stdlib.h          General Utilities for numeric conversion, random\r
+                              num., etc.\r
+LibString   string.h          String copying, concatenation, comparison,\r
+                              & search\r
+LibSignal   signal.h          Functions and types for handling run-time\r
+                              conditions\r
+LibTime     time.h            Time and Date types, macros, and functions\r
+LibUefi     sys/EfiSysCall.h  Provides the UEFI system interface and\r
+                              "System Calls"\r
+LibWchar    wchar.h           Extended multibyte and wide character utilities\r
+LibNetUtil                    Network address and number manipulation utilities\r
+DevConsole                    Automatically provided  File I/O abstractions for\r
+                              the UEFI Console device.  No need to list this\r
+                              library class in your INF file(s).\r
+DevShell    Add if desired    File I/O abstractions using UEFI shell\r
+                              facilities.  Add this to the application's main\r
+                              INF file if file-system access needed.\r
+DevUtility  -- Do Not Use --  Utility functions used by the Device abstractions\r
+LibGdtoa    -- Do Not Use --  This library is used internally and should not\r
+                              need to be explicitly specified by an\r
+                              application.  It must be defined as one of the\r
+                              available library classes in the application's\r
+                              DSC file.\r
+\r
+                         Table 1:  Standard Libraries\r
+                         ============================\r
+\r
+\r
+These libraries must be fully described in the [LibraryClasses] section of the\r
+application package's DSC file. Then, each individual application needs to\r
+specify which libraries to link to by specifying the Library Class, from the\r
+above table, in the [LibraryClasses] section of the application's INF file. The\r
+AppPkg.dsc, StdLib.dsc, and Enquire.inf files provide good examples of this.\r
+More details are in the CONFIGURATION section, below.\r
+\r
+Within the source files of the application, use of the Standard headers and\r
+library functions follow standard C programming practices as formalized by\r
+ISO/IEC 9899:1990, with Addendum 1, (C 95) C language specification.\r
+\r
+\r
+CONFIGURATION\r
+=============\r
+DSC Files\r
+---------\r
+\r
+All EDK II packages which build applications that use the standard libraries\r
+must include some "boilerplate" text in the package's .dsc file.  To make it\r
+easier, and to reduce cut-and-paste errors, the "boilerplate" text has been\r
+consolidated into a single file, StdLib/StdLib.inc, which can be included in\r
+your .dsc file using the !include directive.  The provided AppPkg.dsc and\r
+StdLib.dsc files do this on their last line.\r
+\r
+Each affected section of the DSC file is described below.\r
+\r
+  [LibraryClasses]\r
+    #\r
+    # Common Libraries\r
+    #\r
+    BaseLib|MdePkg/Library/BaseLib/BaseLib.inf\r
+    BaseMemoryLib|MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf\r
+\r
+    TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf\r
+    # To run in an emulation environment, such as NT32, comment out\r
+    # the TimerLib description above and un-comment the line below.\r
+    # TimerLib| MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf\r
+\r
+    #\r
+    # C Standard Libraries\r
+    #\r
+    LibC|StdLib/LibC/LibC.inf\r
+    LibStdLib|StdLib/LibC/StdLib/StdLib.inf\r
+    LibString|StdLib/LibC/String/String.inf\r
+    LibWchar|StdLib/LibC/Wchar/Wchar.inf\r
+    LibCType|StdLib/LibC/Ctype/Ctype.inf\r
+    LibTime|StdLib/LibC/Time/Time.inf\r
+    LibStdio|StdLib/LibC/Stdio/Stdio.inf\r
+    LibGdtoa|StdLib/LibC/gdtoa/gdtoa.inf\r
+    LibLocale|StdLib/LibC/Locale/Locale.inf\r
+    LibUefi|StdLib/LibC/Uefi/Uefi.inf\r
+    LibMath|StdLib/LibC/Math/Math.inf\r
+    LibSignal|StdLib/LibC/Signal/Signal.inf\r
+    LibNetUtil|StdLib/LibC/LibGcc/LibGcc.inf\r
+\r
+  # Libraries for device abstractions within the Standard C Library.\r
+  # Applications should not directly access any functions defined\r
+  # in these libraries.\r
+    DevUtility|StdLib/LibC/Uefi/Devices/daUtility.inf\r
+    DevConsole|StdLib/LibC/Uefi/Devices/daConsole.inf\r
+    DevShell|StdLib/LibC/Uefi/Devices/daShell.inf\r
+\r
+                     Figure 1: Library Class Descriptions\r
+                     ====================================\r
+\r
+\r
+Descriptions of the Library Classes comprising the Standard Libraries must be\r
+included in your application package's DSC file, as shown in Figure 1: Library\r
+Class Descriptions, above.\r
+\r
+The directives in Figure 2: Package Component Descriptions will create\r
+instances of the BaseLib and BaseMemoryLib library classes that are built\r
+with Link-time-Code-Generation disabled.  This is necessary when using the\r
+Microsoft tool chains in order to allow the library's functions to be\r
+resolved during the second pass of the linker during Link-Time-Code-Generation\r
+of the application.\r
+\r
+  [Components]\r
+  # BaseLib and BaseMemoryLib need to be built with the /GL- switch\r
+  # when using the Microsoft tool chains.  This is required so that\r
+  # the library functions can be resolved during the second pass of\r
+  # the linker during link-time-code-generation.\r
+  #\r
+    MdePkg/Library/BaseLib/BaseLib.inf {\r
+      <BuildOptions>\r
+        MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-\r
+    }\r
+    MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf {\r
+      <BuildOptions>\r
+        MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-\r
+    }\r
+\r
+                    Figure 2: Package Component Descriptions\r
+                    ========================================\r
+\r
+\r
+The NULL TimerLib instance must be selected if you desire to run your\r
+application under an emulation environment -- unless there is a supported\r
+TimerLib for that environment.  For example, the InOsEmuPkg provides a\r
+DxeTimerLib which can be used for the TimerLib instance.\r
+\r
+The "boilerplate" text in StdLib.inc will automatically adjust which Timer\r
+Library is instantiated based upon whether the $(EMULATE) macro has been\r
+defined, or not.\r
+\r
+  ###\r
+  # Select the correct TimerLib instance depending upon whether running under\r
+  # an emulation environment, or not.\r
+  !ifndef $(EMULATE)\r
+    # Not running in an Emulation Environment\r
+  [LibraryClasses.IA32.UEFI_APPLICATION]\r
+    TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf\r
+\r
+  [LibraryClasses.X64.UEFI_APPLICATION]\r
+    TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf\r
+\r
+  [LibraryClasses.IPF.UEFI_APPLICATION]\r
+    PalLib|MdePkg/Library/UefiPalLib/UefiPalLib.inf\r
+    TimerLib|MdePkg/Library/SecPeiDxeTimerLibCpu/SecPeiDxeTimerLibCpu.inf\r
+\r
+  !else\r
+    # Use this instance if Running in an Emulation Environment.\r
+  [LibraryClasses.Common.UEFI_APPLICATION]\r
+    TimerLib|MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf\r
+  !endif\r
+\r
+                      Figure 3: Timer Library Selection\r
+                      =================================\r
+\r
+\r
+Each compiler assumes, by default, that it will be used with standard libraries\r
+and headers provided by the compiler vendor.  Many of these assumptions are\r
+incorrect for the UEFI environment.  By including a BuildOptions section, as\r
+shown in Figure 3: Package Build Options, these assumptions can be\r
+tailored for compatibility with UEFI and the EDK II Standard Libraries.\r
+\r
+  [BuildOptions]\r
+    INTEL:*_*_IA32_CC_FLAGS  = /Qfreestanding\r
+     MSFT:*_*_IA32_CC_FLAGS  = /X /Zc:wchar_t\r
+      GCC:*_*_IA32_CC_FLAGS  = /ffreestanding ?nostdinc ?nostdlib\r
+\r
+  # The Build Options, below, are only used when building the C library\r
+  # to be run under an emulation environment.  The clock() system call\r
+  # is modified to return -1 indicating that it is unsupported.\r
+  # Just un-comment the lines below and select the correct\r
+  # TimerLib instance, above.\r
+\r
+    # INTEL:*_*_IA32_CC_FLAGS  = /D NT32dvm\r
+    #  MSFT:*_*_IA32_CC_FLAGS  = /D NT32dvm\r
+    #   GCC:*_*_IA32_CC_FLAGS  = -DNT32dvm\r
+\r
+                        Figure 4: Package Build Options\r
+                        ===============================\r
+\r
+The "boilerplate" text can be included using a !include directive in the\r
+package's .dsc file.  The provided AppPkg.dsc and StdLib.dsc files include\r
+the "boilerplate" text as follows:\r
+\r
+  # Include Boilerplate text required for building with the Standard Libraries.\r
+  #\r
+  #############################################################################\r
+  !include StdLib/StdLib.inc\r
+\r
+                      Figure 5: "Boilerplate" Inclusion\r
+                      =================================\r
+\r
+\r
+INF Files\r
+=========\r
+The INF files for most modules will not require special directives in order to\r
+support the Standard Libraries.  The two cases which could occur are described\r
+below.\r
+\r
+  [LibraryClasses]\r
+    UefiLib\r
+    LibC\r
+    LibString\r
+    LibStdio\r
+    DevShell\r
+  \r
+                      Figure 6: Module Library Classes\r
+                      ================================\r
+\r
+\r
+Modules of type UEFI_APPLICATION that perform file I/O should include library\r
+class DevShell.  Including this library class will allow file operations to be\r
+handled by the UEFI Shell.  Without this class, only Console I/O is permitted.\r
+\r
+ [BuildOptions]\r
+  INTEL:*_*_*_CC_FLAGS          = /Qdiag-disable:181,186\r
+   MSFT:*_*_*_CC_FLAGS          = /Oi- /wd4018 /wd4131\r
+    GCC:*_*_IPF_SYMRENAME_FLAGS = --redefine-syms=Rename.txt\r
+    \r
+                        Figure 7: Module Build Options\r
+                        ==============================\r
+\r
+\r
+An application's INF file may need to include a [BuildOptions] section\r
+specifying additional compiler and linker flags necessary to allow the\r
+application to be built. Usually, this section is not needed.  When building\r
+code from external sources, though, it may be necessary to disable some\r
+warnings or enable/disable some compiler features.\r
+\r
+\r
+IMPLEMENTATION-Specific Features\r
+================================\r
+It is very strongly recommended that applications not use the long or\r
+unsigned long types. The size of this type varies between compilers and is one\r
+of the less portable aspects of C. Instead, one should use the UEFI defined\r
+types whenever possible. Use of these types, listed below for reference,\r
+ensures that the declared objects have unambiguous, explicitly declared, sizes\r
+and characteristics.\r
+\r
+        UINT64   INT64     UINT32   INT32   UINT16   CHAR16\r
+        INT16    BOOLEAN   UINT8    CHAR8   INT8\r
+        UINTN    INTN                       PHYSICALADDRESS\r
+\r
+There are similar types declared in sys/types.h and related files.\r
+\r
+The types UINTN and INTN have the native width of the target processor\r
+architecture. Thus, INTN on IA32 has a width of 32 bits while INTN on X64 and\r
+IPF has a width of 64 bits.\r
+\r
+For maximum portability, data objects intended to hold addresses should be\r
+declared with type intptr_t or uintptr_t. These types, declared in\r
+sys/stdint.h, can be used to create objects capable of holding pointers. Note\r
+that these types will generate different sized objects on different processor\r
+architectures.  If a constant size across all processors and compilers is\r
+needed, use type PHYSICAL_ADDRESS.\r
+\r
+Though not specifically required by the ISO/IEC 9899 standard, this\r
+implementation of the Standard C Library provides the following system calls\r
+which are declared in sys/EfiSysCall.h.\r
+\r
+          close   dup      dup2     fcntl\r
+          fstat   getcwd   ioctl    isatty\r
+          lseek   lstat    mkdir    open\r
+          poll    read     rename   rmdir\r
+          stat    unlink   write\r
+\r
+The open function will accept file names of "stdin:", "stdout:", and "stderr:"\r
+which cause the respective streams specified in the UEFI System Table to be\r
+opened.  Normally, these are associated with the console device.  When the\r
+application is first started, these streams are automatically opened on File\r
+Descriptors 0, 1, and 2 respectively.\r
+\r
+\r
diff --git a/StdLib/ReadMe.pdf b/StdLib/ReadMe.pdf
deleted file mode 100644 (file)
index 9dc6c0a..0000000
Binary files a/StdLib/ReadMe.pdf and /dev/null differ
diff --git a/StdLib/ReadMe.txt b/StdLib/ReadMe.txt
new file mode 100644 (file)
index 0000000..731b18d
--- /dev/null
@@ -0,0 +1,443 @@
+                           EDK II Standard Libraries\r
+                                    ReadMe\r
+                                 Beta Release\r
+                               4:03 PM 8/2/2011\r
+\r
+\r
+OVERVIEW\r
+========\r
+This document describes the EDK II specific aspects of installing, building, and\r
+using the Standard C Library component of the EDK II Application Development\r
+Kit, EADK.\r
+\r
+The EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateInternalFiles.\r
+\r
+  AppPkg   This package contains applications which demonstrate use of the\r
+           Standard C Library.\r
+           These applications reside in AppPkg/Applications.\r
+\r
+      Enquire  This is a program that determines many properties of the\r
+               C compiler and the target machine that Enquire is run on.  The\r
+               only changes required to port this 1990s era Unix program to\r
+               EDK II were the addition of eight pragmas to enquire.c in\r
+               order to disable some Microsoft VC++ specific warnings.\r
+\r
+      Hello    This is a very simple EDK II native application that doesn't use\r
+               any features of the Standard C Library.\r
+\r
+      Main     This application is functionally identical to Hello, except that\r
+               it uses the Standard C Library to provide a main() entry point.\r
+\r
+      Python   A port of the Python-2.7.1 interpreter for UEFI.  This\r
+               application is disabled by default.  Un-comment the line for\r
+               PythonCore.inf in the [Components] section of AppPkg.dsc to\r
+               enable building Python.\r
+\r
+      Sockets  A collection of applications demonstrating use of the\r
+               EDK II Socket Libraries.  These applications include:\r
+\r
+               *   DataSink\r
+               *   DataSource\r
+               *   GetHostByAddr\r
+               *   GetHostByDns\r
+               *   GetHostByName\r
+               *   GetNetByAddr\r
+               *   GetNetByName\r
+               *   GetServByName\r
+               *   GetServByPort\r
+               *   RecvDgram\r
+               *   SetHostName\r
+               *   SetSockOpt\r
+               *   TftpServer\r
+               *   WebServer\r
+\r
+  StdLib   The StdLib package contains the standard header files as well as\r
+           implementations of the standard libraries.\r
+\r
+  StdLibPrivateInternalFiles  The contents of this package are for the\r
+           exclusive use of the library implementations in StdLib.  Please do\r
+           not use anything from this package in your application or else\r
+           unexpected behavior may occur.\r
+           This package may be removed in a future release.\r
+\r
+\r
+RELEASE NOTES\r
+=============\r
+This release of the EADK has some restrictions, as described below.\r
+\r
+    1. Only the Microsoft VS2005 and VS2008, Intel C Compiler 10.1 (or later),\r
+        GCC 4.3 (mingw32), GCC 4.4, and GCC 4.5 C compilers are supported for\r
+        Ia32 or X64 CPU architectures.\r
+        \r
+    2. The target machine must be running firmware which provides the\r
+        UEFI 2.3 HII protocol.\r
+        \r
+    3. The EADK has not been through Intel's Quality Assurance process. This\r
+        means that specified standards compliance has not been validated, nor\r
+        has it undergone formal functionality testing.\r
+        \r
+    4. Applications must be launched from within the EFI Shell.\r
+    \r
+    5. All file paths must use the forward slash, '/', as the separator\r
+        character.\r
+        \r
+    6. Absolute file paths may optionally be prefixed by a volume specifier\r
+        such as "FS0:".  The volume specifier is separated from the remainder\r
+        of the path by a single colon ':'.  The volume specifier must be one of\r
+        the Shell's mapped volume names as shown by the "map" command.\r
+        \r
+    7. Absolute file paths that don't begin with a volume specifier;\r
+        e.g. paths that begin with "/", are relative to the currently selected\r
+        volume.  When the EFI Shell starts, there is NO selected volume.\r
+        \r
+    8. The tmpfile(), and related, functions require that the current volume\r
+        have a temporary directory as specified in <paths.h>.  This directory\r
+        is specified by macro _PATH_TMP.\r
+\r
+The Standard C Library provided by this package is a "hosted" implementation\r
+conforming to the ISO/IEC 9899-1990 C Language Standard with Addendum 1. This\r
+is commonly referred to as the "C 95" specification or ISO/IEC 9899:199409.\r
+The following instructions assume that you have an existing EDK II or UDK 2010\r
+source tree that has been configured to build with your tool chain.  For\r
+convenience, it is assumed that your EDK II source tree is located at\r
+C:\Source\Edk2.\r
+\r
+\r
+INSTALLATION\r
+============\r
+The EADK is integrated within the EDK II source tree and is included with\r
+current EDK II check-outs.  If they are missing from your tree, they may be\r
+installed by extracting, downloading or copying them to the root of your EDK II\r
+source tree.  The three package directories should be peers to the Conf,\r
+MdePkg, Nt32Pkg, etc. directories.\r
+\r
+The Python 2.7.1 distribution must be downloaded from python.org before the\r
+Python application can be built.  Extracting Python-2.7.1.tgz into the\r
+AppPkg\Applications\Python directory will produce a Python-2.7.1 directory\r
+containing the Python distribution.  Python files that had to be modified for\r
+EDK II are in the AppPkg\Applications\Python\PyMod-2.7.1 directory.  These\r
+files need to be copied into the corresponding directories within Python-2.7.1.\r
+\r
+There are some boiler-plate declarations and definitions that need to be\r
+included in your application's INF and DSC build files.  These are described\r
+in the CONFIGURATION section, below.\r
+\r
+\r
+BUILDING\r
+========\r
+It is not necessary to build the libraries separately from the target\r
+application(s). If the application references the libraries, as described in\r
+USAGE, below; the required libraries will be built as needed.\r
+To build the applications included in AppPkg, one would execute the following\r
+commands within the "Visual Studio Command Prompt" window:\r
+\r
+    > cd C:\Source\Edk2\r
+    > .\edksetup.bat\r
+    > build ?a X64 ?p AppPkg\AppPkg.dsc\r
+\r
+This will produce the application executables: Enquire.efi, Hello.efi, and\r
+Main.efi in the C:\Source\Edk2\Build\AppPkg\DEBUG_VS2008\X64 directory; with\r
+the DEBUG_VS2008 component being replaced with the actual tool chain and build\r
+type you have selected in Conf\Tools_def.txt. These executables can now be\r
+loaded onto the target platform and executed.\r
+\r
+If you examine the AppPkg.dsc file, you will notice that the StdLib package is\r
+referenced in order to resolve the library classes comprising the Standard\r
+C Library.  This, plus referencing the StdLib package in your application's\r
+.inf file is all that is needed to link your application to the standard\r
+libraries.\r
+\r
+\r
+USAGE\r
+=====\r
+This implementation of the Standard C Library is comprised of 16 separate\r
+libraries in addition to the standard header files. Nine of the libraries are\r
+associated with use of one of the standard headers; thus, if the header is used\r
+in an application, it must be linked with the associated library.  Three\r
+libraries are used to provide the Console and File-system device abstractions.\r
+The libraries and associated header files are described in the following table.\r
+\r
+ Library\r
+  Class      Header File(s)    Notes\r
+----------  ----------------  -------------------------------------------------\r
+LibC        -- Use Always --  This library is always required.\r
+LibCtype    ctype.h, wctype.h Character classification and mapping\r
+LibLocale   locale.h          Localization types, macros, and functions\r
+LibMath     math.h            Mathematical functions, types, and macros\r
+LibStdio    stdio.h           Standard Input and Output functions, types, and\r
+                              macros\r
+LibStdLib   stdlib.h          General Utilities for numeric conversion, random\r
+                              num., etc.\r
+LibString   string.h          String copying, concatenation, comparison,\r
+                              & search\r
+LibSignal   signal.h          Functions and types for handling run-time\r
+                              conditions\r
+LibTime     time.h            Time and Date types, macros, and functions\r
+LibUefi     sys/EfiSysCall.h  Provides the UEFI system interface and\r
+                              "System Calls"\r
+LibWchar    wchar.h           Extended multibyte and wide character utilities\r
+LibNetUtil                    Network address and number manipulation utilities\r
+DevConsole                    Automatically provided  File I/O abstractions for\r
+                              the UEFI Console device.  No need to list this\r
+                              library class in your INF file(s).\r
+DevShell    Add if desired    File I/O abstractions using UEFI shell\r
+                              facilities.  Add this to the application's main\r
+                              INF file if file-system access needed.\r
+DevUtility  -- Do Not Use --  Utility functions used by the Device abstractions\r
+LibGdtoa    -- Do Not Use --  This library is used internally and should not\r
+                              need to be explicitly specified by an\r
+                              application.  It must be defined as one of the\r
+                              available library classes in the application's\r
+                              DSC file.\r
+\r
+                         Table 1:  Standard Libraries\r
+                         ============================\r
+\r
+\r
+These libraries must be fully described in the [LibraryClasses] section of the\r
+application package's DSC file. Then, each individual application needs to\r
+specify which libraries to link to by specifying the Library Class, from the\r
+above table, in the [LibraryClasses] section of the application's INF file. The\r
+AppPkg.dsc, StdLib.dsc, and Enquire.inf files provide good examples of this.\r
+More details are in the CONFIGURATION section, below.\r
+\r
+Within the source files of the application, use of the Standard headers and\r
+library functions follow standard C programming practices as formalized by\r
+ISO/IEC 9899:1990, with Addendum 1, (C 95) C language specification.\r
+\r
+\r
+CONFIGURATION\r
+=============\r
+DSC Files\r
+---------\r
+\r
+All EDK II packages which build applications that use the standard libraries\r
+must include some "boilerplate" text in the package's .dsc file.  To make it\r
+easier, and to reduce cut-and-paste errors, the "boilerplate" text has been\r
+consolidated into a single file, StdLib/StdLib.inc, which can be included in\r
+your .dsc file using the !include directive.  The provided AppPkg.dsc and\r
+StdLib.dsc files do this on their last line.\r
+\r
+Each affected section of the DSC file is described below.\r
+\r
+  [LibraryClasses]\r
+    #\r
+    # Common Libraries\r
+    #\r
+    BaseLib|MdePkg/Library/BaseLib/BaseLib.inf\r
+    BaseMemoryLib|MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf\r
+\r
+    TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf\r
+    # To run in an emulation environment, such as NT32, comment out\r
+    # the TimerLib description above and un-comment the line below.\r
+    # TimerLib| MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf\r
+\r
+    #\r
+    # C Standard Libraries\r
+    #\r
+    LibC|StdLib/LibC/LibC.inf\r
+    LibStdLib|StdLib/LibC/StdLib/StdLib.inf\r
+    LibString|StdLib/LibC/String/String.inf\r
+    LibWchar|StdLib/LibC/Wchar/Wchar.inf\r
+    LibCType|StdLib/LibC/Ctype/Ctype.inf\r
+    LibTime|StdLib/LibC/Time/Time.inf\r
+    LibStdio|StdLib/LibC/Stdio/Stdio.inf\r
+    LibGdtoa|StdLib/LibC/gdtoa/gdtoa.inf\r
+    LibLocale|StdLib/LibC/Locale/Locale.inf\r
+    LibUefi|StdLib/LibC/Uefi/Uefi.inf\r
+    LibMath|StdLib/LibC/Math/Math.inf\r
+    LibSignal|StdLib/LibC/Signal/Signal.inf\r
+    LibNetUtil|StdLib/LibC/LibGcc/LibGcc.inf\r
+\r
+  # Libraries for device abstractions within the Standard C Library.\r
+  # Applications should not directly access any functions defined\r
+  # in these libraries.\r
+    DevUtility|StdLib/LibC/Uefi/Devices/daUtility.inf\r
+    DevConsole|StdLib/LibC/Uefi/Devices/daConsole.inf\r
+    DevShell|StdLib/LibC/Uefi/Devices/daShell.inf\r
+\r
+                     Figure 1: Library Class Descriptions\r
+                     ====================================\r
+\r
+\r
+Descriptions of the Library Classes comprising the Standard Libraries must be\r
+included in your application package's DSC file, as shown in Figure 1: Library\r
+Class Descriptions, above.\r
+\r
+The directives in Figure 2: Package Component Descriptions will create\r
+instances of the BaseLib and BaseMemoryLib library classes that are built\r
+with Link-time-Code-Generation disabled.  This is necessary when using the\r
+Microsoft tool chains in order to allow the library's functions to be\r
+resolved during the second pass of the linker during Link-Time-Code-Generation\r
+of the application.\r
+\r
+  [Components]\r
+  # BaseLib and BaseMemoryLib need to be built with the /GL- switch\r
+  # when using the Microsoft tool chains.  This is required so that\r
+  # the library functions can be resolved during the second pass of\r
+  # the linker during link-time-code-generation.\r
+  #\r
+    MdePkg/Library/BaseLib/BaseLib.inf {\r
+      <BuildOptions>\r
+        MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-\r
+    }\r
+    MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf {\r
+      <BuildOptions>\r
+        MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-\r
+    }\r
+\r
+                    Figure 2: Package Component Descriptions\r
+                    ========================================\r
+\r
+\r
+The NULL TimerLib instance must be selected if you desire to run your\r
+application under an emulation environment -- unless there is a supported\r
+TimerLib for that environment.  For example, the InOsEmuPkg provides a\r
+DxeTimerLib which can be used for the TimerLib instance.\r
+\r
+The "boilerplate" text in StdLib.inc will automatically adjust which Timer\r
+Library is instantiated based upon whether the $(EMULATE) macro has been\r
+defined, or not.\r
+\r
+  ###\r
+  # Select the correct TimerLib instance depending upon whether running under\r
+  # an emulation environment, or not.\r
+  !ifndef $(EMULATE)\r
+    # Not running in an Emulation Environment\r
+  [LibraryClasses.IA32.UEFI_APPLICATION]\r
+    TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf\r
+\r
+  [LibraryClasses.X64.UEFI_APPLICATION]\r
+    TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf\r
+\r
+  [LibraryClasses.IPF.UEFI_APPLICATION]\r
+    PalLib|MdePkg/Library/UefiPalLib/UefiPalLib.inf\r
+    TimerLib|MdePkg/Library/SecPeiDxeTimerLibCpu/SecPeiDxeTimerLibCpu.inf\r
+\r
+  !else\r
+    # Use this instance if Running in an Emulation Environment.\r
+  [LibraryClasses.Common.UEFI_APPLICATION]\r
+    TimerLib|MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf\r
+  !endif\r
+\r
+                      Figure 3: Timer Library Selection\r
+                      =================================\r
+\r
+\r
+Each compiler assumes, by default, that it will be used with standard libraries\r
+and headers provided by the compiler vendor.  Many of these assumptions are\r
+incorrect for the UEFI environment.  By including a BuildOptions section, as\r
+shown in Figure 3: Package Build Options, these assumptions can be\r
+tailored for compatibility with UEFI and the EDK II Standard Libraries.\r
+\r
+  [BuildOptions]\r
+    INTEL:*_*_IA32_CC_FLAGS  = /Qfreestanding\r
+     MSFT:*_*_IA32_CC_FLAGS  = /X /Zc:wchar_t\r
+      GCC:*_*_IA32_CC_FLAGS  = /ffreestanding ?nostdinc ?nostdlib\r
+\r
+  # The Build Options, below, are only used when building the C library\r
+  # to be run under an emulation environment.  The clock() system call\r
+  # is modified to return -1 indicating that it is unsupported.\r
+  # Just un-comment the lines below and select the correct\r
+  # TimerLib instance, above.\r
+\r
+    # INTEL:*_*_IA32_CC_FLAGS  = /D NT32dvm\r
+    #  MSFT:*_*_IA32_CC_FLAGS  = /D NT32dvm\r
+    #   GCC:*_*_IA32_CC_FLAGS  = -DNT32dvm\r
+\r
+                        Figure 4: Package Build Options\r
+                        ===============================\r
+\r
+The "boilerplate" text can be included using a !include directive in the\r
+package's .dsc file.  The provided AppPkg.dsc and StdLib.dsc files include\r
+the "boilerplate" text as follows:\r
+\r
+  # Include Boilerplate text required for building with the Standard Libraries.\r
+  #\r
+  #############################################################################\r
+  !include StdLib/StdLib.inc\r
+\r
+                      Figure 5: "Boilerplate" Inclusion\r
+                      =================================\r
+\r
+\r
+INF Files\r
+=========\r
+The INF files for most modules will not require special directives in order to\r
+support the Standard Libraries.  The two cases which could occur are described\r
+below.\r
+\r
+  [LibraryClasses]\r
+    UefiLib\r
+    LibC\r
+    LibString\r
+    LibStdio\r
+    DevShell\r
+  \r
+                      Figure 6: Module Library Classes\r
+                      ================================\r
+\r
+\r
+Modules of type UEFI_APPLICATION that perform file I/O should include library\r
+class DevShell.  Including this library class will allow file operations to be\r
+handled by the UEFI Shell.  Without this class, only Console I/O is permitted.\r
+\r
+ [BuildOptions]\r
+  INTEL:*_*_*_CC_FLAGS          = /Qdiag-disable:181,186\r
+   MSFT:*_*_*_CC_FLAGS          = /Oi- /wd4018 /wd4131\r
+    GCC:*_*_IPF_SYMRENAME_FLAGS = --redefine-syms=Rename.txt\r
+    \r
+                        Figure 7: Module Build Options\r
+                        ==============================\r
+\r
+\r
+An application's INF file may need to include a [BuildOptions] section\r
+specifying additional compiler and linker flags necessary to allow the\r
+application to be built. Usually, this section is not needed.  When building\r
+code from external sources, though, it may be necessary to disable some\r
+warnings or enable/disable some compiler features.\r
+\r
+\r
+IMPLEMENTATION-Specific Features\r
+================================\r
+It is very strongly recommended that applications not use the long or\r
+unsigned long types. The size of this type varies between compilers and is one\r
+of the less portable aspects of C. Instead, one should use the UEFI defined\r
+types whenever possible. Use of these types, listed below for reference,\r
+ensures that the declared objects have unambiguous, explicitly declared, sizes\r
+and characteristics.\r
+\r
+        UINT64   INT64     UINT32   INT32   UINT16   CHAR16\r
+        INT16    BOOLEAN   UINT8    CHAR8   INT8\r
+        UINTN    INTN                       PHYSICALADDRESS\r
+\r
+There are similar types declared in sys/types.h and related files.\r
+\r
+The types UINTN and INTN have the native width of the target processor\r
+architecture. Thus, INTN on IA32 has a width of 32 bits while INTN on X64 and\r
+IPF has a width of 64 bits.\r
+\r
+For maximum portability, data objects intended to hold addresses should be\r
+declared with type intptr_t or uintptr_t. These types, declared in\r
+sys/stdint.h, can be used to create objects capable of holding pointers. Note\r
+that these types will generate different sized objects on different processor\r
+architectures.  If a constant size across all processors and compilers is\r
+needed, use type PHYSICAL_ADDRESS.\r
+\r
+Though not specifically required by the ISO/IEC 9899 standard, this\r
+implementation of the Standard C Library provides the following system calls\r
+which are declared in sys/EfiSysCall.h.\r
+\r
+          close   dup      dup2     fcntl\r
+          fstat   getcwd   ioctl    isatty\r
+          lseek   lstat    mkdir    open\r
+          poll    read     rename   rmdir\r
+          stat    unlink   write\r
+\r
+The open function will accept file names of "stdin:", "stdout:", and "stderr:"\r
+which cause the respective streams specified in the UEFI System Table to be\r
+opened.  Normally, these are associated with the console device.  When the\r
+application is first started, these streams are automatically opened on File\r
+Descriptors 0, 1, and 2 respectively.\r
+\r
+\r
index 454f310..717e2d8 100644 (file)
   StdLib/PosixLib/Glob/LibGlob.inf\r
   StdLib/PosixLib/Stringlist/LibStringlist.inf\r
 \r
-#    Socket Applications - LibC based\r
+#    Socket Libraries - LibC based\r
   StdLib/BsdSocketLib/BsdSocketLib.inf\r
   StdLib/EfiSocketLib/EfiSocketLib.inf\r
   StdLib/UseSocketDxe/UseSocketDxe.inf\r
 \r
-###################################################################################################\r
+##############################################################################\r
 #\r
-#       Include Boilerplate text required for building with the Standard Libraries.\r
+#  Include Boilerplate text required for building with the Standard Libraries.\r
 #\r
-###################################################################################################\r
+##############################################################################\r
 !include StdLib/StdLib.inc\r
index e6d1b45..3f16fb9 100644 (file)
@@ -63,8 +63,7 @@
   TimerLib|MdePkg/Library/SecPeiDxeTimerLibCpu/SecPeiDxeTimerLibCpu.inf\r
 \r
 !else\r
-  # Running in an Emulation Environment.\r
-  # Adds this to the end of the current [LibraryClasses.Common.UEFI_APPLICATION] section.\r
+  # Use this instance if Running in an Emulation Environment.\r
 [LibraryClasses.Common.UEFI_APPLICATION]\r
   TimerLib|MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf\r
 !endif\r
diff --git a/StdLibPrivateInternalFiles/ReadMe.pdf b/StdLibPrivateInternalFiles/ReadMe.pdf
deleted file mode 100644 (file)
index 9dc6c0a..0000000
Binary files a/StdLibPrivateInternalFiles/ReadMe.pdf and /dev/null differ
diff --git a/StdLibPrivateInternalFiles/ReadMe.txt b/StdLibPrivateInternalFiles/ReadMe.txt
new file mode 100644 (file)
index 0000000..731b18d
--- /dev/null
@@ -0,0 +1,443 @@
+                           EDK II Standard Libraries\r
+                                    ReadMe\r
+                                 Beta Release\r
+                               4:03 PM 8/2/2011\r
+\r
+\r
+OVERVIEW\r
+========\r
+This document describes the EDK II specific aspects of installing, building, and\r
+using the Standard C Library component of the EDK II Application Development\r
+Kit, EADK.\r
+\r
+The EADK is comprised of three packages: AppPkg, StdLib, and StdLibPrivateInternalFiles.\r
+\r
+  AppPkg   This package contains applications which demonstrate use of the\r
+           Standard C Library.\r
+           These applications reside in AppPkg/Applications.\r
+\r
+      Enquire  This is a program that determines many properties of the\r
+               C compiler and the target machine that Enquire is run on.  The\r
+               only changes required to port this 1990s era Unix program to\r
+               EDK II were the addition of eight pragmas to enquire.c in\r
+               order to disable some Microsoft VC++ specific warnings.\r
+\r
+      Hello    This is a very simple EDK II native application that doesn't use\r
+               any features of the Standard C Library.\r
+\r
+      Main     This application is functionally identical to Hello, except that\r
+               it uses the Standard C Library to provide a main() entry point.\r
+\r
+      Python   A port of the Python-2.7.1 interpreter for UEFI.  This\r
+               application is disabled by default.  Un-comment the line for\r
+               PythonCore.inf in the [Components] section of AppPkg.dsc to\r
+               enable building Python.\r
+\r
+      Sockets  A collection of applications demonstrating use of the\r
+               EDK II Socket Libraries.  These applications include:\r
+\r
+               *   DataSink\r
+               *   DataSource\r
+               *   GetHostByAddr\r
+               *   GetHostByDns\r
+               *   GetHostByName\r
+               *   GetNetByAddr\r
+               *   GetNetByName\r
+               *   GetServByName\r
+               *   GetServByPort\r
+               *   RecvDgram\r
+               *   SetHostName\r
+               *   SetSockOpt\r
+               *   TftpServer\r
+               *   WebServer\r
+\r
+  StdLib   The StdLib package contains the standard header files as well as\r
+           implementations of the standard libraries.\r
+\r
+  StdLibPrivateInternalFiles  The contents of this package are for the\r
+           exclusive use of the library implementations in StdLib.  Please do\r
+           not use anything from this package in your application or else\r
+           unexpected behavior may occur.\r
+           This package may be removed in a future release.\r
+\r
+\r
+RELEASE NOTES\r
+=============\r
+This release of the EADK has some restrictions, as described below.\r
+\r
+    1. Only the Microsoft VS2005 and VS2008, Intel C Compiler 10.1 (or later),\r
+        GCC 4.3 (mingw32), GCC 4.4, and GCC 4.5 C compilers are supported for\r
+        Ia32 or X64 CPU architectures.\r
+        \r
+    2. The target machine must be running firmware which provides the\r
+        UEFI 2.3 HII protocol.\r
+        \r
+    3. The EADK has not been through Intel's Quality Assurance process. This\r
+        means that specified standards compliance has not been validated, nor\r
+        has it undergone formal functionality testing.\r
+        \r
+    4. Applications must be launched from within the EFI Shell.\r
+    \r
+    5. All file paths must use the forward slash, '/', as the separator\r
+        character.\r
+        \r
+    6. Absolute file paths may optionally be prefixed by a volume specifier\r
+        such as "FS0:".  The volume specifier is separated from the remainder\r
+        of the path by a single colon ':'.  The volume specifier must be one of\r
+        the Shell's mapped volume names as shown by the "map" command.\r
+        \r
+    7. Absolute file paths that don't begin with a volume specifier;\r
+        e.g. paths that begin with "/", are relative to the currently selected\r
+        volume.  When the EFI Shell starts, there is NO selected volume.\r
+        \r
+    8. The tmpfile(), and related, functions require that the current volume\r
+        have a temporary directory as specified in <paths.h>.  This directory\r
+        is specified by macro _PATH_TMP.\r
+\r
+The Standard C Library provided by this package is a "hosted" implementation\r
+conforming to the ISO/IEC 9899-1990 C Language Standard with Addendum 1. This\r
+is commonly referred to as the "C 95" specification or ISO/IEC 9899:199409.\r
+The following instructions assume that you have an existing EDK II or UDK 2010\r
+source tree that has been configured to build with your tool chain.  For\r
+convenience, it is assumed that your EDK II source tree is located at\r
+C:\Source\Edk2.\r
+\r
+\r
+INSTALLATION\r
+============\r
+The EADK is integrated within the EDK II source tree and is included with\r
+current EDK II check-outs.  If they are missing from your tree, they may be\r
+installed by extracting, downloading or copying them to the root of your EDK II\r
+source tree.  The three package directories should be peers to the Conf,\r
+MdePkg, Nt32Pkg, etc. directories.\r
+\r
+The Python 2.7.1 distribution must be downloaded from python.org before the\r
+Python application can be built.  Extracting Python-2.7.1.tgz into the\r
+AppPkg\Applications\Python directory will produce a Python-2.7.1 directory\r
+containing the Python distribution.  Python files that had to be modified for\r
+EDK II are in the AppPkg\Applications\Python\PyMod-2.7.1 directory.  These\r
+files need to be copied into the corresponding directories within Python-2.7.1.\r
+\r
+There are some boiler-plate declarations and definitions that need to be\r
+included in your application's INF and DSC build files.  These are described\r
+in the CONFIGURATION section, below.\r
+\r
+\r
+BUILDING\r
+========\r
+It is not necessary to build the libraries separately from the target\r
+application(s). If the application references the libraries, as described in\r
+USAGE, below; the required libraries will be built as needed.\r
+To build the applications included in AppPkg, one would execute the following\r
+commands within the "Visual Studio Command Prompt" window:\r
+\r
+    > cd C:\Source\Edk2\r
+    > .\edksetup.bat\r
+    > build ?a X64 ?p AppPkg\AppPkg.dsc\r
+\r
+This will produce the application executables: Enquire.efi, Hello.efi, and\r
+Main.efi in the C:\Source\Edk2\Build\AppPkg\DEBUG_VS2008\X64 directory; with\r
+the DEBUG_VS2008 component being replaced with the actual tool chain and build\r
+type you have selected in Conf\Tools_def.txt. These executables can now be\r
+loaded onto the target platform and executed.\r
+\r
+If you examine the AppPkg.dsc file, you will notice that the StdLib package is\r
+referenced in order to resolve the library classes comprising the Standard\r
+C Library.  This, plus referencing the StdLib package in your application's\r
+.inf file is all that is needed to link your application to the standard\r
+libraries.\r
+\r
+\r
+USAGE\r
+=====\r
+This implementation of the Standard C Library is comprised of 16 separate\r
+libraries in addition to the standard header files. Nine of the libraries are\r
+associated with use of one of the standard headers; thus, if the header is used\r
+in an application, it must be linked with the associated library.  Three\r
+libraries are used to provide the Console and File-system device abstractions.\r
+The libraries and associated header files are described in the following table.\r
+\r
+ Library\r
+  Class      Header File(s)    Notes\r
+----------  ----------------  -------------------------------------------------\r
+LibC        -- Use Always --  This library is always required.\r
+LibCtype    ctype.h, wctype.h Character classification and mapping\r
+LibLocale   locale.h          Localization types, macros, and functions\r
+LibMath     math.h            Mathematical functions, types, and macros\r
+LibStdio    stdio.h           Standard Input and Output functions, types, and\r
+                              macros\r
+LibStdLib   stdlib.h          General Utilities for numeric conversion, random\r
+                              num., etc.\r
+LibString   string.h          String copying, concatenation, comparison,\r
+                              & search\r
+LibSignal   signal.h          Functions and types for handling run-time\r
+                              conditions\r
+LibTime     time.h            Time and Date types, macros, and functions\r
+LibUefi     sys/EfiSysCall.h  Provides the UEFI system interface and\r
+                              "System Calls"\r
+LibWchar    wchar.h           Extended multibyte and wide character utilities\r
+LibNetUtil                    Network address and number manipulation utilities\r
+DevConsole                    Automatically provided  File I/O abstractions for\r
+                              the UEFI Console device.  No need to list this\r
+                              library class in your INF file(s).\r
+DevShell    Add if desired    File I/O abstractions using UEFI shell\r
+                              facilities.  Add this to the application's main\r
+                              INF file if file-system access needed.\r
+DevUtility  -- Do Not Use --  Utility functions used by the Device abstractions\r
+LibGdtoa    -- Do Not Use --  This library is used internally and should not\r
+                              need to be explicitly specified by an\r
+                              application.  It must be defined as one of the\r
+                              available library classes in the application's\r
+                              DSC file.\r
+\r
+                         Table 1:  Standard Libraries\r
+                         ============================\r
+\r
+\r
+These libraries must be fully described in the [LibraryClasses] section of the\r
+application package's DSC file. Then, each individual application needs to\r
+specify which libraries to link to by specifying the Library Class, from the\r
+above table, in the [LibraryClasses] section of the application's INF file. The\r
+AppPkg.dsc, StdLib.dsc, and Enquire.inf files provide good examples of this.\r
+More details are in the CONFIGURATION section, below.\r
+\r
+Within the source files of the application, use of the Standard headers and\r
+library functions follow standard C programming practices as formalized by\r
+ISO/IEC 9899:1990, with Addendum 1, (C 95) C language specification.\r
+\r
+\r
+CONFIGURATION\r
+=============\r
+DSC Files\r
+---------\r
+\r
+All EDK II packages which build applications that use the standard libraries\r
+must include some "boilerplate" text in the package's .dsc file.  To make it\r
+easier, and to reduce cut-and-paste errors, the "boilerplate" text has been\r
+consolidated into a single file, StdLib/StdLib.inc, which can be included in\r
+your .dsc file using the !include directive.  The provided AppPkg.dsc and\r
+StdLib.dsc files do this on their last line.\r
+\r
+Each affected section of the DSC file is described below.\r
+\r
+  [LibraryClasses]\r
+    #\r
+    # Common Libraries\r
+    #\r
+    BaseLib|MdePkg/Library/BaseLib/BaseLib.inf\r
+    BaseMemoryLib|MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf\r
+\r
+    TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf\r
+    # To run in an emulation environment, such as NT32, comment out\r
+    # the TimerLib description above and un-comment the line below.\r
+    # TimerLib| MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf\r
+\r
+    #\r
+    # C Standard Libraries\r
+    #\r
+    LibC|StdLib/LibC/LibC.inf\r
+    LibStdLib|StdLib/LibC/StdLib/StdLib.inf\r
+    LibString|StdLib/LibC/String/String.inf\r
+    LibWchar|StdLib/LibC/Wchar/Wchar.inf\r
+    LibCType|StdLib/LibC/Ctype/Ctype.inf\r
+    LibTime|StdLib/LibC/Time/Time.inf\r
+    LibStdio|StdLib/LibC/Stdio/Stdio.inf\r
+    LibGdtoa|StdLib/LibC/gdtoa/gdtoa.inf\r
+    LibLocale|StdLib/LibC/Locale/Locale.inf\r
+    LibUefi|StdLib/LibC/Uefi/Uefi.inf\r
+    LibMath|StdLib/LibC/Math/Math.inf\r
+    LibSignal|StdLib/LibC/Signal/Signal.inf\r
+    LibNetUtil|StdLib/LibC/LibGcc/LibGcc.inf\r
+\r
+  # Libraries for device abstractions within the Standard C Library.\r
+  # Applications should not directly access any functions defined\r
+  # in these libraries.\r
+    DevUtility|StdLib/LibC/Uefi/Devices/daUtility.inf\r
+    DevConsole|StdLib/LibC/Uefi/Devices/daConsole.inf\r
+    DevShell|StdLib/LibC/Uefi/Devices/daShell.inf\r
+\r
+                     Figure 1: Library Class Descriptions\r
+                     ====================================\r
+\r
+\r
+Descriptions of the Library Classes comprising the Standard Libraries must be\r
+included in your application package's DSC file, as shown in Figure 1: Library\r
+Class Descriptions, above.\r
+\r
+The directives in Figure 2: Package Component Descriptions will create\r
+instances of the BaseLib and BaseMemoryLib library classes that are built\r
+with Link-time-Code-Generation disabled.  This is necessary when using the\r
+Microsoft tool chains in order to allow the library's functions to be\r
+resolved during the second pass of the linker during Link-Time-Code-Generation\r
+of the application.\r
+\r
+  [Components]\r
+  # BaseLib and BaseMemoryLib need to be built with the /GL- switch\r
+  # when using the Microsoft tool chains.  This is required so that\r
+  # the library functions can be resolved during the second pass of\r
+  # the linker during link-time-code-generation.\r
+  #\r
+    MdePkg/Library/BaseLib/BaseLib.inf {\r
+      <BuildOptions>\r
+        MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-\r
+    }\r
+    MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf {\r
+      <BuildOptions>\r
+        MSFT:*_*_*_CC_FLAGS = /X /Zc:wchar_t /GL-\r
+    }\r
+\r
+                    Figure 2: Package Component Descriptions\r
+                    ========================================\r
+\r
+\r
+The NULL TimerLib instance must be selected if you desire to run your\r
+application under an emulation environment -- unless there is a supported\r
+TimerLib for that environment.  For example, the InOsEmuPkg provides a\r
+DxeTimerLib which can be used for the TimerLib instance.\r
+\r
+The "boilerplate" text in StdLib.inc will automatically adjust which Timer\r
+Library is instantiated based upon whether the $(EMULATE) macro has been\r
+defined, or not.\r
+\r
+  ###\r
+  # Select the correct TimerLib instance depending upon whether running under\r
+  # an emulation environment, or not.\r
+  !ifndef $(EMULATE)\r
+    # Not running in an Emulation Environment\r
+  [LibraryClasses.IA32.UEFI_APPLICATION]\r
+    TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf\r
+\r
+  [LibraryClasses.X64.UEFI_APPLICATION]\r
+    TimerLib|PerformancePkg/Library/DxeTscTimerLib/DxeTscTimerLib.inf\r
+\r
+  [LibraryClasses.IPF.UEFI_APPLICATION]\r
+    PalLib|MdePkg/Library/UefiPalLib/UefiPalLib.inf\r
+    TimerLib|MdePkg/Library/SecPeiDxeTimerLibCpu/SecPeiDxeTimerLibCpu.inf\r
+\r
+  !else\r
+    # Use this instance if Running in an Emulation Environment.\r
+  [LibraryClasses.Common.UEFI_APPLICATION]\r
+    TimerLib|MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf\r
+  !endif\r
+\r
+                      Figure 3: Timer Library Selection\r
+                      =================================\r
+\r
+\r
+Each compiler assumes, by default, that it will be used with standard libraries\r
+and headers provided by the compiler vendor.  Many of these assumptions are\r
+incorrect for the UEFI environment.  By including a BuildOptions section, as\r
+shown in Figure 3: Package Build Options, these assumptions can be\r
+tailored for compatibility with UEFI and the EDK II Standard Libraries.\r
+\r
+  [BuildOptions]\r
+    INTEL:*_*_IA32_CC_FLAGS  = /Qfreestanding\r
+     MSFT:*_*_IA32_CC_FLAGS  = /X /Zc:wchar_t\r
+      GCC:*_*_IA32_CC_FLAGS  = /ffreestanding ?nostdinc ?nostdlib\r
+\r
+  # The Build Options, below, are only used when building the C library\r
+  # to be run under an emulation environment.  The clock() system call\r
+  # is modified to return -1 indicating that it is unsupported.\r
+  # Just un-comment the lines below and select the correct\r
+  # TimerLib instance, above.\r
+\r
+    # INTEL:*_*_IA32_CC_FLAGS  = /D NT32dvm\r
+    #  MSFT:*_*_IA32_CC_FLAGS  = /D NT32dvm\r
+    #   GCC:*_*_IA32_CC_FLAGS  = -DNT32dvm\r
+\r
+                        Figure 4: Package Build Options\r
+                        ===============================\r
+\r
+The "boilerplate" text can be included using a !include directive in the\r
+package's .dsc file.  The provided AppPkg.dsc and StdLib.dsc files include\r
+the "boilerplate" text as follows:\r
+\r
+  # Include Boilerplate text required for building with the Standard Libraries.\r
+  #\r
+  #############################################################################\r
+  !include StdLib/StdLib.inc\r
+\r
+                      Figure 5: "Boilerplate" Inclusion\r
+                      =================================\r
+\r
+\r
+INF Files\r
+=========\r
+The INF files for most modules will not require special directives in order to\r
+support the Standard Libraries.  The two cases which could occur are described\r
+below.\r
+\r
+  [LibraryClasses]\r
+    UefiLib\r
+    LibC\r
+    LibString\r
+    LibStdio\r
+    DevShell\r
+  \r
+                      Figure 6: Module Library Classes\r
+                      ================================\r
+\r
+\r
+Modules of type UEFI_APPLICATION that perform file I/O should include library\r
+class DevShell.  Including this library class will allow file operations to be\r
+handled by the UEFI Shell.  Without this class, only Console I/O is permitted.\r
+\r
+ [BuildOptions]\r
+  INTEL:*_*_*_CC_FLAGS          = /Qdiag-disable:181,186\r
+   MSFT:*_*_*_CC_FLAGS          = /Oi- /wd4018 /wd4131\r
+    GCC:*_*_IPF_SYMRENAME_FLAGS = --redefine-syms=Rename.txt\r
+    \r
+                        Figure 7: Module Build Options\r
+                        ==============================\r
+\r
+\r
+An application's INF file may need to include a [BuildOptions] section\r
+specifying additional compiler and linker flags necessary to allow the\r
+application to be built. Usually, this section is not needed.  When building\r
+code from external sources, though, it may be necessary to disable some\r
+warnings or enable/disable some compiler features.\r
+\r
+\r
+IMPLEMENTATION-Specific Features\r
+================================\r
+It is very strongly recommended that applications not use the long or\r
+unsigned long types. The size of this type varies between compilers and is one\r
+of the less portable aspects of C. Instead, one should use the UEFI defined\r
+types whenever possible. Use of these types, listed below for reference,\r
+ensures that the declared objects have unambiguous, explicitly declared, sizes\r
+and characteristics.\r
+\r
+        UINT64   INT64     UINT32   INT32   UINT16   CHAR16\r
+        INT16    BOOLEAN   UINT8    CHAR8   INT8\r
+        UINTN    INTN                       PHYSICALADDRESS\r
+\r
+There are similar types declared in sys/types.h and related files.\r
+\r
+The types UINTN and INTN have the native width of the target processor\r
+architecture. Thus, INTN on IA32 has a width of 32 bits while INTN on X64 and\r
+IPF has a width of 64 bits.\r
+\r
+For maximum portability, data objects intended to hold addresses should be\r
+declared with type intptr_t or uintptr_t. These types, declared in\r
+sys/stdint.h, can be used to create objects capable of holding pointers. Note\r
+that these types will generate different sized objects on different processor\r
+architectures.  If a constant size across all processors and compilers is\r
+needed, use type PHYSICAL_ADDRESS.\r
+\r
+Though not specifically required by the ISO/IEC 9899 standard, this\r
+implementation of the Standard C Library provides the following system calls\r
+which are declared in sys/EfiSysCall.h.\r
+\r
+          close   dup      dup2     fcntl\r
+          fstat   getcwd   ioctl    isatty\r
+          lseek   lstat    mkdir    open\r
+          poll    read     rename   rmdir\r
+          stat    unlink   write\r
+\r
+The open function will accept file names of "stdin:", "stdout:", and "stderr:"\r
+which cause the respective streams specified in the UEFI System Table to be\r
+opened.  Normally, these are associated with the console device.  When the\r
+application is first started, these streams are automatically opened on File\r
+Descriptors 0, 1, and 2 respectively.\r
+\r
+\r