1 // SPDX-License-Identifier: GPL-2.0-only
2 /*
3 * Framework to handle complex IIO aggregate devices.
4 *
5 * The typical architecture is to have one device as the frontend device which
6 * can be "linked" against one or multiple backend devices. All the IIO and
7 * userspace interface is expected to be registers/managed by the frontend
8 * device which will callback into the backends when needed (to get/set some
9 * configuration that it does not directly control).
10 *
11 * -------------------------------------------------------
12 * ------------------ | ------------ ------------ ------- FPGA|
13 * | ADC |------------------------| | ADC CORE |---------| DMA CORE |------| RAM | |
14 * | (Frontend/IIO) | Serial Data (eg: LVDS) | |(backend) |---------| |------| | |
15 * | |------------------------| ------------ ------------ ------- |
16 * ------------------ -------------------------------------------------------
17 *
18 * The framework interface is pretty simple:
19 * - Backends should register themselves with devm_iio_backend_register()
20 * - Frontend devices should get backends with devm_iio_backend_get()
21 *
22 * Also to note that the primary target for this framework are converters like
23 * ADC/DACs so iio_backend_ops will have some operations typical of converter
24 * devices. On top of that, this is "generic" for all IIO which means any kind
25 * of device can make use of the framework. That said, If the iio_backend_ops
26 * struct begins to grow out of control, we can always refactor things so that
27 * the industrialio-backend.c is only left with the really generic stuff. Then,
28 * we can build on top of it depending on the needs.
29 *
30 * Copyright (C) 2023-2024 Analog Devices Inc.
31 */
32 #define dev_fmt(fmt) "iio-backend: " fmt
33
34 #include <linux/cleanup.h>
35 #include <linux/debugfs.h>
36 #include <linux/device.h>
37 #include <linux/err.h>
38 #include <linux/errno.h>
39 #include <linux/list.h>
40 #include <linux/module.h>
41 #include <linux/mutex.h>
42 #include <linux/property.h>
43 #include <linux/slab.h>
44 #include <linux/stringify.h>
45 #include <linux/types.h>
46
47 #include <linux/iio/backend.h>
48 #include <linux/iio/iio.h>
49
50 struct iio_backend {
51 struct list_head entry;
52 const struct iio_backend_ops *ops;
53 struct device *frontend_dev;
54 struct device *dev;
55 struct module *owner;
56 void *priv;
57 const char *name;
58 unsigned int cached_reg_addr;
59 /*
60 * This index is relative to the frontend. Meaning that for
61 * frontends with multiple backends, this will be the index of this
62 * backend. Used for the debugfs directory name.
63 */
64 u8 idx;
65 };
66
67 /*
68 * Helper struct for requesting buffers. This ensures that we have all data
69 * that we need to free the buffer in a device managed action.
70 */
71 struct iio_backend_buffer_pair {
72 struct iio_backend *back;
73 struct iio_buffer *buffer;
74 };
75
76 static LIST_HEAD(iio_back_list);
77 static DEFINE_MUTEX(iio_back_lock);
78
79 /*
80 * Helper macros to call backend ops. Makes sure the option is supported.
81 */
82 #define iio_backend_check_op(back, op) ({ \
83 struct iio_backend *____back = back; \
84 int ____ret = 0; \
85 \
86 if (!____back->ops->op) \
87 ____ret = -EOPNOTSUPP; \
88 \
89 ____ret; \
90 })
91
92 #define iio_backend_op_call(back, op, args...) ({ \
93 struct iio_backend *__back = back; \
94 int __ret; \
95 \
96 __ret = iio_backend_check_op(__back, op); \
97 if (!__ret) \
98 __ret = __back->ops->op(__back, ##args); \
99 \
100 __ret; \
101 })
102
103 #define iio_backend_ptr_op_call(back, op, args...) ({ \
104 struct iio_backend *__back = back; \
105 void *ptr_err; \
106 int __ret; \
107 \
108 __ret = iio_backend_check_op(__back, op); \
109 if (__ret) \
110 ptr_err = ERR_PTR(__ret); \
111 else \
112 ptr_err = __back->ops->op(__back, ##args); \
113 \
114 ptr_err; \
115 })
116
117 #define iio_backend_void_op_call(back, op, args...) { \
118 struct iio_backend *__back = back; \
119 int __ret; \
120 \
121 __ret = iio_backend_check_op(__back, op); \
122 if (!__ret) \
123 __back->ops->op(__back, ##args); \
124 else \
125 dev_dbg(__back->dev, "Op(%s) not implemented\n",\
126 __stringify(op)); \
127 }
128
iio_backend_debugfs_read_reg(struct file * file,char __user * userbuf,size_t count,loff_t * ppos)129 static ssize_t iio_backend_debugfs_read_reg(struct file *file,
130 char __user *userbuf,
131 size_t count, loff_t *ppos)
132 {
133 struct iio_backend *back = file->private_data;
134 char read_buf[20];
135 unsigned int val;
136 int ret, len;
137
138 ret = iio_backend_op_call(back, debugfs_reg_access,
139 back->cached_reg_addr, 0, &val);
140 if (ret)
141 return ret;
142
143 len = scnprintf(read_buf, sizeof(read_buf), "0x%X\n", val);
144
145 return simple_read_from_buffer(userbuf, count, ppos, read_buf, len);
146 }
147
iio_backend_debugfs_write_reg(struct file * file,const char __user * userbuf,size_t count,loff_t * ppos)148 static ssize_t iio_backend_debugfs_write_reg(struct file *file,
149 const char __user *userbuf,
150 size_t count, loff_t *ppos)
151 {
152 struct iio_backend *back = file->private_data;
153 unsigned int val;
154 char buf[80];
155 ssize_t rc;
156 int ret;
157
158 rc = simple_write_to_buffer(buf, sizeof(buf) - 1, ppos, userbuf, count);
159 if (rc < 0)
160 return rc;
161
162 buf[count] = '\0';
163
164 ret = sscanf(buf, "%i %i", &back->cached_reg_addr, &val);
165
166 switch (ret) {
167 case 1:
168 return count;
169 case 2:
170 ret = iio_backend_op_call(back, debugfs_reg_access,
171 back->cached_reg_addr, val, NULL);
172 if (ret)
173 return ret;
174 return count;
175 default:
176 return -EINVAL;
177 }
178 }
179
180 static const struct file_operations iio_backend_debugfs_reg_fops = {
181 .open = simple_open,
182 .read = iio_backend_debugfs_read_reg,
183 .write = iio_backend_debugfs_write_reg,
184 };
185
iio_backend_debugfs_read_name(struct file * file,char __user * userbuf,size_t count,loff_t * ppos)186 static ssize_t iio_backend_debugfs_read_name(struct file *file,
187 char __user *userbuf,
188 size_t count, loff_t *ppos)
189 {
190 struct iio_backend *back = file->private_data;
191 char name[128];
192 int len;
193
194 len = scnprintf(name, sizeof(name), "%s\n", back->name);
195
196 return simple_read_from_buffer(userbuf, count, ppos, name, len);
197 }
198
199 static const struct file_operations iio_backend_debugfs_name_fops = {
200 .open = simple_open,
201 .read = iio_backend_debugfs_read_name,
202 };
203
204 /**
205 * iio_backend_debugfs_add - Add debugfs interfaces for Backends
206 * @back: Backend device
207 * @indio_dev: IIO device
208 */
iio_backend_debugfs_add(struct iio_backend * back,struct iio_dev * indio_dev)209 void iio_backend_debugfs_add(struct iio_backend *back,
210 struct iio_dev *indio_dev)
211 {
212 struct dentry *d = iio_get_debugfs_dentry(indio_dev);
213 struct dentry *back_d;
214 char name[128];
215
216 if (!IS_ENABLED(CONFIG_DEBUG_FS) || !d)
217 return;
218 if (!back->ops->debugfs_reg_access && !back->name)
219 return;
220
221 snprintf(name, sizeof(name), "backend%d", back->idx);
222
223 back_d = debugfs_create_dir(name, d);
224 if (IS_ERR(back_d))
225 return;
226
227 if (back->ops->debugfs_reg_access)
228 debugfs_create_file("direct_reg_access", 0600, back_d, back,
229 &iio_backend_debugfs_reg_fops);
230
231 if (back->name)
232 debugfs_create_file("name", 0400, back_d, back,
233 &iio_backend_debugfs_name_fops);
234 }
235 EXPORT_SYMBOL_NS_GPL(iio_backend_debugfs_add, "IIO_BACKEND");
236
237 /**
238 * iio_backend_debugfs_print_chan_status - Print channel status
239 * @back: Backend device
240 * @chan: Channel number
241 * @buf: Buffer where to print the status
242 * @len: Available space
243 *
244 * One usecase where this is useful is for testing test tones in a digital
245 * interface and "ask" the backend to dump more details on why a test tone might
246 * have errors.
247 *
248 * RETURNS:
249 * Number of copied bytes on success, negative error code on failure.
250 */
iio_backend_debugfs_print_chan_status(struct iio_backend * back,unsigned int chan,char * buf,size_t len)251 ssize_t iio_backend_debugfs_print_chan_status(struct iio_backend *back,
252 unsigned int chan, char *buf,
253 size_t len)
254 {
255 if (!IS_ENABLED(CONFIG_DEBUG_FS))
256 return -ENODEV;
257
258 return iio_backend_op_call(back, debugfs_print_chan_status, chan, buf,
259 len);
260 }
261 EXPORT_SYMBOL_NS_GPL(iio_backend_debugfs_print_chan_status, "IIO_BACKEND");
262
263 /**
264 * iio_backend_chan_enable - Enable a backend channel
265 * @back: Backend device
266 * @chan: Channel number
267 *
268 * RETURNS:
269 * 0 on success, negative error number on failure.
270 */
iio_backend_chan_enable(struct iio_backend * back,unsigned int chan)271 int iio_backend_chan_enable(struct iio_backend *back, unsigned int chan)
272 {
273 return iio_backend_op_call(back, chan_enable, chan);
274 }
275 EXPORT_SYMBOL_NS_GPL(iio_backend_chan_enable, "IIO_BACKEND");
276
277 /**
278 * iio_backend_chan_disable - Disable a backend channel
279 * @back: Backend device
280 * @chan: Channel number
281 *
282 * RETURNS:
283 * 0 on success, negative error number on failure.
284 */
iio_backend_chan_disable(struct iio_backend * back,unsigned int chan)285 int iio_backend_chan_disable(struct iio_backend *back, unsigned int chan)
286 {
287 return iio_backend_op_call(back, chan_disable, chan);
288 }
289 EXPORT_SYMBOL_NS_GPL(iio_backend_chan_disable, "IIO_BACKEND");
290
__iio_backend_disable(void * back)291 static void __iio_backend_disable(void *back)
292 {
293 iio_backend_void_op_call(back, disable);
294 }
295
296 /**
297 * iio_backend_disable - Backend disable
298 * @back: Backend device
299 */
iio_backend_disable(struct iio_backend * back)300 void iio_backend_disable(struct iio_backend *back)
301 {
302 __iio_backend_disable(back);
303 }
304 EXPORT_SYMBOL_NS_GPL(iio_backend_disable, "IIO_BACKEND");
305
306 /**
307 * iio_backend_enable - Backend enable
308 * @back: Backend device
309 *
310 * RETURNS:
311 * 0 on success, negative error number on failure.
312 */
iio_backend_enable(struct iio_backend * back)313 int iio_backend_enable(struct iio_backend *back)
314 {
315 return iio_backend_op_call(back, enable);
316 }
317 EXPORT_SYMBOL_NS_GPL(iio_backend_enable, "IIO_BACKEND");
318
319 /**
320 * devm_iio_backend_enable - Device managed backend enable
321 * @dev: Consumer device for the backend
322 * @back: Backend device
323 *
324 * RETURNS:
325 * 0 on success, negative error number on failure.
326 */
devm_iio_backend_enable(struct device * dev,struct iio_backend * back)327 int devm_iio_backend_enable(struct device *dev, struct iio_backend *back)
328 {
329 int ret;
330
331 ret = iio_backend_enable(back);
332 if (ret)
333 return ret;
334
335 return devm_add_action_or_reset(dev, __iio_backend_disable, back);
336 }
337 EXPORT_SYMBOL_NS_GPL(devm_iio_backend_enable, "IIO_BACKEND");
338
339 /**
340 * iio_backend_data_format_set - Configure the channel data format
341 * @back: Backend device
342 * @chan: Channel number
343 * @data: Data format
344 *
345 * Properly configure a channel with respect to the expected data format. A
346 * @struct iio_backend_data_fmt must be passed with the settings.
347 *
348 * RETURNS:
349 * 0 on success, negative error number on failure.
350 */
iio_backend_data_format_set(struct iio_backend * back,unsigned int chan,const struct iio_backend_data_fmt * data)351 int iio_backend_data_format_set(struct iio_backend *back, unsigned int chan,
352 const struct iio_backend_data_fmt *data)
353 {
354 if (!data || data->type >= IIO_BACKEND_DATA_TYPE_MAX)
355 return -EINVAL;
356
357 return iio_backend_op_call(back, data_format_set, chan, data);
358 }
359 EXPORT_SYMBOL_NS_GPL(iio_backend_data_format_set, "IIO_BACKEND");
360
361 /**
362 * iio_backend_data_source_set - Select data source
363 * @back: Backend device
364 * @chan: Channel number
365 * @data: Data source
366 *
367 * A given backend may have different sources to stream/sync data. This allows
368 * to choose that source.
369 *
370 * RETURNS:
371 * 0 on success, negative error number on failure.
372 */
iio_backend_data_source_set(struct iio_backend * back,unsigned int chan,enum iio_backend_data_source data)373 int iio_backend_data_source_set(struct iio_backend *back, unsigned int chan,
374 enum iio_backend_data_source data)
375 {
376 if (data >= IIO_BACKEND_DATA_SOURCE_MAX)
377 return -EINVAL;
378
379 return iio_backend_op_call(back, data_source_set, chan, data);
380 }
381 EXPORT_SYMBOL_NS_GPL(iio_backend_data_source_set, "IIO_BACKEND");
382
383 /**
384 * iio_backend_set_sampling_freq - Set channel sampling rate
385 * @back: Backend device
386 * @chan: Channel number
387 * @sample_rate_hz: Sample rate
388 *
389 * RETURNS:
390 * 0 on success, negative error number on failure.
391 */
iio_backend_set_sampling_freq(struct iio_backend * back,unsigned int chan,u64 sample_rate_hz)392 int iio_backend_set_sampling_freq(struct iio_backend *back, unsigned int chan,
393 u64 sample_rate_hz)
394 {
395 return iio_backend_op_call(back, set_sample_rate, chan, sample_rate_hz);
396 }
397 EXPORT_SYMBOL_NS_GPL(iio_backend_set_sampling_freq, "IIO_BACKEND");
398
399 /**
400 * iio_backend_test_pattern_set - Configure a test pattern
401 * @back: Backend device
402 * @chan: Channel number
403 * @pattern: Test pattern
404 *
405 * Configure a test pattern on the backend. This is typically used for
406 * calibrating the timings on the data digital interface.
407 *
408 * RETURNS:
409 * 0 on success, negative error number on failure.
410 */
iio_backend_test_pattern_set(struct iio_backend * back,unsigned int chan,enum iio_backend_test_pattern pattern)411 int iio_backend_test_pattern_set(struct iio_backend *back,
412 unsigned int chan,
413 enum iio_backend_test_pattern pattern)
414 {
415 if (pattern >= IIO_BACKEND_TEST_PATTERN_MAX)
416 return -EINVAL;
417
418 return iio_backend_op_call(back, test_pattern_set, chan, pattern);
419 }
420 EXPORT_SYMBOL_NS_GPL(iio_backend_test_pattern_set, "IIO_BACKEND");
421
422 /**
423 * iio_backend_chan_status - Get the channel status
424 * @back: Backend device
425 * @chan: Channel number
426 * @error: Error indication
427 *
428 * Get the current state of the backend channel. Typically used to check if
429 * there were any errors sending/receiving data.
430 *
431 * RETURNS:
432 * 0 on success, negative error number on failure.
433 */
iio_backend_chan_status(struct iio_backend * back,unsigned int chan,bool * error)434 int iio_backend_chan_status(struct iio_backend *back, unsigned int chan,
435 bool *error)
436 {
437 return iio_backend_op_call(back, chan_status, chan, error);
438 }
439 EXPORT_SYMBOL_NS_GPL(iio_backend_chan_status, "IIO_BACKEND");
440
441 /**
442 * iio_backend_iodelay_set - Set digital I/O delay
443 * @back: Backend device
444 * @lane: Lane number
445 * @taps: Number of taps
446 *
447 * Controls delays on sending/receiving data. One usecase for this is to
448 * calibrate the data digital interface so we get the best results when
449 * transferring data. Note that @taps has no unit since the actual delay per tap
450 * is very backend specific. Hence, frontend devices typically should go through
451 * an array of @taps (the size of that array should typically match the size of
452 * calibration points on the frontend device) and call this API.
453 *
454 * RETURNS:
455 * 0 on success, negative error number on failure.
456 */
iio_backend_iodelay_set(struct iio_backend * back,unsigned int lane,unsigned int taps)457 int iio_backend_iodelay_set(struct iio_backend *back, unsigned int lane,
458 unsigned int taps)
459 {
460 return iio_backend_op_call(back, iodelay_set, lane, taps);
461 }
462 EXPORT_SYMBOL_NS_GPL(iio_backend_iodelay_set, "IIO_BACKEND");
463
464 /**
465 * iio_backend_data_sample_trigger - Control when to sample data
466 * @back: Backend device
467 * @trigger: Data trigger
468 *
469 * Mostly useful for input backends. Configures the backend for when to sample
470 * data (eg: rising vs falling edge).
471 *
472 * RETURNS:
473 * 0 on success, negative error number on failure.
474 */
iio_backend_data_sample_trigger(struct iio_backend * back,enum iio_backend_sample_trigger trigger)475 int iio_backend_data_sample_trigger(struct iio_backend *back,
476 enum iio_backend_sample_trigger trigger)
477 {
478 if (trigger >= IIO_BACKEND_SAMPLE_TRIGGER_MAX)
479 return -EINVAL;
480
481 return iio_backend_op_call(back, data_sample_trigger, trigger);
482 }
483 EXPORT_SYMBOL_NS_GPL(iio_backend_data_sample_trigger, "IIO_BACKEND");
484
iio_backend_free_buffer(void * arg)485 static void iio_backend_free_buffer(void *arg)
486 {
487 struct iio_backend_buffer_pair *pair = arg;
488
489 iio_backend_void_op_call(pair->back, free_buffer, pair->buffer);
490 }
491
492 /**
493 * devm_iio_backend_request_buffer - Device managed buffer request
494 * @dev: Consumer device for the backend
495 * @back: Backend device
496 * @indio_dev: IIO device
497 *
498 * Request an IIO buffer from the backend. The type of the buffer (typically
499 * INDIO_BUFFER_HARDWARE) is up to the backend to decide. This is because,
500 * normally, the backend dictates what kind of buffering we can get.
501 *
502 * The backend .free_buffer() hooks is automatically called on @dev detach.
503 *
504 * RETURNS:
505 * 0 on success, negative error number on failure.
506 */
devm_iio_backend_request_buffer(struct device * dev,struct iio_backend * back,struct iio_dev * indio_dev)507 int devm_iio_backend_request_buffer(struct device *dev,
508 struct iio_backend *back,
509 struct iio_dev *indio_dev)
510 {
511 struct iio_backend_buffer_pair *pair;
512 struct iio_buffer *buffer;
513
514 pair = devm_kzalloc(dev, sizeof(*pair), GFP_KERNEL);
515 if (!pair)
516 return -ENOMEM;
517
518 buffer = iio_backend_ptr_op_call(back, request_buffer, indio_dev);
519 if (IS_ERR(buffer))
520 return PTR_ERR(buffer);
521
522 /* weak reference should be all what we need */
523 pair->back = back;
524 pair->buffer = buffer;
525
526 return devm_add_action_or_reset(dev, iio_backend_free_buffer, pair);
527 }
528 EXPORT_SYMBOL_NS_GPL(devm_iio_backend_request_buffer, "IIO_BACKEND");
529
530 /**
531 * iio_backend_read_raw - Read a channel attribute from a backend device.
532 * @back: Backend device
533 * @chan: IIO channel reference
534 * @val: First returned value
535 * @val2: Second returned value
536 * @mask: Specify the attribute to return
537 *
538 * RETURNS:
539 * 0 on success, negative error number on failure.
540 */
iio_backend_read_raw(struct iio_backend * back,struct iio_chan_spec const * chan,int * val,int * val2,long mask)541 int iio_backend_read_raw(struct iio_backend *back,
542 struct iio_chan_spec const *chan, int *val, int *val2,
543 long mask)
544 {
545 return iio_backend_op_call(back, read_raw, chan, val, val2, mask);
546 }
547 EXPORT_SYMBOL_NS_GPL(iio_backend_read_raw, "IIO_BACKEND");
548
iio_backend_from_indio_dev_parent(const struct device * dev)549 static struct iio_backend *iio_backend_from_indio_dev_parent(const struct device *dev)
550 {
551 struct iio_backend *back = ERR_PTR(-ENODEV), *iter;
552
553 /*
554 * We deliberately go through all backends even after finding a match.
555 * The reason is that we want to catch frontend devices which have more
556 * than one backend in which case returning the first we find is bogus.
557 * For those cases, frontends need to explicitly define
558 * get_iio_backend() in struct iio_info.
559 */
560 guard(mutex)(&iio_back_lock);
561 list_for_each_entry(iter, &iio_back_list, entry) {
562 if (dev == iter->frontend_dev) {
563 if (!IS_ERR(back)) {
564 dev_warn(dev,
565 "Multiple backends! get_iio_backend() needs to be implemented");
566 return ERR_PTR(-ENODEV);
567 }
568
569 back = iter;
570 }
571 }
572
573 return back;
574 }
575
576 /**
577 * iio_backend_ext_info_get - IIO ext_info read callback
578 * @indio_dev: IIO device
579 * @private: Data private to the driver
580 * @chan: IIO channel
581 * @buf: Buffer where to place the attribute data
582 *
583 * This helper is intended to be used by backends that extend an IIO channel
584 * (through iio_backend_extend_chan_spec()) with extended info. In that case,
585 * backends are not supposed to give their own callbacks (as they would not have
586 * a way to get the backend from indio_dev). This is the getter.
587 *
588 * RETURNS:
589 * Number of bytes written to buf, negative error number on failure.
590 */
iio_backend_ext_info_get(struct iio_dev * indio_dev,uintptr_t private,const struct iio_chan_spec * chan,char * buf)591 ssize_t iio_backend_ext_info_get(struct iio_dev *indio_dev, uintptr_t private,
592 const struct iio_chan_spec *chan, char *buf)
593 {
594 struct iio_backend *back;
595
596 /*
597 * The below should work for the majority of the cases. It will not work
598 * when one frontend has multiple backends in which case we'll need a
599 * new callback in struct iio_info so we can directly request the proper
600 * backend from the frontend. Anyways, let's only introduce new options
601 * when really needed...
602 */
603 back = iio_backend_from_indio_dev_parent(indio_dev->dev.parent);
604 if (IS_ERR(back))
605 return PTR_ERR(back);
606
607 return iio_backend_op_call(back, ext_info_get, private, chan, buf);
608 }
609 EXPORT_SYMBOL_NS_GPL(iio_backend_ext_info_get, "IIO_BACKEND");
610
611 /**
612 * iio_backend_ext_info_set - IIO ext_info write callback
613 * @indio_dev: IIO device
614 * @private: Data private to the driver
615 * @chan: IIO channel
616 * @buf: Buffer holding the sysfs attribute
617 * @len: Buffer length
618 *
619 * This helper is intended to be used by backends that extend an IIO channel
620 * (trough iio_backend_extend_chan_spec()) with extended info. In that case,
621 * backends are not supposed to give their own callbacks (as they would not have
622 * a way to get the backend from indio_dev). This is the setter.
623 *
624 * RETURNS:
625 * Buffer length on success, negative error number on failure.
626 */
iio_backend_ext_info_set(struct iio_dev * indio_dev,uintptr_t private,const struct iio_chan_spec * chan,const char * buf,size_t len)627 ssize_t iio_backend_ext_info_set(struct iio_dev *indio_dev, uintptr_t private,
628 const struct iio_chan_spec *chan,
629 const char *buf, size_t len)
630 {
631 struct iio_backend *back;
632
633 back = iio_backend_from_indio_dev_parent(indio_dev->dev.parent);
634 if (IS_ERR(back))
635 return PTR_ERR(back);
636
637 return iio_backend_op_call(back, ext_info_set, private, chan, buf, len);
638 }
639 EXPORT_SYMBOL_NS_GPL(iio_backend_ext_info_set, "IIO_BACKEND");
640
641 /**
642 * iio_backend_interface_type_get - get the interface type used.
643 * @back: Backend device
644 * @type: Interface type
645 *
646 * RETURNS:
647 * 0 on success, negative error number on failure.
648 */
iio_backend_interface_type_get(struct iio_backend * back,enum iio_backend_interface_type * type)649 int iio_backend_interface_type_get(struct iio_backend *back,
650 enum iio_backend_interface_type *type)
651 {
652 int ret;
653
654 ret = iio_backend_op_call(back, interface_type_get, type);
655 if (ret)
656 return ret;
657
658 if (*type >= IIO_BACKEND_INTERFACE_MAX)
659 return -EINVAL;
660
661 return 0;
662 }
663 EXPORT_SYMBOL_NS_GPL(iio_backend_interface_type_get, "IIO_BACKEND");
664
665 /**
666 * iio_backend_data_size_set - set the data width/size in the data bus.
667 * @back: Backend device
668 * @size: Size in bits
669 *
670 * Some frontend devices can dynamically control the word/data size on the
671 * interface/data bus. Hence, the backend device needs to be aware of it so
672 * data can be correctly transferred.
673 *
674 * Return:
675 * 0 on success, negative error number on failure.
676 */
iio_backend_data_size_set(struct iio_backend * back,unsigned int size)677 int iio_backend_data_size_set(struct iio_backend *back, unsigned int size)
678 {
679 if (!size)
680 return -EINVAL;
681
682 return iio_backend_op_call(back, data_size_set, size);
683 }
684 EXPORT_SYMBOL_NS_GPL(iio_backend_data_size_set, "IIO_BACKEND");
685
686 /**
687 * iio_backend_oversampling_ratio_set - set the oversampling ratio
688 * @back: Backend device
689 * @ratio: The oversampling ratio - value 1 corresponds to no oversampling.
690 *
691 * Return:
692 * 0 on success, negative error number on failure.
693 */
iio_backend_oversampling_ratio_set(struct iio_backend * back,unsigned int ratio)694 int iio_backend_oversampling_ratio_set(struct iio_backend *back,
695 unsigned int ratio)
696 {
697 return iio_backend_op_call(back, oversampling_ratio_set, ratio);
698 }
699 EXPORT_SYMBOL_NS_GPL(iio_backend_oversampling_ratio_set, "IIO_BACKEND");
700
701 /**
702 * iio_backend_extend_chan_spec - Extend an IIO channel
703 * @back: Backend device
704 * @chan: IIO channel
705 *
706 * Some backends may have their own functionalities and hence capable of
707 * extending a frontend's channel.
708 *
709 * RETURNS:
710 * 0 on success, negative error number on failure.
711 */
iio_backend_extend_chan_spec(struct iio_backend * back,struct iio_chan_spec * chan)712 int iio_backend_extend_chan_spec(struct iio_backend *back,
713 struct iio_chan_spec *chan)
714 {
715 const struct iio_chan_spec_ext_info *frontend_ext_info = chan->ext_info;
716 const struct iio_chan_spec_ext_info *back_ext_info;
717 int ret;
718
719 ret = iio_backend_op_call(back, extend_chan_spec, chan);
720 if (ret)
721 return ret;
722 /*
723 * Let's keep things simple for now. Don't allow to overwrite the
724 * frontend's extended info. If ever needed, we can support appending
725 * it.
726 */
727 if (frontend_ext_info && chan->ext_info != frontend_ext_info)
728 return -EOPNOTSUPP;
729 if (!chan->ext_info)
730 return 0;
731
732 /* Don't allow backends to get creative and force their own handlers */
733 for (back_ext_info = chan->ext_info; back_ext_info->name; back_ext_info++) {
734 if (back_ext_info->read != iio_backend_ext_info_get)
735 return -EINVAL;
736 if (back_ext_info->write != iio_backend_ext_info_set)
737 return -EINVAL;
738 }
739
740 return 0;
741 }
742 EXPORT_SYMBOL_NS_GPL(iio_backend_extend_chan_spec, "IIO_BACKEND");
743
iio_backend_release(void * arg)744 static void iio_backend_release(void *arg)
745 {
746 struct iio_backend *back = arg;
747
748 module_put(back->owner);
749 }
750
__devm_iio_backend_get(struct device * dev,struct iio_backend * back)751 static int __devm_iio_backend_get(struct device *dev, struct iio_backend *back)
752 {
753 struct device_link *link;
754 int ret;
755
756 /*
757 * Make sure the provider cannot be unloaded before the consumer module.
758 * Note that device_links would still guarantee that nothing is
759 * accessible (and breaks) but this makes it explicit that the consumer
760 * module must be also unloaded.
761 */
762 if (!try_module_get(back->owner))
763 return dev_err_probe(dev, -ENODEV,
764 "Cannot get module reference\n");
765
766 ret = devm_add_action_or_reset(dev, iio_backend_release, back);
767 if (ret)
768 return ret;
769
770 link = device_link_add(dev, back->dev, DL_FLAG_AUTOREMOVE_CONSUMER);
771 if (!link)
772 return dev_err_probe(dev, -EINVAL,
773 "Could not link to supplier(%s)\n",
774 dev_name(back->dev));
775
776 back->frontend_dev = dev;
777
778 dev_dbg(dev, "Found backend(%s) device\n", dev_name(back->dev));
779
780 return 0;
781 }
782
783 /**
784 * iio_backend_ddr_enable - Enable interface DDR (Double Data Rate) mode
785 * @back: Backend device
786 *
787 * Enable DDR, data is generated by the IP at each front (raising and falling)
788 * of the bus clock signal.
789 *
790 * RETURNS:
791 * 0 on success, negative error number on failure.
792 */
iio_backend_ddr_enable(struct iio_backend * back)793 int iio_backend_ddr_enable(struct iio_backend *back)
794 {
795 return iio_backend_op_call(back, ddr_enable);
796 }
797 EXPORT_SYMBOL_NS_GPL(iio_backend_ddr_enable, "IIO_BACKEND");
798
799 /**
800 * iio_backend_ddr_disable - Disable interface DDR (Double Data Rate) mode
801 * @back: Backend device
802 *
803 * Disable DDR, setting into SDR mode (Single Data Rate).
804 *
805 * RETURNS:
806 * 0 on success, negative error number on failure.
807 */
iio_backend_ddr_disable(struct iio_backend * back)808 int iio_backend_ddr_disable(struct iio_backend *back)
809 {
810 return iio_backend_op_call(back, ddr_disable);
811 }
812 EXPORT_SYMBOL_NS_GPL(iio_backend_ddr_disable, "IIO_BACKEND");
813
814 /**
815 * iio_backend_data_stream_enable - Enable data stream
816 * @back: Backend device
817 *
818 * Enable data stream over the bus interface.
819 *
820 * RETURNS:
821 * 0 on success, negative error number on failure.
822 */
iio_backend_data_stream_enable(struct iio_backend * back)823 int iio_backend_data_stream_enable(struct iio_backend *back)
824 {
825 return iio_backend_op_call(back, data_stream_enable);
826 }
827 EXPORT_SYMBOL_NS_GPL(iio_backend_data_stream_enable, "IIO_BACKEND");
828
829 /**
830 * iio_backend_data_stream_disable - Disable data stream
831 * @back: Backend device
832 *
833 * Disable data stream over the bus interface.
834 *
835 * RETURNS:
836 * 0 on success, negative error number on failure.
837 */
iio_backend_data_stream_disable(struct iio_backend * back)838 int iio_backend_data_stream_disable(struct iio_backend *back)
839 {
840 return iio_backend_op_call(back, data_stream_disable);
841 }
842 EXPORT_SYMBOL_NS_GPL(iio_backend_data_stream_disable, "IIO_BACKEND");
843
844 /**
845 * iio_backend_data_transfer_addr - Set data address.
846 * @back: Backend device
847 * @address: Data register address
848 *
849 * Some devices may need to inform the backend about an address
850 * where to read or write the data.
851 *
852 * RETURNS:
853 * 0 on success, negative error number on failure.
854 */
iio_backend_data_transfer_addr(struct iio_backend * back,u32 address)855 int iio_backend_data_transfer_addr(struct iio_backend *back, u32 address)
856 {
857 return iio_backend_op_call(back, data_transfer_addr, address);
858 }
859 EXPORT_SYMBOL_NS_GPL(iio_backend_data_transfer_addr, "IIO_BACKEND");
860
__devm_iio_backend_fwnode_get(struct device * dev,const char * name,struct fwnode_handle * fwnode)861 static struct iio_backend *__devm_iio_backend_fwnode_get(struct device *dev, const char *name,
862 struct fwnode_handle *fwnode)
863 {
864 struct fwnode_handle *fwnode_back;
865 struct iio_backend *back;
866 unsigned int index;
867 int ret;
868
869 if (name) {
870 ret = device_property_match_string(dev, "io-backend-names",
871 name);
872 if (ret < 0)
873 return ERR_PTR(ret);
874 index = ret;
875 } else {
876 index = 0;
877 }
878
879 fwnode_back = fwnode_find_reference(fwnode, "io-backends", index);
880 if (IS_ERR(fwnode_back))
881 return dev_err_cast_probe(dev, fwnode_back,
882 "Cannot get Firmware reference\n");
883
884 guard(mutex)(&iio_back_lock);
885 list_for_each_entry(back, &iio_back_list, entry) {
886 if (!device_match_fwnode(back->dev, fwnode_back))
887 continue;
888
889 fwnode_handle_put(fwnode_back);
890 ret = __devm_iio_backend_get(dev, back);
891 if (ret)
892 return ERR_PTR(ret);
893
894 if (name)
895 back->idx = index;
896
897 return back;
898 }
899
900 fwnode_handle_put(fwnode_back);
901 return ERR_PTR(-EPROBE_DEFER);
902 }
903
904 /**
905 * devm_iio_backend_get - Device managed backend device get
906 * @dev: Consumer device for the backend
907 * @name: Backend name
908 *
909 * Get's the backend associated with @dev.
910 *
911 * RETURNS:
912 * A backend pointer, negative error pointer otherwise.
913 */
devm_iio_backend_get(struct device * dev,const char * name)914 struct iio_backend *devm_iio_backend_get(struct device *dev, const char *name)
915 {
916 return __devm_iio_backend_fwnode_get(dev, name, dev_fwnode(dev));
917 }
918 EXPORT_SYMBOL_NS_GPL(devm_iio_backend_get, "IIO_BACKEND");
919
920 /**
921 * devm_iio_backend_fwnode_get - Device managed backend firmware node get
922 * @dev: Consumer device for the backend
923 * @name: Backend name
924 * @fwnode: Firmware node of the backend consumer
925 *
926 * Get's the backend associated with a firmware node.
927 *
928 * RETURNS:
929 * A backend pointer, negative error pointer otherwise.
930 */
devm_iio_backend_fwnode_get(struct device * dev,const char * name,struct fwnode_handle * fwnode)931 struct iio_backend *devm_iio_backend_fwnode_get(struct device *dev,
932 const char *name,
933 struct fwnode_handle *fwnode)
934 {
935 return __devm_iio_backend_fwnode_get(dev, name, fwnode);
936 }
937 EXPORT_SYMBOL_NS_GPL(devm_iio_backend_fwnode_get, "IIO_BACKEND");
938
939 /**
940 * __devm_iio_backend_get_from_fwnode_lookup - Device managed fwnode backend device get
941 * @dev: Consumer device for the backend
942 * @fwnode: Firmware node of the backend device
943 *
944 * Search the backend list for a device matching @fwnode.
945 * This API should not be used and it's only present for preventing the first
946 * user of this framework to break it's DT ABI.
947 *
948 * RETURNS:
949 * A backend pointer, negative error pointer otherwise.
950 */
951 struct iio_backend *
__devm_iio_backend_get_from_fwnode_lookup(struct device * dev,struct fwnode_handle * fwnode)952 __devm_iio_backend_get_from_fwnode_lookup(struct device *dev,
953 struct fwnode_handle *fwnode)
954 {
955 struct iio_backend *back;
956 int ret;
957
958 guard(mutex)(&iio_back_lock);
959 list_for_each_entry(back, &iio_back_list, entry) {
960 if (!device_match_fwnode(back->dev, fwnode))
961 continue;
962
963 ret = __devm_iio_backend_get(dev, back);
964 if (ret)
965 return ERR_PTR(ret);
966
967 return back;
968 }
969
970 return ERR_PTR(-EPROBE_DEFER);
971 }
972 EXPORT_SYMBOL_NS_GPL(__devm_iio_backend_get_from_fwnode_lookup, "IIO_BACKEND");
973
974 /**
975 * iio_backend_get_priv - Get driver private data
976 * @back: Backend device
977 */
iio_backend_get_priv(const struct iio_backend * back)978 void *iio_backend_get_priv(const struct iio_backend *back)
979 {
980 return back->priv;
981 }
982 EXPORT_SYMBOL_NS_GPL(iio_backend_get_priv, "IIO_BACKEND");
983
iio_backend_unregister(void * arg)984 static void iio_backend_unregister(void *arg)
985 {
986 struct iio_backend *back = arg;
987
988 guard(mutex)(&iio_back_lock);
989 list_del(&back->entry);
990 }
991
992 /**
993 * devm_iio_backend_register - Device managed backend device register
994 * @dev: Backend device being registered
995 * @info: Backend info
996 * @priv: Device private data
997 *
998 * @info is mandatory. Not providing it results in -EINVAL.
999 *
1000 * RETURNS:
1001 * 0 on success, negative error number on failure.
1002 */
devm_iio_backend_register(struct device * dev,const struct iio_backend_info * info,void * priv)1003 int devm_iio_backend_register(struct device *dev,
1004 const struct iio_backend_info *info, void *priv)
1005 {
1006 struct iio_backend *back;
1007
1008 if (!info || !info->ops)
1009 return dev_err_probe(dev, -EINVAL, "No backend ops given\n");
1010
1011 /*
1012 * Through device_links, we guarantee that a frontend device cannot be
1013 * bound/exist if the backend driver is not around. Hence, we can bind
1014 * the backend object lifetime with the device being passed since
1015 * removing it will tear the frontend/consumer down.
1016 */
1017 back = devm_kzalloc(dev, sizeof(*back), GFP_KERNEL);
1018 if (!back)
1019 return -ENOMEM;
1020
1021 back->ops = info->ops;
1022 back->name = info->name;
1023 back->owner = dev->driver->owner;
1024 back->dev = dev;
1025 back->priv = priv;
1026 scoped_guard(mutex, &iio_back_lock)
1027 list_add(&back->entry, &iio_back_list);
1028
1029 return devm_add_action_or_reset(dev, iio_backend_unregister, back);
1030 }
1031 EXPORT_SYMBOL_NS_GPL(devm_iio_backend_register, "IIO_BACKEND");
1032
1033 MODULE_AUTHOR("Nuno Sa <nuno.sa@analog.com>");
1034 MODULE_DESCRIPTION("Framework to handle complex IIO aggregate devices");
1035 MODULE_LICENSE("GPL");
1036