ddi_dmae_req(9S)

NAME

ddi_dmae_req − DMA engine request structure

SYNOPSIS

#include <sys/dma_engine.h>

INTERFACE LEVEL

Solaris x86 architecture specific (SunDDI).

DESCRIPTION

A ddi_dmae_req structure is used by a device driver to describe the desired operating parameters for a DMA channel. This structure contains all the information necessary to set up the channel, except for the memory address and count. This structure is implemented with default values equal to zero, so that normally only the der_command structure member has to be set in an otherwise clear structure. The defaults support most standard devices. Other modes may be desirable for some devices, or to increase performance. The DMA engine request structure is passed to ddi_dmae_prog() (see ddi_dmae(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;	/∗ NoAuto_init / Chain / Auto_init ∗/
uchar_t	der_step;	/∗ Inc / Dec / Hold ∗/
uchar_t	der_trans;	/∗ Single / Demand / Block ∗/
uchar_t	der_path;	/∗ 8 / 16 / 32 ∗/
uchar_t	der_cycles;	/∗ Compat / Type A / Type B / Burst ∗/
ddi_dma_cookie_t	∗(∗proc)();	/∗ address of nextcookie routine ∗/
void	∗procparms;	/∗ parameter for nextcookie call ∗/

The der_command field 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().

The value of the der_bufprocess field determines what the action of the DMA engine will be at the end of the DMA transfer. If der_bufprocess is set to DMAE_BUF_AUTO, then at the end of each DMA transfer the DMA engine will automatically reset its count and address registers to the same values programmed at the beginning of the transfer. At that point the channel will be ready to perform another DMA data transfer into the same data buffer without further programming.

On EISA buses, der_bufprocess may be set to DMAE_BUF_CHAIN to specify that multiple DMA cookies will be given to the DMA engine for a single I/O transfer, thus effecting 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 routine that 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 has finished using up a cookie, it will interrupt the processor to ask for the next cookie. The routine specified by the proc structure member will be called at that time. It should call ddi_dma_nextseg(9F) to get the next segment, and then call ddi_dma_segtocookie(9F) to convert it to a cookie. It should then return the address of the cookie (in static storage) to the DMA engine interrupt routine. If there are no more segments in the window, then (∗proc)() should return the NULL pointer.

DMAE_BUF_AUTO and DMAE_BUF_CHAIN are mutually exclusive options. The default value of zero for the der_bufprocess structure member specifies neither of those features.

The der_step field specifies whether the DMA engine will count up or down memory during a data transfer. The default of zero (DMAE_STEP_INC) specifies that the engine will transfer data into (or out of) memory starting at the base address and incrementing addresses upward. If the der_path structure member is zero (DMAE_PATH_8), or DMAE_PATH_16, then der_step may specify DMAE_STEP_DEC, which will cause the DMA engine to transfer data into (or out of) memory decrementing addresses downward.

The der_trans field specifies the bus transfer mode that the DMA engine should expect from the device. The value default of zero (DMAE_TRANS_SNGL) specifies that the device will perform 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.

A value of DMAE_TRANS_BLCK specifies that the device will perform a block of transfers for each arbitration cycle. A value of DMAE_TRANS_DMND specifies that the device will perform the Demand Transfer Mode protocol.

The der_path field 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). On the EISA bus, other sizes may be specified: DMAE_PATH_32 specifies 32-bit mode, and DMAE_PATH_16B specifies a 16-bit, count-by-byte mode.

The der_cycles field 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.

Museum