/* SPDX-License-Identifier: GPL-2.0 */
/*
* Copyright (C) 2018 Cadence Design Systems Inc.
*
* Author: Boris Brezillon <boris.brezillon@bootlin.com>
*/
#ifndef I3C_DEV_H
#define I3C_DEV_H
#include <linux/bitops.h>
#include <linux/device.h>
#include <linux/i2c.h>
#include <linux/kconfig.h>
#include <linux/mod_devicetable.h>
#include <linux/module.h>
/**
* enum i3c_error_code - I3C error codes
*
* These are the standard error codes as defined by the I3C specification.
* When -EIO is returned by the i3c_device_do_priv_xfers() or
* i3c_device_send_hdr_cmds() one can check the error code in
* &struct_i3c_priv_xfer.err or &struct i3c_hdr_cmd.err to get a better idea of
* what went wrong.
*
* @I3C_ERROR_UNKNOWN: unknown error, usually means the error is not I3C
* related
* @I3C_ERROR_M0: M0 error
* @I3C_ERROR_M1: M1 error
* @I3C_ERROR_M2: M2 error
*/
enum i3c_error_code {
I3C_ERROR_UNKNOWN = 0,
I3C_ERROR_M0 = 1,
I3C_ERROR_M1,
I3C_ERROR_M2,
};
/**
* enum i3c_hdr_mode - HDR mode ids
* @I3C_HDR_DDR: DDR mode
* @I3C_HDR_TSP: TSP mode
* @I3C_HDR_TSL: TSL mode
*/
enum i3c_hdr_mode {
I3C_HDR_DDR,
I3C_HDR_TSP,
I3C_HDR_TSL,
};
/**
* struct i3c_priv_xfer - I3C SDR private transfer
* @rnw: encodes the transfer direction. true for a read, false for a write
* @len: transfer length in bytes of the transfer
* @data: input/output buffer
* @data.in: input buffer. Must point to a DMA-able buffer
* @data.out: output buffer. Must point to a DMA-able buffer
* @err: I3C error code
*/
struct i3c_priv_xfer {
u8 rnw;
u16 len;
union {
void *in;
const void *out;
} data;
enum i3c_error_code err;
};
/**
* enum i3c_dcr - I3C DCR values
* @I3C_DCR_GENERIC_DEVICE: generic I3C device
*/
enum i3c_dcr {
I3C_DCR_GENERIC_DEVICE = 0,
};
#define I3C_PID_MANUF_ID(pid) (((pid) & GENMASK_ULL(47, 33)) >> 33)
#define I3C_PID_RND_LOWER_32BITS(pid) (!!((pid) & BIT_ULL(32)))
#define I3C_PID_RND_VAL(pid) ((pid) & GENMASK_ULL(31, 0))
#define I3C_PID_PART_ID(pid) (((pid) & GENMASK_ULL(31, 16)) >> 16)
#define I3C_PID_INSTANCE_ID(pid) (((pid) & GENMASK_ULL(15, 12)) >> 12)
#define I3C_PID_EXTRA_INFO(pid) ((pid) & GENMASK_ULL(11, 0))
#define I3C_BCR_DEVICE_ROLE(bcr) ((bcr) & GENMASK(7, 6))
#define I3C_BCR_I3C_SLAVE (0 << 6)
#define I3C_BCR_I3C_MASTER (1 << 6)
#define I3C_BCR_HDR_CAP BIT(5)
#define I3C_BCR_BRIDGE BIT(4)
#define I3C_BCR_OFFLINE_CAP BIT(3)
#define I3C_BCR_IBI_PAYLOAD BIT(2)
#define I3C_BCR_IBI_REQ_CAP BIT(1)
#define I3C_BCR_MAX_DATA_SPEED_LIM BIT(0)
/**
* struct i3c_device_info - I3C device information
* @pid: Provisional ID
* @bcr: Bus Characteristic Register
* @dcr: Device Characteristic Register
* @static_addr: static/I2C address
* @dyn_addr: dynamic address
* @hdr_cap: supported HDR modes
* @max_read_ds: max read speed information
* @max_write_ds: max write speed information
* @max_ibi_len: max IBI payload length
* @max_read_turnaround: max read turn-around time in micro-seconds
* @max_read_len: max private SDR read length in bytes
* @max_write_len: max private SDR write length in bytes
*
* These are all basic information that should be advertised by an I3C device.
* Some of them are optional depending on the device type and device
* capabilities.
* For each I3C slave attached to a master with
* i3c_master_add_i3c_dev_locked(), the core will send the relevant CCC command
* to retrieve these data.
*/
struct i3c_device_info {
u64 pid;
u8 bcr;
u8 dcr;
u8 static_addr;
u8 dyn_addr;
u8 hdr_cap;
u8 max_read_ds;
u8 max_write_ds;
u8 max_ibi_len;
u32 max_read_turnaround;
u16 max_read_len;
u16 max_write_len;
};
/*
* I3C device internals are kept hidden from I3C device users. It's just
* simpler to refactor things when everything goes through getter/setters, and
* I3C device drivers should not have to worry about internal representation
* anyway.
*/
struct i3c_device;
/* These macros should be used to i3c_device_id entries. */
#define I3C_MATCH_MANUF_AND_PART (I3C_MATCH_MANUF | I3C_MATCH_PART)
#define I3C_DEVICE(_manufid, _partid, _drvdata) \
{ \
.match_flags = I3C_MATCH_MANUF_AND_PART, \
.manuf_id = _manufid, \
.part_id = _partid, \
.data = _drvdata, \
}
#define I3C_DEVICE_EXTRA_INFO(_manufid, _partid, _info, _drvdata) \
{ \
.match_flags = I3C_MATCH_MANUF_AND_PART | \
I3C_MATCH_EXTRA_INFO, \
.manuf_id = _manufid, \
.part_id = _partid, \
.extra_info = _info, \
.data = _drvdata, \
}
#define I3C_CLASS(_dcr, _drvdata) \
{ \
.match_flags = I3C_MATCH_DCR, \
.dcr = _dcr, \
}
/**
* struct i3c_driver - I3C device driver
* @driver: inherit from device_driver
* @probe: I3C device probe method
* @remove: I3C device remove method
* @id_table: I3C device match table. Will be used by the framework to decide
* which device to bind to this driver
*/
struct i3c_driver {
struct device_driver driver;
int (*probe)(struct i3c_device *dev);
int (*remove)(struct i3c_device *dev);
const struct i3c_device_id *id_table;
};
static inline struct i3c_driver *drv_to_i3cdrv(struct device_driver *drv)
{
return container_of(drv, struct i3c_driver, driver);
}
struct device *i3cdev_to_dev(struct i3c_device *i3cdev);
struct i3c_device *dev_to_i3cdev(struct device *dev);
const struct i3c_device_id *
i3c_device_match_id(struct i3c_device *i3cdev,
const struct i3c_device_id *id_table);
static inline void i3cdev_set_drvdata(struct i3c_device *i3cdev,
void *data)
{
struct device *dev = i3cdev_to_dev(i3cdev);
dev_set_drvdata(dev, data);
}
static inline void *i3cdev_get_drvdata(struct i3c_device *i3cdev)
{
struct device *dev = i3cdev_to_dev(i3cdev);
return dev_get_drvdata(dev);
}
int i3c_driver_register_with_owner(struct i3c_driver *drv,
struct module *owner);
void i3c_driver_unregister(struct i3c_driver *drv);
#define i3c_driver_register(__drv) \
i3c_driver_register_with_owner(__drv, THIS_MODULE)
/**
* module_i3c_driver() - Register a module providing an I3C driver
* @__drv: the I3C driver to register
*
* Provide generic init/exit functions that simply register/unregister an I3C
* driver.
* Should be used by any driver that does not require extra init/cleanup steps.
*/
#define module_i3c_driver(__drv) \
module_driver(__drv, i3c_driver_register, i3c_driver_unregister)
/**
* i3c_i2c_driver_register() - Register an i2c and an i3c driver
* @i3cdrv: the I3C driver to register
* @i2cdrv: the I2C driver to register
*
* This function registers both @i2cdev and @i3cdev, and fails if one of these
* registrations fails. This is mainly useful for devices that support both I2C
* and I3C modes.
* Note that when CONFIG_I3C is not enabled, this function only registers the
* I2C driver.
*
* Return: 0 if both registrations succeeds, a negative error code otherwise.
*/
static inline int i3c_i2c_driver_register(struct i3c_driver *i3cdrv,
struct i2c_driver *i2cdrv)
{
int ret;
ret = i2c_add_driver(i2cdrv);
if (ret || !IS_ENABLED([31mCONFIG_I3C[0m))
return ret;
ret = i3c_driver_register(i3cdrv);
if (ret)
i2c_del_driver(i2cdrv);
return ret;
}
/**
* i3c_i2c_driver_unregister() - Unregister an i2c and an i3c driver
* @i3cdrv: the I3C driver to register
* @i2cdrv: the I2C driver to register
*
* This function unregisters both @i3cdrv and @i2cdrv.
* Note that when CONFIG_I3C is not enabled, this function only unregisters the
* @i2cdrv.
*/
static inline void i3c_i2c_driver_unregister(struct i3c_driver *i3cdrv,
struct i2c_driver *i2cdrv)
{
if (IS_ENABLED([31mCONFIG_I3C[0m))
i3c_driver_unregister(i3cdrv);
i2c_del_driver(i2cdrv);
}
/**
* module_i3c_i2c_driver() - Register a module providing an I3C and an I2C
* driver
* @__i3cdrv: the I3C driver to register
* @__i2cdrv: the I3C driver to register
*
* Provide generic init/exit functions that simply register/unregister an I3C
* and an I2C driver.
* This macro can be used even if CONFIG_I3C is disabled, in this case, only
* the I2C driver will be registered.
* Should be used by any driver that does not require extra init/cleanup steps.
*/
#define module_i3c_i2c_driver(__i3cdrv, __i2cdrv) \
module_driver(__i3cdrv, \
i3c_i2c_driver_register, \
i3c_i2c_driver_unregister)
int i3c_device_do_priv_xfers(struct i3c_device *dev,
struct i3c_priv_xfer *xfers,
int nxfers);
void i3c_device_get_info(struct i3c_device *dev, struct i3c_device_info *info);
struct i3c_ibi_payload {
unsigned int len;
const void *data;
};
/**
* struct i3c_ibi_setup - IBI setup object
* @max_payload_len: maximum length of the payload associated to an IBI. If one
* IBI appears to have a payload that is bigger than this
* number, the IBI will be rejected.
* @num_slots: number of pre-allocated IBI slots. This should be chosen so that
* the system never runs out of IBI slots, otherwise you'll lose
* IBIs.
* @handler: IBI handler, every time an IBI is received. This handler is called
* in a workqueue context. It is allowed to sleep and send new
* messages on the bus, though it's recommended to keep the
* processing done there as fast as possible to avoid delaying
* processing of other queued on the same workqueue.
*
* Temporary structure used to pass information to i3c_device_request_ibi().
* This object can be allocated on the stack since i3c_device_request_ibi()
* copies every bit of information and do not use it after
* i3c_device_request_ibi() has returned.
*/
struct i3c_ibi_setup {
unsigned int max_payload_len;
unsigned int num_slots;
void (*handler)(struct i3c_device *dev,
const struct i3c_ibi_payload *payload);
};
int i3c_device_request_ibi(struct i3c_device *dev,
const struct i3c_ibi_setup *setup);
void i3c_device_free_ibi(struct i3c_device *dev);
int i3c_device_enable_ibi(struct i3c_device *dev);
int i3c_device_disable_ibi(struct i3c_device *dev);
#endif /* I3C_DEV_H */