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
 17struct device;
 18struct fwnode_handle;
 19struct i2c_atr;
 20
 21/**
 22 * enum i2c_atr_flags - Flags for an I2C ATR driver
 23 *
 24 * @I2C_ATR_F_STATIC: ATR does not support dynamic mapping, use static mapping.
 25 *                    Mappings will only be added or removed as a result of
 26 *                    devices being added or removed from a child bus.
 27 *                    The ATR pool will have to be big enough to accomodate all
 28 *                    devices expected to be added to the child buses.
 29 * @I2C_ATR_F_PASSTHROUGH: Allow unmapped incoming addresses to pass through
 30 */
 31enum i2c_atr_flags {
 32	I2C_ATR_F_STATIC = BIT(0),
 33	I2C_ATR_F_PASSTHROUGH = BIT(1),
 34};
 35
 36/**
 37 * struct i2c_atr_ops - Callbacks from ATR to the device driver.
 38 * @attach_addr: Notify the driver of a new device connected on a child
 39 *               bus, with the alias assigned to it. The driver must
 40 *               configure the hardware to use the alias.
 41 * @detach_addr: Notify the driver of a device getting disconnected. The
 42 *               driver must configure the hardware to stop using the
 43 *               alias.
 44 *
 45 * All these functions return 0 on success, a negative error code otherwise.
 46 */
 47struct i2c_atr_ops {
 48	int (*attach_addr)(struct i2c_atr *atr, u32 chan_id,
 49			   u16 addr, u16 alias);
 50	void (*detach_addr)(struct i2c_atr *atr, u32 chan_id,
 51			    u16 addr);
 52};
 53
 54/**
 55 * struct i2c_atr_adap_desc - An ATR downstream bus descriptor
 56 * @chan_id:        Index of the new adapter (0 .. max_adapters-1).  This value is
 57 *                  passed to the callbacks in `struct i2c_atr_ops`.
 58 * @parent:         The device used as the parent of the new i2c adapter, or NULL
 59 *                  to use the i2c-atr device as the parent.
 60 * @bus_handle:     The fwnode handle that points to the adapter's i2c
 61 *                  peripherals, or NULL.
 62 * @num_aliases:    The number of aliases in this adapter's private alias pool. Set
 63 *                  to zero if this adapter uses the ATR's global alias pool.
 64 * @aliases:        An optional array of private aliases used by the adapter
 65 *                  instead of the ATR's global pool of aliases. Must contain
 66 *                  exactly num_aliases entries if num_aliases > 0, is ignored
 67 *                  otherwise.
 68 */
 69struct i2c_atr_adap_desc {
 70	u32 chan_id;
 71	struct device *parent;
 72	struct fwnode_handle *bus_handle;
 73	size_t num_aliases;
 74	u16 *aliases;
 75};
 76
 77/**
 78 * i2c_atr_new() - Allocate and initialize an I2C ATR helper.
 79 * @parent:       The parent (upstream) adapter
 80 * @dev:          The device acting as an ATR
 81 * @ops:          Driver-specific callbacks
 82 * @max_adapters: Maximum number of child adapters
 83 * @flags:        Flags for ATR
 84 *
 85 * The new ATR helper is connected to the parent adapter but has no child
 86 * adapters. Call i2c_atr_add_adapter() to add some.
 87 *
 88 * Call i2c_atr_delete() to remove.
 89 *
 90 * Return: pointer to the new ATR helper object, or ERR_PTR
 91 */
 92struct i2c_atr *i2c_atr_new(struct i2c_adapter *parent, struct device *dev,
 93			    const struct i2c_atr_ops *ops, int max_adapters,
 94			    u32 flags);
 95
 96/**
 97 * i2c_atr_delete - Delete an I2C ATR helper.
 98 * @atr: I2C ATR helper to be deleted.
 99 *
100 * Precondition: all the adapters added with i2c_atr_add_adapter() must be
101 * removed by calling i2c_atr_del_adapter().
102 */
103void i2c_atr_delete(struct i2c_atr *atr);
104
105/**
106 * i2c_atr_add_adapter - Create a child ("downstream") I2C bus.
107 * @atr:        The I2C ATR
108 * @desc:       An ATR adapter descriptor
109 *
110 * After calling this function a new i2c bus will appear. Adding and removing
111 * devices on the downstream bus will result in calls to the
112 * &i2c_atr_ops->attach_client and &i2c_atr_ops->detach_client callbacks for the
113 * driver to assign an alias to the device.
114 *
115 * The adapter's fwnode is set to @bus_handle, or if @bus_handle is NULL the
116 * function looks for a child node whose 'reg' property matches the chan_id
117 * under the i2c-atr device's 'i2c-atr' node.
118 *
119 * Call i2c_atr_del_adapter() to remove the adapter.
120 *
121 * Return: 0 on success, a negative error code otherwise.
122 */
123int i2c_atr_add_adapter(struct i2c_atr *atr, struct i2c_atr_adap_desc *desc);
124
125/**
126 * i2c_atr_del_adapter - Remove a child ("downstream") I2C bus added by
127 *                       i2c_atr_add_adapter(). If no I2C bus has been added
128 *                       this function is a no-op.
129 * @atr:     The I2C ATR
130 * @chan_id: Index of the adapter to be removed (0 .. max_adapters-1)
131 */
132void i2c_atr_del_adapter(struct i2c_atr *atr, u32 chan_id);
133
134/**
135 * i2c_atr_set_driver_data - Set private driver data to the i2c-atr instance.
136 * @atr:  The I2C ATR
137 * @data: Pointer to the data to store
138 */
139void i2c_atr_set_driver_data(struct i2c_atr *atr, void *data);
140
141/**
142 * i2c_atr_get_driver_data - Get the stored drive data.
143 * @atr:     The I2C ATR
144 *
145 * Return: Pointer to the stored data
146 */
147void *i2c_atr_get_driver_data(struct i2c_atr *atr);
148
149#endif /* _LINUX_I2C_ATR_H */