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 raw reads from iio channels are in adc counts and hence 205 * scale will need to be applied if standard units required. 206 */ 207 int iio_read_channel_raw(struct iio_channel *chan, 208 int *val); 209 210 /** 211 * iio_read_channel_average_raw() - read from a given channel 212 * @chan: The channel being queried. 213 * @val: Value read back. 214 * 215 * Note raw reads from iio channels are in adc counts and hence 216 * scale will need to be applied if standard units required. 217 * 218 * In opposit to the normal iio_read_channel_raw this function 219 * returns the average of multiple reads. 220 */ 221 int iio_read_channel_average_raw(struct iio_channel *chan, int *val); 222 223 /** 224 * iio_read_channel_processed() - read processed value from a given channel 225 * @chan: The channel being queried. 226 * @val: Value read back. 227 * 228 * Returns an error code or 0. 229 * 230 * This function will read a processed value from a channel. A processed value 231 * means that this value will have the correct unit and not some device internal 232 * representation. If the device does not support reporting a processed value 233 * the function will query the raw value and the channels scale and offset and 234 * do the appropriate transformation. 235 */ 236 int iio_read_channel_processed(struct iio_channel *chan, int *val); 237 238 /** 239 * iio_read_channel_processed_scale() - read and scale a processed value 240 * @chan: The channel being queried. 241 * @val: Value read back. 242 * @scale: Scale factor to apply during the conversion 243 * 244 * Returns an error code or 0. 245 * 246 * This function will read a processed value from a channel. This will work 247 * like @iio_read_channel_processed() but also scale with an additional 248 * scale factor while attempting to minimize any precision loss. 249 */ 250 int iio_read_channel_processed_scale(struct iio_channel *chan, int *val, 251 unsigned int scale); 252 253 /** 254 * iio_write_channel_attribute() - Write values to the device attribute. 255 * @chan: The channel being queried. 256 * @val: Value being written. 257 * @val2: Value being written.val2 use depends on attribute type. 258 * @attribute: info attribute to be read. 259 * 260 * Returns an error code or 0. 261 */ 262 int iio_write_channel_attribute(struct iio_channel *chan, int val, 263 int val2, enum iio_chan_info_enum attribute); 264 265 /** 266 * iio_read_channel_attribute() - Read values from the device attribute. 267 * @chan: The channel being queried. 268 * @val: Value being written. 269 * @val2: Value being written.Val2 use depends on attribute type. 270 * @attribute: info attribute to be written. 271 * 272 * Returns an error code if failed. Else returns a description of what is in val 273 * and val2, such as IIO_VAL_INT_PLUS_MICRO telling us we have a value of val 274 * + val2/1e6 275 */ 276 int iio_read_channel_attribute(struct iio_channel *chan, int *val, 277 int *val2, enum iio_chan_info_enum attribute); 278 279 /** 280 * iio_write_channel_raw() - write to a given channel 281 * @chan: The channel being queried. 282 * @val: Value being written. 283 * 284 * Note raw writes to iio channels are in dac counts and hence 285 * scale will need to be applied if standard units required. 286 */ 287 int iio_write_channel_raw(struct iio_channel *chan, int val); 288 289 /** 290 * iio_read_max_channel_raw() - read maximum available raw value from a given 291 * channel, i.e. the maximum possible value. 292 * @chan: The channel being queried. 293 * @val: Value read back. 294 * 295 * Note raw reads from iio channels are in adc counts and hence 296 * scale will need to be applied if standard units are required. 297 */ 298 int iio_read_max_channel_raw(struct iio_channel *chan, int *val); 299 300 /** 301 * iio_read_avail_channel_raw() - read available raw values from a given channel 302 * @chan: The channel being queried. 303 * @vals: Available values read back. 304 * @length: Number of entries in vals. 305 * 306 * Returns an error code, IIO_AVAIL_RANGE or IIO_AVAIL_LIST. 307 * 308 * For ranges, three vals are always returned; min, step and max. 309 * For lists, all the possible values are enumerated. 310 * 311 * Note raw available values from iio channels are in adc counts and 312 * hence scale will need to be applied if standard units are required. 313 */ 314 int iio_read_avail_channel_raw(struct iio_channel *chan, 315 const int **vals, int *length); 316 317 /** 318 * iio_read_avail_channel_attribute() - read available channel attribute values 319 * @chan: The channel being queried. 320 * @vals: Available values read back. 321 * @type: Type of values read back. 322 * @length: Number of entries in vals. 323 * @attribute: info attribute to be read back. 324 * 325 * Returns an error code, IIO_AVAIL_RANGE or IIO_AVAIL_LIST. 326 */ 327 int iio_read_avail_channel_attribute(struct iio_channel *chan, 328 const int **vals, int *type, int *length, 329 enum iio_chan_info_enum attribute); 330 331 /** 332 * iio_get_channel_type() - get the type of a channel 333 * @channel: The channel being queried. 334 * @type: The type of the channel. 335 * 336 * returns the enum iio_chan_type of the channel 337 */ 338 int iio_get_channel_type(struct iio_channel *channel, 339 enum iio_chan_type *type); 340 341 /** 342 * iio_read_channel_offset() - read the offset value for a channel 343 * @chan: The channel being queried. 344 * @val: First part of value read back. 345 * @val2: Second part of value read back. 346 * 347 * Note returns a description of what is in val and val2, such 348 * as IIO_VAL_INT_PLUS_MICRO telling us we have a value of val 349 * + val2/1e6 350 */ 351 int iio_read_channel_offset(struct iio_channel *chan, int *val, 352 int *val2); 353 354 /** 355 * iio_read_channel_scale() - read the scale value for a channel 356 * @chan: The channel being queried. 357 * @val: First part of value read back. 358 * @val2: Second part of value read back. 359 * 360 * Note returns a description of what is in val and val2, such 361 * as IIO_VAL_INT_PLUS_MICRO telling us we have a value of val 362 * + val2/1e6 363 */ 364 int iio_read_channel_scale(struct iio_channel *chan, int *val, 365 int *val2); 366 367 /** 368 * iio_convert_raw_to_processed() - Converts a raw value to a processed value 369 * @chan: The channel being queried 370 * @raw: The raw IIO to convert 371 * @processed: The result of the conversion 372 * @scale: Scale factor to apply during the conversion 373 * 374 * Returns an error code or 0. 375 * 376 * This function converts a raw value to processed value for a specific channel. 377 * A raw value is the device internal representation of a sample and the value 378 * returned by iio_read_channel_raw, so the unit of that value is device 379 * depended. A processed value on the other hand is value has a normed unit 380 * according with the IIO specification. 381 * 382 * The scale factor allows to increase the precession of the returned value. For 383 * a scale factor of 1 the function will return the result in the normal IIO 384 * unit for the channel type. E.g. millivolt for voltage channels, if you want 385 * nanovolts instead pass 1000000 as the scale factor. 386 */ 387 int iio_convert_raw_to_processed(struct iio_channel *chan, int raw, 388 int *processed, unsigned int scale); 389 390 /** 391 * iio_get_channel_ext_info_count() - get number of ext_info attributes 392 * connected to the channel. 393 * @chan: The channel being queried 394 * 395 * Returns the number of ext_info attributes 396 */ 397 unsigned int iio_get_channel_ext_info_count(struct iio_channel *chan); 398 399 /** 400 * iio_read_channel_ext_info() - read ext_info attribute from a given channel 401 * @chan: The channel being queried. 402 * @attr: The ext_info attribute to read. 403 * @buf: Where to store the attribute value. Assumed to hold 404 * at least PAGE_SIZE bytes. 405 * 406 * Returns the number of bytes written to buf (perhaps w/o zero termination; 407 * it need not even be a string), or an error code. 408 */ 409 ssize_t iio_read_channel_ext_info(struct iio_channel *chan, 410 const char *attr, char *buf); 411 412 /** 413 * iio_write_channel_ext_info() - write ext_info attribute from a given channel 414 * @chan: The channel being queried. 415 * @attr: The ext_info attribute to read. 416 * @buf: The new attribute value. Strings needs to be zero- 417 * terminated, but the terminator should not be included 418 * in the below len. 419 * @len: The size of the new attribute value. 420 * 421 * Returns the number of accepted bytes, which should be the same as len. 422 * An error code can also be returned. 423 */ 424 ssize_t iio_write_channel_ext_info(struct iio_channel *chan, const char *attr, 425 const char *buf, size_t len); 426 427 #endif 428