include/linux/i2c-atr.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 /*
   3  * I2C Address Translator
   4  *
   5  * Copyright (c) 2019,2022 Luca Ceresoli <luca@lucaceresoli.net>
   6  * Copyright (c) 2022,2023 Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
   7  *
   8  * Based on i2c-mux.h
   9  */
  10
  11 #ifndef _LINUX_I2C_ATR_H
  12 #define _LINUX_I2C_ATR_H
  13
  14 #include <linux/i2c.h>
  15 #include <linux/types.h>
  16
  17 struct device;
  18 struct fwnode_handle;
  19 struct i2c_atr;
  20
  21 /**
  22  * struct i2c_atr_ops - Callbacks from ATR to the device driver.
  23  * @attach_client: Notify the driver of a new device connected on a child
  24  *                 bus, with the alias assigned to it. The driver must
  25  *                 configure the hardware to use the alias.
  26  * @detach_client: Notify the driver of a device getting disconnected. The
  27  *                 driver must configure the hardware to stop using the
  28  *                 alias.
  29  *
  30  * All these functions return 0 on success, a negative error code otherwise.
  31  */
  32 struct i2c_atr_ops {
  33         int (*attach_client)(struct i2c_atr *atr, u32 chan_id,
  34                              const struct i2c_client *client, u16 alias);
  35         void (*detach_client)(struct i2c_atr *atr, u32 chan_id,
  36                               const struct i2c_client *client);
  37 };
  38
  39 /**
  40  * i2c_atr_new() - Allocate and initialize an I2C ATR helper.
  41  * @parent:       The parent (upstream) adapter
  42  * @dev:          The device acting as an ATR
  43  * @ops:          Driver-specific callbacks
  44  * @max_adapters: Maximum number of child adapters
  45  *
  46  * The new ATR helper is connected to the parent adapter but has no child
  47  * adapters. Call i2c_atr_add_adapter() to add some.
  48  *
  49  * Call i2c_atr_delete() to remove.
  50  *
  51  * Return: pointer to the new ATR helper object, or ERR_PTR
  52  */
  53 struct i2c_atr *i2c_atr_new(struct i2c_adapter *parent, struct device *dev,
  54                             const struct i2c_atr_ops *ops, int max_adapters);
  55
  56 /**
  57  * i2c_atr_delete - Delete an I2C ATR helper.
  58  * @atr: I2C ATR helper to be deleted.
  59  *
  60  * Precondition: all the adapters added with i2c_atr_add_adapter() must be
  61  * removed by calling i2c_atr_del_adapter().
  62  */
  63 void i2c_atr_delete(struct i2c_atr *atr);
  64
  65 /**
  66  * i2c_atr_add_adapter - Create a child ("downstream") I2C bus.
  67  * @atr:        The I2C ATR
  68  * @chan_id:    Index of the new adapter (0 .. max_adapters-1).  This value is
  69  *              passed to the callbacks in `struct i2c_atr_ops`.
  70  * @adapter_parent: The device used as the parent of the new i2c adapter, or NULL
  71  *                  to use the i2c-atr device as the parent.
  72  * @bus_handle: The fwnode handle that points to the adapter's i2c
  73  *              peripherals, or NULL.
  74  *
  75  * After calling this function a new i2c bus will appear. Adding and removing
  76  * devices on the downstream bus will result in calls to the
  77  * &i2c_atr_ops->attach_client and &i2c_atr_ops->detach_client callbacks for the
  78  * driver to assign an alias to the device.
  79  *
  80  * The adapter's fwnode is set to @bus_handle, or if @bus_handle is NULL the
  81  * function looks for a child node whose 'reg' property matches the chan_id
  82  * under the i2c-atr device's 'i2c-atr' node.
  83  *
  84  * Call i2c_atr_del_adapter() to remove the adapter.
  85  *
  86  * Return: 0 on success, a negative error code otherwise.
  87  */
  88 int i2c_atr_add_adapter(struct i2c_atr *atr, u32 chan_id,
  89                         struct device *adapter_parent,
  90                         struct fwnode_handle *bus_handle);
  91
  92 /**
  93  * i2c_atr_del_adapter - Remove a child ("downstream") I2C bus added by
  94  *                       i2c_atr_add_adapter(). If no I2C bus has been added
  95  *                       this function is a no-op.
  96  * @atr:     The I2C ATR
  97  * @chan_id: Index of the adapter to be removed (0 .. max_adapters-1)
  98  */
  99 void i2c_atr_del_adapter(struct i2c_atr *atr, u32 chan_id);
 100
 101 /**
 102  * i2c_atr_set_driver_data - Set private driver data to the i2c-atr instance.
 103  * @atr:  The I2C ATR
 104  * @data: Pointer to the data to store
 105  */
 106 void i2c_atr_set_driver_data(struct i2c_atr *atr, void *data);
 107
 108 /**
 109  * i2c_atr_get_driver_data - Get the stored drive data.
 110  * @atr:     The I2C ATR
 111  *
 112  * Return: Pointer to the stored data
 113  */
 114 void *i2c_atr_get_driver_data(struct i2c_atr *atr);
 115
 116 #endif /* _LINUX_I2C_ATR_H */