5  * SPDX-License-Identifier: Apache-2.0
29 #include <zephyr/drivers/i2c.h>
42  * - BCR[7:6]: Device Role
43  *   - 0: I3C Target
44  *   - 1: I3C Controller capable
45  *   - 2: Reserved
46  *   - 3: Reserved
48  * - BCR[5]: Advanced Capabilities
49  *   - 0: Does not support optional advanced capabilities.
50  *   - 1: Supports optional advanced capabilities which
53  * - BCR[4]: Virtual Target Support
54  *   - 0: Is not a virtual target.
55  *   - 1: Is a virtual target.
57  * - BCR[3]: Offline Capable
58  *   - 0: Will always response to I3C commands.
59  *   - 1: Will not always response to I3C commands.
61  * - BCR[2]: IBI Payload
62  *   - 0: No data bytes following the accepted IBI.
63  *   - 1: One data byte (MDB, Mandatory Data Byte) follows
67  * - BCR[1]: IBI Request Capable
68  *   - 0: Not capable
69  *   - 1: Capable
71  * - BCR[0]: Max Data Speed Limitation
72  *   - 0: No Limitation
73  *   - 1: Limitation obtained via GETMXDS CCC.
82  * 0 - No Limitation.
83  * 1 - Limitation obtained via GETMXDS CCC.
93  * 0 - No data bytes following the accepted IBI.
94  * 1 - One data byte (MDB, Mandatory Data Byte) follows the accepted IBI.
102  * 0 - Will always respond to I3C commands.
103  * 1 - Will not always respond to I3C commands.
110  * 0 - Is not a virtual target.
111  * 1 - Is a virtual target.
118  * 0 - Does not support optional advanced capabilities.
119  * 1 - Supports optional advanced capabilities which can be viewed via
124 /** Device Role - I3C Target. */
127 /** Device Role - I3C Controller Capable. */
150  * - LVR[7:5]: I2C device index:
151  *   - 0: I2C device has a 50 ns spike filter where
152  *        it is not affected by high frequency on SCL.
153  *   - 1: I2C device does not have a 50 ns spike filter
154  *        but can work with high frequency on SCL.
155  *   - 2: I2C device does not have a 50 ns spike filter
156  *        and cannot work with high frequency on SCL.
157  * - LVR[4]: I2C mode indicator:
158  *   - 0: FM+ mode
159  *   - 1: FM mode
160  * - LVR[3:0]: Reserved.
165 /** I2C FM+ Mode. */
168 /** I2C FM Mode. */
171 /** I2C Mode Indicator bitmask. */
175  * @brief I2C Mode
177  * Obtain I2C Mode value from the LVR value.
185  * @brief I2C Device Index 0.
187  * I2C device has a 50 ns spike filter where it is not affected by high
188  * frequency on SCL.
193  * @brief I2C Device Index 1.
195  * I2C device does not have a 50 ns spike filter but can work with high
196  * frequency on SCL.
201  * @brief I2C Device Index 2.
203  * I2C device does not have a 50 ns spike filter and cannot work with high
204  * frequency on SCL.
208 /** I2C Device Index bitmask. */
212  * @brief I2C Device Index
214  * Obtain I2C Device Index value from the LVR value.
231 	 * Both I3C and legacy I2C devices are on the bus.
232 	 * The I2C devices have 50ns spike filter on SCL.
237 	 * Both I3C and legacy I2C devices are on the bus.
238 	 * The I2C devices do not have 50ns spike filter on SCL
239 	 * and can tolerate maximum SDR SCL clock frequency.
244 	 * Both I3C and legacy I2C devices are on the bus.
245 	 * The I2C devices do not have 50ns spike filter on SCL
246 	 * but cannot tolerate maximum SDR SCL clock frequency.
255  * @brief I2C bus speed under I3C bus.
257  * Only FM and FM+ modes are supported for I2C devices under I3C bus.
260 	/** I2C FM mode */
263 	/** I2C FM+ mode */
279 	/** High Data Rate - Double Data Rate messaging */
282 	/** High Data Rate - Ternary Symbol Legacy-inclusive-Bus */
285 	/** High Data Rate - Ternary Symbol for Pure Bus */
288 	/** High Data Rate - Bulk Transport */
404  * that follows a write, or vice-versa.  Some drivers will merge
440 /** I3C HDR-DDR (Double Data Rate) */
443 /** I3C HDR-TSP (Ternary Symbol Pure-bus) */
446 /** I3C HDR-TSL (Ternary Symbol Legacy-inclusive-bus) */
449 /** I3C HDR-BT (Bulk Transport) */
500 	/** HDR command code field (7-bit) for HDR-DDR, HDR-TSP and HDR-TSL */
526 		/** SCL frequency (in Hz) for I3C transfers. */
529 		/** SCL frequency (in Hz) for I2C transfers. */
530 		uint32_t i2c;  member
531 	} scl;  member
534 	 * Bit mask of supported HDR modes (0 - 7).
581 	 * For backward compatibility to I2C API.
682 	 * I2C Device Attach
697 	 * I2C Device Detach
773 	 * Raise In-Band Interrupt (IBI).
918  * - i3c_device_register() to tell the controller of a target device.
919  * - i3c_transfers() to initiate data transfers between controller and
958 	 * This is specified in the device tree property "assigned-address"
979 	 * - During Dynamic Address Assignment (during ENTDAA)
980 	 * - Reset Dynamic Address Assignment (RSTDAA)
981 	 * - Set All Addresses to Static Addresses (SETAASA)
982 	 * - Set New Dynamic Address (SETNEWDA)
983 	 * - Set Dynamic Address from Static Address (SETDASA)
992 	 * - Reset Group Address(es) (RSTGRPA)
993 	 * - Set Group Address (SETGRPA)
1042 			 * - Bit[0]: HDR-DDR
1043 			 * - Bit[1]: HDR-TSP
1044 			 * - Bit[2]: HDR-TSL
1045 			 * - Bit[7:3]: Reserved
1051 			 * - Bit[0]: HDR-DDR
1052 			 * - Bit[1]: HDR-TSP
1053 			 * - Bit[2]: HDR-TSL
1054 			 * - Bit[3]: HDR-BT
1055 			 * - Bit[7:4]: Reserved
1062 		 * - Bit[3:0]: I3C 1.x Specification Version
1063 		 * - Bit[5:4]: Group Address Capabilities
1064 		 * - Bit[6]: HDR-DDR Write Abort
1065 		 * - Bit[7]: HDR-DDR Abort CRC
1071 		 * - Bit[0]: Multi-Lane (ML) Data Transfer Support
1072 		 * - Bit[1]: Device to Device Transfer (D2DXFER) Support
1073 		 * - Bit[2]: Device to Device Transfer (D2DXFER) IBI Capable
1074 		 * - Bit[3]: Defining Byte Support in GETCAPS
1075 		 * - Bit[4]: Defining Byte Support in GETSTATUS
1076 		 * - Bit[5]: HDR-BT CRC-32 Support
1077 		 * - Bit[6]: IBI MDB Support for Pending Read Notification
1078 		 * - Bit[7]: Reserved
1084 		 * - Bit[7:0]: Reserved
1098 	 * In-Band Interrupt (IBI) callback.
1106  * @brief Structure describing a I2C device on I3C bus.
1110  * () i3c_i2c_device_register() to tell the controller of an I2C device.
1112  *    and I2C device.
1121 	/** I3C bus to which this I2C device is attached */
1124 	/** Static address for this I2C device. */
1144  * This contains slists of attached I3C and I2C devices.
1152 	 * - Aid in dynamic address assignment.
1153 	 * - Quick way to find out if a target address is
1154 	 *   a I3C or I2C device.
1165 		 * Linked list of attached I2C devices.
1167 		sys_slist_t i2c;  member
1174  * This contains arrays of known I3C and I2C devices.
1186 	 * Pointer to array of known I2C devices.
1188 	struct i3c_i2c_device_desc * const i2c;  member
1196 	 * Number of I2C devices in array.
1207 	/** I3C/I2C device list struct. */
1219 	/** Attached I3C/I2C devices and addresses */
1232 		&((struct i3c_driver_data *)(bus->data))->attached_dev.devices.i3c, desc, node)
1235  * @brief iterate over all I2C devices present on the bus
1238  * @param desc: an I2C device descriptor pointer updated to point to the current slot
1243 		&((struct i3c_driver_data *)(bus->data))->attached_dev.devices.i2c, desc, node)
1276  * @brief Find a I2C target device descriptor by address.
1278  * This finds the I2C target device descriptor in the attached
1284  * @return Pointer to the I2C target device descriptor, or
1297  * a preferred address (i.e. assigned-address in device tree,
1315  * device (for example, hot-join after device coming back from
1335  * @retval -ENODEV if no device matches the PID (@p pid) in
1337  * @retval -EINVAL if the device matching PID (@p pid) already
1357  * @retval -EINVAL If invalid configure parameters.
1358  * @retval -EIO General Input/Output errors.
1359  * @retval -ENOSYS If not implemented.
1365 		(const struct i3c_driver_api *)dev->api;  in i3c_configure()
1367 	if (api->configure == NULL) {  in i3c_configure()
1368 		return -ENOSYS;  in i3c_configure()
1371 	return api->configure(dev, type, config);  in i3c_configure()
1391  * @retval -EIO General Input/Output errors.
1392  * @retval -ENOSYS If not implemented.
1398 		(const struct i3c_driver_api *)dev->api;  in i3c_config_get()
1400 	if (api->config_get == NULL) {  in i3c_config_get()
1401 		return -ENOSYS;  in i3c_config_get()
1404 	return api->config_get(dev, type, config);  in i3c_config_get()
1413  * @retval -EBUSY If bus recovery fails.
1414  * @retval -EIO General input / output error.
1415  * @retval -ENOSYS Bus recovery is not supported by the controller driver.
1420 		(const struct i3c_driver_api *)dev->api;  in i3c_recover_bus()
1422 	if (api->recover_bus == NULL) {  in i3c_recover_bus()
1423 		return -ENOSYS;  in i3c_recover_bus()
1426 	return api->recover_bus(dev);  in i3c_recover_bus()
1438  * Use cases involving multiple writers to the i3c/i2c devices must prevent
1440  * being preempted or by using a mutex to govern writes to the i3c/i2c devices.
1445  * @retval -EINVAL If address is not available or if the device
1463  * Use cases involving multiple writers to the i3c/i2c devices must prevent
1465  * being preempted or by using a mutex to govern writes to the i3c/i2c devices.
1472  * @retval -EINVAL If address is not available
1486  * Use cases involving multiple writers to the i3c/i2c devices must prevent
1488  * being preempted or by using a mutex to govern writes to the i3c/i2c devices.
1493  * @retval -EINVAL If device is already detached
1498  * @brief Attach an I2C device
1500  * Called to attach a I2C device to the addresses. This will
1505  * Use cases involving multiple writers to the i3c/i2c devices must prevent
1507  * being preempted or by using a mutex to govern writes to the i3c/i2c devices.
1512  * @retval -EINVAL If address is not available or if the device
1518  * @brief Detach I2C Device
1520  * called to remove an I2C device and to free up the address
1525  * Use cases involving multiple writers to the i3c/i2c devices must prevent
1527  * being preempted or by using a mutex to govern writes to the i3c/i2c devices.
1532  * @retval -EINVAL If device is already detached
1551  * @retval -EBUSY Bus is busy.
1552  * @retval -EIO General input / output error.
1553  * @retval -ENODEV If a provisioned ID does not match to any target devices
1555  * @retval -ENOSPC No more free addresses can be assigned to target.
1556  * @retval -ENOSYS Dynamic address assignment is not supported by
1562 		(const struct i3c_driver_api *)dev->api;  in i3c_do_daa()
1564 	if (api->do_daa == NULL) {  in i3c_do_daa()
1565 		return -ENOSYS;  in i3c_do_daa()
1568 	return api->do_daa(dev);  in i3c_do_daa()
1579  * @retval -EBUSY Bus is busy.
1580  * @retval -EIO General Input / output error.
1581  * @retval -EINVAL Invalid valid set in the payload structure.
1582  * @retval -ENOSYS Not implemented.
1591 		(const struct i3c_driver_api *)dev->api;  in z_impl_i3c_do_ccc()
1593 	if (api->do_ccc == NULL) {  in z_impl_i3c_do_ccc()
1594 		return -ENOSYS;  in z_impl_i3c_do_ccc()
1597 	return api->do_ccc(dev, payload);  in z_impl_i3c_do_ccc()
1621  * limitations on support for multi-message bus transactions.
1628  * @retval -EBUSY Bus is busy.
1629  * @retval -EIO General input / output error.
1638 		(const struct i3c_driver_api *)target->bus->api;  in z_impl_i3c_transfer()
1640 	return api->i3c_xfers(target->bus, target, msgs, num_msgs);  in z_impl_i3c_transfer()
1664 		(const struct i3c_driver_api *)dev->api;  in i3c_device_find()
1666 	if (api->i3c_device_find == NULL) {  in i3c_device_find()
1670 	return api->i3c_device_find(dev, id);  in i3c_device_find()
1679  * @brief Raise an In-Band Interrupt (IBI).
1681  * This raises an In-Band Interrupt (IBI) to the active controller.
1687  * @retval -EIO General input / output error.
1693 		(const struct i3c_driver_api *)dev->api;  in i3c_ibi_raise()
1695 	if (api->ibi_raise == NULL) {  in i3c_ibi_raise()
1696 		return -ENOSYS;  in i3c_ibi_raise()
1699 	return api->ibi_raise(dev, request);  in i3c_ibi_raise()
1711  * @retval -EIO General Input / output error.
1712  * @retval -ENOMEM If these is no more empty entries in
1719 		(const struct i3c_driver_api *)target->bus->api;  in i3c_ibi_enable()
1721 	if (api->ibi_enable == NULL) {  in i3c_ibi_enable()
1722 		return -ENOSYS;  in i3c_ibi_enable()
1725 	return api->ibi_enable(target->bus, target);  in i3c_ibi_enable()
1737  * @retval -EIO General Input / output error.
1738  * @retval -ENODEV If IBI is not previously enabled for @p target.
1743 		(const struct i3c_driver_api *)target->bus->api;  in i3c_ibi_disable()
1745 	if (api->ibi_disable == NULL) {  in i3c_ibi_disable()
1746 		return -ENOSYS;  in i3c_ibi_disable()
1749 	return api->ibi_disable(target->bus, target);  in i3c_ibi_disable()
1765 	return (target->bcr & I3C_BCR_IBI_PAYLOAD_HAS_DATA_BYTE)  in i3c_ibi_has_payload()
1782 	return (target->bcr & I3C_BCR_IBI_REQUEST_CAPABLE)  in i3c_device_is_ibi_capable()
1799 	return I3C_BCR_DEVICE_ROLE(target->bcr)  in i3c_device_is_controller_capable()
1820  * @retval -EBUSY Bus is busy.
1821  * @retval -EIO General input / output error.
1847  * @retval -EBUSY Bus is busy.
1848  * @retval -EIO General input / output error.
1868  * it to me" transaction pair through a combined write-then-read bus
1878  * @retval -EBUSY Bus is busy.
1879  * @retval -EIO General input / output error.
1916  * @retval -EBUSY Bus is busy.
1917  * @retval -EIO General input / output error.
1946  * @retval -EBUSY Bus is busy.
1947  * @retval -EIO General input / output error.
1974  * This routine reads the value of an 8-bit internal register of an I3C target
1982  * @retval -EBUSY Bus is busy.
1983  * @retval -EIO General input / output error.
1996  * This routine writes a value to an 8-bit internal register of an I3C target
2007  * @retval -EBUSY Bus is busy.
2008  * @retval -EIO General input / output error.
2021  * This routine updates the value of a set of bits from an 8-bit internal
2033  * @retval -EBUSY Bus is busy.
2034  * @retval -EIO General input / output error.
2092  * @retval -EBUSY Bus is busy.
2093  * @retval -EIO General input / output error.
2094  * @retval -ENODEV If a provisioned ID does not match to any target devices
2096  * @retval -ENOSPC No more free addresses can be assigned to target.
2097  * @retval -ENOSYS Dynamic address assignment is not supported by
2120  * @retval -EIO General Input/Output error.
2144  * @retval -ENOMEM No memory to build the payload.
2145  * @retval -EIO General Input/Output error.
2177 		(const struct i3c_iodev_data *)iodev_sqe->sqe.iodev->data;  in i3c_iodev_submit()
2178 	const struct i3c_driver_api *api = (const struct i3c_driver_api *)data->bus->api;  in i3c_iodev_submit()
2180 	if (api->iodev_submit == NULL) {  in i3c_iodev_submit()
2181 		rtio_iodev_sqe_err(iodev_sqe, -ENOSYS);  in i3c_iodev_submit()
2184 	api->iodev_submit(data->bus, iodev_sqe);  in i3c_iodev_submit()
2231  * Include High-Data-Rate (HDR) inline helper functions