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   Note that a reserved macro named MDEPKG_NDEBUG is introduced for the intention
  12   of size reduction when compiler optimization is disabled. If MDEPKG_NDEBUG is
  13   defined, then debug and assert related macros wrapped by it are the NULL implementations.
  14
  15 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
  16 This program and the accompanying materials are licensed and made available under
  17 the terms and conditions of the BSD License that accompanies this distribution.
  18 The full text of the license may be found at
  19 http://opensource.org/licenses/bsd-license.php.
  20
  21 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  22 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  23
  24 **/
  25
  26 #ifndef __UEFI_LIB_H__
  27 #define __UEFI_LIB_H__
  28
  29 #include <Protocol/DriverBinding.h>
  30 #include <Protocol/DriverConfiguration.h>
  31 #include <Protocol/ComponentName.h>
  32 #include <Protocol/ComponentName2.h>
  33 #include <Protocol/DriverDiagnostics.h>
  34 #include <Protocol/DriverDiagnostics2.h>
  35 #include <Protocol/GraphicsOutput.h>
  36
  37 #include <Library/BaseLib.h>
  38
  39 ///
  40 /// Unicode String Table
  41 ///
  42 typedef struct {
  43   CHAR8   *Language;
  44   CHAR16  *UnicodeString;
  45 } EFI_UNICODE_STRING_TABLE;
  46
  47 ///
  48 /// EFI Lock Status
  49 ///
  50 typedef enum {
  51   EfiLockUninitialized = 0,
  52   EfiLockReleased      = 1,
  53   EfiLockAcquired      = 2
  54 } EFI_LOCK_STATE;
  55
  56 ///
  57 /// EFI Lock
  58 ///
  59 typedef struct {
  60   EFI_TPL         Tpl;
  61   EFI_TPL         OwnerTpl;
  62   EFI_LOCK_STATE  Lock;
  63 } EFI_LOCK;
  64
  65 /**
  66   Macro that returns the number of 100 ns units for a specified number of microseconds.
  67   This is useful for managing EFI timer events.
  68
  69   @param  Microseconds           The number of microseconds.
  70
  71   @return The number of 100 ns units equivalent to the number of microseconds specified
  72           by Microseconds.
  73
  74 **/
  75 #define EFI_TIMER_PERIOD_MICROSECONDS(Microseconds) MultU64x32((UINT64)(Microseconds), 10)
  76
  77 /**
  78   Macro that returns the number of 100 ns units for a specified number of milliseconds.
  79   This is useful for managing EFI timer events.
  80
  81   @param  Milliseconds           The number of milliseconds.
  82
  83   @return The number of 100 ns units equivalent to the number of milliseconds specified
  84           by Milliseconds.
  85
  86 **/
  87 #define EFI_TIMER_PERIOD_MILLISECONDS(Milliseconds) MultU64x32((UINT64)(Milliseconds), 10000)
  88
  89 /**
  90   Macro that returns the number of 100 ns units for a specified number of seconds.
  91   This is useful for managing EFI timer events.
  92
  93   @param  Seconds                The number of seconds.
  94
  95   @return The number of 100 ns units equivalent to the number of seconds specified
  96           by Seconds.
  97
  98 **/
  99 #define EFI_TIMER_PERIOD_SECONDS(Seconds)           MultU64x32((UINT64)(Seconds), 10000000)
 100
 101 /**
 102   Macro that returns the a pointer to the next EFI_MEMORY_DESCRIPTOR in an array
 103   returned from GetMemoryMap().
 104
 105   @param  MemoryDescriptor  A pointer to an EFI_MEMORY_DESCRIPTOR.
 106
 107   @param  Size              The size, in bytes, of the current EFI_MEMORY_DESCRIPTOR.
 108
 109   @return A pointer to the next EFI_MEMORY_DESCRIPTOR.
 110
 111 **/
 112 #define NEXT_MEMORY_DESCRIPTOR(MemoryDescriptor, Size) \
 113   ((EFI_MEMORY_DESCRIPTOR *)((UINT8 *)(MemoryDescriptor) + (Size)))
 114
 115 /**
 116   Retrieves a pointer to the system configuration table from the EFI System Table
 117   based on a specified GUID.
 118
 119   This function searches the list of configuration tables stored in the EFI System Table
 120   for a table with a GUID that matches TableGuid. If a match is found, then a pointer to
 121   the configuration table is returned in Table, and EFI_SUCCESS is returned. If a matching GUID
 122   is not found, then EFI_NOT_FOUND is returned.
 123   If TableGuid is NULL, then ASSERT().
 124   If Table is NULL, then ASSERT().
 125
 126   @param  TableGuid       The pointer to table's GUID type..
 127   @param  Table           The pointer to the table associated with TableGuid in the EFI System Table.
 128
 129   @retval EFI_SUCCESS     A configuration table matching TableGuid was found.
 130   @retval EFI_NOT_FOUND   A configuration table matching TableGuid could not be found.
 131
 132 **/
 133 EFI_STATUS
 134 EFIAPI
 135 EfiGetSystemConfigurationTable (
 136   IN  EFI_GUID  *TableGuid,
 137   OUT VOID      **Table
 138   );
 139
 140 /**
 141   Creates and returns a notification event and registers that event with all the protocol
 142   instances specified by ProtocolGuid.
 143
 144   This function causes the notification function to be executed for every protocol of type
 145   ProtocolGuid instance that exists in the system when this function is invoked. If there are
 146   no instances of ProtocolGuid in the handle database at the time this function is invoked,
 147   then the notification function is still executed one time. In addition, every time a protocol
 148   of type ProtocolGuid instance is installed or reinstalled, the notification function is also
 149   executed. This function returns the notification event that was created.
 150   If ProtocolGuid is NULL, then ASSERT().
 151   If NotifyTpl is not a legal TPL value, then ASSERT().
 152   If NotifyFunction is NULL, then ASSERT().
 153   If Registration is NULL, then ASSERT().
 154
 155
 156   @param  ProtocolGuid    Supplies GUID of the protocol upon whose installation the event is fired.
 157   @param  NotifyTpl       Supplies the task priority level of the event notifications.
 158   @param  NotifyFunction  Supplies the function to notify when the event is signaled.
 159   @param  NotifyContext   The context parameter to pass to NotifyFunction.
 160   @param  Registration    A pointer to a memory location to receive the registration value.
 161                           This value is passed to LocateHandle() to obtain new handles that
 162                           have been added that support the ProtocolGuid-specified protocol.
 163
 164   @return The notification event that was created.
 165
 166 **/
 167 EFI_EVENT
 168 EFIAPI
 169 EfiCreateProtocolNotifyEvent(
 170   IN  EFI_GUID          *ProtocolGuid,
 171   IN  EFI_TPL           NotifyTpl,
 172   IN  EFI_EVENT_NOTIFY  NotifyFunction,
 173   IN  VOID              *NotifyContext,  OPTIONAL
 174   OUT VOID              **Registration
 175   );
 176
 177 /**
 178   Creates a named event that can be signaled with EfiNamedEventSignal().
 179
 180   This function creates an event using NotifyTpl, NoifyFunction, and NotifyContext.
 181   This event is signaled with EfiNamedEventSignal(). This provides the ability for one or more
 182   listeners on the same event named by the GUID specified by Name.
 183   If Name is NULL, then ASSERT().
 184   If NotifyTpl is not a legal TPL value, then ASSERT().
 185   If NotifyFunction is NULL, then ASSERT().
 186
 187   @param  Name                  Supplies GUID name of the event.
 188   @param  NotifyTpl             Supplies the task priority level of the event notifications.
 189   @param  NotifyFunction        Supplies the function to notify when the event is signaled.
 190   @param  NotifyContext         The context parameter to pass to NotifyFunction.
 191   @param  Registration          A pointer to a memory location to receive the registration value.
 192
 193   @retval EFI_SUCCESS           A named event was created.
 194   @retval EFI_OUT_OF_RESOURCES  There are not enough resources to create the named event.
 195
 196 **/
 197 EFI_STATUS
 198 EFIAPI
 199 EfiNamedEventListen (
 200   IN CONST EFI_GUID    *Name,
 201   IN EFI_TPL           NotifyTpl,
 202   IN EFI_EVENT_NOTIFY  NotifyFunction,
 203   IN CONST VOID        *NotifyContext,  OPTIONAL
 204   OUT VOID             *Registration OPTIONAL
 205   );
 206
 207 /**
 208   Signals a named event created with EfiNamedEventListen().
 209
 210   This function signals the named event specified by Name. The named event must have been
 211   created with EfiNamedEventListen().
 212   If Name is NULL, then ASSERT().
 213
 214   @param  Name                  Supplies the GUID name of the event.
 215
 216   @retval EFI_SUCCESS           A named event was signaled.
 217   @retval EFI_OUT_OF_RESOURCES  There are not enough resources to signal the named event.
 218
 219 **/
 220 EFI_STATUS
 221 EFIAPI
 222 EfiNamedEventSignal (
 223   IN CONST EFI_GUID  *Name
 224   );
 225
 226 /**
 227   Signals an event group by placing a new event in the group temporarily and
 228   signaling it.
 229
 230   @param[in] EventGroup          Supplies the unique identifier of the event
 231                                  group to signal.
 232
 233   @retval EFI_SUCCESS            The event group was signaled successfully.
 234   @retval EFI_INVALID_PARAMETER  EventGroup is NULL.
 235   @return                        Error codes that report problems about event
 236                                  creation or signaling.
 237 **/
 238 EFI_STATUS
 239 EFIAPI
 240 EfiEventGroupSignal (
 241   IN CONST EFI_GUID *EventGroup
 242   );
 243
 244 /**
 245   An empty function that can be used as NotifyFunction parameter of
 246   CreateEvent() or CreateEventEx().
 247
 248   @param Event              Event whose notification function is being invoked.
 249   @param Context            The pointer to the notification function's context,
 250                             which is implementation-dependent.
 251
 252 **/
 253 VOID
 254 EFIAPI
 255 EfiEventEmptyFunction (
 256   IN EFI_EVENT              Event,
 257   IN VOID                   *Context
 258   );
 259
 260 /**
 261   Returns the current TPL.
 262
 263   This function returns the current TPL.  There is no EFI service to directly
 264   retrieve the current TPL. Instead, the RaiseTPL() function is used to raise
 265   the TPL to TPL_HIGH_LEVEL.  This will return the current TPL.  The TPL level
 266   can then immediately be restored back to the current TPL level with a call
 267   to RestoreTPL().
 268
 269   @return The current TPL.
 270
 271 **/
 272 EFI_TPL
 273 EFIAPI
 274 EfiGetCurrentTpl (
 275   VOID
 276   );
 277
 278 /**
 279   Initializes a basic mutual exclusion lock.
 280
 281   This function initializes a basic mutual exclusion lock to the released state
 282   and returns the lock.  Each lock provides mutual exclusion access at its task
 283   priority level.  Since there is no preemption or multiprocessor support in EFI,
 284   acquiring the lock only consists of raising to the locks TPL.
 285   If Lock is NULL, then ASSERT().
 286   If Priority is not a valid TPL value, then ASSERT().
 287
 288   @param  Lock       A pointer to the lock data structure to initialize.
 289   @param  Priority   The EFI TPL associated with the lock.
 290
 291   @return The lock.
 292
 293 **/
 294 EFI_LOCK *
 295 EFIAPI
 296 EfiInitializeLock (
 297   IN OUT EFI_LOCK  *Lock,
 298   IN EFI_TPL        Priority
 299   );
 300
 301 /**
 302   Initializes a basic mutual exclusion lock.
 303
 304   This macro initializes the contents of a basic mutual exclusion lock to the
 305   released state.  Each lock provides mutual exclusion access at its task
 306   priority level.  Since there is no preemption or multiprocessor support in EFI,
 307   acquiring the lock only consists of raising to the locks TPL.
 308
 309   @param  Priority  The task priority level of the lock.
 310
 311   @return The lock.
 312
 313 **/
 314 #define EFI_INITIALIZE_LOCK_VARIABLE(Priority) \
 315   {Priority, TPL_APPLICATION, EfiLockReleased }
 316
 317
 318 /**
 319   Macro that calls DebugAssert() if an EFI_LOCK structure is not in the locked state.
 320
 321   If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED
 322   bit of PcdDebugProperyMask is set, then this macro evaluates the EFI_LOCK
 323   structure specified by Lock.  If Lock is not in the locked state, then
 324   DebugAssert() is called passing in the source filename, source line number,
 325   and Lock.
 326
 327   If Lock is NULL, then ASSERT().
 328
 329   @param  LockParameter  A pointer to the lock to acquire.
 330
 331 **/
 332 #if !defined(MDEPKG_NDEBUG)
 333   #define ASSERT_LOCKED(LockParameter)                  \
 334     do {                                                \
 335       if (DebugAssertEnabled ()) {                      \
 336         ASSERT (LockParameter != NULL);                 \
 337         if ((LockParameter)->Lock != EfiLockAcquired) { \
 338           _ASSERT (LockParameter not locked);           \
 339         }                                               \
 340       }                                                 \
 341     } while (FALSE)
 342 #else
 343   #define ASSERT_LOCKED(LockParameter)
 344 #endif
 345
 346
 347 /**
 348   Acquires ownership of a lock.
 349
 350   This function raises the system's current task priority level to the task
 351   priority level of the mutual exclusion lock.  Then, it places the lock in the
 352   acquired state.
 353   If Lock is NULL, then ASSERT().
 354   If Lock is not initialized, then ASSERT().
 355   If Lock is already in the acquired state, then ASSERT().
 356
 357   @param  Lock              A pointer to the lock to acquire.
 358
 359 **/
 360 VOID
 361 EFIAPI
 362 EfiAcquireLock (
 363   IN EFI_LOCK  *Lock
 364   );
 365
 366 /**
 367   Acquires ownership of a lock.
 368
 369   This function raises the system's current task priority level to the task priority
 370   level of the mutual exclusion lock.  Then, it attempts to place the lock in the acquired state.
 371   If the lock is already in the acquired state, then EFI_ACCESS_DENIED is returned.
 372   Otherwise, EFI_SUCCESS is returned.
 373   If Lock is NULL, then ASSERT().
 374   If Lock is not initialized, then ASSERT().
 375
 376   @param  Lock              A pointer to the lock to acquire.
 377
 378   @retval EFI_SUCCESS       The lock was acquired.
 379   @retval EFI_ACCESS_DENIED The lock could not be acquired because it is already owned.
 380
 381 **/
 382 EFI_STATUS
 383 EFIAPI
 384 EfiAcquireLockOrFail (
 385   IN EFI_LOCK  *Lock
 386   );
 387
 388 /**
 389   Releases ownership of a lock.
 390
 391   This function transitions a mutual exclusion lock from the acquired state to
 392   the released state, and restores the system's task priority level to its
 393   previous level.
 394   If Lock is NULL, then ASSERT().
 395   If Lock is not initialized, then ASSERT().
 396   If Lock is already in the released state, then ASSERT().
 397
 398   @param  Lock  A pointer to the lock to release.
 399
 400 **/
 401 VOID
 402 EFIAPI
 403 EfiReleaseLock (
 404   IN EFI_LOCK  *Lock
 405   );
 406
 407 /**
 408   Tests whether a controller handle is being managed by a specific driver.
 409
 410   This function tests whether the driver specified by DriverBindingHandle is
 411   currently managing the controller specified by ControllerHandle.  This test
 412   is performed by evaluating if the the protocol specified by ProtocolGuid is
 413   present on ControllerHandle and is was opened by DriverBindingHandle with an
 414   attribute of EFI_OPEN_PROTOCOL_BY_DRIVER.
 415   If ProtocolGuid is NULL, then ASSERT().
 416
 417   @param  ControllerHandle     A handle for a controller to test.
 418   @param  DriverBindingHandle  Specifies the driver binding handle for the
 419                                driver.
 420   @param  ProtocolGuid         Specifies the protocol that the driver specified
 421                                by DriverBindingHandle opens in its Start()
 422                                function.
 423
 424   @retval EFI_SUCCESS          ControllerHandle is managed by the driver
 425                                specified by DriverBindingHandle.
 426   @retval EFI_UNSUPPORTED      ControllerHandle is not managed by the driver
 427                                specified by DriverBindingHandle.
 428
 429 **/
 430 EFI_STATUS
 431 EFIAPI
 432 EfiTestManagedDevice (
 433   IN CONST EFI_HANDLE       ControllerHandle,
 434   IN CONST EFI_HANDLE       DriverBindingHandle,
 435   IN CONST EFI_GUID         *ProtocolGuid
 436   );
 437
 438 /**
 439   Tests whether a child handle is a child device of the controller.
 440
 441   This function tests whether ChildHandle is one of the children of
 442   ControllerHandle.  This test is performed by checking to see if the protocol
 443   specified by ProtocolGuid is present on ControllerHandle and opened by
 444   ChildHandle with an attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
 445   If ProtocolGuid is NULL, then ASSERT().
 446
 447   @param  ControllerHandle     A handle for a (parent) controller to test.
 448   @param  ChildHandle          A child handle to test.
 449   @param  ProtocolGuid         Supplies the protocol that the child controller
 450                                opens on its parent controller.
 451
 452   @retval EFI_SUCCESS          ChildHandle is a child of the ControllerHandle.
 453   @retval EFI_UNSUPPORTED      ChildHandle is not a child of the
 454                                ControllerHandle.
 455
 456 **/
 457 EFI_STATUS
 458 EFIAPI
 459 EfiTestChildHandle (
 460   IN CONST EFI_HANDLE       ControllerHandle,
 461   IN CONST EFI_HANDLE       ChildHandle,
 462   IN CONST EFI_GUID         *ProtocolGuid
 463   );
 464
 465 /**
 466   This function looks up a Unicode string in UnicodeStringTable.
 467
 468   If Language is a member of SupportedLanguages and a Unicode string is found in
 469   UnicodeStringTable that matches the language code specified by Language, then it
 470   is returned in UnicodeString.
 471
 472   @param  Language                A pointer to the ISO 639-2 language code for the
 473                                   Unicode string to look up and return.
 474   @param  SupportedLanguages      A pointer to the set of ISO 639-2 language codes
 475                                   that the Unicode string table supports.  Language
 476                                   must be a member of this set.
 477   @param  UnicodeStringTable      A pointer to the table of Unicode strings.
 478   @param  UnicodeString           A pointer to the Unicode string from UnicodeStringTable
 479                                   that matches the language specified by Language.
 480
 481   @retval EFI_SUCCESS             The Unicode string that matches the language
 482                                   specified by Language was found
 483                                   in the table of Unicode strings UnicodeStringTable,
 484                                   and it was returned in UnicodeString.
 485   @retval EFI_INVALID_PARAMETER   Language is NULL.
 486   @retval EFI_INVALID_PARAMETER   UnicodeString is NULL.
 487   @retval EFI_UNSUPPORTED         SupportedLanguages is NULL.
 488   @retval EFI_UNSUPPORTED         UnicodeStringTable is NULL.
 489   @retval EFI_UNSUPPORTED         The language specified by Language is not a
 490                                   member of SupportedLanguages.
 491   @retval EFI_UNSUPPORTED         The language specified by Language is not
 492                                   supported by UnicodeStringTable.
 493
 494 **/
 495 EFI_STATUS
 496 EFIAPI
 497 LookupUnicodeString (
 498   IN CONST CHAR8                     *Language,
 499   IN CONST CHAR8                     *SupportedLanguages,
 500   IN CONST EFI_UNICODE_STRING_TABLE  *UnicodeStringTable,
 501   OUT CHAR16                         **UnicodeString
 502   );
 503
 504 /**
 505   This function looks up a Unicode string in UnicodeStringTable.
 506
 507   If Language is a member of SupportedLanguages and a Unicode string is found in
 508   UnicodeStringTable that matches the language code specified by Language, then
 509   it is returned in UnicodeString.
 510
 511   @param  Language             A pointer to an ASCII string containing the ISO 639-2 or the
 512                                RFC 4646 language code for the Unicode string to look up and
 513                                return. If Iso639Language is TRUE, then this ASCII string is
 514                                not assumed to be Null-terminated, and only the first three
 515                                characters are used. If Iso639Language is FALSE, then this ASCII
 516                                string must be Null-terminated.
 517   @param  SupportedLanguages   A pointer to a Null-terminated ASCII string that contains a
 518                                set of ISO 639-2 or RFC 4646 language codes that the Unicode
 519                                string table supports.  Language must be a member of this set.
 520                                If Iso639Language is TRUE, then this string contains one or more
 521                                ISO 639-2 language codes with no separator characters. If Iso639Language
 522                                is FALSE, then is string contains one or more RFC 4646 language
 523                                codes separated by ';'.
 524   @param  UnicodeStringTable   A pointer to the table of Unicode strings. Type EFI_UNICODE_STRING_TABLE
 525                                is defined in "Related Definitions".
 526   @param  UnicodeString        A pointer to the Null-terminated Unicode string from UnicodeStringTable
 527                                that matches the language specified by Language.
 528   @param  Iso639Language       Specifies the supported language code format. If it is TRUE, then
 529                                Language and SupportedLanguages follow ISO 639-2 language code format.
 530                                Otherwise, they follow the RFC 4646 language code format.
 531
 532
 533   @retval  EFI_SUCCESS            The Unicode string that matches the language specified by Language
 534                                   was found in the table of Unicode strings UnicodeStringTable, and
 535                                   it was returned in UnicodeString.
 536   @retval  EFI_INVALID_PARAMETER  Language is NULL.
 537   @retval  EFI_INVALID_PARAMETER  UnicodeString is NULL.
 538   @retval  EFI_UNSUPPORTED        SupportedLanguages is NULL.
 539   @retval  EFI_UNSUPPORTED        UnicodeStringTable is NULL.
 540   @retval  EFI_UNSUPPORTED        The language specified by Language is not a member of SupportedLanguages.
 541   @retval  EFI_UNSUPPORTED        The language specified by Language is not supported by UnicodeStringTable.
 542
 543 **/
 544 EFI_STATUS
 545 EFIAPI
 546 LookupUnicodeString2 (
 547   IN CONST CHAR8                     *Language,
 548   IN CONST CHAR8                     *SupportedLanguages,
 549   IN CONST EFI_UNICODE_STRING_TABLE  *UnicodeStringTable,
 550   OUT CHAR16                         **UnicodeString,
 551   IN BOOLEAN                         Iso639Language
 552   );
 553
 554 /**
 555   This function adds a Unicode string to UnicodeStringTable.
 556
 557   If Language is a member of SupportedLanguages then UnicodeString is added to
 558   UnicodeStringTable.  New buffers are allocated for both Language and
 559   UnicodeString.  The contents of Language and UnicodeString are copied into
 560   these new buffers.  These buffers are automatically freed when
 561   FreeUnicodeStringTable() is called.
 562
 563   @param  Language                A pointer to the ISO 639-2 language code for the Unicode
 564                                   string to add.
 565   @param  SupportedLanguages      A pointer to the set of ISO 639-2 language codes
 566                                   that the Unicode string table supports.
 567                                   Language must be a member of this set.
 568   @param  UnicodeStringTable      A pointer to the table of Unicode strings.
 569   @param  UnicodeString           A pointer to the Unicode string to add.
 570
 571   @retval EFI_SUCCESS             The Unicode string that matches the language
 572                                   specified by Language was found in the table of
 573                                   Unicode strings UnicodeStringTable, and it was
 574                                   returned in UnicodeString.
 575   @retval EFI_INVALID_PARAMETER   Language is NULL.
 576   @retval EFI_INVALID_PARAMETER   UnicodeString is NULL.
 577   @retval EFI_INVALID_PARAMETER   UnicodeString is an empty string.
 578   @retval EFI_UNSUPPORTED         SupportedLanguages is NULL.
 579   @retval EFI_ALREADY_STARTED     A Unicode string with language Language is
 580                                   already present in UnicodeStringTable.
 581   @retval EFI_OUT_OF_RESOURCES    There is not enough memory to add another
 582                                   Unicode string to UnicodeStringTable.
 583   @retval EFI_UNSUPPORTED         The language specified by Language is not a
 584                                   member of SupportedLanguages.
 585
 586 **/
 587 EFI_STATUS
 588 EFIAPI
 589 AddUnicodeString (
 590   IN     CONST CHAR8               *Language,
 591   IN     CONST CHAR8               *SupportedLanguages,
 592   IN OUT EFI_UNICODE_STRING_TABLE  **UnicodeStringTable,
 593   IN     CONST CHAR16              *UnicodeString
 594   );
 595
 596 /**
 597   This function adds the Null-terminated Unicode string specified by UnicodeString
 598   to UnicodeStringTable.
 599
 600   If Language is a member of SupportedLanguages then UnicodeString is added to
 601   UnicodeStringTable.  New buffers are allocated for both Language and UnicodeString.
 602   The contents of Language and UnicodeString are copied into these new buffers.
 603   These buffers are automatically freed when EfiLibFreeUnicodeStringTable() is called.
 604
 605   @param  Language            A pointer to an ASCII string containing the ISO 639-2 or
 606                               the RFC 4646 language code for the Unicode string to add.
 607                               If Iso639Language is TRUE, then this ASCII string is not
 608                               assumed to be Null-terminated, and only the first three
 609                               chacters are used. If Iso639Language is FALSE, then this
 610                               ASCII string must be Null-terminated.
 611   @param  SupportedLanguages  A pointer to a Null-terminated ASCII string that contains
 612                               a set of ISO 639-2 or RFC 4646 language codes that the Unicode
 613                               string table supports.  Language must be a member of this set.
 614                               If Iso639Language is TRUE, then this string contains one or more
 615                               ISO 639-2 language codes with no separator characters.
 616                               If Iso639Language is FALSE, then is string contains one or more
 617                               RFC 4646 language codes separated by ';'.
 618   @param  UnicodeStringTable  A pointer to the table of Unicode strings. Type EFI_UNICODE_STRING_TABLE
 619                               is defined in "Related Definitions".
 620   @param  UnicodeString       A pointer to the Unicode string to add.
 621   @param  Iso639Language      Specifies the supported language code format. If it is TRUE,
 622                               then Language and SupportedLanguages follow ISO 639-2 language code format.
 623                               Otherwise, they follow RFC 4646 language code format.
 624
 625   @retval EFI_SUCCESS            The Unicode string that matches the language specified by
 626                                  Language was found in the table of Unicode strings UnicodeStringTable,
 627                                  and it was returned in UnicodeString.
 628   @retval EFI_INVALID_PARAMETER  Language is NULL.
 629   @retval EFI_INVALID_PARAMETER  UnicodeString is NULL.
 630   @retval EFI_INVALID_PARAMETER  UnicodeString is an empty string.
 631   @retval EFI_UNSUPPORTED        SupportedLanguages is NULL.
 632   @retval EFI_ALREADY_STARTED    A Unicode string with language Language is already present in
 633                                  UnicodeStringTable.
 634   @retval EFI_OUT_OF_RESOURCES   There is not enough memory to add another Unicode string UnicodeStringTable.
 635   @retval EFI_UNSUPPORTED        The language specified by Language is not a member of SupportedLanguages.
 636
 637 **/
 638 EFI_STATUS
 639 EFIAPI
 640 AddUnicodeString2 (
 641   IN     CONST CHAR8               *Language,
 642   IN     CONST CHAR8               *SupportedLanguages,
 643   IN OUT EFI_UNICODE_STRING_TABLE  **UnicodeStringTable,
 644   IN     CONST CHAR16              *UnicodeString,
 645   IN     BOOLEAN                   Iso639Language
 646   );
 647
 648 /**
 649   This function frees the table of Unicode strings in UnicodeStringTable.
 650
 651   If UnicodeStringTable is NULL, then EFI_SUCCESS is returned.
 652   Otherwise, each language code, and each Unicode string in the Unicode string
 653   table are freed, and EFI_SUCCESS is returned.
 654
 655   @param  UnicodeStringTable  A pointer to the table of Unicode strings.
 656
 657   @retval EFI_SUCCESS         The Unicode string table was freed.
 658
 659 **/
 660 EFI_STATUS
 661 EFIAPI
 662 FreeUnicodeStringTable (
 663   IN EFI_UNICODE_STRING_TABLE  *UnicodeStringTable
 664   );
 665
 666 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
 667
 668 /**
 669   [ATTENTION] This function will be deprecated for security reason.
 670
 671   Returns a pointer to an allocated buffer that contains the contents of a
 672   variable retrieved through the UEFI Runtime Service GetVariable().  The
 673   returned buffer is allocated using AllocatePool().  The caller is responsible
 674   for freeing this buffer with FreePool().
 675
 676   If Name is NULL, then ASSERT().
 677   If Guid is NULL, then ASSERT().
 678
 679   @param[in]  Name  The pointer to a Null-terminated Unicode string.
 680   @param[in]  Guid  The pointer to an EFI_GUID structure.
 681
 682   @retval NULL   The variable could not be retrieved.
 683   @retval NULL   There are not enough resources available for the variable contents.
 684   @retval Other  A pointer to allocated buffer containing the variable contents.
 685
 686 **/
 687 VOID *
 688 EFIAPI
 689 GetVariable (
 690   IN CONST CHAR16    *Name,
 691   IN CONST EFI_GUID  *Guid
 692   );
 693
 694 /**
 695   [ATTENTION] This function will be deprecated for security reason.
 696
 697   Returns a pointer to an allocated buffer that contains the contents of a
 698   variable retrieved through the UEFI Runtime Service GetVariable().  This
 699   function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables.
 700   The returned buffer is allocated using AllocatePool().  The caller is
 701   responsible for freeing this buffer with FreePool().
 702
 703   If Name is NULL, then ASSERT().
 704
 705   @param[in]  Name  The pointer to a Null-terminated Unicode string.
 706
 707   @retval NULL   The variable could not be retrieved.
 708   @retval NULL   There are not enough resources available for the variable contents.
 709   @retval Other  A pointer to allocated buffer containing the variable contents.
 710
 711 **/
 712 VOID *
 713 EFIAPI
 714 GetEfiGlobalVariable (
 715   IN CONST CHAR16  *Name
 716   );
 717 #endif
 718
 719
 720 /**
 721   Returns the status whether get the variable success. The function retrieves
 722   variable  through the UEFI Runtime Service GetVariable().  The
 723   returned buffer is allocated using AllocatePool().  The caller is responsible
 724   for freeing this buffer with FreePool().
 725
 726   If Name  is NULL, then ASSERT().
 727   If Guid  is NULL, then ASSERT().
 728   If Value is NULL, then ASSERT().
 729
 730   @param[in]  Name  The pointer to a Null-terminated Unicode string.
 731   @param[in]  Guid  The pointer to an EFI_GUID structure
 732   @param[out] Value The buffer point saved the variable info.
 733   @param[out] Size  The buffer size of the variable.
 734
 735   @return EFI_OUT_OF_RESOURCES      Allocate buffer failed.
 736   @return EFI_SUCCESS               Find the specified variable.
 737   @return Others Errors             Return errors from call to gRT->GetVariable.
 738
 739 **/
 740 EFI_STATUS
 741 EFIAPI
 742 GetVariable2 (
 743   IN CONST CHAR16    *Name,
 744   IN CONST EFI_GUID  *Guid,
 745   OUT VOID           **Value,
 746   OUT UINTN          *Size OPTIONAL
 747   );
 748
 749 /**
 750   Returns a pointer to an allocated buffer that contains the contents of a
 751   variable retrieved through the UEFI Runtime Service GetVariable().  This
 752   function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables.
 753   The returned buffer is allocated using AllocatePool().  The caller is
 754   responsible for freeing this buffer with FreePool().
 755
 756   If Name  is NULL, then ASSERT().
 757   If Value is NULL, then ASSERT().
 758
 759   @param[in]  Name  The pointer to a Null-terminated Unicode string.
 760   @param[out] Value The buffer point saved the variable info.
 761   @param[out] Size  The buffer size of the variable.
 762
 763   @return EFI_OUT_OF_RESOURCES      Allocate buffer failed.
 764   @return EFI_SUCCESS               Find the specified variable.
 765   @return Others Errors             Return errors from call to gRT->GetVariable.
 766
 767 **/
 768 EFI_STATUS
 769 EFIAPI
 770 GetEfiGlobalVariable2 (
 771   IN CONST CHAR16    *Name,
 772   OUT VOID           **Value,
 773   OUT UINTN          *Size OPTIONAL
 774   );
 775
 776 /**
 777   Returns a pointer to an allocated buffer that contains the best matching language
 778   from a set of supported languages.
 779
 780   This function supports both ISO 639-2 and RFC 4646 language codes, but language
 781   code types may not be mixed in a single call to this function.  The language
 782   code returned is allocated using AllocatePool().  The caller is responsible for
 783   freeing the allocated buffer using FreePool().  This function supports a variable
 784   argument list that allows the caller to pass in a prioritized list of language
 785   codes to test against all the language codes in SupportedLanguages.
 786
 787   If SupportedLanguages is NULL, then ASSERT().
 788
 789   @param[in]  SupportedLanguages  A pointer to a Null-terminated ASCII string that
 790                                   contains a set of language codes in the format
 791                                   specified by Iso639Language.
 792   @param[in]  Iso639Language      If not zero, then all language codes are assumed to be
 793                                   in ISO 639-2 format.  If zero, then all language
 794                                   codes are assumed to be in RFC 4646 language format
 795   @param[in]  ...                 A variable argument list that contains pointers to
 796                                   Null-terminated ASCII strings that contain one or more
 797                                   language codes in the format specified by Iso639Language.
 798                                   The first language code from each of these language
 799                                   code lists is used to determine if it is an exact or
 800                                   close match to any of the language codes in
 801                                   SupportedLanguages.  Close matches only apply to RFC 4646
 802                                   language codes, and the matching algorithm from RFC 4647
 803                                   is used to determine if a close match is present.  If
 804                                   an exact or close match is found, then the matching
 805                                   language code from SupportedLanguages is returned.  If
 806                                   no matches are found, then the next variable argument
 807                                   parameter is evaluated.  The variable argument list
 808                                   is terminated by a NULL.
 809
 810   @retval NULL   The best matching language could not be found in SupportedLanguages.
 811   @retval NULL   There are not enough resources available to return the best matching
 812                  language.
 813   @retval Other  A pointer to a Null-terminated ASCII string that is the best matching
 814                  language in SupportedLanguages.
 815
 816 **/
 817 CHAR8 *
 818 EFIAPI
 819 GetBestLanguage (
 820   IN CONST CHAR8  *SupportedLanguages,
 821   IN UINTN        Iso639Language,
 822   ...
 823   );
 824
 825 /**
 826   Draws a dialog box to the console output device specified by
 827   ConOut defined in the EFI_SYSTEM_TABLE and waits for a keystroke
 828   from the console input device specified by ConIn defined in the
 829   EFI_SYSTEM_TABLE.
 830
 831   If there are no strings in the variable argument list, then ASSERT().
 832   If all the strings in the variable argument list are empty, then ASSERT().
 833
 834   @param[in]   Attribute  Specifies the foreground and background color of the popup.
 835   @param[out]  Key        A pointer to the EFI_KEY value of the key that was
 836                           pressed.  This is an optional parameter that may be NULL.
 837                           If it is NULL then no wait for a keypress will be performed.
 838   @param[in]  ...         The variable argument list that contains pointers to Null-
 839                           terminated Unicode strings to display in the dialog box.
 840                           The variable argument list is terminated by a NULL.
 841
 842 **/
 843 VOID
 844 EFIAPI
 845 CreatePopUp (
 846   IN  UINTN          Attribute,
 847   OUT EFI_INPUT_KEY  *Key,      OPTIONAL
 848   ...
 849   );
 850
 851 /**
 852   Retrieves the width of a Unicode character.
 853
 854   This function computes and returns the width of the Unicode character specified
 855   by UnicodeChar.
 856
 857   @param  UnicodeChar   A Unicode character.
 858
 859   @retval 0             The width if UnicodeChar could not be determined.
 860   @retval 1             UnicodeChar is a narrow glyph.
 861   @retval 2             UnicodeChar is a wide glyph.
 862
 863 **/
 864 UINTN
 865 EFIAPI
 866 GetGlyphWidth (
 867   IN CHAR16  UnicodeChar
 868   );
 869
 870 /**
 871   Computes the display length of a Null-terminated Unicode String.
 872
 873   This function computes and returns the display length of the Null-terminated Unicode
 874   string specified by String.  If String is NULL then 0 is returned. If any of the widths
 875   of the Unicode characters in String can not be determined, then 0 is returned. The display
 876   width of String can be computed by summing the display widths of each Unicode character
 877   in String.  Unicode characters that are narrow glyphs have a width of 1, and Unicode
 878   characters that are width glyphs have a width of 2.
 879   If String is not aligned on a 16-bit boundary, then ASSERT().
 880
 881   @param  String      A pointer to a Null-terminated Unicode string.
 882
 883   @return The display length of the Null-terminated Unicode string specified by String.
 884
 885 **/
 886 UINTN
 887 EFIAPI
 888 UnicodeStringDisplayLength (
 889   IN CONST CHAR16  *String
 890   );
 891
 892 //
 893 // Functions that abstract early Framework contamination of UEFI.
 894 //
 895 /**
 896   Create, Signal, and Close the Ready to Boot event using EfiSignalEventReadyToBoot().
 897
 898   This function abstracts the signaling of the Ready to Boot Event. The Framework moved
 899   from a proprietary to UEFI 2.0 based mechanism. This library abstracts the caller
 900   from how this event is created to prevent to code form having to change with the
 901   version of the specification supported.
 902
 903 **/
 904 VOID
 905 EFIAPI
 906 EfiSignalEventReadyToBoot (
 907   VOID
 908   );
 909
 910 /**
 911   Create, Signal, and Close the Ready to Boot event using EfiSignalEventLegacyBoot().
 912
 913   This function abstracts the signaling of the Legacy Boot Event. The Framework moved from
 914   a proprietary to UEFI 2.0 based mechanism.  This library abstracts the caller from how
 915   this event is created to prevent to code form having to change with the version of the
 916   specification supported.
 917
 918 **/
 919 VOID
 920 EFIAPI
 921 EfiSignalEventLegacyBoot (
 922   VOID
 923   );
 924
 925 /**
 926   Creates an EFI event in the Legacy Boot Event Group.
 927
 928   Prior to UEFI 2.0 this was done via a non blessed UEFI extensions and this library
 929   abstracts the implementation mechanism of this event from the caller. This function
 930   abstracts the creation of the Legacy Boot Event. The Framework moved from a proprietary
 931   to UEFI 2.0 based mechanism.  This library abstracts the caller from how this event
 932   is created to prevent to code form having to change with the version of the
 933   specification supported.
 934   If LegacyBootEvent is NULL, then ASSERT().
 935
 936   @param  LegacyBootEvent   Returns the EFI event returned from gBS->CreateEvent(Ex).
 937
 938   @retval EFI_SUCCESS       The event was created.
 939   @retval Other             The event was not created.
 940
 941 **/
 942 EFI_STATUS
 943 EFIAPI
 944 EfiCreateEventLegacyBoot (
 945   OUT EFI_EVENT  *LegacyBootEvent
 946   );
 947
 948 /**
 949   Create an EFI event in the Legacy Boot Event Group and allows
 950   the caller to specify a notification function.
 951
 952   This function abstracts the creation of the Legacy Boot Event.
 953   The Framework moved from a proprietary to UEFI 2.0 based mechanism.
 954   This library abstracts the caller from how this event is created to prevent
 955   to code form having to change with the version of the specification supported.
 956   If LegacyBootEvent is NULL, then ASSERT().
 957
 958   @param  NotifyTpl         The task priority level of the event.
 959   @param  NotifyFunction    The notification function to call when the event is signaled.
 960   @param  NotifyContext     The content to pass to NotifyFunction when the event is signaled.
 961   @param  LegacyBootEvent   Returns the EFI event returned from gBS->CreateEvent(Ex).
 962
 963   @retval EFI_SUCCESS       The event was created.
 964   @retval Other             The event was not created.
 965
 966 **/
 967 EFI_STATUS
 968 EFIAPI
 969 EfiCreateEventLegacyBootEx (
 970   IN  EFI_TPL           NotifyTpl,
 971   IN  EFI_EVENT_NOTIFY  NotifyFunction,  OPTIONAL
 972   IN  VOID              *NotifyContext,  OPTIONAL
 973   OUT EFI_EVENT         *LegacyBootEvent
 974   );
 975
 976 /**
 977   Create an EFI event in the Ready To Boot Event Group.
 978
 979   Prior to UEFI 2.0 this was done via a non-standard UEFI extension, and this library
 980   abstracts the implementation mechanism of this event from the caller.
 981   This function abstracts the creation of the Ready to Boot Event.  The Framework
 982   moved from a proprietary to UEFI 2.0-based mechanism.  This library abstracts
 983   the caller from how this event is created to prevent the code form having to
 984   change with the version of the specification supported.
 985   If ReadyToBootEvent is NULL, then ASSERT().
 986
 987   @param  ReadyToBootEvent   Returns the EFI event returned from gBS->CreateEvent(Ex).
 988
 989   @retval EFI_SUCCESS       The event was created.
 990   @retval Other             The event was not created.
 991
 992 **/
 993 EFI_STATUS
 994 EFIAPI
 995 EfiCreateEventReadyToBoot (
 996   OUT EFI_EVENT  *ReadyToBootEvent
 997   );
 998
 999 /**
1000   Create an EFI event in the Ready To Boot Event Group and allows
1001   the caller to specify a notification function.
1002
1003   This function abstracts the creation of the Ready to Boot Event.
1004   The Framework moved from a proprietary to UEFI 2.0 based mechanism.
1005   This library abstracts the caller from how this event is created to prevent
1006   to code form having to change with the version of the specification supported.
1007   If ReadyToBootEvent is NULL, then ASSERT().
1008
1009   @param  NotifyTpl         The task priority level of the event.
1010   @param  NotifyFunction    The notification function to call when the event is signaled.
1011   @param  NotifyContext     The content to pass to NotifyFunction when the event is signaled.
1012   @param  ReadyToBootEvent  Returns the EFI event returned from gBS->CreateEvent(Ex).
1013
1014   @retval EFI_SUCCESS       The event was created.
1015   @retval Other             The event was not created.
1016
1017 **/
1018 EFI_STATUS
1019 EFIAPI
1020 EfiCreateEventReadyToBootEx (
1021   IN  EFI_TPL           NotifyTpl,
1022   IN  EFI_EVENT_NOTIFY  NotifyFunction,  OPTIONAL
1023   IN  VOID              *NotifyContext,  OPTIONAL
1024   OUT EFI_EVENT         *ReadyToBootEvent
1025   );
1026
1027 /**
1028   Initialize a Firmware Volume (FV) Media Device Path node.
1029
1030   The Framework FwVol Device Path changed to conform to the UEFI 2.0 specification.
1031   This library function abstracts initializing a device path node.
1032   Initialize the MEDIA_FW_VOL_FILEPATH_DEVICE_PATH data structure.  This device
1033   path changed in the DXE CIS version 0.92 in a non back ward compatible way to
1034   not conflict with the UEFI 2.0 specification.  This function abstracts the
1035   differences from the caller.
1036   If FvDevicePathNode is NULL, then ASSERT().
1037   If NameGuid is NULL, then ASSERT().
1038
1039   @param  FvDevicePathNode  The pointer to a FV device path node to initialize
1040   @param  NameGuid          FV file name to use in FvDevicePathNode
1041
1042 **/
1043 VOID
1044 EFIAPI
1045 EfiInitializeFwVolDevicepathNode (
1046   IN OUT MEDIA_FW_VOL_FILEPATH_DEVICE_PATH  *FvDevicePathNode,
1047   IN CONST EFI_GUID                         *NameGuid
1048   );
1049
1050 /**
1051   Check to see if the Firmware Volume (FV) Media Device Path is valid
1052
1053   The Framework FwVol Device Path changed to conform to the UEFI 2.0 specification.
1054   This library function abstracts validating a device path node.
1055   Check the MEDIA_FW_VOL_FILEPATH_DEVICE_PATH data structure to see if it's valid.
1056   If it is valid, then return the GUID file name from the device path node.  Otherwise,
1057   return NULL.  This device path changed in the DXE CIS version 0.92 in a non backward
1058   compatible way to not conflict with the UEFI 2.0 specification.  This function abstracts
1059   the differences from the caller.
1060   If FvDevicePathNode is NULL, then ASSERT().
1061
1062   @param  FvDevicePathNode  The pointer to FV device path to check.
1063
1064   @retval NULL              FvDevicePathNode is not valid.
1065   @retval Other             FvDevicePathNode is valid and pointer to NameGuid was returned.
1066
1067 **/
1068 EFI_GUID *
1069 EFIAPI
1070 EfiGetNameGuidFromFwVolDevicePathNode (
1071   IN CONST MEDIA_FW_VOL_FILEPATH_DEVICE_PATH  *FvDevicePathNode
1072   );
1073
1074 /**
1075   Prints a formatted Unicode string to the console output device specified by
1076   ConOut defined in the EFI_SYSTEM_TABLE.
1077
1078   This function prints a formatted Unicode string to the console output device
1079   specified by ConOut in EFI_SYSTEM_TABLE and returns the number of Unicode
1080   characters that printed to ConOut.  If the length of the formatted Unicode
1081   string is greater than PcdUefiLibMaxPrintBufferSize, then only the first
1082   PcdUefiLibMaxPrintBufferSize characters are sent to ConOut.
1083   If Format is NULL, then ASSERT().
1084   If Format is not aligned on a 16-bit boundary, then ASSERT().
1085   If gST->ConOut is NULL, then ASSERT().
1086
1087   @param Format   A null-terminated Unicode format string.
1088   @param ...      The variable argument list whose contents are accessed based
1089                   on the format string specified by Format.
1090
1091   @return Number of Unicode characters printed to ConOut.
1092
1093 **/
1094 UINTN
1095 EFIAPI
1096 Print (
1097   IN CONST CHAR16  *Format,
1098   ...
1099   );
1100
1101 /**
1102   Prints a formatted Unicode string to the console output device specified by
1103   StdErr defined in the EFI_SYSTEM_TABLE.
1104
1105   This function prints a formatted Unicode string to the console output device
1106   specified by StdErr in EFI_SYSTEM_TABLE and returns the number of Unicode
1107   characters that printed to StdErr.  If the length of the formatted Unicode
1108   string is greater than PcdUefiLibMaxPrintBufferSize, then only the first
1109   PcdUefiLibMaxPrintBufferSize characters are sent to StdErr.
1110   If Format is NULL, then ASSERT().
1111   If Format is not aligned on a 16-bit boundary, then ASSERT().
1112   If gST->StdErr is NULL, then ASSERT().
1113
1114   @param Format   A null-terminated Unicode format string.
1115   @param ...      The variable argument list whose contents are accessed based
1116                   on the format string specified by Format.
1117
1118   @return Number of Unicode characters printed to StdErr.
1119
1120 **/
1121 UINTN
1122 EFIAPI
1123 ErrorPrint (
1124   IN CONST CHAR16  *Format,
1125   ...
1126   );
1127
1128 /**
1129   Prints a formatted ASCII string to the console output device specified by
1130   ConOut defined in the EFI_SYSTEM_TABLE.
1131
1132   This function prints a formatted ASCII string to the console output device
1133   specified by ConOut in EFI_SYSTEM_TABLE and returns the number of ASCII
1134   characters that printed to ConOut.  If the length of the formatted ASCII
1135   string is greater than PcdUefiLibMaxPrintBufferSize, then only the first
1136   PcdUefiLibMaxPrintBufferSize characters are sent to ConOut.
1137   If Format is NULL, then ASSERT().
1138   If gST->ConOut is NULL, then ASSERT().
1139
1140   @param Format   A null-terminated ASCII format string.
1141   @param ...      The variable argument list whose contents are accessed based
1142                   on the format string specified by Format.
1143
1144   @return Number of ASCII characters printed to ConOut.
1145
1146 **/
1147 UINTN
1148 EFIAPI
1149 AsciiPrint (
1150   IN CONST CHAR8  *Format,
1151   ...
1152   );
1153
1154 /**
1155   Prints a formatted ASCII string to the console output device specified by
1156   StdErr defined in the EFI_SYSTEM_TABLE.
1157
1158   This function prints a formatted ASCII string to the console output device
1159   specified by StdErr in EFI_SYSTEM_TABLE and returns the number of ASCII
1160   characters that printed to StdErr.  If the length of the formatted ASCII
1161   string is greater than PcdUefiLibMaxPrintBufferSize, then only the first
1162   PcdUefiLibMaxPrintBufferSize characters are sent to StdErr.
1163   If Format is NULL, then ASSERT().
1164   If gST->StdErr is NULL, then ASSERT().
1165
1166   @param Format   A null-terminated ASCII format string.
1167   @param ...      The variable argument list whose contents are accessed based
1168                   on the format string specified by Format.
1169
1170   @return Number of ASCII characters printed to ConErr.
1171
1172 **/
1173 UINTN
1174 EFIAPI
1175 AsciiErrorPrint (
1176   IN CONST CHAR8  *Format,
1177   ...
1178   );
1179
1180
1181 /**
1182   Prints a formatted Unicode string to a graphics console device specified by
1183   ConsoleOutputHandle defined in the EFI_SYSTEM_TABLE at the given (X,Y) coordinates.
1184
1185   This function prints a formatted Unicode string to the graphics console device
1186   specified by ConsoleOutputHandle in EFI_SYSTEM_TABLE and returns the number of
1187   Unicode characters displayed, not including partial characters that may be clipped
1188   by the right edge of the display.  If the length of the formatted Unicode string is
1189   greater than PcdUefiLibMaxPrintBufferSize, then at most the first
1190   PcdUefiLibMaxPrintBufferSize characters are printed.  The EFI_HII_FONT_PROTOCOL
1191   is used to convert the string to a bitmap using the glyphs registered with the
1192   HII database.  No wrapping is performed, so any portions of the string the fall
1193   outside the active display region will not be displayed.
1194
1195   If a graphics console device is not associated with the ConsoleOutputHandle
1196   defined in the EFI_SYSTEM_TABLE then no string is printed, and 0 is returned.
1197   If the EFI_HII_FONT_PROTOCOL is not present in the handle database, then no
1198   string is printed, and 0 is returned.
1199   If Format is NULL, then ASSERT().
1200   If Format is not aligned on a 16-bit boundary, then ASSERT().
1201   If gST->ConsoleOutputHandle is NULL, then ASSERT().
1202
1203   @param  PointX       X coordinate to print the string.
1204   @param  PointY       Y coordinate to print the string.
1205   @param  ForeGround   The foreground color of the string being printed.  This is
1206                        an optional parameter that may be NULL.  If it is NULL,
1207                        then the foreground color of the current ConOut device
1208                        in the EFI_SYSTEM_TABLE is used.
1209   @param  BackGround   The background color of the string being printed.  This is
1210                        an optional parameter that may be NULL.  If it is NULL,
1211                        then the background color of the current ConOut device
1212                        in the EFI_SYSTEM_TABLE is used.
1213   @param  Format       A null-terminated Unicode format string.  See Print Library
1214                        for the supported format string syntax.
1215   @param  ...          Variable argument list whose contents are accessed based on
1216                        the format string specified by Format.
1217
1218   @return  The number of Unicode characters printed.
1219
1220 **/
1221 UINTN
1222 EFIAPI
1223 PrintXY (
1224   IN UINTN                            PointX,
1225   IN UINTN                            PointY,
1226   IN EFI_GRAPHICS_OUTPUT_BLT_PIXEL    *ForeGround, OPTIONAL
1227   IN EFI_GRAPHICS_OUTPUT_BLT_PIXEL    *BackGround, OPTIONAL
1228   IN CONST CHAR16                     *Format,
1229   ...
1230   );
1231
1232 /**
1233   Prints a formatted ASCII string to a graphics console device specified by
1234   ConsoleOutputHandle defined in the EFI_SYSTEM_TABLE at the given (X,Y) coordinates.
1235
1236   This function prints a formatted ASCII string to the graphics console device
1237   specified by ConsoleOutputHandle in EFI_SYSTEM_TABLE and returns the number of
1238   ASCII characters displayed, not including partial characters that may be clipped
1239   by the right edge of the display.  If the length of the formatted ASCII string is
1240   greater than PcdUefiLibMaxPrintBufferSize, then at most the first
1241   PcdUefiLibMaxPrintBufferSize characters are printed.  The EFI_HII_FONT_PROTOCOL
1242   is used to convert the string to a bitmap using the glyphs registered with the
1243   HII database.  No wrapping is performed, so any portions of the string the fall
1244   outside the active display region will not be displayed.
1245
1246   If a graphics console device is not associated with the ConsoleOutputHandle
1247   defined in the EFI_SYSTEM_TABLE then no string is printed, and 0 is returned.
1248   If the EFI_HII_FONT_PROTOCOL is not present in the handle database, then no
1249   string is printed, and 0 is returned.
1250   If Format is NULL, then ASSERT().
1251   If gST->ConsoleOutputHandle is NULL, then ASSERT().
1252
1253   @param  PointX       X coordinate to print the string.
1254   @param  PointY       Y coordinate to print the string.
1255   @param  ForeGround   The foreground color of the string being printed.  This is
1256                        an optional parameter that may be NULL.  If it is NULL,
1257                        then the foreground color of the current ConOut device
1258                        in the EFI_SYSTEM_TABLE is used.
1259   @param  BackGround   The background color of the string being printed.  This is
1260                        an optional parameter that may be NULL.  If it is NULL,
1261                        then the background color of the current ConOut device
1262                        in the EFI_SYSTEM_TABLE is used.
1263   @param  Format       A null-terminated ASCII format string.  See Print Library
1264                        for the supported format string syntax.
1265   @param  ...          The variable argument list whose contents are accessed based on
1266                        the format string specified by Format.
1267
1268   @return  The number of ASCII characters printed.
1269
1270 **/
1271 UINTN
1272 EFIAPI
1273 AsciiPrintXY (
1274   IN UINTN                            PointX,
1275   IN UINTN                            PointY,
1276   IN EFI_GRAPHICS_OUTPUT_BLT_PIXEL    *ForeGround, OPTIONAL
1277   IN EFI_GRAPHICS_OUTPUT_BLT_PIXEL    *BackGround, OPTIONAL
1278   IN CONST CHAR8                      *Format,
1279   ...
1280   );
1281
1282 /**
1283   Installs and completes the initialization of a Driver Binding Protocol instance.
1284
1285   Installs the Driver Binding Protocol specified by DriverBinding onto the handle
1286   specified by DriverBindingHandle. If DriverBindingHandle is NULL, then DriverBinding
1287   is installed onto a newly created handle. DriverBindingHandle is typically the same
1288   as the driver's ImageHandle, but it can be different if the driver produces multiple
1289   Driver Binding Protocols.
1290   If DriverBinding is NULL, then ASSERT().
1291   If DriverBinding can not be installed onto a handle, then ASSERT().
1292
1293   @param  ImageHandle          The image handle of the driver.
1294   @param  SystemTable          The EFI System Table that was passed to the driver's entry point.
1295   @param  DriverBinding        A Driver Binding Protocol instance that this driver is producing.
1296   @param  DriverBindingHandle  The handle that DriverBinding is to be installed onto.  If this
1297                                parameter is NULL, then a new handle is created.
1298
1299   @retval EFI_SUCCESS           The protocol installation completed successfully.
1300   @retval EFI_OUT_OF_RESOURCES  There was not enough system resources to install the protocol.
1301   @retval Others                Status from gBS->InstallMultipleProtocolInterfaces().
1302
1303 **/
1304 EFI_STATUS
1305 EFIAPI
1306 EfiLibInstallDriverBinding (
1307   IN CONST EFI_HANDLE             ImageHandle,
1308   IN CONST EFI_SYSTEM_TABLE       *SystemTable,
1309   IN EFI_DRIVER_BINDING_PROTOCOL  *DriverBinding,
1310   IN EFI_HANDLE                   DriverBindingHandle
1311   );
1312
1313
1314 /**
1315   Installs and completes the initialization of a Driver Binding Protocol instance and
1316   optionally installs the Component Name, Driver Configuration and Driver Diagnostics Protocols.
1317
1318   Initializes a driver by installing the Driver Binding Protocol together with the
1319   optional Component Name, optional Driver Configure and optional Driver Diagnostic
1320   Protocols onto the driver's DriverBindingHandle. If DriverBindingHandle is NULL,
1321   then the protocols are installed onto a newly created handle. DriverBindingHandle
1322   is typically the same as the driver's ImageHandle, but it can be different if the
1323   driver produces multiple Driver Binding Protocols.
1324   If DriverBinding is NULL, then ASSERT().
1325   If the installation fails, then ASSERT().
1326
1327   @param  ImageHandle          The image handle of the driver.
1328   @param  SystemTable          The EFI System Table that was passed to the driver's entry point.
1329   @param  DriverBinding        A Driver Binding Protocol instance that this driver is producing.
1330   @param  DriverBindingHandle  The handle that DriverBinding is to be installed onto.  If this
1331                                parameter is NULL, then a new handle is created.
1332   @param  ComponentName        A Component Name Protocol instance that this driver is producing.
1333   @param  DriverConfiguration  A Driver Configuration Protocol instance that this driver is producing.
1334   @param  DriverDiagnostics    A Driver Diagnostics Protocol instance that this driver is producing.
1335
1336   @retval EFI_SUCCESS           The protocol installation completed successfully.
1337   @retval EFI_OUT_OF_RESOURCES  There was not enough memory in the pool to install all the protocols.
1338
1339 **/
1340 EFI_STATUS
1341 EFIAPI
1342 EfiLibInstallAllDriverProtocols (
1343   IN CONST EFI_HANDLE                         ImageHandle,
1344   IN CONST EFI_SYSTEM_TABLE                   *SystemTable,
1345   IN EFI_DRIVER_BINDING_PROTOCOL              *DriverBinding,
1346   IN EFI_HANDLE                               DriverBindingHandle,
1347   IN CONST EFI_COMPONENT_NAME_PROTOCOL        *ComponentName,       OPTIONAL
1348   IN CONST EFI_DRIVER_CONFIGURATION_PROTOCOL  *DriverConfiguration, OPTIONAL
1349   IN CONST EFI_DRIVER_DIAGNOSTICS_PROTOCOL    *DriverDiagnostics    OPTIONAL
1350   );
1351
1352
1353
1354 /**
1355   Installs Driver Binding Protocol with optional Component Name and Component Name 2 Protocols.
1356
1357   Initializes a driver by installing the Driver Binding Protocol together with the
1358   optional Component Name and optional Component Name 2 protocols onto the driver's
1359   DriverBindingHandle.  If DriverBindingHandle is NULL, then the protocols are installed
1360   onto a newly created handle.  DriverBindingHandle is typically the same as the driver's
1361   ImageHandle, but it can be different if the driver produces multiple Driver Binding Protocols.
1362   If DriverBinding is NULL, then ASSERT().
1363   If the installation fails, then ASSERT().
1364
1365   @param  ImageHandle          The image handle of the driver.
1366   @param  SystemTable          The EFI System Table that was passed to the driver's entry point.
1367   @param  DriverBinding        A Driver Binding Protocol instance that this driver is producing.
1368   @param  DriverBindingHandle  The handle that DriverBinding is to be installed onto.  If this
1369                                parameter is NULL, then a new handle is created.
1370   @param  ComponentName        A Component Name Protocol instance that this driver is producing.
1371   @param  ComponentName2       A Component Name 2 Protocol instance that this driver is producing.
1372
1373   @retval EFI_SUCCESS           The protocol installation completed successfully.
1374   @retval EFI_OUT_OF_RESOURCES  There was not enough memory in pool to install all the protocols.
1375
1376 **/
1377 EFI_STATUS
1378 EFIAPI
1379 EfiLibInstallDriverBindingComponentName2 (
1380   IN CONST EFI_HANDLE                         ImageHandle,
1381   IN CONST EFI_SYSTEM_TABLE                   *SystemTable,
1382   IN EFI_DRIVER_BINDING_PROTOCOL              *DriverBinding,
1383   IN EFI_HANDLE                               DriverBindingHandle,
1384   IN CONST EFI_COMPONENT_NAME_PROTOCOL        *ComponentName,       OPTIONAL
1385   IN CONST EFI_COMPONENT_NAME2_PROTOCOL       *ComponentName2       OPTIONAL
1386   );
1387
1388
1389 /**
1390   Installs Driver Binding Protocol with optional Component Name, Component Name 2, Driver
1391   Configuration, Driver Configuration 2, Driver Diagnostics, and Driver Diagnostics 2 Protocols.
1392
1393   Initializes a driver by installing the Driver Binding Protocol together with the optional
1394   Component Name, optional Component Name 2, optional Driver Configuration, optional Driver Configuration 2,
1395   optional Driver Diagnostic, and optional Driver Diagnostic 2 Protocols onto the driver's DriverBindingHandle.
1396   DriverBindingHandle is typically the same as the driver's ImageHandle, but it can be different if the driver
1397   produces multiple Driver Binding Protocols.
1398   If DriverBinding is NULL, then ASSERT().
1399   If the installation fails, then ASSERT().
1400
1401
1402   @param  ImageHandle           The image handle of the driver.
1403   @param  SystemTable           The EFI System Table that was passed to the driver's entry point.
1404   @param  DriverBinding         A Driver Binding Protocol instance that this driver is producing.
1405   @param  DriverBindingHandle   The handle that DriverBinding is to be installed onto.  If this
1406                                 parameter is NULL, then a new handle is created.
1407   @param  ComponentName         A Component Name Protocol instance that this driver is producing.
1408   @param  ComponentName2        A Component Name 2 Protocol instance that this driver is producing.
1409   @param  DriverConfiguration   A Driver Configuration Protocol instance that this driver is producing.
1410   @param  DriverConfiguration2  A Driver Configuration Protocol 2 instance that this driver is producing.
1411   @param  DriverDiagnostics     A Driver Diagnostics Protocol instance that this driver is producing.
1412   @param  DriverDiagnostics2    A Driver Diagnostics Protocol 2 instance that this driver is producing.
1413
1414   @retval EFI_SUCCESS           The protocol installation completed successfully.
1415   @retval EFI_OUT_OF_RESOURCES  There was not enough memory in pool to install all the protocols.
1416
1417 **/
1418 EFI_STATUS
1419 EFIAPI
1420 EfiLibInstallAllDriverProtocols2 (
1421   IN CONST EFI_HANDLE                         ImageHandle,
1422   IN CONST EFI_SYSTEM_TABLE                   *SystemTable,
1423   IN EFI_DRIVER_BINDING_PROTOCOL              *DriverBinding,
1424   IN EFI_HANDLE                               DriverBindingHandle,
1425   IN CONST EFI_COMPONENT_NAME_PROTOCOL        *ComponentName,        OPTIONAL
1426   IN CONST EFI_COMPONENT_NAME2_PROTOCOL       *ComponentName2,       OPTIONAL
1427   IN CONST EFI_DRIVER_CONFIGURATION_PROTOCOL  *DriverConfiguration,  OPTIONAL
1428   IN CONST EFI_DRIVER_CONFIGURATION2_PROTOCOL *DriverConfiguration2, OPTIONAL
1429   IN CONST EFI_DRIVER_DIAGNOSTICS_PROTOCOL    *DriverDiagnostics,    OPTIONAL
1430   IN CONST EFI_DRIVER_DIAGNOSTICS2_PROTOCOL   *DriverDiagnostics2    OPTIONAL
1431   );
1432
1433 /**
1434   Appends a formatted Unicode string to a Null-terminated Unicode string
1435
1436   This function appends a formatted Unicode string to the Null-terminated
1437   Unicode string specified by String.   String is optional and may be NULL.
1438   Storage for the formatted Unicode string returned is allocated using
1439   AllocatePool().  The pointer to the appended string is returned.  The caller
1440   is responsible for freeing the returned string.
1441
1442   If String is not NULL and not aligned on a 16-bit boundary, then ASSERT().
1443   If FormatString is NULL, then ASSERT().
1444   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
1445
1446   @param[in] String         A Null-terminated Unicode string.
1447   @param[in] FormatString   A Null-terminated Unicode format string.
1448   @param[in]  Marker        VA_LIST marker for the variable argument list.
1449
1450   @retval NULL    There was not enough available memory.
1451   @return         Null-terminated Unicode string is that is the formatted
1452                   string appended to String.
1453 **/
1454 CHAR16*
1455 EFIAPI
1456 CatVSPrint (
1457   IN  CHAR16  *String, OPTIONAL
1458   IN  CONST CHAR16  *FormatString,
1459   IN  VA_LIST       Marker
1460   );
1461
1462 /**
1463   Appends a formatted Unicode string to a Null-terminated Unicode string
1464
1465   This function appends a formatted Unicode string to the Null-terminated
1466   Unicode string specified by String.   String is optional and may be NULL.
1467   Storage for the formatted Unicode string returned is allocated using
1468   AllocatePool().  The pointer to the appended string is returned.  The caller
1469   is responsible for freeing the returned string.
1470
1471   If String is not NULL and not aligned on a 16-bit boundary, then ASSERT().
1472   If FormatString is NULL, then ASSERT().
1473   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
1474
1475   @param[in] String         A Null-terminated Unicode string.
1476   @param[in] FormatString   A Null-terminated Unicode format string.
1477   @param[in] ...            The variable argument list whose contents are
1478                             accessed based on the format string specified by
1479                             FormatString.
1480
1481   @retval NULL    There was not enough available memory.
1482   @return         Null-terminated Unicode string is that is the formatted
1483                   string appended to String.
1484 **/
1485 CHAR16 *
1486 EFIAPI
1487 CatSPrint (
1488   IN  CHAR16  *String, OPTIONAL
1489   IN  CONST CHAR16  *FormatString,
1490   ...
1491   );
1492
1493 /**
1494   Returns an array of protocol instance that matches the given protocol.
1495
1496   @param[in]  Protocol      Provides the protocol to search for.
1497   @param[out] NoProtocols   The number of protocols returned in Buffer.
1498   @param[out] Buffer        A pointer to the buffer to return the requested
1499                             array of protocol instances that match Protocol.
1500                             The returned buffer is allocated using
1501                             EFI_BOOT_SERVICES.AllocatePool().  The caller is
1502                             responsible for freeing this buffer with
1503                             EFI_BOOT_SERVICES.FreePool().
1504
1505   @retval EFI_SUCCESS            The array of protocols was returned in Buffer,
1506                                  and the number of protocols in Buffer was
1507                                  returned in NoProtocols.
1508   @retval EFI_NOT_FOUND          No protocols found.
1509   @retval EFI_OUT_OF_RESOURCES   There is not enough pool memory to store the
1510                                  matching results.
1511   @retval EFI_INVALID_PARAMETER  Protocol is NULL.
1512   @retval EFI_INVALID_PARAMETER  NoProtocols is NULL.
1513   @retval EFI_INVALID_PARAMETER  Buffer is NULL.
1514
1515 **/
1516 EFI_STATUS
1517 EFIAPI
1518 EfiLocateProtocolBuffer (
1519   IN  EFI_GUID  *Protocol,
1520   OUT UINTN     *NoProtocols,
1521   OUT VOID      ***Buffer
1522   );
1523 #endif