Data Structures for Drivers ddidmaereq(9S)
NAME
ddidmaereq - DMA engine request structure
SYNOPSIS
#include
INTERFACE LEVEL
Solaris x86 DI specific (Solaris x86 DI).
DESCRIPTION
A device driver uses the ddidmaereq 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
ddidmaeprog(9F).
STRUCTURE MEMBERS
The ddidmaereq 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.
uchartdercommand; /* Read / Write *
/uchartderbufprocess; /* Standard / Chain */
uchartderpath; /* 8 / 16 / 32 */
uchartdercycles; /* Compat / Type A / Type B / Burst */
uchartdertrans; /* Single / Demand / Block */
ddidmacookiet*(*proc)(); /* address of nextcookie routine */
void*procparms; /* parameter for nextcookie call */
dercommand Specifies what DMA operation is to be per-
formed. The value DMAECMDWRITE signifies
that data is to be transferred from memory
to the I/O device. The value DMAECMDREAD
signifies that data is to be transferred
from the I/O device to memory. This field
must be set by the driver before calling
ddidmaeprog().
derbufprocess On some bus types, a driver can set
derbufprocess to the value DMAEBUFCHAIN
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
SunOS 5.11 Last change: 18 Nov 2004 1
Data Structures for Drivers ddidmaereq(9S)
ddidmaeprog() 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 proc-
parms structure member, and returns a
pointer to a structure of type
ddidmacookiet 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 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 seg-
ments in the current DMA window, then
(*proc)() must return the NUL pointer.
A driver can specify the DMAEBUFCHAIN
flag only if the particular bus architec-
ture 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 examin-
ing the scatter/gather list size returned
in the dlimsgllen member of the DMA limit
structure returned by the driver's call to
ddidmaegetlim(). (See
ddidmalimx86(9S).) If the size of the
scatter/gather list is 1, then no chaining
is available. The driver must not specify
the DMAEBUFCHAIN flag in the
ddidmaereq structure it passes to
ddidmaeprog(), 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 pass-
ing it to the DMA setup routine, and (b)
the driver must not set the DMAEBUFCHAIN
SunOS 5.11 Last change: 18 Nov 2004 2
Data Structures for Drivers ddidmaereq(9S)
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 DMAEBUFCHAIN flag in the
ddidmaereq structure. Before calling
ddidmaeprog(), the driver must prefetch
cookies by repeatedly calling
ddidmanextseg(9F) and
ddidmasegtocookie(9F) until either (1)
the end of the DMA window is reached
(ddidmanextseg(9F) returns NUL), 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 NUL pointer.
The size of the scatter/gather list deter-
mines how many discontiguous segments of
physical memory can participate in a sin-
gle 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 ddidmaeprog(). The rea-
sons 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
SunOS 5.11 Last change: 18 Nov 2004 3
Data Structures for Drivers ddidmaereq(9S)
memory position and alignment of
the DMA object, all or just part
of the current DMA window might
be able to participate in a sin-
gle I/O operation. The driver
must compute the I/O count by
adding up the sizes of the pre-
fetched 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 architec-
tures, 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 ddidmanextseg() and
ddidmasegtocookie() 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 multi-
ple of the scatter/gather list size to
fall on a device-granularity boundary, as
specified in the dlimgranular field in
the ddidmalimx86(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
ddidmaeprog(). In this case, the system
arranges for each DMA segment to be a mul-
tiple of the device-granularity size.
derpath Specifies the DMA transfer size. The
default of zero (DMAEPATHDEF) specifies
ISA compatibility mode. In that mode,
channels 0, 1, 2, and 3 are programmed in
8-bit mode (DMAEPATH8), and channels 5,
6, and 7 are programmed in 16-bit, count-
by-word mode (DMAEPATH16).
SunOS 5.11 Last change: 18 Nov 2004 4
Data Structures for Drivers ddidmaereq(9S)
dercycles Specifies the timing mode to be used dur-
ing DMA data transfers. The default of
zero (DMAECYCLES1) specifies ISA compa-
tible timing. Drivers using this mode must
also specify DMAETRANSNGL in the
dertrans structure member.
dertrans Specifies the bus transfer mode that the
DMA engine should expect from the device.
The default value of zero
(DMAETRANSNGL) specifies that the dev-
ice 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
dercycles structure member) should use
the DMAETRANSNGL mode.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Architecture x86
SEE ALSO
isa(4), attributes(5), ddidmasegtocookie(9F),
ddidmae(9F), ddidmalimx86(9S), ddidmareq(9S)
SunOS 5.11 Last change: 18 Nov 2004 5
|
