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