Data Structures for Drivers ddi_dmae_req(9S)
NAME
ddi_dmae_req - DMA engine request structure
SYNOPSIS
#include
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 toddi_dmae_prog(9F).
STRUCTURE MEMBERSThe 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 per-
formed. The value DMAE_CMD_WRITE signifies
that data is to be transferred from memoryto the I/O device. The value DMAE_CMD_READ
signifies that data is to be transferredfrom 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 singleI/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 ddi_dmae_req(9S)
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 routinetakes one argument, specified by the proc-
parms structure member, and returns a pointer to a structure of typeddi_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 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 routinethat called it. If there are no more seg-
ments 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 architec-
ture supports the use of multiple DMAcookies 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 parentbus nexus supports this feature by examin-
ing the scatter/gather list size returnedin the dlim_sgllen member of the DMA limit
structure returned by the driver's call toddi_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 specifythe 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 ofthe scatter/gather list to 1 before pass-
ing it to the DMA setup routine, and (b)the driver must not set the DMAE_BUF_CHAIN
SunOS 5.11 Last change: 18 Nov 2004 2
Data Structures for Drivers ddi_dmae_req(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 DMAE_BUF_CHAIN flag in the
ddi_dmae_req structure. Before calling
ddi_dmae_prog(), the driver must prefetch
cookies by repeatedly callingddi_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 deter-
mines how many discontiguous segments ofphysical 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 cookiesbefore calling ddi_dmae_prog(). The rea-
sons for this are: o First, the driver must have someway 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 ddi_dmae_req(9S)
memory position and alignment of the DMA object, all or just part of the current DMA window mightbe 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 ahigh-level interrupt routine. If
the cookies were not prefetched, the nextcookie routine would haveto 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 everysegment whose number is an integral multi-
ple of the scatter/gather list size tofall 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 usethe 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 mul-
tiple 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 in8-bit mode (DMAE_PATH_8), and channels 5,
6, and 7 are programmed in 16-bit, count-
by-word mode (DMAE_PATH_16).
SunOS 5.11 Last change: 18 Nov 2004 4
Data Structures for Drivers ddi_dmae_req(9S)
der_cycles Specifies the timing mode to be used dur-
ing DMA data transfers. The default ofzero (DMAE_CYCLES_1) specifies ISA compa-
tible timing. Drivers using this mode mustalso 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 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 theder_cycles structure member) should use
the DMAE_TRANS_SNGL mode.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Architecture | x86 ||_____________________________|_____________________________|
SEE ALSO
isa(4), attributes(5), ddi_dma_segtocookie(9F),
ddi_dmae(9F), ddi_dma_lim_x86(9S), ddi_dma_req(9S)
SunOS 5.11 Last change: 18 Nov 2004 5