MdePkg/Include/Library/UefiLib.h

   1 /** @file
   2   Provides library functions for common UEFI operations. Only available to DXE
   3   and UEFI module types.
   4
   5   The UEFI Library provides functions and macros that simplify the development of
   6   UEFI Drivers and UEFI Applications.  These functions and macros help manage EFI
   7   events, build simple locks utilizing EFI Task Priority Levels (TPLs), install
   8   EFI Driver Model related protocols, manage Unicode string tables for UEFI Drivers,
   9   and print messages on the console output and standard error devices.
  10
  11 Copyright (c) 2006 - 2008, Intel Corporation
  12 All rights reserved. This program and the accompanying materials
  13 are licensed and made available under the terms and conditions of the BSD License
  14 which accompanies this distribution.  The full text of the license may be found at
  15 http://opensource.org/licenses/bsd-license.php
  16
  17 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  18 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  19
  20 **/
  21
  22 #ifndef __UEFI_LIB_H__
  23 #define __UEFI_LIB_H__
  24
  25 #include <Protocol/DriverBinding.h>
  26 #include <Protocol/DriverConfiguration.h>
  27 #include <Protocol/ComponentName.h>
  28 #include <Protocol/ComponentName2.h>
  29 #include <Protocol/DriverDiagnostics.h>
  30 #include <Protocol/DriverDiagnostics2.h>
  31
  32 #include <Library/BaseLib.h>
  33
  34 ///
  35 /// Unicode String Table
  36 ///
  37 typedef struct {
  38   CHAR8   *Language;
  39   CHAR16  *UnicodeString;
  40 } EFI_UNICODE_STRING_TABLE;
  41
  42 ///
  43 /// EFI Lock Status
  44 ///
  45 typedef enum {
  46   EfiLockUninitialized = 0,
  47   EfiLockReleased      = 1,
  48   EfiLockAcquired      = 2
  49 } EFI_LOCK_STATE;
  50
  51 ///
  52 /// EFI Lock
  53 ///
  54 typedef struct {
  55   EFI_TPL         Tpl;
  56   EFI_TPL         OwnerTpl;
  57   EFI_LOCK_STATE  Lock;
  58 } EFI_LOCK;
  59
  60
  61 /**
  62   Macro that returns the number of 100 ns units for a specified number of microseconds.
  63   Useful for managing EFI timer events.
  64
  65   @param  Microseconds           Number of microseonds.
  66
  67   @return The number of 100 ns units equivalent to the number of microseconds specified
  68           by Microseconds.
  69
  70 **/
  71 #define EFI_TIMER_PERIOD_MICROSECONDS(Microseconds) MultU64x32((UINT64)(Microseconds), 10)
  72
  73
  74 /**
  75   Macro that returns the number of 100 ns units for a specified number of milliseoconds.
  76   Useful for managing EFI timer events.
  77
  78   @param  Milliseconds           Number of milliseconds.
  79
  80   @return The number of 100 ns units equivalent to the number of milliseconds specified
  81           by Milliseconds.
  82
  83 **/
  84 #define EFI_TIMER_PERIOD_MILLISECONDS(Milliseconds) MultU64x32((UINT64)(Milliseconds), 10000)
  85
  86
  87 /**
  88   Macro that returns the number of 100 ns units for a specified number of seoconds.
  89   Useful for managing EFI timer events.
  90
  91   @param  Seconds                Number of seconds.
  92
  93   @return The number of 100 ns units equivalent to the number of seconds specified
  94           by Seconds.
  95
  96 **/
  97 #define EFI_TIMER_PERIOD_SECONDS(Seconds)           MultU64x32((UINT64)(Seconds), 10000000)
  98
  99
 100 /**
 101   This function searches the list of configuration tables stored in the EFI System
 102   Table for a table with a GUID that matches TableGuid.  If a match is found,
 103   then a pointer to the configuration table is returned in Table, and EFI_SUCCESS
 104   is returned.  If a matching GUID is not found, then EFI_NOT_FOUND is returned.
 105
 106   @param  TableGuid       Pointer to table's GUID type..
 107   @param  Table           Pointer to the table associated with TableGuid in the EFI System Table.
 108
 109   @retval EFI_SUCCESS     A configuration table matching TableGuid was found.
 110   @retval EFI_NOT_FOUND   A configuration table matching TableGuid could not be found.
 111
 112 **/
 113 EFI_STATUS
 114 EFIAPI
 115 EfiGetSystemConfigurationTable (
 116   IN  EFI_GUID  *TableGuid,
 117   OUT VOID      **Table
 118   );
 119
 120 /**
 121   This function causes the notification function to be executed for every protocol
 122   of type ProtocolGuid instance that exists in the system when this function is
 123   invoked.  In addition, every time a protocol of type ProtocolGuid instance is
 124   installed or reinstalled, the notification function is also executed.
 125
 126   @param  ProtocolGuid    Supplies GUID of the protocol upon whose installation the event is fired.
 127   @param  NotifyTpl       Supplies the task priority level of the event notifications.
 128   @param  NotifyFunction  Supplies the function to notify when the event is signaled.
 129   @param  NotifyContext   The context parameter to pass to NotifyFunction.
 130   @param  Registration    A pointer to a memory location to receive the registration value.
 131
 132   @return The notification event that was created.
 133
 134 **/
 135 EFI_EVENT
 136 EFIAPI
 137 EfiCreateProtocolNotifyEvent(
 138   IN  EFI_GUID          *ProtocolGuid,
 139   IN  EFI_TPL           NotifyTpl,
 140   IN  EFI_EVENT_NOTIFY  NotifyFunction,
 141   IN  VOID              *NotifyContext,  OPTIONAL
 142   OUT VOID              **Registration
 143   );
 144
 145 /**
 146   This function creates an event using NotifyTpl, NoifyFunction, and NotifyContext.
 147   This event is signaled with EfiNamedEventSignal().  This provide the ability for
 148   one or more listeners on the same event named by the GUID specified by Name.
 149
 150   @param  Name                  Supplies GUID name of the event.
 151   @param  NotifyTpl             Supplies the task priority level of the event notifications.
 152   @param  NotifyFunction        Supplies the function to notify when the event is signaled.
 153   @param  NotifyContext         The context parameter to pass to NotifyFunction.
 154   @param  Registration          A pointer to a memory location to receive the registration value.
 155
 156   @retval EFI_SUCCESS           A named event was created.
 157   @retval EFI_OUT_OF_RESOURCES  There are not enough resource to create the named event.
 158
 159 **/
 160 EFI_STATUS
 161 EFIAPI
 162 EfiNamedEventListen (
 163   IN CONST EFI_GUID    *Name,
 164   IN EFI_TPL           NotifyTpl,
 165   IN EFI_EVENT_NOTIFY  NotifyFunction,
 166   IN CONST VOID        *NotifyContext,  OPTIONAL
 167   OUT VOID             *Registration OPTIONAL
 168   );
 169
 170 /**
 171   This function signals the named event specified by Name.  The named event must
 172   have been created with EfiNamedEventListen().
 173
 174   @param  Name                  Supplies GUID name of the event.
 175
 176   @retval EFI_SUCCESS           A named event was signaled.
 177   @retval EFI_OUT_OF_RESOURCES  There are not enough resource to signal the named event.
 178
 179 **/
 180 EFI_STATUS
 181 EFIAPI
 182 EfiNamedEventSignal (
 183   IN CONST EFI_GUID  *Name
 184   );
 185
 186 /**
 187   Returns the current TPL.
 188
 189   This function returns the current TPL.  There is no EFI service to directly
 190   retrieve the current TPL. Instead, the RaiseTPL() function is used to raise
 191   the TPL to TPL_HIGH_LEVEL.  This will return the current TPL.  The TPL level
 192   can then immediately be restored back to the current TPL level with a call
 193   to RestoreTPL().
 194
 195   @return The current TPL.
 196
 197 **/
 198 EFI_TPL
 199 EFIAPI
 200 EfiGetCurrentTpl (
 201   VOID
 202   );
 203
 204 /**
 205   This function initializes a basic mutual exclusion lock to the released state
 206   and returns the lock.  Each lock provides mutual exclusion access at its task
 207   priority level.  Since there is no preemption or multiprocessor support in EFI,
 208   acquiring the lock only consists of raising to the locks TPL.
 209
 210   @param  Lock       A pointer to the lock data structure to initialize.
 211   @param  Priority   EFI TPL associated with the lock.
 212
 213   @return The lock.
 214
 215 **/
 216 EFI_LOCK *
 217 EFIAPI
 218 EfiInitializeLock (
 219   IN OUT EFI_LOCK  *Lock,
 220   IN EFI_TPL        Priority
 221   );
 222
 223 /**
 224   This macro initializes the contents of a basic mutual exclusion lock to the
 225   released state.  Each lock provides mutual exclusion access at its task
 226   priority level.  Since there is no preemption or multiprocessor support in EFI,
 227   acquiring the lock only consists of raising to the locks TPL.
 228
 229   @param  Priority  The task priority level of the lock.
 230
 231   @return The lock.
 232
 233 **/
 234 #define EFI_INITIALIZE_LOCK_VARIABLE(Priority) \
 235   {Priority, TPL_APPLICATION, EfiLockReleased }
 236
 237
 238 /**
 239
 240   Macro that calls DebugAssert() if an EFI_LOCK structure is not in the locked state.
 241
 242   If the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set,
 243   then this macro evaluates the EFI_LOCK structure specified by Lock.  If Lock
 244   is not in the locked state, then DebugAssert() is called passing in the source
 245   filename, source line number, and Lock.
 246
 247   If Lock is NULL, then ASSERT().
 248
 249   @param  LockParameter  A pointer to the lock to acquire.
 250
 251 **/
 252 #define ASSERT_LOCKED(LockParameter)                  \
 253   do {                                                \
 254     if (DebugAssertEnabled ()) {                      \
 255       ASSERT (LockParameter != NULL);                 \
 256       if ((LockParameter)->Lock != EfiLockAcquired) { \
 257         _ASSERT (LockParameter not locked);           \
 258       }                                               \
 259     }                                                 \
 260   } while (FALSE)
 261
 262
 263 /**
 264   This function raises the system's current task priority level to the task
 265   priority level of the mutual exclusion lock.  Then, it places the lock in the
 266   acquired state.
 267
 268   @param  Lock              A pointer to the lock to acquire.
 269
 270 **/
 271 VOID
 272 EFIAPI
 273 EfiAcquireLock (
 274   IN EFI_LOCK  *Lock
 275   );
 276
 277 /**
 278   This function raises the system's current task priority level to the task
 279   priority level of the mutual exclusion lock.  Then, it attempts to place the
 280   lock in the acquired state.
 281
 282   @param  Lock              A pointer to the lock to acquire.
 283
 284   @retval EFI_SUCCESS       The lock was acquired.
 285   @retval EFI_ACCESS_DENIED The lock could not be acquired because it is already owned.
 286
 287 **/
 288 EFI_STATUS
 289 EFIAPI
 290 EfiAcquireLockOrFail (
 291   IN EFI_LOCK  *Lock
 292   );
 293
 294 /**
 295   This function transitions a mutual exclusion lock from the acquired state to
 296   the released state, and restores the system's task priority level to its
 297   previous level.
 298
 299   @param  Lock  A pointer to the lock to release.
 300
 301 **/
 302 VOID
 303 EFIAPI
 304 EfiReleaseLock (
 305   IN EFI_LOCK  *Lock
 306   );
 307
 308 /**
 309   Tests whether a controller handle is being managed by a specific driver.
 310
 311   This function tests whether the driver specified by DriverBindingHandle is
 312   currently managing the controller specified by ControllerHandle.  This test
 313   is performed by evaluating if the the protocol specified by ProtocolGuid is
 314   present on ControllerHandle and is was opened by DriverBindingHandle with an
 315   attribute of EFI_OPEN_PROTOCOL_BY_DRIVER.
 316   If ProtocolGuid is NULL, then ASSERT().
 317
 318   @param  ControllerHandle     A handle for a controller to test.
 319   @param  DriverBindingHandle  Specifies the driver binding handle for the
 320                                driver.
 321   @param  ProtocolGuid         Specifies the protocol that the driver specified
 322                                by DriverBindingHandle opens in its Start()
 323                                function.
 324
 325   @retval EFI_SUCCESS          ControllerHandle is managed by the driver
 326                                specifed by DriverBindingHandle.
 327   @retval EFI_UNSUPPORTED      ControllerHandle is not managed by the driver
 328                                specifed by DriverBindingHandle.
 329
 330 **/
 331 EFI_STATUS
 332 EFIAPI
 333 EfiTestManagedDevice (
 334   IN CONST EFI_HANDLE       ControllerHandle,
 335   IN CONST EFI_HANDLE       DriverBindingHandle,
 336   IN CONST EFI_GUID         *ProtocolGuid
 337   );
 338
 339 /**
 340   Tests whether a child handle is a child device of the controller.
 341
 342   This function tests whether ChildHandle is one of the children of
 343   ControllerHandle.  This test is performed by checking to see if the protocol
 344   specified by ProtocolGuid is present on ControllerHandle and opened by
 345   ChildHandle with an attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
 346   If ProtocolGuid is NULL, then ASSERT().
 347
 348   @param  ControllerHandle     A handle for a (parent) controller to test.
 349   @param  ChildHandle          A child handle to test.
 350   @param  ProtocolGuid         Supplies the protocol that the child controller
 351                                opens on its parent controller.
 352
 353   @retval EFI_SUCCESS          ChildHandle is a child of the ControllerHandle.
 354   @retval EFI_UNSUPPORTED      ChildHandle is not a child of the
 355                                ControllerHandle.
 356
 357 **/
 358 EFI_STATUS
 359 EFIAPI
 360 EfiTestChildHandle (
 361   IN CONST EFI_HANDLE       ControllerHandle,
 362   IN CONST EFI_HANDLE       ChildHandle,
 363   IN CONST EFI_GUID         *ProtocolGuid
 364   );
 365
 366 /**
 367   This function looks up a Unicode string in UnicodeStringTable.  If Language is
 368   a member of SupportedLanguages and a Unicode string is found in UnicodeStringTable
 369   that matches the language code specified by Language, then it is returned in
 370   UnicodeString.
 371
 372   @param  Language                A pointer to the ISO 639-2 language code for the
 373                                   Unicode string to look up and return.
 374   @param  SupportedLanguages      A pointer to the set of ISO 639-2 language codes
 375                                   that the Unicode string table supports.  Language
 376                                   must be a member of this set.
 377   @param  UnicodeStringTable      A pointer to the table of Unicode strings.
 378   @param  UnicodeString           A pointer to the Unicode string from UnicodeStringTable
 379                                   that matches the language specified by Language.
 380
 381   @retval EFI_SUCCESS             The Unicode string that matches the language
 382                                   specified by Language was found
 383                                   in the table of Unicoide strings UnicodeStringTable,
 384                                   and it was returned in UnicodeString.
 385   @retval EFI_INVALID_PARAMETER   Language is NULL.
 386   @retval EFI_INVALID_PARAMETER   UnicodeString is NULL.
 387   @retval EFI_UNSUPPORTED         SupportedLanguages is NULL.
 388   @retval EFI_UNSUPPORTED         UnicodeStringTable is NULL.
 389   @retval EFI_UNSUPPORTED         The language specified by Language is not a
 390                                   member of SupportedLanguages.
 391   @retval EFI_UNSUPPORTED         The language specified by Language is not
 392                                   supported by UnicodeStringTable.
 393
 394 **/
 395 EFI_STATUS
 396 EFIAPI
 397 LookupUnicodeString (
 398   IN CONST CHAR8                     *Language,
 399   IN CONST CHAR8                     *SupportedLanguages,
 400   IN CONST EFI_UNICODE_STRING_TABLE  *UnicodeStringTable,
 401   OUT CHAR16                         **UnicodeString
 402   );
 403
 404 /**
 405   This function looks up a Unicode string in UnicodeStringTable.
 406   If Language is a member of SupportedLanguages and a Unicode
 407   string is found in UnicodeStringTable that matches the
 408   language code specified by Language, then it is returned in
 409   UnicodeString.
 410
 411   @param  Language                A pointer to the ISO 639-2 or
 412                                   RFC 3066 language code for the
 413                                   Unicode string to look up and
 414                                   return.
 415
 416   @param  SupportedLanguages      A pointer to the set of ISO
 417                                   639-2 or RFC 3066 language
 418                                   codes that the Unicode string
 419                                   table supports. Language must
 420                                   be a member of this set.
 421
 422   @param  UnicodeStringTable      A pointer to the table of
 423                                   Unicode strings.
 424
 425   @param  UnicodeString           A pointer to the Unicode
 426                                   string from UnicodeStringTable
 427                                   that matches the language
 428                                   specified by Language.
 429
 430   @param  Iso639Language          Specify the language code
 431                                   format supported. If true,
 432                                   then the format follow ISO
 433                                   639-2. If false, then it
 434                                   follows RFC3066.
 435
 436   @retval  EFI_SUCCESS            The Unicode string that
 437                                   matches the language specified
 438                                   by Language was found in the
 439                                   table of Unicoide strings
 440                                   UnicodeStringTable, and it was
 441                                   returned in UnicodeString.
 442
 443   @retval  EFI_INVALID_PARAMETER  Language is NULL.
 444
 445   @retval  EFI_INVALID_PARAMETER  UnicodeString is NULL.
 446
 447   @retval  EFI_UNSUPPORTED        SupportedLanguages is NULL.
 448
 449   @retval  EFI_UNSUPPORTED        UnicodeStringTable is NULL.
 450
 451   @retval  EFI_UNSUPPORTED        The language specified by
 452                                   Language is not a member
 453                                   ofSupportedLanguages.
 454
 455   @retval EFI_UNSUPPORTED         The language specified by
 456                                   Language is not supported by
 457                                   UnicodeStringTable.
 458
 459 **/
 460 EFI_STATUS
 461 EFIAPI
 462 LookupUnicodeString2 (
 463   IN CONST CHAR8                     *Language,
 464   IN CONST CHAR8                     *SupportedLanguages,
 465   IN CONST EFI_UNICODE_STRING_TABLE  *UnicodeStringTable,
 466   OUT CHAR16                         **UnicodeString,
 467   IN BOOLEAN                         Iso639Language
 468   );
 469
 470 /**
 471   This function adds a Unicode string to UnicodeStringTable.
 472   If Language is a member of SupportedLanguages then UnicodeString is added to
 473   UnicodeStringTable.  New buffers are allocated for both Language and
 474   UnicodeString.  The contents of Language and UnicodeString are copied into
 475   these new buffers.  These buffers are automatically freed when
 476   FreeUnicodeStringTable() is called.
 477
 478   @param  Language                A pointer to the ISO 639-2 language code for the Unicode
 479                                   string to add.
 480   @param  SupportedLanguages      A pointer to the set of ISO 639-2 language codes
 481                                   that the Unicode string table supports.
 482                                   Language must be a member of this set.
 483   @param  UnicodeStringTable      A pointer to the table of Unicode strings.
 484   @param  UnicodeString           A pointer to the Unicode string to add.
 485
 486   @retval EFI_SUCCESS             The Unicode string that matches the language
 487                                   specified by Language was found in the table of
 488                                   Unicode strings UnicodeStringTable, and it was
 489                                   returned in UnicodeString.
 490   @retval EFI_INVALID_PARAMETER   Language is NULL.
 491   @retval EFI_INVALID_PARAMETER   UnicodeString is NULL.
 492   @retval EFI_INVALID_PARAMETER   UnicodeString is an empty string.
 493   @retval EFI_UNSUPPORTED         SupportedLanguages is NULL.
 494   @retval EFI_ALREADY_STARTED     A Unicode string with language Language is
 495                                   already present in UnicodeStringTable.
 496   @retval EFI_OUT_OF_RESOURCES    There is not enough memory to add another
 497                                   Unicode string to UnicodeStringTable.
 498   @retval EFI_UNSUPPORTED         The language specified by Language is not a
 499                                   member of SupportedLanguages.
 500
 501 **/
 502 EFI_STATUS
 503 EFIAPI
 504 AddUnicodeString (
 505   IN CONST CHAR8               *Language,
 506   IN CONST CHAR8               *SupportedLanguages,
 507   IN EFI_UNICODE_STRING_TABLE  **UnicodeStringTable,
 508   IN CONST CHAR16              *UnicodeString
 509   );
 510
 511 /**
 512
 513   This function adds a Unicode string to UnicodeStringTable.
 514   If Language is a member of SupportedLanguages then
 515   UnicodeString is added to UnicodeStringTable.  New buffers are
 516   allocated for both Language and UnicodeString.  The contents
 517   of Language and UnicodeString are copied into these new
 518   buffers.  These buffers are automatically freed when
 519   FreeUnicodeStringTable() is called.
 520
 521   @param  Language                A pointer to the ISO 639-2 or
 522                                   RFC 3066 language code for the
 523                                   Unicode string to add.
 524
 525   @param  SupportedLanguages      A pointer to the set of ISO
 526                                   639-2 or RFC 3066 language
 527                                   codes that the Unicode string
 528                                   table supports. Language must
 529                                   be a member of this set.
 530
 531   @param  UnicodeStringTable      A pointer to the table of
 532                                   Unicode strings.
 533
 534   @param  UnicodeString           A pointer to the Unicode
 535                                   string to add.
 536
 537   @param  Iso639Language          Specify the language code
 538                                   format supported. If true,
 539                                   then the format follow ISO
 540                                   639-2. If false, then it
 541                                   follows RFC3066.
 542
 543   @retval EFI_SUCCESS             The Unicode string that
 544                                   matches the language specified
 545                                   by Language was found in the
 546                                   table of Unicode strings
 547                                   UnicodeStringTable, and it was
 548                                   returned in UnicodeString.
 549
 550   @retval EFI_INVALID_PARAMETER   Language is NULL.
 551
 552   @retval EFI_INVALID_PARAMETER   UnicodeString is NULL.
 553
 554   @retval EFI_INVALID_PARAMETER   UnicodeString is an empty string.
 555
 556   @retval EFI_UNSUPPORTED         SupportedLanguages is NULL.
 557
 558   @retval EFI_ALREADY_STARTED     A Unicode string with language
 559                                   Language is already present in
 560                                   UnicodeStringTable.
 561
 562   @retval EFI_OUT_OF_RESOURCES    There is not enough memory to
 563                                   add another Unicode string to
 564                                   UnicodeStringTable.
 565
 566   @retval EFI_UNSUPPORTED         The language specified by
 567                                   Language is not a member of
 568                                   SupportedLanguages.
 569
 570 **/
 571 EFI_STATUS
 572 EFIAPI
 573 AddUnicodeString2 (
 574   IN CONST CHAR8               *Language,
 575   IN CONST CHAR8               *SupportedLanguages,
 576   IN EFI_UNICODE_STRING_TABLE  **UnicodeStringTable,
 577   IN CONST CHAR16              *UnicodeString,
 578   IN BOOLEAN                   Iso639Language
 579   );
 580
 581 /**
 582   This function frees the table of Unicode strings in UnicodeStringTable.
 583   If UnicodeStringTable is NULL, then EFI_SUCCESS is returned.
 584   Otherwise, each language code, and each Unicode string in the Unicode string
 585   table are freed, and EFI_SUCCESS is returned.
 586
 587   @param  UnicodeStringTable  A pointer to the table of Unicode strings.
 588
 589   @retval EFI_SUCCESS         The Unicode string table was freed.
 590
 591 **/
 592 EFI_STATUS
 593 EFIAPI
 594 FreeUnicodeStringTable (
 595   IN EFI_UNICODE_STRING_TABLE  *UnicodeStringTable
 596   );
 597
 598 /**
 599   This function computes and returns the width of the Unicode character
 600   specified by UnicodeChar.
 601
 602   @param  UnicodeChar   A Unicode character.
 603
 604   @retval 0             The width if UnicodeChar could not be determined.
 605   @retval 1             UnicodeChar is a narrow glyph.
 606   @retval 2             UnicodeChar is a wide glyph.
 607
 608 **/
 609 UINTN
 610 EFIAPI
 611 GetGlyphWidth (
 612   IN CHAR16  UnicodeChar
 613   );
 614
 615 /**
 616   This function computes and returns the display length of
 617   the Null-terminated Unicode string specified by String.
 618   If String is NULL, then 0 is returned.
 619   If any of the widths of the Unicode characters in String
 620   can not be determined, then 0 is returned.
 621
 622   @param  String      A pointer to a Null-terminated Unicode string.
 623
 624   @return The display length of the Null-terminated Unicode string specified by String.
 625
 626 **/
 627 UINTN
 628 EFIAPI
 629 UnicodeStringDisplayLength (
 630   IN CONST CHAR16  *String
 631   );
 632
 633 //
 634 // Functions that abstract early Framework contamination of UEFI.
 635 //
 636 /**
 637   Signal a Ready to Boot Event.
 638
 639   Create a Ready to Boot Event. Signal it and close it. This causes other
 640   events of the same event group to be signaled in other modules.
 641
 642 **/
 643 VOID
 644 EFIAPI
 645 EfiSignalEventReadyToBoot (
 646   VOID
 647   );
 648
 649 /**
 650   Signal a Legacy Boot Event.
 651
 652   Create a legacy Boot Event. Signal it and close it. This causes other
 653   events of the same event group to be signaled in other modules.
 654
 655 **/
 656 VOID
 657 EFIAPI
 658 EfiSignalEventLegacyBoot (
 659   VOID
 660   );
 661
 662 /**
 663   Creates an EFI event in the Legacy Boot Event Group.  Prior to UEFI 2.0 this
 664   was done via a non blessed UEFI extensions and this library abstracts the
 665   implementation mechanism of this event from the caller.
 666
 667   This function abstracts the creation of the Legacy Boot Event.  The Framework
 668   moved from a proprietary to UEFI 2.0 based mechanism.  This library abstracts
 669   the caller from how this event is created to prevent to code form having to
 670   change with the version of the specification supported.
 671   If LegacyBootEvent is NULL, then ASSERT().
 672
 673   @param  LegacyBootEvent   Returns the EFI event returned from gBS->CreateEvent(Ex).
 674
 675   @retval EFI_SUCCESS       Event was created.
 676   @retval Other             Event was not created.
 677
 678 **/
 679 EFI_STATUS
 680 EFIAPI
 681 EfiCreateEventLegacyBoot (
 682   OUT EFI_EVENT  *LegacyBootEvent
 683   );
 684
 685 /**
 686   Create an EFI event in the Legacy Boot Event Group and allows
 687   the caller to specify a notification function.
 688
 689   This function abstracts the creation of the Legacy Boot Event.
 690   The Framework moved from a proprietary to UEFI 2.0 based mechanism.
 691   This library abstracts the caller from how this event is created to prevent
 692   to code form having to change with the version of the specification supported.
 693   If LegacyBootEvent is NULL, then ASSERT().
 694
 695   @param  NotifyTpl         The task priority level of the event.
 696   @param  NotifyFunction    The notification function to call when the event is signaled.
 697   @param  NotifyContext     The content to pass to NotifyFunction when the event is signaled.
 698   @param  LegacyBootEvent   Returns the EFI event returned from gBS->CreateEvent(Ex).
 699
 700   @retval EFI_SUCCESS       Event was created.
 701   @retval Other             Event was not created.
 702
 703 **/
 704 EFI_STATUS
 705 EFIAPI
 706 EfiCreateEventLegacyBootEx (
 707   IN  EFI_TPL           NotifyTpl,
 708   IN  EFI_EVENT_NOTIFY  NotifyFunction,  OPTIONAL
 709   IN  VOID              *NotifyContext,  OPTIONAL
 710   OUT EFI_EVENT         *LegacyBootEvent
 711   );
 712
 713 /**
 714   Create an EFI event in the Ready To Boot Event Group.  Prior to UEFI 2.0 this
 715   was done via a non-standard UEFI extension, and this library abstracts the
 716   implementation mechanism of this event from the caller.
 717
 718   This function abstracts the creation of the Ready to Boot Event.  The Framework
 719   moved from a proprietary to UEFI 2.0-based mechanism.  This library abstracts
 720   the caller from how this event is created to prevent the code form having to
 721   change with the version of the specification supported.
 722   If ReadyToBootEvent is NULL, then ASSERT().
 723
 724   @param  ReadyToBootEvent   Returns the EFI event returned from gBS->CreateEvent(Ex).
 725
 726   @retval EFI_SUCCESS       Event was created.
 727   @retval Other             Event was not created.
 728
 729 **/
 730 EFI_STATUS
 731 EFIAPI
 732 EfiCreateEventReadyToBoot (
 733   OUT EFI_EVENT  *ReadyToBootEvent
 734   );
 735
 736 /**
 737   Create an EFI event in the Ready To Boot Event Group and allows
 738   the caller to specify a notification function.
 739
 740   This function abstracts the creation of the Ready to Boot Event.
 741   The Framework moved from a proprietary to UEFI 2.0 based mechanism.
 742   This library abstracts the caller from how this event is created to prevent
 743   to code form having to change with the version of the specification supported.
 744   If ReadyToBootEvent is NULL, then ASSERT().
 745
 746   @param  NotifyTpl         The task priority level of the event.
 747   @param  NotifyFunction    The notification function to call when the event is signaled.
 748   @param  NotifyContext     The content to pass to NotifyFunction when the event is signaled.
 749   @param  ReadyToBootEvent  Returns the EFI event returned from gBS->CreateEvent(Ex).
 750
 751   @retval EFI_SUCCESS       Event was created.
 752   @retval Other             Event was not created.
 753
 754 **/
 755 EFI_STATUS
 756 EFIAPI
 757 EfiCreateEventReadyToBootEx (
 758   IN  EFI_TPL           NotifyTpl,
 759   IN  EFI_EVENT_NOTIFY  NotifyFunction,  OPTIONAL
 760   IN  VOID              *NotifyContext,  OPTIONAL
 761   OUT EFI_EVENT         *ReadyToBootEvent
 762   );
 763
 764 /**
 765   Initialize a Firmware Volume (FV) Media Device Path node.
 766
 767   The Framework FwVol Device Path changed to conform to the UEFI 2.0 specification.
 768   This library function abstracts initializing a device path node.
 769
 770   Initialize the MEDIA_FW_VOL_FILEPATH_DEVICE_PATH data structure.  This device
 771   path changed in the DXE CIS version 0.92 in a non back ward compatible way to
 772   not conflict with the UEFI 2.0 specification.  This function abstracts the
 773   differences from the caller.
 774
 775   If FvDevicePathNode is NULL, then ASSERT().
 776   If NameGuid is NULL, then ASSERT().
 777
 778   @param  FvDevicePathNode  Pointer to a FV device path node to initialize
 779   @param  NameGuid          FV file name to use in FvDevicePathNode
 780
 781 **/
 782 VOID
 783 EFIAPI
 784 EfiInitializeFwVolDevicepathNode (
 785   IN OUT MEDIA_FW_VOL_FILEPATH_DEVICE_PATH  *FvDevicePathNode,
 786   IN CONST EFI_GUID                         *NameGuid
 787   );
 788
 789 /**
 790   Check to see if the Firmware Volume (FV) Media Device Path is valid
 791
 792   The Framework FwVol Device Path changed to conform to the UEFI 2.0 specification.
 793   This library function abstracts validating a device path node.
 794
 795   Check the MEDIA_FW_VOL_FILEPATH_DEVICE_PATH data structure to see if it's valid.
 796   If it is valid, then return the GUID file name from the device path node.  Otherwise,
 797   return NULL.  This device path changed in the DXE CIS version 0.92 in a non back ward
 798   compatible way to not conflict with the UEFI 2.0 specification.  This function abstracts
 799   the differences from the caller.
 800   If FvDevicePathNode is NULL, then ASSERT().
 801
 802   @param  FvDevicePathNode  Pointer to FV device path to check.
 803
 804   @retval NULL              FvDevicePathNode is not valid.
 805   @retval Other             FvDevicePathNode is valid and pointer to NameGuid was returned.
 806
 807 **/
 808 EFI_GUID *
 809 EFIAPI
 810 EfiGetNameGuidFromFwVolDevicePathNode (
 811   IN CONST MEDIA_FW_VOL_FILEPATH_DEVICE_PATH  *FvDevicePathNode
 812   );
 813
 814 /**
 815   Prints a formatted Unicode string to the console output device specified by
 816   ConOut defined in the EFI_SYSTEM_TABLE.
 817
 818   This function prints a formatted Unicode string to the console output device
 819   specified by ConOut in EFI_SYSTEM_TABLE and returns the number of Unicode
 820   characters that printed to ConOut.  If the length of the formatted Unicode
 821   string is greater than PcdUefiLibMaxPrintBufferSize, then only the first
 822   PcdUefiLibMaxPrintBufferSize characters are sent to ConOut.
 823
 824   @param Format   Null-terminated Unicode format string.
 825   @param ...      VARARG list consumed to process Format.
 826   If Format is NULL, then ASSERT().
 827   If Format is not aligned on a 16-bit boundary, then ASSERT().
 828
 829   @return Number of Unicode characters printed to ConOut.
 830
 831 **/
 832 UINTN
 833 EFIAPI
 834 Print (
 835   IN CONST CHAR16  *Format,
 836   ...
 837   );
 838
 839 /**
 840   Prints a formatted Unicode string to the console output device specified by
 841   StdErr defined in the EFI_SYSTEM_TABLE.
 842
 843   This function prints a formatted Unicode string to the console output device
 844   specified by StdErr in EFI_SYSTEM_TABLE and returns the number of Unicode
 845   characters that printed to StdErr.  If the length of the formatted Unicode
 846   string is greater than PcdUefiLibMaxPrintBufferSize, then only the first
 847   PcdUefiLibMaxPrintBufferSize characters are sent to StdErr.
 848
 849   @param Format   Null-terminated Unicode format string.
 850   @param ...      VARARG list consumed to process Format.
 851   If Format is NULL, then ASSERT().
 852   If Format is not aligned on a 16-bit boundary, then ASSERT().
 853
 854   @return Number of Unicode characters printed to StdErr.
 855
 856 **/
 857 UINTN
 858 EFIAPI
 859 ErrorPrint (
 860   IN CONST CHAR16  *Format,
 861   ...
 862   );
 863
 864 /**
 865   Prints a formatted ASCII string to the console output device specified by
 866   ConOut defined in the EFI_SYSTEM_TABLE.
 867
 868   This function prints a formatted ASCII string to the console output device
 869   specified by ConOut in EFI_SYSTEM_TABLE and returns the number of ASCII
 870   characters that printed to ConOut.  If the length of the formatted ASCII
 871   string is greater than PcdUefiLibMaxPrintBufferSize, then only the first
 872   PcdUefiLibMaxPrintBufferSize characters are sent to ConOut.
 873
 874   @param Format   Null-terminated ASCII format string.
 875   @param ...      VARARG list consumed to process Format.
 876   If Format is NULL, then ASSERT().
 877   If Format is not aligned on a 16-bit boundary, then ASSERT().
 878
 879   @return Number of ASCII characters printed to ConOut.
 880
 881 **/
 882 UINTN
 883 EFIAPI
 884 AsciiPrint (
 885   IN CONST CHAR8  *Format,
 886   ...
 887   );
 888
 889 /**
 890   Prints a formatted ASCII string to the console output device specified by
 891   StdErr defined in the EFI_SYSTEM_TABLE.
 892
 893   This function prints a formatted ASCII string to the console output device
 894   specified by StdErr in EFI_SYSTEM_TABLE and returns the number of ASCII
 895   characters that printed to StdErr.  If the length of the formatted ASCII
 896   string is greater than PcdUefiLibMaxPrintBufferSize, then only the first
 897   PcdUefiLibMaxPrintBufferSize characters are sent to StdErr.
 898
 899   @param Format   Null-terminated ASCII format string.
 900   @param ...      VARARG list consumed to process Format.
 901   If Format is NULL, then ASSERT().
 902   If Format is not aligned on a 16-bit boundary, then ASSERT().
 903
 904   @return Number of ASCII characters printed to ConErr.
 905
 906 **/
 907 UINTN
 908 EFIAPI
 909 AsciiErrorPrint (
 910   IN CONST CHAR8  *Format,
 911   ...
 912   );
 913
 914 /**
 915   Initializes a driver by installing the Driver Binding Protocol onto the driver's
 916   DriverBindingHandle.  This is typically the same as the driver's ImageHandle, but
 917   it can be different if the driver produces multiple DriverBinding Protocols.
 918   If the Driver Binding Protocol interface is NULL, then ASSERT ().
 919   If the installation fails, then ASSERT ().
 920
 921   @param  ImageHandle                 The image handle of the driver.
 922   @param  SystemTable                 The EFI System Table that was passed to the driver's entry point.
 923   @param  DriverBinding               A Driver Binding Protocol instance that this driver is producing.
 924   @param  DriverBindingHandle         The handle that DriverBinding is to be installed onto.  If this
 925                                       parameter is NULL, then a new handle is created.
 926
 927   @retval EFI_SUCCESS                 The protocol installation is completed successfully.
 928   @retval Others                      Status from gBS->InstallMultipleProtocolInterfaces().
 929
 930 **/
 931 EFI_STATUS
 932 EFIAPI
 933 EfiLibInstallDriverBinding (
 934   IN CONST EFI_HANDLE             ImageHandle,
 935   IN CONST EFI_SYSTEM_TABLE       *SystemTable,
 936   IN EFI_DRIVER_BINDING_PROTOCOL  *DriverBinding,
 937   IN EFI_HANDLE                   DriverBindingHandle
 938   );
 939
 940
 941 /**
 942   Initializes a driver by installing the Driver Binding Protocol together with the optional Component Name,
 943   Driver Configure and Driver Diagnostic Protocols onto the driver's DriverBindingHandle.  This is
 944   typically the same as the driver's ImageHandle, but it can be different if the driver produces multiple
 945   DriverBinding Protocols.
 946   If the Driver Binding Protocol interface is NULL, then ASSERT ().
 947   If the installation fails, then ASSERT ().
 948
 949   @param  ImageHandle                 The image handle of the driver.
 950   @param  SystemTable                 The EFI System Table that was passed to the driver's entry point.
 951   @param  DriverBinding               A Driver Binding Protocol instance that this driver is producing.
 952   @param  DriverBindingHandle         The handle that DriverBinding is to be installed onto.  If this
 953                                       parameter is NULL, then a new handle is created.
 954   @param  ComponentName               A Component Name Protocol instance that this driver is producing.
 955   @param  DriverConfiguration         A Driver Configuration Protocol instance that this driver is producing.
 956   @param  DriverDiagnostics           A Driver Diagnostics Protocol instance that this driver is producing.
 957
 958   @retval EFI_SUCCESS                 The protocol installation is completed successfully.
 959   @retval Others                      Status from gBS->InstallMultipleProtocolInterfaces().
 960
 961 **/
 962 EFI_STATUS
 963 EFIAPI
 964 EfiLibInstallAllDriverProtocols (
 965   IN CONST EFI_HANDLE                         ImageHandle,
 966   IN CONST EFI_SYSTEM_TABLE                   *SystemTable,
 967   IN EFI_DRIVER_BINDING_PROTOCOL              *DriverBinding,
 968   IN EFI_HANDLE                               DriverBindingHandle,
 969   IN CONST EFI_COMPONENT_NAME_PROTOCOL        *ComponentName,       OPTIONAL
 970   IN CONST EFI_DRIVER_CONFIGURATION_PROTOCOL  *DriverConfiguration, OPTIONAL
 971   IN CONST EFI_DRIVER_DIAGNOSTICS_PROTOCOL    *DriverDiagnostics    OPTIONAL
 972   );
 973
 974
 975
 976 /**
 977   Initializes a driver by installing the Driver Binding Protocol together with the optional Component Name,
 978   Component Name 2 onto the driver's DriverBindingHandle.  This is typically the same as the driver's
 979   ImageHandle, but it can be different if the driver produces multiple DriverBinding Protocols.
 980   If the Driver Binding Protocol interface is NULL, then ASSERT ().
 981   If the installation fails, then ASSERT ().
 982
 983   @param  ImageHandle                 The image handle of the driver.
 984   @param  SystemTable                 The EFI System Table that was passed to the driver's entry point.
 985   @param  DriverBinding               A Driver Binding Protocol instance that this driver is producing.
 986   @param  DriverBindingHandle         The handle that DriverBinding is to be installed onto.  If this
 987                                       parameter is NULL, then a new handle is created.
 988   @param  ComponentName               A Component Name Protocol instance that this driver is producing.
 989   @param  ComponentName2              A Component Name 2 Protocol instance that this driver is producing.
 990
 991   @retval EFI_SUCCESS                 The protocol installation is completed successfully.
 992   @retval Others                      Status from gBS->InstallMultipleProtocolInterfaces().
 993
 994 **/
 995 EFI_STATUS
 996 EFIAPI
 997 EfiLibInstallDriverBindingComponentName2 (
 998   IN CONST EFI_HANDLE                         ImageHandle,
 999   IN CONST EFI_SYSTEM_TABLE                   *SystemTable,
1000   IN EFI_DRIVER_BINDING_PROTOCOL              *DriverBinding,
1001   IN EFI_HANDLE                               DriverBindingHandle,
1002   IN CONST EFI_COMPONENT_NAME_PROTOCOL        *ComponentName,       OPTIONAL
1003   IN CONST EFI_COMPONENT_NAME2_PROTOCOL       *ComponentName2       OPTIONAL
1004   );
1005
1006
1007 /**
1008   Intialize a driver by installing the Driver Binding Protocol together with the optional Component Name,
1009   Component Name 2, Driver Configure, Driver Diagnostic and Driver Diagnostic 2 Protocols onto the driver's
1010   DriverBindingHandle.  This is typically the same as the driver's ImageHandle, but it can be different if
1011   the driver produces multiple DriverBinding Protocols.
1012   If the Drvier Binding Protocol interface is NULL, then ASSERT ().
1013   If the installation fails, then ASSERT ().
1014
1015   @param  ImageHandle                 The image handle of the driver.
1016   @param  SystemTable                 The EFI System Table that was passed to the driver's entry point.
1017   @param  DriverBinding               A Driver Binding Protocol instance that this driver is producing.
1018   @param  DriverBindingHandle         The handle that DriverBinding is to be installe onto.  If this
1019                                       parameter is NULL, then a new handle is created.
1020   @param  ComponentName               A Component Name Protocol instance that this driver is producing.
1021   @param  ComponentName2              A Component Name 2 Protocol instance that this driver is producing.
1022   @param  DriverConfiguration         A Driver Configuration Protocol instance that this driver is producing.
1023   @param  DriverConfiguration2        A Driver Configuration Protocol 2 instance that this driver is producing.
1024   @param  DriverDiagnostics           A Driver Diagnostics Protocol instance that this driver is producing.
1025   @param  DriverDiagnostics2          A Driver Diagnostics Protocol 2 instance that this driver is producing.
1026
1027   @retval EFI_SUCCESS                 The protocol installation is completed successfully.
1028   @retval Others                      Status from gBS->InstallMultipleProtocolInterfaces().
1029
1030 **/
1031 EFI_STATUS
1032 EFIAPI
1033 EfiLibInstallAllDriverProtocols2 (
1034   IN CONST EFI_HANDLE                         ImageHandle,
1035   IN CONST EFI_SYSTEM_TABLE                   *SystemTable,
1036   IN EFI_DRIVER_BINDING_PROTOCOL              *DriverBinding,
1037   IN EFI_HANDLE                               DriverBindingHandle,
1038   IN CONST EFI_COMPONENT_NAME_PROTOCOL        *ComponentName,        OPTIONAL
1039   IN CONST EFI_COMPONENT_NAME2_PROTOCOL       *ComponentName2,       OPTIONAL
1040   IN CONST EFI_DRIVER_CONFIGURATION_PROTOCOL  *DriverConfiguration,  OPTIONAL
1041   IN CONST EFI_DRIVER_CONFIGURATION_PROTOCOL  *DriverConfiguration2, OPTIONAL
1042   IN CONST EFI_DRIVER_DIAGNOSTICS_PROTOCOL    *DriverDiagnostics,    OPTIONAL
1043   IN CONST EFI_DRIVER_DIAGNOSTICS2_PROTOCOL   *DriverDiagnostics2    OPTIONAL
1044   );
1045
1046 /**
1047   Determine what is the current language setting. The space reserved for Lang
1048   must be at least RFC_3066_ENTRY_SIZE bytes;
1049
1050   If Lang is NULL, then ASSERT.
1051
1052   @param  Lang                   Pointer of system language. Lang will always be filled with
1053                                          a valid RFC 3066 language string. If "PlatformLang" is not
1054                                          set in the system, the default language specifed by PcdUefiVariableDefaultPlatformLang
1055                                          is returned.
1056
1057   @return  EFI_SUCCESS     If the EFI Variable with "PlatformLang" is set and return in Lang.
1058   @return  EFI_NOT_FOUND If the EFI Variable with "PlatformLang" is not set, but a valid default language is return in Lang.
1059
1060 **/
1061 EFI_STATUS
1062 EFIAPI
1063 GetCurrentLanguage (
1064   OUT     CHAR8               *Lang
1065   );
1066
1067
1068 #endif