Zephyr API Documentation 4.0.0-rc2
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
dma.h
Go to the documentation of this file.
1
7/*
8 * Copyright (c) 2016 Intel Corporation
9 *
10 * SPDX-License-Identifier: Apache-2.0
11 */
12
13#ifndef ZEPHYR_INCLUDE_DRIVERS_DMA_H_
14#define ZEPHYR_INCLUDE_DRIVERS_DMA_H_
15
16#include <zephyr/kernel.h>
17#include <zephyr/device.h>
18
19#ifdef __cplusplus
20extern "C" {
21#endif
22
23
66
80
85 DMA_CHANNEL_NORMAL, /* normal DMA channel */
86 DMA_CHANNEL_PERIODIC, /* can be triggered by periodic sources */
87};
88
98
166
168#define DMA_STATUS_COMPLETE 0
170#define DMA_STATUS_BLOCK 1
171
190typedef void (*dma_callback_t)(const struct device *dev, void *user_data,
191 uint32_t channel, int status);
192
271
291
305
307#define DMA_MAGIC 0x47494749
308
315typedef int (*dma_api_config)(const struct device *dev, uint32_t channel,
316 struct dma_config *config);
317
318#ifdef CONFIG_DMA_64BIT
319typedef int (*dma_api_reload)(const struct device *dev, uint32_t channel,
320 uint64_t src, uint64_t dst, size_t size);
321#else
322typedef int (*dma_api_reload)(const struct device *dev, uint32_t channel,
323 uint32_t src, uint32_t dst, size_t size);
324#endif
325
326typedef int (*dma_api_start)(const struct device *dev, uint32_t channel);
327
328typedef int (*dma_api_stop)(const struct device *dev, uint32_t channel);
329
330typedef int (*dma_api_suspend)(const struct device *dev, uint32_t channel);
331
332typedef int (*dma_api_resume)(const struct device *dev, uint32_t channel);
333
334typedef int (*dma_api_get_status)(const struct device *dev, uint32_t channel,
335 struct dma_status *status);
336
337typedef int (*dma_api_get_attribute)(const struct device *dev, uint32_t type, uint32_t *value);
338
352typedef bool (*dma_api_chan_filter)(const struct device *dev,
353 int channel, void *filter_param);
354
355__subsystem struct dma_driver_api {
356 dma_api_config config;
357 dma_api_reload reload;
358 dma_api_start start;
359 dma_api_stop stop;
360 dma_api_suspend suspend;
361 dma_api_resume resume;
362 dma_api_get_status get_status;
363 dma_api_get_attribute get_attribute;
364 dma_api_chan_filter chan_filter;
365};
381static inline int dma_config(const struct device *dev, uint32_t channel,
382 struct dma_config *config)
383{
384 const struct dma_driver_api *api =
385 (const struct dma_driver_api *)dev->api;
386
387 return api->config(dev, channel, config);
388}
389
403#ifdef CONFIG_DMA_64BIT
404static inline int dma_reload(const struct device *dev, uint32_t channel,
405 uint64_t src, uint64_t dst, size_t size)
406#else
407static inline int dma_reload(const struct device *dev, uint32_t channel,
408 uint32_t src, uint32_t dst, size_t size)
409#endif
410{
411 const struct dma_driver_api *api =
412 (const struct dma_driver_api *)dev->api;
413
414 if (api->reload) {
415 return api->reload(dev, channel, src, dst, size);
416 }
417
418 return -ENOSYS;
419}
420
440__syscall int dma_start(const struct device *dev, uint32_t channel);
441
442static inline int z_impl_dma_start(const struct device *dev, uint32_t channel)
443{
444 const struct dma_driver_api *api =
445 (const struct dma_driver_api *)dev->api;
446
447 return api->start(dev, channel);
448}
449
468__syscall int dma_stop(const struct device *dev, uint32_t channel);
469
470static inline int z_impl_dma_stop(const struct device *dev, uint32_t channel)
471{
472 const struct dma_driver_api *api =
473 (const struct dma_driver_api *)dev->api;
474
475 return api->stop(dev, channel);
476}
477
478
495__syscall int dma_suspend(const struct device *dev, uint32_t channel);
496
497static inline int z_impl_dma_suspend(const struct device *dev, uint32_t channel)
498{
499 const struct dma_driver_api *api = (const struct dma_driver_api *)dev->api;
500
501 if (api->suspend == NULL) {
502 return -ENOSYS;
503 }
504 return api->suspend(dev, channel);
505}
506
523__syscall int dma_resume(const struct device *dev, uint32_t channel);
524
525static inline int z_impl_dma_resume(const struct device *dev, uint32_t channel)
526{
527 const struct dma_driver_api *api = (const struct dma_driver_api *)dev->api;
528
529 if (api->resume == NULL) {
530 return -ENOSYS;
531 }
532 return api->resume(dev, channel);
533}
534
549__syscall int dma_request_channel(const struct device *dev,
550 void *filter_param);
551
552static inline int z_impl_dma_request_channel(const struct device *dev,
553 void *filter_param)
554{
555 int i = 0;
556 int channel = -EINVAL;
557 const struct dma_driver_api *api =
558 (const struct dma_driver_api *)dev->api;
559 /* dma_context shall be the first one in dev data */
560 struct dma_context *dma_ctx = (struct dma_context *)dev->data;
561
562 if (dma_ctx->magic != DMA_MAGIC) {
563 return channel;
564 }
565
566 for (i = 0; i < dma_ctx->dma_channels; i++) {
567 if (!atomic_test_and_set_bit(dma_ctx->atomic, i)) {
568 if (api->chan_filter &&
569 !api->chan_filter(dev, i, filter_param)) {
570 atomic_clear_bit(dma_ctx->atomic, i);
571 continue;
572 }
573 channel = i;
574 break;
575 }
576 }
577
578 return channel;
579}
580
592__syscall void dma_release_channel(const struct device *dev,
593 uint32_t channel);
594
595static inline void z_impl_dma_release_channel(const struct device *dev,
596 uint32_t channel)
597{
598 struct dma_context *dma_ctx = (struct dma_context *)dev->data;
599
600 if (dma_ctx->magic != DMA_MAGIC) {
601 return;
602 }
603
604 if ((int)channel < dma_ctx->dma_channels) {
605 atomic_clear_bit(dma_ctx->atomic, channel);
606 }
607
608}
609
622__syscall int dma_chan_filter(const struct device *dev,
623 int channel, void *filter_param);
624
625static inline int z_impl_dma_chan_filter(const struct device *dev,
626 int channel, void *filter_param)
627{
628 const struct dma_driver_api *api =
629 (const struct dma_driver_api *)dev->api;
630
631 if (api->chan_filter) {
632 return api->chan_filter(dev, channel, filter_param);
633 }
634
635 return -ENOSYS;
636}
637
654static inline int dma_get_status(const struct device *dev, uint32_t channel,
655 struct dma_status *stat)
656{
657 const struct dma_driver_api *api =
658 (const struct dma_driver_api *)dev->api;
659
660 if (api->get_status) {
661 return api->get_status(dev, channel, stat);
662 }
663
664 return -ENOSYS;
665}
666
684static inline int dma_get_attribute(const struct device *dev, uint32_t type, uint32_t *value)
685{
686 const struct dma_driver_api *api = (const struct dma_driver_api *)dev->api;
687
688 if (api->get_attribute) {
689 return api->get_attribute(dev, type, value);
690 }
691
692 return -ENOSYS;
693}
694
709{
710 /* Check boundaries (max supported width is 32 Bytes) */
711 if (size < 1 || size > 32) {
712 return 0; /* Zero is the default (8 Bytes) */
713 }
714
715 /* Ensure size is a power of 2 */
716 if (!is_power_of_two(size)) {
717 return 0; /* Zero is the default (8 Bytes) */
718 }
719
720 /* Convert to bit pattern for writing to a register */
721 return find_msb_set(size);
722}
723
738{
739 /* Check boundaries (max supported burst length is 256) */
740 if (burst < 1 || burst > 256) {
741 return 0; /* Zero is the default (1 burst length) */
742 }
743
744 /* Ensure burst is a power of 2 */
745 if (!(burst & (burst - 1))) {
746 return 0; /* Zero is the default (1 burst length) */
747 }
748
749 /* Convert to bit pattern for writing to a register */
750 return find_msb_set(burst);
751}
752
762#define DMA_BUF_ADDR_ALIGNMENT(node) DT_PROP(node, dma_buf_addr_alignment)
763
773#define DMA_BUF_SIZE_ALIGNMENT(node) DT_PROP(node, dma_buf_size_alignment)
774
781#define DMA_COPY_ALIGNMENT(node) DT_PROP(node, dma_copy_alignment)
782
787#ifdef __cplusplus
788}
789#endif
790
791#include <zephyr/syscalls/dma.h>
792
793#endif /* ZEPHYR_INCLUDE_DRIVERS_DMA_H_ */
long atomic_t
Definition atomic_types.h:15
static ALWAYS_INLINE unsigned int find_msb_set(uint32_t op)
find most significant bit set in a 32-bit word
Definition ffs.h:31
static void atomic_clear_bit(atomic_t *target, int bit)
Atomically clear a bit.
Definition atomic.h:191
static bool atomic_test_and_set_bit(atomic_t *target, int bit)
Atomically set a bit and test it.
Definition atomic.h:170
dma_attribute_type
DMA attributes.
Definition dma.h:92
static int dma_get_status(const struct device *dev, uint32_t channel, struct dma_status *stat)
get current runtime status of DMA transfer
Definition dma.h:654
int dma_stop(const struct device *dev, uint32_t channel)
Stops the DMA transfer and disables the channel.
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.
Definition dma.h:407
static int dma_get_attribute(const struct device *dev, uint32_t type, uint32_t *value)
get attribute of a dma controller
Definition dma.h:684
int dma_suspend(const struct device *dev, uint32_t channel)
Suspend a DMA channel transfer.
static int dma_config(const struct device *dev, uint32_t channel, struct dma_config *config)
Configure individual channel for DMA transfer.
Definition dma.h:381
int dma_chan_filter(const struct device *dev, int channel, void *filter_param)
DMA channel filter.
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_callback_t)(const struct device *dev, void *user_data, uint32_t channel, int status)
Callback function for DMA transfer completion.
Definition dma.h:190
static uint32_t dma_burst_index(uint32_t burst)
Look-up generic burst index to be used in registers.
Definition dma.h:737
void dma_release_channel(const struct device *dev, uint32_t channel)
release 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.
static uint32_t dma_width_index(uint32_t size)
Look-up generic width index to be used in registers.
Definition dma.h:708
dma_channel_filter
DMA channel attributes.
Definition dma.h:84
#define DMA_MAGIC
Magic code to identify context content.
Definition dma.h:307
dma_channel_direction
DMA channel direction.
Definition dma.h:36
dma_addr_adj
DMA address adjustment.
Definition dma.h:72
@ DMA_ATTR_BUFFER_ADDRESS_ALIGNMENT
Definition dma.h:93
@ DMA_ATTR_COPY_ALIGNMENT
Definition dma.h:95
@ DMA_ATTR_BUFFER_SIZE_ALIGNMENT
Definition dma.h:94
@ DMA_ATTR_MAX_BLOCK_COUNT
Definition dma.h:96
@ DMA_CHANNEL_NORMAL
Definition dma.h:85
@ DMA_CHANNEL_PERIODIC
Definition dma.h:86
@ DMA_CHANNEL_DIRECTION_PRIV_START
This and higher values are dma controller or soc specific.
Definition dma.h:59
@ MEMORY_TO_PERIPHERAL
Memory to peripheral.
Definition dma.h:40
@ MEMORY_TO_MEMORY
Memory to memory.
Definition dma.h:38
@ PERIPHERAL_TO_MEMORY
Peripheral to memory.
Definition dma.h:42
@ MEMORY_TO_HOST
Memory to host.
Definition dma.h:48
@ HOST_TO_MEMORY
Host to memory.
Definition dma.h:46
@ DMA_CHANNEL_DIRECTION_MAX
Maximum allowed value (3 bit field!)
Definition dma.h:64
@ PERIPHERAL_TO_PERIPHERAL
Peripheral to peripheral.
Definition dma.h:44
@ DMA_CHANNEL_DIRECTION_COMMON_COUNT
Number of all common channel directions.
Definition dma.h:53
@ DMA_ADDR_ADJ_DECREMENT
Decrement the address.
Definition dma.h:76
@ DMA_ADDR_ADJ_INCREMENT
Increment the address.
Definition dma.h:74
@ DMA_ADDR_ADJ_NO_CHANGE
No change the address.
Definition dma.h:78
static bool is_power_of_two(unsigned int x)
Is x a power of two?
Definition util.h:438
#define EINVAL
Invalid argument.
Definition errno.h:60
#define ENOSYS
Function not implemented.
Definition errno.h:82
Public kernel APIs.
#define bool
Definition stdbool.h:13
__UINT32_TYPE__ uint32_t
Definition stdint.h:90
__INT32_TYPE__ int32_t
Definition stdint.h:74
__UINT64_TYPE__ uint64_t
Definition stdint.h:91
__UINT16_TYPE__ uint16_t
Definition stdint.h:89
Runtime device structure (in ROM) per driver instance.
Definition device.h:412
void * data
Address of the device instance private data.
Definition device.h:422
const void * api
Address of the API structure exposed by the device instance.
Definition device.h:418
DMA block configuration structure.
Definition dma.h:106
uint32_t dest_scatter_interval
Address adjustment at scatter boundary.
Definition dma.h:121
uint32_t source_gather_interval
Address adjustment at gather boundary.
Definition dma.h:119
uint32_t block_size
Number of bytes to be transferred for this block.
Definition dma.h:127
uint16_t source_reload_en
Reload source address at the end of block transfer.
Definition dma.h:151
uint16_t dest_scatter_en
Enable destination scattering when set to 1.
Definition dma.h:133
uint16_t dest_reload_en
Reload destination address at the end of block transfer.
Definition dma.h:153
uint16_t fifo_mode_control
FIFO fill before starting transfer, HW specific meaning.
Definition dma.h:155
uint16_t source_gather_count
Continuous transfer count between gather boundaries.
Definition dma.h:125
uint16_t source_addr_adj
Source address adjustment option.
Definition dma.h:141
struct dma_block_config * next_block
Pointer to next block in a transfer list.
Definition dma.h:129
uint32_t dest_address
block starting address at destination
Definition dma.h:116
uint32_t source_address
block starting address at source
Definition dma.h:114
uint16_t source_gather_en
Enable source gathering when set to 1.
Definition dma.h:131
uint16_t dest_addr_adj
Destination address adjustment.
Definition dma.h:149
uint16_t dest_scatter_count
Continuous transfer count between scatter boundaries.
Definition dma.h:123
uint16_t flow_control_mode
Transfer flow control mode.
Definition dma.h:162
DMA configuration structure.
Definition dma.h:197
uint32_t channel_priority
Channel priority for arbitration, HW specific.
Definition dma.h:243
uint32_t source_handshake
Source handshake, HW specific.
Definition dma.h:232
uint32_t complete_callback_en
Completion callback enable.
Definition dma.h:218
uint32_t error_callback_dis
Error callback disable.
Definition dma.h:225
void * user_data
Optional attached user data for callbacks.
Definition dma.h:267
dma_callback_t dma_callback
Optional callback for completion and error events.
Definition dma.h:269
uint32_t source_chaining_en
Source chaining enable, HW specific.
Definition dma.h:245
uint32_t dest_chaining_en
Destination chaining enable, HW specific.
Definition dma.h:247
uint32_t dma_slot
Which peripheral and direction, HW specific.
Definition dma.h:199
uint32_t channel_direction
Direction the transfers are occurring.
Definition dma.h:211
uint32_t source_data_size
Width of source data (in bytes)
Definition dma.h:255
uint32_t dest_burst_length
Destination burst length in bytes.
Definition dma.h:261
struct dma_block_config * head_block
Pointer to the first block in the transfer list.
Definition dma.h:265
uint32_t linked_channel
Linked channel, HW specific.
Definition dma.h:249
uint32_t source_burst_length
Source burst length in bytes.
Definition dma.h:259
uint32_t block_count
Number of blocks in transfer list.
Definition dma.h:263
uint32_t dest_data_size
Width of destination data (in bytes)
Definition dma.h:257
uint32_t dest_handshake
Destination handshake, HW specific.
Definition dma.h:239
uint32_t cyclic
Cyclic transfer list, HW specific.
Definition dma.h:251
DMA context structure Note: the dma_context shall be the first member of DMA client driver Data,...
Definition dma.h:297
int32_t magic
magic code to identify the context
Definition dma.h:299
atomic_t * atomic
atomic holding bit flags for each channel to mark as used/unused
Definition dma.h:303
int dma_channels
number of dma channels
Definition dma.h:301
DMA runtime status structure.
Definition dma.h:275
uint32_t free
Available buffers space, HW specific.
Definition dma.h:283
uint32_t pending_length
Pending length to be transferred in bytes, HW specific.
Definition dma.h:281
bool busy
Is the current DMA transfer busy or idle.
Definition dma.h:277
uint64_t total_copied
Total copied, HW specific.
Definition dma.h:289
uint32_t write_position
Write position in circular DMA buffer, HW specific.
Definition dma.h:285
enum dma_channel_direction dir
Direction for the transfer.
Definition dma.h:279
uint32_t read_position
Read position in circular DMA buffer, HW specific.
Definition dma.h:287
Definition stat.h:57