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