Comments have been synchronized with spec.

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

diff --git a/MdePkg/Include/Library/UefiDriverEntryPoint.h b/MdePkg/Include/Library/UefiDriverEntryPoint.h
index a7c89514758a3ae99f56dd5b63c57e1bfe1395a6..6db6086af01bf74b273203cf14b274fd81a52ae3 100644 (file)
--- a/MdePkg/Include/Library/UefiDriverEntryPoint.h
+++ b/MdePkg/Include/Library/UefiDriverEntryPoint.h
@@ -30,11 +30,22 @@ extern CONST UINT8                    _gDriverUnloadImageCount;
 /**\r
   Enrty point to DXE Driver.\r
 \r
-  @param  ImageHandle ImageHandle of the loaded driver.\r
-  @param  SystemTable Pointer to the EFI System Table.\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
+  This function is the entry point for a DXE Driver, DXE Runtime Driver, DXE SMM Driver,\r
+  or UEFI Driver. This function must call ProcessLibraryConstructorList() and\r
+  ProcessModuleEntryPointList(). If the return status from ProcessModuleEntryPointList()\r
+  is an error status, then ProcessLibraryDestructorList() must be called. The return\r
+  value from ProcessModuleEntryPointList() is returned. If _gDriverUnloadImageCount is\r
+  greater than zero, then an unload handler must be registered for this image and the\r
+  unload handler must invoke ProcessModuleUnloadList(). If _gUefiDriverRevision is not\r
+  zero and SystemTable->Hdr.Revision is less than _gUefiDriverRevison, then return\r
+  EFI_INCOMPATIBLE_VERSION.\r
+\r
+  @param  ImageHandle  ImageHandle of the loaded driver.\r
+  @param  SystemTable  Pointer to the EFI System Table.\r
+\r
+  @retval  EFI_SUCCESS               One or more of the drivers returned a success code.\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
@@ -46,14 +57,17 @@ _ModuleEntryPoint (
 \r
 \r
 /**\r
-  Enrty point wrapper of DXE Driver.\r
+  Required by the EBC compiler and identical in functionality to _ModuleEntryPoint().\r
+\r
+  This function is required to call _ModuleEntryPoint() passing in ImageHandle, and SystemTable.\r
 \r
   @param  ImageHandle ImageHandle of the loaded driver.\r
   @param  SystemTable Pointer to the EFI System Table.\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
-\r
+  @retval  EFI_SUCCESS               The DXE Driver, DXE Runtime Driver, DXE SMM Driver,\r
+                                     or UEFI Driver exited normally.\r
+  @retval  EFI_INCOMPATIBLE_VERSION  _gUefiDriverRevision is greater than SystemTable->Hdr.Revision.\r
+  @retval  Other                     Return value from ProcessModuleEntryPointList().\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
@@ -64,8 +78,11 @@ EfiMain (
 \r
 \r
 /**\r
-  Computes the cummulative return status for the driver entry point and perform\r
-  a long jump back into DriverEntryPoint().\r
+  Invokes the library destructors fror all dependent libraries and terminates the\r
+  DXE Driver, DXE Runtime Driver, DXE SMM Driver, or UEFI Driver. \r
+\r
+  This function calls ProcessLibraryDestructorList() and the EFI Boot Service Exit()\r
+  with a status specified by Status.\r
 \r
   @param  Status Status returned by the driver that is exiting.\r
 \r
@@ -78,7 +95,17 @@ ExitDriver (
 \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
+  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\r
+  for collecting the set of library instances, determine which ones have constructors,\r
+  and calling the library constructors in the proper order based upon each of the library\r
+  instances own dependencies.\r
 \r
   @param  ImageHandle ImageHandle of the loaded driver.\r
   @param  SystemTable Pointer to the EFI System Table.\r
@@ -93,7 +120,15 @@ ProcessLibraryConstructorList (
 \r
 \r
 /**\r
-  Call destructors for all libraries. Automatics Generated by tool.\r
+  Autogenerated function that calls the library descructors for all of the module's dependent libraries.\r
+\r
+  This function may be called by _ModuleEntryPoint() or ExitDriver().\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 for\r
+  collecting the set of library instances, determine which ones have destructors, and calling\r
+  the library destructors in the proper order based upon each of the library instances own dependencies.\r
 \r
   @param  ImageHandle ImageHandle of the loaded driver.\r
   @param  SystemTable Pointer to the EFI System Table.\r
@@ -106,24 +141,20 @@ ProcessLibraryDestructorList (
   IN EFI_SYSTEM_TABLE  *SystemTable\r
   );\r
 \r
-/**\r
-  Call the list of driver entry points. Automatics Generated by tool.\r
-\r
-  @param  ImageHandle ImageHandle of the loaded driver.\r
-  @param  SystemTable Pointer to the EFI System Table.\r
-\r
-  @return Status returned by entry points of drivers.  \r
- \r
-**/\r
 \r
 /**\r
-  Call the list of driver entry points. Automatics Generated by tool.\r
+  Autogenerated function that calls a set of module entry points.\r
+\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  ImageHandle ImageHandle of the loaded driver.\r
   @param  SystemTable Pointer to the EFI System Table.\r
 \r
-  @return Status returned by entry points of drivers.  \r
- \r
+  @retval  EFI_SUCCESS   The UEFI Application executed normally.\r
+  @retval  !EFI_SUCCESS  The UEFI Application failed to execute normally.\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
@@ -134,11 +165,17 @@ ProcessModuleEntryPointList (
 \r
 \r
 /**\r
-  Call the unload handlers for all the modules. Automatics Generated by tool.\r
+  Autogenerated function that calls a set of module unload handlers.\r
+\r
+  This function must be called from the unload handler registered by _ModuleEntryPoint().\r
+  This function calls the set of module unload handlers.  \r
+  This function is autogenerated by build tools and those build tools are responsible\r
+  for collecting the module unload handlers and calling them in a specified order.\r
 \r
   @param  ImageHandle ImageHandle of the loaded driver.\r
- \r
-  @return Status returned by unload handlers of drivers.\r
+\r
+  @retval  EFI_SUCCESS  The unoad handlers executed normally.\r
+  @retval  !EFI_SUCCESS The unload handlers failed to execute normally.\r
 \r
 **/\r
 EFI_STATUS\r