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