d_map_list Kernel Service

Purpose

Performs platform-specific DMA mapping for a list of virtual addresses.

Syntax

#include <sys/dma.h>
int d_map_list (*handle, flags, minxfer, *virt_list, *bus_list)
struct d_handle *handle;
int flags;
int minxfer;
struct dio *virt_list; 
struct dio *bus_list;
Note: The following is the interface definition for d_map_list when the DMA_ADDRESS_64 and DMA_ENABLE_64 flags are set on the d_map_init call.
int d_map_list (*handle, flags, minxfer, *virt_list, *bus_list)
struct d_handle *handle;
int flags;
int minxfer;
struct dio_64 *virt_list; 
struct dio_64 *bus_list;

Parameters

Item Description
handle Indicates the unique handle returned by the d_map_init kernel service.
flags Specifies one of the following flags:
DMA_READ
Transfers from a device to memory.
BUS_DMA
Transfers from one device to another device.
DMA_BYPASS
Do not check page access.
DMA_STMAP
Indicates a short-term mapping.
minxfer Specifies the minimum transfer size for the device.
virt_list Specifies a list of virtual buffer addresses and lengths.
bus_list Specifies a list of bus addresses and lengths.

Description

The d_map_list kernel service is a bus-specific utility routine determined by the d_map_init kernel service that accepts a list of virtual addresses and sizes and provides the resulting list of bus addresses. This service fills out the corresponding bus address list for use by the device in performing the DMA transfer. This service allows for scatter/gather capability of a device and also allows the device to combine multiple requests that are contiguous with respect to the device. The lists are passed via the dio structure. If the d_map_list service is unable to complete the mapping due to exhausting the capacity of the provided dio structure, the DMA_DIOFULL error is returned. If the d_map_list service is unable to complete the mapping due to exhausting resources required for the mapping, the DMA_NORES error is returned. In both of these cases, the bytes_done field of the dio virtual list is set to the number of bytes successfully mapped. This byte count is a multiple of the minxfer size for the device as provided on the call to d_map_list. The resid_iov field is set to the index of the remaining d_iovec fields in the list. Unless the DMA_BYPASS flag is set, this service verifies access permissions to each page. If an access violation is encountered on a page with the list, the DMA_NOACC error is returned, and the bytes_done field is set to the number of bytes preceding the faulting iovec. If the mapping is for short term (that is, it is unmapped as soon as the I/O is complete), you must set the DMA_STMAP flag.

Note:
  1. When the DMA_NOACC return value is received, no mapping is done, and the bus list is undefined. In this case, the resid_iov field is set to the index of the d_iovec that encountered the access violation.
  2. You can use the D_MAP_LIST macro provided in the /usr/include/sys/dma.h file to code calls to the d_map_list kernel service.

Return Values

Item Description
DMA_NORES Indicates that resources were exhausted during mapping.
Note: d_map_list possible partial transfer was mapped. Device driver may continue with partial transfer and submit the remainer on a subsequent d_map_list call, or call d_unmap_list to undo the partial mapping. If a partial transfer is issued, then the driver must call d_unmap_list when the I/O is complete.
Item Description
DMA_DIOFULL Indicates that the target bus list is full.
Note: d_map_list possible partial transfer was mapped. Device driver may continue with partial transfer and submit the remainder on a subsequent d_map_list call, or call d_unmap_list to undo the partial mapping. If a partial transfer is issued, then the driver must call d_unmap_list when the I/O is complete.
Item Description
DMA_NOACC Indicates no access permission to a page in the list.
.
Note: d_map_list no mapping was performed. No need for the device driver to call d_unmap_list, but the driver must fail the faulting I/O request, and resubmit any remainder in a subsequent d_map_list call.
Item Description
DMA_SUCC Indicates that the entire transfer successfully mapped.
Note: d_map_list successful mapping was performed. Device driver must call d_unmap_list when the I/O is complete. In the case of a long-term mapping, the driver must call d_unmap_list when the long-term mapping is no longer needed.