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