Skip to content

doc: Ironside update architecture #25951

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kyberdin wants to merge 1 commit into
base: main
Choose a base branch
from
+138 −107
Open

doc: Ironside update architecture #25951

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added doc/nrf/app_dev/device_guides/nrf54h/images/nrf54h20_ironside_update.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
24 changes: 8 additions & 16 deletions doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_ironside_services.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,27 +37,19 @@ For details about the CPUCONF peripheral, refer to the nRF54H20 SoC datasheet.
|ISE| update service
********************

The |ISE| update service will update |ISE| itself.
|ISE| provides an update service that allows local domains to trigger the :ref:`update process <ug_nrf54h20_ironside_se_update_architecture>` of |ISE| itself.

|ISE| is updated by the Secure Domain ROM (SDROM), which performs the update operation when triggered by a set of SICR registers.
SDROM verifies and copies the update candidate specified through these registers.
SDROM requires the |ISE| update to be located in MRAM.
The update service requires a release of |ISE| or the |ISE| Recovery image to be programmed within a valid memory range that is accessible by the Application core.
See :file:`nrf_ironside/update.h` for more details on the supported memory range.

|ISE| exposes an update service that allows local domains to trigger the update process by indirectly writing to the relevant SICR registers.
After the Application has invoked the service, |ISE| will update on the next system reset.
The update can be verified by checking the listed versions in the :ref:`boot report <ug_nrf54h20_ironside_se_boot_report>` on startup.

.. note::
The update data must be placed within a valid memory range.
See :file:`nrf_ironside/update.h` for more details.
Updating through the service is limited to a single image at a time.
Updating both |ISE| and |ISE| Recovery images requires performing two rounds of the update service procedure, in which the |ISE| Recovery image is updated first.
Copy link
Contributor

@jonathannilsen jonathannilsen Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is updating the recovery image first a recommendation or requirement?


The release ZIP archive for |ISE| includes the following components:

* A HEX file containing the update candidate for |ISE|.
* A HEX file for |ISE| Recovery.
* An application core image that executes the |ISE| update service to install the update candidate HEX files.

The |NCS| defines the west ``ncs-ironside-se-update`` command to update |ISE| on a device via the debugger.
This command takes a nRF54H20 SoC binary ZIP file and uses the |ISE| update service to update both the |ISE| and |ISE| Recovery (or optionally just one of them).
For more information, see :ref:`abi_compatibility`.
See the :zephyr:code-sample:`update application <nrf_ironside_update>` sample for an example on calling the service at runtime.

.. _ug_nrf54h20_ironside_se_counter_service:

Expand Down
221 changes: 130 additions & 91 deletions doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_ironside_update.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,25 @@
.. _ug_nrf54h20_ironside_update:
.. _ug_nrf54h20_ironside_se_update:

Programming and updating |ISE|
##############################
Updating |ISE|
##############

.. contents::
:local:
:depth: 2

|ISE| is released independently of the |NCS| release cycle and is provided as a ZIP archive that contains the following components:
Updating the |ISE| is only possible after it has been initially :ref:`provisioned <ug_nrf54h20_SoC_binaries>` on the nRF54H20 SoC.

The update operation is initiated through its :ref:`update service <ug_nrf54h20_ironside_se_update_service>` at runtime by application firmware.

.. _ug_nrf54h20_ironside_se_deliverables:

Release package
***************

The |ISE| is released independently of the |NCS| release cycle and is provided as a ZIP archive.

The archive is used to update the existing |ISE| firmware on the nRF54H20 and consists of the following components:

.. list-table::
:header-rows: 1
Expand All @@ -18,7 +30,7 @@ Programming and updating |ISE|
- Description
* - IronSide SE firmware
- :file:`ironside_se.hex`
- Used when bringing up a new DK and programming both the recovery firmware and |ISE| for the first time.
- Used when provisioning a new DK with |ISE| and |ISE| Recovery firmware for the first time.
* - IronSide SE update firmware
- :file:`ironside_se_update.hex`
- Used when updating |ISE|.
Expand All @@ -27,152 +39,179 @@ Programming and updating |ISE|
- The recovery firmware, reserved for future recovery operations. Currently, it does not provide user-facing functionality. Used when updating the recovery firmware.
* - Update application
- :file:`update_application.hex`
- The local domain :zephyr:code-sample:`update application <nrf_ironside_update>` that is used to perform an |ISE| update. See :ref:`ug_nrf54h20_ironside_se_update_manual`.
- The local domain :zephyr:code-sample:`update application <nrf_ironside_update>` that is used to perform an |ISE| update. See :ref:`ug_nrf54h20_ironside_se_update_architecture` for details on its role.

.. _ug_nrf54h20_ironside_se_programming:
For more information on |ISE| release binaries, see :ref:`abi_compatibility`.

Programming |ISE| on the nRF54H20 SoC
*************************************
For instructions on how to provision the nRF54H20 with |ISE| for the first time, see :ref:`ug_nrf54h20_SoC_binaries`.

For instructions on how to program |ISE|, see :ref:`ug_nrf54h20_SoC_binaries`.
.. _ug_nrf54h20_ironside_se_updating:

By default, the nRF54H20 SoC uses the following memory and access configurations:
Performing an update
********************

* MRAMC configuration: MRAM operates in Direct Write mode with READYNEXTTIMEOUT disabled.
* MPC configuration: All memory not reserved by Nordic firmware is accessible with read, write, and execute (RWX) permissions by any domain.
* TAMPC configuration: The access ports (AP) for the local domains are enabled, allowing direct programming of all the memory not reserved by Nordic firmware in the default configuration.
.. caution::
You cannot update |ISE| from a SUIT-based (up to 0.9.6) to an |ISE|-based (20.0.0 and onwards) version.

.. _ug_nrf54h20_ironside_se_update_manual:

.. note::
* The Radio Domain AP is only usable when the Radio domain has booted.
* Access to external memory (EXMIF) requires a non-default configuration of the GPIO.CTRLSEL register.
Manual update
=============

You can protect global domain memory from write operations by configuring the UICR registers.
To remove these protections and disable all other protection mechanisms enforced through UICR settings, perform an ``ERASEALL`` operation.
|NCS| supports the following methods for manually updating the |ISE| firmware on the nRF54H20 SoC:

Comment on lines -39 to 52
Copy link
Contributor

@jonathannilsen jonathannilsen Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where did this information go?

Copy link
Contributor Author

@kyberdin kyberdin Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I took it out into a separate branch of doc changes unrelated to update docs to keep the scope limited here. Can bring it back in if we just want to take all changes around this here.

.. _ug_nrf54h20_ironside_se_update:
* Using the ``west`` command provided by the |NCS|.
* Using the nRF Util `device <Device command overview_>`_ command.

Updating |ISE|
**************
.. important::
Manual updates will replace existing firmware running in the Application core.
User application firmware must be reprogrammed after successfully updating the device.

|NCS| supports two methods for updating the |ISE| firmware on the nRF54H20 SoC:
.. tabs::

* Using the ``west`` command.
You can use the ``west`` command provided by the |NCS| to install the firmware update.
For step-by-step instructions, see :ref:`ug_nrf54h20_ironside_se_update_west`.
.. group-tab:: West

* Using the nRF Util `device command <Device command overview_>`_.
Alternatively, you can perform the update by manually executing the same steps that the ``west`` command performs.
For step-by-step instructions, see :ref:`ug_nrf54h20_ironside_se_update_manual`.
The |NCS| defines the west ``ncs-ironside-se-update`` command to update |ISE| firmware on a device via the debugger.

.. caution::
You cannot update |ISE| from a SUIT-based (up to 0.9.6) to an |ISE|-based (20.0.0 and onwards) version.
This command takes the nRF54H20 SoC binary ZIP file and uses the |ISE| update service to update both the |ISE| and |ISE| Recovery (or optionally just one of them):

.. _ug_nrf54h20_ironside_se_update_west:
.. code-block:: console
Updating using west
===================
west ncs-ironside-se-update --allow-erase --zip <path_to_soc_binaries.zip>
To update the |ISE| firmware, you can use the ``west ncs-ironside-se-update`` command with the following syntax:
Use the ``--help`` option to see all possible options and descriptions of their use.

.. code-block:: console
.. group-tab:: nrf Util

west ncs-ironside-se-update --zip <path_to_soc_binaries.zip> --allow-erase
.. note::

The command accepts the following main options:
To use nRF Util for the update, you must install the nRF Util `device` command v2.14.0 or higher.
See `Installing specific versions of nRF Util commands`_ for more information.

* ``--zip`` (required) - Sets the path to the nRF54H20 IronSide SE binaries ZIP file.
* ``--allow-erase`` (required) - Enables erasing the device during the update process.
* ``--serial`` - Specifies the serial number of the target device.
* ``--firmware-slot`` - Updates only a specific firmware slot (``uslot`` for |ISE| or ``rslot`` for |ISE| Recovery).
* ``--wait-time`` - Specifies the timeout in seconds to wait for the device to boot (default: 2.0 seconds).
The |ISE| update can be performed by manually executing nRF Util commands that perform the same steps that the ``west`` command performs.

.. _ug_nrf54h20_ironside_se_update_manual:
To perform the manual update process using nRF Util's `device <Device command overview_>`_ command, complete the following steps:

1. Extract the update bundle:

.. code-block:: console
unzip <soc_binaries.zip> -d /tmp/update_dir
#. Erase non-volatile memory:

.. code-block:: console
nrfutil device recover --serial-number <serial>
Updating manually
=================
#. Program the update application:

The manual update process involves the following steps:
.. code-block:: console
1. Executing the update application.
The :zephyr:code-sample:`update application <nrf_ironside_update>` runs on the application core and communicates with |ISE| using the :ref:`update service <ug_nrf54h20_ironside_se_update_service>`.
It reads the update firmware from memory and passes the update blob metadata to the |ISE|.
The |ISE| validates the update parameters and writes the update metadata to the Secure Information Configuration Registers (SICR).
nrfutil device program --firmware /tmp/update_dir/update/update_application.hex --serial-number <serial>
#. Installing the update.
After a reset, the Secure Domain ROM (SDROM) detects the pending update through the SICR registers, verifies the update firmware signature, and installs the new firmware.
#. Program the |ISE| update firmware:

#. Completing the update.
The system boots with the updated |ISE| firmware, and the update status in the boot report can be read to verify successful installation.
.. code-block:: console
Updating manually using nRF Util
--------------------------------
nrfutil device program --options chip_erase_mode=ERASE_NONE --firmware /tmp/update_dir/update/ironside_se_update.hex --serial-number <serial>
To update |ISE|, you can use nRF Util instead of ``west ncs-ironside-se-update``.
To use nRF Util for the update, you must install the nRF Util `device` command v2.14.0 or higher.
See `Installing specific versions of nRF Util commands`_ for more information.
#. Reset the device to execute the update service:

To perform the manual update process using nRF Util's `device <Device command overview_>`_ command, complete the following steps:
.. code-block:: console
1. Extract the update bundle:
nrfutil device reset --serial-number <serial>
.. code-block:: console
#. Reset through Secure Domain to trigger the installation of the update:

unzip <soc_binaries.zip> -d /tmp/update_dir
.. code-block:: console
#. Erase non-volatile memory:
nrfutil device reset --reset-kind RESET_VIA_SECDOM --serial-number <serial>
.. code-block:: console
#. If you are updating both slots, complete the following additional steps:

nrfutil device recover --serial-number <serial>
a. Program the |ISE| Recovery update firmware:

#. Program the update application:
.. code-block:: console
.. code-block:: console
nrfutil device program --options chip_erase_mode=ERASE_NONE --firmware /tmp/update_dir/update/ironside_se_recovery_update.hex --serial-number <serial>
nrfutil device program --firmware /tmp/update_dir/update/update_application.hex --serial-number <serial>
#. Reset again to execute the update service:

#. Program the |ISE| update firmware:
.. code-block:: console
.. code-block:: console
nrfutil device reset --serial-number <serial>
nrfutil device program --options chip_erase_mode=ERASE_NONE --firmware /tmp/update_dir/update/ironside_se_update.hex --serial-number <serial>
#. Reset again through Secure Domain to trigger the installation of the update:

#. Reset the device to execute the update service:
.. code-block:: console
.. code-block:: console
nrfutil device reset --reset-kind RESET_VIA_SECDOM --serial-number <serial>
nrfutil device reset --serial-number <serial>
#. Reset through Secure Domain to trigger the installation of the update:
#. Erase the update application (regardless of whether you update one or both slots):

.. code-block:: console
.. code-block:: console
nrfutil device reset --reset-kind RESET_VIA_SECDOM --serial-number <serial>
nrfutil device erase --all --serial-number <serial>
#. If you are updating both slots, complete the following additional steps:
.. _ug_nrf54h20_ironside_se_update_architecture:

a. Program the |ISE| Recovery update firmware:
Architecture
============

.. code-block:: console
The |ISE| update process starts when Application firmware invokes the :ref:`update service <ug_nrf54h20_ironside_se_update_service>` with the address of where the update release package has been written in MRAM.

nrfutil device program --options chip_erase_mode=ERASE_NONE --firmware /tmp/update_dir/update/ironside_se_recovery_update.hex --serial-number <serial>
The diagram below illustrates the process flow between Application, |ISE|, and Secure Domain ROM (SDROM) in performing the firmware update.

#. Reset again to execute the update service:
.. figure:: images/nrf54h20_ironside_update.svg

.. code-block:: console
.. _ug_nrf54h20_ironside_se_update_architecture_app:

nrfutil device reset --serial-number <serial>
Application side
----------------

#. Reset again through Secure Domain to trigger the installation of the update:
The following describes the procedure for an |ISE| update from Application firmware:

.. code-block:: console
1. Program update image into MRAM.
#. Call the |ISE| update service with update image location.
#. Verify update request is acknowledged.
#. Trigger a reset.
#. Check version in boot report on startup.

nrfutil device reset --reset-kind RESET_VIA_SECDOM --serial-number <serial>
.. _ug_nrf54h20_ironside_se_update_architecture_ise:

|ISE| side
----------

#. Erase the update application (regardless of whether you update one or both slots):
The |ISE| side of the update process involves both |ISE| firmware and SDROM.
Comment on lines +184 to +187
Copy link
Contributor

@jonathannilsen jonathannilsen Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: should we choose a different wording to avoid "IronSide side"?


.. code-block:: console
The following describes the update procedure in the |ISE| upon request:

nrfutil device erase --all --serial-number <serial>
1. Service receives update request with update image location in MRAM.
#. Update request is validated.
#. SICR registers are updated with image metadata.
#. Service request is acknowledged.
#. Operation continues normally until a reset is performed.

Once the device comes out of reset, SDROM performs the following:

Copy link
Contributor

@jonathannilsen jonathannilsen Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't there be a step with something like "applies the update"?

1. Enables write-protection on the update image and firmware contents.
#. Checks firmware metadata stored in SICR registers against address range and size constraints.
#. Verifies update version against current firmware to prevent downgrades.
#. Computes and validates digest of the public key.
#. Checks public key is not revoked.
#. Computes and validates digest of update firmware.
#. Verifies signature of the update firmware.
#. Updates SICR's update status with result.

If any of the above steps fail, the installation is aborted and the existing |ISE| is booted.
Otherwise, the update firmware's metadata is stored in SICR and the new image is installed.

If the updated firmware is for |ISE| Recovery, the device is reset into Safe Mode after installation.
When Safe Mode has acknowledged its update, the device is reset to boot back into the |ISE| context.

On boot, |ISE| reads the update result from the SICR update status register and writes the value into the boot report.

.. note::
|ISE| does not delete the update image contents from MRAM after a successful update.
Loading