From 162ed594438ab8d39f89b43e6d645ca24e1e1e65 Mon Sep 17 00:00:00 2001 From: qhuang8 Date: Fri, 9 May 2008 07:08:30 +0000 Subject: 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 --- MdeModulePkg/Core/Dxe/Library.h | 366 +++++++++++++++------------------------- 1 file changed, 135 insertions(+), 231 deletions(-) (limited to 'MdeModulePkg/Core/Dxe/Library.h') 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 -- cgit v1.2.3