1 /* 2 * Copyright (c) 2020 - 2024 Renesas Electronics Corporation and/or its affiliates 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 #ifndef R_ADC_API_H 8 #define R_ADC_API_H 9 10 /*******************************************************************************************************************//** 11 * @ingroup RENESAS_INTERFACES 12 * @defgroup ADC_API ADC Interface 13 * @brief Interface for A/D Converters. 14 * 15 * @section ADC_API_SUMMARY Summary 16 * The ADC interface provides standard ADC functionality including one-shot mode (single scan), continuous scan and 17 * group scan. It also allows configuration of hardware and software triggers for starting scans. After each conversion 18 * an interrupt can be triggered, and if a callback function is provided, the call back is invoked with the 19 * appropriate event information. 20 * 21 * Implemented by: 22 * @ref ADC_C 23 * 24 * @{ 25 **********************************************************************************************************************/ 26 27 /*********************************************************************************************************************** 28 * Includes 29 **********************************************************************************************************************/ 30 31 /* Includes board and MCU related header files. */ 32 #include "bsp_api.h" 33 #ifndef BSP_OVERRIDE_ADC_INCLUDE 34 #include "r_elc_api.h" 35 #endif 36 #include "r_transfer_api.h" 37 38 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */ 39 FSP_HEADER 40 41 /********************************************************************************************************************** 42 * Macro definitions 43 **********************************************************************************************************************/ 44 45 /***************************************************************************** 46 * Typedef definitions 47 ******************************************************************************/ 48 49 #ifndef BSP_OVERRIDE_ADC_MODE_T 50 51 /** ADC operation mode definitions */ 52 typedef enum e_adc_mode 53 { 54 ADC_MODE_SINGLE_SCAN = 0, ///< Single scan - one or more channels 55 ADC_MODE_GROUP_SCAN = 1, ///< Two trigger sources to trigger scan for two groups which contain one or more channels 56 ADC_MODE_CONTINUOUS_SCAN = 2, ///< Continuous scan - one or more channels 57 } adc_mode_t; 58 59 #endif 60 61 /** ADC data resolution definitions */ 62 typedef enum e_adc_resolution 63 { 64 ADC_RESOLUTION_12_BIT = 0, ///< 12 bit resolution 65 ADC_RESOLUTION_10_BIT = 1, ///< 10 bit resolution 66 ADC_RESOLUTION_8_BIT = 2, ///< 8 bit resolution 67 ADC_RESOLUTION_14_BIT = 3, ///< 14 bit resolution 68 ADC_RESOLUTION_16_BIT = 4, ///< 16 bit resolution 69 ADC_RESOLUTION_24_BIT = 5, ///< 24 bit resolution 70 } adc_resolution_t; 71 72 /** ADC data alignment definitions */ 73 typedef enum e_adc_alignment 74 { 75 ADC_ALIGNMENT_RIGHT = 0, ///< Data alignment right 76 ADC_ALIGNMENT_LEFT = 1 ///< Data alignment left 77 } adc_alignment_t; 78 79 #ifndef BSP_OVERRIDE_ADC_TRIGGER_T 80 81 /** ADC trigger mode definitions */ 82 typedef enum e_adc_trigger 83 { 84 ADC_TRIGGER_SOFTWARE = 0, ///< Software trigger; not for group modes 85 ADC_TRIGGER_SYNC_ELC = 2, ///< Synchronous trigger via ELC 86 ADC_TRIGGER_ASYNC_EXTERNAL = 3, ///< External asynchronous trigger; not for group modes 87 } adc_trigger_t; 88 89 #endif 90 91 #ifndef BSP_OVERRIDE_ADC_EVENT_T 92 93 /** ADC callback event definitions */ 94 typedef enum e_adc_event 95 { 96 ADC_EVENT_SCAN_COMPLETE, ///< Normal/Group A scan complete 97 ADC_EVENT_SCAN_COMPLETE_GROUP_B, ///< Group B scan complete 98 ADC_EVENT_SCAN_COMPLETE_GROUP_C, ///< Group C scan complete 99 ADC_EVENT_CALIBRATION_COMPLETE, ///< Calibration complete 100 ADC_EVENT_CONVERSION_COMPLETE, ///< Conversion complete 101 ADC_EVENT_CALIBRATION_REQUEST, ///< Calibration requested 102 ADC_EVENT_CONVERSION_ERROR, ///< Scan error 103 ADC_EVENT_OVERFLOW, ///< Overflow occurred 104 ADC_EVENT_LIMIT_CLIP, ///< Limiter clipping occurred 105 ADC_EVENT_FIFO_READ_REQUEST, ///< FIFO read requested 106 ADC_EVENT_FIFO_OVERFLOW, ///< FIFO overflow occurred 107 ADC_EVENT_WINDOW_COMPARE_A, ///< Window A comparison condition met 108 ADC_EVENT_WINDOW_COMPARE_B, ///< Window B comparison condition met 109 } adc_event_t; 110 111 #endif 112 113 #ifndef BSP_OVERRIDE_ADC_CHANNEL_T 114 115 /** ADC channels */ 116 typedef enum e_adc_channel 117 { 118 ADC_CHANNEL_0 = 0, ///< ADC channel 0 119 ADC_CHANNEL_1 = 1, ///< ADC channel 1 120 ADC_CHANNEL_2 = 2, ///< ADC channel 2 121 ADC_CHANNEL_3 = 3, ///< ADC channel 3 122 ADC_CHANNEL_4 = 4, ///< ADC channel 4 123 ADC_CHANNEL_5 = 5, ///< ADC channel 5 124 ADC_CHANNEL_6 = 6, ///< ADC channel 6 125 ADC_CHANNEL_7 = 7, ///< ADC channel 7 126 ADC_CHANNEL_8 = 8, ///< ADC channel 8 127 ADC_CHANNEL_9 = 9, ///< ADC channel 9 128 ADC_CHANNEL_10 = 10, ///< ADC channel 10 129 ADC_CHANNEL_11 = 11, ///< ADC channel 11 130 ADC_CHANNEL_12 = 12, ///< ADC channel 12 131 ADC_CHANNEL_13 = 13, ///< ADC channel 13 132 ADC_CHANNEL_14 = 14, ///< ADC channel 14 133 ADC_CHANNEL_15 = 15, ///< ADC channel 15 134 ADC_CHANNEL_16 = 16, ///< ADC channel 16 135 ADC_CHANNEL_17 = 17, ///< ADC channel 17 136 ADC_CHANNEL_18 = 18, ///< ADC channel 18 137 ADC_CHANNEL_19 = 19, ///< ADC channel 19 138 ADC_CHANNEL_20 = 20, ///< ADC channel 20 139 ADC_CHANNEL_21 = 21, ///< ADC channel 21 140 ADC_CHANNEL_22 = 22, ///< ADC channel 22 141 ADC_CHANNEL_23 = 23, ///< ADC channel 23 142 ADC_CHANNEL_24 = 24, ///< ADC channel 24 143 ADC_CHANNEL_25 = 25, ///< ADC channel 25 144 ADC_CHANNEL_26 = 26, ///< ADC channel 26 145 ADC_CHANNEL_27 = 27, ///< ADC channel 27 146 ADC_CHANNEL_28 = 28, ///< ADC channel 28 147 ADC_CHANNEL_DUPLEX_A = 50, ///< Data duplexing register A 148 ADC_CHANNEL_DUPLEX_B = 51, ///< Data duplexing register B 149 ADC_CHANNEL_DUPLEX = -4, ///< Data duplexing register 150 ADC_CHANNEL_TEMPERATURE = -3, ///< Temperature sensor output 151 ADC_CHANNEL_VOLT = -2, ///< Internal reference voltage 152 } adc_channel_t; 153 154 #endif 155 156 typedef enum e_adc_group_id 157 { 158 ADC_GROUP_ID_0 = 0, ///< Group ID 0 159 ADC_GROUP_ID_1 = 1, ///< Group ID 1 160 ADC_GROUP_ID_2 = 2, ///< Group ID 2 161 ADC_GROUP_ID_3 = 3, ///< Group ID 3 162 ADC_GROUP_ID_4 = 4, ///< Group ID 4 163 ADC_GROUP_ID_5 = 5, ///< Group ID 5 164 ADC_GROUP_ID_6 = 6, ///< Group ID 6 165 ADC_GROUP_ID_7 = 7, ///< Group ID 7 166 ADC_GROUP_ID_8 = 8, ///< Group ID 8 167 } adc_group_id_t; 168 169 typedef enum e_adc_group_mask 170 { 171 ADC_GROUP_MASK_NONE = 0x000, ///< Group Mask Unknown or None 172 ADC_GROUP_MASK_0 = 0x001, ///< Group Mask 0 173 ADC_GROUP_MASK_1 = 0x002, ///< Group Mask 1 174 ADC_GROUP_MASK_2 = 0x004, ///< Group Mask 2 175 ADC_GROUP_MASK_3 = 0x008, ///< Group Mask 3 176 ADC_GROUP_MASK_4 = 0x010, ///< Group Mask 4 177 ADC_GROUP_MASK_5 = 0x020, ///< Group Mask 5 178 ADC_GROUP_MASK_6 = 0x040, ///< Group Mask 6 179 ADC_GROUP_MASK_7 = 0x080, ///< Group Mask 7 180 ADC_GROUP_MASK_8 = 0x100, ///< Group Mask 8 181 ADC_GROUP_MASK_ALL = 0x1FF, ///< All Groups 182 } adc_group_mask_t; 183 184 /** ADC states. */ 185 typedef enum e_adc_state 186 { 187 ADC_STATE_IDLE = 0, ///< ADC is idle 188 ADC_STATE_SCAN_IN_PROGRESS = 1, ///< ADC scan in progress 189 ADC_STATE_CALIBRATION_IN_PROGRESS = 2, ///< ADC calibration in progress - Not used by all ADC instances 190 } adc_state_t; 191 192 /** ADC status. */ 193 typedef struct st_adc_status 194 { 195 adc_state_t state; ///< Current state 196 } adc_status_t; 197 198 /** ADC callback arguments definitions */ 199 typedef struct st_adc_callback_args 200 { 201 uint16_t unit; ///< ADC device in use 202 adc_event_t event; ///< ADC callback event 203 void const * p_context; ///< Placeholder for user data 204 adc_channel_t channel; ///< Channel of conversion result. Only valid for r_adc ADC_EVENT_CONVERSION_COMPLETE 205 uint64_t channel_mask; ///< Channel mask for conversion result. Only valid for r_adc_b 206 adc_group_mask_t group_mask; ///< Group Mask 207 } adc_callback_args_t; 208 209 #ifndef BSP_OVERRIDE_ADC_INFO_T 210 211 /** ADC Information Structure for Transfer Interface */ 212 typedef struct st_adc_info 213 { 214 __I void * p_address; ///< The address to start reading the data from 215 uint32_t length; ///< The total number of transfers to read 216 217 transfer_size_t transfer_size; ///< The size of each transfer 218 elc_peripheral_t elc_peripheral; ///< Name of the peripheral in the ELC list 219 elc_event_t elc_event; ///< Name of the ELC event for the peripheral 220 uint32_t calibration_data; ///< Temperature sensor calibration data (0xFFFFFFFF if unsupported) for reference voltage 221 int16_t slope_microvolts; ///< Temperature sensor slope in microvolts/degrees C 222 bool calibration_ongoing; ///< Calibration is in progress. 223 } adc_info_t; 224 225 #endif 226 227 /** ADC general configuration */ 228 typedef struct st_adc_cfg 229 { 230 uint16_t unit; ///< ADC unit to be used 231 adc_mode_t mode; ///< ADC operation mode 232 adc_resolution_t resolution; ///< ADC resolution 233 adc_alignment_t alignment; ///< Specify left or right alignment; ignored if addition used 234 adc_trigger_t trigger; ///< Default and Group A trigger source 235 IRQn_Type scan_end_irq; ///< Scan end IRQ number 236 IRQn_Type scan_end_b_irq; ///< Scan end group B IRQ number 237 IRQn_Type scan_end_c_irq; ///< Scan end group C IRQ number 238 uint8_t scan_end_ipl; ///< Scan end interrupt priority 239 uint8_t scan_end_b_ipl; ///< Scan end group B interrupt priority 240 uint8_t scan_end_c_ipl; ///< Scan end group C interrupt priority 241 void (* p_callback)(adc_callback_args_t * p_args); ///< Callback function; set to NULL for none 242 void const * p_context; ///< Placeholder for user data. Passed to the user callback in @ref adc_callback_args_t. 243 void const * p_extend; ///< Extension parameter for hardware specific settings 244 } adc_cfg_t; 245 246 /** ADC control block. Allocate using driver instance control structure from driver instance header file. */ 247 typedef void adc_ctrl_t; 248 249 /** ADC functions implemented at the HAL layer will follow this API. */ 250 typedef struct st_adc_api 251 { 252 /** Initialize ADC Unit; apply power, set the operational mode, trigger sources, interrupt priority, 253 * and configurations common to all channels and sensors. 254 * @par Implemented as 255 * - @ref R_ADC_C_Open() 256 * 257 * @pre Configure peripheral clocks, ADC pins and IRQs prior to calling this function. 258 * @param[in] p_ctrl Pointer to control handle structure 259 * @param[in] p_cfg Pointer to configuration structure 260 */ 261 fsp_err_t (* open)(adc_ctrl_t * const p_ctrl, adc_cfg_t const * const p_cfg); 262 263 /** Configure the scan including the channels, groups, and scan triggers to be used for the unit that 264 * was initialized in the open call. Some configurations are not supported for all implementations. 265 * See implementation for details. 266 * @par Implemented as 267 * - @ref R_ADC_C_ScanCfg() 268 * 269 * @param[in] p_ctrl Pointer to control handle structure 270 * @param[in] p_extend See implementation for details 271 */ 272 fsp_err_t (* scanCfg)(adc_ctrl_t * const p_ctrl, void const * const p_extend); 273 274 /** Start the scan (in case of a software trigger), or enable the hardware trigger. 275 * @par Implemented as 276 * - @ref R_ADC_C_ScanStart() 277 * 278 * @param[in] p_ctrl Pointer to control handle structure 279 */ 280 fsp_err_t (* scanStart)(adc_ctrl_t * const p_ctrl); 281 282 /** Start the scan group (in case of a software trigger), or enable the hardware trigger. 283 * @par Implemented as 284 * - @ref R_ADC_C_ScanGroupStart() 285 * 286 * @param[in] p_ctrl Pointer to control handle structure 287 * @param[in] group_mask Mask of groups to start 288 */ 289 fsp_err_t (* scanGroupStart)(adc_ctrl_t * p_ctrl, adc_group_mask_t group_mask); 290 291 /** Stop the ADC scan (in case of a software trigger), or disable the hardware trigger. 292 * @par Implemented as 293 * - @ref R_ADC_C_ScanStop() 294 * 295 * @param[in] p_ctrl Pointer to control handle structure 296 */ 297 fsp_err_t (* scanStop)(adc_ctrl_t * const p_ctrl); 298 299 /** Check scan status. 300 * @par Implemented as 301 * - @ref R_ADC_C_StatusGet() 302 * 303 * @param[in] p_ctrl Pointer to control handle structure 304 * @param[out] p_status Pointer to store current status in 305 */ 306 fsp_err_t (* scanStatusGet)(adc_ctrl_t * const p_ctrl, adc_status_t * p_status); 307 308 /** Read ADC conversion result. 309 * @par Implemented as 310 * - @ref R_ADC_C_Read() 311 * 312 * @param[in] p_ctrl Pointer to control handle structure 313 * @param[in] reg_id ADC channel to read (see enumeration adc_channel_t) 314 * @param[in] p_data Pointer to variable to load value into. 315 */ 316 fsp_err_t (* read)(adc_ctrl_t * const p_ctrl, adc_channel_t const reg_id, uint16_t * const p_data); 317 318 /** Read ADC conversion result into a 32-bit word. 319 * @par Implemented as 320 * - @ref R_ADC_C_Read32() 321 * 322 * @param[in] p_ctrl Pointer to control handle structure 323 * @param[in] reg_id ADC channel to read (see enumeration adc_channel_t) 324 * @param[in] p_data Pointer to variable to load value into. 325 */ 326 fsp_err_t (* read32)(adc_ctrl_t * const p_ctrl, adc_channel_t const reg_id, uint32_t * const p_data); 327 328 /** Calibrate ADC or associated PGA (programmable gain amplifier). The driver may require implementation specific 329 * arguments to the p_extend input. Not supported for all implementations. See implementation for details. 330 * @par Implemented as 331 * - @ref R_ADC_C_Calibrate() 332 * 333 * @param[in] p_ctrl Pointer to control handle structure 334 * @param[in] p_extend Pointer to implementation specific arguments 335 */ 336 fsp_err_t (* calibrate)(adc_ctrl_t * const p_ctrl, void const * p_extend); 337 338 /** Set offset for input PGA configured for differential input. Not supported for all implementations. 339 * See implementation for details. 340 * @par Implemented as 341 * - @ref R_ADC_C_OffsetSet() 342 * 343 * @param[in] p_ctrl Pointer to control handle structure 344 * @param[in] reg_id ADC channel to read (see enumeration adc_channel_t) 345 * @param[in] offset See implementation for details. 346 */ 347 fsp_err_t (* offsetSet)(adc_ctrl_t * const p_ctrl, adc_channel_t const reg_id, int32_t const offset); 348 349 /** 350 * Specify callback function and optional context pointer and working memory pointer. 351 * @par Implemented as 352 * - @ref R_ADC_C_CallbackSet() 353 * 354 * @param[in] p_ctrl Pointer to the ADC control block. 355 * @param[in] p_callback Callback function 356 * @param[in] p_context Pointer to send to callback function 357 * @param[in] p_working_memory Pointer to volatile memory where callback structure can be allocated. 358 * Callback arguments allocated here are only valid during the callback. 359 */ 360 fsp_err_t (* callbackSet)(adc_ctrl_t * const p_api_ctrl, void (* p_callback)(adc_callback_args_t *), 361 void const * const p_context, adc_callback_args_t * const p_callback_memory); 362 363 /** Close the specified ADC unit by ending any scan in progress, disabling interrupts, and removing power to the 364 * specified A/D unit. 365 * @par Implemented as 366 * - @ref R_ADC_C_Close() 367 * 368 * @param[in] p_ctrl Pointer to control handle structure 369 */ 370 fsp_err_t (* close)(adc_ctrl_t * const p_ctrl); 371 372 /** Return the ADC data register address of the first (lowest number) channel and the total number of bytes 373 * to be read in order for the DTC/DMAC to read the conversion results of all configured channels. 374 * Return the temperature sensor calibration and slope data. 375 * @par Implemented as 376 * - @ref R_ADC_C_InfoGet() 377 * 378 * @param[in] p_ctrl Pointer to control handle structure 379 * @param[out] p_adc_info Pointer to ADC information structure 380 */ 381 fsp_err_t (* infoGet)(adc_ctrl_t * const p_ctrl, adc_info_t * const p_adc_info); 382 } adc_api_t; 383 384 /** This structure encompasses everything that is needed to use an instance of this interface. */ 385 typedef struct st_adc_instance 386 { 387 adc_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 388 adc_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 389 void const * p_channel_cfg; ///< Pointer to the channel configuration structure for this instance 390 adc_api_t const * p_api; ///< Pointer to the API structure for this instance 391 } adc_instance_t; 392 393 /*******************************************************************************************************************//** 394 * @} (end defgroup ADC_API) 395 **********************************************************************************************************************/ 396 397 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */ 398 FSP_FOOTER 399 #endif 400
