include/adc.h

   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  */
  25 enum 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  */
  37 struct 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  */
  74 struct 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  */
  91 struct 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  */
 169 int 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  */
 182 int 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  */
 192 int 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  */
 207 int 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  */
 219 int 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  */
 230 int 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  */
 246 int 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  */
 263 int 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 */
 276 int 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 */
 288 int 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  */
 296 int 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  */
 306 int adc_raw_to_uV(struct udevice *dev, unsigned int raw, int *uV);
 307
 308 #endif