From PhoenixWiki

Contains a table header and pointers to all of the DXE-specific services.

Prototype

typedef struct {
  EFI_TABLE_HEADER                 Hdr;
  EFI_ADD_MEMORY_SPACE             AddMemorySpace;
  EFI_ALLOCATE_MEMORY_SPACE        AllocateMemorySpace;
  EFI_FREE_MEMORY_SPACE            FreeMemorySpace;
  EFI_REMOVE_MEMORY_SPACE          RemoveMemorySpace;
  EFI_GET_MEMORY_SPACE_DESCRIPTOR  GetMemorySpaceDescriptor;
  EFI_SET_MEMORY_SPACE_ATTRIBUTES  SetMemorySpaceAttributes;
  EFI_GET_MEMORY_SPACE_MAP         GetMemorySpaceMap;
  EFI_ADD_IO_SPACE                 AddIoSpace;
  EFI_ALLOCATE_IO_SPACE            AllocateIoSpace;
  EFI_FREE_IO_SPACE                FreeIoSpace;
  EFI_REMOVE_IO_SPACE              RemoveIoSpace;
  EFI_GET_IO_SPACE_DESCRIPTOR      GetIoSpaceDescriptor;
  EFI_GET_IO_SPACE_MAP             GetIoSpaceMap;
  EFI_DISPATCH                     Dispatch;
  EFI_SCHEDULE                     Schedule;
  EFI_TRUST                        Trust;
  EFI_PROCESS_FIRMWARE_VOLUME      ProcessFirmwareVolume;
} EFI_DXE_SERVICES;

Members

Member	Description
Hdr	The table header for the DXE Services Table. This header contains the DXE_SERVICES_SIGNATURE and DXE_SERVICES_REVISION values along with the size of the DXE_SERVICES_TABLE structure and a 32-bit CRC to verify that the contents of the DXE Services Table are valid.
AddMemorySpace	Adds reserved memory, system memory, or memory-mapped I/O resources to the global coherency domain of the processor.
AllocateMemorySpace	Allocates nonexistent memory, reserved memory, system memory, or memory-mapped I/O resources from the global coherency domain of the processor.
FreeMemorySpace	Frees nonexistent memory, reserved memory, system memory, or memory-mapped I/O resources from the global coherency domain of the processor.
RemoveMemorySpace	Removes reserved memory, system memory, or memory-mapped I/O resources from the global coherency domain of the processor.
GetMemorySpaceDescriptor	Retrieves the descriptor for a memory region containing a specified address.
SetMemorySpaceAttributes	Modifies the attributes for a memory region in the global coherency domain of the processor.
GetMemorySpaceMap	Returns a map of the memory resources in the global coherency domain of the processor.
AddIoSpace	Adds reserved I/O or I/O resources to the global coherency domain of the processor.
AllocateIoSpace	Allocates nonexistent I/O, reserved I/O, or I/O resources from the global coherency domain of the processor.
FreeIoSpace	Frees nonexistent I/O, reserved I/O, or I/O resources from the global coherency domain of the processor.
RemoveIoSpace	Removes reserved I/O or I/O resources from the global coherency domain of the processor.
GetIoSpaceDescriptor	Retrieves the descriptor for an I/O region containing a specified address.
GetIoSpaceMap	Returns a map of the I/O resources in the global coherency domain of the processor.
Dispatch	Loads and executed DXE drivers from firmware volumes.
Schedule	Clears the Schedule on Request (SOR) flag for a component that is stored in a firmware volume.
Trust	Promotes a file stored in a firmware volume from the untrusted to the trusted state.
ProcessFirmwareVolume	Creates a firmware volume handle for a firmware volume that is present in system memory.

Description

The DXE Services Table contains a table header and pointers to all of the DXE-specific services. Except for the table header, all elements in the DXE Services Tables are prototypes of function pointers to functions.

AddMemorySpace()

This service adds reserved memory, system memory, or memory-mapped I/O resources to the global coherency domain of the processor.

Prototype

EFI_STATUS
AddMemorySpace (
  IN EFI_GCD_MEMORY_TYPE  GcdMemoryType,
  IN EFI_PHYSICAL_ADDRESS BaseAddress,
  IN UINT64               Length,
  IN UINT64               Capabilities
  );

Parameters

Parameter	Description
GcdMemoryType	The type of memory resource being added. The only types allowed are EfiGcdMemoryTypeReserved, EfiGcdMemoryTypeSystemMemory, and EfiGcdMemoryTypeMemoryMappedIo.
BaseAddress	The physical address that is the start address of the memory resource being added.
Length	The size, in bytes, of the memory resource that is being added.
Capabilities	The bit mask of attributes that the memory resource region supports. The bit mask of available attributes is defined in the GetMemoryMap() function.

Description
The AddMemorySpace() function converts unallocated non-existent memory ranges to a range of reserved memory, a range of system memory, or a range of memory mapped I/O.

BaseAddress and Length specify the memory range, and GcdMemoryType specifies the memory type. The bit mask of all supported attributes for the memory range being added is specified by Capabilities. If the memory range is successfully added, then EFI_SUCCESS is returned.

If the memory range specified by BaseAddress and Length is of type EfiGcdMemoryTypeSystemMemory, then the memory range may be automatically allocated for use by the EFI memory services. If the addition of the memory range specified by BaseAddress and Length results in a GCD memory space map containing one or more 4 KB regions of unallocated EfiGcdMemoryTypeSystemMemory aligned on 4 KB boundaries, then those regions will always be converted to ranges of allocated EfiGcdMemoryTypeSystemMemory. This extra conversion will never be performed for fragments of memory that do not meet the above criteria.

If the GCD memory space map contains adjacent memory regions that only differ in their base address and length fields, then those adjacent memory regions must be merged into a single memory descriptor.

If Length is zero, then EFI_INVALID_PARAMETER is returned.

If GcdMemoryType is not EfiGcdMemoryTypeReserved, EfiGcdMemoryTypeSystemMemory, or EfiGcdMemoryTypeMemoryMappedIo, then EFI_INVALID_PARAMETER is returned.

If the processor does not support one or more bytes of the memory range specified by BaseAddress and Length, then EFI_UNSUPPORTED is returned.

If any portion of the memory range specified by BaseAddress and Length is not of type EfiGcdMemoryTypeNonExistent, then EFI_ACCESS_DENIED is returned.

If any portion of the memory range specified by BaseAddress and Length was allocated in a prior call to AllocateMemorySpace(), then EFI_ACCESS_DENIED is returned.

If there are not enough system resources available to add the memory resource to the global coherency domain of the processor, then EFI_OUT_OF_RESOURCES is returned.

Status Codes Returned

Status Code	Description
EFI_SUCCESS	The memory resource was added to the global coherency domain of the processor.
EFI_INVALID_PARAMETER	GcdMemoryType is invalid.
EFI_INVALID_PARAMETER	Length is zero.
EFI_OUT_OF_RESOURCES	There are not enough system resources to add the memory resource to the global coherency domain of the processor.
EFI_UNSUPPORTED	The processor does not support one or more bytes of the memory resource range specified by BaseAddress and Length.
EFI_ACCESS_DENIED	One or more bytes of the memory resource range specified by BaseAddress and Length conflicts with a memory resource range that was previously added to the global coherency domain of the processor.
EFI_ACCESS_DENIED	One or more bytes of the memory resource range specified by BaseAddress and Length was allocated in a prior call to AllocateMemorySpace().

AllocateMemorySpace()

This service allocates nonexistent memory, reserved memory, system memory, or memory-mapped I/O resources from the global coherency domain of the processor.

Prototype

EFI_STATUS
AllocateMemorySpace (
  IN     EFI_GCD_ALLOCATE_TYPE GcdAllocateType,
  IN     EFI_GCD_MEMORY_TYPE   GcdMemoryType,
  IN     UINTN                 Alignment,
  IN     UINT64                Length,
  IN OUT EFI_PHYSICAL_ADDRESS  *BaseAddress,
  IN     EFI_HANDLE            ImageHandle,
  IN     EFI_HANDLE            DeviceHandle OPTIONAL
  );

Parameters

Parameter	Description
GcdAllocateType	The type of allocation to perform.
GcdMemoryType	The type of memory resource being allocated. The only types allowed are EfiGcdMemoryTypeNonExistent, EfiGcdMemoryTypeReserved, EfiGcdMemoryTypeSystemMemory, and EfiGcdMemoryTypeMemoryMappedIo.
Alignment	The log base 2 of the boundary that BaseAddress must be aligned on output. For example, a value of 0 means that BaseAddress can be aligned on any byte boundary, and a value of 12 means that BaseAddress must be aligned on a 4 KB boundary.
Length	The size in bytes of the memory resource range that is being allocated.
BaseAddress	A pointer to a physical address. On input, the way in which the address is used depends on the value of Type. See “Description” below for more information. On output the address is set to the base of the memory resource range that was allocated.
ImageHandle	The image handle of the agent that is allocating the memory resource.
DeviceHandle	The device handle for which the memory resource is being allocated. If the memory resource is not being allocated for a device that has an associated device handle, then this parameter is optional and may be NULL.

Description
The AllocateMemorySpace() function searches for a memory range of type GcdMemoryType and converts the discovered memory range from the unallocated state to the allocated state. The parameters GcdAllocateType, Alignment, Length, and BaseAddress specify the manner in which the GCD memory space map is searched. If a memory range is found that meets the search criteria, then the base address of the memory range is returned in BaseAddress, and EFI_SUCCESS is returned. ImageHandle and DeviceHandle are used to convert the memory range from the unallocated state to the allocated state. ImageHandle identifies the image that is calling AllocateMemorySpace(), and DeviceHandle identifies the device that ImageHandle is managing that requires the memory range. DeviceHandle is optional, because the device that ImageHandle is managing might not have an associated device handle. If a memory range meeting the search criteria cannot be found, then EFI_NOT_FOUND is returned.

If GcdAllocateType is EfiGcdAllocateAnySearchBottomUp, then the GCD memory space map is searched from the lowest address up to the highest address looking for unallocated memory ranges of Length bytes beginning on a boundary specified by Alignment that matches GcdMemoryType.

If GcdAllocateType is EfiGcdAllocateAnySearchTopDown, then the GCD memory space map is searched from the highest address down to the lowest address looking for unallocated memory ranges of Length bytes beginning on a boundary specified by Alignment that matches GcdMemoryType.

If GcdAllocateType is EfiGcdAllocateMaxAddressSearchBottomUp, then the GCD memory space map is searched from the lowest address up to BaseAddress looking for unallocated memory ranges of Length bytes beginning on a boundary specified by Alignment that matches GcdMemoryType.

If GcdAllocateType is EfiGcdAllocateMaxAddressSearchTopDown, then the GCD memory space map is searched from BaseAddress down to the lowest address looking for unallocated memory ranges of Length bytes beginning on a boundary specified by Alignment that matches GcdMemoryType.

If GcdAllocateType is EfiGcdAllocateAddress, then the GCD memory space map is checked to see if the memory range starting at BaseAddress for Length bytes is of type GcdMemoryType, unallocated, and begins on a the boundary specified by Alignment.

If the GCD memory space map contains adjacent memory regions that only differ in their base address and length fields, then those adjacent memory regions must be merged into a single memory descriptor.

If Length is zero, then EFI_INVALID_PARAMETER is returned. If BaseAddress is NULL, then EFI_INVALID_PARAMETER is returned. If ImageHandle is NULL, then EFI_INVALID_PARAMETER is returned. If GcdMemoryType is not EfiGcdMemoryTypeNonExistent, EfiGcdMemoryTypeReserved, EfiGcdMemoryTypeSystem Memory, or EfiGcdMemoryTypeMemoryMappedIo, then EFI_INVALID_PARAMETER is returned.

If GcdAlocateType is less than zero, or GcdAllocateType is greater than or equal to EfiGcdMaxAllocateType then EFI_INVALID_PARAMETER is returned.

If there are not enough system resources available to allocate the memory range, then EFI_OUT_OF_RESOURCES is returned.

Related Definitions

Status Codes Returned

Status Code	Description
EFI_SUCCESS	The memory resource was allocated from the global coherency domain of the processor.
EFI_INVALID_PARAMETER	GcdAllocateType is invalid.
EFI_INVALID_PARAMETER	GcdMemoryType is invalid.
EFI_INVALID_PARAMETER	Length is zero.
EFI_INVALID_PARAMETER	BaseAddress is NULL.
EFI_INVALID_PARAMETER	ImageHandle is NULL.
EFI_OUT_OF_RESOURCES	There are not enough system resources to allocate the memory resource from the global coherency domain of the processor.
EFI_NOT_FOUND	The memory resource request could not be satisfied.

FreeMemorySpace()

This service frees nonexistent memory, reserved memory, system memory, or memory-mapped I/O resources from the global coherency domain of the processor.

Prototype

EFI_STATUS
FreeMemorySpace (
  IN EFI_PHYSICAL_ADDRESS BaseAddress,
  IN UINT64               Length
  );

Parameters

Parameter	Description
BaseAddress	The physical address that is the start address of the memory resource being freed.
Length	The size in bytes of the memory resource range that is being freed.

Description
The FreeMemorySpace() function converts the memory range specified by BaseAddress and Length from the allocated state to the unallocated state. If this conversion is successful, then EFI_SUCCESS is returned.

If the GCD memory space map contains adjacent memory regions that only differ in their base address and length fields, then those adjacent memory regions must be merged into a single memory descriptor.

If Length is zero, then EFI_INVALID_PARAMETER is returned.

If the processor does not support one or more bytes of the memory range specified by BaseAddress and Length, then EFI_UNSUPPORTED is returned.

If one or more bytes of the memory range specified by BaseAddress and Length were not allocated on previous calls to AllocateMemorySpace(), then EFI_NOT_FOUND is returned.

If there are not enough system resources available to free the memory range, then EFI_OUT_OF_RESOURCES is returned.

Status Codes Returned

Status Code	Description
EFI_SUCCESS	The memory resource was freed from the global coherency domain of the processor.
EFI_INVALID_PARAMETER	Length is zero.
EFI_UNSUPPORTED	The processor does not support one or more bytes of the memory resource range specified by BaseAddress and Length.
EFI_NOT_FOUND	The memory resource range specified by BaseAddress and Length was not allocated with previous calls to AllocateMemorySpace().
EFI_OUT_OF_RESOURCES	There are not enough system resources to free the memory resource from the global coherency domain of the processor.

RemoveMemorySpace()

This service removes reserved memory, system memory, or memory-mapped I/O resources from the global coherency domain of the processor.

Prototype

EFI_STATUS
RemoveMemorySpace (
  IN EFI_PHYSICAL_ADDRESS BaseAddress,
  IN UINT64               Length
  );

Parameters

Parameter	Description
BaseAddress	The physical address that is the start address of the memory resource being removed.
Length	The size in bytes of the memory resource that is being removed.

Description
The RemoveMemorySpace() function converts the memory range specified by BaseAddress and Length to the memory type EfiGcdMemoryTypeNonExistent. If this conversion is successful, then EFI_SUCCESS is returned.If the GCD memory space map contains adjacent memory regions that only differ in their base address and length fields, then those adjacent memory regions must be merged into a single memory descriptor.

If Length is zero, then EFI_INVALID_PARAMETER is returned.

If the processor does not support one or more bytes of the memory range specified by BaseAddress and Length, then EFI_UNSUPPORTED is returned.

If one or more bytes of the memory range specified by BaseAddress and Length were not added to the GCD memory space map with previous calls to AddMemorySpace(), then EFI_NOT_FOUND is returned.

If one or more bytes of the memory range specified by BaseAddress and Length were allocated from the GCD memory space map with previous calls to AllocateMemorySpace(), then EFI_ACCESS_DENIED is returned.

If there are not enough system resources available to remove the memory range, then EFI_OUT_OF_RESOURCES is returned.

Status Codes Returned

Status Code	Description
EFI_SUCCESS	The memory resource was removed from the global coherency domain of the processor.
EFI_INVALID_PARAMETER	Length is zero.
EFI_UNSUPPORTED	The processor does not support one or more bytes of the memory resource range specified by BaseAddress and Length.
EFI_NOT_FOUND	One or more bytes of the memory resource range specified by BaseAddress and Length was not added with previous calls to AddMemorySpace().
EFI_ACCESS_DENIED	One or more bytes of the memory resource range specified by BaseAddress and Length has been allocated with AllocateMemorySpace().
EFI_OUT_OF_RESOURCES	There are not enough system resources to remove the memory resource from the global coherency domain of the processor.

GetMemorySpaceDescriptor()

This service retrieves the descriptor for a memory region containing a specified address.

Prototype

EFI_STATUS
GetMemorySpaceDescriptor (
  IN  EFI_PHYSICAL_ADDRESS            BaseAddress,
  OUT EFI_GCD_MEMORY_SPACE_DESCRIPTOR *Descriptor
  );

Parameters

Parameter	Description
BaseAddress	The physical address that is the start address of a memory region.
Descriptor	A pointer to a caller allocated descriptor. On return, the descriptor describes the memory region containing BaseAddress.

Description
The GetMemorySpaceDescriptor() function retrieves the descriptor for the memory region that contains the address specified by BaseAddress. If a memory region containing BaseAddress is found, then the descriptor for that memory region is returned in the caller allocated structure Descriptor, and EFI_SUCCESS is returned.

If Descriptor is NULL, then EFI_INVALID_PARAMETER is returned.

If a memory region containing BaseAddress is not present in the GCD memory space map, then EFI_NOT_FOUND is returned.

Status Codes Returned

Status Code	Description
EFI_SUCCESS	The descriptor for the memory resource region containing BaseAddress was returned in Descriptor.
EFI_INVALID_PARAMETER	Descriptor is NULL.
EFI_NOT_FOUND	A memory resource range containing BaseAddress was not found.

SetMemorySpaceAttributes()

This service modifies the attributes for a memory region in the global coherency domain of the processor.

Prototype

EFI_STATUS
SetMemorySpaceAttributes (
  IN EFI_PHYSICAL_ADDRESS BaseAddress,
  IN UINT64               Length,
  IN UINT64               Attributes
  );

Parameters

Parameter	Description
BaseAddress	The physical address that is the start address of a memory region.
Length	The size in bytes of the memory region.
Attributes	The bit mask of attributes to set for the memory region. The bit mask of available attributes is defined in the GetMemoryMap() function.

Description
The SetMemorySpaceAttributes() function modifies the attributes for the memory region specified by BaseAddress and Length from their current attributes to the attributes specified by Attributes. If this modification of attributes succeeds, then EFI_SUCCESS is returned.

If the GCD memory space map contains adjacent memory regions that only differ in their base address and length fields, then those adjacent memory regions must be merged into a single memory descriptor.

If Length is zero, then EFI_INVALID_PARAMETER is returned.

If the processor does not support one or more bytes of the memory range specified by BaseAddress and Length, then EFI_UNSUPPORTED is returned.

If the attributes specified by Attributes are not supported for the memory region specified by BaseAddress and Length, then EFI_UNSUPPORTED is returned. The Attributes bit mask must be a proper subset of the capabilities bit mask for the specified memory region. The capabilities bit mask is specified when a memory region is added with AddMemorySpace() and can be retrieved with GetMemorySpaceDescriptor() or GetMemorySpaceMap().

If the attributes for one or more bytes of the memory range specified by BaseAddress and Length cannot be modified because the current system policy does not allow them to be modified, then EFI_ACCESS_DENIED is returned.

If there are not enough system resources available to modify the attributes of the memory range, then EFI_OUT_OF_RESOURCES is returned.

Status Codes Returned

Status Code	Description
EFI_SUCCESS	The attributes were set for the memory region.
EFI_INVALID_PARAMETER	Length is zero.
EFI_UNSUPPORTED	The processor does not support one or more bytes of the memory resource range specified by BaseAddress and Length.
EFI_UNSUPPORTED	The bit mask of attributes is not support for the memory resource range specified by BaseAddress and Length.
EFI_ACCESS_DENIED	The attributes for the memory resource range specified by BaseAddress and Length cannot be modified.
EFI_OUT_OF_RESOURCES	There are not enough system resources to modify the attributes of the memory resource range.

GetMemorySpaceMap()

Returns a map of the memory resources in the global coherency domain of the processor.

Prototype

EFI_STATUS
GetMemorySpaceMap (
  OUT UINTN                           *NumberOfDescriptors,
  OUT EFI_GCD_MEMORY_SPACE_DESCRIPTOR **MemorySpaceMap
  );

Parameters

Parameter	Description
NumberOfDescriptors	A pointer to number of descriptors returned in the MemorySpaceMap buffer. This parameter is ignored on input, and is set to the number of descriptors in the MemorySpaceMap buffer on output.
MemorySpaceMap	A pointer to the array of EFI_GCD_MEMORY_SPACE_DESCRIPTORs. This buffer is allocated with AllocatePool(), so it is the caller’s responsibility to free this buffer with a call to FreePool(). The number of descriptors in MemorySpaceMap is returned in NumberOfDescriptors.

Description
The GetMemorySpaceMap() function retrieves the entire GCD memory space map. If there are no errors retrieving the GCD memory space map, then the number of descriptors in the GCD memory space map is returned in NumberOfDescriptors, the array of descriptors from the GCD memory space map is allocated with AllocatePool(), the descriptors are transferred into MemorySpaceMap, and EFI_SUCCESS is returned.

If NumberOfDescriptors is NULL, then EFI_INVALID_PARAMETER is returned.

If MemorySpaceMap is NULL, then EFI_INVALID_PARAMETER is returned.

If there are not enough resources to allocate MemorySpaceMap, then EFI_OUT_OF_RESOURCES is returned.

Status Codes Returned

Status Code	Description
EFI_SUCCESS	The memory space map was returned in the MemorySpaceMap buffer, and the number of descriptors in MemorySpaceMap was returned in NumberOfDescriptors.
EFI_INVALID_PARAMETER	NumberOfDescriptors is NULL.
EFI_INVALID_PARAMETER	MemorySpaceMap is NULL.
EFI_OUT_OF_RESOURCES	There are not enough resources to allocate MemorySpaceMap.

AddIoSpace()

Summary This service adds reserved I/O, or I/O resources to the global coherency domain of the processor.

Prototype

EFI_STATUS
AddIoSpace (
  IN EFI_GCD_IO_TYPE      GcdIoType,
  IN EFI_PHYSICAL_ADDRESS BaseAddress,
  IN UINT64               Length
  );

Parameters

Parameter	Description
GcdIoType	The type of I/O resource being added. The only types allowed are EfiGcdIoTypeReserved and EfiGcdIoTypeIo.
BaseAddress	The physical address that is the start address of the I/O resource being added.
Length	The size in bytes of the I/O resource that is being added.

Description
The AddIoSpace() function converts unallocated non-existent I/O ranges to a range of reserved I/O, or a range of I/O. BaseAddress and Length specify the I/O range, and GcdIoType specifies the I/O type. If the I/O range is successfully added, then EFI_SUCCESS is returned.

If the GCD I/O space map contains adjacent I/O regions that only differ in their base address and length fields, then those adjacent I/O regions must be merged into a single I/O descriptor.

If Length is zero, then EFI_INVALID_PARAMETER is returned.

If GcdIoType is not EfiGcdIoTypeReserved or EfiGcdIoTypeIo, then EFI_INVALID_PARAMETER is returned.

If the processor does not support one or more bytes of the I/O range specified by BaseAddress and Length, then EFI_UNSUPPORTED is returned.

If any portion of the I/O range specified by BaseAddress and Length is not of type EfiGcdIoTypeNonExistent, then EFI_ACCESS_DENIED is returned.

If any portion of the I/O range specified by BaseAddress and Length was allocated in a prior call to AllocateIoSpace(), then EFI_ACCESS_DENIED is returned.

If there are not enough system resources available to add the I/O resource to the global coherency domain of the processor, then EFI_OUT_OF_RESOURCES is returned.

Related Definitions

Status Codes Returned

Status Code	Description
EFI_SUCCESS	The I/O resource was added to the global coherency domain of the processor.
EFI_INVALID_PARAMETER	GcdIoType is invalid.
EFI_INVALID_PARAMETER	Length is zero.
EFI_OUT_OF_RESOURCES	There are not enough system resources to add the I/O resource to the global coherency domain of the processor.
EFI_UNSUPPORTED	The processor does not support one or more bytes of the I/O resource range specified by BaseAddress and Length.
EFI_ACCESS_DENIED	One or more bytes of the I/O resource range specified by BaseAddress and Length conflicts with an I/O resource range that was previously added to the global coherency domain of the processor.
EFI_ACCESS_DENIED	One or more bytes of the I/O resource range specified by BaseAddress and Length was allocated in a prior call to AllocateIoSpace().

AllocateIoSpace()

This service allocates nonexistent I/O, reserved I/O, or I/O resources from the global coherency domain of the processor.

Prototype

EFI_STATUS
AllocateIoSpace (
  IN     EFI_GCD_ALLOCATE_TYPE AllocateType,
  IN     EFI_GCD_IO_TYPE       GcdIoType,
  IN     UINTN                 Alignment,
  IN     UINT64                Length,
  IN OUT EFI_PHYSICAL_ADDRESS  *BaseAddress,
  IN     EFI_HANDLE            ImageHandle,
  IN     EFI_HANDLE            DeviceHandle OPTIONAL
  );

Parameters

Parameter	Description
GcdAllocateType	The type of allocation to perform.
GcdIoType	The type of I/O resource being allocated. The only types allowed are EfiGcdIoTypeNonExistent, EfiGcdIoTypeReserved, and EfiGcdIoTypeIo.
Alignment	The log base 2 of the boundary that BaseAddress must be aligned on output. For example, a value of 0 means that BaseAddress can be aligned on any byte boundary, and a value of 12 means that BaseAddress must be aligned on a 4 KB boundary.
Length	The size in bytes of the I/O resource range that is being allocated.
BaseAddress	A pointer to a physical address. On input, the way in which the address is used depends on the value of Type. See "Description" below for more information. On output the address is set to the base of the I/O resource range that was allocated.
ImageHandle	The image handle of the agent that is allocating the I/O resource.
DeviceHandle	The device handle for which the I/O resource is being allocated. If the I/O resource is not being allocated for a device that has an associated device handle, then this parameter is optional and may be NULL.

Description
The AllocateIoSpace() function searches for an I/O range of type GcdIoType and converts the discovered I/O range from the unallocated state to the allocated state. The parameters GcdAllocateType, Alignment, Length, and BaseAddress specify the manner in which the GCD I/O space map is searched. If an I/O range is found that meets the search criteria, then the base address of the I/O range is returned in BaseAddress, and EFI_SUCCESS is returned.

ImageHandle and DeviceHandle are used to convert the I/O range from the unallocated state to the allocated state. ImageHandle identifies the image that is calling AllocateIoSpace(), and DeviceHandle identifies the device that ImageHandle is managing that requires the I/O range. DeviceHandle is optional, because the device that ImageHandle is managing might not have an associated device handle. If an I/O range meeting the search criteria cannot be found, then EFI_NOT_FOUND is returned.

If GcdAllocateType is EfiGcdAllocateAnySearchBottomUp, then the GCD I/O space map is searched from the lowest address up to the highest address looking for unallocated I/O ranges of Length bytes beginning on a boundary specified by Alignment that matches GcdIoType.

If GcdAllocateType is EfiGcdAllocateAnySearchTopDown, then the GCD I/O space map is searched from the highest address down to the lowest address looking for unallocated I/O ranges of Length bytes beginning on a boundary specified by Alignment that matches GcdIoType.

If GcdAllocateType is EfiGcdAllocateMaxAddressSearchBottomUp, then the GCD I/O space map is searched from the lowest address up to BaseAddress looking for unallocated I/O ranges of Length bytes beginning on a boundary specified by Alignment that matches GcdIoType.

If GcdAllocateType is EfiGcdAllocateMaxAddressSearchTopDown, then the GCD I/O space map is searched from BaseAddress down to the lowest address looking for unallocated I/O ranges of Length bytes beginning on a boundary specified by Alignment that matches GcdIoType.

If GcdAllocateType is EfiGcdAllocateAddress, then the GCD I/O space map is checked to see if the I/O range starting at BaseAddress for Length bytes is of type GcdIoType, unallocated, and begins on a the boundary specified by Alignment.

If the GCD I/O space map contains adjacent I/O regions that only differ in their base address and length fields, then those adjacent I/O regions must be merged into a single I/O descriptor.

If Length is zero, then EFI_INVALID_PARAMETER is returned. If BaseAddress is NULL, then EFI_INVALID_PARAMETER is returned. If ImageHandle is NULL, then EFI_INVALID_PARAMETER is returned.

If GcdIoType is not EfiGcdIoTypeNonExistent, EfiGcdIoTypeReserved, or EfiGcdIoTypeIo, then EFI_INVALID_PARAMETER is returned.

If GcdAlocateType is less than zero, or GcdAllocateType is greater than or equal to EfiGcdMaxAllocateType then EFI_INVALID_PARAMETER is returned.

If there are not enough system resources available to allocate the I/O range, then EFI_OUT_OF_RESOURCES is returned.

Status Codes Returned

Status Code	Description
EFI_SUCCESS	The I/O resource was allocated from the global coherency domain of the processor.
EFI_INVALID_PARAMETER	GcdAllocateType is invalid.
EFI_INVALID_PARAMETER	GcdIoType is invalid.
EFI_INVALID_PARAMETER	Length is zero.
EFI_INVALID_PARAMETER	BaseAddress is NULL.
EFI_INVALID_PARAMETER	ImageHandle is NULL.
EFI_OUT_OF_RESOURCES	There are not enough system resources to allocate the I/O resource from the global coherency domain of the processor.
EFI_NOT_FOUND	The I/O resource request could not be satisfied.

FreeIoSpace()

This service frees nonexistent I/O, reserved I/O, or I/O resources from the global coherency domain of the processor.

Prototype

EFI_STATUS
FreeIoSpace (
  IN EFI_PHYSICAL_ADDRESS BaseAddress,
  IN UINT64               Length
  );

Parameters

Parameter	Description
BaseAddress	The physical address that is the start address of the I/O resource being freed.
Length	The size in bytes of the I/O resource range that is being freed.

Description
The FreeIoSpace() function converts the I/O range specified by BaseAddress and Length from the allocated state to the unallocated state. If this conversion is successful, then EFI_SUCCESS is returned.

If the GCD I/O space map contains adjacent I/O regions that only differ in their base address and length fields, then those adjacent I/O regions must be merged into a single I/O descriptor.

If Length is zero, then EFI_INVALID_PARAMETER is returned.

If the processor does not support one or more bytes of the I/O range specified by BaseAddress and Length, then EFI_UNSUPPORTED is returned.

If one or more bytes of the I/O range specified by BaseAddress and Length were not allocated on previous calls to AllocateIoSpace(), then EFI_NOT_FOUND is returned.

If there are not enough system resources available to free the I/O range, then EFI_OUT_OF_RESOURCES is returned.

Status Codes Returned

Status Code	Description
EFI_SUCCESS	The I/O resource was freed from the global coherency domain of the processor.
EFI_INVALID_PARAMETER	Length is zero.
EFI_UNSUPPORTED	The processor does not support one or more bytes of the I/O resource range specified by BaseAddress and Length.
EFI_NOT_FOUND	The I/O resource range specified by BaseAddress and Length was not allocated with previous calls to AllocateIoSpace().
EFI_OUT_OF_RESOURCES	There are not enough system resources to free the I/O resource from the global coherency domain of the processor.

RemoveIoSpace()

This service removes reserved I/O, or I/O resources from the global coherency domain of the processor.

Prototype

EFI_STATUS
RemoveIoSpace (
  IN EFI_PHYSICAL_ADDRESS BaseAddress,
  IN UINT64                   Length
  );

Parameters

Parameter	Description
BaseAddress	A pointer to a physical address that is the start address of the I/O resource being removed.
Length	The size in bytes of the I/O resource that is being removed.

Description
The RemoveIoSpace() function converts the I/O range specified by BaseAddress and Length to the I/O type EfiGcdIoTypeNonExistent. If this conversion is successful, then EFI_SUCCESS is returned.

If the GCD I/O space map contains adjacent I/O regions that only differ in their base address and length fields, then those adjacent I/O regions must be merged into a single I/O descriptor.

If Length is zero, then EFI_INVALID_PARAMETER is returned.

If the processor does not support one or more bytes of the I/O range specified by BaseAddress and Length, then EFI_UNSUPPORTED is returned.

If one or more bytes of the I/O range specified by BaseAddress and Length were not added to the GCD I/O space map with previous calls to AddIoSpace(), then EFI_NOT_FOUND is returned.

If one or more bytes of the I/O range specified by BaseAddress and Length were allocated from the GCD I/O space map with previous calls to AllocateIoSpace(), then EFI_ACCESS_DENIED is returned.

If there are not enough system resources available to remove the I/O range, then EFI_OUT_OF_RESOURCES is returned.

Status Codes Returned

Status Code	Description
EFI_SUCCESS	The I/O resource was removed from the global coherency domain of the processor.
EFI_INVALID_PARAMETER \	Length is zero.
EFI_UNSUPPORTED	The processor does not support one or more bytes of the I/O resource range specified by BaseAddress and Length.
EFI_NOT_FOUND	One or more bytes of the I/O resource range specified by BaseAddress and Length was not added with previous calls to AddIoSpace().
EFI_ACCESS_DENIED	One or more bytes of the I/O resource range specified by BaseAddress and Length has been allocated with AllocateIoSpace().
EFI_OUT_OF_RESOURCES	There are not enough system resources to remove the I/O resource from the global coherency domain of the processor.

GetIoSpaceDescriptor()

This service retrieves the descriptor for an I/O region containing a specified address.

Prototype

EFI_STATUS
GetIoSpaceDescriptor (
  IN  EFI_PHYSICAL_ADDRESS        BaseAddress,
  OUT EFI_GCD_IO_SPACE_DESCRIPTOR *Descriptor
  );

Parameters

Parameter	Description
BaseAddress	The physical address that is the start address of an I/O region.
Descriptor	A pointer to a caller allocated descriptor. On return, the descriptor describes the I/O region containing BaseAddress.

Description
The GetIoSpaceDescriptor() function retrieves the descriptor for the I/O region that contains the address specified by BaseAddress. If an I/O region containing BaseAddress is found, then the descriptor for that I/O region is returned in the caller allocated structure Descriptor, and EFI_SUCCESS is returned.

If Descriptor is NULL, then EFI_INVALID_PARAMETER is returned.

If an I/O region containing BaseAddress is not present in the GCD I/O space map, then EFI_NOT_FOUND is returned.

Status Codes Returned

Status Code	Description
EFI_SUCCESS	The descriptor for the I/O resource region containing BaseAddress was returned in Descriptor.
EFI_INVALID_PARAMETER	Descriptor is NULL.
EFI_NOT_FOUND	An I/O resource range containing BaseAddress was not found.

GetIoSpaceMap()

Returns a map of the I/O resources in the global coherency domain of the processor.

Prototype

EFI_STATUS
GetIoSpaceMap (
  OUT UINTN                       *NumberOfDescriptors,
  OUT EFI_GCD_IO_SPACE_DESCRIPTOR **IoSpaceMap
  );

Parameters

Parameter	Description
NumberOfDescriptors	A pointer to number of descriptors returned in the IoSpaceMap buffer. This parameter is ignored on input, and is set to the number of descriptors in the IoSpaceMap buffer on output.
IoSpaceMap	A pointer to the array of EFI_GCD_IO_SPACE_DESCRIPTORs. This buffer is allocated with AllocatePool(), so it is the caller’s responsibility to free this buffer with a call to FreePool(). The number of descriptors in IoSpaceMap is returned in NumberOfDescriptors.

Description
The GetIoSpaceMap() function retrieves the entire GCD I/O space map. If there are no errors retrieving the GCD I/O space map, then the number of descriptors in the GCD I/O space map is returned in NumberOfDescriptors, the array of descriptors from the GCD I/O space map is allocated with AllocatePool(), the descriptors are transferred into IoSpaceMap, and EFI_SUCCESS is returned.

If NumberOfDescriptors is NULL, then EFI_INVALID_PARAMETER is returned.

If IoSpaceMap is NULL, then EFI_INVALID_PARAMETER is returned.

If there are not enough resources to allocate IoSpaceMap, then EFI_OUT_OF_RESOURCES is returned.

Status Codes Returned

Status Code	Description
EFI_SUCCESS	The I/O space map was returned in the IoSpaceMap buffer, and the number of descriptors in IoSpaceMap was returned in NumberOfDescriptors.
EFI_INVALID_PARAMETER	NumberOfDescriptors is NULL.
EFI_INVALID_PARAMETER	IoSpaceMap is NULL.
EFI_OUT_OF_RESOURCES	There are not enough resources to allocate IoSpaceMap.

Dispatch()

Loads and executes DXE drivers from firmware volumes.

Prototype

EFI_STATUS
Dispatch (
  VOID
  );

Description
The Dispatch() function searches for DXE drivers in firmware volumes that have been installed since the last time the Dispatch() service was called. It then evaluates the dependency expressions of all the DXE drivers and loads and executes those DXE drivers whose dependency expression evaluate to TRUE. This service must interact with the Security Architectural Protocol to authenticate DXE drivers before they are executed. This process is continued until no more DXE drivers can be executed. If one or more DXE drivers are executed, then EFI_SUCCESS is returned. If no DXE drivers are executed, EFI_NOT_FOUND is returned.

If an attempt is made to invoke the DXE Dispatcher recursively, then no action is performed by the Dispatch() service, and EFI_ALREADY_STARTED is returned. In this case, because the DXE Dispatcher is already running, it is not necessary to invoke it again. All the DXE drivers that can be dispatched will be dispatched.

Status Codes Returned

Status Code	Description
EFI_SUCCESS	One or more DXE driver were dispatched.
EFI_NOT_FOUND	No DXE drivers were dispatched.
EFI_ALREADY_STARTED	An attempt is being made to start the DXE Dispatcher recursively. Thus no action was taken.

Schedule()

Clears the Schedule on Request (SOR) flag for a component that is stored in a firmware volume.

Prototype

EFI_STATUS
Schedule (
  IN EFI_HANDLE FirmwareVolumeHandle,
  IN EFI_GUID   *FileName
  );

Parameters

Parameter	Description
FirmwareVolumeHandle	The handle of the firmware volume that contains the file specified by FileName.
FileName	A pointer to the name of the file in a firmware volume. This is the file that should have its SOR bit cleared.

Description
The Schedule() function searches the dispatcher queues for the driver specified by FirmwareVolumeHandle and FileName. If this driver cannot be found, then EFI_NOT_FOUND is returned. If the driver is found, and its Schedule On Request (SOR) flag is not set in its dependency expression, then EFI_NOT_FOUND is returned. If the driver is found, and its SOR bit is set in its dependency expression, then the SOR flag is cleared, and EFI_SUCCESS is returned. After the SOR flag is cleared, the driver will be dispatched if the remaining portions of its dependency expression are satisfied. This service does not automatically invoke the DXE Dispatcher. Instead, the Dispatch() service must be used to invoke the DXE Dispatcher.

Status Codes Returned

Status Code	Description
EFI_SUCCESS	The DXE driver was found and its SOR bit was cleared.
EFI_NOT_FOUND	The DXE driver does not exist, or the DXE driver exists and its SOR bit is not set.

Trust()

Promotes a file stored in a firmware volume from the untrusted to the trusted state. Only the Security Architectural Protocol can place a file in the untrusted state. A platform specific component may choose to use this service to promote a previously untrusted file to the trusted state.

Prototype

EFI_STATUS
Trust (
  IN EFI_HANDLE FirmwareVolumeHandle,
  IN EFI_GUID   *FileName
  );

Parameters

Parameter	Description
FirmwareVolumeHandle	The handle of the firmware volume that contains the file specified by FileName.
FileName	A pointer to the name of the file in a firmware volume. This is the file that should be promoted from the untrusted state to the trusted state.

Description
The Trust() function promotes the file specified by FirmwareVolumeHandle and FileName from the untrusted state to the trusted state. If this file is not found in the queue of untrusted files, then EFI_NOT_FOUND is returned. If the driver is found, and its state is changed to trusted and EFI_SUCCESS is returned. This service does not automatically invoke the DXE Dispatcher. Instead, the Dispatch() service must be used to invoke the DXE Dispatcher.

Status Codes Returned

Status Code	Description
EFI_SUCCESS	The file was found in the untrusted state, and it was promoted to the trusted state.
EFI_NOT_FOUND	The file was not found in the untrusted state.

ProcessFirmwareVolume()

Creates a firmware volume handle for a firmware volume that is present in system memory.

Prototype

typedef
EFI_STATUS
ProcessFirmwareVolume (
  IN  VOID       *FirmwareVolumeHeader,
  IN  UINTN      Size,
  OUT EFI_HANDLE *FirmwareVolumeHandle
  );

Parameters

Parameter	Description
FirmwareVolumeHeader	A pointer to the header of the firmware volume.
Size	The size, in bytes, of the firmware volume.
FirmwareVolumeHandle	On output, a pointer to the created handle. This service will install the EFI_FIRMWARE_VOLUME_PROTOCOL and EFI_DEVICE_PATH_PROTOCOL for the of the firmware volume that is described by FirmwareVolumeHeader and Size.

Description
The ProcessFirmwareVolume() function examines the contents of the buffer specified by FirmwareVolumeHeader and Size. If the buffer contains a valid firmware volume, then a new handle is created, and the EFI_FIRMWARE_VOLUME_PROTOCOL and a memory-mapped EFI_DEVICE_PATH_PROTOCOL are installed onto the new handle. The new handle is returned in FirmwareVolumeHandle.

Status Codes Returned

Status Code	Description
EFI_SUCCESS	The EFI_FIRMWARE_VOLUME_PROTOCOL and EFI_DEVICE_PATH_PROTOCOL were installed onto FirmwareVolumeHandle for the firmware volume described by FirmwareVolumeHeader and Size.
EFI_VOLUME_CORRUPTED	The firmware volume described by FirmwareVolumeHeader and Size is corrupted.
EFI_OUT_OF_RESOURCES	There are not enough system resources available to produce the EFI_FIRMWARE_VOLUME_PROTOCOL and EFI_DEVICE_PATH_PROTOCOL for the firmware volume described by FirmwareVolumeHeader and Size.

EFI DXE SERVICES

From PhoenixWiki

Contents

Prototype

Members

Description

AddMemorySpace()

AllocateMemorySpace()

FreeMemorySpace()

RemoveMemorySpace()

GetMemorySpaceDescriptor()

SetMemorySpaceAttributes()

GetMemorySpaceMap()

AddIoSpace()

AllocateIoSpace()

FreeIoSpace()

RemoveIoSpace()

GetIoSpaceDescriptor()

GetIoSpaceMap()

Dispatch()

Schedule()

Trust()

ProcessFirmwareVolume()

Views

Personal tools

Navigation

Search

Toolbox