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