blob: 5841dfb54b9fb7747d2183962f6c3680ddcc1f07 [file] [log] [blame]
Tom Rini83d290c2018-05-06 17:58:06 -04001/* SPDX-License-Identifier: GPL-2.0+ */
Przemyslaw Marczak5decbf52015-10-27 13:08:00 +01002/*
3 * Copyright (C) 2015 Samsung Electronics
4 * Przemyslaw Marczak <p.marczak@samsung.com>
Przemyslaw Marczak5decbf52015-10-27 13:08:00 +01005 */
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 */
25enum 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 */
37struct adc_channel {
38 int id;
39 unsigned int data;
40};
41
42/**
43 * struct adc_uclass_platdata - 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 */
74struct adc_uclass_platdata {
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 */
91struct 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 */
169int 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 */
182int 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 */
192int 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 */
207int 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 */
219int adc_data_mask(struct udevice *dev, unsigned int *data_mask);
220
221/**
Fabrice Gasnier63f004e2018-11-12 14:03:58 +0100222 * 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 */
230int adc_channel_mask(struct udevice *dev, unsigned int *channel_mask);
231
232/**
Przemyslaw Marczak5decbf52015-10-27 13:08:00 +0100233 * 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 */
246int 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 */
263int 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*/
276int 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*/
288int 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 */
296int adc_stop(struct udevice *dev);
297
Fabrice Gasnier63f004e2018-11-12 14:03:58 +0100298/**
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 */
306int adc_raw_to_uV(struct udevice *dev, unsigned int raw, int *uV);
307
Przemyslaw Marczak5decbf52015-10-27 13:08:00 +0100308#endif