DMA Interface

DMA Interface . More...

Data Structures
struct	dma_block_config
	DMA block configuration structure. More...
struct	dma_config
	DMA configuration structure. More...
struct	dma_status
	DMA runtime status structure. More...
struct	dma_context
	DMA context structure Note: the dma_context shall be the first member of DMA client driver Data, got by dev->data. More...

Macros
#define	DMA_STATUS_COMPLETE   0
	The DMA callback event has occurred at the completion of a transfer list.
#define	DMA_STATUS_BLOCK   1
	The DMA callback has occurred at the completion of a single transfer block in a transfer list.
#define	DMA_MAGIC   0x47494749
	Magic code to identify context content.
#define	DMA_BUF_ADDR_ALIGNMENT(node)
	Get the device tree property describing the buffer address alignment.
#define	DMA_BUF_SIZE_ALIGNMENT(node)
	Get the device tree property describing the buffer size alignment.
#define	DMA_COPY_ALIGNMENT(node)
	Get the device tree property describing the 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.

Enumerations
enum	dma_channel_direction {   MEMORY_TO_MEMORY = 0x0 , MEMORY_TO_PERIPHERAL , PERIPHERAL_TO_MEMORY , PERIPHERAL_TO_PERIPHERAL ,   HOST_TO_MEMORY , MEMORY_TO_HOST , DMA_CHANNEL_DIRECTION_COMMON_COUNT , DMA_CHANNEL_DIRECTION_PRIV_START = DMA_CHANNEL_DIRECTION_COMMON_COUNT ,   DMA_CHANNEL_DIRECTION_MAX = 0x7 }
	DMA channel direction. More...
enum	dma_addr_adj { DMA_ADDR_ADJ_INCREMENT , DMA_ADDR_ADJ_DECREMENT , DMA_ADDR_ADJ_NO_CHANGE }
	DMA address adjustment. More...
enum	dma_channel_filter { DMA_CHANNEL_NORMAL , DMA_CHANNEL_PERIODIC }
	DMA channel attributes. More...
enum	dma_attribute_type { DMA_ATTR_BUFFER_ADDRESS_ALIGNMENT , DMA_ATTR_BUFFER_SIZE_ALIGNMENT , DMA_ATTR_COPY_ALIGNMENT , DMA_ATTR_MAX_BLOCK_COUNT }
	DMA attributes. More...

Functions
static int	dma_config (const struct device *dev, uint32_t channel, struct dma_config *config)
	Configure individual channel for DMA transfer.
static 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.
int	dma_start (const struct device *dev, uint32_t channel)
	Enables DMA channel and starts the transfer, the channel must be configured beforehand.
int	dma_stop (const struct device *dev, uint32_t channel)
	Stops the DMA transfer and disables the channel.
int	dma_suspend (const struct device *dev, uint32_t channel)
	Suspend a DMA channel transfer.
int	dma_resume (const struct device *dev, uint32_t channel)
	Resume a DMA channel transfer.
int	dma_request_channel (const struct device *dev, void *filter_param)
	request DMA channel.
void	dma_release_channel (const struct device *dev, uint32_t channel)
	release DMA channel.
int	dma_chan_filter (const struct device *dev, int channel, void *filter_param)
	DMA channel filter.
static int	dma_get_status (const struct device *dev, uint32_t channel, struct dma_status *stat)
	get current runtime status of DMA transfer
static int	dma_get_attribute (const struct device *dev, uint32_t type, uint32_t *value)
	get attribute of a dma controller
static uint32_t	dma_width_index (uint32_t size)
	Look-up generic width index to be used in registers.
static uint32_t	dma_burst_index (uint32_t burst)
	Look-up generic burst index to be used in registers.

Detailed Description

DMA Interface .

Since

1.5

Version

1.0.0

Macro Definition Documentation

DMA_BUF_ADDR_ALIGNMENT

#define DMA_BUF_ADDR_ALIGNMENT

(

node

)

#include <zephyr/drivers/dma.h>

Value:

DT_PROP(node, dma_buf_addr_alignment)

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

#define DMA_BUF_SIZE_ALIGNMENT

(

node

)

#include <zephyr/drivers/dma.h>

Value:

DT_PROP(node, dma_buf_size_alignment)

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

#define DMA_COPY_ALIGNMENT

(

node

)

#include <zephyr/drivers/dma.h>

Value:

DT_PROP(node, dma_copy_alignment)

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

DMA_MAGIC

#define DMA_MAGIC   0x47494749

#include <zephyr/drivers/dma.h>

Magic code to identify context content.

DMA_STATUS_BLOCK

#define DMA_STATUS_BLOCK   1

#include <zephyr/drivers/dma.h>

The DMA callback has occurred at the completion of a single transfer block in a transfer list.

DMA_STATUS_COMPLETE

#define DMA_STATUS_COMPLETE   0

#include <zephyr/drivers/dma.h>

The DMA callback event has occurred at the completion of a transfer list.

Typedef Documentation

dma_callback_t

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

#include <zephyr/drivers/dma.h>

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

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	Status of the transfer DMA_STATUS_COMPLETE buffer fully consumed DMA_STATUS_BLOCK buffer consumption reached a configured block or water mark A negative errno otherwise

Enumeration Type Documentation

dma_addr_adj

enum dma_addr_adj

#include <zephyr/drivers/dma.h>

DMA address adjustment.

Valid values for source_addr_adj and dest_addr_adj

Enumerator
DMA_ADDR_ADJ_INCREMENT	Increment the address.
DMA_ADDR_ADJ_DECREMENT	Decrement the address.
DMA_ADDR_ADJ_NO_CHANGE	No change the address.

dma_attribute_type

enum dma_attribute_type

#include <zephyr/drivers/dma.h>

DMA attributes.

Enumerator
DMA_ATTR_BUFFER_ADDRESS_ALIGNMENT
DMA_ATTR_BUFFER_SIZE_ALIGNMENT
DMA_ATTR_COPY_ALIGNMENT
DMA_ATTR_MAX_BLOCK_COUNT

dma_channel_direction

enum dma_channel_direction

#include <zephyr/drivers/dma.h>

DMA channel direction.

Enumerator
MEMORY_TO_MEMORY	Memory to memory.
MEMORY_TO_PERIPHERAL	Memory to peripheral.
PERIPHERAL_TO_MEMORY	Peripheral to memory.
PERIPHERAL_TO_PERIPHERAL	Peripheral to peripheral.
HOST_TO_MEMORY	Host to memory.
MEMORY_TO_HOST	Memory to host.
DMA_CHANNEL_DIRECTION_COMMON_COUNT	Number of all common channel directions.
DMA_CHANNEL_DIRECTION_PRIV_START	This and higher values are dma controller or soc specific. Refer to the specified dma driver header file.
DMA_CHANNEL_DIRECTION_MAX	Maximum allowed value (3 bit field!)

dma_channel_filter

enum dma_channel_filter

#include <zephyr/drivers/dma.h>

DMA channel attributes.

Enumerator
DMA_CHANNEL_NORMAL
DMA_CHANNEL_PERIODIC

Function Documentation

dma_burst_index()

static uint32_t dma_burst_index ( uint32_t burst )

inlinestatic

#include <zephyr/drivers/dma.h>

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.

dma_chan_filter()

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

#include <zephyr/drivers/dma.h>

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

dma_config()

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

inlinestatic

#include <zephyr/drivers/dma.h>

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.

dma_get_attribute()

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

inlinestaticisr-ok

#include <zephyr/drivers/dma.h>

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.

Function properties (list may not be complete)

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.

dma_get_status()

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

inlinestaticisr-ok

#include <zephyr/drivers/dma.h>

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.

Function properties (list may not be complete)

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.

dma_release_channel()

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

#include <zephyr/drivers/dma.h>

release DMA channel.

release DMA channel resources

Note

It is safe to use this function in contexts where blocking is not allowed, e.g. ISR, provided the implementation of the release function does not block.

Parameters

dev	Pointer to the device structure for the driver instance.
channel	channel number

dma_reload()

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

inlinestatic

#include <zephyr/drivers/dma.h>

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.

dma_request_channel()

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

#include <zephyr/drivers/dma.h>

request DMA channel.

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

Note

It is safe to use this function in contexts where blocking is not allowed, e.g. ISR, provided the implementation of the filter function does not block.

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.

dma_resume()

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

isr-ok

#include <zephyr/drivers/dma.h>

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.

Function properties (list may not be complete)

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.

dma_start()

int dma_start ( const struct device * dev, uint32_t channel )

isr-ok

#include <zephyr/drivers/dma.h>

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.

Function properties (list may not be complete)

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.

dma_stop()

int dma_stop ( const struct device * dev, uint32_t channel )

isr-ok

#include <zephyr/drivers/dma.h>

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.

Function properties (list may not be complete)

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.

dma_suspend()

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

isr-ok

#include <zephyr/drivers/dma.h>

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.

Function properties (list may not be complete)

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.

dma_width_index()

static uint32_t dma_width_index ( uint32_t size )

inlinestatic

#include <zephyr/drivers/dma.h>

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.