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 device_node; 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 * of_iio_channel_get_by_name() - get description of all that is needed to access channel. 103 * @np: Pointer to consumer device tree 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 #ifdef CONFIG_OF 109 struct iio_channel *of_iio_channel_get_by_name(struct device_node *np, const char *name); 110 #else 111 static inline struct iio_channel * 112 of_iio_channel_get_by_name(struct device_node *np, const char *name) 113 { 114 return NULL; 115 } 116 #endif 117 118 /** 119 * devm_of_iio_channel_get_by_name() - Resource managed version of of_iio_channel_get_by_name(). 120 * @dev: Pointer to consumer device. 121 * @np: Pointer to consumer device tree node 122 * @consumer_channel: Unique name to identify the channel on the consumer 123 * side. This typically describes the channels use within 124 * the consumer. E.g. 'battery_voltage' 125 * 126 * Returns a pointer to negative errno if it is not able to get the iio channel 127 * otherwise returns valid pointer for iio channel. 128 * 129 * The allocated iio channel is automatically released when the device is 130 * unbound. 131 */ 132 struct iio_channel *devm_of_iio_channel_get_by_name(struct device *dev, 133 struct device_node *np, 134 const char *consumer_channel); 135 136 struct iio_cb_buffer; 137 /** 138 * iio_channel_get_all_cb() - register callback for triggered capture 139 * @dev: Pointer to client device. 140 * @cb: Callback function. 141 * @private: Private data passed to callback. 142 * 143 * NB right now we have no ability to mux data from multiple devices. 144 * So if the channels requested come from different devices this will 145 * fail. 146 */ 147 struct iio_cb_buffer *iio_channel_get_all_cb(struct device *dev, 148 int (*cb)(const void *data, 149 void *private), 150 void *private); 151 /** 152 * iio_channel_cb_set_buffer_watermark() - set the buffer watermark. 153 * @cb_buffer: The callback buffer from whom we want the channel 154 * information. 155 * @watermark: buffer watermark in bytes. 156 * 157 * This function allows to configure the buffer watermark. 158 */ 159 int iio_channel_cb_set_buffer_watermark(struct iio_cb_buffer *cb_buffer, 160 size_t watermark); 161 162 /** 163 * iio_channel_release_all_cb() - release and unregister the callback. 164 * @cb_buffer: The callback buffer that was allocated. 165 */ 166 void iio_channel_release_all_cb(struct iio_cb_buffer *cb_buffer); 167 168 /** 169 * iio_channel_start_all_cb() - start the flow of data through callback. 170 * @cb_buff: The callback buffer we are starting. 171 */ 172 int iio_channel_start_all_cb(struct iio_cb_buffer *cb_buff); 173 174 /** 175 * iio_channel_stop_all_cb() - stop the flow of data through the callback. 176 * @cb_buff: The callback buffer we are stopping. 177 */ 178 void iio_channel_stop_all_cb(struct iio_cb_buffer *cb_buff); 179 180 /** 181 * iio_channel_cb_get_channels() - get access to the underlying channels. 182 * @cb_buffer: The callback buffer from whom we want the channel 183 * information. 184 * 185 * This function allows one to obtain information about the channels. 186 * Whilst this may allow direct reading if all buffers are disabled, the 187 * primary aim is to allow drivers that are consuming a channel to query 188 * things like scaling of the channel. 189 */ 190 struct iio_channel 191 *iio_channel_cb_get_channels(const struct iio_cb_buffer *cb_buffer); 192 193 /** 194 * iio_channel_cb_get_iio_dev() - get access to the underlying device. 195 * @cb_buffer: The callback buffer from whom we want the device 196 * information. 197 * 198 * This function allows one to obtain information about the device. 199 * The primary aim is to allow drivers that are consuming a device to query 200 * things like current trigger. 201 */ 202 struct iio_dev 203 *iio_channel_cb_get_iio_dev(const struct iio_cb_buffer *cb_buffer); 204 205 /** 206 * iio_read_channel_raw() - read from a given channel 207 * @chan: The channel being queried. 208 * @val: Value read back. 209 * 210 * Note raw reads from iio channels are in adc counts and hence 211 * scale will need to be applied if standard units required. 212 */ 213 int iio_read_channel_raw(struct iio_channel *chan, 214 int *val); 215 216 /** 217 * iio_read_channel_average_raw() - read from a given channel 218 * @chan: The channel being queried. 219 * @val: Value read back. 220 * 221 * Note raw reads from iio channels are in adc counts and hence 222 * scale will need to be applied if standard units required. 223 * 224 * In opposit to the normal iio_read_channel_raw this function 225 * returns the average of multiple reads. 226 */ 227 int iio_read_channel_average_raw(struct iio_channel *chan, int *val); 228 229 /** 230 * iio_read_channel_processed() - read processed value from a given channel 231 * @chan: The channel being queried. 232 * @val: Value read back. 233 * 234 * Returns an error code or 0. 235 * 236 * This function will read a processed value from a channel. A processed value 237 * means that this value will have the correct unit and not some device internal 238 * representation. If the device does not support reporting a processed value 239 * the function will query the raw value and the channels scale and offset and 240 * do the appropriate transformation. 241 */ 242 int iio_read_channel_processed(struct iio_channel *chan, int *val); 243 244 /** 245 * iio_write_channel_attribute() - Write values to the device attribute. 246 * @chan: The channel being queried. 247 * @val: Value being written. 248 * @val2: Value being written.val2 use depends on attribute type. 249 * @attribute: info attribute to be read. 250 * 251 * Returns an error code or 0. 252 */ 253 int iio_write_channel_attribute(struct iio_channel *chan, int val, 254 int val2, enum iio_chan_info_enum attribute); 255 256 /** 257 * iio_read_channel_attribute() - Read values from 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 written. 262 * 263 * Returns an error code if failed. Else returns a description of what is in val 264 * and val2, such as IIO_VAL_INT_PLUS_MICRO telling us we have a value of val 265 * + val2/1e6 266 */ 267 int iio_read_channel_attribute(struct iio_channel *chan, int *val, 268 int *val2, enum iio_chan_info_enum attribute); 269 270 /** 271 * iio_write_channel_raw() - write to a given channel 272 * @chan: The channel being queried. 273 * @val: Value being written. 274 * 275 * Note raw writes to iio channels are in dac counts and hence 276 * scale will need to be applied if standard units required. 277 */ 278 int iio_write_channel_raw(struct iio_channel *chan, int val); 279 280 /** 281 * iio_read_max_channel_raw() - read maximum available raw value from a given 282 * channel, i.e. the maximum possible value. 283 * @chan: The channel being queried. 284 * @val: Value read back. 285 * 286 * Note raw reads from iio channels are in adc counts and hence 287 * scale will need to be applied if standard units are required. 288 */ 289 int iio_read_max_channel_raw(struct iio_channel *chan, int *val); 290 291 /** 292 * iio_read_avail_channel_raw() - read available raw values from a given channel 293 * @chan: The channel being queried. 294 * @vals: Available values read back. 295 * @length: Number of entries in vals. 296 * 297 * Returns an error code, IIO_AVAIL_RANGE or IIO_AVAIL_LIST. 298 * 299 * For ranges, three vals are always returned; min, step and max. 300 * For lists, all the possible values are enumerated. 301 * 302 * Note raw available values from iio channels are in adc counts and 303 * hence scale will need to be applied if standard units are required. 304 */ 305 int iio_read_avail_channel_raw(struct iio_channel *chan, 306 const int **vals, int *length); 307 308 /** 309 * iio_read_avail_channel_attribute() - read available channel attribute values 310 * @chan: The channel being queried. 311 * @vals: Available values read back. 312 * @type: Type of values read back. 313 * @length: Number of entries in vals. 314 * @attribute: info attribute to be read back. 315 * 316 * Returns an error code, IIO_AVAIL_RANGE or IIO_AVAIL_LIST. 317 */ 318 int iio_read_avail_channel_attribute(struct iio_channel *chan, 319 const int **vals, int *type, int *length, 320 enum iio_chan_info_enum attribute); 321 322 /** 323 * iio_get_channel_type() - get the type of a channel 324 * @channel: The channel being queried. 325 * @type: The type of the channel. 326 * 327 * returns the enum iio_chan_type of the channel 328 */ 329 int iio_get_channel_type(struct iio_channel *channel, 330 enum iio_chan_type *type); 331 332 /** 333 * iio_read_channel_offset() - read the offset value for a channel 334 * @chan: The channel being queried. 335 * @val: First part of value read back. 336 * @val2: Second part of value read back. 337 * 338 * Note returns a description of what is in val and val2, such 339 * as IIO_VAL_INT_PLUS_MICRO telling us we have a value of val 340 * + val2/1e6 341 */ 342 int iio_read_channel_offset(struct iio_channel *chan, int *val, 343 int *val2); 344 345 /** 346 * iio_read_channel_scale() - read the scale value for a channel 347 * @chan: The channel being queried. 348 * @val: First part of value read back. 349 * @val2: Second part of value read back. 350 * 351 * Note returns a description of what is in val and val2, such 352 * as IIO_VAL_INT_PLUS_MICRO telling us we have a value of val 353 * + val2/1e6 354 */ 355 int iio_read_channel_scale(struct iio_channel *chan, int *val, 356 int *val2); 357 358 /** 359 * iio_convert_raw_to_processed() - Converts a raw value to a processed value 360 * @chan: The channel being queried 361 * @raw: The raw IIO to convert 362 * @processed: The result of the conversion 363 * @scale: Scale factor to apply during the conversion 364 * 365 * Returns an error code or 0. 366 * 367 * This function converts a raw value to processed value for a specific channel. 368 * A raw value is the device internal representation of a sample and the value 369 * returned by iio_read_channel_raw, so the unit of that value is device 370 * depended. A processed value on the other hand is value has a normed unit 371 * according with the IIO specification. 372 * 373 * The scale factor allows to increase the precession of the returned value. For 374 * a scale factor of 1 the function will return the result in the normal IIO 375 * unit for the channel type. E.g. millivolt for voltage channels, if you want 376 * nanovolts instead pass 1000000 as the scale factor. 377 */ 378 int iio_convert_raw_to_processed(struct iio_channel *chan, int raw, 379 int *processed, unsigned int scale); 380 381 /** 382 * iio_get_channel_ext_info_count() - get number of ext_info attributes 383 * connected to the channel. 384 * @chan: The channel being queried 385 * 386 * Returns the number of ext_info attributes 387 */ 388 unsigned int iio_get_channel_ext_info_count(struct iio_channel *chan); 389 390 /** 391 * iio_read_channel_ext_info() - read ext_info attribute from a given channel 392 * @chan: The channel being queried. 393 * @attr: The ext_info attribute to read. 394 * @buf: Where to store the attribute value. Assumed to hold 395 * at least PAGE_SIZE bytes. 396 * 397 * Returns the number of bytes written to buf (perhaps w/o zero termination; 398 * it need not even be a string), or an error code. 399 */ 400 ssize_t iio_read_channel_ext_info(struct iio_channel *chan, 401 const char *attr, char *buf); 402 403 /** 404 * iio_write_channel_ext_info() - write ext_info attribute from a given channel 405 * @chan: The channel being queried. 406 * @attr: The ext_info attribute to read. 407 * @buf: The new attribute value. Strings needs to be zero- 408 * terminated, but the terminator should not be included 409 * in the below len. 410 * @len: The size of the new attribute value. 411 * 412 * Returns the number of accepted bytes, which should be the same as len. 413 * An error code can also be returned. 414 */ 415 ssize_t iio_write_channel_ext_info(struct iio_channel *chan, const char *attr, 416 const char *buf, size_t len); 417 418 #endif 419