Add doxygen style comments for functions in DxeMain.

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

1 files changed, 135 insertions, 231 deletions

diff --git a/MdeModulePkg/Core/Dxe/Library.h b/MdeModulePkg/Core/Dxe/Library.h
index 7c15c938e2..067f0dab5e 100644
--- a/MdeModulePkg/Core/Dxe/Library.h
+++ b/MdeModulePkg/Core/Dxe/Library.h
@@ -11,356 +11,286 @@ http://opensource.org/licenses/bsd-license.php
 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     

 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.             

 

---*/

+

+**/

 

 #ifndef _DXE_LIBRARY_H_

 #define _DXE_LIBRARY_H_

 

 

+

+/**

+  Report status code of type EFI_PROGRESS_CODE by caller ID gEfiCallerIdGuid.

+

+  @param  Value              Describes the class/subclass/operation of the 

+                             hardware or software entity that the Status Code 

+                             relates to.

+

+**/

 VOID

 CoreReportProgressCode (

   IN  EFI_STATUS_CODE_VALUE   Value

   )

-/*++

-

-Routine Description:

-

-  Report status code of type EFI_PROGRESS_CODE by caller ID gEfiCallerIdGuid.

-    

-Arguments:

+;

 

-  Value    - Describes the class/subclass/operation of the hardware or software entity 

-             that the Status Code relates to. 

-   

-Returns:

 

-  None

+/**

+  Report status code of type EFI_PROGRESS_CODE by caller ID gEfiCallerIdGuid,

+  with a handle as additional information.

 

---*/

-;

+  @param  Value              Describes the class/subclass/operation of the 

+                             hardware or software entity that the Status Code 

+                             relates to. 

+  @param  Handle             Additional information.

 

+**/

 VOID

 CoreReportProgressCodeSpecific (

   IN  EFI_STATUS_CODE_VALUE   Value,

   IN  EFI_HANDLE              Handle

   )

-/*++

-

-Routine Description:

+;

 

-  Report status code of type EFI_PROGRESS_CODE by caller ID gEfiCallerIdGuid, 

-  with a handle as additional information.

-    

-Arguments:

 

-  Value    - Describes the class/subclass/operation of the hardware or software entity 

-             that the Status Code relates to. 

-             

-  Handle   - Additional information.

-   

-Returns:

+/**

+  Raising to the task priority level of the mutual exclusion

+  lock, and then acquires ownership of the lock.

 

-  None

+  @param  Lock               The lock to acquire 

 

---*/

-;

+  @return Lock owned

 

+**/

 VOID

 CoreAcquireLock (

   IN EFI_LOCK *Lock

   )

-/*++

-

-Routine Description:

+;

 

-  Raising to the task priority level of the mutual exclusion

-  lock, and then acquires ownership of the lock.

-    

-Arguments:

 

-  Lock - The lock to acquire

-    

-Returns:

+/**

+  Initialize a basic mutual exclusion lock.   Each lock

+  provides mutual exclusion access at it's task priority

+  level.  Since there is no-premption (at any TPL) or

+  multiprocessor support, acquiring the lock only consists

+  of raising to the locks TPL.

 

-  Lock owned

+  @param  Lock               The EFI_LOCK structure to initialize 

 

---*/

-;

+  @retval EFI_SUCCESS        Lock Owned. 

+  @retval EFI_ACCESS_DENIED  Reentrant Lock Acquisition, Lock not Owned.

 

+**/

 EFI_STATUS

 CoreAcquireLockOrFail (

   IN EFI_LOCK  *Lock

   )

-/*++

-

-Routine Description:

+;

 

-  Initialize a basic mutual exclusion lock.   Each lock

-  provides mutual exclusion access at it's task priority

-  level.  Since there is no-premption (at any TPL) or

-  multiprocessor support, acquiring the lock only consists

-  of raising to the locks TPL.

-    

-Arguments:

 

-  Lock        - The EFI_LOCK structure to initialize

-   

-Returns:

+/**

+  Releases ownership of the mutual exclusion lock, and

+  restores the previous task priority level.

 

-  EFI_SUCCESS       - Lock Owned.

-  EFI_ACCESS_DENIED - Reentrant Lock Acquisition, Lock not Owned.

+  @param  Lock               The lock to release 

 

---*/

-;

+  @return Lock unowned

 

+**/

 VOID

 CoreReleaseLock (

   IN EFI_LOCK *Lock

   )

-/*++

-

-Routine Description:

-

-    Releases ownership of the mutual exclusion lock, and

-    restores the previous task priority level.

-    

-Arguments:

-

-    Lock - The lock to release

-    

-Returns:

-

-    Lock unowned

-

---*/

 ;

 

 //

 // Device Path functions

 //

 

+

+/**

+  Calculate the size of a whole device path.

+

+  @param  DevicePath         The pointer to the device path data. 

+

+  @return Size of device path data structure..

+

+**/

 UINTN

 CoreDevicePathSize (

   IN EFI_DEVICE_PATH_PROTOCOL  *DevicePath

   )

-/*++

-

-Routine Description:

+;

 

-  Calculate the size of a whole device path.    

-    

-Arguments:

 

-  DevicePath - The pointer to the device path data.

-    

-Returns:

+/**

+  Return TRUE is this is a multi instance device path.

 

-  Size of device path data structure..

+  @param  DevicePath         A pointer to a device path data structure. 

 

---*/

-;

+  @retval TRUE               If DevicePath is multi instance. FALSE - If 

+                             DevicePath is not multi instance.

 

+**/

 BOOLEAN

 CoreIsDevicePathMultiInstance (

   IN EFI_DEVICE_PATH_PROTOCOL  *DevicePath

   )

-/*++

-

-Routine Description:

-  Return TRUE is this is a multi instance device path.

+;

 

-Arguments:

-  DevicePath  - A pointer to a device path data structure.

 

 

-Returns:

-  TRUE - If DevicePath is multi instance. FALSE - If DevicePath is not multi

-  instance.

+/**

+  Duplicate a new device path data structure from the old one.

 

---*/

-;

+  @param  DevicePath         A pointer to a device path data structure. 

 

+  @return A pointer to the new allocated device path data.

+  @return Caller must free the memory used by DevicePath if it is no longer needed.

 

+**/

 EFI_DEVICE_PATH_PROTOCOL *

 CoreDuplicateDevicePath (

   IN EFI_DEVICE_PATH_PROTOCOL   *DevicePath

   )

-/*++

+;

 

-Routine Description:

-  Duplicate a new device path data structure from the old one.

 

-Arguments:

-  DevicePath  - A pointer to a device path data structure.

+/**

+  Function is used to append a Src1 and Src2 together.

 

-Returns:

-  A pointer to the new allocated device path data.

-  Caller must free the memory used by DevicePath if it is no longer needed.

+  @param  Src1               A pointer to a device path data structure. 

+  @param  Src2               A pointer to a device path data structure. 

 

---*/

-;

+  @return A pointer to the new device path is returned.

+  @return NULL is returned if space for the new device path could not be allocated from pool.

+  @return It is up to the caller to free the memory used by Src1 and Src2 if they are no longer needed.

 

+**/

 EFI_DEVICE_PATH_PROTOCOL *

 CoreAppendDevicePath (

   IN EFI_DEVICE_PATH_PROTOCOL  *Src1,

-  IN EFI_DEVICE_PATH_PROTOCOL  *Node

+  IN EFI_DEVICE_PATH_PROTOCOL  *Src2

   )

-/*++

-

-Routine Description:

-  Function is used to append a Src1 and Src2 together.

-

-Arguments:

-  Src1  - A pointer to a device path data structure.

+;

 

-  Node  - A pointer to a device path data structure.

 

-Returns:

+/**

+  Allocate pool of type EfiBootServicesData, the size is specified with AllocationSize.

 

-  A pointer to the new device path is returned.

-  NULL is returned if space for the new device path could not be allocated from pool.

-  It is up to the caller to free the memory used by Src1 and Src2 if they are no longer needed.

+  @param  AllocationSize     Size to allocate. 

 

---*/

-;

+  @return Pointer of the allocated pool.

 

+**/

 VOID *

 CoreAllocateBootServicesPool (

   IN  UINTN   AllocationSize

   )

-/*++

+;

 

-Routine Description:

 

-  Allocate pool of type EfiBootServicesData, the size is specified with AllocationSize.

-    

-Arguments:

-

-  AllocationSize    - Size to allocate.

-   

-Returns:

+/**

+  Allocate pool of type EfiBootServicesData and zero it, the size is specified with AllocationSize.

 

-  Pointer of the allocated pool.

+  @param  AllocationSize     Size to allocate. 

 

---*/

-;

+  @return Pointer of the allocated pool.

 

+**/

 VOID *

 CoreAllocateZeroBootServicesPool (

   IN  UINTN   AllocationSize

   )

-/*++

+;

 

-Routine Description:

 

-  Allocate pool of type EfiBootServicesData and zero it, the size is specified with AllocationSize.

-    

-Arguments:

+/**

+  Find a config table by name in system table's ConfigurationTable.

 

-  AllocationSize    - Size to allocate.

-   

-Returns:

+  @param  Guid           The table name to look for 

+  @param  Table          Pointer of the config table 

 

-  Pointer of the allocated pool.

-

---*/

-;

+  @retval EFI_NOT_FOUND  Could not find the table in system table's 

+                         ConfigurationTable. 

+  @retval EFI_SUCCESS    Table successfully found.

 

+**/

 EFI_STATUS

 CoreGetConfigTable (

   IN EFI_GUID *Guid,

   IN OUT VOID **Table

   )

-/*++

-

-Routine Description:

-

-  Find a config table by name in system table's ConfigurationTable.

-

-Arguments:

+;

 

-  Guid        - The table name to look for

-  

-  Table       - Pointer of the config table

 

-Returns: 

+/**

+  Allocate pool of specified size with EfiRuntimeServicesData type, and copy specified buffer to this pool.

 

-  EFI_NOT_FOUND       - Could not find the table in system table's ConfigurationTable.

-  

-  EFI_SUCCESS         - Table successfully found.

+  @param  AllocationSize     Size to allocate. 

+  @param  Buffer             Specified buffer that will be copy to the allocated 

+                             pool 

 

---*/

-;

+  @return Pointer of the allocated pool.

 

+**/

 VOID *

 CoreAllocateRuntimeCopyPool (

   IN  UINTN   AllocationSize,

   IN  VOID    *Buffer

   )

-/*++

-

-Routine Description:

+;

 

-  Allocate pool of specified size with EfiRuntimeServicesData type, and copy specified buffer to this pool.

-    

-Arguments:

 

-  AllocationSize    - Size to allocate.

-  

-  Buffer            - Specified buffer that will be copy to the allocated pool

-   

-Returns:

+/**

+  Allocate pool of type EfiRuntimeServicesData, the size is specified with AllocationSize.

 

-  Pointer of the allocated pool.

+  @param  AllocationSize     Size to allocate. 

 

---*/

-;

+  @return Pointer of the allocated pool.

 

+**/

 VOID *

 CoreAllocateRuntimePool (

   IN  UINTN   AllocationSize

   )

-/*++

-

-Routine Description:

+;

 

-  Allocate pool of type EfiRuntimeServicesData, the size is specified with AllocationSize.

-    

-Arguments:

 

-  AllocationSize    - Size to allocate.

-   

-Returns:

+/**

+  Allocate pool of specified size with EfiBootServicesData type, and copy specified buffer to this pool.

 

-  Pointer of the allocated pool.

+  @param  AllocationSize     Size to allocate. 

+  @param  Buffer             Specified buffer that will be copy to the allocated 

+                             pool 

 

---*/

-;

+  @return Pointer of the allocated pool.

 

+**/

 VOID *

 CoreAllocateCopyPool (

   IN  UINTN   AllocationSize,

   IN  VOID    *Buffer

   )

-/*++

+;

 

-Routine Description:

 

-  Allocate pool of specified size with EfiBootServicesData type, and copy specified buffer to this pool.

-    

-Arguments:

-

-  AllocationSize    - Size to allocate.

-  

-  Buffer            - Specified buffer that will be copy to the allocated pool

-   

-Returns:

+/**

+  Create a protocol notification event and return it.

 

-  Pointer of the allocated pool.

+  @param  ProtocolGuid       Protocol to register notification event on. 

+  @param  NotifyTpl          Maximum TPL to signal the NotifyFunction. 

+  @param  NotifyFunction     EFI notification routine. 

+  @param  NotifyContext      Context passed into Event when it is created. 

+  @param  Registration       Registration key returned from 

+                             RegisterProtocolNotify(). 

+  @param  SignalFlag         Boolean value to decide whether kick the event after 

+                             register or not. 

 

---*/

-;

+  @return The EFI_EVENT that has been registered to be signaled when a ProtocolGuid

+          is added to the system.

 

+**/

 EFI_EVENT

 CoreCreateProtocolNotifyEvent (

   IN EFI_GUID             *ProtocolGuid,

@@ -370,32 +300,6 @@ CoreCreateProtocolNotifyEvent (
   OUT VOID                **Registration,

   IN  BOOLEAN             SignalFlag

   )

-/*++

-

-Routine Description:

-

-  Create a protocol notification event and return it.

-

-Arguments:

-

-  ProtocolGuid    - Protocol to register notification event on.

-

-  NotifyTpl       - Maximum TPL to signal the NotifyFunction.

-

-  NotifyFuncition - EFI notification routine.

-

-  NotifyContext   - Context passed into Event when it is created.

-

-  Registration    - Registration key returned from RegisterProtocolNotify().

-

-  SignalFlag      -  Boolean value to decide whether kick the event after register or not. 

-

-Returns:

-

-  The EFI_EVENT that has been registered to be signaled when a ProtocolGuid

-  is added to the system.

-

---*/

 ;

 

 #endif