add the extra comments into BasePeCoffRelocateImage, BasePeCoffLoadImage and BasePeCo...

[mirror_edk2.git] / MdePkg / Include / Library / PeimEntryPoint.h

diff --git a/MdePkg/Include/Library/PeimEntryPoint.h b/MdePkg/Include/Library/PeimEntryPoint.h
index 9980c91d0efa931ddfa1603f87763d8b67038df6..05be31fc41d7841fd70fbbe345398c277e5e16c0 100644 (file)
--- a/MdePkg/Include/Library/PeimEntryPoint.h
+++ b/MdePkg/Include/Library/PeimEntryPoint.h
@@ -22,14 +22,17 @@ extern CONST UINT32       _gPeimRevision;
 \r
 \r
 /**\r
-  Image entry point of Peim.\r
+  The entry point of PE/COFF Image for a PEIM.\r
+\r
+  This function is the entry point for a PEIM.  This function must call ProcessLibraryConstructorList() \r
+  and ProcessModuleEntryPointList().  The return value from ProcessModuleEntryPointList() is returned.\r
+  If _gPeimRevision is not zero and PeiServices->Hdr.Revision is less than _gPeimRevison, then ASSERT().\r
 \r
   @param  FileHandle  Handle of the file being invoked. \r
-                      Type EFI_PEI_FILE_HANDLE is defined in FfsFindNextFile().\r
   @param  PeiServices Describes the list of possible PEI Services.\r
 \r
-  @return  Status returned by entry points of Peims.\r
-\r
+  @retval  EFI_SUCCESS   The PEIM executed normally.\r
+  @retval  !EFI_SUCCESS  The PEIM failed to execute normally.\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
@@ -40,13 +43,15 @@ _ModuleEntryPoint (
 \r
 \r
 /**\r
-  Wrapper of Peim image entry point.\r
+  Required by the EBC compiler and identical in functionality to _ModuleEntryPoint().\r
+  \r
+  This function is required to call _ModuleEntryPoint() passing in FileHandle and PeiServices.\r
 \r
   @param  FileHandle  Handle of the file being invoked. \r
-                      Type EFI_PEI_FILE_HANDLE is defined in FfsFindNextFile().\r
   @param  PeiServices Describes the list of possible PEI Services.\r
 \r
-  @return  Status returned by entry points of Peims.\r
+  @retval EFI_SUCCESS  The PEIM executed normally.\r
+  @retval !EFI_SUCCESS The PEIM failed to execute normally.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -56,13 +61,20 @@ EfiMain (
   IN CONST EFI_PEI_SERVICES    **PeiServices\r
   );\r
 \r
-\r
 /**\r
-  Call constructs for all libraries. Automatics Generated by tool.\r
+  Autogenerated function that calls the library constructors for all of the module's\r
+  dependent libraries.\r
 \r
-  @param  FileHandle  Handle of the file being invoked. \r
-                      Type EFI_PEI_FILE_HANDLE is defined in FfsFindNextFile().\r
-  @param  PeiServices Describes the list of possible PEI Services.\r
+  This function must be called by _ModuleEntryPoint().\r
+  This function calls the set of library constructors for the set of library instances that a\r
+  module depends on. This includes library instances that a module depends on directly and library\r
+  instances that a module depends on indirectly through other libraries.  \r
+  This function is autogenerated by build tools and those build tools are responsible for collecting\r
+  the set of library instances, determine which ones have constructors, and calling the library\r
+  constructors in the proper order based upon each of the library instances own dependencies.\r
+\r
+  @param  FileHandle   Handle of the file being invoked.\r
+  @param  PeiServices  Describes the list of possible PEI Services.\r
 \r
 **/\r
 VOID\r
@@ -72,31 +84,19 @@ ProcessLibraryConstructorList (
   IN CONST EFI_PEI_SERVICES    **PeiServices\r
   );\r
 \r
-\r
 /**\r
-  Call destructors for all libraries. Automatics Generated by tool.\r
-\r
-  @param  FileHandle  Handle of the file being invoked. \r
-                      Type EFI_PEI_FILE_HANDLE is defined in FfsFindNextFile().\r
-  @param  PeiServices Describes the list of possible PEI Services.\r
+  Autogenerated function that calls a set of module entry points.\r
 \r
-**/\r
-VOID\r
-EFIAPI\r
-ProcessLibraryDestructorList (\r
-  IN EFI_PEI_FILE_HANDLE       FileHandle,\r
-  IN CONST EFI_PEI_SERVICES    **PeiServices\r
-  );\r
-\r
-\r
-/**\r
-  Call the list of driver entry points. Automatics Generated by tool.\r
+  This function must be called by _ModuleEntryPoint().\r
+  This function calls the set of module entry points.  \r
+  This function is autogenerated by build tools and those build tools are responsible\r
+  for collecting the module entry points and calling them in a specified order.\r
 \r
   @param  FileHandle  Handle of the file being invoked. \r
-                      Type EFI_PEI_FILE_HANDLE is defined in FfsFindNextFile().\r
   @param  PeiServices Describes the list of possible PEI Services.\r
 \r
-  @return Status returned by entry points of drivers.  \r
+  @retval EFI_SUCCESS  The PEIM executed normally.\r
+  @retval !EFI_SUCCESS The PEIM failed to execute normally.\r
  \r
 **/\r
 EFI_STATUS\r