DMA

Overview

API Reference

group dma_interface

DMA Interface.

Enums

enum dma_channel_direction

Values:

MEMORY_TO_MEMORY = 0x0
MEMORY_TO_PERIPHERAL
PERIPHERAL_TO_MEMORY
enum dma_addr_adj

Valid values for source_addr_adj and dest_addr_adj

Values:

DMA_ADDR_ADJ_INCREMENT
DMA_ADDR_ADJ_DECREMENT
DMA_ADDR_ADJ_NO_CHANGE

Functions

static int dma_config(struct device *dev, u32_t channel, struct dma_config *config)

Configure individual channel for DMA transfer.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • channel: Numeric identification of the channel to configure
  • config: Data structure containing the intended configuration for the selected channel
Return Value
  • 0: if successful.
  • Negative: errno code if failure.

static int dma_reload(struct device *dev, u32_t channel, u32_t src, u32_t dst, size_t size)

Reload buffer(s) for a DMA channel.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • channel: Numeric identification of the channel to configure selected channel
  • src: source address for the DMA transfer
  • dst: destination address for the DMA transfer
  • size: size of DMA transfer
Return Value
  • 0: if successful.
  • Negative: errno code if failure.

int dma_start(struct device *dev, u32_t channel)

Enables DMA channel and starts the transfer, the channel must be configured beforehand.

Implementations must check the validity of the channel ID passed in and return -EINVAL if it is invalid.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • channel: Numeric identification of the channel where the transfer will be processed
Return Value
  • 0: if successful.
  • Negative: errno code if failure.

static int z_impl_dma_start(struct device *dev, u32_t channel)
int dma_stop(struct device *dev, u32_t channel)

Stops the DMA transfer and disables the channel.

Implementations must check the validity of the channel ID passed in and return -EINVAL if it is invalid.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • channel: Numeric identification of the channel where the transfer was being processed
Return Value
  • 0: if successful.
  • Negative: errno code if failure.

static int z_impl_dma_stop(struct device *dev, u32_t channel)
static u32_t dma_width_index(u32_t size)

Look-up generic width index to be used in registers.

WARNING: This look-up works for most controllers, but may not work for yours. Ensure your controller expects the most common register bit values before using this convenience function. If your controller does not support these values, you will have to write your own look-up inside the controller driver.

Parameters
  • size: width of bus (in bytes)
Return Value
  • common: DMA index to be placed into registers.

static u32_t dma_burst_index(u32_t burst)

Look-up generic burst index to be used in registers.

WARNING: This look-up works for most controllers, but may not work for yours. Ensure your controller expects the most common register bit values before using this convenience function. If your controller does not support these values, you will have to write your own look-up inside the controller driver.

Parameters
  • burst: number of bytes to be sent in a single burst
Return Value
  • common: DMA index to be placed into registers.

struct dma_block_config
#include <dma.h>

DMA block configuration structure.

source_address is block starting address at source source_gather_interval is the address adjustment at gather boundary dest_address is block starting address at destination dest_scatter_interval is the address adjustment at scatter boundary dest_scatter_count is the continuous transfer count between scatter boundaries source_gather_count is the continuous transfer count between gather boundaries block_size is the number of bytes to be transferred for this block.

config is a bit field with the following parts: source_gather_en [ 0 ] - 0-disable, 1-enable dest_scatter_en [ 1 ] - 0-disable, 1-enable source_addr_adj [ 2 : 3 ] - 00-increment, 01-decrement, 10-no change dest_addr_adj [ 4 : 5 ] - 00-increment, 01-decrement, 10-no change source_reload_en [ 6 ] - reload source address at the end of block transfer 0-disable, 1-enable dest_reload_en [ 7 ] - reload destination address at the end of block transfer 0-disable, 1-enable fifo_mode_control [ 8 : 11 ] - How full of the fifo before transfer start. HW specific. flow_control_mode [ 12 ] - 0-source request served upon data availability 1-source request postponed until destination request happens reserved [ 13 : 15 ]

struct dma_config
#include <dma.h>

DMA configuration structure.

dma_slot [ 0 : 5 ] - which peripheral and direction (HW specific) channel_direction [ 6 : 8 ] - 000-memory to memory, 001-memory to peripheral, 010-peripheral to memory, … complete_callback_en [ 9 ] - 0-callback invoked at completion only 1-callback invoked at completion of each block error_callback_en [ 10 ] - 0-error callback enabled 1-error callback disabled source_handshake [ 11 ] - 0-HW, 1-SW dest_handshake [ 12 ] - 0-HW, 1-SW channel_priority [ 13 : 16 ] - DMA channel priority source_chaining_en [ 17 ] - enable/disable source block chaining 0-disable, 1-enable dest_chaining_en [ 18 ] - enable/disable destination block chaining. 0-disable, 1-enable reserved [ 19 : 31 ]

source_data_size [ 0 : 15 ] - width of source data (in bytes) dest_data_size [ 16 : 31 ] - width of dest data (in bytes) source_burst_length [ 0 : 15 ] - number of source data units dest_burst_length [ 16 : 31 ] - number of destination data units

block_count is the number of blocks used for block chaining, this depends on availability of the DMA controller.

callback_arg private argument from DMA client.

dma_callback is the callback function pointer. If enabled, callback function will be invoked at transfer completion or when error happens (error_code: zero-transfer success, non zero-error happens).