Home › The Linux Kernel › STMicroelectronics DMA API

Configuring a transfer

To configure a transfer, declare a new transfer descriptor struct stm_dma_params and initialize it for the required transfer mode using the dma_params_init() helper function: 

void dma_params_init(struct stm_dma_params *p,
                     unsigned long mode,
                     unsigned long list_type);

The dma_params_init() function takes three parameters, as described below.

Parameters Description
p This is a pointer to an empty stm_dma_params structure. The structure is filled in by this and the following configuration functions. This structure is declared in linux/stm/stm-dma.h.
mode This is the operating mode of the transfer, and may be one of the following: MODE_FREERUNNING, MODE_PACED, MODE_SRC_SCATTER or MODE_DST_SCATTER
list_type This parameter specifies the type of linked list in use, and is either STM_DMA_LIST_CIRC (for a closed, circular linked list) or STM_DMA_LIST_OPEN (for an open, linear linked list).

The next step is to fill in transfer-specific parameters and configuration. This is done by using a set of inline functions, which set parameters in the transfer descriptor. Which parameters need to be set, and thus which functions need to be called, depends on the transfer mode.

To configure a transfer, declare a new transfer descriptor struct stm_dma_params and fill it with the mode parameters for the transfer using the declare_dma_parms() helper function. It is necessary to associate the transfer with a particular DMA controller at this stage, as there may be more than one controller available in the system.

Note: Attempting to recompile a transfer with different values than those given in declare_dma_params() without a call to dma_free_descriptor() first is an undefined operation and should not be attempted. 

	static inline void declare_dma_parms(
					struct stm_dma_params *p,
					unsigned long mode,
					unsigned long list_type,
					unsigned long context,
					unsigned long blocking,
					char *name)

The declare_dma_parms() function takes six parameters, as described below.

Parameters Description
p This is a pointer to an empty stm_dma_params structure. The structure is filled in by this and the following configuration functions. This structure is declared in linux/stm/stm-dma.h.
mode This is the operating mode of the transfer, and may be one of the following: MODE_FREERUNNING, MODE_PACED, MODE_SH_COMPATIBILITY, MODE_SRC_SCATTER or MODE_DST_SCATTER
list_type This parameter specifies the type of linked list in use, and is either STM_DMA_LIST_CIRC (for a closed, circular linked list) or STM_DMA_LIST_OPEN (for an open, linear linked list.
context This parameter specifies whether the function from which dma_compile_params() is called is executing in task or interrupt context. Valid values are: STM_DMA_SETUP_CONTEXT_TASK or STM_DMA_SETUP_CONTEXT_ISR.
blocking This parameter specifies how the dma_xfer_list() function should behave if the selected channel is busy when the transfer starts. The two options are to sleep until the channel becomes free or return immediately with a -BUSY error message. Note that blocking cannot be used from interrupt context.
name The parameter is the string associated with the FDMA controller. It must match the name registered by the DMAC in question. For the STM_DMA controller the only valid string is exported from linux/stm/smt-dma.h as STM_DMAC_ID. Maximum of 30 characters.

This function returns zero on success, or an STDERR error number otherwise.

The next step is to specify transfer-specific parameters and configuration. This is done by using a set of inline functions, all of which are defined in the header file stm-dma.h.