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