include/linux/i3c/device.h

   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 */