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