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 NULLchannel
: The channel numberstatus
: 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¶
-
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!)
-
enumerator MEMORY_TO_MEMORY = 0x0¶
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 configureconfig
: Data structure containing the intended configuration for the selected channel
- Return Value
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 channelsrc
: source address for the DMA transferdst
: destination address for the DMA transfersize
: size of DMA transfer
- Return Value
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
- Return Value
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
- Return Value
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 Value
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 Value
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 Value
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 numberfilter_param
: filter attribute
- Return Value
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 processedstat
: a non-NULL dma_status object for storing DMA status
- Return Value
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 Value
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 Value
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 sourcesource_gather_interval
: is the address adjustment at gather boundarydest_address
: is block starting address at destinationdest_scatter_interval
: is the address adjustment at scatter boundarydest_scatter_count
: is the continuous transfer count between scatter boundariessource_gather_count
: is the continuous transfer count between gather boundariesblock_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, 100-host to memory 101-memory to host …complete_callback_en
: [ 10 ] - 0-callback invoked at completion only 1-callback invoked at completion of each blockerror_callback_en
: [ 11 ] - 0-error callback enabled 1-error callback disabledsource_handshake
: [ 12 ] - 0-HW, 1-SWdest_handshake
: [ 13 ] - 0-HW, 1-SWchannel_priority
: [ 14 : 17 ] - DMA channel prioritysource_chaining_en
: [ 18 ] - enable/disable source block chaining 0-disable, 1-enabledest_chaining_en
: [ 19 ] - enable/disable destination block chaining. 0-disable, 1-enablelinked_channel
: [ 20 : 26 ] - after channel count exhaust will initiate a channel service request at this channelreserved
: [ 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 unitsdest_burst_length
: [ 16 : 31 ] - number of destination data unitsblock_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
-
DMA_MAGIC¶