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