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