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

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