1 /* SPDX-License-Identifier: GPL-2.0 */
14 #include <linux/i2c.h>
38  * struct i3c_i2c_dev_desc - Common part of the I3C/I2C device descriptor
39  * @node: node element used to insert the slot into the I2C or I3C device
42  *	    I2C/I3C transfers
46  * This structure is describing common I3C/I2C dev information.
61  * struct i2c_dev_boardinfo - I2C device board information
62  * @node: used to insert the boardinfo object in the I2C boardinfo list
63  * @base: regular I2C board information
65  *	 the I2C device limitations
67  * This structure is used to attach board-level information to an I2C device.
68  * Each I2C device connected on the I3C bus should have one.
77  * struct i2c_dev_desc - I2C device descriptor
78  * @common: common part of the I2C device descriptor
79  * @dev: I2C device object registered to the I2C framework
80  * @addr: I2C device address
82  *	 the I2C device limitations
84  * Each I2C device connected on the bus will have an i2c_dev_desc.
86  * using &struct_i3c_master_controller->ops->attach_i2c_dev().
88  * &struct_i2c_dev_desc is the internal representation of an I2C device
89  * connected on an I3C bus. This object is also passed to all
100  * struct i3c_ibi_slot - I3C IBI (In-Band Interrupt) slot
107  * An IBI slot is an object pre-allocated by the controller and used when an
114  * simple kmalloc-based allocation, the generic IBI slot pool can be used.
124  * struct i3c_device_ibi_info - IBI information attached to a specific device
152  * controller-private data.
166  * struct i3c_dev_boardinfo - I3C device board information
174  *		 bus initialization to assign it a specific dynamic address
181  * This structure is used to attach board-level information to an I3C device.
182  * Not all I3C devices connected on the bus will have a boardinfo. It's only
195  * struct i3c_dev_desc - I3C device descriptor
199  * @ibi_lock: lock used to protect the &struct_i3c_device->ibi
204  *	 code should manipulate it in when updating the dev <-> desc link or
224  * struct i3c_device - I3C device object
229  * @bus: I3C bus this device is attached to
233  * All I3C devs on the I3C bus are represented, including I3C masters. For each
239 	struct i3c_bus *bus;  member
244  * bus is 11, but this number depends on external parameters like trace length,
245  * capacitive load per Device, and the types of Devices present on the Bus.
247  * reference and should be adjusted on a per-controller/per-board basis.
258  * enum i3c_bus_mode - I3C bus mode
259  * @I3C_BUS_MODE_PURE: only I3C devices are connected to the bus. No limitation
261  * @I3C_BUS_MODE_MIXED_FAST: I2C devices with 50ns spike filter are present on
262  *			     the bus. The only impact in this mode is that the
263  *			     high SCL pulse has to stay below 50ns to trick I2C
265  * @I3C_BUS_MODE_MIXED_LIMITED: I2C devices without 50ns spike filter are
266  *				present on the bus. However they allow
269  * @I3C_BUS_MODE_MIXED_SLOW: I2C devices without 50ns spike filter are present
270  *			     on the bus
280  * enum i3c_addr_slot_status - I3C address slot status
283  * @I3C_ADDR_SLOT_I2C_DEV: address is assigned to an I2C device
287  * On an I3C bus, addresses are assigned dynamically, and we need to know which
302  * struct i3c_bus - I3C bus object
303  * @cur_master: I3C master currently driving the bus. Since I3C is multi-master
305  *		know whether it needs to request bus ownership before sending
307  * @id: bus ID. Assigned by the framework when register the bus
308  * @addrslots: a bitmap with 2-bits per-slot to encode the address status and
311  * @mode: bus mode (see &enum i3c_bus_mode)
314  * @scl_rate.i2c: maximum rate for the clock signal when doing I2C transfers
315  * @scl_rate: SCL signal rate for I3C and I2C mode
317  *	      devices connected on the bus and successfully attached to the
319  * @devs.i2c: contains a list of I2C device descriptors representing I2C
320  *	      devices connected on the bus and successfully attached to the
322  * @devs: 2 lists containing all I3C/I2C devices connected to the bus
323  * @lock: read/write lock on the bus. This is needed to protect against
324  *	  operations that have an impact on the whole bus and the devices
329  *	  devices: several drivers can send different I3C/I2C frames through
334  * The I3C bus is represented with its own object and not implicitly described
335  * by the I3C master to cope with the multi-master functionality, where one bus
336  * can be shared amongst several masters, each of them requesting bus ownership
346 		unsigned long i2c;  member
350 		struct list_head i2c;  member
356  * struct i3c_master_controller_ops - I3C master methods
357  * @bus_init: hook responsible for the I3C bus initialization. You should at
358  *	      least call master_set_info() from there and set the bus mode.
362  *		 &i3c_master_controller_ops->bus_init().
364  * @attach_i3c_dev: called every time an I3C device is attached to the bus. It
379  * @detach_i3c_dev: called when an I3C device is detached from the bus. Usually
386  *	    attached or re-attached to the controller.
396  * @attach_i2c_dev: called every time an I2C device is attached to the bus.
398  *		    data to I2C devices.
400  * @detach_i2c_dev: called when an I2C device is detached from the bus. Usually
403  * @i2c_xfers: do one or several I2C transfers. Note that, unlike i3c
405  *	       the transfers are DMA-safe. If drivers want to have DMA-safe
407  *	       and i2c_put_dma_safe_msg_buf() helpers provided by the I2C
412  *		 length and number of pre-allocated slots).
413  *		 Some controllers support less IBI-capable devices than regular
414  *		 devices, so this method might return -%EBUSY if there's no
417  * @free_ibi: free an IBI previously requested with ->request_ibi(). The IBI
418  *	      should have been disabled with ->disable_irq() prior to that
419  *	      This method is mandatory only if ->request_ibi is not NULL.
420  * @enable_ibi: enable the IBI. Only valid if ->request_ibi() has been called
421  *		prior to ->enable_ibi(). The controller should first enable
425  *		This method is mandatory only if ->request_ibi is not NULL.
429  *		 This method is mandatory only if ->request_ibi is not NULL.
432  *		      in the IBI slot pool so that the controller can re-use it
434  *		      This method is mandatory only if ->request_ibi is not
469  * struct i3c_master_controller - I3C master controller object
470  * @dev: device to be registered to the device-model
472  *	  added to the list of I3C devs available on the bus
473  * @i2c: I2C adapter used for backward compatibility. This adapter is
474  *	 registered to the I2C subsystem to be as transparent as possible to
475  *	 existing I2C drivers
478  * @init_done: true when the bus initialization is done
481  * @boardinfo.i2c: list of I2C boardinfo objects
482  * @boardinfo: board-level information attached to devices connected on the bus
483  * @bus: I3C bus exposed by this master
487  *	requires taking the bus lock in maintenance, which in turn, can only
488  *	be done from a sleep-able context
498 	struct i2c_adapter i2c;  member
505 		struct list_head i2c;  member
507 	struct i3c_bus bus;  member
512  * i3c_bus_for_each_i2cdev() - iterate over all I2C devices present on the bus
513  * @bus: the I3C bus
514  * @dev: an I2C device descriptor pointer updated to point to the current slot
517  * Iterate over all I2C devs present on the bus.
519 #define i3c_bus_for_each_i2cdev(bus, dev)				\  argument
520 	list_for_each_entry(dev, &(bus)->devs.i2c, common.node)
523  * i3c_bus_for_each_i3cdev() - iterate over all I3C devices present on the bus
524  * @bus: the I3C bus
528  * Iterate over all I3C devs present on the bus.
530 #define i3c_bus_for_each_i3cdev(bus, dev)				\  argument
531 	list_for_each_entry(dev, &(bus)->devs.i3c, common.node)
563  * i3c_dev_get_master_data() - get master private data attached to an I3C
572 	return dev->common.master_priv;  in i3c_dev_get_master_data()
576  * i3c_dev_set_master_data() - attach master private data to an I3C device
581  * This functions allows a master controller to attach per-device private data
587 	dev->common.master_priv = data;  in i3c_dev_set_master_data()
591  * i2c_dev_get_master_data() - get master private data attached to an I2C
593  * @dev: the I2C device descriptor to get private data from
600 	return dev->common.master_priv;  in i2c_dev_get_master_data()
604  * i2c_dev_set_master_data() - attach master private data to an I2C device
606  * @dev: the I2C device descriptor to attach private data to
609  * This functions allows a master controller to attach per-device private data
615 	dev->common.master_priv = data;  in i2c_dev_set_master_data()
619  * i3c_dev_get_master() - get master used to communicate with a device
627 	return dev->common.master;  in i3c_dev_get_master()
631  * i2c_dev_get_master() - get master used to communicate with a device
632  * @dev: I2C dev
639 	return dev->common.master;  in i2c_dev_get_master()
643  * i3c_master_get_bus() - get the bus attached to a master
646  * Return: the I3C bus @master is connected to
651 	return &master->bus;  in i3c_master_get_bus()
670 void i3c_for_each_bus_locked(int (*fn)(struct i3c_bus *bus, void *data),