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. [STMicroelectronics boards](#44-stmicroelectronics-boards) 11 4. [Allwinner A80](#45-allwinner-a80) 12 4. [Freescale MX6UL EVK](#46-freescale-mx6ul-evk) 135. [repo manifests](#5-repo-manifests) 14 5. [Install repo](#51-install-repo) 15 5. [Get the source code](#52-get-the-source-code) 16 5. [Targets](#521-targets) 17 5. [Branches](#522-branches) 18 5. [Get the toolchains](#523-get-the-toolchains) 19 5. [QEMU](#53-qemu) 20 5. [FVP](#54-fvp) 21 5. [HiKey](#55-hikey) 22 5. [MT8173-EVB](#56-mt8173-evb) 23 5. [Juno](#57-juno) 24 5. [Update flash and its layout](#571-update-flash-and-its-layout) 25 5. [GlobalPlatform testsuite support](#572-globalplatform-testsuite-support) 26 5. [GCC5 support](#573-gcc5-support) 27 5. [Raspberry Pi 3](#58-raspberry-pi-3) 28 5. [Tips and tricks](#59-tips-and-tricks) 29 5. [Reference existing project to speed up repo sync](#581-reference-existing-project-to-speed-up-repo-sync) 30 5. [Use ccache](#582-use-ccache) 316. [Load driver, tee-supplicant and run xtest](#6-load-driver-tee-supplicant-and-run-xtest) 327. [Coding standards](#7-coding-standards) 33 7. [checkpatch](#71-checkpatch) 34 35# 1. Introduction 36The `optee_os git`, contains the source code for the TEE in Linux using the 37ARM® TrustZone® technology. This component meets the GlobalPlatform 38TEE System Architecture specification. It also provides the TEE Internal core API 39v1.1 as defined by the GlobalPlatform TEE Standard for the development of 40Trusted Applications. For a general overview of OP-TEE and to find out how to 41contribute, please see the [Notice.md](Notice.md) file. 42 43The Trusted OS is accessible from the Rich OS (Linux) using the 44[GlobalPlatform TEE Client API Specification v1.0](http://www.globalplatform.org/specificationsdevice.asp), 45which also is used to trigger secure execution of applications within the TEE. 46 47--- 48## 2. License 49The software is distributed mostly under the 50[BSD 2-Clause](http://opensource.org/licenses/BSD-2-Clause) open source 51license, apart from some files in the `optee_os/lib/libutils` directory 52which are distributed under the 53[BSD 3-Clause](http://opensource.org/licenses/BSD-3-Clause) or public domain 54licenses. 55 56--- 57## 3. Platforms supported 58Several platforms are supported. In order to manage slight differences 59between platforms, a `PLATFORM_FLAVOR` flag has been introduced. 60The `PLATFORM` and `PLATFORM_FLAVOR` flags define the whole configuration 61for a chip the where the Trusted OS runs. Note that there is also a 62composite form which makes it possible to append `PLATFORM_FLAVOR` directly, 63by adding a dash in-between the names. The composite form is shown below 64for the different boards. For more specific details about build flags etc, 65please read the file [build_system.md](documentation/build_system.md). Some 66platforms have different sub-maintainers, please refer to the file 67[MAINTAINERS.md](MAINTAINERS.md) for contact details for various platforms. 68 69<!-- Please keep this list sorted in alphabetic order --> 70| Platform | Composite PLATFORM flag | Publicly available? | 71|----------|-------------------------|---------------------| 72| [Allwinner A80 Board](http://www.allwinnertech.com/en/clq/processora/A80.html)|`PLATFORM=sunxi`| No | 73| [ARM Juno Board](http://www.arm.com/products/tools/development-boards/versatile-express/juno-arm-development-platform.php) |`PLATFORM=vexpress-juno`| Yes | 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`| Yes | 75| [FSL i.MX6 Quad SABRE Lite Board](https://boundarydevices.com/product/sabre-lite-imx6-sbc/) |`PLATFORM=imx`| Yes | 76| [FSL i.MX6 Quad SABRE SD Board](http://www.nxp.com/products/software-and-tools/hardware-development-tools/sabre-development-system/sabre-board-for-smart-devices-based-on-the-i.mx-6quad-applications-processors:RD-IMX6Q-SABRE) |`PLATFORM=imx`| Yes | 77| [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 | 78| [ARM Foundation FVP](http://www.arm.com/fvp) |`PLATFORM=vexpress-fvp`| Yes | 79| [HiSilicon D02](http://open-estuary.org/d02-2)|`PLATFORM=d02`| No | 80| [HiKey Board (HiSilicon Kirin 620)](https://www.96boards.org/products/hikey)|`PLATFORM=hikey`| Yes | 81| [MediaTek MT8173 EVB Board](http://www.mediatek.com/en/products/mobile-communications/tablet/mt8173)|`PLATFORM=mediatek-mt8173`| No | 82| [QEMU](http://wiki.qemu.org/Main_Page) |`PLATFORM=vexpress-qemu_virt`| Yes | 83| [QEMUv8](http://wiki.qemu.org/Main_Page) |`PLATFORM=vexpress-qemu_armv8a`| Yes | 84| [Raspberry Pi 3](https://www.raspberrypi.org/products/raspberry-pi-3-model-b) |`PLATFORM=rpi3`| Yes | 85| [Renesas RCAR](https://www.renesas.com/en-sg/solutions/automotive/products/rcar-h3.html)|`PLATFORM=rcar`| No | 86| [STMicroelectronics b2260 - h410 (96boards fmt)](http://www.st.com/web/en/catalog/mmc/FM131/SC999/SS1628/PF258776) |`PLATFORM=stm-b2260`| No | 87| [STMicroelectronics b2120 - h310 / h410](http://www.st.com/web/en/catalog/mmc/FM131/SC999/SS1628/PF258776) |`PLATFORM=stm-cannes`| No | 88| [Texas Instruments DRA7xx](http://www.ti.com/product/DRA746)|`PLATFORM=ti-dra7xx`| Yes | 89| [Xilinx Zynq 7000 ZC702](http://www.xilinx.com/products/boards-and-kits/ek-z7-zc702-g.html)|`PLATFORM=zynq7k-zc702`| Yes | 90| [Xilinx Zynq UltraScale+ MPSOC](http://www.xilinx.com/products/silicon-devices/soc/zynq-ultrascale-mpsoc.html)|`PLATFORM=zynqmp-zcu102`| Yes | 91| [Spreadtrum SC9860](http://www.spreadtrum.com/en/SC9860GV.html)|`PLATFORM=sprd-sc9860`| No | 92 93### 3.1 Development board for community user 94For community users, we suggest using [HiKey board](https://www.96boards.org/products/ce/hikey/) 95as development board. It provides detailed documentation including chip 96datasheet, board schematics, source code, binaries etc on the download link at 97the website. 98 99--- 100## 4. Get and build OP-TEE software 101There are a couple of different build options depending on the target you are 102going to use. If you just want to get the software and compile it, then you 103should follow the instructions under the "Basic setup" below. In case you are 104going to run for a certain hardware or FVP, QEMU for example, then please follow 105the respective section found below instead, having that said, we are moving from 106the shell script based setups to instead use 107[repo](https://source.android.com/source/downloading.html), so for some targets 108you will see that we are using repo ([section 5](#5-repo-manifests)) and for 109others we are still using the shell script based setup 110([section 4](#4-get-and-build-op-tee-software)), please see this transitions as 111work in progress. 112 113--- 114### 4.1 Prerequisites 115We believe that you can use any Linux distribution to build OP-TEE, but as 116maintainers of OP-TEE we are mainly using Ubuntu-based distributions and to be 117able to build and run OP-TEE there are a few packages that needs to be installed 118to start with. Therefore install the following packages regardless of what 119target you will use in the end. 120``` 121$ sudo apt-get install android-tools-adb android-tools-fastboot autoconf bc \ 122 bison cscope curl flex gdisk libc6:i386 libfdt-dev libftdi-dev \ 123 libglib2.0-dev libhidapi-dev libncurses5-dev libpixman-1-dev \ 124 libstdc++6:i386 libtool libz1:i386 mtools netcat python-crypto \ 125 python-serial python-wand unzip uuid-dev xdg-utils xz-utils zlib1g-dev 126``` 127 128--- 129### 4.2 Basic setup 130#### 4.2.1 Get the compiler 131We strive to use the latest available compiler from Linaro. Start by downloading 132and unpacking the compiler. Then export the `PATH` to the compilers `bin` 133folder. Beware that we are using a couple of different toolchains depending on 134the target device. This includes both 64- and 32-bit toolchains. For the exact 135toolchain in use, please have a look at [toolchain.mk](https://github.com/OP-TEE/build/blob/master/toolchain.mk) 136and then look at the targets makefile (see [build.git](https://github.com/OP-TEE/build)) 137to find out where the respective toolchain will be used. For example in the 138[QEMU makefile](https://github.com/OP-TEE/build/blob/master/qemu.mk#L6-L9) and 139[common makefile](https://github.com/OP-TEE/build/blob/master/common.mk#L90-L93) 140you will see, respectively: 141``` 142override COMPILE_NS_USER := 32 143override COMPILE_NS_KERNEL := 32 144override COMPILE_S_USER := 32 145override COMPILE_S_KERNEL := 32 146``` 147``` 148CROSS_COMPILE_NS_USER ?= "$(CCACHE)$(AARCH$(COMPILE_NS_USER)_CROSS_COMPILE)" 149CROSS_COMPILE_NS_KERNEL ?= "$(CCACHE)$(AARCH$(COMPILE_NS_KERNEL)_CROSS_COMPILE)" 150CROSS_COMPILE_S_USER ?= "$(CCACHE)$(AARCH$(COMPILE_S_USER)_CROSS_COMPILE)" 151CROSS_COMPILE_S_KERNEL ?= "$(CCACHE)$(AARCH$(COMPILE_S_KERNEL)_CROSS_COMPILE)" 152``` 153 154However, if you only want to compile optee_os, then you can do like this: 155``` 156$ cd $HOME 157$ mkdir toolchains 158$ cd toolchains 159$ wget http://releases.linaro.org/archive/14.08/components/toolchain/binaries/gcc-linaro-arm-linux-gnueabihf-4.9-2014.08_linux.tar.xz 160$ tar xvf gcc-linaro-arm-linux-gnueabihf-4.9-2014.08_linux.tar.xz 161$ export PATH=$HOME/toolchains/gcc-linaro-arm-linux-gnueabihf-4.9-2014.08_linux/bin:$PATH 162``` 163 164#### 4.2.2 Download the source code 165``` 166$ cd $HOME 167$ mkdir devel 168$ cd devel 169$ git clone https://github.com/OP-TEE/optee_os.git 170``` 171 172#### 4.2.3 Build 173``` 174$ cd $HOME/devel/optee_os 175$ CROSS_COMPILE=arm-linux-gnueabihf- make 176``` 177 178#### 4.2.4 Compiler flags 179To be able to see the full command when building you could build using 180following flag: 181``` 182$ make V=1 183``` 184 185To enable debug builds use the following flag: 186``` 187$ make DEBUG=1 188``` 189 190OP-TEE supports a couple of different levels of debug prints for both TEE core 191itself and for the Trusted Applications. The level ranges from 1 to 4, where 192four is the most verbose. To set the level you use the following flag: 193``` 194$ make CFG_TEE_CORE_LOG_LEVEL=4 195``` 196 197--- 198### 4.4 STMicroelectronics boards 199Currently OP-TEE is supported Cannes family (`b2120` both `h310` and `h410` 200chips) and the 96boards/cannes board (`b2260-h410`). 201 202#### 4.4.1 Get the compiler 203Follow the instructions in the "4.2 Basic setup". 204 205#### 4.4.2 Download the source code 206See section "4.2.2 Download the source code". 207 208#### 4.4.3 Build the images and files 209For the 96boards/cannes: 210``` 211$ make PLATFORM=stm-b2260 212``` 213For the legacy cannes family: 214``` 215$ make PLATFORM=stm-cannes 216``` 217 218#### 4.4.4 Prepare, install and run the software 219For 96board/cannes: 220Copy the generated 'optee.bin' on target SD or USB stick and insure the boot 221media boot scripts defines optee and non-secure worlds boot. 222 223More info to come... 224 225--- 226### 4.5 Allwinner A80 227 228#### 4.5.1 Locked versus unlocked A80 boards 229**Important!** All A80 boards sold to the general public are boards where secure 230side has been locked down, which means that you **cannot** use them for secure 231side development, i.e, it will not be possible to put OP-TEE on those devices. 232If you want to use A80 board for secure side development, then you will need to 233talk to 234[Allwinner](https://github.com/OP-TEE/optee_os/blob/master/MAINTAINERS.md) 235directly and ask if it is possible get a device from them. 236 237#### 4.5.2 Get the compiler and source 238Follow the instructions in the "4.2 Basic setup". 239 240#### 4.5.3 Build 241``` 242$ cd optee_os 243$ export PLATFORM=sunxi 244$ export CROSS_COMPILE=arm-linux-gnueabihf- 245$ make 246``` 247 248#### 4.5.4 Prepare the images to run on A80 Board 249 250Download Allwinner A80 platform SDK, the SDK refers to Allwinner A80 platform 251SDK root directory. A80 SDK directory tree looks like this: 252``` 253SDK/ 254 Android 255 lichee 256``` 257`Android` contains all source code related to Android and `lichee` 258contains the bootloader and Linux kernel. 259 260##### 4.5.4.1 Copy OP-TEE output to package directory 261Copy the OP-TEE output binary to `SDK/lichee/tools/pack/sun9i/bin` 262 263``` 264$ cd optee_os 265$ cp ./out/arm32-plat-sunxi/core/tee.bin SDK/lichee/tools/pack/sun9i/bin 266``` 267 268##### 4.5.4.2 Build Linux kernel 269In the `lichee` directory, run the following commands: 270``` 271$ cd SDK/lichee 272$ ./build.sh 273``` 274 275##### 4.5.4.3 Build Android 276In the Android directory, run the following commands: 277``` 278$ cd SDK/android 279$ extract-bsp 280$ make -j 281``` 282 283##### 4.5.4.4 Create the Android image 284In the Android directory, run the following commands: 285``` 286$ cd SDK/android 287$ pack 288``` 289The output image will been signed internally when packed. The output image name 290is `a80_android_board.img`. 291 292##### 4.5.4.5 Download the Android image 293Use `Allwinner PhoenixSuit` tool to download to A80 board. 294Choose the output image(`a80_android_board.img`), select download and wait 295for the download to complete. 296 297#### 4.5.5 Boot and run the software on A80 Board 298When the host platform is Windows, use a console application to connect A80 299board `uart0`. In the console window, You can install OP-TEE linux kernel 300driver `optee.ko`, load OP-TEE-Client daemon `tee-supplicant` and run 301the example "hello world" Trusted Application, do this by running: 302``` 303$ insmod /system/vendor/modules/optee.ko 304$ /system/bin/tee-supplicant & 305$ /system/bin/tee-helloworld 306``` 307 308--- 309### 4.6 Freescale MX6UL EVK 310 311Get U-Boot source: 312https://github.com/MrVan/uboot/commit/4f016adae573aaadd7bf6a37f8c58a882b391ae6 313 314Build U-Boot: 315``` 316 make ARCH=arm mx6ul_14x14_evk_optee_defconfig 317 make ARCH=arm 318 Burn u-boot.imx to offset 0x400 of SD card 319``` 320 321Get Kernel source: https://github.com/linaro-swg/linux/tree/optee 322 323Patch kernel: 324```c 325 diff --git a/arch/arm/boot/dts/imx6ul-14x14-evk.dts b/arch/arm/boot/dts/imx6ul-14x14-evk.dts 326 index 6aaa5ec..2ac9c80 100644 327 --- a/arch/arm/boot/dts/imx6ul-14x14-evk.dts 328 +++ b/arch/arm/boot/dts/imx6ul-14x14-evk.dts 329 @@ -23,6 +23,13 @@ 330 reg = <0x80000000 0x20000000>; 331 }; 332 333 + firmware { 334 + optee { 335 + compatible = "linaro,optee-tz"; 336 + method = "smc"; 337 + }; 338 + }; 339 + 340 regulators { 341 compatible = "simple-bus"; 342 #address-cells = <1>; 343``` 344 345Compile the Kernel: 346 347``` 348make ARCH=arm imx_v6_v7_defconfig 349make menuconfig 350select the two entries 351 CONFIG_TEE=y 352 CONFIG_OPTEE 353make ARCH=arm 354``` 355Copy zImage and imx6ul_14x14_evk.dtb to SD card. 356 357OPTEE OS Build: 358``` 359 PLATFORM_FLAVOR=mx6ulevk make PLATFORM=imx 360 ${CROSS_COMPILE}-objcopy -O binary out/arm-plat-imx/core/tee.elf optee.bin 361 copy optee.bin to the first partition of SD card which is used for boot. 362``` 363 364Run using U-Boot: 365``` 366 run loadfdt; 367 run loadimage; 368 fatload mmc 1:1 0x9c100000 optee.bin; 369 run mmcargs; 370 bootz ${loadaddr} - ${fdt_addr}; 371``` 372 373Note: 374 CAAM is not implemented now, this will be added later. 375 376More steps: http://mrvan.github.io/optee-imx6ul 377 378--- 379## 5. repo manifests 380 381A Git repository is available at https://github.com/OP-TEE/manifest where you 382will find XML-files for use with the Android 'repo' tool. 383 384### 5.1. Install repo 385Follow the instructions under the "Installing Repo" section 386[here](https://source.android.com/source/downloading.html). 387 388### 5.2. Get the source code 389First ensure that you have the necessary Ubuntu packages installed, see [4.1 390Prerequisites](#41-prerequisites) (this is the only important step from section 3914 in case you are setting up any of the target devices mentioned below). 392 393``` 394$ mkdir -p $HOME/devel/optee 395$ cd $HOME/devel/optee 396$ repo init -u https://github.com/OP-TEE/manifest.git -m ${TARGET}.xml [-b ${BRANCH}] 397$ repo sync 398``` 399**Notes**<br> 400* The folder could be at any location, we are just giving a suggestion by 401 saying `$HOME/devel/optee`. 402* `repo sync` can take an additional parameter -j to sync multiple remotes. For 403 example `repo sync -j3` will sync three remotes in parallel. 404 405#### 5.2.1 Targets 406| Target | Latest | Stable | 407|--------|--------|--------| 408| QEMU | `default.xml` | `default_stable.xml` | 409| QEMUv8 | `qemu_v8.xml` | `qemu_v8_stable.xml` | 410| FVP | `fvp.xml` | `fvp_stable.xml` | 411| HiKey | `hikey.xml` | `hikey_stable.xml` | 412| HiKey Debian | `hikey_debian.xml` | `hikey_debian_stable.xml` | 413| MediaTek MT8173 EVB Board | `mt8173-evb.xml` | `mt8173-evb_stable.xml` | 414| ARM Juno board| `juno.xml` | `juno_stable.xml` | 415| Raspberry Pi 3 | `rpi3.xml` | `rpi3_stable.xml` | 416 417#### 5.2.2 Branches 418Currently we are only using one branch, i.e, the `master` branch. 419 420#### 5.2.3 Get the toolchains 421This is a one time thing you run only once after getting all the source code 422using repo. 423``` 424$ cd build 425$ make toolchains 426``` 427 428##### Note : 429If you have been using GCC4.9 and are upgrading to GCC5 via [this commit] (https://github.com/OP-TEE/build/commit/69a8a37bc417d28d62ae57e7ca2a8df4bdec93c8), please make sure that you delete the `toolchains` directory before running `make toolchains` again, or else the toolchain binaries can get mixed up or corrupted, and generate errors during builds. 430 431--- 432### 5.3. QEMU 433After getting the source and toolchain, just run (from the `build` folder) 434``` 435$ make all run 436``` 437and everything should compile and at the end QEMU should start. 438 439--- 440### 5.4. FVP 441After getting the source and toolchain you must also obtain Foundation Model 442([link](http://www.arm.com/products/tools/models/fast-models/foundation-model.php)) 443binaries and untar it to the forest root, then just run (from the `build` folder) 444 445``` 446$ make all run 447``` 448and everything should compile and at the end FVP should start. 449 450--- 451### 5.5. HiKey 452#### 5.5.1 Initramfs based 453After getting the source and toolchain, just run (from the `build` folder) 454``` 455$ make all 456``` 457 458After that connect the board and flash the binaries by running: 459``` 460$ make flash 461``` 462 463(more information about how to flash individual binaries could be found 464[here](https://github.com/96boards/documentation/wiki/HiKeyUEFI#flash-binaries-to-emmc-)) 465 466The board is ready to be booted. 467#### 5.5.2 Debian based / 96boards RPB 468Start by getting the source and toolchain (see above), then continue by 469downloading the system image (root fs). Note that this step is something you 470only should do once. 471 472``` 473$ make system-img 474``` 475 476Which should be followed by 477``` 478$ make all 479``` 480 481When everything has been built, flash the files to the device: 482``` 483$ make flash 484``` 485 486Now you can boot up the device, note that OP-TEE normal world binaries still 487hasn't been put on the device at this stage. So by now you're basically booting 488up an RPB build. When you have a prompt, the next step is to connect the device 489to the network. WiFi is preferable, since HiKey has no Ethernet jack. Easiest is 490to edit `/etc/network/interfaces`. To find out what to add, run: 491``` 492$ make help 493``` 494 495When that's been added, reboot and when you have a prompt again, you're ready to 496push the OP-TEE client binaries and the kernel with OP-TEE support. First find 497out the IP for your device (`ifconfig`). Then send the files to HiKey by 498running: 499``` 500$ IP=111.222.333.444 make send 501 502Credentials for the image are: 503username: linaro 504password: linaro 505``` 506 507When the files has been transfered, please follow the commands from the `make 508send` command which will install the debian packages on the device. Typically it 509tells you to run something like this on the device itself: 510``` 511$ dpkg --force-all -i /tmp/out/optee_2.0-1.deb 512$ dpkg --force-all -i /tmp/linux-image-*.deb 513``` 514 515Now you are ready to use OP-TEE on HiKey using Debian, please goto step 6 below 516to continue. 517 518##### Good to know 519Just want to update secure side? Put the device in fastboot mode and 520``` 521$ make arm-tf 522$ make flash-fip 523 524``` 525 526Just want to update OP-TEE client software? Put the device in fastboot mode and 527``` 528$ make optee-client 529$ make xtest 530``` 531 532Boot up the device and follow the instructions from make send 533``` 534$ IP=111.222.333.444 make send 535``` 536 537--- 538### 5.6. MT8173-EVB 539After getting the source and toolchain, just run (from the `build` folder) 540 541``` 542$ make all run 543``` 544 545When `< waiting for device >` prompt appears, press reset button and the 546flashing procedure should begin. 547 548--- 549### 5.7 Juno 550After getting the source and toolchain, just run (from the `build` folder) 551``` 552$ make all 553``` 554 555Enter the firmware console on the juno board and press enter to stop 556the auto boot flow 557``` 558ARM V2M_Juno Firmware v1.3.9 559Build Date: Nov 11 2015 560 561Time : 12:50:45 562Date : 29:03:2016 563 564Press Enter to stop auto boot... 565 566``` 567Enable ftp at the firmware prompt 568``` 569Cmd> ftp_on 570Enabling ftp server... 571 MAC address: xxxxxxxxxxxx 572 573 IP address: 192.168.1.158 574 575 Local host name = V2M-JUNO-A2 576``` 577 578Flash the binary by running (note the IP address from above): 579``` 580make JUNO_IP=192.168.1.158 flash 581``` 582 583Once the binaries are transferred, reboot the board: 584``` 585Cmd> reboot 586 587``` 588 589#### 5.7.1 Update flash and its layout 590The flash in the board may need to be updated for the flashing above to 591work. If the flashing fails or if ARM-TF refuses to boot due to wrong 592version of the SCP binary the flash needs to be updated. To update the 593flash please follow the instructions at [Using Linaro's deliverable on 594Juno](https://community.arm.com/docs/DOC-10804) selecting one of the zips 595under "4.1 Prebuilt configurations" flashing it as described under "5. 596Running the software". 597 598#### 5.7.2 GlobalPlatform testsuite support 599##### Warning : 600Depending on the Juno pre-built configuration, the built ramdisk.img 601size with GlobalPlatform testsuite may exceed its pre-defined Juno flash 602memory reserved location (image.txt file). 603In that case, you will need to extend the Juno flash block size reserved 604location for the ramdisk.img in the image.txt file accordingly and 605follow the instructions under "5.7.1 Update flash and its layout". 606 607##### Example with juno-latest-busybox-uboot.zip: 608The current ramdisk.img size with GlobalPlatform testsuite 609is 8.6 MBytes. 610 611###### Updated file is /JUNO/SITE1/HBI0262B/images.txt (limited to 8.3 MB) 612``` 613NOR4UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE 614NOR4ADDRESS: 0x01800000 ;Image Flash Address 615NOR4FILE: \SOFTWARE\ramdisk.img ;Image File Name 616NOR4NAME: ramdisk.img 617NOR4LOAD: 00000000 ;Image Load Address 618NOR4ENTRY: 00000000 ;Image Entry Point 619``` 620 621###### Extended to 16MB 622``` 623NOR4UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE 624NOR4ADDRESS: 0x01000000 ;Image Flash Address 625NOR4FILE: \SOFTWARE\ramdisk.img ;Image File Name 626NOR4NAME: ramdisk.img 627NOR4LOAD: 00000000 ;Image Load Address 628NOR4ENTRY: 00000000 ;Image Entry Point 629``` 630 631#### 5.7.3 GCC5 support 632##### Note : 633In case you are using the **Latest version** of the ARM Juno board (this is 634`juno.xml` manifest), the built `ramdisk.img` size with GCC5 compiler, at 635the moment, exceeds its pre-defined Juno flash memory reserved location 636(`image.txt` file). 637 638To solve this problem you will need to extend the Juno flash block size 639reserved location for the `ramdisk.img` and decrease the size for other 640images in the `image.txt` file accordingly and then follow the instructions 641under "5.7.1 Update flash and its layout". 642 643##### Example with juno-latest-busybox-uboot.zip: 644The current `ramdisk.img` size with GCC5 compiler is 29.15 MBytes we will 645extend it to 32 MBytes. The only changes that you need to do are those in 646**bold** 647 648###### File to update is /JUNO/SITE1/HBI0262B/images.txt 649<pre> 650NOR2UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE 651NOR2ADDRESS: <b>0x00100000</b> ;Image Flash Address 652NOR2FILE: \SOFTWARE\Image ;Image File Name 653NOR2NAME: norkern ;Rename kernel to norkern 654NOR2LOAD: 00000000 ;Image Load Address 655NOR2ENTRY: 00000000 ;Image Entry Point 656 657NOR3UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE 658NOR3ADDRESS: <b>0x02C00000</b> ;Image Flash Address 659NOR3FILE: \SOFTWARE\juno.dtb ;Image File Name 660NOR3NAME: board.dtb ;Specify target filename to preserve file extension 661NOR3LOAD: 00000000 ;Image Load Address 662NOR3ENTRY: 00000000 ;Image Entry Point 663 664NOR4UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE 665NOR4ADDRESS: <b>0x00D00000</b> ;Image Flash Address 666NOR4FILE: \SOFTWARE\ramdisk.img ;Image File Name 667NOR4NAME: ramdisk.img 668NOR4LOAD: 00000000 ;Image Load Address 669NOR4ENTRY: 00000000 ;Image Entry Point 670 671NOR5UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE 672NOR5ADDRESS: <b>0x02D00000</b> ;Image Flash Address 673NOR5FILE: \SOFTWARE\hdlcdclk.dat ;Image File Name 674NOR5LOAD: 00000000 ;Image Load Address 675NOR5ENTRY: 00000000 ;Image Entry Point 676</pre> 677 678--- 679### 5.8 Raspberry Pi 3 680There is a separate document for Raspberry Pi 3 [here](documentation/rpi3.md). 681That document will tell you how to flash, how to debug, known problems and 682things still to be done. 683 684--- 685### 5.9 Tips and tricks 686#### 5.9.1 Reference existing project to speed up repo sync 687Doing a `repo init`, `repo sync` from scratch can take a fair amount of time. 688The main reason for that is simply because of the size of some of the gits we 689are using, like for the Linux kernel and EDK2. With repo you can reference an 690existing forest and by doing so you can speed up repo sync to instead taking ~20 691seconds instead of an hour. The way to do this are as follows. 692 6931. Start by setup a clean forest that you will not touch, in this example, let 694 us call that `optee-ref` and put that under for `$HOME/devel/optee-ref`. This 695 step will take roughly an hour. 6962. Then setup a cronjob (`crontab -e`) that does a `repo sync` in this folder 697 particular folder once a night (that is more than enough). 6983. Now you should setup your actual tree which you are going to use as your 699 working tree. The way to do this is almost the same as stated in the 700 instructions above, the only difference is that you reference the other local 701 forest when running `repo init`, like this 702 ``` 703 repo init -u https://github.com/OP-TEE/manifest.git --reference /home/jbech/devel/optee-ref 704 ``` 7054. The rest is the same above, but now it will only take a couple of seconds to 706 clone a forest. 707 708Normally step 1 and 2 above is something you will only do once. Also if you 709ignore step 2, then you will still get the latest from official git trees, since 710repo will also check for updates that aren't at the local reference. 711 712#### 5.9.2. Use ccache 713ccache is a tool that caches build object-files etc locally on the disc and can 714speed up build time significantly in subsequent builds. On Debian-based systems 715(Ubuntu, Mint etc) you simply install it by running: 716``` 717$ sudo apt-get install ccache 718``` 719 720The helper makefiles are configured to automatically find and use ccache if 721ccache is installed on your system, so other than having it installed you don't 722have to think about anything. 723 724#### 5.9.3 Host-Guest folder sharing in QEMU/QEMUv8 configurations 725To avoid changing rootfs CPIO archive each time you need to add additional 726files to it, you can also use VirtFS QEMU feature to share a folder between 727the guest and host operating systems. To use this feature enable VirtFS 728QEMU build in `build/common.mk` (set `QEMU_VIRTFS_ENABLE ?= y`), adjust 729`QEMU_VIRTFS_HOST_DIR` and rebuild QEMU. 730 731To mount host folder in QEMU, simply run: 732``` 733$ mount_shared <mount_point> 734``` 735--- 736## 6. Load driver, tee-supplicant and run xtest 737Since release v2.0.0 you don't have to load the kernel driver explicitly. In the 738standard configuration it will be built into the kernel directly. To actually 739run something on a device you however need to run tee-supplicant. This is the 740same for all platforms, so when a device has booted, then run 741``` 742$ tee-supplicant & 743``` 744and OP-TEE is ready to be used. 745 746In case you want to try run something that triggers both normal and secure side 747code you could run xtest (the main test suite for OP-TEE), run 748``` 749$ xtest 750``` 751 752--- 753## 7. Coding standards 754In this project we are trying to adhere to the same coding convention as used in 755the Linux kernel (see 756[CodingStyle](https://www.kernel.org/doc/Documentation/CodingStyle)). We achieve this by running 757[checkpatch](http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/scripts/checkpatch.pl) 758from Linux kernel. However there are a few exceptions that we had to make since 759the code also follows GlobalPlatform standards. The exceptions are as follows: 760 761- CamelCase for GlobalPlatform types are allowed. 762- And we also exclude checking third party code that we might use in this 763 project, such as LibTomCrypt, MPA, newlib (not in this particular git, but 764 those are also part of the complete TEE solution). The reason for excluding 765 and not fixing third party code is because we would probably deviate too much 766 from upstream and therefore it would be hard to rebase against those projects 767 later on (and we don't expect that it is easy to convince other software 768 projects to change coding style). 769 770### 7.1 checkpatch 771Since checkpatch is licensed under the terms of GNU GPL License Version 2, we 772cannot include this script directly into this project. Therefore we have 773written the Makefile so you need to explicitly point to the script by exporting 774an environment variable, namely CHECKPATCH. So, suppose that the source code for 775the Linux kernel is at `$HOME/devel/linux`, then you have to export like follows: 776 777 $ export CHECKPATCH=$HOME/devel/linux/scripts/checkpatch.pl 778thereafter it should be possible to use one of the different checkpatch targets 779in the [Makefile](Makefile). There are targets for checking all files, checking 780against latest commit, against a certain base-commit etc. For the details, read 781the [Makefile](Makefile). 782