include/adc.h

   1 /* SPDX-License-Identifier: GPL-2.0+ */
   2 /*
   3  * Copyright (C) 2015 Samsung Electronics
   4  * Przemyslaw Marczak <[email protected]>
   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