1 /*
2  * SPDX-FileCopyrightText: 2020-2021 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #pragma once
8 
9 #ifdef __cplusplus
10 extern "C" {
11 #endif
12 
13 #include <stdint.h>
14 #include <stdbool.h>
15 #include "esp_err.h"
16 #include "esp_etm.h"
17 
18 /**
19  * @brief Type of async memcpy handle
20  *
21  */
22 typedef struct async_memcpy_context_t *async_memcpy_t;
23 
24 /**
25  * @brief Type of async memcpy event object
26  *
27  */
28 typedef struct {
29     void *data; /*!< Event data */
30 } async_memcpy_event_t;
31 
32 /**
33  * @brief Type of async memcpy interrupt callback function
34  *
35  * @param mcp_hdl Handle of async memcpy
36  * @param event Event object, which contains related data, reserved for future
37  * @param cb_args User defined arguments, passed from esp_async_memcpy function
38  * @return Whether a high priority task is woken up by the callback function
39  *
40  * @note User can call OS primitives (semaphore, mutex, etc) in the callback function.
41  *       Keep in mind, if any OS primitive wakes high priority task up, the callback should return true.
42  */
43 typedef bool (*async_memcpy_isr_cb_t)(async_memcpy_t mcp_hdl, async_memcpy_event_t *event, void *cb_args);
44 
45 /**
46  * @brief Type of async memcpy configuration
47  *
48  */
49 typedef struct {
50     uint32_t backlog;          /*!< Maximum number of streams that can be handled simultaneously */
51     size_t sram_trans_align;   /*!< DMA transfer alignment (both in size and address) for SRAM memory */
52     size_t psram_trans_align;  /*!< DMA transfer alignment (both in size and address) for PSRAM memory */
53     uint32_t flags;            /*!< Extra flags to control async memcpy feature */
54 } async_memcpy_config_t;
55 
56 /**
57  * @brief Default configuration for async memcpy
58  *
59  */
60 #define ASYNC_MEMCPY_DEFAULT_CONFIG() \
61     {                                 \
62         .backlog = 8,                 \
63         .sram_trans_align = 0,        \
64         .psram_trans_align = 0,       \
65         .flags = 0,                   \
66     }
67 
68 /**
69  * @brief Install async memcpy driver
70  *
71  * @param[in] config Configuration of async memcpy
72  * @param[out] asmcp Handle of async memcpy that returned from this API. If driver installation is failed, asmcp would be assigned to NULL.
73  * @return
74  *      - ESP_OK: Install async memcpy driver successfully
75  *      - ESP_ERR_INVALID_ARG: Install async memcpy driver failed because of invalid argument
76  *      - ESP_ERR_NO_MEM: Install async memcpy driver failed because out of memory
77  *      - ESP_FAIL: Install async memcpy driver failed because of other error
78  */
79 esp_err_t esp_async_memcpy_install(const async_memcpy_config_t *config, async_memcpy_t *asmcp);
80 
81 /**
82  * @brief Uninstall async memcpy driver
83  *
84  * @param[in] asmcp Handle of async memcpy driver that returned from esp_async_memcpy_install
85  * @return
86  *      - ESP_OK: Uninstall async memcpy driver successfully
87  *      - ESP_ERR_INVALID_ARG: Uninstall async memcpy driver failed because of invalid argument
88  *      - ESP_FAIL: Uninstall async memcpy driver failed because of other error
89  */
90 esp_err_t esp_async_memcpy_uninstall(async_memcpy_t asmcp);
91 
92 /**
93  * @brief Send an asynchronous memory copy request
94  *
95  * @note The callback function is invoked in interrupt context, never do blocking jobs in the callback.
96  *
97  * @param[in] asmcp Handle of async memcpy driver that returned from esp_async_memcpy_install
98  * @param[in] dst Destination address (copy to)
99  * @param[in] src Source address (copy from)
100  * @param[in] n Number of bytes to copy
101  * @param[in] cb_isr Callback function, which got invoked in interrupt context. Set to NULL can bypass the callback.
102  * @param[in] cb_args User defined argument to be passed to the callback function
103  * @return
104  *      - ESP_OK: Send memory copy request successfully
105  *      - ESP_ERR_INVALID_ARG: Send memory copy request failed because of invalid argument
106  *      - ESP_FAIL: Send memory copy request failed because of other error
107  */
108 esp_err_t esp_async_memcpy(async_memcpy_t asmcp, void *dst, void *src, size_t n, async_memcpy_isr_cb_t cb_isr, void *cb_args);
109 
110 /**
111  * @brief Async memory copy specific events that supported by the ETM module
112  */
113 typedef enum {
114     ASYNC_MEMCPY_ETM_EVENT_COPY_DONE, /*!< memory copy finished */
115 } async_memcpy_etm_event_t;
116 
117 /**
118  * @brief Get the ETM event handle for async memcpy done signal
119  *
120  * @note The created ETM event object can be deleted later by calling `esp_etm_del_event`
121  *
122  * @param[in] asmcp Handle of async memcpy driver that returned from `esp_async_memcpy_install`
123  * @param[in] event_type ETM event type
124  * @param[out] out_event Returned ETM event handle
125  * @return
126  * @return
127  *      - ESP_OK: Get ETM event successfully
128  *      - ESP_ERR_INVALID_ARG: Get ETM event failed because of invalid argument
129  *      - ESP_ERR_NOT_SUPPORTED: Get ETM event failed because the DMA hardware doesn't support ETM submodule
130  *      - ESP_FAIL: Get ETM event failed because of other error
131  */
132 esp_err_t esp_async_memcpy_new_etm_event(async_memcpy_t asmcp, async_memcpy_etm_event_t event_type, esp_etm_event_handle_t *out_event);
133 
134 #ifdef __cplusplus
135 }
136 #endif
137