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