Code have been checked with spec

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

diff --git a/MdePkg/Include/Library/UefiApplicationEntryPoint.h b/MdePkg/Include/Library/UefiApplicationEntryPoint.h
index b6c193b710d37abfae4be5503efa5af916ec9428..5fe4be2a8f6694009e5467cbe623019fdbb86be9 100644 (file)
--- a/MdePkg/Include/Library/UefiApplicationEntryPoint.h
+++ b/MdePkg/Include/Library/UefiApplicationEntryPoint.h
@@ -24,11 +24,18 @@ extern CONST UINT32        _gUefiDriverRevision;
 /**\r
   Enrty point to UEFI Application.\r
 \r
 /**\r
   Enrty point to UEFI Application.\r
 \r

-  @param  ImageHandle ImageHandle of the loaded driver.\r
-  @param  SystemTable Pointer to the EFI System Table.\r
+  This function is the entry point for a UEFI Application. This function must call\r
+  ProcessLibraryConstructorList(), ProcessModuleEntryPointList(), and ProcessLibraryDestructorList().\r
+  The return value from ProcessModuleEntryPointList() is returned.\r
+  If _gUefiDriverRevision is not zero and SystemTable->Hdr.Revision is less than _gUefiDriverRevison,\r
+  then return EFI_INCOMPATIBLE_VERSION.\r

 \r
 \r

-  @retval  EFI_SUCCESS One or more of the drivers returned a success code.\r
-  @retval  !EFI_SUCESS The return status from the last driver entry point in the list.\r
+  @param  ImageHandle  The image handle of the UEFI Application.\r
+  @param  SystemTable  A pointer to the EFI System Table.\r
+\r
+  @retval  EFI_SUCCESS               The UEFI Application exited normally.\r
+  @retval  EFI_INCOMPATIBLE_VERSION  _gUefiDriverRevision is greater than SystemTable->Hdr.Revision.\r
+  @retval  Other                     Return value from ProcessModuleEntryPointList().\r

 \r
 **/\r
 EFI_STATUS\r
 \r
 **/\r
 EFI_STATUS\r


@@ -40,13 +47,14 @@ _ModuleEntryPoint (
 \r
 \r
 /**\r
 \r
 \r
 /**\r

-  Enrty point wrapper of UEFI Application.\r
+  Required by the EBC compiler and identical in functionality to _ModuleEntryPoint(). \r

 \r
 \r

-  @param  ImageHandle ImageHandle of the loaded driver.\r
-  @param  SystemTable Pointer to the EFI System Table.\r
+  @param  ImageHandle  The image handle of the UEFI Application.\r
+  @param  SystemTable  A pointer to the EFI System Table.\r

 \r
 \r

-  @retval  EFI_SUCCESS One or more of the drivers returned a success code.\r
-  @retval  !EFI_SUCESS The return status from the last driver entry point in the list.\r
+  @retval  EFI_SUCCESS               The UEFI Application exited normally.\r
+  @retval  EFI_INCOMPATIBLE_VERSION  _gUefiDriverRevision is greater than SystemTable->Hdr.Revision.\r
+  @retval  Other                     Return value from ProcessModuleEntryPointList().\r

 \r
 **/\r
 EFI_STATUS\r
 \r
 **/\r
 EFI_STATUS\r


@@ -58,10 +66,13 @@ EfiMain (
 \r
 \r
 /**\r
 \r
 \r
 /**\r

-  Invoke the destuctors of all libraries and call gBS->Exit\r
-  to return control to firmware core.\r
+  Invokes the library destructors for all dependent libraries and terminates\r
+  the UEFI Application. \r
+\r
+  This function calls ProcessLibraryDestructorList() and the EFI Boot Service Exit()\r
+  with a status specified by Status.\r

 \r
 \r

-  @param  Status Status returned by the application that is exiting.\r
+  @param  Status  Status returned by the application that is exiting.\r

   \r
 **/\r
 VOID\r
   \r
 **/\r
 VOID\r


@@ -72,11 +83,20 @@ Exit (
 \r
 \r
 /**\r
 \r
 \r
 /**\r

-  Call constructors for all libraries.  Autogen tool inserts the implementation\r
-  of this function into Autogen.c.\r
-\r
-  @param  ImageHandle ImageHandle of the loaded driver.\r
-  @param  SystemTable Pointer to the EFI System Table.\r
+  Autogenerated function that calls the library constructors for all of the module's\r
+  dependent libraries.\r
+\r
+  This function must be called by _ModuleEntryPoint().\r
+  This function calls the set of library constructors for the set of library instances\r
+  that a module depends on. This includes library instances that a module depends on\r
+  directly and library 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\r
+  collecting the set of library instances, determine which ones have constructors, and\r
+  calling the library constructors in the proper order based upon each of the library\r
+  instances own dependencies.\r
+\r
+  @param  ImageHandle  The image handle of the UEFI Application.\r
+  @param  SystemTable  A pointer to the EFI System Table.\r

   \r
 **/\r
 VOID\r
   \r
 **/\r
 VOID\r


@@ -88,11 +108,20 @@ ProcessLibraryConstructorList (
 \r
 \r
 /**\r
 \r
 \r
 /**\r

-  Call destructors for all libraries. Autogen tool inserts the implementation\r
-  of this function into Autogen.c.\r
+  Autogenerated function that calls the library descructors for all of the module's\r
+  dependent libraries.\r

 \r
 \r

-  @param  ImageHandle ImageHandle of the loaded driver.\r
-  @param  SystemTable Pointer to the EFI System Table.\r
+  This function may be called by _ModuleEntryPoint()or Exit().\r
+  This function calls the set of library destructors for the set of library instances\r
+  that a module depends on.  This includes library instances that a module depends on\r
+  directly and library instances that a module depends on indirectly through other libraries.  \r
+  This function is autogenerated by build tools and those build tools are responsible\r
+  for collecting the set of library instances, determine which ones have destructors,\r
+  and calling the library destructors in the proper order based upon each of the library\r
+  instances own dependencies.\r
+\r
+  @param  ImageHandle  The image handle of the UEFI Application.\r
+  @param  SystemTable  A pointer to the EFI System Table.\r

 \r
 **/\r
 VOID\r
 \r
 **/\r
 VOID\r


@@ -103,16 +132,17 @@ ProcessLibraryDestructorList (
   );\r
 \r
 /**\r
   );\r
 \r
 /**\r

-  Call driver entry point. For UEFI application, user\r
-  can only specify one entry point. Tool will automatically insert\r
-  this to Autogen.c.\r
+  This function calls the set of module entry points. It must be called by _ModuleEntryPoint().\r
+\r
+  This function is autogenerated by build tools and those build tools are \r
+  responsible for collecting the module entry points and calling them in a specified order.\r
+\r
+  @param  ImageHandle    The image handle of the UEFI Application.\r
+  @param  SystemTable    A pointer to the EFI System Table.\r

 \r
 \r

-  @param  ImageHandle ImageHandle of the loaded driver.\r
-  @param  SystemTable Pointer to the EFI System Table.\r
+  @retval  EFI_SUCCESS   The UEFI Application executed normally.\r
+  @retval  !EFI_SUCCESS  The UEFI Application failed to execute normally.\r

 \r
 \r

-  @return Status returned by entry points specified by\r
-          the user.  \r
- \r

 **/\r
 EFI_STATUS\r
 EFIAPI\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r