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: - 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.
- 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.