samples: mbox: Add mbox sample with data transfer

This commits add mbox sample which supports transfering of
4 bytes of data between cores.

Signed-off-by: Tomas Galbicka <tomas.galbicka@nxp.com>

samples/drivers/mbox_data/CMakeLists.txt

@@ -0,0 +1,29 @@
+# Copyright 2024 NXP
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+
+cmake_minimum_required(VERSION 3.20.0)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+
+set(REMOTE_ZEPHYR_DIR ${CMAKE_CURRENT_BINARY_DIR}/../remote/zephyr)
+
+if(("${BOARD}" STREQUAL "mimxrt1170_evkb_cm7") OR
+   ("${BOARD}" STREQUAL "mimxrt1170_evk_cm7") OR
+   ("${BOARD}" STREQUAL "mimxrt1160_evk_cm7"))
+  message(STATUS "${BOARD} compile as Main in this sample")
+else()
+  message(FATAL_ERROR "${BOARD} is not supported for this sample")
+endif()
+
+project(mbox_data_ipc)
+
+enable_language(C ASM)
+
+if(CONFIG_INCLUDE_REMOTE_DIR)
+  target_include_directories(zephyr_interface
+    INTERFACE ${REMOTE_ZEPHYR_DIR}/include/public)
+endif()
+
+target_sources(app PRIVATE src/main.c)

samples/drivers/mbox_data/Kconfig

@@ -0,0 +1,11 @@
+# Copyright 2024 NXP
+#
+# SPDX-License-Identifier: Apache-2.0
+
+source "Kconfig.zephyr"
+
+config INCLUDE_REMOTE_DIR
+	bool "Include remote core header directory"
+	help
+	  Include remote build header files. Can be used if primary image
+	  needs to be aware of size or base address of secondary image

samples/drivers/mbox_data/Kconfig.sysbuild

@@ -0,0 +1,11 @@
+# Copyright 2024 NXP
+#
+# SPDX-License-Identifier: Apache-2.0
+
+source "share/sysbuild/Kconfig"
+
+config REMOTE_BOARD
+string
+	default "mimxrt1170_evkb_cm4" if $(BOARD) = "mimxrt1170_evkb_cm7"
+	default "mimxrt1170_evk_cm4" if $(BOARD) = "mimxrt1170_evk_cm7"
+	default "mimxrt1160_evk_cm4" if $(BOARD) = "mimxrt1160_evk_cm7"

samples/drivers/mbox_data/README.rst

@@ -0,0 +1,95 @@
+.. zephyr:code-sample:: mbox_data
+   :name: MBOX Data
+   :relevant-api: mbox_interface
+
+   Perform inter-processor mailbox communication using the MBOX API with data.
+
+Overview
+********
+
+This sample demonstrates how to use the :ref:`MBOX API <mbox_api>` in data transfer mode.
+It can be used only with mbox driver which supports data transfer mode.
+
+Sample will ping-pong 4 bytes of data between two cores via two mbox channels.
+After each core receives data, it increments it by one and sends it back to other core.
+
+Building and Running
+********************
+
+The sample can be built and executed on boards supporting MBOX with data transfer mode.
+
+Building the application for mimxrt1160_evk_cm7
+===============================================
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/drivers/mbox_data/
+   :board: mimxrt1160_evk_cm7
+   :goals: debug
+   :west-args: --sysbuild
+
+Building the application for mimxrt1170_evk_cm7
+===============================================
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/drivers/mbox_data/
+   :board: mimxrt1170_evk_cm7
+   :goals: debug
+   :west-args: --sysbuild
+
+Building the application for mimxrt1170_evkb_cm7
+================================================
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/drivers/mbox_data/
+   :board: mimxrt1170_evkb_cm7
+   :goals: debug
+   :west-args: --sysbuild
+
+Sample Output
+=============
+
+Open a serial terminal (minicom, putty, etc.) and connect the board with the
+following settings:
+
+- Speed: 115200
+- Data: 8 bits
+- Parity: None
+- Stop bits: 1
+
+Reset the board and the following message will appear on the corresponding
+serial port, one is the main core another is the remote core:
+
+.. code-block:: console
+
+   *** Booting Zephyr OS build zephyr-v3.5.0-4051-g12f4f4dc8679 ***
+   mbox_data Client demo started
+   Client send (on channel 3) value: 0
+   Client received (on channel 2) value: 1
+   Client send (on channel 3) value: 2
+   Client received (on channel 2) value: 3
+   Client send (on channel 3) value: 4
+   ...
+   Client received (on channel 2) value: 95
+   Client send (on channel 3) value: 96
+   Client received (on channel 2) value: 97
+   Client send (on channel 3) value: 98
+   Client received (on channel 2) value: 99
+   mbox_data Client demo ended
+
+
+.. code-block:: console
+
+   *** Booting Zephyr OS build zephyr-v3.5.0-4051-g12f4f4dc8679 ***
+   mbox_data Server demo started
+   Server receive (on channel 3) value: 0
+   Server send (on channel 2) value: 1
+   Server receive (on channel 3) value: 2
+   Server send (on channel 2) value: 3
+   Server receive (on channel 3) value: 4
+   ...
+   Server send (on channel 2) value: 95
+   Server receive (on channel 3) value: 96
+   Server send (on channel 2) value: 97
+   Server receive (on channel 3) value: 98
+   Server send (on channel 2) value: 99
+   mbox_data Server demo ended.

samples/drivers/mbox_data/boards/mimxrt1160_evk_cm7.conf

@@ -0,0 +1,3 @@
+CONFIG_MBOX_NXP_IMX_MU=y
+CONFIG_INCLUDE_REMOTE_DIR=y
+CONFIG_SECOND_CORE_MCUX=y

samples/drivers/mbox_data/boards/mimxrt1160_evk_cm7.overlay

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2024 NXP
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/ {
+	chosen {
+		/* Delete ipc chosen property where old IPM mailbox driver bellow is
+		 * configured.
+		 */
+		/delete-property/ zephyr,ipc;
+	};
+
+	soc {
+		/* Delete IPM Driver node nxp,imx-mu */
+		/delete-node/ mailbox@40c48000;
+
+		/* Attach MBOX driver to MU Unit */
+		mbox:mbox@40c48000 {
+			compatible = "nxp,mbox-imx-mu";
+			reg = <0x40c48000 0x4000>;
+			interrupts = <118 0>;
+			rx-channels = <4>;
+			#mbox-cells = <1>;
+			status = "okay";
+		};
+	};
+};

samples/drivers/mbox_data/boards/mimxrt1170_evk_cm7.conf

@@ -0,0 +1,3 @@
+CONFIG_MBOX_NXP_IMX_MU=y
+CONFIG_INCLUDE_REMOTE_DIR=y
+CONFIG_SECOND_CORE_MCUX=y

samples/drivers/mbox_data/boards/mimxrt1170_evk_cm7.overlay

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2024 NXP
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/ {
+	chosen {
+		/* Delete ipc chosen property where old IPM mailbox driver bellow is
+		 * configured.
+		 */
+		/delete-property/ zephyr,ipc;
+	};
+
+	soc {
+		/* Delete IPM Driver node nxp,imx-mu */
+		/delete-node/ mailbox@40c48000;
+
+		/* Attach MBOX driver to MU Unit */
+		mbox:mbox@40c48000 {
+			compatible = "nxp,mbox-imx-mu";
+			reg = <0x40c48000 0x4000>;
+			interrupts = <118 0>;
+			rx-channels = <4>;
+			#mbox-cells = <1>;
+			status = "okay";
+		};
+	};
+};

samples/drivers/mbox_data/boards/mimxrt1170_evkb_cm7.conf

@@ -0,0 +1,3 @@
+CONFIG_MBOX_NXP_IMX_MU=y
+CONFIG_SECOND_CORE_MCUX=y
+CONFIG_INCLUDE_REMOTE_DIR=y

samples/drivers/mbox_data/boards/mimxrt1170_evkb_cm7.overlay

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2024 NXP
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/ {
+	chosen {
+		/* Delete ipc chosen property where old IPM mailbox driver bellow is
+		 * configured.
+		 */
+		/delete-property/ zephyr,ipc;
+	};
+
+	soc {
+		/* Delete IPM Driver node nxp,imx-mu */
+		/delete-node/ mailbox@40c48000;
+
+		/* Attach MBOX driver to MU Unit */
+		mbox:mbox@40c48000 {
+			compatible = "nxp,mbox-imx-mu";
+			reg = <0x40c48000 0x4000>;
+			interrupts = <118 0>;
+			rx-channels = <4>;
+			#mbox-cells = <1>;
+			status = "okay";
+		};
+	};
+};

samples/drivers/mbox_data/prj.conf

@@ -0,0 +1,2 @@
+CONFIG_PRINTK=y
+CONFIG_MBOX=y

samples/drivers/mbox_data/remote/CMakeLists.txt

@@ -0,0 +1,20 @@
+# Copyright 2024 NXP
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+
+cmake_minimum_required(VERSION 3.20.0)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+
+if(("${BOARD}" STREQUAL "mimxrt1170_evkb_cm4") OR
+  ("${BOARD}" STREQUAL "mimxrt1170_evk_cm4") OR
+  ("${BOARD}" STREQUAL "mimxrt1160_evk_cm4"))
+  message(STATUS "${BOARD} compile as remote in this sample")
+else()
+  message(FATAL_ERROR "${BOARD} is not supported for this sample")
+endif()
+
+project(mbox_data_ipc_remote)
+
+target_sources(app PRIVATE src/main.c)

samples/drivers/mbox_data/remote/boards/mimxrt1160_evk_cm4.conf

@@ -0,0 +1,4 @@
+CONFIG_MBOX_NXP_IMX_MU=y
+CONFIG_BUILD_OUTPUT_INFO_HEADER=y
+CONFIG_BUILD_OUTPUT_HEX=y
+CONFIG_SECOND_CORE_MCUX=y

samples/drivers/mbox_data/remote/boards/mimxrt1160_evk_cm4.overlay

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2024 NXP
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/ {
+	chosen {
+		zephyr,flash = &ocram;
+		zephyr,console = &lpuart2;
+		zephyr,shell-uart = &lpuart2;
+
+		/* Delete ipc chosen property where old IPM mailbox driver bellow is
+		 * configured.
+		 */
+		/delete-property/ zephyr,ipc;
+	};
+
+	soc {
+		/delete-node/ gpt@400f0000;
+
+		/* Replace GPT2 with another GPT kernel timer */
+		gpt2_hw_timer:gpt@400f0000 {
+			compatible = "nxp,gpt-hw-timer";
+			reg = <0x400f0000 0x4000>;
+			interrupts = <120 0>;
+			status = "okay";
+		};
+
+		/* Delete IPM Driver node nxp,imx-mu */
+		/delete-node/ mailbox@40c4c000;
+
+		/* Attach MBOX driver to MU Unit */
+		mbox:mbox@40c4c000 {
+			compatible = "nxp,mbox-imx-mu";
+			reg = <0x40c4c000 0x4000>;
+			interrupts = <118 0>;
+			rx-channels = <4>;
+			#mbox-cells = <1>;
+			status = "okay";
+		};
+	};
+};
+
+/* Enable secondary LPUART */
+&lpuart2 {
+	status = "okay";
+	current-speed = <115200>;
+};
+
+/* Disable primary GPT timer */
+&gpt_hw_timer {
+	status = "disabled";
+};

samples/drivers/mbox_data/remote/boards/mimxrt1170_evk_cm4.conf

@@ -0,0 +1,4 @@
+CONFIG_MBOX_NXP_IMX_MU=y
+CONFIG_BUILD_OUTPUT_INFO_HEADER=y
+CONFIG_BUILD_OUTPUT_HEX=y
+CONFIG_SECOND_CORE_MCUX=y

samples/drivers/mbox_data/remote/boards/mimxrt1170_evk_cm4.overlay

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2024 NXP
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/ {
+	chosen {
+		zephyr,flash = &ocram;
+		zephyr,console = &lpuart2;
+		zephyr,shell-uart = &lpuart2;
+
+		/* Delete ipc chosen property where old IPM mailbox driver bellow is
+		 * configured.
+		 */
+		/delete-property/ zephyr,ipc;
+	};
+
+	soc {
+		/delete-node/ gpt@400f0000;
+
+		/* Replace GPT2 with another GPT kernel timer */
+		gpt2_hw_timer:gpt@400f0000 {
+			compatible = "nxp,gpt-hw-timer";
+			reg = <0x400f0000 0x4000>;
+			interrupts = <120 0>;
+			status = "okay";
+		};
+
+		/* Delete IPM Driver node nxp,imx-mu */
+		/delete-node/ mailbox@40c4c000;
+
+		/* Attach MBOX driver to MU Unit */
+		mbox:mbox@40c4c000 {
+			compatible = "nxp,mbox-imx-mu";
+			reg = <0x40c4c000 0x4000>;
+			interrupts = <118 0>;
+			rx-channels = <4>;
+			#mbox-cells = <1>;
+			status = "okay";
+		};
+	};
+};
+
+/* Enable secondary LPUART */
+&lpuart2 {
+	status = "okay";
+	current-speed = <115200>;
+};
+
+/* Disable primary GPT timer */
+&gpt_hw_timer {
+	status = "disabled";
+};

samples/drivers/mbox_data/remote/boards/mimxrt1170_evkb_cm4.conf

@@ -0,0 +1,4 @@
+CONFIG_MBOX_NXP_IMX_MU=y
+CONFIG_BUILD_OUTPUT_INFO_HEADER=y
+CONFIG_BUILD_OUTPUT_HEX=y
+CONFIG_SECOND_CORE_MCUX=y

samples/drivers/mbox_data/remote/boards/mimxrt1170_evkb_cm4.overlay

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2024 NXP
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/ {
+	chosen {
+		zephyr,flash = &ocram;
+		zephyr,console = &lpuart2;
+		zephyr,shell-uart = &lpuart2;
+
+		/* Delete ipc chosen property where old IPM mailbox driver bellow is
+		 * configured.
+		 */
+		/delete-property/ zephyr,ipc;
+	};
+
+	soc {
+		/delete-node/ gpt@400f0000;
+
+		/* Replace GPT2 with another GPT kernel timer */
+		gpt2_hw_timer:gpt@400f0000 {
+			compatible = "nxp,gpt-hw-timer";
+			reg = <0x400f0000 0x4000>;
+			interrupts = <120 0>;
+			status = "okay";
+		};
+
+		/* Delete IPM Driver node nxp,imx-mu */
+		/delete-node/ mailbox@40c4c000;
+
+		/* Attach MBOX driver to MU Unit */
+		mbox:mbox@40c4c000 {
+			compatible = "nxp,mbox-imx-mu";
+			reg = <0x40c4c000 0x4000>;
+			interrupts = <118 0>;
+			rx-channels = <4>;
+			#mbox-cells = <1>;
+			status = "okay";
+		};
+	};
+
+};
+
+/* Enable secondary LPUART */
+&lpuart2 {
+	status = "okay";
+	current-speed = <115200>;
+};
+
+/* Disable primary GPT timer */
+&gpt_hw_timer {
+	status = "disabled";
+};

samples/drivers/mbox_data/remote/prj.conf

@@ -0,0 +1,2 @@
+CONFIG_STDOUT_CONSOLE=n
+CONFIG_MBOX=y

samples/drivers/mbox_data/remote/src/main.c

@@ -0,0 +1,75 @@
+/*
+ * Copyright 2024 NXP
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <zephyr/kernel.h>
+#include <zephyr/drivers/mbox.h>
+
+static K_SEM_DEFINE(g_mbox_data_rx_sem, 0, 1);
+
+static uint32_t g_mbox_received_data;
+static uint32_t g_mbox_received_channel;
+
+#define TX_ID (2)
+#define RX_ID (3)
+
+static void callback(const struct device *dev, uint32_t channel, void *user_data,
+		     struct mbox_msg *data)
+{
+	memcpy(&g_mbox_received_data, data->data, data->size);
+	g_mbox_received_channel = channel;
+
+	k_sem_give(&g_mbox_data_rx_sem);
+}
+
+int main(void)
+{
+	struct mbox_channel tx_channel;
+	struct mbox_channel rx_channel;
+	const struct device *dev;
+	struct mbox_msg msg = {0};
+	uint32_t message = 0;
+
+	printk("mbox_data Server demo started\n");
+
+	dev = DEVICE_DT_GET(DT_NODELABEL(mbox));
+
+	mbox_init_channel(&tx_channel, dev, TX_ID);
+	mbox_init_channel(&rx_channel, dev, RX_ID);
+
+	if (mbox_register_callback(&rx_channel, callback, NULL)) {
+		printk("mbox_register_callback() error\n");
+		return 0;
+	}
+
+	if (mbox_set_enabled(&rx_channel, 1)) {
+		printk("mbox_set_enable() error\n");
+		return 0;
+	}
+
+	while (message < 99) {
+		k_sem_take(&g_mbox_data_rx_sem, K_FOREVER);
+		message = g_mbox_received_data;
+
+		printk("Server receive (on channel %d) value: %d\n", g_mbox_received_channel,
+		       g_mbox_received_data);
+
+		message++;
+
+		msg.data = &message;
+		msg.size = 4;
+
+		printk("Server send (on channel %d) value: %d\n", tx_channel.id, message);
+		if (mbox_send(&tx_channel, &msg) < 0) {
+			printk("mbox_send() error\n");
+			return 0;
+		}
+	}
+
+	printk("mbox_data Server demo ended.\n");
+	return 0;
+}

samples/drivers/mbox_data/sample.yaml

@@ -0,0 +1,27 @@
+sample:
+  name: MBOX Data IPC sample
+common:
+  sysbuild: true
+  tags: mbox
+tests:
+  sample.drivers.mbox_data.real_hw:
+    platform_allow:
+      - mimxrt1170_evkb_cm7
+      - mimxrt1170_evk_cm7
+      - mimxrt1160_evk_cm7
+    integration_platforms:
+      - mimxrt1160_evk_cm7
+    harness: console
+    harness_config:
+      type: multi_line
+      ordered: false
+      regex:
+        - "Client received \\(on channel 2\\) value: 1"
+        - "Client send \\(on channel 3\\) value: 2"
+        - "Client received \\(on channel 2\\) value: 3"
+        - "Client send \\(on channel 3\\) value: 4"
+        - "Client received \\(on channel 2\\) value: 41"
+        - "Client send \\(on channel 3\\) value: 42"
+        - "Client received \\(on channel 2\\) value: 97"
+        - "Client send \\(on channel 3\\) value: 98"
+        - "Client received \\(on channel 2\\) value: 99"

samples/drivers/mbox_data/src/main.c

@@ -0,0 +1,74 @@
+/*
+ * Copyright 2024 NXP
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <zephyr/kernel.h>
+#include <zephyr/drivers/mbox.h>
+
+static K_SEM_DEFINE(g_mbox_data_rx_sem, 0, 1);
+
+static uint32_t g_mbox_received_data;
+static uint32_t g_mbox_received_channel;
+
+#define TX_ID (3)
+#define RX_ID (2)
+
+static void callback(const struct device *dev, uint32_t channel, void *user_data,
+		     struct mbox_msg *data)
+{
+	memcpy(&g_mbox_received_data, data->data, data->size);
+	g_mbox_received_channel = channel;
+
+	k_sem_give(&g_mbox_data_rx_sem);
+}
+
+int main(void)
+{
+	struct mbox_channel tx_channel;
+	struct mbox_channel rx_channel;
+	const struct device *dev;
+	struct mbox_msg msg = {0};
+	uint32_t message = 0;
+
+	printk("mbox_data Client demo started\n");
+
+	dev = DEVICE_DT_GET(DT_NODELABEL(mbox));
+
+	mbox_init_channel(&tx_channel, dev, TX_ID);
+	mbox_init_channel(&rx_channel, dev, RX_ID);
+
+	if (mbox_register_callback(&rx_channel, callback, NULL)) {
+		printk("mbox_register_callback() error\n");
+		return 0;
+	}
+
+	if (mbox_set_enabled(&rx_channel, 1)) {
+		printk("mbox_set_enable() error\n");
+		return 0;
+	}
+
+	while (message < 100) {
+		msg.data = &message;
+		msg.size = 4;
+
+		printk("Client send (on channel %d) value: %d\n", tx_channel.id, message);
+		if (mbox_send(&tx_channel, &msg) < 0) {
+			printk("mbox_send() error\n");
+			return 0;
+		}
+
+		k_sem_take(&g_mbox_data_rx_sem, K_FOREVER);
+		message = g_mbox_received_data;
+
+		printk("Client received (on channel %d) value: %d\n", g_mbox_received_channel,
+		       message);
+		message++;
+	}
+
+	printk("mbox_data Client demo ended\n");
+	return 0;
+}

samples/drivers/mbox_data/sysbuild.cmake

@@ -0,0 +1,28 @@
+# Copyright 2024 NXP
+#
+# SPDX-License-Identifier: Apache-2.0
+
+if("${SB_CONFIG_REMOTE_BOARD}" STREQUAL "")
+    message(FATAL_ERROR
+    "Target ${BOARD} not supported for this sample. "
+    "There is no remote board selected in Kconfig.sysbuild")
+endif()
+
+set(REMOTE_APP remote)
+
+ExternalZephyrProject_Add(
+    APPLICATION ${REMOTE_APP}
+    SOURCE_DIR  ${APP_DIR}/${REMOTE_APP}
+    BOARD       ${SB_CONFIG_REMOTE_BOARD}
+)
+
+if ("${BOARD}" STREQUAL "mimxrt1170_evkb_cm7" OR
+    "${BOARD}" STREQUAL "mimxrt1170_evk_cm7"  OR
+    "${BOARD}" STREQUAL "mimxrt1160_evk_cm7"
+    )
+    # For these NXP boards the main core application is dependent on
+    # 'zephyr_image_info.h' generated by remote application.
+
+    # Let's build the remote application first
+    add_dependencies(${DEFAULT_IMAGE} ${REMOTE_APP})
+endif()