1# OP-TEE Trusted OS 2## Contents 3<!--- TOC generated using http://doctoc.herokuapp.com/ --> 41. [Introduction](#1-introduction) 52. [License](#2-license) 63. [Platforms supported](#3-platforms-supported) 74. [Get and build the software](#4-get-and-build-the-software) 8 4. [Basic setup](#41-basic-setup) 9 4. [Foundation Models](#42-foundation-models) 10 4. [ARM Juno board](#43-juno) 11 4. [QEMU](#44-qemu) 12 4. [STMicroelectronics boards](#45-stmicroelectronics-boards) 13 4. [Allwinner A80](#46-allwinner-a80) 145. [Coding standards](#5-coding-standards) 15 5. [checkpatch](#51-checkpatch) 16 17# 1. Introduction 18The optee_os git, contains the source code for the TEE in Linux using the ARM(R) 19TrustZone(R) technology. This component meets the GlobalPlatform TEE System 20Architecture specification. It also provides the TEE Internal API v1.0 as 21defined by the Global Platform TEE Standard for the development of Trusted 22Applications. For a general overview of OP-TEE and to find out how to contribute, 23please see the [Notice.md](Notice.md) file. 24 25The Trusted OS is accessible from the Rich OS (Linux) using the 26[GlobalPlatform TEE Client API Specification v1.0](http://www.globalplatform.org/specificationsdevice.asp), 27which also is used to trigger secure execution of applications within the TEE. 28 29## 2. License 30The software is distributed mostly under the 31[BSD 2-Clause](http://opensource.org/licenses/BSD-2-Clause) open source 32license, apart from some files in the optee_os/lib/libutils directory which 33are distributed under the 34[BSD 3-Clause](http://opensource.org/licenses/BSD-3-Clause) or public domain 35licenses. 36 37## 3. Platforms supported 38Several platforms are supported. In order to manage slight differences 39between platforms, a `PLATFORM_FLAVOR` flag has been introduced. 40The `PLATFORM` and `PLATFORM_FLAVOR` flags define the whole configuration 41for a chip the where the Trusted OS runs. Note that there is also a 42composite form which makes it possible to append `PLATFORM_FLAVOR` directly, 43by adding a dash inbetween the names. The composite form is shown below 44for the different boards. For more specific details about build flags etc, 45please read the file [build_system.md](documentation/build_system.md). 46 47| Platform | Composite PLATFORM flag | 48|--------|--------| 49| [Foundation FVP](http://www.arm.com/fvp) |`PLATFORM=vexpress-fvp`| 50| [ARMs Juno Board](http://www.arm.com/products/tools/development-boards/versatile-express/juno-arm-development-platform.php) |`PLATFORM=vexpress-juno`| 51| [QEMU](http://wiki.qemu.org/Main_Page) |`PLATFORM=vexpress-qemu_virt`| 52| [STMicroelectronics b2120 - h310 / h410](http://www.st.com/web/en/catalog/mmc/FM131/SC999/SS1628/PF258776) |`PLATFORM=stm-cannes`| 53| [STMicroelectronics b2020-h416](http://www.st.com/web/catalog/mmc/FM131/SC999/SS1633/PF253155?sc=internet/imag_video/product/253155.jsp)|`PLATFORM=stm-orly2`| 54| [Allwinner A80 Board](http://www.allwinnertech.com/en/clq/processora/A80.html)|`PLATFORM=sunxi`| 55 56## 4. Get and build the software 57There are a couple of different build options depending on the target you are 58going to use. If you just want to get the software and compile it, then you 59should follow the instructions under the "Basic setup" below. In case you are 60going to run for a certain hardware or FVP, QEMU for example, then please follow 61the respective section instead. 62 63--- 64### 4.1 Basic setup 65#### 4.1.1 Get the compiler 66We will strive to use the latest available compiler from Linaro. Start by 67downloading and unpacking the compiler. Then export the PATH to the bin folder. 68 69``` 70$ cd $HOME 71$ mkdir toolchains 72$ cd toolchains 73$ wget http://releases.linaro.org/14.05/components/toolchain/binaries/gcc-linaro-arm-linux-gnueabihf-4.9-2014.05_linux.tar.xz 74$ tar xvf gcc-linaro-arm-linux-gnueabihf-4.9-2014.05_linux.tar.xz 75$ export PATH=$HOME/toolchains/gcc-linaro-arm-linux-gnueabihf-4.9-2014.05_linux/bin:$PATH 76``` 77 78#### 4.1.2 Download the source code 79``` 80$ cd $HOME 81$ mkdir devel 82$ cd devel 83$ git clone https://github.com/OP-TEE/optee_os.git 84``` 85 86#### 4.1.3 Build 87``` 88$ cd $HOME/devel/optee_os 89$ CROSS_COMPILE=arm-linux-gnueabihf- make 90``` 91 92#### 4.1.4 Compiler flags 93To be able to see the full command when building you could build using 94following flag: 95``` 96$ make V=1 97``` 98 99To enable debug builds use the following flag: 100``` 101$ make DEBUG=1 102``` 103 104OP-TEE supports a couple of different levels of debug prints for both TEE core 105itself and for the Trusted Applications. The level ranges from 1 to 4, where 106four is the most verbose. To set the level you use the following flag: 107``` 108$ make CFG_TEE_CORE_LOG_LEVEL=4 109``` 110 111--- 112### 4.2 Foundation Models 113By following this section will setup OP-TEE using FVP (Foundation Models and 114also Fast Models). You will have to download a script in this git and then run 115it, modify it slightly and then run it again. The reason for this is that we 116are not allowed to share Foundation models. I.e, the user has to download it 117from ARM directly. 118 119#### 4.2.1 Prerequisites 120To be able run this script you will need to install a couple of dependencies. On 121a Debian based system (Ubuntu, Mint etc.), you will at least need to install the 122following packages: 123 124``` 125$ sudo apt-get install uuid-dev 126``` 127and in case you are running on a 64bits system, then you will need to install 128the following packages. 129 130``` 131$ sudo apt-get install libc6:i386 libstdc++6:i386 libz1:i386 132``` 133 134#### 4.2.2 Download and setup FVP 135``` 136$ wget https://raw.githubusercontent.com/OP-TEE/optee_os/master/scripts/setup_fvp_optee.sh 137$ chmod 711 setup_fvp_optee.sh 138$ ./setup_fvp_optee.sh 139``` 140Follow the instructions to download Foundation Models and then update the first 141few lines under the "EDIT" section in the script. Note that if you are not 142working in Linaro and belongs to Security Working Group you will probably not 143have access to teetest.git, hence you should most likely leave this as it is. 144Run the script again. 145``` 146$ ./setup_fvp_optee.sh 147``` 148After about one hour (it's mainly cloning the kernel and edk2 that takes time) 149everything should have been cloned and built and you should be ready to use 150this. Pay attention to the line saying `OP-TEE and FVP setup completed.` that 151would be displayed when the script successfully ended. If you don't see this at 152the end, then something went wrong. 153 154#### 4.2.3 Compile 155During installation a couple of helper scripts were generated, the main reason 156for this is that there is a lot of interdependencies between the different 157software components and it's a bit tricky to point to the correct toolchains and 158to know in which order to build things. 159 160* `build_atf_opteed.sh`: This is used to build ARM-Trusted-Firmware and must be 161 called when you have updated any component that are included in the FIP (like 162 for example OP-TEE os). 163 164* `build_linux.sh`: This is used to build the Linux Kernel. 165 166* `build_normal.sh`: This is a pure helper script that build all the normal 167 world components (in correct order). 168 169* `build_optee_client.sh`: This will build OP-TEEs client library. 170 171* `build_optee_linuxkernel.sh`: This will build OP-TEEs Linux Kernel driver (as 172 a module). 173 174* `build_optee_os.sh`: Builds the Trusted OS itself. 175 176* `build_optee_tests.sh`: This will build the test suite (pay attention to the 177 access needed). 178 179* `build_secure.sh`: This is the helper script for the secure side that will 180 build all secure side components in the correct order. 181 182* `build_uefi.sh`: This will build Tianocore (UEFI). 183 184* `clean_gits.sh`: This will clean all gits. Beware that it will not reset the 185 commit to the one used when first cloning. Also note that it will only clean 186 git's (meaning that it will not clean Foundation models, toolchain folders). 187 188* `run_foundation.sh`: This is the script to use when starting FVP. 189 190* `update_rootfs.sh`: This script will update rootfs. For example when you have 191 updated normal world component, you will need to put them into rootfs. Calling 192 this script will do so. In case you are creating a new Trusted Application, 193 you must also edit filelist-tee.text in the gen_rootfs folder accordingly. 194 195Depending on how you are working you have the option to build components 196separately or you can build everything by running two of the scripts above. 197In case you want to make sure that everything was built and updated, we suggest 198that you call the scripts in the following order. 199``` 200$ ./build_secure.sh 201$ ./build_normal.sh 202``` 203By doing so all components should be (re-)built in the correct order and rootfs 204will be updated accordingly. 205 206#### 4.2.4 Run Foundation models and OP-TEE 207You simply run the script `run_foundation.sh`, load the module and start 208tee-supplicant. 209``` 210$ ./run_foundation.sh 211``` 212and in the console write 213``` 214root@FVP:/ modprobe optee_armtz 215root@FVP:/ tee-supplicant & 216``` 217Now everything has been set up and OP-TEE is ready to be used. 218 219#### 4.2.5 Known problems and limitations 220* The script `setup_fvp_optee.sh` doesn't do much error checking and doesn't 221 have many fallbacks in case of a problem. 222* The script `setup_fvp_optee.sh` setup things using absolute paths, i.e, you 223 cannot just copy a working environment to a new location. 224* In some situations you will get an error message about `undefined reference to 225 raise`. We know about this issue and it is being tracked in 226 [#issue95](https://github.com/OP-TEE/optee_os/issues/95) at GitHub. 227 228--- 229### 4.3 Juno 230Juno has been supported in OP-TEE since mid October 2014. 231#### 4.3.1 Get the compiler and source 232Follow the instructions in the "4.1 Basic setup". 233 234#### 4.3.2 Build 235``` 236$ cd optee_os 237$ PLATFORM=vexpress PLATFORM_FLAVOR=juno CROSS_COMPILE=arm-linux-gnueabihf- make 238``` 239 240#### 4.3.3 Prepare the images to run on Juno 241Will be written soon. 242 243#### 4.3.4 Boot and run the software on Juno 244Will be written soon. 245 246--- 247### 4.4 QEMU 248You can run OP-TEE using QEMU since October 2014. 249 250#### 4.4.1 Prerequisites 251To be able run this script you will need to install a couple of dependencies. On 252a Debian based system (Ubuntu, Mint etc.), you will at least need to install the 253following packages: 254 255``` 256$ sudo apt-get install zlib1g-dev libglib2.0-dev libpixman-1-dev libfdt-dev \ 257 libc6:i386 libstdc++6:i386 libz1:i386 cscope 258``` 259 260#### 4.4.2 Download and setup QEMU 261``` 262$ wget https://raw.githubusercontent.com/OP-TEE/optee_os/master/scripts/setup_qemu_optee.sh 263$ chmod 711 setup_qemu_optee.sh 264$ ./setup_qemu_optee.sh 265``` 266 267#### 4.4.3 Compile for QEMU 268During installation a couple of helper scripts were generated, the main reason 269for this is that there is a lot of interdependencies between the different 270software components and it's a bit tricky to point to the correct toolchains and 271to know in which order to build things. 272 273* `build_bios.sh`: This build the BIOS needed in QEMU 274 275* `build_linux.sh`: This is used to build the Linux Kernel. 276 277* `build_optee_client.sh`: This will build OP-TEEs client library. 278 279* `build_optee_linuxkernel.sh`: This will build OP-TEEs Linux Kernel driver (as 280 a module). 281 282* `build_optee_os.sh`: Builds the Trusted OS itself. 283 284* `build.sh`: Builds all software components in the correct order. 285 286* `run_qemu.sh`: This script starts QEMU. 287 288* `serial_0.sh`: Starts listening to QEMUs normal world UART console. 289 290* `serial_1.sh`: Starts listening to QEMUs secure world UART console. 291 292* `update_rootfs.sh`: This script will update rootfs. For example when you have 293 updated normal world component, you will need to put them into rootfs. Calling 294 this script will do so. In case you are creating a new Trusted Application, 295 you must also edit filelist-tee.text in the gen_rootfs folder accordingly. 296 297To build everything you will need to run the script `build.sh`, which will build 298all gits and in the correct order. 299 300#### 4.4.4 Boot and run QEMU and OP-TEE 301To run this you need to lunch two consoles for the UARTs and one console for 302QEMU itself, so in separate shell windows run: 303``` 304$ ./serial_0.sh 305``` 306``` 307$ ./serial_1.sh 308``` 309and finally 310``` 311$ ./run_qemu.sh 312... 313QEMU 2.1.50 monitor - type 'help' for more information 314(qemu) c 315``` 316 317In the window for serial_0 you will now get the normal world console and here 318you need to load and OP-TEEs Linux Kernel driver and also load tee-supplicant. 319This is done by the following lines: 320 321``` 322$ root@Vexpress:/ modprobe optee_armtz 323$ root@Vexpress:/ tee-supplicant & 324``` 325 326--- 327### 4.5 STMicroelectronics boards 328Currently OP-TEE is supported on Orly-2 (b2020-h416) and Cannes family (b2120 329both h310 and h410 chip). 330 331#### 4.5.1 Get the compiler for Orly-2 332Will be written soon. 333 334#### 4.5.2 Download the source code 335See section "4.1.2 Download the source code". 336 337#### 4.5.3 Build for Orly-2 338Will be written soon. 339 340For Orly-2 do as follows 341``` 342$ PLATFORM_FLAVOR=orly2 CROSS_COMPILE=arm-linux-gnueabihf- make 343``` 344 345For Cannes family do as follows 346``` 347$ PLATFORM_FLAVOR=cannes CROSS_COMPILE=arm-linux-gnueabihf- make 348``` 349 350#### 4.5.4 Prepare and install the images 351Will be written soon. 352 353For Orly-2 do as follows 354``` 355To be written. 356``` 357 358For Cannes family do as follows 359``` 360To be written. 361``` 362 363#### 4.5.5 Boot and run the software 364Will be written soon. All magic with STM and so on must be stated here. 365 366For Orly-2 do as follows 367``` 368To be written. 369``` 370 371For Cannes family do as follows 372``` 373To be written. 374``` 375 376--- 377### 4.6 Allwinner A80 378Allwinner A80 platform has been supported in OP-TEE since mid December 2014. 379#### 4.6.1 Get the compiler and source 380Follow the instructions in the "4.1 Basic setup". 381 382#### 4.6.2 Build 383``` 384$ cd optee_os 385$ export PLATFORM=sunxi 386$ export CROSS_COMPILE=arm-linux-gnueabihf- 387$ make 388``` 389 390#### 4.6.3 Prepare the images to run on A80 Board 391 392Download Allwinner A80 platform SDK. 393The SDK refer to Allwinner A80 platform SDK root directory. 394A80 SDK directory tree like this: 395``` 396SDK/ 397 Android 398 lichee 399``` 400Android include all Android source code, 401lichee include bootloader and linux kernel. 402 403##### 4.6.3.1 Copy OP-TEE output to package directory 404copy the OP-TEE output binary to SDK/lichee/tools/pack/sun9i/bin 405``` 406$ cd optee_os 407$ cp ./out/arm32-plat-sunxi/core/tee.bin SDK/lichee/tools/pack/sun9i/bin 408``` 409 410##### 4.6.3.2 Build linux kernel 411In lichee directory, Type the following commands: 412``` 413$ cd SDK/lichee 414$ ./build.sh 415``` 416 417##### 4.6.3.3 Build Android 418In Android directory, Type the following commands: 419``` 420$ cd SDK/android 421$ extract-bsp 422$ make -j 423``` 424 425##### 4.6.3.4 Create Android image 426In andoid directory, Type the following commands: 427``` 428$ cd SDK/android 429$ pack 430``` 431The output image will been signed internally when pack. 432The output image name is a80_android_board.img. 433 434##### 4.6.3.5 Download Android image 435Use Allwinner PhoenixSuit tool to download to A80 board. 436Choose the output image(a80_android_board.img), 437Choose download, 438Wait for the download to complete. 439 440#### 4.6.4 Boot and run the software on A80 Board 441When the host platform is Windows, Use a console application 442to connect A80 board uart0. In the console window, 443You can install OP-TEE linux kernel driver optee.ko, 444Load OP-TEE-Client daemon tee-supplicant, 445Run OP-TEE example hello world application. 446This is done by the following lines: 447``` 448$ insmod /system/vendor/modules/optee.ko 449$ /system/bin/tee-supplicant & 450$ /system/bin/tee-helloworld 451``` 452Enjoying OP-TEE on A80 board. 453 454## 5. Coding standards 455In this project we are trying to adhere to the same coding convention as used in 456the Linux kernel (see 457[CodingStyle](https://www.kernel.org/doc/Documentation/CodingStyle)). We achieve this by running 458[checkpatch](http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/scripts/checkpatch.pl) from Linux kernel. 459However there are a few exceptions that we had to make since the code also 460follows GlobalPlatform standards. The exceptions are as follows: 461 462- CamelCase for GlobalPlatform types are allowed. 463- And we also exclude checking third party code that we might use in this 464 project, such as LibTomCrypt, MPA, newlib (not in this particular git, but 465 those are also part of the complete TEE solution). The reason for excluding 466 and not fixing third party code is because we would probably deviate too much 467 from upstream and therefore it would be hard to rebase against those projects 468 later on (and we don't expect that it is easy to convince other software 469 projects to change coding style). 470 471### 5.1 checkpatch 472Since checkpatch is licensed under the terms of GNU GPL License Version 2, we 473cannot include this script directly into this project. Therefore we have 474written the Makefile so you need to explicitly point to the script by exporting 475an environment variable, namely CHECKPATCH. So, suppose that the source code for 476the Linux kernel is at `$HOME/devel/linux`, then you have to export like follows: 477 478 $ export CHECKPATCH=$HOME/devel/linux/scripts/checkpatch.pl 479thereafter it should be possible to use one of the different checkpatch targets 480in the [Makefile](Makefile). There are targets for checking all files, checking 481against latest commit, against a certain base-commit etc. For the details, read 482the [Makefile](Makefile). 483