| /* SPDX-License-Identifier: GPL-2.0+ */ |
| /* |
| * Copyright (C) 2015 Samsung Electronics |
| * Przemyslaw Marczak <p.marczak@samsung.com> |
| */ |
| |
| #ifndef _ADC_H_ |
| #define _ADC_H_ |
| |
| #include <stdbool.h> |
| |
| /* ADC_CHANNEL() - ADC channel bit mask, to select only required channels */ |
| #define ADC_CHANNEL(x) (1 << x) |
| |
| /* The last possible selected channel with 32-bit mask */ |
| #define ADC_MAX_CHANNEL 31 |
| |
| /** |
| * adc_data_format: define the ADC output data format, can be useful when |
| * the device's input Voltage range is bipolar. |
| * - ADC_DATA_FORMAT_BIN - binary offset |
| * - ADC_DATA_FORMAT_2S - two's complement |
| * |
| * Note: Device's driver should fill the 'data_format' field of its uclass's |
| * platform data using one of the above data format types. |
| */ |
| enum adc_data_format { |
| ADC_DATA_FORMAT_BIN, |
| ADC_DATA_FORMAT_2S, |
| }; |
| |
| /** |
| * struct adc_channel - structure to hold channel conversion data. |
| * Useful to keep the result of a multi-channel conversion output. |
| * |
| * @id - channel id |
| * @data - channel conversion data |
| */ |
| struct adc_channel { |
| int id; |
| unsigned int data; |
| }; |
| |
| /** |
| * struct adc_uclass_plat - basic ADC info |
| * |
| * Note: The positive/negative reference Voltage is only a name and it doesn't |
| * provide an information about the value polarity. It is possible, for both |
| * values to be a negative or positive. For this purpose the uclass's platform |
| * data provides a bool fields: 'vdd/vss_supply_is_negative'. This is useful, |
| * since the regulator API returns only a positive Voltage values. |
| * |
| * To get the reference Voltage values with polarity, use functions: |
| * - adc_vdd_value() |
| * - adc_vss_value() |
| * Those are useful for some cases of ADC's references, e.g.: |
| * * Vdd: +3.3V; Vss: -3.3V -> 6.6 Vdiff |
| * * Vdd: +3.3V; Vss: +0.3V -> 3.0 Vdiff |
| * * Vdd: +3.3V; Vss: 0.0V -> 3.3 Vdiff |
| * The last one is usually standard and doesn't require the fdt polarity info. |
| * |
| * For more informations read binding info: |
| * - doc/device-tree-bindings/adc/adc.txt |
| * |
| * @data_mask - conversion output data mask |
| * @data_timeout_us - single channel conversion timeout |
| * @multidata_timeout_us - multi channel conversion timeout |
| * @channel_mask - bit mask of available channels [0:31] |
| * @vdd_supply - positive reference Voltage supply (regulator) |
| * @vss_supply - negative reference Voltage supply (regulator) |
| * @vdd_polarity_negative - positive reference Voltage has negative polarity |
| * @vss_polarity_negative - negative reference Voltage has negative polarity |
| * @vdd_microvolts - positive reference Voltage value |
| * @vss_microvolts - negative reference Voltage value |
| */ |
| struct adc_uclass_plat { |
| int data_format; |
| unsigned int data_mask; |
| unsigned int data_timeout_us; |
| unsigned int multidata_timeout_us; |
| unsigned int channel_mask; |
| struct udevice *vdd_supply; |
| struct udevice *vss_supply; |
| bool vdd_polarity_negative; |
| bool vss_polarity_negative; |
| int vdd_microvolts; |
| int vss_microvolts; |
| }; |
| |
| /** |
| * struct adc_ops - ADC device operations for single/multi-channel operation. |
| */ |
| struct adc_ops { |
| /** |
| * start_channel() - start conversion with its default parameters |
| * for the given channel number. |
| * |
| * @dev: ADC device to init |
| * @channel: analog channel number |
| * @return: 0 if OK, -ve on error |
| */ |
| int (*start_channel)(struct udevice *dev, int channel); |
| |
| /** |
| * start_channels() - start conversion with its default parameters |
| * for the channel numbers selected by the bit mask. |
| * |
| * This is optional, useful when the hardware supports multichannel |
| * conversion by the single software trigger. |
| * |
| * @dev: ADC device to init |
| * @channel_mask: bit mask of selected analog channels |
| * @return: 0 if OK, -ve on error |
| */ |
| int (*start_channels)(struct udevice *dev, unsigned int channel_mask); |
| |
| /** |
| * channel_data() - get conversion output data for the given channel. |
| * |
| * Note: The implementation of this function should only check, that |
| * the conversion data is available at the call time. If the hardware |
| * requires some delay to get the data, then this function should |
| * return with -EBUSY value. The ADC API will call it in a loop, |
| * until the data is available or the timeout expires. The maximum |
| * timeout for this operation is defined by the field 'data_timeout_us' |
| * in ADC uclasses platform data structure. |
| * |
| * @dev: ADC device to trigger |
| * @channel: selected analog channel number |
| * @data: returned pointer to selected channel's output data |
| * @return: 0 if OK, -EBUSY if busy, and other negative on error |
| */ |
| int (*channel_data)(struct udevice *dev, int channel, |
| unsigned int *data); |
| |
| /** |
| * channels_data() - get conversion data for the selected channels. |
| * |
| * This is optional, useful when multichannel conversion is supported |
| * by the hardware, by the single software trigger. |
| * |
| * For the proper implementation, please look at the 'Note' for the |
| * above method. The only difference is in used timeout value, which |
| * is defined by field 'multidata_timeout_us'. |
| * |
| * @dev: ADC device to trigger |
| * @channel_mask: bit mask of selected analog channels |
| * @channels: returned pointer to array of output data for channels |
| * selected by the given mask |
| * @return: 0 if OK, -ve on error |
| */ |
| int (*channels_data)(struct udevice *dev, unsigned int channel_mask, |
| struct adc_channel *channels); |
| |
| /** |
| * stop() - stop conversion of the given ADC device |
| * |
| * @dev: ADC device to stop |
| * @return: 0 if OK, -ve on error |
| */ |
| int (*stop)(struct udevice *dev); |
| }; |
| |
| /** |
| * adc_start_channel() - start conversion for given device/channel and exit. |
| * |
| * @dev: ADC device |
| * @channel: analog channel number |
| * @return: 0 if OK, -ve on error |
| */ |
| int adc_start_channel(struct udevice *dev, int channel); |
| |
| /** |
| * adc_start_channels() - start conversion for given device/channels and exit. |
| * |
| * Note: |
| * To use this function, device must implement method: start_channels(). |
| * |
| * @dev: ADC device to start |
| * @channel_mask: channel selection - a bit mask |
| * @channel_mask: bit mask of analog channels |
| * @return: 0 if OK, -ve on error |
| */ |
| int adc_start_channels(struct udevice *dev, unsigned int channel_mask); |
| |
| /** |
| * adc_channel_data() - get conversion data for the given device channel number. |
| * |
| * @dev: ADC device to read |
| * @channel: analog channel number |
| * @data: pointer to returned channel's data |
| * @return: 0 if OK, -ve on error |
| */ |
| int adc_channel_data(struct udevice *dev, int channel, unsigned int *data); |
| |
| /** |
| * adc_channels_data() - get conversion data for the channels selected by mask |
| * |
| * Note: |
| * To use this function, device must implement methods: |
| * - start_channels() |
| * - channels_data() |
| * |
| * @dev: ADC device to read |
| * @channel_mask: channel selection - a bit mask |
| * @channels: pointer to structure array of returned data for each channel |
| * @return: 0 if OK, -ve on error |
| */ |
| int adc_channels_data(struct udevice *dev, unsigned int channel_mask, |
| struct adc_channel *channels); |
| |
| /** |
| * adc_data_mask() - get data mask (ADC resolution bitmask) for given ADC device |
| * |
| * This can be used if adc uclass platform data is filled. |
| * |
| * @dev: ADC device to check |
| * @data_mask: pointer to the returned data bitmask |
| * @return: 0 if OK, -ve on error |
| */ |
| int adc_data_mask(struct udevice *dev, unsigned int *data_mask); |
| |
| /** |
| * adc_channel_mask() - get channel mask for given ADC device |
| * |
| * This can be used if adc uclass platform data is filled. |
| * |
| * @dev: ADC device to check |
| * @channel_mask: pointer to the returned channel bitmask |
| * @return: 0 if OK, -ve on error |
| */ |
| int adc_channel_mask(struct udevice *dev, unsigned int *channel_mask); |
| |
| /** |
| * adc_channel_single_shot() - get output data of conversion for the ADC |
| * device's channel. This function searches for the device with the given name, |
| * starts the given channel conversion and returns the output data. |
| * |
| * Note: To use this function, device must implement metods: |
| * - start_channel() |
| * - channel_data() |
| * |
| * @name: device's name to search |
| * @channel: device's input channel to init |
| * @data: pointer to conversion output data |
| * @return: 0 if OK, -ve on error |
| */ |
| int adc_channel_single_shot(const char *name, int channel, unsigned int *data); |
| |
| /** |
| * adc_channels_single_shot() - get ADC conversion output data for the selected |
| * device's channels. This function searches for the device by the given name, |
| * starts the selected channels conversion and returns the output data as array |
| * of type 'struct adc_channel'. |
| * |
| * Note: This function can be used if device implements one of ADC's single |
| * or multi-channel operation API. If multi-channel operation is not supported, |
| * then each selected channel is triggered by the sequence start/data in a loop. |
| * |
| * @name: device's name to search |
| * @channel_mask: channel selection - a bit mask |
| * @channels: pointer to conversion output data for the selected channels |
| * @return: 0 if OK, -ve on error |
| */ |
| int adc_channels_single_shot(const char *name, unsigned int channel_mask, |
| struct adc_channel *channels); |
| |
| /** |
| * adc_vdd_value() - get the ADC device's positive reference Voltage value |
| * |
| * Note: Depending on bool value 'vdd_supply_is_negative' of platform data, |
| * the returned uV value can be negative, and it's not an error. |
| * |
| * @dev: ADC device to check |
| * @uV: Voltage value with polarization sign (uV) |
| * @return: 0 on success or -ve on error |
| */ |
| int adc_vdd_value(struct udevice *dev, int *uV); |
| |
| /** |
| * adc_vss_value() - get the ADC device's negative reference Voltage value |
| * |
| * Note: Depending on bool value 'vdd_supply_is_negative' of platform data, |
| * the returned uV value can be negative, and it's not an error. |
| * |
| * @dev: ADC device to check |
| * @uV: Voltage value with polarization sign (uV) |
| * @return: 0 on success or -ve on error |
| */ |
| int adc_vss_value(struct udevice *dev, int *uV); |
| |
| /** |
| * adc_stop() - stop operation for given ADC device. |
| * |
| * @dev: ADC device to stop |
| * @return: 0 if OK, -ve on error |
| */ |
| int adc_stop(struct udevice *dev); |
| |
| /** |
| * adc_raw_to_uV() - converts raw value to microvolts for given ADC device. |
| * |
| * @dev: ADC device used from conversion |
| * @raw: raw value to convert |
| * @uV: converted value in microvolts |
| * @return: 0 on success or -ve on error |
| */ |
| int adc_raw_to_uV(struct udevice *dev, unsigned int raw, int *uV); |
| |
| #endif |