1 /* 2 * Copyright (c) 2020 - 2025 Renesas Electronics Corporation and/or its affiliates 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 /*******************************************************************************************************************//** 8 * @ingroup RENESAS_TRANSFER_INTERFACES 9 * @defgroup TRANSFER_API Transfer Interface 10 * 11 * @brief Interface for data transfer functions. 12 * 13 * @section TRANSFER_API_SUMMARY Summary 14 * The transfer interface supports background data transfer (no CPU intervention). 15 * 16 * 17 * @{ 18 **********************************************************************************************************************/ 19 20 #ifndef R_TRANSFER_API_H 21 #define R_TRANSFER_API_H 22 23 /*********************************************************************************************************************** 24 * Includes 25 **********************************************************************************************************************/ 26 27 /* Common error codes and definitions. */ 28 #include "bsp_api.h" 29 30 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */ 31 FSP_HEADER 32 33 /********************************************************************************************************************** 34 * Macro definitions 35 **********************************************************************************************************************/ 36 37 #define TRANSFER_SETTINGS_MODE_BITS (30U) 38 #define TRANSFER_SETTINGS_SIZE_BITS (28U) 39 #define TRANSFER_SETTINGS_SRC_ADDR_BITS (26U) 40 #define TRANSFER_SETTINGS_CHAIN_MODE_BITS (22U) 41 #define TRANSFER_SETTINGS_IRQ_BITS (21U) 42 #define TRANSFER_SETTINGS_REPEAT_AREA_BITS (20U) 43 #define TRANSFER_SETTINGS_DEST_ADDR_BITS (18U) 44 45 /********************************************************************************************************************** 46 * Typedef definitions 47 **********************************************************************************************************************/ 48 49 /** Transfer control block. Allocate an instance specific control block to pass into the transfer API calls. 50 */ 51 typedef void transfer_ctrl_t; 52 53 #ifndef BSP_OVERRIDE_TRANSFER_MODE_T 54 55 /** Transfer mode describes what will happen when a transfer request occurs. */ 56 typedef enum e_transfer_mode 57 { 58 /** In normal mode, each transfer request causes a transfer of @ref transfer_size_t from the source pointer to 59 * the destination pointer. The transfer length is decremented and the source and address pointers are 60 * updated according to @ref transfer_addr_mode_t. After the transfer length reaches 0, transfer requests 61 * will not cause any further transfers. */ 62 TRANSFER_MODE_NORMAL = 0, 63 64 /** Repeat mode is like normal mode, except that when the transfer length reaches 0, the pointer to the 65 * repeat area and the transfer length will be reset to their initial values. If DMAC is used, the 66 * transfer repeats only transfer_info_t::num_blocks times. After the transfer repeats 67 * transfer_info_t::num_blocks times, transfer requests will not cause any further transfers. If DTC is 68 * used, the transfer repeats continuously (no limit to the number of repeat transfers). */ 69 TRANSFER_MODE_REPEAT = 1, 70 71 /** In block mode, each transfer request causes transfer_info_t::length transfers of @ref transfer_size_t. 72 * After each individual transfer, the source and destination pointers are updated according to 73 * @ref transfer_addr_mode_t. After the block transfer is complete, transfer_info_t::num_blocks is 74 * decremented. After the transfer_info_t::num_blocks reaches 0, transfer requests will not cause any 75 * further transfers. */ 76 TRANSFER_MODE_BLOCK = 2, 77 78 /** In addition to block mode features, repeat-block mode supports a ring buffer of blocks and offsets 79 * within a block (to split blocks into arrays of their first data, second data, etc.) */ 80 TRANSFER_MODE_REPEAT_BLOCK = 3 81 } transfer_mode_t; 82 83 #endif 84 85 #ifndef BSP_OVERRIDE_TRANSFER_SIZE_T 86 87 /** Transfer size specifies the size of each individual transfer. 88 * Total transfer length = transfer_size_t * transfer_length_t 89 */ 90 typedef enum e_transfer_size 91 { 92 TRANSFER_SIZE_1_BYTE = 0, /* /< Each transfer transfers a 8-bit value */ 93 TRANSFER_SIZE_2_BYTE = 1, /* /< Each transfer transfers a 16-bit value */ 94 TRANSFER_SIZE_4_BYTE = 2, /* /< Each transfer transfers a 32-bit value */ 95 TRANSFER_SIZE_8_BYTE = 3 /* /< Each transfer transfers a 64-bit value */ 96 } transfer_size_t; 97 98 #endif 99 100 #ifndef BSP_OVERRIDE_TRANSFER_ADDR_MODE_T 101 102 /** Address mode specifies whether to modify (increment or decrement) pointer after each transfer. */ 103 typedef enum e_transfer_addr_mode 104 { 105 /** Address pointer remains fixed after each transfer. */ 106 TRANSFER_ADDR_MODE_FIXED = 0, 107 108 /** Offset is added to the address pointer after each transfer. */ 109 TRANSFER_ADDR_MODE_OFFSET = 1, 110 111 /** Address pointer is incremented by associated @ref transfer_size_t after each transfer. */ 112 TRANSFER_ADDR_MODE_INCREMENTED = 2, 113 114 /** Address pointer is decremented by associated @ref transfer_size_t after each transfer. */ 115 TRANSFER_ADDR_MODE_DECREMENTED = 3 116 } transfer_addr_mode_t; 117 118 #endif 119 120 #ifndef BSP_OVERRIDE_TRANSFER_REPEAT_AREA_T 121 122 /** Repeat area options (source or destination). In @ref TRANSFER_MODE_REPEAT, the selected pointer returns to its 123 * original value after transfer_info_t::length transfers. In @ref TRANSFER_MODE_BLOCK and @ref TRANSFER_MODE_REPEAT_BLOCK, 124 * the selected pointer returns to its original value after each transfer. */ 125 typedef enum e_transfer_repeat_area 126 { 127 /** Destination area repeated in @ref TRANSFER_MODE_REPEAT or @ref TRANSFER_MODE_BLOCK or @ref TRANSFER_MODE_REPEAT_BLOCK. */ 128 TRANSFER_REPEAT_AREA_DESTINATION = 0, 129 130 /** Source area repeated in @ref TRANSFER_MODE_REPEAT or @ref TRANSFER_MODE_BLOCK or @ref TRANSFER_MODE_REPEAT_BLOCK. */ 131 TRANSFER_REPEAT_AREA_SOURCE = 1 132 } transfer_repeat_area_t; 133 134 #endif 135 136 #ifndef BSP_OVERRIDE_TRANSFER_CHAIN_MODE_T 137 138 /** Chain transfer mode options. 139 * @note Only applies for DTC. */ 140 typedef enum e_transfer_chain_mode 141 { 142 /** Chain mode not used. */ 143 TRANSFER_CHAIN_MODE_DISABLED = 0, 144 145 /** Switch to next transfer after a single transfer from this @ref transfer_info_t. */ 146 TRANSFER_CHAIN_MODE_EACH = 2, 147 148 /** Complete the entire transfer defined in this @ref transfer_info_t before chaining to next transfer. */ 149 TRANSFER_CHAIN_MODE_END = 3 150 } transfer_chain_mode_t; 151 152 #endif 153 154 #ifndef BSP_OVERRIDE_TRANSFER_IRQ_T 155 156 /** Interrupt options. */ 157 typedef enum e_transfer_irq 158 { 159 /** Interrupt occurs only after last transfer. If this transfer is chained to a subsequent transfer, 160 * the interrupt will occur only after subsequent chained transfer(s) are complete. 161 * @warning DTC triggers the interrupt of the activation source. Choosing TRANSFER_IRQ_END with DTC will 162 * prevent activation source interrupts until the transfer is complete. */ 163 TRANSFER_IRQ_END = 0, 164 165 /** Interrupt occurs after each transfer. 166 * @note Not available in all HAL drivers. See HAL driver for details. */ 167 TRANSFER_IRQ_EACH = 1 168 } transfer_irq_t; 169 170 #endif 171 172 #ifndef BSP_OVERRIDE_TRANSFER_CALLBACK_ARGS_T 173 174 /** Callback function parameter data. */ 175 typedef struct st_transfer_callback_args_t 176 { 177 void const * p_context; /* /< Placeholder for user data. Set in @ref transfer_api_t::open function in ::transfer_cfg_t. */ 178 } transfer_callback_args_t; 179 180 #endif 181 182 /** Driver specific information. */ 183 typedef struct st_transfer_properties 184 { 185 uint32_t block_count_max; /* /< Maximum number of blocks */ 186 uint32_t block_count_remaining; /* /< Number of blocks remaining */ 187 uint32_t transfer_length_max; /* /< Maximum number of transfers */ 188 uint32_t transfer_length_remaining; /* /< Number of transfers remaining */ 189 } transfer_properties_t; 190 191 #ifndef BSP_OVERRIDE_TRANSFER_INFO_T 192 193 /** This structure specifies the properties of the transfer. 194 * @warning When using DTC, this structure corresponds to the descriptor block registers required by the DTC. 195 * The following components may be modified by the driver: p_src, p_dest, num_blocks, and length. 196 * @warning When using DTC, do NOT reuse this structure to configure multiple transfers. Each transfer must 197 * have a unique transfer_info_t. 198 * @warning When using DTC, this structure must not be allocated in a temporary location. Any instance of this 199 * structure must remain in scope until the transfer it is used for is closed. 200 * @note When using DTC, consider placing instances of this structure in a protected section of memory. */ 201 typedef struct st_transfer_info 202 { 203 union 204 { 205 struct 206 { 207 uint32_t : 16; 208 uint32_t : 2; 209 210 /** Select what happens to destination pointer after each transfer. */ 211 transfer_addr_mode_t dest_addr_mode : 2; 212 213 /** Select to repeat source or destination area, unused in @ref TRANSFER_MODE_NORMAL. */ 214 transfer_repeat_area_t repeat_area : 1; 215 216 /** Select if interrupts should occur after each individual transfer or after the completion of all planned 217 * transfers. */ 218 transfer_irq_t irq : 1; 219 220 /** Select when the chain transfer ends. */ 221 transfer_chain_mode_t chain_mode : 2; 222 223 uint32_t : 2; 224 225 /** Select what happens to source pointer after each transfer. */ 226 transfer_addr_mode_t src_addr_mode : 2; 227 228 /** Select number of bytes to transfer at once. @see transfer_info_t::length. */ 229 transfer_size_t size : 2; 230 231 /** Select mode from @ref transfer_mode_t. */ 232 transfer_mode_t mode : 2; 233 } transfer_settings_word_b; 234 235 uint32_t transfer_settings_word; 236 }; 237 238 void const * volatile p_src; /* /< Source pointer */ 239 void * volatile p_dest; /* /< Destination pointer */ 240 241 /** Number of blocks to transfer when using @ref TRANSFER_MODE_BLOCK (both DTC an DMAC) or 242 * @ref TRANSFER_MODE_REPEAT (DMAC only) or 243 * @ref TRANSFER_MODE_REPEAT_BLOCK (DMAC only), unused in other modes. */ 244 volatile uint16_t num_blocks; 245 246 /** Length of each transfer. Range limited for @ref TRANSFER_MODE_BLOCK, @ref TRANSFER_MODE_REPEAT, 247 * and @ref TRANSFER_MODE_REPEAT_BLOCK 248 * see HAL driver for details. */ 249 volatile uint16_t length; 250 } transfer_info_t; 251 252 #endif 253 254 /** Driver configuration set in @ref transfer_api_t::open. All elements except p_extend are required and must be 255 * initialized. */ 256 typedef struct st_transfer_cfg 257 { 258 /** Pointer to transfer configuration options. If using chain transfer (DTC only), this can be a pointer to 259 * an array of chained transfers that will be completed in order. */ 260 transfer_info_t * p_info; 261 262 void const * p_extend; /* /< Extension parameter for hardware specific settings. */ 263 } transfer_cfg_t; 264 265 /** Select whether to start single or repeated transfer with software start. */ 266 typedef enum e_transfer_start_mode 267 { 268 TRANSFER_START_MODE_SINGLE = 0, /* /< Software start triggers single transfer. */ 269 TRANSFER_START_MODE_REPEAT = 1 /* /< Software start transfer continues until transfer is complete. */ 270 } transfer_start_mode_t; 271 272 /** Transfer functions implemented at the HAL layer will follow this API. */ 273 typedef struct st_transfer_api 274 { 275 /** Initial configuration. 276 * 277 * @param[in,out] p_ctrl Pointer to control block. Must be declared by user. Elements set here. 278 * @param[in] p_cfg Pointer to configuration structure. All elements of this structure 279 * must be set by user. 280 */ 281 fsp_err_t (* open)(transfer_ctrl_t * const p_ctrl, transfer_cfg_t const * const p_cfg); 282 283 /** Reconfigure the transfer. 284 * Enable the transfer if p_info is valid. 285 * 286 * @param[in,out] p_ctrl Pointer to control block. Must be declared by user. Elements set here. 287 * @param[in] p_info Pointer to a new transfer info structure. 288 */ 289 fsp_err_t (* reconfigure)(transfer_ctrl_t * const p_ctrl, transfer_info_t * p_info); 290 291 /** Reset source address pointer, destination address pointer, and/or length, keeping all other settings the same. 292 * Enable the transfer if p_src, p_dest, and length are valid. 293 * 294 * @param[in] p_ctrl Control block set in @ref transfer_api_t::open call for this transfer. 295 * @param[in] p_src Pointer to source. Set to NULL if source pointer should not change. 296 * @param[in] p_dest Pointer to destination. Set to NULL if destination pointer should not change. 297 * @param[in] num_transfers Transfer length in normal mode or number of blocks in block mode. In DMAC only, 298 * resets number of repeats (initially stored in transfer_info_t::num_blocks) in 299 * repeat mode. Not used in repeat mode for DTC. 300 */ 301 fsp_err_t (* reset)(transfer_ctrl_t * const p_ctrl, void const * p_src, void * p_dest, 302 uint16_t const num_transfers); 303 304 /** Enable transfer. Transfers occur after the activation source event (or when 305 * @ref transfer_api_t::softwareStart is called if no peripheral event is chosen as activation source). 306 * 307 * @param[in] p_ctrl Control block set in @ref transfer_api_t::open call for this transfer. 308 */ 309 fsp_err_t (* enable)(transfer_ctrl_t * const p_ctrl); 310 311 /** Disable transfer. Transfers do not occur after the activation source event (or when 312 * @ref transfer_api_t::softwareStart is called if no peripheral event is chosen as the DMAC activation source). 313 * @note If a transfer is in progress, it will be completed. Subsequent transfer requests do not cause a 314 * transfer. 315 * 316 * @param[in] p_ctrl Control block set in @ref transfer_api_t::open call for this transfer. 317 */ 318 fsp_err_t (* disable)(transfer_ctrl_t * const p_ctrl); 319 320 /** Start transfer in software. 321 * @warning Only works if no peripheral event is chosen as the DMAC activation source. 322 * @note Not supported for DTC. 323 * 324 * @param[in] p_ctrl Control block set in @ref transfer_api_t::open call for this transfer. 325 * @param[in] mode Select mode from @ref transfer_start_mode_t. 326 */ 327 fsp_err_t (* softwareStart)(transfer_ctrl_t * const p_ctrl, transfer_start_mode_t mode); 328 329 /** Stop transfer in software. The transfer will stop after completion of the current transfer. 330 * @note Not supported for DTC. 331 * @note Only applies for transfers started with TRANSFER_START_MODE_REPEAT. 332 * @warning Only works if no peripheral event is chosen as the DMAC activation source. 333 * 334 * @param[in] p_ctrl Control block set in @ref transfer_api_t::open call for this transfer. 335 */ 336 fsp_err_t (* softwareStop)(transfer_ctrl_t * const p_ctrl); 337 338 /** Provides information about this transfer. 339 * 340 * @param[in] p_ctrl Control block set in @ref transfer_api_t::open call for this transfer. 341 * @param[out] p_properties Driver specific information. 342 */ 343 fsp_err_t (* infoGet)(transfer_ctrl_t * const p_ctrl, transfer_properties_t * const p_properties); 344 345 /** Releases hardware lock. This allows a transfer to be reconfigured using @ref transfer_api_t::open. 346 * 347 * @param[in] p_ctrl Control block set in @ref transfer_api_t::open call for this transfer. 348 */ 349 fsp_err_t (* close)(transfer_ctrl_t * const p_ctrl); 350 351 /** To update next transfer information without interruption during transfer. 352 * Allow further transfer continuation. 353 * 354 * @param[in] p_ctrl Control block set in @ref transfer_api_t::open call for this transfer. 355 * @param[in] p_src Pointer to source. Set to NULL if source pointer should not change. 356 * @param[in] p_dest Pointer to destination. Set to NULL if destination pointer should not change. 357 * @param[in] num_transfers Transfer length in normal mode or block mode. 358 */ 359 fsp_err_t (* reload)(transfer_ctrl_t * const p_ctrl, void const * p_src, void * p_dest, 360 uint32_t const num_transfers); 361 362 /** Specify callback function and optional context pointer and working memory pointer. 363 * 364 * @param[in] p_ctrl Control block set in @ref transfer_api_t::open call for this transfer. 365 * @param[in] p_callback Callback function to register 366 * @param[in] p_context Pointer to send to callback function 367 * @param[in] p_callback_memory Pointer to volatile memory where callback structure can be allocated. 368 * Callback arguments allocated here are only valid during the callback. 369 */ 370 fsp_err_t (* callbackSet)(transfer_ctrl_t * const p_ctrl, void (* p_callback)(transfer_callback_args_t *), 371 void const * const p_context, transfer_callback_args_t * const p_callback_memory); 372 } transfer_api_t; 373 374 /** This structure encompasses everything that is needed to use an instance of this interface. */ 375 typedef struct st_transfer_instance 376 { 377 transfer_ctrl_t * p_ctrl; /* /< Pointer to the control structure for this instance */ 378 transfer_cfg_t const * p_cfg; /* /< Pointer to the configuration structure for this instance */ 379 transfer_api_t const * p_api; /* /< Pointer to the API structure for this instance */ 380 } transfer_instance_t; 381 382 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */ 383 FSP_FOOTER 384 385 #endif 386 387 /*******************************************************************************************************************//** 388 * @} (end defgroup TRANSFER_API) 389 **********************************************************************************************************************/ 390 391