Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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)
#define DT_PROP(node_id, prop)
Get a devicetree property value.
Definition devicetree.h:749

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
nodeNode 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
nodeNode 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
nodeNode 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
devPointer to the DMA device calling the callback.
user_dataA pointer to some user data or NULL
channelThe channel number
statusStatus 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

#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

#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

#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

#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
burstnumber of bytes to be sent in a single burst
Return values
commonDMA 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
devPointer to the device structure for the driver instance.
channelchannel number
filter_paramfilter attribute
Return values
Negativeerrno 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
devPointer to the device structure for the driver instance.
channelNumeric identification of the channel to configure
configData structure containing the intended configuration for the selected channel
Return values
0if successful.
Negativeerrno code if failure.

◆ dma_get_attribute()

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

#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)
isr-ok
Parameters
devPointer to the device structure for the driver instance.
typeNumeric identification of the attribute
valueA non-NULL pointer to the variable where the read value is to be placed
Return values
non-negativeif successful.
Negativeerrno code if failure.

◆ dma_get_status()

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

#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)
isr-ok
Parameters
devPointer to the device structure for the driver instance.
channelNumeric identification of the channel where the transfer was being processed
stata non-NULL dma_status object for storing DMA status
Return values
non-negativeif successful.
Negativeerrno 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

Function properties (list may not be complete)
isr-ok
Parameters
devPointer to the device structure for the driver instance.
channelchannel 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
devPointer to the device structure for the driver instance.
channelNumeric identification of the channel to configure selected channel
srcsource address for the DMA transfer
dstdestination address for the DMA transfer
sizesize of DMA transfer
Return values
0if successful.
Negativeerrno 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.

Function properties (list may not be complete)
isr-ok
Parameters
devPointer to the device structure for the driver instance.
filter_paramfilter function parameter
Return values
dmachannel if successful.
Negativeerrno code if failure.

◆ dma_resume()

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

#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)
isr-ok
Parameters
devPointer to the device structure for the driver instance.
channelNumeric identification of the channel to resume
Return values
0If successful.
-ENOSYSIf not implemented
-EINVALIf invalid channel id or state.
-errnoOther negative errno code failure.

◆ dma_start()

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

#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)
isr-ok
Parameters
devPointer to the device structure for the driver instance.
channelNumeric identification of the channel where the transfer will be processed
Return values
0if successful.
Negativeerrno code if failure.

◆ dma_stop()

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

#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)
isr-ok
Parameters
devPointer to the device structure for the driver instance.
channelNumeric identification of the channel where the transfer was being processed
Return values
0if successful.
Negativeerrno code if failure.

◆ dma_suspend()

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

#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)
isr-ok
Parameters
devPointer to the device structure for the driver instance.
channelNumeric identification of the channel to suspend
Return values
0If successful.
-ENOSYSIf not implemented.
-EINVALIf invalid channel id or state.
-errnoOther 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
sizewidth of bus (in bytes)
Return values
commonDMA index to be placed into registers.