Intel Extensible Firmware Interface - Manual (Page 450)

Extensible Firmware Interface Specification
12-32 12/01/02 Version 1.10
Attributes The requested bit mask of attributes for the allocated range. Only
the attributes
EFI_PCI_ATTRIBUTE_MEMORY_WRITE_COMBINE ,
EFI_PCI_ATTRIBUTE_MEMORY_CACHED , and
EFI_PCI_ATTRIBUTE_DUAL_ADDRESS_CYCLE may be used
with this function. If any other bits are set, then
EFI_UNSUPPORTED is returned. This function may choose to
ignore this bit mask. The
EFI_PCI_ATTRIBUTE_MEMORY_WRITE_COMBINE , and
EFI_PCI_ATTRIBUTE_MEMORY_CACHED attributes provide a
hint to the implementation that may improve the performance of
the calling driver. The implementation may choose any default for
the memory attributes including write combining, cached, both, or
neither as long as the allocated buffer can be seen equally by both
the processor and the PCI bus master.
Description
The AllocateBuffer() function allocates pages that are suitable for an
EfiPciOperationBusMasterCommonBuffer or
EfiPciOperationBusMasterCommonBuffer64 mapping. This means that the buffer
allocated by this function must support simultaneous access by both the processor and a PCI Bus
Master. The device address that the PCI Bus Master uses to access the buffer can be retrieved with
a call to
Map() .
If the EFI_PCI_ATTRIBUTE_DUAL_ADDRESS_CYCLE bit of Attributes is set, then when
the buffer allocated by this function is mapped with a call to Map() , the device address that is
returned by Map() must be within the 64-bit device address space of the PCI Bus Master.
If the EFI_PCI_ATTRIBUTE_DUAL_ADDRESS_CYCLE bit of Attributes is clear, then
when the buffer allocated by this function is mapped with a call to Map() , the device address that
is returned by Map() must be within the 32-bit device address space of the PCI Bus Master.
If the memory allocation specified by MemoryType and Pages cannot be satisfied, then
EFI_OUT_OF_RESOURCES is returned.
Status Codes Returned
EFI_SUCCESS The requested memory pages were allocated.
EFI_INVALID_PARAMETER MemoryType is invalid.
EFI_INVALID_PARAMETER HostAddress is NULL .
EFI_UNSUPPORTED Attributes is unsupported. The only legal attribute bits are
MEMORY_WRITE_COMBINE , MEMORY_CACHED , and
DUAL_ADDRESS_CYCLE .
EFI_OUT_OF_RESOURCES The memory pages could not be allocated.