Signed-off-by: Nuno Sa <nuno.sa@xxxxxxxxxx>
---
drivers/iio/addac/converter.c | 547 ++++++++++++++++++++++++++++
include/linux/iio/addac/converter.h | 485 ++++++++++++++++++++++++
2 files changed, 1032 insertions(+)
create mode 100644 drivers/iio/addac/converter.c
create mode 100644 include/linux/iio/addac/converter.h
diff --git a/drivers/iio/addac/converter.c b/drivers/iio/addac/converter.c
new file mode 100644
index 000000000000..31ac704255ad
--- /dev/null
+++ b/drivers/iio/addac/converter.c
@@ -0,0 +1,547 @@
+// SPDX-License-Identifier: GPL-2.0-only
+/*
+ * Framework to handle complex IIO aggregate devices
+ *
+ * A note on some of the design expectations with regards to lifetimes and
+ * devices bringup/removal.
+ *
+ * The Framework is using, under the wood, the component API which makes it to
+ * easy treat a bunch of devices as one aggregate device. This means that the
+ * complete thing is only brought to live when all the deviced are probed. To do
+ * this, two callbacks are used that should in fact completely replace .probe()
+ * and .remove(). The formers should only be used the minimum needed. Ideally,
+ * only to call the functions to add and remove frontend annd backend devices.
+ *
+ * It is advised for frontend and backend drivers to use their .remove()
+ * callbacks (to use devres API during the frontend and backends initialization).
+ * See the comment in @converter_frontend_bind().
+ *
+ * It is also assumed that converter objects cannot be accessed once one of the
+ * devices of the aggregate device is removed (effectively bringing the all the
+ * devices down). Based on that assumption, these objects are not refcount which
+ * means accessing them will likely fail miserably.
+ *
+ * Copyright (C) 2023 Analog Devices Inc.
+ */
+
+#define dev_fmt(fmt) "Converter - " fmt
+
+#include <linux/component.h>
+#include <linux/debugfs.h>
+#include <linux/device.h>
+#include <linux/err.h>
+#include <linux/iio/addc/converter.h>
+#include <linux/iio/iio.h>
+#include <linux/list.h>
+#include <linux/module.h>
+#include <linux/property.h>
+#include <linux/regmap.h>
+
+struct converter_backend {
+ struct list_head entry;
+ struct device *dev;
+ const struct converter_ops *ops;
+ const char *name;
+ void *drvdata;
+
+ struct regmap *regmap;
+ unsigned int cached_reg_addr;
+};
+
+struct converter_frontend {
+ struct list_head list;
+ const struct frontend_ops *ops;
+ struct device *dev;
+};
+
+static ssize_t converter_debugfs_read_reg(struct file *file,
+ char __user *userbuf,
+ size_t count, loff_t *ppos)
+{
+ struct converter_backend *conv = file->private_data;
+ unsigned int val = 0;
+ char read_buf[20];
+ int ret, len;
+
+ ret = regmap_read(conv->regmap, conv->cached_reg_addr, &val);
+ if (ret) {
+ dev_err(conv->dev, "%s: read failed\n", __func__);
+ return ret;
+ }
+
+ len = scnprintf(read_buf, sizeof(read_buf), "0x%X\n", val);
+
+ return simple_read_from_buffer(userbuf, count, ppos, read_buf, len);
+}
+
+static ssize_t converter_debugfs_write_reg(struct file *file,
+ const char __user *userbuf,
+ size_t count, loff_t *ppos)
+{
+ struct converter_backend *conv = file->private_data;
+ unsigned int val;
+ char buf[80];
+ ssize_t rc;
+ int ret;
+
+ rc = simple_write_to_buffer(buf, sizeof(buf), ppos, userbuf, count);
+ if (rc < 0)
+ return rc;
+
+ ret = sscanf(buf, "%i %i", &conv->cached_reg_addr, &val);
+
+ switch (ret) {
+ case 1:
+ break;
+ case 2:
+ ret = regmap_write(conv->regmap, conv->cached_reg_addr, val);
+ if (ret) {
+ dev_err(conv->dev, "%s: write failed\n", __func__);
+ return ret;
+ }
+ break;
+ default:
+ return -EINVAL;
+ }
+
+ return count;
+}
+
+static const struct file_operations converter_debugfs_reg_fops = {
+ .open = simple_open,
+ .read = converter_debugfs_read_reg,
+ .write = converter_debugfs_write_reg,
+};
+
+static void __converter_add_direct_reg_access(struct converter_backend *conv,
+ struct iio_dev *indio_dev)
+{
+ struct dentry *d = iio_get_debugfs_dentry(indio_dev);
+ const char *name = conv->name;
+ char file_name[64];
+
+ if (!conv->regmap)
+ return;
+ if (!d)
+ return;
+
+ if (!conv->name)
+ name = "converter";
+
+ snprintf(file_name, sizeof(file_name), "%s_direct_reg_access", name);
+
+ debugfs_create_file(file_name, 0644, d, conv,
+ &converter_debugfs_reg_fops);
+}
+
+void converter_add_direct_reg_access(struct converter_backend *conv,
+ struct iio_dev *indio_dev)
+{
+ if (IS_ENABLED(CONFIG_DEBUG_FS))
+ __converter_add_direct_reg_access(conv, indio_dev);
+}
+EXPORT_SYMBOL_NS_GPL(converter_add_direct_reg_access, IIO_CONVERTER);
+
+static int converter_bind(struct device *dev, struct device *aggregate,
+ void *data)
+{
+ struct converter_frontend *frontend = dev_get_drvdata(aggregate);
+ struct converter_backend *conv = dev_get_drvdata(dev);
+ int ret;
+
+ ret = conv->ops->backend_init(conv, dev);
+ if (ret)
+ return ret;
+
+ list_add_tail(&conv->entry, &frontend->list);
+
+ return 0;
+}
+
+static void converter_unbind(struct device *dev, struct device *aggregate,
+ void *data)
+{
+ struct converter_backend *conv = dev_get_drvdata(dev);
+
+ if (conv->ops->backend_close)
+ conv->ops->backend_close(conv);
+
+ /* after this point the converter should not be used anymore */
+ converter_set_drvdata(conv, NULL);
+}
+
+static const struct component_ops converter_component_ops = {
+ .bind = converter_bind,
+ .unbind = converter_unbind,
+};
+
+static int converter_frontend_bind(struct device *dev)
+{
+ struct converter_frontend *frontend = dev_get_drvdata(dev);
+ int ret;
+
+ ret = component_bind_all(dev, NULL);
+ if (ret)
+ return ret;
+ /*
+ * We open a new group so that we can control when resources are
+ * released and still use device managed (devm_) calls. The expectations
+ * are that on probe, backend resources are allocated first followed by
+ * the frontend resources (where registering the IIO device must happen)
+ * Naturally we want the reverse order on the unbind path and that would
+ * not be possible without opening our own devres group.
+
+ * Note that the component API also opens it's own devres group when
+ * calling the .bind() callbacks for both the aggregate device
+ * (our frontend) and each of the components (our backends). On the
+ * unbind path, the aggregate .unbind() function is called
+ * (@converter_frontend_unbind()) which should be responsible to tear
+ * down all the components (effectively releasing all the resources
+ * allocated on each component devres group) and only then the aggregate
+ * devres group is released. Hence, the order we want to maintain for
+ * releasing resources would not be satisfied because backend resources
+ * would be freed first. With our own group, we can control when
+ * releasing the resources and we do it before @component_unbind_all().
+ *
+ * This also relies that internally the component API is releasing each
+ * of the component's devres group. That is likely not to change, but
+ * maybe we should not trust it and also open our own groups for backend
+ * devices?!
+ *
+ * Another very important thing to keep in mind is that this is only
+ * valid if frontend and backend driver's are implementing their
+ * .remove() callback to call @converter_frontend_del() and
+ * @converter_backend_del(). Calling those functions from
+ * devm_add_action* and use devm APIs in .frontend_init() and
+ * .backend_init() is not going to work. Not perfect but still better
+ * than having to tear everything down in .frontend_close() and
+ * .backend_close()
+ */
+ if (!devres_open_group(dev, frontend, GFP_KERNEL))
+ return -ENOMEM;
+
+ ret = frontend->ops->frontend_init(frontend, dev);
+ if (ret) {
+ devres_release_group(dev, frontend);
+ return ret;
+ }
+
+ devres_close_group(dev, NULL);
+ return 0;
+}
+
+static void converter_frontend_unbind(struct device *dev)
+{
+ struct converter_frontend *frontend = dev_get_drvdata(dev);
+
+ if (frontend->ops->frontend_close)
+ frontend->ops->frontend_close(frontend);
+
+ devres_release_group(dev, frontend);
+ component_unbind_all(dev, NULL);
+ list_del_init(&frontend->list);
+}
+
+static const struct component_master_ops frontend_component_ops = {
+ .bind = converter_frontend_bind,
+ .unbind = converter_frontend_unbind,
+};
+
+struct converter_backend *converter_get(const struct converter_frontend *frontend,
+ const char *name)
+{
+ struct converter_backend *iter, *conv = NULL;
+ struct device *dev = frontend->dev;
+ struct fwnode_handle *fwnode;
+ int index = 0;
+
+ if (list_empty(&frontend->list)) {
+ dev_err(dev, "Backend list is empty...\n");
+ return ERR_PTR(-ENODEV);
+ }
+
+ /* if no name given, we assume only one converter_backend exists */
+ if (!name)
+ return list_first_entry(&frontend->list,
+ struct converter_backend, entry);
+
+ index = device_property_match_string(frontend->dev, "converter-names",
+ name);
+ if (index < 0)
+ return ERR_PTR(index);
+
+ fwnode = fwnode_find_reference(dev_fwnode(dev), "converters", index);
+ if (IS_ERR(fwnode))
+ return ERR_CAST(fwnode);
+
+ list_for_each_entry(iter, &frontend->list, entry) {
+ if (device_match_fwnode(iter->dev, fwnode)) {
+ conv = iter;
+ break;
+ }
+ }
+
+ fwnode_handle_put(fwnode);
+
+ if (!conv) {
+ dev_err(dev, "Converter (%s) not found in the list\n", name);
+ return ERR_PTR(-ENODEV);
+ }
+
+ /* See if we can add device_property_string_read_index() */
+ conv->name = kstrdup_const(name, GFP_KERNEL);
+ if (!conv->name)
+ return ERR_PTR(-ENOMEM);
+
+ return conv;
+}
+EXPORT_SYMBOL_NS_GPL(converter_get, IIO_CONVERTER);
+
+static int converter_frontend_add_matches(struct converter_frontend *frontend,
+ struct component_match **match)
+{
+ struct device *dev = frontend->dev;
+ struct fwnode_handle *fwnode;
+ int index = 0;
+
+ do {
+ fwnode = fwnode_find_reference(dev_fwnode(dev), "converters",
+ index);
+ if (IS_ERR(fwnode))
+ break;
+
+ component_match_add_release(dev, match,
+ component_release_fwnode,
+ component_compare_fwnode, fwnode);
+ index++;
+ } while (true);
+
+ /* no devices?! */
+ if (!index) {
+ dev_err(dev, "No converters. Make sure the \"converters\" property is given!\n");
+ return -ENODEV;
+ }
+
+ if (PTR_ERR(fwnode) != -ENOENT)
+ return PTR_ERR(fwnode);
+
+ return 0;
+}
+
+int converter_test_pattern_set(struct converter_backend *conv,
+ unsigned int chan,
+ enum converter_test_pattern pattern)
+{
+ if (pattern >= CONVERTER_TEST_PATTERN_MAX)
+ return -EINVAL;
+ if (!conv->ops->test_pattern_set)
+ return -ENOTSUPP;
+
+ return conv->ops->test_pattern_set(conv, chan, pattern);
+}
+EXPORT_SYMBOL_NS_GPL(converter_test_pattern_set, IIO_CONVERTER);
+
+int converter_chan_status_get(struct converter_backend *conv,
+ unsigned int chan,
+ struct converter_chan_status *status)
+{
+ if (!conv->ops->chan_status)
+ return -ENOTSUPP;
+
+ return conv->ops->chan_status(conv, chan, status);
+}
+EXPORT_SYMBOL_NS_GPL(converter_chan_status_get, IIO_CONVERTER);
+
+int converter_iodelay_set(struct converter_backend *conv,
+ unsigned int num_lanes, unsigned int delay)
+{
+ if (!num_lanes)
+ return -EINVAL;
+ if (!conv->ops->iodelay_set)
+ return -ENOTSUPP;
+
+ return conv->ops->iodelay_set(conv, num_lanes, delay);
+}
+EXPORT_SYMBOL_NS_GPL(converter_iodelay_set, IIO_CONVERTER);
+
+int converter_data_format_set(struct converter_backend *conv,
+ unsigned int chan,
+ const struct converter_data_fmt *data)
+{
+ if (data->type >= CONVERTER_DATA_TYPE_MAX)
+ return -EINVAL;
+ if (!conv->ops->data_format_set)
+ return -ENOTSUPP;
+
+ return conv->ops->data_format_set(conv, chan, data);
+}
+EXPORT_SYMBOL_NS_GPL(converter_data_format_set, IIO_CONVERTER);
+
+int converter_sample_edge_select(struct converter_backend *conv,
+ enum converter_edge edge)
+{
+ if (edge >= CONVERTER_EDGE_MAX)
+ return -EINVAL;
+ if (conv->ops->sample_edge_select)
+ return -ENOTSUPP;
+
+ return conv->ops->sample_edge_select(conv, edge);
+}
+EXPORT_SYMBOL_NS_GPL(converter_sample_edge_select, IIO_CONVERTER);
+
+int converter_chan_enable(struct converter_backend *conv, unsigned int chan)
+{
+ if (!conv->ops->chan_enable)
+ return -ENOTSUPP;
+
+ return conv->ops->chan_enable(conv, chan);
+}
+EXPORT_SYMBOL_NS_GPL(converter_chan_enable, IIO_CONVERTER);
+
+int converter_chan_disable(struct converter_backend *conv, unsigned int chan)
+{
+ if (!conv->ops->disable)
+ return -ENOTSUPP;
+
+ return conv->ops->chan_disable(conv, chan);
+}
+EXPORT_SYMBOL_NS_GPL(converter_chan_disable, IIO_CONVERTER);
+
+int converter_enable(struct converter_backend *conv)
+{
+ if (!conv->ops->enable)
+ return -ENOTSUPP;
+
+ return conv->ops->enable(conv);
+}
+EXPORT_SYMBOL_NS_GPL(converter_enable, IIO_CONVERTER);
+
+void converter_disable(struct converter_backend *conv)
+{
+ if (!conv->ops->disable)
+ return;
+
+ conv->ops->disable(conv);
+}
+EXPORT_SYMBOL_NS_GPL(converter_disable, IIO_CONVERTER);
+
+int __converter_test_pattern_xlate(unsigned int pattern,
+ const struct converter_test_pattern_xlate *xlate,
+ int n_matches)
+{
+ unsigned int p = n_matches;
+
+ while (p--) {
+ if (pattern == xlate[p].pattern)
+ return xlate[p].reg_val;
+ }
+
+ return -EINVAL;
+}
+EXPORT_SYMBOL_NS_GPL(__converter_test_pattern_xlate, IIO_CONVERTER);
+
+void converter_set_regmap(struct converter_backend *conv,
+ struct regmap *regmap)
+{
+ conv->regmap = regmap;
+}
+EXPORT_SYMBOL_NS_GPL(converter_set_regmap, IIO_CONVERTER);
+
+void converter_set_drvdata(struct converter_backend *conv, void *drvdata)
+{
+ conv->drvdata = drvdata;
+}
+EXPORT_SYMBOL_NS_GPL(converter_set_drvdata, IIO_CONVERTER);
+
+void *converter_get_drvdata(const struct converter_backend *conv)
+{
+ WARN_ON(!conv->drvdata);
+ return conv->drvdata;
+}
+EXPORT_SYMBOL_NS_GPL(converter_get_drvdata, IIO_CONVERTER);
+
+void converter_del(struct device *dev)
+{
+ component_del(dev, &converter_component_ops);
+}
+EXPORT_SYMBOL_NS_GPL(converter_del, IIO_CONVERTER);
+
+static void converter_free(void *conv)
+{
+ struct converter_backend *__conv = conv;
+
+ if (__conv->name)
+ kfree_const(__conv->name);
+
+ kfree(__conv);
+}
+
+int converter_add(struct device *dev, const struct converter_ops *ops)
+{
+ struct converter_backend *conv;
+ int ret;
+
+ if (!ops || !ops->backend_init)
+ return -EINVAL;
+
+ conv = kzalloc(sizeof(*conv), GFP_KERNEL);
+ if (!conv)
+ return -ENOMEM;
+
+ /*
+ * The expectation is that everything goes up and down in
+ * .converter_bind() and .converter_unbind() respectively. Hence, it's
+ * not expected for converter objects to be accessed after unbind(). As
+ * soon as that does not stand anymore, we need to
+ * drop devm_add_action_or_reset() and properly refcount the objects.
+ */
+ ret = devm_add_action_or_reset(dev, converter_free, conv);
+ if (ret)
+ return ret;
+
+ conv->ops = ops;
+ dev_set_drvdata(dev, conv);
+ conv->dev = dev;
+
+ return component_add(dev, &converter_component_ops);
+}
+EXPORT_SYMBOL_NS_GPL(converter_add, IIO_CONVERTER);
+
+void converter_frontend_del(struct device *dev)
+{
+ component_master_del(dev, &frontend_component_ops);
+}
+EXPORT_SYMBOL_NS_GPL(converter_frontend_del, IIO_CONVERTER);
+
+int converter_frontend_add(struct device *dev, const struct frontend_ops *ops)
+{
+ struct converter_frontend *frontend;
+ struct component_match *match;
+ int ret;
+
+ if (!ops || !ops->frontend_init) {
+ dev_err(dev, "Mandatory ops missing\n");
+ return -EINVAL;
+ }
+
+ frontend = devm_kzalloc(dev, sizeof(*frontend), GFP_KERNEL);
+ if (!frontend)
+ return -ENOMEM;
+
+ frontend->ops = ops;
+ frontend->dev = dev;
+ INIT_LIST_HEAD(&frontend->list);
+ dev_set_drvdata(dev, frontend);
+
+ ret = converter_frontend_add_matches(frontend, &match);
+ if (ret)
+ return ret;
+
+ return component_master_add_with_match(dev, &frontend_component_ops,
+ match);
+}
+EXPORT_SYMBOL_NS_GPL(converter_frontend_add, IIO_CONVERTER);
+
+MODULE_AUTHOR("Nuno Sa <nuno.sa@xxxxxxxxxx>");
+MODULE_DESCRIPTION("Framework to handle complex IIO aggregate devices");
+MODULE_LICENSE("GPL v2");
diff --git a/include/linux/iio/addac/converter.h b/include/linux/iio/addac/converter.h
new file mode 100644
index 000000000000..09d9d491b2b8
--- /dev/null
+++ b/include/linux/iio/addac/converter.h
@@ -0,0 +1,485 @@
+/* SPDX-License-Identifier: GPL-2.0-only */
+#ifndef _CONVERTER_H
+#define _CONVERTER_H
+
+struct converter_frontend;
+struct converter_backend;
+struct iio_dev;
+struct device;
+struct regmap;
+
+enum converter_test_pattern {
+ CONVERTER_PRBS_7,
+ CONVERTER_PRBS_15,
+ CONVERTER_PRBS_23,
+ CONVERTER_PRBS_31,
+ CONVERTER_RAMP_NIBBLE,
+ CONVERTER_RAMP_16,
+ /* vendor specific from 32 */
+ CONVERTER_ADI_PRBS_9A = 32,
+ CONVERTER_ADI_PRBS_23A,
+ CONVERTER_ADI_PRBS_X,
+ CONVERTER_TEST_PATTERN_MAX
+};
+
+enum converter_data_type {
+ CONVERTER_TWOS_COMPLEMENT,
+ CONVERTER_OFFSET_BINARY,
+ CONVERTER_DATA_TYPE_MAX
+};
+
+enum converter_edge {
+ CONVERTER_RISING_EDGE_SAMPLE,
+ CONVERTER_FALLING_EDGE_SAMPLE,
+ CONVERTER_EDGE_MAX
+};
+
+struct converter_chan_status {
+ bool errors;
+};
+
+/**
+ * struct converter_data_fmt - Backend data format
+ * @type: Data type.
+ * @sign_extend: Bool to tell if the data is sign extended.
+ * @enable: Enable/Disable the data format module. If disabled,
+ * not formatting will happen.
+ */
+struct converter_data_fmt {
+ enum converter_data_type type;
+ bool sign_extend;
+ bool enable;
+};
+
+/**
+ * struct converter_test_pattern_xlate - Helper struct for test pattern handling
+ * @pattern: Pattern to configure.
+ * @reg_val: Register value for the pattern to configure.
+ */
+struct converter_test_pattern_xlate {
+ enum converter_test_pattern pattern;
+ unsigned int reg_val;
+};
+
+/**
+ * struct converter_ops - Backend supported operations
+ * @backend_init: Mandatory function to initialize the backend device. It
+ * should be a replacement for .probe() where the latest
+ * should only have to care about doing @converter_add().
+ * @backend_close: Optional function to tear down the device.
+ * @enable: Enable the backend device.
+ * @disable: Disable the backend device.
+ * @data_format_set: Configure the data format for a specific channel.
+ * @chan_enable: Enable one channel.
+ * @chan_disable: Disable one channel.
+ * @iodelay_set: Controls the IO delay for all the lanes at the interface
+ * (where data is actually transferred between frontend and
+ backend) level.
+ * @test_pattern_set: Set's a test pattern to be transmitted/received by the
+ * backend. Typically useful for debug or interface
+ * purposes calibration.
+ */
+struct converter_ops {
+ int (*backend_init)(struct converter_backend *conv, struct device *dev);
+ void (*backend_close)(struct converter_backend *conv);
+ int (*enable)(struct converter_backend *conv);
+ void (*disable)(struct converter_backend *conv);
+ int (*data_format_set)(struct converter_backend *conv,
+ unsigned int chan,
+ const struct converter_data_fmt *data);
+ int (*chan_enable)(struct converter_backend *conv, unsigned int chan);
+ int (*chan_disable)(struct converter_backend *conv, unsigned int chan);
+ int (*iodelay_set)(struct converter_backend *conv,
+ unsigned int num_lanes, unsigned int delay);
+ int (*test_pattern_set)(struct converter_backend *conv,
+ unsigned int chan,
+ enum converter_test_pattern pattern);
+ int (*chan_status)(struct converter_backend *conv, unsigned int chan,
+ struct converter_chan_status *status);
+ int (*sample_edge_select)(struct converter_backend *conv,
+ enum converter_edge edge);
+};
+
+/**
+ * struct frontend_ops - Frontend supported operations
+ * @frontend_init: Mandatory function to initialize the frontend device. It
+ * should be a replacement for .probe() where the latest
+ * should only have to care about doing @frontend_add().
+ * @frontend_close: Optional function to tear down the device.
+ */
+struct frontend_ops {
+ int (*frontend_init)(struct converter_frontend *frontend,
+ struct device *dev);
+ void (*frontend_close)(struct converter_frontend *frontend);
+};
+
+/**
+ * converter_test_pattern_xlate() - Helper macro for translatting test patterns
+ * @pattern: Pattern to translate.
+ * @xlate: List of @struct converter_test_pattern_xlate pairs.
+ *
+ * Simple helper to match a supported pattern and get the register value. Should
+ * only be called by backend devices. Automatically computes the number of
+ * @xlate entries.
+ */
+#define converter_test_pattern_xlate(pattern, xlate) \
+ __converter_test_pattern_xlate(pattern, xlate, ARRAY_SIZE(xlate));
+
+#if IS_ENABLED(CONFIG_IIO_CONVERTER)
+
+/**
+ * converter_get_drvdata - Get driver private data
+ * @conv: Converter device.
+ */
+void *converter_get_drvdata(const struct converter_backend *conv);
+
+/**
+ * converter_set_drvdata - Set driver private data
+ * @conv: Converter device.
+ * @drvdata: Driver private data.
+ */
+void converter_set_drvdata(struct converter_backend *conv, void *drvdata);
+
+/**
+ * converter_set_regmap - Add a regmap object to a converter
+ * @conv: Converter device.
+ * @regmap: Regmap object.
+ */
+void converter_set_regmap(struct converter_backend *conv,
+ struct regmap *regmap);
+
+/**
+ * __converter_test_pattern_xlate - Helper macro for translatting test patterns
+ * @pattern: Pattern to translate.
+ * @xlate: List of @struct converter_test_pattern_xlate pairs.
+ * @n_matches: Number of entries in @xlate.
+ *
+ * Simple helper to match a supported pattern and get the register value. Should
+ * only be called by backend devices.
+ */
+int __converter_test_pattern_xlate(unsigned int pattern,
+ const struct converter_test_pattern_xlate *xlate,
+ int n_matches);
+
+/**
+ *
+ */
+int converter_add(struct device *dev, const struct converter_ops *ops);
+
+/**
+ * converter_del - Remove the converter device
+ * @dev: device to remove from the aggregate
+ *
+ * Removes the converter from the aggregate device. This tears down the frontend
+ * and all the converters.
+ *
+ * Ideally, this should be called from the backend driver .remove() callback.
+ * This means that all the converters (and the frontend) will be tear down before
+ * running any specific devres cleanup (at the driver core level). What this all
+ * means is that we can use devm_ apis in @backend_init() and being sure those
+ * resources will be released after the backend resources and before any devm_*
+ * used in @probe(). If that is not the case, one should likely not use any
+ * devm_ API in @backend_init(). That means .backend_close() should be
+ * provided to do all the necessary cleanups.
+ */
+void converter_del(struct device *dev);
+
+/**
+ * converter_enable - Enable the device
+ * @conv: Converter device.
+ *
+ * Enables the backend device.
+ *
+ * RETURNS:
+ * 0 on success, negative error number on failure.
+ */
+int converter_enable(struct converter_backend *conv);
+
+/**
+ * converter_disable - Disable the device
+ * @conv: Converter device.
+ *
+ * Disables the backend device.
+ */
+void converter_disable(struct converter_backend *conv);
+
+/**
+ * converter_test_pattern_set - Set a test pattern
+ * @conv: Converter device.
+ * @chan: Channel number.
+ * @pattern: Pattern to set.
+ *
+ * Set's a test pattern to be transmitted/received by the backend. Typically
+ * useful for debug or interface calibration purposes. A backend driver can
+ * call the @converter_test_pattern_xlate() helper to validate the pattern
+ * (given an array of @struct converter_test_pattern_xlate).
+ *
+ * Note that some patterns might be frontend specific. I.e, as far as the
+ * backend is concerned the pattern is valid (from a register point of view) but
+ * the actual support for the pattern is not implemented in the device for this
+ * specific frontend. It's up to the frontend to ask for a proper pattern
+ * (as it should know better).
+ *
+ * RETURNS:
+ * 0 on success, negative error number on failure.
+ */
+int converter_test_pattern_set(struct converter_backend *conv,
+ unsigned int chan,
+ enum converter_test_pattern pattern);
+
+int converter_chan_status_get(struct converter_backend *conv,
+ unsigned int chan,
+ struct converter_chan_status *status);
+
+/**
+ * converter_data_format_set - Configure the data format
+ * @conv: Converter device.
+ * @chan: Channel number.
+ * @data: Data format.
+ *
+ * Properly configure a channel with respect to the expected data format. A
+ * @struct converter_data_fmt must be passed with the settings.
+ *
+ * RETURNS:
+ * 0 on success, negative error number on failure.
+ */
+int converter_data_format_set(struct converter_backend *conv,
+ unsigned int chan,
+ const struct converter_data_fmt *data);
+
+int converter_sample_edge_select(struct converter_backend *conv,
+ enum converter_edge edge);
+
+static inline int
+converter_sample_on_falling_edge(struct converter_backend *conv)
+{
+ return converter_sample_edge_select(conv, CONVERTER_RISING_EDGE_SAMPLE);
+}
+
+static inline int
+converter_sample_on_rising_edge(struct converter_backend *conv)
+{
+ return converter_sample_edge_select(conv, CONVERTER_FALLING_EDGE_SAMPLE);
+}
+
+/**
+ * converter_chan_enable - Enable a backend channel
+ * @conv: Converter device.
+ * @chan: Channel number.
+ *
+ * Enables a channel on the backend device.
+ *
+ * RETURNS:
+ * 0 on success, negative error number on failure.
+ */
+int converter_chan_enable(struct converter_backend *conv, unsigned int chan);
+
+/**
+ * converter_chan_disable - Disable a backend channel
+ * @conv: Converter device.
+ * @chan: Channel number.
+ *
+ * Disables a channel on the backend device.
+ *
+ * RETURNS:
+ * 0 on success, negative error number on failure.
+ */
+int converter_chan_disable(struct converter_backend *conv, unsigned int chan);
+
+/**
+ * converter_iodelay_set - Set's the backend data interface IO delay
+ * @conv: Converter device.
+ * @num_lanes: Number of lanes in the data interface.
+ * @delay: Delay to set.
+ *
+ * Controls the IO delay for all the lanes at the data interface (where data is
+ * actually transferred between frontend and backend) level.
+ *
+ * RETURNS:
+ * 0 on success, negative error number on failure.
+ */
+int converter_iodelay_set(struct converter_backend *conv,
+ unsigned int num_lanes, unsigned int delay);
+
+/**
+ * converter_frontend_del - Remove the frontend device
+ * @dev: Device to remove from the aggregate
+ *
+ * Removes the frontend from the aggregate device. This tears down the frontend
+ * and all the converters.
+ *
+ * Ideally, this should be called from the frontend driver .remove() callback.
+ * This means that all the converters (and the frontend) will be tear down
+ * before running any specific devres cleanup (at the driver core level). What
+ * this all means is that we can use devm_ apis in .frontend_init() and being
+ * sure those resources will be released after the backend resources and before
+ * any devm_* used in .probe(). If that is not the case, one should likely not
+ * use any devm_ API in .frontend_init(). That means .frontend_close() should be
+ * provided to do all the necessary cleanups.
+ */
+void converter_frontend_del(struct device *dev);
+
+/**
+ * converter_frontend_add - Allocate and add a frontend device
+ * @dev: Device to allocate frontend for.
+ * @ops: Frontend callbacks.
+ *
+ * This allocates the frontend device and looks for all converters needed
+ * so that, when they are available, all of the devices in the aggregate can be
+ * initialized.
+ *
+ * RETURNS:
+ * 0 on success, negative error number on failure.
+ */
+int converter_frontend_add(struct device *dev, const struct frontend_ops *ops);
+
+/**
+ * converter_get - Get a converter object
+ * @frontend: Frontend device.
+ * @name: Converter name.
+ *
+ * Get's a pointer to a converter device. If name is NULL, then it is assumed
+ * that only one backend device is bond with the frontend and the first element
+ * in the list is retrieved. Should only be called from the .frontend_init()
+ * callback.
+ *
+ * RETURNS:
+ * A converter pointer, negative error pointer otherwise.
+ */
+struct converter_backend *__must_check
+converter_get(const struct converter_frontend *frontend, const char *name);
+
+/**
+ * converter_add_direct_reg_access - Add debugfs direct register access
+ * @conv: Coverter device
+ * @indio_dev: IIO device
+ *
+ * This is analogous to the typical IIO direct register access in debugfs. The
+ * extra converter file will be added in the same debugs dir as @indio_dev.
+ * Moreover, if @conv->name is NULL, the file will be called
+ * converter_direct_reg_access. Otherwise, will be
+ * @conv->name_converter_direct_reg_access.
+ */
+void converter_add_direct_reg_access(struct converter_backend *conv,
+ struct iio_dev *indio_dev);
+
+#else
+
+static inline void *converter_get_drvdata(const struct converter_backend *conv)
+{
+ WARN_ONCE(1, "converter API is disabled");
+ return NULL;
+}
+
+static inline void converter_set_drvdata(struct converter_backend *conv,
+ void *drvdata)
+{
+ WARN_ONCE(1, "converter API is disabled");
+}
+
+static inline void converter_set_regmap(struct converter_backend *conv,
+ struct regmap *regmap)
+{
+ WARN_ONCE(1, "converter API is disabled");
+}
+
+static inline int
+__converter_test_pattern_xlate(unsigned int pattern,
+ const struct converter_test_pattern_xlate *xlate,
+ int n_matches)
+{
+ WARN_ONCE(1, "converter API is disabled");
+ return -ENOTSUPP;
+}
+
+static inline struct converter_backend *__must_check
+converter_get(const struct converter_frontend *frontend, const char *name)
+{
+ WARN_ONCE(1, "converter API is disabled");
+ return ERR_PTR(-ENOTSUPP);
+}
+
+static inline int converter_add(struct device *dev,
+ const struct converter_ops *ops)
+{
+ WARN_ONCE(1, "converter API is disabled");
+ return -ENOTSUPP;
+}
+
+static inline void converter_del(struct device *dev)
+{
+ WARN_ONCE(1, "converter API is disabled");
+}
+
+static inline int converter_enable(struct converter_backend *conv)
+{
+ WARN_ONCE(1, "converter API is disabled");
+ return -ENOTSUPP;
+}
+
+static inline void converter_disable(struct converter_backend *conv)
+{
+ WARN_ONCE(1, "converter API is disabled");
+}
+
+static inline int
+converter_test_pattern_set(struct converter_backend *conv,
+ unsigned int chan,
+ enum converter_test_pattern pattern)
+{
+ WARN_ONCE(1, "converter API is disabled");
+ return -ENOTSUPP;
+}
+
+static inline int
+converter_data_format_set(struct converter_backend *conv,
+ unsigned int chan,
+ const struct converter_data_fmt *data)
+{
+ WARN_ONCE(1, "converter API is disabled");
+ return -ENOTSUPP;
+}
+
+static inline int converter_chan_enable(struct converter_backend *conv,
+ unsigned int chan)
+{
+ WARN_ONCE(1, "converter API is disabled");
+ return -ENOTSUPP;
+}
+
+static inline int converter_chan_disable(struct converter_backend *conv,
+ unsigned int chan)
+{
+ WARN_ONCE(1, "converter API is disabled");
+ return -ENOTSUPP;
+}
+
+static inline int converter_iodelay_set(struct converter_backend *conv,
+ unsigned int num_lanes,
+ unsigned int val)
+{
+ WARN_ONCE(1, "converter API is disabled");
+ return -ENOTSUPP;
+}
+
+static inline void
+converter_add_direct_reg_access(struct converter_backend *conv,
+ struct iio_dev *indio_dev)
+{
+ WARN_ONCE(1, "converter API is disabled");
+}
+
+static inline int converter_frontend_add(struct device *dev,
+ const struct frontend_ops *ops)
+{
+ WARN_ONCE(1, "converter API is disabled");
+ return -ENOTSUPP;
+}
+
+static inline void converter_frontend_del(struct device *dev)
+{
+ WARN_ONCE(1, "converter API is disabled");
+}
+
+#endif
+#endif
--
2.41.0
