1 /**
2  * @file    dma.h
3  * @brief   Direct Memory Access (DMA) driver function prototypes and data types.
4  */
5 
6 /******************************************************************************
7  *
8  * Copyright (C) 2022-2023 Maxim Integrated Products, Inc. (now owned by
9  * Analog Devices, Inc.),
10  * Copyright (C) 2023-2024 Analog Devices, Inc.
11  *
12  * Licensed under the Apache License, Version 2.0 (the "License");
13  * you may not use this file except in compliance with the License.
14  * You may obtain a copy of the License at
15  *
16  *     http://www.apache.org/licenses/LICENSE-2.0
17  *
18  * Unless required by applicable law or agreed to in writing, software
19  * distributed under the License is distributed on an "AS IS" BASIS,
20  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
21  * See the License for the specific language governing permissions and
22  * limitations under the License.
23  *
24  ******************************************************************************/
25 
26 #ifndef LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32662_DMA_H_
27 #define LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32662_DMA_H_
28 
29 /* **** Includes **** */
30 #include <stdbool.h>
31 #include "mxc_device.h"
32 #include "dma_regs.h"
33 
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 
38 /**
39  * @defgroup dma Direct Memory Access (DMA)
40  * @ingroup periphlibs
41  * @{
42  */
43 
44 /* **** Definitions **** */
45 
46 /**
47  * @brief   Enumeration for the DMA Channel's priority level.
48  *
49  */
50 typedef enum {
51     MXC_DMA_PRIO_HIGH = MXC_V_DMA_CTRL_PRI_HIGH, ///< High Priority
52     MXC_DMA_PRIO_MEDHIGH = MXC_V_DMA_CTRL_PRI_MEDHIGH, ///< Medium High Priority
53     MXC_DMA_PRIO_MEDLOW = MXC_V_DMA_CTRL_PRI_MEDLOW, ///< Medium Low Priority
54     MXC_DMA_PRIO_LOW = MXC_V_DMA_CTRL_PRI_LOW, ///< Low Priority
55 } mxc_dma_priority_t;
56 
57 /** @brief DMA request select */
58 typedef enum {
59     MXC_DMA_REQUEST_MEMTOMEM =
60         MXC_S_DMA_CTRL_REQUEST_MEMTOMEM, ///< Memory to Memory DMA Request Selection
61     MXC_DMA_REQUEST_SPI0RX = MXC_S_DMA_CTRL_REQUEST_SPI0RX, ///< SPI0 Receive DMA Request Selection
62     MXC_DMA_REQUEST_SPI1RX = MXC_S_DMA_CTRL_REQUEST_SPI1RX, ///< SPI1 Receive DMA Request Selection
63     MXC_DMA_REQUEST_UART0RX =
64         MXC_S_DMA_CTRL_REQUEST_UART0RX, ///< UART0 Receive DMA Request Selection
65     MXC_DMA_REQUEST_UART1RX =
66         MXC_S_DMA_CTRL_REQUEST_UART1RX, ///< UART1 Receive DMA Request Selection
67     MXC_DMA_REQUEST_I2C0RX = MXC_S_DMA_CTRL_REQUEST_I2C0RX, ///< I2C0 Receive DMA Request Selection
68     MXC_DMA_REQUEST_I2C1RX = MXC_S_DMA_CTRL_REQUEST_I2C1RX, ///< I2C1 Receive DMA Request Selection
69     MXC_DMA_REQUEST_ADC = MXC_S_DMA_CTRL_REQUEST_ADC, ///< ADC Receive DMA Request Selection
70     MXC_DMA_REQUEST_I2SRX = MXC_S_DMA_CTRL_REQUEST_I2SRX, ///< I2S Receive DMA Request Selection
71     MXC_DMA_REQUEST_AESRX = MXC_S_DMA_CTRL_REQUEST_AESRX, ///< AES Receive DMA Request Selection
72     MXC_DMA_REQUEST_CANRX = MXC_S_DMA_CTRL_REQUEST_CANRX, ///< CAN Receive DMA Request Selection
73     MXC_DMA_REQUEST_SPI0TX = MXC_S_DMA_CTRL_REQUEST_SPI0TX, ///< SPI0 Transmit DMA Request Selection
74     MXC_DMA_REQUEST_SPI1TX = MXC_S_DMA_CTRL_REQUEST_SPI1TX, ///< SPI1 Transmit DMA Request Selection
75     MXC_DMA_REQUEST_UART0TX =
76         MXC_S_DMA_CTRL_REQUEST_UART0TX, ///< UART0 Transmit DMA Request Selection
77     MXC_DMA_REQUEST_UART1TX =
78         MXC_S_DMA_CTRL_REQUEST_UART1TX, ///< UART1 Transmit DMA Request Selection
79     MXC_DMA_REQUEST_I2C0TX = MXC_S_DMA_CTRL_REQUEST_I2C0TX, ///< I2C0 Transmit DMA Request Selection
80     MXC_DMA_REQUEST_I2C1TX = MXC_S_DMA_CTRL_REQUEST_I2C1TX, ///< I2C1 Transmit DMA Request Selection
81     MXC_DMA_REQUEST_I2STX = MXC_S_DMA_CTRL_REQUEST_I2STX, ///< I2S Transmit DMA Request Selection
82     MXC_DMA_REQUEST_AESTX = MXC_S_DMA_CTRL_REQUEST_AESTX, ///< AES Transmit DMA Request Selection
83     MXC_DMA_REQUEST_CANTX = MXC_S_DMA_CTRL_REQUEST_CANTX, ///< CAN Transmit DMA Request Selection
84 } mxc_dma_reqsel_t;
85 
86 /** @brief Enumeration for the DMA prescaler */
87 typedef enum {
88     MXC_DMA_PRESCALE_DISABLE = MXC_S_DMA_CTRL_TO_CLKDIV_DIS, ///< Prescaler disabled
89     MXC_DMA_PRESCALE_DIV256 = MXC_S_DMA_CTRL_TO_CLKDIV_DIV256, ///< Divide by 256
90     MXC_DMA_PRESCALE_DIV64K = MXC_S_DMA_CTRL_TO_CLKDIV_DIV64K, ///< Divide by 65,536
91     MXC_DMA_PRESCALE_DIV16M = MXC_S_DMA_CTRL_TO_CLKDIV_DIV16M, ///< Divide by 16,777,216
92 } mxc_dma_prescale_t;
93 
94 /** @brief Enumeration for the DMA timeout value */
95 typedef enum {
96     MXC_DMA_TIMEOUT_4_CLK = MXC_S_DMA_CTRL_TO_PER_TO4, ///< DMA timeout of 4 clocks
97     MXC_DMA_TIMEOUT_8_CLK = MXC_S_DMA_CTRL_TO_PER_TO8, ///< DMA timeout of 8 clocks
98     MXC_DMA_TIMEOUT_16_CLK = MXC_S_DMA_CTRL_TO_PER_TO16, ///< DMA timeout of 16 clocks
99     MXC_DMA_TIMEOUT_32_CLK = MXC_S_DMA_CTRL_TO_PER_TO32, ///< DMA timeout of 32 clocks
100     MXC_DMA_TIMEOUT_64_CLK = MXC_S_DMA_CTRL_TO_PER_TO64, ///< DMA timeout of 64 clocks
101     MXC_DMA_TIMEOUT_128_CLK = MXC_S_DMA_CTRL_TO_PER_TO128, ///< DMA timeout of 128 clocks
102     MXC_DMA_TIMEOUT_256_CLK = MXC_S_DMA_CTRL_TO_PER_TO256, ///< DMA timeout of 256 clocks
103     MXC_DMA_TIMEOUT_512_CLK = MXC_S_DMA_CTRL_TO_PER_TO512, ///< DMA timeout of 512 clocks
104 } mxc_dma_timeout_t;
105 
106 /** @brief DMA transfer data width */
107 typedef enum {
108     /* Using the '_V_' define instead of the '_S_' since these same values will be used to
109        specify the DSTWD also.  The API functions will shift the value the correct amount
110        prior to writing the cfg register. */
111     MXC_DMA_WIDTH_BYTE = MXC_V_DMA_CTRL_SRCWD_BYTE, ///< DMA transfer in bytes
112     MXC_DMA_WIDTH_HALFWORD = MXC_V_DMA_CTRL_SRCWD_HALFWORD, ///< DMA transfer in 16-bit half-words
113     MXC_DMA_WIDTH_WORD = MXC_V_DMA_CTRL_SRCWD_WORD, ///< DMA transfer in 32-bit words
114 } mxc_dma_width_t;
115 
116 /**
117  * @brief   The basic configuration information to set up a DMA channel
118  *          and prepare it for transfers.
119  *
120  */
121 typedef struct {
122     int ch; ///< The channel to load the configuration data into
123     mxc_dma_reqsel_t reqsel; ///< The request select line to be used (mem2mem, peripheral)
124     mxc_dma_width_t srcwd; ///< The source width (could be dependent on FIFO width)
125     mxc_dma_width_t dstwd; ///< The destination width (could be dependent on FIFO width)
126     int srcinc_en; ///< Whether to increment the source address during the transfer
127     int dstinc_en; ///< Whether to increment the source address during the transfer
128 } mxc_dma_config_t;
129 
130 /**
131  * @brief   The information needed to complete a DMA transfer
132  *
133  */
134 typedef struct {
135     int ch; ///< The channel to use for the transfer
136     void *source; ///< Pointer to the source address, if applicable
137     void *dest; ///< Pointer to the destination address, if applicable
138     int len; ///< Number of bytes to transfer
139 } mxc_dma_srcdst_t;
140 
141 /**
142  * @brief   The advanced configuration options, these are optional but could
143  *          be needed in cases where multiple DMA channels are running concurrently
144  *          or DMA is being used with low bandwidth peripherals.
145  *
146  */
147 typedef struct {
148     int ch; ///< The channel to use for the transfer
149     mxc_dma_priority_t prio; ///< The DMA priority for the channel
150     unsigned int reqwait_en; ///< Delay the timeout timer start until after first transfer
151     mxc_dma_timeout_t tosel; ///< Number of prescaled clocks seen by the channel before a timeout
152     mxc_dma_prescale_t pssel; ///< Prescaler for the timeout timer
153     unsigned int burst_size; ///< Number of bytes moved in a single burst
154 } mxc_dma_adv_config_t;
155 
156 /**
157  * @brief   The callback called on completion of a DMA_MemCpy() transfer
158  *
159  * @param   dest    Pointer to the destination of the copy
160  */
161 typedef void (*mxc_dma_complete_cb_t)(void *dest);
162 
163 /**
164  * @brief   The callback called on completion of a transfer,
165  * @note    This callback is used with MXC_DMA_DoTransfer()
166  *          to allow the user to chain an unlimited number of
167  *          DMA Transfers.
168  *
169  * @param   trans    Struct of the completed transfer
170  *
171  * @return  Returns the next transfer to be completed, or NULL
172  *          if no more transfers will be done
173  */
174 typedef mxc_dma_srcdst_t (*mxc_dma_trans_chain_t)(mxc_dma_srcdst_t dest);
175 
176 /* **** Function Prototypes **** */
177 /*************************/
178 /* Low Level Functions   */
179 /*************************/
180 /**
181  * @brief      Initialize DMA resources
182  * @details    This initialization is required before using the DMA driver functions.
183  * @note       On default this function enables DMA peripheral clock.
184  *             if you wish to manage clock and gpio related things in upper level instead of here.
185  *             Define MSDK_NO_GPIO_CLK_INIT flag in project.mk file.
186  *             By this flag this function will remove clock and gpio related codes from file.
187  * @return     #E_NO_ERROR if successful
188  */
189 int MXC_DMA_Init(void);
190 
191 /**
192  * @brief      De-Initialize DMA resources.
193  */
194 void MXC_DMA_DeInit(void);
195 
196 /**
197  * @brief      Request DMA channel
198  * @details    Returns a handle to the first free DMA channel, which can be used via API calls
199  *             or direct access to channel registers using the MXC_DMA_GetCHRegs(int ch) function.
200  * @return     Non-negative channel handle (inclusive of zero).
201  * @return     #E_NONE_AVAIL    All channels in use.
202  * @return     #E_BAD_STATE     DMA is not initialized, call MXC_DMA_Init() first.
203  * @return     #E_BUSY          DMA is currently busy (locked), try again later.
204  */
205 int MXC_DMA_AcquireChannel(void);
206 
207 /**
208  * @brief      Release DMA channel
209  * @details    Stops any DMA operation on the channel and returns it to the pool of free channels.
210  *
211  * @param          ch   channel handle to release
212  *
213  * @return     #E_BAD_PARAM if an unused or invalid channel handle, #E_NO_ERROR otherwise
214  */
215 int MXC_DMA_ReleaseChannel(int ch);
216 
217 /**
218  * @brief      Configure the DMA channel
219  * @details    Configures the channel, which was previously requested by MXC_DMA_Getchannel()
220  *
221  * @param      config   Struct containing DMA configuration parameters
222  * @param      srcdst   Struct containing pointers and length of DMA operation
223  *
224  * @return     #E_BAD_PARAM if an unused or invalid channel handle, #E_NO_ERROR otherwise
225  */
226 int MXC_DMA_ConfigChannel(mxc_dma_config_t config, mxc_dma_srcdst_t srcdst);
227 
228 /**
229  * @brief      Configure the DMA channel with more advanced parameters
230  *
231  * @param      advConfig    Struct containing advanced DMA parameters
232  *
233  * @return     #E_BAD_PARAM if an unused or invalid channel handle, #E_NO_ERROR otherwise
234  */
235 int MXC_DMA_AdvConfigChannel(mxc_dma_adv_config_t advConfig);
236 
237 /**
238  * @brief      Set channel source, destination, and count for the transfer
239  * @param      srcdst Struct containing the channel, source, destination, and count for the channel
240  * @note       Unless the channel request select is #mxc_dma_srcdst_t = MXC_DMA_REQUEST_MEMTOMEM,
241  *             either src_addr or dst_addr will be ignored by the DMA engine.
242  *             In these cases, the address is a don't-care. See the User's
243  *             Guide for more information.
244  * @return     #E_BAD_PARAM if an unused or invalid channel handle, #E_NO_ERROR otherwise
245  */
246 int MXC_DMA_SetSrcDst(mxc_dma_srcdst_t srcdst);
247 
248 /**
249  * @brief      Get channel source, destination, and count for transfer
250  *
251  * @param      srcdst Pointer to struct with the correct channel number
252  *
253  * @return     See \ref MXC_Error_Codes for a list of return values
254  */
255 int MXC_DMA_GetSrcDst(mxc_dma_srcdst_t *srcdst);
256 
257 /**
258  * @brief      Set channel reload source, destination, and count for the transfer
259  * @param      srcdstReload Struct containing the channel, source, destination, and count for the channel
260  * @note       Unless the channel request select is #mxc_dma_srcdst_t = MXC_DMA_REQUEST_MEMTOMEM,
261  *             either src_addr or dst_addr will be ignored by the DMA engine.
262  *             In these cases, the address is a don't-care. See the User's
263  *             Guide for more information.
264  * @return     #E_BAD_PARAM if an unused or invalid channel handle, #E_NO_ERROR otherwise
265  */
266 int MXC_DMA_SetSrcReload(mxc_dma_srcdst_t srcdstReload);
267 
268 /**
269  * @brief      Get channel reload source, destination, and count for transfer
270  *
271  * @param      srcdstReload Pointer to struct with the correct channel number
272  *
273  * @return     See \ref MXC_Error_Codes for a list of return values
274  */
275 int MXC_DMA_GetSrcReload(mxc_dma_srcdst_t *srcdstReload);
276 
277 /**
278  * @brief      Set channel interrupt callback
279  * @param      ch        channel handle
280  * @param      callback  Pointer to a function to call when the channel
281  *                       interrupt flag is set and interrupts are enabled or
282  *                       when DMA is shutdown by the driver.
283  * @details    Configures the channel interrupt callback. The @p callback
284  *             function is called for two conditions:
285  *               -# When the channel's interrupt flag is set and DMA interrupts
286  *                  are enabled.
287  *               -# If the driver calls the MXC_DMA_Shutdown() function. The
288  *                  callback function prototype is:
289  * @code
290  *             void callback_fn(int ch, int reason);
291  * @endcode
292  *             @p ch indicates the channel that generated the callback, @p
293  *             reason is either #E_NO_ERROR for a DMA interrupt or #E_SHUTDOWN
294  *             if the DMA is being shutdown.
295  *
296  * @return     #E_BAD_PARAM if an unused or invalid channel handle,
297  *             #E_NO_ERROR otherwise, \ref MXC_Error_Codes
298  */
299 int MXC_DMA_SetCallback(int ch, void (*callback)(int, int));
300 
301 /**
302  * @brief      Set channel interrupt
303  * @note       Each channel has two interrupts (complete, and count to zero).
304  *             To enable complete, pass true for chdis. To enable count to zero,
305  *             pass true for ctz.
306  * @param      ch Channel Handle
307  * @param      chdis Enable channel complete interrupt
308  * @param      ctz Enable channel count to zero interrupt.
309  * @return     #E_BAD_PARAM if an unused or invalid channel handle, #E_NO_ERROR otherwise
310  */
311 int MXC_DMA_SetChannelInterruptEn(int ch, bool chdis, bool ctz);
312 
313 /**
314  * @brief      Enable channel interrupt
315  * @note       Each channel has two interrupts (complete, and count to zero)
316                which must also be enabled with MXC_DMA_SetChannelInterruptEn()
317  * @param      ch   channel handle
318  * @param      flags The flags to enable
319  * @return     #E_BAD_PARAM if an unused or invalid channel handle,
320  *             #E_NO_ERROR otherwise, \ref MXC_Error_Codes
321  */
322 int MXC_DMA_ChannelEnableInt(int ch, int flags);
323 
324 /**
325  * @brief      Disable channel interrupt
326  * @param      ch   channel handle
327  * @param      flags The flags to disable
328  * @return     #E_BAD_PARAM if an unused or invalid channel handle,
329  *             #E_NO_ERROR otherwise, \ref MXC_Error_Codes
330  */
331 int MXC_DMA_ChannelDisableInt(int ch, int flags);
332 
333 /**
334  * @brief      Read channel interrupt flags
335  * @param      ch   channel handle
336  * @return     #E_BAD_PARAM if an unused or invalid channel handle,
337  *             flags otherwise, \ref MXC_Error_Codes
338  */
339 int MXC_DMA_ChannelGetFlags(int ch);
340 
341 /**
342  * @brief      Clear channel interrupt flags
343  * @param      ch   channel handle
344  * @param      flags The flags to clear
345  * @return     #E_BAD_PARAM if an unused or invalid channel handle,
346  *             #E_NO_ERROR otherwise, \ref MXC_Error_Codes
347  */
348 int MXC_DMA_ChannelClearFlags(int ch, int flags);
349 
350 /**
351  * @brief      Enable channel interrupt
352  * @note       Each channel has two interrupts (complete, and count to zero)
353                which must also be enabled with MXC_DMA_SetChannelInterruptEn()
354  * @param      ch   channel handle
355  * @return     #E_BAD_PARAM if an unused or invalid channel handle,
356  *             #E_NO_ERROR otherwise, \ref MXC_Error_Codes
357  */
358 int MXC_DMA_EnableInt(int ch);
359 
360 /**
361  * @brief      Disable channel interrupt
362  * @param      ch   channel handle
363  * @return     #E_BAD_PARAM if an unused or invalid channel handle,
364  *             #E_NO_ERROR otherwise, \ref MXC_Error_Codes
365  */
366 int MXC_DMA_DisableInt(int ch);
367 
368 /**
369  * @brief      Start transfer
370  * @param      ch   channel handle
371  * @details    Start the DMA channel transfer, assumes that MXC_DMA_SetSrcDstCnt() has been called beforehand.
372  * @return     #E_BAD_PARAM if an unused or invalid channel handle,
373  *             #E_NO_ERROR otherwise, \ref MXC_Error_Codes
374  */
375 int MXC_DMA_Start(int ch);
376 
377 /**
378  * @brief      Stop DMA transfer, irrespective of status (complete or in-progress)
379  * @param      ch   channel handle
380  * @return     #E_BAD_PARAM if an unused or invalid channel handle,
381  *             #E_NO_ERROR otherwise, \ref MXC_Error_Codes
382  */
383 int MXC_DMA_Stop(int ch);
384 
385 /**
386  * @brief      Get a pointer to the DMA channel registers
387  * @param      ch   channel handle
388  * @details    If direct access to DMA channel registers is required, this
389  *             function can be used on a channel handle returned by MXC_DMA_AcquireChannel().
390  * @return     NULL if an unused or invalid channel handle, or a valid pointer otherwise
391  */
392 mxc_dma_ch_regs_t *MXC_DMA_GetCHRegs(int ch);
393 
394 /**
395  * @brief      Interrupt handler function
396  * @details    Call this function as the ISR for each DMA channel under driver control.
397  *             Interrupt flags for channel ch will be automatically cleared before return.
398  */
399 void MXC_DMA_Handler(void);
400 
401 /*************************/
402 /* High Level Functions  */
403 /*************************/
404 
405 /**
406  * @brief      Performs a memcpy, using DMA, optionally asynchronous
407  * @note       The user must have the DMA interrupt enabled and call
408  *             MXC_DMA_Handler() from the ISR.
409  *
410  * @param      dest     pointer to destination memory
411  * @param      src      pointer to source memory
412  * @param      len      number of bytes to copy
413  * @param      callback function to call when transfer is complete
414  *
415  * @return     see \ref MXC_Error_Codes
416  */
417 int MXC_DMA_MemCpy(void *dest, void *src, int len, mxc_dma_complete_cb_t callback);
418 
419 /**
420  * @brief      Performs a memcpy, using DMA, optionally asynchronous
421  * @note       The user must have the DMA interrupt enabled and call
422  *             MXC_DMA_Handler() from the ISR.
423  *
424  * @param      config   The channel config struct
425  * @param      firstSrcDst  The source, destination, and count for the first transfer
426  * @param      callback function is called when transfer is complete
427  *
428  * @return     see \ref MXC_Error_Codes
429  */
430 int MXC_DMA_DoTransfer(mxc_dma_config_t config, mxc_dma_srcdst_t firstSrcDst,
431                        mxc_dma_trans_chain_t callback);
432 /**
433  * For other functional uses of DMA (UART, SPI, etc) see the appropriate peripheral driver
434  */
435 
436 /**@} end of group dma */
437 #ifdef __cplusplus
438 }
439 #endif
440 
441 #endif // LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32662_DMA_H_
442