Detailed Description

Interface for data transfer functions.

Summary

The transfer interface supports background data transfer (no CPU intervention).

Data Structures
struct	transfer_callback_args_t

struct	transfer_properties_t

struct	transfer_info_t

struct	transfer_cfg_t

struct	transfer_api_t

struct	transfer_instance_t

Typedefs
typedef void	transfer_ctrl_t

Enumerations
enum	transfer_mode_t

enum	transfer_size_t

enum	transfer_addr_mode_t

enum	transfer_repeat_area_t

enum	transfer_chain_mode_t

enum	transfer_irq_t

enum	transfer_start_mode_t

Data Structure Documentation

◆ transfer_callback_args_t

struct transfer_callback_args_t

Callback function parameter data.

Data Fields
void const *	p_context	Placeholder for user data. Set in transfer_api_t::open function in transfer_cfg_t.

◆ transfer_properties_t

struct transfer_properties_t

Driver specific information.

Data Fields
uint32_t	block_count_max	Maximum number of blocks.
uint32_t	block_count_remaining	Number of blocks remaining.
uint32_t	transfer_length_max	Maximum number of transfers.
uint32_t	transfer_length_remaining	Number of transfers remaining.

◆ transfer_info_t

struct transfer_info_t

This structure specifies the properties of the transfer.

Warning: When using DTC, this structure corresponds to the descriptor block registers required by the DTC. The following components may be modified by the driver: p_src, p_dest, num_blocks, and length.; When using DTC, do NOT reuse this structure to configure multiple transfers. Each transfer must have a unique transfer_info_t.; When using DTC, this structure must not be allocated in a temporary location. Any instance of this structure must remain in scope until the transfer it is used for is closed.

Note: When using DTC, consider placing instances of this structure in a protected section of memory.

Data Fields
union transfer_info_t	__unnamed__
void const *volatile	p_src	Source pointer.
void *volatile	p_dest	Destination pointer.
volatile uint16_t	num_blocks	Number of blocks to transfer when using TRANSFER_MODE_BLOCK (both DTC an DMAC) or TRANSFER_MODE_REPEAT (DMAC only) or TRANSFER_MODE_REPEAT_BLOCK (DMAC only), unused in other modes.
volatile uint16_t	length	Length of each transfer. Range limited for TRANSFER_MODE_BLOCK, TRANSFER_MODE_REPEAT, and TRANSFER_MODE_REPEAT_BLOCK see HAL driver for details.

◆ transfer_cfg_t

struct transfer_cfg_t

Driver configuration set in transfer_api_t::open. All elements except p_extend are required and must be initialized.

Data Fields
transfer_info_t *	p_info	Pointer to transfer configuration options. If using chain transfer (DTC only), this can be a pointer to an array of chained transfers that will be completed in order.
void const *	p_extend	Extension parameter for hardware specific settings.

◆ transfer_api_t

struct transfer_api_t

Transfer functions implemented at the HAL layer will follow this API.

Data Fields
fsp_err_t(*	open )(transfer_ctrl_t const p_ctrl, transfer_cfg_t const const p_cfg)

fsp_err_t(*	reconfigure )(transfer_ctrl_t const p_ctrl, transfer_info_t p_info)

fsp_err_t(*	reset )(transfer_ctrl_t const p_ctrl, void const p_src, void *p_dest, uint16_t const num_transfers)

fsp_err_t(*	enable )(transfer_ctrl_t *const p_ctrl)

fsp_err_t(*	disable )(transfer_ctrl_t *const p_ctrl)

fsp_err_t(*	softwareStart )(transfer_ctrl_t *const p_ctrl, transfer_start_mode_t mode)

fsp_err_t(*	softwareStop )(transfer_ctrl_t *const p_ctrl)

fsp_err_t(*	infoGet )(transfer_ctrl_t const p_ctrl, transfer_properties_t const p_properties)

fsp_err_t(*	close )(transfer_ctrl_t *const p_ctrl)

fsp_err_t(*	reload )(transfer_ctrl_t const p_ctrl, void const p_src, void *p_dest, uint32_t const num_transfers)

fsp_err_t(*	callbackSet )(transfer_ctrl_t const p_ctrl, void(p_callback)(transfer_callback_args_t ), void const const p_context, transfer_callback_args_t *const p_callback_memory)

Field Documentation

◆ open

fsp_err_t(* transfer_api_t::open) (transfer_ctrl_t *const p_ctrl, transfer_cfg_t const *const p_cfg)

Initial configuration.

Parameters

[in,out]	p_ctrl	Pointer to control block. Must be declared by user. Elements set here.
[in]	p_cfg	Pointer to configuration structure. All elements of this structure must be set by user.

◆ reconfigure

fsp_err_t(* transfer_api_t::reconfigure) (transfer_ctrl_t *const p_ctrl, transfer_info_t *p_info)

Reconfigure the transfer. Enable the transfer if p_info is valid.

Parameters

[in,out]	p_ctrl	Pointer to control block. Must be declared by user. Elements set here.
[in]	p_info	Pointer to a new transfer info structure.

◆ reset

fsp_err_t(* transfer_api_t::reset) (transfer_ctrl_t *const p_ctrl, void const *p_src, void *p_dest, uint16_t const num_transfers)

Reset source address pointer, destination address pointer, and/or length, keeping all other settings the same. Enable the transfer if p_src, p_dest, and length are valid.

Parameters

[in]	p_ctrl	Control block set in transfer_api_t::open call for this transfer.
[in]	p_src	Pointer to source. Set to NULL if source pointer should not change.
[in]	p_dest	Pointer to destination. Set to NULL if destination pointer should not change.
[in]	num_transfers	Transfer length in normal mode or number of blocks in block mode. In DMAC only, resets number of repeats (initially stored in transfer_info_t::num_blocks) in repeat mode. Not used in repeat mode for DTC.

◆ enable

fsp_err_t(* transfer_api_t::enable) (transfer_ctrl_t *const p_ctrl)

Enable transfer. Transfers occur after the activation source event (or when transfer_api_t::softwareStart is called if no peripheral event is chosen as activation source).

Parameters

[in] p_ctrl Control block set in transfer_api_t::open call for this transfer.

◆ disable

fsp_err_t(* transfer_api_t::disable) (transfer_ctrl_t *const p_ctrl)

Disable transfer. Transfers do not occur after the activation source event (or when transfer_api_t::softwareStart is called if no peripheral event is chosen as the DMAC activation source).

Note: If a transfer is in progress, it will be completed. Subsequent transfer requests do not cause a transfer.

Parameters

[in] p_ctrl Control block set in transfer_api_t::open call for this transfer.

◆ softwareStart

fsp_err_t(* transfer_api_t::softwareStart) (transfer_ctrl_t *const p_ctrl, transfer_start_mode_t mode)

Start transfer in software.

Warning: Only works if no peripheral event is chosen as the DMAC activation source.

Note: Not supported for DTC.

Parameters

[in]	p_ctrl	Control block set in transfer_api_t::open call for this transfer.
[in]	mode	Select mode from transfer_start_mode_t.

◆ softwareStop

fsp_err_t(* transfer_api_t::softwareStop) (transfer_ctrl_t *const p_ctrl)

Stop transfer in software. The transfer will stop after completion of the current transfer.

Note: Not supported for DTC.; Only applies for transfers started with TRANSFER_START_MODE_REPEAT.

Warning: Only works if no peripheral event is chosen as the DMAC activation source.

Parameters

[in] p_ctrl Control block set in transfer_api_t::open call for this transfer.

◆ infoGet

fsp_err_t(* transfer_api_t::infoGet) (transfer_ctrl_t *const p_ctrl, transfer_properties_t *const p_properties)

Provides information about this transfer.

Parameters

[in]	p_ctrl	Control block set in transfer_api_t::open call for this transfer.
[out]	p_properties	Driver specific information.

◆ close

fsp_err_t(* transfer_api_t::close) (transfer_ctrl_t *const p_ctrl)

Releases hardware lock. This allows a transfer to be reconfigured using transfer_api_t::open.

Parameters

[in] p_ctrl Control block set in transfer_api_t::open call for this transfer.

◆ reload

fsp_err_t(* transfer_api_t::reload) (transfer_ctrl_t *const p_ctrl, void const *p_src, void *p_dest, uint32_t const num_transfers)

To update next transfer information without interruption during transfer. Allow further transfer continuation.

Parameters

[in]	p_ctrl	Control block set in transfer_api_t::open call for this transfer.
[in]	p_src	Pointer to source. Set to NULL if source pointer should not change.
[in]	p_dest	Pointer to destination. Set to NULL if destination pointer should not change.
[in]	num_transfers	Transfer length in normal mode or block mode.

◆ callbackSet

fsp_err_t(* transfer_api_t::callbackSet) (transfer_ctrl_t *const p_ctrl, void(*p_callback)(transfer_callback_args_t *), void const *const p_context, transfer_callback_args_t *const p_callback_memory)

Specify callback function and optional context pointer and working memory pointer.

Parameters

[in]	p_ctrl	Control block set in transfer_api_t::open call for this transfer.
[in]	p_callback	Callback function to register
[in]	p_context	Pointer to send to callback function
[in]	p_callback_memory	Pointer to volatile memory where callback structure can be allocated. Callback arguments allocated here are only valid during the callback.

◆ transfer_instance_t

struct transfer_instance_t

This structure encompasses everything that is needed to use an instance of this interface.

Data Fields
transfer_ctrl_t *	p_ctrl	Pointer to the control structure for this instance.
transfer_cfg_t const *	p_cfg	Pointer to the configuration structure for this instance.
transfer_api_t const *	p_api	Pointer to the API structure for this instance.

Typedef Documentation

◆ transfer_ctrl_t

typedef void transfer_ctrl_t

Transfer control block. Allocate an instance specific control block to pass into the transfer API calls.

Enumeration Type Documentation

◆ transfer_mode_t

enum transfer_mode_t

Transfer mode describes what will happen when a transfer request occurs.

Enumerator
TRANSFER_MODE_NORMAL	In normal mode, each transfer request causes a transfer of transfer_size_t from the source pointer to the destination pointer. The transfer length is decremented and the source and address pointers are updated according to transfer_addr_mode_t. After the transfer length reaches 0, transfer requests will not cause any further transfers.
TRANSFER_MODE_REPEAT	Repeat mode is like normal mode, except that when the transfer length reaches 0, the pointer to the repeat area and the transfer length will be reset to their initial values. If DMAC is used, the transfer repeats only transfer_info_t::num_blocks times. After the transfer repeats transfer_info_t::num_blocks times, transfer requests will not cause any further transfers. If DTC is used, the transfer repeats continuously (no limit to the number of repeat transfers).
TRANSFER_MODE_BLOCK	In block mode, each transfer request causes transfer_info_t::length transfers of transfer_size_t. After each individual transfer, the source and destination pointers are updated according to transfer_addr_mode_t. After the block transfer is complete, transfer_info_t::num_blocks is decremented. After the transfer_info_t::num_blocks reaches 0, transfer requests will not cause any further transfers.
TRANSFER_MODE_REPEAT_BLOCK	In addition to block mode features, repeat-block mode supports a ring buffer of blocks and offsets within a block (to split blocks into arrays of their first data, second data, etc.)

◆ transfer_size_t

enum transfer_size_t

Transfer size specifies the size of each individual transfer. Total transfer length = transfer_size_t * transfer_length_t

Enumerator
TRANSFER_SIZE_1_BYTE	Each transfer transfers a 8-bit value.
TRANSFER_SIZE_2_BYTE	Each transfer transfers a 16-bit value.
TRANSFER_SIZE_4_BYTE	Each transfer transfers a 32-bit value.
TRANSFER_SIZE_8_BYTE	Each transfer transfers a 64-bit value.

◆ transfer_addr_mode_t

enum transfer_addr_mode_t

Address mode specifies whether to modify (increment or decrement) pointer after each transfer.

Enumerator
TRANSFER_ADDR_MODE_FIXED	Address pointer remains fixed after each transfer.
TRANSFER_ADDR_MODE_OFFSET	Offset is added to the address pointer after each transfer.
TRANSFER_ADDR_MODE_INCREMENTED	Address pointer is incremented by associated transfer_size_t after each transfer.
TRANSFER_ADDR_MODE_DECREMENTED	Address pointer is decremented by associated transfer_size_t after each transfer.

◆ transfer_repeat_area_t

enum transfer_repeat_area_t

Repeat area options (source or destination). In TRANSFER_MODE_REPEAT, the selected pointer returns to its original value after transfer_info_t::length transfers. In TRANSFER_MODE_BLOCK and TRANSFER_MODE_REPEAT_BLOCK, the selected pointer returns to its original value after each transfer.

Enumerator
TRANSFER_REPEAT_AREA_DESTINATION	Destination area repeated in TRANSFER_MODE_REPEAT or TRANSFER_MODE_BLOCK or TRANSFER_MODE_REPEAT_BLOCK.
TRANSFER_REPEAT_AREA_SOURCE	Source area repeated in TRANSFER_MODE_REPEAT or TRANSFER_MODE_BLOCK or TRANSFER_MODE_REPEAT_BLOCK.

◆ transfer_chain_mode_t

enum transfer_chain_mode_t

Chain transfer mode options.

Note: Only applies for DTC.

Enumerator
TRANSFER_CHAIN_MODE_DISABLED	Chain mode not used.
TRANSFER_CHAIN_MODE_EACH	Switch to next transfer after a single transfer from this transfer_info_t.
TRANSFER_CHAIN_MODE_END	Complete the entire transfer defined in this transfer_info_t before chaining to next transfer.

◆ transfer_irq_t

enum transfer_irq_t

Interrupt options.

Enumerator

TRANSFER_IRQ_END

Interrupt occurs only after last transfer. If this transfer is chained to a subsequent transfer, the interrupt will occur only after subsequent chained transfer(s) are complete.

Warning: DTC triggers the interrupt of the activation source. Choosing TRANSFER_IRQ_END with DTC will prevent activation source interrupts until the transfer is complete.

TRANSFER_IRQ_EACH

Interrupt occurs after each transfer.

Note: Not available in all HAL drivers. See HAL driver for details.

◆ transfer_start_mode_t

enum transfer_start_mode_t

Select whether to start single or repeated transfer with software start.

Enumerator
TRANSFER_START_MODE_SINGLE	Software start triggers single transfer.
TRANSFER_START_MODE_REPEAT	Software start transfer continues until transfer is complete.

Detailed Description

Summary

Data Structures

Typedefs

Enumerations

Data Structure Documentation

◆ transfer_callback_args_t

◆ transfer_properties_t

◆ transfer_info_t

◆ transfer_cfg_t

◆ transfer_api_t

Data Fields

Field Documentation

◆ open

◆ reconfigure

◆ reset

◆ enable

◆ disable

◆ softwareStart

◆ softwareStop

◆ infoGet

◆ close

◆ reload

◆ callbackSet

◆ transfer_instance_t

Typedef Documentation

◆ transfer_ctrl_t

Enumeration Type Documentation

◆ transfer_mode_t

◆ transfer_size_t

◆ transfer_addr_mode_t

◆ transfer_repeat_area_t

◆ transfer_chain_mode_t

◆ transfer_irq_t

◆ transfer_start_mode_t