1 // SPDX-License-Identifier: GPL-2.0-only
3  * Framework to handle complex IIO aggregate devices.
5  * The typical architecture is to have one device as the frontend device which
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
11  *                                           -------------------------------------------------------
12  * ------------------                        | ------------         ------------      -------  FPGA|
13  * |     ADC        |------------------------| | ADC CORE |---------| DMA CORE |------| RAM |      |
14  * | (Frontend/IIO) | Serial Data (eg: LVDS) | |(backend) |---------|          |------|     |      |
15  * |                |------------------------| ------------         ------------      -------      |
16  * ------------------                        -------------------------------------------------------
19  *   - Backends should register themselves with devm_iio_backend_register()
20  *   - Frontend devices should get backends with devm_iio_backend_get()
22  * Also to note that the primary target for this framework are converters like
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,
30  * Copyright (C) 2023-2024 Analog Devices Inc.
32 #define dev_fmt(fmt) "iio-backend: " fmt
60 	 * This index is relative to the frontend. Meaning that for
69  * that we need to free the buffer in a device managed action.
72 	struct iio_backend *back;  member
80  * Helper macros to call backend ops. Makes sure the option is supported.
82 #define iio_backend_check_op(back, op) ({ \  argument
83 	struct iio_backend *____back = back;				\
86 	if (!____back->ops->op)						\
87 		____ret = -EOPNOTSUPP;					\
92 #define iio_backend_op_call(back, op, args...) ({		\  argument
93 	struct iio_backend *__back = back;			\
98 		__ret = __back->ops->op(__back, ##args);	\
103 #define iio_backend_ptr_op_call(back, op, args...) ({		\  argument
104 	struct iio_backend *__back = back;			\
112 		ptr_err = __back->ops->op(__back, ##args);	\
117 #define iio_backend_void_op_call(back, op, args...) {		\  argument
118 	struct iio_backend *__back = back;			\
123 		__back->ops->op(__back, ##args);		\
125 		dev_dbg(__back->dev, "Op(%s) not implemented\n",\
133 	struct iio_backend *back = file->private_data;  in iio_backend_debugfs_read_reg()  local
138 	ret = iio_backend_op_call(back, debugfs_reg_access,  in iio_backend_debugfs_read_reg()
139 				  back->cached_reg_addr, 0, &val);  in iio_backend_debugfs_read_reg()
152 	struct iio_backend *back = file->private_data;  in iio_backend_debugfs_write_reg()  local
159 		return -ENOSPC;  in iio_backend_debugfs_write_reg()
161 	rc = simple_write_to_buffer(buf, sizeof(buf) - 1, ppos, userbuf, count);  in iio_backend_debugfs_write_reg()
167 	ret = sscanf(buf, "%i %i", &back->cached_reg_addr, &val);  in iio_backend_debugfs_write_reg()
173 		ret = iio_backend_op_call(back, debugfs_reg_access,  in iio_backend_debugfs_write_reg()
174 					  back->cached_reg_addr, val, NULL);  in iio_backend_debugfs_write_reg()
179 		return -EINVAL;  in iio_backend_debugfs_write_reg()
193 	struct iio_backend *back = file->private_data;  in iio_backend_debugfs_read_name()  local
197 	len = scnprintf(name, sizeof(name), "%s\n", back->name);  in iio_backend_debugfs_read_name()
208  * iio_backend_debugfs_add - Add debugfs interfaces for Backends
209  * @back: Backend device
212 void iio_backend_debugfs_add(struct iio_backend *back,  in iio_backend_debugfs_add()  argument
221 	if (!back->ops->debugfs_reg_access && !back->name)  in iio_backend_debugfs_add()
224 	snprintf(name, sizeof(name), "backend%d", back->idx);  in iio_backend_debugfs_add()
230 	if (back->ops->debugfs_reg_access)  in iio_backend_debugfs_add()
231 		debugfs_create_file("direct_reg_access", 0600, back_d, back,  in iio_backend_debugfs_add()
234 	if (back->name)  in iio_backend_debugfs_add()
235 		debugfs_create_file("name", 0400, back_d, back,  in iio_backend_debugfs_add()
241  * iio_backend_debugfs_print_chan_status - Print channel status
242  * @back: Backend device
244  * @buf: Buffer where to print the status
248  * interface and "ask" the backend to dump more details on why a test tone might
254 ssize_t iio_backend_debugfs_print_chan_status(struct iio_backend *back,  in iio_backend_debugfs_print_chan_status()  argument
259 		return -ENODEV;  in iio_backend_debugfs_print_chan_status()
261 	return iio_backend_op_call(back, debugfs_print_chan_status, chan, buf,  in iio_backend_debugfs_print_chan_status()
267  * iio_backend_chan_enable - Enable a backend channel
268  * @back: Backend device
274 int iio_backend_chan_enable(struct iio_backend *back, unsigned int chan)  in iio_backend_chan_enable()  argument
276 	return iio_backend_op_call(back, chan_enable, chan);  in iio_backend_chan_enable()
281  * iio_backend_chan_disable - Disable a backend channel
282  * @back: Backend device
288 int iio_backend_chan_disable(struct iio_backend *back, unsigned int chan)  in iio_backend_chan_disable()  argument
290 	return iio_backend_op_call(back, chan_disable, chan);  in iio_backend_chan_disable()
294 static void __iio_backend_disable(void *back)  in __iio_backend_disable()  argument
296 	iio_backend_void_op_call(back, disable);  in __iio_backend_disable()
300  * iio_backend_disable - Backend disable
301  * @back: Backend device
303 void iio_backend_disable(struct iio_backend *back)  in iio_backend_disable()  argument
305 	__iio_backend_disable(back);  in iio_backend_disable()
310  * iio_backend_enable - Backend enable
311  * @back: Backend device
316 int iio_backend_enable(struct iio_backend *back)  in iio_backend_enable()  argument
318 	return iio_backend_op_call(back, enable);  in iio_backend_enable()
323  * devm_iio_backend_enable - Device managed backend enable
325  * @back: Backend device
330 int devm_iio_backend_enable(struct device *dev, struct iio_backend *back)  in devm_iio_backend_enable()  argument
334 	ret = iio_backend_enable(back);  in devm_iio_backend_enable()
338 	return devm_add_action_or_reset(dev, __iio_backend_disable, back);  in devm_iio_backend_enable()
343  * iio_backend_data_format_set - Configure the channel data format
344  * @back: Backend device
348  * Properly configure a channel with respect to the expected data format. A
354 int iio_backend_data_format_set(struct iio_backend *back, unsigned int chan,  in iio_backend_data_format_set()  argument
357 	if (!data || data->type >= IIO_BACKEND_DATA_TYPE_MAX)  in iio_backend_data_format_set()
358 		return -EINVAL;  in iio_backend_data_format_set()
360 	return iio_backend_op_call(back, data_format_set, chan, data);  in iio_backend_data_format_set()
365  * iio_backend_data_source_set - Select data source
366  * @back: Backend device
370  * A given backend may have different sources to stream/sync data. This allows
371  * to choose that source.
376 int iio_backend_data_source_set(struct iio_backend *back, unsigned int chan,  in iio_backend_data_source_set()  argument
380 		return -EINVAL;  in iio_backend_data_source_set()
382 	return iio_backend_op_call(back, data_source_set, chan, data);  in iio_backend_data_source_set()
387  * iio_backend_data_source_get - Get current data source
388  * @back: Backend device
390  * @data: Pointer to receive the current source value
392  * A given backend may have different sources to stream/sync data. This allows
393  * to know what source is in use.
398 int iio_backend_data_source_get(struct iio_backend *back, unsigned int chan,  in iio_backend_data_source_get()  argument
403 	ret = iio_backend_op_call(back, data_source_get, chan, data);  in iio_backend_data_source_get()
408 		return -EINVAL;  in iio_backend_data_source_get()
415  * iio_backend_set_sampling_freq - Set channel sampling rate
416  * @back: Backend device
423 int iio_backend_set_sampling_freq(struct iio_backend *back, unsigned int chan,  in iio_backend_set_sampling_freq()  argument
426 	return iio_backend_op_call(back, set_sample_rate, chan, sample_rate_hz);  in iio_backend_set_sampling_freq()
431  * iio_backend_test_pattern_set - Configure a test pattern
432  * @back: Backend device
442 int iio_backend_test_pattern_set(struct iio_backend *back,  in iio_backend_test_pattern_set()  argument
447 		return -EINVAL;  in iio_backend_test_pattern_set()
449 	return iio_backend_op_call(back, test_pattern_set, chan, pattern);  in iio_backend_test_pattern_set()
454  * iio_backend_chan_status - Get the channel status
455  * @back: Backend device
459  * Get the current state of the backend channel. Typically used to check if
465 int iio_backend_chan_status(struct iio_backend *back, unsigned int chan,  in iio_backend_chan_status()  argument
468 	return iio_backend_op_call(back, chan_status, chan, error);  in iio_backend_chan_status()
473  * iio_backend_iodelay_set - Set digital I/O delay
474  * @back: Backend device
478  * Controls delays on sending/receiving data. One usecase for this is to
488 int iio_backend_iodelay_set(struct iio_backend *back, unsigned int lane,  in iio_backend_iodelay_set()  argument
491 	return iio_backend_op_call(back, iodelay_set, lane, taps);  in iio_backend_iodelay_set()
496  * iio_backend_data_sample_trigger - Control when to sample data
497  * @back: Backend device
500  * Mostly useful for input backends. Configures the backend for when to sample
506 int iio_backend_data_sample_trigger(struct iio_backend *back,  in iio_backend_data_sample_trigger()  argument
510 		return -EINVAL;  in iio_backend_data_sample_trigger()
512 	return iio_backend_op_call(back, data_sample_trigger, trigger);  in iio_backend_data_sample_trigger()
520 	iio_backend_void_op_call(pair->back, free_buffer, pair->buffer);  in iio_backend_free_buffer()
524  * devm_iio_backend_request_buffer - Device managed buffer request
526  * @back: Backend device
530  * INDIO_BUFFER_HARDWARE) is up to the backend to decide. This is because,
539 				    struct iio_backend *back,  in devm_iio_backend_request_buffer()  argument
547 		return -ENOMEM;  in devm_iio_backend_request_buffer()
549 	buffer = iio_backend_ptr_op_call(back, request_buffer, indio_dev);  in devm_iio_backend_request_buffer()
554 	pair->back = back;  in devm_iio_backend_request_buffer()
555 	pair->buffer = buffer;  in devm_iio_backend_request_buffer()
562  * iio_backend_read_raw - Read a channel attribute from a backend device.
563  * @back:	Backend device
567  * @mask:	Specify the attribute to return
572 int iio_backend_read_raw(struct iio_backend *back,  in iio_backend_read_raw()  argument
576 	return iio_backend_op_call(back, read_raw, chan, val, val2, mask);  in iio_backend_read_raw()
582 	struct iio_backend *back = ERR_PTR(-ENODEV), *iter;  in iio_backend_from_indio_dev_parent()  local
586 	 * The reason is that we want to catch frontend devices which have more  in iio_backend_from_indio_dev_parent()
588 	 * For those cases, frontends need to explicitly define  in iio_backend_from_indio_dev_parent()
593 		if (dev == iter->frontend_dev) {  in iio_backend_from_indio_dev_parent()
594 			if (!IS_ERR(back)) {  in iio_backend_from_indio_dev_parent()
596 					 "Multiple backends! get_iio_backend() needs to be implemented");  in iio_backend_from_indio_dev_parent()
597 				return ERR_PTR(-ENODEV);  in iio_backend_from_indio_dev_parent()
600 			back = iter;  in iio_backend_from_indio_dev_parent()
604 	return back;  in iio_backend_from_indio_dev_parent()
608  * iio_backend_ext_info_get - IIO ext_info read callback
610  * @private: Data private to the driver
612  * @buf: Buffer where to place the attribute data
614  * This helper is intended to be used by backends that extend an IIO channel
616  * backends are not supposed to give their own callbacks (as they would not have
617  * a way to get the backend from indio_dev). This is the getter.
620  * Number of bytes written to buf, negative error number on failure.
625 	struct iio_backend *back;  in iio_backend_ext_info_get()  local
634 	back = iio_backend_from_indio_dev_parent(indio_dev->dev.parent);  in iio_backend_ext_info_get()
635 	if (IS_ERR(back))  in iio_backend_ext_info_get()
636 		return PTR_ERR(back);  in iio_backend_ext_info_get()
638 	return iio_backend_op_call(back, ext_info_get, private, chan, buf);  in iio_backend_ext_info_get()
643  * iio_backend_ext_info_set - IIO ext_info write callback
645  * @private: Data private to the driver
650  * This helper is intended to be used by backends that extend an IIO channel
652  * backends are not supposed to give their own callbacks (as they would not have
653  * a way to get the backend from indio_dev). This is the setter.
662 	struct iio_backend *back;  in iio_backend_ext_info_set()  local
664 	back = iio_backend_from_indio_dev_parent(indio_dev->dev.parent);  in iio_backend_ext_info_set()
665 	if (IS_ERR(back))  in iio_backend_ext_info_set()
666 		return PTR_ERR(back);  in iio_backend_ext_info_set()
668 	return iio_backend_op_call(back, ext_info_set, private, chan, buf, len);  in iio_backend_ext_info_set()
673  * iio_backend_interface_type_get - get the interface type used.
674  * @back: Backend device
680 int iio_backend_interface_type_get(struct iio_backend *back,  in iio_backend_interface_type_get()  argument
685 	ret = iio_backend_op_call(back, interface_type_get, type);  in iio_backend_interface_type_get()
690 		return -EINVAL;  in iio_backend_interface_type_get()
697  * iio_backend_data_size_set - set the data width/size in the data bus.
698  * @back: Backend device
702  * interface/data bus. Hence, the backend device needs to be aware of it so
708 int iio_backend_data_size_set(struct iio_backend *back, unsigned int size)  in iio_backend_data_size_set()  argument
711 		return -EINVAL;  in iio_backend_data_size_set()
713 	return iio_backend_op_call(back, data_size_set, size);  in iio_backend_data_size_set()
718  * iio_backend_oversampling_ratio_set - set the oversampling ratio
719  * @back: Backend device
720  * @ratio: The oversampling ratio - value 1 corresponds to no oversampling.
725 int iio_backend_oversampling_ratio_set(struct iio_backend *back,  in iio_backend_oversampling_ratio_set()  argument
729 	return iio_backend_op_call(back, oversampling_ratio_set, chan, ratio);  in iio_backend_oversampling_ratio_set()
734  * iio_backend_extend_chan_spec - Extend an IIO channel
735  * @back: Backend device
744 int iio_backend_extend_chan_spec(struct iio_backend *back,  in iio_backend_extend_chan_spec()  argument
747 	const struct iio_chan_spec_ext_info *frontend_ext_info = chan->ext_info;  in iio_backend_extend_chan_spec()
751 	ret = iio_backend_op_call(back, extend_chan_spec, chan);  in iio_backend_extend_chan_spec()
755 	 * Let's keep things simple for now. Don't allow to overwrite the  in iio_backend_extend_chan_spec()
759 	if (frontend_ext_info && chan->ext_info != frontend_ext_info)  in iio_backend_extend_chan_spec()
760 		return -EOPNOTSUPP;  in iio_backend_extend_chan_spec()
761 	if (!chan->ext_info)  in iio_backend_extend_chan_spec()
764 	/* Don't allow backends to get creative and force their own handlers */  in iio_backend_extend_chan_spec()
765 	for (back_ext_info = chan->ext_info; back_ext_info->name; back_ext_info++) {  in iio_backend_extend_chan_spec()
766 		if (back_ext_info->read != iio_backend_ext_info_get)  in iio_backend_extend_chan_spec()
767 			return -EINVAL;  in iio_backend_extend_chan_spec()
768 		if (back_ext_info->write != iio_backend_ext_info_set)  in iio_backend_extend_chan_spec()
769 			return -EINVAL;  in iio_backend_extend_chan_spec()
778 	struct iio_backend *back = arg;  in iio_backend_release()  local
780 	module_put(back->owner);  in iio_backend_release()
783 static int __devm_iio_backend_get(struct device *dev, struct iio_backend *back)  in __devm_iio_backend_get()  argument
794 	if (!try_module_get(back->owner))  in __devm_iio_backend_get()
795 		return dev_err_probe(dev, -ENODEV,  in __devm_iio_backend_get()
798 	ret = devm_add_action_or_reset(dev, iio_backend_release, back);  in __devm_iio_backend_get()
802 	link = device_link_add(dev, back->dev, DL_FLAG_AUTOREMOVE_CONSUMER);  in __devm_iio_backend_get()
804 		return dev_err_probe(dev, -EINVAL,  in __devm_iio_backend_get()
805 				     "Could not link to supplier(%s)\n",  in __devm_iio_backend_get()
806 				     dev_name(back->dev));  in __devm_iio_backend_get()
808 	back->frontend_dev = dev;  in __devm_iio_backend_get()
810 	dev_dbg(dev, "Found backend(%s) device\n", dev_name(back->dev));  in __devm_iio_backend_get()
816  * iio_backend_filter_type_set - Set filter type
817  * @back: Backend device
823 int iio_backend_filter_type_set(struct iio_backend *back,  in iio_backend_filter_type_set()  argument
827 		return -EINVAL;  in iio_backend_filter_type_set()
829 	return iio_backend_op_call(back, filter_type_set, type);  in iio_backend_filter_type_set()
834  * iio_backend_interface_data_align - Perform the data alignment process.
835  * @back: Backend device
847 int iio_backend_interface_data_align(struct iio_backend *back, u32 timeout_us)  in iio_backend_interface_data_align()  argument
850 		return -EINVAL;  in iio_backend_interface_data_align()
852 	return iio_backend_op_call(back, interface_data_align, timeout_us);  in iio_backend_interface_data_align()
857  * iio_backend_num_lanes_set - Number of lanes enabled.
858  * @back: Backend device
864 int iio_backend_num_lanes_set(struct iio_backend *back, unsigned int num_lanes)  in iio_backend_num_lanes_set()  argument
867 		return -EINVAL;  in iio_backend_num_lanes_set()
869 	return iio_backend_op_call(back, num_lanes_set, num_lanes);  in iio_backend_num_lanes_set()
874  * iio_backend_ddr_enable - Enable interface DDR (Double Data Rate) mode
875  * @back: Backend device
883 int iio_backend_ddr_enable(struct iio_backend *back)  in iio_backend_ddr_enable()  argument
885 	return iio_backend_op_call(back, ddr_enable);  in iio_backend_ddr_enable()
890  * iio_backend_ddr_disable - Disable interface DDR (Double Data Rate) mode
891  * @back: Backend device
898 int iio_backend_ddr_disable(struct iio_backend *back)  in iio_backend_ddr_disable()  argument
900 	return iio_backend_op_call(back, ddr_disable);  in iio_backend_ddr_disable()
905  * iio_backend_data_stream_enable - Enable data stream
906  * @back: Backend device
913 int iio_backend_data_stream_enable(struct iio_backend *back)  in iio_backend_data_stream_enable()  argument
915 	return iio_backend_op_call(back, data_stream_enable);  in iio_backend_data_stream_enable()
920  * iio_backend_data_stream_disable - Disable data stream
921  * @back: Backend device
928 int iio_backend_data_stream_disable(struct iio_backend *back)  in iio_backend_data_stream_disable()  argument
930 	return iio_backend_op_call(back, data_stream_disable);  in iio_backend_data_stream_disable()
935  * iio_backend_data_transfer_addr - Set data address.
936  * @back: Backend device
939  * Some devices may need to inform the backend about an address
940  * where to read or write the data.
945 int iio_backend_data_transfer_addr(struct iio_backend *back, u32 address)  in iio_backend_data_transfer_addr()  argument
947 	return iio_backend_op_call(back, data_transfer_addr, address);  in iio_backend_data_transfer_addr()
955 	struct iio_backend *back;  in __devm_iio_backend_fwnode_get()  local
960 		ret = device_property_match_string(dev, "io-backend-names",  in __devm_iio_backend_fwnode_get()
969 	fwnode_back = fwnode_find_reference(fwnode, "io-backends", index);  in __devm_iio_backend_fwnode_get()
975 	list_for_each_entry(back, &iio_back_list, entry) {  in __devm_iio_backend_fwnode_get()
976 		if (!device_match_fwnode(back->dev, fwnode_back))  in __devm_iio_backend_fwnode_get()
980 		ret = __devm_iio_backend_get(dev, back);  in __devm_iio_backend_fwnode_get()
985 			back->idx = index;  in __devm_iio_backend_fwnode_get()
987 		return back;  in __devm_iio_backend_fwnode_get()
991 	return ERR_PTR(-EPROBE_DEFER);  in __devm_iio_backend_fwnode_get()
995  * devm_iio_backend_get - Device managed backend device get
1011  * devm_iio_backend_fwnode_get - Device managed backend firmware node get
1030  * __devm_iio_backend_get_from_fwnode_lookup - Device managed fwnode backend device get
1036  * user of this framework to break it's DT ABI.
1045 	struct iio_backend *back;  in __devm_iio_backend_get_from_fwnode_lookup()  local
1049 	list_for_each_entry(back, &iio_back_list, entry) {  in __devm_iio_backend_get_from_fwnode_lookup()
1050 		if (!device_match_fwnode(back->dev, fwnode))  in __devm_iio_backend_get_from_fwnode_lookup()
1053 		ret = __devm_iio_backend_get(dev, back);  in __devm_iio_backend_get_from_fwnode_lookup()
1057 		return back;  in __devm_iio_backend_get_from_fwnode_lookup()
1060 	return ERR_PTR(-EPROBE_DEFER);  in __devm_iio_backend_get_from_fwnode_lookup()
1065  * iio_backend_get_priv - Get driver private data
1066  * @back: Backend device
1068 void *iio_backend_get_priv(const struct iio_backend *back)  in iio_backend_get_priv()  argument
1070 	return back->priv;  in iio_backend_get_priv()
1076 	struct iio_backend *back = arg;  in iio_backend_unregister()  local
1079 	list_del(&back->entry);  in iio_backend_unregister()
1083  * devm_iio_backend_register - Device managed backend device register
1088  * @info is mandatory. Not providing it results in -EINVAL.
1096 	struct iio_backend *back;  in devm_iio_backend_register()  local
1098 	if (!info || !info->ops)  in devm_iio_backend_register()
1099 		return dev_err_probe(dev, -EINVAL, "No backend ops given\n");  in devm_iio_backend_register()
1107 	back = devm_kzalloc(dev, sizeof(*back), GFP_KERNEL);  in devm_iio_backend_register()
1108 	if (!back)  in devm_iio_backend_register()
1109 		return -ENOMEM;  in devm_iio_backend_register()
1111 	back->ops = info->ops;  in devm_iio_backend_register()
1112 	back->name = info->name;  in devm_iio_backend_register()
1113 	back->owner = dev->driver->owner;  in devm_iio_backend_register()
1114 	back->dev = dev;  in devm_iio_backend_register()
1115 	back->priv = priv;  in devm_iio_backend_register()
1117 		list_add(&back->entry, &iio_back_list);  in devm_iio_backend_register()
1119 	return devm_add_action_or_reset(dev, iio_backend_unregister, back);  in devm_iio_backend_register()
1124 MODULE_DESCRIPTION("Framework to handle complex IIO aggregate devices");