RA Flexible Software Package Documentation  Release v5.7.0

 
Transfer Interface

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_ctrlPointer to control block. Must be declared by user. Elements set here.
[in]p_cfgPointer 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_ctrlPointer to control block. Must be declared by user. Elements set here.
[in]p_infoPointer 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_ctrlControl block set in transfer_api_t::open call for this transfer.
[in]p_srcPointer to source. Set to NULL if source pointer should not change.
[in]p_destPointer to destination. Set to NULL if destination pointer should not change.
[in]num_transfersTransfer 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_ctrlControl 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_ctrlControl 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_ctrlControl block set in transfer_api_t::open call for this transfer.
[in]modeSelect 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_ctrlControl 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_ctrlControl block set in transfer_api_t::open call for this transfer.
[out]p_propertiesDriver 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_ctrlControl 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_ctrlControl block set in transfer_api_t::open call for this transfer.
[in]p_srcPointer to source. Set to NULL if source pointer should not change.
[in]p_destPointer to destination. Set to NULL if destination pointer should not change.
[in]num_transfersTransfer 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_ctrlControl block set in transfer_api_t::open call for this transfer.
[in]p_callbackCallback function to register
[in]p_contextPointer to send to callback function
[in]p_callback_memoryPointer 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

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

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

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

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

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

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

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.