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.
Note: In this documentation, we expect CROSS_COMPILE and ARCH environment variables to be defined in the user development environment:
CROSS_COMPILE=arm-linux-gnueabi-
ARCH=arm
You can easily download AT91Bootstrap source code on the
at91bootstrap repository.
To get the source code, you should clone the repository by doing:
$ git clone https://github.com/linux4sam/at91bootstrap.git
Cloning into 'at91bootstrap'...
remote: Enumerating objects: 17621, done.
remote: Counting objects: 100% (3324/3324), done.
remote: Compressing objects: 100% (1029/1029), done.
remote: Total 17621 (delta 2465), reused 3102 (delta 2285), pack-reused 14297
Receiving objects: 100% (17621/17621), 5.65 MiB | 4.65 MiB/s, done.
Resolving deltas: 100% (13459/13459), done.
$ cd 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:
sama5d27_som1_ek-opteesd_uboot_defconfig
You can configure AT91Bootstrap by doing:
$ make mrproper
$ make sama5d27_som1_ek-opteesd_uboot_defconfig
If the configuring process is successful, the .config file can be found at AT91Bootstrap root directory.
Then you can build the AT91Bootstrap binary by doing:
$ make
If the building process is successful, the final .bin image is build/binaries/at91bootstrap.bin.
OP-TEE
To get the source code for OP-TEE OS the repository must be cloned.
$ git clone https://github.com/OP-TEE/optee_os.git
Cloning into 'optee_os'...
remote: Enumerating objects: 72568, done.
remote: Counting objects: 100% (14031/14031), done.
remote: Compressing objects: 100% (1909/1909), done.
remote: Total 72568 (delta 12442), reused 12192 (delta 12121), pack-reused 58537
Receiving objects: 100% (72568/72568), 26.90 MiB | 2.82 MiB/s, done.
Resolving deltas: 100% (53100/53100), done.
$ cd optee_os/
After cloning the default branch is
master which pointing to the latest version of optee_os. Checkout to the latest tag 4.0.0.
$ git checkout 4.0.0
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
$ sudo apt install python3-pyelftools
To build OP-TEE binary
$ make CROSS_COMPILE=arm-linux-gnueabi- PLATFORM=sam PLATFORM_FLAVOR=sama5d27_som1_ek -j12
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:
$ make CROSS_COMPILE=arm-linux-gnueabi- PLATFORM=sam PLATFORM_FLAVOR=sama5d27_som1_ek DEBUG=1 CFG_TEE_CORE_LOG_LEVEL=4 CFG_TEE_CORE_DEBUG=y -j12
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/*
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/
$ make sama5d27_som1_ek_mmc_optee_defconfig
$ make
Once built, a u-boot.bin file will be available in the build directory. This file should be copied on the SDCard.
Kernel
Follow the steps listed here to download the kernel source files.
To configure the Linux kernel the default configuration must be loaded found in arch/arm/configs/
$make ARCH=arm sama5_defconfig
HOSTCC scripts/basic/fixdep
HOSTCC scripts/kconfig/conf.o
HOSTCC scripts/kconfig/confdata.o
HOSTCC scripts/kconfig/expr.o
LEX scripts/kconfig/lexer.lex.c
YACC scripts/kconfig/parser.tab.[ch]
HOSTCC scripts/kconfig/lexer.lex.o
HOSTCC scripts/kconfig/menu.o
HOSTCC scripts/kconfig/parser.tab.o
HOSTCC scripts/kconfig/preprocess.o
HOSTCC scripts/kconfig/symbol.o
HOSTCC scripts/kconfig/util.o
HOSTLD scripts/kconfig/conf
#
# configuration written to .config
#
TO add the OP-TEE support configurations to the .config file need to be changed to match what is shown below:
CONFIG_OPTEE=y
CONFIG_ARM_PSCI=y
CONFIG_ARM_PSCI_FW=y
CONFIG_HAVE_ARM_SMCCC=y
CONFIG_HAVE_ARM_SMCCC_DISCOVERY=y
CONFIG_ARM_SMCCC_SOC_ID=y
CONFIG_REGMAP_SMCCC=y
CONFIG_ARM_SCMI_PROTOCOL=y
CONFIG_COMMON_CLK_SCMI=y
CONFIG_CPU_IDLE=y
CONFIG_ARM_PSCI_CPUIDLE=y
# CONFIG_ARM_PSCI_CPUIDLE_DOMAIN is not set
# CONFIG_ARM_AT91_CPUIDLE is not set
# CONFIG_ATMEL_PM is not set
CONFIG_ATMEL_SECURE_PM=y
Now to build the Linux kernel image, before you build you need to set up the cross compile toochain here(link).
$ARCH=arm make
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:
configs/sama5d27_som1_ek_optee_graphics_defconfig
configs/sama5d27_som1_ek_optee_headless_defconfig
Then to load the OP-TEE config you'll have to do:
$ BR2_EXTERNAL=../buildroot-external-microchip/ make sama5d27_som1_ek_optee_graphics_defconfig
Then you can build the image:
$ make
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:
BR2_EXTERNAL=../buildroot-external-microchip/ make menuconfig
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.
starting with Linux4SAM 2022.10 release, the meta-atmel layer supports OP-TEE for the following boards
sama5d27-som1-ek-optee-sd
The Build commands are as follows
1/ To build the microchip image with no graphics support:
[MACHINE=] bitbake microchip-headless-image
Example for sama5d27-som1-ek-optee-sd SD card image:
MACHINE=sama5d27-som1-ek-optee-sd bitbake microchip-headless-image
2/ To build the microchip image with graphics support (EGT):
[MACHINE=] bitbake microchip-graphics-image
Example for sama5d27-som1-ek-optee-sd SD card image:
MACHINE=sama5d27-som1-ek-optee-sd bitbake microchip-graphics-image
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.
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
Note: For clarity the UUID that was generated for this instance is cd9a3290-457b-4e49-99ff-32145fbde7cb and TA_MY_PROGRAM_CMD_INC_VALUE is a parameter passed into the main program from the host program.
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:
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:
The sub.mk file is the entry point for the source files to build example shown below:
global-incdirs-y +=include
srcs-y += my_program_ta.c
This adds the include folder globally and adds the trusted application main.c file to the list of source files.
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:
$ make CROSS_COMPILE=<buildroot-at91>/output/host/bin/arm-buildroot-gnueabihf- TEEC_EXPORT=<buildroot-at91>/output/build/optee-client-3.15.0/out/export/usr --no-builtin-variables
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:
$ make CROSS_COMPILE=<buildroot-at91>/output/host/bin/arm-buildroot-gnueabihf- PLATFORM=sam TA_DEV_KIT_DIR=<buildroot-at91>/output/build/<optee-os>/out/export-ta_arm32/
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
.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.
