1 /*
2  * Copyright (C) 2017-2019 Alibaba Group Holding Limited
3  */
4 
5 
6 /******************************************************************************
7  * @file     drv_adc.h
8  * @brief    Header File for ADC Driver
9  * @version  V1.0
10  * @date     15. October 2017
11  * @model    adc
12  ******************************************************************************/
13 #ifndef _CSI_ADC_H_
14 #define _CSI_ADC_H_
15 
16 
17 #include <stdint.h>
18 #include <drv/errno.h>
19 #include <drv/common.h>
20 
21 #ifdef __cplusplus
22 extern "C" {
23 #endif
24 /// definition for adc handle.
25 typedef void *adc_handle_t;
26 
27 /****** ADC conversion mode *****/
28 typedef enum {
29     ADC_SINGLE = 0,       ///< Single conversion mode --- select one channel to convert at a time.
30     ADC_CONTINUOUS,       ///< Continuous conversion mode --- select a channel to convert in a specific times.
31     ADC_SCAN,             ///< Scan mode --- select a group channel to convert at a time.
32 } adc_mode_e;
33 
34 /****** ADC Event *****/
35 typedef enum {
36     ADC_EVENT_CONVERSION_COMPLETE = 0,   ///< All data conversion completed.
37     ADC_EVENT_DATA_LOST,                 ///< Data lost: adc buffer overflow / transmit underflow.
38     ADC_EVENT_DATA_OVERWRITE,            ///< Converted data has not been read before the new conversion result is load to the data register.
39     ADC_EVENT_DATA_COMPARE_VALID,        ///< Data compare right with adc comparator.
40 } adc_event_e;
41 
42 /****** ADC Status *****/
43 typedef struct {
44     uint32_t busy       : 1;              ///< adc conversion on going.
45     uint32_t data_lost  : 1;              ///< adc buffer overflow.
46     uint32_t complete   : 1;              ///< adc conversion completion.
47     uint32_t compare_valid : 1;           ///< data valid through adc comparator.
48 } adc_status_t;
49 
50 /**
51 \brief ADC Driver Capabilities.
52 */
53 typedef struct {
54     uint32_t single : 1;
55     uint32_t continuous : 1;
56     uint32_t scan : 1;
57     uint32_t calibration : 1;
58     uint32_t comparator : 1;
59 } adc_capabilities_t;
60 
61 typedef struct {
62     uint32_t    clk_prescaler;  ///< select ADC clock  prescaler.
63     adc_mode_e  mode;           ///< \ref adc_mode_e
64     uint32_t    trigger;  ///< 0 -- software adc start or 1 -- external event trigger to start adc.
65     uint32_t    intrp_mode;  ///< specifies whether the ADC is configured is interrupt mode (1)or in polling mode (0).
66     uint32_t   *channel_array;  ///< channel array base address, the ordinal of channel count from zero, like ADC_CHANNEL0 (0), ADC_CHANNEL1(1), etc.
67     uint32_t    channel_nbr; ///< specifies the number of channels in channel array that will be converted.
68     uint32_t    conv_cnt;  ///< conversion count times for conversion mode.
69     uint32_t    sampling_time; ///< sampling time value to be set for the selected channel. Unit:ADC clock cycles.
70     uint32_t    offset;  ///< reserved for future use, can be set to 0.
71 } adc_conf_t;
72 
73 typedef struct {
74     uint32_t    cmp_data;        ///< the data is used to compare with conversion result of specified channel.
75     uint32_t    cmp_channel;     ///< compare channel selection.
76     uint32_t    cmp_condition;   ///< compare condition: 0 = Set the compare condition as that when a A/D conversion result is less than the cmp_data. 1 = Set the compare condition as that when a A/D conversion result is greater or equal to the cmp_data.
77     uint32_t    cmp_match_cnt;   ///< when the specified A/D channel analog conversion result matches the compare condition defined by cmp_condition, the internal match counter will increase 1. When the internal counter reaches the value to (cpm_match_cnt), the correspond status or flag bit will be set.
78 } adc_cmp_conf_t;
79 
80 typedef void (*adc_event_cb_t)(int32_t idx, adc_event_e event);  ///< Pointer to \ref adc_event_cb_t : adc Event call back.
81 
82 /**
83   \brief       Initialize adc Interface. 1. Initializes the resources needed for the adc interface 2.registers event callback function.
84   \param[in]   idx       adc index.
85   \param[in]   cb_event  event call back function \ref adc_event_cb_t
86   \return      return adc handle if success
87 */
88 adc_handle_t drv_adc_initialize(int32_t idx, adc_event_cb_t cb_event);
89 
90 /**
91   \brief       De-initialize adc Interface. stops operation and releases the software resources used by the interface
92   \param[in]   handle   adc handle to operate.
93   \return      error code
94 */
95 int32_t drv_adc_uninitialize(adc_handle_t handle);
96 
97 /**
98   \brief       control adc power.
99   \param[in]   handle  adc handle to operate.
100   \param[in]   state   power state.\ref csi_power_stat_e.
101   \return      error code
102 */
103 int32_t drv_adc_power_control(adc_handle_t handle, csi_power_stat_e state);
104 
105 /**
106   \brief       Get driver capabilities.
107   \param[in]   idx    adc index.
108   \return      \ref adc_capabilities_t
109 */
110 adc_capabilities_t drv_adc_get_capabilities(int32_t idx);
111 
112 
113 int32_t drv_adc_pin2channel(int pin);
114 
115 /**
116   \brief       config adc mode.
117   \param[in]   handle     adc handle to operate.
118   \param[in]   config   adc_conf_t\ref  . pointer to adc configuration structure.
119   \return      error code
120 */
121 int32_t drv_adc_config(adc_handle_t handle, adc_conf_t *config);
122 
123 /**
124   \brief       config adc comparator.
125   \param[in]   handle     adc handle to operate.
126   \param[in]   config   adc_conf_t\ref  . pointer to adc configuration structure.
127   \return      error code
128 */
129 int32_t drv_adc_comparator_config(adc_handle_t handle, adc_cmp_conf_t *config);
130 
131 /**
132   \brief       start adc.
133   \param[in]   handle adc handle to operate.
134   \return      error code
135 */
136 int32_t drv_adc_start(adc_handle_t handle);
137 
138 /**
139   \brief       stop adc.
140   \param[in]   handle adc handle to operate.
141   \return      error code
142 */
143 int32_t drv_adc_stop(adc_handle_t handle);
144 
145 /**
146   \brief       receiving data from ADC receiver.
147   \param[in]   handle ADC handle to operate.
148   \param[out]  data  Pointer to buffer for data to receive from ADC receiver, the data array is correspond to channel array.
149   \param[in]   num   Number of data items to receive.
150   \return      error code
151 */
152 int32_t drv_adc_read(adc_handle_t handle, uint32_t *data, uint32_t num);
153 
154 /**
155   \brief       Get ADC status.
156   \param[in]   handle   adc handle to operate.
157   \return      ADC status \ref adc_status_t
158 */
159 adc_status_t drv_adc_get_status(adc_handle_t handle);
160 
161 #ifdef __cplusplus
162 }
163 #endif
164 
165 #endif /* _CSI_ADC_H_ */
166