build

Why this particular git? As it turns out it’s totally possible to put together everything on your own. You can build all the individual components, os, client, xtest, Linux kernel, TF-A, TianoCore, QEMU, Buildroot etc and put all the binaries at correct locations and write your own command lines, Makefiles, shell-scripts etc that will work nicely on the devices you are interested in. If you know how to do that, fine, please go a head. But for newcomers it’s way to much behind the scenes to be able to setup a working environment. Also, if you for some reason want to run something in an automated way, then you need something else wrapping it up for you.

With this particular git built.git our goal is to simply to make it easy for newcomers to get started with OP-TEE using the devices we’ve listed in this document.

git location

https://github.com/OP-TEE/build

Why repo?

We discussed alternatives, initially we started out with having a simple shell-script, that worked to start with, but after getting more gits in use and support for more devices it started to be difficult to maintain. In the end we ended up choosing between repo from the Google AOSP project and git submodules. No matter which you choose, there will always be some person arguing that one is better than the other. For us we decided to use repo. Not directly for the features itself from repo, but for the ability to simply work with different manifests containing both stable and non-stable release. Using some tips and tricks you can also speed up setup time significantly. For day to day work with commits, branches etc we tend to use git commands directly.

Root filesystem

The rootfs in the builds that we cover here are as small as possible and is based on a stripped down Buildroot configuration adding just enough in the rootfs such that one can:

  • Boot OP-TEE.

  • Run xtest with no regressions.

  • Easily add additional developer tools like, strace, valgrind etc.

Note

As a consequence of enabling “just enough”, it is likely that non-UART based enviroments won’t work out of the box. I.e., if you try to boot up an enviroment using HDMI and connect keyboards and other devices it is likely that things will not work. To make them work, you probably need to rebuild Linux kernel with correct drivers/frameworks enabled and in addition to that enable binaries/daemons in Buildroot that might be necessary (user space tools and drivers).

How do I build using AOSP / OpenEmbedded?

For guides how to build AOSP, please refer to our AOSP page. For OpenEmbedded we have no guide ready.

Platforms supported by build.git

Below is a table showing the platforms supported by build.git. OP-TEE as such supports many more platforms. To find out how to run OP-TEE on those, please reach out to the maintainer of that platform directly if you have build related questions etc. Please see the MAINTAINERS file for contact information.

Platform

Composite flag

Publicly available?

AMD/Xilinx Versal ACAP VCK190

PLATFORM=versal

Yes

ARM Juno Board

PLATFORM=vexpress-juno

Yes

ARM Foundation FVP

PLATFORM=vexpress-fvp

Yes

DeveloperBox

PLATFORM=synquacer

Yes

HiKey Kirin 620

PLATFORM=hikey

Yes

HiKey 960

PLATFORM=hikey-hikey960

Yes

MediaTek MT8173 EVB Board (deprecated)

PLATFORM=mediatek-mt8173

No

Poplar

PLATFORM=poplar

Yes

QEMU

PLATFORM=vexpress-qemu_virt

Yes

QEMUv8

PLATFORM=vexpress-qemu_armv8a

Yes

Raspberry Pi 3

PLATFORM=rpi3

Yes

STM32MP157A-DK1

PLATFORM=stm32mp1-157A_DK1

Yes

STM32MP157C-DK2

PLATFORM=stm32mp1-157C_DK2

Yes

STM32MP157C-EV1

PLATFORM=stm32mp1-157C_EV1

Yes

Texas Instruments DRA7xx

PLATFORM=ti-dra7xx

Yes

Texas Instruments AM57xx

PLATFORM=ti-am57xx

Yes

Texas Instruments AM43xx

PLATFORM=ti-am43xx

Yes

Manifests

Current version

Here is a list of manifests for the devices currently supported in build.git. With these you will get a setup containing the all necessary software components to run OP-TEE on the chosen device. Beware that this will run latest available on OP-TEE gits meaning that if you re-sync then you will most likely get new commits. If you need a stable/tagged version with non-moving gits, then please refer to the next section instead.

Target

Manifest xml

Device documentation

AM43xx

am43xx.xml

Texas Instruments SoCs

AM57xx

am57xx.xml

Texas Instruments SoCs

DeveloperBox

synquacer.xml

DeveloperBox

ARM Juno board

juno.xml

Juno

DRA7xx

dra7xx.xml

Texas Instruments SoCs

FVP

fvp.xml

FVP

HiKey 960

hikey960.xml

HiKey 960

HiKey

hikey.xml

HiKey 620

Poplar Debian

poplar.xml

QEMU

default.xml

QEMU v7

QEMUv8

qemu_v8.xml

QEMU v8

Raspberry Pi 3

rpi3.xml

Raspberry Pi 3

STM32MP1

stm32mp1.xml

STM32MP1

VCK190

versal.xml

AMD/Xilinx Versal ACAP VCK190

Stable releases

Starting from OP-TEE v3.1 you can check out stable releases by using the same manifests as for current version above, but with the difference that you also need to specify a branch where the name corresponds to the release version. I.e., when we are doing releases we are creating a branch with a name corresponding to the release version. So, let’s for example say that you want to checkout a stable OP-TEE v3.12 for Raspberry Pi 3, then you do like this instead of what is mentioned further down in section “Step 3 - Get the source code” (note the -b 3.12.0):

Hint

If there is no strong need for an older version, then we always recommend to use the most recent release. I.e., in the example here we do say 3.12.0, but there may very well be more recent version when you are reading this. To find out, please have a look at the “Release dates” page.

...
$ repo init -u https://github.com/OP-TEE/manifest.git -m rpi3.xml -b 3.12.0
...

Stable releases prior to OP-TEE v3.1 (v1.0.0 to v3.0.0)

Before OP-TEE v3.1 we used to have separate xml-manifest files for the stable builds. If you for some reason need an older stable release, please refer to “Build stable releases v1.0.0 to v3.0.0”.

Stable releases prior to OP-TEE v3.9 (3.1.0 to 3.8.0)

Due to a change in the Google repo tool, you might get an error when cloning OP-TEE repositories before version 3.9.0. In this case please refer to “Build stable releases 3.1.0 to 3.8.0”.

Get and build the solution

Below we will describe the general way of how to get the source, build the solution and how to run xtest on the device. For device specific instructions, please see the links in the table in the “Current version” section.

Step 1 - Prerequisites

Install prerequisites according to the Prerequisites page.

Step 2 - Install Android repo

Note that here you don’t install a huge SDK, it’s simply a Python script that you download and put in your $PATH, that’s it. Exactly how to “install” repo, can be found at the Google repo pages, so follow those instructions before continuing.

Step 3 - Get the source code

Choose the manifest corresponding to the platform you intend to use (see the table in section “Current version”. For example, if you intend to use Raspberry Pi3, then at line 3 below, ${TARGET}.xml shall be rpi3.xml. The <optee-project> is whatever location where you want to store the entire OP-TEE developer setup.

1$ mkdir -p <optee-project>
2$ cd <optee-project>
3$ repo init -u https://github.com/OP-TEE/manifest.git -m ${TARGET}.xml [-b ${BRANCH}]
4$ repo sync -j4 --no-clone-bundle

Hint

By referencing an existing and locally saved repo forest you can save lots of time. We are talking about doing repo sync in 30 seconds instead of 15-30 minutes (see the Tips and Tricks section for more details).

Step 4 - Get the toolchains

In OP-TEE we’re using different toolchains for different targets (depends on ARMv7-A ARMv8-A 64/32bit solutions). In any case start by downloading the toolchains by:

$ cd <optee-project>/build
$ make -j2 toolchains

Step 5 - Build the solution

We’ve configured our repo manifests, so that repo will always automatically symlink the Makefile to the correct device specific makefile, that means that you simply start the build by running (still in <optee-project>/build)

$ make -j `nproc`

This step will also take some time, but you can speed up subsequent builds by enabling ccache (again see Tips and Tricks).

Hint

If you’re having build issues, then you can pipe the entire build log to a file, which makes it easier to search for the issue using a regular editor. In that case also avoid the -j flag so it’s easier to see in what order things are happening. To create a build.log file do: $ make 2>&1 | tee build.log

Step 6 - Flash the device

On non-emulated solutions (this means that you shouldn’t do this step when you are running QEMU-v7/v8 and FVP), you will need to flash the software in some way. We’ve tried to “hide” that under the following make target:

$ make flash

But, since some devices are trickier to flash than others, please see the Device specific information. See this just as a general instruction.

Step 7 - Boot up the device

This is device specific (see Device specific information).

Step 8 - Load tee-supplicant

On most solutions tee-supplicant is already running (check by running $ ps aux | grep tee-supplicant) on others not. If it’s not running, then start it by running:

$ tee-supplicant -d

Note

If you’ve built using our manifest you should not need to modprobe any OP-TEE/TEE kernel driver since it’s built into the kernel in all our setups.

Step 9 - Run xtest

The entire xtest test suite has been deployed when you we’re making the builds in previous steps, i.e, in general there is no need to copy any binaries manually. Everything has been put into the Root filesystem automatically. So, to run xtest, you simply type:

$ xtest

If there are no regressions / issues found, xtest should end with something like this:

...
+-----------------------------------------------------
23476 subtests of which 0 failed
67 test cases of which 0 failed
0 test case was skipped
TEE test application done!

Hint

For other ways to run xtest, please refer to the “Run xtest” page at optee_test.

Tips and Tricks

Reference existing project to speed up repo sync

Doing a repo init, repo sync from scratch can take a fair amount of time. The main reason for that is simply because of the size of some of the gits we are using, like for the Linux kernel and EDK2. With repo you can reference an existing forest and by doing so you can speed up repo sync to taking 30 seconds instead of 15-30 minutes. The way to do this are as follows.

  1. Start by setup a clean forest that you will not touch, in this example, let us call that optee-ref and put that under for $HOME/devel/optee-ref. This step will take somewhere between 15- to 45 minutes, depending on your connection speed to internet.

  2. Then setup a cronjob (crontab -e) that does a repo sync in this folder particular folder once a night (that is more than enough).

  3. Now you should setup your actual tree which you are going to use as your working tree. The way to do this is almost the same as stated in the instructions above (see the “Step 3 - Get the source code” section) , the only difference is that you also reference the other local forest when running repo init, like this

    $ repo init -u https://github.com/OP-TEE/manifest.git --reference $HOME/devel/optee-ref
    
  4. The rest is the same above, but now it will only take a couple of seconds to clone a forest.

Normally ‘1’ and ‘2’ above is something you will only do once. Also if you ignore step ‘2’, then you will still get the latest from official git trees, since repo will also check for updates that aren’t at the local reference.

Use ccache

ccache is a tool that caches build object-files etc locally on the disc and can speed up build time significantly in subsequent builds. On Debian-based systems (Ubuntu, Mint etc) you simply install it by running:

$ sudo apt-get install ccache

The makefiles in build.git are configured to automatically find and use ccache if ccache is installed on your system, so other than having it installed you don’t have to think about anything.