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