EADK (StdLib, AppPkg, StdLibPrivateInternalFiles): Update ReadMe.txt in all packages.
[mirror_edk2.git] / AppPkg / ReadMe.txt
index 0039691..35e3b6a 100644 (file)
@@ -1,9 +1,8 @@
-                                    EADK\r
+                                     EADK\r
                   EDK II Standard Libraries and Applications\r
                                     ReadMe\r
-                                Beta-1 Release\r
-                                 27 Jan. 2012\r
-                                    DRAFT\r
+                                 Version 1.02\r
+                                 21 Dec. 2012\r
 \r
 \r
 OVERVIEW\r
@@ -17,8 +16,9 @@ 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\r
 primarily due to size and environmental requirements.\r
 \r
-Some components of the EADK can be built as drivers.  These will be identified\r
-explicitly in their documentation.\r
+This release of the EADK should only be used to produce UEFI Applications.  Due to the execution\r
+environment built by the StdLib component, execution as a UEFI driver can cause system stability\r
+issues.\r
 \r
 This document describes the EDK II specific aspects of installing, building,\r
 and using the Standard C Library component of the EDK II Application\r
@@ -28,7 +28,7 @@ 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
+           Standard C and Sockets Libraries.\r
            These applications reside in AppPkg/Applications.\r
 \r
       Enquire  This is a program that determines many properties of the\r
@@ -43,7 +43,7 @@ The EADK is comprised of three packages:
       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.2 interpreter for UEFI.  This\r
+      Python   A port of the Python-2.7.2 interpreter for UEFI.  Building this\r
                application is disabled by default.\r
                See the PythonReadMe.txt file, in the Python directory,\r
                for information on configuring and building Python.\r
@@ -51,28 +51,19 @@ The EADK is comprised of three packages:
       Sockets  A collection of applications demonstrating use of the\r
                EDK II Socket Libraries.  These applications include:\r
 \r
-               *   DataSink\r
-               *   DataSource\r
-               *   GetAddrInfo\r
-               *   GetHostByAddr\r
-               *   GetHostByDns\r
-               *   GetHostByName\r
-               *   GetNetByAddr\r
-               *   GetNetByName\r
-               *   GetServByName\r
-               *   GetServByPort\r
-               *   OobRx\r
-               *   OobTx\r
-               *   RawIp4Rx\r
-               *   RawIp4Tx\r
-               *   RecvDgram\r
-               *   SetHostName\r
-               *   SetSockOpt\r
-               *   TftpServer\r
+               *   DataSink                     *   DataSource\r
+               *   GetAddrInfo                  *   GetHostByAddr\r
+               *   GetHostByDns                 *   GetHostByName\r
+               *   GetNetByAddr                 *   GetNetByName\r
+               *   GetServByName                *   GetServByPort\r
+               *   OobRx                        *   OobTx\r
+               *   RawIp4Rx                     *   RawIp4Tx\r
+               *   RecvDgram                    *   SetHostName\r
+               *   SetSockOpt                   *   TftpServer\r
                *   WebServer\r
 \r
   StdLib   The StdLib package contains the standard header files as well as\r
-           implementations of standards based libraries.\r
+           implementations of other standards-based libraries.\r
 \r
            *   BsdSocketLib\r
                   Support routines above the sockets layer and C interface for\r
@@ -109,44 +100,31 @@ RELEASE NOTES
 =============\r
   Fixes and Additions\r
   -------------------\r
-Beginning with this release, applications built with the StdLib package\r
+Beginning with release 1.01, applications built with the StdLib package\r
 no longer have a dependency on the TimerLib.\r
 \r
   Known Issues\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.  Others may work but have not been tested.\r
-\r
-    2.  The target machine must be running firmware which provides the\r
+    1.  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
+    2.  Applications must be launched from within the EFI Shell.\r
 \r
-    6.  Absolute file paths may optionally be prefixed by a volume specifier\r
+    3.  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
+    4.  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 first starts, there is NO selected volume.\r
 \r
-    8.  The tmpfile(), and related, functions require that the current volume\r
+    5.  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 as /Efi/StdLib/tmp.\r
 \r
-    9.  Input line editing is not supported.  Backspacing, deleting, or\r
-        otherwise attempting to modify interactive input will result in a\r
-        syntax error since the editing characters are interpreted the\r
-        same as any other character.\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
@@ -164,21 +142,19 @@ 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,\r
 MdePkg, Nt32Pkg, etc. directories.\r
 \r
-The Python 2.7.2 distribution must be downloaded from python.org before the\r
-Python application can be built.  Extracting Python-2.7.2.tgz into the\r
-AppPkg\Applications\Python directory will produce a Python-2.7.2 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.2 directory.  These\r
-files need to be copied into the corresponding directories within Python-2.7.2.\r
-\r
-The Python 2.7.1 port was superseded before it was completed.  The PyMod-2.7.1\r
-directory tree will be deleted in the near future.  Use the Python 2.7.2 port,\r
-as described above.\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
+A subset of the Python 2.7.2 distribution is included as part of AppPkg.  If desired,\r
+the full Python 2.7.2 distribution may be downloaded from python.org and used instead.\r
+Delete or rename the existing Python-2.7.2 directory then extract the downloaded\r
+Python-2.7.2.tgz file into the AppPkg\Applications\Python directory.  This will produce a\r
+Python-2.7.2 directory containing the full Python distribution.  Python files that had to be\r
+modified for EDK II are in the AppPkg\Applications\Python\PyMod-2.7.2 directory.  These\r
+files need to be copied into the corresponding directories within the extracted Python-2.7.2\r
+directory before Python can be built.\r
+\r
 \r
 BUILDING\r
 ========\r
@@ -240,13 +216,13 @@ LibUefi     sys/EfiSysCall.h  Provides the UEFI system interface and
                               "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
+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
+DevUtility  -- Do Not Use --  Utility functions used internally 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
@@ -256,6 +232,10 @@ LibGdtoa    -- Do Not Use --  This library is used internally and should not
                          Table 1:  Standard Libraries\r
                          ============================\r
 \r
+The DevConsole and DevShell libraries provide device I/O functionality and are treated\r
+specially.  DevConsole is automatically included so there is no need to reference it in your\r
+application's DSC or INF files.  DevShell must be listed, in your application's INF file in the\r
+[LibraryClasses] section, if your application does file I/O.\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
@@ -264,6 +244,11 @@ above table, in the [LibraryClasses] section of the application's INF file. The
 AppPkg.dsc, StdLib.dsc, and Enquire.inf files provide good examples of this.\r
 More details are in the CONFIGURATION section, below.\r
 \r
+In order to simplify this process, the [LibraryClasses] definitions, and others, are\r
+specified in the StdLib.inc file.  If this file is included in the DSC file, usually at the\r
+end, then other DSC file changes or additions are unnecessary.  This is further described in\r
+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
@@ -281,8 +266,44 @@ 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\r
 StdLib.dsc files do this on their last line.\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 following "boilerplate" text:\r
+\r
+  ##############################################################################\r
+  #\r
+  # Specify whether we are running in an emulation environment, or not.\r
+  # Define EMULATE if we are, else keep the DEFINE commented out.\r
+  #\r
+  # DEFINE  EMULATE = 1\r
+\r
+  ##############################################################################\r
+  #\r
+  #  Include Boilerplate text required for building with the Standard Libraries.\r
+  #\r
+  ##############################################################################\r
+  !include StdLib/StdLib.inc\r
+\r
+                      Figure 1: "Boilerplate" Inclusion\r
+                      =================================\r
+\r
+The EMULATE macro must be defined if one desires to do source-level debugging within one of\r
+the emulated environments such as NT32Pkg or UnixPkg.\r
+\r
+The final boilerplate line, in Figure 1, includes the StdLib.inc file.\r
 Each section of StdLib/StdLib.inc is described below.\r
 \r
+If desired, all of the Socket applications, in AppPkg, can be built by including Sockets.inc:\r
+\r
+  !include AppPkg/Applications/Sockets/Sockets.inc\r
+\r
+              Figure 2: Socket Applications "Boilerplate" Inclusion\r
+              =====================================================\r
+\r
+\r
+Descriptions of the Library Classes comprising the Standard Libraries,\r
+as shown in Figure 3: Library Class Descriptions, are provided.\r
+\r
   [LibraryClasses]\r
     #\r
     # C Standard Libraries\r
@@ -318,14 +339,11 @@ Each section of StdLib/StdLib.inc is described below.
   [LibraryClasses.ARM.UEFI_APPLICATION]\r
     NULL|ArmPkg/Library/CompilerIntrinsicsLib/CompilerIntrinsicsLib.inf\r
 \r
-                     Figure 1: Library Class Descriptions\r
+                     Figure 3: Library Class Descriptions\r
                      ====================================\r
 \r
 \r
-Descriptions of the Library Classes comprising the Standard Libraries,\r
-as shown above in Figure 1: Library Class Descriptions, are provided.\r
-\r
-The directives in Figure 2: Package Component Descriptions will create\r
+The directives in Figure 4: 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
@@ -354,50 +372,43 @@ A DXE driver version of the Socket library is also built.
   ##########\r
     StdLib/SocketDxe/SocketDxe.inf\r
 \r
-                    Figure 2: Package Component Descriptions\r
+                    Figure 4: Package Component Descriptions\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
+shown in Figure 5: Package Build Options, these assumptions can be\r
 tailored for compatibility with UEFI and the EDK II Standard Libraries.\r
 \r
+Note that the set of BuildOptions used is determined by the state of the EMULATE macro.\r
+\r
   [BuildOptions]\r
+  !ifndef $(EMULATE)\r
+    # These Build Options are used when building the Standard Libraries to be run\r
+    # on real hardware.\r
     INTEL:*_*_IA32_CC_FLAGS  = /Qfreestanding\r
      MSFT:*_*_IA32_CC_FLAGS  = /X /Zc:wchar_t\r
       GCC:*_*_IA32_CC_FLAGS  = -nostdinc -nostdlib\r
 \r
-  # The Build Options, below, are only used when building the C library\r
-  # to be run under an emulation environment.  They disable optimization\r
-  # which facillitates debugging under the Emulation environment.\r
+  !else\r
+    # The Build Options, below, are only used when building the Standard Libraries\r
+    # to be run under an emulation environment.\r
+    # They disable optimization which facillitates debugging under the Emulation environment.\r
+    INTEL:*_*_IA32_CC_FLAGS  = /Od\r
+     MSFT:*_*_IA32_CC_FLAGS  = /Od\r
+      GCC:*_*_IA32_CC_FLAGS  = -O0\r
 \r
-    # INTEL:*_*_IA32_CC_FLAGS  = /Od\r
-    #  MSFT:*_*_IA32_CC_FLAGS  = /Od\r
-    #   GCC:*_*_IA32_CC_FLAGS  = -O0\r
-\r
-                        Figure 4: Package Build Options\r
+                        Figure 5: 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
+support the Standard Libraries.  The two sections which require attention: LibraryClasses\r
+and BuildOptions, are described below.\r
 \r
   [LibraryClasses]\r
     UefiLib\r
@@ -410,9 +421,16 @@ below.
                       ================================\r
 \r
 \r
-Modules of type UEFI_APPLICATION that perform file I/O should include library\r
+Modules of type UEFI_APPLICATION that perform file I/O must 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
+handled by the UEFI Shell.  Without this class, only Console I/O is supported.\r
+\r
+\r
+An application's INF file might 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
  [BuildOptions]\r
   INTEL:*_*_*_CC_FLAGS          = /Qdiag-disable:181,186\r
@@ -423,13 +441,6 @@ handled by the UEFI Shell.  Without this class, only Console I/O is permitted.
                         ==============================\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
 TARGET-SYSTEM INSTALLATION\r
 ==========================\r
 Applications that use file system features or the Socket library depend upon\r
@@ -444,13 +455,13 @@ the application was loaded from.  This tree structure is described below:
          |- /tmp              Temporary files created by tmpfile(), etc.\r
 \r
 \r
-The /Efi/StdLib/etc directory is populated from the StdLib/Efi/etc source\r
+The /Efi/StdLib/etc directory must be manually populated from the StdLib/Efi/etc source\r
 directory.\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
+unsigned long types. The size of these types 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