Direct Memory Access (DMA)

Overview

API Reference

group dma_interface

DMA Interface.

Defines

DMA_STATUS_COMPLETE

DMA_STATUS_BLOCK

DMA_MAGIC

DMA_BUF_ADDR_ALIGNMENT(node)

Get the device tree property describing the buffer address alignment.

Useful when statically defining or allocating buffers for DMA usage where memory alignment often matters.

Parameters:

node – Node identifier, e.g. DT_NODELABEL(dma_0)

Returns:

alignment Memory byte alignment required for DMA buffers

DMA_BUF_SIZE_ALIGNMENT(node)

Get the device tree property describing the buffer size alignment.

Useful when statically defining or allocating buffers for DMA usage where memory alignment often matters.

Parameters:

node – Node identifier, e.g. DT_NODELABEL(dma_0)

Returns:

alignment Memory byte alignment required for DMA buffers

DMA_COPY_ALIGNMENT(node)

Get the device tree property describing the minimal chunk of data possible to be copied.

Parameters:

node – Node identifier, e.g. DT_NODELABEL(dma_0)

Returns:

minimal Minimal chunk of data possible to be copied

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 or block completion, or when an error happens. In circular mode, status indicates that the DMA device has reached either the end of the buffer (DMA_STATUS_COMPLETE) or a water mark (DMA_STATUS_BLOCK).

Param dev:

Pointer to the DMA device calling the callback.

Param user_data:

A pointer to some user data or NULL

Param channel:

The channel number

Param status:

- 0-DMA_STATUS_COMPLETE buffer fully consumed

1-DMA_STATUS_BLOCK buffer consumption reached a configured block or water mark
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

enumerator HOST_TO_MEMORY

enumerator MEMORY_TO_HOST

enumerator DMA_CHANNEL_DIRECTION_COMMON_COUNT: Number of all common channel directions.

enumerator DMA_CHANNEL_DIRECTION_PRIV_START = DMA_CHANNEL_DIRECTION_COMMON_COUNT 

This and higher values are dma controller or soc specific.

Refer to the specified dma driver header file.

enumerator DMA_CHANNEL_DIRECTION_MAX = 0x7: Maximum allowed value (3 bit field!)

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

enum dma_attribute_type

Values:

enumerator DMA_ATTR_BUFFER_ADDRESS_ALIGNMENT

enumerator DMA_ATTR_BUFFER_SIZE_ALIGNMENT

enumerator DMA_ATTR_COPY_ALIGNMENT

enumerator DMA_ATTR_MAX_BLOCK_COUNT

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

Return values:

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

Return values:

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.

Start is allowed on channels that have already been started and must report success.

Parameters:

dev – Pointer to the device structure for the driver instance.
channel – Numeric identification of the channel where the transfer will be processed

Return values:

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.

Stop is allowed on channels that have already been stopped and must report success.

Parameters:

dev – Pointer to the device structure for the driver instance.
channel – Numeric identification of the channel where the transfer was being processed

Return values:

0 – if successful.
Negative – errno code if failure.

int dma_suspend(const struct device *dev, uint32_t channel)

Suspend a DMA channel transfer.

Implementations must check the validity of the channel state and ID passed in and return -EINVAL if either are invalid.

Parameters:

dev – Pointer to the device structure for the driver instance.
channel – Numeric identification of the channel to suspend

Return values:

0 – If successful.
-ENOSYS – If not implemented.
-EINVAL – If invalid channel id or state.
-errno – Other negative errno code failure.

int dma_resume(const struct device *dev, uint32_t channel)

Resume a DMA channel transfer.

Implementations must check the validity of the channel state and ID passed in and return -EINVAL if either are invalid.

Parameters:

dev – Pointer to the device structure for the driver instance.
channel – Numeric identification of the channel to resume

Return values:

0 – If successful.
-ENOSYS – If not implemented
-EINVAL – If invalid channel id or state.
-errno – Other negative errno code 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

Return values:

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

Return values:

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

Return values:

non-negative – if successful.
Negative – errno code if failure.

static inline int dma_get_attribute(const struct device *dev, uint32_t type, uint32_t *value)

get attribute of a dma controller

This function allows to get a device specific static or runtime attribute like required address and size alignment of a buffer. Implementations must check the validity of the type 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.
type – Numeric identification of the attribute
value – A non-NULL pointer to the variable where the read value is to be placed

Return values:

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)

Return values:

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

Return values:

common – DMA index to be placed into registers.

struct dma_block_config

#include <dma.h>

DMA block configuration structure.

Param source_address:

is block starting address at source

Param source_gather_interval:

is the address adjustment at gather boundary

Param dest_address:

is block starting address at destination

Param dest_scatter_interval:

is the address adjustment at scatter boundary

Param dest_scatter_count:

is the continuous transfer count between scatter boundaries

Param source_gather_count:

is the continuous transfer count between gather boundaries

Param block_size:

is the number of bytes to be transferred for this block.

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

Param dma_slot:: [ 0 : 7 ] - which peripheral and direction (HW specific)
Param channel_direction:: [ 8 : 10 ] - 000-memory to memory, 001-memory to peripheral, 010-peripheral to memory, 011-peripheral to peripheral, 100-host to memory 101-memory to host …
Param complete_callback_en:: [ 11 ] - 0-callback invoked at completion only 1-callback invoked at completion of each block
Param error_callback_en:: [ 12 ] - 0-error callback enabled 1-error callback disabled
Param source_handshake:: [ 13 ] - 0-HW, 1-SW
Param dest_handshake:: [ 14 ] - 0-HW, 1-SW
Param channel_priority:: [ 15 : 18 ] - DMA channel priority
Param source_chaining_en:: [ 19 ] - enable/disable source block chaining 0-disable, 1-enable
Param dest_chaining_en:: [ 20 ] - enable/disable destination block chaining. 0-disable, 1-enable
Param linked_channel:: [ 21 : 27 ] - after channel count exhaust will initiate a channel service request at this channel
Param cyclic:: [ 28 ] - enable/disable cyclic buffer 0-disable, 1-enable
Param reserved:: [ 29 : 31 ]
Param source_data_size:: [ 0 : 15 ] - width of source data (in bytes)
Param dest_data_size:: [ 16 : 31 ] - width of dest data (in bytes)
Param source_burst_length:: [ 0 : 15 ] - number of source data units
Param dest_burst_length:: [ 16 : 31 ] - number of destination data units
Param block_count:: is the number of blocks used for block chaining, this depends on availability of the DMA controller.
Param user_data:: private data from DMA client.
Param 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. free - free buffer space write_position - write position in a circular dma buffer read_position - read position in a circular dma buffer

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