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 (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: Provisioned 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 (_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 | |
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 | |
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 | |
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 | */ |
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(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 | */ |
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(drv: i3cdrv); |
281 | |
282 | i2c_del_driver(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 | |