include/linux/i3c/master.h

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