1 /* SPDX-License-Identifier: GPL-2.0 */
2 /*
3  * Copyright (C) 2018 Cadence Design Systems Inc.
4  *
5  * Author: Boris Brezillon <boris.brezillon@bootlin.com>
6  */
7 
8 #ifndef I3C_DEV_H
9 #define I3C_DEV_H
10 
11 #include <linux/bitops.h>
12 #include <linux/device.h>
13 #include <linux/i2c.h>
14 #include <linux/kconfig.h>
15 #include <linux/mod_devicetable.h>
16 #include <linux/module.h>
17 
18 /**
19  * enum i3c_error_code - I3C error codes
20  *
21  * These are the standard error codes as defined by the I3C specification.
22  * When -EIO is returned by the i3c_device_do_priv_xfers() or
23  * i3c_device_send_hdr_cmds() one can check the error code in
24  * &struct_i3c_priv_xfer.err or &struct i3c_hdr_cmd.err to get a better idea of
25  * what went wrong.
26  *
27  * @I3C_ERROR_UNKNOWN: unknown error, usually means the error is not I3C
28  *		       related
29  * @I3C_ERROR_M0: M0 error
30  * @I3C_ERROR_M1: M1 error
31  * @I3C_ERROR_M2: M2 error
32  */
33 enum i3c_error_code {
34 	I3C_ERROR_UNKNOWN = 0,
35 	I3C_ERROR_M0 = 1,
36 	I3C_ERROR_M1,
37 	I3C_ERROR_M2,
38 };
39 
40 /**
41  * enum i3c_hdr_mode - HDR mode ids
42  * @I3C_HDR_DDR: DDR mode
43  * @I3C_HDR_TSP: TSP mode
44  * @I3C_HDR_TSL: TSL mode
45  */
46 enum i3c_hdr_mode {
47 	I3C_HDR_DDR,
48 	I3C_HDR_TSP,
49 	I3C_HDR_TSL,
50 };
51 
52 /**
53  * struct i3c_priv_xfer - I3C SDR private transfer
54  * @rnw: encodes the transfer direction. true for a read, false for a write
55  * @len: transfer length in bytes of the transfer
56  * @data: input/output buffer
57  * @data.in: input buffer. Must point to a DMA-able buffer
58  * @data.out: output buffer. Must point to a DMA-able buffer
59  * @err: I3C error code
60  */
61 struct i3c_priv_xfer {
62 	u8 rnw;
63 	u16 len;
64 	union {
65 		void *in;
66 		const void *out;
67 	} data;
68 	enum i3c_error_code err;
69 };
70 
71 /**
72  * enum i3c_dcr - I3C DCR values
73  * @I3C_DCR_GENERIC_DEVICE: generic I3C device
74  */
75 enum i3c_dcr {
76 	I3C_DCR_GENERIC_DEVICE = 0,
77 };
78 
79 #define I3C_PID_MANUF_ID(pid)		(((pid) & GENMASK_ULL(47, 33)) >> 33)
80 #define I3C_PID_RND_LOWER_32BITS(pid)	(!!((pid) & BIT_ULL(32)))
81 #define I3C_PID_RND_VAL(pid)		((pid) & GENMASK_ULL(31, 0))
82 #define I3C_PID_PART_ID(pid)		(((pid) & GENMASK_ULL(31, 16)) >> 16)
83 #define I3C_PID_INSTANCE_ID(pid)	(((pid) & GENMASK_ULL(15, 12)) >> 12)
84 #define I3C_PID_EXTRA_INFO(pid)		((pid) & GENMASK_ULL(11, 0))
85 
86 #define I3C_BCR_DEVICE_ROLE(bcr)	((bcr) & GENMASK(7, 6))
87 #define I3C_BCR_I3C_SLAVE		(0 << 6)
88 #define I3C_BCR_I3C_MASTER		(1 << 6)
89 #define I3C_BCR_HDR_CAP			BIT(5)
90 #define I3C_BCR_BRIDGE			BIT(4)
91 #define I3C_BCR_OFFLINE_CAP		BIT(3)
92 #define I3C_BCR_IBI_PAYLOAD		BIT(2)
93 #define I3C_BCR_IBI_REQ_CAP		BIT(1)
94 #define I3C_BCR_MAX_DATA_SPEED_LIM	BIT(0)
95 
96 /**
97  * struct i3c_device_info - I3C device information
98  * @pid: Provisional ID
99  * @bcr: Bus Characteristic Register
100  * @dcr: Device Characteristic Register
101  * @static_addr: static/I2C address
102  * @dyn_addr: dynamic address
103  * @hdr_cap: supported HDR modes
104  * @max_read_ds: max read speed information
105  * @max_write_ds: max write speed information
106  * @max_ibi_len: max IBI payload length
107  * @max_read_turnaround: max read turn-around time in micro-seconds
108  * @max_read_len: max private SDR read length in bytes
109  * @max_write_len: max private SDR write length in bytes
110  *
111  * These are all basic information that should be advertised by an I3C device.
112  * Some of them are optional depending on the device type and device
113  * capabilities.
114  * For each I3C slave attached to a master with
115  * i3c_master_add_i3c_dev_locked(), the core will send the relevant CCC command
116  * to retrieve these data.
117  */
118 struct i3c_device_info {
119 	u64 pid;
120 	u8 bcr;
121 	u8 dcr;
122 	u8 static_addr;
123 	u8 dyn_addr;
124 	u8 hdr_cap;
125 	u8 max_read_ds;
126 	u8 max_write_ds;
127 	u8 max_ibi_len;
128 	u32 max_read_turnaround;
129 	u16 max_read_len;
130 	u16 max_write_len;
131 };
132 
133 /*
134  * I3C device internals are kept hidden from I3C device users. It's just
135  * simpler to refactor things when everything goes through getter/setters, and
136  * I3C device drivers should not have to worry about internal representation
137  * anyway.
138  */
139 struct i3c_device;
140 
141 /* These macros should be used to i3c_device_id entries. */
142 #define I3C_MATCH_MANUF_AND_PART (I3C_MATCH_MANUF | I3C_MATCH_PART)
143 
144 #define I3C_DEVICE(_manufid, _partid, _drvdata)				\
145 	{								\
146 		.match_flags = I3C_MATCH_MANUF_AND_PART,		\
147 		.manuf_id = _manufid,					\
148 		.part_id = _partid,					\
149 		.data = _drvdata,					\
150 	}
151 
152 #define I3C_DEVICE_EXTRA_INFO(_manufid, _partid, _info, _drvdata)	\
153 	{								\
154 		.match_flags = I3C_MATCH_MANUF_AND_PART |		\
155 			       I3C_MATCH_EXTRA_INFO,			\
156 		.manuf_id = _manufid,					\
157 		.part_id = _partid,					\
158 		.extra_info = _info,					\
159 		.data = _drvdata,					\
160 	}
161 
162 #define I3C_CLASS(_dcr, _drvdata)					\
163 	{								\
164 		.match_flags = I3C_MATCH_DCR,				\
165 		.dcr = _dcr,						\
166 	}
167 
168 /**
169  * struct i3c_driver - I3C device driver
170  * @driver: inherit from device_driver
171  * @probe: I3C device probe method
172  * @remove: I3C device remove method
173  * @id_table: I3C device match table. Will be used by the framework to decide
174  *	      which device to bind to this driver
175  */
176 struct i3c_driver {
177 	struct device_driver driver;
178 	int (*probe)(struct i3c_device *dev);
179 	void (*remove)(struct i3c_device *dev);
180 	const struct i3c_device_id *id_table;
181 };
182 
drv_to_i3cdrv(struct device_driver * drv)183 static inline struct i3c_driver *drv_to_i3cdrv(struct device_driver *drv)
184 {
185 	return container_of(drv, struct i3c_driver, driver);
186 }
187 
188 struct device *i3cdev_to_dev(struct i3c_device *i3cdev);
189 struct i3c_device *dev_to_i3cdev(struct device *dev);
190 
191 const struct i3c_device_id *
192 i3c_device_match_id(struct i3c_device *i3cdev,
193 		    const struct i3c_device_id *id_table);
194 
i3cdev_set_drvdata(struct i3c_device * i3cdev,void * data)195 static inline void i3cdev_set_drvdata(struct i3c_device *i3cdev,
196 				      void *data)
197 {
198 	struct device *dev = i3cdev_to_dev(i3cdev);
199 
200 	dev_set_drvdata(dev, data);
201 }
202 
i3cdev_get_drvdata(struct i3c_device * i3cdev)203 static inline void *i3cdev_get_drvdata(struct i3c_device *i3cdev)
204 {
205 	struct device *dev = i3cdev_to_dev(i3cdev);
206 
207 	return dev_get_drvdata(dev);
208 }
209 
210 int i3c_driver_register_with_owner(struct i3c_driver *drv,
211 				   struct module *owner);
212 void i3c_driver_unregister(struct i3c_driver *drv);
213 
214 #define i3c_driver_register(__drv)		\
215 	i3c_driver_register_with_owner(__drv, THIS_MODULE)
216 
217 /**
218  * module_i3c_driver() - Register a module providing an I3C driver
219  * @__drv: the I3C driver to register
220  *
221  * Provide generic init/exit functions that simply register/unregister an I3C
222  * driver.
223  * Should be used by any driver that does not require extra init/cleanup steps.
224  */
225 #define module_i3c_driver(__drv)		\
226 	module_driver(__drv, i3c_driver_register, i3c_driver_unregister)
227 
228 /**
229  * i3c_i2c_driver_register() - Register an i2c and an i3c driver
230  * @i3cdrv: the I3C driver to register
231  * @i2cdrv: the I2C driver to register
232  *
233  * This function registers both @i2cdev and @i3cdev, and fails if one of these
234  * registrations fails. This is mainly useful for devices that support both I2C
235  * and I3C modes.
236  * Note that when CONFIG_I3C is not enabled, this function only registers the
237  * I2C driver.
238  *
239  * Return: 0 if both registrations succeeds, a negative error code otherwise.
240  */
i3c_i2c_driver_register(struct i3c_driver * i3cdrv,struct i2c_driver * i2cdrv)241 static inline int i3c_i2c_driver_register(struct i3c_driver *i3cdrv,
242 					  struct i2c_driver *i2cdrv)
243 {
244 	int ret;
245 
246 	ret = i2c_add_driver(i2cdrv);
247 	if (ret || !IS_ENABLED(CONFIG_I3C))
248 		return ret;
249 
250 	ret = i3c_driver_register(i3cdrv);
251 	if (ret)
252 		i2c_del_driver(i2cdrv);
253 
254 	return ret;
255 }
256 
257 /**
258  * i3c_i2c_driver_unregister() - Unregister an i2c and an i3c driver
259  * @i3cdrv: the I3C driver to register
260  * @i2cdrv: the I2C driver to register
261  *
262  * This function unregisters both @i3cdrv and @i2cdrv.
263  * Note that when CONFIG_I3C is not enabled, this function only unregisters the
264  * @i2cdrv.
265  */
i3c_i2c_driver_unregister(struct i3c_driver * i3cdrv,struct i2c_driver * i2cdrv)266 static inline void i3c_i2c_driver_unregister(struct i3c_driver *i3cdrv,
267 					     struct i2c_driver *i2cdrv)
268 {
269 	if (IS_ENABLED(CONFIG_I3C))
270 		i3c_driver_unregister(i3cdrv);
271 
272 	i2c_del_driver(i2cdrv);
273 }
274 
275 /**
276  * module_i3c_i2c_driver() - Register a module providing an I3C and an I2C
277  *			     driver
278  * @__i3cdrv: the I3C driver to register
279  * @__i2cdrv: the I3C driver to register
280  *
281  * Provide generic init/exit functions that simply register/unregister an I3C
282  * and an I2C driver.
283  * This macro can be used even if CONFIG_I3C is disabled, in this case, only
284  * the I2C driver will be registered.
285  * Should be used by any driver that does not require extra init/cleanup steps.
286  */
287 #define module_i3c_i2c_driver(__i3cdrv, __i2cdrv)	\
288 	module_driver(__i3cdrv,				\
289 		      i3c_i2c_driver_register,		\
290 		      i3c_i2c_driver_unregister)
291 
292 int i3c_device_do_priv_xfers(struct i3c_device *dev,
293 			     struct i3c_priv_xfer *xfers,
294 			     int nxfers);
295 
296 void i3c_device_get_info(struct i3c_device *dev, struct i3c_device_info *info);
297 
298 struct i3c_ibi_payload {
299 	unsigned int len;
300 	const void *data;
301 };
302 
303 /**
304  * struct i3c_ibi_setup - IBI setup object
305  * @max_payload_len: maximum length of the payload associated to an IBI. If one
306  *		     IBI appears to have a payload that is bigger than this
307  *		     number, the IBI will be rejected.
308  * @num_slots: number of pre-allocated IBI slots. This should be chosen so that
309  *	       the system never runs out of IBI slots, otherwise you'll lose
310  *	       IBIs.
311  * @handler: IBI handler, every time an IBI is received. This handler is called
312  *	     in a workqueue context. It is allowed to sleep and send new
313  *	     messages on the bus, though it's recommended to keep the
314  *	     processing done there as fast as possible to avoid delaying
315  *	     processing of other queued on the same workqueue.
316  *
317  * Temporary structure used to pass information to i3c_device_request_ibi().
318  * This object can be allocated on the stack since i3c_device_request_ibi()
319  * copies every bit of information and do not use it after
320  * i3c_device_request_ibi() has returned.
321  */
322 struct i3c_ibi_setup {
323 	unsigned int max_payload_len;
324 	unsigned int num_slots;
325 	void (*handler)(struct i3c_device *dev,
326 			const struct i3c_ibi_payload *payload);
327 };
328 
329 int i3c_device_request_ibi(struct i3c_device *dev,
330 			   const struct i3c_ibi_setup *setup);
331 void i3c_device_free_ibi(struct i3c_device *dev);
332 int i3c_device_enable_ibi(struct i3c_device *dev);
333 int i3c_device_disable_ibi(struct i3c_device *dev);
334 
335 #endif /* I3C_DEV_H */
336