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