MdePkg/Include/Library/UefiLib.h

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