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