EdkModulePkg/Core/Dxe/DxeMain.h

   1 /*++
   2
   3 Copyright (c) 2006, Intel Corporation
   4 All rights reserved. This program and the accompanying materials
   5 are licensed and made available under the terms and conditions of the BSD License
   6 which accompanies this distribution.  The full text of the license may be found at
   7 http://opensource.org/licenses/bsd-license.php
   8
   9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12 Module Name:
  13
  14   DxeMain.h
  15
  16 Abstract:
  17
  18 Revision History
  19
  20 --*/
  21
  22 #ifndef _DXE_MAIN_H_
  23 #define _DXE_MAIN_H_
  24
  25
  26 #include "DebugImageInfo.h"
  27 #include "Library.h"
  28 #include "FwVolBlock.h"
  29 #include "FwVolDriver.h"
  30 #include "gcd.h"
  31 #include "imem.h"
  32 #include "Image.h"
  33 #include "Exec.h"
  34 #include "hand.h"
  35
  36 typedef struct {
  37   EFI_GUID                    *ProtocolGuid;
  38   VOID                        **Protocol;
  39   EFI_EVENT                   Event;
  40   VOID                        *Registration;
  41   BOOLEAN                     Present;
  42 } ARCHITECTURAL_PROTOCOL_ENTRY;
  43
  44
  45 //
  46 // DXE Dispatcher Data structures
  47 //
  48
  49 #define KNOWN_HANDLE_SIGNATURE  EFI_SIGNATURE_32('k','n','o','w')
  50 typedef struct {
  51   UINTN           Signature;
  52   LIST_ENTRY      Link;         // mFvHandleList
  53   EFI_HANDLE      Handle;
  54 } KNOWN_HANDLE;
  55
  56
  57 #define EFI_CORE_DRIVER_ENTRY_SIGNATURE EFI_SIGNATURE_32('d','r','v','r')
  58 typedef struct {
  59   UINTN                           Signature;
  60   LIST_ENTRY                      Link;             // mDriverList
  61
  62   LIST_ENTRY                      ScheduledLink;    // mScheduledQueue
  63
  64   EFI_HANDLE                      FvHandle;
  65   EFI_GUID                        FileName;
  66   EFI_DEVICE_PATH_PROTOCOL        *FvFileDevicePath;
  67   EFI_FIRMWARE_VOLUME_PROTOCOL    *Fv;
  68
  69   VOID                            *Depex;
  70   UINTN                           DepexSize;
  71
  72   BOOLEAN                         Before;
  73   BOOLEAN                         After;
  74   EFI_GUID                        BeforeAfterGuid;
  75
  76   BOOLEAN                         Dependent;
  77   BOOLEAN                         Unrequested;
  78   BOOLEAN                         Scheduled;
  79   BOOLEAN                         Untrusted;
  80   BOOLEAN                         Initialized;
  81   BOOLEAN                         DepexProtocolError;
  82
  83   EFI_HANDLE                      ImageHandle;
  84
  85 } EFI_CORE_DRIVER_ENTRY;
  86
  87 //
  88 //The data structure of GCD memory map entry
  89 //
  90 #define EFI_GCD_MAP_SIGNATURE  EFI_SIGNATURE_32('g','c','d','m')
  91 typedef struct {
  92   UINTN                 Signature;
  93   LIST_ENTRY            Link;
  94   EFI_PHYSICAL_ADDRESS  BaseAddress;
  95   UINT64                EndAddress;
  96   UINT64                Capabilities;
  97   UINT64                Attributes;
  98   EFI_GCD_MEMORY_TYPE   GcdMemoryType;
  99   EFI_GCD_IO_TYPE       GcdIoType;
 100   EFI_HANDLE            ImageHandle;
 101   EFI_HANDLE            DeviceHandle;
 102 } EFI_GCD_MAP_ENTRY;
 103
 104 //
 105 // DXE Core Global Variables
 106 //
 107 extern EFI_SYSTEM_TABLE                         *gST;
 108 extern EFI_BOOT_SERVICES                        *gBS;
 109 extern EFI_RUNTIME_SERVICES                     *gRT;
 110 extern EFI_DXE_SERVICES                         *gDS;
 111 extern EFI_HANDLE                               gDxeCoreImageHandle;
 112
 113 extern EFI_DECOMPRESS_PROTOCOL                  gEfiDecompress;
 114 extern EFI_PEI_PE_COFF_LOADER_PROTOCOL          *gEfiPeiPeCoffLoader;
 115
 116 extern EFI_RUNTIME_ARCH_PROTOCOL                *gRuntime;
 117 extern EFI_CPU_ARCH_PROTOCOL                    *gCpu;
 118 extern EFI_WATCHDOG_TIMER_ARCH_PROTOCOL         *gWatchdogTimer;
 119 extern EFI_METRONOME_ARCH_PROTOCOL              *gMetronome;
 120 extern EFI_TIMER_ARCH_PROTOCOL                  *gTimer;
 121 extern EFI_SECURITY_ARCH_PROTOCOL               *gSecurity;
 122 extern EFI_BDS_ARCH_PROTOCOL                    *gBds;
 123 extern EFI_STATUS_CODE_PROTOCOL                 *gStatusCode;
 124
 125 extern EFI_TPL                                  gEfiCurrentTpl;
 126
 127 extern EFI_GUID                                 *gDxeCoreFileName;
 128 extern EFI_LOADED_IMAGE_PROTOCOL                *gDxeCoreLoadedImage;
 129
 130 extern EFI_MEMORY_TYPE_INFORMATION              gMemoryTypeInformation[EfiMaxMemoryType + 1];
 131
 132 extern BOOLEAN                                  gDispatcherRunning;
 133 extern EFI_RUNTIME_ARCH_PROTOCOL                gRuntimeTemplate;
 134
 135 //
 136 // Service Initialization Functions
 137 //
 138
 139
 140 VOID
 141 CoreInitializePool (
 142   VOID
 143   )
 144 /*++
 145
 146 Routine Description:
 147
 148   Called to initialize the pool.
 149
 150 Arguments:
 151
 152   None
 153
 154 Returns:
 155
 156   None
 157
 158 --*/
 159 ;
 160
 161 VOID
 162 CoreAddMemoryDescriptor (
 163   IN EFI_MEMORY_TYPE       Type,
 164   IN EFI_PHYSICAL_ADDRESS  Start,
 165   IN UINT64                NumberOfPages,
 166   IN UINT64                Attribute
 167   )
 168 /*++
 169
 170 Routine Description:
 171
 172   Called to initialize the memory map and add descriptors to
 173   the current descriptor list.
 174
 175        The first descriptor that is added must be general usable
 176   memory as the addition allocates heap.
 177
 178 Arguments:
 179
 180   Type          - The type of memory to add
 181
 182   Start         - The starting address in the memory range
 183                   Must be page aligned
 184
 185   NumberOfPages - The number of pages in the range
 186
 187   Attribute     - Attributes of the memory to add
 188
 189 Returns:
 190
 191   None.  The range is added to the memory map
 192
 193 --*/
 194 ;
 195
 196 VOID
 197 CoreReleaseGcdMemoryLock (
 198   VOID
 199   )
 200 /*++
 201
 202 Routine Description:
 203     Release memory lock on mGcdMemorySpaceLock
 204
 205 Arguments:
 206     None
 207
 208 Returns:
 209     None
 210
 211 --*/
 212 ;
 213
 214 VOID
 215 CoreAcquireGcdMemoryLock (
 216   VOID
 217   )
 218 /*++
 219
 220 Routine Description:
 221     Acquire memory lock on mGcdMemorySpaceLock
 222
 223 Arguments:
 224     None
 225
 226 Returns:
 227     None
 228
 229 --*/
 230 ;
 231
 232 EFI_STATUS
 233 CoreInitializeMemoryServices (
 234   IN VOID                  **HobStart,
 235   IN EFI_PHYSICAL_ADDRESS  *MemoryBaseAddress,
 236   IN UINT64                *MemoryLength
 237   )
 238 /*++
 239
 240 Routine Description:
 241
 242   External function. Initializes the GCD and memory services based on the memory
 243   descriptor HOBs.  This function is responsible for priming the GCD map and the
 244   memory map, so memory allocations and resource allocations can be made.  The first
 245   part of this function can not depend on any memory services until at least one
 246   memory descriptor is provided to the memory services.  Then the memory services
 247   can be used to intialize the GCD map.
 248
 249 Arguments:
 250
 251   HobStart - The start address of the HOB.
 252
 253   MemoryBaseAddress   - Start address of memory region found to init DXE core.
 254
 255   MemoryLength        - Length of memory region found to init DXE core.
 256
 257 Returns:
 258
 259   EFI_SUCCESS         - Memory services successfully initialized.
 260
 261 --*/
 262 ;
 263
 264
 265 EFI_STATUS
 266 CoreInitializeGcdServices (
 267   IN VOID                  **HobStart,
 268   IN EFI_PHYSICAL_ADDRESS  MemoryBaseAddress,
 269   IN UINT64                MemoryLength
 270   )
 271 /*++
 272
 273 Routine Description:
 274
 275   External function. Initializes the GCD and memory services based on the memory
 276   descriptor HOBs.  This function is responsible for priming the GCD map and the
 277   memory map, so memory allocations and resource allocations can be made.  The first
 278   part of this function can not depend on any memory services until at least one
 279   memory descriptor is provided to the memory services.  Then the memory services
 280   can be used to intialize the GCD map.
 281
 282 Arguments:
 283
 284   HobStart - The start address of the HOB
 285
 286   MemoryBaseAddress   - Start address of memory region found to init DXE core.
 287
 288   MemoryLength        - Length of memory region found to init DXE core.
 289
 290
 291 Returns:
 292
 293   EFI_SUCCESS         - GCD services successfully initialized.
 294
 295 --*/
 296 ;
 297
 298 EFI_STATUS
 299 CoreInitializeEventServices (
 300   VOID
 301   )
 302 /*++
 303
 304 Routine Description:
 305
 306   Initializes "event" support and populates parts of the System and Runtime Table.
 307
 308 Arguments:
 309
 310   None
 311
 312 Returns:
 313
 314   EFI_SUCCESS - Always return success
 315
 316 --*/
 317 ;
 318
 319 EFI_STATUS
 320 CoreInitializeImageServices (
 321   IN  VOID *HobStart
 322   )
 323 /*++
 324
 325 Routine Description:
 326
 327   Add the Image Services to EFI Boot Services Table and install the protocol
 328   interfaces for this image.
 329
 330 Arguments:
 331
 332   HobStart        - The HOB to initialize
 333
 334 Returns:
 335
 336   Status code.
 337
 338 --*/
 339 ;
 340
 341 VOID
 342 CoreNotifyOnArchProtocolInstallation (
 343   VOID
 344   )
 345 /*++
 346
 347 Routine Description:
 348   Creates an event that is fired everytime a Protocol of a specific type is installed
 349
 350 Arguments:
 351   NONE
 352
 353 Returns:
 354   NONE
 355
 356 --*/
 357 ;
 358
 359 EFI_STATUS
 360 CoreAllEfiServicesAvailable (
 361   VOID
 362   )
 363 /*++
 364
 365 Routine Description:
 366   Return TRUE if all AP services are availible.
 367
 368 Arguments:
 369   NONE
 370
 371 Returns:
 372   EFI_SUCCESS   - All AP services are available
 373   EFI_NOT_FOUND - At least one AP service is not available
 374
 375 --*/
 376 ;
 377
 378 VOID
 379 CalculateEfiHdrCrc (
 380   IN  OUT EFI_TABLE_HEADER    *Hdr
 381   )
 382 /*++
 383
 384 Routine Description:
 385
 386   Calcualte the 32-bit CRC in a EFI table using the service provided by the
 387   gRuntime service.
 388
 389 Arguments:
 390
 391   Hdr  - Pointer to an EFI standard header
 392
 393 Returns:
 394
 395   None
 396
 397 --*/
 398 ;
 399
 400 VOID
 401 EFIAPI
 402 CoreTimerTick (
 403   IN UINT64     Duration
 404   )
 405 /*++
 406
 407 Routine Description:
 408
 409   Called by the platform code to process a tick.
 410
 411 Arguments:
 412
 413   Duration    - The number of 100ns elasped since the last call to TimerTick
 414
 415 Returns:
 416
 417   None
 418
 419 --*/
 420 ;
 421
 422 VOID
 423 CoreInitializeDispatcher (
 424   VOID
 425   )
 426 /*++
 427
 428 Routine Description:
 429
 430   Initialize the dispatcher. Initialize the notification function that runs when
 431   a FV protocol is added to the system.
 432
 433 Arguments:
 434
 435   NONE
 436
 437 Returns:
 438
 439   NONE
 440
 441 --*/
 442 ;
 443
 444 BOOLEAN
 445 CoreIsSchedulable (
 446   IN  EFI_CORE_DRIVER_ENTRY   *DriverEntry
 447   )
 448 /*++
 449
 450 Routine Description:
 451
 452   This is the POSTFIX version of the dependency evaluator.  This code does
 453   not need to handle Before or After, as it is not valid to call this
 454   routine in this case. The SOR is just ignored and is a nop in the grammer.
 455
 456   POSTFIX means all the math is done on top of the stack.
 457
 458 Arguments:
 459
 460   DriverEntry - DriverEntry element to update
 461
 462 Returns:
 463
 464   TRUE - If driver is ready to run.
 465
 466   FALSE - If driver is not ready to run or some fatal error was found.
 467
 468 --*/
 469 ;
 470
 471 EFI_STATUS
 472 CorePreProcessDepex (
 473   IN  EFI_CORE_DRIVER_ENTRY   *DriverEntry
 474   )
 475 /*++
 476
 477 Routine Description:
 478
 479   Preprocess dependency expression and update DriverEntry to reflect the
 480   state of  Before, After, and SOR dependencies. If DriverEntry->Before
 481   or DriverEntry->After is set it will never be cleared. If SOR is set
 482   it will be cleared by CoreSchedule(), and then the driver can be
 483   dispatched.
 484
 485 Arguments:
 486
 487   DriverEntry - DriverEntry element to update
 488
 489 Returns:
 490
 491   EFI_SUCCESS - It always works.
 492
 493 --*/
 494 ;
 495
 496
 497 EFI_STATUS
 498 EFIAPI
 499 CoreExitBootServices (
 500   IN EFI_HANDLE   ImageHandle,
 501   IN UINTN        MapKey
 502   )
 503 /*++
 504
 505 Routine Description:
 506
 507   EFI 1.0 API to terminate Boot Services
 508
 509 Arguments:
 510
 511   ImageHandle - Handle that represents the identity of the calling image
 512
 513   MapKey      -Key to the latest memory map.
 514
 515 Returns:
 516
 517   EFI_SUCCESS - Boot Services terminated
 518   EFI_INVALID_PARAMETER - MapKey is incorrect.
 519
 520 --*/
 521 ;
 522
 523 EFI_STATUS
 524 CoreTerminateMemoryMap (
 525   IN UINTN        MapKey
 526   )
 527 /*++
 528
 529 Routine Description:
 530
 531   Make sure the memory map is following all the construction rules,
 532   it is the last time to check memory map error before exit boot services.
 533
 534 Arguments:
 535
 536   MapKey        - Memory map key
 537
 538 Returns:
 539
 540   EFI_INVALID_PARAMETER       - Memory map not consistent with construction rules.
 541
 542   EFI_SUCCESS                 - Valid memory map.
 543
 544 --*/
 545 ;
 546
 547 VOID
 548 CoreNotifySignalList (
 549   IN EFI_GUID     *EventGroup
 550   )
 551 /*++
 552
 553 Routine Description:
 554
 555   Signals all events on the requested list
 556
 557 Arguments:
 558
 559   SignalType      - The list to signal
 560
 561 Returns:
 562
 563   None
 564
 565 --*/
 566 ;
 567
 568
 569 EFI_STATUS
 570 EFIAPI
 571 CoreInstallConfigurationTable (
 572   IN EFI_GUID         *Guid,
 573   IN VOID             *Table
 574   )
 575 /*++
 576
 577 Routine Description:
 578
 579   Boot Service called to add, modify, or remove a system configuration table from
 580   the EFI System Table.
 581
 582 Arguments:
 583
 584   Guid:   Pointer to the GUID for the entry to add, update, or remove
 585   Table:  Pointer to the configuration table for the entry to add, update, or
 586           remove, may be NULL.
 587
 588 Returns:
 589
 590   EFI_SUCCESS               Guid, Table pair added, updated, or removed.
 591   EFI_INVALID_PARAMETER     Input GUID not valid.
 592   EFI_NOT_FOUND             Attempted to delete non-existant entry
 593   EFI_OUT_OF_RESOURCES      Not enough memory available
 594
 595 --*/
 596 ;
 597
 598
 599 EFI_TPL
 600 EFIAPI
 601 CoreRaiseTpl (
 602   IN EFI_TPL  NewTpl
 603   )
 604 /*++
 605
 606 Routine Description:
 607
 608   Raise the task priority level to the new level.
 609   High level is implemented by disabling processor interrupts.
 610
 611 Arguments:
 612
 613   NewTpl  - New task priority level
 614
 615 Returns:
 616
 617   The previous task priority level
 618
 619 --*/
 620 ;
 621
 622
 623 VOID
 624 EFIAPI
 625 CoreRestoreTpl (
 626   IN EFI_TPL  NewTpl
 627   )
 628 /*++
 629
 630 Routine Description:
 631
 632   Lowers the task priority to the previous value.   If the new
 633   priority unmasks events at a higher priority, they are dispatched.
 634
 635 Arguments:
 636
 637   NewTpl  - New, lower, task priority
 638
 639 Returns:
 640
 641   None
 642
 643 --*/
 644 ;
 645
 646
 647 EFI_STATUS
 648 EFIAPI
 649 CoreStall (
 650   IN UINTN            Microseconds
 651   )
 652 /*++
 653
 654 Routine Description:
 655
 656   Introduces a fine-grained stall.
 657
 658 Arguments:
 659
 660   Microseconds      The number of microseconds to stall execution
 661
 662 Returns:
 663
 664   EFI_SUCCESS            - Execution was stalled for at least the requested amount
 665                            of microseconds.
 666
 667   EFI_NOT_AVAILABLE_YET  - gMetronome is not available yet
 668
 669 --*/
 670 ;
 671
 672
 673 EFI_STATUS
 674 EFIAPI
 675 CoreSetWatchdogTimer (
 676   IN UINTN            Timeout,
 677   IN UINT64           WatchdogCode,
 678   IN UINTN            DataSize,
 679   IN CHAR16           *WatchdogData   OPTIONAL
 680   )
 681 /*++
 682
 683 Routine Description:
 684
 685   Sets the system's watchdog timer.
 686
 687 Arguments:
 688
 689   Timeout         The number of seconds.  Zero disables the timer.
 690
 691   ///////following  three parameters are left for platform specific using
 692
 693   WatchdogCode    The numberic code to log.  0x0 to 0xffff are firmware
 694   DataSize        Size of the optional data
 695   WatchdogData    Optional Null terminated unicode string followed by binary
 696                   data.
 697
 698 Returns:
 699
 700   EFI_SUCCESS               Timeout has been set
 701   EFI_NOT_AVAILABLE_YET     WatchdogTimer is not available yet
 702   EFI_UNSUPPORTED           System does not have a timer (currently not used)
 703   EFI_DEVICE_ERROR          Could not complete due to hardware error
 704
 705 --*/
 706 ;
 707
 708
 709 EFI_STATUS
 710 EFIAPI
 711 CoreInstallProtocolInterface (
 712   IN OUT EFI_HANDLE     *UserHandle,
 713   IN EFI_GUID           *Protocol,
 714   IN EFI_INTERFACE_TYPE InterfaceType,
 715   IN VOID               *Interface
 716   )
 717 /*++
 718
 719 Routine Description:
 720
 721   Wrapper function to CoreInstallProtocolInterfaceNotify.  This is the public API which
 722   Calls the private one which contains a BOOLEAN parameter for notifications
 723
 724 Arguments:
 725
 726   UserHandle     - The handle to install the protocol handler on,
 727                     or NULL if a new handle is to be allocated
 728
 729   Protocol       - The protocol to add to the handle
 730
 731   InterfaceType  - Indicates whether Interface is supplied in native form.
 732
 733   Interface      - The interface for the protocol being added
 734
 735 Returns:
 736
 737   Status code
 738
 739 --*/
 740 ;
 741
 742 EFI_STATUS
 743 CoreInstallProtocolInterfaceNotify (
 744   IN OUT EFI_HANDLE     *UserHandle,
 745   IN EFI_GUID           *Protocol,
 746   IN EFI_INTERFACE_TYPE InterfaceType,
 747   IN VOID               *Interface,
 748   IN BOOLEAN            Notify
 749   )
 750 /*++
 751
 752 Routine Description:
 753
 754   Installs a protocol interface into the boot services environment.
 755
 756 Arguments:
 757
 758   UserHandle     - The handle to install the protocol handler on,
 759                    or NULL if a new handle is to be allocated
 760
 761   Protocol       - The protocol to add to the handle
 762
 763   InterfaceType  - Indicates whether Interface is supplied in native form.
 764
 765   Interface      - The interface for the protocol being added
 766
 767   Notify         - Whether to notify the notification list for this protocol
 768
 769 Returns:
 770
 771   EFI_INVALID_PARAMETER     - Invalid parameter
 772
 773   EFI_OUT_OF_RESOURCES       - No enough buffer to allocate
 774
 775   EFI_SUCCESS               - Protocol interface successfully installed
 776
 777 --*/
 778 ;
 779
 780
 781 EFI_STATUS
 782 EFIAPI
 783 CoreInstallMultipleProtocolInterfaces (
 784   IN OUT EFI_HANDLE           *Handle,
 785   ...
 786   )
 787 /*++
 788
 789 Routine Description:
 790
 791   Installs a list of protocol interface into the boot services environment.
 792   This function calls InstallProtocolInterface() in a loop. If any error
 793   occures all the protocols added by this function are removed. This is
 794   basically a lib function to save space.
 795
 796 Arguments:
 797
 798   Handle      - The handle to install the protocol handlers on,
 799                 or NULL if a new handle is to be allocated
 800   ...         - EFI_GUID followed by protocol instance. A NULL terminates the
 801                 list. The pairs are the arguments to InstallProtocolInterface().
 802                 All the protocols are added to Handle.
 803
 804 Returns:
 805
 806   EFI_INVALID_PARAMETER       - Handle is NULL.
 807
 808   EFI_SUCCESS                 - Protocol interfaces successfully installed.
 809
 810 --*/
 811 ;
 812
 813
 814 EFI_STATUS
 815 EFIAPI
 816 CoreUninstallMultipleProtocolInterfaces (
 817   IN EFI_HANDLE           Handle,
 818   ...
 819   )
 820 /*++
 821
 822 Routine Description:
 823
 824   Uninstalls a list of protocol interface in the boot services environment.
 825   This function calls UnisatllProtocolInterface() in a loop. This is
 826   basically a lib function to save space.
 827
 828 Arguments:
 829
 830   Handle      - The handle to uninstall the protocol
 831
 832   ...         - EFI_GUID followed by protocol instance. A NULL terminates the
 833                 list. The pairs are the arguments to UninstallProtocolInterface().
 834                 All the protocols are added to Handle.
 835
 836 Returns:
 837
 838   Status code
 839
 840 --*/
 841 ;
 842
 843
 844 EFI_STATUS
 845 EFIAPI
 846 CoreReinstallProtocolInterface (
 847   IN EFI_HANDLE     UserHandle,
 848   IN EFI_GUID       *Protocol,
 849   IN VOID           *OldInterface,
 850   IN VOID           *NewInterface
 851   )
 852 /*++
 853
 854 Routine Description:
 855
 856   Reinstall a protocol interface on a device handle.  The OldInterface for Protocol is replaced by the NewInterface.
 857
 858 Arguments:
 859
 860   UserHandle    - Handle on which the interface is to be reinstalled
 861   Protocol      - The numeric ID of the interface
 862   OldInterface  - A pointer to the old interface
 863   NewInterface  - A pointer to the new interface
 864
 865
 866 Returns:
 867
 868   Status code.
 869
 870   On EFI_SUCCESS            The protocol interface was installed
 871   On EFI_NOT_FOUND          The OldInterface on the handle was not found
 872   On EFI_INVALID_PARAMETER  One of the parameters has an invalid value
 873
 874 --*/
 875 ;
 876
 877
 878 EFI_STATUS
 879 EFIAPI
 880 CoreUninstallProtocolInterface (
 881   IN EFI_HANDLE       UserHandle,
 882   IN EFI_GUID         *Protocol,
 883   IN VOID             *Interface
 884   )
 885 /*++
 886
 887 Routine Description:
 888
 889   Uninstalls all instances of a protocol:interfacer from a handle.
 890   If the last protocol interface is remove from the handle, the
 891   handle is freed.
 892
 893 Arguments:
 894
 895   UserHandle      - The handle to remove the protocol handler from
 896
 897   Protocol        - The protocol, of protocol:interface, to remove
 898
 899   Interface       - The interface, of protocol:interface, to remove
 900
 901 Returns:
 902
 903   EFI_INVALID_PARAMETER       - Protocol is NULL.
 904
 905   EFI_SUCCESS                 - Protocol interface successfully uninstalled.
 906
 907 --*/
 908 ;
 909
 910
 911 EFI_STATUS
 912 EFIAPI
 913 CoreHandleProtocol (
 914   IN  EFI_HANDLE       UserHandle,
 915   IN  EFI_GUID         *Protocol,
 916   OUT VOID             **Interface
 917   )
 918 /*++
 919
 920 Routine Description:
 921
 922   Queries a handle to determine if it supports a specified protocol.
 923
 924 Arguments:
 925
 926   UserHandle  - The handle being queried.
 927
 928   Protocol    - The published unique identifier of the protocol.
 929
 930   Interface   - Supplies the address where a pointer to the corresponding Protocol
 931                Interface is returned.
 932
 933 Returns:
 934
 935   The requested protocol interface for the handle
 936
 937 --*/
 938 ;
 939
 940
 941 EFI_STATUS
 942 EFIAPI
 943 CoreOpenProtocol (
 944   IN  EFI_HANDLE                UserHandle,
 945   IN  EFI_GUID                  *Protocol,
 946   OUT VOID                      **Interface OPTIONAL,
 947   IN  EFI_HANDLE                ImageHandle,
 948   IN  EFI_HANDLE                ControllerHandle,
 949   IN  UINT32                    Attributes
 950   )
 951 /*++
 952
 953 Routine Description:
 954
 955   Locates the installed protocol handler for the handle, and
 956   invokes it to obtain the protocol interface. Usage information
 957   is registered in the protocol data base.
 958
 959 Arguments:
 960
 961   UserHandle        - The handle to obtain the protocol interface on
 962
 963   Protocol          - The ID of the protocol
 964
 965   Interface         - The location to return the protocol interface
 966
 967   ImageHandle       - The handle of the Image that is opening the protocol interface
 968                     specified by Protocol and Interface.
 969
 970   ControllerHandle  - The controller handle that is requiring this interface.
 971
 972   Attributes     - The open mode of the protocol interface specified by Handle
 973                     and Protocol.
 974
 975 Returns:
 976
 977   EFI_INVALID_PARAMETER       - Protocol is NULL.
 978
 979   EFI_SUCCESS                 - Get the protocol interface.
 980
 981 --*/
 982 ;
 983
 984
 985 EFI_STATUS
 986 EFIAPI
 987 CoreOpenProtocolInformation (
 988   IN  EFI_HANDLE                          UserHandle,
 989   IN  EFI_GUID                            *Protocol,
 990   OUT EFI_OPEN_PROTOCOL_INFORMATION_ENTRY **EntryBuffer,
 991   OUT UINTN                               *EntryCount
 992   )
 993 /*++
 994
 995 Routine Description:
 996
 997   Return information about Opened protocols in the system
 998
 999 Arguments:
1000
1001   UserHandle  - The handle to close the protocol interface on
1002
1003   Protocol    - The ID of the protocol
1004
1005   EntryBuffer - A pointer to a buffer of open protocol information in the form of
1006                 EFI_OPEN_PROTOCOL_INFORMATION_ENTRY structures.
1007
1008   EntryCount  - Number of EntryBuffer entries
1009
1010 Returns:
1011
1012
1013 --*/
1014 ;
1015
1016
1017 EFI_STATUS
1018 EFIAPI
1019 CoreCloseProtocol (
1020   IN  EFI_HANDLE                UserHandle,
1021   IN  EFI_GUID                  *Protocol,
1022   IN  EFI_HANDLE                ImageHandle,
1023   IN  EFI_HANDLE                ControllerHandle
1024   )
1025 /*++
1026
1027 Routine Description:
1028
1029   Close Protocol
1030
1031 Arguments:
1032
1033   UserHandle       - The handle to close the protocol interface on
1034
1035   Protocol         - The ID of the protocol
1036
1037   ImageHandle      - The user of the protocol to close
1038
1039   ControllerHandle - The user of the protocol to close
1040
1041 Returns:
1042
1043   EFI_INVALID_PARAMETER     - Protocol is NULL.
1044
1045 --*/
1046 ;
1047
1048
1049 EFI_STATUS
1050 EFIAPI
1051 CoreProtocolsPerHandle (
1052   IN  EFI_HANDLE       UserHandle,
1053   OUT EFI_GUID         ***ProtocolBuffer,
1054   OUT UINTN            *ProtocolBufferCount
1055   )
1056 /*++
1057
1058 Routine Description:
1059
1060   Retrieves the list of protocol interface GUIDs that are installed on a handle in a buffer allocated
1061  from pool.
1062
1063 Arguments:
1064
1065   UserHandle           - The handle from which to retrieve the list of protocol interface
1066                           GUIDs.
1067
1068   ProtocolBuffer       - A pointer to the list of protocol interface GUID pointers that are
1069                           installed on Handle.
1070
1071   ProtocolBufferCount  - A pointer to the number of GUID pointers present in
1072                           ProtocolBuffer.
1073
1074 Returns:
1075   EFI_SUCCESS   -  The list of protocol interface GUIDs installed on Handle was returned in
1076                    ProtocolBuffer. The number of protocol interface GUIDs was
1077                    returned in ProtocolBufferCount.
1078   EFI_INVALID_PARAMETER   -  Handle is NULL.
1079   EFI_INVALID_PARAMETER   -  Handle is not a valid EFI_HANDLE.
1080   EFI_INVALID_PARAMETER   -  ProtocolBuffer is NULL.
1081   EFI_INVALID_PARAMETER   -  ProtocolBufferCount is NULL.
1082   EFI_OUT_OF_RESOURCES    -  There is not enough pool memory to store the results.
1083
1084 --*/
1085 ;
1086
1087
1088 EFI_STATUS
1089 EFIAPI
1090 CoreRegisterProtocolNotify (
1091   IN  EFI_GUID       *Protocol,
1092   IN  EFI_EVENT      Event,
1093   OUT VOID           **Registration
1094   )
1095 /*++
1096
1097 Routine Description:
1098
1099   Add a new protocol notification record for the request protocol.
1100
1101 Arguments:
1102
1103   Protocol      - The requested protocol to add the notify registration
1104
1105   Event         - The event to signal
1106
1107   Registration  - Returns the registration record
1108
1109
1110 Returns:
1111
1112   EFI_INVALID_PARAMETER       - Invalid parameter
1113
1114   EFI_SUCCESS                 - Successfully returned the registration record that has been added
1115
1116 --*/
1117 ;
1118
1119
1120 EFI_STATUS
1121 EFIAPI
1122 CoreLocateHandle (
1123   IN     EFI_LOCATE_SEARCH_TYPE         SearchType,
1124   IN     EFI_GUID                       *Protocol OPTIONAL,
1125   IN     VOID                           *SearchKey OPTIONAL,
1126   IN OUT UINTN                          *BufferSize,
1127   OUT    EFI_HANDLE                     *Buffer
1128   )
1129 /*++
1130
1131 Routine Description:
1132
1133   Locates the requested handle(s) and returns them in Buffer.
1134
1135 Arguments:
1136
1137   SearchType  - The type of search to perform to locate the handles
1138
1139   Protocol    - The protocol to search for
1140
1141   SearchKey   - Dependant on SearchType
1142
1143   BufferSize  - On input the size of Buffer.  On output the
1144                 size of data returned.
1145
1146   Buffer      - The buffer to return the results in
1147
1148
1149 Returns:
1150
1151   EFI_BUFFER_TOO_SMALL      - Buffer too small, required buffer size is returned in BufferSize.
1152
1153   EFI_INVALID_PARAMETER     - Invalid parameter
1154
1155   EFI_SUCCESS               - Successfully found the requested handle(s) and returns them in Buffer.
1156
1157 --*/
1158 ;
1159
1160
1161 EFI_STATUS
1162 EFIAPI
1163 CoreLocateDevicePath (
1164   IN     EFI_GUID                       *Protocol,
1165   IN OUT EFI_DEVICE_PATH_PROTOCOL       **FilePath,
1166   OUT    EFI_HANDLE                     *Device
1167   )
1168 /*++
1169
1170 Routine Description:
1171
1172   Locates the handle to a device on the device path that supports the specified protocol.
1173
1174 Arguments:
1175
1176   Protocol    - The protocol to search for.
1177   FilePath    - On input, a pointer to a pointer to the device path. On output, the device
1178                   path pointer is modified to point to the remaining part of the devicepath.
1179   Device      - A pointer to the returned device handle.
1180
1181 Returns:
1182
1183   EFI_SUCCESS           - The resulting handle was returned.
1184   EFI_NOT_FOUND         - No handles matched the search.
1185   EFI_INVALID_PARAMETER - One of the parameters has an invalid value.
1186
1187 --*/
1188 ;
1189
1190
1191 EFI_STATUS
1192 EFIAPI
1193 CoreLocateHandleBuffer (
1194   IN     EFI_LOCATE_SEARCH_TYPE         SearchType,
1195   IN     EFI_GUID                       *Protocol OPTIONAL,
1196   IN     VOID                           *SearchKey OPTIONAL,
1197   IN OUT UINTN                          *NumberHandles,
1198   OUT    EFI_HANDLE                     **Buffer
1199   )
1200 /*++
1201
1202 Routine Description:
1203
1204   Function returns an array of handles that support the requested protocol
1205   in a buffer allocated from pool. This is a version of CoreLocateHandle()
1206   that allocates a buffer for the caller.
1207
1208 Arguments:
1209
1210   SearchType           - Specifies which handle(s) are to be returned.
1211   Protocol             - Provides the protocol to search by.
1212                          This parameter is only valid for SearchType ByProtocol.
1213   SearchKey            - Supplies the search key depending on the SearchType.
1214   NumberHandles      - The number of handles returned in Buffer.
1215   Buffer               - A pointer to the buffer to return the requested array of
1216                          handles that support Protocol.
1217
1218 Returns:
1219
1220   EFI_SUCCESS             - The result array of handles was returned.
1221   EFI_NOT_FOUND           - No handles match the search.
1222   EFI_OUT_OF_RESOURCES    - There is not enough pool memory to store the matching results.
1223   EFI_INVALID_PARAMETER   - Invalid parameter
1224
1225 --*/
1226 ;
1227
1228
1229 EFI_STATUS
1230 EFIAPI
1231 CoreLocateProtocol (
1232   IN    EFI_GUID  *Protocol,
1233   IN    VOID      *Registration OPTIONAL,
1234   OUT   VOID      **Interface
1235   )
1236 /*++
1237
1238 Routine Description:
1239
1240   Return the first Protocol Interface that matches the Protocol GUID. If
1241   Registration is pasased in return a Protocol Instance that was just add
1242   to the system. If Retistration is NULL return the first Protocol Interface
1243   you find.
1244
1245 Arguments:
1246
1247   Protocol     - The protocol to search for
1248
1249   Registration - Optional Registration Key returned from RegisterProtocolNotify()
1250
1251   Interface    - Return the Protocol interface (instance).
1252
1253 Returns:
1254
1255   EFI_SUCCESS                 - If a valid Interface is returned
1256
1257   EFI_INVALID_PARAMETER       - Invalid parameter
1258
1259   EFI_NOT_FOUND               - Protocol interface not found
1260
1261 --*/
1262 ;
1263
1264 UINT64
1265 CoreGetHandleDatabaseKey (
1266   VOID
1267   )
1268 /*++
1269
1270 Routine Description:
1271
1272   return handle database key.
1273
1274 Arguments:
1275
1276   None
1277
1278 Returns:
1279
1280   Handle database key.
1281
1282 --*/
1283 ;
1284
1285 VOID
1286 CoreConnectHandlesByKey (
1287   UINT64  Key
1288   )
1289 /*++
1290
1291 Routine Description:
1292
1293   Go connect any handles that were created or modified while a image executed.
1294
1295 Arguments:
1296
1297   Key  -  The Key to show that the handle has been created/modified
1298
1299 Returns:
1300
1301   None
1302 --*/
1303 ;
1304
1305
1306 EFI_STATUS
1307 EFIAPI
1308 CoreConnectController (
1309   IN  EFI_HANDLE                ControllerHandle,
1310   IN  EFI_HANDLE                *DriverImageHandle    OPTIONAL,
1311   IN  EFI_DEVICE_PATH_PROTOCOL  *RemainingDevicePath  OPTIONAL,
1312   IN  BOOLEAN                   Recursive
1313   )
1314 /*++
1315
1316 Routine Description:
1317
1318   Connects one or more drivers to a controller.
1319
1320 Arguments:
1321
1322   ControllerHandle            - Handle of the controller to be connected.
1323
1324   DriverImageHandle           - DriverImageHandle A pointer to an ordered list of driver image handles.
1325
1326   RemainingDevicePath         - RemainingDevicePath A pointer to the device path that specifies a child of the
1327                                 controller specified by ControllerHandle.
1328
1329   Recursive -                 - Whether the function would be called recursively or not.
1330
1331 Returns:
1332
1333   Status code.
1334
1335 --*/
1336 ;
1337
1338
1339 EFI_STATUS
1340 EFIAPI
1341 CoreDisconnectController (
1342   IN EFI_HANDLE  ControllerHandle,
1343   IN EFI_HANDLE  DriverImageHandle  OPTIONAL,
1344   IN EFI_HANDLE  ChildHandle        OPTIONAL
1345   )
1346 /*++
1347
1348 Routine Description:
1349
1350   Disonnects a controller from a driver
1351
1352 Arguments:
1353
1354   ControllerHandle  - ControllerHandle The handle of the controller from which driver(s)
1355                         are to be disconnected.
1356   DriverImageHandle - DriverImageHandle The driver to disconnect from ControllerHandle.
1357   ChildHandle       - ChildHandle The handle of the child to destroy.
1358
1359 Returns:
1360
1361   EFI_SUCCESS           -  One or more drivers were disconnected from the controller.
1362   EFI_SUCCESS           -  On entry, no drivers are managing ControllerHandle.
1363   EFI_SUCCESS           -  DriverImageHandle is not NULL, and on entry DriverImageHandle is not managing ControllerHandle.
1364   EFI_INVALID_PARAMETER -  ControllerHandle is not a valid EFI_HANDLE.
1365   EFI_INVALID_PARAMETER -  DriverImageHandle is not NULL, and it is not a valid EFI_HANDLE.
1366   EFI_INVALID_PARAMETER -  ChildHandle is not NULL, and it is not a valid EFI_HANDLE.
1367   EFI_OUT_OF_RESOURCES  -  There are not enough resources available to disconnect any drivers from ControllerHandle.
1368   EFI_DEVICE_ERROR      -  The controller could not be disconnected because of a device error.
1369
1370 --*/
1371 ;
1372
1373
1374 EFI_STATUS
1375 EFIAPI
1376 CoreAllocatePages (
1377   IN      EFI_ALLOCATE_TYPE       Type,
1378   IN      EFI_MEMORY_TYPE         MemoryType,
1379   IN      UINTN                   NumberOfPages,
1380   IN OUT  EFI_PHYSICAL_ADDRESS    *Memory
1381   )
1382 /*++
1383
1384 Routine Description:
1385
1386   Allocates pages from the memory map.
1387
1388 Arguments:
1389
1390   Type          - The type of allocation to perform
1391
1392   MemoryType    - The type of memory to turn the allocated pages into
1393
1394   NumberOfPages - The number of pages to allocate
1395
1396   Memory        - A pointer to receive the base allocated memory address
1397
1398 Returns:
1399
1400   Status. On success, Memory is filled in with the base address allocated
1401
1402   EFI_INVALID_PARAMETER     - Parameters violate checking rules defined in spec.
1403
1404   EFI_NOT_FOUND             - Could not allocate pages match the requirement.
1405
1406   EFI_OUT_OF_RESOURCES      - No enough pages to allocate.
1407
1408   EFI_SUCCESS               - Pages successfully allocated.
1409
1410 --*/
1411 ;
1412
1413
1414 EFI_STATUS
1415 EFIAPI
1416 CoreFreePages (
1417   IN EFI_PHYSICAL_ADDRESS   Memory,
1418   IN UINTN                  NumberOfPages
1419   )
1420 /*++
1421
1422 Routine Description:
1423
1424   Frees previous allocated pages.
1425
1426 Arguments:
1427
1428   Memory        - Base address of memory being freed
1429
1430   NumberOfPages - The number of pages to free
1431
1432 Returns:
1433
1434   EFI_NOT_FOUND       - Could not find the entry that covers the range
1435
1436   EFI_INVALID_PARAMETER   - Address not aligned
1437
1438   EFI_SUCCESS         -Pages successfully freed.
1439
1440 --*/
1441 ;
1442
1443
1444 EFI_STATUS
1445 EFIAPI
1446 CoreGetMemoryMap (
1447   IN OUT UINTN                       *MemoryMapSize,
1448   IN OUT EFI_MEMORY_DESCRIPTOR       *Desc,
1449   OUT    UINTN                       *MapKey,
1450   OUT    UINTN                       *DescriptorSize,
1451   OUT    UINT32                      *DescriptorVersion
1452   )
1453 /*++
1454
1455 Routine Description:
1456
1457   Returns the current memory map.
1458
1459 Arguments:
1460
1461   MemoryMapSize     - On input the buffer size of MemoryMap allocated by caller
1462                       On output the required buffer size to contain the memory map
1463
1464   Desc              - The buffer to return the current memory map
1465
1466   MapKey            - The address to return the current map key
1467
1468   DescriptorSize    - The size in bytes for an individual EFI_MEMORY_DESCRIPTOR
1469
1470   DescriptorVersion - The version number associated with the EFI_MEMORY_DESCRIPTOR
1471
1472 Returns:
1473
1474   EFI_SUCCESS           The current memory map was returned successfully
1475
1476   EFI_BUFFER_TOO_SMALL  The MemoryMap buffer was too small
1477
1478   EFI_INVALID_PARAMETER One of the parameters has an invalid value
1479
1480 --*/
1481 ;
1482
1483
1484 EFI_STATUS
1485 EFIAPI
1486 CoreAllocatePool (
1487   IN   EFI_MEMORY_TYPE  PoolType,
1488   IN   UINTN            Size,
1489   OUT  VOID             **Buffer
1490   )
1491 /*++
1492
1493 Routine Description:
1494
1495   Allocate pool of a particular type.
1496
1497 Arguments:
1498
1499   PoolType    - Type of pool to allocate
1500
1501   Size        - The amount of pool to allocate
1502
1503   Buffer      - The address to return a pointer to the allocated pool
1504
1505 Returns:
1506
1507   EFI_INVALID_PARAMETER     - PoolType not valid
1508
1509   EFI_OUT_OF_RESOURCES      - Size exceeds max pool size or allocation failed.
1510
1511   EFI_SUCCESS               - Pool successfully allocated.
1512
1513 --*/
1514 ;
1515
1516
1517 EFI_STATUS
1518 EFIAPI
1519 CoreFreePool (
1520   IN VOID      *Buffer
1521   )
1522 /*++
1523
1524 Routine Description:
1525
1526   Frees pool.
1527
1528 Arguments:
1529
1530   Buffer      - The allocated pool entry to free
1531
1532 Returns:
1533
1534   EFI_INVALID_PARAMETER   - Buffer is not a valid value.
1535
1536   EFI_SUCCESS             - Pool successfully freed.
1537
1538 --*/
1539 ;
1540
1541
1542 EFI_STATUS
1543 EFIAPI
1544 CoreLoadImage (
1545   IN  BOOLEAN                    BootPolicy,
1546   IN  EFI_HANDLE                 ParentImageHandle,
1547   IN  EFI_DEVICE_PATH_PROTOCOL   *FilePath,
1548   IN  VOID                       *SourceBuffer   OPTIONAL,
1549   IN  UINTN                      SourceSize,
1550   OUT EFI_HANDLE                 *ImageHandle
1551   )
1552 /*++
1553
1554 Routine Description:
1555
1556   Loads an EFI image into memory and returns a handle to the image.
1557
1558 Arguments:
1559
1560   BootPolicy          - If TRUE, indicates that the request originates from the boot manager,
1561                         and that the boot manager is attempting to load FilePath as a boot selection.
1562   ParentImageHandle   - The caller's image handle.
1563   FilePath            - The specific file path from which the image is loaded.
1564   SourceBuffer        - If not NULL, a pointer to the memory location containing a copy of
1565                         the image to be loaded.
1566   SourceSize          - The size in bytes of SourceBuffer.
1567   ImageHandle         - Pointer to the returned image handle that is created when the image
1568                         is successfully loaded.
1569
1570 Returns:
1571
1572   EFI_SUCCESS            - The image was loaded into memory.
1573   EFI_NOT_FOUND          - The FilePath was not found.
1574   EFI_INVALID_PARAMETER  - One of the parameters has an invalid value.
1575   EFI_UNSUPPORTED        - The image type is not supported, or the device path cannot be
1576                            parsed to locate the proper protocol for loading the file.
1577   EFI_OUT_OF_RESOURCES   - Image was not loaded due to insufficient resources.
1578 --*/
1579 ;
1580
1581
1582 EFI_STATUS
1583 EFIAPI
1584 CoreUnloadImage (
1585   IN EFI_HANDLE  ImageHandle
1586   )
1587 /*++
1588
1589 Routine Description:
1590
1591   Unload the specified image.
1592
1593 Arguments:
1594
1595   ImageHandle       - The specified image handle.
1596
1597 Returns:
1598
1599   EFI_INVALID_PARAMETER       - Image handle is NULL.
1600
1601   EFI_UNSUPPORTED             - Attempt to unload an unsupported image.
1602
1603   EFI_SUCCESS                 - Image successfully unloaded.
1604
1605 --*/
1606 ;
1607
1608
1609 EFI_STATUS
1610 EFIAPI
1611 CoreStartImage (
1612   IN  EFI_HANDLE  ImageHandle,
1613   OUT UINTN       *ExitDataSize,
1614   OUT CHAR16      **ExitData  OPTIONAL
1615   )
1616 /*++
1617
1618 Routine Description:
1619
1620   Transfer control to a loaded image's entry point.
1621
1622 Arguments:
1623
1624   ImageHandle     - Handle of image to be started.
1625
1626   ExitDataSize    - Pointer of the size to ExitData
1627
1628   ExitData        - Pointer to a pointer to a data buffer that includes a Null-terminated
1629                     Unicode string, optionally followed by additional binary data. The string
1630                     is a description that the caller may use to further indicate the reason for
1631                     the image's exit.
1632
1633 Returns:
1634
1635   EFI_INVALID_PARAMETER     - Invalid parameter
1636
1637   EFI_OUT_OF_RESOURCES       - No enough buffer to allocate
1638
1639   EFI_SUCCESS               - Successfully transfer control to the image's entry point.
1640
1641 --*/
1642 ;
1643
1644
1645 EFI_STATUS
1646 EFIAPI
1647 CoreExit (
1648   IN EFI_HANDLE  ImageHandle,
1649   IN EFI_STATUS  Status,
1650   IN UINTN       ExitDataSize,
1651   IN CHAR16      *ExitData  OPTIONAL
1652   )
1653 /*++
1654
1655 Routine Description:
1656
1657   Terminates the currently loaded EFI image and returns control to boot services.
1658
1659 Arguments:
1660
1661   ImageHandle       - Handle that identifies the image. This parameter is passed to the image
1662                       on entry.
1663   Status            - The image's exit code.
1664   ExitDataSize      - The size, in bytes, of ExitData. Ignored if ExitStatus is
1665                       EFI_SUCCESS.
1666   ExitData          - Pointer to a data buffer that includes a Null-terminated Unicode string,
1667                       optionally followed by additional binary data. The string is a
1668                       description that the caller may use to further indicate the reason for
1669                       the image's exit.
1670
1671 Returns:
1672
1673   EFI_INVALID_PARAMETER     - Image handle is NULL or it is not current image.
1674
1675   EFI_SUCCESS               - Successfully terminates the currently loaded EFI image.
1676
1677   EFI_ACCESS_DENIED         - Should never reach there.
1678
1679 --*/
1680 ;
1681
1682
1683 EFI_STATUS
1684 EFIAPI
1685 CoreCreateEvent (
1686   IN  UINT32               Type,
1687   IN  EFI_TPL              NotifyTpl,
1688   IN  EFI_EVENT_NOTIFY     NotifyFunction,
1689   IN  VOID                 *NotifyContext,
1690   OUT EFI_EVENT            *pEvent
1691   )
1692 /*++
1693
1694 Routine Description:
1695
1696   Creates a general-purpose event structure
1697
1698 Arguments:
1699
1700   Type                - The type of event to create and its mode and attributes
1701   NotifyTpl           - The task priority level of event notifications
1702   NotifyFunction      - Pointer to the event's notification function
1703   NotifyContext       - Pointer to the notification function's context; corresponds to
1704                         parameter "Context" in the notification function
1705   pEvent              - Pointer to the newly created event if the call succeeds; undefined otherwise
1706
1707 Returns:
1708
1709   EFI_SUCCESS           - The event structure was created
1710   EFI_INVALID_PARAMETER - One of the parameters has an invalid value
1711   EFI_OUT_OF_RESOURCES  - The event could not be allocated
1712
1713 --*/
1714 ;
1715
1716
1717 EFI_STATUS
1718 EFIAPI
1719 CoreCreateEventEx (
1720   IN UINT32                   Type,
1721   IN EFI_TPL                  NotifyTpl,
1722   IN EFI_EVENT_NOTIFY         NotifyFunction, OPTIONAL
1723   IN CONST VOID               *NotifyContext, OPTIONAL
1724   IN CONST EFI_GUID           *EventGroup,    OPTIONAL
1725   OUT EFI_EVENT               *Event
1726   )
1727 /*++
1728
1729 Routine Description:
1730   Creates a general-purpose event structure
1731
1732 Arguments:
1733   Type                - The type of event to create and its mode and attributes
1734   NotifyTpl           - The task priority level of event notifications
1735   NotifyFunction      - Pointer to the events notification function
1736   NotifyContext       - Pointer to the notification functions context; corresponds to
1737                         parameter "Context" in the notification function
1738   EventGrout          - GUID for EventGroup if NULL act the same as gBS->CreateEvent().
1739   Event               - Pointer to the newly created event if the call succeeds; undefined otherwise
1740
1741 Returns:
1742   EFI_SUCCESS           - The event structure was created
1743   EFI_INVALID_PARAMETER - One of the parameters has an invalid value
1744   EFI_OUT_OF_RESOURCES  - The event could not be allocated
1745
1746 --*/
1747 ;
1748
1749
1750 EFI_STATUS
1751 EFIAPI
1752 CoreSetTimer (
1753   IN EFI_EVENT            Event,
1754   IN EFI_TIMER_DELAY      Type,
1755   IN UINT64               TriggerTime
1756   )
1757 /*++
1758
1759 Routine Description:
1760
1761   Sets the type of timer and the trigger time for a timer event.
1762
1763 Arguments:
1764
1765   UserEvent   - The timer event that is to be signaled at the specified time
1766   Type        - The type of time that is specified in TriggerTime
1767   TriggerTime - The number of 100ns units until the timer expires
1768
1769 Returns:
1770
1771   EFI_SUCCESS           - The event has been set to be signaled at the requested time
1772   EFI_INVALID_PARAMETER - Event or Type is not valid
1773
1774 --*/
1775 ;
1776
1777
1778 EFI_STATUS
1779 EFIAPI
1780 CoreSignalEvent (
1781   IN EFI_EVENT            Event
1782   )
1783 /*++
1784
1785 Routine Description:
1786
1787   Signals the event.  Queues the event to be notified if needed
1788
1789 Arguments:
1790
1791   Event - The event to signal
1792
1793 Returns:
1794
1795   EFI_INVALID_PARAMETER - Parameters are not valid.
1796
1797   EFI_SUCCESS - The event was signaled.
1798
1799 --*/
1800 ;
1801
1802
1803 EFI_STATUS
1804 EFIAPI
1805 CoreWaitForEvent (
1806   IN  UINTN        NumberOfEvents,
1807   IN  EFI_EVENT    *UserEvents,
1808   OUT UINTN        *UserIndex
1809   )
1810 /*++
1811
1812 Routine Description:
1813
1814   Stops execution until an event is signaled.
1815
1816 Arguments:
1817
1818   NumberOfEvents  - The number of events in the UserEvents array
1819   UserEvents      - An array of EFI_EVENT
1820   UserIndex       - Pointer to the index of the event which satisfied the wait condition
1821
1822 Returns:
1823
1824   EFI_SUCCESS           - The event indicated by Index was signaled.
1825   EFI_INVALID_PARAMETER - The event indicated by Index has a notification function or
1826                           Event was not a valid type
1827   EFI_UNSUPPORTED       - The current TPL is not TPL_APPLICATION
1828
1829 --*/
1830 ;
1831
1832
1833 EFI_STATUS
1834 EFIAPI
1835 CoreCloseEvent (
1836   IN EFI_EVENT            Event
1837   )
1838 /*++
1839
1840 Routine Description:
1841
1842   Closes an event and frees the event structure.
1843
1844 Arguments:
1845
1846   UserEvent - Event to close
1847
1848 Returns:
1849
1850   EFI_INVALID_PARAMETER - Parameters are not valid.
1851
1852   EFI_SUCCESS - The event has been closed
1853
1854 --*/
1855 ;
1856
1857
1858 EFI_STATUS
1859 EFIAPI
1860 CoreCheckEvent (
1861   IN EFI_EVENT            Event
1862   )
1863 /*++
1864
1865 Routine Description:
1866
1867   Check the status of an event
1868
1869 Arguments:
1870
1871   UserEvent - The event to check
1872
1873 Returns:
1874
1875   EFI_SUCCESS           - The event is in the signaled state
1876   EFI_NOT_READY         - The event is not in the signaled state
1877   EFI_INVALID_PARAMETER - Event is of type EVT_NOTIFY_SIGNAL
1878
1879 --*/
1880 ;
1881
1882 EFI_STATUS
1883 CoreAddMemorySpace (
1884   IN EFI_GCD_MEMORY_TYPE   GcdMemoryType,
1885   IN EFI_PHYSICAL_ADDRESS  BaseAddress,
1886   IN UINT64                Length,
1887   IN UINT64                Capabilities
1888   )
1889 /*++
1890
1891 Routine Description:
1892
1893   Add a segment of memory space to GCD map and add all available pages in this segment
1894   as memory descriptors.
1895
1896 Arguments:
1897
1898   GcdMemoryType     - Memory type of the segment.
1899
1900   BaseAddress       - Base address of the segment.
1901
1902   Length            - Length of the segment.
1903
1904   Capabilities      - alterable attributes of the segment.
1905
1906 Returns:
1907
1908   EFI_SUCCESS       - Merged this segment into GCD map.
1909
1910 --*/
1911 ;
1912
1913 EFI_STATUS
1914 CoreAllocateMemorySpace (
1915   IN     EFI_GCD_ALLOCATE_TYPE  GcdAllocateType,
1916   IN     EFI_GCD_MEMORY_TYPE    GcdMemoryType,
1917   IN     UINTN                  Alignment,
1918   IN     UINT64                 Length,
1919   IN OUT EFI_PHYSICAL_ADDRESS   *BaseAddress,
1920   IN     EFI_HANDLE             ImageHandle,
1921   IN     EFI_HANDLE             DeviceHandle OPTIONAL
1922   )
1923 /*++
1924
1925 Routine Description:
1926
1927   Allocate memory space on GCD map.
1928
1929 Arguments:
1930
1931   GcdAllocateType   - The type of allocate operation
1932
1933   GcdMemoryType     - The desired memory type
1934
1935   Alignment         - Align with 2^Alignment
1936
1937   Length            - Length to allocate
1938
1939   BaseAddress       - Base address to allocate
1940
1941   ImageHandle       - The image handle consume the allocated space.
1942
1943   DeviceHandle      - The device handle consume the allocated space.
1944
1945 Returns:
1946
1947   EFI_INVALID_PARAMETER       - Invalid parameter.
1948
1949   EFI_NOT_FOUND               - No descriptor contains the desired space.
1950
1951   EFI_SUCCESS                 - Memory space successfully allocated.
1952
1953 --*/
1954 ;
1955
1956 EFI_STATUS
1957 CoreFreeMemorySpace (
1958   IN EFI_PHYSICAL_ADDRESS  BaseAddress,
1959   IN UINT64                Length
1960   )
1961 /*++
1962
1963 Routine Description:Routine Description:
1964
1965   Free a segment of memory space in GCD map.
1966
1967 Arguments:
1968
1969   BaseAddress       - Base address of the segment.
1970
1971   Length            - Length of the segment.
1972
1973 Returns:
1974
1975   EFI_SUCCESS       - Space successfully freed.
1976
1977 --*/
1978 ;
1979
1980 EFI_STATUS
1981 CoreRemoveMemorySpace (
1982   IN EFI_PHYSICAL_ADDRESS  BaseAddress,
1983   IN UINT64                Length
1984   )
1985 /*++
1986
1987 Routine Description:Routine Description:
1988
1989   Remove a segment of memory space in GCD map.
1990
1991 Arguments:
1992
1993   BaseAddress       - Base address of the segment.
1994
1995   Length            - Length of the segment.
1996
1997 Returns:
1998
1999   EFI_SUCCESS       - Successfully a segment of memory space.
2000
2001 --*/
2002 ;
2003
2004 EFI_STATUS
2005 CoreGetMemorySpaceDescriptor (
2006   IN  EFI_PHYSICAL_ADDRESS             BaseAddress,
2007   OUT EFI_GCD_MEMORY_SPACE_DESCRIPTOR  *Descriptor
2008   )
2009 /*++
2010
2011 Routine Description:
2012
2013   Search all entries in GCD map which contains specified segment and build it to a descriptor.
2014
2015 Arguments:
2016
2017   BaseAddress       - Specified start address
2018
2019   Descriptor        - Specified length
2020
2021 Returns:
2022
2023   EFI_INVALID_PARAMETER       - Invalid parameter
2024
2025   EFI_SUCCESS                 - Successfully get memory space descriptor.
2026
2027 --*/
2028 ;
2029
2030 EFI_STATUS
2031 CoreSetMemorySpaceAttributes (
2032   IN EFI_PHYSICAL_ADDRESS  BaseAddress,
2033   IN UINT64                Length,
2034   IN UINT64                Attributes
2035   )
2036 /*++
2037
2038 Routine Description:
2039
2040   Set memory space with specified attributes.
2041
2042 Arguments:
2043
2044   BaseAddress       - Specified start address
2045
2046   Length            - Specified length
2047
2048   Attributes        - Specified attributes
2049
2050 Returns:
2051
2052   EFI_SUCCESS       - Successfully set attribute of a segment of memory space.
2053
2054 --*/
2055 ;
2056
2057 EFI_STATUS
2058 CoreGetMemorySpaceMap (
2059   OUT UINTN                            *NumberOfDescriptors,
2060   OUT EFI_GCD_MEMORY_SPACE_DESCRIPTOR  **MemorySpaceMap
2061   )
2062 /*++
2063
2064 Routine Description:
2065
2066   Transer all entries of GCD memory map into memory descriptors and pass to caller.
2067
2068 Arguments:
2069
2070   NumberOfDescriptors       - Number of descriptors.
2071
2072   MemorySpaceMap            - Descriptor array
2073
2074 Returns:
2075
2076   EFI_INVALID_PARAMETER     - Invalid parameter
2077
2078   EFI_OUT_OF_RESOURCES      - No enough buffer to allocate
2079
2080   EFI_SUCCESS               - Successfully get memory space map.
2081
2082 --*/
2083 ;
2084
2085 EFI_STATUS
2086 CoreAddIoSpace (
2087   IN EFI_GCD_IO_TYPE       GcdIoType,
2088   IN EFI_PHYSICAL_ADDRESS  BaseAddress,
2089   IN UINT64                Length
2090   )
2091 /*++
2092
2093 Routine Description:
2094
2095   Add a segment of IO space to GCD map.
2096
2097 Arguments:
2098
2099   GcdIoType         - IO type of the segment.
2100
2101   BaseAddress       - Base address of the segment.
2102
2103   Length            - Length of the segment.
2104
2105 Returns:
2106
2107   EFI_SUCCESS       - Merged this segment into GCD map.
2108
2109 --*/
2110 ;
2111
2112 EFI_STATUS
2113 CoreAllocateIoSpace (
2114   IN     EFI_GCD_ALLOCATE_TYPE  GcdAllocateType,
2115   IN     EFI_GCD_IO_TYPE        GcdIoType,
2116   IN     UINTN                  Alignment,
2117   IN     UINT64                 Length,
2118   IN OUT EFI_PHYSICAL_ADDRESS   *BaseAddress,
2119   IN     EFI_HANDLE             ImageHandle,
2120   IN     EFI_HANDLE             DeviceHandle OPTIONAL
2121   )
2122 /*++
2123
2124 Routine Description:
2125
2126   Allocate IO space on GCD map.
2127
2128 Arguments:
2129
2130   GcdAllocateType   - The type of allocate operation
2131
2132   GcdIoType         - The desired IO type
2133
2134   Alignment         - Align with 2^Alignment
2135
2136   Length            - Length to allocate
2137
2138   BaseAddress       - Base address to allocate
2139
2140   ImageHandle       - The image handle consume the allocated space.
2141
2142   DeviceHandle      - The device handle consume the allocated space.
2143
2144 Returns:
2145
2146   EFI_INVALID_PARAMETER       - Invalid parameter.
2147
2148   EFI_NOT_FOUND               - No descriptor contains the desired space.
2149
2150   EFI_SUCCESS                 - IO space successfully allocated.
2151
2152 --*/
2153 ;
2154
2155 EFI_STATUS
2156 CoreFreeIoSpace (
2157   IN EFI_PHYSICAL_ADDRESS  BaseAddress,
2158   IN UINT64                Length
2159   )
2160 /*++
2161
2162 Routine Description:Routine Description:
2163
2164   Free a segment of IO space in GCD map.
2165
2166 Arguments:
2167
2168   BaseAddress       - Base address of the segment.
2169
2170   Length            - Length of the segment.
2171
2172 Returns:
2173
2174   EFI_SUCCESS       - Space successfully freed.
2175
2176 --*/
2177 ;
2178
2179 EFI_STATUS
2180 CoreRemoveIoSpace (
2181   IN EFI_PHYSICAL_ADDRESS  BaseAddress,
2182   IN UINT64                Length
2183   )
2184 /*++
2185
2186 Routine Description:Routine Description:
2187
2188   Remove a segment of IO space in GCD map.
2189
2190 Arguments:
2191
2192   BaseAddress       - Base address of the segment.
2193
2194   Length            - Length of the segment.
2195
2196 Returns:
2197
2198   EFI_SUCCESS       - Successfully removed a segment of IO space.
2199
2200 --*/
2201 ;
2202
2203 EFI_STATUS
2204 CoreGetIoSpaceDescriptor (
2205   IN  EFI_PHYSICAL_ADDRESS         BaseAddress,
2206   OUT EFI_GCD_IO_SPACE_DESCRIPTOR  *Descriptor
2207   )
2208 /*++
2209
2210 Routine Description:
2211
2212   Search all entries in GCD map which contains specified segment and build it to a descriptor.
2213
2214 Arguments:
2215
2216   BaseAddress       - Specified start address
2217
2218   Descriptor        - Specified length
2219
2220 Returns:
2221
2222   EFI_INVALID_PARAMETER       - Descriptor is NULL.
2223
2224   EFI_SUCCESS                 - Successfully get the IO space descriptor.
2225
2226 --*/
2227 ;
2228
2229 EFI_STATUS
2230 CoreGetIoSpaceMap (
2231   OUT UINTN                        *NumberOfDescriptors,
2232   OUT EFI_GCD_IO_SPACE_DESCRIPTOR  **IoSpaceMap
2233   )
2234 /*++
2235
2236 Routine Description:
2237
2238   Transer all entries of GCD IO map into IO descriptors and pass to caller.
2239
2240 Arguments:
2241
2242   NumberOfDescriptors       - Number of descriptors.
2243
2244   IoSpaceMap                - Descriptor array
2245
2246 Returns:
2247
2248   EFI_INVALID_PARAMETER     - Invalid parameter
2249
2250   EFI_OUT_OF_RESOURCES      - No enough buffer to allocate
2251
2252   EFI_SUCCESS               - Successfully get IO space map.
2253
2254 --*/
2255 ;
2256
2257 EFI_DXESERVICE
2258 EFI_STATUS
2259 EFIAPI
2260 CoreDispatcher (
2261   VOID
2262   )
2263 /*++
2264
2265 Routine Description:
2266
2267   This is the main Dispatcher for DXE and it exits when there are no more
2268   drivers to run. Drain the mScheduledQueue and load and start a PE
2269   image for each driver. Search the mDiscoveredList to see if any driver can
2270   be placed on the mScheduledQueue. If no drivers are placed on the
2271   mScheduledQueue exit the function. On exit it is assumed the Bds()
2272   will be called, and when the Bds() exits the Dispatcher will be called
2273   again.
2274
2275 Arguments:
2276
2277   NONE
2278
2279 Returns:
2280
2281   EFI_ALREADY_STARTED - The DXE Dispatcher is already running
2282
2283   EFI_NOT_FOUND       - No DXE Drivers were dispatched
2284
2285   EFI_SUCCESS         - One or more DXE Drivers were dispatched
2286
2287 --*/
2288 ;
2289 EFI_DXESERVICE
2290 EFI_STATUS
2291 EFIAPI
2292 CoreSchedule (
2293   IN  EFI_HANDLE  FirmwareVolumeHandle,
2294   IN  EFI_GUID    *DriverName
2295   )
2296 /*++
2297
2298 Routine Description:
2299
2300   Check every driver and locate a matching one. If the driver is found, the Unrequested
2301   state flag is cleared.
2302
2303 Arguments:
2304
2305   FirmwareVolumeHandle - The handle of the Firmware Volume that contains the firmware
2306                          file specified by DriverName.
2307
2308   DriverName           - The Driver name to put in the Dependent state.
2309
2310 Returns:
2311
2312   EFI_SUCCESS   - The DriverName was found and it's SOR bit was cleared
2313
2314   EFI_NOT_FOUND - The DriverName does not exist or it's SOR bit was not set.
2315
2316 --*/
2317 ;
2318
2319 EFI_DXESERVICE
2320 EFI_STATUS
2321 EFIAPI
2322 CoreTrust (
2323   IN  EFI_HANDLE  FirmwareVolumeHandle,
2324   IN  EFI_GUID    *DriverName
2325   )
2326 /*++
2327
2328 Routine Description:
2329
2330   Convert a driver from the Untrused back to the Scheduled state
2331
2332 Arguments:
2333
2334   FirmwareVolumeHandle - The handle of the Firmware Volume that contains the firmware
2335                          file specified by DriverName.
2336
2337   DriverName           - The Driver name to put in the Scheduled state
2338
2339 Returns:
2340
2341   EFI_SUCCESS   - The file was found in the untrusted state, and it was promoted
2342                   to the trusted state.
2343
2344   EFI_NOT_FOUND - The file was not found in the untrusted state.
2345
2346 --*/
2347 ;
2348
2349 BOOLEAN
2350 CoreGrowBuffer (
2351   IN OUT EFI_STATUS       *Status,
2352   IN OUT VOID             **Buffer,
2353   IN     UINTN            BufferSize
2354   )
2355 /*++
2356
2357 Routine Description:
2358
2359     Helper function called as part of the code needed
2360     to allocate the proper sized buffer for various
2361     EFI interfaces.
2362
2363 Arguments:
2364
2365     Status      - Current status
2366
2367     Buffer      - Current allocated buffer, or NULL
2368
2369     BufferSize  - Current buffer size needed
2370
2371 Returns:
2372
2373     TRUE - if the buffer was reallocated and the caller
2374     should try the API again.
2375
2376     FALSE - buffer could not be allocated and the caller
2377     should not try the API again.
2378
2379 --*/
2380 ;
2381
2382 EFI_STATUS
2383 EFIAPI
2384 FwVolDriverInit (
2385   IN EFI_HANDLE                   ImageHandle,
2386   IN EFI_SYSTEM_TABLE             *SystemTable
2387   )
2388 /*++
2389
2390 Routine Description:
2391     This routine is the driver initialization entry point.  It initializes the
2392     libraries, and registers two notification functions.  These notification
2393     functions are responsible for building the FV stack dynamically.
2394
2395 Arguments:
2396     ImageHandle   - The image handle.
2397     SystemTable   - The system table.
2398
2399 Returns:
2400     EFI_SUCCESS   - Function successfully returned.
2401
2402 --*/
2403 ;
2404
2405 EFI_STATUS
2406 EFIAPI
2407 InitializeSectionExtraction (
2408   IN EFI_HANDLE                   ImageHandle,
2409   IN EFI_SYSTEM_TABLE             *SystemTable
2410   )
2411 /*++
2412
2413 Routine Description:
2414   Entry point of the section extraction code. Initializes an instance of the
2415   section extraction interface and installs it on a new handle.
2416
2417 Arguments:
2418   ImageHandle   EFI_HANDLE: A handle for the image that is initializing this driver
2419   SystemTable   EFI_SYSTEM_TABLE: A pointer to the EFI system table
2420
2421 Returns:
2422   EFI_SUCCESS:  Driver initialized successfully
2423   EFI_OUT_OF_RESOURCES:   Could not allocate needed resources
2424
2425 --*/
2426 ;
2427
2428 EFI_STATUS
2429 CoreProcessFirmwareVolume (
2430   IN  VOID                         *FvHeader,
2431   IN  UINTN                        Size,
2432   OUT EFI_HANDLE                   *FVProtocolHandle
2433   )
2434 /*++
2435
2436 Routine Description:
2437     This DXE service routine is used to process a firmware volume. In
2438     particular, it can be called by BDS to process a single firmware
2439     volume found in a capsule.
2440
2441 Arguments:
2442     FvHeader              - pointer to a firmware volume header
2443     Size                  - the size of the buffer pointed to by FvHeader
2444     FVProtocolHandle      - the handle on which a firmware volume protocol
2445                             was produced for the firmware volume passed in.
2446
2447 Returns:
2448     EFI_OUT_OF_RESOURCES  - if an FVB could not be produced due to lack of
2449                             system resources
2450     EFI_VOLUME_CORRUPTED  - if the volume was corrupted
2451     EFI_SUCCESS           - a firmware volume protocol was produced for the
2452                             firmware volume
2453
2454 --*/
2455 ;
2456
2457 //
2458 //Functions used during debug buils
2459 //
2460 VOID
2461 CoreDisplayMissingArchProtocols (
2462   VOID
2463   )
2464 /*++
2465
2466   Routine Description:
2467   Displays Architectural protocols that were not loaded and are required for DXE core to function
2468   Only used in Debug Builds
2469
2470   Arguments:
2471     NONE
2472
2473   Returns:
2474     NONE
2475
2476 --*/;
2477
2478 VOID
2479 CoreDisplayDiscoveredNotDispatched (
2480   VOID
2481   )
2482 /*++
2483
2484   Routine Description:
2485
2486     Traverse the discovered list for any drivers that were discovered but not loaded
2487     because the dependency experessions evaluated to false
2488
2489   Arguments:
2490
2491     NONE
2492
2493   Returns:
2494
2495     NONE
2496
2497 --*/;
2498 #endif