MdePkg/Include/Library/UefiLib.h

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