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