Zephyr API Documentation 4.0.99
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
366typedef void (*dma_api_chan_release)(const struct device *dev,
367 uint32_t channel);
368
369__subsystem struct dma_driver_api {
370 dma_api_config config;
371 dma_api_reload reload;
372 dma_api_start start;
373 dma_api_stop stop;
374 dma_api_suspend suspend;
375 dma_api_resume resume;
376 dma_api_get_status get_status;
377 dma_api_get_attribute get_attribute;
378 dma_api_chan_filter chan_filter;
379 dma_api_chan_release chan_release;
380};
396static inline int dma_config(const struct device *dev, uint32_t channel,
397 struct dma_config *config)
398{
399 const struct dma_driver_api *api =
400 (const struct dma_driver_api *)dev->api;
401
402 return api->config(dev, channel, config);
403}
404
418#ifdef CONFIG_DMA_64BIT
419static inline int dma_reload(const struct device *dev, uint32_t channel,
420 uint64_t src, uint64_t dst, size_t size)
421#else
422static inline int dma_reload(const struct device *dev, uint32_t channel,
423 uint32_t src, uint32_t dst, size_t size)
424#endif
425{
426 const struct dma_driver_api *api =
427 (const struct dma_driver_api *)dev->api;
428
429 if (api->reload) {
430 return api->reload(dev, channel, src, dst, size);
431 }
432
433 return -ENOSYS;
434}
435
455__syscall int dma_start(const struct device *dev, uint32_t channel);
456
457static inline int z_impl_dma_start(const struct device *dev, uint32_t channel)
458{
459 const struct dma_driver_api *api =
460 (const struct dma_driver_api *)dev->api;
461
462 return api->start(dev, channel);
463}
464
483__syscall int dma_stop(const struct device *dev, uint32_t channel);
484
485static inline int z_impl_dma_stop(const struct device *dev, uint32_t channel)
486{
487 const struct dma_driver_api *api =
488 (const struct dma_driver_api *)dev->api;
489
490 return api->stop(dev, channel);
491}
492
493
510__syscall int dma_suspend(const struct device *dev, uint32_t channel);
511
512static inline int z_impl_dma_suspend(const struct device *dev, uint32_t channel)
513{
514 const struct dma_driver_api *api = (const struct dma_driver_api *)dev->api;
515
516 if (api->suspend == NULL) {
517 return -ENOSYS;
518 }
519 return api->suspend(dev, channel);
520}
521
538__syscall int dma_resume(const struct device *dev, uint32_t channel);
539
540static inline int z_impl_dma_resume(const struct device *dev, uint32_t channel)
541{
542 const struct dma_driver_api *api = (const struct dma_driver_api *)dev->api;
543
544 if (api->resume == NULL) {
545 return -ENOSYS;
546 }
547 return api->resume(dev, channel);
548}
549
566__syscall int dma_request_channel(const struct device *dev,
567 void *filter_param);
568
569static inline int z_impl_dma_request_channel(const struct device *dev,
570 void *filter_param)
571{
572 int i = 0;
573 int channel = -EINVAL;
574 const struct dma_driver_api *api =
575 (const struct dma_driver_api *)dev->api;
576 /* dma_context shall be the first one in dev data */
577 struct dma_context *dma_ctx = (struct dma_context *)dev->data;
578
579 if (dma_ctx->magic != DMA_MAGIC) {
580 return channel;
581 }
582
583 for (i = 0; i < dma_ctx->dma_channels; i++) {
584 if (!atomic_test_and_set_bit(dma_ctx->atomic, i)) {
585 if (api->chan_filter &&
586 !api->chan_filter(dev, i, filter_param)) {
587 atomic_clear_bit(dma_ctx->atomic, i);
588 continue;
589 }
590 channel = i;
591 break;
592 }
593 }
594
595 return channel;
596}
597
611__syscall void dma_release_channel(const struct device *dev,
612 uint32_t channel);
613
614static inline void z_impl_dma_release_channel(const struct device *dev,
615 uint32_t channel)
616{
617 const struct dma_driver_api *api =
618 (const struct dma_driver_api *)dev->api;
619 struct dma_context *dma_ctx = (struct dma_context *)dev->data;
620
621 if (dma_ctx->magic != DMA_MAGIC) {
622 return;
623 }
624
625 if ((int)channel < dma_ctx->dma_channels) {
626 if (api->chan_release) {
627 api->chan_release(dev, channel);
628 }
629
630 atomic_clear_bit(dma_ctx->atomic, channel);
631 }
632
633}
634
647__syscall int dma_chan_filter(const struct device *dev,
648 int channel, void *filter_param);
649
650static inline int z_impl_dma_chan_filter(const struct device *dev,
651 int channel, void *filter_param)
652{
653 const struct dma_driver_api *api =
654 (const struct dma_driver_api *)dev->api;
655
656 if (api->chan_filter) {
657 return api->chan_filter(dev, channel, filter_param);
658 }
659
660 return -ENOSYS;
661}
662
679static inline int dma_get_status(const struct device *dev, uint32_t channel,
680 struct dma_status *stat)
681{
682 const struct dma_driver_api *api =
683 (const struct dma_driver_api *)dev->api;
684
685 if (api->get_status) {
686 return api->get_status(dev, channel, stat);
687 }
688
689 return -ENOSYS;
690}
691
709static inline int dma_get_attribute(const struct device *dev, uint32_t type, uint32_t *value)
710{
711 const struct dma_driver_api *api = (const struct dma_driver_api *)dev->api;
712
713 if (api->get_attribute) {
714 return api->get_attribute(dev, type, value);
715 }
716
717 return -ENOSYS;
718}
719
734{
735 /* Check boundaries (max supported width is 32 Bytes) */
736 if (size < 1 || size > 32) {
737 return 0; /* Zero is the default (8 Bytes) */
738 }
739
740 /* Ensure size is a power of 2 */
741 if (!is_power_of_two(size)) {
742 return 0; /* Zero is the default (8 Bytes) */
743 }
744
745 /* Convert to bit pattern for writing to a register */
746 return find_msb_set(size);
747}
748
763{
764 /* Check boundaries (max supported burst length is 256) */
765 if (burst < 1 || burst > 256) {
766 return 0; /* Zero is the default (1 burst length) */
767 }
768
769 /* Ensure burst is a power of 2 */
770 if (!(burst & (burst - 1))) {
771 return 0; /* Zero is the default (1 burst length) */
772 }
773
774 /* Convert to bit pattern for writing to a register */
775 return find_msb_set(burst);
776}
777
787#define DMA_BUF_ADDR_ALIGNMENT(node) DT_PROP(node, dma_buf_addr_alignment)
788
798#define DMA_BUF_SIZE_ALIGNMENT(node) DT_PROP(node, dma_buf_size_alignment)
799
806#define DMA_COPY_ALIGNMENT(node) DT_PROP(node, dma_copy_alignment)
807
812#ifdef __cplusplus
813}
814#endif
815
816#include <zephyr/syscalls/dma.h>
817
818#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:679
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:422
static int dma_get_attribute(const struct device *dev, uint32_t type, uint32_t *value)
get attribute of a dma controller
Definition dma.h:709
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:396
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:762
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:733
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