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