STM32MP2 firewall configuration

Applicable for

This article describes how the STM32MP2 series firewall should be configured to allow STM32 MPU embedded software distribution execution.

1. Overview[edit | edit source]

The objective of this article is to provide guidelines for the hardware system firewall configuration considering the different platform constraints. On STM32MP2 series, the RIF : Resource Isolation Framework, protects internal RAM, external memories, and internal peripherals. A minimal coherent RIF configuration is required to execute STM32 MPU Embedded Software distribution and support the different low power modes.

2. RIF initial hardware configuration[edit | edit source]

The RIF is made up of several protection units like described in Resource Isolation Framework overview.
The initial hardware configuration depends on the type of peripheral/memory to protect and their usage by the ROM code.

2.1. RIFSC and RISAx[edit | edit source]

Default state for RIFSC and RISAx protection units:

RIFSC RISUP protected peripherals:
- Nonsecure
- Unprivileged
- CID filtering disabled
RIFSC RIMU for bus master peripherals:
- Nonsecure
- Unprivileged
- CID in RISUP CID inheritance mode. This implies a CID0 for all bus master peripherals as RISUP initial configuration is CID filtering disabled

Information

A configurable RIMU is nonsecure and unprivileged by default. Whether RISUP CID inheritance is used or not, the secure/privilege attributes of the master port can be configured. Note that for RIMU with secure-guard, if associated RISUP secure attribute is set to nonsecure, then RIMU secure attribute is forced to nonsecure by hardware. Please be aware that some RIMUs do not support RISUP inheritance or have a specific CID by default. For more information, refer to the STM32 MPU reference manuals.

RIFSC RISAL for LPSRAMs:
- Nonsecure
- Unprivileged
- Accessible by Cortex-M33®(CID2) and Cortex-M0+®(CID3)

Information

There is no RISAL on STM32MP21x lines

RISAF protected external memories:
- Base region0 only accessible by main processor (TDCID) in secure mode (CID1 Secure when Cortex-A35 is the main processor, CID2 secure when Cortex-M33 is the main processor).
RISAB protected internal memories:
- No CID filtering.
- Security level depends on protected memory. Please refer to RISAB internal peripheral article.

2.2. RIF-Aware peripherals[edit | edit source]

Default state for RIF-Aware peripherals:

RIF component	Secure level	Privilege level	CID filtering
GPIO	Secure	Unprivileged	CID filtering disabled
EXTI	Nonsecure	Unprivileged	CID filtering disabled
FMC	Nonsecure	Unprivileged	CID filtering disabled
HPDMA	Nonsecure	Unprivileged	CID filtering disabled
IPCC	Nonsecure	Unprivileged	CID filtering disabled
PWR	Nonsecure	Unprivileged	CID filtering disabled
RCC	Nonsecure	Unprivileged	CID filtering disabled
RTC	Nonsecure	Unprivileged	CID filtering disabled
TAMP	Nonsecure	Unprivileged	CID filtering disabled
HSEM	Nonsecure	Unprivileged	CID filtering disabled

2.3. Minimal RIF configuration rules[edit | edit source]

According to the above statements, a minimal RIF configuration should be performed by the secure OS running on main processor (TDCID). This ensures correct and coherent execution of the embedded software, considering that there is no compartment isolation:

Secure level of GPIO should be configured to allow access to the hardware execution context configuring and using them. For IO ports used by peripherals, nonsecure peripherals can use secure pins as well but secure peripherals cannot use nonsecure pins.
RISAB memory blocks should be configured to allow access to the hardware execution contexts using them.
RISAF memory regions should be configured to allow access to the hardware execution contexts using them.
Secure level of some peripherals such as RNG should be set.

3. ROM code constraints[edit | edit source]

The STM32MP2 series ROM code which is running on Cortex-A35, shall be certified SESIP level3. This implies a certain number of security and isolation rules to guarantee ROM code execution:

All secure and nonsecure hardware resources required by ROM secure and/or nonsecure code shall be accessible respectively to the Cortex-A35 secure and/or nonsecure each time the ROM code is executed (cold boot, application reset, low power exit).
- RIFSC RISUP configuration associated with ROM code resources shall allow Cortex-A35 access.
- RISAB1&2 dedicated to SYSRAM protection shall allow Cortex-A35 access.
- PWR & RCC resources associated with ROM code resources shall allow Cortex-A35 access
It shall not be possible to change RIF configuration of secure resources used by ROM code during its execution.
- When Cortex-M33 is the main processor (TDCID), RIFSC RISUP configuration associated with ROM code secure resources must be locked.
No active bus master peripheral shall have same RIF configuration as Cortex-A35 secure context executing secure ROM code.
- If a RIFSC RIMU of a bus master peripheral is defined as Secure and CID1, its associated clock must be disabled during ROM code execution.

ROM code is checking the firewall settings of some resources. If one setting does not match ROM code requirements, ROM code stops its execution and goes in failure. For more information, please refer to STM32MP2 ROM code resource isolation.

4. STM32MPU Embedded Software ecosystem configuration[edit | edit source]

4.1. RIF attributes of OSTL software components[edit | edit source]

Firewall Attribute	TF-A	OP-TEE Core	OP-TEE Trusted Applications	U-Boot	Linux kernel space	Linux user space	TF-M Core	TF-M Applications RoT	Cube Firmware
Secure level	Secure	Secure	Secure	Nonsecure	Nonsecure	Nonsecure	Secure	Secure	Nonsecure
Privilege level	Privileged	Privileged	Non-Privileged	Privileged	Privileged	Non-Privileged	Privileged	Non-Privileged	Privileged
CID attribute	CID1	CID1	CID1	CID1	CID1	CID1	CID2	CID2	CID2

4.2. Ecosystem configuration[edit | edit source]

The ecosystem "*-ostl" configuration present in the External device tree is an example of a complete and secure ecosystem firewall configuration, it enables:

Cortex-A35 and Cortex-M33 secure OSes
Isolation between Cortex-A35 and Cortex-M33
LTDC secure layer
Authenticated Cortex-M33 co-processor

To do that, RIF is configured to assign peripherals and features to the different execution contexts with the following rules:

The peripherals and resources used by Cortex-A35 secure OS are configured as secure, privileged, with CID filtering enabled on CID1.
The peripherals and resources used by Cortex-M33 secure OS are configured as secure, privileged with CID filtering enabled on CID2.
The peripherals and resources shared by Cortex-A35 and by Cortex-M33 secure OS are configured as secure, privileged, and semaphore mode enabled for CID1/2 when possible, else TDCID only.

Information

Note that sharing a peripheral should be avoided in most cases. Please refer to RIF ROM code constraints.

The peripherals and resources used by Cortex-A35 nonsecure OS are configured as nonsecure, privileged, with CID filtering enabled on CID1.
The peripherals and resources used by Cortex-M33 nonsecure OS are configured as nonsecure, privileged, with CID filtering enabled on CID2.
The GPIO associated to one peripheral are usually configured with the same configuration as associated peripheral.
RCC and PWR system resources (resources common to several execution contexts) are configured to be controlled by the main processor (TDCID) secure OS.
All peripherals used by ROM code are configured with access rights compliant with ROM code execution.

Information

Unused peripherals or resources within a RIF-Aware peripheral are configured in no-access mode that is semaphore mode enabled with no CID authorized. This prevents any access to them.

Regarding bus master peripherals, it is important to define the identity of their accesses by configuring their RIFSC RIMU. There are two possible methods:

RIFSC RISUP CID inheritance: In that case, the master port accesses on the bus will have the same RIF CID attributes as the associated RISUP of the peripheral (default value).
Define a specific CID for this RIMU through the RIFSC RIMC master attribute register. Notice that RISAF and RISAB configurations should be adapted to allow these peripherals' master port to access memory regions shared with the software component controlling it.

Regarding memories, RISAB and RISAF shall be configured according to product memory mapping:

Memory regions exclusively used by a software component shall be configured to allow only access of the execution context (security level, privilege level, and CID) running the software component.
DDR memory regions used by secure OS can be defined as encrypted.
Memory regions shared between software components (for inter-OS or processor communication) shall be configured to both execution contexts.

Examples:

In case of Cortex-A35 main processor boot from eMMC, SDMMC2 shall be accessible by:

Cortex-A35 ROM code nonsecure
Cortex-A35 FSBL TF-A BL2
Cortex-A35 SSBL U-Boot
Cortex-A35 Linux kernel

This implies to configure SDMMC2 RISUP in nonsecure, privilege, and CID1 (CID filtering enabled).

Moreover, SDMMC2 shall be able to access any buffer allocated by the different software components. It shall behave as an extension of Cortex-A35 nonsecure.

This implies to configure associated RIMU in nonsecure, unprivileged with CID inheritance.

Associated device tree configuration is the following one:

&rifsc {
	st,protreg = < 
		RIFPROT(STM32MP25_RIFSC_SDMMC2_ID, RIF_UNUSED, RIF_UNLOCK, RIF_NSEC, RIF_PRIV, RIF_CID1, RIF_SEM_DIS, RIF_CFEN)
	>;
	st,rimu = <
		RIMUPROT(RIMU_ID(2), RIF_UNUSED, RIF_NSEC, RIF_PRIV, RIF_CIDSEL_P)
	>;
};

In case of Cortex-A35 main processor secure boot, some security peripherals like SAES or PKA shall be accessible by:

Cortex-A35 ROM code secure
Cortex-A35 FSBL TF-A BL2
Cortex-A35 Secure OS OP-TEE

This implies to configure SAES and PKA RISUP in secure, privilege, and CID1 (CID filtering enabled).

Associated device tree configuration is the following one:

&rifsc {
	st,protreg = < 
		RIFPROT(STM32MP25_RIFSC_PKA_ID, RIF_UNUSED, RIF_UNLOCK, RIF_SEC, RIF_PRIV, RIF_CID1, RIF_SEM_DIS, RIF_CFEN)
		RIFPROT(STM32MP25_RIFSC_SAES_ID, RIF_UNUSED, RIF_UNLOCK, RIF_SEC, RIF_PRIV, RIF_CID1, RIF_SEM_DIS, RIF_CFEN)
	>;
};

In case of Cortex-A35 main processor secure boot and secondary secure OS running in Cortex-M33 secure context, some peripherals like SAES or PKA could be accessible by:

Cortex-A35 ROM code secure
Cortex-A35 FSBL TF-A BL2
Cortex-A35 Secure OS OP-TEE
Cortex-M33 Secure OS TF-M

This implies to configure SAES and PKA RISUP in secure, privilege, and shared between CID1 and CID2 thanks to RIF semaphore.

Associated device tree configuration is the following one:

&rifsc {
	st,protreg = < 
		RIFPROT(STM32MP25_RIFSC_PKA_ID, RIF_CID1_BF|RIF_CID2_BF, RIF_LOCK, RIF_SEC, RIF_PRIV, RIF_UNUSED, RIF_SEM_EN, RIF_CFEN)
		RIFPROT(STM32MP25_RIFSC_SAES_ID, RIF_CID1_BF|RIF_CID2_BF, RIF_LOCK, RIF_SEC, RIF_PRIV, RIF_UNUSED, RIF_SEM_EN, RIF_CFEN)
	>;
};

OSTL RIF ecosystem configuration for ST reference board is available in external device tree repository.

5. STM32MPU Embedded Software upstream configuration[edit | edit source]

The upstream configuration is the one present in the trusted OS repository (Either https://github.com/STMicroelectronics/optee_os.git or https://github.com/STMicroelectronics/trusted-firmware-m.git. This configuration is very permissive and should be used for development purposes. For that, this minimal configuration is following these rules:

Secure resources (peripherals and memory regions) used by either Cortex-A35 or Cortex-M33 secure OS are defined as secure. CID filtering may be enabled.
Access to peripherals (and associated IOs) unused by secure OSes are defined as nonsecure, unprivileged, and CID filtering disabled.
Bus master peripherals accesses remain at their default value (nonsecure, unprivileged, and CID inheritance).
Memory regions unused by secure OSes are configured to allow accesses from any bus master peripherals (nonsecure, unprivileged, RW for all CID).

6. How to configure RIF[edit | edit source]

6.1. RIF configuration ownership[edit | edit source]

RIF main configuration is under the TDCID responsibility. CID filtering configuration registers cannot be accessed by other masters. That means RIF configuration should be done by the secure OS running on main processor.

Nevertheless, almost all RIF registers are in read for all, that means any execution context can read them to check if it can access a resource or not.

It is also possible to delegate some subconfigurations to some execution contexts. For examples:

Secure master having access to a resource can change its security level
Privileged master having access to a resource can change its privilege level
Memory regions can be delegated to an owner (defined by CID, secure, and privilege levels) that can define new secure/privilege access rights and subregions. It is useful for memory sharing management.

6.2. How to generate RIF configuration[edit | edit source]

The RIF configuration could be done via STM32CubeMX graphical tool:

Peripheral assignment between the different execution contexts makes it possible to generate RIFSC RISUP configuration
RIF-aware configuration panels allow to assign each feature to the different execution contexts to generate associated configuration
RIF panel provides a way to configure the different master interfaces and generate RIFSC RIMU configuration, to create the different memory regions and to generate associated RISAF, RISAB and RISAL

The advantage of using STM32CubeMX is that consistencies between the different RIF components and between the different software components running on the platform including ROM code are managed. RIF peripheral protection is extended to associated IOs, clock, and reset. To guarantee the coherency between all the software components, CubeMX generates device tree files for all software components, which include RIF and memory and clock tree configuration.

6.3. RIF drivers bindings[edit | edit source]

For more information about RIF configuration in device tree files please refer to device tree configuration pages: