1 // Copyright 2020 Espressif Systems (Shanghai) PTE LTD
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 //     http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 /*******************************************************************************
16  * NOTICE
17  * The HAL is not public api, don't use in application code.
18  * See readme.md in soc/README.md
19  ******************************************************************************/
20 
21 // CP DMA HAL usages:
22 // 1. Initialize HAL layer by cp_dma_hal_init, pass in the allocated descriptors for TX and RX
23 // 2. Enable DMA and interrupt by cp_dma_hal_start
24 // 3. Prepare descriptors used for TX and RX
25 // 4. Restart the DMA engine in case it's not in working
26 
27 #pragma once
28 
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32 
33 #include <stddef.h>
34 #include <stdbool.h>
35 #include "esp_attr.h"
36 #include "hal/dma_types.h"
37 #include "soc/cp_dma_struct.h"
38 
39 /**
40  * @brief HAL context
41  *
42  */
43 typedef struct {
44     cp_dma_dev_t *dev;
45 } cp_dma_hal_context_t;
46 
47 typedef struct {
48 } cp_dma_hal_config_t;
49 
50 /**
51  * @brief Initialize HAL layer context
52  *
53  * @param hal HAL layer context, whose memroy should be allocated at driver layer
54  * @param config configuration for the HAL layer
55  */
56 void cp_dma_hal_init(cp_dma_hal_context_t *hal, const cp_dma_hal_config_t *config);
57 
58 /**
59  * @brief Deinitialize HAL layer context
60  */
61 void cp_dma_hal_deinit(cp_dma_hal_context_t *hal);
62 
63 /**
64  * @brief Set descriptor base address
65  */
66 void cp_dma_hal_set_desc_base_addr(cp_dma_hal_context_t *hal, intptr_t outlink_base, intptr_t inlink_base);
67 
68 /**
69  * @brief Start mem2mem DMA state machine
70  */
71 void cp_dma_hal_start(cp_dma_hal_context_t *hal);
72 
73 /**
74  * @brief Stop mem2mem DMA state machine
75  */
76 void cp_dma_hal_stop(cp_dma_hal_context_t *hal);
77 
78 /**
79  * @brief Get interrupt status word
80  *
81  * @return uint32_t Interrupt status
82  */
83 uint32_t cp_dma_hal_get_intr_status(cp_dma_hal_context_t *hal) IRAM_ATTR;
84 
85 /**
86  * @brief Clear interrupt mask
87  *
88  * @param mask interrupt mask
89  */
90 void cp_dma_hal_clear_intr_status(cp_dma_hal_context_t *hal, uint32_t mask) IRAM_ATTR;
91 
92 /**@{*/
93 /**
94  * @brief Give the owner of descriptors between [start_desc, end_desc] to DMA, and restart DMA HW engine
95  *
96  * @param hal HAL layer context
97  * @param start_desc The first descriptor that carries one transaction
98  * @param end_desc The last descriptor that carries one transaction
99  */
100 void cp_dma_hal_restart_tx(cp_dma_hal_context_t *hal);
101 void cp_dma_hal_restart_rx(cp_dma_hal_context_t *hal);
102 /**@}*/
103 
104 #ifdef __cplusplus
105 }
106 #endif
107