samples: i2c: rtio: add i2c_rtio_loopback sample

Add sample which clearly and thorougly shows how to use RTIO with
I2C controllers, both synchronously and async, comparing it with
the "standard" I2C API, in an controlled environment. Both the I2C
controller and I2C target are managed by the sample, using loopback
to monitor and control the I2C transfers.

Signed-off-by: Bjarki Arge Andreasen <[email protected]>

Author: bjarki-andreasen

samples/drivers/i2c/rtio_loopback/CMakeLists.txt

@@ -0,0 +1,9 @@
+# Copyright (c) 2024 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(i2c_rtio_loopback)
+
+FILE(GLOB app_sources src/*.c)
+target_sources(app PRIVATE ${app_sources})

samples/drivers/i2c/rtio_loopback/README.rst

@@ -0,0 +1,50 @@
+.. zephyr:code-sample:: i2c-rtio-loopback
+   :name: I2C RTIO loopback
+   :relevant-api: rtio i2c_interface
+
+   Perform I2C transfers between I2C controller and custom I2C target using RTIO.
+
+Overview
+********
+
+This sample demonstrates how to perform I2C transfers, synchronously and async
+using RTIO. It uses up to two I2C controllers, acting as I2C controller and
+target.
+
+Requirements
+************
+
+This sample requires either:
+
+* Two I2C controllers, one supporting the I2C controller role, one supporting the
+  I2C peripheral role, both connected to the same I2C bus.
+* An I2C controller supporting both I2C controller and peripheral role
+  simultaneously.
+
+.. note::
+
+   Remember to set up the I2C bus, connecting SCL and SDA pull-up resistors, and
+   connecting the relevant I2C controllers to the bus physically.
+
+Board support
+*************
+
+Any board which meets the requirements must use an overlay to specify which
+I2C controller will act as the controller, and which as the peripheral, note
+that this could be the same controller. This is done using the devicetree
+aliases ``i2c-controller`` and ``i2c-controller-target`` respectively:
+
+.. code-block:: devicetree
+
+   / {
+           aliases {
+                   i2c-controller = &i2c1;
+                   i2c-controller-target = &i2c2;
+           };
+   };
+
+If necessary, add any board specific configs to the board specific overlay:
+
+.. code-block:: cfg
+
+   CONFIG_I2C_TARGET_BUFFER_MODE=y

samples/drivers/i2c/rtio_loopback/boards/b_u585i_iot02a.conf

@@ -0,0 +1 @@
+CONFIG_I2C_STM32_INTERRUPT=y

samples/drivers/i2c/rtio_loopback/boards/b_u585i_iot02a.overlay

@@ -0,0 +1,18 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+
+/* I2C bus pins are exposed on the STMod+.
+ *
+ *  Bus        SDA               SCL
+ *          Pin   Hdr         Pin   Hdr
+ *  i2c1    PB9   CN3:10      PB8  CN3:7
+ *  i2c2    PH5   CN2:10      PH4  CN2:7
+ *
+ * Short Pin PB9 to PH5, and PB8 to PH4, for the test to pass.
+ */
+
+/ {
+	aliases {
+		i2c-controller = &i2c1;
+		i2c-controller-target = &i2c2;
+	};
+};

samples/drivers/i2c/rtio_loopback/prj.conf

@@ -0,0 +1,8 @@
+# Copyright (c) 2024 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+CONFIG_I2C=y
+CONFIG_RTIO=y
+CONFIG_I2C_RTIO=y
+CONFIG_I2C_TARGET=y
+CONFIG_I2C_TARGET_BUFFER_MODE=y

samples/drivers/i2c/rtio_loopback/sample.yaml

@@ -0,0 +1,9 @@
+sample:
+  name: I2C RTIO loopback sample
+tests:
+  sample.drivers.i2c.rtio_loopback:
+    tags:
+      - rtio
+      - i2c_target
+    platform_allow:
+      - b_u585i_iot02a