OP-TEE

Introduction

OP-TEE documentation is the primary site for OP-TEE.

This document describes the sama5d2 platform support for OP-TEE that has been added in various components (at91bootstrap, OP-TEE, U-Boot, Linux Kernel and buildroot). The sama5d27_som1_ek board will be used as an example through this whole document.

AT91 Bootstrap

Get Sources

You can easily download AT91Bootstrap source code on the at91bootstrap repository.

To get the source code, you should clone the repository by doing:

Configure AT91Bootstrap

Inside the AT91Bootstrap root directory you will find a configs folder which contains several default configuration files only one file contains the correct configuration for OP-TEE:

You can configure AT91Bootstrap by doing:

If the configuring process is successful, the .config file can be found at AT91Bootstrap root directory.

Build AT91Bootstrap

Then you can build the AT91Bootstrap binary by doing:

If the building process is successful, the final .bin image is build/binaries/at91bootstrap.bin.

OP-TEE

Get Sources

To get the source code for OP-TEE OS the repository must be cloned.

After cloning the default branch is master which pointing to the latest version of optee_os. Checkout to the latest tag 4.0.0.

Build

OP-TEE does not have any Kconfig system but can be configured through command line. However, by default, there is no need to add more options. Default platform flavor is sama5d27_som1_ek. Note: Currently there is only the sama5d27_som1_ek is supported.

prerequisites

To build OP-TEE binary

A tee.bin file will be created in out/arm-plat-sam/core and should be copied on a SDCard to allow at91bootstrap booting it.

Note: By default OP-TEE will not display anything, only some messages in case of errors. To enable a more verbose debug, compile it with the following options:

Debugging

As mentioned above debug messages are not enabled by default and have to be enabled by build variables.

Different print log levels are able to be configured for both TEE core and TEE trusted application. The default value is 1

• 0: none
• 1: error only
• 2: error and info
• 3: error, info, and debug
• 4: error,info,debug, and flow

Along with showing the core log for debugging OP-TEE provides a helper script called symbolize.py located in the optee-os/scripts folder. This script will extend the abort or panic message from OP-TEE, example of this call is here

scripts/symbolize.py -d out/arm-plat-hikey/core -d ../optee_test/out/ta/* <paste whole dump here>

Secure Storage

Secure storage is implemented in two different ways as described in the documentation as well as API and the data-path flow. The commands that are mentioned for example, CFG_REE_FS, this would be passed into the additional build variables.

Both secure storage implementations can be enabled at the same time by passing these commands into the build variables, CFG_RPMB_FS=y CFG_RPMB_WRITE_KEY=y CFG_RPMB_TESTKEY=y CFG_REE_FS=y

The xtest program will verify the secure storage when it runs its regression test. To call a specific secure storage memory test run xtest _6, and xtest -t benchmark -l 15.

U-Boot

Follow the steps to get U-Boot

To build U-boot with OP-TEE configs there is only one config in configs/

Once built, a u-boot.bin file will be available in the build directory. This file should be copied on the SDCard.

Kernel

Get Sources

Follow the steps listed here to download the kernel source files.

Build

To configure the Linux kernel the default configuration must be loaded found in arch/arm/configs/

TO add the OP-TEE support configurations to the .config file need to be changed to match what is shown below:

Now to build the Linux kernel image, before you build you need to set up the cross compile toochain here(link).

Now you have a usable compressed kernel image zImage.

Buildroot

For OP-TEE the steps for BuildRoot should be followed remembering to select one of the two OP-TEE configs listed below:

Then to load the OP-TEE config you'll have to do:

Then you can build the image:

Advanced Features

Before building the Buildroot image you may want to customize the OP-TEE arguments such as adding debug messages.

Configurations in Kconfig

OP-TEE has multiple extra configurations, as mentioned above, that are not included in the default build configuration.

These can be added by running:

and go into Bootloaders menu to find the highlighted portion:

Simply add any additional build variables that you might need as if you are building OP-TEE stand alone.

Yocto Project

For building the OP-TEE supported boards using the Yocto Project one can follow the steps mentioned in How to build Poky for AT91.

The Build commands are as follows

Trusted Applications

In OP-TEE there are two types of applications the traditional user-space applications and trusted applications. Trusted applications are applications that access the secure portion of the OS.

To see more Trusted Application examples they can be found here OP-TEE Examples.

Building Trusted Application

In OP-TEE to build a trusted application there are a mandatory files that need to follow a certain layout shown below:

The parent directory for the tree is called my_program, this format makes it easy to organize multiple trusted applications.

Host

The host folder contains the main user-space program.

This program will need to:

• Initialize a context connecting to TEE
• Open a TEE session
• Use a TEEC_Operation variable to pass in arguments from the non-secure world to the secure world
• Prepare the arguments that are about to be passed using TEEC_PARAM_TYPES() function
• Call the trusted application using TEEC_InvokeCommand()
• At the end Close the session and context

The Makefile is similar to other Makefiles just adding the flags to include the trusted application and the host application this belongs in the host folder, shown below:

Trusted Application (TA)

The trusted application folder is more complicated and has many moving parts.

Include Folder

This contains the programs header file that has the TA commands API and the TA_UUID. The UUID can be generated here. Shown below is an example header file called ta_my_program.h

Main Program

The main program that interacts with the TA entry points his located in this folder as a .c file. The OP-TEE documentation mentioned above that there are TA mandatory entry points. These entry points are implemented in this main function, in this example my_program_ta.c. An example of implementing a counter within the TA is shown below, notice that InvokeCommandEntryPoint can be used to call different functions depending on the parameters passed into it similar to an ISR.

Trusted Application Properties Header File

This is a header file that stores the uuid, flags, stack size, and data size. This file is normally called user_ta_header_defines.h and is located in the ta folder. An Example:

<img src="%ATTACHURL%/ExampleTAPropertiesFile.jpg" width="800" height="361.31" border="0" align="center"/>

Makefiles

There are two Makefiles that need to be in the TA folder a Makefile and a sub.mk file. The Makefile needs to have the UUID labeled BINARY and the include path for the TA devkit, this is taken from the OP-TEE build and passed in as compile arguments.

Example:

<img src="%ATTACHURL%/ExampleTaMakeFile.jpg" width="800" height="294.09" border="0" align="center"/>

The sub.mk file is the entry point for the source files to build example shown below:

This adds the include folder globally and adds the trusted application main.c file to the list of source files.

Compiling Trusted Applications

Inside the host folder the cross compiler needs to be set and the tee client export needs to be set as well.

If using the Buildroot OP-TEE build:

This will output the program as a binary in the host folder, where the build was done.

To compile the trusted application first navigate to the ta folder. The cross compiler needs to be set just like the above step as well as the location of the ta_dev_kit, which is made when the optee_os is built.

An example using buildroot:

Copy the Trusted Application

Once the TA and the host application are compiled they can be copied into the root file system.

If using buildroot follow these steps after build has finished:

• Copy the trusted application from the ta folder, the application would be titled <uuid>.ta into <buildroot-at91>/output/target/lib/optee_armtz/ folder If this folder is not there double check the environment was configured correctly for OP-TEE and finished building.
• Copy the host application from the host folder into the root file system, <buildroot-at91>/output/target/usr/bin/ This location is different due to how OP-TEE separates the secure world and the non secure world.
• Go into the buildroot-at91 main build directory and run make, this will build the file system with the new application added.

The image is ready for use.