Intel Extensible Firmware Interface - Manual (Page 447)

Protocols — PCI Bus Support
Version 1.10 12/01/02 12-29
Description
The Map() function provides the PCI controller specific addresses needed to access system
memory. This function is used to map system memory for PCI bus master DMA accesses.
All PCI bus master accesses must be performed through their mapped addresses and such
mappings must be freed with
Unmap() when complete. If the bus master access is a single read
or single write data transfer, then EfiPciOperationBusMasterRead ,
EfiPciOperationBusMasterRead64 , EfiPciOperationBusMasterWrite , or
EfiPciOperationBusMasterWrite64 is used and the range is unmapped to complete the
operation. If performing an EfiPciOperationBusMasterRead or
EfiPciOperationBusMasterRead64 operation, all the data must be present in system
memory before Map() is performed. Similarly, if performing an EfiPciOperation-
BusMasterWrite or EfiPciOperationBusMasterWrite64 the data cannot be
properly accessed in system memory until Unmap() is performed.
Bus master operations that require both read and write access or require multiple host device
interactions within the same mapped region must use
EfiPciOperation-
BusMasterCommonBuffer or EfiPciOperationBusMasterCommonBuffer64 .
However, only memory allocated via the AllocateBuffer() interface can be mapped for
this type of operation.
In all mapping requests the resulting NumberOfBytes actually mapped may be less than the
requested amount. In this case, the DMA operation will have to be broken up into smaller
chunks. The
Map() function will map as much of the DMA operation as it can at one time. The
caller may have to loop on Map() and Unmap() in order to complete a large DMA transfer.
Status Codes Returned
EFI_SUCCESS The range was mapped for the returned NumberOfBytes .
EFI_INVALID_PARAMETER Operation is invalid.
EFI_INVALID_PARAMETER HostAddress is NULL .
EFI_INVALID_PARAMETER NumberOfBytes is NULL .
EFI_INVALID_PARAMETER DeviceAddress is NULL .
EFI_INVALID_PARAMETER Mapping is NULL .
EFI_UNSUPPORTED The HostAddress cannot be mapped as a common buffer.
EFI_DEVICE_ERROR The system hardware could not map the requested address.
EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.