ddi_dmae_req(9S)
NAME
ddi_dmae_req - DMA engine request structure
SYNOPSIS
#include <sys/dma_engine.h>
INTERFACE LEVEL
Solaris x86 DDI specific (Solaris 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_tder_command; /* Read / Write *
/uchar_tder_bufprocess; /* Standard / Chain */
uchar_tder_path; /* 8 / 16 / 32 */
uchar_tder_cycles; /* Compat / Type A / Type B / Burst */
uchar_tder_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 cal-
ling 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 rou-
tine. 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 con-
trolling that DMA engine calls the routine speci-
fied 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 such as
the one implemented in the EISA architecture. A
driver must determine whether its parent bus
nexus supports this feature by examining the
scatter/gather list size returned in the
dlim_sgllen member of the DMA limit structure
returned by the driver's call to
ddi_dmae_getlim(). (See ddi_dma_lim_x86(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 cal-
ling ddi_dmae_prog(), the driver must prefetch
cookies by repeatedly calling ddi_dma_nextseg(9F)
and ddi_dma_segtocookie(9F) until either (1) the
end of the DMA window is reached
(ddi_dma_nextseg(9F) returns NULL), 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 capa-
bility, so their scatter/gather list sizes are 1.
EISA bus DMA engines have a DMA chaining inter-
rupt facility that allows very large
scatter/gather operations. 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 pro-
gram the I/O device. This I/O count must
match the total size of all the DMA seg-
ments 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 cook-
ies 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
ddi_dma_nextseg() and ddi_dma_segtocookie()
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 dlim_granular field in the ddi_dma_lim_x86(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 chan-
nels 5, 6, and 7 are programmed in 16-bit,
count-by-word mode (DMAE_PATH_16). On the EISA
bus, other sizes can be specified: DMAE_PATH_32
specifies 32-bit mode, and DMAE_PATH_16B speci-
fies a 16-bit, count-by-byte mode.
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. On EISA buses, these other timing modes
are available:
DMAE_CYCLES_2
Specifies type ``A'' timing;
DMAE_CYCLES_3
Specifies type ``B'' timing;
DMAE_CYCLES_4
Specifies ``Burst'' timing.
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 compati-
ble timing (specified by a value of zero, which
is the default, in the der_cycles structure
member) should use the DMAE_TRANS_SNGL mode. On
EISA buses, a der_trans value of DMAE_TRANS_BLCK
specifies that the device perform a block of
transfers for each arbitration cycle. A value of
DMAE_TRANS_DMND specifies that the device perform
the Demand Transfer Mode protocol.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Architecture | x86 |
|_____________________________|_____________________________|
SEE ALSO
eisa(4), isa(4), attributes(5), ddi_dma_segtocookie(9F),
ddi_dmae(9F), ddi_dma_lim_x86(9S), ddi_dma_req(9S)
Man(1) output converted with
man2html