MdePkg/Include/Library/UefiLib.h

   1 /** @file
   2   MDE UEFI library functions and macros
   3
   4   Copyright (c) 2006 - 2007, Intel Corporation
   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 __UEFI_LIB_H__
  16 #define __UEFI_LIB_H__
  17
  18 //
  19 // Unicode String Table
  20 //
  21 typedef struct {
  22   CHAR8   *Language;
  23   CHAR16  *UnicodeString;
  24 } EFI_UNICODE_STRING_TABLE;
  25
  26 //
  27 // EFI Lock Status
  28 //
  29 typedef enum {
  30   EfiLockUninitialized = 0,
  31   EfiLockReleased      = 1,
  32   EfiLockAcquired      = 2
  33 } EFI_LOCK_STATE;
  34
  35 //
  36 // EFI Lock
  37 //
  38 typedef struct {
  39   EFI_TPL         Tpl;
  40   EFI_TPL         OwnerTpl;
  41   EFI_LOCK_STATE  Lock;
  42 } EFI_LOCK;
  43
  44
  45 /**
  46   This function searches the list of configuration tables stored in the EFI System
  47   Table for a table with a GUID that matches TableGuid.  If a match is found,
  48   then a pointer to the configuration table is returned in Table, and EFI_SUCCESS
  49   is returned.  If a matching GUID is not found, then EFI_NOT_FOUND is returned.
  50
  51   @param  TableGuid       Pointer to table's GUID type..
  52   @param  Table           Pointer to the table associated with TableGuid in the EFI System Table.
  53
  54   @retval EFI_SUCCESS     A configuration table matching TableGuid was found.
  55   @retval EFI_NOT_FOUND   A configuration table matching TableGuid could not be found.
  56
  57 **/
  58 EFI_STATUS
  59 EFIAPI
  60 EfiGetSystemConfigurationTable (
  61   IN  EFI_GUID  *TableGuid,
  62   OUT VOID      **Table
  63   );
  64
  65 /**
  66   This function causes the notification function to be executed for every protocol
  67   of type ProtocolGuid instance that exists in the system when this function is
  68   invoked.  In addition, every time a protocol of type ProtocolGuid instance is
  69   installed or reinstalled, the notification function is also executed.
  70
  71   @param  ProtocolGuid    Supplies GUID of the protocol upon whose installation the event is fired.
  72   @param  NotifyTpl       Supplies the task priority level of the event notifications.
  73   @param  NotifyFunction  Supplies the function to notify when the event is signaled.
  74   @param  NotifyContext   The context parameter to pass to NotifyFunction.
  75   @param  Registration    A pointer to a memory location to receive the registration value.
  76
  77   @return The notification event that was created.
  78
  79 **/
  80 EFI_EVENT
  81 EFIAPI
  82 EfiCreateProtocolNotifyEvent(
  83   IN  EFI_GUID          *ProtocolGuid,
  84   IN  EFI_TPL           NotifyTpl,
  85   IN  EFI_EVENT_NOTIFY  NotifyFunction,
  86   IN  VOID              *NotifyContext,  OPTIONAL
  87   OUT VOID              **Registration
  88   );
  89
  90 /**
  91   This function creates an event using NotifyTpl, NoifyFunction, and NotifyContext.
  92   This event is signaled with EfiNamedEventSignal().  This provide the ability for
  93   one or more listeners on the same event named by the GUID specified by Name.
  94
  95   @param  Name                  Supplies GUID name of the event.
  96   @param  NotifyTpl             Supplies the task priority level of the event notifications.
  97   @param  NotifyFunction        Supplies the function to notify when the event is signaled.
  98   @param  NotifyContext         The context parameter to pass to NotifyFunction.
  99   @param  Registration          A pointer to a memory location to receive the registration value.
 100
 101   @retval EFI_SUCCESS           A named event was created.
 102   @retval EFI_OUT_OF_RESOURCES  There are not enough resource to create the named event.
 103
 104 **/
 105 EFI_STATUS
 106 EFIAPI
 107 EfiNamedEventListen (
 108   IN CONST EFI_GUID    *Name,
 109   IN EFI_TPL           NotifyTpl,
 110   IN EFI_EVENT_NOTIFY  NotifyFunction,
 111   IN CONST VOID        *NotifyContext,  OPTIONAL
 112   OUT VOID             *Registration OPTIONAL
 113   );
 114
 115 /**
 116   This function signals the named event specified by Name.  The named event must
 117   have been created with EfiNamedEventListen().
 118
 119   @param  Name                  Supplies GUID name of the event.
 120
 121   @retval EFI_SUCCESS           A named event was signaled.
 122   @retval EFI_OUT_OF_RESOURCES  There are not enough resource to signal the named event.
 123
 124 **/
 125 EFI_STATUS
 126 EFIAPI
 127 EfiNamedEventSignal (
 128   IN CONST EFI_GUID  *Name
 129   );
 130
 131 /**
 132   This function initializes a basic mutual exclusion lock to the released state
 133   and returns the lock.  Each lock provides mutual exclusion access at its task
 134   priority level.  Since there is no preemption or multiprocessor support in EFI,
 135   acquiring the lock only consists of raising to the locks TPL.
 136
 137   @param  Lock       A pointer to the lock data structure to initialize.
 138   @param  Priority   EFI TPL associated with the lock.
 139
 140   @return The lock.
 141
 142 **/
 143 EFI_LOCK *
 144 EFIAPI
 145 EfiInitializeLock (
 146   IN OUT EFI_LOCK  *Lock,
 147   IN EFI_TPL        Priority
 148   );
 149
 150 /**
 151   This macro initializes the contents of a basic mutual exclusion lock to the
 152   released state.  Each lock provides mutual exclusion access at its task
 153   priority level.  Since there is no preemption or multiprocessor support in EFI,
 154   acquiring the lock only consists of raising to the locks TPL.
 155
 156   @param  Lock      A pointer to the lock data structure to initialize.
 157   @param  Priority  The task priority level of the lock.
 158
 159   @return The lock.
 160
 161 **/
 162 #define EFI_INITIALIZE_LOCK_VARIABLE(Priority) \
 163   {Priority, EFI_TPL_APPLICATION, EfiLockReleased }
 164
 165
 166 /**
 167
 168   Macro that calls DebugAssert() if an EFI_LOCK structure is not in the locked state.
 169
 170   If the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set,
 171   then this macro evaluates the EFI_LOCK structure specified by Lock.  If Lock
 172   is not in the locked state, then DebugAssert() is called passing in the source
 173   filename, source line number, and Lock.
 174
 175   If Lock is NULL, then ASSERT().
 176
 177   @param  LockParameter  A pointer to the lock to acquire.
 178
 179 **/
 180 #define ASSERT_LOCKED(LockParameter)                  \
 181   do {                                                \
 182     if (DebugAssertEnabled ()) {                      \
 183       ASSERT (LockParameter != NULL);                 \
 184       if ((LockParameter)->Lock != EfiLockAcquired) { \
 185         _ASSERT (LockParameter not locked);           \
 186       }                                               \
 187     }                                                 \
 188   } while (FALSE)
 189
 190
 191 /**
 192   This function raises the system's current task priority level to the task
 193   priority level of the mutual exclusion lock.  Then, it places the lock in the
 194   acquired state.
 195
 196   @param  Priority  The task priority level of the lock.
 197
 198 **/
 199 VOID
 200 EFIAPI
 201 EfiAcquireLock (
 202   IN EFI_LOCK  *Lock
 203   );
 204
 205 /**
 206   This function raises the system's current task priority level to the task
 207   priority level of the mutual exclusion lock.  Then, it attempts to place the
 208   lock in the acquired state.
 209
 210   @param  Lock              A pointer to the lock to acquire.
 211
 212   @retval EFI_SUCCESS       The lock was acquired.
 213   @retval EFI_ACCESS_DENIED The lock could not be acquired because it is already owned.
 214
 215 **/
 216 EFI_STATUS
 217 EFIAPI
 218 EfiAcquireLockOrFail (
 219   IN EFI_LOCK  *Lock
 220   );
 221
 222 /**
 223   This function transitions a mutual exclusion lock from the acquired state to
 224   the released state, and restores the system's task priority level to its
 225   previous level.
 226
 227   @param  Lock  A pointer to the lock to release.
 228
 229 **/
 230 VOID
 231 EFIAPI
 232 EfiReleaseLock (
 233   IN EFI_LOCK  *Lock
 234   );
 235
 236 /**
 237   Tests whether a controller is managed by a specific driver.
 238
 239   This function tests whether a specific driver manages ControllerHandle by
 240   opening on DriverBindingHandle a protocol specified by ProtocolGuid with
 241   attribute EFI_OPEN_PROTOCOL_BY_DRIVER.  This library function is used to
 242   implement the Component Name Protocol for EFI Drivers.
 243   If ProtocolGuid is NULL, then ASSERT().
 244
 245   @param  ControllerHandle     A handle for a controller to test.
 246   @param  DriverBindingHandle  Specifies the driver binding handle for the
 247                                driver.
 248   @param  ProtocolGuid         Supplies GUID for the protocol opened by the
 249                                driver on the controller.
 250
 251   @retval EFI_SUCCESS          ControllerHandle is managed by the specific
 252                                driver.
 253   @retval EFI_UNSUPPORTED      ControllerHandle is not managed by the specific
 254                                driver.
 255
 256 **/
 257 EFI_STATUS
 258 EFIAPI
 259 EfiTestManagedDevice (
 260   IN CONST EFI_HANDLE       ControllerHandle,
 261   IN CONST EFI_HANDLE       DriverBindingHandle,
 262   IN CONST EFI_GUID         *ProtocolGuid
 263   );
 264
 265 /**
 266   Tests whether a child handle is a children device of the controller.
 267
 268   This function tests whether ChildHandle is one of the children of
 269   ControllerHandle which are consuming a protocol specified by ProtocolGuid
 270   with the attribute bit EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER set.  This
 271   library function is used to implement the Component Name Protocol for EFI
 272   Drivers.
 273   If ProtocolGuid is NULL, then ASSERT().
 274
 275   @param  ControllerHandle     A handle for a (parent) controller to test.
 276   @param  ChildHandle          A child handle to test.
 277   @param  ConsumsedGuid        Supplies GUID for the protocol consumed by
 278                                children from controller.
 279
 280   @retval EFI_SUCCESS          ChildHandle is a child of the ControllerHandle.
 281   @retval EFI_UNSUPPORTED      ChildHandle is not a child of the
 282                                ControllerHandle.
 283
 284 **/
 285 EFI_STATUS
 286 EFIAPI
 287 EfiTestChildHandle (
 288   IN CONST EFI_HANDLE       ControllerHandle,
 289   IN CONST EFI_HANDLE       ChildHandle,
 290   IN CONST EFI_GUID         *ProtocolGuid
 291   );
 292
 293 /**
 294   This function looks up a Unicode string in UnicodeStringTable.  If Language is
 295   a member of SupportedLanguages and a Unicode string is found in UnicodeStringTable
 296   that matches the language code specified by Language, then it is returned in
 297   UnicodeString.
 298
 299   @param  Language                A pointer to the ISO 639-2 language code for the
 300                                   Unicode string to look up and return.
 301   @param  SupportedLanguages      A pointer to the set of ISO 639-2 language codes
 302                                   that the Unicode string table supports.  Language
 303                                   must be a member of this set.
 304   @param  UnicodeStringTable      A pointer to the table of Unicode strings.
 305   @param  UnicodeString           A pointer to the Unicode string from UnicodeStringTable
 306                                   that matches the language specified by Language.
 307
 308   @retval EFI_SUCCESS             The Unicode string that matches the language
 309                                   specified by Language was found
 310                                   in the table of Unicoide strings UnicodeStringTable,
 311                                   and it was returned in UnicodeString.
 312   @retval EFI_INVALID_PARAMETER   Language is NULL.
 313   @retval EFI_INVALID_PARAMETER   UnicodeString is NULL.
 314   @retval EFI_UNSUPPORTED         SupportedLanguages is NULL.
 315   @retval EFI_UNSUPPORTED         UnicodeStringTable is NULL.
 316   @retval EFI_UNSUPPORTED         The language specified by Language is not a
 317                                   member of SupportedLanguages.
 318   @retval EFI_UNSUPPORTED         The language specified by Language is not
 319                                   supported by UnicodeStringTable.
 320
 321 **/
 322 EFI_STATUS
 323 EFIAPI
 324 LookupUnicodeString (
 325   IN CONST CHAR8                     *Language,
 326   IN CONST CHAR8                     *SupportedLanguages,
 327   IN CONST EFI_UNICODE_STRING_TABLE  *UnicodeStringTable,
 328   OUT CHAR16                         **UnicodeString
 329   );
 330
 331 /**
 332   This function adds a Unicode string to UnicodeStringTable.
 333   If Language is a member of SupportedLanguages then UnicodeString is added to
 334   UnicodeStringTable.  New buffers are allocated for both Language and
 335   UnicodeString.  The contents of Language and UnicodeString are copied into
 336   these new buffers.  These buffers are automatically freed when
 337   FreeUnicodeStringTable() is called.
 338
 339   @param  Language                A pointer to the ISO 639-2 language code for the Unicode
 340                                   string to add.
 341   @param  SupportedLanguages      A pointer to the set of ISO 639-2 language codes
 342                                   that the Unicode string table supports.
 343                                   Language must be a member of this set.
 344   @param  UnicodeStringTable      A pointer to the table of Unicode strings.
 345   @param  UnicodeString           A pointer to the Unicode string to add.
 346
 347   @retval EFI_SUCCESS             The Unicode string that matches the language
 348                                   specified by Language was found in the table of
 349                                   Unicode strings UnicodeStringTable, and it was
 350                                   returned in UnicodeString.
 351   @retval EFI_INVALID_PARAMETER   Language is NULL.
 352   @retval EFI_INVALID_PARAMETER   UnicodeString is NULL.
 353   @retval EFI_INVALID_PARAMETER   UnicodeString is an empty string.
 354   @retval EFI_UNSUPPORTED         SupportedLanguages is NULL.
 355   @retval EFI_ALREADY_STARTED     A Unicode string with language Language is
 356                                   already present in UnicodeStringTable.
 357   @retval EFI_OUT_OF_RESOURCES    There is not enough memory to add another
 358                                   Unicode string to UnicodeStringTable.
 359   @retval EFI_UNSUPPORTED         The language specified by Language is not a
 360                                   member of SupportedLanguages.
 361
 362 **/
 363 EFI_STATUS
 364 EFIAPI
 365 AddUnicodeString (
 366   IN CONST CHAR8               *Language,
 367   IN CONST CHAR8               *SupportedLanguages,
 368   IN EFI_UNICODE_STRING_TABLE  **UnicodeStringTable,
 369   IN CONST CHAR16              *UnicodeString
 370   );
 371
 372 /**
 373   This function frees the table of Unicode strings in UnicodeStringTable.
 374   If UnicodeStringTable is NULL, then EFI_SUCCESS is returned.
 375   Otherwise, each language code, and each Unicode string in the Unicode string
 376   table are freed, and EFI_SUCCESS is returned.
 377
 378   @param  UnicodeStringTable  A pointer to the table of Unicode strings.
 379
 380   @retval EFI_SUCCESS         The Unicode string table was freed.
 381
 382 **/
 383 EFI_STATUS
 384 EFIAPI
 385 FreeUnicodeStringTable (
 386   IN EFI_UNICODE_STRING_TABLE  *UnicodeStringTable
 387   );
 388
 389 /**
 390   This function computes and returns the width of the Unicode character
 391   specified by UnicodeChar.
 392
 393   @param  UnicodeChar   A Unicode character.
 394
 395   @retval 0             The width if UnicodeChar could not be determined.
 396   @retval 1             UnicodeChar is a narrow glyph.
 397   @retval 2             UnicodeChar is a wide glyph.
 398
 399 **/
 400 UINTN
 401 EFIAPI
 402 GetGlyphWidth (
 403   IN CHAR16  UnicodeChar
 404   );
 405
 406 /**
 407   This function computes and returns the display length of
 408   the Null-terminated Unicode string specified by String.
 409   If String is NULL, then 0 is returned.
 410   If any of the widths of the Unicode characters in String
 411   can not be determined, then 0 is returned.
 412
 413   @param  String      A pointer to a Null-terminated Unicode string.
 414
 415   @return The display length of the Null-terminated Unicode string specified by String.
 416
 417 **/
 418 UINTN
 419 EFIAPI
 420 UnicodeStringDisplayLength (
 421   IN CONST CHAR16  *String
 422   );
 423
 424 //
 425 // Functions that abstract early Framework contamination of UEFI.
 426 //
 427 /**
 428   Signal a Ready to Boot Event.
 429
 430   Create a Ready to Boot Event. Signal it and close it. This causes other
 431   events of the same event group to be signaled in other modules.
 432
 433 **/
 434 VOID
 435 EFIAPI
 436 EfiSignalEventReadyToBoot (
 437   VOID
 438   );
 439
 440 /**
 441   Signal a Legacy Boot Event.
 442
 443   Create a legacy Boot Event. Signal it and close it. This causes other
 444   events of the same event group to be signaled in other modules.
 445
 446 **/
 447 VOID
 448 EFIAPI
 449 EfiSignalEventLegacyBoot (
 450   VOID
 451   );
 452
 453 /**
 454   Create a Legacy Boot Event.
 455
 456   Tiano extended the CreateEvent Type enum to add a legacy boot event type.
 457   This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was
 458   added and now it's possible to not voilate the UEFI specification by
 459   declaring a GUID for the legacy boot event class. This library supports
 460   the EDK/EFI 1.10 form and EDK II/UEFI 2.0 form and allows common code to
 461   work both ways.
 462
 463   @param  LegacyBootEvent   Returns the EFI event returned from gBS->CreateEvent(Ex).
 464
 465   @retval EFI_SUCCESS       Event was created.
 466   @retval Other             Event was not created.
 467
 468 **/
 469 EFI_STATUS
 470 EFIAPI
 471 EfiCreateEventLegacyBoot (
 472   OUT EFI_EVENT  *LegacyBootEvent
 473   );
 474
 475 /**
 476   Create an EFI event in the Legacy Boot Event Group and allows
 477   the caller to specify a notification function.
 478
 479   This function abstracts the creation of the Legacy Boot Event.
 480   The Framework moved from a proprietary to UEFI 2.0 based mechanism.
 481   This library abstracts the caller from how this event is created to prevent
 482   to code form having to change with the version of the specification supported.
 483   If LegacyBootEvent is NULL, then ASSERT().
 484
 485   @param  NotifyTpl         The task priority level of the event.
 486   @param  NotifyFunction    The notification function to call when the event is signaled.
 487   @param  NotifyContext     The content to pass to NotifyFunction when the event is signaled.
 488   @param  LegacyBootEvent   Returns the EFI event returned from gBS->CreateEvent(Ex).
 489
 490   @retval EFI_SUCCESS       Event was created.
 491   @retval Other             Event was not created.
 492
 493 **/
 494 EFI_STATUS
 495 EFIAPI
 496 EfiCreateEventLegacyBootEx (
 497   IN  EFI_TPL           NotifyTpl,
 498   IN  EFI_EVENT_NOTIFY  NotifyFunction,  OPTIONAL
 499   IN  VOID              *NotifyContext,  OPTIONAL
 500   OUT EFI_EVENT         *LegacyBootEvent
 501   );
 502
 503 /**
 504   Create a Read to Boot Event.
 505
 506   Tiano extended the CreateEvent Type enum to add a ready to boot event type.
 507   This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was
 508   added and now it's possible to not voilate the UEFI specification and use
 509   the ready to boot event class defined in UEFI 2.0. This library supports
 510   the EDK/EFI 1.10 form and EDKII/UEFI 2.0 form and allows common code to
 511   work both ways.
 512
 513   @param  LegacyBootEvent   Returns the EFI event returned from gBS->CreateEvent(Ex).
 514
 515   @retval EFI_SUCCESS       Event was created.
 516   @retval Other             Event was not created.
 517
 518 **/
 519 EFI_STATUS
 520 EFIAPI
 521 EfiCreateEventReadyToBoot (
 522   OUT EFI_EVENT  *ReadyToBootEvent
 523   );
 524
 525 /**
 526   Create an EFI event in the Ready To Boot Event Group and allows
 527   the caller to specify a notification function.
 528
 529   This function abstracts the creation of the Ready to Boot Event.
 530   The Framework moved from a proprietary to UEFI 2.0 based mechanism.
 531   This library abstracts the caller from how this event is created to prevent
 532   to code form having to change with the version of the specification supported.
 533   If ReadyToBootEvent is NULL, then ASSERT().
 534
 535   @param  NotifyTpl         The task priority level of the event.
 536   @param  NotifyFunction    The notification function to call when the event is signaled.
 537   @param  NotifyContext     The content to pass to NotifyFunction when the event is signaled.
 538   @param  LegacyBootEvent   Returns the EFI event returned from gBS->CreateEvent(Ex).
 539
 540   @retval EFI_SUCCESS       Event was created.
 541   @retval Other             Event was not created.
 542
 543 **/
 544 EFI_STATUS
 545 EFIAPI
 546 EfiCreateEventReadyToBootEx (
 547   IN  EFI_TPL           NotifyTpl,
 548   IN  EFI_EVENT_NOTIFY  NotifyFunction,  OPTIONAL
 549   IN  VOID              *NotifyContext,  OPTIONAL
 550   OUT EFI_EVENT         *ReadyToBootEvent
 551   );
 552
 553 /**
 554   Initialize a Firmware Volume (FV) Media Device Path node.
 555
 556   Tiano extended the EFI 1.10 device path nodes. Tiano does not own this enum
 557   so as we move to UEFI 2.0 support we must use a mechanism that conforms with
 558   the UEFI 2.0 specification to define the FV device path. An UEFI GUIDed
 559   device path is defined for Tiano extensions of device path. If the code
 560   is compiled to conform with the UEFI 2.0 specification use the new device path
 561   else use the old form for backwards compatability.
 562
 563   @param  FvDevicePathNode  Pointer to a FV device path node to initialize
 564   @param  NameGuid          FV file name to use in FvDevicePathNode
 565
 566 **/
 567 VOID
 568 EFIAPI
 569 EfiInitializeFwVolDevicepathNode (
 570   IN OUT MEDIA_FW_VOL_FILEPATH_DEVICE_PATH  *FvDevicePathNode,
 571   IN CONST EFI_GUID                         *NameGuid
 572   );
 573
 574 /**
 575   Check to see if the Firmware Volume (FV) Media Device Path is valid
 576
 577   Tiano extended the EFI 1.10 device path nodes. Tiano does not own this enum
 578   so as we move to UEFI 2.0 support we must use a mechanism that conforms with
 579   the UEFI 2.0 specification to define the FV device path. An UEFI GUIDed
 580   device path is defined for Tiano extensions of device path. If the code
 581   is compiled to conform with the UEFI 2.0 specification use the new device path
 582   else use the old form for backwards compatability. The return value to this
 583   function points to a location in FvDevicePathNode and it does not allocate
 584   new memory for the GUID pointer that is returned.
 585
 586   @param  FvDevicePathNode  Pointer to FV device path to check.
 587
 588   @retval NULL              FvDevicePathNode is not valid.
 589   @retval Other             FvDevicePathNode is valid and pointer to NameGuid was returned.
 590
 591 **/
 592 EFI_GUID *
 593 EFIAPI
 594 EfiGetNameGuidFromFwVolDevicePathNode (
 595   IN CONST MEDIA_FW_VOL_FILEPATH_DEVICE_PATH  *FvDevicePathNode
 596   );
 597
 598
 599 #endif