Skip to content

Commit 4e10804

Browse files
FrancescoSernordicjm
FrancescoSer
authored and
nordicjm
committed
doc: Added suit to ironside migration guide
Added suit to ironside migration guide Signed-off-by: Francesco Domenico Servidio <[email protected]>
1 parent 4992ac5 commit 4e10804

File tree

2 files changed

+197
-0
lines changed

2 files changed

+197
-0
lines changed

‎doc/nrf/links.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1885,3 +1885,5 @@
18851885

18861886
.. _`Zephyr's nRF clock control API extensions`: https://github.com/nrfconnect/sdk-zephyr/blob/main/include/zephyr/drivers/clock_control/nrf_clock_control.h
18871887
.. _`clocks devicetree macro API`: https://github.com/nrfconnect/sdk-zephyr/blob/main/include/zephyr/devicetree/clocks.h
1888+
1889+
.. _`nRF54H20 DK memory map`: https://github.com/nrfconnect/sdk-zephyr/blob/main/boards/nordic/nrf54h20dk/nrf54h20dk_nrf54h20-memory_map.dtsi

‎doc/nrf/releases_and_maturity/migration/migration_3.1_54h_suit_ironside.rst

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
.. _migration_3.1_54h_suit_ironside:
2+
3+
Migration from SUIT to IronSide SE for the nRF54H20 SoC
4+
=======================================================
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
This document explains how to migrate your existing |NCS| v3.0.0 application for the nRF54H20 SoC running SUIT to the |NCS| v3.1.0 using IronSide SE.
11+
12+
To follow this guide, you must meet the following prerequisites:
13+
14+
* You have a working the |NCS| v3.0.0 application for the nRF54H20 SoC using SUIT.
15+
* You have installed the |NCS| v3.1.0 and its toolchain.
16+
For more information, see :ref:`install_ncs`.
17+
18+
.. note::
19+
To program IronSide SE on your nRF54H20 SoC-based device, your device must be in lifecycle state (LCS) ``EMPTY``.
20+
Devices using SUIT in LCS RoT cannot be transitioned back to LCS EMPTY.
21+
22+
Breaking changes
23+
================
24+
25+
The following is a summary of the breaking changes that apply when migrating applications:
26+
27+
* SUIT support is removed in the |NCS| v3.1.0.
28+
The Secure Domain now runs IronSide SE, which is agnostic to the device firmware update (DFU) mechanism used.
29+
DFU is handled by the local domain (for example, using MCUboot).
30+
* IronSide SE uses a new UICR format and moves the peripheral configuration into a dedicated MRAM partition.
31+
* The shared memory used for communication with the Secure Domain is now located in a fixed RAM-20 region.
32+
You no longer reserve it manually.
33+
* DFU support moves from SUIT to MCUboot.
34+
You must enable and configure MCUboot in your project.
35+
36+
Update prj.conf
37+
---------------
38+
39+
To update :file:`prj.conf`, complete the following steps:
40+
41+
1. Remove the following SUIT-specific Kconfig options:
42+
43+
* :kconfig:option:`CONFIG_SUIT`
44+
* :kconfig:option:`CONFIG_SUIT_SECURE_DOMAIN`
45+
* :kconfig:option:`SB_CONFIG_SUIT_ENVELOPE`
46+
* :kconfig:option:`CONFIG_SUIT_ENVELOPE_TEMPLATE_FILENAME`
47+
48+
#. Disable SUIT-specific SMP extensions:
49+
50+
* :kconfig:option:`CONFIG_MGMT_SUITFU`
51+
* :kconfig:option:`CONFIG_MGMT_SUITFU_GRP_SUIT`
52+
53+
#. Disable legacy RC code encoding (:kconfig:option:`CONFIG_MCUMGR_SMP_LEGACY_RC_BEHAVIOUR`) as it is no longer needed.
54+
#. Enable MCUboot for device firmware update (DFU) in the :file:`sysbuild.conf` by setting :kconfig:option:`SB_CONFIG_BOOTLOADER_MCUBOOT` to ``y``.
55+
If the application uses a custom memory map, include the map in the MCUboot overlay (for example, :file:`sysbuild/mcuboot.overlay`).
56+
If the customized MCUboot overlay is defined, it must also include the following lines:
57+
58+
.. code-block::
59+
60+
/ {
61+
chosen {
62+
zephyr,code-partition = &boot_partition;
63+
};
64+
};
65+
66+
Update devicetree files
67+
-----------------------
68+
69+
To update your devicetree files, complete the following steps:
70+
71+
1. Remove the old UICR partition.
72+
In your board's DTS overlay, remove any node that defined the ``uicr`` partition.
73+
74+
#. Add the PERIPHCONF array.
75+
In your devicetree, under the ``mram1x`` partitions node, define a partition node labeled ``peripconf_partition`` with a size of at least 8 KB to embed the generated address-value blob.
76+
77+
#. Remove IPC-shared-memory reservation.
78+
As IronSide relocates the IPC buffer to a fixed RAM20 address, you can delete any manual reservation in RAM0.
79+
Refer to the `Memory map changes`_ section.
80+
81+
#. Update IPC configuration for IronSide SE.
82+
The shared memory for communication with the Secure Domain now uses fixed addresses in ``RAM20``.
83+
A single memory region is used for both RX and TX operations.
84+
The IPC nodes use the ``nordic,ironside-call`` compatible and communicate using the new *IronSide Calls* IPC driver.
85+
86+
For custom board devicetree files, you can copy the IPC configuration from the nRF54H20 DK reference implementation.
87+
The devicetree defines the shared memory region and IPC nodes as follows:
88+
89+
.. code-block:: dts
90+
91+
// Shared memory region in RAM20
92+
cpusec_cpuapp_ipc: memory@2f88f000 {
93+
reg = <0x2f88f000 DT_SIZE_K(4)>;
94+
};
95+
96+
.. code-block:: dts
97+
98+
// IPC nodes using IronSide calls driver
99+
cpusec_cpuapp_ipc_tx: ipc@deadbeef {
100+
compatible = "nordic,ironside-call";
101+
mboxes = <&cpuapp_cpusec_ipc 0>, <&cpuapp_cpusec_ipc 1>;
102+
mbox-names = "rx", "tx";
103+
memory-region = <&cpusec_cpuapp_ipc>;
104+
status = "okay";
105+
};
106+
107+
.. code-block:: dts
108+
109+
cpusec_cpuapp_ipc_rx: ipc@deadbeef {
110+
compatible = "nordic,ironside-call";
111+
mboxes = <&cpusec_cpuapp_ipc 2>, <&cpuapp_cpusec_ipc 3>;
112+
mbox-names = "rx", "tx";
113+
memory-region = <&cpusec_cpuapp_ipc>;
114+
status = "okay";
115+
};
116+
117+
#. Remove the SUIT recovery partitions (``cpuapp_recovery_partition`` and ``cpurad_recovery_partition``).
118+
119+
Update PERIPHCONF
120+
-----------------
121+
122+
The new UICR format no longer holds peripheral configuration initial values.
123+
You must generate a PERIPHCONF blob at build time.
124+
125+
The Zephyr build invokes the :file:`gen_uicr.py` script (:file:`soc/nordic/common/uicr/gen_uicr.py` in the Zephyr tree) using ``nrf-regtool`` in the |NCS|'s implementation of :ref:`configuration_system_overview_sysbuild`.
126+
When the following Kconfig options are set:
127+
128+
* :kconfig:option:`CONFIG_NRF_HALTIUM_GENERATE_UICR` to ``y``
129+
* :kconfig:option:`CONFIG_NRF_HALTIUM_UICR_PERIPHCONF` to ``y``
130+
131+
the script does the following:
132+
133+
1. It reads the ``peripconf_partition`` node in the devicetree to discover the partition's address and size.
134+
#. It extracts the address/value pairs from the ``PERIPHCONF`` section of the Zephyr ELF image.
135+
#. It generates two Intel HEX files:
136+
137+
* :file:`uicr.hex` - the new UICR entries
138+
* :file:`periphconf.hex` - the MRAM-resident ``PERIPHCONF`` blob
139+
140+
Both HEX files must be programmed alongside your firmware image.
141+
``west flash`` handles this automatically.
142+
143+
You do not need to modify your application code.
144+
You only need to ensure the DTS partition exists.
145+
146+
Memory protection and isolation
147+
-------------------------------
148+
149+
IronSide SE currently grants full memory-access permissions to both application and radio domains by default.
150+
Delete any UICR settings related to the following:
151+
152+
* Secure Domain IPC buffer location
153+
* Secure-Domain offsets
154+
* Partition lock bits
155+
156+
Memory map changes
157+
------------------
158+
159+
With IronSide SE, the memory map changed as follows:
160+
161+
* The application core firmware now always starts at address ``0xE03_0000``, which is the first address in ``MRAM00`` immediately following the IronSide firmware.
162+
If the application uses MCUboot, the application starts at address ``0xE04_0000``.
163+
The default location for the radio firmware is now ``0xE09_2000``.
164+
* Nordic-reserved partitions in ``MRAM11`` and ``RAM0x`` have been removed.
165+
* IPC buffers toward the Secure Domain are relocated to fixed addresses in ``RAM20``.
166+
Memory previously reserved in ``RAM0x`` for IPC can now be repurposed.
167+
* The devicetree no longer uses the ``nordic,owned-memory`` or ``nordic,owned-partitions`` compatibles.
168+
Remove memory access groups, such as ``cpuapp_rx_partitions``, ``cpurad_rx_partitions``, ``cpuapp_rw_partitions`` and define partitions under the ``partitions`` node under the ``mram1x`` node.
169+
Refer to the `nRF54H20 DK memory map`_ for details.
170+
171+
To enable ``UICR/PERIPHCONF`` generation, ensure a DTS partition labeled ``peripconf_partition`` exists with sufficient size (for example, 8 KBs) to embed the generated address-value blob.
172+
173+
DFU support with MCUboot
174+
------------------------
175+
176+
IronSide SE drops SUIT in favor of MCUboot.
177+
To migrate the DFU solution, complete the following steps:
178+
179+
1. Remove SUIT-specific Kconfig symbols from both :file:`prj.conf` and :file:`sysbuild.conf` files.
180+
#. Delete SUIT manifest templates, typically located in the :file:`suit` directory.
181+
#. Choose one of the supported MCUboot bootloader modes.
182+
#. If your chosen mode does not require a DFU slot, remove the ``dfu_partition``.
183+
Otherwise, split the ``dfu_partition`` into ``cpuapp_slot1_partition`` and ``cpurad_slot1_partition``.
184+
These partitions must match the size of their counterparts (``cpuapp_slot0_partition`` and ``cpurad_slot0_partition``, respectively).
185+
#. If your application uses the radio core:
186+
187+
a. Add the radio image to the updateable image list by calling the ``UpdateableImage_Add`` function in your CMake build.
188+
b. Enable the :kconfig:option:`CONFIG_SOC_NRF54H20_CPURAD_ENABLE` Kconfig option to ensure the radio core starts at runtime.
189+
190+
#. Remove recovery and companion images, as MCUboot no longer supports them.
191+
192+
Other changes
193+
-------------
194+
195+
The radio core is no longer started automatically.

0 commit comments

Comments
 (0)