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