Comments have been synchronized with spec.

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

1 files changed, 65 insertions, 28 deletions

diff --git a/MdePkg/Include/Library/UefiDriverEntryPoint.h b/MdePkg/Include/Library/UefiDriverEntryPoint.h
index a7c8951475..6db6086af0 100644
--- a/MdePkg/Include/Library/UefiDriverEntryPoint.h
+++ b/MdePkg/Include/Library/UefiDriverEntryPoint.h
@@ -30,11 +30,22 @@ extern CONST UINT8                    _gDriverUnloadImageCount;
 /**

   Enrty point to DXE Driver.

 

-  @param  ImageHandle ImageHandle of the loaded driver.

-  @param  SystemTable Pointer to the EFI System Table.

-

-  @retval  EFI_SUCCESS One or more of the drivers returned a success code.

-  @retval  !EFI_SUCESS The return status from the last driver entry point in the list.

+  This function is the entry point for a DXE Driver, DXE Runtime Driver, DXE SMM Driver,

+  or UEFI Driver. This function must call ProcessLibraryConstructorList() and

+  ProcessModuleEntryPointList(). If the return status from ProcessModuleEntryPointList()

+  is an error status, then ProcessLibraryDestructorList() must be called. The return

+  value from ProcessModuleEntryPointList() is returned. If _gDriverUnloadImageCount is

+  greater than zero, then an unload handler must be registered for this image and the

+  unload handler must invoke ProcessModuleUnloadList(). If _gUefiDriverRevision is not

+  zero and SystemTable->Hdr.Revision is less than _gUefiDriverRevison, then return

+  EFI_INCOMPATIBLE_VERSION.

+

+  @param  ImageHandle  ImageHandle of the loaded driver.

+  @param  SystemTable  Pointer to the EFI System Table.

+

+  @retval  EFI_SUCCESS               One or more of the drivers returned a success code.

+  @retval  EFI_INCOMPATIBLE_VERSION  _gUefiDriverRevision is greater than SystemTable->Hdr.Revision.

+  @retval  Other                     Return value from ProcessModuleEntryPointList().

 

 **/

 EFI_STATUS

@@ -46,14 +57,17 @@ _ModuleEntryPoint (
 

 

 /**

-  Enrty point wrapper of DXE Driver.

+  Required by the EBC compiler and identical in functionality to _ModuleEntryPoint().

+

+  This function is required to call _ModuleEntryPoint() passing in ImageHandle, and SystemTable.

 

   @param  ImageHandle ImageHandle of the loaded driver.

   @param  SystemTable Pointer to the EFI System Table.

 

-  @retval  EFI_SUCCESS One or more of the drivers returned a success code.

-  @retval  !EFI_SUCESS The return status from the last driver entry point in the list.

-

+  @retval  EFI_SUCCESS               The DXE Driver, DXE Runtime Driver, DXE SMM Driver,

+                                     or UEFI Driver exited normally.

+  @retval  EFI_INCOMPATIBLE_VERSION  _gUefiDriverRevision is greater than SystemTable->Hdr.Revision.

+  @retval  Other                     Return value from ProcessModuleEntryPointList().

 **/

 EFI_STATUS

 EFIAPI

@@ -64,8 +78,11 @@ EfiMain (
 

 

 /**

-  Computes the cummulative return status for the driver entry point and perform

-  a long jump back into DriverEntryPoint().

+  Invokes the library destructors fror all dependent libraries and terminates the

+  DXE Driver, DXE Runtime Driver, DXE SMM Driver, or UEFI Driver. 

+

+  This function calls ProcessLibraryDestructorList() and the EFI Boot Service Exit()

+  with a status specified by Status.

 

   @param  Status Status returned by the driver that is exiting.

 

@@ -78,7 +95,17 @@ ExitDriver (
 

 

 /**

-  Call constructs for all libraries. Automatics Generated by tool.

+  Autogenerated function that calls the library constructors for all of the module's

+  dependent libraries.

+

+  This function must be called by _ModuleEntryPoint().

+  This function calls the set of library constructors for the set of library instances

+  that a module depends on. This includes library instances that a module depends on

+  directly and library instances that a module depends on indirectly through other libraries.  

+  This function is autogenerated by build tools and those build tools are responsible

+  for collecting the set of library instances, determine which ones have constructors,

+  and calling the library constructors in the proper order based upon each of the library

+  instances own dependencies.

 

   @param  ImageHandle ImageHandle of the loaded driver.

   @param  SystemTable Pointer to the EFI System Table.

@@ -93,7 +120,15 @@ ProcessLibraryConstructorList (
 

 

 /**

-  Call destructors for all libraries. Automatics Generated by tool.

+  Autogenerated function that calls the library descructors for all of the module's dependent libraries.

+

+  This function may be called by _ModuleEntryPoint() or ExitDriver().

+  This function calls the set of library destructors for the set of library instances

+  that a module depends on. This includes library instances that a module depends on

+  directly and library instances that a module depends on indirectly through other libraries.  

+  This function is autogenerated by build tools and those build tools are responsible for

+  collecting the set of library instances, determine which ones have destructors, and calling

+  the library destructors in the proper order based upon each of the library instances own dependencies.

 

   @param  ImageHandle ImageHandle of the loaded driver.

   @param  SystemTable Pointer to the EFI System Table.

@@ -106,24 +141,20 @@ ProcessLibraryDestructorList (
   IN EFI_SYSTEM_TABLE  *SystemTable

   );

 

-/**

-  Call the list of driver entry points. Automatics Generated by tool.

-

-  @param  ImageHandle ImageHandle of the loaded driver.

-  @param  SystemTable Pointer to the EFI System Table.

-

-  @return Status returned by entry points of drivers.  

- 

-**/

 

 /**

-  Call the list of driver entry points. Automatics Generated by tool.

+  Autogenerated function that calls a set of module entry points.

+

+  This function must be called by _ModuleEntryPoint().

+  This function calls the set of module entry points.  

+  This function is autogenerated by build tools and those build tools are responsible

+  for collecting the module entry points and calling them in a specified order.

 

   @param  ImageHandle ImageHandle of the loaded driver.

   @param  SystemTable Pointer to the EFI System Table.

 

-  @return Status returned by entry points of drivers.  

- 

+  @retval  EFI_SUCCESS   The UEFI Application executed normally.

+  @retval  !EFI_SUCCESS  The UEFI Application failed to execute normally.

 **/

 EFI_STATUS

 EFIAPI

@@ -134,11 +165,17 @@ ProcessModuleEntryPointList (
 

 

 /**

-  Call the unload handlers for all the modules. Automatics Generated by tool.

+  Autogenerated function that calls a set of module unload handlers.

+

+  This function must be called from the unload handler registered by _ModuleEntryPoint().

+  This function calls the set of module unload handlers.  

+  This function is autogenerated by build tools and those build tools are responsible

+  for collecting the module unload handlers and calling them in a specified order.

 

   @param  ImageHandle ImageHandle of the loaded driver.

- 

-  @return Status returned by unload handlers of drivers.

+

+  @retval  EFI_SUCCESS  The unoad handlers executed normally.

+  @retval  !EFI_SUCCESS The unload handlers failed to execute normally.

 

 **/

 EFI_STATUS