modules: hal_nordic: Integrate nrf-regtool

nrf-regtool is a Python utility from Nordic Semiconductor, which is used
for generating binary files with register values for given peripherals.
It sources the descriptions of peripheral registers from CMSIS-SVD files
(typically ones bundled with nRF MDK).

For some peripherals, such as UICR, nrf-regtool supports parsing values
from devicetree as well, based on the bindings already found in Zephyr.

Currently, this tool is not submitted as a script to Zephyr, but it can
be installed from PyPI.

Having nrf-regtool installed is recommended when working with nRF54H20.
Booting the Application or Radiocore CPU requires flashing not only its
firmware, but also its respective UICR instance. On this SoC, the UICR
is used to assign ownership of global hardware resources, including
memory and peripherals, to individual cores. The Zephyr build system can
call nrf-regtool to generate the UICR based on devicetree, to reflect
the boot-time hardware configuration required for a given application.
The generated `uicr.hex` is then merged with `zephyr.hex`, so that they
can be flashed together using west.

The build system integration takes the form of a CMake package, which
includes a version check and reusable components; over time, some of
these components can be reused by sysbuild. This package is located in
the `hal_nordic` module, because it depends on the `SOC_SVD_FILE` CMake
variable, which is defined there as well.

Signed-off-by: Grzegorz Swiderski <grzegorz.swiderski@nordicsemi.no>

modules/hal_nordic/CMakeLists.txt

@@ -6,3 +6,19 @@ if (CONFIG_NRF_802154_RADIO_DRIVER OR CONFIG_NRF_802154_SERIALIZATION)
 endif (CONFIG_NRF_802154_RADIO_DRIVER OR CONFIG_NRF_802154_SERIALIZATION)
 
 add_subdirectory_ifdef(CONFIG_HAS_NRFX nrfx)
+
+if(CONFIG_NRF_REGTOOL_GENERATE_UICR)
+  list(APPEND nrf_regtool_components GENERATE:UICR)
+endif()
+if(DEFINED nrf_regtool_components)
+  find_package(nrf-regtool 5.0.1
+    COMPONENTS ${nrf_regtool_components}
+    PATHS ${CMAKE_CURRENT_LIST_DIR}/nrf-regtool
+    NO_CMAKE_PATH
+    NO_CMAKE_ENVIRONMENT_PATH
+    NO_SYSTEM_ENVIRONMENT_PATH
+    NO_CMAKE_PACKAGE_REGISTRY
+    NO_CMAKE_SYSTEM_PATH
+    NO_CMAKE_SYSTEM_PACKAGE_REGISTRY
+  )
+endif()

modules/hal_nordic/Kconfig

@@ -236,3 +236,4 @@ endif # NRF_802154_RADIO_DRIVER || NRF_802154_SERIALIZATION
 endmenu # HAS_NORDIC_DRIVERS
 
 rsource "nrfx/Kconfig"
+rsource "Kconfig.nrf_regtool"

modules/hal_nordic/Kconfig.nrf_regtool

@@ -0,0 +1,36 @@
+# Copyright (c) 2024 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+menu "nrf-regtool options"
+	depends on SOC_SERIES_NRF54HX
+
+config NRF_REGTOOL_GENERATE_UICR
+	bool "Generate UICR"
+	help
+	  Generate a UICR hex based on devicetree contents using nrf-regtool.
+	  CPU domains that require UICR allocation aren't bootable without it
+	  being programmed alongside the firmware.
+
+config NRF_REGTOOL_VERBOSITY
+	int "Verbosity level of console output"
+	range 0 3
+	default 0
+	help
+	  Level of verbose output that nrf-regtool will print to the console.
+
+	  0. Only critical information and warnings.
+	  1. Print a pretty, human-readable representation of a peripheral's
+	     configuration. This is recommended for inspecting register values.
+	  2. Print extra details for debugging purposes, such as memory maps of
+	     the peripheral configurations, but in a less readable format.
+	  3. Print even more details, which are typically only useful for
+	     nrf-regtool developers.
+
+config NRF_REGTOOL_EXTRA_GENERATE_ARGS
+	string "Extra arguments to 'nrf-regtool generate'"
+	help
+	  List of additional arguments to every nrf-regtool invocation used for
+	  generating hex files. Example value: "--fill all --fill-byte 0xff".
+	  Run "nrf-regtool generate -h" to see all of the available options.
+
+endmenu

modules/hal_nordic/nrf-regtool/nrf-regtoolConfig.cmake

@@ -0,0 +1,48 @@
+# Copyright (c) 2024 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+function(nrf_regtool_generate_hex_from_dts peripheral)
+  string(TOLOWER "${peripheral}.hex" generated_hex_name)
+  string(TOLOWER "${peripheral}_merged.hex" merged_hex_name)
+
+  # Prepare common argument sub-lists.
+  string(REPEAT "-v;" ${CONFIG_NRF_REGTOOL_VERBOSITY} verbosity)
+  list(TRANSFORM CACHED_DTS_ROOT_BINDINGS PREPEND "--bindings-dir;" OUTPUT_VARIABLE bindings_dirs)
+  separate_arguments(extra_args UNIX_COMMAND "${CONFIG_NRF_REGTOOL_EXTRA_GENERATE_ARGS}")
+
+  set(generated_hex_file ${PROJECT_BINARY_DIR}/${generated_hex_name})
+  execute_process(
+    COMMAND ${NRF_REGTOOL} ${verbosity} generate
+    --peripheral ${peripheral}
+    --svd-file ${SOC_SVD_FILE}
+    --dts-file ${ZEPHYR_DTS}
+    ${bindings_dirs}
+    --output-file ${generated_hex_file}
+    ${extra_args}
+    WORKING_DIRECTORY ${APPLICATION_SOURCE_DIR}
+    COMMAND_ERROR_IS_FATAL ANY
+  )
+  message(STATUS "Generated ${peripheral} hex file: ${generated_hex_file}")
+
+  set(merged_hex_file ${PROJECT_BINARY_DIR}/${merged_hex_name})
+  set_property(GLOBAL APPEND PROPERTY extra_post_build_commands
+    COMMAND ${PYTHON_EXECUTABLE} ${ZEPHYR_BASE}/scripts/build/mergehex.py
+    -o ${merged_hex_file}
+    ${generated_hex_file}
+    ${PROJECT_BINARY_DIR}/${KERNEL_HEX_NAME}
+  )
+  set_property(TARGET runners_yaml_props_target PROPERTY hex_file ${merged_hex_file})
+endfunction()
+
+
+foreach(component IN LISTS ${CMAKE_FIND_PACKAGE_NAME}_FIND_COMPONENTS)
+  string(REGEX MATCH "(^.*):(.*$)" match ${component})
+  set(operation  "${CMAKE_MATCH_1}")
+  set(peripheral "${CMAKE_MATCH_2}")
+
+  if(operation STREQUAL "GENERATE")
+    nrf_regtool_generate_hex_from_dts(${peripheral})
+  else()
+    message(FATAL_ERROR "Unrecognized package component: \"${component}\"")
+  endif()
+endforeach()

modules/hal_nordic/nrf-regtool/nrf-regtoolConfigVersion.cmake

@@ -0,0 +1,32 @@
+# Copyright (c) 2024 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+find_program(NRF_REGTOOL nrf-regtool)
+
+if(NRF_REGTOOL)
+  execute_process(
+    COMMAND ${NRF_REGTOOL} --version
+    OUTPUT_VARIABLE version
+    RESULT_VARIABLE result
+  )
+
+  if(result EQUAL 0 AND version MATCHES "version ([0-9]+[.][0-9]+[.][0-9]+)")
+    set(PACKAGE_VERSION ${CMAKE_MATCH_1})
+    if(PACKAGE_VERSION VERSION_GREATER_EQUAL PACKAGE_FIND_VERSION)
+      set(PACKAGE_VERSION_COMPATIBLE TRUE)
+      if(PACKAGE_VERSION VERSION_EQUAL PACKAGE_FIND_VERSION)
+        set(PACKAGE_VERSION_EXACT TRUE)
+      endif()
+
+      message(STATUS
+        "Found nrf-regtool (found suitable version \"${PACKAGE_VERSION}\", "
+        "minimum required is \"${PACKAGE_FIND_VERSION}\")"
+      )
+      return()
+    endif()
+  endif()
+endif()
+
+# We only get here if we don't pass the version check.
+set(PACKAGE_VERSION_UNSUITABLE TRUE)
+set(NRF_REGTOOL NRF_REGTOOL-NOTFOUND CACHE INTERNAL "Path to a program")

soc/arm/nordic_nrf/nrf54h/Kconfig.defconfig.nrf54h20_cpuapp

@@ -11,4 +11,7 @@ config SOC
 config NUM_IRQS
 	default 471
 
+config NRF_REGTOOL_GENERATE_UICR
+	default y
+
 endif # SOC_NRF54H20_ENGA_CPUAPP

soc/arm/nordic_nrf/nrf54h/Kconfig.defconfig.nrf54h20_cpurad

@@ -11,4 +11,7 @@ config SOC
 config NUM_IRQS
 	default 471
 
+config NRF_REGTOOL_GENERATE_UICR
+	default y
+
 endif # SOC_NRF54H20_ENGA_CPURAD