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