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