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 */ 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_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 */ 74struct 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 */ 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/** 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 */ 230int 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 */ 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 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 */ 306int adc_raw_to_uV(struct udevice *dev, unsigned int raw, int *uV); 307 308#endif 309