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