[nrf fromlist] soc: nordic: Add support for IRONside calls

Upstream PR #: 88937

IRONside calls are remote procedure calls which comprise the runtime
interface of Nordic IRONside SE. They are realized using a simple IPC
mechanism.

A local domain (client) issues requests to the server by exchanging data
in shared memory, which is divided into evenly sized buffers. The client
selects a buffer, writes a request into it, and sends it to the server.
The server processes that request and writes a response into the same
buffer before returning it to the client.

This patch adds the initial client-side implementation on top of MBOX.
It features cache management and a blocking alloc/dispatch/release API
for synchronous, zero-copy transfers.

A new devicetree binding is added to support this implementation. It is
patterned after the `zephyr,ipc-*` bindings, where each node associates
a pair of mailboxes and a shared memory region.

Signed-off-by: Grzegorz Swiderski <[email protected]>
(cherry picked from commit 53c8dc9775b148f07f427b8e24f71da3a7c97bdb)

Author: 57300

dts/bindings/ipc/nordic,ipc-ironside.yaml

@@ -0,0 +1,22 @@
+# Copyright (c) 2025 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+description: IPC configuration for Nordic IRONside calls
+
+compatible: "nordic,ipc-ironside"
+
+include: base.yaml
+
+properties:
+  memory-region:
+    type: phandle
+    required: true
+    description: phandle to shared memory region
+
+  mboxes:
+    required: true
+    description: MBOX channel specifiers (TX and RX are required)
+
+  mbox-names:
+    required: true
+    description: MBOX channel names (must be called "tx" and "rx")

soc/nordic/common/CMakeLists.txt

@@ -2,6 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 add_subdirectory_ifdef(CONFIG_RISCV_CORE_NORDIC_VPR vpr)
+add_subdirectory_ifdef(CONFIG_SOC_NRF54H20_IRON ironside)
 
 if(CONFIG_ARM)
   # Let SystemInit() be called in place of soc_reset_hook() by default.
@@ -26,6 +27,7 @@ if((CONFIG_SOC_SERIES_NRF54HX OR CONFIG_SOC_SERIES_NRF92X) AND CONFIG_CPU_HAS_CU
 endif()
 
 zephyr_include_directories(.)
+zephyr_include_directories(include)
 
 if(CONFIG_HAS_NORDIC_DMM)
   zephyr_library_sources(dmm.c)

soc/nordic/common/Kconfig

@@ -49,3 +49,4 @@ source "subsys/logging/Kconfig.template.log_config"
 endif # MRAM_LATENCY
 
 rsource "vpr/Kconfig"
+rsource "ironside/Kconfig"

soc/nordic/common/include/nrf/ironside/call.h

@@ -0,0 +1,75 @@
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_SOC_NORDIC_COMMON_INCLUDE_NRF_IRONSIDE_SE_CALL_H_
+#define ZEPHYR_SOC_NORDIC_COMMON_INCLUDE_NRF_IRONSIDE_SE_CALL_H_
+
+#include <stdint.h>
+
+/** @brief Maximum number of arguments to an IRONside call.
+ *
+ * This is chosen so that the containing message buffer size is minimal but
+ * cache line aligned.
+ */
+#define NRF_IRONSIDE_CALL_NUM_ARGS 7
+
+/** @brief Message buffer. */
+struct ironside_call_buf {
+	/** See enum ironside_call_status. */
+	uint16_t status;
+	/** Operation identifier. */
+	uint16_t id;
+	/** Arguments to the given operation. */
+	uint32_t args[NRF_IRONSIDE_CALL_NUM_ARGS];
+};
+
+/** @brief Status code of a message buffer. */
+enum ironside_call_status {
+	/** Buffer is idle and available for allocation. */
+	IRONSIDE_CALL_STATUS_IDLE,
+	/** Request was processed successfully by the server. */
+	IRONSIDE_CALL_STATUS_RSP_SUCCESS,
+	/** Request status code is unknown. */
+	IRONSIDE_CALL_STATUS_RSP_ERR_UNKNOWN_STATUS,
+	/** Request status code is no longer supported. */
+	IRONSIDE_CALL_STATUS_RSP_ERR_EXPIRED_STATUS,
+	/** Operation identifier is unknown. */
+	IRONSIDE_CALL_STATUS_RSP_ERR_UNKNOWN_ID,
+	/** Operation identifier is no longer supported. */
+	IRONSIDE_CALL_STATUS_RSP_ERR_EXPIRED_ID,
+	/** Buffer contains a request from the client. */
+	IRONSIDE_CALL_STATUS_REQ,
+};
+
+/**
+ * @brief Allocate memory for an IRONside call.
+ *
+ * This function may block when no buffers are available, until one is released.
+ *
+ * @return Pointer to the allocated buffer.
+ */
+struct ironside_call_buf *ironside_call_alloc(void);
+
+/**
+ * @brief Dispatch an IRONside call.
+ *
+ * This function will block until a response is received.
+ *
+ * @param buf Buffer returned by ironside_call_alloc(). It should be populated
+ *            with request data before calling this function. Upon returning,
+ *            this data will have been replaced by response data.
+ */
+void ironside_call_dispatch(struct ironside_call_buf *buf);
+
+/**
+ * @brief Release an IRONside call buffer.
+ *
+ * This function must be called after processing the response.
+ *
+ * @param buf Buffer used to perform the call.
+ */
+void ironside_call_release(struct ironside_call_buf *buf);
+
+#endif /* ZEPHYR_SOC_NORDIC_COMMON_INCLUDE_NRF_IRONSIDE_SE_CALL_H_ */

soc/nordic/common/ironside/CMakeLists.txt

@@ -0,0 +1,6 @@
+# Copyright (c) 2025 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+zephyr_include_directories(include)
+
+zephyr_library_sources_ifdef(CONFIG_NRF_IRONSIDE_CALL call.c)

soc/nordic/common/ironside/Kconfig

@@ -0,0 +1,19 @@
+# Copyright (c) 2025 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+config NRF_IRONSIDE_CALL
+	bool
+	depends on DT_HAS_NORDIC_IPC_IRONSIDE_ENABLED
+	depends on SOC_NRF54H20_IRON
+	select EVENTS
+	select MBOX
+	help
+	  This is selected by features that require support for IRONside calls.
+
+if NRF_IRONSIDE_CALL
+
+config NRF_IRONSIDE_CALL_INIT_PRIORITY
+	int "IRONside calls' initialization priority"
+	default 47
+
+endif # NRF_IRONSIDE_CALL

soc/nordic/common/ironside/call.c

@@ -0,0 +1,128 @@
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <nrf/ironside/call.h>
+#include <zephyr/cache.h>
+#include <zephyr/device.h>
+#include <zephyr/drivers/mbox.h>
+#include <zephyr/kernel.h>
+#include <zephyr/sys/barrier.h>
+#include <zephyr/sys/math_extras.h>
+#include <zephyr/sys/util.h>
+
+#define DT_DRV_COMPAT nordic_ipc_ironside
+
+#define SHM_NODE     DT_INST_PHANDLE(0, memory_region)
+#define NUM_BUFS     (DT_REG_SIZE(SHM_NODE) / sizeof(struct ironside_call_buf))
+#define ALL_BUF_BITS BIT_MASK(NUM_BUFS)
+
+/* Note: this area is already zero-initialized at reset time. */
+static struct ironside_call_buf *const bufs = (void *)DT_REG_ADDR(SHM_NODE);
+
+#if defined(CONFIG_DCACHE_LINE_SIZE)
+BUILD_ASSERT((DT_REG_ADDR(SHM_NODE) % CONFIG_DCACHE_LINE_SIZE) == 0);
+BUILD_ASSERT((sizeof(struct ironside_call_buf) % CONFIG_DCACHE_LINE_SIZE) == 0);
+#endif
+
+static const struct mbox_dt_spec mbox_rx = MBOX_DT_SPEC_INST_GET(0, rx);
+static const struct mbox_dt_spec mbox_tx = MBOX_DT_SPEC_INST_GET(0, tx);
+
+K_EVENT_DEFINE(alloc_evts);
+K_EVENT_DEFINE(rsp_evts);
+
+static void ironside_call_rsp(const struct device *dev, mbox_channel_id_t channel_id,
+			      void *user_data, struct mbox_msg *data)
+{
+	ARG_UNUSED(dev);
+	ARG_UNUSED(channel_id);
+	ARG_UNUSED(user_data);
+	ARG_UNUSED(data);
+
+	struct ironside_call_buf *buf;
+	uint32_t rsp_buf_bits = 0;
+	const uint32_t skip_buf_bits = k_event_test(&rsp_evts, ALL_BUF_BITS);
+
+	for (int i = 0; i < NUM_BUFS; i++) {
+		if (skip_buf_bits & BIT(i)) {
+			/* Must not cache-invalidate this buffer. */
+			continue;
+		}
+
+		buf = &bufs[i];
+
+		sys_cache_data_invd_range(buf, sizeof(*buf));
+		barrier_dmem_fence_full();
+
+		if (buf->status != IRONSIDE_CALL_STATUS_IDLE &&
+		    buf->status != IRONSIDE_CALL_STATUS_REQ) {
+			rsp_buf_bits |= BIT(i);
+		}
+	}
+	k_event_post(&rsp_evts, rsp_buf_bits);
+}
+
+static int ironside_call_init(const struct device *dev)
+{
+	ARG_UNUSED(dev);
+
+	int err;
+
+	k_event_set(&alloc_evts, ALL_BUF_BITS);
+	k_event_set(&rsp_evts, ALL_BUF_BITS);
+
+	err = mbox_register_callback_dt(&mbox_rx, ironside_call_rsp, NULL);
+	__ASSERT_NO_MSG(err == 0);
+
+	err = mbox_set_enabled_dt(&mbox_rx, 1);
+	__ASSERT_NO_MSG(err == 0);
+
+	return 0;
+}
+
+DEVICE_DT_INST_DEFINE(0, ironside_call_init, NULL, NULL, NULL, POST_KERNEL,
+		      CONFIG_NRF_IRONSIDE_CALL_INIT_PRIORITY, NULL);
+
+struct ironside_call_buf *ironside_call_alloc(void)
+{
+	uint32_t avail_buf_bits;
+	uint32_t alloc_buf_bit;
+
+	do {
+		avail_buf_bits = k_event_wait(&alloc_evts, ALL_BUF_BITS, false, K_FOREVER);
+		alloc_buf_bit = LSB_GET(avail_buf_bits);
+	} while (!k_event_clear(&alloc_evts, alloc_buf_bit));
+
+	return &bufs[u32_count_trailing_zeros(alloc_buf_bit)];
+}
+
+void ironside_call_dispatch(struct ironside_call_buf *buf)
+{
+	const uint32_t buf_bit = BIT(buf - bufs);
+	int err;
+
+	buf->status = IRONSIDE_CALL_STATUS_REQ;
+	barrier_dmem_fence_full();
+
+	sys_cache_data_flush_range(buf, sizeof(*buf));
+
+	k_event_clear(&rsp_evts, buf_bit);
+
+	err = mbox_send_dt(&mbox_tx, NULL);
+	__ASSERT_NO_MSG(err == 0);
+
+	k_event_wait(&rsp_evts, buf_bit, false, K_FOREVER);
+}
+
+void ironside_call_release(struct ironside_call_buf *buf)
+{
+	const uint32_t buf_bit = BIT(buf - bufs);
+
+	buf->status = IRONSIDE_CALL_STATUS_IDLE;
+	barrier_dmem_fence_full();
+
+	sys_cache_data_flush_range(buf, sizeof(*buf));
+
+	k_event_post(&alloc_evts, buf_bit);
+}