1 /* 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 */ 26 enum 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 */ 38 struct 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 */ 75 struct 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 */ 92 struct 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 */ 170 int 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 */ 183 int 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 */ 193 int 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 */ 208 int 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 */ 220 int 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 */ 236 int 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 */ 253 int 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 */ 266 int 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 */ 278 int 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 */ 286 int adc_stop(struct udevice *dev); 287 288 #endif 289