adc.h 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308
  1. /* SPDX-License-Identifier: GPL-2.0+ */
  2. /*
  3. * Copyright (C) 2015 Samsung Electronics
  4. * Przemyslaw Marczak <p.marczak@samsung.com>
  5. */
  6. #ifndef _ADC_H_
  7. #define _ADC_H_
  8. /* ADC_CHANNEL() - ADC channel bit mask, to select only required channels */
  9. #define ADC_CHANNEL(x) (1 << x)
  10. /* The last possible selected channel with 32-bit mask */
  11. #define ADC_MAX_CHANNEL 31
  12. /**
  13. * adc_data_format: define the ADC output data format, can be useful when
  14. * the device's input Voltage range is bipolar.
  15. * - ADC_DATA_FORMAT_BIN - binary offset
  16. * - ADC_DATA_FORMAT_2S - two's complement
  17. *
  18. * Note: Device's driver should fill the 'data_format' field of its uclass's
  19. * platform data using one of the above data format types.
  20. */
  21. enum adc_data_format {
  22. ADC_DATA_FORMAT_BIN,
  23. ADC_DATA_FORMAT_2S,
  24. };
  25. /**
  26. * struct adc_channel - structure to hold channel conversion data.
  27. * Useful to keep the result of a multi-channel conversion output.
  28. *
  29. * @id - channel id
  30. * @data - channel conversion data
  31. */
  32. struct adc_channel {
  33. int id;
  34. unsigned int data;
  35. };
  36. /**
  37. * struct adc_uclass_platdata - basic ADC info
  38. *
  39. * Note: The positive/negative reference Voltage is only a name and it doesn't
  40. * provide an information about the value polarity. It is possible, for both
  41. * values to be a negative or positive. For this purpose the uclass's platform
  42. * data provides a bool fields: 'vdd/vss_supply_is_negative'. This is useful,
  43. * since the regulator API returns only a positive Voltage values.
  44. *
  45. * To get the reference Voltage values with polarity, use functions:
  46. * - adc_vdd_value()
  47. * - adc_vss_value()
  48. * Those are useful for some cases of ADC's references, e.g.:
  49. * * Vdd: +3.3V; Vss: -3.3V -> 6.6 Vdiff
  50. * * Vdd: +3.3V; Vss: +0.3V -> 3.0 Vdiff
  51. * * Vdd: +3.3V; Vss: 0.0V -> 3.3 Vdiff
  52. * The last one is usually standard and doesn't require the fdt polarity info.
  53. *
  54. * For more informations read binding info:
  55. * - doc/device-tree-bindings/adc/adc.txt
  56. *
  57. * @data_mask - conversion output data mask
  58. * @data_timeout_us - single channel conversion timeout
  59. * @multidata_timeout_us - multi channel conversion timeout
  60. * @channel_mask - bit mask of available channels [0:31]
  61. * @vdd_supply - positive reference Voltage supply (regulator)
  62. * @vss_supply - negative reference Voltage supply (regulator)
  63. * @vdd_polarity_negative - positive reference Voltage has negative polarity
  64. * @vss_polarity_negative - negative reference Voltage has negative polarity
  65. * @vdd_microvolts - positive reference Voltage value
  66. * @vss_microvolts - negative reference Voltage value
  67. */
  68. struct adc_uclass_platdata {
  69. int data_format;
  70. unsigned int data_mask;
  71. unsigned int data_timeout_us;
  72. unsigned int multidata_timeout_us;
  73. unsigned int channel_mask;
  74. struct udevice *vdd_supply;
  75. struct udevice *vss_supply;
  76. bool vdd_polarity_negative;
  77. bool vss_polarity_negative;
  78. int vdd_microvolts;
  79. int vss_microvolts;
  80. };
  81. /**
  82. * struct adc_ops - ADC device operations for single/multi-channel operation.
  83. */
  84. struct adc_ops {
  85. /**
  86. * start_channel() - start conversion with its default parameters
  87. * for the given channel number.
  88. *
  89. * @dev: ADC device to init
  90. * @channel: analog channel number
  91. * @return: 0 if OK, -ve on error
  92. */
  93. int (*start_channel)(struct udevice *dev, int channel);
  94. /**
  95. * start_channels() - start conversion with its default parameters
  96. * for the channel numbers selected by the bit mask.
  97. *
  98. * This is optional, useful when the hardware supports multichannel
  99. * conversion by the single software trigger.
  100. *
  101. * @dev: ADC device to init
  102. * @channel_mask: bit mask of selected analog channels
  103. * @return: 0 if OK, -ve on error
  104. */
  105. int (*start_channels)(struct udevice *dev, unsigned int channel_mask);
  106. /**
  107. * channel_data() - get conversion output data for the given channel.
  108. *
  109. * Note: The implementation of this function should only check, that
  110. * the conversion data is available at the call time. If the hardware
  111. * requires some delay to get the data, then this function should
  112. * return with -EBUSY value. The ADC API will call it in a loop,
  113. * until the data is available or the timeout expires. The maximum
  114. * timeout for this operation is defined by the field 'data_timeout_us'
  115. * in ADC uclasses platform data structure.
  116. *
  117. * @dev: ADC device to trigger
  118. * @channel: selected analog channel number
  119. * @data: returned pointer to selected channel's output data
  120. * @return: 0 if OK, -EBUSY if busy, and other negative on error
  121. */
  122. int (*channel_data)(struct udevice *dev, int channel,
  123. unsigned int *data);
  124. /**
  125. * channels_data() - get conversion data for the selected channels.
  126. *
  127. * This is optional, useful when multichannel conversion is supported
  128. * by the hardware, by the single software trigger.
  129. *
  130. * For the proper implementation, please look at the 'Note' for the
  131. * above method. The only difference is in used timeout value, which
  132. * is defined by field 'multidata_timeout_us'.
  133. *
  134. * @dev: ADC device to trigger
  135. * @channel_mask: bit mask of selected analog channels
  136. * @channels: returned pointer to array of output data for channels
  137. * selected by the given mask
  138. * @return: 0 if OK, -ve on error
  139. */
  140. int (*channels_data)(struct udevice *dev, unsigned int channel_mask,
  141. struct adc_channel *channels);
  142. /**
  143. * stop() - stop conversion of the given ADC device
  144. *
  145. * @dev: ADC device to stop
  146. * @return: 0 if OK, -ve on error
  147. */
  148. int (*stop)(struct udevice *dev);
  149. };
  150. /**
  151. * adc_start_channel() - start conversion for given device/channel and exit.
  152. *
  153. * @dev: ADC device
  154. * @channel: analog channel number
  155. * @return: 0 if OK, -ve on error
  156. */
  157. int adc_start_channel(struct udevice *dev, int channel);
  158. /**
  159. * adc_start_channels() - start conversion for given device/channels and exit.
  160. *
  161. * Note:
  162. * To use this function, device must implement method: start_channels().
  163. *
  164. * @dev: ADC device to start
  165. * @channel_mask: channel selection - a bit mask
  166. * @channel_mask: bit mask of analog channels
  167. * @return: 0 if OK, -ve on error
  168. */
  169. int adc_start_channels(struct udevice *dev, unsigned int channel_mask);
  170. /**
  171. * adc_channel_data() - get conversion data for the given device channel number.
  172. *
  173. * @dev: ADC device to read
  174. * @channel: analog channel number
  175. * @data: pointer to returned channel's data
  176. * @return: 0 if OK, -ve on error
  177. */
  178. int adc_channel_data(struct udevice *dev, int channel, unsigned int *data);
  179. /**
  180. * adc_channels_data() - get conversion data for the channels selected by mask
  181. *
  182. * Note:
  183. * To use this function, device must implement methods:
  184. * - start_channels()
  185. * - channels_data()
  186. *
  187. * @dev: ADC device to read
  188. * @channel_mask: channel selection - a bit mask
  189. * @channels: pointer to structure array of returned data for each channel
  190. * @return: 0 if OK, -ve on error
  191. */
  192. int adc_channels_data(struct udevice *dev, unsigned int channel_mask,
  193. struct adc_channel *channels);
  194. /**
  195. * adc_data_mask() - get data mask (ADC resolution bitmask) for given ADC device
  196. *
  197. * This can be used if adc uclass platform data is filled.
  198. *
  199. * @dev: ADC device to check
  200. * @data_mask: pointer to the returned data bitmask
  201. * @return: 0 if OK, -ve on error
  202. */
  203. int adc_data_mask(struct udevice *dev, unsigned int *data_mask);
  204. /**
  205. * adc_channel_mask() - get channel mask for given ADC device
  206. *
  207. * This can be used if adc uclass platform data is filled.
  208. *
  209. * @dev: ADC device to check
  210. * @channel_mask: pointer to the returned channel bitmask
  211. * @return: 0 if OK, -ve on error
  212. */
  213. int adc_channel_mask(struct udevice *dev, unsigned int *channel_mask);
  214. /**
  215. * adc_channel_single_shot() - get output data of conversion for the ADC
  216. * device's channel. This function searches for the device with the given name,
  217. * starts the given channel conversion and returns the output data.
  218. *
  219. * Note: To use this function, device must implement metods:
  220. * - start_channel()
  221. * - channel_data()
  222. *
  223. * @name: device's name to search
  224. * @channel: device's input channel to init
  225. * @data: pointer to conversion output data
  226. * @return: 0 if OK, -ve on error
  227. */
  228. int adc_channel_single_shot(const char *name, int channel, unsigned int *data);
  229. /**
  230. * adc_channels_single_shot() - get ADC conversion output data for the selected
  231. * device's channels. This function searches for the device by the given name,
  232. * starts the selected channels conversion and returns the output data as array
  233. * of type 'struct adc_channel'.
  234. *
  235. * Note: This function can be used if device implements one of ADC's single
  236. * or multi-channel operation API. If multi-channel operation is not supported,
  237. * then each selected channel is triggered by the sequence start/data in a loop.
  238. *
  239. * @name: device's name to search
  240. * @channel_mask: channel selection - a bit mask
  241. * @channels: pointer to conversion output data for the selected channels
  242. * @return: 0 if OK, -ve on error
  243. */
  244. int adc_channels_single_shot(const char *name, unsigned int channel_mask,
  245. struct adc_channel *channels);
  246. /**
  247. * adc_vdd_value() - get the ADC device's positive reference Voltage value
  248. *
  249. * Note: Depending on bool value 'vdd_supply_is_negative' of platform data,
  250. * the returned uV value can be negative, and it's not an error.
  251. *
  252. * @dev: ADC device to check
  253. * @uV: Voltage value with polarization sign (uV)
  254. * @return: 0 on success or -ve on error
  255. */
  256. int adc_vdd_value(struct udevice *dev, int *uV);
  257. /**
  258. * adc_vss_value() - get the ADC device's negative reference Voltage value
  259. *
  260. * Note: Depending on bool value 'vdd_supply_is_negative' of platform data,
  261. * the returned uV value can be negative, and it's not an error.
  262. *
  263. * @dev: ADC device to check
  264. * @uV: Voltage value with polarization sign (uV)
  265. * @return: 0 on success or -ve on error
  266. */
  267. int adc_vss_value(struct udevice *dev, int *uV);
  268. /**
  269. * adc_stop() - stop operation for given ADC device.
  270. *
  271. * @dev: ADC device to stop
  272. * @return: 0 if OK, -ve on error
  273. */
  274. int adc_stop(struct udevice *dev);
  275. /**
  276. * adc_raw_to_uV() - converts raw value to microvolts for given ADC device.
  277. *
  278. * @dev: ADC device used from conversion
  279. * @raw: raw value to convert
  280. * @uV: converted value in microvolts
  281. * @return: 0 on success or -ve on error
  282. */
  283. int adc_raw_to_uV(struct udevice *dev, unsigned int raw, int *uV);
  284. #endif