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 /**
 424   This function adds a Unicode string to UnicodeStringTable.
 425   If Language is a member of SupportedLanguages then UnicodeString is added to
 426   UnicodeStringTable.  New buffers are allocated for both Language and
 427   UnicodeString.  The contents of Language and UnicodeString are copied into
 428   these new buffers.  These buffers are automatically freed when
 429   FreeUnicodeStringTable() is called.
 430
 431   @param  Language                A pointer to the ISO 639-2 language code for the Unicode
 432                                   string to add.
 433   @param  SupportedLanguages      A pointer to the set of ISO 639-2 language codes
 434                                   that the Unicode string table supports.
 435                                   Language must be a member of this set.
 436   @param  UnicodeStringTable      A pointer to the table of Unicode strings.
 437   @param  UnicodeString           A pointer to the Unicode string to add.
 438
 439   @retval EFI_SUCCESS             The Unicode string that matches the language
 440                                   specified by Language was found in the table of
 441                                   Unicode strings UnicodeStringTable, and it was
 442                                   returned in UnicodeString.
 443   @retval EFI_INVALID_PARAMETER   Language is NULL.
 444   @retval EFI_INVALID_PARAMETER   UnicodeString is NULL.
 445   @retval EFI_INVALID_PARAMETER   UnicodeString is an empty string.
 446   @retval EFI_UNSUPPORTED         SupportedLanguages is NULL.
 447   @retval EFI_ALREADY_STARTED     A Unicode string with language Language is
 448                                   already present in UnicodeStringTable.
 449   @retval EFI_OUT_OF_RESOURCES    There is not enough memory to add another
 450                                   Unicode string to UnicodeStringTable.
 451   @retval EFI_UNSUPPORTED         The language specified by Language is not a
 452                                   member of SupportedLanguages.
 453
 454 **/
 455 EFI_STATUS
 456 EFIAPI
 457 AddUnicodeString (
 458   IN CONST CHAR8               *Language,
 459   IN CONST CHAR8               *SupportedLanguages,
 460   IN EFI_UNICODE_STRING_TABLE  **UnicodeStringTable,
 461   IN CONST CHAR16              *UnicodeString
 462   );
 463
 464 /**
 465
 466   This function adds a Unicode string to UnicodeStringTable.
 467   If Language is a member of SupportedLanguages then
 468   UnicodeString is added to UnicodeStringTable.  New buffers are
 469   allocated for both Language and UnicodeString.  The contents
 470   of Language and UnicodeString are copied into these new
 471   buffers.  These buffers are automatically freed when
 472   FreeUnicodeStringTable() is called.
 473
 474   @param  Language                A pointer to the ISO 639-2 or
 475                                   RFC 3066 language code for the
 476                                   Unicode string to add.
 477
 478   @param  SupportedLanguages      A pointer to the set of ISO
 479                                   639-2 or RFC 3066 language
 480                                   codes that the Unicode string
 481                                   table supports. Language must
 482                                   be a member of this set.
 483
 484   @param  UnicodeStringTable      A pointer to the table of
 485                                   Unicode strings.
 486
 487   @param  UnicodeString           A pointer to the Unicode
 488                                   string to add.
 489
 490   @param  Iso639Language          Specify the language code
 491                                   format supported. If true,
 492                                   then the format follow ISO
 493                                   639-2. If false, then it
 494                                   follows RFC3066.
 495
 496   @retval EFI_SUCCESS             The Unicode string that
 497                                   matches the language specified
 498                                   by Language was found in the
 499                                   table of Unicode strings
 500                                   UnicodeStringTable, and it was
 501                                   returned in UnicodeString.
 502
 503   @retval EFI_INVALID_PARAMETER   Language is NULL.
 504
 505   @retval EFI_INVALID_PARAMETER   UnicodeString is NULL.
 506
 507   @retval EFI_INVALID_PARAMETER   UnicodeString is an empty string.
 508
 509   @retval EFI_UNSUPPORTED         SupportedLanguages is NULL.
 510
 511   @retval EFI_ALREADY_STARTED     A Unicode string with language
 512                                   Language is already present in
 513                                   UnicodeStringTable.
 514
 515   @retval EFI_OUT_OF_RESOURCES    There is not enough memory to
 516                                   add another Unicode string to
 517                                   UnicodeStringTable.
 518
 519   @retval EFI_UNSUPPORTED         The language specified by
 520                                   Language is not a member of
 521                                   SupportedLanguages.
 522
 523 **/
 524 EFI_STATUS
 525 EFIAPI
 526 AddUnicodeString2 (
 527   IN CONST CHAR8               *Language,
 528   IN CONST CHAR8               *SupportedLanguages,
 529   IN EFI_UNICODE_STRING_TABLE  **UnicodeStringTable,
 530   IN CONST CHAR16              *UnicodeString,
 531   IN BOOLEAN                   Iso639Language
 532   )
 533 ;
 534
 535 /**
 536   This function frees the table of Unicode strings in UnicodeStringTable.
 537   If UnicodeStringTable is NULL, then EFI_SUCCESS is returned.
 538   Otherwise, each language code, and each Unicode string in the Unicode string
 539   table are freed, and EFI_SUCCESS is returned.
 540
 541   @param  UnicodeStringTable  A pointer to the table of Unicode strings.
 542
 543   @retval EFI_SUCCESS         The Unicode string table was freed.
 544
 545 **/
 546 EFI_STATUS
 547 EFIAPI
 548 FreeUnicodeStringTable (
 549   IN EFI_UNICODE_STRING_TABLE  *UnicodeStringTable
 550   );
 551
 552 /**
 553   This function computes and returns the width of the Unicode character
 554   specified by UnicodeChar.
 555
 556   @param  UnicodeChar   A Unicode character.
 557
 558   @retval 0             The width if UnicodeChar could not be determined.
 559   @retval 1             UnicodeChar is a narrow glyph.
 560   @retval 2             UnicodeChar is a wide glyph.
 561
 562 **/
 563 UINTN
 564 EFIAPI
 565 GetGlyphWidth (
 566   IN CHAR16  UnicodeChar
 567   );
 568
 569 /**
 570   This function computes and returns the display length of
 571   the Null-terminated Unicode string specified by String.
 572   If String is NULL, then 0 is returned.
 573   If any of the widths of the Unicode characters in String
 574   can not be determined, then 0 is returned.
 575
 576   @param  String      A pointer to a Null-terminated Unicode string.
 577
 578   @return The display length of the Null-terminated Unicode string specified by String.
 579
 580 **/
 581 UINTN
 582 EFIAPI
 583 UnicodeStringDisplayLength (
 584   IN CONST CHAR16  *String
 585   );
 586
 587 //
 588 // Functions that abstract early Framework contamination of UEFI.
 589 //
 590 /**
 591   Signal a Ready to Boot Event.
 592
 593   Create a Ready to Boot Event. Signal it and close it. This causes other
 594   events of the same event group to be signaled in other modules.
 595
 596 **/
 597 VOID
 598 EFIAPI
 599 EfiSignalEventReadyToBoot (
 600   VOID
 601   );
 602
 603 /**
 604   Signal a Legacy Boot Event.
 605
 606   Create a legacy Boot Event. Signal it and close it. This causes other
 607   events of the same event group to be signaled in other modules.
 608
 609 **/
 610 VOID
 611 EFIAPI
 612 EfiSignalEventLegacyBoot (
 613   VOID
 614   );
 615
 616 /**
 617   Create a Legacy Boot Event.
 618
 619   Tiano extended the CreateEvent Type enum to add a legacy boot event type.
 620   This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was
 621   added and now it's possible to not voilate the UEFI specification by
 622   declaring a GUID for the legacy boot event class. This library supports
 623   the EDK/EFI 1.10 form and EDK II/UEFI 2.0 form and allows common code to
 624   work both ways.
 625
 626   @param  LegacyBootEvent   Returns the EFI event returned from gBS->CreateEvent(Ex).
 627
 628   @retval EFI_SUCCESS       Event was created.
 629   @retval Other             Event was not created.
 630
 631 **/
 632 EFI_STATUS
 633 EFIAPI
 634 EfiCreateEventLegacyBoot (
 635   OUT EFI_EVENT  *LegacyBootEvent
 636   );
 637
 638 /**
 639   Create an EFI event in the Legacy Boot Event Group and allows
 640   the caller to specify a notification function.
 641
 642   This function abstracts the creation of the Legacy Boot Event.
 643   The Framework moved from a proprietary to UEFI 2.0 based mechanism.
 644   This library abstracts the caller from how this event is created to prevent
 645   to code form having to change with the version of the specification supported.
 646   If LegacyBootEvent is NULL, then ASSERT().
 647
 648   @param  NotifyTpl         The task priority level of the event.
 649   @param  NotifyFunction    The notification function to call when the event is signaled.
 650   @param  NotifyContext     The content to pass to NotifyFunction when the event is signaled.
 651   @param  LegacyBootEvent   Returns the EFI event returned from gBS->CreateEvent(Ex).
 652
 653   @retval EFI_SUCCESS       Event was created.
 654   @retval Other             Event was not created.
 655
 656 **/
 657 EFI_STATUS
 658 EFIAPI
 659 EfiCreateEventLegacyBootEx (
 660   IN  EFI_TPL           NotifyTpl,
 661   IN  EFI_EVENT_NOTIFY  NotifyFunction,  OPTIONAL
 662   IN  VOID              *NotifyContext,  OPTIONAL
 663   OUT EFI_EVENT         *LegacyBootEvent
 664   );
 665
 666 /**
 667   Create a Read to Boot Event.
 668
 669   Tiano extended the CreateEvent Type enum to add a ready to boot event type.
 670   This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was
 671   added and now it's possible to not voilate the UEFI specification and use
 672   the ready to boot event class defined in UEFI 2.0. This library supports
 673   the EDK/EFI 1.10 form and EDKII/UEFI 2.0 form and allows common code to
 674   work both ways.
 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   Tiano extended the EFI 1.10 device path nodes. Tiano does not own this enum
 720   so as we move to UEFI 2.0 support we must use a mechanism that conforms with
 721   the UEFI 2.0 specification to define the FV device path. An UEFI GUIDed
 722   device path is defined for Tiano extensions of device path. If the code
 723   is compiled to conform with the UEFI 2.0 specification use the new device path
 724   else use the old form for backwards compatability.
 725
 726   @param  FvDevicePathNode  Pointer to a FV device path node to initialize
 727   @param  NameGuid          FV file name to use in FvDevicePathNode
 728
 729 **/
 730 VOID
 731 EFIAPI
 732 EfiInitializeFwVolDevicepathNode (
 733   IN OUT MEDIA_FW_VOL_FILEPATH_DEVICE_PATH  *FvDevicePathNode,
 734   IN CONST EFI_GUID                         *NameGuid
 735   );
 736
 737 /**
 738   Check to see if the Firmware Volume (FV) Media Device Path is valid
 739
 740   Tiano extended the EFI 1.10 device path nodes. Tiano does not own this enum
 741   so as we move to UEFI 2.0 support we must use a mechanism that conforms with
 742   the UEFI 2.0 specification to define the FV device path. An UEFI GUIDed
 743   device path is defined for Tiano extensions of device path. If the code
 744   is compiled to conform with the UEFI 2.0 specification use the new device path
 745   else use the old form for backwards compatability. The return value to this
 746   function points to a location in FvDevicePathNode and it does not allocate
 747   new memory for the GUID pointer that is returned.
 748
 749   @param  FvDevicePathNode  Pointer to FV device path to check.
 750
 751   @retval NULL              FvDevicePathNode is not valid.
 752   @retval Other             FvDevicePathNode is valid and pointer to NameGuid was returned.
 753
 754 **/
 755 EFI_GUID *
 756 EFIAPI
 757 EfiGetNameGuidFromFwVolDevicePathNode (
 758   IN CONST MEDIA_FW_VOL_FILEPATH_DEVICE_PATH  *FvDevicePathNode
 759   );
 760
 761 /**
 762   Prints a formatted Unicode string to the console output device specified by
 763   ConOut defined in the EFI_SYSTEM_TABLE.
 764
 765   This function prints a formatted Unicode string to the console output device
 766   specified by ConOut in EFI_SYSTEM_TABLE and returns the number of Unicode
 767   characters that printed to ConOut.  If the length of the formatted Unicode
 768   string is greater than PcdUefiLibMaxPrintBufferSize, then only the first
 769   PcdUefiLibMaxPrintBufferSize characters are sent to ConOut.
 770
 771   @param Format   Null-terminated Unicode format string.
 772   @param ...      VARARG list consumed to process Format.
 773   If Format is NULL, then ASSERT().
 774   If Format is not aligned on a 16-bit boundary, then ASSERT().
 775
 776   @return Number of Unicode characters printed to ConOut.
 777
 778 **/
 779 UINTN
 780 EFIAPI
 781 Print (
 782   IN CONST CHAR16  *Format,
 783   ...
 784   );
 785
 786 /**
 787   Prints a formatted Unicode string to the console output device specified by
 788   StdErr defined in the EFI_SYSTEM_TABLE.
 789
 790   This function prints a formatted Unicode string to the console output device
 791   specified by StdErr in EFI_SYSTEM_TABLE and returns the number of Unicode
 792   characters that printed to StdErr.  If the length of the formatted Unicode
 793   string is greater than PcdUefiLibMaxPrintBufferSize, then only the first
 794   PcdUefiLibMaxPrintBufferSize characters are sent to StdErr.
 795
 796   @param Format   Null-terminated Unicode format string.
 797   @param ...      VARARG list consumed to process Format.
 798   If Format is NULL, then ASSERT().
 799   If Format is not aligned on a 16-bit boundary, then ASSERT().
 800
 801   @return Number of Unicode characters printed to StdErr.
 802
 803 **/
 804 UINTN
 805 EFIAPI
 806 ErrorPrint (
 807   IN CONST CHAR16  *Format,
 808   ...
 809   );
 810
 811 /**
 812   Prints a formatted ASCII string to the console output device specified by
 813   ConOut defined in the EFI_SYSTEM_TABLE.
 814
 815   This function prints a formatted ASCII string to the console output device
 816   specified by ConOut in EFI_SYSTEM_TABLE and returns the number of ASCII
 817   characters that printed to ConOut.  If the length of the formatted ASCII
 818   string is greater than PcdUefiLibMaxPrintBufferSize, then only the first
 819   PcdUefiLibMaxPrintBufferSize characters are sent to ConOut.
 820
 821   @param Format   Null-terminated ASCII format string.
 822   @param ...      VARARG list consumed to process Format.
 823   If Format is NULL, then ASSERT().
 824   If Format is not aligned on a 16-bit boundary, then ASSERT().
 825
 826   @return Number of ASCII characters printed to ConOut.
 827
 828 **/
 829 UINTN
 830 EFIAPI
 831 AsciiPrint (
 832   IN CONST CHAR8  *Format,
 833   ...
 834   );
 835
 836 /**
 837   Prints a formatted ASCII string to the console output device specified by
 838   StdErr defined in the EFI_SYSTEM_TABLE.
 839
 840   This function prints a formatted ASCII string to the console output device
 841   specified by StdErr in EFI_SYSTEM_TABLE and returns the number of ASCII
 842   characters that printed to StdErr.  If the length of the formatted ASCII
 843   string is greater than PcdUefiLibMaxPrintBufferSize, then only the first
 844   PcdUefiLibMaxPrintBufferSize characters are sent to StdErr.
 845
 846   @param Format   Null-terminated ASCII format string.
 847   @param ...      VARARG list consumed to process Format.
 848   If Format is NULL, then ASSERT().
 849   If Format is not aligned on a 16-bit boundary, then ASSERT().
 850
 851   @return Number of ASCII characters printed to ConErr.
 852
 853 **/
 854 UINTN
 855 EFIAPI
 856 AsciiErrorPrint (
 857   IN CONST CHAR8  *Format,
 858   ...
 859   );
 860
 861 /**
 862   Initializes a driver by installing the Driver Binding Protocol onto the driver's
 863   DriverBindingHandle.  This is typically the same as the driver's ImageHandle, but
 864   it can be different if the driver produces multiple DriverBinding Protocols.
 865   If the Driver Binding Protocol interface is NULL, then ASSERT ().
 866   If the installation fails, then ASSERT ().
 867
 868   @param  ImageHandle                 The image handle of the driver.
 869   @param  SystemTable                 The EFI System Table that was passed to the driver's entry point.
 870   @param  DriverBinding               A Driver Binding Protocol instance that this driver is producing.
 871   @param  DriverBindingHandle         The handle that DriverBinding is to be installed onto.  If this
 872                                       parameter is NULL, then a new handle is created.
 873
 874   @retval EFI_SUCCESS                 The protocol installation is completed successfully.
 875   @retval Others                      Status from gBS->InstallMultipleProtocolInterfaces().
 876
 877 **/
 878 EFI_STATUS
 879 EFIAPI
 880 EfiLibInstallDriverBinding (
 881   IN CONST EFI_HANDLE             ImageHandle,
 882   IN CONST EFI_SYSTEM_TABLE       *SystemTable,
 883   IN EFI_DRIVER_BINDING_PROTOCOL  *DriverBinding,
 884   IN EFI_HANDLE                   DriverBindingHandle
 885   );
 886
 887
 888 /**
 889   Initializes a driver by installing the Driver Binding Protocol together with the optional Component Name,
 890   Driver Configure and Driver Diagnostic Protocols onto the driver's DriverBindingHandle.  This is
 891   typically the same as the driver's ImageHandle, but it can be different if the driver produces multiple
 892   DriverBinding Protocols.
 893   If the Driver Binding Protocol interface is NULL, then ASSERT ().
 894   If the installation fails, then ASSERT ().
 895
 896   @param  ImageHandle                 The image handle of the driver.
 897   @param  SystemTable                 The EFI System Table that was passed to the driver's entry point.
 898   @param  DriverBinding               A Driver Binding Protocol instance that this driver is producing.
 899   @param  DriverBindingHandle         The handle that DriverBinding is to be installed onto.  If this
 900                                       parameter is NULL, then a new handle is created.
 901   @param  ComponentName               A Component Name Protocol instance that this driver is producing.
 902   @param  DriverConfiguration         A Driver Configuration Protocol instance that this driver is producing.
 903   @param  DriverDiagnostics           A Driver Diagnostics Protocol instance that this driver is producing.
 904
 905   @retval EFI_SUCCESS                 The protocol installation is completed successfully.
 906   @retval Others                      Status from gBS->InstallMultipleProtocolInterfaces().
 907
 908 **/
 909 EFI_STATUS
 910 EFIAPI
 911 EfiLibInstallAllDriverProtocols (
 912   IN CONST EFI_HANDLE                         ImageHandle,
 913   IN CONST EFI_SYSTEM_TABLE                   *SystemTable,
 914   IN EFI_DRIVER_BINDING_PROTOCOL              *DriverBinding,
 915   IN EFI_HANDLE                               DriverBindingHandle,
 916   IN CONST EFI_COMPONENT_NAME_PROTOCOL        *ComponentName,       OPTIONAL
 917   IN CONST EFI_DRIVER_CONFIGURATION_PROTOCOL  *DriverConfiguration, OPTIONAL
 918   IN CONST EFI_DRIVER_DIAGNOSTICS_PROTOCOL    *DriverDiagnostics    OPTIONAL
 919   );
 920
 921
 922
 923 /**
 924   Initializes a driver by installing the Driver Binding Protocol together with the optional Component Name,
 925   Component Name 2 onto the driver's DriverBindingHandle.  This is typically the same as the driver's
 926   ImageHandle, but it can be different if the driver produces multiple DriverBinding Protocols.
 927   If the Driver Binding Protocol interface is NULL, then ASSERT ().
 928   If the installation fails, then ASSERT ().
 929
 930   @param  ImageHandle                 The image handle of the driver.
 931   @param  SystemTable                 The EFI System Table that was passed to the driver's entry point.
 932   @param  DriverBinding               A Driver Binding Protocol instance that this driver is producing.
 933   @param  DriverBindingHandle         The handle that DriverBinding is to be installed onto.  If this
 934                                       parameter is NULL, then a new handle is created.
 935   @param  ComponentName               A Component Name Protocol instance that this driver is producing.
 936   @param  ComponentName2              A Component Name 2 Protocol instance that this driver is producing.
 937
 938   @retval EFI_SUCCESS                 The protocol installation is completed successfully.
 939   @retval Others                      Status from gBS->InstallMultipleProtocolInterfaces().
 940
 941 **/
 942 EFI_STATUS
 943 EFIAPI
 944 EfiLibInstallDriverBindingComponentName2 (
 945   IN CONST EFI_HANDLE                         ImageHandle,
 946   IN CONST EFI_SYSTEM_TABLE                   *SystemTable,
 947   IN EFI_DRIVER_BINDING_PROTOCOL              *DriverBinding,
 948   IN EFI_HANDLE                               DriverBindingHandle,
 949   IN CONST EFI_COMPONENT_NAME_PROTOCOL        *ComponentName,       OPTIONAL
 950   IN CONST EFI_COMPONENT_NAME2_PROTOCOL       *ComponentName2       OPTIONAL
 951   );
 952
 953
 954 /**
 955   Initializes a driver by installing the Driver Binding Protocol together with the optional Component Name,
 956   Component Name 2, Driver Configure, Driver Diagnostic and Driver Diagnostic 2 Protocols onto the driver's
 957   DriverBindingHandle.  This is typically the same as the driver's ImageHandle, but it can be different if
 958   the driver produces multiple DriverBinding Protocols.
 959   If the Driver Binding Protocol interface is NULL, then ASSERT ().
 960   If the installation fails, then ASSERT ().
 961
 962   @param  ImageHandle                 The image handle of the driver.
 963   @param  SystemTable                 The EFI System Table that was passed to the driver's entry point.
 964   @param  DriverBinding               A Driver Binding Protocol instance that this driver is producing.
 965   @param  DriverBindingHandle         The handle that DriverBinding is to be installed onto.  If this
 966                                       parameter is NULL, then a new handle is created.
 967   @param  ComponentName               A Component Name Protocol instance that this driver is producing.
 968   @param  ComponentName2              A Component Name 2 Protocol instance that this driver is producing.
 969   @param  DriverConfiguration         A Driver Configuration Protocol instance that this driver is producing.
 970   @param  DriverDiagnostics           A Driver Diagnostics Protocol instance that this driver is producing.
 971   @param  DriverDiagnostics2          A Driver Diagnostics Protocol 2 instance that this driver is producing.
 972
 973   @retval EFI_SUCCESS                 The protocol installation is completed successfully.
 974   @retval Others                      Status from gBS->InstallMultipleProtocolInterfaces().
 975
 976 **/
 977 EFI_STATUS
 978 EFIAPI
 979 EfiLibInstallAllDriverProtocols2 (
 980   IN CONST EFI_HANDLE                         ImageHandle,
 981   IN CONST EFI_SYSTEM_TABLE                   *SystemTable,
 982   IN EFI_DRIVER_BINDING_PROTOCOL              *DriverBinding,
 983   IN EFI_HANDLE                               DriverBindingHandle,
 984   IN CONST EFI_COMPONENT_NAME_PROTOCOL        *ComponentName,       OPTIONAL
 985   IN CONST EFI_COMPONENT_NAME2_PROTOCOL       *ComponentName2,      OPTIONAL
 986   IN CONST EFI_DRIVER_CONFIGURATION_PROTOCOL  *DriverConfiguration, OPTIONAL
 987   IN CONST EFI_DRIVER_DIAGNOSTICS_PROTOCOL    *DriverDiagnostics,   OPTIONAL
 988   IN CONST EFI_DRIVER_DIAGNOSTICS2_PROTOCOL   *DriverDiagnostics2   OPTIONAL
 989   );
 990
 991 #endif