1 /* SPDX-License-Identifier: GPL-2.0-only */ 2 /* 3 * Industrial I/O in kernel consumer interface 4 * 5 * Copyright (c) 2011 Jonathan Cameron 6 */ 7 #ifndef _IIO_INKERN_CONSUMER_H_ 8 #define _IIO_INKERN_CONSUMER_H_ 9 10 #include <linux/types.h> 11 #include <linux/iio/types.h> 12 13 struct iio_dev; 14 struct iio_chan_spec; 15 struct device; 16 17 /** 18 * struct iio_channel - everything needed for a consumer to use a channel 19 * @indio_dev: Device on which the channel exists. 20 * @channel: Full description of the channel. 21 * @data: Data about the channel used by consumer. 22 */ 23 struct iio_channel { 24 struct iio_dev *indio_dev; 25 const struct iio_chan_spec *channel; 26 void *data; 27 }; 28 29 /** 30 * iio_channel_get() - get description of all that is needed to access channel. 31 * @dev: Pointer to consumer device. Device name must match 32 * the name of the device as provided in the iio_map 33 * with which the desired provider to consumer mapping 34 * was registered. 35 * @consumer_channel: Unique name to identify the channel on the consumer 36 * side. This typically describes the channels use within 37 * the consumer. E.g. 'battery_voltage' 38 */ 39 struct iio_channel *iio_channel_get(struct device *dev, 40 const char *consumer_channel); 41 42 /** 43 * iio_channel_release() - release channels obtained via iio_channel_get 44 * @chan: The channel to be released. 45 */ 46 void iio_channel_release(struct iio_channel *chan); 47 48 /** 49 * devm_iio_channel_get() - Resource managed version of iio_channel_get(). 50 * @dev: Pointer to consumer device. Device name must match 51 * the name of the device as provided in the iio_map 52 * with which the desired provider to consumer mapping 53 * was registered. 54 * @consumer_channel: Unique name to identify the channel on the consumer 55 * side. This typically describes the channels use within 56 * the consumer. E.g. 'battery_voltage' 57 * 58 * Returns a pointer to negative errno if it is not able to get the iio channel 59 * otherwise returns valid pointer for iio channel. 60 * 61 * The allocated iio channel is automatically released when the device is 62 * unbound. 63 */ 64 struct iio_channel *devm_iio_channel_get(struct device *dev, 65 const char *consumer_channel); 66 /** 67 * iio_channel_get_all() - get all channels associated with a client 68 * @dev: Pointer to consumer device. 69 * 70 * Returns an array of iio_channel structures terminated with one with 71 * null iio_dev pointer. 72 * This function is used by fairly generic consumers to get all the 73 * channels registered as having this consumer. 74 */ 75 struct iio_channel *iio_channel_get_all(struct device *dev); 76 77 /** 78 * iio_channel_release_all() - reverse iio_channel_get_all 79 * @chan: Array of channels to be released. 80 */ 81 void iio_channel_release_all(struct iio_channel *chan); 82 83 /** 84 * devm_iio_channel_get_all() - Resource managed version of 85 * iio_channel_get_all(). 86 * @dev: Pointer to consumer device. 87 * 88 * Returns a pointer to negative errno if it is not able to get the iio channel 89 * otherwise returns an array of iio_channel structures terminated with one with 90 * null iio_dev pointer. 91 * 92 * This function is used by fairly generic consumers to get all the 93 * channels registered as having this consumer. 94 * 95 * The allocated iio channels are automatically released when the device is 96 * unbounded. 97 */ 98 struct iio_channel *devm_iio_channel_get_all(struct device *dev); 99 100 struct iio_cb_buffer; 101 /** 102 * iio_channel_get_all_cb() - register callback for triggered capture 103 * @dev: Pointer to client device. 104 * @cb: Callback function. 105 * @private: Private data passed to callback. 106 * 107 * NB right now we have no ability to mux data from multiple devices. 108 * So if the channels requested come from different devices this will 109 * fail. 110 */ 111 struct iio_cb_buffer *iio_channel_get_all_cb(struct device *dev, 112 int (*cb)(const void *data, 113 void *private), 114 void *private); 115 /** 116 * iio_channel_cb_set_buffer_watermark() - set the buffer watermark. 117 * @cb_buffer: The callback buffer from whom we want the channel 118 * information. 119 * @watermark: buffer watermark in bytes. 120 * 121 * This function allows to configure the buffer watermark. 122 */ 123 int iio_channel_cb_set_buffer_watermark(struct iio_cb_buffer *cb_buffer, 124 size_t watermark); 125 126 /** 127 * iio_channel_release_all_cb() - release and unregister the callback. 128 * @cb_buffer: The callback buffer that was allocated. 129 */ 130 void iio_channel_release_all_cb(struct iio_cb_buffer *cb_buffer); 131 132 /** 133 * iio_channel_start_all_cb() - start the flow of data through callback. 134 * @cb_buff: The callback buffer we are starting. 135 */ 136 int iio_channel_start_all_cb(struct iio_cb_buffer *cb_buff); 137 138 /** 139 * iio_channel_stop_all_cb() - stop the flow of data through the callback. 140 * @cb_buff: The callback buffer we are stopping. 141 */ 142 void iio_channel_stop_all_cb(struct iio_cb_buffer *cb_buff); 143 144 /** 145 * iio_channel_cb_get_channels() - get access to the underlying channels. 146 * @cb_buffer: The callback buffer from whom we want the channel 147 * information. 148 * 149 * This function allows one to obtain information about the channels. 150 * Whilst this may allow direct reading if all buffers are disabled, the 151 * primary aim is to allow drivers that are consuming a channel to query 152 * things like scaling of the channel. 153 */ 154 struct iio_channel 155 *iio_channel_cb_get_channels(const struct iio_cb_buffer *cb_buffer); 156 157 /** 158 * iio_channel_cb_get_iio_dev() - get access to the underlying device. 159 * @cb_buffer: The callback buffer from whom we want the device 160 * information. 161 * 162 * This function allows one to obtain information about the device. 163 * The primary aim is to allow drivers that are consuming a device to query 164 * things like current trigger. 165 */ 166 struct iio_dev 167 *iio_channel_cb_get_iio_dev(const struct iio_cb_buffer *cb_buffer); 168 169 /** 170 * iio_read_channel_raw() - read from a given channel 171 * @chan: The channel being queried. 172 * @val: Value read back. 173 * 174 * Note raw reads from iio channels are in adc counts and hence 175 * scale will need to be applied if standard units required. 176 */ 177 int iio_read_channel_raw(struct iio_channel *chan, 178 int *val); 179 180 /** 181 * iio_read_channel_average_raw() - read from a given channel 182 * @chan: The channel being queried. 183 * @val: Value read back. 184 * 185 * Note raw reads from iio channels are in adc counts and hence 186 * scale will need to be applied if standard units required. 187 * 188 * In opposit to the normal iio_read_channel_raw this function 189 * returns the average of multiple reads. 190 */ 191 int iio_read_channel_average_raw(struct iio_channel *chan, int *val); 192 193 /** 194 * iio_read_channel_processed() - read processed value from a given channel 195 * @chan: The channel being queried. 196 * @val: Value read back. 197 * 198 * Returns an error code or 0. 199 * 200 * This function will read a processed value from a channel. A processed value 201 * means that this value will have the correct unit and not some device internal 202 * representation. If the device does not support reporting a processed value 203 * the function will query the raw value and the channels scale and offset and 204 * do the appropriate transformation. 205 */ 206 int iio_read_channel_processed(struct iio_channel *chan, int *val); 207 208 /** 209 * iio_write_channel_attribute() - Write values to the device attribute. 210 * @chan: The channel being queried. 211 * @val: Value being written. 212 * @val2: Value being written.val2 use depends on attribute type. 213 * @attribute: info attribute to be read. 214 * 215 * Returns an error code or 0. 216 */ 217 int iio_write_channel_attribute(struct iio_channel *chan, int val, 218 int val2, enum iio_chan_info_enum attribute); 219 220 /** 221 * iio_read_channel_attribute() - Read values from the device attribute. 222 * @chan: The channel being queried. 223 * @val: Value being written. 224 * @val2: Value being written.Val2 use depends on attribute type. 225 * @attribute: info attribute to be written. 226 * 227 * Returns an error code if failed. Else returns a description of what is in val 228 * and val2, such as IIO_VAL_INT_PLUS_MICRO telling us we have a value of val 229 * + val2/1e6 230 */ 231 int iio_read_channel_attribute(struct iio_channel *chan, int *val, 232 int *val2, enum iio_chan_info_enum attribute); 233 234 /** 235 * iio_write_channel_raw() - write to a given channel 236 * @chan: The channel being queried. 237 * @val: Value being written. 238 * 239 * Note raw writes to iio channels are in dac counts and hence 240 * scale will need to be applied if standard units required. 241 */ 242 int iio_write_channel_raw(struct iio_channel *chan, int val); 243 244 /** 245 * iio_read_max_channel_raw() - read maximum available raw value from a given 246 * channel, i.e. the maximum possible value. 247 * @chan: The channel being queried. 248 * @val: Value read back. 249 * 250 * Note raw reads from iio channels are in adc counts and hence 251 * scale will need to be applied if standard units are required. 252 */ 253 int iio_read_max_channel_raw(struct iio_channel *chan, int *val); 254 255 /** 256 * iio_read_avail_channel_raw() - read available raw values from a given channel 257 * @chan: The channel being queried. 258 * @vals: Available values read back. 259 * @length: Number of entries in vals. 260 * 261 * Returns an error code, IIO_AVAIL_RANGE or IIO_AVAIL_LIST. 262 * 263 * For ranges, three vals are always returned; min, step and max. 264 * For lists, all the possible values are enumerated. 265 * 266 * Note raw available values from iio channels are in adc counts and 267 * hence scale will need to be applied if standard units are required. 268 */ 269 int iio_read_avail_channel_raw(struct iio_channel *chan, 270 const int **vals, int *length); 271 272 /** 273 * iio_read_avail_channel_attribute() - read available channel attribute values 274 * @chan: The channel being queried. 275 * @vals: Available values read back. 276 * @type: Type of values read back. 277 * @length: Number of entries in vals. 278 * @attribute: info attribute to be read back. 279 * 280 * Returns an error code, IIO_AVAIL_RANGE or IIO_AVAIL_LIST. 281 */ 282 int iio_read_avail_channel_attribute(struct iio_channel *chan, 283 const int **vals, int *type, int *length, 284 enum iio_chan_info_enum attribute); 285 286 /** 287 * iio_get_channel_type() - get the type of a channel 288 * @channel: The channel being queried. 289 * @type: The type of the channel. 290 * 291 * returns the enum iio_chan_type of the channel 292 */ 293 int iio_get_channel_type(struct iio_channel *channel, 294 enum iio_chan_type *type); 295 296 /** 297 * iio_read_channel_offset() - read the offset value for a channel 298 * @chan: The channel being queried. 299 * @val: First part of value read back. 300 * @val2: Second part of value read back. 301 * 302 * Note returns a description of what is in val and val2, such 303 * as IIO_VAL_INT_PLUS_MICRO telling us we have a value of val 304 * + val2/1e6 305 */ 306 int iio_read_channel_offset(struct iio_channel *chan, int *val, 307 int *val2); 308 309 /** 310 * iio_read_channel_scale() - read the scale value for a channel 311 * @chan: The channel being queried. 312 * @val: First part of value read back. 313 * @val2: Second part of value read back. 314 * 315 * Note returns a description of what is in val and val2, such 316 * as IIO_VAL_INT_PLUS_MICRO telling us we have a value of val 317 * + val2/1e6 318 */ 319 int iio_read_channel_scale(struct iio_channel *chan, int *val, 320 int *val2); 321 322 /** 323 * iio_convert_raw_to_processed() - Converts a raw value to a processed value 324 * @chan: The channel being queried 325 * @raw: The raw IIO to convert 326 * @processed: The result of the conversion 327 * @scale: Scale factor to apply during the conversion 328 * 329 * Returns an error code or 0. 330 * 331 * This function converts a raw value to processed value for a specific channel. 332 * A raw value is the device internal representation of a sample and the value 333 * returned by iio_read_channel_raw, so the unit of that value is device 334 * depended. A processed value on the other hand is value has a normed unit 335 * according with the IIO specification. 336 * 337 * The scale factor allows to increase the precession of the returned value. For 338 * a scale factor of 1 the function will return the result in the normal IIO 339 * unit for the channel type. E.g. millivolt for voltage channels, if you want 340 * nanovolts instead pass 1000000 as the scale factor. 341 */ 342 int iio_convert_raw_to_processed(struct iio_channel *chan, int raw, 343 int *processed, unsigned int scale); 344 345 /** 346 * iio_get_channel_ext_info_count() - get number of ext_info attributes 347 * connected to the channel. 348 * @chan: The channel being queried 349 * 350 * Returns the number of ext_info attributes 351 */ 352 unsigned int iio_get_channel_ext_info_count(struct iio_channel *chan); 353 354 /** 355 * iio_read_channel_ext_info() - read ext_info attribute from a given channel 356 * @chan: The channel being queried. 357 * @attr: The ext_info attribute to read. 358 * @buf: Where to store the attribute value. Assumed to hold 359 * at least PAGE_SIZE bytes. 360 * 361 * Returns the number of bytes written to buf (perhaps w/o zero termination; 362 * it need not even be a string), or an error code. 363 */ 364 ssize_t iio_read_channel_ext_info(struct iio_channel *chan, 365 const char *attr, char *buf); 366 367 /** 368 * iio_write_channel_ext_info() - write ext_info attribute from a given channel 369 * @chan: The channel being queried. 370 * @attr: The ext_info attribute to read. 371 * @buf: The new attribute value. Strings needs to be zero- 372 * terminated, but the terminator should not be included 373 * in the below len. 374 * @len: The size of the new attribute value. 375 * 376 * Returns the number of accepted bytes, which should be the same as len. 377 * An error code can also be returned. 378 */ 379 ssize_t iio_write_channel_ext_info(struct iio_channel *chan, const char *attr, 380 const char *buf, size_t len); 381 382 #endif 383