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 checks the supported languages list for a target language,
 466   This only supports RFC 4646 Languages.
 467
 468   @param  SupportedLanguages  The supported languages
 469   @param  TargetLanguage      The target language
 470
 471   @retval Returns EFI_SUCCESS if the language is supported,
 472           EFI_UNSUPPORTED otherwise
 473
 474 **/
 475 EFI_STATUS
 476 EFIAPI
 477 IsLanguageSupported (
 478   IN CONST CHAR8 *SupportedLanguages,
 479   IN CONST CHAR8 *TargetLanguage
 480   );
 481
 482 /**
 483   This function looks up a Unicode string in UnicodeStringTable.
 484
 485   If Language is a member of SupportedLanguages and a Unicode string is found in
 486   UnicodeStringTable that matches the language code specified by Language, then it
 487   is returned in UnicodeString.
 488
 489   @param  Language                A pointer to the ISO 639-2 language code for the
 490                                   Unicode string to look up and return.
 491   @param  SupportedLanguages      A pointer to the set of ISO 639-2 language codes
 492                                   that the Unicode string table supports.  Language
 493                                   must be a member of this set.
 494   @param  UnicodeStringTable      A pointer to the table of Unicode strings.
 495   @param  UnicodeString           A pointer to the Unicode string from UnicodeStringTable
 496                                   that matches the language specified by Language.
 497
 498   @retval EFI_SUCCESS             The Unicode string that matches the language
 499                                   specified by Language was found
 500                                   in the table of Unicode strings UnicodeStringTable,
 501                                   and it was returned in UnicodeString.
 502   @retval EFI_INVALID_PARAMETER   Language is NULL.
 503   @retval EFI_INVALID_PARAMETER   UnicodeString is NULL.
 504   @retval EFI_UNSUPPORTED         SupportedLanguages is NULL.
 505   @retval EFI_UNSUPPORTED         UnicodeStringTable is NULL.
 506   @retval EFI_UNSUPPORTED         The language specified by Language is not a
 507                                   member of SupportedLanguages.
 508   @retval EFI_UNSUPPORTED         The language specified by Language is not
 509                                   supported by UnicodeStringTable.
 510
 511 **/
 512 EFI_STATUS
 513 EFIAPI
 514 LookupUnicodeString (
 515   IN CONST CHAR8                     *Language,
 516   IN CONST CHAR8                     *SupportedLanguages,
 517   IN CONST EFI_UNICODE_STRING_TABLE  *UnicodeStringTable,
 518   OUT CHAR16                         **UnicodeString
 519   );
 520
 521 /**
 522   This function looks up a Unicode string in UnicodeStringTable.
 523
 524   If Language is a member of SupportedLanguages and a Unicode string is found in
 525   UnicodeStringTable that matches the language code specified by Language, then
 526   it is returned in UnicodeString.
 527
 528   @param  Language             A pointer to an ASCII string containing the ISO 639-2 or the
 529                                RFC 4646 language code for the Unicode string to look up and
 530                                return. If Iso639Language is TRUE, then this ASCII string is
 531                                not assumed to be Null-terminated, and only the first three
 532                                characters are used. If Iso639Language is FALSE, then this ASCII
 533                                string must be Null-terminated.
 534   @param  SupportedLanguages   A pointer to a Null-terminated ASCII string that contains a
 535                                set of ISO 639-2 or RFC 4646 language codes that the Unicode
 536                                string table supports.  Language must be a member of this set.
 537                                If Iso639Language is TRUE, then this string contains one or more
 538                                ISO 639-2 language codes with no separator characters. If Iso639Language
 539                                is FALSE, then is string contains one or more RFC 4646 language
 540                                codes separated by ';'.
 541   @param  UnicodeStringTable   A pointer to the table of Unicode strings. Type EFI_UNICODE_STRING_TABLE
 542                                is defined in "Related Definitions".
 543   @param  UnicodeString        A pointer to the Null-terminated Unicode string from UnicodeStringTable
 544                                that matches the language specified by Language.
 545   @param  Iso639Language       Specifies the supported language code format. If it is TRUE, then
 546                                Language and SupportedLanguages follow ISO 639-2 language code format.
 547                                Otherwise, they follow the RFC 4646 language code format.
 548
 549
 550   @retval  EFI_SUCCESS            The Unicode string that matches the language specified by Language
 551                                   was found in the table of Unicode strings UnicodeStringTable, and
 552                                   it was returned in UnicodeString.
 553   @retval  EFI_INVALID_PARAMETER  Language is NULL.
 554   @retval  EFI_INVALID_PARAMETER  UnicodeString is NULL.
 555   @retval  EFI_UNSUPPORTED        SupportedLanguages is NULL.
 556   @retval  EFI_UNSUPPORTED        UnicodeStringTable is NULL.
 557   @retval  EFI_UNSUPPORTED        The language specified by Language is not a member of SupportedLanguages.
 558   @retval  EFI_UNSUPPORTED        The language specified by Language is not supported by UnicodeStringTable.
 559
 560 **/
 561 EFI_STATUS
 562 EFIAPI
 563 LookupUnicodeString2 (
 564   IN CONST CHAR8                     *Language,
 565   IN CONST CHAR8                     *SupportedLanguages,
 566   IN CONST EFI_UNICODE_STRING_TABLE  *UnicodeStringTable,
 567   OUT CHAR16                         **UnicodeString,
 568   IN BOOLEAN                         Iso639Language
 569   );
 570
 571 /**
 572   This function adds a Unicode string to UnicodeStringTable.
 573
 574   If Language is a member of SupportedLanguages then UnicodeString is added to
 575   UnicodeStringTable.  New buffers are allocated for both Language and
 576   UnicodeString.  The contents of Language and UnicodeString are copied into
 577   these new buffers.  These buffers are automatically freed when
 578   FreeUnicodeStringTable() is called.
 579
 580   @param  Language                A pointer to the ISO 639-2 language code for the Unicode
 581                                   string to add.
 582   @param  SupportedLanguages      A pointer to the set of ISO 639-2 language codes
 583                                   that the Unicode string table supports.
 584                                   Language must be a member of this set.
 585   @param  UnicodeStringTable      A pointer to the table of Unicode strings.
 586   @param  UnicodeString           A pointer to the Unicode string to add.
 587
 588   @retval EFI_SUCCESS             The Unicode string that matches the language
 589                                   specified by Language was found in the table of
 590                                   Unicode strings UnicodeStringTable, and it was
 591                                   returned in UnicodeString.
 592   @retval EFI_INVALID_PARAMETER   Language is NULL.
 593   @retval EFI_INVALID_PARAMETER   UnicodeString is NULL.
 594   @retval EFI_INVALID_PARAMETER   UnicodeString is an empty string.
 595   @retval EFI_UNSUPPORTED         SupportedLanguages is NULL.
 596   @retval EFI_ALREADY_STARTED     A Unicode string with language Language is
 597                                   already present in UnicodeStringTable.
 598   @retval EFI_OUT_OF_RESOURCES    There is not enough memory to add another
 599                                   Unicode string to UnicodeStringTable.
 600   @retval EFI_UNSUPPORTED         The language specified by Language is not a
 601                                   member of SupportedLanguages.
 602
 603 **/
 604 EFI_STATUS
 605 EFIAPI
 606 AddUnicodeString (
 607   IN     CONST CHAR8               *Language,
 608   IN     CONST CHAR8               *SupportedLanguages,
 609   IN OUT EFI_UNICODE_STRING_TABLE  **UnicodeStringTable,
 610   IN     CONST CHAR16              *UnicodeString
 611   );
 612
 613 /**
 614   This function adds the Null-terminated Unicode string specified by UnicodeString
 615   to UnicodeStringTable.
 616
 617   If Language is a member of SupportedLanguages then UnicodeString is added to
 618   UnicodeStringTable.  New buffers are allocated for both Language and UnicodeString.
 619   The contents of Language and UnicodeString are copied into these new buffers.
 620   These buffers are automatically freed when EfiLibFreeUnicodeStringTable() is called.
 621
 622   @param  Language            A pointer to an ASCII string containing the ISO 639-2 or
 623                               the RFC 4646 language code for the Unicode string to add.
 624                               If Iso639Language is TRUE, then this ASCII string is not
 625                               assumed to be Null-terminated, and only the first three
 626                               chacters are used. If Iso639Language is FALSE, then this
 627                               ASCII string must be Null-terminated.
 628   @param  SupportedLanguages  A pointer to a Null-terminated ASCII string that contains
 629                               a set of ISO 639-2 or RFC 4646 language codes that the Unicode
 630                               string table supports.  Language must be a member of this set.
 631                               If Iso639Language is TRUE, then this string contains one or more
 632                               ISO 639-2 language codes with no separator characters.
 633                               If Iso639Language is FALSE, then is string contains one or more
 634                               RFC 4646 language codes separated by ';'.
 635   @param  UnicodeStringTable  A pointer to the table of Unicode strings. Type EFI_UNICODE_STRING_TABLE
 636                               is defined in "Related Definitions".
 637   @param  UnicodeString       A pointer to the Unicode string to add.
 638   @param  Iso639Language      Specifies the supported language code format. If it is TRUE,
 639                               then Language and SupportedLanguages follow ISO 639-2 language code format.
 640                               Otherwise, they follow RFC 4646 language code format.
 641
 642   @retval EFI_SUCCESS            The Unicode string that matches the language specified by
 643                                  Language was found in the table of Unicode strings UnicodeStringTable,
 644                                  and it was returned in UnicodeString.
 645   @retval EFI_INVALID_PARAMETER  Language is NULL.
 646   @retval EFI_INVALID_PARAMETER  UnicodeString is NULL.
 647   @retval EFI_INVALID_PARAMETER  UnicodeString is an empty string.
 648   @retval EFI_UNSUPPORTED        SupportedLanguages is NULL.
 649   @retval EFI_ALREADY_STARTED    A Unicode string with language Language is already present in
 650                                  UnicodeStringTable.
 651   @retval EFI_OUT_OF_RESOURCES   There is not enough memory to add another Unicode string UnicodeStringTable.
 652   @retval EFI_UNSUPPORTED        The language specified by Language is not a member of SupportedLanguages.
 653
 654 **/
 655 EFI_STATUS
 656 EFIAPI
 657 AddUnicodeString2 (
 658   IN     CONST CHAR8               *Language,
 659   IN     CONST CHAR8               *SupportedLanguages,
 660   IN OUT EFI_UNICODE_STRING_TABLE  **UnicodeStringTable,
 661   IN     CONST CHAR16              *UnicodeString,
 662   IN     BOOLEAN                   Iso639Language
 663   );
 664
 665 /**
 666   This function frees the table of Unicode strings in UnicodeStringTable.
 667
 668   If UnicodeStringTable is NULL, then EFI_SUCCESS is returned.
 669   Otherwise, each language code, and each Unicode string in the Unicode string
 670   table are freed, and EFI_SUCCESS is returned.
 671
 672   @param  UnicodeStringTable  A pointer to the table of Unicode strings.
 673
 674   @retval EFI_SUCCESS         The Unicode string table was freed.
 675
 676 **/
 677 EFI_STATUS
 678 EFIAPI
 679 FreeUnicodeStringTable (
 680   IN EFI_UNICODE_STRING_TABLE  *UnicodeStringTable
 681   );
 682
 683 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
 684
 685 /**
 686   [ATTENTION] This function will be deprecated for security reason.
 687
 688   Returns a pointer to an allocated buffer that contains the contents of a
 689   variable retrieved through the UEFI Runtime Service GetVariable().  The
 690   returned buffer is allocated using AllocatePool().  The caller is responsible
 691   for freeing this buffer with FreePool().
 692
 693   If Name is NULL, then ASSERT().
 694   If Guid is NULL, then ASSERT().
 695
 696   @param[in]  Name  The pointer to a Null-terminated Unicode string.
 697   @param[in]  Guid  The pointer to an EFI_GUID structure.
 698
 699   @retval NULL   The variable could not be retrieved.
 700   @retval NULL   There are not enough resources available for the variable contents.
 701   @retval Other  A pointer to allocated buffer containing the variable contents.
 702
 703 **/
 704 VOID *
 705 EFIAPI
 706 GetVariable (
 707   IN CONST CHAR16    *Name,
 708   IN CONST EFI_GUID  *Guid
 709   );
 710
 711 /**
 712   [ATTENTION] This function will be deprecated for security reason.
 713
 714   Returns a pointer to an allocated buffer that contains the contents of a
 715   variable retrieved through the UEFI Runtime Service GetVariable().  This
 716   function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables.
 717   The returned buffer is allocated using AllocatePool().  The caller is
 718   responsible for freeing this buffer with FreePool().
 719
 720   If Name is NULL, then ASSERT().
 721
 722   @param[in]  Name  The pointer to a Null-terminated Unicode string.
 723
 724   @retval NULL   The variable could not be retrieved.
 725   @retval NULL   There are not enough resources available for the variable contents.
 726   @retval Other  A pointer to allocated buffer containing the variable contents.
 727
 728 **/
 729 VOID *
 730 EFIAPI
 731 GetEfiGlobalVariable (
 732   IN CONST CHAR16  *Name
 733   );
 734 #endif
 735
 736
 737 /**
 738   Returns the status whether get the variable success. The function retrieves
 739   variable  through the UEFI Runtime Service GetVariable().  The
 740   returned buffer is allocated using AllocatePool().  The caller is responsible
 741   for freeing this buffer with FreePool().
 742
 743   If Name  is NULL, then ASSERT().
 744   If Guid  is NULL, then ASSERT().
 745   If Value is NULL, then ASSERT().
 746
 747   @param[in]  Name  The pointer to a Null-terminated Unicode string.
 748   @param[in]  Guid  The pointer to an EFI_GUID structure
 749   @param[out] Value The buffer point saved the variable info.
 750   @param[out] Size  The buffer size of the variable.
 751
 752   @retval EFI_OUT_OF_RESOURCES      Allocate buffer failed.
 753   @retval EFI_SUCCESS               Find the specified variable.
 754   @retval Others Errors             Return errors from call to gRT->GetVariable.
 755
 756 **/
 757 EFI_STATUS
 758 EFIAPI
 759 GetVariable2 (
 760   IN CONST CHAR16    *Name,
 761   IN CONST EFI_GUID  *Guid,
 762   OUT VOID           **Value,
 763   OUT UINTN          *Size OPTIONAL
 764   );
 765
 766 /**
 767   Returns a pointer to an allocated buffer that contains the contents of a
 768   variable retrieved through the UEFI Runtime Service GetVariable().  This
 769   function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables.
 770   The returned buffer is allocated using AllocatePool().  The caller is
 771   responsible for freeing this buffer with FreePool().
 772
 773   If Name  is NULL, then ASSERT().
 774   If Value is NULL, then ASSERT().
 775
 776   @param[in]  Name  The pointer to a Null-terminated Unicode string.
 777   @param[out] Value The buffer point saved the variable info.
 778   @param[out] Size  The buffer size of the variable.
 779
 780   @retval EFI_OUT_OF_RESOURCES      Allocate buffer failed.
 781   @retval EFI_SUCCESS               Find the specified variable.
 782   @retval Others Errors             Return errors from call to gRT->GetVariable.
 783
 784 **/
 785 EFI_STATUS
 786 EFIAPI
 787 GetEfiGlobalVariable2 (
 788   IN CONST CHAR16    *Name,
 789   OUT VOID           **Value,
 790   OUT UINTN          *Size OPTIONAL
 791   );
 792
 793 /** Return the attributes of the variable.
 794
 795   Returns the status whether get the variable success. The function retrieves
 796   variable  through the UEFI Runtime Service GetVariable().  The
 797   returned buffer is allocated using AllocatePool().  The caller is responsible
 798   for freeing this buffer with FreePool().  The attributes are returned if
 799   the caller provides a valid Attribute parameter.
 800
 801   If Name  is NULL, then ASSERT().
 802   If Guid  is NULL, then ASSERT().
 803   If Value is NULL, then ASSERT().
 804
 805   @param[in]  Name  The pointer to a Null-terminated Unicode string.
 806   @param[in]  Guid  The pointer to an EFI_GUID structure
 807   @param[out] Value The buffer point saved the variable info.
 808   @param[out] Size  The buffer size of the variable.
 809   @param[out] Attr  The pointer to the variable attributes as found in var store
 810
 811   @retval EFI_OUT_OF_RESOURCES      Allocate buffer failed.
 812   @retval EFI_SUCCESS               Find the specified variable.
 813   @retval Others Errors             Return errors from call to gRT->GetVariable.
 814
 815 **/
 816 EFI_STATUS
 817 EFIAPI
 818 GetVariable3(
 819   IN CONST CHAR16       *Name,
 820   IN CONST EFI_GUID     *Guid,
 821      OUT VOID           **Value,
 822      OUT UINTN          *Size OPTIONAL,
 823      OUT UINT32         *Attr OPTIONAL
 824   );
 825
 826 /**
 827   Returns a pointer to an allocated buffer that contains the best matching language
 828   from a set of supported languages.
 829
 830   This function supports both ISO 639-2 and RFC 4646 language codes, but language
 831   code types may not be mixed in a single call to this function.  The language
 832   code returned is allocated using AllocatePool().  The caller is responsible for
 833   freeing the allocated buffer using FreePool().  This function supports a variable
 834   argument list that allows the caller to pass in a prioritized list of language
 835   codes to test against all the language codes in SupportedLanguages.
 836
 837   If SupportedLanguages is NULL, then ASSERT().
 838
 839   @param[in]  SupportedLanguages  A pointer to a Null-terminated ASCII string that
 840                                   contains a set of language codes in the format
 841                                   specified by Iso639Language.
 842   @param[in]  Iso639Language      If not zero, then all language codes are assumed to be
 843                                   in ISO 639-2 format.  If zero, then all language
 844                                   codes are assumed to be in RFC 4646 language format
 845   @param[in]  ...                 A variable argument list that contains pointers to
 846                                   Null-terminated ASCII strings that contain one or more
 847                                   language codes in the format specified by Iso639Language.
 848                                   The first language code from each of these language
 849                                   code lists is used to determine if it is an exact or
 850                                   close match to any of the language codes in
 851                                   SupportedLanguages.  Close matches only apply to RFC 4646
 852                                   language codes, and the matching algorithm from RFC 4647
 853                                   is used to determine if a close match is present.  If
 854                                   an exact or close match is found, then the matching
 855                                   language code from SupportedLanguages is returned.  If
 856                                   no matches are found, then the next variable argument
 857                                   parameter is evaluated.  The variable argument list
 858                                   is terminated by a NULL.
 859
 860   @retval NULL   The best matching language could not be found in SupportedLanguages.
 861   @retval NULL   There are not enough resources available to return the best matching
 862                  language.
 863   @retval Other  A pointer to a Null-terminated ASCII string that is the best matching
 864                  language in SupportedLanguages.
 865
 866 **/
 867 CHAR8 *
 868 EFIAPI
 869 GetBestLanguage (
 870   IN CONST CHAR8  *SupportedLanguages,
 871   IN UINTN        Iso639Language,
 872   ...
 873   );
 874
 875 /**
 876   Draws a dialog box to the console output device specified by
 877   ConOut defined in the EFI_SYSTEM_TABLE and waits for a keystroke
 878   from the console input device specified by ConIn defined in the
 879   EFI_SYSTEM_TABLE.
 880
 881   If there are no strings in the variable argument list, then ASSERT().
 882   If all the strings in the variable argument list are empty, then ASSERT().
 883
 884   @param[in]   Attribute  Specifies the foreground and background color of the popup.
 885   @param[out]  Key        A pointer to the EFI_KEY value of the key that was
 886                           pressed.  This is an optional parameter that may be NULL.
 887                           If it is NULL then no wait for a keypress will be performed.
 888   @param[in]  ...         The variable argument list that contains pointers to Null-
 889                           terminated Unicode strings to display in the dialog box.
 890                           The variable argument list is terminated by a NULL.
 891
 892 **/
 893 VOID
 894 EFIAPI
 895 CreatePopUp (
 896   IN  UINTN          Attribute,
 897   OUT EFI_INPUT_KEY  *Key,      OPTIONAL
 898   ...
 899   );
 900
 901 /**
 902   Retrieves the width of a Unicode character.
 903
 904   This function computes and returns the width of the Unicode character specified
 905   by UnicodeChar.
 906
 907   @param  UnicodeChar   A Unicode character.
 908
 909   @retval 0             The width if UnicodeChar could not be determined.
 910   @retval 1             UnicodeChar is a narrow glyph.
 911   @retval 2             UnicodeChar is a wide glyph.
 912
 913 **/
 914 UINTN
 915 EFIAPI
 916 GetGlyphWidth (
 917   IN CHAR16  UnicodeChar
 918   );
 919
 920 /**
 921   Computes the display length of a Null-terminated Unicode String.
 922
 923   This function computes and returns the display length of the Null-terminated Unicode
 924   string specified by String.  If String is NULL then 0 is returned. If any of the widths
 925   of the Unicode characters in String can not be determined, then 0 is returned. The display
 926   width of String can be computed by summing the display widths of each Unicode character
 927   in String.  Unicode characters that are narrow glyphs have a width of 1, and Unicode
 928   characters that are width glyphs have a width of 2.
 929   If String is not aligned on a 16-bit boundary, then ASSERT().
 930
 931   @param  String      A pointer to a Null-terminated Unicode string.
 932
 933   @return The display length of the Null-terminated Unicode string specified by String.
 934
 935 **/
 936 UINTN
 937 EFIAPI
 938 UnicodeStringDisplayLength (
 939   IN CONST CHAR16  *String
 940   );
 941
 942 //
 943 // Functions that abstract early Framework contamination of UEFI.
 944 //
 945 /**
 946   Create, Signal, and Close the Ready to Boot event using EfiSignalEventReadyToBoot().
 947
 948   This function abstracts the signaling of the Ready to Boot Event. The Framework moved
 949   from a proprietary to UEFI 2.0 based mechanism. This library abstracts the caller
 950   from how this event is created to prevent to code form having to change with the
 951   version of the specification supported.
 952
 953 **/
 954 VOID
 955 EFIAPI
 956 EfiSignalEventReadyToBoot (
 957   VOID
 958   );
 959
 960 /**
 961   Create, Signal, and Close the Ready to Boot event using EfiSignalEventLegacyBoot().
 962
 963   This function abstracts the signaling of the Legacy Boot Event. The Framework moved from
 964   a proprietary to UEFI 2.0 based mechanism.  This library abstracts the caller from how
 965   this event is created to prevent to code form having to change with the version of the
 966   specification supported.
 967
 968 **/
 969 VOID
 970 EFIAPI
 971 EfiSignalEventLegacyBoot (
 972   VOID
 973   );
 974
 975 /**
 976   Creates an EFI event in the Legacy Boot Event Group.
 977
 978   Prior to UEFI 2.0 this was done via a non blessed UEFI extensions and this library
 979   abstracts the implementation mechanism of this event from the caller. This function
 980   abstracts the creation of the Legacy Boot Event. The Framework moved from a proprietary
 981   to UEFI 2.0 based mechanism.  This library abstracts the caller from how this event
 982   is created to prevent to code form having to change with the version of the
 983   specification supported.
 984   If LegacyBootEvent is NULL, then ASSERT().
 985
 986   @param  LegacyBootEvent   Returns the EFI event returned from gBS->CreateEvent(Ex).
 987
 988   @retval EFI_SUCCESS       The event was created.
 989   @retval Other             The event was not created.
 990
 991 **/
 992 EFI_STATUS
 993 EFIAPI
 994 EfiCreateEventLegacyBoot (
 995   OUT EFI_EVENT  *LegacyBootEvent
 996   );
 997
 998 /**
 999   Create an EFI event in the Legacy Boot Event Group and allows
1000   the caller to specify a notification function.
1001
1002   This function abstracts the creation of the Legacy Boot Event.
1003   The Framework moved from a proprietary to UEFI 2.0 based mechanism.
1004   This library abstracts the caller from how this event is created to prevent
1005   to code form having to change with the version of the specification supported.
1006   If LegacyBootEvent is NULL, then ASSERT().
1007
1008   @param  NotifyTpl         The task priority level of the event.
1009   @param  NotifyFunction    The notification function to call when the event is signaled.
1010   @param  NotifyContext     The content to pass to NotifyFunction when the event is signaled.
1011   @param  LegacyBootEvent   Returns the EFI event returned from gBS->CreateEvent(Ex).
1012
1013   @retval EFI_SUCCESS       The event was created.
1014   @retval Other             The event was not created.
1015
1016 **/
1017 EFI_STATUS
1018 EFIAPI
1019 EfiCreateEventLegacyBootEx (
1020   IN  EFI_TPL           NotifyTpl,
1021   IN  EFI_EVENT_NOTIFY  NotifyFunction,  OPTIONAL
1022   IN  VOID              *NotifyContext,  OPTIONAL
1023   OUT EFI_EVENT         *LegacyBootEvent
1024   );
1025
1026 /**
1027   Create an EFI event in the Ready To Boot Event Group.
1028
1029   Prior to UEFI 2.0 this was done via a non-standard UEFI extension, and this library
1030   abstracts the implementation mechanism of this event from the caller.
1031   This function abstracts the creation of the Ready to Boot Event.  The Framework
1032   moved from a proprietary to UEFI 2.0-based mechanism.  This library abstracts
1033   the caller from how this event is created to prevent the code form having to
1034   change with the version of the specification supported.
1035   If ReadyToBootEvent is NULL, then ASSERT().
1036
1037   @param  ReadyToBootEvent   Returns the EFI event returned from gBS->CreateEvent(Ex).
1038
1039   @retval EFI_SUCCESS       The event was created.
1040   @retval Other             The event was not created.
1041
1042 **/
1043 EFI_STATUS
1044 EFIAPI
1045 EfiCreateEventReadyToBoot (
1046   OUT EFI_EVENT  *ReadyToBootEvent
1047   );
1048
1049 /**
1050   Create an EFI event in the Ready To Boot Event Group and allows
1051   the caller to specify a notification function.
1052
1053   This function abstracts the creation of the Ready to Boot Event.
1054   The Framework moved from a proprietary to UEFI 2.0 based mechanism.
1055   This library abstracts the caller from how this event is created to prevent
1056   to code form having to change with the version of the specification supported.
1057   If ReadyToBootEvent is NULL, then ASSERT().
1058
1059   @param  NotifyTpl         The task priority level of the event.
1060   @param  NotifyFunction    The notification function to call when the event is signaled.
1061   @param  NotifyContext     The content to pass to NotifyFunction when the event is signaled.
1062   @param  ReadyToBootEvent  Returns the EFI event returned from gBS->CreateEvent(Ex).
1063
1064   @retval EFI_SUCCESS       The event was created.
1065   @retval Other             The event was not created.
1066
1067 **/
1068 EFI_STATUS
1069 EFIAPI
1070 EfiCreateEventReadyToBootEx (
1071   IN  EFI_TPL           NotifyTpl,
1072   IN  EFI_EVENT_NOTIFY  NotifyFunction,  OPTIONAL
1073   IN  VOID              *NotifyContext,  OPTIONAL
1074   OUT EFI_EVENT         *ReadyToBootEvent
1075   );
1076
1077 /**
1078   Initialize a Firmware Volume (FV) Media Device Path node.
1079
1080   The Framework FwVol Device Path changed to conform to the UEFI 2.0 specification.
1081   This library function abstracts initializing a device path node.
1082   Initialize the MEDIA_FW_VOL_FILEPATH_DEVICE_PATH data structure.  This device
1083   path changed in the DXE CIS version 0.92 in a non back ward compatible way to
1084   not conflict with the UEFI 2.0 specification.  This function abstracts the
1085   differences from the caller.
1086   If FvDevicePathNode is NULL, then ASSERT().
1087   If NameGuid is NULL, then ASSERT().
1088
1089   @param  FvDevicePathNode  The pointer to a FV device path node to initialize
1090   @param  NameGuid          FV file name to use in FvDevicePathNode
1091
1092 **/
1093 VOID
1094 EFIAPI
1095 EfiInitializeFwVolDevicepathNode (
1096   IN OUT MEDIA_FW_VOL_FILEPATH_DEVICE_PATH  *FvDevicePathNode,
1097   IN CONST EFI_GUID                         *NameGuid
1098   );
1099
1100 /**
1101   Check to see if the Firmware Volume (FV) Media Device Path is valid
1102
1103   The Framework FwVol Device Path changed to conform to the UEFI 2.0 specification.
1104   This library function abstracts validating a device path node.
1105   Check the MEDIA_FW_VOL_FILEPATH_DEVICE_PATH data structure to see if it's valid.
1106   If it is valid, then return the GUID file name from the device path node.  Otherwise,
1107   return NULL.  This device path changed in the DXE CIS version 0.92 in a non backward
1108   compatible way to not conflict with the UEFI 2.0 specification.  This function abstracts
1109   the differences from the caller.
1110   If FvDevicePathNode is NULL, then ASSERT().
1111
1112   @param  FvDevicePathNode  The pointer to FV device path to check.
1113
1114   @retval NULL              FvDevicePathNode is not valid.
1115   @retval Other             FvDevicePathNode is valid and pointer to NameGuid was returned.
1116
1117 **/
1118 EFI_GUID *
1119 EFIAPI
1120 EfiGetNameGuidFromFwVolDevicePathNode (
1121   IN CONST MEDIA_FW_VOL_FILEPATH_DEVICE_PATH  *FvDevicePathNode
1122   );
1123
1124 /**
1125   Prints a formatted Unicode string to the console output device specified by
1126   ConOut defined in the EFI_SYSTEM_TABLE.
1127
1128   This function prints a formatted Unicode string to the console output device
1129   specified by ConOut in EFI_SYSTEM_TABLE and returns the number of Unicode
1130   characters that printed to ConOut.  If the length of the formatted Unicode
1131   string is greater than PcdUefiLibMaxPrintBufferSize, then only the first
1132   PcdUefiLibMaxPrintBufferSize characters are sent to ConOut.
1133   If Format is NULL, then ASSERT().
1134   If Format is not aligned on a 16-bit boundary, then ASSERT().
1135   If gST->ConOut is NULL, then ASSERT().
1136
1137   @param Format   A null-terminated Unicode format string.
1138   @param ...      The variable argument list whose contents are accessed based
1139                   on the format string specified by Format.
1140
1141   @return Number of Unicode characters printed to ConOut.
1142
1143 **/
1144 UINTN
1145 EFIAPI
1146 Print (
1147   IN CONST CHAR16  *Format,
1148   ...
1149   );
1150
1151 /**
1152   Prints a formatted Unicode string to the console output device specified by
1153   StdErr defined in the EFI_SYSTEM_TABLE.
1154
1155   This function prints a formatted Unicode string to the console output device
1156   specified by StdErr in EFI_SYSTEM_TABLE and returns the number of Unicode
1157   characters that printed to StdErr.  If the length of the formatted Unicode
1158   string is greater than PcdUefiLibMaxPrintBufferSize, then only the first
1159   PcdUefiLibMaxPrintBufferSize characters are sent to StdErr.
1160   If Format is NULL, then ASSERT().
1161   If Format is not aligned on a 16-bit boundary, then ASSERT().
1162   If gST->StdErr is NULL, then ASSERT().
1163
1164   @param Format   A null-terminated Unicode format string.
1165   @param ...      The variable argument list whose contents are accessed based
1166                   on the format string specified by Format.
1167
1168   @return Number of Unicode characters printed to StdErr.
1169
1170 **/
1171 UINTN
1172 EFIAPI
1173 ErrorPrint (
1174   IN CONST CHAR16  *Format,
1175   ...
1176   );
1177
1178 /**
1179   Prints a formatted ASCII string to the console output device specified by
1180   ConOut defined in the EFI_SYSTEM_TABLE.
1181
1182   This function prints a formatted ASCII string to the console output device
1183   specified by ConOut in EFI_SYSTEM_TABLE and returns the number of ASCII
1184   characters that printed to ConOut.  If the length of the formatted ASCII
1185   string is greater than PcdUefiLibMaxPrintBufferSize, then only the first
1186   PcdUefiLibMaxPrintBufferSize characters are sent to ConOut.
1187   If Format is NULL, then ASSERT().
1188   If gST->ConOut is NULL, then ASSERT().
1189
1190   @param Format   A null-terminated ASCII format string.
1191   @param ...      The variable argument list whose contents are accessed based
1192                   on the format string specified by Format.
1193
1194   @return Number of ASCII characters printed to ConOut.
1195
1196 **/
1197 UINTN
1198 EFIAPI
1199 AsciiPrint (
1200   IN CONST CHAR8  *Format,
1201   ...
1202   );
1203
1204 /**
1205   Prints a formatted ASCII string to the console output device specified by
1206   StdErr defined in the EFI_SYSTEM_TABLE.
1207
1208   This function prints a formatted ASCII string to the console output device
1209   specified by StdErr in EFI_SYSTEM_TABLE and returns the number of ASCII
1210   characters that printed to StdErr.  If the length of the formatted ASCII
1211   string is greater than PcdUefiLibMaxPrintBufferSize, then only the first
1212   PcdUefiLibMaxPrintBufferSize characters are sent to StdErr.
1213   If Format is NULL, then ASSERT().
1214   If gST->StdErr is NULL, then ASSERT().
1215
1216   @param Format   A null-terminated ASCII format string.
1217   @param ...      The variable argument list whose contents are accessed based
1218                   on the format string specified by Format.
1219
1220   @return Number of ASCII characters printed to ConErr.
1221
1222 **/
1223 UINTN
1224 EFIAPI
1225 AsciiErrorPrint (
1226   IN CONST CHAR8  *Format,
1227   ...
1228   );
1229
1230
1231 /**
1232   Prints a formatted Unicode string to a graphics console device specified by
1233   ConsoleOutputHandle defined in the EFI_SYSTEM_TABLE at the given (X,Y) coordinates.
1234
1235   This function prints a formatted Unicode string to the graphics console device
1236   specified by ConsoleOutputHandle in EFI_SYSTEM_TABLE and returns the number of
1237   Unicode characters displayed, not including partial characters that may be clipped
1238   by the right edge of the display.  If the length of the formatted Unicode string is
1239   greater than PcdUefiLibMaxPrintBufferSize, then at most the first
1240   PcdUefiLibMaxPrintBufferSize characters are printed.  The EFI_HII_FONT_PROTOCOL
1241   is used to convert the string to a bitmap using the glyphs registered with the
1242   HII database.  No wrapping is performed, so any portions of the string the fall
1243   outside the active display region will not be displayed.
1244
1245   If a graphics console device is not associated with the ConsoleOutputHandle
1246   defined in the EFI_SYSTEM_TABLE then no string is printed, and 0 is returned.
1247   If the EFI_HII_FONT_PROTOCOL is not present in the handle database, then no
1248   string is printed, and 0 is returned.
1249   If Format is NULL, then ASSERT().
1250   If Format is not aligned on a 16-bit boundary, then ASSERT().
1251   If gST->ConsoleOutputHandle is NULL, then ASSERT().
1252
1253   @param  PointX       X coordinate to print the string.
1254   @param  PointY       Y coordinate to print the string.
1255   @param  ForeGround   The foreground color of the string being printed.  This is
1256                        an optional parameter that may be NULL.  If it is NULL,
1257                        then the foreground color of the current ConOut device
1258                        in the EFI_SYSTEM_TABLE is used.
1259   @param  BackGround   The background color of the string being printed.  This is
1260                        an optional parameter that may be NULL.  If it is NULL,
1261                        then the background color of the current ConOut device
1262                        in the EFI_SYSTEM_TABLE is used.
1263   @param  Format       A null-terminated Unicode format string.  See Print Library
1264                        for the supported format string syntax.
1265   @param  ...          Variable argument list whose contents are accessed based on
1266                        the format string specified by Format.
1267
1268   @return  The number of Unicode characters printed.
1269
1270 **/
1271 UINTN
1272 EFIAPI
1273 PrintXY (
1274   IN UINTN                            PointX,
1275   IN UINTN                            PointY,
1276   IN EFI_GRAPHICS_OUTPUT_BLT_PIXEL    *ForeGround, OPTIONAL
1277   IN EFI_GRAPHICS_OUTPUT_BLT_PIXEL    *BackGround, OPTIONAL
1278   IN CONST CHAR16                     *Format,
1279   ...
1280   );
1281
1282 /**
1283   Prints a formatted ASCII string to a graphics console device specified by
1284   ConsoleOutputHandle defined in the EFI_SYSTEM_TABLE at the given (X,Y) coordinates.
1285
1286   This function prints a formatted ASCII string to the graphics console device
1287   specified by ConsoleOutputHandle in EFI_SYSTEM_TABLE and returns the number of
1288   ASCII characters displayed, not including partial characters that may be clipped
1289   by the right edge of the display.  If the length of the formatted ASCII string is
1290   greater than PcdUefiLibMaxPrintBufferSize, then at most the first
1291   PcdUefiLibMaxPrintBufferSize characters are printed.  The EFI_HII_FONT_PROTOCOL
1292   is used to convert the string to a bitmap using the glyphs registered with the
1293   HII database.  No wrapping is performed, so any portions of the string the fall
1294   outside the active display region will not be displayed.
1295
1296   If a graphics console device is not associated with the ConsoleOutputHandle
1297   defined in the EFI_SYSTEM_TABLE then no string is printed, and 0 is returned.
1298   If the EFI_HII_FONT_PROTOCOL is not present in the handle database, then no
1299   string is printed, and 0 is returned.
1300   If Format is NULL, then ASSERT().
1301   If gST->ConsoleOutputHandle is NULL, then ASSERT().
1302
1303   @param  PointX       X coordinate to print the string.
1304   @param  PointY       Y coordinate to print the string.
1305   @param  ForeGround   The foreground color of the string being printed.  This is
1306                        an optional parameter that may be NULL.  If it is NULL,
1307                        then the foreground color of the current ConOut device
1308                        in the EFI_SYSTEM_TABLE is used.
1309   @param  BackGround   The background color of the string being printed.  This is
1310                        an optional parameter that may be NULL.  If it is NULL,
1311                        then the background color of the current ConOut device
1312                        in the EFI_SYSTEM_TABLE is used.
1313   @param  Format       A null-terminated ASCII format string.  See Print Library
1314                        for the supported format string syntax.
1315   @param  ...          The variable argument list whose contents are accessed based on
1316                        the format string specified by Format.
1317
1318   @return  The number of ASCII characters printed.
1319
1320 **/
1321 UINTN
1322 EFIAPI
1323 AsciiPrintXY (
1324   IN UINTN                            PointX,
1325   IN UINTN                            PointY,
1326   IN EFI_GRAPHICS_OUTPUT_BLT_PIXEL    *ForeGround, OPTIONAL
1327   IN EFI_GRAPHICS_OUTPUT_BLT_PIXEL    *BackGround, OPTIONAL
1328   IN CONST CHAR8                      *Format,
1329   ...
1330   );
1331
1332
1333 /**
1334   Installs and completes the initialization of a Driver Binding Protocol instance.
1335
1336   Installs the Driver Binding Protocol specified by DriverBinding onto the handle
1337   specified by DriverBindingHandle. If DriverBindingHandle is NULL, then DriverBinding
1338   is installed onto a newly created handle. DriverBindingHandle is typically the same
1339   as the driver's ImageHandle, but it can be different if the driver produces multiple
1340   Driver Binding Protocols.
1341   If DriverBinding is NULL, then ASSERT().
1342   If DriverBinding can not be installed onto a handle, then ASSERT().
1343
1344   @param  ImageHandle          The image handle of the driver.
1345   @param  SystemTable          The EFI System Table that was passed to the driver's entry point.
1346   @param  DriverBinding        A Driver Binding Protocol instance that this driver is producing.
1347   @param  DriverBindingHandle  The handle that DriverBinding is to be installed onto.  If this
1348                                parameter is NULL, then a new handle is created.
1349
1350   @retval EFI_SUCCESS           The protocol installation completed successfully.
1351   @retval EFI_OUT_OF_RESOURCES  There was not enough system resources to install the protocol.
1352   @retval Others                Status from gBS->InstallMultipleProtocolInterfaces().
1353
1354 **/
1355 EFI_STATUS
1356 EFIAPI
1357 EfiLibInstallDriverBinding (
1358   IN CONST EFI_HANDLE             ImageHandle,
1359   IN CONST EFI_SYSTEM_TABLE       *SystemTable,
1360   IN EFI_DRIVER_BINDING_PROTOCOL  *DriverBinding,
1361   IN EFI_HANDLE                   DriverBindingHandle
1362   );
1363
1364
1365 /**
1366   Uninstalls a Driver Binding Protocol instance.
1367
1368   If DriverBinding is NULL, then ASSERT().
1369   If DriverBinding can not be uninstalled, then ASSERT().
1370
1371   @param  DriverBinding        A Driver Binding Protocol instance that this driver produced.
1372
1373   @retval EFI_SUCCESS           The protocol uninstallation successfully completed.
1374   @retval Others                Status from gBS->UninstallMultipleProtocolInterfaces().
1375
1376 **/
1377 EFI_STATUS
1378 EFIAPI
1379 EfiLibUninstallDriverBinding (
1380   IN EFI_DRIVER_BINDING_PROTOCOL  *DriverBinding
1381   );
1382
1383
1384 /**
1385   Installs and completes the initialization of a Driver Binding Protocol instance and
1386   optionally installs the Component Name, Driver Configuration and Driver Diagnostics Protocols.
1387
1388   Initializes a driver by installing the Driver Binding Protocol together with the
1389   optional Component Name, optional Driver Configure and optional Driver Diagnostic
1390   Protocols onto the driver's DriverBindingHandle. If DriverBindingHandle is NULL,
1391   then the protocols are installed onto a newly created handle. DriverBindingHandle
1392   is typically the same as the driver's ImageHandle, but it can be different if the
1393   driver produces multiple Driver Binding Protocols.
1394   If DriverBinding is NULL, then ASSERT().
1395   If the installation fails, then ASSERT().
1396
1397   @param  ImageHandle          The image handle of the driver.
1398   @param  SystemTable          The EFI System Table that was passed to the driver's entry point.
1399   @param  DriverBinding        A Driver Binding Protocol instance that this driver is producing.
1400   @param  DriverBindingHandle  The handle that DriverBinding is to be installed onto.  If this
1401                                parameter is NULL, then a new handle is created.
1402   @param  ComponentName        A Component Name Protocol instance that this driver is producing.
1403   @param  DriverConfiguration  A Driver Configuration Protocol instance that this driver is producing.
1404   @param  DriverDiagnostics    A Driver Diagnostics Protocol instance that this driver is producing.
1405
1406   @retval EFI_SUCCESS           The protocol installation completed successfully.
1407   @retval EFI_OUT_OF_RESOURCES  There was not enough memory in the pool to install all the protocols.
1408
1409 **/
1410 EFI_STATUS
1411 EFIAPI
1412 EfiLibInstallAllDriverProtocols (
1413   IN CONST EFI_HANDLE                         ImageHandle,
1414   IN CONST EFI_SYSTEM_TABLE                   *SystemTable,
1415   IN EFI_DRIVER_BINDING_PROTOCOL              *DriverBinding,
1416   IN EFI_HANDLE                               DriverBindingHandle,
1417   IN CONST EFI_COMPONENT_NAME_PROTOCOL        *ComponentName,       OPTIONAL
1418   IN CONST EFI_DRIVER_CONFIGURATION_PROTOCOL  *DriverConfiguration, OPTIONAL
1419   IN CONST EFI_DRIVER_DIAGNOSTICS_PROTOCOL    *DriverDiagnostics    OPTIONAL
1420   );
1421
1422
1423 /**
1424   Uninstalls a Driver Binding Protocol instance and optionally uninstalls the
1425   Component Name, Driver Configuration and Driver Diagnostics Protocols.
1426
1427   If DriverBinding is NULL, then ASSERT().
1428   If the uninstallation fails, then ASSERT().
1429
1430   @param  DriverBinding        A Driver Binding Protocol instance that this driver produced.
1431   @param  ComponentName        A Component Name Protocol instance that this driver produced.
1432   @param  DriverConfiguration  A Driver Configuration Protocol instance that this driver produced.
1433   @param  DriverDiagnostics    A Driver Diagnostics Protocol instance that this driver produced.
1434
1435   @retval EFI_SUCCESS           The protocol uninstallation successfully completed.
1436   @retval Others                Status from gBS->UninstallMultipleProtocolInterfaces().
1437
1438 **/
1439 EFI_STATUS
1440 EFIAPI
1441 EfiLibUninstallAllDriverProtocols (
1442   IN EFI_DRIVER_BINDING_PROTOCOL              *DriverBinding,
1443   IN CONST EFI_COMPONENT_NAME_PROTOCOL        *ComponentName,       OPTIONAL
1444   IN CONST EFI_DRIVER_CONFIGURATION_PROTOCOL  *DriverConfiguration, OPTIONAL
1445   IN CONST EFI_DRIVER_DIAGNOSTICS_PROTOCOL    *DriverDiagnostics    OPTIONAL
1446   );
1447
1448
1449 /**
1450   Installs Driver Binding Protocol with optional Component Name and Component Name 2 Protocols.
1451
1452   Initializes a driver by installing the Driver Binding Protocol together with the
1453   optional Component Name and optional Component Name 2 protocols onto the driver's
1454   DriverBindingHandle.  If DriverBindingHandle is NULL, then the protocols are installed
1455   onto a newly created handle.  DriverBindingHandle is typically the same as the driver's
1456   ImageHandle, but it can be different if the driver produces multiple Driver Binding Protocols.
1457   If DriverBinding is NULL, then ASSERT().
1458   If the installation fails, then ASSERT().
1459
1460   @param  ImageHandle          The image handle of the driver.
1461   @param  SystemTable          The EFI System Table that was passed to the driver's entry point.
1462   @param  DriverBinding        A Driver Binding Protocol instance that this driver is producing.
1463   @param  DriverBindingHandle  The handle that DriverBinding is to be installed onto.  If this
1464                                parameter is NULL, then a new handle is created.
1465   @param  ComponentName        A Component Name Protocol instance that this driver is producing.
1466   @param  ComponentName2       A Component Name 2 Protocol instance that this driver is producing.
1467
1468   @retval EFI_SUCCESS           The protocol installation completed successfully.
1469   @retval EFI_OUT_OF_RESOURCES  There was not enough memory in pool to install all the protocols.
1470
1471 **/
1472 EFI_STATUS
1473 EFIAPI
1474 EfiLibInstallDriverBindingComponentName2 (
1475   IN CONST EFI_HANDLE                         ImageHandle,
1476   IN CONST EFI_SYSTEM_TABLE                   *SystemTable,
1477   IN EFI_DRIVER_BINDING_PROTOCOL              *DriverBinding,
1478   IN EFI_HANDLE                               DriverBindingHandle,
1479   IN CONST EFI_COMPONENT_NAME_PROTOCOL        *ComponentName,       OPTIONAL
1480   IN CONST EFI_COMPONENT_NAME2_PROTOCOL       *ComponentName2       OPTIONAL
1481   );
1482
1483
1484 /**
1485   Uninstalls Driver Binding Protocol with optional Component Name and Component Name 2 Protocols.
1486
1487   If DriverBinding is NULL, then ASSERT().
1488   If the uninstallation fails, then ASSERT().
1489
1490   @param  DriverBinding        A Driver Binding Protocol instance that this driver produced.
1491   @param  ComponentName        A Component Name Protocol instance that this driver produced.
1492   @param  ComponentName2       A Component Name 2 Protocol instance that this driver produced.
1493
1494   @retval EFI_SUCCESS           The protocol installation successfully completed.
1495   @retval Others                Status from gBS->UninstallMultipleProtocolInterfaces().
1496
1497 **/
1498 EFI_STATUS
1499 EFIAPI
1500 EfiLibUninstallDriverBindingComponentName2 (
1501   IN EFI_DRIVER_BINDING_PROTOCOL              *DriverBinding,
1502   IN CONST EFI_COMPONENT_NAME_PROTOCOL        *ComponentName,       OPTIONAL
1503   IN CONST EFI_COMPONENT_NAME2_PROTOCOL       *ComponentName2       OPTIONAL
1504   );
1505
1506
1507 /**
1508   Installs Driver Binding Protocol with optional Component Name, Component Name 2, Driver
1509   Configuration, Driver Configuration 2, Driver Diagnostics, and Driver Diagnostics 2 Protocols.
1510
1511   Initializes a driver by installing the Driver Binding Protocol together with the optional
1512   Component Name, optional Component Name 2, optional Driver Configuration, optional Driver Configuration 2,
1513   optional Driver Diagnostic, and optional Driver Diagnostic 2 Protocols onto the driver's DriverBindingHandle.
1514   DriverBindingHandle is typically the same as the driver's ImageHandle, but it can be different if the driver
1515   produces multiple Driver Binding Protocols.
1516   If DriverBinding is NULL, then ASSERT().
1517   If the installation fails, then ASSERT().
1518
1519
1520   @param  ImageHandle           The image handle of the driver.
1521   @param  SystemTable           The EFI System Table that was passed to the driver's entry point.
1522   @param  DriverBinding         A Driver Binding Protocol instance that this driver is producing.
1523   @param  DriverBindingHandle   The handle that DriverBinding is to be installed onto.  If this
1524                                 parameter is NULL, then a new handle is created.
1525   @param  ComponentName         A Component Name Protocol instance that this driver is producing.
1526   @param  ComponentName2        A Component Name 2 Protocol instance that this driver is producing.
1527   @param  DriverConfiguration   A Driver Configuration Protocol instance that this driver is producing.
1528   @param  DriverConfiguration2  A Driver Configuration Protocol 2 instance that this driver is producing.
1529   @param  DriverDiagnostics     A Driver Diagnostics Protocol instance that this driver is producing.
1530   @param  DriverDiagnostics2    A Driver Diagnostics Protocol 2 instance that this driver is producing.
1531
1532   @retval EFI_SUCCESS           The protocol installation completed successfully.
1533   @retval EFI_OUT_OF_RESOURCES  There was not enough memory in pool to install all the protocols.
1534
1535 **/
1536 EFI_STATUS
1537 EFIAPI
1538 EfiLibInstallAllDriverProtocols2 (
1539   IN CONST EFI_HANDLE                         ImageHandle,
1540   IN CONST EFI_SYSTEM_TABLE                   *SystemTable,
1541   IN EFI_DRIVER_BINDING_PROTOCOL              *DriverBinding,
1542   IN EFI_HANDLE                               DriverBindingHandle,
1543   IN CONST EFI_COMPONENT_NAME_PROTOCOL        *ComponentName,        OPTIONAL
1544   IN CONST EFI_COMPONENT_NAME2_PROTOCOL       *ComponentName2,       OPTIONAL
1545   IN CONST EFI_DRIVER_CONFIGURATION_PROTOCOL  *DriverConfiguration,  OPTIONAL
1546   IN CONST EFI_DRIVER_CONFIGURATION2_PROTOCOL *DriverConfiguration2, OPTIONAL
1547   IN CONST EFI_DRIVER_DIAGNOSTICS_PROTOCOL    *DriverDiagnostics,    OPTIONAL
1548   IN CONST EFI_DRIVER_DIAGNOSTICS2_PROTOCOL   *DriverDiagnostics2    OPTIONAL
1549   );
1550
1551
1552 /**
1553   Uninstalls Driver Binding Protocol with optional Component Name, Component Name 2, Driver
1554   Configuration, Driver Configuration 2, Driver Diagnostics, and Driver Diagnostics 2 Protocols.
1555
1556   If DriverBinding is NULL, then ASSERT().
1557   If the installation fails, then ASSERT().
1558
1559
1560   @param  DriverBinding         A Driver Binding Protocol instance that this driver produced.
1561   @param  ComponentName         A Component Name Protocol instance that this driver produced.
1562   @param  ComponentName2        A Component Name 2 Protocol instance that this driver produced.
1563   @param  DriverConfiguration   A Driver Configuration Protocol instance that this driver produced.
1564   @param  DriverConfiguration2  A Driver Configuration Protocol 2 instance that this driver produced.
1565   @param  DriverDiagnostics     A Driver Diagnostics Protocol instance that this driver produced.
1566   @param  DriverDiagnostics2    A Driver Diagnostics Protocol 2 instance that this driver produced.
1567
1568   @retval EFI_SUCCESS           The protocol uninstallation successfully completed.
1569   @retval Others                Status from gBS->UninstallMultipleProtocolInterfaces().
1570
1571 **/
1572 EFI_STATUS
1573 EFIAPI
1574 EfiLibUninstallAllDriverProtocols2 (
1575   IN EFI_DRIVER_BINDING_PROTOCOL              *DriverBinding,
1576   IN CONST EFI_COMPONENT_NAME_PROTOCOL        *ComponentName,        OPTIONAL
1577   IN CONST EFI_COMPONENT_NAME2_PROTOCOL       *ComponentName2,       OPTIONAL
1578   IN CONST EFI_DRIVER_CONFIGURATION_PROTOCOL  *DriverConfiguration,  OPTIONAL
1579   IN CONST EFI_DRIVER_CONFIGURATION2_PROTOCOL *DriverConfiguration2, OPTIONAL
1580   IN CONST EFI_DRIVER_DIAGNOSTICS_PROTOCOL    *DriverDiagnostics,    OPTIONAL
1581   IN CONST EFI_DRIVER_DIAGNOSTICS2_PROTOCOL   *DriverDiagnostics2    OPTIONAL
1582   );
1583
1584
1585 /**
1586   Appends a formatted Unicode string to a Null-terminated Unicode string
1587
1588   This function appends a formatted Unicode string to the Null-terminated
1589   Unicode string specified by String.   String is optional and may be NULL.
1590   Storage for the formatted Unicode string returned is allocated using
1591   AllocatePool().  The pointer to the appended string is returned.  The caller
1592   is responsible for freeing the returned string.
1593
1594   If String is not NULL and not aligned on a 16-bit boundary, then ASSERT().
1595   If FormatString is NULL, then ASSERT().
1596   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
1597
1598   @param[in] String         A Null-terminated Unicode string.
1599   @param[in] FormatString   A Null-terminated Unicode format string.
1600   @param[in]  Marker        VA_LIST marker for the variable argument list.
1601
1602   @retval NULL    There was not enough available memory.
1603   @return         Null-terminated Unicode string is that is the formatted
1604                   string appended to String.
1605 **/
1606 CHAR16*
1607 EFIAPI
1608 CatVSPrint (
1609   IN  CHAR16  *String, OPTIONAL
1610   IN  CONST CHAR16  *FormatString,
1611   IN  VA_LIST       Marker
1612   );
1613
1614 /**
1615   Appends a formatted Unicode string to a Null-terminated Unicode string
1616
1617   This function appends a formatted Unicode string to the Null-terminated
1618   Unicode string specified by String.   String is optional and may be NULL.
1619   Storage for the formatted Unicode string returned is allocated using
1620   AllocatePool().  The pointer to the appended string is returned.  The caller
1621   is responsible for freeing the returned string.
1622
1623   If String is not NULL and not aligned on a 16-bit boundary, then ASSERT().
1624   If FormatString is NULL, then ASSERT().
1625   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
1626
1627   @param[in] String         A Null-terminated Unicode string.
1628   @param[in] FormatString   A Null-terminated Unicode format string.
1629   @param[in] ...            The variable argument list whose contents are
1630                             accessed based on the format string specified by
1631                             FormatString.
1632
1633   @retval NULL    There was not enough available memory.
1634   @return         Null-terminated Unicode string is that is the formatted
1635                   string appended to String.
1636 **/
1637 CHAR16 *
1638 EFIAPI
1639 CatSPrint (
1640   IN  CHAR16  *String, OPTIONAL
1641   IN  CONST CHAR16  *FormatString,
1642   ...
1643   );
1644
1645 /**
1646   Returns an array of protocol instance that matches the given protocol.
1647
1648   @param[in]  Protocol      Provides the protocol to search for.
1649   @param[out] NoProtocols   The number of protocols returned in Buffer.
1650   @param[out] Buffer        A pointer to the buffer to return the requested
1651                             array of protocol instances that match Protocol.
1652                             The returned buffer is allocated using
1653                             EFI_BOOT_SERVICES.AllocatePool().  The caller is
1654                             responsible for freeing this buffer with
1655                             EFI_BOOT_SERVICES.FreePool().
1656
1657   @retval EFI_SUCCESS            The array of protocols was returned in Buffer,
1658                                  and the number of protocols in Buffer was
1659                                  returned in NoProtocols.
1660   @retval EFI_NOT_FOUND          No protocols found.
1661   @retval EFI_OUT_OF_RESOURCES   There is not enough pool memory to store the
1662                                  matching results.
1663   @retval EFI_INVALID_PARAMETER  Protocol is NULL.
1664   @retval EFI_INVALID_PARAMETER  NoProtocols is NULL.
1665   @retval EFI_INVALID_PARAMETER  Buffer is NULL.
1666
1667 **/
1668 EFI_STATUS
1669 EFIAPI
1670 EfiLocateProtocolBuffer (
1671   IN  EFI_GUID  *Protocol,
1672   OUT UINTN     *NoProtocols,
1673   OUT VOID      ***Buffer
1674   );
1675
1676 /**
1677   Open or create a file or directory, possibly creating the chain of
1678   directories leading up to the directory.
1679
1680   EfiOpenFileByDevicePath() first locates EFI_SIMPLE_FILE_SYSTEM_PROTOCOL on
1681   FilePath, and opens the root directory of that filesystem with
1682   EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.OpenVolume().
1683
1684   On the remaining device path, the longest initial sequence of
1685   FILEPATH_DEVICE_PATH nodes is node-wise traversed with
1686   EFI_FILE_PROTOCOL.Open().
1687
1688   (As a consequence, if OpenMode includes EFI_FILE_MODE_CREATE, and Attributes
1689   includes EFI_FILE_DIRECTORY, and each FILEPATH_DEVICE_PATH specifies a single
1690   pathname component, then EfiOpenFileByDevicePath() ensures that the specified
1691   series of subdirectories exist on return.)
1692
1693   The EFI_FILE_PROTOCOL identified by the last FILEPATH_DEVICE_PATH node is
1694   output to the caller; intermediate EFI_FILE_PROTOCOL instances are closed. If
1695   there are no FILEPATH_DEVICE_PATH nodes past the node that identifies the
1696   filesystem, then the EFI_FILE_PROTOCOL of the root directory of the
1697   filesystem is output to the caller. If a device path node that is different
1698   from FILEPATH_DEVICE_PATH is encountered relative to the filesystem, the
1699   traversal is stopped with an error, and a NULL EFI_FILE_PROTOCOL is output.
1700
1701   @param[in,out] FilePath  On input, the device path to the file or directory
1702                            to open or create. The caller is responsible for
1703                            ensuring that the device path pointed-to by FilePath
1704                            is well-formed. On output, FilePath points one past
1705                            the last node in the original device path that has
1706                            been successfully processed. FilePath is set on
1707                            output even if EfiOpenFileByDevicePath() returns an
1708                            error.
1709
1710   @param[out] File         On error, File is set to NULL. On success, File is
1711                            set to the EFI_FILE_PROTOCOL of the root directory
1712                            of the filesystem, if there are no
1713                            FILEPATH_DEVICE_PATH nodes in FilePath; otherwise,
1714                            File is set to the EFI_FILE_PROTOCOL identified by
1715                            the last node in FilePath.
1716
1717   @param[in] OpenMode      The OpenMode parameter to pass to
1718                            EFI_FILE_PROTOCOL.Open().
1719
1720   @param[in] Attributes    The Attributes parameter to pass to
1721                            EFI_FILE_PROTOCOL.Open().
1722
1723   @retval EFI_SUCCESS            The file or directory has been opened or
1724                                  created.
1725
1726   @retval EFI_INVALID_PARAMETER  FilePath is NULL; or File is NULL; or FilePath
1727                                  contains a device path node, past the node
1728                                  that identifies
1729                                  EFI_SIMPLE_FILE_SYSTEM_PROTOCOL, that is not a
1730                                  FILEPATH_DEVICE_PATH node.
1731
1732   @retval EFI_OUT_OF_RESOURCES   Memory allocation failed.
1733
1734   @return                        Error codes propagated from the
1735                                  LocateDevicePath() and OpenProtocol() boot
1736                                  services, and from the
1737                                  EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.OpenVolume()
1738                                  and EFI_FILE_PROTOCOL.Open() member functions.
1739 **/
1740 EFI_STATUS
1741 EFIAPI
1742 EfiOpenFileByDevicePath (
1743   IN OUT EFI_DEVICE_PATH_PROTOCOL  **FilePath,
1744   OUT    EFI_FILE_PROTOCOL         **File,
1745   IN     UINT64                    OpenMode,
1746   IN     UINT64                    Attributes
1747   );
1748
1749 /**
1750   This function locates next ACPI table in XSDT/RSDT based on Signature and
1751   previous returned Table.
1752
1753   If PreviousTable is NULL:
1754   This function will locate the first ACPI table in XSDT/RSDT based on
1755   Signature in gEfiAcpi20TableGuid system configuration table first, and then
1756   gEfiAcpi10TableGuid system configuration table.
1757   This function will locate in XSDT first, and then RSDT.
1758   For DSDT, this function will locate XDsdt in FADT first, and then Dsdt in
1759   FADT.
1760   For FACS, this function will locate XFirmwareCtrl in FADT first, and then
1761   FirmwareCtrl in FADT.
1762
1763   If PreviousTable is not NULL:
1764   1. If it could be located in XSDT in gEfiAcpi20TableGuid system configuration
1765      table, then this function will just locate next table in XSDT in
1766      gEfiAcpi20TableGuid system configuration table.
1767   2. If it could be located in RSDT in gEfiAcpi20TableGuid system configuration
1768      table, then this function will just locate next table in RSDT in
1769      gEfiAcpi20TableGuid system configuration table.
1770   3. If it could be located in RSDT in gEfiAcpi10TableGuid system configuration
1771      table, then this function will just locate next table in RSDT in
1772      gEfiAcpi10TableGuid system configuration table.
1773
1774   It's not supported that PreviousTable is not NULL but PreviousTable->Signature
1775   is not same with Signature, NULL will be returned.
1776
1777   @param Signature          ACPI table signature.
1778   @param PreviousTable      Pointer to previous returned table to locate next
1779                             table, or NULL to locate first table.
1780
1781   @return Next ACPI table or NULL if not found.
1782
1783 **/
1784 EFI_ACPI_COMMON_HEADER *
1785 EFIAPI
1786 EfiLocateNextAcpiTable (
1787   IN UINT32                     Signature,
1788   IN EFI_ACPI_COMMON_HEADER     *PreviousTable OPTIONAL
1789   );
1790
1791 /**
1792   This function locates first ACPI table in XSDT/RSDT based on Signature.
1793
1794   This function will locate the first ACPI table in XSDT/RSDT based on
1795   Signature in gEfiAcpi20TableGuid system configuration table first, and then
1796   gEfiAcpi10TableGuid system configuration table.
1797   This function will locate in XSDT first, and then RSDT.
1798   For DSDT, this function will locate XDsdt in FADT first, and then Dsdt in
1799   FADT.
1800   For FACS, this function will locate XFirmwareCtrl in FADT first, and then
1801   FirmwareCtrl in FADT.
1802
1803   @param Signature          ACPI table signature.
1804
1805   @return First ACPI table or NULL if not found.
1806
1807 **/
1808 EFI_ACPI_COMMON_HEADER *
1809 EFIAPI
1810 EfiLocateFirstAcpiTable (
1811   IN UINT32                     Signature
1812   );
1813
1814 #endif