1 /* SPDX-License-Identifier: GPL-2.0+ */
2 /*
3  * Copyright (C) 2015 Samsung Electronics
4  * Przemyslaw Marczak <p.marczak@samsung.com>
5  */
6 
7 #ifndef _ADC_H_
8 #define _ADC_H_
9 
10 /* ADC_CHANNEL() - ADC channel bit mask, to select only required channels */
11 #define ADC_CHANNEL(x)		(1 << x)
12 
13 /* The last possible selected channel with 32-bit mask */
14 #define ADC_MAX_CHANNEL		31
15 
16 /**
17  * adc_data_format: define the ADC output data format, can be useful when
18  * the device's input Voltage range is bipolar.
19  * - ADC_DATA_FORMAT_BIN - binary offset
20  * - ADC_DATA_FORMAT_2S  - two's complement
21  *
22  * Note: Device's driver should fill the 'data_format' field of its uclass's
23  * platform data using one of the above data format types.
24  */
25 enum adc_data_format {
26 	ADC_DATA_FORMAT_BIN,
27 	ADC_DATA_FORMAT_2S,
28 };
29 
30 /**
31  * struct adc_channel - structure to hold channel conversion data.
32  * Useful to keep the result of a multi-channel conversion output.
33  *
34  * @id   - channel id
35  * @data - channel conversion data
36  */
37 struct adc_channel {
38 	int id;
39 	unsigned int data;
40 };
41 
42 /**
43  * struct adc_uclass_plat - basic ADC info
44  *
45  * Note: The positive/negative reference Voltage is only a name and it doesn't
46  * provide an information about the value polarity. It is possible, for both
47  * values to be a negative or positive. For this purpose the uclass's platform
48  * data provides a bool fields: 'vdd/vss_supply_is_negative'. This is useful,
49  * since the regulator API returns only a positive Voltage values.
50  *
51  * To get the reference Voltage values with polarity, use functions:
52  * - adc_vdd_value()
53  * - adc_vss_value()
54  * Those are useful for some cases of ADC's references, e.g.:
55  * * Vdd: +3.3V; Vss: -3.3V -> 6.6 Vdiff
56  * * Vdd: +3.3V; Vss: +0.3V -> 3.0 Vdiff
57  * * Vdd: +3.3V; Vss:  0.0V -> 3.3 Vdiff
58  * The last one is usually standard and doesn't require the fdt polarity info.
59  *
60  * For more informations read binding info:
61  * - doc/device-tree-bindings/adc/adc.txt
62  *
63  * @data_mask              - conversion output data mask
64  * @data_timeout_us        - single channel conversion timeout
65  * @multidata_timeout_us   - multi channel conversion timeout
66  * @channel_mask           - bit mask of available channels [0:31]
67  * @vdd_supply             - positive reference Voltage supply (regulator)
68  * @vss_supply             - negative reference Voltage supply (regulator)
69  * @vdd_polarity_negative  - positive reference Voltage has negative polarity
70  * @vss_polarity_negative  - negative reference Voltage has negative polarity
71  * @vdd_microvolts         - positive reference Voltage value
72  * @vss_microvolts         - negative reference Voltage value
73  */
74 struct adc_uclass_plat {
75 	int data_format;
76 	unsigned int data_mask;
77 	unsigned int data_timeout_us;
78 	unsigned int multidata_timeout_us;
79 	unsigned int channel_mask;
80 	struct udevice *vdd_supply;
81 	struct udevice *vss_supply;
82 	bool vdd_polarity_negative;
83 	bool vss_polarity_negative;
84 	int vdd_microvolts;
85 	int vss_microvolts;
86 };
87 
88 /**
89  * struct adc_ops - ADC device operations for single/multi-channel operation.
90  */
91 struct adc_ops {
92 	/**
93 	 * start_channel() - start conversion with its default parameters
94 	 *                   for the given channel number.
95 	 *
96 	 * @dev:          ADC device to init
97 	 * @channel:      analog channel number
98 	 * @return:       0 if OK, -ve on error
99 	 */
100 	int (*start_channel)(struct udevice *dev, int channel);
101 
102 	/**
103 	 * start_channels() - start conversion with its default parameters
104 	 *                    for the channel numbers selected by the bit mask.
105 	 *
106 	 * This is optional, useful when the hardware supports multichannel
107 	 * conversion by the single software trigger.
108 	 *
109 	 * @dev:          ADC device to init
110 	 * @channel_mask: bit mask of selected analog channels
111 	 * @return:       0 if OK, -ve on error
112 	 */
113 	int (*start_channels)(struct udevice *dev, unsigned int channel_mask);
114 
115 	/**
116 	 * channel_data() - get conversion output data for the given channel.
117 	 *
118 	 * Note: The implementation of this function should only check, that
119 	 * the conversion data is available at the call time. If the hardware
120 	 * requires some delay to get the data, then this function should
121 	 * return with -EBUSY value. The ADC API will call it in a loop,
122 	 * until the data is available or the timeout expires. The maximum
123 	 * timeout for this operation is defined by the field 'data_timeout_us'
124 	 * in ADC uclasses platform data structure.
125 	 *
126 	 * @dev:          ADC device to trigger
127 	 * @channel:      selected analog channel number
128 	 * @data:         returned pointer to selected channel's output data
129 	 * @return:       0 if OK, -EBUSY if busy, and other negative on error
130 	 */
131 	int (*channel_data)(struct udevice *dev, int channel,
132 			    unsigned int *data);
133 
134 	/**
135 	 * channels_data() - get conversion data for the selected channels.
136 	 *
137 	 * This is optional, useful when multichannel conversion is supported
138 	 * by the hardware, by the single software trigger.
139 	 *
140 	 * For the proper implementation, please look at the 'Note' for the
141 	 * above method. The only difference is in used timeout value, which
142 	 * is defined by field 'multidata_timeout_us'.
143 	 *
144 	 * @dev:          ADC device to trigger
145 	 * @channel_mask: bit mask of selected analog channels
146 	 * @channels:     returned pointer to array of output data for channels
147 	 *                selected by the given mask
148 	 * @return:       0 if OK, -ve on error
149 	 */
150 	int (*channels_data)(struct udevice *dev, unsigned int channel_mask,
151 			     struct adc_channel *channels);
152 
153 	/**
154 	 * stop() - stop conversion of the given ADC device
155 	 *
156 	 * @dev:          ADC device to stop
157 	 * @return:       0 if OK, -ve on error
158 	 */
159 	int (*stop)(struct udevice *dev);
160 };
161 
162 /**
163  * adc_start_channel() - start conversion for given device/channel and exit.
164  *
165  * @dev:     ADC device
166  * @channel: analog channel number
167  * @return:  0 if OK, -ve on error
168  */
169 int adc_start_channel(struct udevice *dev, int channel);
170 
171 /**
172  * adc_start_channels() - start conversion for given device/channels and exit.
173  *
174  * Note:
175  * To use this function, device must implement method: start_channels().
176  *
177  * @dev:          ADC device to start
178  * @channel_mask: channel selection - a bit mask
179  * @channel_mask: bit mask of analog channels
180  * @return:       0 if OK, -ve on error
181  */
182 int adc_start_channels(struct udevice *dev, unsigned int channel_mask);
183 
184 /**
185  * adc_channel_data() - get conversion data for the given device channel number.
186  *
187  * @dev:     ADC device to read
188  * @channel: analog channel number
189  * @data:    pointer to returned channel's data
190  * @return:  0 if OK, -ve on error
191  */
192 int adc_channel_data(struct udevice *dev, int channel, unsigned int *data);
193 
194 /**
195  * adc_channels_data() - get conversion data for the channels selected by mask
196  *
197  * Note:
198  * To use this function, device must implement methods:
199  * - start_channels()
200  * - channels_data()
201  *
202  * @dev:          ADC device to read
203  * @channel_mask: channel selection - a bit mask
204  * @channels:     pointer to structure array of returned data for each channel
205  * @return:       0 if OK, -ve on error
206  */
207 int adc_channels_data(struct udevice *dev, unsigned int channel_mask,
208 		      struct adc_channel *channels);
209 
210 /**
211  * adc_data_mask() - get data mask (ADC resolution bitmask) for given ADC device
212  *
213  * This can be used if adc uclass platform data is filled.
214  *
215  * @dev:       ADC device to check
216  * @data_mask: pointer to the returned data bitmask
217  * @return: 0 if OK, -ve on error
218  */
219 int adc_data_mask(struct udevice *dev, unsigned int *data_mask);
220 
221 /**
222  * adc_channel_mask() - get channel mask for given ADC device
223  *
224  * This can be used if adc uclass platform data is filled.
225  *
226  * @dev:       ADC device to check
227  * @channel_mask: pointer to the returned channel bitmask
228  * @return: 0 if OK, -ve on error
229  */
230 int adc_channel_mask(struct udevice *dev, unsigned int *channel_mask);
231 
232 /**
233  * adc_channel_single_shot() - get output data of conversion for the ADC
234  * device's channel. This function searches for the device with the given name,
235  * starts the given channel conversion and returns the output data.
236  *
237  * Note: To use this function, device must implement metods:
238  * - start_channel()
239  * - channel_data()
240  *
241  * @name:    device's name to search
242  * @channel: device's input channel to init
243  * @data:    pointer to conversion output data
244  * @return:  0 if OK, -ve on error
245  */
246 int adc_channel_single_shot(const char *name, int channel, unsigned int *data);
247 
248 /**
249  * adc_channels_single_shot() - get ADC conversion output data for the selected
250  * device's channels. This function searches for the device by the given name,
251  * starts the selected channels conversion and returns the output data as array
252  * of type 'struct adc_channel'.
253  *
254  * Note: This function can be used if device implements one of ADC's single
255  * or multi-channel operation API. If multi-channel operation is not supported,
256  * then each selected channel is triggered by the sequence start/data in a loop.
257  *
258  * @name:         device's name to search
259  * @channel_mask: channel selection - a bit mask
260  * @channels:     pointer to conversion output data for the selected channels
261  * @return:       0 if OK, -ve on error
262  */
263 int adc_channels_single_shot(const char *name, unsigned int channel_mask,
264 			     struct adc_channel *channels);
265 
266 /**
267  * adc_vdd_value() - get the ADC device's positive reference Voltage value
268  *
269  * Note: Depending on bool value 'vdd_supply_is_negative' of platform data,
270  * the returned uV value can be negative, and it's not an error.
271  *
272  * @dev:     ADC device to check
273  * @uV:      Voltage value with polarization sign (uV)
274  * @return:  0 on success or -ve on error
275 */
276 int adc_vdd_value(struct udevice *dev, int *uV);
277 
278 /**
279  * adc_vss_value() - get the ADC device's negative reference Voltage value
280  *
281  * Note: Depending on bool value 'vdd_supply_is_negative' of platform data,
282  * the returned uV value can be negative, and it's not an error.
283  *
284  * @dev:     ADC device to check
285  * @uV:      Voltage value with polarization sign (uV)
286  * @return:  0 on success or -ve on error
287 */
288 int adc_vss_value(struct udevice *dev, int *uV);
289 
290 /**
291  * adc_stop() - stop operation for given ADC device.
292  *
293  * @dev:     ADC device to stop
294  * @return:  0 if OK, -ve on error
295  */
296 int adc_stop(struct udevice *dev);
297 
298 /**
299  * adc_raw_to_uV() - converts raw value to microvolts for given ADC device.
300  *
301  * @dev:     ADC device used from conversion
302  * @raw:     raw value to convert
303  * @uV:	     converted value in microvolts
304  * @return:  0 on success or -ve on error
305  */
306 int adc_raw_to_uV(struct udevice *dev, unsigned int raw, int *uV);
307 
308 #endif
309