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: 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 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 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(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(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