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 struct 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 */ 24 struct 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 */ 40 struct 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 */ 47 void 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 */ 65 struct 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 */ 76 struct 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 */ 82 void 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 */ 99 struct 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 */ 108 struct 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 */ 126 struct iio_channel *devm_fwnode_iio_channel_get_by_name(struct device *dev, 127 struct fwnode_handle *fwnode, 128 const char *consumer_channel); 129 130 struct 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. Must be safe to call from any context 135 * (e.g. must not sleep). 136 * @private: Private data passed to callback. 137 * 138 * NB right now we have no ability to mux data from multiple devices. 139 * So if the channels requested come from different devices this will 140 * fail. 141 */ 142 struct iio_cb_buffer *iio_channel_get_all_cb(struct device *dev, 143 int (*cb)(const void *data, 144 void *private), 145 void *private); 146 /** 147 * iio_channel_cb_set_buffer_watermark() - set the buffer watermark. 148 * @cb_buffer: The callback buffer from whom we want the channel 149 * information. 150 * @watermark: buffer watermark in bytes. 151 * 152 * This function allows to configure the buffer watermark. 153 */ 154 int iio_channel_cb_set_buffer_watermark(struct iio_cb_buffer *cb_buffer, 155 size_t watermark); 156 157 /** 158 * iio_channel_release_all_cb() - release and unregister the callback. 159 * @cb_buffer: The callback buffer that was allocated. 160 */ 161 void iio_channel_release_all_cb(struct iio_cb_buffer *cb_buffer); 162 163 /** 164 * iio_channel_start_all_cb() - start the flow of data through callback. 165 * @cb_buff: The callback buffer we are starting. 166 */ 167 int iio_channel_start_all_cb(struct iio_cb_buffer *cb_buff); 168 169 /** 170 * iio_channel_stop_all_cb() - stop the flow of data through the callback. 171 * @cb_buff: The callback buffer we are stopping. 172 */ 173 void iio_channel_stop_all_cb(struct iio_cb_buffer *cb_buff); 174 175 /** 176 * iio_channel_cb_get_channels() - get access to the underlying channels. 177 * @cb_buffer: The callback buffer from whom we want the channel 178 * information. 179 * 180 * This function allows one to obtain information about the channels. 181 * Whilst this may allow direct reading if all buffers are disabled, the 182 * primary aim is to allow drivers that are consuming a channel to query 183 * things like scaling of the channel. 184 */ 185 struct iio_channel 186 *iio_channel_cb_get_channels(const struct iio_cb_buffer *cb_buffer); 187 188 /** 189 * iio_channel_cb_get_iio_dev() - get access to the underlying device. 190 * @cb_buffer: The callback buffer from whom we want the device 191 * information. 192 * 193 * This function allows one to obtain information about the device. 194 * The primary aim is to allow drivers that are consuming a device to query 195 * things like current trigger. 196 */ 197 struct iio_dev 198 *iio_channel_cb_get_iio_dev(const struct iio_cb_buffer *cb_buffer); 199 200 /** 201 * iio_read_channel_raw() - read from a given channel 202 * @chan: The channel being queried. 203 * @val: Value read back. 204 * 205 * Note, if standard units are required, raw reads from iio channels 206 * need the offset (default 0) and scale (default 1) to be applied 207 * as (raw + offset) * scale. 208 */ 209 int iio_read_channel_raw(struct iio_channel *chan, 210 int *val); 211 212 /** 213 * iio_read_channel_average_raw() - read from a given channel 214 * @chan: The channel being queried. 215 * @val: Value read back. 216 * 217 * Note, if standard units are required, raw reads from iio channels 218 * need the offset (default 0) and scale (default 1) to be applied 219 * as (raw + offset) * scale. 220 * 221 * In opposit to the normal iio_read_channel_raw this function 222 * returns the average of multiple reads. 223 */ 224 int iio_read_channel_average_raw(struct iio_channel *chan, int *val); 225 226 /** 227 * iio_read_channel_processed() - read processed value from a given channel 228 * @chan: The channel being queried. 229 * @val: Value read back. 230 * 231 * Returns an error code or 0. 232 * 233 * This function will read a processed value from a channel. A processed value 234 * means that this value will have the correct unit and not some device internal 235 * representation. If the device does not support reporting a processed value 236 * the function will query the raw value and the channels scale and offset and 237 * do the appropriate transformation. 238 */ 239 int iio_read_channel_processed(struct iio_channel *chan, int *val); 240 241 /** 242 * iio_read_channel_processed_scale() - read and scale a processed value 243 * @chan: The channel being queried. 244 * @val: Value read back. 245 * @scale: Scale factor to apply during the conversion 246 * 247 * Returns an error code or 0. 248 * 249 * This function will read a processed value from a channel. This will work 250 * like @iio_read_channel_processed() but also scale with an additional 251 * scale factor while attempting to minimize any precision loss. 252 */ 253 int iio_read_channel_processed_scale(struct iio_channel *chan, int *val, 254 unsigned int scale); 255 256 /** 257 * iio_write_channel_attribute() - Write values to the device attribute. 258 * @chan: The channel being queried. 259 * @val: Value being written. 260 * @val2: Value being written.val2 use depends on attribute type. 261 * @attribute: info attribute to be read. 262 * 263 * Returns an error code or 0. 264 */ 265 int iio_write_channel_attribute(struct iio_channel *chan, int val, 266 int val2, enum iio_chan_info_enum attribute); 267 268 /** 269 * iio_read_channel_attribute() - Read values from the device attribute. 270 * @chan: The channel being queried. 271 * @val: Value being written. 272 * @val2: Value being written.Val2 use depends on attribute type. 273 * @attribute: info attribute to be written. 274 * 275 * Returns an error code if failed. Else returns a description of what is in val 276 * and val2, such as IIO_VAL_INT_PLUS_MICRO telling us we have a value of val 277 * + val2/1e6 278 */ 279 int iio_read_channel_attribute(struct iio_channel *chan, int *val, 280 int *val2, enum iio_chan_info_enum attribute); 281 282 /** 283 * iio_write_channel_raw() - write to a given channel 284 * @chan: The channel being queried. 285 * @val: Value being written. 286 * 287 * Note that for raw writes to iio channels, if the value provided is 288 * in standard units, the affect of the scale and offset must be removed 289 * as (value / scale) - offset. 290 */ 291 int iio_write_channel_raw(struct iio_channel *chan, int val); 292 293 /** 294 * iio_read_max_channel_raw() - read maximum available raw value from a given 295 * channel, i.e. the maximum possible value. 296 * @chan: The channel being queried. 297 * @val: Value read back. 298 * 299 * Note, if standard units are required, raw reads from iio channels 300 * need the offset (default 0) and scale (default 1) to be applied 301 * as (raw + offset) * scale. 302 */ 303 int iio_read_max_channel_raw(struct iio_channel *chan, int *val); 304 305 /** 306 * iio_read_min_channel_raw() - read minimum available raw value from a given 307 * channel, i.e. the minimum possible value. 308 * @chan: The channel being queried. 309 * @val: Value read back. 310 * 311 * Note, if standard units are required, raw reads from iio channels 312 * need the offset (default 0) and scale (default 1) to be applied 313 * as (raw + offset) * scale. 314 */ 315 int iio_read_min_channel_raw(struct iio_channel *chan, int *val); 316 317 /** 318 * iio_read_avail_channel_raw() - read available raw values from a given channel 319 * @chan: The channel being queried. 320 * @vals: Available values read back. 321 * @length: Number of entries in vals. 322 * 323 * Returns an error code, IIO_AVAIL_RANGE or IIO_AVAIL_LIST. 324 * 325 * For ranges, three vals are always returned; min, step and max. 326 * For lists, all the possible values are enumerated. 327 * 328 * Note, if standard units are required, raw available values from iio 329 * channels need the offset (default 0) and scale (default 1) to be applied 330 * as (raw + offset) * scale. 331 */ 332 int iio_read_avail_channel_raw(struct iio_channel *chan, 333 const int **vals, int *length); 334 335 /** 336 * iio_read_avail_channel_attribute() - read available channel attribute values 337 * @chan: The channel being queried. 338 * @vals: Available values read back. 339 * @type: Type of values read back. 340 * @length: Number of entries in vals. 341 * @attribute: info attribute to be read back. 342 * 343 * Returns an error code, IIO_AVAIL_RANGE or IIO_AVAIL_LIST. 344 */ 345 int iio_read_avail_channel_attribute(struct iio_channel *chan, 346 const int **vals, int *type, int *length, 347 enum iio_chan_info_enum attribute); 348 349 /** 350 * iio_get_channel_type() - get the type of a channel 351 * @channel: The channel being queried. 352 * @type: The type of the channel. 353 * 354 * returns the enum iio_chan_type of the channel 355 */ 356 int iio_get_channel_type(struct iio_channel *channel, 357 enum iio_chan_type *type); 358 359 /** 360 * iio_read_channel_offset() - read the offset value for a channel 361 * @chan: The channel being queried. 362 * @val: First part of value read back. 363 * @val2: Second part of value read back. 364 * 365 * Note returns a description of what is in val and val2, such 366 * as IIO_VAL_INT_PLUS_MICRO telling us we have a value of val 367 * + val2/1e6 368 */ 369 int iio_read_channel_offset(struct iio_channel *chan, int *val, 370 int *val2); 371 372 /** 373 * iio_read_channel_scale() - read the scale value for a channel 374 * @chan: The channel being queried. 375 * @val: First part of value read back. 376 * @val2: Second part of value read back. 377 * 378 * Note returns a description of what is in val and val2, such 379 * as IIO_VAL_INT_PLUS_MICRO telling us we have a value of val 380 * + val2/1e6 381 */ 382 int iio_read_channel_scale(struct iio_channel *chan, int *val, 383 int *val2); 384 385 /** 386 * iio_multiply_value() - Multiply an IIO value 387 * @result: Destination pointer for the multiplication result 388 * @multiplier: Multiplier. 389 * @type: One of the IIO_VAL_* constants. This decides how the @val and 390 * @val2 parameters are interpreted. 391 * @val: Value being multiplied. 392 * @val2: Value being multiplied. @val2 use depends on type. 393 * 394 * Multiply an IIO value with a s64 multiplier storing the result as 395 * IIO_VAL_INT. This is typically used for scaling. 396 * 397 * Returns: 398 * IIO_VAL_INT on success or a negative error-number on failure. 399 */ 400 int iio_multiply_value(int *result, s64 multiplier, 401 unsigned int type, int val, int val2); 402 403 /** 404 * iio_convert_raw_to_processed() - Converts a raw value to a processed value 405 * @chan: The channel being queried 406 * @raw: The raw IIO to convert 407 * @processed: The result of the conversion 408 * @scale: Scale factor to apply during the conversion 409 * 410 * Returns an error code or 0. 411 * 412 * This function converts a raw value to processed value for a specific channel. 413 * A raw value is the device internal representation of a sample and the value 414 * returned by iio_read_channel_raw, so the unit of that value is device 415 * depended. A processed value on the other hand is value has a normed unit 416 * according with the IIO specification. 417 * 418 * The scale factor allows to increase the precession of the returned value. For 419 * a scale factor of 1 the function will return the result in the normal IIO 420 * unit for the channel type. E.g. millivolt for voltage channels, if you want 421 * nanovolts instead pass 1000000 as the scale factor. 422 */ 423 int iio_convert_raw_to_processed(struct iio_channel *chan, int raw, 424 int *processed, unsigned int scale); 425 426 /** 427 * iio_get_channel_ext_info_count() - get number of ext_info attributes 428 * connected to the channel. 429 * @chan: The channel being queried 430 * 431 * Returns the number of ext_info attributes 432 */ 433 unsigned int iio_get_channel_ext_info_count(struct iio_channel *chan); 434 435 /** 436 * iio_read_channel_ext_info() - read ext_info attribute from a given channel 437 * @chan: The channel being queried. 438 * @attr: The ext_info attribute to read. 439 * @buf: Where to store the attribute value. Assumed to hold 440 * at least PAGE_SIZE bytes and to be aligned at PAGE_SIZE. 441 * 442 * Returns the number of bytes written to buf (perhaps w/o zero termination; 443 * it need not even be a string), or an error code. 444 */ 445 ssize_t iio_read_channel_ext_info(struct iio_channel *chan, 446 const char *attr, char *buf); 447 448 /** 449 * iio_write_channel_ext_info() - write ext_info attribute from a given channel 450 * @chan: The channel being queried. 451 * @attr: The ext_info attribute to read. 452 * @buf: The new attribute value. Strings needs to be zero- 453 * terminated, but the terminator should not be included 454 * in the below len. 455 * @len: The size of the new attribute value. 456 * 457 * Returns the number of accepted bytes, which should be the same as len. 458 * An error code can also be returned. 459 */ 460 ssize_t iio_write_channel_ext_info(struct iio_channel *chan, const char *attr, 461 const char *buf, size_t len); 462 463 /** 464 * iio_read_channel_label() - read label for a given channel 465 * @chan: The channel being queried. 466 * @buf: Where to store the attribute value. Assumed to hold 467 * at least PAGE_SIZE bytes and to be aligned at PAGE_SIZE. 468 * 469 * Returns the number of bytes written to buf, or an error code. 470 */ 471 ssize_t iio_read_channel_label(struct iio_channel *chan, char *buf); 472 473 #endif 474