d_map_slave Kernel Service

Purpose

Accepts a list of virtual addresses and sizes and sets up the slave DMA controller.

Syntax

#include <sys/dma.h>
int d_map_slave (*handle, flags, minxfer, *vlist, chan_flag)
struct d_handle *handle;
int flags;
int minxfer;
struct dio *vlist;
uint chan_flag;

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.
minxfer Specifies the minimum transfer size for the device.
vlist Specifies a list of buffer addresses and lengths.
chan_flag Specifies the device and bus specific flags for the transfer.

Description

The d_map_slave kernel service accepts a list of virtual buffer addresses and sizes and sets up the slave DMA controller for the requested DMA transfer. This includes setting up the system address generation hardware for a specific slave channel to indicate the specified data buffers, and enabling the specific hardware channel. The d_map_slave kernel service is not an exported kernel service, but a bus-specific utility routine determined by the d_map_init kernel service and provided to the caller through the d_handle structure.

This service allows for scatter/gather capability of the slave DMA controller and also allows the device driver to coalesce multiple requests that are contiguous with respect to the device. The list is passed with the dio structure. If the d_map_slave kernel service is unable to complete the mapping due to resource, an error, DMA_NORES is returned, and the bytes_done field of the dio list is set to the number of bytes that were successfully mapped. This byte count is guaranteed to be a multiple of the minxfer parameter size of the device as provided to d_map_slave. Also, the resid_iov field is set to the index of the remaining d_iovec that could not be mapped. Unless the DMA_BYPASS flag is set, this service will verify access permissions to each page. If an access violation is encountered on a page within the list, an error, DMA_NOACC is returned and no mapping is done. The bytes_done field of the virtual list is set to the number of bytes preceding the faulting iovec. Also in this case, the resid_iov field is set to the index of the d_iovec entry that encountered the access violation.

The virtual addresses provided in the vlist parameter can be within multiple address spaces, distinguished by the cross-memory structure pointed to for each element of the dio list. Each cross-memory pointer can point to the same cross-memory descriptor for multiple buffers in the same address space, and for global space buffers, the pointers can be set to the address of the exported GLOBAL cross-memory descriptor, xmem_global.

The minxfer parameter specifies the absolute minimum data transfer supported by the device( the device blocking factor). If the device supports a minimum transfer of 512 bytes (floppy and disks, for example), the minxfer parameter would be set to 512. This allows the underlying services to map partial transfers to a correct multiple of the device block size.

Note:
  1. The d_map_slave kernel service does not support more than one outstanding DMA transfer per channel. Attempts to do multiple slave mappings on a single channel will corrupt the previous mappings.
  2. You can use the D_MAP_SLAVE macro provided in the /usr/include/sys/dma.h file to code calls to the d_map_clear kernel service.
  3. The possible flag values for the chan_flag parameter can be found in /usr/include/sys/dma.h. These flags can be logically ORed together to reflect the desired characteristics of the device and channel.
  4. If the CH_AUTOINIT flag is used then the transfer described by the vlist pointer is limited to a single buffer address with a length no greater than 4K bytes.

Return Values

Item Description
DMA_NORES Indicates that resources were exhausted during the mapping.
DMA_NOACC Indicates no access permission to a page in the list.
DMA_BAD_MODE Indicates that the mode specified by the chan_flag parameter is not supported.