How to assign an internal peripheral to a runtime context

1 Article purpose[edit]

This article explains how to configure the software that assigns a peripheral to a runtime context.

2 Introduction[edit]

A peripheral can be assigned to a runtime context via the configuration defined in the device tree. The device tree can be either generated by the STM32CubeMX tool or edited manually.

On STM32MP15 line devices, the assignement can be strengthened by a hardware mechanism: the ETZPC internal peripheral, which is configured by the TF-A boot loader. The ETZPC internal peripheral isolates the peripherals for the  Cortex-A7 secure  or the  Cortex-M4  context. The peripherals assigned to the  Cortex-A7 non-secure  context are visible from any context, without any isolation.

The components running on the platform after TF-A execution (such as U-Boot, Linux, STM32Cube and OP-TEE) must have a configuration that is consistent with the assignment and the isolation configurations.

The following sections describe how to configure TF-A, U-Boot, Linux and STM32Cube accordingly.

Info white.png Information
Beyond the peripherals assignment, explained in this article, it is also important to understand How to configure system resources (i.e clocks, regulator, gpio,...), shared between the Cortex-A7 and Cortex-M4 contexts

3 STM32CubeMX generated assignment[edit]

The screenshot below shows the STM32CubeMX user interface:

  • I2C2 peripheral is selected, on the left
  • I2C2 Mode and Configuration panel, on the right, shows that this I2C instance can be assigned to the  Cortex-A7 non-secure  or the  Cortex-M4  (that is selected) runtime context
  • I2C mode is enabled in the drop down menu


CubeMX-assign-peripheral.png
Info white.png Information
The context assignment table is displayed inside each peripheral Mode and Configuration panel but it is possible to display it for all the peripherals in the Options menu via the Show contexts option

The GENERATE CODE button, on the top right, produces the following:

  • The TF-A device tree with the ETZPC configuration that isolates the I2C2 instance (in the example) for the  Cortex-M4  context. This same device tree can be used by OP-TEE, when enabled
  • The U-Boot device tree widely inherited from the Linux one, just below
  • The Linux kernel device tree with the I2C node disabled for Linux and enabled for the coprocessor
  • The STM32Cube project with I2C2 HAL initialization code

The Manual assignment section, just below, illustrates what STM32CubeMX is generating as it follows the same example.

Info white.png Information
In addition of this generation, the user may have to manually complete the system resources configuration in the user sections embedded in the STM32CubeMX generated device tree. Refer to How to configure system resources for details.

4 Manual assignment[edit]

This section gives step by step instructions, per software components, to manually perform the peripherals assignments.
It takes the same I2C2 example as the previous section, that showed how to use STM32CubeMX, in order to make the move from one approach to the other easier.

Info white.png Information
The assignments combinations described in the STM32MP15 peripherals overview article are naturally supported by STM32MPU Embedded Software distribution. Note that the STM32MP15 reference manual may describe more options that would require embedded software adaptations

4.1 TF-A[edit]

The assignment follows the ETZPC device tree configuration, with below possible values:

  • DECPROT_S_RW for the  Cortex-A7 secure  (Secure OS like OP-TEE)
  • DECPROT_NS_RW for the  Cortex-A7 non-secure  (Linux)
    • As stated earlier in this article, there is no hardware isolation for the Cortex-A7 non-secure so this value allows accesses from any context
  • DECPROT_MCU_ISOLATION for the  Cortex-M4  (STM32Cube)


Example:

@etzpc: etzpc@5C007000 {
       st,decprot = <
           DECPROT(STM32MP1_ETZPC_I2C2_ID, DECPROT_MCU_ISOLATION, DECPROT_UNLOCK)
       >;
};
Info white.png Information
The value DECPROT_NS_RW can be used with DECPROT_LOCK as last parameter. In Cortex-M4 context, this specific configuration allows the generation of an error in the resource manager utility while trying to use on Cortex-M4 side a peripheral that is assigned to the Cortex-A7 non-secure context. If DECPROT_UNLOCK is used, then the utility allows the Cortex-M4 to use a peripheral that is assigned to the Cortex-A7 non-secure context.

4.2 U-boot[edit]

No specific configuration is needed in U-Boot to configure the access to the peripheral.

Info white.png Information
U-Boot does not perform any check with regards to ETZPC configuration before accessing to a peripheral. In case of inconsistency an illegal access is generated.
Info white.png Information
U-Boot checks the consistency between ETZPC isolation configuration and Linux kernel device tree configuration to guarantee that Linux kernel do not access an unauthorized device. In order to avoid the access to an unauthorized device, the U-boot fixes up the Linux kernel device tree to disable the peripheral nodes which are not assigned to the Cortex-A7 non-secure context.

4.3 Linux kernel[edit]

Each assignable peripheral is declared twice in the Linux kernel device tree:


In the board device tree file (*.dts), each assignable peripheral has to be enabled only for the context to which it is assigned, in line with TF-A configuration.
As a consequence, a peripheral assigned to the Cortex-A7 secure has both nodes disabled in the Linux device tree.

Example:

&i2c2 {
	status = "disabled";
};
...
&m4_i2c2 {
	status = "okay";
};
Info white.png Information
In addition of this assignment, the user may have to complete the system resources configuration in the device tree nodes. Refer to How to configure system resources for details.

4.4 STM32Cube[edit]

There is no configuration to do on STM32Cube side regarding the assignment and isolation. Nevertheless, the resource manager utility, relying on ETZPC configuration, can be used to check that the corresponding peripheral is well assigned to the Cortex-M4 before using it.

Example:

int main(void)
{
...
 /* Initialize I2C2------------------------------------------------------ */
 /* Ask the resource manager for the I2C2 resource */
 ResMgr_Init(NULL, NULL);
 if (ResMgr_Request(RESMGR_ID_I2C2, RESMGR_FLAGS_ACCESS_NORMAL | \
                                    RESMGR_FLAGS_CPU1, 0, NULL) != RESMGR_OK)
 {
   Error_Handler();
 }
...
 if (HAL_I2C_Init(&I2C2) != HAL_OK)
 {
   Error_Handler();
 }
}

4.5 OP-TEE[edit]

The OP-TEE OS may use STM32MP1 resources. OP-TEE STM32MP1 drivers register the device driver they intend to used in a secure context. This information is used to consolidate system configuration including secure hardening of configurable peripherals.

In most case, the OP-TEE driver probe relies on OP-TEE device tree porperty secure-status = "okay".