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 */ 117