Getting started with TEE

Yes

Getting Started with the MCUXpresso Config Tools

MCUXpresso Config Tools is available both as a standalone application, which can be used in connection with various IDEs (Integrated Development Environments), MCUXpresso IDE. This document focuses on the integrated version. However, the basic principles are also applicable to the standalone version.

A tutorial containing three videos is available on nxp.com. The first video shows how to install MCUXpresso IDE with MCUXpresso SDK. The remaining videos demonstrate, among other things, the usage of the MCUXpresso Config Tools.

Introducing TEE tool with a simple example

The TEE (Trusted Execution Environment) tool is part of the MCUXpresso Config Tools. It can be used to configure ARM TrustZone®, the AHB Security Controller, Memory Protection Unit, and other .

This document describes the TEE tool user interface and the standard configuration process with a simple example – adding a new secure memory region and a secure peripheral to an existing project for a LPCXpresso55S69 board. To demonstrate access restrictions, the configuration of DMA0 as secure and DMA1 as non-secure is also described. For general overview of the MCUXpresso Config Tools, refer to the guide.

Preparations

Start by importing an existing SDK example. You must first download and install the LPCXpresso55S69 MCUXpresso SDK into the MCUXpresso IDE. For more information about downloading and installing SDK, see MCUXpresso Config Tools Getting Started.

Once the MCUXpresso IDE contains the LPCXpresso55S69 SDK you can proceed and import an example project.

In the Quickstart Panel, select Import SDK example(s)…
In the SDK Import Wizard, select the LPCXpresso55S69 board.
Select the checkboxes to import the hello_world_s and the hello_world_ns projects, located under the trustzone_examples node.
After the projects are imported, open the TEE tool by right-clicking the hello_world_s example in the Project Explorer view and selecting MCUXpresso Config Tools > Open TEE.

TEE Tool Overview

The TEE tool is graphically divided into three logical groups, from the left to the right: Configuration Area, Access Details, and Output. This tutorial will make use of all three.

Configuration Area

The configuration area consists of two complementary views:

User Memory Regions contains simplified security configuration possibilities for memories.
Security Access Configuration contains low-level detailed configuration of memories, peripherals, bus masters, etc.

The suggested configuration flow is to first define regions in the User Memory Regions view and then fine-tune the configuration using the Security Access Configuration view. The hello_world_s example already contains pre-defined regions but if you to start from an empty project, or modify the existing regions, you can import a regions stub based on the hello_world_s and hello_world_ns projects linker memory configuration.

To demonstrate this functionality, change the linker memory configuration and then import it into the TEE tool.

Open the Project Explorer view inside of the Develop perspective.
Open the Edit Memory dialog, and add a new RAM region at the address 0x30040000, with a size of 0x400.

Note: Make sure not to create an overlap between the hello_world_s and the hello_world_ns memory configuration. Keep in mind that the 28th bit in addresses is used just to separate secure areas from non-secure areas. Therefore, addresses differing in the 28th bit only, for example, 0x20000000 and 0x30000000, point to the same physical location in the RAM memory.

Once done, navigate back to the TEE tool, and click Import in the User Memory Regions view
In the Select Project dialog, select the hello_world_s and hello_world_ns project and click OK.

Note: The Import button is not available in the standalone MCUXpresso Config Tools version.

Now you can modify the imported regions stub:

Change security level of the secure regions from S-User (Secure-User) to S-Priv (Secure-Privileged) and from NSC-User (Non-Secure-Callable-User) to NSC-Priv (Non-Secure-Callable-Privileged). An error appears after changing security level of the newly added Ram_2S region to S-Priv (Secure-Privileged). That

Right-click the error icon and select the quick-fix option from the context menu to fix the problem by changing the security level of associated region in the Memory Protection Checker.

Note: After a linker-memory configuration is imported, S-User (Secure-User), or NS-User (Non-Secure-User) is used by default depending on whether the memory region belongs to a secure or to a non-secure project. It may be needed to change it to S-Priv (Secure-Privileged), or NS-Priv (Non-Secure-Privileged), if you want to use the privileged state.

Note: The MCUXpresso Config Tools can point out configuration inconsistencies and problems and suggests quick-fixes. These fixes are not applied automatically. The reason is that there can be multiple interconnected settings influencing each other in the configuration, and changing the value of one of them could cause an unwanted chain reaction.

Now switch to the Security Access Configuration view.

This view consists of multiple sub-views, each of them allowing the configuration of separate block(s):

SAU allows to enable and configure the Security Attribution Unit for the primary core
Secure and Non-Secure MPU allow to enable and configure the Memory Protection Unit for the primary core
MPC allows to configure the Memory Protection Checker
Interrupts allows to specify which interrupt handlers should run in the secure mode and to allow/deny handling interrupts
Pins tab allows to specify which pins’ state cannot be read by the GPIO
Masters/Slaves allows to specify security level of non-primary core bus masters, and to configure the Peripheral Protection Checker
Miscellaneous contains various useful AHB Controller settings, such as enable/disable of AHB security checking, enable/disable of AHB privileges checking, and so on

Set the security level of the DMA0 bus master to S-Priv to enable it to access secure peripherals/memories.
Change security of the ADC0 peripheral to secure, so only a secure master will be able to access it.
Open the Masters/Slaves sub-view and change security levels of DMA0 and ADC0 to S-Priv.

Access Details

The access details area consists of three views.

Domains Overview (not applicable for LPC55S69) can be used to provide domain-related access details for domain-aware MCUs (Micro Controller Units).
Memory Attribution Map provides memory and peripherals security attribute configuration details as well as detailed information about a bus master access to peripherals and memories.
Access Overview, in contrast, provides a simplified general overview of resulting bus master to memory/peripheral access rules.

Memory Attribution Map

The Memory Attribution Map view displays security configuration of peripherals/memories, as well as the resulting memory/peripheral security attribute, in its default state. It is possible to switch the memory map into the detailed bus master to memory/peripherals access detail view. This can be done using the Filter access for checkbox. Once checked, the memory map starts displaying access details for the selected bus master and its security level.

Note: The memory map displays S and NS in the Resulting Security Level column. This is caused by the privilege checking being disabled by default, therefore S-User and S-Priv are both considered the same. This option can be in the Miscellaneous sub-view of the Security Access Configuration view.

We will now check the access details of DMA0 to the Ram2_S region as well as to the ADC0 peripheral which we configured to S-Priv previously.

Open the Memory Attribution Map view and switch to the Other Masters sub-view.
Select the Filter access for checkbox and select DMA0 and see the resulting access to Ram2_S and ADC0.
Now select DMA1 instead of DMA0 and see the resulting access to Ram2_S and ADC0 again.
You can see that both Ram2_S and ADC0 are accessible by the DMA0 but are inaccessible by DMA1 using any of its aliases.

Note: Notice that the Memory Attribution Map contains different columns in the Core 0 and Other Masters sub-views. This is because different mechanisms protect the access to different bus masters. Core 0 uses SAU (and MPU), but other bus masters use Master Security Wrapper (MSW).

Access Overview

You can also check the Access Overview view for simplified overall yes/no access information. Rows represent memory/peripherals, columns represent bus masters, cells represent access details of a corresponding bus master and memory/peripheral combination.

Note: Core 0 master contains four columns in the Access Overview. Each of the columns represent access from different security level of the Core 0.

Output

The output area consists of four views:

Overview contains summary of the TEE status – generated files, number of problems, etc.
Code Preview displays the source code reflecting the current configuration.
Registers shows registers state reflecting the current configuration.
Problems lists the current errors, warnings, and information. Many of them can be resolved directly inside of the Problems view using a quick-fix functionality available via context menu.

Note: Code Preview displays just a preview of the source files, but the source code is not updated in the MCUXpresso IDE project yet. To update it, use the Update Code button.

Conclusion

This tutorial described the basic principles of configuration flow in the TEE tool and brief overview of the TEE tool views. For a hands-on example see the Creating Secure and Non-Secure projects post. If you would like to get more information regarding the ARM TrustZone® or LPC55S69, refer to the https://mcuoneclipse.com/2019/04/27/trustzone-with-armv8-m-and-the-nxp-lpc55s69-evk/ or https://mcuoneclipse.com/2019/10/21/investigating-arm-cortex-m33-core-with-trustzone-trusted-executi...