Add doxygen style comments for functions in DxeMain.

[mirror_edk2.git] / MdeModulePkg / Core / Dxe / Library.h

/** @file \r
\r
  Internal functions shared in DxeCore module.\r
\r
Copyright (c) 2006 - 2008, Intel Corporation                                                         \r
All rights reserved. This program and the accompanying materials                          \r
are licensed and made available under the terms and conditions of the BSD License         \r
which accompanies this distribution.  The full text of the license may be found at        \r
http://opensource.org/licenses/bsd-license.php                                            \r
                                                                                          \r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     \r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.             \r
\r
\r
**/\r
\r
#ifndef _DXE_LIBRARY_H_\r
#define _DXE_LIBRARY_H_\r
\r
\r
\r
/**\r
  Report status code of type EFI_PROGRESS_CODE by caller ID gEfiCallerIdGuid.\r
\r
  @param  Value              Describes the class/subclass/operation of the \r
                             hardware or software entity that the Status Code \r
                             relates to.\r
\r
**/\r
VOID\r
CoreReportProgressCode (\r
  IN  EFI_STATUS_CODE_VALUE   Value\r
  )\r
;\r
\r
\r
/**\r
  Report status code of type EFI_PROGRESS_CODE by caller ID gEfiCallerIdGuid,\r
  with a handle as additional information.\r
\r
  @param  Value              Describes the class/subclass/operation of the \r
                             hardware or software entity that the Status Code \r
                             relates to. \r
  @param  Handle             Additional information.\r
\r
**/\r
VOID\r
CoreReportProgressCodeSpecific (\r
  IN  EFI_STATUS_CODE_VALUE   Value,\r
  IN  EFI_HANDLE              Handle\r
  )\r
;\r
\r
\r
/**\r
  Raising to the task priority level of the mutual exclusion\r
  lock, and then acquires ownership of the lock.\r
\r
  @param  Lock               The lock to acquire \r
\r
  @return Lock owned\r
\r
**/\r
VOID\r
CoreAcquireLock (\r
  IN EFI_LOCK *Lock\r
  )\r
;\r
\r
\r
/**\r
  Initialize a basic mutual exclusion lock.   Each lock\r
  provides mutual exclusion access at it's task priority\r
  level.  Since there is no-premption (at any TPL) or\r
  multiprocessor support, acquiring the lock only consists\r
  of raising to the locks TPL.\r
\r
  @param  Lock               The EFI_LOCK structure to initialize \r
\r
  @retval EFI_SUCCESS        Lock Owned. \r
  @retval EFI_ACCESS_DENIED  Reentrant Lock Acquisition, Lock not Owned.\r
\r
**/\r
EFI_STATUS\r
CoreAcquireLockOrFail (\r
  IN EFI_LOCK  *Lock\r
  )\r
;\r
\r
\r
/**\r
  Releases ownership of the mutual exclusion lock, and\r
  restores the previous task priority level.\r
\r
  @param  Lock               The lock to release \r
\r
  @return Lock unowned\r
\r
**/\r
VOID\r
CoreReleaseLock (\r
  IN EFI_LOCK *Lock\r
  )\r
;\r
\r
//\r
// Device Path functions\r
//\r
\r
\r
/**\r
  Calculate the size of a whole device path.\r
\r
  @param  DevicePath         The pointer to the device path data. \r
\r
  @return Size of device path data structure..\r
\r
**/\r
UINTN\r
CoreDevicePathSize (\r
  IN EFI_DEVICE_PATH_PROTOCOL  *DevicePath\r
  )\r
;\r
\r
\r
/**\r
  Return TRUE is this is a multi instance device path.\r
\r
  @param  DevicePath         A pointer to a device path data structure. \r
\r
  @retval TRUE               If DevicePath is multi instance. FALSE - If \r
                             DevicePath is not multi instance.\r
\r
**/\r
BOOLEAN\r
CoreIsDevicePathMultiInstance (\r
  IN EFI_DEVICE_PATH_PROTOCOL  *DevicePath\r
  )\r
;\r
\r
\r
\r
/**\r
  Duplicate a new device path data structure from the old one.\r
\r
  @param  DevicePath         A pointer to a device path data structure. \r
\r
  @return A pointer to the new allocated device path data.\r
  @return Caller must free the memory used by DevicePath if it is no longer needed.\r
\r
**/\r
EFI_DEVICE_PATH_PROTOCOL *\r
CoreDuplicateDevicePath (\r
  IN EFI_DEVICE_PATH_PROTOCOL   *DevicePath\r
  )\r
;\r
\r
\r
/**\r
  Function is used to append a Src1 and Src2 together.\r
\r
  @param  Src1               A pointer to a device path data structure. \r
  @param  Src2               A pointer to a device path data structure. \r
\r
  @return A pointer to the new device path is returned.\r
  @return NULL is returned if space for the new device path could not be allocated from pool.\r
  @return It is up to the caller to free the memory used by Src1 and Src2 if they are no longer needed.\r
\r
**/\r
EFI_DEVICE_PATH_PROTOCOL *\r
CoreAppendDevicePath (\r
  IN EFI_DEVICE_PATH_PROTOCOL  *Src1,\r
  IN EFI_DEVICE_PATH_PROTOCOL  *Src2\r
  )\r
;\r
\r
\r
/**\r
  Allocate pool of type EfiBootServicesData, the size is specified with AllocationSize.\r
\r
  @param  AllocationSize     Size to allocate. \r
\r
  @return Pointer of the allocated pool.\r
\r
**/\r
VOID *\r
CoreAllocateBootServicesPool (\r
  IN  UINTN   AllocationSize\r
  )\r
;\r
\r
\r
/**\r
  Allocate pool of type EfiBootServicesData and zero it, the size is specified with AllocationSize.\r
\r
  @param  AllocationSize     Size to allocate. \r
\r
  @return Pointer of the allocated pool.\r
\r
**/\r
VOID *\r
CoreAllocateZeroBootServicesPool (\r
  IN  UINTN   AllocationSize\r
  )\r
;\r
\r
\r
/**\r
  Find a config table by name in system table's ConfigurationTable.\r
\r
  @param  Guid           The table name to look for \r
  @param  Table          Pointer of the config table \r
\r
  @retval EFI_NOT_FOUND  Could not find the table in system table's \r
                         ConfigurationTable. \r
  @retval EFI_SUCCESS    Table successfully found.\r
\r
**/\r
EFI_STATUS\r
CoreGetConfigTable (\r
  IN EFI_GUID *Guid,\r
  IN OUT VOID **Table\r
  )\r
;\r
\r
\r
/**\r
  Allocate pool of specified size with EfiRuntimeServicesData type, and copy specified buffer to this pool.\r
\r
  @param  AllocationSize     Size to allocate. \r
  @param  Buffer             Specified buffer that will be copy to the allocated \r
                             pool \r
\r
  @return Pointer of the allocated pool.\r
\r
**/\r
VOID *\r
CoreAllocateRuntimeCopyPool (\r
  IN  UINTN   AllocationSize,\r
  IN  VOID    *Buffer\r
  )\r
;\r
\r
\r
/**\r
  Allocate pool of type EfiRuntimeServicesData, the size is specified with AllocationSize.\r
\r
  @param  AllocationSize     Size to allocate. \r
\r
  @return Pointer of the allocated pool.\r
\r
**/\r
VOID *\r
CoreAllocateRuntimePool (\r
  IN  UINTN   AllocationSize\r
  )\r
;\r
\r
\r
/**\r
  Allocate pool of specified size with EfiBootServicesData type, and copy specified buffer to this pool.\r
\r
  @param  AllocationSize     Size to allocate. \r
  @param  Buffer             Specified buffer that will be copy to the allocated \r
                             pool \r
\r
  @return Pointer of the allocated pool.\r
\r
**/\r
VOID *\r
CoreAllocateCopyPool (\r
  IN  UINTN   AllocationSize,\r
  IN  VOID    *Buffer\r
  )\r
;\r
\r
\r
/**\r
  Create a protocol notification event and return it.\r
\r
  @param  ProtocolGuid       Protocol to register notification event on. \r
  @param  NotifyTpl          Maximum TPL to signal the NotifyFunction. \r
  @param  NotifyFunction     EFI notification routine. \r
  @param  NotifyContext      Context passed into Event when it is created. \r
  @param  Registration       Registration key returned from \r
                             RegisterProtocolNotify(). \r
  @param  SignalFlag         Boolean value to decide whether kick the event after \r
                             register or not. \r
\r
  @return The EFI_EVENT that has been registered to be signaled when a ProtocolGuid\r
          is added to the system.\r
\r
**/\r
EFI_EVENT\r
CoreCreateProtocolNotifyEvent (\r
  IN EFI_GUID             *ProtocolGuid,\r
  IN EFI_TPL              NotifyTpl,\r
  IN EFI_EVENT_NOTIFY     NotifyFunction,\r
  IN VOID                 *NotifyContext,\r
  OUT VOID                **Registration,\r
  IN  BOOLEAN             SignalFlag\r
  )\r
;\r
\r
#endif\r