10  * SPDX-License-Identifier: Apache-2.0
27 #include <zephyr/device.h>
55 /** Device Tree specified speed */
65 /** Use 10-bit addressing. DEPRECATED - Use I2C_MSG_ADDR_10_BITS instead. */
78 	const struct device *bus;
89  * @param node_id Devicetree node identifier for the I2C device whose
103  * @param node_id Devicetree node identifier for the I2C device whose
117  * @param node_id Devicetree node identifier for the I2C device whose
160  * that follows a write, or vice-versa.  Some drivers will merge
165 /** Use 10-bit addressing for this message.
198  * @param dev I2C device which is notifying of transfer completion or error
199  * @param result Result code of the transfer request. 0 is success, -errno for failure.
202 typedef void (*i2c_callback_t)(const struct device *dev, int result, void *data);
212 typedef int (*i2c_api_configure_t)(const struct device *dev,
214 typedef int (*i2c_api_get_config_t)(const struct device *dev,
216 typedef int (*i2c_api_full_io_t)(const struct device *dev,
220 typedef int (*i2c_api_target_register_t)(const struct device *dev,
222 typedef int (*i2c_api_target_unregister_t)(const struct device *dev,
225 typedef int (*i2c_api_transfer_cb_t)(const struct device *dev,
236  * @brief Callback API for submitting work to a I2C device with RTIO
238 typedef void (*i2c_api_iodev_submit)(const struct device *dev,
242 typedef int (*i2c_api_recover_bus_t)(const struct device *dev);
259 typedef int (*i2c_target_api_register_t)(const struct device *dev);
260 typedef int (*i2c_target_api_unregister_t)(const struct device *dev);
271 /** Target device responds to 10-bit addressing. */
274 /** @brief Function called when a write to the device is initiated.
278  * with a particular device.
285  * device to which the operation is addressed.
292 /** @brief Function called when a write to the device is continued.
296  * device.
303  * device to which the operation is addressed.
313 /** @brief Function called when a read from the device is initiated.
317  * with a particular device.
325  * device to which the operation is addressed.
335 /** @brief Function called when a read from the device is continued.
339  * associated with the device device.
347  * device to which the operation is addressed.
358 /** @brief Function called when a write to the device is completed.
362  * buffer in an ongoing write operation to the device.
365  * device to which the operation is addressed.
374 /** @brief Function called when a read from the device is initiated.
378  * associated with the device.
386  * device to which the operation is addressed.
401  * start condition addressed to a particular device.
405  * associated with the device device.  After the function returns the
410  * device to which the operation is addressed.
434 /** @brief Structure describing a device that supports the I2C
439  * of a target device, respective.
442  * implements the device behavior prior to passing the object
449 	/** Flags for the target device defined by I2C_TARGET_FLAGS_* constants */
452 	/** Address for this target device */
470 	return device_is_ready(spec->bus);  in i2c_is_ready_dt()
482 	return (msg->flags & I2C_MSG_READ) == I2C_MSG_READ;  in i2c_is_read_op()
494 	return (msg->flags & I2C_MSG_STOP) == I2C_MSG_STOP;  in i2c_is_stop_op()
520  * @param addr Address of the I2C target device.
523 void i2c_dump_msgs_rw(const struct device *dev, const struct i2c_msg *msgs, uint8_t num_msgs,
538  * @param addr Address of the I2C target device.
540 static inline void i2c_dump_msgs(const struct device *dev, const struct i2c_msg *msgs,  in i2c_dump_msgs()
570  * @brief I2C specific device state which allows for i2c device class specific additions
580  * @param dev I2C device to update stats for
584 static inline void i2c_xfer_stats(const struct device *dev, struct i2c_msg *msgs,  in i2c_xfer_stats()
588 		CONTAINER_OF(dev->state, struct i2c_device_state, devstate);  in i2c_xfer_stats()
592 	STATS_INC(state->stats, transfer_call_count);  in i2c_xfer_stats()
593 	STATS_INCN(state->stats, message_count, num_msgs);  in i2c_xfer_stats()
601 	STATS_INCN(state->stats, bytes_read, bytes_read);  in i2c_xfer_stats()
602 	STATS_INCN(state->stats, bytes_written, bytes_written);  in i2c_xfer_stats()
608  * @brief Define a statically allocated and section assigned i2c device state
615  * @brief Define an i2c device init wrapper function
617  * This does device instance specific initialization of common data (such as stats)
621 	static inline int UTIL_CAT(dev_id, _init)(const struct device *dev) \
624 			CONTAINER_OF(dev->state, struct i2c_device_state, devstate); \
625 		stats_init(&state->stats.s_hdr, STATS_SIZE_32, 4,	\
627 		stats_register(dev->name, &(state->stats.s_hdr));	\
640  * @details Defines a device which implements the I2C API. May
648  * @param pm PM device resources reference (NULL if device does not use PM).
650  * @param data Pointer to the device's private data.
677 static inline void i2c_xfer_stats(const struct device *dev, struct i2c_msg *msgs,  in i2c_xfer_stats()
707  * @param dev Pointer to the device structure for the driver instance.
708  * @param dev_config Bit-packed 32-bit value to the device runtime configuration
712  * @retval -EIO General input / output error, failed to configure device.
714 __syscall int i2c_configure(const struct device *dev, uint32_t dev_config);
716 static inline int z_impl_i2c_configure(const struct device *dev,  in z_impl_i2c_configure()
720 		(const struct i2c_driver_api *)dev->api;  in z_impl_i2c_configure()
722 	return api->configure(dev, dev_config);  in z_impl_i2c_configure()
736  * @param dev Pointer to the device structure for the driver instance.
737  * @param dev_config Pointer to return bit-packed 32-bit value of
741  * @retval -EIO General input / output error.
742  * @retval -ERANGE Configured I2C frequency is invalid.
743  * @retval -ENOSYS If get config is not implemented
745 __syscall int i2c_get_config(const struct device *dev, uint32_t *dev_config);
747 static inline int z_impl_i2c_get_config(const struct device *dev, uint32_t *dev_config)  in z_impl_i2c_get_config()
749 	const struct i2c_driver_api *api = (const struct i2c_driver_api *)dev->api;  in z_impl_i2c_get_config()
751 	if (api->get_config == NULL) {  in z_impl_i2c_get_config()
752 		return -ENOSYS;  in z_impl_i2c_get_config()
755 	return api->get_config(dev, dev_config);  in z_impl_i2c_get_config()
759  * @brief Perform data transfer to another I2C device in controller mode.
762  * to another I2C device synchronously. Use i2c_read()/i2c_write()
774  * limitations on support for multi-message bus transactions.
780  * @param dev Pointer to the device structure for an I2C controller
784  * @param addr Address of the I2C target device.
787  * @retval -EIO General input / output error.
789 __syscall int i2c_transfer(const struct device *dev,
793 static inline int z_impl_i2c_transfer(const struct device *dev,  in z_impl_i2c_transfer()
798 		(const struct i2c_driver_api *)dev->api;  in z_impl_i2c_transfer()
805 		msgs[num_msgs - 1].flags |= I2C_MSG_STOP;  in z_impl_i2c_transfer()
808 	int res =  api->transfer(dev, msgs, num_msgs, addr);  in z_impl_i2c_transfer()
822  * @brief Perform data transfer to another I2C device in controller mode.
825  * to another I2C device asynchronously with a callback completion.
830  * @param dev Pointer to the device structure for an I2C controller
834  * @param addr Address of the I2C target device.
839  * @retval -EIO General input / output error.
840  * @retval -ENOSYS If transfer async is not implemented
841  * @retval -EWOULDBLOCK If the device is temporarily busy doing another transfer
843 static inline int i2c_transfer_cb(const struct device *dev,  in i2c_transfer_cb()
851 		(const struct i2c_driver_api *)dev->api;  in i2c_transfer_cb()
853 	if (api->transfer_cb == NULL) {  in i2c_transfer_cb()
854 		return -ENOSYS;  in i2c_transfer_cb()
863 		msgs[num_msgs - 1].flags |= I2C_MSG_STOP;  in i2c_transfer_cb()
866 	return api->transfer_cb(dev, msgs, num_msgs, addr, cb, userdata);  in i2c_transfer_cb()
870  * @brief Perform data transfer to another I2C device in master mode asynchronously.
874  *     i2c_transfer_cb(spec->bus, msgs, num_msgs, spec->addr, cb, userdata);
890 	return i2c_transfer_cb(spec->bus, msgs, num_msgs, spec->addr, cb, userdata);  in i2c_transfer_cb_dt()
894  * @brief Write then read data from an I2C device asynchronously.
897  * it to me" transaction pair through a combined write-then-read bus
901  * @param dev Pointer to the device structure for an I2C controller
905  * @param addr Address of the I2C device
916 static inline int i2c_write_read_cb(const struct device *dev, struct i2c_msg *msgs,  in i2c_write_read_cb()
922 		return -EINVAL;  in i2c_write_read_cb()
937  * @brief Write then read data from an I2C device asynchronously.
941  *     i2c_write_read_cb(spec->bus, msgs, num_msgs,
942  *                    spec->addr, write_buf,
962 	return i2c_write_read_cb(spec->bus, msgs, num_msgs, spec->addr, write_buf, num_write,  in i2c_write_read_cb_dt()
969 void z_i2c_transfer_signal_cb(const struct device *dev, int result, void *userdata);
973  * @brief Perform data transfer to another I2C device in controller mode.
976  * to another I2C device asynchronously with a k_poll_signal completion.
981  * @param dev Pointer to the device structure for an I2C controller
985  * @param addr Address of the I2C target device.
989  * @retval -EIO General input / output error.
990  * @retval -ENOSYS If transfer async is not implemented
991  * @retval -EWOULDBLOCK If the device is temporarily busy doing another transfer
993 static inline int i2c_transfer_signal(const struct device *dev,  in i2c_transfer_signal()
999 	const struct i2c_driver_api *api = (const struct i2c_driver_api *)dev->api;  in i2c_transfer_signal()
1001 	if (api->transfer_cb == NULL) {  in i2c_transfer_signal()
1002 		return -ENOSYS;  in i2c_transfer_signal()
1005 	return api->transfer_cb(dev, msgs, num_msgs, addr, z_i2c_transfer_signal_cb, sig);  in i2c_transfer_signal()
1021  * @param dev Pointer to the device structure for an I2C controller driver.
1025 void i2c_iodev_submit_fallback(const struct device *dev, struct rtio_iodev_sqe *iodev_sqe);
1028  * @brief Submit request(s) to an I2C device with RTIO
1035 	const struct i2c_dt_spec *dt_spec = (const struct i2c_dt_spec *)iodev_sqe->sqe.iodev->data;  in i2c_iodev_submit()
1036 	const struct device *dev = dt_spec->bus;  in i2c_iodev_submit()
1037 	const struct i2c_driver_api *api = (const struct i2c_driver_api *)dev->api;  in i2c_iodev_submit()
1039 	if (api->iodev_submit == NULL) {  in i2c_iodev_submit()
1040 		rtio_iodev_sqe_err(iodev_sqe, -ENOSYS);  in i2c_iodev_submit()
1043 	api->iodev_submit(dt_spec->bus, iodev_sqe);  in i2c_iodev_submit()
1063  * @brief Define an iodev for a given i2c device on a bus
1098  * @brief Perform data transfer to another I2C device in controller mode.
1102  *     i2c_transfer(spec->bus, msgs, num_msgs, spec->addr);
1113 	return i2c_transfer(spec->bus, msgs, num_msgs, spec->addr);  in i2c_transfer_dt()
1121  * @param dev Pointer to the device structure for an I2C controller
1124  * @retval -EBUSY If bus is not clear after recovery attempt.
1125  * @retval -EIO General input / output error.
1126  * @retval -ENOSYS If bus recovery is not implemented
1128 __syscall int i2c_recover_bus(const struct device *dev);
1130 static inline int z_impl_i2c_recover_bus(const struct device *dev)  in z_impl_i2c_recover_bus()
1133 		(const struct i2c_driver_api *)dev->api;  in z_impl_i2c_recover_bus()
1135 	if (api->recover_bus == NULL) {  in z_impl_i2c_recover_bus()
1136 		return -ENOSYS;  in z_impl_i2c_recover_bus()
1139 	return api->recover_bus(dev);  in z_impl_i2c_recover_bus()
1143  * @brief Registers the provided config as Target device of a controller.
1148  * struct member. Addressing mode - 7 or 10 bit - depends on the 'flags'
1150  * onto I2C target device driver via a set of callback functions provided in
1156  * @param dev Pointer to the device structure for an I2C controller
1162  * @retval -EINVAL If parameters are invalid
1163  * @retval -EIO General input / output error.
1164  * @retval -ENOSYS If target mode is not implemented
1166 static inline int i2c_target_register(const struct device *dev,  in i2c_target_register()
1170 		(const struct i2c_driver_api *)dev->api;  in i2c_target_register()
1172 	if (api->target_register == NULL) {  in i2c_target_register()
1173 		return -ENOSYS;  in i2c_target_register()
1176 	return api->target_register(dev, cfg);  in i2c_target_register()
1180  * @brief Unregisters the provided config as Target device
1186  * @param dev Pointer to the device structure for an I2C controller
1192  * @retval -EINVAL If parameters are invalid
1193  * @retval -ENOSYS If target mode is not implemented
1195 static inline int i2c_target_unregister(const struct device *dev,  in i2c_target_unregister()
1199 		(const struct i2c_driver_api *)dev->api;  in i2c_target_unregister()
1201 	if (api->target_unregister == NULL) {  in i2c_target_unregister()
1202 		return -ENOSYS;  in i2c_target_unregister()
1205 	return api->target_unregister(dev, cfg);  in i2c_target_unregister()
1209  * @brief Instructs the I2C Target device to register itself to the I2C Controller
1211  * This routine instructs the I2C Target device to register itself to the I2C
1214  * @param dev Pointer to the device structure for the I2C target
1215  * device (not itself an I2C controller).
1218  * @retval -EINVAL If parameters are invalid
1219  * @retval -EIO General input / output error.
1221 __syscall int i2c_target_driver_register(const struct device *dev);
1223 static inline int z_impl_i2c_target_driver_register(const struct device *dev)  in z_impl_i2c_target_driver_register()
1226 		(const struct i2c_target_driver_api *)dev->api;  in z_impl_i2c_target_driver_register()
1228 	return api->driver_register(dev);  in z_impl_i2c_target_driver_register()
1232  * @brief Instructs the I2C Target device to unregister itself from the I2C
1235  * This routine instructs the I2C Target device to unregister itself from the I2C
1238  * @param dev Pointer to the device structure for the I2C target
1239  * device (not itself an I2C controller).
1242  * @retval -EINVAL If parameters are invalid
1244 __syscall int i2c_target_driver_unregister(const struct device *dev);
1246 static inline int z_impl_i2c_target_driver_unregister(const struct device *dev)  in z_impl_i2c_target_driver_unregister()
1249 		(const struct i2c_target_driver_api *)dev->api;  in z_impl_i2c_target_driver_unregister()
1251 	return api->driver_unregister(dev);  in z_impl_i2c_target_driver_unregister()
1255  * Derived i2c APIs -- all implemented in terms of i2c_transfer()
1259  * @brief Write a set amount of data to an I2C device.
1263  * @param dev Pointer to the device structure for an I2C controller
1267  * @param addr Address to the target I2C device for writing.
1270  * @retval -EIO General input / output error.
1272 static inline int i2c_write(const struct device *dev, const uint8_t *buf,  in i2c_write()
1285  * @brief Write a set amount of data to an I2C device.
1289  *     i2c_write(spec->bus, buf, num_bytes, spec->addr);
1300 	return i2c_write(spec->bus, buf, num_bytes, spec->addr);  in i2c_write_dt()
1304  * @brief Read a set amount of data from an I2C device.
1308  * @param dev Pointer to the device structure for an I2C controller
1312  * @param addr Address of the I2C device being read.
1315  * @retval -EIO General input / output error.
1317 static inline int i2c_read(const struct device *dev, uint8_t *buf,  in i2c_read()
1330  * @brief Read a set amount of data from an I2C device.
1334  *     i2c_read(spec->bus, buf, num_bytes, spec->addr);
1345 	return i2c_read(spec->bus, buf, num_bytes, spec->addr);  in i2c_read_dt()
1349  * @brief Write then read data from an I2C device.
1352  * it to me" transaction pair through a combined write-then-read bus
1355  * @param dev Pointer to the device structure for an I2C controller
1357  * @param addr Address of the I2C device
1366 static inline int i2c_write_read(const struct device *dev, uint16_t addr,  in i2c_write_read()
1384  * @brief Write then read data from an I2C device.
1388  *     i2c_write_read(spec->bus, spec->addr,
1404 	return i2c_write_read(spec->bus, spec->addr,  in i2c_write_read_dt()
1410  * @brief Read multiple bytes from an internal address of an I2C device.
1413  * I2C device synchronously.
1417  * @param dev Pointer to the device structure for an I2C controller
1419  * @param dev_addr Address of the I2C device for reading.
1425  * @retval -EIO General input / output error.
1427 static inline int i2c_burst_read(const struct device *dev,  in i2c_burst_read()
1439  * @brief Read multiple bytes from an internal address of an I2C device.
1443  *     i2c_burst_read(spec->bus, spec->addr, start_addr, buf, num_bytes);
1457 	return i2c_burst_read(spec->bus, spec->addr,  in i2c_burst_read_dt()
1462  * @brief Write multiple bytes to an internal address of an I2C device.
1465  * I2C device synchronously.
1469  * portable by replacing them with calls to i2c_write() passing a
1472  * @param dev Pointer to the device structure for an I2C controller
1474  * @param dev_addr Address of the I2C device for writing.
1480  * @retval -EIO General input / output error.
1482 static inline int i2c_burst_write(const struct device *dev,  in i2c_burst_write()
1502  * @brief Write multiple bytes to an internal address of an I2C device.
1506  *     i2c_burst_write(spec->bus, spec->addr, start_addr, buf, num_bytes);
1520 	return i2c_burst_write(spec->bus, spec->addr,  in i2c_burst_write_dt()
1525  * @brief Read internal register of an I2C device.
1527  * This routine reads the value of an 8-bit internal register of an I2C
1528  * device synchronously.
1530  * @param dev Pointer to the device structure for an I2C controller
1532  * @param dev_addr Address of the I2C device for reading.
1537  * @retval -EIO General input / output error.
1539 static inline int i2c_reg_read_byte(const struct device *dev,  in i2c_reg_read_byte()
1549  * @brief Read internal register of an I2C device.
1553  *     i2c_reg_read_byte(spec->bus, spec->addr, reg_addr, value);
1564 	return i2c_reg_read_byte(spec->bus, spec->addr, reg_addr, value);  in i2c_reg_read_byte_dt()
1568  * @brief Write internal register of an I2C device.
1570  * This routine writes a value to an 8-bit internal register of an I2C
1571  * device synchronously.
1576  * @param dev Pointer to the device structure for an I2C controller
1578  * @param dev_addr Address of the I2C device for writing.
1583  * @retval -EIO General input / output error.
1585 static inline int i2c_reg_write_byte(const struct device *dev,  in i2c_reg_write_byte()
1595  * @brief Write internal register of an I2C device.
1599  *     i2c_reg_write_byte(spec->bus, spec->addr, reg_addr, value);
1610 	return i2c_reg_write_byte(spec->bus, spec->addr, reg_addr, value);  in i2c_reg_write_byte_dt()
1614  * @brief Update internal register of an I2C device.
1616  * This routine updates the value of a set of bits from an 8-bit internal
1617  * register of an I2C device synchronously.
1622  * @param dev Pointer to the device structure for an I2C controller
1624  * @param dev_addr Address of the I2C device for updating.
1630  * @retval -EIO General input / output error.
1632 static inline int i2c_reg_update_byte(const struct device *dev,  in i2c_reg_update_byte()
1654  * @brief Update internal register of an I2C device.
1658  *     i2c_reg_update_byte(spec->bus, spec->addr, reg_addr, mask, value);
1671 	return i2c_reg_update_byte(spec->bus, spec->addr,  in i2c_reg_update_byte_dt()