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