EdkModulePkg/Core/Dxe/Library.h

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