MdePkg/Include/Library/UefiLib.h

   1 /** @file
   2   MDE UEFI library functions and macros
   3
   4   Copyright (c) 2006, 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   This function looks up a Unicode string in UnicodeStringTable.  If Language is
 238   a member of SupportedLanguages and a Unicode string is found in UnicodeStringTable
 239   that matches the language code specified by Language, then it is returned in
 240   UnicodeString.
 241
 242   @param  Language                A pointer to the ISO 639-2 language code for the
 243                                   Unicode string to look up and return.
 244   @param  SupportedLanguages      A pointer to the set of ISO 639-2 language codes
 245                                   that the Unicode string table supports.  Language
 246                                   must be a member of this set.
 247   @param  UnicodeStringTable      A pointer to the table of Unicode strings.
 248   @param  UnicodeString           A pointer to the Unicode string from UnicodeStringTable
 249                                   that matches the language specified by Language.
 250
 251   @retval EFI_SUCCESS             The Unicode string that matches the language
 252                                   specified by Language was found
 253                                   in the table of Unicoide strings UnicodeStringTable,
 254                                   and it was returned in UnicodeString.
 255   @retval EFI_INVALID_PARAMETER   Language is NULL.
 256   @retval EFI_INVALID_PARAMETER   UnicodeString is NULL.
 257   @retval EFI_UNSUPPORTED         SupportedLanguages is NULL.
 258   @retval EFI_UNSUPPORTED         UnicodeStringTable is NULL.
 259   @retval EFI_UNSUPPORTED         The language specified by Language is not a
 260                                   member of SupportedLanguages.
 261   @retval EFI_UNSUPPORTED         The language specified by Language is not
 262                                   supported by UnicodeStringTable.
 263
 264 **/
 265 EFI_STATUS
 266 EFIAPI
 267 LookupUnicodeString (
 268   IN CONST CHAR8                     *Language,
 269   IN CONST CHAR8                     *SupportedLanguages,
 270   IN CONST EFI_UNICODE_STRING_TABLE  *UnicodeStringTable,
 271   OUT CHAR16                         **UnicodeString
 272   );
 273
 274 /**
 275   This function adds a Unicode string to UnicodeStringTable.
 276   If Language is a member of SupportedLanguages then UnicodeString is added to
 277   UnicodeStringTable.  New buffers are allocated for both Language and
 278   UnicodeString.  The contents of Language and UnicodeString are copied into
 279   these new buffers.  These buffers are automatically freed when
 280   FreeUnicodeStringTable() is called.
 281
 282   @param  Language                A pointer to the ISO 639-2 language code for the Unicode
 283                                   string to add.
 284   @param  SupportedLanguages      A pointer to the set of ISO 639-2 language codes
 285                                   that the Unicode string table supports.
 286                                   Language must be a member of this set.
 287   @param  UnicodeStringTable      A pointer to the table of Unicode strings.
 288   @param  UnicodeString           A pointer to the Unicode string to add.
 289
 290   @retval EFI_SUCCESS             The Unicode string that matches the language
 291                                   specified by Language was found in the table of
 292                                   Unicode strings UnicodeStringTable, and it was
 293                                   returned in UnicodeString.
 294   @retval EFI_INVALID_PARAMETER   Language is NULL.
 295   @retval EFI_INVALID_PARAMETER   UnicodeString is NULL.
 296   @retval EFI_INVALID_PARAMETER   UnicodeString is an empty string.
 297   @retval EFI_UNSUPPORTED         SupportedLanguages is NULL.
 298   @retval EFI_ALREADY_STARTED     A Unicode string with language Language is
 299                                   already present in UnicodeStringTable.
 300   @retval EFI_OUT_OF_RESOURCES    There is not enough memory to add another
 301                                   Unicode string to UnicodeStringTable.
 302   @retval EFI_UNSUPPORTED         The language specified by Language is not a
 303                                   member of SupportedLanguages.
 304
 305 **/
 306 EFI_STATUS
 307 EFIAPI
 308 AddUnicodeString (
 309   IN CONST CHAR8               *Language,
 310   IN CONST CHAR8               *SupportedLanguages,
 311   IN EFI_UNICODE_STRING_TABLE  **UnicodeStringTable,
 312   IN CONST CHAR16              *UnicodeString
 313   );
 314
 315 /**
 316   This function frees the table of Unicode strings in UnicodeStringTable.
 317   If UnicodeStringTable is NULL, then EFI_SUCCESS is returned.
 318   Otherwise, each language code, and each Unicode string in the Unicode string
 319   table are freed, and EFI_SUCCESS is returned.
 320
 321   @param  UnicodeStringTable  A pointer to the table of Unicode strings.
 322
 323   @retval EFI_SUCCESS         The Unicode string table was freed.
 324
 325 **/
 326 EFI_STATUS
 327 EFIAPI
 328 FreeUnicodeStringTable (
 329   IN EFI_UNICODE_STRING_TABLE  *UnicodeStringTable
 330   );
 331
 332 /**
 333   This function computes and returns the width of the Unicode character
 334   specified by UnicodeChar.
 335
 336   @param  UnicodeChar   A Unicode character.
 337
 338   @retval 0             The width if UnicodeChar could not be determined.
 339   @retval 1             UnicodeChar is a narrow glyph.
 340   @retval 2             UnicodeChar is a wide glyph.
 341
 342 **/
 343 UINTN
 344 EFIAPI
 345 GetGlyphWidth (
 346   IN CHAR16  UnicodeChar
 347   );
 348
 349 /**
 350   This function computes and returns the display length of
 351   the Null-terminated Unicode string specified by String.
 352   If String is NULL, then 0 is returned.
 353   If any of the widths of the Unicode characters in String
 354   can not be determined, then 0 is returned.
 355
 356   @param  String      A pointer to a Null-terminated Unicode string.
 357
 358   @return The display length of the Null-terminated Unicode string specified by String.
 359
 360 **/
 361 UINTN
 362 EFIAPI
 363 UnicodeStringDisplayLength (
 364   IN CONST CHAR16  *String
 365   );
 366
 367 //
 368 // Functions that abstract early Framework contamination of UEFI.
 369 //
 370 /**
 371   Signal a Ready to Boot Event.
 372
 373   Create a Ready to Boot Event. Signal it and close it. This causes other
 374   events of the same event group to be signaled in other modules.
 375
 376 **/
 377 VOID
 378 EFIAPI
 379 EfiSignalEventReadyToBoot (
 380   VOID
 381   );
 382
 383 /**
 384   Signal a Legacy Boot Event.
 385
 386   Create a legacy Boot Event. Signal it and close it. This causes other
 387   events of the same event group to be signaled in other modules.
 388
 389 **/
 390 VOID
 391 EFIAPI
 392 EfiSignalEventLegacyBoot (
 393   VOID
 394   );
 395
 396 /**
 397   Create a Legacy Boot Event.
 398
 399   Tiano extended the CreateEvent Type enum to add a legacy boot event type.
 400   This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was
 401   added and now it's possible to not voilate the UEFI specification by
 402   declaring a GUID for the legacy boot event class. This library supports
 403   the R8.5/EFI 1.10 form and R9/UEFI 2.0 form and allows common code to
 404   work both ways.
 405
 406   @param  LegacyBootEvent   Returns the EFI event returned from gBS->CreateEvent(Ex).
 407
 408   @retval EFI_SUCCESS       Event was created.
 409   @retval Other             Event was not created.
 410
 411 **/
 412 EFI_STATUS
 413 EFIAPI
 414 EfiCreateEventLegacyBoot (
 415   OUT EFI_EVENT  *LegacyBootEvent
 416   );
 417
 418 /**
 419   Create a Read to Boot Event.
 420
 421   Tiano extended the CreateEvent Type enum to add a ready to boot event type.
 422   This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was
 423   added and now it's possible to not voilate the UEFI specification and use
 424   the ready to boot event class defined in UEFI 2.0. This library supports
 425   the R8.5/EFI 1.10 form and R9/UEFI 2.0 form and allows common code to
 426   work both ways.
 427
 428   @param  LegacyBootEvent   Returns the EFI event returned from gBS->CreateEvent(Ex).
 429
 430   @retval EFI_SUCCESS       Event was created.
 431   @retval Other             Event was not created.
 432
 433 **/
 434 EFI_STATUS
 435 EFIAPI
 436 EfiCreateEventReadyToBoot (
 437   OUT EFI_EVENT  *ReadyToBootEvent
 438   );
 439
 440 /**
 441   Initialize a Firmware Volume (FV) Media Device Path node.
 442
 443   Tiano extended the EFI 1.10 device path nodes. Tiano does not own this enum
 444   so as we move to UEFI 2.0 support we must use a mechanism that conforms with
 445   the UEFI 2.0 specification to define the FV device path. An UEFI GUIDed
 446   device path is defined for PIWG extensions of device path. If the code
 447   is compiled to conform with the UEFI 2.0 specification use the new device path
 448   else use the old form for backwards compatability.
 449
 450   @param  FvDevicePathNode  Pointer to a FV device path node to initialize
 451   @param  NameGuid          FV file name to use in FvDevicePathNode
 452
 453 **/
 454 VOID
 455 EFIAPI
 456 EfiInitializeFwVolDevicepathNode (
 457   IN OUT MEDIA_FW_VOL_FILEPATH_DEVICE_PATH  *FvDevicePathNode,
 458   IN CONST EFI_GUID                         *NameGuid
 459   );
 460
 461 /**
 462   Check to see if the Firmware Volume (FV) Media Device Path is valid
 463
 464   Tiano extended the EFI 1.10 device path nodes. Tiano does not own this enum
 465   so as we move to UEFI 2.0 support we must use a mechanism that conforms with
 466   the UEFI 2.0 specification to define the FV device path. An UEFI GUIDed
 467   device path is defined for PIWG extensions of device path. If the code
 468   is compiled to conform with the UEFI 2.0 specification use the new device path
 469   else use the old form for backwards compatability. The return value to this
 470   function points to a location in FvDevicePathNode and it does not allocate
 471   new memory for the GUID pointer that is returned.
 472
 473   @param  FvDevicePathNode  Pointer to FV device path to check.
 474
 475   @retval NULL              FvDevicePathNode is not valid.
 476   @retval Other             FvDevicePathNode is valid and pointer to NameGuid was returned.
 477
 478 **/
 479 EFI_GUID *
 480 EFIAPI
 481 EfiGetNameGuidFromFwVolDevicePathNode (
 482   IN CONST MEDIA_FW_VOL_FILEPATH_DEVICE_PATH  *FvDevicePathNode
 483   );
 484
 485
 486 #endif