drivers/iio/industrialio-backend.c

   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
  47 struct 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  */
  59 struct iio_backend_buffer_pair {
  60         struct iio_backend *back;
  61         struct iio_buffer *buffer;
  62 };
  63
  64 static LIST_HEAD(iio_back_list);
  65 static 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  */
 122 int iio_backend_chan_enable(struct iio_backend *back, unsigned int chan)
 123 {
 124         return iio_backend_op_call(back, chan_enable, chan);
 125 }
 126 EXPORT_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  */
 136 int iio_backend_chan_disable(struct iio_backend *back, unsigned int chan)
 137 {
 138         return iio_backend_op_call(back, chan_disable, chan);
 139 }
 140 EXPORT_SYMBOL_NS_GPL(iio_backend_chan_disable, IIO_BACKEND);
 141
 142 static 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  */
 155 int 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 }
 165 EXPORT_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  */
 179 int 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 }
 187 EXPORT_SYMBOL_NS_GPL(iio_backend_data_format_set, IIO_BACKEND);
 188
 189 static 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  */
 211 int 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 }
 232 EXPORT_SYMBOL_NS_GPL(devm_iio_backend_request_buffer, IIO_BACKEND);
 233
 234 static void iio_backend_release(void *arg)
 235 {
 236         struct iio_backend *back = arg;
 237
 238         module_put(back->owner);
 239 }
 240
 241 static 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  */
 281 struct 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 }
 321 EXPORT_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  */
 335 struct 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 }
 356 EXPORT_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  */
 362 void *iio_backend_get_priv(const struct iio_backend *back)
 363 {
 364         return back->priv;
 365 }
 366 EXPORT_SYMBOL_NS_GPL(iio_backend_get_priv, IIO_BACKEND);
 367
 368 static 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  */
 387 int 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 }
 414 EXPORT_SYMBOL_NS_GPL(devm_iio_backend_register, IIO_BACKEND);
 415
 416 MODULE_AUTHOR("Nuno Sa <nuno.sa@analog.com>");
 417 MODULE_DESCRIPTION("Framework to handle complex IIO aggregate devices");
 418 MODULE_LICENSE("GPL");