1 /*
2 * Copyright (c) 2021-2022 HPMicro
3 *
4 * SPDX-License-Identifier: BSD-3-Clause
5 *
6 */
7
8
9 #ifndef HPM_DMA_DRV_H
10 #define HPM_DMA_DRV_H
11 #include "hpm_common.h"
12 #include "hpm_soc_feature.h"
13 #include "hpm_dma_regs.h"
14
15 /**
16 *
17 * @brief DMA driver APIs
18 * @defgroup dma_interface DMA driver APIs
19 * @ingroup io_interfaces
20 * @{
21 */
22
23 #define DMA_NUM_TRANSFER_PER_BURST_1T (0U)
24 #define DMA_NUM_TRANSFER_PER_BURST_2T (1U)
25 #define DMA_NUM_TRANSFER_PER_BURST_4T (2U)
26 #define DMA_NUM_TRANSFER_PER_BURST_8T (3U)
27 #define DMA_NUM_TRANSFER_PER_BURST_16T (4U)
28 #define DMA_NUM_TRANSFER_PER_BURST_32T (5U)
29 #define DMA_NUM_TRANSFER_PER_BURST_64T (6U)
30 #define DMA_NUM_TRANSFER_PER_BURST_128T (7U)
31 #define DMA_NUM_TRANSFER_PER_BURST_256T (8U)
32 #define DMA_NUM_TRANSFER_PER_BURST_512T (9U)
33 #define DMA_NUM_TRANSFER_PER_BURST_1024T (10U)
34
35 #define DMA_TRANSFER_WIDTH_BYTE (0U)
36 #define DMA_TRANSFER_WIDTH_HALF_WORD (1U)
37 #define DMA_TRANSFER_WIDTH_WORD (2U)
38 #define DMA_TRANSFER_WIDTH_DOUBLE_WORD (3U)
39 #define DMA_TRANSFER_WIDTH_QUAD_WORD (4U)
40 #define DMA_TRANSFER_WIDTH_EIGHT_WORD (5U)
41
42 #define DMA_STATUS_ERROR_SHIFT (0U)
43 #define DMA_STATUS_ABORT_SHIFT (8U)
44 #define DMA_STATUS_TC_SHIFT (16U)
45
46 #define DMA_CHANNEL_STATUS_ONGOING (1U)
47 #define DMA_CHANNEL_STATUS_ERROR (2U)
48 #define DMA_CHANNEL_STATUS_ABORT (4U)
49 #define DMA_CHANNEL_STATUS_TC (8U)
50
51 #define DMA_CHANNEL_IRQ_STATUS_ERROR(x) (uint32_t)(1 << (DMA_STATUS_ERROR_SHIFT + x))
52 #define DMA_CHANNEL_IRQ_STATUS_ABORT(x) (uint32_t)(1 << (DMA_STATUS_ABORT_SHIFT + x))
53 #define DMA_CHANNEL_IRQ_STATUS_TC(x) (uint32_t)(1 << (DMA_STATUS_TC_SHIFT + x))
54 #define DMA_CHANNEL_IRQ_STATUS(x) (uint32_t)(DMA_CHANNEL_IRQ_STATUS_TC(x) | \
55 DMA_CHANNEL_IRQ_STATUS_ABORT(x) | \
56 DMA_CHANNEL_IRQ_STATUS_ERROR(x))
57
58 #define DMA_CHANNEL_IRQ_STATUS_GET_ALL_TC(x) ((x) & (((0x01UL << DMA_SOC_CHANNEL_NUM) - 1) << DMA_STATUS_TC_SHIFT))
59 #define DMA_CHANNEL_IRQ_STATUS_GET_ALL_ABORT(x) ((x) & (((0x01UL << DMA_SOC_CHANNEL_NUM) - 1) << DMA_STATUS_ABORT_SHIFT))
60 #define DMA_CHANNEL_IRQ_STATUS_GET_ALL_ERROR(x) ((x) & (((0x01UL << DMA_SOC_CHANNEL_NUM) - 1) << DMA_STATUS_ERROR_SHIFT))
61
62 #define DMA_HANDSHAKE_MODE_HANDSHAKE (1U)
63 #define DMA_HANDSHAKE_MODE_NORMAL (0U)
64
65 #define DMA_ADDRESS_CONTROL_INCREMENT (0U)
66 #define DMA_ADDRESS_CONTROL_DECREMENT (1U)
67 #define DMA_ADDRESS_CONTROL_FIXED (2U)
68
69 #define DMA_INTERRUPT_MASK_NONE (0U)
70 #define DMA_INTERRUPT_MASK_ERROR DMA_CHCTRL_CTRL_INTERRMASK_MASK
71 #define DMA_INTERRUPT_MASK_ABORT DMA_CHCTRL_CTRL_INTABTMASK_MASK
72 #define DMA_INTERRUPT_MASK_TERMINAL_COUNT DMA_CHCTRL_CTRL_INTTCMASK_MASK
73 #define DMA_INTERRUPT_MASK_ALL \
74 (uint8_t)(DMA_INTERRUPT_MASK_TERMINAL_COUNT \
75 | DMA_INTERRUPT_MASK_ABORT \
76 | DMA_INTERRUPT_MASK_ERROR)
77
78 #ifndef DMA_SUPPORT_64BIT_ADDR
79 #define DMA_SUPPORT_64BIT_ADDR (0)
80 #endif
81
82 /**
83 * @brief Linked descriptor
84 *
85 * It is consumed by DMA controlled directly
86 */
87 typedef struct dma_linked_descriptor {
88 uint32_t ctrl; /**< Control */
89 uint32_t trans_size; /**< Transfer size in source width */
90 uint32_t src_addr; /**< Source address */
91 uint32_t src_addr_high; /**< Source address high 32-bit, only valid when bus width > 32bits */
92 uint32_t dst_addr; /**< Destination address */
93 uint32_t dst_addr_high; /**< Destination address high 32-bit, only valid when bus width > 32bits */
94 uint32_t linked_ptr; /**< Linked descriptor address */
95 uint32_t linked_ptr_high; /**< Linked descriptor address high 32-bit, , only valid when bus width > 32bits */
96 } dma_linked_descriptor_t;
97
98 /* @brief Channel config */
99 typedef struct dma_channel_config {
100 uint8_t priority; /**< Channel priority */
101 uint8_t src_burst_size; /**< Source burst size */
102 uint8_t src_mode; /**< Source work mode */
103 uint8_t dst_mode; /**< Destination work mode */
104 uint8_t src_width; /**< Source width */
105 uint8_t dst_width; /**< Destination width */
106 uint8_t src_addr_ctrl; /**< Source address control */
107 uint8_t dst_addr_ctrl; /**< Destination address control */
108 uint16_t interrupt_mask; /**< Interrupt mask */
109 uint32_t src_addr; /**< Source address */
110 uint32_t dst_addr; /**< Destination address */
111 uint32_t linked_ptr; /**< Next linked descriptor */
112 uint32_t size_in_byte; /**< Total size to be transferred in byte */
113 #if DMA_SUPPORT_64BIT_ADDR
114 uint32_t src_addr_high; /**< Source address high 32bits */
115 uint32_t dst_addr_high; /**< Destination address high 32bits */
116 uint32_t linked_ptr_high; /**< Linked descriptor high 32bits */
117 #endif
118 } dma_channel_config_t;
119
120
121 /* @brief Channel config */
122 typedef struct dma_handshake_config {
123 uint32_t dst;
124 uint32_t src;
125 uint32_t size_in_byte;
126 uint8_t ch_index;
127 bool dst_fixed;
128 bool src_fixed;
129 } dma_handshake_config_t;
130
131
132 /* @brief DMA specific status */
133 enum {
134 status_dma_transfer_done = MAKE_STATUS(status_group_dma, 0),
135 status_dma_transfer_error = MAKE_STATUS(status_group_dma, 1),
136 status_dma_transfer_abort = MAKE_STATUS(status_group_dma, 2),
137 status_dma_transfer_ongoing = MAKE_STATUS(status_group_dma, 3),
138 status_dma_alignment_error = MAKE_STATUS(status_group_dma, 4),
139 };
140
141 #ifdef __cplusplus
142 extern "C" {
143 #endif
144
145 /**
146 * @brief Reset DMA
147 *
148 * @param[in] ptr DMA base address
149 */
dma_reset(DMA_Type * ptr)150 static inline void dma_reset(DMA_Type *ptr)
151 {
152 ptr->DMACTRL |= DMA_DMACTRL_RESET_MASK;
153 }
154
155 /**
156 * @brief Enable DMA channel
157 *
158 * @param[in] ptr DMA base address
159 * @param[in] ch_index Index of the channel to be enabled
160 *
161 * @return status_success if everything's okay
162 */
dma_enable_channel(DMA_Type * ptr,uint32_t ch_index)163 static inline hpm_stat_t dma_enable_channel(DMA_Type *ptr, uint32_t ch_index)
164 {
165 ptr->CHCTRL[ch_index].CTRL |= DMA_CHCTRL_CTRL_ENABLE_MASK;
166
167 if ((ptr->CHEN == 0) || !(ptr->CHEN & 1 << ch_index)) {
168 return status_fail;
169 }
170 return status_success;
171 }
172
173 /**
174 * @brief Disable DMA channel
175 *
176 * @param[in] ptr DMA base address
177 * @param[in] ch_index Index of the channel to be disabled
178 *
179 */
dma_disable_channel(DMA_Type * ptr,uint32_t ch_index)180 static inline void dma_disable_channel(DMA_Type *ptr, uint32_t ch_index)
181 {
182 ptr->CHCTRL[ch_index].CTRL &= ~DMA_CHCTRL_CTRL_ENABLE_MASK;
183 }
184
185 /**
186 * @brief Abort channel transfer with mask
187 *
188 * @param[in] ptr DMA base address
189 * @param[in] ch_index_mask Mask of channels to be aborted
190 */
dma_abort_channel(DMA_Type * ptr,uint32_t ch_index_mask)191 static inline void dma_abort_channel(DMA_Type *ptr, uint32_t ch_index_mask)
192 {
193 ptr->CHABORT |= DMA_CHABORT_CHABORT_SET(ch_index_mask);
194 }
195
196 /**
197 * @brief Check if channels are enabled with mask
198 *
199 * @param[in] ptr DMA base address
200 * @param[in] ch_index_mask Mask of channels to be checked
201 *
202 * @return Enabled channel mask
203 */
dma_check_enabled_channel(DMA_Type * ptr,uint32_t ch_index_mask)204 static inline uint32_t dma_check_enabled_channel(DMA_Type *ptr,
205 uint32_t ch_index_mask)
206 {
207 return (ch_index_mask & ptr->CHEN);
208 }
209
210 /**
211 * @brief Check if linked pointer has been configured
212 *
213 * @param[in] ptr DMA base address
214 * @param[in] ch_index Target channel index to be checked
215 *
216 * @return true if linked pointer has been configured
217 */
dma_has_linked_pointer_configured(DMA_Type * ptr,uint32_t ch_index)218 static inline bool dma_has_linked_pointer_configured(DMA_Type *ptr, uint32_t ch_index)
219 {
220 return ptr->CHCTRL[ch_index].LLPOINTER != 0;
221 }
222
223 /**
224 * @brief Check transfer status
225 *
226 * @param[in] ptr DMA base address
227 * @param[in] ch_index Target channel index to be checked
228 *
229 * @retval 1 if transfer is still ongoing
230 * @retval 2 if any error occurred during transferring
231 * @retval 4 if transfer is aborted
232 * @retval 8 if transfer is finished without error
233 */
dma_check_transfer_status(DMA_Type * ptr,uint8_t ch_index)234 static inline uint32_t dma_check_transfer_status(DMA_Type *ptr, uint8_t ch_index)
235 {
236 volatile uint32_t tmp = ptr->INTSTATUS;
237 volatile uint32_t tmp_channel;
238 uint32_t dma_status;
239
240 dma_status = 0;
241 tmp_channel = tmp & (1 << (DMA_STATUS_TC_SHIFT + ch_index));
242 if (tmp_channel) {
243 dma_status |= DMA_CHANNEL_STATUS_TC;
244 ptr->INTSTATUS = tmp_channel;
245 }
246 tmp_channel = tmp & (1 << (DMA_STATUS_ERROR_SHIFT + ch_index));
247 if (tmp_channel) {
248 dma_status |= DMA_CHANNEL_STATUS_ERROR;
249 ptr->INTSTATUS = tmp_channel;
250 }
251 tmp_channel = tmp & (1 << (DMA_STATUS_ABORT_SHIFT + ch_index));
252 if (tmp_channel) {
253 dma_status |= DMA_CHANNEL_STATUS_ABORT;
254 ptr->INTSTATUS = tmp_channel;
255 }
256 if (dma_status == 0) {
257 dma_status = DMA_CHANNEL_STATUS_ONGOING;
258 }
259 return dma_status;
260 }
261
262 /**
263 * @brief Clear transfer status
264 *
265 * @param[in] ptr DMA base address
266 * @param[in] ch_index Target channel index
267 *
268 */
dma_clear_transfer_status(DMA_Type * ptr,uint8_t ch_index)269 static inline void dma_clear_transfer_status(DMA_Type *ptr, uint8_t ch_index)
270 {
271 ptr->INTSTATUS &= ~((1 << (DMA_STATUS_TC_SHIFT + ch_index)) | (1 << (DMA_STATUS_ERROR_SHIFT + ch_index)) | (1 << (DMA_STATUS_ABORT_SHIFT + ch_index)));
272 }
273
274 /**
275 * @brief Enable DMA Channel interrupt
276 *
277 * @param [in] ptr DMA base address
278 * @param [in] ch_index Target channel index
279 * @param [in] interrupt_mask Interrupt mask
280 */
dma_enable_channel_interrupt(DMA_Type * ptr,uint8_t ch_index,int32_t interrupt_mask)281 static inline void dma_enable_channel_interrupt(DMA_Type *ptr, uint8_t ch_index, int32_t interrupt_mask)
282 {
283 ptr->CHCTRL[ch_index].CTRL &= ~(interrupt_mask & (DMA_INTERRUPT_MASK_ERROR | DMA_INTERRUPT_MASK_ABORT | DMA_INTERRUPT_MASK_TERMINAL_COUNT));
284 }
285
286 /**
287 * @brief Disable DMA Channel interrupt
288 *
289 * @param [in] ptr DMA base address
290 * @param [in] ch_index Target channel index
291 * @param [in] interrupt_mask Interrupt mask
292 */
dma_disable_channel_interrupt(DMA_Type * ptr,uint8_t ch_index,int32_t interrupt_mask)293 static inline void dma_disable_channel_interrupt(DMA_Type *ptr, uint8_t ch_index, int32_t interrupt_mask)
294 {
295 ptr->CHCTRL[ch_index].CTRL |= (interrupt_mask & (DMA_INTERRUPT_MASK_ERROR | DMA_INTERRUPT_MASK_ABORT | DMA_INTERRUPT_MASK_TERMINAL_COUNT));
296 }
297
298
299 /**
300 * @brief Check Channel interrupt master
301 *
302 * @param[in] ptr DMA base address
303 * @param[in] ch_index Target channel index to be checked
304 * @return uint32_t Interrupt mask
305 */
dma_check_channel_interrupt_mask(DMA_Type * ptr,uint8_t ch_index)306 static inline uint32_t dma_check_channel_interrupt_mask(DMA_Type *ptr, uint8_t ch_index)
307 {
308 return ptr->CHCTRL[ch_index].CTRL & (DMA_INTERRUPT_MASK_ERROR | DMA_INTERRUPT_MASK_ABORT | DMA_INTERRUPT_MASK_TERMINAL_COUNT);
309 }
310
311 /**
312 * @brief Get clear IRQ status
313 *
314 * @param[in] ptr DMA base address
315 * @param[in] mask irq mask to be cleared
316 */
dma_clear_irq_status(DMA_Type * ptr,uint32_t mask)317 static inline void dma_clear_irq_status(DMA_Type *ptr, uint32_t mask)
318 {
319 ptr->INTSTATUS = mask; /* Write-1-Clear */
320 }
321
322 /**
323 * @brief Get IRQ status
324 *
325 * @param[in] ptr DMA base address
326 */
dma_get_irq_status(DMA_Type * ptr)327 static inline uint32_t dma_get_irq_status(DMA_Type *ptr)
328 {
329 return ptr->INTSTATUS;
330 }
331
332 /**
333 * @brief Get default channel config
334 *
335 * @param[in] ptr DMA base address
336 * @param[in] ch Channel config
337 */
338 void dma_default_channel_config(DMA_Type *ptr, dma_channel_config_t *ch);
339
340 /**
341 * @brief Setup DMA channel
342 *
343 * @param[in] ptr DMA base address
344 * @param[in] ch_index Target channel index to be configured
345 * @param[in] ch Channel config
346 * @param[in] start_transfer Set true to start transfer
347 *
348 * @return status_success if everything is okay
349 */
350 hpm_stat_t dma_setup_channel(DMA_Type *ptr, uint32_t ch_index,
351 dma_channel_config_t *ch, bool start_transfer);
352 /**
353 * @brief Start DMA copy
354 *
355 * @param[in] ptr DMA base address
356 * @param[in] ch_index Target channel index
357 * @param[in] dst Destination address
358 * @param[in] src Source Address
359 * @param[in] size_in_byte Size in byte
360 * @param[in] burst_len_in_byte Burst length in byte
361 *
362 * @return status_success if everthing is okay
363 * @note: dst, src, size should be aligned with burst_len_in_byte
364 */
365 hpm_stat_t dma_start_memcpy(DMA_Type *ptr, uint8_t ch_index,
366 uint32_t dst, uint32_t src,
367 uint32_t size_in_byte, uint32_t burst_len_in_byte);
368
369 /**
370 * @brief config dma handshake function
371 *
372 * @param[in] ptr DMA base address
373 * @param[in] pconfig dma handshake config pointer
374 * @param[in] start_transfer Set true to start transfer
375 *
376 * @return status_success if everything is okay
377 */
378 hpm_stat_t dma_setup_handshake(DMA_Type *ptr, dma_handshake_config_t *pconfig, bool start_transfer);
379
380 #ifdef __cplusplus
381 }
382 #endif
383 /**
384 * @}
385 */
386 #endif /* HPM_DMA_DRV_H */
387