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