illumos: manual page: ddi_dmae

DDI_DMAE_REQ(9S) Data Structures for Drivers DDI_DMAE_REQ(9S)

NAME

ddi_dmae_req - DMA engine request structure

SYNOPSIS

#include <sys/dma_engine.h>

INTERFACE LEVEL

illumos x86 DDI specific (illumos x86 DDI).

DESCRIPTION

A device driver uses the ddi_dmae_req structure to describe the
parameters for a DMA channel. This structure contains all the information
necessary to set up the channel, except for the DMA memory address and
transfer count. The defaults, as specified below, support most standard
devices. Other modes might be desirable for some devices, or to increase
performance. The DMA engine request structure is passed to
ddi_dmae_prog(9F).

STRUCTURE MEMBERS

The ddi_dmae_req structure contains several members, each of which
controls some aspect of DMA engine operation. The structure members
associated with supported DMA engine options are described here.

uchar_t der_command; /* Read / Write * /
uchar_t der_bufprocess; /* Standard / Chain */
uchar_t der_path; /* 8 / 16 / 32 */
uchar_t der_cycles; /* Compat / Type A / Type B / Burst */
uchar_t der_trans; /* Single / Demand / Block */
ddi_dma_cookie_t *(*proc)(); /* address of nextcookie routine */
void *procparms; /* parameter for nextcookie call */

der_command
Specifies what DMA operation is to be performed. The
value DMAE_CMD_WRITE signifies that data is to be
transferred from memory to the I/O device. The value
DMAE_CMD_READ signifies that data is to be transferred
from the I/O device to memory. This field must be set
by the driver before calling ddi_dmae_prog().

der_bufprocess
On some bus types, a driver can set der_bufprocess to
the value DMAE_BUF_CHAIN to specify that multiple DMA
cookies will be given to the DMA engine for a single
I/O transfer. This action causes a scatter/gather
operation. In this mode of operation, the driver calls
ddi_dmae_prog() to give the DMA engine the DMA engine
request structure and a pointer to the first cookie.
The proc structure member must be set to the address of
a driver nextcookie routine. This routine takes one
argument, specified by the procparms structure member,
and returns a pointer to a structure of type
ddi_dma_cookie_t that specifies the next cookie for the
I/O transfer. When the DMA engine is ready to receive
an additional cookie, the bus nexus driver controlling
that DMA engine calls the routine specified by the proc
structure member to obtain the next cookie from the
driver. The driver's nextcookie routine must then
return the address of the next cookie (in static
storage) to the bus nexus routine that called it. If
there are no more segments in the current DMA window,
then (*proc)() must return the NULL pointer.

A driver can specify the DMAE_BUF_CHAIN flag only if
the particular bus architecture supports the use of
multiple DMA cookies in a single I/O transfer. A bus
DMA engine can support this feature either with a
fixed-length scatter/gather list, or by an interrupt
chaining feature. A driver must determine whether its
parent bus nexus supports this feature by examining the
scatter/gather list size returned in the
dma_attr_sgllen member of the DMA attributes structure
returned by the driver's call to ddi_dmae_getattr().
(See ddi_dma_attr(9S).) If the size of the
scatter/gather list is 1, then no chaining is
available. The driver must not specify the
DMAE_BUF_CHAIN flag in the ddi_dmae_req structure it
passes to ddi_dmae_prog(), and the driver need not
provide a nextcookie routine.

If the size of the scatter/gather list is greater than
1, then DMA chaining is available, and the driver has
two options. Under the first option, the driver chooses
not to use the chaining feature. In this case (a) the
driver must set the size of the scatter/gather list to
1 before passing it to the DMA setup routine, and (b)
the driver must not set the DMAE_BUF_CHAIN flag.

Under the second option, the driver chooses to use the
chaining feature, in which case, (a) it should leave
the size of the scatter/gather list alone, and (b) it
must set the DMAE_BUF_CHAIN flag in the ddi_dmae_req
structure. Before calling ddi_dmae_prog(), the driver
must prefetch cookies until either (1) the end of the
DMA window is reached, or (2) the size of the
scatter/gather list is reached, whichever occurs first.
These cookies must be saved by the driver until they
are requested by the nexus driver calling the driver's
nextcookie routine. The driver's nextcookie routine
must return the prefetched cookies in order, one cookie
for each call to the nextcookie routine, until the list
of prefetched cookies is exhausted. After the end of
the list of cookies is reached, the nextcookie routine
must return the NULL pointer.

The size of the scatter/gather list determines how many
discontiguous segments of physical memory can
participate in a single DMA transfer. ISA bus DMA
engines have no scatter/gather capability, so their
scatter/gather list sizes are 1. Other finite
scatter/gather list sizes would also be possible. For
performance reasons, drivers should use the chaining
capability if it is available on their parent bus.

As described above, a driver making use of DMA chaining
must prefetch DMA cookies before calling
ddi_dmae_prog(). The reasons for this are:

o First, the driver must have some way to know
the total I/O count with which to program
the I/O device. This I/O count must match
the total size of all the DMA segments that
will be chained together into one DMA
operation. Depending on the size of the
scatter/gather list and the memory position
and alignment of the DMA object, all or just
part of the current DMA window might be able
to participate in a single I/O operation.
The driver must compute the I/O count by
adding up the sizes of the prefetched DMA
cookies. The number of cookies whose sizes
are to be summed is the lesser of (a) the
size of the scatter/gather list, or (b) the
number of segments remaining in the window.

o Second, on some bus architectures, the
driver's nextcookie routine can be called
from a high-level interrupt routine. If the
cookies were not prefetched, the nextcookie
routine would have to call DMA functions
from a high-level interrupt routine, which
is not recommended.
When breaking a DMA window into segments, the system
arranges for the end of every segment whose number is
an integral multiple of the scatter/gather list size to
fall on a device-granularity boundary, as specified in
the dma_attr_granular field in the ddi_dma_attr(9S)
structure.

If the scatter/gather list size is 1 (either because no
chaining is available or because the driver does not
want to use the chaining feature), then the total I/O
count for a single DMA operation is the size of DMA
segment denoted by the single DMA cookie that is passed
in the call to ddi_dmae_prog(). In this case, the
system arranges for each DMA segment to be a multiple
of the device-granularity size.

der_path
Specifies the DMA transfer size. The default of zero
(DMAE_PATH_DEF) specifies ISA compatibility mode. In
that mode, channels 0, 1, 2, and 3 are programmed in
8-bit mode (DMAE_PATH_8), and channels 5, 6, and 7 are
programmed in 16-bit, count-by-word mode
(DMAE_PATH_16).

der_cycles
Specifies the timing mode to be used during DMA data
transfers. The default of zero (DMAE_CYCLES_1)
specifies ISA compatible timing. Drivers using this
mode must also specify DMAE_TRANS_SNGL in the der_trans
structure member.

der_trans
Specifies the bus transfer mode that the DMA engine
should expect from the device. The default value of
zero (DMAE_TRANS_SNGL) specifies that the device
performs one transfer for each bus arbitration cycle.
Devices that use ISA compatible timing (specified by a
value of zero, which is the default, in the der_cycles
structure member) should use the DMAE_TRANS_SNGL mode.

ATTRIBUTES