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. 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 */ 141 struct 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 */ 153 int 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 */ 160 void 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 */ 166 int 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 */ 172 void 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 */ 184 struct 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 */ 196 struct 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 */ 208 int 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 */ 223 int 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 */ 238 int 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 */ 252 int 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 */ 264 int 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 */ 278 int 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 */ 290 int 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 */ 302 int 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 */ 314 int 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 */ 331 int 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 */ 344 int 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 */ 355 int 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 */ 368 int 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 */ 381 int 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 */ 404 int 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 */ 414 unsigned 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 */ 426 ssize_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 */ 441 ssize_t iio_write_channel_ext_info(struct iio_channel *chan, const char *attr, 442 const char *buf, size_t len); 443 444 /** 445 * iio_read_channel_label() - read label for a given channel 446 * @chan: The channel being queried. 447 * @buf: Where to store the attribute value. Assumed to hold 448 * at least PAGE_SIZE bytes. 449 * 450 * Returns the number of bytes written to buf, or an error code. 451 */ 452 ssize_t iio_read_channel_label(struct iio_channel *chan, char *buf); 453 454 #endif 455