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

- Main Page
- Modules
- Data Structures
- Files

Data Structures | Enumerations | Functions
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

enum qm_dma_burst_length_t

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.

enum qm_dma_channel_direction_t

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.

enum qm_dma_handshake_polarity_t

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.

enum qm_dma_transfer_type_t

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.

enum qm_dma_transfer_width_t

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] | dma | DMA instance.
  [in] | channel_id | The channel to start.
  [in] | channel_config | The DMA channel configuration as defined by the DMA client. This must not be NULL.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | dma | DMA instance.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | dma | DMA instance.
  [in] | channel_id | The channel to start.
  [in] | multi_transfer_config | The transfer DMA configuration as defined by the dma client. This must not be NULL.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | dma | DMA device.
  [in] | ctx | DMA context structure. This must not be NULL.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | dma | DMA device.
  [out] | ctx | DMA context structure. This must not be NULL.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | dma | DMA instance.
  [in] | channel_id | The channel to start.
  [in] | transfer_config | The transfer DMA configuration as defined by the dma client. This must not be NULL.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | dma | DMA instance.
  [in] | channel_id | The channel to start.
  [in] | transfer_config | The transfer DMA configuration as defined by the dma client. This must not be NULL.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | dma | DMA instance.
  [in] | channel_id | The channel to start.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | dma | DMA instance.
  [in] | channel_id | The channel to stop.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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().