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