The Async memcpy API

Overview

ESP32-S2 has a DMA engine which can help to offload internal memory copy operations from the CPU in a asynchronous way.

The async memcpy API wraps all DMA configurations and operations, the signature of esp_async_memcpy() is almost the same to the standard libc one.

Thanks to the benefit of the DMA, we don't have to wait for each memory copy to be done before we issue another memcpy request. By the way, it's still possible to know when memcpy is finished by listening in the memcpy callback function.

Note

Memory copy from/to external PSRAM is not supported on ESP32-S2, esp_async_memcpy() will abort returning an error if buffer address is not in SRAM.

Configure and Install driver

esp_async_memcpy_install() is used to install the driver with user's configuration. Please note that async memcpy has to be called with the handle returned from esp_async_memcpy_install().

Driver configuration is described in async_memcpy_config_t:

  • backlog: This is used to configure the maximum number of DMA operations being processed at the same time.

  • sram_trans_align: Declare SRAM alignment for both data address and copy size, set to zero if the data has no restriction in alignment. If set to a quadruple value (i.e. 4X), the driver will enable the burst mode internally, which is helpful for some performance related application.

  • psram_trans_align: Declare PSRAM alignment for both data address and copy size. User has to give it a valid value (only 16, 32, 64 are supported) if the destination of memcpy is located in PSRAM. The default alignment (i.e. 16) will be applied if it's set to zero. Internally, the driver configures the size of block used by DMA to access PSRAM, according to the alignment.

  • flags: This is used to enable some special driver features.

ASYNC_MEMCPY_DEFAULT_CONFIG provides a default configuration, which specifies the backlog to 8.

async_memcpy_config_t config = ASYNC_MEMCPY_DEFAULT_CONFIG();
// update the maximum data stream supported by underlying DMA engine
config.backlog = 16;
async_memcpy_t driver = NULL;
ESP_ERROR_CHECK(esp_async_memcpy_install(&config, &driver)); // install driver, return driver handle

Send memory copy request

esp_async_memcpy() is the API to send memory copy request to DMA engine. It must be called after driver is installed successfully. This API is thread safe, so it can be called from different tasks.

Different from the libc version of memcpy, user should also pass a callback to esp_async_memcpy(), if it's necessary to be notified when the memory copy is done. The callback is executed in the ISR context, make sure you won't violate the restriction applied to ISR handler.

Besides that, the callback function should reside in IRAM space by applying IRAM_ATTR attribute. The prototype of the callback function is async_memcpy_isr_cb_t, please note that, the callback function should return true if it wakes up a high priority task by some API like xSemaphoreGiveFromISR().

// Callback implementation, running in ISR context
static IRAM_ATTR bool my_async_memcpy_cb(async_memcpy_t mcp_hdl, async_memcpy_event_t *event, void *cb_args)
{
    SemaphoreHandle_t sem = (SemaphoreHandle_t)cb_args;
    BaseType_t high_task_wakeup = pdFALSE;
    xSemaphoreGiveFromISR(semphr, &high_task_wakeup); // high_task_wakeup set to pdTRUE if some high priority task unblocked
    return high_task_wakeup == pdTRUE;
}

// Create a semaphore used to report the completion of async memcpy
SemaphoreHandle_t semphr = xSemaphoreCreateBinary();

// Called from user's context
ESP_ERROR_CHECK(esp_async_memcpy(driver_handle, to, from, copy_len, my_async_memcpy_cb, my_semaphore));
// Do something else here
xSemaphoreTake(my_semaphore, portMAX_DELAY); // Wait until the buffer copy is done

Uninstall driver (optional)

esp_async_memcpy_uninstall() is used to uninstall asynchronous memcpy driver. It's not necessary to uninstall the driver after each memcpy operation. If you know your application won't use this driver anymore, then this API can recycle the memory for you.

API Reference

Header File

Functions

esp_err_t esp_async_memcpy_install(const async_memcpy_config_t *config, async_memcpy_t *asmcp)

Install async memcpy driver.

Parameters

  • config -- [in] Configuration of async memcpy

  • asmcp -- [out] Handle of async memcpy that returned from this API. If driver installation is failed, asmcp would be assigned to NULL.

Returns

  • ESP_OK: Install async memcpy driver successfully

  • ESP_ERR_INVALID_ARG: Install async memcpy driver failed because of invalid argument

  • ESP_ERR_NO_MEM: Install async memcpy driver failed because out of memory

  • ESP_FAIL: Install async memcpy driver failed because of other error

esp_err_t esp_async_memcpy_uninstall(async_memcpy_t asmcp)

Uninstall async memcpy driver.

Parameters

asmcp -- [in] Handle of async memcpy driver that returned from esp_async_memcpy_install

Returns

  • ESP_OK: Uninstall async memcpy driver successfully

  • ESP_ERR_INVALID_ARG: Uninstall async memcpy driver failed because of invalid argument

  • ESP_FAIL: Uninstall async memcpy driver failed because of other error

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)

Send an asynchronous memory copy request.

Note

The callback function is invoked in interrupt context, never do blocking jobs in the callback.

Parameters

  • asmcp -- [in] Handle of async memcpy driver that returned from esp_async_memcpy_install

  • dst -- [in] Destination address (copy to)

  • src -- [in] Source address (copy from)

  • n -- [in] Number of bytes to copy

  • cb_isr -- [in] Callback function, which got invoked in interrupt context. Set to NULL can bypass the callback.

  • cb_args -- [in] User defined argument to be passed to the callback function

Returns

  • ESP_OK: Send memory copy request successfully

  • ESP_ERR_INVALID_ARG: Send memory copy request failed because of invalid argument

  • ESP_FAIL: Send memory copy request failed because of other error

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)

Get the ETM event handle for async memcpy done signal.

Note

The created ETM event object can be deleted later by calling esp_etm_del_event

Parameters

  • asmcp -- [in] Handle of async memcpy driver that returned from esp_async_memcpy_install

  • event_type -- [in] ETM event type

  • out_event -- [out] Returned ETM event handle

Returns

Returns

  • ESP_OK: Get ETM event successfully

  • ESP_ERR_INVALID_ARG: Get ETM event failed because of invalid argument

  • ESP_ERR_NOT_SUPPORTED: Get ETM event failed because the DMA hardware doesn't support ETM submodule

  • ESP_FAIL: Get ETM event failed because of other error

Structures

struct async_memcpy_event_t

Type of async memcpy event object.

Public Members

void *data

Event data

struct async_memcpy_config_t

Type of async memcpy configuration.

Public Members

uint32_t backlog

Maximum number of streams that can be handled simultaneously

size_t sram_trans_align

DMA transfer alignment (both in size and address) for SRAM memory

size_t psram_trans_align

DMA transfer alignment (both in size and address) for PSRAM memory

uint32_t flags

Extra flags to control async memcpy feature

Macros

ASYNC_MEMCPY_DEFAULT_CONFIG()

Default configuration for async memcpy.

Type Definitions

typedef struct async_memcpy_context_t *async_memcpy_t

Type of async memcpy handle.

typedef bool (*async_memcpy_isr_cb_t)(async_memcpy_t mcp_hdl, async_memcpy_event_t *event, void *cb_args)

Type of async memcpy interrupt callback function.

Note

User can call OS primitives (semaphore, mutex, etc) in the callback function. Keep in mind, if any OS primitive wakes high priority task up, the callback should return true.

Param mcp_hdl

Handle of async memcpy

Param event

Event object, which contains related data, reserved for future

Param cb_args

User defined arguments, passed from esp_async_memcpy function

Return

Whether a high priority task is woken up by the callback function

Enumerations

enum async_memcpy_etm_event_t

Async memory copy specific events that supported by the ETM module.

Values:

enumerator ASYNC_MEMCPY_ETM_EVENT_COPY_DONE

memory copy finished

Provide feedback about this document