1 /*********************************************************************************************************************** 2 * Copyright [2015-2017] Renesas Electronics Corporation and/or its licensors. All Rights Reserved. 3 * 4 * This file is part of Renesas SynergyTM Software Package (SSP) 5 * 6 * The contents of this file (the "contents") are proprietary and confidential to Renesas Electronics Corporation 7 * and/or its licensors ("Renesas") and subject to statutory and contractual protections. 8 * 9 * This file is subject to a Renesas SSP license agreement. Unless otherwise agreed in an SSP license agreement with 10 * Renesas: 1) you may not use, copy, modify, distribute, display, or perform the contents; 2) you may not use any name 11 * or mark of Renesas for advertising or publicity purposes or in connection with your use of the contents; 3) RENESAS 12 * MAKES NO WARRANTY OR REPRESENTATIONS ABOUT THE SUITABILITY OF THE CONTENTS FOR ANY PURPOSE; THE CONTENTS ARE PROVIDED 13 * "AS IS" WITHOUT ANY EXPRESS OR IMPLIED WARRANTY, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 14 * PARTICULAR PURPOSE, AND NON-INFRINGEMENT; AND 4) RENESAS SHALL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, OR 15 * CONSEQUENTIAL DAMAGES, INCLUDING DAMAGES RESULTING FROM LOSS OF USE, DATA, OR PROJECTS, WHETHER IN AN ACTION OF 16 * CONTRACT OR TORT, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE CONTENTS. Third-party contents 17 * included in this file may be subject to different terms. 18 **********************************************************************************************************************/ 19 20 /********************************************************************************************************************** 21 * File Name : r_transfer_api.h 22 * Description : Provides an API to configure background data transfers. 23 **********************************************************************************************************************/ 24 25 #ifndef DRV_TRANSFER_API_H 26 #define DRV_TRANSFER_API_H 27 28 /*******************************************************************************************************************//** 29 * @ingroup Interface_Library 30 * @defgroup TRANSFER_API Transfer Interface 31 * 32 * @brief Interface for data transfer functions. 33 * 34 * @section TRANSFER_API_SUMMARY Summary 35 * The transfer interface supports background data transfer (no CPU intervention). 36 * 37 * The transfer interface can be implemented by: 38 * - @ref DTC 39 * - @ref DMAC 40 * 41 * Related SSP architecture topics: 42 * - @ref ssp-interfaces 43 * - @ref ssp-predefined-layers 44 * - @ref using-ssp-modules 45 * 46 * Transfer Interface description: @ref HALDTCInterface and @ref HALDMACInterface 47 * 48 * @{ 49 **********************************************************************************************************************/ 50 51 /*********************************************************************************************************************** 52 * Includes 53 **********************************************************************************************************************/ 54 /* Common error codes and definitions. */ 55 #include "bsp_api.h" 56 #include "r_elc_api.h" 57 58 /* Common macro for SSP header files. There is also a corresponding SSP_FOOTER macro at the end of this file. */ 59 SSP_HEADER 60 61 /********************************************************************************************************************** 62 * Macro definitions 63 **********************************************************************************************************************/ 64 #define TRANSFER_API_VERSION_MAJOR (1U) 65 #define TRANSFER_API_VERSION_MINOR (3U) 66 67 /********************************************************************************************************************** 68 * Typedef definitions 69 **********************************************************************************************************************/ 70 /** Transfer control block. Allocate an instance specific control block to pass into the transfer API calls. 71 * @par Implemented as 72 * - dtc_instance_ctrl_t 73 * - dmac_instance_ctrl_t 74 */ 75 typedef void transfer_ctrl_t; 76 77 /** Transfer mode describes what will happen when a transfer request occurs. */ 78 typedef enum e_transfer_mode 79 { 80 /** In normal mode, each transfer request causes a transfer of ::transfer_size_t from the source pointer to 81 * the destination pointer. The transfer length is decremented and the source and address pointers are 82 * updated according to ::transfer_addr_mode_t. After the transfer length reaches 0, transfer requests 83 * will not cause any further transfers. */ 84 TRANSFER_MODE_NORMAL = 0, 85 86 /** Repeat mode is like normal mode, except that when the transfer length reaches 0, the pointer to the 87 * repeat area and the transfer length will be reset to their initial values. If DMAC is used, the 88 * transfer repeats only transfer_info_t::num_blocks times. After the transfer repeats 89 * transfer_info_t::num_blocks times, transfer requests will not cause any further transfers. If DTC is 90 * used, the transfer repeats continuously (no limit to the number of repeat transfers). */ 91 TRANSFER_MODE_REPEAT = 1, 92 93 /** In block mode, each transfer request causes transfer_info_t::length transfers of ::transfer_size_t. 94 * After each individual transfer, the source and destination pointers are updated according to 95 * ::transfer_addr_mode_t. After the block transfer is complete, transfer_info_t::num_blocks is 96 * decremented. After the transfer_info_t::num_blocks reaches 0, transfer requests will not cause any 97 * further transfers. */ 98 TRANSFER_MODE_BLOCK = 2 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 an 8-bit value 107 TRANSFER_SIZE_2_BYTE = 1, ///< Address pointer is incremented after each transfer 108 TRANSFER_SIZE_4_BYTE = 2 ///< Address pointer is incremented after each transfer 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 /** Address pointer changes as per the configured value of offset_byte. */ 118 TRANSFER_ADDR_MODE_OFFSET = 1, 119 120 /** Address pointer is incremented by associated ::transfer_size_t after each transfer. */ 121 TRANSFER_ADDR_MODE_INCREMENTED = 2, 122 123 /** Address pointer is decremented by associated ::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 ::TRANSFER_MODE_REPEAT, the selected pointer returns to its 128 * original value after transfer_info_t::length transfers. In ::TRANSFER_MODE_BLOCK, the selected pointer 129 * returns to its original value after each transfer. */ 130 typedef enum e_transfer_repeat_area 131 { 132 /** Destination area repeated in ::TRANSFER_MODE_REPEAT or ::TRANSFER_MODE_BLOCK. */ 133 TRANSFER_REPEAT_AREA_DESTINATION = 0, 134 135 /** Source area repeated in ::TRANSFER_MODE_REPEAT or ::TRANSFER_MODE_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 ::transfer_info_t. */ 147 TRANSFER_CHAIN_MODE_EACH = 2, 148 149 /** Complete the entire transfer defined in this ::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 * @warning This will prevent chained transfers that would have happened after this one until the 165 * next activation source. */ 166 TRANSFER_IRQ_EACH = 1 167 } transfer_irq_t; 168 169 /** Driver specific information. */ 170 typedef struct st_transfer_properties 171 { 172 uint32_t transfer_length_max; ///< Maximum number of transfers 173 uint16_t transfer_length_remaining; ///< Number of transfers remaining 174 bool in_progress; ///< Whether or not this transfer is in progress 175 } transfer_properties_t; 176 177 178 /** This structure specifies the properties of the transfer. 179 * @warning When using DTC, this structure corresponds to the descriptor block registers required by the DTC. 180 * The following components may be modified by the driver: p_src, p_dest, num_blocks, and length. 181 * @warning When using DTC, do NOT reuse this structure to configure multiple transfers. Each transfer must 182 * have a unique transfer_info_t. 183 * @warning When using DTC, this structure must not be allocated in a temporary location. Any instance of this 184 * structure must remain in scope until the transfer it is used for is closed. 185 * @note When using DTC, consider placing instances of this structure in a protected section of memory. */ 186 typedef struct st_transfer_info 187 { 188 uint32_t : 16; 189 uint32_t : 2; 190 191 /** Select what happens to destination pointer after each transfer. */ 192 transfer_addr_mode_t dest_addr_mode : 2; 193 194 /** Select to repeat source or destination area, unused in ::TRANSFER_MODE_NORMAL. */ 195 transfer_repeat_area_t repeat_area : 1; 196 197 /** Select if interrupts should occur after each individual transfer or after the completion of all planned 198 * transfers. */ 199 transfer_irq_t irq : 1; 200 201 /** Select when the chain transfer ends. */ 202 transfer_chain_mode_t chain_mode : 2; 203 204 uint32_t : 2; 205 206 /** Select what happens to source pointer after each transfer. */ 207 transfer_addr_mode_t src_addr_mode : 2; 208 209 /** Select number of bytes to transfer at once. @see transfer_info_t::length. */ 210 transfer_size_t size : 2; 211 212 /** Select mode from ::transfer_mode_t. */ 213 transfer_mode_t mode : 2; 214 215 void const * volatile p_src; ///< Source pointer 216 void * volatile p_dest; ///< Destination pointer 217 218 /** Number of blocks to transfer when using ::TRANSFER_MODE_BLOCK (both DTC an DMAC) and 219 * ::TRANSFER_MODE_REPEAT (DMAC only), unused in other modes. */ 220 volatile uint16_t num_blocks; 221 222 /** Length of each transfer. Range limited for ::TRANSFER_MODE_BLOCK and ::TRANSFER_MODE_REPEAT, 223 * see HAL driver for details. */ 224 volatile uint16_t length; 225 } transfer_info_t; 226 227 /** Callback function parameter data. */ 228 typedef struct st_transfer_callback_args_t 229 { 230 void const * p_context; ///< Placeholder for user data. Set in r_transfer_t::open function in ::transfer_cfg_t. 231 } transfer_callback_args_t; 232 233 /** Driver configuration set in transfer_api_t::open. All elements except p_extend are required and must be 234 * initialized. */ 235 typedef struct st_transfer_cfg 236 { 237 /** Pointer to transfer configuration options. If using chain transfer (DTC only), this can be a pointer to 238 * an array of chained transfers that will be completed in order. */ 239 transfer_info_t * p_info; 240 241 /** Select which event will trigger the transfer. 242 * @note Select ELC_EVENT_ELC_SOFTWARE_EVENT_0 or ELC_EVENT_ELC_SOFTWARE_EVENT_0 for software activation. When 243 * using DTC, these events may only be used once each. DMAC uses internal software start when either of these 244 * events are selected. */ 245 elc_event_t activation_source; 246 247 /** Select whether the transfer should be enabled after open. */ 248 bool auto_enable; 249 250 /** Interrupt priority level. 251 * @warning Unsupported for DTC except when ELC software events are used. DTC transfers trigger the 252 * interrupt associated with the activation source. */ 253 uint8_t irq_ipl; 254 255 /** Callback for transfer end interrupt. Set to NULL for no CPU interrupt. 256 * @warning Unsupported for DTC except when ELC software events are used. DTC transfers trigger the 257 * interrupt associated with the activation source. */ 258 void (* p_callback)(transfer_callback_args_t * p_args); 259 260 /** Placeholder for user data. Passed to the user p_callback in ::transfer_callback_args_t. */ 261 void const * p_context; 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. Enables the transfer if auto_enable is true and p_src, p_dest, and length are valid. 276 * Transfers can also be enabled using transfer_api_t::enable or transfer_api_t::reset. 277 * @par Implemented as 278 * - R_DTC_Open() 279 * - R_DMAC_Open() 280 * 281 * @param[in,out] p_ctrl Pointer to control block. Must be declared by user. Elements set here. 282 * @param[in] p_cfg Pointer to configuration structure. All elements of this structure 283 * must be set by user. 284 */ 285 ssp_err_t (* open)(transfer_ctrl_t * const p_ctrl, 286 transfer_cfg_t const * const p_cfg); 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 * - R_DTC_Reset() 292 * - R_DMAC_Reset() 293 * 294 * @param[in] p_ctrl Control block set in 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 ssp_err_t (* reset)(transfer_ctrl_t * const p_ctrl, 302 void const * p_src, 303 void * p_dest, 304 uint16_t const num_transfers); 305 306 /** Enable transfer. Transfers occur after the activation source event (or when transfer_api_t::start is called 307 * if ELC_EVENT_ELC_SOFTWARE_EVENT_0 or ELC_EVENT_ELC_SOFTWARE_EVENT_0 is chosen as activation source). 308 * @par Implemented as 309 * - R_DMAC_Enable() 310 * - R_DTC_Enable() 311 * 312 * @param[in] p_ctrl Control block set in transfer_api_t::open call for this transfer. 313 */ 314 ssp_err_t (* enable) (transfer_ctrl_t * const p_ctrl); 315 316 /** Disable transfer. Transfers do not occur after the transfer_info_t::activation source event (or when 317 * transfer_api_t::start is called if ELC_EVENT_ELC_SOFTWARE_EVENT_0 or ELC_EVENT_ELC_SOFTWARE_EVENT_0 is chosen as 318 * transfer_info_t::activation_source). 319 * @note If a transfer is in progress, it will be completed. Subsequent transfer requests do not cause a 320 * transfer. 321 * @par Implemented as 322 * - R_DMAC_Disable() 323 * - R_DTC_Disable() 324 * 325 * @param[in] p_ctrl Control block set in transfer_api_t::open call for this transfer. 326 */ 327 ssp_err_t (* disable)(transfer_ctrl_t * const p_ctrl); 328 329 /** Start transfer in software. 330 * @warning Only works if ELC_EVENT_ELC_SOFTWARE_EVENT_0 or ELC_EVENT_ELC_SOFTWARE_EVENT_0 is chosen as 331 * transfer_info_t::activation_source. 332 * @note DTC only supports TRANSFER_START_MODE_SINGLE. DTC does not support TRANSFER_START_MODE_REPEAT. 333 * @par Implemented as 334 * - R_DMAC_Start() 335 * - R_DTC_Start() 336 * 337 * @param[in] p_ctrl Control block set in transfer_api_t::open call for this transfer. 338 * @param[in] mode Select mode from ::transfer_start_mode_t. 339 */ 340 ssp_err_t (* start)(transfer_ctrl_t * const p_ctrl, 341 transfer_start_mode_t mode); 342 343 /** Stop transfer in software. The transfer will stop after completion of the current transfer. 344 * @note Not supported for DTC. 345 * @note Only applies for transfers started with TRANSFER_START_MODE_REPEAT. 346 * @warning Only works if ELC_EVENT_ELC_SOFTWARE_EVENT_0 or ELC_EVENT_ELC_SOFTWARE_EVENT_0 is chosen as 347 * transfer_info_t::activation_source. 348 * @par Implemented as 349 * - R_DMAC_Stop() 350 * 351 * @param[in] p_ctrl Control block set in transfer_api_t::open call for this transfer. 352 */ 353 ssp_err_t (* stop)(transfer_ctrl_t * const p_ctrl); 354 355 /** Provides information about this transfer. 356 * @par Implemented as 357 * - R_DTC_InfoGet() 358 * - R_DMAC_InfoGet() 359 * 360 * @param[in] p_ctrl Control block set in transfer_api_t::open call for this transfer. 361 * @param[out] p_info Driver specific information. 362 */ 363 ssp_err_t (* infoGet)(transfer_ctrl_t * const p_ctrl, 364 transfer_properties_t * const p_info); 365 366 /** Releases hardware lock. This allows a transfer to be reconfigured using transfer_api_t::open. 367 * @par Implemented as 368 * - R_DTC_Close() 369 * - R_DMAC_Close() 370 * @param[in] p_ctrl Control block set in transfer_api_t::open call for this transfer. 371 */ 372 ssp_err_t (* close)(transfer_ctrl_t * const p_ctrl); 373 374 /** Gets version and stores it in provided pointer p_version. 375 * @par Implemented as 376 * - R_DTC_VersionGet() 377 * - R_DMAC_VersionGet() 378 * @param[out] p_version Code and API version used. 379 */ 380 ssp_err_t (* versionGet)(ssp_version_t * const p_version); 381 382 /** Reset source address pointer, destination address pointer, and/or length, for block transfer keeping all other settings the same. 383 * Enable the transfer if p_src, p_dest, and length are valid. 384 * @par Implemented as 385 * - R_DMAC_BlockReset() 386 * - R_DTC_BlockReset() 387 * 388 * 389 * @param[in] p_ctrl Control block set in transfer_api_t::open call for this transfer. 390 * @param[in] p_src Pointer to source. Set to NULL if source pointer should not change. 391 * @param[in] p_dest Pointer to destination. Set to NULL if destination pointer should not change. 392 * @param[in] length Transfer length in block mode.In DMAC only. 393 * @param[in] size Transfer size in block mode. In DMAC only. 394 * @param[in] num_transfers number of blocks in block mode. In DMAC only. 395 * 396 */ 397 ssp_err_t (* blockReset)(transfer_ctrl_t * const p_ctrl, 398 void const * p_src, 399 void * p_dest, 400 uint16_t const length, 401 transfer_size_t size, 402 uint16_t const num_transfers); 403 } transfer_api_t; 404 405 /** This structure encompasses everything that is needed to use an instance of this interface. */ 406 typedef struct st_transfer_instance 407 { 408 transfer_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 409 transfer_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 410 transfer_api_t const * p_api; ///< Pointer to the API structure for this instance 411 } transfer_instance_t; 412 413 /* Common macro for SSP header files. There is also a corresponding SSP_HEADER macro at the top of this file. */ 414 SSP_FOOTER 415 416 #endif /* DRV_TRANSFER_API_H */ 417 418 /*******************************************************************************************************************//** 419 * @} (end defgroup TRANSFER_API) 420 **********************************************************************************************************************/ 421