Add nRF54H20 BICR generation support

CODEOWNERS

@@ -656,7 +656,10 @@
 /scripts/ncs-toolchain-version-minimum.txt @nrfconnect/ncs-co-build-system @nrfconnect/ncs-ci
 /scripts/tools-versions-*.txt             @nrfconnect/ncs-co-build-system @nrfconnect/ncs-ci
 /scripts/requirements-*.txt               @nrfconnect/ncs-co-build-system @nrfconnect/ncs-ci
+/scripts/west_commands/utils/             @gmarull
 /scripts/west_commands/create_board/      @gmarull
+/scripts/west_commands/ncs-bicr.py        @gmarull
+/scripts/west_commands/ncs-board-actions.py @gmarull
 /scripts/west_commands/sbom/              @nrfconnect/ncs-si-muffin
 /scripts/west_commands/thingy91x_dfu.py   @nrfconnect/ncs-cia
 /scripts/west_commands/ncs-provision.py   @nrfconnect/ncs-pluto

doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_custom_pcb.rst

@@ -16,23 +16,22 @@ First, you need to create your PCB for the nRF54H20 SoC.
 
 We highly recommend using the PCB layouts and component values provided by Nordic Semiconductor, especially for clock and power sources, considering the following limitations:
 
-* The DC/DC inductor must be present on the PCB, and the ``inductor-present;`` node must be configured either in the :file:`zephyr/boards/your_board/nrf54h20dk_bicr.dtsi` file or in the section where ``bicr: bicr@fff87b0`` is present in the devicetree.
-* For the lowest sleep power consumption, use a 32 KHz crystal.
-* The **P9** port cannot be used with internal or external pull-down resistors.
-* For optimal performance, the output impedance of the **P6** and **P7** ports should match the PCB and external device pin impedance.
-* Use one of the following power supply options:
+* The DC/DC inductor must be present on the PCB for any of the supported power schemes.
+  Use one of the following power supply options:
 
   * VDDH higher than 2.05V.
   * VDDH shorted to VDD at 1.8V
 
+* For the lowest sleep power consumption, use a 32 KHz crystal.
+* The **P9** port cannot be used with internal or external pull-down resistors.
+* For optimal performance, the output impedance of the **P6** and **P7** ports should match the PCB and external device pin impedance.
+
 Prepare the configuration files for your custom board in the |NCS|
 ******************************************************************
 
-The nRF54H20 DK uses multiple board files for its configuration.
-You can use these files as a starting point for configuring your own custom board.
-When creating a :ref:`Zephyr repository application <zephyr:zephyr-repo-app>`, copy the files from :file:`sdk-zephyr/boards/nordic/nrf54h20dk` to the :file:`sdk-zephyr/boards/<your_vendor_prefix>/<your_custom_board_name>` file.
+Use the `nRF Connect for VS Code Extension Pack`_ to generate a custom board skeleton.
 
-You must edit the :file:`.dts` and :file:`.overlay` files for your project to match your board configuration, similarly to any new board added to the |NCS| or Zephyr.
+Use the nRF54H20 DK board files found in :file:`sdk-zephyr/boards/nordic/nrf54h20dk` as a reference point for configuring your own custom board.
 
 See the following documentation pages for more information:
 
@@ -60,16 +59,16 @@ The power and clock control firmware uses this information to apply the proper r
 
 BICR allows for the configuration of various components on your custom board, like the following:
 
-* Power rails
-* Low-frequency oscillator
+* Power scheme
+* Low-frequency oscillator (LFXO or LFRC)
 * High-frequency oscillator (HFXO)
 * GPIO ports power and drive control
 * Tamper switches
 * Active shield channels
 
-You can find the details in the DTS specification for the BICR in :file:`sdk-zephyr/dts/bindings/misc/nordic,nrf-bicr.yaml`
+You can find the details in the BICR configuration file scheme in :file:`sdk-zephyr/soc/nordic/nrf54h/bicr/bicr-schema.json`.
 
-When not set, the registers' default value is ``0xFFFFFFFF``.
+When the BICR has not been programmed, all the registers contain ``0xFFFFFFFF``.
 
 The ``LFOSC.LFXOCAL`` register is used by the device to store the calibration of the LFXO.
 
@@ -81,25 +80,23 @@ Each subsequent start will use this initial calibration as the starting point.
 BICR configuration
 ==================
 
-The nRF54H20 DK BICR configuration can be found in the board configuration directory as :file:`sdk-zephyr/boards/nordic/nrf54h20dk/nrf54h20dk_bicr.dtsi`.
+The nRF54H20 DK BICR configuration can be found in the board configuration directory as :file:`sdk-zephyr/boards/nordic/nrf54h20dk/bicr.json`.
 This file is used by the |NCS| build system to generate a corresponding HEX file.
-You can start from this file when editing the values of the devicetree properties inside your custom board folder (:file:`boards/nordic/your_custom_board`), according to your board configuration.
+The scheme for this file can be found in :file:`sdk-zephyr/soc/nordic/nrf54h/bicr/bicr-schema.json`.
 
 .. caution::
    A mismatch between the board and the configuration values in BICR can damage the device or set it in an unrecoverable state.
 
 Generate the BICR binary
 ========================
 
-To generate the BICR binary, you must first set the Kconfig option :kconfig:option:`CONFIG_NRF_REGTOOL_GENERATE_BICR` to ``y``.
-When running ``west build``, the build system then creates the relevant HEX file (:file:`bicr.hex`) at build time.
-Based on the peripheral definition extracted from the nRF54H20 SVD file, the modified registers from the configuration are mapped into their relevant position in memory.
+To generate the BICR binary, you must first set the Kconfig option :kconfig:option:`CONFIG_SOC_NRF54H20_GENERATE_BICR` to ``y``.
+When running ``west build`` for the ``cpuapp`` core, the build system creates the relevant HEX file (:file:`bicr.hex`) at build time.
 
 .. note::
-   If the build system cannot locate the ``bicr`` node inside your custom board's devicetree, or if you did not create a custom :file:`.dtsi` file for it, the BICR generation cannot progress, and the build system will skip it.
+   If the build system is unable to locate the :file:`bicr.json` file inside your custom board's directory, the build system will skip it.
 
-You can find the generated :file:`bicr.hex` file in the :file:`build_dir/zephyr/`.
-The presence of a ``bicr`` node in the application devicetree will automatically trigger a build of the BICR binary, and will place this file alongside the other binary outputs such as ``zephyr.hex`` and ``uicr.hex``.
+You can find the generated :file:`bicr.hex` file in the :file:`build_dir/<sample>/zephyr/`.
 
 Program the BICR binary
 =======================

doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_suit_recovery.rst

@@ -129,15 +129,15 @@ To turn an application into a recovery application, the following steps have to
 
    * :kconfig:option:`CONFIG_SUIT_RECOVERY` set to ``y``
    * :kconfig:option:`CONFIG_NRF_REGTOOL_GENERATE_UICR` set to ``n``
-   * :kconfig:option:`CONFIG_NRF_REGTOOL_GENERATE_BICR` set to ``n``
+   * :kconfig:option:`CONFIG_SOC_NRF54H20_GENERATE_BICR` set to ``n``
 
    To do that you can simply paste the following code snippet into your configuration files:
 
       .. code-block:: cfg
 
          CONFIG_SUIT_RECOVERY=y
          CONFIG_NRF_REGTOOL_GENERATE_UICR=n
-         CONFIG_NRF_REGTOOL_GENERATE_BICR=n
+         CONFIG_SOC_NRF54H20_GENERATE_BICR=n
 
 #. Create the overlay files to be used by the recovery application.
    In this guide it is assumed that for the application core they are placed in the custom recovery application directory in the :file:`boards/nrf54h20dk_nrf54h20_cpuapp.overlay` file.

samples/suit/flash_companion/prj.conf

@@ -63,7 +63,7 @@ CONFIG_USE_DT_CODE_PARTITION=y
 CONFIG_SUIT_LOCAL_ENVELOPE_GENERATE=n
 CONFIG_SUIT_ENVELOPE_TARGET=""
 CONFIG_NRF_REGTOOL_GENERATE_UICR=n
-CONFIG_NRF_REGTOOL_GENERATE_BICR=n
+CONFIG_SOC_NRF54H20_GENERATE_BICR=n
 
 # Enable canonical zcbor encoding
 CONFIG_ZCBOR_CANONICAL=y

samples/suit/recovery/prj.conf

@@ -11,7 +11,7 @@ CONFIG_SUIT_RECOVERY=y
 # It is the main application which is responsible for flashing and generating the UICR
 # configuration - the recovery application should not do it.
 CONFIG_NRF_REGTOOL_GENERATE_UICR=n
-CONFIG_NRF_REGTOOL_GENERATE_BICR=n
+CONFIG_SOC_NRF54H20_GENERATE_BICR=n
 
 ############
 

samples/suit/recovery/sysbuild/hci_ipc.conf

@@ -11,7 +11,7 @@ CONFIG_SUIT_RECOVERY=y
 # It is the main application which is responsible for flashing and generating the UICR
 # configuration - the recovery application should not do it.
 CONFIG_NRF_REGTOOL_GENERATE_UICR=n
-CONFIG_NRF_REGTOOL_GENERATE_BICR=n
+CONFIG_SOC_NRF54H20_GENERATE_BICR=n
 
 ###########
 CONFIG_BT_BUF_ACL_RX_SIZE=502

scripts/west-commands.yml

@@ -39,3 +39,13 @@ west-commands:
       - name: ncs-provision
         class: NcsProvision
         help: Provision utility
+  - file: scripts/west_commands/ncs-bicr.py
+    commands:
+      - name: ncs-bicr
+        class: NcsBICR
+        help: Assist with board BICR creation for any applicable Nordic SoC
+  - file: scripts/west_commands/ncs-board-actions.py
+    commands:
+      - name: ncs-board-actions
+        class: NcsBoardActions
+        help: Obtain available actions for any board

scripts/west_commands/create_board/config.yml

@@ -71,6 +71,30 @@ products:
                 arch: arm
                 ram: 188
                 flash: 324
+  - series: nrf54h
+    socs:
+      - name: nrf54h20
+        variants:
+          - name: ckaa
+            cores:
+              - name: cpuapp
+                arch: arm
+                ram: 256
+                flash: 296
+              - name: cpurad
+                arch: arm
+                ram: 192
+                flash: 256
+              - name: cpuppr
+                arch: riscv
+                ram: 62
+                flash: 62
+                xip: true
+              - name: cpuflpr
+                arch: riscv
+                ram: 46
+                flash: 46
+                xip: true
   - series: nrf91
     socs:
       - name: nrf9131

scripts/west_commands/create_board/ncs_create_board.py

@@ -4,10 +4,10 @@
 from pathlib import Path
 import json
 import shutil
+import sys
 
 from jinja2 import Environment, FileSystemLoader
 from west.commands import WestCommand
-from west import log
 from yaml import load
 import jsonschema
 
@@ -16,6 +16,12 @@
 except ImportError:
     from yaml import Loader
 
+sys.path.append(str(Path(__file__).parents[1]))
+import utils
+
+
+utils.install_json_excepthook()
+
 
 SCRIPT_DIR = Path(__file__).absolute().parent
 TEMPLATE_DIR = SCRIPT_DIR / "templates"
@@ -50,6 +56,11 @@ def do_run(self, args, unknown_args):
             schema = json.loads(f.read())
 
         if args.json_schema:
+            schema = {
+                "schema": schema,
+                "state": None,
+            }
+
             print(json.dumps(schema))
             return
 
@@ -62,7 +73,7 @@ def do_run(self, args, unknown_args):
         try:
             jsonschema.validate(input, schema)
         except jsonschema.ValidationError as e:
-            raise Exception("Board configuration is not valid") from e
+            raise ValueError("Board configuration is not valid") from e
 
         soc_parts = input["soc"].split("-")
         req_soc = soc_parts[0].lower()
@@ -81,8 +92,7 @@ def do_run(self, args, unknown_args):
                     break
 
         if not series:
-            log.err(f"Invalid/unsupported SoC: {req_soc}")
-            return
+            raise ValueError(f"Invalid/unsupported SoC: {req_soc}")
 
         targets = []
         for variant in soc["variants"]:
@@ -125,8 +135,7 @@ def do_run(self, args, unknown_args):
                 break
 
         if not targets:
-            log.err(f"Invalid/unsupported variant: {req_variant}")
-            return
+            raise ValueError(f"Invalid/unsupported variant: {req_variant}")
 
         # prepare Jinja environment
         env = Environment(
@@ -180,6 +189,14 @@ def do_run(self, args, unknown_args):
             tmpl = TEMPLATE_DIR / series / "board-shared_sram.dtsi"
             shutil.copy(tmpl, out_dir / f"{ input['board'] }-shared_sram.dtsi")
 
+        # nrf54H specific files
+        if series == "nrf54h":
+            tmpl = TEMPLATE_DIR / series / "board-ipc_conf.dtsi"
+            shutil.copy(tmpl, out_dir / f"{ input['board'] }-ipc_conf.dtsi")
+
+            tmpl = TEMPLATE_DIR / series / "board-memory_map.dtsi"
+            shutil.copy(tmpl, out_dir / f"{ input['board'] }-memory_map.dtsi")
+
         # nrf91 specific files
         if series == "nrf91":
             tmpl = env.get_template("board-partitioning.dtsi.jinja2")
@@ -200,12 +217,31 @@ def do_run(self, args, unknown_args):
             with open(out_dir / f"{ name }_defconfig", "w") as f:
                 f.write(tmpl.render(target=target))
 
-            tmpl = env.get_template("board.dts.jinja2")
+            if not target["xip"]:
+                tmpl = env.get_template("board.dts.jinja2")
+            else:
+                tmpl = env.get_template("board-xip.dts.jinja2")
+
             with open(out_dir / f"{name}.dts", "w") as f:
                 f.write(tmpl.render(target=target))
 
             tmpl = env.get_template("board_twister.yml.jinja2")
             with open(out_dir / f"{name}.yml", "w") as f:
                 f.write(tmpl.render(target=target))
 
-        print(f"Board {input['board']} created successfully")
+        # return post-commands
+        commands = []
+
+        if series == "nrf54h":
+            commands.append(
+                {
+                    "name": "Create BICR",
+                    "command": "west",
+                    "args": ["ncs-bicr", "--board-dir", str(out_dir.resolve())],
+                    "properties": {
+                        "providesJsonSchema": True,
+                    },
+                }
+            )
+
+        print(json.dumps({"commands": commands}))

scripts/west_commands/create_board/schema.json

@@ -39,6 +39,7 @@
         "nRF52840-QFAA",
         "nRF52840-QIAA",
         "nRF5340-QKAA",
+        "nRF54H20-CKAA",
         "nRF54L15-QFAA",
         "nRF9131-LACA",
         "nRF9151-LACA",

scripts/west_commands/create_board/templates/nrf54h/Kconfig.board.jinja2

@@ -0,0 +1,7 @@
+config BOARD_{{ board | upper }}
+	select SOC_NRF54H20_CPUAPP if BOARD_{{ board | upper }}_NRF54H20_CPUAPP
+	select SOC_NRF54H20_CPURAD if BOARD_{{ board | upper }}_NRF54H20_CPURAD
+	select SOC_NRF54H20_CPUPPR if BOARD_{{ board | upper }}_NRF54H20_CPUPPR || \
+					BOARD_{{ board | upper }}_NRF54H20_CPUPPR_XIP
+	select SOC_NRF54H20_CPUFLPR if BOARD_{{ board | upper }}_NRF54H20_CPUFLPR || \
+					BOARD_{{ board | upper }}_NRF54H20_CPUFLPR_XIP

scripts/west_commands/create_board/templates/nrf54h/Kconfig.defconfig.jinja2

@@ -0,0 +1,13 @@
+if BOARD_{{ board | upper }}_NRF54H20_CPUAPP
+
+config BT_HCI_IPC
+	default y if BT
+
+endif # BOARD_{{ board | upper }}_NRF54H20_CPUAPP
+
+if BOARD_{{ board | upper }}_NRF54H20_CPURAD
+
+config BT_CTLR
+	default y if BT
+
+endif # BOARD_{{ board | upper }}_NRF54H20_CPURAD

scripts/west_commands/create_board/templates/nrf54h/board-common.dtsi

@@ -0,0 +1,17 @@
+#include "{{ board }}-memory_map.dtsi"
+#include "{{ board }}-ipc_conf.dtsi"
+#include "{{ board }}-pinctrl.dtsi"
+
+&hfxo {
+	status = "okay";
+	accuracy-ppm = <30>;
+	startup-time-us = <850>;
+	mode = "crystal";
+};
+
+&lfxo {
+	status = "okay";
+	accuracy-ppm = <20>;
+	startup-time-us = <600000>;
+	mode = "crystal";
+};