1 /*++ 2 3 Copyright (c) 2004 - 2011, 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 EFI 1.10 form and UEFI 2.0 form and allows common code to work both ways. 1128 1129 Arguments: 1130 LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex) 1131 1132 Returns: 1133 EFI_SUCCESS Event was created. 1134 Other Event was not created. 1135 1136 --*/ 1137 ; 1138 1139 EFI_STATUS 1140 EFIAPI 1141 EfiCreateEventReadyToBoot ( 1142 IN EFI_TPL NotifyTpl, 1143 IN EFI_EVENT_NOTIFY NotifyFunction, 1144 IN VOID *NotifyContext, 1145 OUT EFI_EVENT *ReadyToBootEvent 1146 ) 1147 /*++ 1148 1149 Routine Description: 1150 Create a Read to Boot Event. 1151 1152 Tiano extended the CreateEvent Type enum to add a ready to boot event type. 1153 This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was 1154 added and now it's possible to not voilate the UEFI specification and use 1155 the ready to boot event class defined in UEFI 2.0. This library supports 1156 the EFI 1.10 form and UEFI 2.0 form and allows common code to work both ways. 1157 1158 Arguments: 1159 @param LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex) 1160 1161 Return: 1162 EFI_SUCCESS - Event was created. 1163 Other - Event was not created. 1164 1165 --*/ 1166 ; 1167 1168 VOID 1169 EFIAPI 1170 EfiInitializeFwVolDevicepathNode ( 1171 IN MEDIA_FW_VOL_FILEPATH_DEVICE_PATH *FvDevicePathNode, 1172 IN EFI_GUID *NameGuid 1173 ) 1174 /*++ 1175 Routine Description: 1176 Initialize a Firmware Volume (FV) Media Device Path node. 1177 1178 Arguments: 1179 FvDevicePathNode - Pointer to a FV device path node to initialize 1180 NameGuid - FV file name to use in FvDevicePathNode 1181 1182 --*/ 1183 ; 1184 1185 EFI_GUID * 1186 EFIAPI 1187 EfiGetNameGuidFromFwVolDevicePathNode ( 1188 IN MEDIA_FW_VOL_FILEPATH_DEVICE_PATH *FvDevicePathNode 1189 ) 1190 /*++ 1191 Routine Description: 1192 Check to see if the Firmware Volume (FV) Media Device Path is valid. 1193 1194 Arguments: 1195 FvDevicePathNode - Pointer to FV device path to check 1196 1197 Return: 1198 NULL - FvDevicePathNode is not valid. 1199 Other - FvDevicePathNode is valid and pointer to NameGuid was returned. 1200 1201 --*/ 1202 ; 1203 1204 VOID 1205 EfiLibSafeFreePool ( 1206 IN VOID *Buffer 1207 ) 1208 /*++ 1209 1210 Routine Description: 1211 1212 Free pool safely. 1213 1214 Arguments: 1215 1216 Buffer - The allocated pool entry to free 1217 1218 Returns: 1219 1220 Pointer of the buffer allocated. 1221 1222 --*/ 1223 ; 1224 1225 EFI_STATUS 1226 EfiLibTestManagedDevice ( 1227 IN EFI_HANDLE ControllerHandle, 1228 IN EFI_HANDLE DriverBindingHandle, 1229 IN EFI_GUID *ManagedProtocolGuid 1230 ) 1231 /*++ 1232 1233 Routine Description: 1234 1235 Test to see if the controller is managed by a specific driver. 1236 1237 Arguments: 1238 1239 ControllerHandle - Handle for controller to test 1240 1241 DriverBindingHandle - Driver binding handle for controller 1242 1243 ManagedProtocolGuid - The protocol guid the driver opens on controller 1244 1245 Returns: 1246 1247 EFI_SUCCESS - The controller is managed by the driver 1248 1249 EFI_UNSUPPORTED - The controller is not managed by the driver 1250 1251 --*/ 1252 ; 1253 1254 EFI_STATUS 1255 EfiLibTestChildHandle ( 1256 IN EFI_HANDLE ControllerHandle, 1257 IN EFI_HANDLE ChildHandle, 1258 IN EFI_GUID *ConsumedGuid 1259 ) 1260 /*++ 1261 1262 Routine Description: 1263 1264 Test to see if the child handle is the child of the controller 1265 1266 Arguments: 1267 1268 ControllerHandle - Handle for controller (parent) 1269 1270 ChildHandle - Child handle to test 1271 1272 ConsumsedGuid - Protocol guid consumed by child from controller 1273 1274 Returns: 1275 1276 EFI_SUCCESS - The child handle is the child of the controller 1277 1278 EFI_UNSUPPORTED - The child handle is not the child of the controller 1279 1280 --*/ 1281 ; 1282 #endif 1283