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