I3C master controller driver API — The Linux Kernel documentation
The Linux Kernel 7.4.0-rc3 Quick search Contents Working with the development community Development process Submitting patches Code of conduct Maintainer handbook All development-process docs Internal API manuals Core API Driver APIs General information for driver authors Useful support libraries Bus-level documentation Auxiliary Bus Compute Express Link EISA bus support Firewire (IEEE 1394) driver Interface Guide I3C subsystem ISA Drivers MEN Chameleon Bus The Linux PCI driver implementer’s API guide The Linux RapidIO Subsystem Linux kernel SLIMbus support Linux USB API Virtio VME Device Drivers W1: Dallas’ 1-wire bus Xillybus driver for generic FPGA interface Subsystem-specific APIs Subsystems Locking Development tools and processes Licensing rules Writing documentation Development tools Testing guide Hacking guide Tracing Fault injection Livepatching Rust User-oriented documentation Administration Build system Reporting issues Userspace tools Userspace API Firmware-related documentation Firmware Firmware and Devicetree Architecture-specific documentation CPU architectures Other documentation Unsorted documentation Translations Translations This Page Show Source I3C master controller driver API ¶ void i3c_bus_maintenance_lock ( struct i3c_bus * bus ) ¶ Lock the bus for a maintenance operation Parameters struct i3c_bus *bus I3C bus to take the lock on Description This function takes the bus lock so that no other operations can occur on the bus.
This is needed for all kind of bus maintenance operation, like - enabling/disabling slave events - re-triggering DAA - changing the dynamic address of a device - relinquishing mastership - ... The reason for this kind of locking is that we don’t want drivers and core logic to rely on I3C device information that could be changed behind their back. void i3c_bus_maintenance_unlock ( struct i3c_bus * bus ) ¶ Release the bus lock after a maintenance operation Parameters struct i3c_bus *bus I3C bus to release the lock on Description Should be called when the bus maintenance operation is done.
See i3c_bus_maintenance_lock() for more details on what these maintenance operations are. void i3c_bus_normaluse_lock ( struct i3c_bus * bus ) ¶ Lock the bus for a normal operation Parameters struct i3c_bus *bus I3C bus to take the lock on Description This function takes the bus lock for any operation that is not a maintenance operation (see i3c_bus_maintenance_lock() for a non-exhaustive list of maintenance operations).
Basically all communications with I3C devices are normal operations (HDR, SDR transfers or CCC commands that do not change bus state or I3C dynamic address). Note that this lock is not guaranteeing serialization of normal operations. In other words, transfer requests passed to the I3C master can be submitted in parallel and I3C master drivers have to use their own locking to make sure two different communications are not inter-mixed, or access to the output/input queue is not done while the engine is busy. void i3c_bus_normaluse_unlock ( struct i3c_bus * bus ) ¶ Release the bus lock after a normal operation Parameters struct i3c_bus *bus I3C bus to release the lock on Description Should be called when a normal operation is done.
See i3c_bus_normaluse_lock() for more details on what these normal operations are. enum i3c_addr_slot_status i3c_bus_get_addr_slot_status ( struct i3c_bus * bus , u16 addr ) ¶ Get I3C bus address slot status Parameters struct i3c_bus *bus I3C bus. u16 addr I3C address to query. Return Address slot status for addr . void i3c_bus_set_addr_slot_status ( struct i3c_bus * bus , u16 addr , enum i3c_addr_slot_status status ) ¶ Set I3C bus address slot status Parameters struct i3c_bus *bus I3C bus. u16 addr I3C address to update. enum i3c_addr_slot_status status Address slot status to set. void i3c_master_queue_hotjoin ( struct i3c_master_controller * master ) ¶ Queue DAA processing after a Hot-Join event Parameters struct i3c_master_controller *master I3C master object Description Queue the hot-join worker on the master’s workqueue. u32 i3c_dev_supported_xfer_modes_locked ( struct i3c_dev_desc * dev ) ¶ Get the transfer modes usable with a device Parameters struct i3c_dev_desc *dev I3C device descriptor Description The HDR Modes the controller and dev both support, restricted to those the bus configuration allows.
SDR is always supported. The bus lock must be held in normal use mode. Return a bit mask of enum i3c_xfer_mode values. int i3c_master_send_ccc_cmd_locked ( struct i3c_master_controller * master , struct i3c_ccc_cmd * cmd ) ¶ send a CCC (Common Command Codes) Parameters struct i3c_master_controller *master master used to send frames on the bus struct i3c_ccc_cmd *cmd command to send Return 0 in case of success, or a negative error code otherwise.
I3C Mx error codes are stored in cmd->err. int i3c_master_get_free_addr ( struct i3c_master_controller * master , u8 start_addr ) ¶ get a free address on the bus Parameters struct i3c_master_controller *master I3C master object u8 start_addr where to start searching Description This function must be called with the bus lock held in write mode. Return the first free address starting at start_addr (included) or -ENOMEM if there’s no more address available. int i3c_master_setaasa_locked ( struct i3c_master_controller * master ) ¶ start a SETAASA procedure (Set All Addresses to Static Address) Parameters struct i3c_master_controller *master I3C master object Description Send a SETAASA CCC command to set all attached I3C devices’ dynamic addresses to their static address.
This function must be called with the bus lock held in write mode. First, the SETHID CCC command is sent, followed by the SETAASA CCC. Return 0 in case of success, a positive I3C error code if the error is one of the official Mx error codes, and a negative error code otherwise. int i3c_master_entdaa_locked ( struct i3c_master_controller * master ) ¶ start a DAA (Dynamic Address Assignment) procedure Parameters struct i3c_master_controller *master master used to send frames on the bus Description Send a ENTDAA CCC command to start a DAA procedure.
Note that this function only sends the ENTDAA CCC command, all the logic behind dynamic address assignment has to be handled in the I3C master driver. This function must be called with the bus lock held in write mode. Return 0 in case of success, or a negative error code otherwise. int i3c_master_enec_disec_locked ( struct i3c_master_controller * master , u8 addr , bool enable , u8 evts , bool suppress_m2 ) ¶ send an ENEC or DISEC CCC command Parameters struct i3c_master_controller *master master used to send frames on the bus u8 addr a valid I3C slave address or I3C_BROADCAST_ADDR bool enable true to send ENEC, false to send DISEC u8 evts events to enable or disable bool suppress_m2 if true, treat an M2 (NACK) error from the CCC as success Description Send an ENEC or DISEC CCC command to enable or disable some or all events coming from a specific slave, or all devices if addr is I3C_BROADCAST_ADDR .
When suppress_m2 is true, a NACK of the broadcast (which can happen when no devices are present on the bus) is not reported as an error. This is useful for callers that want to configure event reporting unconditionally, regardless of whether any devices are currently on the bus. This function must be called with the bus lock held in write mode. Return 0 in case of success, or a negative error code otherwise. int i3c_master_disec_locked ( struct i3c_master_controller * master , u8 addr , u8 evts ) ¶ send a DISEC CCC command Parameters struct i3c_master_controller *master master used to send frames on the bus u8 addr a valid I3C slave address or I3C_BROADCAST_ADDR u8 evts events to disable Description Send a DISEC CCC command to disable some or all events coming from a specific slave, or all devices if addr is I3C_BROADCAST_ADDR .
This function must be called with the bus lock held in write mode. Return 0 in case
The rest of this page is on the live site.