[nrf fromlist] samples: drivers: firmware: add sample for nrf_ironside update service

Upstream PR #: 89333

Add a sample demonstrating how to use the IRONside update service to
update the IRONside SE firmware on the nrf54h20dk/nrf54h20/cpuapp/iron
board.

Co-authored-by: Håkon Amundsen <[email protected]>
Signed-off-by: Jonathan Nilsen <[email protected]>

Author: 2 people

samples/drivers/firmware/index.rst

@@ -0,0 +1,6 @@
+.. zephyr:code-sample-category:: firmware
+   :name: Firmware drivers
+   :show-listing:
+   :glob: **/*
+
+   These samples demonstrate how to use firmware driver APIs.

samples/drivers/firmware/nrf_ironside/update/CMakeLists.txt

@@ -0,0 +1,10 @@
+# Copyright (c) 2025 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(ironside_se_update)
+
+target_sources(app PRIVATE src/main.c)

samples/drivers/firmware/nrf_ironside/update/Kconfig

@@ -0,0 +1,11 @@
+# Copyright (c) 2025 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+config UPDATE_BLOB_ADDRESS
+	hex "Address of the update blob"
+	default 0xe100000
+	help
+	  Address of the update blob. The default value matches the placement of the
+	  update blobs delivered with the IRONside SE firmware.
+
+source "Kconfig.zephyr"

samples/drivers/firmware/nrf_ironside/update/README.rst

@@ -0,0 +1,74 @@
+.. zephyr:code-sample:: nrf_ironside_update
+   :name: Nordic IRONside SE firmware update
+
+   Update the Nordic IRONside SE firmware.
+
+Overview
+********
+
+The Nordic IRONside SE Update sample updates the IRONside SE firmware on a SoC that already has IRONside SE installed.
+It can update both the main image and the recovery image of IRONside SE using the IRONside SE firmware release ZIP file.
+
+Update procedure
+****************
+
+The update procedure works as follows:
+
+1. The application invokes the IRONside SE update service and passes the parameters that correspond to the location of the HEX file of the IRONside SE firmware update.
+
+#. The application prints the return value of the service call and outputs information from the update HEX file.
+
+#. After the service call completes, the IRONside SE firmware updates the internal state of the device.
+
+#. The firmware installs the update during the next device boot.
+   This operation can take several seconds.
+
+Once the operation has completed, you can read the boot report to verify that the update has taken place.
+
+Building and running the application for nrf54h20dk/nrf54h20/cpuapp/iron
+************************************************************************
+
+.. note::
+   You can use this application only when there is already a version of IRONside SE installed on the device.
+
+1. Unzip the IRONside SE release ZIP to get the update hex file:
+
+   .. code-block:: console
+
+      unzip nrf54h20_soc_binaries_v.*.zip
+
+#. Program the appropriate update hex file from the release ZIP using one (not both) of the following commands:
+
+   a) To update IRONside SE firmware:
+
+      .. code-block:: console
+
+         nrfutil device program --traits jlink --firmware update/ironside_se_update.hex
+
+   b) To update IRONside SE recovery firmware:
+
+      .. code-block:: console
+
+         nrfutil device program --traits jlink --firmware update/ironside_se_recovery_update.hex
+
+#. Build and program the application:
+
+   .. zephyr-app-commands::
+      :zephyr-app: samples/drivers/firmware/nrf_ironside/update
+      :board: nrf54h20dk/nrf54h20/cpuapp/iron
+      :goals: flash
+
+#. Trigger a reset:
+
+.. code-block:: console
+
+   nrfutil device reset --reset-kind RESET_PIN --traits jlink
+
+#. Check that the new version is installed:
+
+   .. code-block:: console
+
+      # Read the version fields from the boot report
+      nrfutil x-read --direct --address 0x2f88fd04 --bytes 16 --traits jlink
+      # Read the update status in the boot report
+      nrfutil x-read --direct --address 0x2f88fd24 --bytes 4 --traits jlink

samples/drivers/firmware/nrf_ironside/update/prj.conf

@@ -0,0 +1,3 @@
+CONFIG_LOG=y
+
+CONFIG_NRF_IRONSIDE_UPDATE_SERVICE=y

samples/drivers/firmware/nrf_ironside/update/sample.yaml

@@ -0,0 +1,12 @@
+sample:
+  name: Nordic IRONside SE update service
+  description: Demonstrates how to update the Nordic IRONside SE firmware
+common:
+  build_only: true
+  tags: nrf_ironside
+  integration_platforms:
+    - nrf54h20dk/nrf54h20/cpuapp/iron
+
+tests:
+  sample.drivers.firmware.nrf_ironside.update:
+    platform_allow: nrf54h20dk/nrf54h20/cpuapp/iron

samples/drivers/firmware/nrf_ironside/update/src/main.c

@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/drivers/firmware/nrf_ironside/update.h>
+#include <zephyr/logging/log.h>
+
+LOG_MODULE_REGISTER(app, LOG_LEVEL_INF);
+
+int main(void)
+{
+	int err;
+	const struct ironside_update_blob *update = (void *)CONFIG_UPDATE_BLOB_ADDRESS;
+
+	err = ironside_update(update);
+	LOG_INF("IRONside update retval: 0x%x", err);
+
+	if (err == 0) {
+		LOG_HEXDUMP_INF(update->manifest, sizeof(update->manifest), "Update manifest:");
+		LOG_HEXDUMP_INF(update->pubkey, sizeof(update->pubkey), "Public key:");
+		LOG_HEXDUMP_INF(update->signature, sizeof(update->signature), "Signature:");
+		LOG_HEXDUMP_INF(update->firmware, 8, "First 8 bytes of encrypted fw:");
+		LOG_INF("Reboot the device to trigger the update");
+	} else {
+		LOG_ERR("The request to update failed");
+	}
+
+	return 0;
+}