This topic focuses on learning some core concepts related to defining custom board definitions for SoCs with multiple board targets like the nRF54L, nRF53, and nRF91-based SoCs.

In terms of custom board definitions, a significant difference between the nRF52 Series and the nRF54L/nRF53/nRF91 Series is the architecture and CPU they use. The nRF52 Series implements the Armv7-M architecture and has a Cortex-M4 CPU, whereas the nRF54L, nRF53, and nRF91 Series implement the Armv8-M architecture and has a Cortex-M33 CPU with TrustZone, which supports TF-M.

In addition to TF-M, the nRF53 Series features dual cores, each fully user-programmable. Furthermore, the nRF54L includes a RISC-V co-processor (Fast Lightweight Peripheral Processor – FLPR). This introduces some challenges when defining a custom board, which we will address in this topic and Exercise 2.

Trusted Firmware-M (TF-M)

Trusted Firmware-M (TF-M) is a blueprint for constructing a Secure Processing Environment (SPE) tailored to Arm M-profile architectures. TF-M relies on the principle of security through separation to safeguard sensitive credentials and code. Additionally, TF-M extends its protective capabilities to applications by offering security services, including Protected Storage, Cryptography, and Attestation.

The Nordic Semiconductor Series, which implements the Armv8-M architecture (Arm Cortex-M33), incorporates TrustZone technology. This technology enforces hardware-based segregation between Secure and Non-secure Processing Environments, effectively creating separate Trusted and Non-Trusted build images.

This means that we have two options for boards based on the nRF54L/nRF53/nRF91 Series. Either:

Option 1 – <board_target>/ns

Enforce security by separation by utilizing TF-M and have our application run in the Non-Secure Processing Environment and have TF-M run in the Secure Processing Environment.

Option 2 – <board_target>

Do not enforce security by separation by having our application run as a single image with full access privileges.

Let’s take a board with a board target <board_target> as an example. When building an application for the board, you could build for either <board_target> or <board_target>/ns.

• <board_target>: The application is built as a single image without security by separation.
• <board_target>/ns: The application will be built as a Non-Secure image. Hence, you will get security by separation as TF-M will automatically be built as the Secure image. The two images will be merged to form a combined image that will be used when programming or updating the device.

Working with the nRF53 Series

The nRF5340 is the only System on Chip (SoC) in the nRF53 Series. It is a wireless ultra-low-power multicore SoC with two fully programmable Arm Cortex-M33 processors: a network core and an application core.

See the nRF5340 Product Specification for more information about the nRF5340 SoC

Network core

The network core is an Arm Cortex-M33 processor with a reduced feature set, designed for ultra-low-power operation. Use this core for radio communication and for real-time processing tasks involving low-level radio protocol layers.

In nRF Connect SDK/Zephyr, firmware of the network core should be built using the following build target:

• <board_target>/cpunet

Application core

The application core is a full-featured Arm Cortex-M33 processor including DSP instructions and FPU. Use this core for tasks that require high performance and for application-level logic.

The M33 TrustZone, one of Cortex-M Security Extensions (CMSE), can divide the application MCU into Secure Processing Environment (SPE) and Non-Secure Processing Environment (NSPE). When the MCU boots, it always starts executing from the secure area.

In nRF Connect SDK/Zephyr, the firmware of the application core should be built using one of the following build targets:

• <board_target>/cpuapp for build targets with TF-M disabled.
• <board_target>/cpuapp/ns for build targets that have TF-M enabled and have the SPE firmware alongside the NSPE firmware.

Working with the nRF91 Series

The nRF91 Series is comprised of four members: nRF9160, nRF9161, nRF9131, and nRF9151 System in Packages (SiP). These are cellular ultra-low-power SiPs with only one fully programmable Arm Cortex-M33 core. The other core is dedicated to the Modem firmware; you can only flash it with a precompiled modem firmware binary.

In nRF Connect SDK/Zephyr, firmware for the nRF91 SIP should be built using one of the following build targets:

• <board_target>/cpuapp for build targets with TF-M disabled.
• <board_target>/cpuapp/ns for build targets that have TF-M enabled and have the SPE firmware alongside the NSPE firmware.

Working with the nRF54L Series

The nRF54L15, together with nRF54L10 and nRF54L05, make up the nRF54L Series. All nRF54L Series SoCs integrate an Arm Cortex-M33 application processor and a RISC-V coprocessor. The RISC-V coprocessor is called fast lightweight peripheral processor (FLPR), which is designed to address challenges associated with time-critical tasks that need to be managed concurrently with the main processor. In certain situations, it can serve as a replacement for an external MCU used to meet these requirements.

In nRF Connect SDK/Zephyr, code could run on nRF54L SoCs on either the Arm Cortex-M33 application core (cpuapp) or the RISC-V coprocessor (cpuflpr).

Application core

Building for the application core follows the default building process for the nRF Connect SDK.

• <board_target>/cpuapp for build targets with TF-M disabled.
• <board_target>/cpuapp/ns for build targets that have TF-M enabled and have the SPE firmware alongside the NSPE firmware.

RISC-V coprocessor (FLPR)

Building for the FLPR core is slightly different from the default nRF Connect SDK procedure. Using the FLPR core also requires additional configuration to enable it. Building the FLPR target is similar to the application core. However, the application core build must incorporate an overlay that enables the FLPR core. Below are the available build targets for FLPR.

• <board_target>/cpuflpr .  FLPR runs from SRAM, which is the recommended method. To build FLPR image with this variant, the application core image must include the nordic-flpr snippet.
• <board_target>/cpuflpr/xip. FLPR runs from RRAM. To build FLPR image with this variant, the application core image must include the nordic-flpr-xip snippet.

Enabling TF-M in board definition

The custom board directory is a single folder with both build target files (<board_target> & <board_target>/ns) in one folder. We will assume a custom board name of “DevAcademyL3E2” featuring the nRF9151 SoC, which we will create in Exercise 2.

In the custom board Kconfig and metadata files

1. board.yml metadata file needs to include the ns variant.

Below is a snippet for a custom board named “DevAcademyL3E2”.

board:
  name: devacademyl3e2
  vendor: nordic
  socs:
  - name: nrf9151
    variants:
    - name: 'ns'

2. A single Kconfig.defconfig file that should detect the passed normalized build target BOARD_DEVACADEMYL3E2_NRF9151_NS or BOARD_DEVACADEMYL3E2_NRF9151 and adjust the FLASH_LOAD_SIZE FLASH_LOAD_OFFSET accordingly.

For the secure board version, firmware is linked at the flash’s start or in the devicetree defined code-partition for MCUboot loading. When combined with a non-secure image, the secure firmware must fit within its code partition. For the non-secure board version, firmware must always be linked to the non-secure devicetree defined code-partition. This is done by setting Kconfig symbols based on devicetree partition details (Step 4).

Below is a snippet of a Kconfig.defconfig for the “DevAcademyL3E2” board.

# nRF9151 DK NRF9151 board configuration

# Copyright (c) 2023 Nordic Semiconductor ASA
# SPDX-License-Identifier: Apache-2.0

if BOARD_DEVACADEMYL3E2_NRF9151 || BOARD_DEVACADEMYL3E2_NRF9151_NS

# For the secure version of the board the firmware is linked at the beginning
# of the flash, or into the code-partition defined in DT if it is intended to
# be loaded by MCUboot. If the secure firmware is to be combined with a non-
# secure image (TRUSTED_EXECUTION_SECURE=y), the secure FW image shall always
# be restricted to the size of its code partition.
# For the non-secure version of the board, the firmware
# must be linked into the code-partition (non-secure) defined in DT, regardless.
# Apply this configuration below by setting the Kconfig symbols used by
# the linker according to the information extracted from DT partitions.

# Workaround for not being able to have commas in macro arguments
DT_CHOSEN_Z_CODE_PARTITION := zephyr,code-partition

config FLASH_LOAD_SIZE
	default $(dt_chosen_reg_size_hex,$(DT_CHOSEN_Z_CODE_PARTITION))
	depends on BOARD_NRF9151DK_NRF9151 && TRUSTED_EXECUTION_SECURE

if BOARD_NRF9151DK_NRF9151_NS

config FLASH_LOAD_OFFSET
	default $(dt_chosen_reg_addr_hex,$(DT_CHOSEN_Z_CODE_PARTITION))

config FLASH_LOAD_SIZE
	default $(dt_chosen_reg_size_hex,$(DT_CHOSEN_Z_CODE_PARTITION))

endif # BOARD_NRF9151DK_NRF9151_NS

config BT_HCI_VS
	default y if BT

config BT_WAIT_NOP
	default BT && $(dt_nodelabel_enabled,nrf5340_reset)

config I2C
	default $(dt_compat_on_bus,$(DT_COMPAT_NXP_PCAL6408A),i2c)

endif # BOARD_DEVACADEMY_NRF9151DK_NRF9151 || BOARD_DEVACADEMY_NRF9151DK_NRF9151_NS

3. Two _defconfig files, basically one for each board target. Therefore, we will have devacademyl3e2_nrf9151_ns_defconfig and devacademyl3e2_nrf9151_defconfig. In addition to the rules we discussed in Creating board files, we need to do the following.

3.1 In the devacademyl3e2_nrf9151_defconfig , we need to enable CONFIG_ARM_TRUSTZONE_M.

# SPDX-License-Identifier: Apache-2.0

# Enable MPU
CONFIG_ARM_MPU=y

# Enable hardware stack protection
CONFIG_HW_STACK_PROTECTION=y

# Enable TrustZone-M
CONFIG_ARM_TRUSTZONE_M=y

# Enable GPIO
CONFIG_GPIO=y

# Enable UART driver
CONFIG_SERIAL=y

# Enable console
CONFIG_CONSOLE=y
CONFIG_UART_CONSOLE=y

3.2 In the devacademyl3e2_nrf9151_ns_defconfig file , we need to enable both

• CONFIG_ARM_TRUSTZONE_M to enable TrustZone APIs for the non-secure domain (Application).
• CONFIG_TRUSTED_EXECUTION_NONSECURE to imply building Non-Secure firmware.

A Non-Secure firmware image will execute in Non-Secure state. Therefore, it shall not access CPU resources (memory areas, peripherals, interrupts etc.) belonging to the Secure domain.

# SPDX-License-Identifier: Apache-2.0

# Enable MPU
CONFIG_ARM_MPU=y

# Enable hardware stack protection
CONFIG_HW_STACK_PROTECTION=y

# Enable TrustZone-M
CONFIG_ARM_TRUSTZONE_M=y

# This board implies building Non-Secure firmware
CONFIG_TRUSTED_EXECUTION_NONSECURE=y

# Enable GPIO
CONFIG_GPIO=y

# Enable UART driver
CONFIG_SERIAL=y

# Enable console
CONFIG_CONSOLE=y
CONFIG_UART_CONSOLE=y

In the custom board Devicetree files

4. Building an application with TF-M, results in building Secure and Non-Secure images.

The secure image should be placed in flash0 (or in slot0, if MCUboot bootloader is present). Secure image will use sram0_s for system memory. The Non-Secure image should be placed in slot0_ns, and use sram0_ns for system memory. This can be done by including the SoC default partitioning .dtsi file available in the SDK (<SDK Installation Path>/dts/common/nordic).

4.1 Create a common Devicetree file devacademyl3e2_nrf9151_common.dtsi (see Exercise 2 source code). In the common Devicetree file, two devicetree files need to be included:

• One common pinctrl file devacademy_nrf9151_common-pinctrl.dtsi (See Exercise 2 source code).

• Default memory partition configuration file for the SoC, for the nRF9151: #include <common/nordic/nrf91xx_partition.dtsi>

4.2 Create a per-image Devicetree file (devacademyl3e2_nrf9151.dts and devacademyl3e2_nrf9151_ns.dts) to select the chosen nodes for flash and RAM and disable peripherals allocated to the other image.

Example devacademyl3e2_nrf9151.dts :

/*
 * Copyright (c) 2023 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: Apache-2.0
 */

/dts-v1/;
#include <nordic/nrf9151_laca.dtsi>
#include "devacademyl3e2_nrf9151_common.dtsi"

/ {
	chosen {
		zephyr,sram = &sram0_s;
		zephyr,flash = &flash0;
		zephyr,code-partition = &slot0_partition;
		zephyr,sram-secure-partition = &sram0_s;
		zephyr,sram-non-secure-partition = &sram0_ns;
	};
};

Example devacademyl3e2_nrf9151_ns.dts :

/*
 * Copyright (c) 2023 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: Apache-2.0
 */

/dts-v1/;
#include <nordic/nrf9151ns_laca.dtsi>
#include "devacademyl3e2_nrf9151_common.dtsi"

/ {
	chosen {
		zephyr,flash = &flash0;
		zephyr,sram = &sram0_ns_app;
		zephyr,code-partition = &slot0_ns_partition;
	};
};

/* Disable UART1, because it is used by default in TF-M */
&uart1 {
	status = "disabled";
};