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

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