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