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