1# OP-TEE Trusted OS 2## Contents 3<!--- TOC generated using http://doctoc.herokuapp.com/ --> 41. [Introduction](#1-introduction) 52. [License](#2-license) 63. [Platforms supported](#3-platforms-supported) 7 3. [Development board for community user] (#31-development-board-for-community-user) 84. [Get and build the software](#4-get-and-build-the-software) 9 4. [Basic setup](#41-basic-setup) 10 4. [Foundation Models](#42-foundation-models) 11 4. [ARM Juno board](#43-juno) 12 4. [QEMU](#44-qemu) 13 4. [STMicroelectronics boards](#45-stmicroelectronics-boards) 14 4. [Allwinner A80](#46-allwinner-a80) 15 4. [Mediatek MT8173 EVB](#47-mediatek-mt8173-evb) 16 4. [HiKey Board](#48-hikey-board) 175. [Coding standards](#5-coding-standards) 18 5. [checkpatch](#51-checkpatch) 196. [repo manifests](#6-repo-manifests) 20 6. [Install repo](#61-install-repo) 21 6. [Get the source code](#62-get-the-source-code) 22 6. [Targets](#621-targets) 23 6. [Branches](#622-branches) 24 6. [Get the toolchains](#623-get-the-toolchains) 25 6. [QEMU](#63-qemu) 26 6. [FVP](#64-fvp) 27 6. [Hikey](#65-hikey) 28 6. [MT8173-EVB](#66-mt8173-evb) 29 6. [Tips and tricks](#67-tips-and-tricks) 30 6. [Reference existing project to speed up repo sync](#671-reference-existing-project-to-speed-up-repo-sync) 31 6. [Use ccache](#672-use-ccache) 32 33# 1. Introduction 34The optee_os git, contains the source code for the TEE in Linux using the ARM(R) 35TrustZone(R) technology. This component meets the GlobalPlatform TEE System 36Architecture specification. It also provides the TEE Internal API v1.0 as 37defined by the Global Platform TEE Standard for the development of Trusted 38Applications. For a general overview of OP-TEE and to find out how to contribute, 39please see the [Notice.md](Notice.md) file. 40 41The Trusted OS is accessible from the Rich OS (Linux) using the 42[GlobalPlatform TEE Client API Specification v1.0](http://www.globalplatform.org/specificationsdevice.asp), 43which also is used to trigger secure execution of applications within the TEE. 44 45## 2. License 46The software is distributed mostly under the 47[BSD 2-Clause](http://opensource.org/licenses/BSD-2-Clause) open source 48license, apart from some files in the optee_os/lib/libutils directory which 49are distributed under the 50[BSD 3-Clause](http://opensource.org/licenses/BSD-3-Clause) or public domain 51licenses. 52 53## 3. Platforms supported 54Several platforms are supported. In order to manage slight differences 55between platforms, a `PLATFORM_FLAVOR` flag has been introduced. 56The `PLATFORM` and `PLATFORM_FLAVOR` flags define the whole configuration 57for a chip the where the Trusted OS runs. Note that there is also a 58composite form which makes it possible to append `PLATFORM_FLAVOR` directly, 59by adding a dash inbetween the names. The composite form is shown below 60for the different boards. For more specific details about build flags etc, 61please read the file [build_system.md](documentation/build_system.md). 62 63| Platform | Composite PLATFORM flag | 64|--------|--------| 65| [Foundation FVP](http://www.arm.com/fvp) |`PLATFORM=vexpress-fvp`| 66| [ARMs Juno Board](http://www.arm.com/products/tools/development-boards/versatile-express/juno-arm-development-platform.php) |`PLATFORM=vexpress-juno`| 67| [QEMU](http://wiki.qemu.org/Main_Page) |`PLATFORM=vexpress-qemu_virt`| 68| [STMicroelectronics b2120 - h310 / h410](http://www.st.com/web/en/catalog/mmc/FM131/SC999/SS1628/PF258776) |`PLATFORM=stm-cannes`| 69| [STMicroelectronics b2020-h416](http://www.st.com/web/catalog/mmc/FM131/SC999/SS1633/PF253155?sc=internet/imag_video/product/253155.jsp)|`PLATFORM=stm-orly2`| 70| [Allwinner A80 Board](http://www.allwinnertech.com/en/clq/processora/A80.html)|`PLATFORM=sunxi`| 71| [HiKey Board (HiSilicon Kirin 620)](https://www.96boards.org/products/hikey/)|`PLATFORM=hikey`| 72| [MediaTek MT8173 EVB Board](http://www.mediatek.com/en/products/mobile-communications/tablet/mt8173/)|`PLATFORM=mediatek-mt8173`| 73| Texas Instruments DRA7xx|`PLATFORM=ti-dra7xx`| 74 75### 3.1 Development board for community user 76For community users, we suggest using [Hikey board](https://www.96boards.org/products/ce/hikey/) 77as development board. It provides detailed documentation including chip 78datasheet, board schematics, ...etc. and also related open source software 79download link on the website. 80 81## 4. Get and build the software 82There are a couple of different build options depending on the target you are 83going to use. If you just want to get the software and compile it, then you 84should follow the instructions under the "Basic setup" below. In case you are 85going to run for a certain hardware or FVP, QEMU for example, then please follow 86the respective section instead. 87 88--- 89### 4.1 Basic setup 90#### 4.1.1 Get the compiler 91We will strive to use the latest available compiler from Linaro. Start by 92downloading and unpacking the compiler. Then export the PATH to the bin folder. 93 94``` 95$ cd $HOME 96$ mkdir toolchains 97$ cd toolchains 98$ wget http://releases.linaro.org/14.05/components/toolchain/binaries/gcc-linaro-arm-linux-gnueabihf-4.9-2014.05_linux.tar.xz 99$ tar xvf gcc-linaro-arm-linux-gnueabihf-4.9-2014.05_linux.tar.xz 100$ export PATH=$HOME/toolchains/gcc-linaro-arm-linux-gnueabihf-4.9-2014.05_linux/bin:$PATH 101``` 102 103#### 4.1.2 Download the source code 104``` 105$ cd $HOME 106$ mkdir devel 107$ cd devel 108$ git clone https://github.com/OP-TEE/optee_os.git 109``` 110 111#### 4.1.3 Build 112``` 113$ cd $HOME/devel/optee_os 114$ CROSS_COMPILE=arm-linux-gnueabihf- make 115``` 116 117#### 4.1.4 Compiler flags 118To be able to see the full command when building you could build using 119following flag: 120``` 121$ make V=1 122``` 123 124To enable debug builds use the following flag: 125``` 126$ make DEBUG=1 127``` 128 129OP-TEE supports a couple of different levels of debug prints for both TEE core 130itself and for the Trusted Applications. The level ranges from 1 to 4, where 131four is the most verbose. To set the level you use the following flag: 132``` 133$ make CFG_TEE_CORE_LOG_LEVEL=4 134``` 135 136--- 137### 4.2 Foundation Models 138 139See section [6. repo manifests]((#6-repo-manifests). 140 141--- 142### 4.3 Juno 143Juno has been supported in OP-TEE since mid October 2014. 144 145#### WARNING: 146 147+ The ```setup_juno_optee.sh``` script provides a coherent set of components (OP-TEE client/driver/os, 148Linux kernel version 3-16.0-rc5) 149 150+ Further release will align the ARM Juno setup with other OP-TEE supported platforms: 151 152 + Linux kernel version alignment (3.18-rc1) with QEMU/FVP (DMA_BUF API change). 153 + Will need arch/arm/Kconfig patch(es) (i.e DMA_SHARED_BUFFER etc...). 154 155+ Temporary patch files required for linux kernel and juno dtb definition: 156 157 + config.linux-linaro-tracking.a226b22057c22b433caafc58eeae6e9b13ac6c8d.patch 158 + juno.dts.linux-linaro-tracking.a226b22057c22b433caafc58eeae6e9b13ac6c8d.patch 159 160#### 4.3.1 Prerequisites 161+ The following packages must be installed: 162 163``` 164$ sudo apt-get install zlib1g-dev libglib2.0-dev libpixman-1-dev libfdt-dev \ 165 libc6:i386 libstdc++6:i386 libz1:i386 cscope netcat 166``` 167 168+ Download ARM Juno pre-built binaries: 169 170 + ARM Juno Pre-built binary bl30.bin (SCP runtime) 171 + ARM Juno Pre-built binary bl33.bin (UEFI) 172 + Download at http://community.arm.com/docs/DOC-8401 173 174 175#### 4.3.2 Download and install ARM Juno 176``` 177$ wget https://raw.githubusercontent.com/OP-TEE/optee_os/master/scripts/setup_juno_optee.sh 178$ chmod 711 setup_juno_optee.sh 179$ ./setup_juno_optee.sh 180``` 181 182#### 4.3.3 Build 183+ List of helper scripts generated during installation: 184 185* `build_atf_opteed.sh`: This is used to build ARM-Trusted-Firmware and must be 186 called when you have updated any component that are included in the FIP (like 187 for example OP-TEE os). 188 189* `build_linux.sh`: This is used to build the Linux Kernel. 190 191* `build_normal.sh`: This is a pure helper script that build all the normal 192 world components (in correct order). 193 194* `build_optee_client.sh`: This will build OP-TEEs client library. 195 196* `build_optee_linuxdriver.sh`: This will build OP-TEEs Linux Kernel driver (as 197 a module). 198 199* `build_optee_os.sh`: Builds the Trusted OS itself. 200 201* `build_optee_tests.sh`: This will build the test suite (pay attention to the 202 access needed). 203 204* `build_secure.sh`: This is the helper script for the secure side that will 205 build all secure side components in the correct order. 206 207* `clean_gits.sh`: This will clean all gits. Beware that it will not reset the 208 commit to the one used when first cloning. Also note that it will only clean 209 git's. 210 211+ Run the scripts in the following order: 212 213``` 214$ ./build_secure.sh 215$ ./build_normal.sh 216``` 217 218#### 4.3.4 Booting up ARM Juno 219 220+ Update the ARM Juno embedded flash memory (path: JUNO/SOFTWARE): 221 222 + bl1.bin 223 + fip.bin 224 + Image 225 + juno.dtb 226 227+ Copy OP-TEE binaries on the filesystem(*) located on the external USB key: 228 229 + user client libraries: libteec.so* 230 + supplicant: tee-supplicant 231 + driver modules: optee.ko. optee_armtz.ko 232 + CA: xtest 233 + TAs: *.ta 234 235+ Connect the USB key (filesystem) on any connector of the rear panel 236 237+ Connect a serial terminal (115200, 8, n, 1) 238to the upper 9-pin (UART0) connector. 239 240+ Connect the 12 volt power, then press the red button on the rear panel. 241 242Note: 243The default configuration is to automatically boot a Linux kernel, 244which expects to find a root filesystem on /dev/sda1 245(any one of the rear panel USB ports). 246 247(*)Download a minimal filesytem at: 248http://releases.linaro.org/14.02/openembedded/aarch64/ 249linaro-image-minimal-genericarmv8-20140223-649.rootfs.tar.gz 250 251UEFI offers a 10 second window to interrupt the boot sequence by pressing 252a key on the serial terminal, after which the kernel is launched. 253 254Once booted you will get the prompt: 255``` 256root@genericarmv8:~# 257``` 258 259#### 4.3.4 Run OP-TEE on ARM Juno 260Write in the console: 261``` 262root@genericarmv8:~# modprobe optee 263root@genericarmv8:~# tee-supplicant & 264``` 265Now everything has been set up and OP-TEE is ready to be used. 266 267#### 4.3.5 Known problems and limitations 268ARM Juno could be sensitive on the USB memory type (filesystem) 269Recommendation: Use USB memory 3.0 (ext3/ext4 filesystem) 270 271--- 272### 4.4 QEMU 273 274Please refer to section [6. repo manifests](#6-repo-manifests). 275 276--- 277### 4.5 STMicroelectronics boards 278Currently OP-TEE is supported on Orly-2 (b2020-h416) and Cannes family (b2120 279both h310 and h410 chip). 280 281#### 4.5.1 Get the compiler for Orly-2 282Will be written soon. 283 284#### 4.5.2 Download the source code 285See section "4.1.2 Download the source code". 286 287#### 4.5.3 Build for Orly-2 288Will be written soon. 289 290For Orly-2 do as follows 291``` 292$ PLATFORM_FLAVOR=orly2 CROSS_COMPILE=arm-linux-gnueabihf- make 293``` 294 295For Cannes family do as follows 296``` 297$ PLATFORM_FLAVOR=cannes CROSS_COMPILE=arm-linux-gnueabihf- make 298``` 299 300#### 4.5.4 Prepare and install the images 301Will be written soon. 302 303For Orly-2 do as follows 304``` 305To be written. 306``` 307 308For Cannes family do as follows 309``` 310To be written. 311``` 312 313#### 4.5.5 Boot and run the software 314Will be written soon. All magic with STM and so on must be stated here. 315 316For Orly-2 do as follows 317``` 318To be written. 319``` 320 321For Cannes family do as follows 322``` 323To be written. 324``` 325 326--- 327### 4.6 Allwinner A80 328Allwinner A80 platform has been supported in OP-TEE since mid December 2014. 329#### 4.6.1 Get the compiler and source 330Follow the instructions in the "4.1 Basic setup". 331 332#### 4.6.2 Build 333``` 334$ cd optee_os 335$ export PLATFORM=sunxi 336$ export CROSS_COMPILE=arm-linux-gnueabihf- 337$ make 338``` 339 340#### 4.6.3 Prepare the images to run on A80 Board 341 342Download Allwinner A80 platform SDK. 343The SDK refer to Allwinner A80 platform SDK root directory. 344A80 SDK directory tree like this: 345``` 346SDK/ 347 Android 348 lichee 349``` 350Android include all Android source code, 351lichee include bootloader and linux kernel. 352 353##### 4.6.3.1 Copy OP-TEE output to package directory 354copy the OP-TEE output binary to SDK/lichee/tools/pack/sun9i/bin 355``` 356$ cd optee_os 357$ cp ./out/arm32-plat-sunxi/core/tee.bin SDK/lichee/tools/pack/sun9i/bin 358``` 359 360##### 4.6.3.2 Build linux kernel 361In lichee directory, Type the following commands: 362``` 363$ cd SDK/lichee 364$ ./build.sh 365``` 366 367##### 4.6.3.3 Build Android 368In Android directory, Type the following commands: 369``` 370$ cd SDK/android 371$ extract-bsp 372$ make -j 373``` 374 375##### 4.6.3.4 Create Android image 376In andoid directory, Type the following commands: 377``` 378$ cd SDK/android 379$ pack 380``` 381The output image will been signed internally when pack. 382The output image name is a80_android_board.img. 383 384##### 4.6.3.5 Download Android image 385Use Allwinner PhoenixSuit tool to download to A80 board. 386Choose the output image(a80_android_board.img), 387Choose download, 388Wait for the download to complete. 389 390#### 4.6.4 Boot and run the software on A80 Board 391When the host platform is Windows, Use a console application 392to connect A80 board uart0. In the console window, 393You can install OP-TEE linux kernel driver optee.ko, 394Load OP-TEE-Client daemon tee-supplicant, 395Run OP-TEE example hello world application. 396This is done by the following lines: 397``` 398$ insmod /system/vendor/modules/optee.ko 399$ /system/bin/tee-supplicant & 400$ /system/bin/tee-helloworld 401``` 402Enjoying OP-TEE on A80 board. 403 404--- 405### 4.7 Mediatek MT8173 EVB 406Please refer to [8173 wiki](https://github.com/ibanezchen/linux-8173/wiki) 407to setup MT8173 evaluation board. 408 409To build the software, please see section [6. repo manifests](#6-repo-manifests). 410 411--- 412### 4.8 HiKey board 413[HiKey](https://www.96boards.org/products/hikey/) is a 96Boards Consumer 414Edition compliant board equipped with a HiSilicon Kirin 620 SoC (8-core, 41564-bit ARM Cortex A53). It can run OP-TEE in 32- and 64-bit modes. 416 417To build for HiKey, please refer to [6. repo manifests](#6-repo-manifests). 418 419## 5. Coding standards 420In this project we are trying to adhere to the same coding convention as used in 421the Linux kernel (see 422[CodingStyle](https://www.kernel.org/doc/Documentation/CodingStyle)). We achieve this by running 423[checkpatch](http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/scripts/checkpatch.pl) from Linux kernel. 424However there are a few exceptions that we had to make since the code also 425follows GlobalPlatform standards. The exceptions are as follows: 426 427- CamelCase for GlobalPlatform types are allowed. 428- And we also exclude checking third party code that we might use in this 429 project, such as LibTomCrypt, MPA, newlib (not in this particular git, but 430 those are also part of the complete TEE solution). The reason for excluding 431 and not fixing third party code is because we would probably deviate too much 432 from upstream and therefore it would be hard to rebase against those projects 433 later on (and we don't expect that it is easy to convince other software 434 projects to change coding style). 435 436### 5.1 checkpatch 437Since checkpatch is licensed under the terms of GNU GPL License Version 2, we 438cannot include this script directly into this project. Therefore we have 439written the Makefile so you need to explicitly point to the script by exporting 440an environment variable, namely CHECKPATCH. So, suppose that the source code for 441the Linux kernel is at `$HOME/devel/linux`, then you have to export like follows: 442 443 $ export CHECKPATCH=$HOME/devel/linux/scripts/checkpatch.pl 444thereafter it should be possible to use one of the different checkpatch targets 445in the [Makefile](Makefile). There are targets for checking all files, checking 446against latest commit, against a certain base-commit etc. For the details, read 447the [Makefile](Makefile). 448 449## 6. repo manifests 450 451A Git repository is available at https://github.com/OP-TEE/manifest where you 452will find configuration files for use with the Android 'repo' tool. 453This sections explains how to use it. 454 455### 6.1. Install repo 456Follow the instructions under the "Installing Repo" section 457[here](https://source.android.com/source/downloading.html). 458 459### 6.2. Get the source code 460``` 461$ mkdir -p $HOME/devel/optee 462$ cd $HOME/devel/optee 463$ repo init -u https://github.com/OP-TEE/manifest.git -m ${TARGET}.xml [-b ${BRANCH}] 464$ repo sync 465``` 466 467#### 6.2.1 Targets 468* QEMU: default.xml 469* FVP: fvp.xml 470* Hikey: hikey.xml 471* MediaTek MT8173 EVB Board: mt8173-evb.xml 472 473#### 6.2.2 Branches 474Currently we are only using one branch, i.e, the master branch. 475 476#### 6.2.3 Get the toolchains 477``` 478$ cd build 479$ make toolchains 480``` 481 482**Notes**<br> 483* The folder could be at any location, we are just giving a suggestion by 484 saying `$HOME/devel/optee`. 485* `repo sync` can take an additional parameter -j to sync multiple remotes. For 486 example `repo sync -j3` will sync three remotes in parallel. 487 488### 6.3. QEMU 489After getting the source and toolchain, just run: 490``` 491$ make all run 492``` 493and everything should compile and at the end QEMU should start. 494 495### 6.4. FVP 496After getting the source and toolchain you must also get the get Foundation 497Model 498([link](http://www.arm.com/products/tools/models/fast-models/foundation-model.php)) 499and untar it to the forest root, then just run: 500``` 501$ make all run 502``` 503and everything should compile and at the end FVP should start. 504 505### 6.5. Hikey 506After running `make` above, follow the instructions at 507[flash-binaries-to-emmc](https://github.com/96boards/documentation/wiki/HiKeyUEFI#flash-binaries-to-emmc-) 508to flash all the required images to and boot the board. 509 510Location of files/images mentioned in the link above: 511* ```$HOME/devel/optee/burn-boot/hisi-idt.py``` 512* ```$HOME/devel/optee/l-loader/l-loader.bin``` 513* ```$HOME/devel/optee/l-loader/ptable.img``` 514* ```$HOME/devel/optee/arm-trusted-firmware/build/hikey/release/fip.bin``` 515* ```$HOME/devel/optee/out/boot-fat.uefi.img``` 516 517### 6.6. MT8173-EVB 518After getting the source and toolchain, please run: 519 520``` 521$ make all run 522``` 523 524When `< waiting for device >` prompt appears, press reset button 525 526### 6.7 Tips and tricks 527#### 6.7.1 Reference existing project to speed up repo sync 528Doing a `repo init`, `repo sync` from scratch can take a fair amount of time. 529The main reason for that is simply because of the size of some of the gits we 530are using, like for the Linux kernel and EDK2. With repo you can reference an 531existing forest and by doing so you can speed up repo sync to instead taking ~20 532seconds instead of an hour. The way to do this are as follows. 533 5341. Start by setup a clean forest that you will not touch, in this example, let 535 us call that `optee-ref` and put that under for `$HOME/devel/optee-ref`. This 536 step will take roughly an hour. 5372. Then setup a cronjob (`crontab -e`) that does a `repo sync` in this folder 538 particular folder once a night (that is more than enough). 5393. Now you should setup your actual tree which you are going to use as your 540 working tree. The way to do this is almost the same as stated in the 541 instructions above, the only difference is that you reference the other local 542 forest when running `repo init`, like this 543 ``` 544 repo init -u https://github.com/OP-TEE/manifest.git --reference /home/jbech/devel/optee-ref 545 ``` 5464. The rest is the same above, but now it will only take a couple of seconds to 547 clone a forest. 548 549Normally step 1 and 2 above is something you will only do once. Also if you 550ignore step 2, then you will still get the latest from official git trees, since 551repo will also check for updates that aren't at the local reference. 552 553#### 6.7.2. Use ccache 554ccache is a tool that caches build object-files etc locally on the disc and can 555speed up build time significantly in subsequent builds. On Debian-based systems 556(Ubuntu, Mint etc) you simply install it by running: 557``` 558$ sudo apt-get install ccache 559``` 560 561The helper makefiles are configured to automatically find and use ccache if 562ccache is installed on your system, so other than having it installed you don't 563have to think about anything. 564 565