Async Transfer

| Async Transfer

API Reference | Macros | Functions
Async Transfer Utility Library

## General Description

Async Transfer Utility Library provides an implementation of data transfer functions in which the calling application initiates the data transfer on the desired communication peripheral and then the data transfer happens in the background without the application involvement.

This library does not have direct knowledge of the underlying communication peripheral being used and the users of the library shall set up the necessary interface needed to support the background transfer on the specific communication peripheral

Features:

- Both read and write transfers can be performed.
- Transfers can performed via either CPU copy or DMA.
- One transfer in each of direction (read and write) can be pending at the same time.
- A callback can be invoked on completion of a transfer.
- It is possible to query whether an async-transfer instance is available in a given direction.
- An in-progress transfer can be aborted.
- Repeated transfers can be performed without re-initializing.
- Multiple instances of the async transfer library can co-exist, managing different communications interfaces.

# Prerequisites

Setup the interfaces necessary to communicate to the underlying hardware. mtb_async_transfer_interface_t.

Allocate the memory for the context structure and set-up the underlying communication inteface's using mtb_async_transfer_init

For CPU based transfers, the user of async transfer must arrange for mtb_async_transfer_process_fifo_level_event to be invoked, (e.g. by registering an interrupt handler) when FIFO reaches the desired level on the underlying communications interface.

For DMA based transfers, the user of async transfer must arrange for mtb_async_transfer_process_dma_complete to be invoked, (e.g. by registering an interrupt handler) when FIFO reaches the desired level on the underlying communications interface.

Set up the callback to be invoked when the async transfer is complete using mtb_async_transfer_register_callback

# Code Snippets

Init sequence for configuring the async tranfer in CPU mode

/* UART interrupt handler */
void uart_interrupt_handler(void)
{
#if defined(COMPONENT_MTB_HAL)
/* If using the HAL UART */
mtb_hal_uart_process_interrupt(&uart_obj);
#else
mtb_async_transfer_direction_t direction = (mtb_async_transfer_direction_t)0;
/* If using PDL UART */
uint32_t txMasked = Cy_SCB_GetTxInterruptStatusMasked(UART_HW);
uint32_t rxMasked = Cy_SCB_GetRxInterruptStatusMasked(UART_HW);
/* RX FIFO level event */
if (0u != (CY_SCB_UART_RX_TRIGGER & rxMasked))
{
direction = MTB_ASYNC_TRANSFER_DIRECTION_READ;
}
/* TX FIFO level event */
if (0u != (CY_SCB_UART_TX_TRIGGER & txMasked))
{
direction |= MTB_ASYNC_TRANSFER_DIRECTION_WRITE;
}
if (direction)
{
result =
mtb_async_transfer_process_fifo_level_event(async_context,
(mtb_async_transfer_direction_t)direction);
}
#endif // if defined(COMPONENT_MTB_HAL)
}
//--------------------------------------------------------------------------------------------------
// uart_get_num_tx_fifo
//--------------------------------------------------------------------------------------------------
uint32_t uart_get_num_tx_fifo(void* inst_ref)
{
return Cy_SCB_GetFifoSize((CySCB_Type*)inst_ref) - Cy_SCB_UART_GetNumInTxFifo(
(CySCB_Type*)inst_ref);
}
void uart_enable_rx_event(void* inst_ref, bool enable)
{
uint32_t rx_mask = Cy_SCB_GetRxInterruptMask((CySCB_Type*)inst_ref);
rx_mask = (enable ? (rx_mask | CY_SCB_UART_RX_TRIGGER) : (rx_mask & ~CY_SCB_UART_RX_TRIGGER));
Cy_SCB_SetRxInterruptMask((CySCB_Type*)inst_ref, rx_mask);
}
void uart_enable_tx_event(void* inst_ref, bool enable)
{
uint32_t tx_mask = Cy_SCB_GetTxInterruptMask((CySCB_Type*)inst_ref);
tx_mask &= ~CY_SCB_UART_TX_DONE;
tx_mask = (enable ? (tx_mask | CY_SCB_UART_TX_TRIGGER) : (tx_mask & ~CY_SCB_UART_TX_TRIGGER));
Cy_SCB_SetTxInterruptMask((CySCB_Type*)inst_ref, tx_mask);
}
uint32_t uart_get_rx_transfer_len(void* inst_ref)
{
/* RX transfer length is half of the fifo size when flow control is not enabled.
When RTS flow control is enabled return the RTS fifo level */
return (Cy_SCB_GetFifoSize((CySCB_Type*)inst_ref)/2);
}
uint32_t uart_get_tx_transfer_len(void* inst_ref)
{
CY_ASSERT(NULL != inst_ref);
/* TX transfer length is half of the fifo size */
return (Cy_SCB_GetFifoSize((CySCB_Type*)inst_ref)/2);
}
//--------------------------------------------------------------------------------------------------
// uart_get_transfer_width
//--------------------------------------------------------------------------------------------------
uint32_t uart_get_transfer_width(CySCB_Type* base)
{
uint32_t transfer_width = 0;
uint8_t mem_width = _FLD2VAL(SCB_CTRL_MEM_WIDTH, SCB_CTRL(base));
if (CY_SCB_MEM_WIDTH_BYTE == mem_width)
{
transfer_width = 1;
}
else if (CY_SCB_MEM_WIDTH_HALFWORD == mem_width)
{
transfer_width = 2;
}
else
{
transfer_width = 4;
}
return transfer_width;
}
//--------------------------------------------------------------------------------------------------
// snippet_async_transfer_init
//--------------------------------------------------------------------------------------------------
void snippet_async_transfer_cpu_mode(void)
{
/* Snippet example using the UART peripheral driver configured to
use async transfer library in cpu mode */
#define INT_PRIORITY 3
cy_rslt_t result;
cy_stc_scb_uart_context_t uart_context;
mtb_async_transfer_interface_t interface;
/* Pre-requisites
1. Initialize the communication peripheral
2. Configure and enable the FIFO level interrupts.
*/
result = (cy_rslt_t)Cy_SCB_UART_Init(UART_HW, &UART_config, &uart_context);
//Optional. If using the HAL UART
result = mtb_hal_uart_setup(&uart_obj, &UART_hal_config, &uart_context, NULL);
// The UART interrupt handler registration
// UART_IRQ generated by configurator, named <alias>_IRQ
cy_stc_sysint_t intr_cfg = { .intrSrc = UART_IRQ, .intrPriority = INT_PRIORITY };
Cy_SysInt_Init(&intr_cfg, uart_interrupt_handler);
NVIC_EnableIRQ(UART_IRQ);
Cy_SCB_UART_Enable(UART_HW);
memset(&interface, 0, sizeof(mtb_async_transfer_interface_t));
/* Setup the interface parameters with the communication peripheral parameters */
interface.rx_addr = (uint32_t*)&(UART_HW->RX_FIFO_RD);
interface.tx_addr = (uint32_t*)&(UART_HW->TX_FIFO_WR);
/*Set this directly to the communications peripheral object.*/
interface.inst_ref = UART_HW;
interface.get_num_rx_fifo = (mtb_async_transfer_get_num_fifo_t)Cy_SCB_UART_GetNumInRxFifo;
interface.get_num_tx_fifo = (mtb_async_transfer_get_num_fifo_t)uart_get_num_tx_fifo;
interface.set_rx_fifo_level = (mtb_async_transfer_set_fifo_level_t)Cy_SCB_SetRxFifoLevel;
interface.set_tx_fifo_level = (mtb_async_transfer_set_fifo_level_t)Cy_SCB_SetTxFifoLevel;
interface.enable_rx_event = uart_enable_rx_event;
interface.enable_tx_event = uart_enable_tx_event;
interface.get_rx_transfer_len = uart_get_rx_transfer_len;
interface.get_tx_transfer_len = uart_get_tx_transfer_len;
interface.transfer_width = uart_get_transfer_width(UART_HW); /* Read from config
registers */
interface.enter_critical_section = Cy_SysLib_EnterCriticalSection;
interface.exit_critical_section = Cy_SysLib_ExitCriticalSection;
/* Initialialize the async transfer lib */
result = mtb_async_transfer_init(&async_context, &interface);
(void)result;
}
mtb_async_transfer_direction_t
mtb_async_transfer_direction_t
Async Transfer direction
Definition: mtb_async_transfer.h:143
MTB_ASYNC_TRANSFER_DIRECTION_WRITE
@ MTB_ASYNC_TRANSFER_DIRECTION_WRITE
Write Transfer.
Definition: mtb_async_transfer.h:145
MTB_ASYNC_TRANSFER_DIRECTION_READ
@ MTB_ASYNC_TRANSFER_DIRECTION_READ
Read Transfer.
Definition: mtb_async_transfer.h:144
mtb_async_transfer_set_fifo_level_t
void(* mtb_async_transfer_set_fifo_level_t)(void *inst_ref, uint32_t level)
Function pointer to set the fifo level for triggering an interrupt when the number of elements in the...
Definition: mtb_async_transfer.h:175
mtb_async_transfer_get_num_fifo_t
uint32_t(* mtb_async_transfer_get_num_fifo_t)(void *inst_ref)
Function pointer for returning the number of elements that can be read from the FIFO in case of rx or...
Definition: mtb_async_transfer.h:166
mtb_async_transfer_interface_t::enter_critical_section
mtb_async_transfer_enter_critical_section_t enter_critical_section
Function to enter critical section.
Definition: mtb_async_transfer.h:315
mtb_async_transfer_interface_t::inst_ref
void * inst_ref
The opaque pointer that is passed as the first argument to all non-DMA functions.
Definition: mtb_async_transfer.h:258
mtb_async_transfer_interface_t::get_tx_transfer_len
mtb_async_transfer_get_len_t get_tx_transfer_len
Number of elements that the peripheral interface can transmit in a single transfer.
Definition: mtb_async_transfer.h:294
mtb_async_transfer_interface_t::exit_critical_section
mtb_async_transfer_exit_critical_section_t exit_critical_section
Function to exit critical section.
Definition: mtb_async_transfer.h:318
mtb_async_transfer_interface_t::enable_rx_event
mtb_async_transfer_set_enabled_t enable_rx_event
Function to enable/disable RX FIFO level interrupt event.
Definition: mtb_async_transfer.h:279
mtb_async_transfer_interface_t::set_tx_fifo_level
mtb_async_transfer_set_fifo_level_t set_tx_fifo_level
Function to set the TX FIFO level below which the interrupt is triggered.
Definition: mtb_async_transfer.h:276
mtb_async_transfer_interface_t::get_num_rx_fifo
mtb_async_transfer_get_num_fifo_t get_num_rx_fifo
Function to get the number of elements available in the RX FIFO.
Definition: mtb_async_transfer.h:267
mtb_async_transfer_interface_t::enable_tx_event
mtb_async_transfer_set_enabled_t enable_tx_event
Function to enable/disable TX FIFO level interrupt event.
Definition: mtb_async_transfer.h:282
mtb_async_transfer_interface_t::tx_addr
volatile uint32_t * tx_addr
Pointer to the write data destination address.
Definition: mtb_async_transfer.h:264
mtb_async_transfer_interface_t::transfer_width
uint32_t transfer_width
Width, in bytes, of each FIFO element.
Definition: mtb_async_transfer.h:297
mtb_async_transfer_interface_t::set_rx_fifo_level
mtb_async_transfer_set_fifo_level_t set_rx_fifo_level
Function to set the RX FIFO level above which the interrupt is triggered.
Definition: mtb_async_transfer.h:273
mtb_async_transfer_interface_t::rx_addr
volatile uint32_t * rx_addr
Pointer to the read data source address.
Definition: mtb_async_transfer.h:261
mtb_async_transfer_interface_t::get_num_tx_fifo
mtb_async_transfer_get_num_fifo_t get_num_tx_fifo
Function to get the number of elements that can be written to the TX FIFO.
Definition: mtb_async_transfer.h:270
mtb_async_transfer_interface_t::get_rx_transfer_len
mtb_async_transfer_get_len_t get_rx_transfer_len
Number of elements that the peripheral interface can receive in a single transfer.
Definition: mtb_async_transfer.h:291
mtb_async_transfer_interface_t
Async Transfer interface data structure.
Definition: mtb_async_transfer.h:254
mtb_async_transfer_init
cy_rslt_t mtb_async_transfer_init(mtb_async_transfer_context_t *context, const mtb_async_transfer_interface_t *iface)
Initializes an async transfer library instance.
Definition: mtb_async_transfer.c:439
mtb_async_transfer_process_fifo_level_event
cy_rslt_t mtb_async_transfer_process_fifo_level_event(mtb_async_transfer_context_t *context, mtb_async_transfer_direction_t direction)
Handler for when the FIFO in the peripheral reaches the trigger level.
Definition: mtb_async_transfer.c:648

Init sequence for configuring the async tranfer in DMA mode

//--------------------------------------------------------------------------------------------------
// dma_interrupt_handler
//--------------------------------------------------------------------------------------------------
void dma_interrupt_handler(void)
{
cy_rslt_t result;
#if defined(COMPONENT_MTB_HAL)
//If using the HAL DMA
mtb_hal_dma_process_interrupt(&dma_obj);
#else
cy_en_dma_intr_cause_t cause = Cy_DMA_Channel_GetStatus(DMA_HW, DMA_CHANNEL);
Cy_DMA_Channel_ClearInterrupt(DMA_HW, DMA_CHANNEL);
if (cause == CY_DMA_INTR_CAUSE_COMPLETION)
{
/* Select the direction as read or write based on if the DMA channel is configured for read
or write */
result = mtb_async_transfer_process_dma_complete(&async_context,
MTB_ASYNC_TRANSFER_DIRECTION_READ);
}
#endif // if defined(COMPONENT_MTB_HAL)
(void)result;
}
//--------------------------------------------------------------------------------------------------
// uart_dma_set_src_addr
//--------------------------------------------------------------------------------------------------
cy_rslt_t uart_dma_set_src_addr(void* dma_ref, void* addr)
{
Cy_DMA_Descriptor_SetSrcAddress((cy_stc_dma_descriptor_t*)dma_ref, addr);
return CY_RSLT_SUCCESS;
}
//--------------------------------------------------------------------------------------------------
// uart_dma_set_dest_addr
//--------------------------------------------------------------------------------------------------
cy_rslt_t uart_dma_set_dest_addr(void* dma_ref, void* addr)
{
Cy_DMA_Descriptor_SetDstAddress((cy_stc_dma_descriptor_t*)dma_ref, addr);
return CY_RSLT_SUCCESS;
}
//--------------------------------------------------------------------------------------------------
// uart_dma_set_len
//--------------------------------------------------------------------------------------------------
cy_rslt_t uart_dma_set_len(void* dma_ref, size_t len)
{
//Set the length based on the descriptor type
Cy_DMA_Descriptor_SetXloopDataCount((cy_stc_dma_descriptor_t*)dma_ref, len);
return CY_RSLT_SUCCESS;
}
//--------------------------------------------------------------------------------------------------
// uart_dma_enable_rx
//--------------------------------------------------------------------------------------------------
void uart_dma_enable_rx(void* dma_ref, bool enable)
{
enable ? Cy_DMA_Channel_Enable(DMA_HW, DMA_CHANNEL) : Cy_DMA_Channel_Disable(DMA_HW,
DMA_CHANNEL);
(void)dma_ref;
}
//--------------------------------------------------------------------------------------------------
// snippet_async_transfer_dma_mode
//--------------------------------------------------------------------------------------------------
void snippet_async_transfer_dma_mode(void)
{
/* Snippet example using the UART peripheral driver configured to
use async transfer library in dma mode */
#define INT_PRIORITY 3
cy_rslt_t result;
cy_en_dma_status_t status;
cy_stc_scb_uart_context_t uart_context;
mtb_async_transfer_interface_t interface;
/* Pre-requisites
1. Initialize the communication peripheral
2. Configure and enable the FIFO level interrupts.
3. Configure and enable the DMA channels if DMA mode async transfer is desired
4. Configure the routing between the communication peripheral and DMA if DMA mode async
transfer is desired
*/
/* Setting up the descriptor and the channel */
status = Cy_DMA_Descriptor_Init(&dma_Descriptor_0, &dma_Descriptor_0_config);
status = Cy_DMA_Channel_Init(DMA_HW, DMA_CHANNEL, &dma_channelConfig);
Cy_DMA_Channel_SetInterruptMask(DMA_HW, DMA_CHANNEL, CY_DMA_INTR_MASK);
//Optional. If using the HAL DMA
result = mtb_hal_dma_setup(&dma_obj, &dma_hal_config);
cy_stc_sysint_t dma_intr_cfg = { .intrSrc = DMA_IRQ, .intrPriority = INT_PRIORITY };
Cy_SysInt_Init(&dma_intr_cfg, dma_interrupt_handler);
NVIC_EnableIRQ(DMA_IRQ);
Cy_DMA_Enable(DMA_HW);
result = (cy_rslt_t)Cy_SCB_UART_Init(UART_HW, &UART_config, &uart_context);
//Optional. If using the HAL UART
result = mtb_hal_uart_setup(&uart_obj, &UART_hal_config, &uart_context, NULL);
// The UART interrupt handler registration
// UART_IRQ generated by configurator, named <alias>_IRQ
cy_stc_sysint_t intr_cfg = { .intrSrc = UART_IRQ, .intrPriority = INT_PRIORITY };
Cy_SysInt_Init(&intr_cfg, uart_interrupt_handler);
NVIC_EnableIRQ(UART_IRQ);
Cy_SCB_UART_Enable(UART_HW);
memset(&interface, 0, sizeof(mtb_async_transfer_interface_t));
/* Setup the interface parameters with the communication peripheral parameters */
interface.rx_addr = (uint32_t*)&(UART_HW->RX_FIFO_RD);
interface.tx_addr = (uint32_t*)&(UART_HW->TX_FIFO_WR);
/* Set this directly to the communications peripheral object.*/
interface.inst_ref = UART_HW;
interface.get_num_rx_fifo = (mtb_async_transfer_get_num_fifo_t)Cy_SCB_UART_GetNumInRxFifo;
interface.get_num_tx_fifo = (mtb_async_transfer_get_num_fifo_t)uart_get_num_tx_fifo;
interface.set_rx_fifo_level = (mtb_async_transfer_set_fifo_level_t)Cy_SCB_SetRxFifoLevel;
interface.set_tx_fifo_level = (mtb_async_transfer_set_fifo_level_t)Cy_SCB_SetTxFifoLevel;
interface.enable_rx_event = uart_enable_rx_event;
interface.enable_tx_event = uart_enable_tx_event;
interface.get_rx_transfer_len = uart_get_rx_transfer_len;
interface.get_tx_transfer_len = uart_get_tx_transfer_len;
interface.transfer_width = uart_get_transfer_width(UART_HW); /* Read from config
registers */
interface.enter_critical_section = Cy_SysLib_EnterCriticalSection;
interface.exit_critical_section = Cy_SysLib_ExitCriticalSection;
/* DMA specfic interface parameters */
/* Using the PDL functions. Use HAL DMA functions when HAL drivers are used */
interface.dma_rx_ref = &dma_Descriptor_0; //Use HAL DMA object when HAL DMA is used
interface.dma_tx_ref = NULL; //Set if tx dma is needed
interface.dma_set_length = uart_dma_set_len;
interface.dma_set_src = uart_dma_set_src_addr;
interface.dma_set_dest = uart_dma_set_dest_addr;
interface.dma_enable_rx = uart_dma_enable_rx;
interface.dma_enable_tx = NULL; //Set if tx dma is needed
/* Initialize the async transfer lib */
result = mtb_async_transfer_init(&async_context, &interface);
(void)status;
(void)result;
}
mtb_async_transfer_interface_t::dma_enable_rx
mtb_async_transfer_set_enabled_t dma_enable_rx
Function to enable/disable RX DMA event and RX DMA channel.
Definition: mtb_async_transfer.h:285
mtb_async_transfer_interface_t::dma_set_length
mtb_async_transfer_dma_set_len_t dma_set_length
Function to set the DMA transfer length.
Definition: mtb_async_transfer.h:306
mtb_async_transfer_interface_t::dma_enable_tx
mtb_async_transfer_set_enabled_t dma_enable_tx
Function to enable/disable TX DMA event and TX DMA channel.
Definition: mtb_async_transfer.h:288
mtb_async_transfer_interface_t::dma_set_src
mtb_async_transfer_dma_set_addr_t dma_set_src
Function to set the DMA source address.
Definition: mtb_async_transfer.h:309
mtb_async_transfer_interface_t::dma_tx_ref
void * dma_tx_ref
Opaque pointer that is passed as the first argument when operating on the TX DMA.
Definition: mtb_async_transfer.h:303
mtb_async_transfer_interface_t::dma_rx_ref
void * dma_rx_ref
Opaque pointer that is passed as the first argument when operating on the RX DMA.
Definition: mtb_async_transfer.h:300
mtb_async_transfer_interface_t::dma_set_dest
mtb_async_transfer_dma_set_addr_t dma_set_dest
Function to set the DMA destination address.
Definition: mtb_async_transfer.h:312
mtb_async_transfer_process_dma_complete
cy_rslt_t mtb_async_transfer_process_dma_complete(mtb_async_transfer_context_t *context, mtb_async_transfer_direction_t direction)
Handler for when a DMA transfer is complete.
Definition: mtb_async_transfer.c:678

Read operation

result = mtb_async_transfer_read(&async_context, rx_buffer, sizeof(rx_buffer));
mtb_async_transfer_read
cy_rslt_t mtb_async_transfer_read(mtb_async_transfer_context_t *context, void *dest, size_t length)
Reads data from the peripheral to the memory in the background.
Definition: mtb_async_transfer.c:457

Write operation

result = mtb_async_transfer_write(&async_context, tx_buffer, sizeof(tx_buffer));
mtb_async_transfer_write
cy_rslt_t mtb_async_transfer_write(mtb_async_transfer_context_t *context, void *source, uint32_t length)
Writes data from memory to the peripheral in the background.
Definition: mtb_async_transfer.c:505

## API Reference
| Enumerated Types
| Function Pointers
| Data Structures

## Macros
#define | MTB_ASYNC_TRANSFER_BAD_PARAM_ERROR CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_MIDDLEWARE_ASYNC_TRANSFER, 0)
| An invalid parameter value is passed in.
#define | MTB_ASYNC_TRANSFER_READ_BUSY CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_MIDDLEWARE_ASYNC_TRANSFER, 1)
| A read transfer is already in progress.
#define | MTB_ASYNC_TRANSFER_WRITE_BUSY CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_MIDDLEWARE_ASYNC_TRANSFER, 2)
| A write transfer is already in progress.
#define | MTB_ASYNC_TRANSFER_READ_ERROR CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_MIDDLEWARE_ASYNC_TRANSFER, 3)
| An error occurred when performing read transfer.
#define | MTB_ASYNC_TRANSFER_WRITE_ERROR CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_MIDDLEWARE_ASYNC_TRANSFER, 4)
| An error occurred when performing write transfer.
#define | MTB_ASYNC_TRANSFER_READ_WRITE_ERROR CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_MIDDLEWARE_ASYNC_TRANSFER, 5)
| An error occurred when performing both read and write transfer.

## Functions
cy_rslt_t | mtb_async_transfer_init (mtb_async_transfer_context_t *context, const mtb_async_transfer_interface_t *iface)
| Initializes an async transfer library instance. More...
cy_rslt_t | mtb_async_transfer_read (mtb_async_transfer_context_t *context, void *dest, size_t length)
| Reads data from the peripheral to the memory in the background. More...
cy_rslt_t | mtb_async_transfer_write (mtb_async_transfer_context_t *context, void *source, uint32_t length)
| Writes data from memory to the peripheral in the background. More...
bool | mtb_async_transfer_available_read (const mtb_async_transfer_context_t *context)
| Checks whether the async-transfer instance is available to start a read transfer. More...
bool | mtb_async_transfer_available_write (const mtb_async_transfer_context_t *context)
| Checks whether the async-transfer instance is available to start a write transfer. More...
cy_rslt_t | mtb_async_transfer_abort_read (mtb_async_transfer_context_t *context)
| Stops an in-progress read transfer. More...
cy_rslt_t | mtb_async_transfer_abort_write (mtb_async_transfer_context_t *context)
| Stops an in-progress write transfer. More...
cy_rslt_t | mtb_async_transfer_register_callback (mtb_async_transfer_context_t *context, mtb_async_transfer_event_callback_t callback, void *arg)
| Register a callback to be invoked when a transfer is complete. More...
cy_rslt_t | mtb_async_transfer_process_fifo_level_event (mtb_async_transfer_context_t *context, mtb_async_transfer_direction_t direction)
| Handler for when the FIFO in the peripheral reaches the trigger level. More...
cy_rslt_t | mtb_async_transfer_process_dma_complete (mtb_async_transfer_context_t *context, mtb_async_transfer_direction_t direction)
| Handler for when a DMA transfer is complete. More...

## Function Documentation

## ◆ mtb_async_transfer_init()

cy_rslt_t mtb_async_transfer_init | ( | mtb_async_transfer_context_t * | context,
|  | const mtb_async_transfer_interface_t * | iface
| ) |  |

Initializes an async transfer library instance.

Parameters

  [in,out] | context | Stores state that async-transfer needs to track between calls. The caller must allocate memory for this struct but should not depend on its contents.
  [in] | iface | Defines the interaction between this async-transfer instance and the peripheral that it is transferring data to/from.

Note
  It is safe to free `iface` or let it go out of scope after this function returns

Returns
  the status of the initialization

## ◆ mtb_async_transfer_read()

cy_rslt_t mtb_async_transfer_read | ( | mtb_async_transfer_context_t * | context,
|  | void * | dest,
|  | size_t | length
| ) |  |

Reads data from the peripheral to the memory in the background.

If D-cache is enabled and DMA is used, the user needs to make sure that the dest pointer passed to the mtb_async_transfer_read function points to a buffer which is aligned to the cache line size (__SCB_DCACHE_LINE_SIZE). The length of buffer data must be a multiple of the cache line size to ensure cache coherency. CY_ALIGN(__SCB_DCACHE_LINE_SIZE) macro can be used for alignment.

Refer to DCACHE_Management for more information.

Parameters

  [in,out] | context | The context object for this peripheral that was populated by mtb_async_transfer_init
  [in,out] | dest | Pointer to the buffer to which the data read from the peripheral should be stored. This buffer must remain valid for the duration of the transfer, and its contents should not be accessed until the read transfer is complete.
  [in] | length | Length, in bytes, of the data that is to be read

Note
  This function modifies the RX FIFO level depending on the number of bytes to receive. User is expected to set it back to the original RX FIFO level after the read is complete, if desired.

Returns
  the status of starting the read

## ◆ mtb_async_transfer_write()

cy_rslt_t mtb_async_transfer_write | ( | mtb_async_transfer_context_t * | context,
|  | void * | source,
|  | uint32_t | length
| ) |  |

Writes data from memory to the peripheral in the background.

If D-cache is enabled and DMA is used, the user needs to make sure that the source pointer passed to the mtb_async_transfer_write function points to a buffer which is aligned to the cache line size (__SCB_DCACHE_LINE_SIZE). The length of buffer data must be a multiple of the cache line size to ensure cache coherency. CY_ALIGN(__SCB_DCACHE_LINE_SIZE) macro can be used for alignment.

Refer to DCACHE_Management for more information.

Parameters

  [in,out] | context | The context object for this peripheral that was populated by mtb_async_transfer_init
  [in] | source | Pointer to the data that is to be written to the peripheral This buffer must remain valid for the duration of the transfer, and its contents should not be accessed until the write transfer is complete.
  [in] | length | Length, in bytes, of the data that is to be written to the peripheral

Note
  This function modifies the TX FIFO level depending on the number of bytes to transmit. User is expected to set it back to the original TX FIFO level after the write is complete, if desired.

Returns
  the status of starting the write

## ◆ mtb_async_transfer_available_read()

bool mtb_async_transfer_available_read | ( | const mtb_async_transfer_context_t * | context | ) |

Checks whether the async-transfer instance is available to start a read transfer.

An instance is available to start a read transfer if there is no read transfer currently waiting to complete

Parameters

  [in,out] | context | The context object for this peripheral that was populated by mtb_async_transfer_init

Returns
  True if a read transfer can be started, false if there is a read transfer in progress

## ◆ mtb_async_transfer_available_write()

bool mtb_async_transfer_available_write | ( | const mtb_async_transfer_context_t * | context | ) |

Checks whether the async-transfer instance is available to start a write transfer.

An instance is available to start a write transfer if there is no write transfer currently waiting to complete

Parameters

  [in,out] | context | The context object for this peripheral that was populated by mtb_async_transfer_init

Returns
  True if a write transfer can be started, false if there is a write transfer in progress

## ◆ mtb_async_transfer_abort_read()

cy_rslt_t mtb_async_transfer_abort_read | ( | mtb_async_transfer_context_t * | context | ) |

Stops an in-progress read transfer.

Parameters

  [in,out] | context | The context object for this peripheral that was populated by mtb_async_transfer_init

Returns
  the status of aborting the read

## ◆ mtb_async_transfer_abort_write()

cy_rslt_t mtb_async_transfer_abort_write | ( | mtb_async_transfer_context_t * | context | ) |

Stops an in-progress write transfer.

Parameters

  [in,out] | context | The context object for this peripheral that was populated by mtb_async_transfer_init

Note
  This only aborts the transfer of data into the hardware FIFO. Data which was already written into the FIFO may still be written even after this function returns.

Returns
  the status of aborting the write

## ◆ mtb_async_transfer_register_callback()

cy_rslt_t mtb_async_transfer_register_callback | ( | mtb_async_transfer_context_t * | context,
|  | mtb_async_transfer_event_callback_t | callback,
|  | void * | arg
| ) |  |

Register a callback to be invoked when a transfer is complete.

Note
  For read, "complete" means that the requested amount of data has been copied into the destination buffer. For write, "complete" means that the requested amount of data has been written into the buffer in the peripheral.It does not mean that all of the data has been sent out over the communications interface. Such a status should be checked via the driver for the underlying peripheral.

Parameters

  [in,out] | context | The context object for this peripheral that was populated by mtb_async_transfer_init
  [in] | callback | The callback to register. This will replace any previously registered callback. A value of `NULL` for this parameter will result in no callback being registered.
  [in,out] | arg | An arbitrary pointer, which will be passed to the callback when it is invoked.

Returns
  the status of registering the callback

Register a callback to be invoked when a transfer is complete.

## ◆ mtb_async_transfer_process_fifo_level_event()

cy_rslt_t mtb_async_transfer_process_fifo_level_event | ( | mtb_async_transfer_context_t * | context,
|  | mtb_async_transfer_direction_t | direction
| ) |  |

Handler for when the FIFO in the peripheral reaches the trigger level.

The user of async-transfer must arrange for this function to be invoked (e.g. by registering an interrupt handler) when this event occurs

Parameters

  [in,out] | context | The context object for this peripheral that was populated by mtb_async_transfer_init
  [in] | direction | The direction (read or write) in which this event occurred

Returns
  the status of handling the event

## ◆ mtb_async_transfer_process_dma_complete()

cy_rslt_t mtb_async_transfer_process_dma_complete | ( | mtb_async_transfer_context_t * | context,
|  | mtb_async_transfer_direction_t | direction
| ) |  |

Handler for when a DMA transfer is complete.

The user of async-transfer must arrange for this function to be invoked (e.g. by registering an interrupt handler) when this event occurs

Parameters

  [in,out] | context | The context object for this peripheral that was populated by mtb_async_transfer_init
  [in] | direction | The direction (read or write) in which this event occurred

Returns
  the status of handling the event