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`| No | 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 310#### 4.5.1 Locked versus unlocked A80 boards 311**Important!** All A80 boards sold to the general public are boards where secure 312side has been locked down, which means that you **cannot** use them for secure 313side development, i.e, it will not be possible to put OP-TEE on those devices. 314If you want to use A80 board for secure side development, then you will need to 315talk to 316[Allwinner](https://github.com/OP-TEE/optee_os/blob/master/MAINTAINERS.md) 317directly and ask if it is possible get a device from them. 318 319#### 4.5.2 Get the compiler and source 320Follow the instructions in the "4.2 Basic setup". 321 322#### 4.5.3 Build 323``` 324$ cd optee_os 325$ export PLATFORM=sunxi 326$ export CROSS_COMPILE=arm-linux-gnueabihf- 327$ make 328``` 329 330#### 4.5.4 Prepare the images to run on A80 Board 331 332Download Allwinner A80 platform SDK, the SDK refers to Allwinner A80 platform 333SDK root directory. A80 SDK directory tree looks like this: 334``` 335SDK/ 336 Android 337 lichee 338``` 339`Android` contains all source code related to Android and `lichee` 340contains the bootloader and Linux kernel. 341 342##### 4.5.4.1 Copy OP-TEE output to package directory 343Copy the OP-TEE output binary to `SDK/lichee/tools/pack/sun9i/bin` 344 345``` 346$ cd optee_os 347$ cp ./out/arm32-plat-sunxi/core/tee.bin SDK/lichee/tools/pack/sun9i/bin 348``` 349 350##### 4.5.4.2 Build Linux kernel 351In the `lichee` directory, run the following commands: 352``` 353$ cd SDK/lichee 354$ ./build.sh 355``` 356 357##### 4.5.4.3 Build Android 358In the Android directory, run the following commands: 359``` 360$ cd SDK/android 361$ extract-bsp 362$ make -j 363``` 364 365##### 4.5.4.4 Create the Android image 366In the Android directory, run the following commands: 367``` 368$ cd SDK/android 369$ pack 370``` 371The output image will been signed internally when packed. The output image name 372is `a80_android_board.img`. 373 374##### 4.5.4.5 Download the Android image 375Use `Allwinner PhoenixSuit` tool to download to A80 board. 376Choose the output image(`a80_android_board.img`), select download and wait 377for the download to complete. 378 379#### 4.5.5 Boot and run the software on A80 Board 380When the host platform is Windows, use a console application to connect A80 381board `uart0`. In the console window, You can install OP-TEE linux kernel 382driver `optee.ko`, load OP-TEE-Client daemon `tee-supplicant` and run 383the example "hello world" Trusted Application, do this by running: 384``` 385$ insmod /system/vendor/modules/optee.ko 386$ /system/bin/tee-supplicant & 387$ /system/bin/tee-helloworld 388``` 389 390--- 391### 4.6 Freescale MX6UL EVK 392Build: 393``` 394 PLATFORM_FLAVOR=mx6ulevk make PLATFORM=imx 395 ${CROSS_COMPILE}-objcopy -O binary out/arm-plat-imx/core/tee.elf optee.bin 396 copy optee.bin to the first partition of SD card which is used for boot. 397``` 398Run using U-Boot: 399``` 400 run loadfdt; 401 run loadimage; 402 fatload mmc 1:1 0x9c100000 optee.bin; 403 run mmcargs; 404 bootz ${loadaddr} - ${fdt_addr}; 405``` 406 407Note: 408 CAAM is not implemented now, this will be added later. 409 410--- 411## 5. repo manifests 412 413A Git repository is available at https://github.com/OP-TEE/manifest where you 414will find XML-files for use with the Android 'repo' tool. 415 416### 5.1. Install repo 417Follow the instructions under the "Installing Repo" section 418[here](https://source.android.com/source/downloading.html). 419 420### 5.2. Get the source code 421First ensure that you have the necessary Ubuntu packages installed, see [4.1 422Prerequisites](#41-prerequisites) (this is the only important step from section 4234 in case you are setting up any of the target devices mentioned below). 424 425``` 426$ mkdir -p $HOME/devel/optee 427$ cd $HOME/devel/optee 428$ repo init -u https://github.com/OP-TEE/manifest.git -m ${TARGET}.xml [-b ${BRANCH}] 429$ repo sync 430``` 431 432#### 5.2.1 Targets 433| Target | Latest | Stable | 434|--------|--------|--------| 435| QEMU | `default.xml` | `default_stable.xml` | 436| FVP | `fvp.xml` | `fvp_stable.xml` | 437| HiKey | `hikey.xml` | `hikey_stable.xml` | 438| MediaTek MT8173 EVB Board | `mt8173-evb.xml` | `mt8173-evb_stable.xml` | 439 440#### 5.2.2 Branches 441Currently we are only using one branch, i.e, the `master` branch. 442 443#### 5.2.3 Get the toolchains 444``` 445$ cd build 446$ make toolchains 447``` 448 449**Notes**<br> 450* The folder could be at any location, we are just giving a suggestion by 451 saying `$HOME/devel/optee`. 452* `repo sync` can take an additional parameter -j to sync multiple remotes. For 453 example `repo sync -j3` will sync three remotes in parallel. 454 455--- 456### 5.3. QEMU 457After getting the source and toolchain, just run (from the `build` folder) 458``` 459$ make all run 460``` 461and everything should compile and at the end QEMU should start. 462 463--- 464### 5.4. FVP 465After getting the source and toolchain you must also obtain Foundation Model 466([link](http://www.arm.com/products/tools/models/fast-models/foundation-model.php)) 467binaries and untar it to the forest root, then just run (from the `build` folder) 468 469``` 470$ make all run 471``` 472and everything should compile and at the end FVP should start. 473 474--- 475### 5.5. HiKey 476After getting the source and toolchain, just run (from the `build` folder) 477``` 478$ make all 479``` 480 481After that connect the board and flash the binaries by running: 482``` 483$ make flash 484``` 485 486(more information about how to flash individual binaries could be found 487[here](https://github.com/96boards/documentation/wiki/HiKeyUEFI#flash-binaries-to-emmc-)) 488 489The board is ready to be booted. 490 491--- 492### 5.6. MT8173-EVB 493After getting the source and toolchain, just run (from the `build` folder) 494 495``` 496$ make all run 497``` 498 499When `< waiting for device >` prompt appears, press reset button and the 500flashing procedure should begin. 501 502--- 503### 5.7 Tips and tricks 504#### 5.7.1 Reference existing project to speed up repo sync 505Doing a `repo init`, `repo sync` from scratch can take a fair amount of time. 506The main reason for that is simply because of the size of some of the gits we 507are using, like for the Linux kernel and EDK2. With repo you can reference an 508existing forest and by doing so you can speed up repo sync to instead taking ~20 509seconds instead of an hour. The way to do this are as follows. 510 5111. Start by setup a clean forest that you will not touch, in this example, let 512 us call that `optee-ref` and put that under for `$HOME/devel/optee-ref`. This 513 step will take roughly an hour. 5142. Then setup a cronjob (`crontab -e`) that does a `repo sync` in this folder 515 particular folder once a night (that is more than enough). 5163. Now you should setup your actual tree which you are going to use as your 517 working tree. The way to do this is almost the same as stated in the 518 instructions above, the only difference is that you reference the other local 519 forest when running `repo init`, like this 520 ``` 521 repo init -u https://github.com/OP-TEE/manifest.git --reference /home/jbech/devel/optee-ref 522 ``` 5234. The rest is the same above, but now it will only take a couple of seconds to 524 clone a forest. 525 526Normally step 1 and 2 above is something you will only do once. Also if you 527ignore step 2, then you will still get the latest from official git trees, since 528repo will also check for updates that aren't at the local reference. 529 530#### 5.7.2. Use ccache 531ccache is a tool that caches build object-files etc locally on the disc and can 532speed up build time significantly in subsequent builds. On Debian-based systems 533(Ubuntu, Mint etc) you simply install it by running: 534``` 535$ sudo apt-get install ccache 536``` 537 538The helper makefiles are configured to automatically find and use ccache if 539ccache is installed on your system, so other than having it installed you don't 540have to think about anything. 541 542--- 543## 6. Load driver, tee-supplicant and run xtest 544To actually run something on a device you need to probe the kernel driver for 545OP-TEE, run tee-supplicant. This is the same for almost all platforms, so when a 546device has booted, then run 547``` 548$ modprobe optee_armtz 549$ tee-supplicant & 550``` 551 552In case you want to try run something triggering both normal and secure side 553code you could run xtest (the main test suite for OP-TEE), run 554``` 555$ xtest 556``` 557 558--- 559## 7. Coding standards 560In this project we are trying to adhere to the same coding convention as used in 561the Linux kernel (see 562[CodingStyle](https://www.kernel.org/doc/Documentation/CodingStyle)). We achieve this by running 563[checkpatch](http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/scripts/checkpatch.pl) 564from Linux kernel. However there are a few exceptions that we had to make since 565the code also follows GlobalPlatform standards. The exceptions are as follows: 566 567- CamelCase for GlobalPlatform types are allowed. 568- And we also exclude checking third party code that we might use in this 569 project, such as LibTomCrypt, MPA, newlib (not in this particular git, but 570 those are also part of the complete TEE solution). The reason for excluding 571 and not fixing third party code is because we would probably deviate too much 572 from upstream and therefore it would be hard to rebase against those projects 573 later on (and we don't expect that it is easy to convince other software 574 projects to change coding style). 575 576### 7.1 checkpatch 577Since checkpatch is licensed under the terms of GNU GPL License Version 2, we 578cannot include this script directly into this project. Therefore we have 579written the Makefile so you need to explicitly point to the script by exporting 580an environment variable, namely CHECKPATCH. So, suppose that the source code for 581the Linux kernel is at `$HOME/devel/linux`, then you have to export like follows: 582 583 $ export CHECKPATCH=$HOME/devel/linux/scripts/checkpatch.pl 584thereafter it should be possible to use one of the different checkpatch targets 585in the [Makefile](Makefile). There are targets for checking all files, checking 586against latest commit, against a certain base-commit etc. For the details, read 587the [Makefile](Makefile). 588 589