doc: nrf54h20: add description of sdfw bootstatus

Ref: NCSDK-30107
Signed-off-by: Håkon Amundsen <[email protected]>
(cherry picked from commit a52b459)

Author: hakonfam

doc/nrf/app_dev/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_debugging.rst

@@ -122,3 +122,87 @@ One of the potential root causes of fatal errors in an application are stack ove
 Read the Stack Overflows section on the :ref:`zephyr:fatal` page in the Zephyr documentation to learn about stack overflows and how to debug them.
 
 You can also use a separate module, such as Zephyr's :ref:`zephyr:thread_analyzer`, to make sure that the stack sizes used by your application are big enough to avoid stack overflows.
+
+Debugging errors reported by SDFW
+*********************************
+
+The Secure Domain Firmware (SDFW) report errors through the ``CTRL-AP.BOOTSTATUS`` register.
+You can read this value using the ``nrfutil device x-boot-status-get`` command:
+
+.. parsed-literal::
+   :class: highlight
+
+    nrfutil device x-boot-status-get --help
+
+SDFW errors
+===========
+
+A value of ``0`` indicates *no error*, while any other value signifies that an error has occurred.
+
+.. note::
+   ``0`` is the reset value of this register.
+   Therefore, a device experiencing erratic behavior might still report ``0`` incorrectly.
+   For example, this may occur if the device is in a boot loop.
+
+
+Several components report errors through this register.
+The first 4 bits of the first byte is reserved for future use and must be ``0``, the second 4 bits of the bootstatus indicate which component reported an error:
+
+ * System Controller ROM -> ``0x01``
+ * Secure Domain ROM -> ``0x02``
+ * System Controller Firmware -> ``0x0A``
+ * Secure Domain Firmware -> ``0x0B``
+
+.. note::
+      Each one of these values has a different handling of the remaining bits.
+      This chapter only describes the semantics for Secure Domain Firmware errors (``0x0B******``).
+
+
+The second byte describes the boot step within the SDFW booting process that reported the failure.
+For more information, see `SDFW Boot Steps`_
+The last two bytes contain the lower 16 bits of the error code.
+
+For example, ``0x0BA1FF62`` indicates that the SDFW reported an error in the BICR validate step (``0xA1``) with error message ``0xFF62``, or ``-158``.
+
+SDFW Boot Steps
+---------------
+
+The boot steps are defined as follows:
+
+.. parsed-literal::
+   :class: highlight
+
+    #define BOOTSTATUS_STEP_START_GRTC 0x06
+    #define BOOTSTATUS_STEP_SDFW_UPDATE 0x30
+    #define BOOTSTATUS_STEP_BELLBOARD_CONFIG 0x4F
+    #define BOOTSTATUS_STEP_SUIT_INIT 0x6F
+    #define BOOTSTATUS_STEP_DOMAIN_ALLOCATE 0x8F
+    #define BOOTSTATUS_STEP_MEMORY_FINALIZE 0x91
+    #define BOOTSTATUS_STEP_TRACEHOST_INIT 0x93
+    #define BOOTSTATUS_STEP_CURRENT_LIMITED 0xA0
+    #define BOOTSTATUS_STEP_BICR_VALIDATE 0xA1
+    #define BOOTSTATUS_STEP_DOMAIN_BOOT 0xAF
+    #define BOOTSTATUS_STEP_ADAC 0xC0
+    #define BOOTSTATUS_STEP_SERVICES 0xCF
+
+Errors are not accumulated, as only one error is reported even if multiple boot steps fail.
+The SDFW chooses which error to report if multiple errors occur.
+The types of errors that can overwrite other errors are the following:
+
+ * An update of SDFW has failed.
+ * The SDFW is unable to initialize the ADAC over CTRL-AP communication.
+
+The following is a short description of the failures related to the boot steps:
+
+ * ``BOOTSTATUS_STEP_START_GRTC``  - SDFW was unable to initialize the driver used for the GRTC.
+ * ``BOOTSTATUS_STEP_SDFW_UPDATE`` - SDROM was instructed to install an update before last reset, and is indicating that an error occurred while performing the update.
+ * ``BOOTSTATUS_STEP_BELLBOARD_CONFIG`` - SDFW was unable to apply the static bellboard configuration.
+ * ``BOOTSTATUS_STEP_SUIT_INIT`` - A SUIT related error occurred.
+ * ``BOOTSTATUS_STEP_DOMAIN_ALLOCATE`` - An error occurred while allocating global resources.
+ * ``BOOTSTATUS_STEP_MEMORY_FINALIZE`` - SDFW was unable to apply the required memory protection configuration.
+ * ``BOOTSTATUS_STEP_TRACEHOST_INIT`` - An error occurred when initializing the trace host.
+ * ``BOOTSTATUS_STEP_CURRENT_LIMITED`` - System Controller ROM booted the system in current limited mode due to an issue in the BICR.
+ * ``BOOTSTATUS_STEP_BICR_VALIDATE`` - SDFW discovered an invalid BICR. Note that not seeing this issue does not imply that there are no issues in the BICR.
+ * ``BOOTSTATUS_STEP_DOMAIN_BOOT`` - An error occurred while booting the local domains.
+ * ``BOOTSTATUS_STEP_ADAC`` - An error occurred while initializing the ADAC transport.
+ * ``BOOTSTATUS_STEP_SERVICES`` - An error occurred while initializing the SSF server.