Intel Extensible Firmware Interface - Manual (Page 497)

Protocols — PCI Bus Support
Version 1.10 12/01/02 12-79
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 write data
transfer, then EfiPciIoOperationBusMasterRead or EfiPciIoOperation-
BusMasterWrite is used and the range is unmapped to complete the operation. If performing
an EfiPciIoOperationBusMasterRead operation, all the data must be present in system
memory before the Map() is performed. Similarly, if performing an EfiPciIoOperation-
BusMasterWrite, 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
EfiPciIoOperation-
BusMasterCommonBuffer . However, only memory allocated via the AllocateBuffer()
interface can be mapped for this operation type.
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.