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