1.. _dma_api:
2
3Direct Memory Access (DMA)
4##########################
5
6Overview
7********
8
9Direct Memory Access (Controller) is a commonly provided type of co-processor that can typically
10offload transferring data to and from peripherals and memory.
11
12The DMA API is not a portable API and really cannot be as each DMA has unique memory requirements,
13peripheral interactions, and features. The API in effect provides a union of all useful DMA
14functionality drivers have needed in the tree. It can still be a good abstraction, with care, for
15peripheral devices for vendors where the DMA IP might be very similar but have slight variances.
16
17The DMA drivers in general do not handle cache coherency; this is left up to the developer as
18requirements vary dramatically depending on the application. See :ref:`cache_guide` for an
19overview of cache management in Zephyr.
20
21Driver Implementation Expectations
22**********************************
23
24Synchronization and Ownership
25+++++++++++++++++++++++++++++
26
27From an API point of view, a DMA channel is a single-owner object, meaning the drivers should not
28attempt to wrap a channel with kernel synchronization primitives such as mutexes or semaphores. If
29DMA channels require mutating shared registers, those register updates should be wrapped in a spin
30lock.
31
32This enables the entire API to be low-cost and callable from any call context, including ISRs where
33it may be very useful to start/stop/suspend/resume/reload a channel transfer.
34
35Transfer Descriptor Memory Management
36+++++++++++++++++++++++++++++++++++++
37
38Drivers should not attempt to use heap allocations of any kind. If object pools are needed for
39transfer descriptors then those should be setup in a way that does not break the promise of
40ISR-allowable calls. Many drivers choose to create a simple static descriptor array per channel with
41the size of the descriptor array adjustable using Kconfig.
42
43Channel State Machine Expectations
44++++++++++++++++++++++++++++++++++
45
46DMA channels should be viewed as state machines that the DMA API provides transition events for in
47the form of API calls. Every driver is expected to maintain its own channel state tracking. The busy
48state of the channel should be inspectable at any time with :c:func:`dma_get_status()`.
49
50A diagram, showing those expected possible state transitions and their API calls is provided here
51for reference.
52
53.. graphviz::
54   :caption: DMA state finite state machine
55
56   digraph {
57       node [style=rounded];
58       edge [fontname=Courier];
59       init [shape=point];
60
61       CONFIGURED [label=Configured,shape=box];
62       RUNNING [label=Running,shape=box];
63       SUSPENDED [label=Suspended,shape=box];
64
65       init -> CONFIGURED [label=dma_config];
66
67       CONFIGURED -> RUNNING [label=dma_start];
68       CONFIGURED -> CONFIGURED [label=dma_stop, headport=c, tailport=e];
69       CONFIGURED -> CONFIGURED [label=dma_config, headport=c, tailport=w];
70
71       RUNNING -> CONFIGURED [label=dma_stop];
72       RUNNING -> RUNNING [label=dma_start];
73       RUNNING -> RUNNING [label=dma_resume, headport=w];
74       RUNNING -> SUSPENDED [label=dma_suspend];
75
76       SUSPENDED -> SUSPENDED [label=dma_suspend];
77       SUSPENDED -> RUNNING [label=dma_resume];
78       SUSPENDED -> CONFIGURED [label=dma_stop];
79   }
80
81API Reference
82*************
83
84.. doxygengroup:: dma_interface
85