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