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