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