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