EdkCompatibilityPkg/Foundation/Library/Dxe/Include/EfiDriverLib.h

   1 /*++
   2
   3 Copyright (c) 2004 - 2008, Intel Corporation
   4 All rights reserved. This program and the accompanying materials
   5 are licensed and made available under the terms and conditions of the BSD License
   6 which accompanies this distribution.  The full text of the license may be found at
   7 http://opensource.org/licenses/bsd-license.php
   8
   9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12 Module Name:
  13
  14   EfiDriverLib.h
  15
  16 Abstract:
  17
  18   Light weight lib to support EFI drivers.
  19
  20 --*/
  21
  22 #ifndef _EFI_DRIVER_LIB_H_
  23 #define _EFI_DRIVER_LIB_H_
  24
  25 #include "EfiStatusCode.h"
  26 #include "EfiCommonLib.h"
  27 #include "EfiPerf.h"
  28 #include "LinkedList.h"
  29 #include "GetImage.h"
  30 #include "EfiImageFormat.h"
  31 #include "EfiCompNameSupport.h"
  32
  33 #include EFI_GUID_DEFINITION (DxeServices)
  34 #include EFI_GUID_DEFINITION (EventGroup)
  35 #include EFI_GUID_DEFINITION (EventLegacyBios)
  36 #include EFI_GUID_DEFINITION (FrameworkDevicePath)
  37 #include EFI_PROTOCOL_DEFINITION (FirmwareVolume)
  38 #include EFI_PROTOCOL_DEFINITION (FirmwareVolume2)
  39 #include EFI_PROTOCOL_DEFINITION (DataHub)
  40 #include EFI_PROTOCOL_DEFINITION (DriverBinding)
  41 #include EFI_PROTOCOL_DEFINITION (ComponentName)
  42 #include EFI_PROTOCOL_DEFINITION (ComponentName2)
  43 #include EFI_PROTOCOL_DEFINITION (DriverConfiguration)
  44 #include EFI_PROTOCOL_DEFINITION (DriverConfiguration2)
  45 #include EFI_PROTOCOL_DEFINITION (DriverDiagnostics)
  46 #include EFI_PROTOCOL_DEFINITION (DriverDiagnostics2)
  47
  48 #include EFI_PROTOCOL_DEFINITION (DebugMask)
  49
  50 typedef struct {
  51   CHAR8   *Language;
  52   CHAR16  *UnicodeString;
  53 } EFI_UNICODE_STRING_TABLE;
  54 #if (EFI_SPECIFICATION_VERSION >= 0x00020000)
  55 #define LANGUAGE_RFC_3066
  56 #define LANGUAGE_CODE_ENGLISH    "en-US"
  57 #else
  58 #define LANGUAGE_ISO_639_2
  59 #define LANGUAGE_CODE_ENGLISH    "eng"
  60 #endif
  61
  62 //
  63 // Macros for EFI Driver Library Functions that are really EFI Boot Services
  64 //
  65 #define EfiCopyMem(_Destination, _Source, _Length)  gBS->CopyMem ((_Destination), (_Source), (_Length))
  66 #define EfiSetMem(_Destination, _Length, _Value)    gBS->SetMem ((_Destination), (_Length), (_Value))
  67 #define EfiZeroMem(_Destination, _Length)           gBS->SetMem ((_Destination), (_Length), 0)
  68
  69 //
  70 // Driver Lib Globals.
  71 //
  72 extern EFI_BOOT_SERVICES        *gBS;
  73 extern EFI_DXE_SERVICES         *gDS;
  74 extern EFI_RUNTIME_SERVICES     *gRT;
  75 extern EFI_SYSTEM_TABLE         *gST;
  76 extern UINTN                    gErrorLevel;
  77 extern EFI_GUID                 gEfiCallerIdGuid;
  78 extern EFI_DEBUG_MASK_PROTOCOL  *gDebugMaskInterface;
  79
  80 EFI_STATUS
  81 EfiInitializeDriverLib (
  82   IN EFI_HANDLE           ImageHandle,
  83   IN EFI_SYSTEM_TABLE     *SystemTable
  84   )
  85 /*++
  86
  87 Routine Description:
  88
  89   Intialize Driver Lib if it has not yet been initialized.
  90
  91 Arguments:
  92
  93   ImageHandle     - The firmware allocated handle for the EFI image.
  94
  95   SystemTable     - A pointer to the EFI System Table.
  96
  97
  98 Returns:
  99
 100   EFI_STATUS always returns EFI_SUCCESS
 101
 102 --*/
 103 ;
 104
 105 EFI_STATUS
 106 DxeInitializeDriverLib (
 107   IN EFI_HANDLE           ImageHandle,
 108   IN EFI_SYSTEM_TABLE     *SystemTable
 109   )
 110 /*++
 111
 112 Routine Description:
 113
 114   Intialize Driver Lib if it has not yet been initialized.
 115
 116 Arguments:
 117
 118   ImageHandle     - The firmware allocated handle for the EFI image.
 119
 120   SystemTable     - A pointer to the EFI System Table.
 121
 122 Returns:
 123
 124   EFI_STATUS always returns EFI_SUCCESS
 125
 126 --*/
 127 ;
 128
 129 EFI_STATUS
 130 EfiLibInstallDriverBinding (
 131   IN EFI_HANDLE                   ImageHandle,
 132   IN EFI_SYSTEM_TABLE             *SystemTable,
 133   IN EFI_DRIVER_BINDING_PROTOCOL  *DriverBinding,
 134   IN EFI_HANDLE                   DriverBindingHandle
 135   )
 136 /*++
 137
 138 Routine Description:
 139
 140   Intialize a driver by installing the Driver Binding Protocol onto the
 141   driver's DriverBindingHandle.  This is typically the same as the driver's
 142   ImageHandle, but it can be different if the driver produces multiple
 143   DriverBinding Protocols.  This function also initializes the EFI Driver
 144   Library that initializes the global variables gST, gBS, gRT.
 145
 146 Arguments:
 147
 148   ImageHandle         - The image handle of the driver
 149
 150   SystemTable         - The EFI System Table that was passed to the driver's entry point
 151
 152   DriverBinding       - A Driver Binding Protocol instance that this driver is producing
 153
 154   DriverBindingHandle - The handle that DriverBinding is to be installe onto.  If this
 155                         parameter is NULL, then a new handle is created.
 156
 157 Returns:
 158
 159   EFI_SUCCESS is DriverBinding is installed onto DriverBindingHandle
 160
 161   Otherwise, then return status from gBS->InstallProtocolInterface()
 162
 163 --*/
 164 ;
 165
 166 EFI_STATUS
 167 EfiLibInstallAllDriverProtocols (
 168   IN EFI_HANDLE                         ImageHandle,
 169   IN EFI_SYSTEM_TABLE                   *SystemTable,
 170   IN EFI_DRIVER_BINDING_PROTOCOL        *DriverBinding,
 171   IN EFI_HANDLE                         DriverBindingHandle,
 172   IN EFI_COMPONENT_NAME_PROTOCOL        *ComponentName, OPTIONAL
 173   IN EFI_DRIVER_CONFIGURATION_PROTOCOL  *DriverConfiguration, OPTIONAL
 174   IN EFI_DRIVER_DIAGNOSTICS_PROTOCOL    *DriverDiagnostics OPTIONAL
 175   )
 176 /*++
 177
 178 Routine Description:
 179
 180   Intialize a driver by installing the Driver Binding Protocol onto the
 181   driver's DriverBindingHandle.  This is typically the same as the driver's
 182   ImageHandle, but it can be different if the driver produces multiple
 183   DriverBinding Protocols.  This function also initializes the EFI Driver
 184   Library that initializes the global variables gST, gBS, gRT.
 185
 186 Arguments:
 187
 188   ImageHandle         - The image handle of the driver
 189
 190   SystemTable         - The EFI System Table that was passed to the driver's entry point
 191
 192   DriverBinding       - A Driver Binding Protocol instance that this driver is producing
 193
 194   DriverBindingHandle - The handle that DriverBinding is to be installe onto.  If this
 195                         parameter is NULL, then a new handle is created.
 196
 197   ComponentName       - A Component Name Protocol instance that this driver is producing
 198
 199   DriverConfiguration - A Driver Configuration Protocol instance that this driver is producing
 200
 201   DriverDiagnostics   - A Driver Diagnostics Protocol instance that this driver is producing
 202
 203 Returns:
 204
 205   EFI_SUCCESS if all the protocols were installed onto DriverBindingHandle
 206
 207   Otherwise, then return status from gBS->InstallProtocolInterface()
 208
 209 --*/
 210 ;
 211
 212 EFI_STATUS
 213 EfiLibInstallAllDriverProtocols2 (
 214   IN EFI_HANDLE                         ImageHandle,
 215   IN EFI_SYSTEM_TABLE                   *SystemTable,
 216   IN EFI_DRIVER_BINDING_PROTOCOL        *DriverBinding,
 217   IN EFI_HANDLE                         DriverBindingHandle,
 218   IN EFI_COMPONENT_NAME2_PROTOCOL       *ComponentName2, OPTIONAL
 219   IN EFI_DRIVER_CONFIGURATION2_PROTOCOL *DriverConfiguration2, OPTIONAL
 220   IN EFI_DRIVER_DIAGNOSTICS2_PROTOCOL   *DriverDiagnostics2 OPTIONAL
 221   )
 222 /*++
 223
 224 Routine Description:
 225
 226   Intialize a driver by installing the Driver Binding Protocol onto the
 227   driver's DriverBindingHandle.  This is typically the same as the driver's
 228   ImageHandle, but it can be different if the driver produces multiple
 229   DriverBinding Protocols.  This function also initializes the EFI Driver
 230   Library that initializes the global variables gST, gBS, gRT.
 231
 232 Arguments:
 233
 234   ImageHandle         - The image handle of the driver
 235
 236   SystemTable         - The EFI System Table that was passed to the driver's entry point
 237
 238   DriverBinding       - A Driver Binding Protocol instance that this driver is producing
 239
 240   DriverBindingHandle - The handle that DriverBinding is to be installe onto.  If this
 241                         parameter is NULL, then a new handle is created.
 242
 243   ComponentName2      - A Component Name2 Protocol instance that this driver is producing
 244
 245   DriverConfiguration2- A Driver Configuration2 Protocol instance that this driver is producing
 246
 247   DriverDiagnostics2  - A Driver Diagnostics2 Protocol instance that this driver is producing
 248
 249 Returns:
 250
 251   EFI_SUCCESS if all the protocols were installed onto DriverBindingHandle
 252
 253   Otherwise, then return status from gBS->InstallProtocolInterface()
 254
 255 --*/
 256 ;
 257
 258 EFI_STATUS
 259 EfiLibGetSystemConfigurationTable (
 260   IN EFI_GUID *TableGuid,
 261   OUT VOID **Table
 262   )
 263 /*++
 264
 265 Routine Description:
 266
 267   Return the EFI 1.0 System Tabl entry with TableGuid
 268
 269 Arguments:
 270
 271   TableGuid - Name of entry to return in the system table
 272   Table     - Pointer in EFI system table associated with TableGuid
 273
 274 Returns:
 275
 276   EFI_SUCCESS - Table returned;
 277   EFI_NOT_FOUND - TableGuid not in EFI system table
 278
 279 --*/
 280 ;
 281
 282 BOOLEAN
 283 EfiLibCompareLanguage (
 284   CHAR8  *Language1,
 285   CHAR8  *Language2
 286   )
 287 /*++
 288
 289 Routine Description:
 290
 291   Compare two languages to say whether they are identical.
 292
 293 Arguments:
 294
 295   Language1 - first language
 296   Language2 - second language
 297
 298 Returns:
 299
 300   TRUE      - identical
 301   FALSE     - not identical
 302
 303 --*/
 304 ;
 305
 306 //
 307 // DevicePath.c
 308 //
 309 BOOLEAN
 310 EfiIsDevicePathMultiInstance (
 311   IN EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 312   )
 313 /*++
 314
 315 Routine Description:
 316   Return TRUE is this is a multi instance device path.
 317
 318 Arguments:
 319   DevicePath  - A pointer to a device path data structure.
 320
 321
 322 Returns:
 323   TRUE - If DevicePath is multi instance.
 324   FALSE - If DevicePath is not multi instance.
 325
 326 --*/
 327 ;
 328
 329 EFI_DEVICE_PATH_PROTOCOL        *
 330 EfiDevicePathInstance (
 331   IN OUT EFI_DEVICE_PATH_PROTOCOL   **DevicePath,
 332   OUT UINTN                         *Size
 333   )
 334 /*++
 335
 336 Routine Description:
 337   Function retrieves the next device path instance from a device path data structure.
 338
 339 Arguments:
 340   DevicePath           - A pointer to a device path data structure.
 341
 342   Size                 - A pointer to the size of a device path instance in bytes.
 343
 344 Returns:
 345
 346   This function returns a pointer to the current device path instance.
 347   In addition, it returns the size in bytes of the current device path instance in Size,
 348   and a pointer to the next device path instance in DevicePath.
 349   If there are no more device path instances in DevicePath, then DevicePath will be set to NULL.
 350
 351 --*/
 352 ;
 353
 354 UINTN
 355 EfiDevicePathSize (
 356   IN EFI_DEVICE_PATH_PROTOCOL  *DevPath
 357   )
 358 /*++
 359
 360 Routine Description:
 361
 362   Calculate the size of a whole device path.
 363
 364 Arguments:
 365
 366   DevPath - The pointer to the device path data.
 367
 368 Returns:
 369
 370   Size of device path data structure..
 371
 372 --*/
 373 ;
 374
 375 EFI_DEVICE_PATH_PROTOCOL        *
 376 EfiAppendDevicePath (
 377   IN EFI_DEVICE_PATH_PROTOCOL  *Src1,
 378   IN EFI_DEVICE_PATH_PROTOCOL  *Src2
 379   )
 380 /*++
 381
 382 Routine Description:
 383   Function is used to append a Src1 and Src2 together.
 384
 385 Arguments:
 386   Src1  - A pointer to a device path data structure.
 387
 388   Src2  - A pointer to a device path data structure.
 389
 390 Returns:
 391
 392   A pointer to the new device path is returned.
 393   NULL is returned if space for the new device path could not be allocated from pool.
 394   It is up to the caller to free the memory used by Src1 and Src2 if they are no longer needed.
 395
 396 --*/
 397 ;
 398
 399 EFI_DEVICE_PATH_PROTOCOL        *
 400 EfiDevicePathFromHandle (
 401   IN EFI_HANDLE       Handle
 402   )
 403 /*++
 404
 405 Routine Description:
 406
 407   Locate device path protocol interface on a device handle.
 408
 409 Arguments:
 410
 411   Handle  - The device handle
 412
 413 Returns:
 414
 415   Device path protocol interface located.
 416
 417 --*/
 418 ;
 419
 420 EFI_DEVICE_PATH_PROTOCOL        *
 421 EfiDuplicateDevicePath (
 422   IN EFI_DEVICE_PATH_PROTOCOL  *DevPath
 423   )
 424 /*++
 425
 426 Routine Description:
 427   Duplicate a new device path data structure from the old one.
 428
 429 Arguments:
 430   DevPath  - A pointer to a device path data structure.
 431
 432 Returns:
 433   A pointer to the new allocated device path data.
 434   Caller must free the memory used by DevicePath if it is no longer needed.
 435
 436 --*/
 437 ;
 438
 439 EFI_DEVICE_PATH_PROTOCOL        *
 440 EfiAppendDevicePathNode (
 441   IN EFI_DEVICE_PATH_PROTOCOL  *Src1,
 442   IN EFI_DEVICE_PATH_PROTOCOL  *Src2
 443   )
 444 /*++
 445
 446 Routine Description:
 447   Function is used to append a device path node to the end of another device path.
 448
 449 Arguments:
 450   Src1  - A pointer to a device path data structure.
 451
 452   Src2 - A pointer to a device path data structure.
 453
 454 Returns:
 455   This function returns a pointer to the new device path.
 456   If there is not enough temporary pool memory available to complete this function,
 457   then NULL is returned.
 458
 459
 460 --*/
 461 ;
 462
 463 EFI_DEVICE_PATH_PROTOCOL        *
 464 EfiFileDevicePath (
 465   IN EFI_HANDLE               Device  OPTIONAL,
 466   IN CHAR16                   *FileName
 467   )
 468 /*++
 469
 470 Routine Description:
 471   Create a device path that appends a MEDIA_DEVICE_PATH with
 472   FileNameGuid to the device path of DeviceHandle.
 473
 474 Arguments:
 475   Device   - Optional Device Handle to use as Root of the Device Path
 476
 477   FileName - FileName
 478
 479 Returns:
 480   EFI_DEVICE_PATH_PROTOCOL that was allocated from dynamic memory
 481   or NULL pointer.
 482
 483 --*/
 484 ;
 485
 486 EFI_DEVICE_PATH_PROTOCOL        *
 487 EfiAppendDevicePathInstance (
 488   IN EFI_DEVICE_PATH_PROTOCOL  *Src,
 489   IN EFI_DEVICE_PATH_PROTOCOL  *Instance
 490   )
 491 /*++
 492
 493 Routine Description:
 494
 495   Append a device path instance to another.
 496
 497 Arguments:
 498
 499   Src       - The device path instance to be appended with.
 500   Instance  - The device path instance appending the other.
 501
 502 Returns:
 503
 504   The contaction of these two.
 505
 506 --*/
 507 ;
 508
 509 //
 510 // Lock.c
 511 //
 512 typedef struct {
 513   EFI_TPL Tpl;
 514   EFI_TPL OwnerTpl;
 515   UINTN   Lock;
 516 } EFI_LOCK;
 517
 518 VOID
 519 EfiInitializeLock (
 520   IN OUT EFI_LOCK *Lock,
 521   IN EFI_TPL      Priority
 522   )
 523 /*++
 524
 525 Routine Description:
 526
 527   Initialize a basic mutual exclusion lock.   Each lock
 528   provides mutual exclusion access at it's task priority
 529   level.  Since there is no-premption (at any TPL) or
 530   multiprocessor support, acquiring the lock only consists
 531   of raising to the locks TPL.
 532
 533   Note on a check build ASSERT()s are used to ensure proper
 534   lock usage.
 535
 536 Arguments:
 537
 538   Lock        - The EFI_LOCK structure to initialize
 539
 540   Priority    - The task priority level of the lock
 541
 542
 543 Returns:
 544
 545   An initialized Efi Lock structure.
 546
 547 --*/
 548 ;
 549
 550 //
 551 // Macro to initialize the state of a lock when a lock variable is declared
 552 //
 553 #define EFI_INITIALIZE_LOCK_VARIABLE(Tpl) {Tpl,0,0}
 554
 555 VOID
 556 EfiAcquireLock (
 557   IN EFI_LOCK *Lock
 558   )
 559 /*++
 560
 561 Routine Description:
 562
 563   Raising to the task priority level of the mutual exclusion
 564   lock, and then acquires ownership of the lock.
 565
 566 Arguments:
 567
 568   Lock - The lock to acquire
 569
 570 Returns:
 571
 572   None
 573
 574 --*/
 575 ;
 576
 577 EFI_STATUS
 578 EfiAcquireLockOrFail (
 579   IN EFI_LOCK  *Lock
 580   )
 581 /*++
 582
 583 Routine Description:
 584
 585   Initialize a basic mutual exclusion lock.   Each lock
 586   provides mutual exclusion access at it's task priority
 587   level.  Since there is no-premption (at any TPL) or
 588   multiprocessor support, acquiring the lock only consists
 589   of raising to the locks TPL.
 590
 591 Arguments:
 592
 593   Lock        - The EFI_LOCK structure to initialize
 594
 595 Returns:
 596
 597   EFI_SUCCESS       - Lock Owned.
 598   EFI_ACCESS_DENIED - Reentrant Lock Acquisition, Lock not Owned.
 599
 600 --*/
 601 ;
 602
 603 VOID
 604 EfiReleaseLock (
 605   IN EFI_LOCK *Lock
 606   )
 607 /*++
 608
 609 Routine Description:
 610
 611     Releases ownership of the mutual exclusion lock, and
 612     restores the previous task priority level.
 613
 614 Arguments:
 615
 616     Lock - The lock to release
 617
 618 Returns:
 619
 620     None
 621
 622 --*/
 623 ;
 624
 625 VOID *
 626 EfiLibAllocatePool (
 627   IN  UINTN   AllocationSize
 628   )
 629 /*++
 630
 631 Routine Description:
 632
 633   Allocate EfiBootServicesData pool of size AllocationSize
 634
 635 Arguments:
 636
 637   AllocationSize  - Pool size
 638
 639 Returns:
 640
 641   Pointer to the pool allocated
 642
 643 --*/
 644 ;
 645
 646 VOID *
 647 EfiLibAllocateRuntimePool (
 648   IN  UINTN   AllocationSize
 649   )
 650 /*++
 651
 652 Routine Description:
 653
 654   Allocate EfiRuntimeServicesData pool of size AllocationSize
 655
 656 Arguments:
 657
 658   AllocationSize  - Pool size
 659
 660 Returns:
 661
 662   Pointer to the pool allocated
 663
 664 --*/
 665 ;
 666
 667 VOID *
 668 EfiLibAllocateZeroPool (
 669   IN  UINTN   AllocationSize
 670   )
 671 /*++
 672
 673 Routine Description:
 674
 675   Allocate EfiBootServicesData pool of size AllocationSize and set memory to zero.
 676
 677 Arguments:
 678
 679   AllocationSize  - Pool size
 680
 681 Returns:
 682
 683   Pointer to the pool allocated
 684
 685 --*/
 686 ;
 687
 688 VOID *
 689 EfiLibAllocateRuntimeZeroPool (
 690   IN  UINTN   AllocationSize
 691   )
 692 /*++
 693
 694 Routine Description:
 695
 696   Allocate EfiRuntimeServicesData pool of size AllocationSize and set memory to zero.
 697
 698 Arguments:
 699
 700   AllocationSize  - Pool size
 701
 702 Returns:
 703
 704   Pointer to the pool allocated
 705
 706 --*/
 707 ;
 708
 709 VOID *
 710 EfiLibAllocateCopyPool (
 711   IN  UINTN   AllocationSize,
 712   IN  VOID    *Buffer
 713   )
 714 /*++
 715
 716 Routine Description:
 717
 718   Allocate BootServicesData pool and use a buffer provided by
 719   caller to fill it.
 720
 721 Arguments:
 722
 723   AllocationSize  - The size to allocate
 724
 725   Buffer          - Buffer that will be filled into the buffer allocated
 726
 727 Returns:
 728
 729   Pointer of the buffer allocated.
 730
 731 --*/
 732 ;
 733
 734 VOID *
 735 EfiLibAllocateRuntimeCopyPool (
 736   IN  UINTN            AllocationSize,
 737   IN  VOID             *Buffer
 738   )
 739 /*++
 740
 741 Routine Description:
 742
 743   Allocate RuntimeServicesData pool and use a buffer provided by
 744   caller to fill it.
 745
 746 Arguments:
 747
 748   AllocationSize  - The size to allocate
 749
 750   Buffer          - Buffer that will be filled into the buffer allocated
 751
 752 Returns:
 753
 754   Pointer of the buffer allocated.
 755
 756 --*/
 757 ;
 758
 759 //
 760 // Event.c
 761 //
 762 EFI_EVENT
 763 EfiLibCreateProtocolNotifyEvent (
 764   IN EFI_GUID             *ProtocolGuid,
 765   IN EFI_TPL              NotifyTpl,
 766   IN EFI_EVENT_NOTIFY     NotifyFunction,
 767   IN VOID                 *NotifyContext,
 768   OUT VOID                **Registration
 769   )
 770 /*++
 771
 772 Routine Description:
 773
 774   Create a protocol notification event and return it.
 775
 776 Arguments:
 777
 778   ProtocolGuid    - Protocol to register notification event on.
 779
 780   NotifyTpl       - Maximum TPL to single the NotifyFunction.
 781
 782   NotifyFunction  - EFI notification routine.
 783
 784   NotifyContext   - Context passed into Event when it is created.
 785
 786   Registration    - Registration key returned from RegisterProtocolNotify().
 787
 788 Returns:
 789
 790   The EFI_EVENT that has been registered to be signaled when a ProtocolGuid
 791   is added to the system.
 792
 793 --*/
 794 ;
 795
 796 EFI_STATUS
 797 EfiLibNamedEventSignal (
 798   IN EFI_GUID            *Name
 799   )
 800 /*++
 801
 802 Routine Description:
 803   Signals a named event. All registered listeners will run.
 804   The listeners should register using EfiLibNamedEventListen() function.
 805
 806   NOTE: For now, the named listening/signalling is implemented
 807   on a protocol interface being installed and uninstalled.
 808   In the future, this maybe implemented based on a dedicated mechanism.
 809
 810 Arguments:
 811   Name - Name to perform the signaling on. The name is a GUID.
 812
 813 Returns:
 814   EFI_SUCCESS if successfull.
 815
 816 --*/
 817 ;
 818
 819 EFI_STATUS
 820 EfiLibNamedEventListen (
 821   IN EFI_GUID             * Name,
 822   IN EFI_TPL              NotifyTpl,
 823   IN EFI_EVENT_NOTIFY     NotifyFunction,
 824   IN VOID                 *NotifyContext
 825   )
 826 /*++
 827
 828 Routine Description:
 829   Listenes to signals on the name.
 830   EfiLibNamedEventSignal() signals the event.
 831
 832   NOTE: For now, the named listening/signalling is implemented
 833   on a protocol interface being installed and uninstalled.
 834   In the future, this maybe implemented based on a dedicated mechanism.
 835
 836 Arguments:
 837   Name            - Name to register the listener on.
 838   NotifyTpl       - Maximum TPL to singnal the NotifyFunction.
 839   NotifyFunction  - The listener routine.
 840   NotifyContext   - Context passed into the listener routine.
 841
 842 Returns:
 843   EFI_SUCCESS if successful.
 844
 845 --*/
 846 ;
 847
 848 //
 849 // Handle.c
 850 //
 851 EFI_STATUS
 852 EfiLibLocateHandleProtocolByProtocols (
 853   IN OUT EFI_HANDLE        * Handle, OPTIONAL
 854   OUT    VOID              **Interface, OPTIONAL
 855   ...
 856   )
 857 /*++
 858 Routine Description:
 859
 860   Function locates Protocol and/or Handle on which all Protocols specified
 861   as a variable list are installed.
 862   It supports continued search. The caller must assure that no handles are added
 863   or removed while performing continued search, by e.g., rising the TPL and not
 864   calling any handle routines. Otherwise the behavior is undefined.
 865
 866 Arguments:
 867
 868   Handle        - The address of handle to receive the handle on which protocols
 869                   indicated by the variable list are installed.
 870                   If points to NULL, all handles are searched. If pointing to a
 871                   handle returned from previous call, searches starting from next handle.
 872                   If NULL, the parameter is ignored.
 873
 874   Interface     - The address of a pointer to a protocol interface that will receive
 875                   the interface indicated by first variable argument.
 876                   If NULL, the parameter is ignored.
 877
 878   ...           - A variable argument list containing protocol GUIDs. Must end with NULL.
 879
 880 Returns:
 881
 882   EFI_SUCCESS  - All the protocols where found on same handle.
 883   EFI_NOT_FOUND - A Handle with all the protocols installed was not found.
 884   Other values as may be returned from LocateHandleBuffer() or HandleProtocol().
 885
 886 --*/
 887 ;
 888
 889 //
 890 // Debug.c init
 891 //
 892 EFI_STATUS
 893 EfiDebugAssertInit (
 894   VOID
 895   )
 896 /*++
 897
 898 Routine Description:
 899
 900   Locate Debug Assert Protocol and set as mDebugAssert
 901
 902 Arguments:
 903
 904   None
 905
 906 Returns:
 907
 908   Status code
 909
 910 --*/
 911 ;
 912
 913 //
 914 // Unicode String Support
 915 //
 916 EFI_STATUS
 917 EfiLibLookupUnicodeString (
 918   CHAR8                     *Language,
 919   CHAR8                     *SupportedLanguages,
 920   EFI_UNICODE_STRING_TABLE  *UnicodeStringTable,
 921   CHAR16                    **UnicodeString
 922   )
 923 /*++
 924
 925 Routine Description:
 926
 927   Translate a unicode string to a specified language if supported.
 928
 929 Arguments:
 930
 931   Language              - The name of language to translate to
 932   SupportedLanguages    - Supported languages set
 933   UnicodeStringTable    - Pointer of one item in translation dictionary
 934   UnicodeString         - The translated string
 935
 936 Returns:
 937
 938   EFI_INVALID_PARAMETER - Invalid parameter
 939   EFI_UNSUPPORTED       - System not supported this language or this string translation
 940   EFI_SUCCESS           - String successfully translated
 941
 942 --*/
 943 ;
 944
 945 EFI_STATUS
 946 EfiLibAddUnicodeString (
 947   CHAR8                     *Language,
 948   CHAR8                     *SupportedLanguages,
 949   EFI_UNICODE_STRING_TABLE  **UnicodeStringTable,
 950   CHAR16                    *UnicodeString
 951   )
 952 /*++
 953
 954 Routine Description:
 955
 956   Add an translation to the dictionary if this language if supported.
 957
 958 Arguments:
 959
 960   Language              - The name of language to translate to
 961   SupportedLanguages    - Supported languages set
 962   UnicodeStringTable    - Translation dictionary
 963   UnicodeString         - The corresponding string for the language to be translated to
 964
 965 Returns:
 966
 967   EFI_INVALID_PARAMETER - Invalid parameter
 968   EFI_UNSUPPORTED       - System not supported this language
 969   EFI_ALREADY_STARTED   - Already has a translation item of this language
 970   EFI_OUT_OF_RESOURCES  - No enough buffer to be allocated
 971   EFI_SUCCESS           - String successfully translated
 972
 973 --*/
 974 ;
 975
 976 EFI_STATUS
 977 EfiLibFreeUnicodeStringTable (
 978   EFI_UNICODE_STRING_TABLE  *UnicodeStringTable
 979   )
 980 /*++
 981
 982 Routine Description:
 983
 984   Free a string table.
 985
 986 Arguments:
 987
 988   UnicodeStringTable      - The string table to be freed.
 989
 990 Returns:
 991
 992   EFI_SUCCESS       - The table successfully freed.
 993
 994 --*/
 995 ;
 996
 997 EFI_STATUS
 998 EfiLibReportStatusCode (
 999   IN EFI_STATUS_CODE_TYPE     Type,
1000   IN EFI_STATUS_CODE_VALUE    Value,
1001   IN UINT32                   Instance,
1002   IN EFI_GUID                 *CallerId OPTIONAL,
1003   IN EFI_STATUS_CODE_DATA     *Data     OPTIONAL
1004   )
1005 /*++
1006
1007 Routine Description:
1008
1009   Report status code.
1010
1011 Arguments:
1012
1013   Type        - Code type
1014   Value       - Code value
1015   Instance    - Instance number
1016   CallerId    - Caller name
1017   DevicePath  - Device path that to be reported
1018
1019 Returns:
1020
1021   Status code.
1022
1023   EFI_OUT_OF_RESOURCES - No enough buffer could be allocated
1024
1025 --*/
1026 ;
1027
1028 EFI_STATUS
1029 ReportStatusCodeWithDevicePath (
1030   IN EFI_STATUS_CODE_TYPE     Type,
1031   IN EFI_STATUS_CODE_VALUE    Value,
1032   IN UINT32                   Instance,
1033   IN EFI_GUID                 * CallerId OPTIONAL,
1034   IN EFI_DEVICE_PATH_PROTOCOL * DevicePath
1035   )
1036 /*++
1037
1038 Routine Description:
1039
1040   Report device path through status code.
1041
1042 Arguments:
1043
1044   Type        - Code type
1045   Value       - Code value
1046   Instance    - Instance number
1047   CallerId    - Caller name
1048   DevicePath  - Device path that to be reported
1049
1050 Returns:
1051
1052   Status code.
1053
1054   EFI_OUT_OF_RESOURCES - No enough buffer could be allocated
1055
1056 --*/
1057 ;
1058
1059 EFI_STATUS
1060 EFIAPI
1061 EfiCreateEventLegacyBoot (
1062   IN EFI_TPL                      NotifyTpl,
1063   IN EFI_EVENT_NOTIFY             NotifyFunction,
1064   IN VOID                         *NotifyContext,
1065   OUT EFI_EVENT                   *LegacyBootEvent
1066   )
1067 /*++
1068
1069 Routine Description:
1070   Create a Legacy Boot Event.
1071   Tiano extended the CreateEvent Type enum to add a legacy boot event type.
1072   This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was
1073   added and now it's possible to not voilate the UEFI specification by
1074   declaring a GUID for the legacy boot event class. This library supports
1075   the R8.5/EFI 1.10 form and R8.6/UEFI 2.0 form and allows common code to
1076   work both ways.
1077
1078 Arguments:
1079   LegacyBootEvent  Returns the EFI event returned from gBS->CreateEvent(Ex)
1080
1081 Returns:
1082   EFI_SUCCESS   Event was created.
1083   Other         Event was not created.
1084
1085 --*/
1086 ;
1087
1088 EFI_STATUS
1089 EFIAPI
1090 EfiCreateEventReadyToBoot (
1091   IN EFI_TPL                      NotifyTpl,
1092   IN EFI_EVENT_NOTIFY             NotifyFunction,
1093   IN VOID                         *NotifyContext,
1094   OUT EFI_EVENT                   *ReadyToBootEvent
1095   )
1096 /*++
1097
1098 Routine Description:
1099   Create a Read to Boot Event.
1100
1101   Tiano extended the CreateEvent Type enum to add a ready to boot event type.
1102   This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was
1103   added and now it's possible to not voilate the UEFI specification and use
1104   the ready to boot event class defined in UEFI 2.0. This library supports
1105   the R8.5/EFI 1.10 form and R8.6/UEFI 2.0 form and allows common code to
1106   work both ways.
1107
1108 Arguments:
1109   @param LegacyBootEvent  Returns the EFI event returned from gBS->CreateEvent(Ex)
1110
1111 Return:
1112   EFI_SUCCESS   - Event was created.
1113   Other         - Event was not created.
1114
1115 --*/
1116 ;
1117
1118 VOID
1119 EFIAPI
1120 EfiInitializeFwVolDevicepathNode (
1121   IN  MEDIA_FW_VOL_FILEPATH_DEVICE_PATH     *FvDevicePathNode,
1122   IN EFI_GUID                               *NameGuid
1123   )
1124 /*++
1125 Routine Description:
1126   Initialize a Firmware Volume (FV) Media Device Path node.
1127
1128   Tiano extended the EFI 1.10 device path nodes. Tiano does not own this enum
1129   so as we move to UEFI 2.0 support we must use a mechanism that conforms with
1130   the UEFI 2.0 specification to define the FV device path. An UEFI GUIDed
1131   device path is defined for PIWG extensions of device path. If the code
1132   is compiled to conform with the UEFI 2.0 specification use the new device path
1133   else use the old form for backwards compatability.
1134
1135 Arguments:
1136   FvDevicePathNode   - Pointer to a FV device path node to initialize
1137   NameGuid           - FV file name to use in FvDevicePathNode
1138
1139 --*/
1140 ;
1141
1142 EFI_GUID *
1143 EFIAPI
1144 EfiGetNameGuidFromFwVolDevicePathNode (
1145   IN  MEDIA_FW_VOL_FILEPATH_DEVICE_PATH   *FvDevicePathNode
1146   )
1147 /*++
1148 Routine Description:
1149   Check to see if the Firmware Volume (FV) Media Device Path is valid.
1150
1151   Tiano extended the EFI 1.10 device path nodes. Tiano does not own this enum
1152   so as we move to UEFI 2.0 support we must use a mechanism that conforms with
1153   the UEFI 2.0 specification to define the FV device path. An UEFI GUIDed
1154   device path is defined for PIWG extensions of device path. If the code
1155   is compiled to conform with the UEFI 2.0 specification use the new device path
1156   else use the old form for backwards compatability. The return value to this
1157   function points to a location in FvDevicePathNode and it does not allocate
1158   new memory for the GUID pointer that is returned.
1159
1160 Arguments:
1161   FvDevicePathNode   - Pointer to FV device path to check
1162
1163 Return:
1164   NULL    - FvDevicePathNode is not valid.
1165   Other   - FvDevicePathNode is valid and pointer to NameGuid was returned.
1166
1167 --*/
1168 ;
1169
1170 VOID
1171 EfiLibSafeFreePool (
1172   IN  VOID             *Buffer
1173   )
1174 /*++
1175
1176 Routine Description:
1177
1178   Free pool safely.
1179
1180 Arguments:
1181
1182   Buffer          - The allocated pool entry to free
1183
1184 Returns:
1185
1186   Pointer of the buffer allocated.
1187
1188 --*/
1189 ;
1190
1191 EFI_STATUS
1192 EfiLibTestManagedDevice (
1193   IN EFI_HANDLE       ControllerHandle,
1194   IN EFI_HANDLE       DriverBindingHandle,
1195   IN EFI_GUID         *ManagedProtocolGuid
1196   )
1197 /*++
1198
1199 Routine Description:
1200
1201   Test to see if the controller is managed by a specific driver.
1202
1203 Arguments:
1204
1205   ControllerHandle          - Handle for controller to test
1206
1207   DriverBindingHandle       - Driver binding handle for controller
1208
1209   ManagedProtocolGuid       - The protocol guid the driver opens on controller
1210
1211 Returns:
1212
1213   EFI_SUCCESS     - The controller is managed by the driver
1214
1215   EFI_UNSUPPORTED - The controller is not managed by the driver
1216
1217 --*/
1218 ;
1219
1220 EFI_STATUS
1221 EfiLibTestChildHandle (
1222   IN EFI_HANDLE       ControllerHandle,
1223   IN EFI_HANDLE       ChildHandle,
1224   IN EFI_GUID         *ConsumedGuid
1225   )
1226 /*++
1227
1228 Routine Description:
1229
1230   Test to see if the child handle is the child of the controller
1231
1232 Arguments:
1233
1234   ControllerHandle          - Handle for controller (parent)
1235
1236   ChildHandle               - Child handle to test
1237
1238   ConsumsedGuid             - Protocol guid consumed by child from controller
1239
1240 Returns:
1241
1242   EFI_SUCCESS     - The child handle is the child of the controller
1243
1244   EFI_UNSUPPORTED - The child handle is not the child of the controller
1245
1246 --*/
1247 ;
1248 #endif