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_MASTER_H
9 #define I3C_MASTER_H
10 
11 #include <asm/bitsperlong.h>
12 
13 #include <linux/bitops.h>
14 #include <linux/i2c.h>
15 #include <linux/i3c/ccc.h>
16 #include <linux/i3c/device.h>
17 #include <linux/rwsem.h>
18 #include <linux/spinlock.h>
19 #include <linux/workqueue.h>
20 
21 #define I3C_HOT_JOIN_ADDR		0x2
22 #define I3C_BROADCAST_ADDR		0x7e
23 #define I3C_MAX_ADDR			GENMASK(6, 0)
24 
25 struct i2c_client;
26 
27 struct i3c_master_controller;
28 struct i3c_bus;
29 struct i3c_device;
30 
31 /**
32  * struct i3c_i2c_dev_desc - Common part of the I3C/I2C device descriptor
33  * @node: node element used to insert the slot into the I2C or I3C device
34  *	  list
35  * @master: I3C master that instantiated this device. Will be used to do
36  *	    I2C/I3C transfers
37  * @master_priv: master private data assigned to the device. Can be used to
38  *		 add master specific information
39  *
40  * This structure is describing common I3C/I2C dev information.
41  */
42 struct i3c_i2c_dev_desc {
43 	struct list_head node;
44 	struct i3c_master_controller *master;
45 	void *master_priv;
46 };
47 
48 #define I3C_LVR_I2C_INDEX_MASK		GENMASK(7, 5)
49 #define I3C_LVR_I2C_INDEX(x)		((x) << 5)
50 #define I3C_LVR_I2C_FM_MODE		BIT(4)
51 
52 #define I2C_MAX_ADDR			GENMASK(6, 0)
53 
54 /**
55  * struct i2c_dev_boardinfo - I2C device board information
56  * @node: used to insert the boardinfo object in the I2C boardinfo list
57  * @base: regular I2C board information
58  * @lvr: LVR (Legacy Virtual Register) needed by the I3C core to know about
59  *	 the I2C device limitations
60  *
61  * This structure is used to attach board-level information to an I2C device.
62  * Each I2C device connected on the I3C bus should have one.
63  */
64 struct i2c_dev_boardinfo {
65 	struct list_head node;
66 	struct i2c_board_info base;
67 	u8 lvr;
68 };
69 
70 /**
71  * struct i2c_dev_desc - I2C device descriptor
72  * @common: common part of the I2C device descriptor
73  * @boardinfo: pointer to the boardinfo attached to this I2C device
74  * @dev: I2C device object registered to the I2C framework
75  * @addr: I2C device address
76  * @lvr: LVR (Legacy Virtual Register) needed by the I3C core to know about
77  *	 the I2C device limitations
78  *
79  * Each I2C device connected on the bus will have an i2c_dev_desc.
80  * This object is created by the core and later attached to the controller
81  * using &struct_i3c_master_controller->ops->attach_i2c_dev().
82  *
83  * &struct_i2c_dev_desc is the internal representation of an I2C device
84  * connected on an I3C bus. This object is also passed to all
85  * &struct_i3c_master_controller_ops hooks.
86  */
87 struct i2c_dev_desc {
88 	struct i3c_i2c_dev_desc common;
89 	struct i2c_client *dev;
90 	u16 addr;
91 	u8 lvr;
92 };
93 
94 /**
95  * struct i3c_ibi_slot - I3C IBI (In-Band Interrupt) slot
96  * @work: work associated to this slot. The IBI handler will be called from
97  *	  there
98  * @dev: the I3C device that has generated this IBI
99  * @len: length of the payload associated to this IBI
100  * @data: payload buffer
101  *
102  * An IBI slot is an object pre-allocated by the controller and used when an
103  * IBI comes in.
104  * Every time an IBI comes in, the I3C master driver should find a free IBI
105  * slot in its IBI slot pool, retrieve the IBI payload and queue the IBI using
106  * i3c_master_queue_ibi().
107  *
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.
110  */
111 struct i3c_ibi_slot {
112 	struct work_struct work;
113 	struct i3c_dev_desc *dev;
114 	unsigned int len;
115 	void *data;
116 };
117 
118 /**
119  * struct i3c_device_ibi_info - IBI information attached to a specific device
120  * @all_ibis_handled: used to be informed when no more IBIs are waiting to be
121  *		      processed. Used by i3c_device_disable_ibi() to wait for
122  *		      all IBIs to be dequeued
123  * @pending_ibis: count the number of pending IBIs. Each pending IBI has its
124  *		  work element queued to the controller workqueue
125  * @max_payload_len: maximum payload length for an IBI coming from this device.
126  *		     this value is specified when calling
127  *		     i3c_device_request_ibi() and should not change at run
128  *		     time. All messages IBIs exceeding this limit should be
129  *		     rejected by the master
130  * @num_slots: number of IBI slots reserved for this device
131  * @enabled: reflect the IBI status
132  * @handler: IBI handler specified at i3c_device_request_ibi() call time. This
133  *	     handler will be called from the controller workqueue, and as such
134  *	     is allowed to sleep (though it is recommended to process the IBI
135  *	     as fast as possible to not stall processing of other IBIs queued
136  *	     on the same workqueue).
137  *	     New I3C messages can be sent from the IBI handler
138  *
139  * The &struct_i3c_device_ibi_info object is allocated when
140  * i3c_device_request_ibi() is called and attached to a specific device. This
141  * object is here to manage IBIs coming from a specific I3C device.
142  *
143  * Note that this structure is the generic view of the IBI management
144  * infrastructure. I3C master drivers may have their own internal
145  * representation which they can associate to the device using
146  * controller-private data.
147  */
148 struct i3c_device_ibi_info {
149 	struct completion all_ibis_handled;
150 	atomic_t pending_ibis;
151 	unsigned int max_payload_len;
152 	unsigned int num_slots;
153 	unsigned int enabled;
154 	void (*handler)(struct i3c_device *dev,
155 			const struct i3c_ibi_payload *payload);
156 };
157 
158 /**
159  * struct i3c_dev_boardinfo - I3C device board information
160  * @node: used to insert the boardinfo object in the I3C boardinfo list
161  * @init_dyn_addr: initial dynamic address requested by the FW. We provide no
162  *		   guarantee that the device will end up using this address,
163  *		   but try our best to assign this specific address to the
164  *		   device
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
167  *		 bus initialization to assign it a specific dynamic address
168  *		 before starting DAA (Dynamic Address Assignment)
169  * @pid: I3C Provisional ID exposed by the device. This is a unique identifier
170  *	 that may be used to attach boardinfo to i3c_dev_desc when the device
171  *	 does not have a static address
172  * @of_node: optional DT node in case the device has been described in the DT
173  *
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
176  * needed if you want to attach extra resources to a device or assign it a
177  * specific dynamic address.
178  */
179 struct i3c_dev_boardinfo {
180 	struct list_head node;
181 	u8 init_dyn_addr;
182 	u8 static_addr;
183 	u64 pid;
184 	struct device_node *of_node;
185 };
186 
187 /**
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
191  *	  your device with i3c_master_add_i3c_dev_locked()
192  * @ibi_lock: lock used to protect the &struct_i3c_device->ibi
193  * @ibi: IBI info attached to a device. Should be NULL until
194  *	 i3c_device_request_ibi() is called
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
198  *	 when propagating IBI events to the driver
199  * @boardinfo: pointer to the boardinfo attached to this I3C device
200  *
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
203  * do some operations on the device.
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).
206  */
207 struct i3c_dev_desc {
208 	struct i3c_i2c_dev_desc common;
209 	struct i3c_device_info info;
210 	struct mutex ibi_lock;
211 	struct i3c_device_ibi_info *ibi;
212 	struct i3c_device *dev;
213 	const struct i3c_dev_boardinfo *boardinfo;
214 };
215 
216 /**
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
221  *	  address assigned
222  * @bus: I3C bus this device is attached to
223  *
224  * I3C device object exposed to I3C device drivers. The takes care of linking
225  * this object to the relevant &struct_i3c_dev_desc one.
226  * All I3C devs on the I3C bus are represented, including I3C masters. For each
227  * of them, we have an instance of &struct i3c_device.
228  */
229 struct i3c_device {
230 	struct device dev;
231 	struct i3c_dev_desc *desc;
232 	struct i3c_bus *bus;
233 };
234 
235 /*
236  * The I3C specification says the maximum number of devices connected on the
237  * bus is 11, but this number depends on external parameters like trace length,
238  * capacitive load per Device, and the types of Devices present on the Bus.
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.
241  */
242 #define I3C_BUS_MAX_DEVS		11
243 
244 #define I3C_BUS_MAX_I3C_SCL_RATE	12900000
245 #define I3C_BUS_TYP_I3C_SCL_RATE	12500000
246 #define I3C_BUS_I2C_FM_PLUS_SCL_RATE	1000000
247 #define I3C_BUS_I2C_FM_SCL_RATE		400000
248 #define I3C_BUS_TLOW_OD_MIN_NS		200
249 
250 /**
251  * enum i3c_bus_mode - I3C bus mode
252  * @I3C_BUS_MODE_PURE: only I3C devices are connected to the bus. No limitation
253  *		       expected
254  * @I3C_BUS_MODE_MIXED_FAST: I2C devices with 50ns spike filter are present on
255  *			     the bus. The only impact in this mode is that the
256  *			     high SCL pulse has to stay below 50ns to trick I2C
257  *			     devices when transmitting I3C frames
258  * @I3C_BUS_MODE_MIXED_LIMITED: I2C devices without 50ns spike filter are
259  *				present on the bus. However they allow
260  *				compliance up to the maximum SDR SCL clock
261  *				frequency.
262  * @I3C_BUS_MODE_MIXED_SLOW: I2C devices without 50ns spike filter are present
263  *			     on the bus
264  */
265 enum i3c_bus_mode {
266 	I3C_BUS_MODE_PURE,
267 	I3C_BUS_MODE_MIXED_FAST,
268 	I3C_BUS_MODE_MIXED_LIMITED,
269 	I3C_BUS_MODE_MIXED_SLOW,
270 };
271 
272 /**
273  * enum i3c_addr_slot_status - I3C address slot status
274  * @I3C_ADDR_SLOT_FREE: address is free
275  * @I3C_ADDR_SLOT_RSVD: address is reserved
276  * @I3C_ADDR_SLOT_I2C_DEV: address is assigned to an I2C device
277  * @I3C_ADDR_SLOT_I3C_DEV: address is assigned to an I3C device
278  * @I3C_ADDR_SLOT_STATUS_MASK: address slot mask
279  *
280  * On an I3C bus, addresses are assigned dynamically, and we need to know which
281  * addresses are free to use and which ones are already assigned.
282  *
283  * Addresses marked as reserved are those reserved by the I3C protocol
284  * (broadcast address, ...).
285  */
286 enum i3c_addr_slot_status {
287 	I3C_ADDR_SLOT_FREE,
288 	I3C_ADDR_SLOT_RSVD,
289 	I3C_ADDR_SLOT_I2C_DEV,
290 	I3C_ADDR_SLOT_I3C_DEV,
291 	I3C_ADDR_SLOT_STATUS_MASK = 3,
292 };
293 
294 /**
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
298  *		know whether it needs to request bus ownership before sending
299  *		a frame or not
300  * @id: bus ID. Assigned by the framework when register the bus
301  * @addrslots: a bitmap with 2-bits per-slot to encode the address status and
302  *	       ease the DAA (Dynamic Address Assignment) procedure (see
303  *	       &enum i3c_addr_slot_status)
304  * @mode: bus mode (see &enum i3c_bus_mode)
305  * @scl_rate.i3c: maximum rate for the clock signal when doing I3C SDR/priv
306  *		  transfers
307  * @scl_rate.i2c: maximum rate for the clock signal when doing I2C transfers
308  * @scl_rate: SCL signal rate for I3C and I2C mode
309  * @devs.i3c: contains a list of I3C device descriptors representing I3C
310  *	      devices connected on the bus and successfully attached to the
311  *	      I3C master
312  * @devs.i2c: contains a list of I2C device descriptors representing I2C
313  *	      devices connected on the bus and successfully attached to the
314  *	      I3C master
315  * @devs: 2 lists containing all I3C/I2C devices connected to the bus
316  * @lock: read/write lock on the bus. This is needed to protect against
317  *	  operations that have an impact on the whole bus and the devices
318  *	  connected to it. For example, when asking slaves to drop their
319  *	  dynamic address (RSTDAA CCC), we need to make sure no one is trying
320  *	  to send I3C frames to these devices.
321  *	  Note that this lock does not protect against concurrency between
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
325  *	  not interlaced
326  *
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
329  * can be shared amongst several masters, each of them requesting bus ownership
330  * when they need to.
331  */
332 struct i3c_bus {
333 	struct i3c_dev_desc *cur_master;
334 	int id;
335 	unsigned long addrslots[((I2C_MAX_ADDR + 1) * 2) / BITS_PER_LONG];
336 	enum i3c_bus_mode mode;
337 	struct {
338 		unsigned long i3c;
339 		unsigned long i2c;
340 	} scl_rate;
341 	struct {
342 		struct list_head i3c;
343 		struct list_head i2c;
344 	} devs;
345 	struct rw_semaphore lock;
346 };
347 
348 /**
349  * struct i3c_master_controller_ops - I3C master methods
350  * @bus_init: hook responsible for the I3C bus initialization. You should at
351  *	      least call master_set_info() from there and set the bus mode.
352  *	      You can also put controller specific initialization in there.
353  *	      This method is mandatory.
354  * @bus_cleanup: cleanup everything done in
355  *		 &i3c_master_controller_ops->bus_init().
356  *		 This method is optional.
357  * @attach_i3c_dev: called every time an I3C device is attached to the bus. It
358  *		    can be after a DAA or when a device is statically declared
359  *		    by the FW, in which case it will only have a static address
360  *		    and the dynamic address will be 0.
361  *		    When this function is called, device information have not
362  *		    been retrieved yet.
363  *		    This is a good place to attach master controller specific
364  *		    data to I3C devices.
365  *		    This method is optional.
366  * @reattach_i3c_dev: called every time an I3C device has its addressed
367  *		      changed. It can be because the device has been powered
368  *		      down and has lost its address, or it can happen when a
369  *		      device had a static address and has been assigned a
370  *		      dynamic address with SETDASA.
371  *		      This method is optional.
372  * @detach_i3c_dev: called when an I3C device is detached from the bus. Usually
373  *		    happens when the master device is unregistered.
374  *		    This method is optional.
375  * @do_daa: do a DAA (Dynamic Address Assignment) procedure. This is procedure
376  *	    should send an ENTDAA CCC command and then add all devices
377  *	    discovered sure the DAA using i3c_master_add_i3c_dev_locked().
378  *	    Add devices added with i3c_master_add_i3c_dev_locked() will then be
379  *	    attached or re-attached to the controller.
380  *	    This method is mandatory.
381  * @supports_ccc_cmd: should return true if the CCC command is supported, false
382  *		      otherwise.
383  *		      This method is optional, if not provided the core assumes
384  *		      all CCC commands are supported.
385  * @send_ccc_cmd: send a CCC command
386  *		  This method is mandatory.
387  * @priv_xfers: do one or several private I3C SDR transfers
388  *		This method is mandatory.
389  * @attach_i2c_dev: called every time an I2C device is attached to the bus.
390  *		    This is a good place to attach master controller specific
391  *		    data to I2C devices.
392  *		    This method is optional.
393  * @detach_i2c_dev: called when an I2C device is detached from the bus. Usually
394  *		    happens when the master device is unregistered.
395  *		    This method is optional.
396  * @i2c_xfers: do one or several I2C transfers. Note that, unlike i3c
397  *	       transfers, the core does not guarantee that buffers attached to
398  *	       the transfers are DMA-safe. If drivers want to have DMA-safe
399  *	       buffers, they should use the i2c_get_dma_safe_msg_buf()
400  *	       and i2c_put_dma_safe_msg_buf() helpers provided by the I2C
401  *	       framework.
402  *	       This method is mandatory.
403  * @request_ibi: attach an IBI handler to an I3C device. This implies defining
404  *		 an IBI handler and the constraints of the IBI (maximum payload
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
408  *		 more space for an extra IBI registration
409  *		 This method is optional.
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
415  *		the IBI on the controller end (for example, unmask the hardware
416  *		IRQ) and then send the ENEC CCC command (with the IBI flag set)
417  *		to the I3C device.
418  *		This method is mandatory only if ->request_ibi is not NULL.
419  * @disable_ibi: disable an IBI. First send the DISEC CCC command with the IBI
420  *		 flag set and then deactivate the hardware IRQ on the
421  *		 controller end.
422  *		 This method is mandatory only if ->request_ibi is not NULL.
423  * @recycle_ibi_slot: recycle an IBI slot. Called every time an IBI has been
424  *		      processed by its handler. The IBI slot should be put back
425  *		      in the IBI slot pool so that the controller can re-use it
426  *		      for a future IBI
427  *		      This method is mandatory only if ->request_ibi is not
428  *		      NULL.
429  */
430 struct i3c_master_controller_ops {
431 	int (*bus_init)(struct i3c_master_controller *master);
432 	void (*bus_cleanup)(struct i3c_master_controller *master);
433 	int (*attach_i3c_dev)(struct i3c_dev_desc *dev);
434 	int (*reattach_i3c_dev)(struct i3c_dev_desc *dev, u8 old_dyn_addr);
435 	void (*detach_i3c_dev)(struct i3c_dev_desc *dev);
436 	int (*do_daa)(struct i3c_master_controller *master);
437 	bool (*supports_ccc_cmd)(struct i3c_master_controller *master,
438 				 const struct i3c_ccc_cmd *cmd);
439 	int (*send_ccc_cmd)(struct i3c_master_controller *master,
440 			    struct i3c_ccc_cmd *cmd);
441 	int (*priv_xfers)(struct i3c_dev_desc *dev,
442 			  struct i3c_priv_xfer *xfers,
443 			  int nxfers);
444 	int (*attach_i2c_dev)(struct i2c_dev_desc *dev);
445 	void (*detach_i2c_dev)(struct i2c_dev_desc *dev);
446 	int (*i2c_xfers)(struct i2c_dev_desc *dev,
447 			 const struct i2c_msg *xfers, int nxfers);
448 	int (*request_ibi)(struct i3c_dev_desc *dev,
449 			   const struct i3c_ibi_setup *req);
450 	void (*free_ibi)(struct i3c_dev_desc *dev);
451 	int (*enable_ibi)(struct i3c_dev_desc *dev);
452 	int (*disable_ibi)(struct i3c_dev_desc *dev);
453 	void (*recycle_ibi_slot)(struct i3c_dev_desc *dev,
454 				 struct i3c_ibi_slot *slot);
455 };
456 
457 /**
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
462  * @i2c: I2C adapter used for backward compatibility. This adapter is
463  *	 registered to the I2C subsystem to be as transparent as possible to
464  *	 existing I2C drivers
465  * @ops: master operations. See &struct i3c_master_controller_ops
466  * @secondary: true if the master is a secondary master
467  * @init_done: true when the bus initialization is done
468  * @boardinfo.i3c: list of I3C  boardinfo objects
469  * @boardinfo.i2c: list of I2C 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
473  *	drivers if they need to postpone operations that need to take place
474  *	in a thread context. Typical examples are Hot Join processing which
475  *	requires taking the bus lock in maintenance, which in turn, can only
476  *	be done from a sleep-able context
477  *
478  * A &struct i3c_master_controller has to be registered to the I3C subsystem
479  * through i3c_master_register(). None of &struct i3c_master_controller fields
480  * should be set manually, just pass appropriate values to
481  * i3c_master_register().
482  */
483 struct i3c_master_controller {
484 	struct device dev;
485 	struct i3c_dev_desc *this;
486 	struct i2c_adapter i2c;
487 	const struct i3c_master_controller_ops *ops;
488 	unsigned int secondary : 1;
489 	unsigned int init_done : 1;
490 	struct {
491 		struct list_head i3c;
492 		struct list_head i2c;
493 	} boardinfo;
494 	struct i3c_bus bus;
495 	struct workqueue_struct *wq;
496 };
497 
498 /**
499  * i3c_bus_for_each_i2cdev() - iterate over all I2C devices present on the bus
500  * @bus: the I3C bus
501  * @dev: an I2C device descriptor pointer updated to point to the current slot
502  *	 at each iteration of the loop
503  *
504  * Iterate over all I2C devs present on the bus.
505  */
506 #define i3c_bus_for_each_i2cdev(bus, dev)				\
507 	list_for_each_entry(dev, &(bus)->devs.i2c, common.node)
508 
509 /**
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
513  *	 at each iteration of the loop
514  *
515  * Iterate over all I3C devs present on the bus.
516  */
517 #define i3c_bus_for_each_i3cdev(bus, dev)				\
518 	list_for_each_entry(dev, &(bus)->devs.i3c, common.node)
519 
520 int i3c_master_do_i2c_xfers(struct i3c_master_controller *master,
521 			    const struct i2c_msg *xfers,
522 			    int nxfers);
523 
524 int i3c_master_disec_locked(struct i3c_master_controller *master, u8 addr,
525 			    u8 evts);
526 int i3c_master_enec_locked(struct i3c_master_controller *master, u8 addr,
527 			   u8 evts);
528 int i3c_master_entdaa_locked(struct i3c_master_controller *master);
529 int i3c_master_defslvs_locked(struct i3c_master_controller *master);
530 
531 int i3c_master_get_free_addr(struct i3c_master_controller *master,
532 			     u8 start_addr);
533 
534 int i3c_master_add_i3c_dev_locked(struct i3c_master_controller *master,
535 				  u8 addr);
536 int i3c_master_do_daa(struct i3c_master_controller *master);
537 
538 int i3c_master_set_info(struct i3c_master_controller *master,
539 			const struct i3c_device_info *info);
540 
541 int i3c_master_register(struct i3c_master_controller *master,
542 			struct device *parent,
543 			const struct i3c_master_controller_ops *ops,
544 			bool secondary);
545 void i3c_master_unregister(struct i3c_master_controller *master);
546 
547 /**
548  * i3c_dev_get_master_data() - get master private data attached to an I3C
549  *			       device descriptor
550  * @dev: the I3C device descriptor to get private data from
551  *
552  * Return: the private data previously attached with i3c_dev_set_master_data()
553  *	   or NULL if no data has been attached to the device.
554  */
i3c_dev_get_master_data(const struct i3c_dev_desc * dev)555 static inline void *i3c_dev_get_master_data(const struct i3c_dev_desc *dev)
556 {
557 	return dev->common.master_priv;
558 }
559 
560 /**
561  * i3c_dev_set_master_data() - attach master private data to an I3C device
562  *			       descriptor
563  * @dev: the I3C device descriptor to attach private data to
564  * @data: private data
565  *
566  * This functions allows a master controller to attach per-device private data
567  * which can then be retrieved with i3c_dev_get_master_data().
568  */
i3c_dev_set_master_data(struct i3c_dev_desc * dev,void * data)569 static inline void i3c_dev_set_master_data(struct i3c_dev_desc *dev,
570 					   void *data)
571 {
572 	dev->common.master_priv = data;
573 }
574 
575 /**
576  * i2c_dev_get_master_data() - get master private data attached to an I2C
577  *			       device descriptor
578  * @dev: the I2C device descriptor to get private data from
579  *
580  * Return: the private data previously attached with i2c_dev_set_master_data()
581  *	   or NULL if no data has been attached to the device.
582  */
i2c_dev_get_master_data(const struct i2c_dev_desc * dev)583 static inline void *i2c_dev_get_master_data(const struct i2c_dev_desc *dev)
584 {
585 	return dev->common.master_priv;
586 }
587 
588 /**
589  * i2c_dev_set_master_data() - attach master private data to an I2C device
590  *			       descriptor
591  * @dev: the I2C device descriptor to attach private data to
592  * @data: private data
593  *
594  * This functions allows a master controller to attach per-device private data
595  * which can then be retrieved with i2c_device_get_master_data().
596  */
i2c_dev_set_master_data(struct i2c_dev_desc * dev,void * data)597 static inline void i2c_dev_set_master_data(struct i2c_dev_desc *dev,
598 					   void *data)
599 {
600 	dev->common.master_priv = data;
601 }
602 
603 /**
604  * i3c_dev_get_master() - get master used to communicate with a device
605  * @dev: I3C dev
606  *
607  * Return: the master controller driving @dev
608  */
609 static inline struct i3c_master_controller *
i3c_dev_get_master(struct i3c_dev_desc * dev)610 i3c_dev_get_master(struct i3c_dev_desc *dev)
611 {
612 	return dev->common.master;
613 }
614 
615 /**
616  * i2c_dev_get_master() - get master used to communicate with a device
617  * @dev: I2C dev
618  *
619  * Return: the master controller driving @dev
620  */
621 static inline struct i3c_master_controller *
i2c_dev_get_master(struct i2c_dev_desc * dev)622 i2c_dev_get_master(struct i2c_dev_desc *dev)
623 {
624 	return dev->common.master;
625 }
626 
627 /**
628  * i3c_master_get_bus() - get the bus attached to a master
629  * @master: master object
630  *
631  * Return: the I3C bus @master is connected to
632  */
633 static inline struct i3c_bus *
i3c_master_get_bus(struct i3c_master_controller * master)634 i3c_master_get_bus(struct i3c_master_controller *master)
635 {
636 	return &master->bus;
637 }
638 
639 struct i3c_generic_ibi_pool;
640 
641 struct i3c_generic_ibi_pool *
642 i3c_generic_ibi_alloc_pool(struct i3c_dev_desc *dev,
643 			   const struct i3c_ibi_setup *req);
644 void i3c_generic_ibi_free_pool(struct i3c_generic_ibi_pool *pool);
645 
646 struct i3c_ibi_slot *
647 i3c_generic_ibi_get_free_slot(struct i3c_generic_ibi_pool *pool);
648 void i3c_generic_ibi_recycle_slot(struct i3c_generic_ibi_pool *pool,
649 				  struct i3c_ibi_slot *slot);
650 
651 void i3c_master_queue_ibi(struct i3c_dev_desc *dev, struct i3c_ibi_slot *slot);
652 
653 struct i3c_ibi_slot *i3c_master_get_free_ibi_slot(struct i3c_dev_desc *dev);
654 
655 #endif /* I3C_MASTER_H */
656