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 int (*remove)(struct i3c_device *dev);
180 const struct i3c_device_id *id_table;
181 };
182
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
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
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 */
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 */
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 */