Intel® Quark™ Microcontroller Software Interface  1.4.0
Intel® Quark™ Microcontroller BSP
DMA

DMA Driver for Quark Microcontrollers. More...

Data Structures

struct  qm_dma_channel_config_t
 DMA channel configuration structure. More...
 
struct  qm_dma_transfer_t
 DMA single block transfer configuration structure. More...
 
struct  qm_dma_multi_transfer_t
 DMA multiblock transfer configuration structure. More...
 

Enumerations

enum  qm_dma_handshake_polarity_t { QM_DMA_HANDSHAKE_POLARITY_HIGH = 0x0, QM_DMA_HANDSHAKE_POLARITY_LOW = 0x1 }
 DMA Handshake Polarity. More...
 
enum  qm_dma_burst_length_t {
  QM_DMA_BURST_TRANS_LENGTH_1 = 0x0, QM_DMA_BURST_TRANS_LENGTH_4 = 0x1, QM_DMA_BURST_TRANS_LENGTH_8 = 0x2, QM_DMA_BURST_TRANS_LENGTH_16 = 0x3,
  QM_DMA_BURST_TRANS_LENGTH_32 = 0x4, QM_DMA_BURST_TRANS_LENGTH_64 = 0x5, QM_DMA_BURST_TRANS_LENGTH_128, QM_DMA_BURST_TRANS_LENGTH_256 = 0x7
}
 DMA Burst Transfer Length. More...
 
enum  qm_dma_transfer_width_t {
  QM_DMA_TRANS_WIDTH_8 = 0x0, QM_DMA_TRANS_WIDTH_16 = 0x1, QM_DMA_TRANS_WIDTH_32 = 0x2, QM_DMA_TRANS_WIDTH_64 = 0x3,
  QM_DMA_TRANS_WIDTH_128 = 0x4, QM_DMA_TRANS_WIDTH_256 = 0x5
}
 DMA Transfer Width. More...
 
enum  qm_dma_channel_direction_t { QM_DMA_MEMORY_TO_MEMORY = 0x0, QM_DMA_MEMORY_TO_PERIPHERAL, QM_DMA_PERIPHERAL_TO_MEMORY = 0x2 }
 DMA channel direction. More...
 
enum  qm_dma_transfer_type_t { QM_DMA_TYPE_SINGLE, QM_DMA_TYPE_MULTI_CONT, QM_DMA_TYPE_MULTI_LL, QM_DMA_TYPE_MULTI_LL_CIRCULAR }
 

Functions

int qm_dma_init (const qm_dma_t dma)
 Initialise the DMA controller. More...
 
int qm_dma_channel_set_config (const qm_dma_t dma, const qm_dma_channel_id_t channel_id, qm_dma_channel_config_t *const channel_config)
 Setup a DMA channel configuration. More...
 
int qm_dma_transfer_set_config (const qm_dma_t dma, const qm_dma_channel_id_t channel_id, qm_dma_transfer_t *const transfer_config)
 Setup a DMA single block transfer. More...
 
int qm_dma_multi_transfer_set_config (const qm_dma_t dma, const qm_dma_channel_id_t channel_id, qm_dma_multi_transfer_t *const multi_transfer_config)
 Setup a DMA multiblock transfer. More...
 
int qm_dma_transfer_start (const qm_dma_t dma, const qm_dma_channel_id_t channel_id)
 Start a DMA transfer. More...
 
int qm_dma_transfer_terminate (const qm_dma_t dma, const qm_dma_channel_id_t channel_id)
 Terminate a DMA transfer. More...
 
int qm_dma_transfer_mem_to_mem (const qm_dma_t dma, const qm_dma_channel_id_t channel_id, qm_dma_transfer_t *const transfer_config)
 Setup and start memory to memory transfer. More...
 
int qm_dma_save_context (const qm_dma_t dma, qm_dma_context_t *const ctx)
 Save DMA peripheral's context. More...
 
int qm_dma_restore_context (const qm_dma_t dma, const qm_dma_context_t *const ctx)
 Restore DMA peripheral's context. More...
 

Detailed Description

DMA Driver for Quark Microcontrollers.

Enumeration Type Documentation

DMA Burst Transfer Length.

Enumerator
QM_DMA_BURST_TRANS_LENGTH_1 

Burst length 1 data item.

QM_DMA_BURST_TRANS_LENGTH_4 

Burst length 4 data items.

QM_DMA_BURST_TRANS_LENGTH_8 

Burst length 8 data items.

QM_DMA_BURST_TRANS_LENGTH_16 

Burst length 16 data items.

QM_DMA_BURST_TRANS_LENGTH_32 

Burst length 32 data items.

QM_DMA_BURST_TRANS_LENGTH_64 

Burst length 64 data items.

QM_DMA_BURST_TRANS_LENGTH_128 

Burst length 128 data items.

QM_DMA_BURST_TRANS_LENGTH_256 

Burst length 256 data items.

Definition at line 29 of file qm_dma.h.

DMA channel direction.

Enumerator
QM_DMA_MEMORY_TO_MEMORY 

Memory to memory transfer.

QM_DMA_MEMORY_TO_PERIPHERAL 

Memory to peripheral transfer.

QM_DMA_PERIPHERAL_TO_MEMORY 

Peripheral to memory transfer.

Definition at line 56 of file qm_dma.h.

DMA Handshake Polarity.

Enumerator
QM_DMA_HANDSHAKE_POLARITY_HIGH 

Set HS polarity high.

QM_DMA_HANDSHAKE_POLARITY_LOW 

Set HS polarity low.

Definition at line 21 of file qm_dma.h.

Enumerator
QM_DMA_TYPE_SINGLE 

Single block mode.

QM_DMA_TYPE_MULTI_CONT 

Contiguous multiblock mode.

QM_DMA_TYPE_MULTI_LL 

Link list multiblock mode.

QM_DMA_TYPE_MULTI_LL_CIRCULAR 

Link list multiblock mode with cyclic operation.

Definition at line 66 of file qm_dma.h.

DMA Transfer Width.

Enumerator
QM_DMA_TRANS_WIDTH_8 

Transfer width of 8 bits.

QM_DMA_TRANS_WIDTH_16 

Transfer width of 16 bits.

QM_DMA_TRANS_WIDTH_32 

Transfer width of 32 bits.

QM_DMA_TRANS_WIDTH_64 

Transfer width of 64 bits.

QM_DMA_TRANS_WIDTH_128 

Transfer width of 128 bits.

QM_DMA_TRANS_WIDTH_256 

Transfer width of 256 bits.

Definition at line 44 of file qm_dma.h.

Function Documentation

int qm_dma_channel_set_config ( const qm_dma_t  dma,
const qm_dma_channel_id_t  channel_id,
qm_dma_channel_config_t *const  channel_config 
)

Setup a DMA channel configuration.

Configures the channel source width, burst size, channel direction, handshaking interface, transfer type and registers the client callback and callback context. qm_dma_init() must first be called before configuring a channel. This function only needs to be called once unless a channel is being repurposed or its transfer type is changed.

Parameters
[in]dmaDMA instance.
[in]channel_idThe channel to start.
[in]channel_configThe DMA channel configuration as defined by the DMA client. This must not be NULL.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 254 of file qm_dma.c.

References qm_dma_channel_config_t::callback_context, qm_dma_channel_config_t::channel_direction, qm_dma_channel_config_t::client_callback, qm_dma_channel_config_t::destination_burst_length, qm_dma_channel_config_t::destination_transfer_width, qm_dma_channel_config_t::handshake_interface, qm_dma_channel_config_t::handshake_polarity, QM_DMA_CHANNEL_NUM, QM_DMA_MEMORY_TO_MEMORY, QM_DMA_MEMORY_TO_PERIPHERAL, QM_DMA_NUM, QM_DMA_PERIPHERAL_TO_MEMORY, QM_DMA_TYPE_MULTI_LL_CIRCULAR, qm_dma_channel_config_t::source_burst_length, qm_dma_channel_config_t::source_transfer_width, and qm_dma_channel_config_t::transfer_type.

Referenced by qm_i2c_dma_channel_config(), qm_spi_dma_channel_config(), and qm_uart_dma_channel_config().

int qm_dma_init ( const qm_dma_t  dma)

Initialise the DMA controller.

The DMA controller and channels are first disabled. All DMA controller interrupts are masked using the controllers interrupt masking registers. The system DMA interrupts are then unmasked. Finally the DMA controller is enabled. This function must only be called once as it resets the DMA controller and interrupt masking.

Parameters
[in]dmaDMA instance.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 208 of file qm_dma.c.

References qm_dma_int_reg_t::clear_block_low, qm_dma_int_reg_t::clear_dst_trans_low, qm_dma_int_reg_t::clear_err_low, qm_dma_int_reg_t::clear_src_trans_low, qm_dma_int_reg_t::clear_tfr_low, clk_dma_enable(), qm_dma_int_reg_t::mask_block_low, qm_dma_int_reg_t::mask_dst_trans_low, qm_dma_int_reg_t::mask_err_low, qm_dma_int_reg_t::mask_src_trans_low, qm_dma_int_reg_t::mask_tfr_low, QM_DMA_CHANNEL_NUM, and QM_DMA_NUM.

int qm_dma_multi_transfer_set_config ( const qm_dma_t  dma,
const qm_dma_channel_id_t  channel_id,
qm_dma_multi_transfer_t *const  multi_transfer_config 
)

Setup a DMA multiblock transfer.

If the DMA channel has been configured for contiguous multiblock transfers, this function sets the source address, destination address, block size and number of block parameters needed to perform a continguous multiblock transfer. The linked_list_first parameter in the transfer struct is ignored.

If the DMA channel has been configured for linked-list multiblock transfers, this function populates a linked list in the client memory area pointed at by the linked_list_first parameter in the transfer struct, using the provided parameters source address, destination address, block size and number of blocks (equal to the number of LLIs). This function may be called repeteadly in order to add different client buffers for transmission/reception that are not contiguous in memory (scatter-gather) in a buffer chain fashion. When calling qm_dma_transfer_start, the DMA core sees a single linked list built using consecutive calls to this function. Furthermore, if the transfer type is linked-list cyclic, the linked_list_address parameter of the last LLI points at the first LLI. The client needs to allocate enough memory starting at linked_list_first for the whole set of LLIs to fit, i.e. (num_blocks * sizeof(qm_dma_linked_list_item_t)).

The DMA driver manages the block interrupts so that only when the last block of a buffer has been transfered, the client callback is invoked. Note that in linked-list mode, each buffer transfer results on a client callback, and all buffers need to contain the same number of blocks.

qm_dma_multi_transfer_set_config() must be called before starting every transfer, even if the addresses, block size and other configuration information remain unchanged.

Parameters
[in]dmaDMA instance.
[in]channel_idThe channel to start.
[in]multi_transfer_configThe transfer DMA configuration as defined by the dma client. This must not be NULL.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 437 of file qm_dma.c.

References qm_dma_multi_transfer_t::block_size, qm_dma_chan_reg_t::ctrl_low, qm_dma_multi_transfer_t::destination_address, qm_dma_multi_transfer_t::linked_list_first, qm_dma_chan_reg_t::llp_low, qm_dma_multi_transfer_t::num_blocks, QM_DMA_CHANNEL_NUM, QM_DMA_NUM, QM_DMA_TYPE_MULTI_CONT, QM_DMA_TYPE_MULTI_LL, QM_DMA_TYPE_MULTI_LL_CIRCULAR, and qm_dma_multi_transfer_t::source_address.

int qm_dma_restore_context ( const qm_dma_t  dma,
const qm_dma_context_t *const  ctx 
)

Restore DMA peripheral's context.

Restore the configuration of the specified DMA peripheral after exiting sleep.

Parameters
[in]dmaDMA device.
[in]ctxDMA context structure. This must not be NULL.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 705 of file qm_dma.c.

References qm_dma_context_t::cfg_high, qm_dma_misc_reg_t::cfg_low, qm_dma_context_t::cfg_low, qm_dma_chan_reg_t::ctrl_low, qm_dma_context_t::ctrl_low, qm_dma_context_t::llp_low, qm_dma_context_t::misc_cfg_low, QM_DMA_CHANNEL_NUM, and QM_DMA_NUM.

int qm_dma_save_context ( const qm_dma_t  dma,
qm_dma_context_t *const  ctx 
)

Save DMA peripheral's context.

Saves the configuration of the specified DMA peripheral before entering sleep.

Parameters
[in]dmaDMA device.
[out]ctxDMA context structure. This must not be NULL.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 681 of file qm_dma.c.

References qm_dma_context_t::cfg_high, qm_dma_context_t::cfg_low, qm_dma_context_t::ctrl_low, qm_dma_context_t::llp_low, qm_dma_context_t::misc_cfg_low, QM_DMA_CHANNEL_NUM, and QM_DMA_NUM.

int qm_dma_transfer_mem_to_mem ( const qm_dma_t  dma,
const qm_dma_channel_id_t  channel_id,
qm_dma_transfer_t *const  transfer_config 
)

Setup and start memory to memory transfer.

This function will setup a memory to memory transfer by calling qm_dma_transfer_setup() and will then start the transfer by calling qm_dma_transfer_start(). This is done for consistency across user applications.

Parameters
[in]dmaDMA instance.
[in]channel_idThe channel to start.
[in]transfer_configThe transfer DMA configuration as defined by the dma client. This must not be NULL.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 656 of file qm_dma.c.

References qm_dma_transfer_t::block_size, qm_dma_transfer_t::destination_address, QM_DMA_CHANNEL_NUM, QM_DMA_NUM, qm_dma_transfer_set_config(), qm_dma_transfer_start(), and qm_dma_transfer_t::source_address.

int qm_dma_transfer_set_config ( const qm_dma_t  dma,
const qm_dma_channel_id_t  channel_id,
qm_dma_transfer_t *const  transfer_config 
)

Setup a DMA single block transfer.

Configure the source address,destination addresses and block size. qm_dma_channel_set_config() must first be called before configuring a transfer. qm_dma_transfer_set_config() must be called before starting every transfer, even if the addresses and block size remain unchanged.

Parameters
[in]dmaDMA instance.
[in]channel_idThe channel to start.
[in]transfer_configThe transfer DMA configuration as defined by the dma client. This must not be NULL.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 345 of file qm_dma.c.

References qm_dma_transfer_t::block_size, qm_dma_transfer_t::destination_address, QM_DMA_CHANNEL_NUM, QM_DMA_NUM, and qm_dma_transfer_t::source_address.

Referenced by qm_dma_transfer_mem_to_mem(), qm_i2c_master_dma_transfer(), qm_spi_dma_transfer(), qm_uart_dma_read(), and qm_uart_dma_write().

int qm_dma_transfer_start ( const qm_dma_t  dma,
const qm_dma_channel_id_t  channel_id 
)

Start a DMA transfer.

qm_dma_transfer_set_config() mustfirst be called before starting a transfer.

Parameters
[in]dmaDMA instance.
[in]channel_idThe channel to start.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 582 of file qm_dma.c.

References qm_dma_int_reg_t::clear_block_low, qm_dma_int_reg_t::clear_err_low, qm_dma_int_reg_t::clear_tfr_low, qm_dma_int_reg_t::mask_block_low, qm_dma_int_reg_t::mask_err_low, qm_dma_int_reg_t::mask_tfr_low, QM_DMA_CHANNEL_NUM, and QM_DMA_NUM.

Referenced by qm_dma_transfer_mem_to_mem(), qm_i2c_master_dma_transfer(), qm_spi_dma_transfer(), qm_uart_dma_read(), and qm_uart_dma_write().

int qm_dma_transfer_terminate ( const qm_dma_t  dma,
const qm_dma_channel_id_t  channel_id 
)

Terminate a DMA transfer.

This function is only called if a transfer needs to be terminated manually. This may be require if an expected transfer complete callback has not been received. Terminating the transfer will trigger the transfer complete callback. The length returned by the callback is the transfer length at the time that the transfer was terminated.

Parameters
[in]dmaDMA instance.
[in]channel_idThe channel to stop.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 618 of file qm_dma.c.

References qm_dma_chan_reg_t::llp_low, qm_dma_int_reg_t::mask_block_low, qm_dma_int_reg_t::mask_err_low, qm_dma_int_reg_t::mask_tfr_low, QM_DMA_CHANNEL_NUM, and QM_DMA_NUM.

Referenced by qm_i2c_dma_transfer_terminate(), qm_spi_dma_transfer_terminate(), qm_uart_dma_read_terminate(), and qm_uart_dma_write_terminate().