Loading...
Note: File does not exist in v3.5.6.
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/device.h>
36#include <linux/err.h>
37#include <linux/errno.h>
38#include <linux/list.h>
39#include <linux/module.h>
40#include <linux/mutex.h>
41#include <linux/property.h>
42#include <linux/slab.h>
43#include <linux/types.h>
44
45#include <linux/iio/backend.h>
46
47struct iio_backend {
48 struct list_head entry;
49 const struct iio_backend_ops *ops;
50 struct device *dev;
51 struct module *owner;
52 void *priv;
53};
54
55/*
56 * Helper struct for requesting buffers. This ensures that we have all data
57 * that we need to free the buffer in a device managed action.
58 */
59struct iio_backend_buffer_pair {
60 struct iio_backend *back;
61 struct iio_buffer *buffer;
62};
63
64static LIST_HEAD(iio_back_list);
65static DEFINE_MUTEX(iio_back_lock);
66
67/*
68 * Helper macros to call backend ops. Makes sure the option is supported.
69 */
70#define iio_backend_check_op(back, op) ({ \
71 struct iio_backend *____back = back; \
72 int ____ret = 0; \
73 \
74 if (!____back->ops->op) \
75 ____ret = -EOPNOTSUPP; \
76 \
77 ____ret; \
78})
79
80#define iio_backend_op_call(back, op, args...) ({ \
81 struct iio_backend *__back = back; \
82 int __ret; \
83 \
84 __ret = iio_backend_check_op(__back, op); \
85 if (!__ret) \
86 __ret = __back->ops->op(__back, ##args); \
87 \
88 __ret; \
89})
90
91#define iio_backend_ptr_op_call(back, op, args...) ({ \
92 struct iio_backend *__back = back; \
93 void *ptr_err; \
94 int __ret; \
95 \
96 __ret = iio_backend_check_op(__back, op); \
97 if (__ret) \
98 ptr_err = ERR_PTR(__ret); \
99 else \
100 ptr_err = __back->ops->op(__back, ##args); \
101 \
102 ptr_err; \
103})
104
105#define iio_backend_void_op_call(back, op, args...) { \
106 struct iio_backend *__back = back; \
107 int __ret; \
108 \
109 __ret = iio_backend_check_op(__back, op); \
110 if (!__ret) \
111 __back->ops->op(__back, ##args); \
112}
113
114/**
115 * iio_backend_chan_enable - Enable a backend channel
116 * @back: Backend device
117 * @chan: Channel number
118 *
119 * RETURNS:
120 * 0 on success, negative error number on failure.
121 */
122int iio_backend_chan_enable(struct iio_backend *back, unsigned int chan)
123{
124 return iio_backend_op_call(back, chan_enable, chan);
125}
126EXPORT_SYMBOL_NS_GPL(iio_backend_chan_enable, IIO_BACKEND);
127
128/**
129 * iio_backend_chan_disable - Disable a backend channel
130 * @back: Backend device
131 * @chan: Channel number
132 *
133 * RETURNS:
134 * 0 on success, negative error number on failure.
135 */
136int iio_backend_chan_disable(struct iio_backend *back, unsigned int chan)
137{
138 return iio_backend_op_call(back, chan_disable, chan);
139}
140EXPORT_SYMBOL_NS_GPL(iio_backend_chan_disable, IIO_BACKEND);
141
142static void __iio_backend_disable(void *back)
143{
144 iio_backend_void_op_call(back, disable);
145}
146
147/**
148 * devm_iio_backend_enable - Device managed backend enable
149 * @dev: Consumer device for the backend
150 * @back: Backend device
151 *
152 * RETURNS:
153 * 0 on success, negative error number on failure.
154 */
155int devm_iio_backend_enable(struct device *dev, struct iio_backend *back)
156{
157 int ret;
158
159 ret = iio_backend_op_call(back, enable);
160 if (ret)
161 return ret;
162
163 return devm_add_action_or_reset(dev, __iio_backend_disable, back);
164}
165EXPORT_SYMBOL_NS_GPL(devm_iio_backend_enable, IIO_BACKEND);
166
167/**
168 * iio_backend_data_format_set - Configure the channel data format
169 * @back: Backend device
170 * @chan: Channel number
171 * @data: Data format
172 *
173 * Properly configure a channel with respect to the expected data format. A
174 * @struct iio_backend_data_fmt must be passed with the settings.
175 *
176 * RETURNS:
177 * 0 on success, negative error number on failure.
178 */
179int iio_backend_data_format_set(struct iio_backend *back, unsigned int chan,
180 const struct iio_backend_data_fmt *data)
181{
182 if (!data || data->type >= IIO_BACKEND_DATA_TYPE_MAX)
183 return -EINVAL;
184
185 return iio_backend_op_call(back, data_format_set, chan, data);
186}
187EXPORT_SYMBOL_NS_GPL(iio_backend_data_format_set, IIO_BACKEND);
188
189static void iio_backend_free_buffer(void *arg)
190{
191 struct iio_backend_buffer_pair *pair = arg;
192
193 iio_backend_void_op_call(pair->back, free_buffer, pair->buffer);
194}
195
196/**
197 * devm_iio_backend_request_buffer - Device managed buffer request
198 * @dev: Consumer device for the backend
199 * @back: Backend device
200 * @indio_dev: IIO device
201 *
202 * Request an IIO buffer from the backend. The type of the buffer (typically
203 * INDIO_BUFFER_HARDWARE) is up to the backend to decide. This is because,
204 * normally, the backend dictates what kind of buffering we can get.
205 *
206 * The backend .free_buffer() hooks is automatically called on @dev detach.
207 *
208 * RETURNS:
209 * 0 on success, negative error number on failure.
210 */
211int devm_iio_backend_request_buffer(struct device *dev,
212 struct iio_backend *back,
213 struct iio_dev *indio_dev)
214{
215 struct iio_backend_buffer_pair *pair;
216 struct iio_buffer *buffer;
217
218 pair = devm_kzalloc(dev, sizeof(*pair), GFP_KERNEL);
219 if (!pair)
220 return -ENOMEM;
221
222 buffer = iio_backend_ptr_op_call(back, request_buffer, indio_dev);
223 if (IS_ERR(buffer))
224 return PTR_ERR(buffer);
225
226 /* weak reference should be all what we need */
227 pair->back = back;
228 pair->buffer = buffer;
229
230 return devm_add_action_or_reset(dev, iio_backend_free_buffer, pair);
231}
232EXPORT_SYMBOL_NS_GPL(devm_iio_backend_request_buffer, IIO_BACKEND);
233
234static void iio_backend_release(void *arg)
235{
236 struct iio_backend *back = arg;
237
238 module_put(back->owner);
239}
240
241static int __devm_iio_backend_get(struct device *dev, struct iio_backend *back)
242{
243 struct device_link *link;
244 int ret;
245
246 /*
247 * Make sure the provider cannot be unloaded before the consumer module.
248 * Note that device_links would still guarantee that nothing is
249 * accessible (and breaks) but this makes it explicit that the consumer
250 * module must be also unloaded.
251 */
252 if (!try_module_get(back->owner))
253 return dev_err_probe(dev, -ENODEV,
254 "Cannot get module reference\n");
255
256 ret = devm_add_action_or_reset(dev, iio_backend_release, back);
257 if (ret)
258 return ret;
259
260 link = device_link_add(dev, back->dev, DL_FLAG_AUTOREMOVE_CONSUMER);
261 if (!link)
262 return dev_err_probe(dev, -EINVAL,
263 "Could not link to supplier(%s)\n",
264 dev_name(back->dev));
265
266 dev_dbg(dev, "Found backend(%s) device\n", dev_name(back->dev));
267
268 return 0;
269}
270
271/**
272 * devm_iio_backend_get - Device managed backend device get
273 * @dev: Consumer device for the backend
274 * @name: Backend name
275 *
276 * Get's the backend associated with @dev.
277 *
278 * RETURNS:
279 * A backend pointer, negative error pointer otherwise.
280 */
281struct iio_backend *devm_iio_backend_get(struct device *dev, const char *name)
282{
283 struct fwnode_handle *fwnode;
284 struct iio_backend *back;
285 unsigned int index;
286 int ret;
287
288 if (name) {
289 ret = device_property_match_string(dev, "io-backend-names",
290 name);
291 if (ret < 0)
292 return ERR_PTR(ret);
293 index = ret;
294 } else {
295 index = 0;
296 }
297
298 fwnode = fwnode_find_reference(dev_fwnode(dev), "io-backends", index);
299 if (IS_ERR(fwnode)) {
300 dev_err_probe(dev, PTR_ERR(fwnode),
301 "Cannot get Firmware reference\n");
302 return ERR_CAST(fwnode);
303 }
304
305 guard(mutex)(&iio_back_lock);
306 list_for_each_entry(back, &iio_back_list, entry) {
307 if (!device_match_fwnode(back->dev, fwnode))
308 continue;
309
310 fwnode_handle_put(fwnode);
311 ret = __devm_iio_backend_get(dev, back);
312 if (ret)
313 return ERR_PTR(ret);
314
315 return back;
316 }
317
318 fwnode_handle_put(fwnode);
319 return ERR_PTR(-EPROBE_DEFER);
320}
321EXPORT_SYMBOL_NS_GPL(devm_iio_backend_get, IIO_BACKEND);
322
323/**
324 * __devm_iio_backend_get_from_fwnode_lookup - Device managed fwnode backend device get
325 * @dev: Consumer device for the backend
326 * @fwnode: Firmware node of the backend device
327 *
328 * Search the backend list for a device matching @fwnode.
329 * This API should not be used and it's only present for preventing the first
330 * user of this framework to break it's DT ABI.
331 *
332 * RETURNS:
333 * A backend pointer, negative error pointer otherwise.
334 */
335struct iio_backend *
336__devm_iio_backend_get_from_fwnode_lookup(struct device *dev,
337 struct fwnode_handle *fwnode)
338{
339 struct iio_backend *back;
340 int ret;
341
342 guard(mutex)(&iio_back_lock);
343 list_for_each_entry(back, &iio_back_list, entry) {
344 if (!device_match_fwnode(back->dev, fwnode))
345 continue;
346
347 ret = __devm_iio_backend_get(dev, back);
348 if (ret)
349 return ERR_PTR(ret);
350
351 return back;
352 }
353
354 return ERR_PTR(-EPROBE_DEFER);
355}
356EXPORT_SYMBOL_NS_GPL(__devm_iio_backend_get_from_fwnode_lookup, IIO_BACKEND);
357
358/**
359 * iio_backend_get_priv - Get driver private data
360 * @back: Backend device
361 */
362void *iio_backend_get_priv(const struct iio_backend *back)
363{
364 return back->priv;
365}
366EXPORT_SYMBOL_NS_GPL(iio_backend_get_priv, IIO_BACKEND);
367
368static void iio_backend_unregister(void *arg)
369{
370 struct iio_backend *back = arg;
371
372 guard(mutex)(&iio_back_lock);
373 list_del(&back->entry);
374}
375
376/**
377 * devm_iio_backend_register - Device managed backend device register
378 * @dev: Backend device being registered
379 * @ops: Backend ops
380 * @priv: Device private data
381 *
382 * @ops is mandatory. Not providing it results in -EINVAL.
383 *
384 * RETURNS:
385 * 0 on success, negative error number on failure.
386 */
387int devm_iio_backend_register(struct device *dev,
388 const struct iio_backend_ops *ops, void *priv)
389{
390 struct iio_backend *back;
391
392 if (!ops)
393 return dev_err_probe(dev, -EINVAL, "No backend ops given\n");
394
395 /*
396 * Through device_links, we guarantee that a frontend device cannot be
397 * bound/exist if the backend driver is not around. Hence, we can bind
398 * the backend object lifetime with the device being passed since
399 * removing it will tear the frontend/consumer down.
400 */
401 back = devm_kzalloc(dev, sizeof(*back), GFP_KERNEL);
402 if (!back)
403 return -ENOMEM;
404
405 back->ops = ops;
406 back->owner = dev->driver->owner;
407 back->dev = dev;
408 back->priv = priv;
409 scoped_guard(mutex, &iio_back_lock)
410 list_add(&back->entry, &iio_back_list);
411
412 return devm_add_action_or_reset(dev, iio_backend_unregister, back);
413}
414EXPORT_SYMBOL_NS_GPL(devm_iio_backend_register, IIO_BACKEND);
415
416MODULE_AUTHOR("Nuno Sa <nuno.sa@analog.com>");
417MODULE_DESCRIPTION("Framework to handle complex IIO aggregate devices");
418MODULE_LICENSE("GPL");