MdeModulePkg/Core/Dxe/Library.h

   1 /** @file
   2   Internal functions shared in DxeCore module.
   3
   4 Copyright (c) 2006 - 2008, Intel Corporation. <BR>
   5 All rights reserved. This program and the accompanying materials
   6 are licensed and made available under the terms and conditions of the BSD License
   7 which accompanies this distribution.  The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef _DXE_LIBRARY_H_
  16 #define _DXE_LIBRARY_H_
  17
  18
  19
  20 /**
  21   Report status code of type EFI_PROGRESS_CODE by caller ID gEfiCallerIdGuid.
  22
  23   @param  Value              Describes the class/subclass/operation of the
  24                              hardware or software entity that the Status Code
  25                              relates to.
  26
  27 **/
  28 VOID
  29 CoreReportProgressCode (
  30   IN  EFI_STATUS_CODE_VALUE   Value
  31   );
  32
  33
  34 /**
  35   Report status code of type EFI_PROGRESS_CODE by caller ID gEfiCallerIdGuid,
  36   with a handle as additional information.
  37
  38   @param  Value              Describes the class/subclass/operation of the
  39                              hardware or software entity that the Status Code
  40                              relates to.
  41   @param  Handle             Additional information.
  42
  43 **/
  44 VOID
  45 CoreReportProgressCodeSpecific (
  46   IN  EFI_STATUS_CODE_VALUE   Value,
  47   IN  EFI_HANDLE              Handle
  48   );
  49
  50
  51 /**
  52   Raising to the task priority level of the mutual exclusion
  53   lock, and then acquires ownership of the lock.
  54
  55   @param  Lock               The lock to acquire
  56
  57   @return Lock owned
  58
  59 **/
  60 VOID
  61 CoreAcquireLock (
  62   IN EFI_LOCK  *Lock
  63   );
  64
  65
  66 /**
  67   Initialize a basic mutual exclusion lock.   Each lock
  68   provides mutual exclusion access at it's task priority
  69   level.  Since there is no-premption (at any TPL) or
  70   multiprocessor support, acquiring the lock only consists
  71   of raising to the locks TPL.
  72
  73   @param  Lock               The EFI_LOCK structure to initialize
  74
  75   @retval EFI_SUCCESS        Lock Owned.
  76   @retval EFI_ACCESS_DENIED  Reentrant Lock Acquisition, Lock not Owned.
  77
  78 **/
  79 EFI_STATUS
  80 CoreAcquireLockOrFail (
  81   IN EFI_LOCK  *Lock
  82   );
  83
  84
  85 /**
  86   Releases ownership of the mutual exclusion lock, and
  87   restores the previous task priority level.
  88
  89   @param  Lock               The lock to release
  90
  91   @return Lock unowned
  92
  93 **/
  94 VOID
  95 CoreReleaseLock (
  96   IN EFI_LOCK  *Lock
  97   );
  98
  99 //
 100 // Device Path functions
 101 //
 102
 103
 104 /**
 105   Calculate the size of a whole device path.
 106
 107   @param  DevicePath         The pointer to the device path data.
 108
 109   @return Size of device path data structure..
 110
 111 **/
 112 UINTN
 113 CoreDevicePathSize (
 114   IN EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 115   );
 116
 117
 118 /**
 119   Return TRUE is this is a multi instance device path.
 120
 121   @param  DevicePath         A pointer to a device path data structure.
 122
 123   @retval TRUE               If DevicePath is multi instance. FALSE - If
 124                              DevicePath is not multi instance.
 125
 126 **/
 127 BOOLEAN
 128 CoreIsDevicePathMultiInstance (
 129   IN EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 130   );
 131
 132
 133
 134 /**
 135   Duplicate a new device path data structure from the old one.
 136
 137   @param  DevicePath         A pointer to a device path data structure.
 138
 139   @return A pointer to the new allocated device path data.
 140   @return Caller must free the memory used by DevicePath if it is no longer needed.
 141
 142 **/
 143 EFI_DEVICE_PATH_PROTOCOL *
 144 CoreDuplicateDevicePath (
 145   IN EFI_DEVICE_PATH_PROTOCOL   *DevicePath
 146   );
 147
 148
 149 /**
 150   Function is used to append a Src1 and Src2 together.
 151
 152   @param  Src1               A pointer to a device path data structure.
 153   @param  Src2               A pointer to a device path data structure.
 154
 155   @return A pointer to the new device path is returned.
 156   @return NULL is returned if space for the new device path could not be allocated from pool.
 157   @return It is up to the caller to free the memory used by Src1 and Src2 if they are no longer needed.
 158
 159 **/
 160 EFI_DEVICE_PATH_PROTOCOL *
 161 CoreAppendDevicePath (
 162   IN EFI_DEVICE_PATH_PROTOCOL  *Src1,
 163   IN EFI_DEVICE_PATH_PROTOCOL  *Src2
 164   );
 165
 166
 167 /**
 168   Allocate pool of type EfiBootServicesData, the size is specified with AllocationSize.
 169
 170   @param  AllocationSize     Size to allocate.
 171
 172   @return Pointer of the allocated pool.
 173
 174 **/
 175 VOID *
 176 CoreAllocateBootServicesPool (
 177   IN  UINTN   AllocationSize
 178   );
 179
 180
 181 /**
 182   Allocate pool of type EfiBootServicesData and zero it, the size is specified with AllocationSize.
 183
 184   @param  AllocationSize     Size to allocate.
 185
 186   @return Pointer of the allocated pool.
 187
 188 **/
 189 VOID *
 190 CoreAllocateZeroBootServicesPool (
 191   IN  UINTN   AllocationSize
 192   );
 193
 194
 195 /**
 196   Find a config table by name in system table's ConfigurationTable.
 197
 198   @param  Guid           The table name to look for
 199   @param  Table          Pointer of the config table
 200
 201   @retval EFI_NOT_FOUND  Could not find the table in system table's
 202                          ConfigurationTable.
 203   @retval EFI_SUCCESS    Table successfully found.
 204
 205 **/
 206 EFI_STATUS
 207 CoreGetConfigTable (
 208   IN EFI_GUID *Guid,
 209   OUT VOID    **Table
 210   );
 211
 212
 213 /**
 214   Allocate pool of specified size with EfiRuntimeServicesData type, and copy specified buffer to this pool.
 215
 216   @param  AllocationSize     Size to allocate.
 217   @param  Buffer             Specified buffer that will be copy to the allocated
 218                              pool
 219
 220   @return Pointer of the allocated pool.
 221
 222 **/
 223 VOID *
 224 CoreAllocateRuntimeCopyPool (
 225   IN  UINTN   AllocationSize,
 226   IN  VOID    *Buffer
 227   );
 228
 229
 230 /**
 231   Allocate pool of type EfiRuntimeServicesData, the size is specified with AllocationSize.
 232
 233   @param  AllocationSize     Size to allocate.
 234
 235   @return Pointer of the allocated pool.
 236
 237 **/
 238 VOID *
 239 CoreAllocateRuntimePool (
 240   IN  UINTN   AllocationSize
 241   );
 242
 243
 244 /**
 245   Allocate pool of specified size with EfiBootServicesData type, and copy specified buffer to this pool.
 246
 247   @param  AllocationSize     Size to allocate.
 248   @param  Buffer             Specified buffer that will be copy to the allocated
 249                              pool
 250
 251   @return Pointer of the allocated pool.
 252
 253 **/
 254 VOID *
 255 CoreAllocateCopyPool (
 256   IN  UINTN   AllocationSize,
 257   IN  VOID    *Buffer
 258   );
 259
 260
 261 /**
 262   Create a protocol notification event and return it.
 263
 264   @param  ProtocolGuid       Protocol to register notification event on.
 265   @param  NotifyTpl          Maximum TPL to signal the NotifyFunction.
 266   @param  NotifyFunction     EFI notification routine.
 267   @param  NotifyContext      Context passed into Event when it is created.
 268   @param  Registration       Registration key returned from
 269                              RegisterProtocolNotify().
 270   @param  SignalFlag         Boolean value to decide whether kick the event after
 271                              register or not.
 272
 273   @return The EFI_EVENT that has been registered to be signaled when a ProtocolGuid
 274           is added to the system.
 275
 276 **/
 277 EFI_EVENT
 278 CoreCreateProtocolNotifyEvent (
 279   IN EFI_GUID             *ProtocolGuid,
 280   IN EFI_TPL              NotifyTpl,
 281   IN EFI_EVENT_NOTIFY     NotifyFunction,
 282   IN VOID                 *NotifyContext,
 283   OUT VOID                **Registration,
 284   IN  BOOLEAN             SignalFlag
 285   );
 286
 287 #endif