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