MdeModulePkg/Core/Dxe/Library.h

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