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