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 <dm/device.h>
12 #include <i2c.h>
13 #include <linux/bitops.h>
14 #include <linux/compat.h>
15
16 /**
17 * enum i3c_error_code - I3C error codes
18 *
19 * These are the standard error codes as defined by the I3C specification.
20 * When -EIO is returned by the i3c_device_do_priv_xfers() or
21 * i3c_device_send_hdr_cmds() one can check the error code in
22 * &struct_i3c_priv_xfer.err or &struct i3c_hdr_cmd.err to get a better idea of
23 * what went wrong.
24 *
25 * @I3C_ERROR_UNKNOWN: unknown error, usually means the error is not I3C
26 * related
27 * @I3C_ERROR_M0: M0 error
28 * @I3C_ERROR_M1: M1 error
29 * @I3C_ERROR_M2: M2 error
30 */
31 enum i3c_error_code {
32 I3C_ERROR_UNKNOWN = 0,
33 I3C_ERROR_M0 = 1,
34 I3C_ERROR_M1,
35 I3C_ERROR_M2,
36 };
37
38 /**
39 * enum i3c_hdr_mode - HDR mode ids
40 * @I3C_HDR_DDR: DDR mode
41 * @I3C_HDR_TSP: TSP mode
42 * @I3C_HDR_TSL: TSL mode
43 */
44 enum i3c_hdr_mode {
45 I3C_HDR_DDR,
46 I3C_HDR_TSP,
47 I3C_HDR_TSL,
48 };
49
50 /**
51 * struct i3c_priv_xfer - I3C SDR private transfer
52 * @rnw: encodes the transfer direction. true for a read, false for a write
53 * @len: transfer length in bytes of the transfer
54 * @data: input/output buffer
55 * @data.in: input buffer. Must point to a DMA-able buffer
56 * @data.out: output buffer. Must point to a DMA-able buffer
57 * @err: I3C error code
58 */
59 struct i3c_priv_xfer {
60 u8 rnw;
61 u16 len;
62 union {
63 void *in;
64 const void *out;
65 } data;
66 enum i3c_error_code err;
67 };
68
69 /**
70 * enum i3c_dcr - I3C DCR values
71 * @I3C_DCR_GENERIC_DEVICE: generic I3C device
72 */
73 enum i3c_dcr {
74 I3C_DCR_GENERIC_DEVICE = 0,
75 };
76
77 #define I3C_PID_MANUF_ID(pid) (((pid) & GENMASK_ULL(47, 33)) >> 33)
78 #define I3C_PID_RND_LOWER_32BITS(pid) (!!((pid) & BIT_ULL(32)))
79 #define I3C_PID_RND_VAL(pid) ((pid) & GENMASK_ULL(31, 0))
80 #define I3C_PID_PART_ID(pid) (((pid) & GENMASK_ULL(31, 16)) >> 16)
81 #define I3C_PID_INSTANCE_ID(pid) (((pid) & GENMASK_ULL(15, 12)) >> 12)
82 #define I3C_PID_EXTRA_INFO(pid) ((pid) & GENMASK_ULL(11, 0))
83
84 #define I3C_BCR_DEVICE_ROLE(bcr) ((bcr) & GENMASK(7, 6))
85 #define I3C_BCR_I3C_SLAVE (0 << 6)
86 #define I3C_BCR_I3C_MASTER BIT(6)
87 #define I3C_BCR_HDR_CAP BIT(5)
88 #define I3C_BCR_BRIDGE BIT(4)
89 #define I3C_BCR_OFFLINE_CAP BIT(3)
90 #define I3C_BCR_IBI_PAYLOAD BIT(2)
91 #define I3C_BCR_IBI_REQ_CAP BIT(1)
92 #define I3C_BCR_MAX_DATA_SPEED_LIM BIT(0)
93
94 /* To determine what functionality is present */
95
96 #define I2C_FUNC_I2C 0x00000001
97 #define I2C_FUNC_10BIT_ADDR 0x00000002 /* required for I2C_M_TEN */
98 #define I2C_FUNC_PROTOCOL_MANGLING 0x00000004 /* required for I2C_M_IGNORE_NAK etc. */
99 #define I2C_FUNC_SMBUS_PEC 0x00000008
100 #define I2C_FUNC_NOSTART 0x00000010 /* required for I2C_M_NOSTART */
101 #define I2C_FUNC_SLAVE 0x00000020
102 #define I2C_FUNC_SMBUS_BLOCK_PROC_CALL 0x00008000 /* SMBus 2.0 or later */
103 #define I2C_FUNC_SMBUS_QUICK 0x00010000
104 #define I2C_FUNC_SMBUS_READ_BYTE 0x00020000
105 #define I2C_FUNC_SMBUS_WRITE_BYTE 0x00040000
106 #define I2C_FUNC_SMBUS_READ_BYTE_DATA 0x00080000
107 #define I2C_FUNC_SMBUS_WRITE_BYTE_DATA 0x00100000
108 #define I2C_FUNC_SMBUS_READ_WORD_DATA 0x00200000
109 #define I2C_FUNC_SMBUS_WRITE_WORD_DATA 0x00400000
110 #define I2C_FUNC_SMBUS_PROC_CALL 0x00800000
111 #define I2C_FUNC_SMBUS_READ_BLOCK_DATA 0x01000000 /* required for I2C_M_RECV_LEN */
112 #define I2C_FUNC_SMBUS_WRITE_BLOCK_DATA 0x02000000
113 #define I2C_FUNC_SMBUS_READ_I2C_BLOCK 0x04000000 /* I2C-like block xfer */
114 #define I2C_FUNC_SMBUS_WRITE_I2C_BLOCK 0x08000000 /* w/ 1-byte reg. addr. */
115 #define I2C_FUNC_SMBUS_HOST_NOTIFY 0x10000000 /* SMBus 2.0 or later */
116
117 #define I2C_FUNC_SMBUS_BYTE (I2C_FUNC_SMBUS_READ_BYTE | \
118 I2C_FUNC_SMBUS_WRITE_BYTE)
119 #define I2C_FUNC_SMBUS_BYTE_DATA (I2C_FUNC_SMBUS_READ_BYTE_DATA | \
120 I2C_FUNC_SMBUS_WRITE_BYTE_DATA)
121 #define I2C_FUNC_SMBUS_WORD_DATA (I2C_FUNC_SMBUS_READ_WORD_DATA | \
122 I2C_FUNC_SMBUS_WRITE_WORD_DATA)
123 #define I2C_FUNC_SMBUS_BLOCK_DATA (I2C_FUNC_SMBUS_READ_BLOCK_DATA | \
124 I2C_FUNC_SMBUS_WRITE_BLOCK_DATA)
125 #define I2C_FUNC_SMBUS_I2C_BLOCK (I2C_FUNC_SMBUS_READ_I2C_BLOCK | \
126 I2C_FUNC_SMBUS_WRITE_I2C_BLOCK)
127
128 #define I2C_FUNC_SMBUS_EMUL (I2C_FUNC_SMBUS_QUICK | \
129 I2C_FUNC_SMBUS_BYTE | \
130 I2C_FUNC_SMBUS_BYTE_DATA | \
131 I2C_FUNC_SMBUS_WORD_DATA | \
132 I2C_FUNC_SMBUS_PROC_CALL | \
133 I2C_FUNC_SMBUS_WRITE_BLOCK_DATA | \
134 I2C_FUNC_SMBUS_I2C_BLOCK | \
135 I2C_FUNC_SMBUS_PEC)
136
137 /**
138 * struct i3c_device_info - I3C device information
139 * @pid: Provisional ID
140 * @bcr: Bus Characteristic Register
141 * @dcr: Device Characteristic Register
142 * @static_addr: static/I2C address
143 * @dyn_addr: dynamic address
144 * @hdr_cap: supported HDR modes
145 * @max_read_ds: max read speed information
146 * @max_write_ds: max write speed information
147 * @max_ibi_len: max IBI payload length
148 * @max_read_turnaround: max read turn-around time in micro-seconds
149 * @max_read_len: max private SDR read length in bytes
150 * @max_write_len: max private SDR write length in bytes
151 *
152 * These are all basic information that should be advertised by an I3C device.
153 * Some of them are optional depending on the device type and device
154 * capabilities.
155 * For each I3C slave attached to a master with
156 * i3c_master_add_i3c_dev_locked(), the core will send the relevant CCC command
157 * to retrieve these data.
158 */
159 struct i3c_device_info {
160 u64 pid;
161 u8 bcr;
162 u8 dcr;
163 u8 static_addr;
164 u8 dyn_addr;
165 u8 hdr_cap;
166 u8 max_read_ds;
167 u8 max_write_ds;
168 u8 max_ibi_len;
169 u32 max_read_turnaround;
170 u16 max_read_len;
171 u16 max_write_len;
172 };
173
174 /*
175 * I3C device internals are kept hidden from I3C device users. It's just
176 * simpler to refactor things when everything goes through getter/setters, and
177 * I3C device drivers should not have to worry about internal representation
178 * anyway.
179 */
180 struct i3c_device;
181
182 /* These macros should be used to i3c_device_id entries. */
183 #define I3C_MATCH_MANUF_AND_PART (I3C_MATCH_MANUF | I3C_MATCH_PART)
184
185 #define I3C_DEVICE(_manufid, _partid, _drvdata) \
186 { \
187 .match_flags = I3C_MATCH_MANUF_AND_PART, \
188 .manuf_id = _manufid, \
189 .part_id = _partid, \
190 .data = _drvdata, \
191 }
192
193 #define I3C_DEVICE_EXTRA_INFO(_manufid, _partid, _info, _drvdata) \
194 { \
195 .match_flags = I3C_MATCH_MANUF_AND_PART | \
196 I3C_MATCH_EXTRA_INFO, \
197 .manuf_id = _manufid, \
198 .part_id = _partid, \
199 .extra_info = _info, \
200 .data = _drvdata, \
201 }
202
203 #define I3C_CLASS(_dcr, _drvdata) \
204 { \
205 .match_flags = I3C_MATCH_DCR, \
206 .dcr = _dcr, \
207 }
208
209 /**
210 * struct i3c_driver - I3C device driver
211 * @driver: inherit from driver
212 * @probe: I3C device probe method
213 * @remove: I3C device remove method
214 * @id_table: I3C device match table. Will be used by the framework to decide
215 * which device to bind to this driver
216 */
217 struct i3c_driver {
218 struct driver driver;
219 int (*probe)(struct i3c_device *dev);
220 void (*remove)(struct i3c_device *dev);
221 const struct i3c_device_id *id_table;
222 };
223
drv_to_i3cdrv(const struct driver * drv)224 static inline struct i3c_driver *drv_to_i3cdrv(const struct driver *drv)
225 {
226 return container_of(drv, struct i3c_driver, driver);
227 }
228
229 struct udevice *i3cdev_to_dev(struct i3c_device *i3cdev);
230 struct i3c_device *dev_to_i3cdev(struct udevice *dev);
231
232 const struct i3c_device_id *
233 i3c_device_match_id(struct i3c_device *i3cdev,
234 const struct i3c_device_id *id_table);
235
236 /**
237 * module_i3c_i2c_driver() - Register a module providing an I3C and an I2C
238 * driver
239 * @__i3cdrv: the I3C driver to register
240 * @__i2cdrv: the I3C driver to register
241 *
242 * Provide generic init/exit functions that simply register/unregister an I3C
243 * and an I2C driver.
244 * This macro can be used even if CONFIG_I3C is disabled, in this case, only
245 * the I2C driver will be registered.
246 * Should be used by any driver that does not require extra init/cleanup steps.
247 */
248 #define module_i3c_i2c_driver(__i3cdrv, __i2cdrv) \
249 module_driver(__i3cdrv, \
250 i3c_i2c_driver_register, \
251 i3c_i2c_driver_unregister)
252
253 void i3c_device_get_info(struct i3c_device *dev, struct i3c_device_info *info);
254
255 struct i3c_ibi_payload {
256 unsigned int len;
257 const void *data;
258 };
259
260 /**
261 * struct i3c_ibi_setup - IBI setup object
262 * @max_payload_len: maximum length of the payload associated to an IBI. If one
263 * IBI appears to have a payload that is bigger than this
264 * number, the IBI will be rejected.
265 * @num_slots: number of pre-allocated IBI slots. This should be chosen so that
266 * the system never runs out of IBI slots, otherwise you'll lose
267 * IBIs.
268 * @handler: IBI handler, every time an IBI is received. This handler is called
269 * in a workqueue context. It is allowed to sleep and send new
270 * messages on the bus, though it's recommended to keep the
271 * processing done there as fast as possible to avoid delaying
272 * processing of other queued on the same workqueue.
273 *
274 * Temporary structure used to pass information to i3c_device_request_ibi().
275 * This object can be allocated on the stack since i3c_device_request_ibi()
276 * copies every bit of information and do not use it after
277 * i3c_device_request_ibi() has returned.
278 */
279 struct i3c_ibi_setup {
280 unsigned int max_payload_len;
281 unsigned int num_slots;
282 void (*handler)(struct i3c_device *dev,
283 const struct i3c_ibi_payload *payload);
284 };
285
286 #endif /* I3C_DEV_H */
287