linux/i3c/device.h

0001 /* SPDX-License-Identifier: GPL-2.0 */
0002 /*
0003  * Copyright (C) 2018 Cadence Design Systems Inc.
0004  *
0005  * Author: Boris Brezillon <boris.brezillon@bootlin.com>
0006  */
0007
0008 #ifndef I3C_DEV_H
0009 #define I3C_DEV_H
0010
0011 #include <linux/bitops.h>
0012 #include <linux/device.h>
0013 #include <linux/i2c.h>
0014 #include <linux/kconfig.h>
0015 #include <linux/mod_devicetable.h>
0016 #include <linux/module.h>
0017
0018 /**
0019  * enum i3c_error_code - I3C error codes
0020  *
0021  * These are the standard error codes as defined by the I3C specification.
0022  * When -EIO is returned by the i3c_device_do_priv_xfers() or
0023  * i3c_device_send_hdr_cmds() one can check the error code in
0024  * &struct_i3c_priv_xfer.err or &struct i3c_hdr_cmd.err to get a better idea of
0025  * what went wrong.
0026  *
0027  * @I3C_ERROR_UNKNOWN: unknown error, usually means the error is not I3C
0028  *             related
0029  * @I3C_ERROR_M0: M0 error
0030  * @I3C_ERROR_M1: M1 error
0031  * @I3C_ERROR_M2: M2 error
0032  */
0033 enum i3c_error_code {
0034     I3C_ERROR_UNKNOWN = 0,
0035     I3C_ERROR_M0 = 1,
0036     I3C_ERROR_M1,
0037     I3C_ERROR_M2,
0038 };
0039
0040 /**
0041  * enum i3c_hdr_mode - HDR mode ids
0042  * @I3C_HDR_DDR: DDR mode
0043  * @I3C_HDR_TSP: TSP mode
0044  * @I3C_HDR_TSL: TSL mode
0045  */
0046 enum i3c_hdr_mode {
0047     I3C_HDR_DDR,
0048     I3C_HDR_TSP,
0049     I3C_HDR_TSL,
0050 };
0051
0052 /**
0053  * struct i3c_priv_xfer - I3C SDR private transfer
0054  * @rnw: encodes the transfer direction. true for a read, false for a write
0055  * @len: transfer length in bytes of the transfer
0056  * @data: input/output buffer
0057  * @data.in: input buffer. Must point to a DMA-able buffer
0058  * @data.out: output buffer. Must point to a DMA-able buffer
0059  * @err: I3C error code
0060  */
0061 struct i3c_priv_xfer {
0062     u8 rnw;
0063     u16 len;
0064     union {
0065         void *in;
0066         const void *out;
0067     } data;
0068     enum i3c_error_code err;
0069 };
0070
0071 /**
0072  * enum i3c_dcr - I3C DCR values
0073  * @I3C_DCR_GENERIC_DEVICE: generic I3C device
0074  */
0075 enum i3c_dcr {
0076     I3C_DCR_GENERIC_DEVICE = 0,
0077 };
0078
0079 #define I3C_PID_MANUF_ID(pid)       (((pid) & GENMASK_ULL(47, 33)) >> 33)
0080 #define I3C_PID_RND_LOWER_32BITS(pid)   (!!((pid) & BIT_ULL(32)))
0081 #define I3C_PID_RND_VAL(pid)        ((pid) & GENMASK_ULL(31, 0))
0082 #define I3C_PID_PART_ID(pid)        (((pid) & GENMASK_ULL(31, 16)) >> 16)
0083 #define I3C_PID_INSTANCE_ID(pid)    (((pid) & GENMASK_ULL(15, 12)) >> 12)
0084 #define I3C_PID_EXTRA_INFO(pid)     ((pid) & GENMASK_ULL(11, 0))
0085
0086 #define I3C_BCR_DEVICE_ROLE(bcr)    ((bcr) & GENMASK(7, 6))
0087 #define I3C_BCR_I3C_SLAVE       (0 << 6)
0088 #define I3C_BCR_I3C_MASTER      (1 << 6)
0089 #define I3C_BCR_HDR_CAP         BIT(5)
0090 #define I3C_BCR_BRIDGE          BIT(4)
0091 #define I3C_BCR_OFFLINE_CAP     BIT(3)
0092 #define I3C_BCR_IBI_PAYLOAD     BIT(2)
0093 #define I3C_BCR_IBI_REQ_CAP     BIT(1)
0094 #define I3C_BCR_MAX_DATA_SPEED_LIM  BIT(0)
0095
0096 /**
0097  * struct i3c_device_info - I3C device information
0098  * @pid: Provisional ID
0099  * @bcr: Bus Characteristic Register
0100  * @dcr: Device Characteristic Register
0101  * @static_addr: static/I2C address
0102  * @dyn_addr: dynamic address
0103  * @hdr_cap: supported HDR modes
0104  * @max_read_ds: max read speed information
0105  * @max_write_ds: max write speed information
0106  * @max_ibi_len: max IBI payload length
0107  * @max_read_turnaround: max read turn-around time in micro-seconds
0108  * @max_read_len: max private SDR read length in bytes
0109  * @max_write_len: max private SDR write length in bytes
0110  *
0111  * These are all basic information that should be advertised by an I3C device.
0112  * Some of them are optional depending on the device type and device
0113  * capabilities.
0114  * For each I3C slave attached to a master with
0115  * i3c_master_add_i3c_dev_locked(), the core will send the relevant CCC command
0116  * to retrieve these data.
0117  */
0118 struct i3c_device_info {
0119     u64 pid;
0120     u8 bcr;
0121     u8 dcr;
0122     u8 static_addr;
0123     u8 dyn_addr;
0124     u8 hdr_cap;
0125     u8 max_read_ds;
0126     u8 max_write_ds;
0127     u8 max_ibi_len;
0128     u32 max_read_turnaround;
0129     u16 max_read_len;
0130     u16 max_write_len;
0131 };
0132
0133 /*
0134  * I3C device internals are kept hidden from I3C device users. It's just
0135  * simpler to refactor things when everything goes through getter/setters, and
0136  * I3C device drivers should not have to worry about internal representation
0137  * anyway.
0138  */
0139 struct i3c_device;
0140
0141 /* These macros should be used to i3c_device_id entries. */
0142 #define I3C_MATCH_MANUF_AND_PART (I3C_MATCH_MANUF | I3C_MATCH_PART)
0143
0144 #define I3C_DEVICE(_manufid, _partid, _drvdata)             \
0145     {                               \
0146         .match_flags = I3C_MATCH_MANUF_AND_PART,        \
0147         .manuf_id = _manufid,                   \
0148         .part_id = _partid,                 \
0149         .data = _drvdata,                   \
0150     }
0151
0152 #define I3C_DEVICE_EXTRA_INFO(_manufid, _partid, _info, _drvdata)   \
0153     {                               \
0154         .match_flags = I3C_MATCH_MANUF_AND_PART |       \
0155                    I3C_MATCH_EXTRA_INFO,            \
0156         .manuf_id = _manufid,                   \
0157         .part_id = _partid,                 \
0158         .extra_info = _info,                    \
0159         .data = _drvdata,                   \
0160     }
0161
0162 #define I3C_CLASS(_dcr, _drvdata)                   \
0163     {                               \
0164         .match_flags = I3C_MATCH_DCR,               \
0165         .dcr = _dcr,                        \
0166     }
0167
0168 /**
0169  * struct i3c_driver - I3C device driver
0170  * @driver: inherit from device_driver
0171  * @probe: I3C device probe method
0172  * @remove: I3C device remove method
0173  * @id_table: I3C device match table. Will be used by the framework to decide
0174  *        which device to bind to this driver
0175  */
0176 struct i3c_driver {
0177     struct device_driver driver;
0178     int (*probe)(struct i3c_device *dev);
0179     void (*remove)(struct i3c_device *dev);
0180     const struct i3c_device_id *id_table;
0181 };
0182
0183 static inline struct i3c_driver *drv_to_i3cdrv(struct device_driver *drv)
0184 {
0185     return container_of(drv, struct i3c_driver, driver);
0186 }
0187
0188 struct device *i3cdev_to_dev(struct i3c_device *i3cdev);
0189 struct i3c_device *dev_to_i3cdev(struct device *dev);
0190
0191 const struct i3c_device_id *
0192 i3c_device_match_id(struct i3c_device *i3cdev,
0193             const struct i3c_device_id *id_table);
0194
0195 static inline void i3cdev_set_drvdata(struct i3c_device *i3cdev,
0196                       void *data)
0197 {
0198     struct device *dev = i3cdev_to_dev(i3cdev);
0199
0200     dev_set_drvdata(dev, data);
0201 }
0202
0203 static inline void *i3cdev_get_drvdata(struct i3c_device *i3cdev)
0204 {
0205     struct device *dev = i3cdev_to_dev(i3cdev);
0206
0207     return dev_get_drvdata(dev);
0208 }
0209
0210 int i3c_driver_register_with_owner(struct i3c_driver *drv,
0211                    struct module *owner);
0212 void i3c_driver_unregister(struct i3c_driver *drv);
0213
0214 #define i3c_driver_register(__drv)      \
0215     i3c_driver_register_with_owner(__drv, THIS_MODULE)
0216
0217 /**
0218  * module_i3c_driver() - Register a module providing an I3C driver
0219  * @__drv: the I3C driver to register
0220  *
0221  * Provide generic init/exit functions that simply register/unregister an I3C
0222  * driver.
0223  * Should be used by any driver that does not require extra init/cleanup steps.
0224  */
0225 #define module_i3c_driver(__drv)        \
0226     module_driver(__drv, i3c_driver_register, i3c_driver_unregister)
0227
0228 /**
0229  * i3c_i2c_driver_register() - Register an i2c and an i3c driver
0230  * @i3cdrv: the I3C driver to register
0231  * @i2cdrv: the I2C driver to register
0232  *
0233  * This function registers both @i2cdev and @i3cdev, and fails if one of these
0234  * registrations fails. This is mainly useful for devices that support both I2C
0235  * and I3C modes.
0236  * Note that when CONFIG_I3C is not enabled, this function only registers the
0237  * I2C driver.
0238  *
0239  * Return: 0 if both registrations succeeds, a negative error code otherwise.
0240  */
0241 static inline int i3c_i2c_driver_register(struct i3c_driver *i3cdrv,
0242                       struct i2c_driver *i2cdrv)
0243 {
0244     int ret;
0245
0246     ret = i2c_add_driver(i2cdrv);
0247     if (ret || !IS_ENABLED(CONFIG_I3C))
0248         return ret;
0249
0250     ret = i3c_driver_register(i3cdrv);
0251     if (ret)
0252         i2c_del_driver(i2cdrv);
0253
0254     return ret;
0255 }
0256
0257 /**
0258  * i3c_i2c_driver_unregister() - Unregister an i2c and an i3c driver
0259  * @i3cdrv: the I3C driver to register
0260  * @i2cdrv: the I2C driver to register
0261  *
0262  * This function unregisters both @i3cdrv and @i2cdrv.
0263  * Note that when CONFIG_I3C is not enabled, this function only unregisters the
0264  * @i2cdrv.
0265  */
0266 static inline void i3c_i2c_driver_unregister(struct i3c_driver *i3cdrv,
0267                          struct i2c_driver *i2cdrv)
0268 {
0269     if (IS_ENABLED(CONFIG_I3C))
0270         i3c_driver_unregister(i3cdrv);
0271
0272     i2c_del_driver(i2cdrv);
0273 }
0274
0275 /**
0276  * module_i3c_i2c_driver() - Register a module providing an I3C and an I2C
0277  *               driver
0278  * @__i3cdrv: the I3C driver to register
0279  * @__i2cdrv: the I3C driver to register
0280  *
0281  * Provide generic init/exit functions that simply register/unregister an I3C
0282  * and an I2C driver.
0283  * This macro can be used even if CONFIG_I3C is disabled, in this case, only
0284  * the I2C driver will be registered.
0285  * Should be used by any driver that does not require extra init/cleanup steps.
0286  */
0287 #define module_i3c_i2c_driver(__i3cdrv, __i2cdrv)   \
0288     module_driver(__i3cdrv,             \
0289               i3c_i2c_driver_register,      \
0290               i3c_i2c_driver_unregister)
0291
0292 int i3c_device_do_priv_xfers(struct i3c_device *dev,
0293                  struct i3c_priv_xfer *xfers,
0294                  int nxfers);
0295
0296 void i3c_device_get_info(struct i3c_device *dev, struct i3c_device_info *info);
0297
0298 struct i3c_ibi_payload {
0299     unsigned int len;
0300     const void *data;
0301 };
0302
0303 /**
0304  * struct i3c_ibi_setup - IBI setup object
0305  * @max_payload_len: maximum length of the payload associated to an IBI. If one
0306  *           IBI appears to have a payload that is bigger than this
0307  *           number, the IBI will be rejected.
0308  * @num_slots: number of pre-allocated IBI slots. This should be chosen so that
0309  *         the system never runs out of IBI slots, otherwise you'll lose
0310  *         IBIs.
0311  * @handler: IBI handler, every time an IBI is received. This handler is called
0312  *       in a workqueue context. It is allowed to sleep and send new
0313  *       messages on the bus, though it's recommended to keep the
0314  *       processing done there as fast as possible to avoid delaying
0315  *       processing of other queued on the same workqueue.
0316  *
0317  * Temporary structure used to pass information to i3c_device_request_ibi().
0318  * This object can be allocated on the stack since i3c_device_request_ibi()
0319  * copies every bit of information and do not use it after
0320  * i3c_device_request_ibi() has returned.
0321  */
0322 struct i3c_ibi_setup {
0323     unsigned int max_payload_len;
0324     unsigned int num_slots;
0325     void (*handler)(struct i3c_device *dev,
0326             const struct i3c_ibi_payload *payload);
0327 };
0328
0329 int i3c_device_request_ibi(struct i3c_device *dev,
0330                const struct i3c_ibi_setup *setup);
0331 void i3c_device_free_ibi(struct i3c_device *dev);
0332 int i3c_device_enable_ibi(struct i3c_device *dev);
0333 int i3c_device_disable_ibi(struct i3c_device *dev);
0334
0335 #endif /* I3C_DEV_H */