doc: Update ABI comp page and 54H gs guide

FrancescoSer · nordicjm · commit 33286926dc49 · 2025-09-15T13:29:42.000+01:00
Updated ABI comp page and 54H gs guide:
 Highlighted need to upgrade to the
 latest SoC binaries available.

Signed-off-by: Francesco Domenico Servidio &lt;francesco.servidio@nordicsemi.no&gt;
diff --git a/doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_gs.rst b/doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_gs.rst
@@ -104,15 +104,16 @@ Install a terminal emulator, such as the `Serial Terminal app`_ (from the nRF Co
 Both of these terminal emulators start the required :ref:`toolchain environment <using_toolchain_environment>`.
 
 .. _ug_nrf54h20_gs_bringup:
+.. _ug_nrf54h20_gs_bringup_bicr:
 .. _ug_nrf54h20_gs_bicr:
 
 .. rst-class:: numbered-step
 
-Programming the BICR
-********************
+Bring-up step: Programming the BICR
+***********************************
 
 The Board Information Configuration Registers (BICR) are non-volatile memory (NVM) registers that contain information on how the nRF54H20 SoC must interact with other board elements, including information about power and clock delivery to the SoC.
-To prepare the nRF54H20 DK for first use, you must manually program the values of the BICR using a precompiled BICR binary file (:file:`bicr.hex`).
+To prepare the nRF54H20 DK for its first use, you must manually program the required values into the BICR using a precompiled BICR binary file (:file:`bicr.hex`).
 
 1. Download the `nRF54H20 DK BICR binary file`_.
 #. Connect the nRF54H20 DK to your computer using the **DEBUGGER** port on the DK.
@@ -129,11 +130,12 @@ To prepare the nRF54H20 DK for first use, you must manually program the values o
       nrfutil device program --options chip_erase_mode=ERASE_NONE --firmware bicr.hex --core Application --serial-number <serial_number>
 
 .. _ug_nrf54h20_SoC_binaries:
+.. _ug_nrf54h20_gs_bringup_soc_bin:
 
 .. rst-class:: numbered-step
 
-Programming the nRF54H20 SoC binaries
-*************************************
+Bring-up step: Programming the nRF54H20 SoC binaries
+****************************************************
 
 .. note::
    To program the nRF54H20 SoC binaries based on IronSide SE on your nRF54H20 SoC-based device, your device must be in lifecycle state (LCS) ``EMPTY``.
@@ -142,11 +144,11 @@ Programming the nRF54H20 SoC binaries
    Devices already provisioned using SUIT-based binaries and in LCS ``RoT`` cannot be transitioned back to LCS ``EMPTY``.
    For more information, see :ref:`abi_compatibility`.
 
-After programming the BICR, program the nRF54H20 SoC with the :ref:`nRF54H20 SoC binaries <abi_compatibility>`.
+After programming the BICR, program the :ref:`nRF54H20 SoC binaries <abi_compatibility>`.
 This bundle contains the precompiled firmware for the :ref:`Secure Domain <ug_nrf54h20_secure_domain>` and :ref:`System Controller <ug_nrf54h20_sys_ctrl>`.
 To program the nRF54H20 SoC binaries to the nRF54H20 DK, do the following:
 
-1. Download the `nRF54H20 SoC binaries v22.2.0+14`_, compatible with the nRF54H20 DK v0.9.0 and later DK revisions.
+1. Download the `latest nRF54H20 SoC binaries`_.
 
    .. note::
       On MacOS, ensure that the ZIP file is not unpacked automatically upon download.
@@ -155,10 +157,12 @@ To program the nRF54H20 SoC binaries to the nRF54H20 DK, do the following:
 
       nrfutil device x-provision-nrf54h --firmware <path-to_bundle_zip_file> --serial-number <serial_number>
 
+.. _ug_nrf54h20_gs_bringup_trasition:
+
 .. rst-class:: numbered-step
 
-Transitioning the nRF54H20 SoC to RoT
-*************************************
+Bring-up step: Transitioning the nRF54H20 SoC to RoT
+****************************************************
 
 The current nRF54H20 DK comes with its lifecycle state (LCS) set to ``EMPTY``.
 To operate correctly, you must transition its lifecycle state to Root of Trust (``RoT``).
diff --git a/doc/nrf/links.txt b/doc/nrf/links.txt
@@ -1934,6 +1934,8 @@
 
 .. _`nRF54H20 SoC binaries v22.2.0+14`: https://files.nordicsemi.com/artifactory/SDSC/external/nrf54h20_soc_binaries_v22.2.0%2B14.zip
 
+.. _`latest nRF54H20 SoC binaries`: https://files.nordicsemi.com/artifactory/SDSC/external/
+
 .. ### Descr: Old 54H BICR file
 
 .. _`BICR binary file`: https://files.nordicsemi.com/artifactory/SDSC/external/bicr_ext_loadcap.hex
diff --git a/doc/nrf/releases_and_maturity/abi_compatibility.rst b/doc/nrf/releases_and_maturity/abi_compatibility.rst
@@ -19,31 +19,24 @@ When ABI compatibility is maintained, binaries of one component can interface co
 For example, adding a new function to a library is typically an ABI-compatible change, as existing binaries remain functional.
 However, changes that affect data structure layouts, such as altering field order or size, break ABI compatibility because they change the memory layout expected by existing binaries.
 
-ABI compatibility matrix for the nRF54H20 SoC binaries
-******************************************************
+ABI compatibility for the nRF54H20 SoC binaries
+***********************************************
 
-.. caution::
-
-   * To use the most recent version of the |NCS|, you must provision your nRF54H20-based device with the compatible IronSide-based SoC binaries.
-     Devices already provisioned using SUIT-based SoC binaries and in LCS ``RoT`` cannot be transitioned back to LCS ``EMPTY``.
+.. note::
+   To use the most recent version of the |NCS|, always provision your nRF54H20 SoC-based device with the latest IronSide SE-based SoC binaries available.
 
-     For more information on provisioning devices, see :ref:`ug_nrf54h20_gs_bringup`.
+.. caution::
+   The nRF54H20 SoC binaries do not support rollbacks to previous versions.
 
-   * The nRF54H20 SoC binaries only support specific versions of the |NCS| and do not support rollbacks to previous versions.
-     Upgrading the nRF54H20 SoC binaries on your development kit might break the DK's compatibility with applications developed for earlier versions of the |NCS|.
+You must download the `latest nRF54H20 SoC binaries`_ for the nRF54H20 SoC.
 
-     To migrate your existing applications to the newest version of the |NCS|, see :ref:`migration_guides`.
+Legacy ABI compatibility matrix for the nRF54H20 SoC binaries
+=============================================================
 
-The following table illustrates ABI compatibility between different versions of the nRF54H20 SoC binaries and the |NCS|:
-
-.. list-table::
-   :header-rows: 1
-
-   * - |NCS| versions
-     - Compatible nRF54H20 SoC binaries version based on IronSide Secure Element (IronSide SE)
-   * - |NCS| v3.1.0
-     - `nRF54H20 SoC binaries v22.2.0+14`_, compatible with the nRF54H20 DK v0.9.0 and later DK revisions in LCS ``EMPTY``.
+The following table illustrates the legacy ABI compatibility between older versions of the nRF54H20 SoC binaries and older versions of the |NCS|:
 
+.. caution::
+   * Devices already provisioned using SUIT-based SoC binaries and in LCS ``RoT`` cannot be upgraded to IronSide SE.
 
 .. list-table::
    :header-rows: 1
@@ -69,19 +62,131 @@ The following table illustrates ABI compatibility between different versions of
    * - |NCS| v2.6.99-cs2
      - nRF54H20 SoC binaries v0.3.3
 
-Maintaining ABI compatibility ensures that the Secure Domain and System Controller firmware binaries do not need to be recompiled each time the application, radio binaries, or both are recompiled, as long as they are based on a compatible |NCS| version.
-Additionally, maintaining ABI compatibility allows the nRF54H20 SoC binary components to work together without recompilation when updating to newer |NCS| versions.
-
 Provisioning the nRF54H20 SoC
 *****************************
 
 To provision the nRF54H20 SoC using the nRF54H20 SoC binaries, see :ref:`ug_nrf54h20_gs_bringup`.
 
-nRF54H20 SoC binaries v22.2.0+14 changelog
-******************************************
+nRF54H20 SoC binaries changelog
+*******************************
 
 The following sections provide detailed lists of changes by component.
 
+IronSide Secure Element (IronSide SE) v23.0.1+16
+================================================
+
+Changed
+-------
+
+* The domain-specific built-in keys identified by ``CRACEN_BUILTIN_*_ID``. (NCSDK-35202)
+* The way IronSide SE treats the ``UICR.VERSION`` field. (NCSDK-35253)
+
+  The erase value is now interpreted as the highest supported UICR format version.
+  Other values must match a supported version or cause a boot error.
+  Currently, only version 2.0 (``0x00020000``) is supported.
+* IronSide SE no longer disables RETAIN for every GPIO pin at boot. (NCSDK-35080)
+
+  Pins are now retained when the application boots, and the application must disable retention before using them.
+* ``UICR.LOCK`` can now be set in ``LCS_EMPTY`` without hindering LFCLK calibration. (NCSDK-34458)
+
+Fixed
+-----
+
+* EXMIF XIP region is now accessible. (NCSDK-35256)
+
+IronSide Secure Element (IronSide SE) v23.0.0+15
+================================================
+
+Added
+-----
+
+* IronSide SE now supports most CRACEN PSA features.
+  The available features correspond to the following configuration::
+
+    CONFIG_PSA_WANT_GENERATE_RANDOM=y
+    CONFIG_PSA_WANT_ALG_CTR_DRBG=y
+    CONFIG_PSA_WANT_ALG_CBC_PKCS7=y
+    CONFIG_PSA_WANT_ALG_CBC_NO_PADDING=y
+    CONFIG_PSA_WANT_ALG_CCM=y
+    CONFIG_PSA_WANT_ALG_CHACHA20_POLY1305=y
+    CONFIG_PSA_WANT_ALG_CMAC=y
+    CONFIG_PSA_WANT_ALG_CTR=y
+    CONFIG_PSA_WANT_ALG_DETERMINISTIC_ECDSA=y
+    CONFIG_PSA_WANT_ALG_ECB_NO_PADDING=y
+    CONFIG_PSA_WANT_ALG_ECDH=y
+    CONFIG_PSA_WANT_ALG_ECDSA=y
+    CONFIG_PSA_WANT_ALG_ECDSA_ANY=y
+    CONFIG_PSA_WANT_ALG_GCM=y
+    CONFIG_PSA_WANT_ALG_HKDF=y
+    CONFIG_PSA_WANT_ALG_HMAC=y
+    CONFIG_PSA_WANT_ALG_JPAKE=y
+    CONFIG_PSA_WANT_ALG_PBKDF2_HMAC=y
+    CONFIG_PSA_WANT_ALG_PBKDF2_AES_CMAC_PRF_128=y
+    CONFIG_PSA_WANT_ALG_PURE_EDDSA=y
+    CONFIG_PSA_WANT_ALG_SHA_256=y
+    CONFIG_PSA_WANT_ALG_SHA_384=y
+    CONFIG_PSA_WANT_ALG_SHA_512=y
+    CONFIG_PSA_WANT_ALG_SHA3_256=y
+    CONFIG_PSA_WANT_ALG_SHA3_384=y
+    CONFIG_PSA_WANT_ALG_SHA3_512=y
+    CONFIG_PSA_WANT_ALG_SHAKE256_512=y
+    CONFIG_PSA_WANT_ALG_SP800_108_COUNTER_CMAC=y
+    CONFIG_PSA_WANT_ALG_SPAKE2P_HMAC=y
+    CONFIG_PSA_WANT_ALG_SPAKE2P_CMAC=y
+    CONFIG_PSA_WANT_ALG_SPAKE2P_MATTER=y
+    CONFIG_PSA_WANT_ALG_TLS12_ECJPAKE_TO_PMS=y
+    CONFIG_PSA_WANT_ALG_TLS12_PRF=y
+    CONFIG_PSA_WANT_ALG_TLS12_PSK_TO_MS=y
+    CONFIG_PSA_WANT_ALG_HKDF_EXTRACT=y
+    CONFIG_PSA_WANT_ALG_HKDF_EXPAND=y
+    CONFIG_PSA_WANT_ALG_ED25519PH=y
+    CONFIG_PSA_WANT_ECC_MONTGOMERY_255=y
+    CONFIG_PSA_WANT_ECC_SECP_R1_256=y
+    CONFIG_PSA_WANT_ECC_SECP_R1_384=y
+    CONFIG_PSA_WANT_ECC_SECP_R1_521=y
+    CONFIG_PSA_WANT_ECC_TWISTED_EDWARDS_255=y
+    CONFIG_PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_GENERATE=y
+    CONFIG_PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_IMPORT=y
+    CONFIG_PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_EXPORT=y
+    CONFIG_PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_DERIVE=y
+    CONFIG_PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY=y
+    CONFIG_PSA_WANT_KEY_TYPE_AES=y
+    CONFIG_PSA_WANT_AES_KEY_SIZE_128=y
+    CONFIG_PSA_WANT_AES_KEY_SIZE_256=y
+    CONFIG_PSA_WANT_KEY_TYPE_CHACHA20=y
+    CONFIG_PSA_WANT_KEY_TYPE_PASSWORD=y
+    CONFIG_PSA_WANT_KEY_TYPE_PASSWORD_HASH=y
+    CONFIG_PSA_WANT_KEY_TYPE_SPAKE2P_KEY_PAIR_DERIVE=y
+    CONFIG_PSA_WANT_KEY_TYPE_SPAKE2P_KEY_PAIR_EXPORT=y
+    CONFIG_PSA_WANT_KEY_TYPE_SPAKE2P_KEY_PAIR_IMPORT=y
+    CONFIG_PSA_WANT_KEY_TYPE_SPAKE2P_KEY_PAIR_GENERATE=y
+    CONFIG_PSA_WANT_KEY_TYPE_SPAKE2P_PUBLIC_KEY=y
+
+* Support for a secondary boot mode. (NCSDK-32171)
+
+  The secondary mode lets you define a separate application firmware that is started on boot error or when requested over IPC.
+  This is configured through the ``UICR.SECONDARY`` registers and can be used for recovery or updates.
+* Support for ``UICR.WDTSTART``, which can be used to automatically start a local domain watchdog ahead of the application boot. (NCSDK-35046)
+* Support for PSA Internal Trusted Storage (ITS). (NCSDK-18548)
+
+  It is configured through the following ``UICR.SECURESTORAGE`` registers:
+
+  * ``UICR.SECURESTORAGE.CRYPTO`` - Enables persistent key storage for the PSA Crypto API.
+  * ``UICR.SECURESTORAGE.ITS`` - Enables the PSA ITS API for managing other sensitive assets.
+  * ``UICR.SECURESTORAGE.ENABLE`` and ``UICR.SECURESTORAGE.ADDRESS`` - Required to enable one or both features.
+
+* Support for the IronSide SE DVFS service, replacing the NRFS DVFS service. (NRFX-7321)
+
+Updated
+-------
+
+* Renamed the release artifact from :file:`sysctrl.hex` to :file:`ironside_se.hex` to correctly reflect its content.
+
+Removed
+-------
+
+* NRFS DVFS service support.
+
 IronSide Secure Element (IronSide SE) v22.2.0+14
 ================================================
 
@@ -105,17 +210,17 @@ Removed
 IronSide Secure Element (IronSide SE) v22.1.0+13
 ================================================
 
-* Added support for configuring TDD (CoreSight++) from local domains (NCSDK-33486).
+* Added support for configuring TDD (CoreSight++) from local domains. (NCSDK-33486)
 
 IronSide Secure Element (IronSide SE) v22.0.4+12
 ================================================
 
 Fixed
 -----
 
-* An issue where the device became stuck in recovery mode after performing a recovery upgrade (NCSDK-34258).
-* An issue where the eraseall operation, on a device in LCS ROT, was permitted regardless of the contents of UICR (NCSDK-34232).
-* An issue where the recovery firmware would incorrectly determine that UICR was corrupted (NCSDK-32241).
+* An issue where the device became stuck in recovery mode after performing a recovery upgrade. (NCSDK-34258)
+* An issue where the eraseall operation, on a device in LCS ROT, was permitted regardless of the contents of UICR. (NCSDK-34232)
+* An issue where the recovery firmware would incorrectly determine that UICR was corrupted. (NCSDK-32241)
 
 Updated
 -------
@@ -130,11 +235,11 @@ Fixed
 
 * psa_crypto:
 
-   * Bytes written are now correctly returned (in place of buffer size) (NCSDK-34172).
-   * Added missing ECC_MONTGOMERY_255 configuration (NCSDK-34200).
-   * Passing 0-sized buffers are now allowed for optional arguments (NCSDK-34171).
+   * Bytes written are now correctly returned (in place of buffer size). (NCSDK-34172)
+   * Added missing ECC_MONTGOMERY_255 configuration. (NCSDK-34200)
+   * Passing 0-sized buffers are now allowed for optional arguments. (NCSDK-34171).
 
-* The default owner ID of some peripherals, where previously it was set to SECURE or SYSCTRL instead of APPLICATION (NCSDK-34187).
+* The default owner ID of some peripherals, where previously it was set to SECURE or SYSCTRL instead of APPLICATION. (NCSDK-34187)
 
 IronSide Secure Element (IronSide SE) v22.0.2+10
 ================================================
@@ -219,7 +324,7 @@ IronSide Secure Element (IronSide SE) v21.0.1
 Added
 -----
 
-* Boot report to be written to radio core (NCSDK-33583).
+* Boot report to be written to radio core. (NCSDK-33583)
 
 Updated
 -------
@@ -242,17 +347,17 @@ Added
 * Support for the IronSide SE update service. (NCSDK-32173)
   This service allows updating IronSide SE firmware using the ``west ncs-ironside-se-update`` command.
   The update is performed over SWD, and the device must be in a debug mode.
-* Experimental support for a new UICR format (NCSDK-32444).
+* Experimental support for a new UICR format. (NCSDK-32444)
   At this stage, the functionality is mainly for internal testing and development, and user tools for interacting with UICR will be added at a later stage.
-* Boot report support (NCSDK-32393).
-* CPUCONF service for booting the radio core (NCSDK-32925).
+* Boot report support. (NCSDK-32393)
+* CPUCONF service for booting the radio core. (NCSDK-32925)
   Currently, only ``hello world`` is supported.
-* IronSide calls, the successor to SSF (NCSDK-32441).
+* IronSide calls, the successor to SSF. (NCSDK-32441).
 
 Updated
 -------
 
-* The limited PSA Crypto API is now implemented as an IronSide call (NCSDK-32912).
+* The limited PSA Crypto API is now implemented as an IronSide call. (NCSDK-32912)
   This replaces the temporary IPC mechanism from the last release.
 
 Fixed
@@ -338,10 +443,10 @@ Updated
 Removed (from legacy SUIT-based SDFW)
 -------------------------------------
 
-* SSF and all SSF services have been disabled (NCSDK-32000).
-* Resource configuration based on UICR has been disabled (NCSDK-31999).
-* The SDFW ADAC interface has been disabled (NCSDK-31994).
-* SUIT is no longer supported (NCSDK-31996).
+* SSF and all SSF services have been disabled. (NCSDK-32000)
+* Resource configuration based on UICR has been disabled. (NCSDK-31999)
+* The SDFW ADAC interface has been disabled. (NCSDK-31994)
+* SUIT is no longer supported. (NCSDK-31996)
 
 nRF54H20 SoC binaries v0.9.6 changelog
 **************************************
