1 /* SPDX-License-Identifier: GPL-2.0 */
15 #include <linux/i3c/ccc.h>
16 #include <linux/i3c/device.h>
31  * struct i3c_i2c_dev_desc - Common part of the I3C/I2C device descriptor
32  * @node: node element used to insert the slot into the I2C or I3C device
34  * @master: I3C master that instantiated this device. Will be used to do
35  *	    I2C/I3C transfers
36  * @master_priv: master private data assigned to the device. Can be used to
37  *		 add master specific information
39  * This structure is describing common I3C/I2C dev information.
43 	struct i3c_master_controller *master;  member
54  * struct i2c_dev_boardinfo - I2C device board information
57  * @lvr: LVR (Legacy Virtual Register) needed by the I3C core to know about
60  * This structure is used to attach board-level information to an I2C device.
61  * Each I2C device connected on the I3C bus should have one.
70  * struct i2c_dev_desc - I2C device descriptor
75  * @lvr: LVR (Legacy Virtual Register) needed by the I3C core to know about
80  * using &struct_i3c_master_controller->ops->attach_i2c_dev().
83  * connected on an I3C bus. This object is also passed to all
95  * struct i3c_ibi_slot - I3C IBI (In-Band Interrupt) slot
98  * @dev: the I3C device that has generated this IBI
102  * An IBI slot is an object pre-allocated by the controller and used when an
104  * Every time an IBI comes in, the I3C master driver should find a free IBI
108  * How IBI slots are allocated is left to the I3C master driver, though, for
109  * simple kmalloc-based allocation, the generic IBI slot pool can be used.
119  * struct i3c_device_ibi_info - IBI information attached to a specific device
129  *		     rejected by the master
137  *	     New I3C messages can be sent from the IBI handler
141  * object is here to manage IBIs coming from a specific I3C device.
144  * infrastructure. I3C master drivers may have their own internal
146  * controller-private data.
159  * struct i3c_dev_boardinfo - I3C device board information
160  * @node: used to insert the boardinfo object in the I3C boardinfo list
165  * @static_addr: static address the I3C device listen on before it's been
166  *		 assigned a dynamic address by the master. Will be used during
169  * @pid: I3C Provisional ID exposed by the device. This is a unique identifier
174  * This structure is used to attach board-level information to an I3C device.
175  * Not all I3C devices connected on the bus will have a boardinfo. It's only
188  * struct i3c_dev_desc - I3C device descriptor
189  * @common: common part of the I3C device descriptor
190  * @info: I3C device information. Will be automatically filled when you create
192  * @ibi_lock: lock used to protect the &struct_i3c_device->ibi
195  * @dev: pointer to the I3C device object exposed to I3C device drivers. This
196  *	 should never be accessed from I3C master controller drivers. Only core
197  *	 code should manipulate it in when updating the dev <-> desc link or
199  * @boardinfo: pointer to the boardinfo attached to this I3C device
201  * Internal representation of an I3C device. This object is only used by the
202  * core and passed to I3C master controller drivers when they're requested to
204  * The core maintains the link between the internal I3C dev descriptor and the
205  * object exposed to the I3C device drivers (&struct_i3c_device).
217  * struct i3c_device - I3C device object
218  * @dev: device object to register the I3C dev to the device model
219  * @desc: pointer to an i3c device descriptor object. This link is updated
220  *	  every time the I3C device is rediscovered with a different dynamic
222  * @bus: I3C bus this device is attached to
224  * I3C device object exposed to I3C device drivers. The takes care of linking
226  * All I3C devs on the I3C bus are represented, including I3C masters. For each
236  * The I3C specification says the maximum number of devices connected on the
239  * I3C master can also have limitations, so this number is just here as a
240  * reference and should be adjusted on a per-controller/per-board basis.
251  * enum i3c_bus_mode - I3C bus mode
252  * @I3C_BUS_MODE_PURE: only I3C devices are connected to the bus. No limitation
257  *			     devices when transmitting I3C frames
273  * enum i3c_addr_slot_status - I3C address slot status
277  * @I3C_ADDR_SLOT_I3C_DEV: address is assigned to an I3C device
280  * On an I3C bus, addresses are assigned dynamically, and we need to know which
283  * Addresses marked as reserved are those reserved by the I3C protocol
295  * struct i3c_bus - I3C bus object
296  * @cur_master: I3C master currently driving the bus. Since I3C is multi-master
297  *		this can change over the time. Will be used to let a master
301  * @addrslots: a bitmap with 2-bits per-slot to encode the address status and
305  * @scl_rate.i3c: maximum rate for the clock signal when doing I3C SDR/priv
308  * @scl_rate: SCL signal rate for I3C and I2C mode
309  * @devs.i3c: contains a list of I3C device descriptors representing I3C
311  *	      I3C master
314  *	      I3C master
315  * @devs: 2 lists containing all I3C/I2C devices connected to the bus
320  *	  to send I3C frames to these devices.
322  *	  devices: several drivers can send different I3C/I2C frames through
323  *	  the same master in parallel. This is the responsibility of the
324  *	  master to guarantee that frames are actually sent sequentially and
327  * The I3C bus is represented with its own object and not implicitly described
328  * by the I3C master to cope with the multi-master functionality, where one bus
338 		unsigned long i3c;  member
342 		struct list_head i3c;  member
349  * struct i3c_master_controller_ops - I3C master methods
350  * @bus_init: hook responsible for the I3C bus initialization. You should at
355  *		 &i3c_master_controller_ops->bus_init().
357  * @attach_i3c_dev: called every time an I3C device is attached to the bus. It
363  *		    This is a good place to attach master controller specific
364  *		    data to I3C devices.
366  * @reattach_i3c_dev: called every time an I3C device has its addressed
372  * @detach_i3c_dev: called when an I3C device is detached from the bus. Usually
373  *		    happens when the master device is unregistered.
379  *	    attached or re-attached to the controller.
387  * @priv_xfers: do one or several private I3C SDR transfers
390  *		    This is a good place to attach master controller specific
394  *		    happens when the master device is unregistered.
396  * @i2c_xfers: do one or several I2C transfers. Note that, unlike i3c
398  *	       the transfers are DMA-safe. If drivers want to have DMA-safe
403  * @request_ibi: attach an IBI handler to an I3C device. This implies defining
405  *		 length and number of pre-allocated slots).
406  *		 Some controllers support less IBI-capable devices than regular
407  *		 devices, so this method might return -%EBUSY if there's no
410  * @free_ibi: free an IBI previously requested with ->request_ibi(). The IBI
411  *	      should have been disabled with ->disable_irq() prior to that
412  *	      This method is mandatory only if ->request_ibi is not NULL.
413  * @enable_ibi: enable the IBI. Only valid if ->request_ibi() has been called
414  *		prior to ->enable_ibi(). The controller should first enable
417  *		to the I3C device.
418  *		This method is mandatory only if ->request_ibi is not NULL.
422  *		 This method is mandatory only if ->request_ibi is not NULL.
425  *		      in the IBI slot pool so that the controller can re-use it
427  *		      This method is mandatory only if ->request_ibi is not
431 	int (*bus_init)(struct i3c_master_controller *master);
432 	void (*bus_cleanup)(struct i3c_master_controller *master);
436 	int (*do_daa)(struct i3c_master_controller *master);
437 	bool (*supports_ccc_cmd)(struct i3c_master_controller *master,
439 	int (*send_ccc_cmd)(struct i3c_master_controller *master,
458  * struct i3c_master_controller - I3C master controller object
459  * @dev: device to be registered to the device-model
460  * @this: an I3C device object representing this master. This device will be
461  *	  added to the list of I3C devs available on the bus
465  * @ops: master operations. See &struct i3c_master_controller_ops
466  * @secondary: true if the master is a secondary master
468  * @boardinfo.i3c: list of I3C  boardinfo objects
470  * @boardinfo: board-level information attached to devices connected on the bus
471  * @bus: I3C bus exposed by this master
472  * @wq: workqueue used to execute IBI handlers. Can also be used by master
476  *	be done from a sleep-able context
478  * A &struct i3c_master_controller has to be registered to the I3C subsystem
491 		struct list_head i3c;  member
499  * i3c_bus_for_each_i2cdev() - iterate over all I2C devices present on the bus
500  * @bus: the I3C bus
507 	list_for_each_entry(dev, &(bus)->devs.i2c, common.node)
510  * i3c_bus_for_each_i3cdev() - iterate over all I3C devices present on the bus
511  * @bus: the I3C bus
512  * @dev: and I3C device descriptor pointer updated to point to the current slot
515  * Iterate over all I3C devs present on the bus.
518 	list_for_each_entry(dev, &(bus)->devs.i3c, common.node)
520 int i3c_master_do_i2c_xfers(struct i3c_master_controller *master,
524 int i3c_master_disec_locked(struct i3c_master_controller *master, u8 addr,
526 int i3c_master_enec_locked(struct i3c_master_controller *master, u8 addr,
528 int i3c_master_entdaa_locked(struct i3c_master_controller *master);
529 int i3c_master_defslvs_locked(struct i3c_master_controller *master);
531 int i3c_master_get_free_addr(struct i3c_master_controller *master,
534 int i3c_master_add_i3c_dev_locked(struct i3c_master_controller *master,
536 int i3c_master_do_daa(struct i3c_master_controller *master);
538 int i3c_master_set_info(struct i3c_master_controller *master,
541 int i3c_master_register(struct i3c_master_controller *master,
545 int i3c_master_unregister(struct i3c_master_controller *master);
548  * i3c_dev_get_master_data() - get master private data attached to an I3C
550  * @dev: the I3C device descriptor to get private data from
557 	return dev->common.master_priv;  in i3c_dev_get_master_data()
561  * i3c_dev_set_master_data() - attach master private data to an I3C device
563  * @dev: the I3C device descriptor to attach private data to
566  * This functions allows a master controller to attach per-device private data
572 	dev->common.master_priv = data;  in i3c_dev_set_master_data()
576  * i2c_dev_get_master_data() - get master private data attached to an I2C
585 	return dev->common.master_priv;  in i2c_dev_get_master_data()
589  * i2c_dev_set_master_data() - attach master private data to an I2C device
594  * This functions allows a master controller to attach per-device private data
600 	dev->common.master_priv = data;  in i2c_dev_set_master_data()
604  * i3c_dev_get_master() - get master used to communicate with a device
605  * @dev: I3C dev
607  * Return: the master controller driving @dev
612 	return dev->common.master;  in i3c_dev_get_master()
616  * i2c_dev_get_master() - get master used to communicate with a device
619  * Return: the master controller driving @dev
624 	return dev->common.master;  in i2c_dev_get_master()
628  * i3c_master_get_bus() - get the bus attached to a master
629  * @master: master object
631  * Return: the I3C bus @master is connected to
634 i3c_master_get_bus(struct i3c_master_controller *master)  in i3c_master_get_bus()  argument
636 	return &master->bus;  in i3c_master_get_bus()