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_xfer.err or &struct i3c_hdr_cmd.err to get a better idea of
 31 * what went wrong.
 32 *
 33 */
 34enum 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_xfer_mode - I3C xfer mode ids
 43 * @I3C_HDR_DDR: DDR mode
 44 * @I3C_HDR_TSP: TSP mode
 45 * @I3C_HDR_TSL: TSL mode
 46 * @I3C_SDR: SDR mode (NOT HDR mode)
 47 */
 48enum i3c_xfer_mode {
 49	/* The below 3 value (I3C_HDR*) must match GETCAP1 Byte bit position */
 50	I3C_HDR_DDR = 0,
 51	I3C_HDR_TSP = 1,
 52	I3C_HDR_TSL = 2,
 53	/* Use for default SDR transfer mode */
 54	I3C_SDR = 31,
 55};
 56
 57/**
 58 * struct i3c_xfer - I3C data transfer
 59 * @rnw: encodes the transfer direction. true for a read, false for a write
 60 * @cmd: Read/Write command in HDR mode, read: 0x80 - 0xff, write: 0x00 - 0x7f
 61 * @len: transfer length in bytes of the transfer
 62 * @actual_len: actual length in bytes are transferred by the controller
 63 * @data: input/output buffer
 64 * @data.in: input buffer. Must point to a DMA-able buffer
 65 * @data.out: output buffer. Must point to a DMA-able buffer
 66 * @err: I3C error code
 67 */
 68struct i3c_xfer {
 69	union {
 70		u8 rnw;
 71		u8 cmd;
 72	};
 73	u16 len;
 74	u16 actual_len;
 75	union {
 76		void *in;
 77		const void *out;
 78	} data;
 79	enum i3c_error_code err;
 80};
 81
 82/* keep back compatible */
 83#define i3c_priv_xfer i3c_xfer
 84
 85/**
 86 * enum i3c_dcr - I3C DCR values
 87 * @I3C_DCR_GENERIC_DEVICE: generic I3C device
 88 */
 89enum i3c_dcr {
 90	I3C_DCR_GENERIC_DEVICE = 0,
 91};
 92
 93#define I3C_PID_MANUF_ID(pid)		(((pid) & GENMASK_ULL(47, 33)) >> 33)
 94#define I3C_PID_RND_LOWER_32BITS(pid)	(!!((pid) & BIT_ULL(32)))
 95#define I3C_PID_RND_VAL(pid)		((pid) & GENMASK_ULL(31, 0))
 96#define I3C_PID_PART_ID(pid)		(((pid) & GENMASK_ULL(31, 16)) >> 16)
 97#define I3C_PID_INSTANCE_ID(pid)	(((pid) & GENMASK_ULL(15, 12)) >> 12)
 98#define I3C_PID_EXTRA_INFO(pid)		((pid) & GENMASK_ULL(11, 0))
 99
100#define I3C_BCR_DEVICE_ROLE(bcr)	((bcr) & GENMASK(7, 6))
101#define I3C_BCR_I3C_SLAVE		(0 << 6)
102#define I3C_BCR_I3C_MASTER		(1 << 6)
103#define I3C_BCR_HDR_CAP			BIT(5)
104#define I3C_BCR_BRIDGE			BIT(4)
105#define I3C_BCR_OFFLINE_CAP		BIT(3)
106#define I3C_BCR_IBI_PAYLOAD		BIT(2)
107#define I3C_BCR_IBI_REQ_CAP		BIT(1)
108#define I3C_BCR_MAX_DATA_SPEED_LIM	BIT(0)
109
110/**
111 * struct i3c_device_info - I3C device information
112 * @pid: Provisioned ID
113 * @bcr: Bus Characteristic Register
114 * @dcr: Device Characteristic Register
115 * @static_addr: static/I2C address
116 * @dyn_addr: dynamic address
117 * @hdr_cap: supported HDR modes
118 * @max_read_ds: max read speed information
119 * @max_write_ds: max write speed information
120 * @max_ibi_len: max IBI payload length
121 * @max_read_turnaround: max read turn-around time in micro-seconds
122 * @max_read_len: max private SDR read length in bytes
123 * @max_write_len: max private SDR write length in bytes
124 *
125 * These are all basic information that should be advertised by an I3C device.
126 * Some of them are optional depending on the device type and device
127 * capabilities.
128 * For each I3C slave attached to a master with
129 * i3c_master_add_i3c_dev_locked(), the core will send the relevant CCC command
130 * to retrieve these data.
131 */
132struct i3c_device_info {
133	u64 pid;
134	u8 bcr;
135	u8 dcr;
136	u8 static_addr;
137	u8 dyn_addr;
138	u8 hdr_cap;
139	u8 max_read_ds;
140	u8 max_write_ds;
141	u8 max_ibi_len;
142	u32 max_read_turnaround;
143	u16 max_read_len;
144	u16 max_write_len;
145};
146
147/*
148 * I3C device internals are kept hidden from I3C device users. It's just
149 * simpler to refactor things when everything goes through getter/setters, and
150 * I3C device drivers should not have to worry about internal representation
151 * anyway.
152 */
153struct i3c_device;
154
155/* These macros should be used to i3c_device_id entries. */
156#define I3C_MATCH_MANUF_AND_PART (I3C_MATCH_MANUF | I3C_MATCH_PART)
157
158#define I3C_DEVICE(_manufid, _partid, _drvdata)				\
159	{								\
160		.match_flags = I3C_MATCH_MANUF_AND_PART,		\
161		.manuf_id = _manufid,					\
162		.part_id = _partid,					\
163		.data = _drvdata,					\
164	}
165
166#define I3C_DEVICE_EXTRA_INFO(_manufid, _partid, _info, _drvdata)	\
167	{								\
168		.match_flags = I3C_MATCH_MANUF_AND_PART |		\
169			       I3C_MATCH_EXTRA_INFO,			\
170		.manuf_id = _manufid,					\
171		.part_id = _partid,					\
172		.extra_info = _info,					\
173		.data = _drvdata,					\
174	}
175
176#define I3C_CLASS(_dcr, _drvdata)					\
177	{								\
178		.match_flags = I3C_MATCH_DCR,				\
179		.dcr = _dcr,						\
180	}
181
182/**
183 * struct i3c_driver - I3C device driver
184 * @driver: inherit from device_driver
185 * @probe: I3C device probe method
186 * @remove: I3C device remove method
187 * @id_table: I3C device match table. Will be used by the framework to decide
188 *	      which device to bind to this driver
189 */
190struct i3c_driver {
191	struct device_driver driver;
192	int (*probe)(struct i3c_device *dev);
193	void (*remove)(struct i3c_device *dev);
194	const struct i3c_device_id *id_table;
195};
196
197#define drv_to_i3cdrv(__drv)	container_of_const(__drv, struct i3c_driver, driver)
198
199struct device *i3cdev_to_dev(struct i3c_device *i3cdev);
200
201/**
202 * dev_to_i3cdev() - Returns the I3C device containing @dev
203 * @__dev: device object
204 *
205 * Return: a pointer to an I3C device object.
206 */
207#define dev_to_i3cdev(__dev)	container_of_const(__dev, struct i3c_device, dev)
208
209const struct i3c_device_id *
210i3c_device_match_id(struct i3c_device *i3cdev,
211		    const struct i3c_device_id *id_table);
212
213static inline void i3cdev_set_drvdata(struct i3c_device *i3cdev,
214				      void *data)
215{
216	struct device *dev = i3cdev_to_dev(i3cdev);
217
218	dev_set_drvdata(dev, data);
219}
220
221static inline void *i3cdev_get_drvdata(struct i3c_device *i3cdev)
222{
223	struct device *dev = i3cdev_to_dev(i3cdev);
224
225	return dev_get_drvdata(dev);
226}
227
228int i3c_driver_register_with_owner(struct i3c_driver *drv,
229				   struct module *owner);
230void i3c_driver_unregister(struct i3c_driver *drv);
231
232#define i3c_driver_register(__drv)		\
233	i3c_driver_register_with_owner(__drv, THIS_MODULE)
234
235/**
236 * module_i3c_driver() - Register a module providing an I3C driver
237 * @__drv: the I3C driver to register
238 *
239 * Provide generic init/exit functions that simply register/unregister an I3C
240 * driver.
241 * Should be used by any driver that does not require extra init/cleanup steps.
242 */
243#define module_i3c_driver(__drv)		\
244	module_driver(__drv, i3c_driver_register, i3c_driver_unregister)
245
246/**
247 * i3c_i2c_driver_register() - Register an i2c and an i3c driver
248 * @i3cdrv: the I3C driver to register
249 * @i2cdrv: the I2C driver to register
250 *
251 * This function registers both @i2cdev and @i3cdev, and fails if one of these
252 * registrations fails. This is mainly useful for devices that support both I2C
253 * and I3C modes.
254 * Note that when CONFIG_I3C is not enabled, this function only registers the
255 * I2C driver.
256 *
257 * Return: 0 if both registrations succeeds, a negative error code otherwise.
258 */
259static __always_inline int i3c_i2c_driver_register(struct i3c_driver *i3cdrv,
260					  struct i2c_driver *i2cdrv)
261{
262	int ret;
263
264	ret = i2c_add_driver(i2cdrv);
265	if (ret || !IS_ENABLED(CONFIG_I3C))
266		return ret;
267
268	ret = i3c_driver_register(i3cdrv);
269	if (ret)
270		i2c_del_driver(i2cdrv);
271
272	return ret;
273}
274
275/**
276 * i3c_i2c_driver_unregister() - Unregister an i2c and an i3c driver
277 * @i3cdrv: the I3C driver to register
278 * @i2cdrv: the I2C driver to register
279 *
280 * This function unregisters both @i3cdrv and @i2cdrv.
281 * Note that when CONFIG_I3C is not enabled, this function only unregisters the
282 * @i2cdrv.
283 */
284static __always_inline void i3c_i2c_driver_unregister(struct i3c_driver *i3cdrv,
285					     struct i2c_driver *i2cdrv)
286{
287	if (IS_ENABLED(CONFIG_I3C))
288		i3c_driver_unregister(i3cdrv);
289
290	i2c_del_driver(i2cdrv);
291}
292
293/**
294 * module_i3c_i2c_driver() - Register a module providing an I3C and an I2C
295 *			     driver
296 * @__i3cdrv: the I3C driver to register
297 * @__i2cdrv: the I2C driver to register
298 *
299 * Provide generic init/exit functions that simply register/unregister an I3C
300 * and an I2C driver.
301 * This macro can be used even if CONFIG_I3C is disabled, in this case, only
302 * the I2C driver will be registered.
303 * Should be used by any driver that does not require extra init/cleanup steps.
304 */
305#define module_i3c_i2c_driver(__i3cdrv, __i2cdrv)	\
306	module_driver(__i3cdrv,				\
307		      i3c_i2c_driver_register,		\
308		      i3c_i2c_driver_unregister,	\
309		      __i2cdrv)
310
311int i3c_device_do_xfers(struct i3c_device *dev, struct i3c_xfer *xfers,
312			int nxfers, enum i3c_xfer_mode mode);
313
314static inline int i3c_device_do_priv_xfers(struct i3c_device *dev,
315					   struct i3c_xfer *xfers,
316					   int nxfers)
317{
318	return i3c_device_do_xfers(dev, xfers, nxfers, I3C_SDR);
319}
320
321int i3c_device_do_setdasa(struct i3c_device *dev);
322
323void i3c_device_get_info(const struct i3c_device *dev, struct i3c_device_info *info);
324
325struct i3c_ibi_payload {
326	unsigned int len;
327	const void *data;
328};
329
330/**
331 * struct i3c_ibi_setup - IBI setup object
332 * @max_payload_len: maximum length of the payload associated to an IBI. If one
333 *		     IBI appears to have a payload that is bigger than this
334 *		     number, the IBI will be rejected.
335 * @num_slots: number of pre-allocated IBI slots. This should be chosen so that
336 *	       the system never runs out of IBI slots, otherwise you'll lose
337 *	       IBIs.
338 * @handler: IBI handler, every time an IBI is received. This handler is called
339 *	     in a workqueue context. It is allowed to sleep and send new
340 *	     messages on the bus, though it's recommended to keep the
341 *	     processing done there as fast as possible to avoid delaying
342 *	     processing of other queued on the same workqueue.
343 *
344 * Temporary structure used to pass information to i3c_device_request_ibi().
345 * This object can be allocated on the stack since i3c_device_request_ibi()
346 * copies every bit of information and do not use it after
347 * i3c_device_request_ibi() has returned.
348 */
349struct i3c_ibi_setup {
350	unsigned int max_payload_len;
351	unsigned int num_slots;
352	void (*handler)(struct i3c_device *dev,
353			const struct i3c_ibi_payload *payload);
354};
355
356int i3c_device_request_ibi(struct i3c_device *dev,
357			   const struct i3c_ibi_setup *setup);
358void i3c_device_free_ibi(struct i3c_device *dev);
359int i3c_device_enable_ibi(struct i3c_device *dev);
360int i3c_device_disable_ibi(struct i3c_device *dev);
361u32 i3c_device_get_supported_xfer_mode(struct i3c_device *dev);
362
363#endif /* I3C_DEV_H */