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 #pragma once 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 #include <stdint.h> 22 #include <stdbool.h> 23 #include "esp_err.h" 24 25 /** 26 * @brief Type of async memcpy handle 27 * 28 */ 29 typedef struct async_memcpy_context_t *async_memcpy_t; 30 31 /** 32 * @brief Type of async memcpy event object 33 * 34 */ 35 typedef struct { 36 void *data; /*!< Event data */ 37 } async_memcpy_event_t; 38 39 /** 40 * @brief Type of async memcpy interrupt callback function 41 * 42 * @param mcp_hdl Handle of async memcpy 43 * @param event Event object, which contains related data, reserved for future 44 * @param cb_args User defined arguments, passed from esp_async_memcpy function 45 * @return Whether a high priority task is woken up by the callback function 46 * 47 * @note User can call OS primitives (semaphore, mutex, etc) in the callback function. 48 * Keep in mind, if any OS primitive wakes high priority task up, the callback should return true. 49 */ 50 typedef bool (*async_memcpy_isr_cb_t)(async_memcpy_t mcp_hdl, async_memcpy_event_t *event, void *cb_args); 51 52 /** 53 * @brief Type of async memcpy configuration 54 * 55 */ 56 typedef struct { 57 uint32_t backlog; /*!< Maximum number of streams that can be handled simultaneously */ 58 uint32_t flags; /*!< Extra flags to control async memcpy feature */ 59 } async_memcpy_config_t; 60 61 /** 62 * @brief Default configuration for async memcpy 63 * 64 */ 65 #define ASYNC_MEMCPY_DEFAULT_CONFIG() \ 66 { \ 67 .backlog = 8, \ 68 .flags = 0, \ 69 } 70 71 /** 72 * @brief Install async memcpy driver 73 * 74 * @param[in] config Configuration of async memcpy 75 * @param[out] asmcp Handle of async memcpy that returned from this API. If driver installation is failed, asmcp would be assigned to NULL. 76 * @return 77 * - ESP_OK: Install async memcpy driver successfully 78 * - ESP_ERR_INVALID_ARG: Install async memcpy driver failed because of invalid argument 79 * - ESP_ERR_NO_MEM: Install async memcpy driver failed because out of memory 80 * - ESP_FAIL: Install async memcpy driver failed because of other error 81 */ 82 esp_err_t esp_async_memcpy_install(const async_memcpy_config_t *config, async_memcpy_t *asmcp); 83 84 /** 85 * @brief Uninstall async memcpy driver 86 * 87 * @param[in] asmcp Handle of async memcpy driver that returned from esp_async_memcpy_install 88 * @return 89 * - ESP_OK: Uninstall async memcpy driver successfully 90 * - ESP_ERR_INVALID_ARG: Uninstall async memcpy driver failed because of invalid argument 91 * - ESP_FAIL: Uninstall async memcpy driver failed because of other error 92 */ 93 esp_err_t esp_async_memcpy_uninstall(async_memcpy_t asmcp); 94 95 /** 96 * @brief Send an asynchronous memory copy request 97 * 98 * @param[in] asmcp Handle of async memcpy driver that returned from esp_async_memcpy_install 99 * @param[in] dst Destination address (copy to) 100 * @param[in] src Source address (copy from) 101 * @param[in] n Number of bytes to copy 102 * @param[in] cb_isr Callback function, which got invoked in interrupt context. Set to NULL can bypass the callback. 103 * @param[in] cb_args User defined argument to be passed to the callback function 104 * @return 105 * - ESP_OK: Send memory copy request successfully 106 * - ESP_ERR_INVALID_ARG: Send memory copy request failed because of invalid argument 107 * - ESP_FAIL: Send memory copy request failed because of other error 108 * 109 * @note The callback function is invoked in interrupt context, never do blocking jobs in the callback. 110 */ 111 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); 112 113 #ifdef __cplusplus 114 } 115 #endif 116