include/linux/i3c/device.h - third_party/kernel - Git at Google

 /* 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(CONFIG_I3C))
 		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(CONFIG_I3C))
 		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 */
	/* 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(CONFIG_I3C))
	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(CONFIG_I3C))
	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 */