libs/rt-thread-official
libs
/
rt-thread-official
mirror of https://github.com/RT-Thread/rt-thread.git
4
0
Fork 0
Code Issues Releases Wiki Activity
rt-thread-official/bsp/ra6m4-cpk/ra/fsp/inc/api/r_transfer_api.h

372 lines
18 KiB
C
Raw Blame History

/***********************************************************************************************************************
* Copyright [2020-2021] Renesas Electronics Corporation and/or its affiliates. All Rights Reserved.
*
* This software and documentation are supplied by Renesas Electronics America Inc. and may only be used with products
* of Renesas Electronics Corp. and its affiliates ("Renesas"). No other uses are authorized. Renesas products are
* sold pursuant to Renesas terms and conditions of sale. Purchasers are solely responsible for the selection and use
* of Renesas products and Renesas assumes no liability. No license, express or implied, to any intellectual property
* right is granted by Renesas. This software is protected under all applicable laws, including copyright laws. Renesas
* reserves the right to change or discontinue this software and/or this documentation. THE SOFTWARE AND DOCUMENTATION
* IS DELIVERED TO YOU "AS IS," AND RENESAS MAKES NO REPRESENTATIONS OR WARRANTIES, AND TO THE FULLEST EXTENT
* PERMISSIBLE UNDER APPLICABLE LAW, DISCLAIMS ALL WARRANTIES, WHETHER EXPLICITLY OR IMPLICITLY, INCLUDING WARRANTIES
* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT, WITH RESPECT TO THE SOFTWARE OR
* DOCUMENTATION. RENESAS SHALL HAVE NO LIABILITY ARISING OUT OF ANY SECURITY VULNERABILITY OR BREACH. TO THE MAXIMUM
* EXTENT PERMITTED BY LAW, IN NO EVENT WILL RENESAS BE LIABLE TO YOU IN CONNECTION WITH THE SOFTWARE OR DOCUMENTATION
* (OR ANY PERSON OR ENTITY CLAIMING RIGHTS DERIVED FROM YOU) FOR ANY LOSS, DAMAGES, OR CLAIMS WHATSOEVER, INCLUDING,
* WITHOUT LIMITATION, ANY DIRECT, CONSEQUENTIAL, SPECIAL, INDIRECT, PUNITIVE, OR INCIDENTAL DAMAGES; ANY LOST PROFITS,
* OTHER ECONOMIC DAMAGE, PROPERTY DAMAGE, OR PERSONAL INJURY; AND EVEN IF RENESAS HAS BEEN ADVISED OF THE POSSIBILITY
* OF SUCH LOSS, DAMAGES, CLAIMS OR COSTS.
**********************************************************************************************************************/
/*******************************************************************************************************************//**
* @ingroup RENESAS_INTERFACES
* @defgroup TRANSFER_API Transfer Interface
*
* @brief Interface for data transfer functions.
*
* @section TRANSFER_API_SUMMARY Summary
* The transfer interface supports background data transfer (no CPU intervention).
*
* Implemented by:
* - @ref DTC
* - @ref DMAC
*
* @{
**********************************************************************************************************************/
#ifndef R_TRANSFER_API_H
#define R_TRANSFER_API_H
/***********************************************************************************************************************
* Includes
**********************************************************************************************************************/
/* Common error codes and definitions. */
#include "bsp_api.h"
/* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */
FSP_HEADER
/**********************************************************************************************************************
* Macro definitions
**********************************************************************************************************************/
#define TRANSFER_SETTINGS_MODE_BITS (30U)
#define TRANSFER_SETTINGS_SIZE_BITS (28U)
#define TRANSFER_SETTINGS_SRC_ADDR_BITS (26U)
#define TRANSFER_SETTINGS_CHAIN_MODE_BITS (22U)
#define TRANSFER_SETTINGS_IRQ_BITS (21U)
#define TRANSFER_SETTINGS_REPEAT_AREA_BITS (20U)
#define TRANSFER_SETTINGS_DEST_ADDR_BITS (18U)
/**********************************************************************************************************************
* Typedef definitions
**********************************************************************************************************************/
/** Transfer control block. Allocate an instance specific control block to pass into the transfer API calls.
* @par Implemented as
* - dtc_instance_ctrl_t
* - dmac_instance_ctrl_t
*/
typedef void transfer_ctrl_t;
/** Transfer mode describes what will happen when a transfer request occurs. */
typedef enum e_transfer_mode
{
/** In normal mode, each transfer request causes a transfer of @ref 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 @ref transfer_addr_mode_t. After the transfer length reaches 0, transfer requests
* will not cause any further transfers. */
TRANSFER_MODE_NORMAL = 0,
/** 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_REPEAT = 1,
/** In block mode, each transfer request causes transfer_info_t::length transfers of @ref transfer_size_t.
* After each individual transfer, the source and destination pointers are updated according to
* @ref 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_BLOCK = 2,
/** 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_MODE_REPEAT_BLOCK = 3
} transfer_mode_t;
/** Transfer size specifies the size of each individual transfer.
* Total transfer length = transfer_size_t * transfer_length_t
*/
typedef enum e_transfer_size
{
TRANSFER_SIZE_1_BYTE = 0, ///< Each transfer transfers a 8-bit value
TRANSFER_SIZE_2_BYTE = 1, ///< Each transfer transfers a 16-bit value
TRANSFER_SIZE_4_BYTE = 2 ///< Each transfer transfers a 32-bit value
} transfer_size_t;
/** Address mode specifies whether to modify (increment or decrement) pointer after each transfer. */
typedef enum e_transfer_addr_mode
{
/** Address pointer remains fixed after each transfer. */
TRANSFER_ADDR_MODE_FIXED = 0,
/** Offset is added to the address pointer after each transfer. */
TRANSFER_ADDR_MODE_OFFSET = 1,
/** Address pointer is incremented by associated @ref transfer_size_t after each transfer. */
TRANSFER_ADDR_MODE_INCREMENTED = 2,
/** Address pointer is decremented by associated @ref transfer_size_t after each transfer. */
TRANSFER_ADDR_MODE_DECREMENTED = 3
} transfer_addr_mode_t;
/** Repeat area options (source or destination). In @ref TRANSFER_MODE_REPEAT, the selected pointer returns to its
* original value after transfer_info_t::length transfers. In @ref TRANSFER_MODE_BLOCK and @ref TRANSFER_MODE_REPEAT_BLOCK,
* the selected pointer returns to its original value after each transfer. */
typedef enum e_transfer_repeat_area
{
/** Destination area repeated in @ref TRANSFER_MODE_REPEAT or @ref TRANSFER_MODE_BLOCK or @ref TRANSFER_MODE_REPEAT_BLOCK. */
TRANSFER_REPEAT_AREA_DESTINATION = 0,
/** Source area repeated in @ref TRANSFER_MODE_REPEAT or @ref TRANSFER_MODE_BLOCK or @ref TRANSFER_MODE_REPEAT_BLOCK. */
TRANSFER_REPEAT_AREA_SOURCE = 1
} transfer_repeat_area_t;
/** Chain transfer mode options.
* @note Only applies for DTC. */
typedef enum e_transfer_chain_mode
{
/** Chain mode not used. */
TRANSFER_CHAIN_MODE_DISABLED = 0,
/** Switch to next transfer after a single transfer from this @ref transfer_info_t. */
TRANSFER_CHAIN_MODE_EACH = 2,
/** Complete the entire transfer defined in this @ref transfer_info_t before chaining to next transfer. */
TRANSFER_CHAIN_MODE_END = 3
} transfer_chain_mode_t;
/** Interrupt options. */
typedef enum e_transfer_irq
{
/** 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_END = 0,
/** Interrupt occurs after each transfer.
* @note Not available in all HAL drivers. See HAL driver for details. */
TRANSFER_IRQ_EACH = 1
} transfer_irq_t;
/** Driver specific information. */
typedef struct st_transfer_properties
{
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_properties_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.
* @warning When using DTC, do NOT reuse this structure to configure multiple transfers. Each transfer must
* have a unique transfer_info_t.
* @warning 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. */
typedef struct st_transfer_info
{
union
{
struct
{
uint32_t : 16;
uint32_t : 2;
/** Select what happens to destination pointer after each transfer. */
transfer_addr_mode_t dest_addr_mode : 2;
/** Select to repeat source or destination area, unused in @ref TRANSFER_MODE_NORMAL. */
transfer_repeat_area_t repeat_area : 1;
/** Select if interrupts should occur after each individual transfer or after the completion of all planned
* transfers. */
transfer_irq_t irq : 1;
/** Select when the chain transfer ends. */
transfer_chain_mode_t chain_mode : 2;
uint32_t : 2;
/** Select what happens to source pointer after each transfer. */
transfer_addr_mode_t src_addr_mode : 2;
/** Select number of bytes to transfer at once. @see transfer_info_t::length. */
transfer_size_t size : 2;
/** Select mode from @ref transfer_mode_t. */
transfer_mode_t mode : 2;
};
uint32_t transfer_settings_word;
};
void const * volatile p_src; ///< Source pointer
void * volatile p_dest; ///< Destination pointer
/** Number of blocks to transfer when using @ref TRANSFER_MODE_BLOCK (both DTC an DMAC) or
* @ref TRANSFER_MODE_REPEAT (DMAC only) or
* @ref TRANSFER_MODE_REPEAT_BLOCK (DMAC only), unused in other modes. */
volatile uint16_t num_blocks;
/** Length of each transfer. Range limited for @ref TRANSFER_MODE_BLOCK, @ref TRANSFER_MODE_REPEAT,
* and @ref TRANSFER_MODE_REPEAT_BLOCK
* see HAL driver for details. */
volatile uint16_t length;
} transfer_info_t;
/** Driver configuration set in @ref transfer_api_t::open. All elements except p_extend are required and must be
* initialized. */
typedef struct st_transfer_cfg
{
/** 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. */
transfer_info_t * p_info;
void const * p_extend; ///< Extension parameter for hardware specific settings.
} transfer_cfg_t;
/** Select whether to start single or repeated transfer with software start. */
typedef enum e_transfer_start_mode
{
TRANSFER_START_MODE_SINGLE = 0, ///< Software start triggers single transfer.
TRANSFER_START_MODE_REPEAT = 1 ///< Software start transfer continues until transfer is complete.
} transfer_start_mode_t;
/** Transfer functions implemented at the HAL layer will follow this API. */
typedef struct st_transfer_api
{
/** Initial configuration.
* @par Implemented as
* - @ref R_DTC_Open()
* - @ref R_DMAC_Open()
*
* @param[in,out] p_ctrl Pointer to control block. Must be declared by user. Elements set here.
* @param[in] p_cfg Pointer to configuration structure. All elements of this structure
* must be set by user.
*/
fsp_err_t (* open)(transfer_ctrl_t * const p_ctrl, transfer_cfg_t const * const p_cfg);
/** Reconfigure the transfer.
* Enable the transfer if p_info is valid.
* @par Implemented as
* - @ref R_DTC_Reconfigure()
* - @ref R_DMAC_Reconfigure()
*
* @param[in,out] p_ctrl Pointer to control block. Must be declared by user. Elements set here.
* @param[in] p_info Pointer to a new transfer info structure.
*/
fsp_err_t (* reconfigure)(transfer_ctrl_t * const p_ctrl, transfer_info_t * p_info);
/** 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.
* @par Implemented as
* - @ref R_DTC_Reset()
* - @ref R_DMAC_Reset()
*
* @param[in] p_ctrl Control block set in @ref transfer_api_t::open call for this transfer.
* @param[in] p_src Pointer to source. Set to NULL if source pointer should not change.
* @param[in] p_dest Pointer to destination. Set to NULL if destination pointer should not change.
* @param[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.
*/
fsp_err_t (* reset)(transfer_ctrl_t * const p_ctrl, void const * p_src, void * p_dest,
uint16_t const num_transfers);
/** Enable transfer. Transfers occur after the activation source event (or when
* @ref transfer_api_t::softwareStart is called if ELC_EVENT_ELC_NONE is chosen as activation source).
* @par Implemented as
* - @ref R_DTC_Enable()
* - @ref R_DMAC_Enable()
*
* @param[in] p_ctrl Control block set in @ref transfer_api_t::open call for this transfer.
*/
fsp_err_t (* enable)(transfer_ctrl_t * const p_ctrl);
/** Disable transfer. Transfers do not occur after the activation source event (or when
* @ref transfer_api_t::softwareStart is called if ELC_EVENT_ELC_NONE 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.
* @par Implemented as
* - @ref R_DTC_Disable()
* - @ref R_DMAC_Disable()
*
* @param[in] p_ctrl Control block set in @ref transfer_api_t::open call for this transfer.
*/
fsp_err_t (* disable)(transfer_ctrl_t * const p_ctrl);
/** Start transfer in software.
* @warning Only works if ELC_EVENT_ELC_NONE is chosen as the DMAC activation source.
* @note Not supported for DTC.
* @par Implemented as
* - @ref R_DMAC_SoftwareStart()
*
* @param[in] p_ctrl Control block set in @ref transfer_api_t::open call for this transfer.
* @param[in] mode Select mode from @ref transfer_start_mode_t.
*/
fsp_err_t (* softwareStart)(transfer_ctrl_t * const p_ctrl, transfer_start_mode_t mode);
/** Stop transfer in software. The transfer will stop after completion of the current transfer.
* @note Not supported for DTC.
* @note Only applies for transfers started with TRANSFER_START_MODE_REPEAT.
* @warning Only works if ELC_EVENT_ELC_NONE is chosen as the DMAC activation source.
* @par Implemented as
* - @ref R_DMAC_SoftwareStop()
*
* @param[in] p_ctrl Control block set in @ref transfer_api_t::open call for this transfer.
*/
fsp_err_t (* softwareStop)(transfer_ctrl_t * const p_ctrl);
/** Provides information about this transfer.
* @par Implemented as
* - @ref R_DTC_InfoGet()
* - @ref R_DMAC_InfoGet()
*
* @param[in] p_ctrl Control block set in @ref transfer_api_t::open call for this transfer.
* @param[out] p_properties Driver specific information.
*/
fsp_err_t (* infoGet)(transfer_ctrl_t * const p_ctrl, transfer_properties_t * const p_properties);
/** Releases hardware lock. This allows a transfer to be reconfigured using @ref transfer_api_t::open.
* @par Implemented as
* - @ref R_DTC_Close()
* - @ref R_DMAC_Close()
* @param[in] p_ctrl Control block set in @ref transfer_api_t::open call for this transfer.
*/
fsp_err_t (* close)(transfer_ctrl_t * const p_ctrl);
} transfer_api_t;
/** This structure encompasses everything that is needed to use an instance of this interface. */
typedef struct st_transfer_instance
{
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
} transfer_instance_t;
/* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */
FSP_FOOTER
#endif
/*******************************************************************************************************************//**
* @} (end defgroup TRANSFER_API)
**********************************************************************************************************************/
View Git Blame Copy Permalink