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