[nrf fromlist] drivers: i2c_nrfx_twim: add asynchronous write and exclusive access API

This commit provides an extension to the i2c_nrfx_twim driver.
It introduces possibility to:
- acquire/release exclusive access to the i2c bus
- perform asynchronous i2c write transfers.

The provided API is necessary for use cases when, i2c transfers
must be started from interrupt context, while still allowing to
share the i2c bus in multi-tasking environment.

Upstream PR #: 86721

Signed-off-by: Andrzej Kuros <[email protected]>

Author: ankuns

drivers/i2c/i2c_nrfx_twim.c

@@ -5,6 +5,7 @@
  */
 
 #include <zephyr/drivers/i2c.h>
+#include <zephyr/drivers/i2c/i2c_nrfx_twim.h>
 #include <zephyr/dt-bindings/i2c/i2c.h>
 #include <zephyr/pm/device.h>
 #include <zephyr/pm/device_runtime.h>
@@ -31,8 +32,57 @@ struct i2c_nrfx_twim_data {
 	struct k_sem transfer_sync;
 	struct k_sem completion_sync;
 	volatile nrfx_err_t res;
+	i2c_nrfx_twim_async_transfer_handler_t async_transfer_handler;
+	void *async_transfer_handler_ctx;
 };
 
+int i2c_nrfx_twim_exclusive_access_acquire(const struct device *dev, k_timeout_t timeout)
+{
+	struct i2c_nrfx_twim_data *dev_data = dev->data;
+	int ret;
+
+	ret = k_sem_take(&dev_data->transfer_sync, timeout);
+
+	if (ret == 0) {
+		(void)pm_device_runtime_get(dev);
+	}
+
+	return ret;
+}
+
+void i2c_nrfx_twim_exclusive_access_release(const struct device *dev)
+{
+	struct i2c_nrfx_twim_data *dev_data = dev->data;
+
+	(void)pm_device_runtime_put(dev);
+
+	k_sem_give(&dev_data->transfer_sync);
+}
+
+int i2c_nrfx_twim_async_transfer_begin(const struct device *dev, struct i2c_msg *msg, uint16_t addr,
+				       i2c_nrfx_twim_async_transfer_handler_t handler, void *ctx)
+{
+	struct i2c_nrfx_twim_data *dev_data = dev->data;
+	const struct i2c_nrfx_twim_common_config *dev_config = dev->config;
+
+	if (I2C_MSG_ADDR_10_BITS & msg->flags) {
+		return -ENOTSUP;
+	}
+
+	if (!nrf_dma_accessible_check(&dev_config->twim, msg->buf)) {
+		return -ENOTSUP;
+	}
+
+	if (handler == NULL) {
+		return -ENOTSUP;
+	}
+
+	dev_data->async_transfer_handler = handler;
+	dev_data->async_transfer_handler_ctx = ctx;
+
+	return i2c_nrfx_twim_msg_transfer(dev, msg->flags, msg->buf, msg->len, addr);
+}
+
 static int i2c_nrfx_twim_transfer(const struct device *dev,
 				  struct i2c_msg *msgs,
 				  uint8_t num_msgs, uint16_t addr)
@@ -46,13 +96,11 @@ static int i2c_nrfx_twim_transfer(const struct device *dev,
 	uint8_t *buf;
 	uint16_t buf_len;
 
-	k_sem_take(&dev_data->transfer_sync, K_FOREVER);
+	(void)i2c_nrfx_twim_exclusive_access_acquire(dev, K_FOREVER);
 
 	/* Dummy take on completion_sync sem to be sure that it is empty */
 	k_sem_take(&dev_data->completion_sync, K_NO_WAIT);
 
-	(void)pm_device_runtime_get(dev);
-
 	for (size_t i = 0; i < num_msgs; i++) {
 		if (I2C_MSG_ADDR_10_BITS & msgs[i].flags) {
 			ret = -ENOTSUP;
@@ -164,9 +212,7 @@ static int i2c_nrfx_twim_transfer(const struct device *dev,
 		msg_buf_used = 0;
 	}
 
-	(void)pm_device_runtime_put(dev);
-
-	k_sem_give(&dev_data->transfer_sync);
+	i2c_nrfx_twim_exclusive_access_release(dev);
 
 	return ret;
 }
@@ -191,6 +237,15 @@ static void event_handler(nrfx_twim_evt_t const *p_event, void *p_context)
 		break;
 	}
 
+	if (dev_data->async_transfer_handler != NULL) {
+		i2c_nrfx_twim_async_transfer_handler_t handler = dev_data->async_transfer_handler;
+		void *ctx = dev_data->async_transfer_handler_ctx;
+
+		dev_data->async_transfer_handler = NULL;
+		handler(dev, dev_data->res == NRFX_SUCCESS ? 0 : -EIO, ctx);
+		return;
+	}
+
 	k_sem_give(&dev_data->completion_sync);
 }
 

include/zephyr/drivers/i2c/i2c_nrfx_twim.h

@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_INCLUDE_DRIVERS_I2C_NRFX_TWIM_H
+#define ZEPHYR_INCLUDE_DRIVERS_I2C_NRFX_TWIM_H
+
+#include <zephyr/kernel.h>
+#include <zephyr/drivers/i2c.h>
+
+/** @brief Acquires exclusive access to the i2c bus controller.
+ *
+ * @param dev      Pointer to the device structure for an I2C controller
+ *                 driver configured in controller mode.
+ * @param timeout  Timeout for waiting to acquire exclusive access.
+ *
+ * @retval 0       If successful.
+ * @retval -EBUSY  Returned without waiting.
+ * @retval -EAGAIN Waiting period timed out,
+ *                 or the underlying semaphore was reset during the waiting period.
+ */
+int i2c_nrfx_twim_exclusive_access_acquire(const struct device *dev, k_timeout_t timeout);
+
+/** @brief Releases exclusive access to the i2c bus controller.
+ *
+ * @param dev      Pointer to the device structure for an I2C controller
+ *                 driver on which @ref i2c_nrfx_twim_exclusive_access_acquire
+ *                 has been successfully called.
+ */
+void i2c_nrfx_twim_exclusive_access_release(const struct device *dev);
+
+/** @brief Type of callback that finishes an asynchronous transfer.
+ *
+ * @param  dev  Pointer to the device structure for an I2C controller driver.
+ * @param  res  Result of a transfer.
+ * @param  ctx  Opaque pointer for providing a context passed to
+ *              @ref i2c_nrfx_twim_async_transfer_begin .
+ */
+typedef void (*i2c_nrfx_twim_async_transfer_handler_t)(const struct device *dev, int res,
+						       void *ctx);
+
+/** @brief Begins an asynchronous write transfer on a I2C bus.
+ *
+ * @note This function may be called only when the exclusive access to the bus is granted.
+ *       See @ref i2c_nrfx_twim_exclusive_access_acquire .
+ *
+ * @param dev      Pointer to the device structure for an I2C controller
+ *                 driver configured in controller mode.
+ * @param msg      Message to transfer.
+ * @param addr     Address of the I2C target device.
+ * @param handler  Pointer to a callback function that will be called from an I2C
+ *                 interrupt handler that notifies end of the transfer.
+ * @param ctx      Opaque pointer passed to the @p handler for passing context.
+ *
+ * @return @c 0 on success, the @p handler will be called in future.
+ *         Other values indicate an error, the @p handler will not be called.
+ */
+int i2c_nrfx_twim_async_transfer_begin(const struct device *dev, struct i2c_msg *msg, uint16_t addr,
+				       i2c_nrfx_twim_async_transfer_handler_t handler, void *ctx);
+
+#endif /* ZEPHYR_INCLUDE_DRIVERS_I2C_NRFX_TWIM_H */