This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

DMA

Overview

API Reference

group dma_interface

DMA Interface.

Defines

DMA_MAGIC

Typedefs

typedef void (*dma_callback_t)(const struct device *dev, void *user_data, uint32_t channel, int status)

Callback function for DMA transfer completion.

If enabled, callback function will be invoked at transfer completion or when error happens.

Parameters

  • dev – Pointer to the DMA device calling the callback.

  • user_data – A pointer to some user data or NULL

  • channel – The channel number

  • status – 0 on success, a negative errno otherwise

Enums

enum dma_channel_direction

Values:

enumerator MEMORY_TO_MEMORY = 0x0
enumerator MEMORY_TO_PERIPHERAL
enumerator PERIPHERAL_TO_MEMORY
enumerator PERIPHERAL_TO_PERIPHERAL
enum dma_addr_adj

Valid values for source_addr_adj and dest_addr_adj

Values:

enumerator DMA_ADDR_ADJ_INCREMENT
enumerator DMA_ADDR_ADJ_DECREMENT
enumerator DMA_ADDR_ADJ_NO_CHANGE
enum dma_channel_filter

Values:

enumerator DMA_CHANNEL_NORMAL
enumerator DMA_CHANNEL_PERIODIC

Functions

static inline int dma_config(const struct device *dev, uint32_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

Returns

  • 0 – if successful.

  • Negative – errno code if failure.

static inline int dma_reload(const struct device *dev, uint32_t channel, uint32_t src, uint32_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

Returns

  • 0 – if successful.

  • Negative – errno code if failure.

int dma_start(const struct device *dev, uint32_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

Returns

  • 0 – if successful.

  • Negative – errno code if failure.

int dma_stop(const struct device *dev, uint32_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

Returns

  • 0 – if successful.

  • Negative – errno code if failure.

int dma_request_channel(const struct device *dev, void *filter_param)

request DMA channel.

request DMA channel resources return -EINVAL if there is no valid channel available.

Parameters

  • dev – Pointer to the device structure for the driver instance.

  • filter_param – filter function parameter

Returns

  • dma – channel if successful.

  • Negative – errno code if failure.

void dma_release_channel(const struct device *dev, uint32_t channel)

release DMA channel.

release DMA channel resources

Parameters

  • dev – Pointer to the device structure for the driver instance.

  • channel – channel number

int dma_chan_filter(const struct device *dev, int channel, void *filter_param)

DMA channel filter.

filter channel by attribute

Parameters

  • dev – Pointer to the device structure for the driver instance.

  • channel – channel number

  • filter_param – filter attribute

Returns

Negative – errno code if not support

static inline int dma_get_status(const struct device *dev, uint32_t channel, struct dma_status *stat)

get current runtime status of DMA transfer

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

Parameters

  • dev – Pointer to the device structure for the driver instance.

  • channel – Numeric identification of the channel where the transfer was being processed

  • stat – a non-NULL dma_status object for storing DMA status

Returns

  • non-negative – if successful.

  • Negative – errno code if failure.

static inline uint32_t dma_width_index(uint32_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)

Returns

common – DMA index to be placed into registers.

static inline uint32_t dma_burst_index(uint32_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

Returns

common – DMA index to be placed into registers.

struct dma_block_config
#include <dma.h>

DMA block configuration structure.

Parameters

  • 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.

Parameters

  • dma_slot – [ 0 : 6 ] - which peripheral and direction (HW specific)

  • channel_direction – [ 7 : 9 ] - 000-memory to memory, 001-memory to peripheral, 010-peripheral to memory, 011-peripheral to peripheral, …

  • complete_callback_en – [ 10 ] - 0-callback invoked at completion only 1-callback invoked at completion of each block

  • error_callback_en – [ 11 ] - 0-error callback enabled 1-error callback disabled

  • source_handshake – [ 12 ] - 0-HW, 1-SW

  • dest_handshake – [ 13 ] - 0-HW, 1-SW

  • channel_priority – [ 14 : 17 ] - DMA channel priority

  • source_chaining_en – [ 18 ] - enable/disable source block chaining 0-disable, 1-enable

  • dest_chaining_en – [ 19 ] - enable/disable destination block chaining. 0-disable, 1-enable

  • linked_channel – [ 20 : 26 ] - after channel count exhaust will initiate a channel service request at this channel

  • reserved – [ 27 : 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.

  • user_data – private data from DMA client.

  • dma_callback – see dma_callback_t for details

struct dma_status
#include <dma.h>

DMA runtime status structure

busy - is current DMA transfer busy or idle dir - DMA transfer direction pending_length - data length pending to be transferred in bytes or platform dependent.

struct dma_context
#include <dma.h>

DMA context structure Note: the dma_context shall be the first member of DMA client driver Data, got by dev->data

magic - magic code to identify the context dma_channels - dma channels atomic - driver atomic_t pointer