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.

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.
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.
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.
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.
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.
cy_rslt_t	mtb_async_transfer_abort_read (mtb_async_transfer_context_t *context)
	Stops an in-progress read transfer.
cy_rslt_t	mtb_async_transfer_abort_write (mtb_async_transfer_context_t *context)
	Stops an in-progress write transfer.
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.
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.
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.

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 section of the README.md 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 section of the README.md 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