Initial commit for the official OP-TEE documentation
This initial commit brings in all existing documentation found across
various gits making up the documentation for the OP-TEE project. So in
summary what this includes and what has been done is:
- Import all old documentation (optee_os, optee_client, optee_test and
so on).
- Convert everything from markdown (*.md) to reStructuredText (*.rst).
- Add a couple of new pages (optee_docs, disclosure policy to name a
few).
- Add Sphinx configuration.
- Add Travis configuration to enable automatic testing of future
documentation patches.
- Finally, a general clean-up and verification of content,
links as well as verification of build instructions etc has also been
done.
diff --git a/building/aosp/aosp.rst b/building/aosp/aosp.rst
new file mode 100644
index 0000000..a43e551
--- /dev/null
+++ b/building/aosp/aosp.rst
@@ -0,0 +1,208 @@
+.. todo::
+
+ Joakim: Technically this would belong under "gits". But I think it is more
+ visible to have it directly under "AOSP" under "Build and run".
+
+.. _aosp:
+
+####
+AOSP
+####
+This page contains information that tells how to get OP-TEE up and running on
+HiKey devices (see :ref:`hikey`, :ref:`hikey960`) together with AOSP. The build
+is based on the latest OP-TEE release and updated every quarter together with
+the regular OP-TEE releases.
+
+.. note::
+
+ We **only** use and support this static/stable configuration. If you try
+ using it with latest available AOSP, there is a risk that both OP-TEE and
+ other parts are not working as expected.
+
+As a reference, there are official instructions for HiKey builds at Google
+pages, see `AOSP Hikey build instructions`_.
+
+Prerequisites
+*************
+
+ - You should already be able to build AOSP according to the official
+ instructions. Distro should have necessary packages installed, and the repo
+ tool should be installed. Note that AOSP needs to be built with Java.
+ Also make sure that the ``mtools`` package is installed, which is needed
+ to make the hikey boot image.
+
+ - In addition, you will need the pre-requisites necessary to build
+ optee-os.
+
+After following the AOSP setup instructions, the following additional packages
+are needed.
+
+.. todo::
+
+ Joakim: How much does this really differ from the "global" prerequisites.
+ Could we instead refer to the global as the "main" prerequisites and then
+ just list the delta here?
+
+.. code-block:: bash
+
+ $ sudo apt-get install android-tools-adb android-tools-fastboot autoconf \
+ automake bc bison build-essential cscope curl device-tree-compiler flex \
+ ftp-upload gdisk iasl libattr1-dev libc6:i386 libcap-dev libfdt-dev \
+ libftdi-dev libglib2.0-dev libhidapi-dev libncurses5-dev \
+ libpixman-1-dev libssl-dev libstdc++6:i386 libtool libz1:i386 make \
+ mtools netcat python-crypto python-serial python-wand unzip uuid-dev \
+ xdg-utils xterm xz-utils zlib1g-dev python-mako openjdk-8-jdk \
+ ncurses-dev realpath android-tools-fsutils dosfstools libxml2-utils
+
+Build instructions
+******************
+
+.. code-block:: bash
+
+ $ git clone https://github.com/linaro-swg/optee_android_manifest
+ $ cd optee_android_manifest
+
+
+HiKey620 - LeMaker 8GB
+ .. code-block:: bash
+
+ $ ./sync-p.sh
+ $ ./build-p.sh
+
+HiKey620 - CircuitCo 4GB
+ .. code-block:: bash
+
+ $ ./sync-p.sh
+ $ ./build.sh -v p -4g
+
+HiKey960
+ .. code-block:: bash
+
+ $ ./sync-p-hikey960.sh
+ $ ./build-p-hikey960.sh
+
+These steps should (must) finish with no errors. In case there are errors, then
+there is no need trying to flash the device.
+
+.. warning::
+
+ - ``--force-sync`` is used which means you might **lose your work** so save
+ often, save frequent, and save accordingly, especially before running
+ ``sync-p.sh`` again!
+
+ - **Attention!** Do **NOT** use ``git clean`` with ``-x`` or ``-X`` or
+ ``-e`` option in ``optee_android_manifest/``, else risk **losing all
+ files** in the directory!!!
+
+.. hint::
+
+ You can add the ``-squashfs`` option to ``build.sh`` option to make
+ ``system.img`` size smaller, but this will make ``/system`` read-only, so
+ you won't be able to push files to it.
+
+For older releases (other versions of relatively stable builds), use
+below instead of ``./sync-p.sh``.
+
+.. code-block:: bash
+
+ $ ./wrappers/sync.sh -v p -t <hikey|hikey960> \
+ -bm <name of a pinned manifest file in archive/> \
+ 2>&1 |tee logs/sync-p.log
+
+E.g.
+ .. code-block:: bash
+
+ $ ./wrappers/sync.sh -v p -t hikey \
+ -bm pinned-manifest-stable_yvr18.xml \
+ 2>&1 |tee logs/sync-p.log
+
+Other existing files are for internal development purposes ONLY and
+**NOT SUPPORTED**!
+
+Flashing the image
+******************
+The instructions for flashing the image can be found in detail under
+``device/linaro/hikey/installer/hikey{960}/README`` in the tree.
+
+ 1. Set jumpers/switches ``1-2`` and ``3-4``, and unset ``5-6``.
+ 2. Reset the board. After that, invoke:
+
+HiKey620
+ .. code-block:: bash
+
+ $ cp -a out/target/product/hikey/*.img device/linaro/hikey/installer/hikey/
+ $ sudo ./device/linaro/hikey/installer/hikey/flash-all.sh /dev/ttyUSBn
+
+HiKey960
+ .. code-block:: bash
+
+ $ cp -a out/target/product/hikey960/*.img device/linaro/hikey/installer/hikey960/
+ $ sudo ./device/linaro/hikey/installer/hikey960/flash-all.sh /dev/ttyUSBn
+
+where the ``/dev/ttyUSBn`` device is the one that appears after rebooting with
+the 3-4 jumper installed. Note that the device only remains in this recovery
+mode for about 90 seconds. If you take too long to run the flash commands, it
+will need to be reset again.
+
+Partial flashing
+****************
+The last handful of lines in the ``flash-all.sh`` script flash various images.
+After modifying and rebuilding Android, it is only necessary to flash `boot`,
+`system`, `cache`, `vendor` and `userdata`. If you aren't modifying the kernel,
+`boot` is not necessary, either.
+
+Experimental prebuilts
+**********************
+Available at http://snapshots.linaro.org/android under ``android-hikey*``
+directories.
+
+Running xtest
+*************
+Do NOT try to run ``tee-supplicant`` as it has already been started
+automatically as a service! Once booted to the command prompt, ``xtest`` can be
+run immediately from an ``adb`` shell. For more details about running OP-TEE,
+please see :ref:`optee_test_run_xtest` at :ref:`optee_test`.
+
+.. note::
+
+ If running from the console shell, run ``su shell,shell,inet xtest``
+ instead. This is due to the console ``shell`` user not belonging to the
+ ``inet`` group by default. We're looking into improving this limitation, and
+ contributions are welcome!
+
+Running VTS Gtest unit for Gatekeeper and Keymaster (Optional)
+**************************************************************
+On the device after going into the command prompt, run:
+
+.. code-block:: bash
+
+ $ su system
+ $ ./data/nativetest64/VtsHalGatekeeperV1_0TargetTest/VtsHalGatekeeperV1_0TargetTest
+ $ ./data/nativetest64/VtsHalKeymasterV3_0TargetTest/VtsHalKeymasterV3_0TargetTest
+
+.. note::
+
+ These tests need to be run as the ``system`` user.
+
+Enable adb over USB
+*******************
+
+Boot the device. On serial console:
+
+.. code-block:: bash
+
+ $ su setprop sys.usb.configfs 1
+ $ stop adbd
+ $ start adbd
+
+Known issues
+************
+Adb over USB currently doesn't work on HiKey960. As a workaround, use adb over
+tcpip. See https://bugs.96boards.org/show_bug.cgi?id=502 for details on how to
+connect. There are still some limitations however. E.g. running ``adb shell`` or
+a second ``adb`` instance will break the current adb tcpip connection. This
+might be due to unstable WiFi (there are periodic error messages like ``wlcore:
+WARNING corrupted packet in RX: status: 0x1 len: 76``) or just incompleteness of
+the generic HiKey960 builds under P.
+
+.. _AOSP Hikey build instructions: https://source.android.com/source/devices.html
diff --git a/building/devices/fvp.rst b/building/devices/fvp.rst
new file mode 100644
index 0000000..bc3c466
--- /dev/null
+++ b/building/devices/fvp.rst
@@ -0,0 +1,55 @@
+.. _fvp:
+
+###
+FVP
+###
+The instructions here will tell how to build and run OP-TEE using Foundation
+Models.
+
+
+.. _fvp_build_instructions:
+
+Build instructions
+******************
+Start out by following the ":ref:`get_and_build_the_solution`" as described in
+:ref:`build`. However, stop before doing ":ref:`build_make`".
+
+Next you should obtain the `Armv8-A Foundation Platform (For Linux Hosts
+Only)`_. To download FVPs you’ll need to log in to Arm Self Service. That binary
+should be untar'ed to the root of the repo forest, i.e., like this:
+``<fpv-project>/Foundation_Platformpkg``. In the end after cloning all source
+code, getting the toolchains and "installing" Foundation_Platformpkg you should
+have a folder structure that looks like this:
+
+.. code-block:: none
+ :emphasize-lines: 9
+
+ $ ls -al
+ drwxrwxr-x 15 jbech jbech 4096 Feb 5 09:10 .
+ drwxr-xr-x 22 jbech jbech 4096 Jan 15 12:45 ..
+ drwxrwxr-x 18 jbech jbech 4096 Feb 5 09:10 arm-trusted-firmware
+ drwxrwxr-x 9 jbech jbech 4096 Feb 5 09:10 build
+ drwxrwxr-x 15 jbech jbech 4096 Feb 5 09:10 buildroot
+ drwxrwxr-x 51 jbech jbech 4096 Feb 5 09:10 edk2
+ drwxrwxr-x 5 jbech jbech 4096 Feb 5 09:10 edk2-platforms
+ drwxrwxr-x 6 jbech jbech 4096 Mar 15 2018 Foundation_Platformpkg
+ drwxrwxr-x 15 jbech jbech 4096 Feb 5 09:10 grub
+ drwxrwxr-x 26 jbech jbech 4096 Feb 5 09:10 linux
+ drwxrwxr-x 6 jbech jbech 4096 Feb 5 09:10 optee_client
+ drwxrwxr-x 10 jbech jbech 4096 Feb 5 09:10 optee_examples
+ drwxrwxr-x 11 jbech jbech 4096 Feb 5 09:10 optee_os
+ drwxrwxr-x 8 jbech jbech 4096 Feb 5 09:10 optee_test
+ drwxrwxr-x 7 jbech jbech 4096 Feb 5 09:10 .repo
+ lrwxrwxrwx 1 jbech jbech 23 Feb 5 09:09 toolchains
+
+When this pre-condition met you can simply continue with
+
+.. code-block:: bash
+
+ $ make run
+
+and then FVP should build the rootfs and then start the simulation and when you
+have a terminal you can log in and run xtest (as described at
+:ref:`build_run_xtest`).
+
+.. _Armv8-A Foundation Platform (For Linux Hosts Only): https://developer.arm.com/products/system-design/fixed-virtual-platforms
diff --git a/building/devices/hikey620.rst b/building/devices/hikey620.rst
new file mode 100644
index 0000000..46fc095
--- /dev/null
+++ b/building/devices/hikey620.rst
@@ -0,0 +1,82 @@
+.. _hikey:
+
+#########
+HiKey 620
+#########
+The instructions here will tell how to run OP-TEE on `HiKey 620`_.
+
+Multiple sources for HiKey and OP-TEE instructions?
+***************************************************
+First you must understand that the HiKey project as such is led by the 96Boards
+project. So, if you **aren't** interested in running OP-TEE on the device, then
+you should stop reading here and instead have a look at the `official HiKey
+documentation`_.
+
+For OP-TEE using HiKey you will still find information in more than one place.
+There are a couple of reasons for that.
+
+* **96Boards**: The official 96Boards project used to host some OP-TEE
+ instructions and they include OP-TEE in their official releases.
+
+* **Google**: has an `AOSP HiKey branch`_, where OP-TEE is supported to some
+ extent.
+
+* **Linaro-SWG**: The OP-TEE team has done some work related to AOSP (see the
+ :ref:`AOSP` page) and there HiKey has been one of the devices in use.
+
+If you have questions regarding the configurations above, please reach out to
+the people on the right forum (96Boards, Google and Linaro-SWG).
+
+This particular guide is maintained by the OP-TEE `core team`_ and this is what
+we use when we are doing are stable releases for our OP-TEE developer builds.
+I.e, for OP-TEE this should be considered as a well maintained guide with a
+fully working setup.
+
+Supported HiKey boards
+**********************
+There are four different versions of the HiKey board.
+
+ +-------+--------------+--------+-------+-------------------+
+ | Name | Manufacturer | Memory | Flash | Comment |
+ +=======+==============+========+=======+===================+
+ | HiKey | CircuitCo | 1GB | 4GB | Green solder mask |
+ +-------+--------------+--------+-------+-------------------+
+ | HiKey | LeMaker | 1GB | 8GB | Black solder mask |
+ +-------+--------------+--------+-------+-------------------+
+ | HiKey | LeMaker | 2GB | 8GB | Black solder mask |
+ +-------+--------------+--------+-------+-------------------+
+
+All of them works, but where differences apply we have default configurations
+that works for the LeMaker 8GB eMMC versions.
+
+UART adapter board
+******************
+Everything is configured to use the `96Boards UART Adapter Board`_. The UART is
+by default configured to ``UART3``. If you don't have any UART adapter board and
+instead would like to use ``UART0``, then you need to change that before
+building. See ``CFG_NW_CONSOLE_UART`` and ``CFG_NW_CONSOLE_UART`` in
+`hikey.mk`_.
+
+Build instructions
+******************
+Just follow the ":ref:`get_and_build_the_solution`" as described in
+:ref:`build`. The ``make flash`` step will tell you how you should set the
+jumpers on the board.
+
+Recovery
+********
+If you manage to corrupt the device, so that fastboot doesn't load automatically
+on boot, then you will need to run the recovery procedure. Basically what you
+will need to do is use another make target and change some jumpers. All that is
+described when you run the target:
+
+.. code-block:: bash
+
+ $ make recovery
+
+.. _96Boards UART Adapter Board: http://www.96boards.org/product/uarts
+.. _AOSP HiKey branch: https://source.android.com/setup/build/devices#620hikey
+.. _core team: https://github.com/orgs/OP-TEE/teams/linaro/members
+.. _HiKey 620: https://www.96boards.org/product/hikey/
+.. _hikey.mk: https://github.com/OP-TEE/build/blob/master/hikey.mk
+.. _official HiKey documentation: http://www.96boards.org/documentation/ConsumerEdition/HiKey/README.md
diff --git a/building/devices/hikey960.rst b/building/devices/hikey960.rst
new file mode 100644
index 0000000..ebc47b1
--- /dev/null
+++ b/building/devices/hikey960.rst
@@ -0,0 +1,50 @@
+.. _hikey960:
+
+#########
+HiKey 960
+#########
+
+The instructions here will tell how to run OP-TEE on `HiKey 960`_.
+
+Supported HiKey960 boards
+*************************
+There are two different versions of the HiKey960 board.
+
++----------+--------------------+--------+-------+-------------------------------+
+| Name | Manufacturer | Memory | Flash | Comment |
++==========+====================+========+=======+===============================+
+| HiKey960 | Archermind/LeMaker | 3GB | 32GB | v2 uses DIP Switches (SW2201) |
++----------+--------------------+--------+-------+-------------------------------+
+| HiKey960 | Archermind/LeMaker | 3GB | 32GB | v1 uses Jumpers (J2001) |
++----------+--------------------+--------+-------+-------------------------------+
+
+UART adapter board
+******************
+Everything is configured to use the 96Boards `UART Serial`_ adapter. The UART is
+by default configured to UART6. If you have a v1 board and need to use UART5,
+then you need to change that before building. See ``CFG_CONSOLE_UART`` in
+`hikey960.mk`_.
+
+Build instructions
+******************
+Just follow the instructions at ":ref:`get_and_build_the_solution`". If ``make
+flash`` doesn't work, try ``make recovery``.
+
+Recovery
+********
+If you manage to corrupt the device, such that fastboot doesn't load
+automatically on boot, then you will need to run the recovery procedure.
+Basically what you will need to do is use another make target and change some
+jumpers. All that is described when you run the target:
+
+External guide
+**************
+https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/plat/hikey960.rst
+
+.. code-block:: bash
+
+ $ make recovery
+
+.. _HiKey 960: https://www.96boards.org/product/hikey960/
+.. _hikey960.mk: https://github.com/OP-TEE/build/blob/master/hikey960.mk
+.. _UART Serial: https://www.96boards.org/product/uartserial/
diff --git a/building/devices/index.rst b/building/devices/index.rst
new file mode 100644
index 0000000..60d55c8
--- /dev/null
+++ b/building/devices/index.rst
@@ -0,0 +1,17 @@
+.. _device_specific:
+
+###########################
+Device specific information
+###########################
+
+.. toctree::
+ :maxdepth: 1
+
+ fvp
+ hikey620
+ hikey960
+ juno
+ qemu
+ rpi3
+ ti
+
diff --git a/building/devices/juno.rst b/building/devices/juno.rst
new file mode 100644
index 0000000..a28138c
--- /dev/null
+++ b/building/devices/juno.rst
@@ -0,0 +1,162 @@
+.. _juno:
+
+####
+Juno
+####
+The instructions here will tell how to run OP-TEE on the Juno board. The
+instructions has been tested and verified on the ``Juno r0`` revision (see `Juno
+revisions`_ for more details).
+
+Regular build
+*************
+First step is to start out by following the instructions in the
+:ref:`get_and_build_the_solution` as described in :ref:`build`.
+
+Deploy files on the device
+**************************
+Enter the firmware console on the Juno board and press **enter** to stop the
+auto boot.
+
+.. code-block:: bash
+
+ ARM V2M_Juno Firmware v1.3.9
+ Build Date: Nov 11 2015
+
+ Time : 12:50:45
+ Date : 29:03:2016
+
+ Press Enter to stop auto boot...
+
+Enable ``FTP`` at the firmware prompt.
+
+.. code-block:: bash
+
+ Cmd> ftp_on
+ Enabling ftp server...
+ MAC address: xxxxxxxxxxxx
+
+ IP address: 192.168.1.158
+
+ Local host name = V2M-JUNO-A2
+
+Flash the binary by running
+
+.. note::
+ Use the **IP address** from output from previous command.
+
+.. code-block:: bash
+
+ $ make JUNO_IP=192.168.1.158 flash
+
+Once all binaries have been transferred, reboot the board:
+
+.. code-block:: bash
+
+ Cmd> reboot
+
+Update the flash layout
+***********************
+The flash layout for Juno may need to be updated for the flashing above to work.
+If flashing fails or if TF-A refuses to boot due to wrong version of the ``SCP``
+binary, then the flash(-layout) needs to be updated. To update the flash please
+follow the instructions at Arm's `old release notes`_ page selecting one of the
+zips under "Development boards / Juno / Prebuilt configurations" and flash it as
+described at `Run the Arm Platforms deliverables on Juno`_.
+
+GlobalPlatform testsuite support
+********************************
+.. note::
+
+ Depending on the Juno pre-built configuration, the built ``ramdisk.img`` size
+ with GlobalPlatform testsuite may exceed its pre-defined Juno flash memory
+ reserved location (``image.txt`` file). In that case, you will need to extend
+ the Juno flash block size reserved location for the ``ramdisk.img`` in the
+ ``image.txt`` file accordingly and follow the instructions under "5.7.1 Update
+ flash and its layout".
+
+Example
+=======
+Example with ``juno-latest-busybox-uboot.zip``. The current ``ramdisk.img`` size
+with GlobalPlatform testsuite is 8.6 MBytes and that is too big to fit in the
+default configuration, therefore we need to make adjustments to the flash
+layout. You will do that by making changes to
+``/JUNO/SITE1/HBI0262B/images.txt``. I.e., from:
+
+.. code-block:: none
+ :emphasize-lines: 2
+ :linenos:
+
+ NOR4UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE
+ NOR4ADDRESS: 0x01800000 ;Image Flash Address
+ NOR4FILE: \SOFTWARE\ramdisk.img ;Image File Name
+ NOR4NAME: ramdisk.img
+ NOR4LOAD: 00000000 ;Image Load Address
+ NOR4ENTRY: 00000000 ;Image Entry Point
+
+to extending the *Image Flash Address* to 16MB
+
+.. code-block:: none
+ :emphasize-lines: 2
+ :linenos:
+
+ NOR4UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE
+ NOR4ADDRESS: 0x01000000 ;Image Flash Address
+ NOR4FILE: \SOFTWARE\ramdisk.img ;Image File Name
+ NOR4NAME: ramdisk.img
+ NOR4LOAD: 00000000 ;Image Load Address
+ NOR4ENTRY: 00000000 ;Image Entry Point
+
+GCC > 5.x support
+*****************
+
+.. note::
+ In case you are using the **latest version** of the OP-TEE Arm Juno build
+ (i.e., ``juno.xml`` manifest), then the ``ramdisk.img`` built with a GCC
+ version newer than 5.x will be bigger than built with older GCC versions.
+ This means that you will need to update the sections in ``image.txt`` that
+ tells where various images will start (see the ``image.txt`` file).
+
+To solve this problem you will need to extend the Juno flash block size reserved
+location for the ``ramdisk.img`` and decrease the size for other images in the
+``image.txt`` file accordingly in the same manner as described in the previous
+section above.
+
+For example with ``juno-latest-busybox-uboot.zip``. The current ``ramdisk.img``
+size with GCC 5.x compiler is 29.15MB and therefore we will need to extend that
+size for that to 32MB. You do that by changing the highlighted ones (i.e.,
+*Image Flash Address*) in file ``/JUNO/SITE1/HBI0262B/images.txt``.
+
+.. code-block:: none
+ :emphasize-lines: 2, 9, 16, 23
+ :linenos:
+
+ NOR2UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE
+ NOR2ADDRESS: 0x00100000 ;Image Flash Address
+ NOR2FILE: \SOFTWARE\Image ;Image File Name
+ NOR2NAME: norkern ;Rename kernel to norkern
+ NOR2LOAD: 00000000 ;Image Load Address
+ NOR2ENTRY: 00000000 ;Image Entry Point
+
+ NOR3UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE
+ NOR3ADDRESS: 0x02C00000 ;Image Flash Address
+ NOR3FILE: \SOFTWARE\juno.dtb ;Image File Name
+ NOR3NAME: board.dtb ;Specify target filename to preserve file extension
+ NOR3LOAD: 00000000 ;Image Load Address
+ NOR3ENTRY: 00000000 ;Image Entry Point
+
+ NOR4UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE
+ NOR4ADDRESS: 0x00D00000 ;Image Flash Address
+ NOR4FILE: \SOFTWARE\ramdisk.img ;Image File Name
+ NOR4NAME: ramdisk.img
+ NOR4LOAD: 00000000 ;Image Load Address
+ NOR4ENTRY: 00000000 ;Image Entry Point
+
+ NOR5UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE
+ NOR5ADDRESS: 0x02D00000 ;Image Flash Address
+ NOR5FILE: \SOFTWARE\hdlcdclk.dat ;Image File Name
+ NOR5LOAD: 00000000 ;Image Load Address
+ NOR5ENTRY: 00000000 ;Image Entry Point
+
+.. _Juno revisions: https://community.arm.com/dev-platforms/w/docs/253/juno-board-revisions
+.. _old release notes: https://community.arm.com/dev-platforms/w/docs/226/old-release-notes
+.. _Run the Arm Platforms deliverables on Juno: https://community.arm.com/dev-platforms/w/docs/391/run-the-arm-platforms-deliverables-on-juno
diff --git a/building/devices/qemu.rst b/building/devices/qemu.rst
new file mode 100644
index 0000000..e00e2a4
--- /dev/null
+++ b/building/devices/qemu.rst
@@ -0,0 +1,136 @@
+On this page you will find device specific information for QEMU v7 (Armv7-A) and
+QEMU v8 (Armv8-A).
+
+.. _qemu_v7:
+
+#######
+QEMU v7
+#######
+The instructions here will tell how to run OP-TEE using QEMU for Armv7-A.
+
+Build instructions
+******************
+As long as you pick the v7 manifest, i.e., ``default.xml`` the
+":ref:`get_and_build_the_solution`" tells all you need to know to build and boot
+up QEMU v7.
+
+
+Consoles
+********
+After running ``make run`` you will end up in the QEMU console and it will also
+spawn two UART consoles. One console containing the UART for secure world and
+one console containing the UART for normal world. You will see that it stops
+waiting for input on the QEMU console. To continue, do:
+
+.. code-block:: none
+
+ (qemu) c
+
+Host-Guest folder sharing
+*************************
+You can use the VirtFS QEMU feature to avoid changing rootfs CPIO archive every
+time you need to add additional files or modify existing files. To do this, you
+share a folder between the guest and host operating systems. To enable and use
+this feature you have to provide additional arguments when running make,
+example:
+
+.. code-block:: bash
+
+ $ make QEMU_VIRTFS_ENABLE=y QEMU_USERNET_ENABLE=y
+
+.. hint::
+
+ You can also add ``QEMU_VIRTFS_HOST_DIR=<share>`` in case you don't want to
+ use the default sharing location (which is the root of <qemu-v7-project>).
+
+When QEMU with OP-TEE is up and running, you can mount the host folder in QEMU
+(normal world UART).
+
+.. code-block:: none
+
+ # mount -t 9p -o trans=virtio host <mount_point>
+
+``<mount_point>`` here is folder in the QEMU where you want to mount the host
+PC's shared folder. So if you want to mount it at ``/mnt/host`` you typically do
+this from QEMU NW/UART.
+
+.. code-block:: none
+
+ # mkdir -p /mnt/host
+ # mount -t 9p -o trans=virtio host /mnt/host
+
+Networking
+**********
+After booting QEMU, ``eth0`` will automatically receive an IP address from
+QEMU via DHCP using the SLiRP user networking feature. QEMU will act as a
+gateway to the host network `SLiRP`_.
+
+Please note that ICMP won't work in the guest unless additional configuration is
+made, so the ``ping`` utility won't work.
+
+GDB - Normal world
+******************
+If you need to debug a client application, using GDB in a remote debugging
+configuration may be useful. Remote debugging means ``gdb`` runs on your PC,
+where it can access the source code, while the program being debugged runs on
+the remote system (in this case, in the QEMU environment in normal world). Here
+is how to do that. On your PC, build with ``GDBSERVER=y``:
+
+.. code-block:: bash
+
+ $ cd <qemu-v7-project>/build
+ # You **only** need to rm -rf the first time you build with the new flag.
+ # If you omit doing so, it's likely that you will see "stamp" errors in the
+ # build log.
+ $ rm -rf <qemu-v7-project>/out-br
+ $ make -j8 run GDBSERVER=y
+
+Boot up as usual
+
+.. code-block:: bash
+
+ (qemu) c
+
+Inside QEMU (Normal World UART), run your application with gdbserver (for
+example ``xtest 4002``):
+
+.. code-block:: none
+
+ # gdbserver :12345 xtest 4002
+ Process xtest created; pid = 654
+ Listening on port 12345
+
+Back on your PC, open another terminal, start GDB and connect to the target:
+
+.. code-block:: bash
+
+ $ <qemu-v7-project>/out-br/host/bin/arm-buildroot-linux-gnueabihf-gdb
+ (gdb) set sysroot <qemu-v7-project>/out-br/host/arm-buildroot-linux-gnueabihf/sysroot
+ (gdb) target remote :12345
+
+Now GDB is connected to the remote application. You may use GDB normally.
+
+.. code-block:: none
+
+ (gdb) b main
+ (gdb) c
+
+
+.. _qemu_v8:
+
+#######
+QEMU v8
+#######
+The instructions here will tell how to run OP-TEE using QEMU for Armv7-A.
+
+Build instructions
+******************
+As long as you pick the v8 manifest, i.e., ``qemu_v8.xml`` the
+":ref:`get_and_build_the_solution`" tells all you need to know to build and boot
+up QEMU v8.
+
+All other things (networking, GDB etc) in the v7 section above is also
+applicable on QEMU v8 as long as you replace ``<qemu-v7-project>`` with
+``<qemu-v8-project>`` to get the correct paths relative to your QEMU v8 setup.
+
+.. _SLiRP: https://wiki.qemu.org/Documentation/Networking#User_Networking_.28SLIRP.29
diff --git a/building/devices/rpi3.rst b/building/devices/rpi3.rst
new file mode 100644
index 0000000..4a0b7a9
--- /dev/null
+++ b/building/devices/rpi3.rst
@@ -0,0 +1,684 @@
+.. _rpi3:
+
+##############
+Raspberry Pi 3
+##############
+`Sequitur Labs`_ did the initial OP-TEE port which at the time also came with
+modifications in U-Boot, Trusted Firmware A and Linux kernel. Since that initial
+port more and more patches have found mainline trees and today the OP-TEE setup
+for Raspberry Pi 3 uses only upstream tree's with the exception of Linux kernel.
+
+
+Disclaimer
+**********
+.. warning::
+
+ This port of Trusted Firmware A and OP-TEE to Raspberry Pi 3 **IS NOT
+ SECURE!** Although the Raspberry Pi3 processor provides ARM TrustZone
+ exception states, the mechanisms and hardware required to implement secure
+ boot, memory, peripherals or other secure functions are not available. Use
+ of OP-TEE or TrustZone capabilities within this package **does not result**
+ in a secure implementation. This package is provided solely for
+ **educational purposes** and **prototyping**.
+
+
+.. _rpi3_software:
+
+What is expected to work?
+*************************
+First, note that all OP-TEE developer builds (ref, :ref:`build`) have rather
+simple overall goals:
+
+ - Successfully build OP-TEE for certain devices.
+ - Run xtest and optee_example binaries successfully with no regressions
+ using UART(s).
+
+I.e., it is important to understand that our "`OP-TEE developer builds`" shall
+not be compared with full Linux distributions which supports "everything". As a
+couple of examples, we don't enable any particular drivers in Linux kernel, we
+don't include all sorts of daemons, we do not include an X-environment etc. At
+the same time this doesn't mean that you cannot use OP-TEE in real environments.
+It is usually perfectly fine to run on all sorts of devices, environments etc.
+It's just that for the OP-TEE developer builds we have intentionally stripped
+down the environment to make it rather fast to get all the source code, build it
+all and run xtest.
+
+We are highlighting this here, since over the years we have had many questions
+at GitHub about things that people usually find working on their Raspberry Pi
+devices when they are using Raspbian (which this is not). The table below
+describes what is `officially` supported in the Raspberry Pi 3 OP-TEE developer
+builds and right after that follows sections for each of giving a bit more
+context to it.
+
+ +-----------------+------------+
+ | Name | Supported? |
+ +=================+============+
+ | Buildroot | Yes |
+ +-----------------+------------+
+ | HDMI | No |
+ +-----------------+------------+
+ | NFS | Yes |
+ +-----------------+------------+
+ | Random packages | Maybe |
+ +-----------------+------------+
+ | Raspbian | No |
+ +-----------------+------------+
+ | Secure boot | Maybe |
+ +-----------------+------------+
+ | TFTP | Yes |
+ +-----------------+------------+
+ | UART | Yes |
+ +-----------------+------------+
+ | Wi-Fi | No |
+ +-----------------+------------+
+
+
+.. _rpi3_support_buildroot:
+
+Buildroot
+=========
+We are using Buildroot as the tool to create a stripped down filesystem for
+Linux where we also put OP-TEE binaries like Trusted Applications, client
+libraries and TEE supplicant. If a user wants to add/enable additional packages,
+then that is also possible by adding new lines in ``common.mk`` in :ref:`build`
+(search for ``BR2_PACKAGE_`` in the git to see how it's done).
+
+
+.. _rpi3_support_hdmi:
+
+HDMI
+====
+X isn't enabled and we have not built nor enabled any drivers for graphics.
+
+
+.. _rpi3_support_nfs:
+
+NFS
+===
+Works to boot up a Linux root filesystem, more on that further down.
+
+
+.. _rpi3_support_random_package:
+
+Random packages
+===============
+See the :ref:`rpi3_support_buildroot` section above. You can enable packages
+supported by Buildroot, but as mentioned initially in this section, lack of
+drivers and other daemons etc might make it impossible to run.
+
+
+.. _rpi3_support_raspbian:
+
+Raspbian
+========
+We are not using it. However, people (from `Sequitur Labs`_) have successfully
+been able to add OP-TEE to Raspbian builds. But since we're not using it and
+haven't tried, we simply don't support it.
+
+
+.. _rpi3_support_secure_boot:
+
+Secure boot
+===========
+First pay attention to the initial warning on this page. I.e., no matter what
+you are doing with Raspberry Pi and TrustZone / OP-TEE you **cannot** make it
+secure. But that doesn't mean that you cannot "enable" secure features as such
+for prototyping and to learn how to build and use those. That kind of knowledge
+can later on be transferred and used on other devices which have all the
+necessary secure capabilities needed to make a secure system. We haven't tested
+to enable secure boot on Raspberry Pi 3. But we believe that a good starting
+point would be Trusted Firmware A's documentation about the "`Authentication
+Framework`_" and `RPi3 in TF-A`_.
+
+
+.. _rpi3_support_tftp:
+
+TFTP
+====
+When you reach U-Boot (see :ref:`rpi3_boot_sequence`), then you can start using
+TFTP to load boot firmware etc. Note that if you overwrite ``armstub8.bin`` for
+example and that happens to be faulty, then you will need to re-mount the BOOT
+partition on the SD-card and put a new working version of it. Also note that
+changing early boot binaries (TF-A, OP-TEE core etc) will require you to reboot
+the device see the changes.
+
+
+.. _rpi3_support_uart:
+
+UART
+====
+Fully supported, for more details look at the UART section further down.
+
+
+.. _rpi3_support_wifi:
+
+Wi-Fi
+=====
+Even though Raspberry Pi 3 has a Wi-Fi chip, we do not support it in our
+stripped down builds.
+
+
+.. _rpi_hardware:
+
+What versions of Raspberry Pi will work?
+****************************************
+Below is a table of supported hardware in our OP-TEE developer builds. We have
+only used the Raspberry Pi 3 Model B, i.e., the first RPi 3 device that was
+released. But we know that people have successfully been able to use it with
+both RPi 2's as well as the newer RPi 3 B+. But as long as we in the `core
+team`_ doesn't have those at hands we cannot guarantee anything, therefore we
+simply say "No" below.
+
+ +-------------------------------+------------+
+ | Hardware | Supported? |
+ +===============================+============+
+ | Raspberry Pi 1 Model A | No |
+ +-------------------------------+------------+
+ | Raspberry Pi 1 Model B | No |
+ +-------------------------------+------------+
+ | Raspberry Pi 1+ Model A | No |
+ +-------------------------------+------------+
+ | Raspberry Pi 1+ Model B | No |
+ +-------------------------------+------------+
+ | Raspberry Pi 2 Model B | No |
+ +-------------------------------+------------+
+ | Raspberry Pi 2 Model B v1.2 | No |
+ +-------------------------------+------------+
+ | Raspberry Pi 3+ Model A | No |
+ +-------------------------------+------------+
+ | Raspberry Pi 3 Model B | Yes |
+ +-------------------------------+------------+
+ | Raspberry Pi 3+ Model B | No |
+ +-------------------------------+------------+
+ | Zero - all versions | No |
+ +-------------------------------+------------+
+ | Compute module - all versions | No |
+ +-------------------------------+------------+
+
+
+.. _rpi3_boot_sequence:
+
+Boot sequence
+*************
+ - The **GPU** starts executing the first stage bootloader, which is stored
+ in ROM on the SoC. The first stage bootloader reads the SD-card, and loads
+ the second stage bootloader (``bootcode.bin``) into the L2 cache, and runs
+ it.
+ - ``bootcode.bin`` enables SDRAM, and reads the third stage bootloader
+ ``loader.bin`` from the SD-card into RAM, and runs it.
+ - ``loader.bin`` reads the GPU firmware (``start.elf``).
+ - ``start.elf`` reads ``config.txt``, pre-loads ``armstub8.bin`` (which
+ contains: BL1/TF-A + BL2/TF-A + BL31/TF-A + BL32/OP-TEE + BL33/U-boot) to
+ ``0x0`` and jumps to the first instruction.
+ - A traditional boot sequence of TF-A -> OP-TEE -> U-boot is performed,
+ i.e., BL1 loads BL2, then BL2 loads and run BL31(SM), BL32(OP-TEE),
+ BL33(U-boot) (one after another)
+ - U-Boot runs ``fatload/booti`` sequence to load from eMMC to RAM both
+ ``zImage`` and then ``DTB`` and boot.
+
+
+.. _rpi3_build_instructions:
+
+Build instructions
+******************
+1. Start by following the :ref:`get_and_build_the_solution` as described in
+ :ref:`build`, but stop at the ":ref:`build_flash`" step (i.e., **don't** run
+ the make flash command!).
+
+2. Next step is to partition and format the memory card and to put the files
+ onto the same. That is something we don't want to automate, since if anything
+ goes wrong, in worst case it might wipe one of your regular hard disks.
+ Instead what we have done, is that we have created another makefile target
+ that will tell you exactly what to do. Run that command and follow the
+ instructions there.
+
+ .. code-block:: bash
+
+ $ make img-help
+
+ .. note::
+
+ The mention of ``/dev/sdx1`` and ``/dev/sdx2`` when running the command
+ above are just examples. You need to figure out and replace that with the
+ correct name(s) for your computer and SD-card (typically run ``dmesg``
+ and look for the device name matching your SD-card).
+
+3. Put the SD-card back into the Raspberry Pi 3.
+
+4. Plug in the UART cable and attach to the UART
+
+ .. code-block:: bash
+
+ $ picocom -b 115200 /dev/ttyUSB0
+
+ .. note::
+
+ Install picocom if not already installed ``$ sudo apt-get install picocom``.
+
+5. Power up the Raspberry Pi 3 and the system shall start booting which you will
+ see on the UART (not :ref:`rpi3_support_hdmi`).
+
+6. When you have a shell, then it's simply just to follow the
+ ":ref:`build_run_xtest`" instructions.
+
+
+.. _rpi3_nfs:
+
+NFS boot
+********
+Booting via NFS is quite useful for several reasons, but the obvious reason when
+working with Raspberry Pi is that you don't have to move the SD-card back and
+forth between the host machine and the Raspberry Pi 3 itself when working with
+**Normal World** files, like Linux kernel and user space programs. Here we will
+describe how to setup NFS server, so the rootfs can be mounted via NFS.
+
+.. warning::
+
+ This guide doesn't focus on any desktop security, so eventually you would
+ need to harden your setup.
+
+In the description below we will use the following terminology, IP addresses and
+paths. The reader of this guide is supposed to update this to match his own
+environment.
+
+.. code-block:: none
+
+ 192.168.1.100 <--- This is your desktop computer (NFS server)
+ 192.168.1.200 <--- This is the Raspberry Pi
+ /srv/nfs/rpi <--- Location for the NFS share
+
+
+Configure NFS
+=============
+Start by installing the NFS server
+
+.. code-block:: bash
+
+ $ sudo apt-get install nfs-kernel-server
+
+Then edit the exports file,
+
+.. code-block:: bash
+
+ $ sudo vim /etc/exports
+
+In this file you shall tell where your files/folder are and the IP's allowed to
+access the files. The way it's written below will make it available to every
+machine on the same subnet (again, be careful about security here). Let's add
+this line to the file (it's the only line necessary in the file, but if you have
+several different filesystems available, then you should of course add them
+too, one line for each share).
+
+.. code-block:: none
+
+ /srv/nfs/rpi 192.168.1.0/24(rw,sync,no_root_squash,no_subtree_check)
+
+Next create the folder where you are going to put the root filesystem
+
+.. code-block:: none
+
+ $ sudo mkdir /srv/nfs/rpi
+
+After this, restart the NFS kernel server
+
+.. code-block:: none
+
+ $ service nfs-kernel-server restart
+
+.. hint::
+
+ To see that your shares are correctly setup and that the NFS server is
+ running, you can run: ``$ showmount --all localhost`` and you should get a
+ list of ``IP:<path>'s`` based on what you have added in your exports file.
+ If you get nothing there, then your NFS server hasn't been setup correctly.
+
+Prepare files to be shared
+==========================
+We are now going to put the root filesystem on the location we prepared in the
+previous section.
+
+.. note::
+
+ The path to the ``rootfs.cpio.gz`` refers to <rpi3-project>, replace this so
+ it matches your setup.
+
+.. code-block:: bash
+
+ $ cd /srv/nfs/rpi
+ $ sudo gunzip -cd <rpi3-project>/out-br/images/rootfs.cpio.gz | sudo cpio -idmv
+ $ sudo rm -rf /srv/nfs/rpi/boot/*
+
+uboot.env configuration
+=======================
+The file ``uboot.env`` contains boot configurations that tells what binaries to
+load and at what addresses. When using NFS you need to tell U-Boot where the NFS
+server is located (IP and path). Since the exact IP and path varies for each
+user, we must update ``uboot.env`` accordingly.
+
+There are two ways to update ``uboot.env``, one is to update
+``uboot.env.txt`` (in :ref:`build`) and the other is to update directly from
+the U-Boot console. Pick the one that you suits your needs. We will cover each
+of them separately here.
+
+Change uboot.env.txt
+====================
+In an editor open: ``<rpi3-project>/build/rpi3/firmware/uboot.env.txt`` and
+change:
+
+ - ``nfsserverip`` to match the IP address of your NFS server.
+ - ``gatewayip`` to the IP address of your router.
+ - ``nfspath`` to the exported filesystem in your NFS share.
+
+As an example a section of ``uboot.env.txt`` could look like this:
+
+.. code-block:: c
+ :emphasize-lines: 2,4,5
+
+ # NFS/TFTP boot configuraton
+ gatewayip=192.168.1.1
+ netmask=255.255.255.0
+ nfsserverip=192.168.1.100
+ nfspath=/srv/nfs/rpi
+
+Next, you need to re-generate ``uboot.env``:
+
+.. code-block:: bash
+
+ $ cd <rpi3-project>/build
+ $ make u-boot-env-clean
+ $ make u-boot-env
+
+Finally, you need to copy the updated ``<rpi3-project>/out/uboot.env`` to the
+**BOOT** partition of your SD-card (mount it as described in
+:ref:`rpi3_build_instructions` and then just overwrite (``cp``) the file on the
+**BOOT** partition of your SD-card).
+
+Update u-boot.env from U-Boot console
+=====================================
+Boot up the device until you see U-Boot running and counting down, then hit any
+key and will see the ``U-Boot>`` prompt. You can then update the
+``nfsserverip``, ``gatewayip`` and ``nfspath`` by writing
+
+.. code-block:: bash
+
+ U-Boot> setenv nfsserverip '192.168.1.100'
+ U-Boot> setenv gatewayip '192.168.1.1'
+ U-Boot> setenv nfspath '/srv/nfs/rpi'
+
+If you want those environment variables to persist between boots, then type.
+
+.. code-block:: bash
+
+ U-Boot> saveenv
+
+Boot up with NFS
+================
+With all preparations above done correctly, you should now be able to boot up
+the device and kernel, secure side OP-TEE and the entire root filesystem should
+be loaded from the network shares (NFS). Power up the Raspberry, halt in U-Boot and
+then type.
+
+.. code-block:: bash
+
+ U-Boot> run nfsboot
+
+
+If everything works, you can simply copy paste files like ``xtest``, Trusted
+Applications and other things that usually resides on the host PC's filesystem,
+i.e., directly from your build folders to the ``/srv/nfs/rpi/...`` folders. By
+doing so you don't have to reboot the device when doing development and testing.
+Just rebuild and copy is sufficient.
+
+.. note::
+
+ You **cannot** make symlinks in the NFS share to the built files, i.e., you
+ must copy them!
+
+
+.. _rpi3_jtag:
+
+JTAG
+****
+To enable JTAG you need to add a line saying ``enable_jtag_gpio=1`` in
+``config.txt``. There are two ways you can do this, both requires that you to
+mount the **BOOT** partition on the SD-card at your computer (see the ``make
+img-help`` step under :ref:`rpi3_build_instructions`). **After** you have
+mounted the BOOT partition continue with whichever way is most suitable for you.
+
+Change config.txt directly
+==========================
+With your editor, open ``/media/boot/config.txt`` and add a line
+``enable_jtag_gpio=1``, save the file, unmount the BOOT partition and you're
+good to go after rebooting the device.
+
+Rebuild and untar
+=================
+1. With your editor, open ``<rpi3-project>/build/rpi3/firmware/config.txt`` and
+ add a line ``enable_jtag_gpio=1``, save the file.
+
+2. ``$ cd <rpi3-project>/build && make``
+
+3. ``$ cd /media``
+
+4. ``$ sudo gunzip -cd <rpi3-project>/out-br/images/rootfs.cpio.gz | sudo cpio -idmv "boot/*"``
+
+ .. note::
+
+ You didn't forget to mount the BOOT partition before trying this step?
+
+5. Unmount the BOOT partition and you're good to go after rebooting the device.
+
+
+.. _rpi3_jtag_cable:
+
+JTAG/RPi3 cable
+===============
+We have created our own cables that consists of a standard 20-pin JTAG
+connector and a 22-pin connector for the Raspberry Pi 3 itself. Then using a
+ribbon cable we have connected the cables according to the table below (JTAG pin
+<-> Raspberry Pi 3 Header pin).
+
++----------+--------+--------+------+-----------------+
+| JTAG pin | Signal | GPIO | Mode | RPi3 Header pin |
++==========+========+========+======+=================+
+| 1 | 3v3 | N/A | N/A | 1 |
++----------+--------+--------+------+-----------------+
+| 3 | nTRST | GPIO22 | ALT4 | 15 |
++----------+--------+--------+------+-----------------+
+| 5 | TDI | GPIO26 | ALT4 | 37 |
++----------+--------+--------+------+-----------------+
+| 7 | TMS | GPIO27 | ALT4 | 13 |
++----------+--------+--------+------+-----------------+
+| 9 | TCK | GPIO25 | ALT4 | 22 |
++----------+--------+--------+------+-----------------+
+| 11 | RTCK | GPIO23 | ALT4 | 16 |
++----------+--------+--------+------+-----------------+
+| 13 | TDO | GPIO24 | ALT4 | 18 |
++----------+--------+--------+------+-----------------+
+| 18 | GND | N/A | N/A | 14 |
++----------+--------+--------+------+-----------------+
+| 20 | GND | N/A | N/A | 20 |
++----------+--------+--------+------+-----------------+
+
+.. warning::
+
+ Be careful and cross check the wiring as incorrect wiring might **damage**
+ your device! Also be careful to connect the cable correctly at both ends
+ (don't flip it and don't put it at the wrong pins in the Raspberry Pi 3
+ side).
+
+
+.. _rpi3_uart_cable:
+
+UART/RPi3 cable
+***************
+In addition to the JTAG connections we have also wired up the RX/TX to be able
+to use the UART. Note, for this you don't need to do JTAG wirings, i.e., it's
+perfectly fine to just wire up the UART only. There are many ready made cables
+for this on the net (`eBay`_) and cost almost nothing. Get one of those if you
+**don't** intend to use JTAG.
+
++-------------+-------+--------+------+----------------+
+| UART pin | Signal| GPIO | Mode | RPi3 Header pin|
++=============+=======+========+======+================+
+| Black (GND) | GND | N/A | N/A | 6 |
++-------------+-------+--------+------+----------------+
+| White (RXD) | TXD | GPIO14 | ALT0 | 8 |
++-------------+-------+--------+------+----------------+
+| Green (TXD) | RXD | GPIO15 | ALT0 | 10 |
++-------------+-------+--------+------+----------------+
+
+.. warning::
+
+ Be careful and cross check the wiring as incorrect wiring might **damage**
+ your device!
+
+
+.. _rpi3_openocd:
+
+OpenOCD
+*******
+Build OpenOCD
+=============
+Before building OpenOCD, ensure that you have the ``libusb-dev`` installed.
+
+.. code-block:: bash
+
+ $ sudo apt-get install libusb-1.0-0-dev
+
+We are using the `official OpenOCD`_ release, simply clone that to your computer
+and then building is like a lot of other software, i.e.,
+
+.. code-block:: bash
+
+ $ git clone http://repo.or.cz/openocd.git
+ $ cd openocd
+ $ ./bootstrap
+ $ ./configure
+ $ make
+
+
+.. note::
+
+ In recent versions of OpenOCD, the legacy ft2332 support has been depracted.
+ All these devices now uses libftdi instead. From OpenOCD release notes:
+ `"GPL-incompatible FTDI D2XX library support dropped (Presto, OpenJTAG and
+ USB-Blaster I are using libftdi only now)"`.
+
+We leave it up to the reader of this guide to decide if he wants to install it
+properly (``make install``) or if he will just run it from the tree directly.
+The rest of this guide will just run it from the tree.
+
+OpenOCD RPi3 configuration file
+===============================
+Unfortunately, the necessary `RPi3 OpenOCD config`_ isn't upstreamed yet into
+the `official OpenOCD`_ repository, so you should use the one stored here
+``<rpi3-project/build/rpi3/debugger/pi3.cfg``.
+
+Running OpenOCD
+===============
+Depending on the JTAG debugger you are using you'll need to find and use the
+interface file for that particular debugger. We've been using `J-Link
+debuggers`_ and `Bus Blaster`_ successfully. To start an OpenOCD session using a
+J-Link device you type:
+
+.. code-block:: bash
+
+ $ cd <openocd>
+ $ ./src/openocd -f ./tcl/interface/jlink.cfg -f <rpi3-project>/build/rpi3/debugger/pi3.cfg
+
+For Bus Blaster type:
+
+.. code-block:: bash
+
+ $ ./src/openocd -f ./tcl/interface/ftdi/dp_busblaster.cfg \ -f <rpi3_repo_dir>/build/rpi3/debugger/pi3.cfg
+
+To be able to write commands directly to OpenOCD, you simply open up another
+shell and type:
+
+.. code-block:: bash
+
+ $ nc localhost 4444
+
+From there you can set breakpoints, examine memory etc ("``> help``" will give
+you a list of available commands). Having that said, if you connect to OpenOCD
+using GDB, then there is not much incentive connecting to OpenOCD directly,
+since you will be able to do the same in GDB by the ``monitor`` command.
+
+Use GDB
+=======
+OpenOCD will by default listen to GDB connections on port ``3333``. So after
+starting OpenOCD, make a connection to GDB.
+
+.. code-block:: bash
+
+ # Ensure that you have "gdb" in your $PATH
+ $ aarch64-linux-gnu-gdb -q
+ (gdb) target remote localhost:3333
+
+To load symbols you just use the ``symbol-file <path/to/my.elf`` as usual. For
+convenience you can create an alias in the ``~/.gdbinit`` file. For TEE core
+debugging this works:
+
+.. code-block:: none
+
+ define jtag_rpi3
+ target remote localhost:3333
+ symbol-file <rpi3-project>/optee_os/out/arm/core/tee.elf
+ end
+
+So, when running GDB, you simply type: ``(gdb) jtag_rpi3`` and it will both
+connect and load the symbols for TEE core. For Linux kernel and other binaries
+you would do the same.
+
+Debug session example
+=====================
+After making an initial Raspberry Pi 3 build for OP-TEE where you've enabled
+JTAG, installed and built OpenOCD, connected the JTAG cable, then you're ready
+for debugging OP-TEE using JTAG on Raspberry 3. Boot up the Raspberry Pi 3 until
+you are in Linux and ready to run xtest. Start a new shell (on the host machine)
+where you run OpenOCD:
+
+.. code-block:: bash
+
+ $ cd <openocd>
+ $ ./src/openocd -f ./tcl/interface/jlink.cfg -f <rpi3-project>/build/rpi3/debugger/pi3.cfg
+
+Start another shell, where you run GDB
+
+.. code-block:: bash
+
+ $ <rpi3-project>/toolchains/aarch64/bin/aarch64-linux-gnu-gdb -q
+ (gdb) target remote localhost:3333
+ (gdb) symbol-file <rpi3-project>/optee_os/out/arm/core/tee.elf
+
+Next, try to set a breakpoint for the function ``hmac_init``, here use
+**hardware** breakpoints (i.e., ``hb``)!
+
+.. code-block:: bash
+
+ (gdb) hb hmac_init
+ Hardware assisted breakpoint 2 at 0x1012a178: file core/lib/libtomcrypt/src/mac/hmac/hmac_init.c, line 65.
+ (gdb) c
+ Continuing.
+
+In the UART console (RPi3/Linux), run xtest.
+
+.. code-block:: bash
+
+ # xtest
+
+And shortly thereafter you will see GDB stops on your breakpoint and from there
+you can debug using normal GDB commands.
+
+
+.. _`Authentication Framework`: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/auth-framework.rst
+.. _Bus Blaster: http://dangerousprototypes.com/docs/Bus_Blaster
+.. _core team: https://github.com/orgs/OP-TEE/teams/linaro/members
+.. _eBay: https://www.ebay.com/sch/i.html?&_nkw=UART+cable
+.. _J-Link debuggers: https://www.segger.com/jlink_base.html
+.. _Linaro rootfs: http://releases.linaro.org/debian/images/installer-arm64/latest/linaro*.tar.gz
+.. _official OpenOCD: http://openocd.org
+.. _RPi3 in TF-A: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/plat/rpi3.rst
+.. _RPi3 OpenOCD config: https://github.com/OP-TEE/build/blob/master/rpi3/debugger/pi3.cfg
+.. _Sequitur Labs: http://www.sequiturlabs.com
diff --git a/building/devices/ti.rst b/building/devices/ti.rst
new file mode 100644
index 0000000..9057604
--- /dev/null
+++ b/building/devices/ti.rst
@@ -0,0 +1,53 @@
+.. _ti:
+
+######################
+Texas Instruments SoCs
+######################
+The instructions here will tell how to run OP-TEE on Texas Instruments devices.
+Secure TI devices require a boot image that is authenticated by ROM code to
+function. Without this, even JTAG remains locked. In order to create a valid
+boot image for a secure device from TI, the initial public software image must
+be signed and combined with various headers, certificates, and other binary
+images.
+
+Information on the details on the complete boot image format can be obtained
+from Texas Instruments. The tools used to generate boot images for secure
+devices are part of a secure development package (SECDEV) that can be downloaded
+from:
+
+ http://www.ti.com/mysecuresoftware (login required)
+
+The secure development package is access controlled due to NDA and export
+control restrictions. Access must be requested and granted by TI before the
+package is viewable and downloadable. Contact TI, either online or by way of a
+local TI representative, to request access.
+
+Regular build
+*************
+Start out by following the :ref:`get_and_build_the_solution` as described in
+:ref:`build`. Stop before the section on flashing the device, this is currently
+not supported automatically.
+
+Booting the device
+******************
+SD Card boot
+============
+Create two partitions on an SD card, ``boot`` of type ``FAT16`` and ``rootfs``
+of type ``EXT4``. To prevent accidental data loss we do not attempt this
+automatically (the RPI3 :ref:`rpi3_build_instructions` use a similar SD card
+layout, you can refer to that page for details).
+
+Extract the generated rootfs to the ``rootfs`` partition
+
+.. code-block:: bash
+
+ $ cd <SD card rootfs partition>
+ $ gunzip -cd <repo directory>/gen_rootfs/filesystem.cpio.gz | sudo cpio -idm
+
+Add the bootloader to the ``boot`` partition
+
+.. code-block:: bash
+
+ $ cd <SD card boot partition>
+ $ cp <repo directory>/u-boot/u-boot-spl_HS_MLO MLO
+ $ cp <repo directory>/u-boot/u-boot_HS.img u-boot.img
diff --git a/building/gits/build.rst b/building/gits/build.rst
new file mode 100644
index 0000000..9c27e3c
--- /dev/null
+++ b/building/gits/build.rst
@@ -0,0 +1,472 @@
+.. _build:
+
+#####
+build
+#####
+Why this particular git? As it turns out it's totally possible to put together
+everything on your own. You can build all the individual components, os, client,
+xtest, Linux kernel, TF-A, TianoCore, QEMU, Buildroot_ etc and put all the
+binaries at correct locations and write your own command lines, Makefiles,
+shell-scripts etc that will work nicely on the devices you are interested in. If
+you know how to do that, fine, please go a head. But for newcomers it's way to
+much behind the scenes to be able to setup a working environment. Also, if you
+for some reason want to run something in an automated way, then you need
+something else wrapping it up for you.
+
+With this particular git **built.git** our goal is to simply to make it easy for
+newcomers to get started with OP-TEE using the devices we've listed in this
+document.
+
+
+git location
+************
+https://github.com/OP-TEE/build
+
+
+Why repo?
+*********
+We discussed alternatives, initially we started out with having a simple
+shell-script, that worked to start with, but after getting more gits in use and
+support for more devices it started to be difficult to maintain. In the end we
+ended up choosing between repo_ from the Google AOSP project and `git
+submodules`_. No matter which you choose, there will always be some person
+arguing that one is better than the other. For us we decided to use repo. Not
+directly for the features itself from repo, but for the ability to simply work
+with different manifests containing both stable and non-stable release. Using
+some tips and tricks you can also speed up setup time significantly. For day to
+day work with commits, branches etc we tend to use git commands directly.
+
+
+.. _root_fs:
+
+Root filesystem
+***************
+The rootfs in the builds that we cover here are as small as possible and is
+based on a stripped down Buildroot_ configuration adding just enough in the
+rootfs such that one can:
+
+ - Boot OP-TEE.
+ - Run xtest with no regressions.
+ - Easily add additional developer tools like, strace, valgrind etc.
+
+.. note::
+
+ As a consequence of enabling "just enough", it is likely that **non-UART**
+ based enviroments won't work out of the box. I.e., if you try to boot up an
+ enviroment using HDMI and connect keyboards and other devices it is likely
+ that things will not work. To make them work, you probably need to rebuild
+ Linux kernel with correct drivers/frameworks enabled and in addition to that
+ enable binaries/daemons in Buildroot that might be necessary (user space
+ tools and drivers).
+
+
+How do I build using AOSP / OpenEmbedded?
+*****************************************
+For guides how to build AOSP, please refer to our :ref:`aosp` page. For
+OpenEmbedded we have no guide ready, however there are teams in Linaro who are
+building OP-TEE using OpenEmbedded. If you want to get in contact with them,
+please reach out to us (see :ref:`contact`).
+
+.. _optee_developer_setup:
+
+Platforms supported by build.git
+********************************
+Below is a table showing the platforms supported by build.git. OP-TEE as such
+supports many more platforms, but since quite a few of the other platforms are
+maintained by people outside Linaro or are using a special setup, we encourage
+you to talk to the maintainer of that platform directly if you have build
+related questions etc. Please see the MAINTAINERS_ file for contact information.
+
+.. Please keep this list sorted in alphabetic order:
+.. list-table::
+ :header-rows: 1
+
+ * - Platform
+ - Composite flag
+ - Publicly available?
+
+ * - `ARM Juno Board`_
+ - ``PLATFORM=vexpress-juno``
+ - Yes
+
+ * - `ARM Foundation FVP`_
+ - ``PLATFORM=vexpress-fvp``
+ - Yes
+
+ * - `HiKey Kirin 620`_
+ - ``PLATFORM=hikey``
+ - Yes
+
+ * - `HiKey 960`_
+ - ``PLATFORM=hikey-hikey960``
+ - Yes
+
+ * - `MediaTek MT8173 EVB Board`_ (deprecated)
+ - ``PLATFORM=mediatek-mt8173``
+ - No
+
+ * - `Poplar`_
+ - ``PLATFORM=poplar``
+ - Yes
+
+ * - `QEMU`_
+ - ``PLATFORM=vexpress-qemu_virt``
+ - Yes
+
+ * - `QEMUv8`_
+ - ``PLATFORM=vexpress-qemu_armv8a``
+ - Yes
+
+ * - `Raspberry Pi 3`_
+ - ``PLATFORM=rpi3``
+ - Yes
+
+ * - `Texas Instruments DRA7xx`_
+ - ``PLATFORM=ti-dra7xx``
+ - Yes
+
+ * - `Texas Instruments AM57xx`_
+ - ``PLATFORM=ti-am57xx``
+ - Yes
+
+ * - `Texas Instruments AM43xx`_
+ - ``PLATFORM=ti-am43xx``
+ - Yes
+
+
+Manifests
+*********
+.. _current_version:
+
+Current version
+===============
+Here is a list of manifests for the devices currently supported in
+``build.git``. With these you will get a setup containing the all necessary
+software components to run OP-TEE on the chosen device. Beware that this will
+run latest available on OP-TEE gits meaning that if you re-sync then you will
+most likely get new commits. If you need a stable/tagged version with non-moving
+gits, then please refer to the next section instead.
+
+.. Please keep this list sorted in alphabetic order:
+
++----------------+------------------+----------------------+
+| Target | Manifest xml | Device documentation |
++================+==================+======================+
+| AM43xx | ``am43xx.xml`` | :ref:`ti` |
++----------------+------------------+----------------------+
+| AM57xx | ``am57xx.xml`` | :ref:`ti` |
++----------------+------------------+----------------------+
+| ARM Juno board | ``juno.xml`` | :ref:`juno` |
++----------------+------------------+----------------------+
+| DRA7xx | ``dra7xx.xml`` | :ref:`ti` |
++----------------+------------------+----------------------+
+| FVP | ``fvp.xml`` | :ref:`fvp` |
++----------------+------------------+----------------------+
+| HiKey 960 | ``hikey960.xml`` | :ref:`hikey960` |
++----------------+------------------+----------------------+
+| HiKey | ``hikey.xml`` | :ref:`hikey` |
++----------------+------------------+----------------------+
+| Poplar Debian | ``poplar.xml`` | |
++----------------+------------------+----------------------+
+| QEMU | ``default.xml`` | :ref:`qemu_v7` |
++----------------+------------------+----------------------+
+| QEMUv8 | ``qemu_v8.xml`` | :ref:`qemu_v8` |
++----------------+------------------+----------------------+
+| Raspberry Pi 3 | ``rpi3.xml`` | :ref:`rpi3` |
++----------------+------------------+----------------------+
+
+Stable releases
+===============
+Starting from OP-TEE ``v3.1`` you can check out stable releases by using the
+same manifests as for current version above, but with the difference that **you
+also need to specify a branch** where the name corresponds to the release
+version. I.e., when we are doing releases we are creating a branch with a name
+corresponding to the release version. So, let's for example say that you want to
+checkout a stable OP-TEE ``v3.4`` for Raspberry Pi 3, then you do like this
+instead of what is mentioned further down in section
+":ref:`build_get_the_source`" (note the ``-b 3.4.0``):
+
+.. code-block:: bash
+
+ ...
+ $ repo init -u https://github.com/OP-TEE/manifest.git -m rpi3.xml -b 3.4.0
+ ...
+
+Stable releases prior to OP-TEE v3.1 (v1.0.0 to v3.0.0)
+=======================================================
+Before OP-TEE ``v3.1`` we used to have separate xml-manifest files for the
+stable builds. If you for some reason need an older stable release, then you can
+use the ``xyz_stable.xml`` file corresponding to your device. The way to init
+``repo`` is almost the same as described above, the major difference is the name
+of manifest being referenced (``-m xyz_stable.xml``) and that we are referring
+to a tag instead of a branch (``-b refs/tags/MAJOR.MINOR.PATCH``). So as an
+example, if you need to setup the ``2.1.0`` stable release for HiKey, then you
+would do like this instead of what is mentioned further down in section
+":ref:`build_get_the_source`".
+
+.. code-block:: bash
+
+ ...
+ repo init -u https://github.com/OP-TEE/manifest.git -m hikey_stable.xml -b refs/tags/2.1.0
+ ...
+
+Here is a list of targets and the names of the stable manifests files which were
+supported by older releases:
+
+.. Please keep this list sorted in alphabetic order:
+
++----------------+-----------------------------+
+| Target | Stable manifest xml |
++================+=============================+
+| AM43xx | ``am43xx_stable.xml`` |
++----------------+-----------------------------+
+| AM57xx | ``am57xx_stable.xml`` |
++----------------+-----------------------------+
+| ARM Juno board | ``juno_stable.xml`` |
++----------------+-----------------------------+
+| DRA7xx | ``dra7xx_stable.xml`` |
++----------------+-----------------------------+
+| FVP | ``fvp_stable.xml`` |
++----------------+-----------------------------+
+| HiKey 960 | ``hikey960_stable.xml`` |
++----------------+-----------------------------+
+| HiKey Debian | ``hikey_debian_stable.xml`` |
++----------------+-----------------------------+
+| HiKey | ``hikey_stable.xml`` |
++----------------+-----------------------------+
+| MTK8173 | ``mt8173-evb_stable.xml`` |
++----------------+-----------------------------+
+| QEMU | ``default_stable.xml`` |
++----------------+-----------------------------+
+| QEMUv8 | ``qemu_v8_stable.xml`` |
++----------------+-----------------------------+
+| Raspberry Pi 3 | ``rpi3_stable.xml`` |
++----------------+-----------------------------+
+
+.. _get_and_build_the_solution:
+
+
+Get and build the solution
+**************************
+Below we will describe the general way of how to get the source, build the
+solution and how to run xtest on the device. For device specific instructions,
+please see the links in the table in the ":ref:`current_version`" section.
+
+.. _build_prerequisites:
+
+Step 1 - Prerequisites
+======================
+Install prerequisites according to the :ref:`prerequisites` page.
+
+
+.. _build_install_repo:
+
+Step 2 - Install Android repo
+=============================
+Note that here you don't install a huge SDK, it's simply a Python script that
+you download and put in your ``$PATH``, that's it. Exactly how to "install"
+repo, can be found at the Google repo_ pages, so follow those instructions
+before continuing.
+
+
+.. _build_get_the_source:
+
+Step 3 - Get the source code
+============================
+Choose the manifest corresponding to the platform you intend to use (see the
+table in section ":ref:`current_version`". For example, if you intend to use
+Raspberry Pi3, then at line 3 below, ``${TARGET}.xml`` shall be ``rpi3.xml``.
+The ``<optee-project>`` is whatever location where you want to store the entire
+OP-TEE developer setup.
+
+.. code-block:: bash
+ :linenos:
+ :emphasize-lines: 3
+
+ $ mkdir -p <optee-project>
+ $ cd <optee-project>
+ $ repo init -u https://github.com/OP-TEE/manifest.git -m ${TARGET}.xml [-b ${BRANCH}]
+ $ repo sync -j4 --no-clone-bundle
+
+.. hint::
+
+ By referencing an existing and locally saved repo forest you can save lots
+ of time. We are talking about doing repo sync in 30 seconds instead of 15-30
+ minutes (see the :ref:`tips_and_tricks` section for more details).
+
+
+.. _build_get_toolchains:
+
+Step 4 - Get the toolchains
+===========================
+In OP-TEE we're using different toolchains for different targets (depends on
+ARMv7-A ARMv8-A 64/32bit solutions). In any case start by downloading the
+toolchains by:
+
+.. code-block:: bash
+
+ $ cd <optee-project>/build
+ $ make -j2 toolchains
+
+
+.. _build_make:
+
+Step 5 - Build the solution
+===========================
+We've configured our repo manifests, so that repo will always automatically
+symlink the ``Makefile`` to the correct device specific makefile, that means
+that you simply start the build by running (still in ``<optee-project>/build``)
+
+.. code-block:: bash
+
+ $ make -j `nproc`
+
+This step will also take some time, but you can speed up subsequent builds by
+enabling ccache_ (again see :ref:`tips_and_tricks`).
+
+.. hint::
+
+ **If you're having build issues**, then you can pipe the entire build log to
+ a file, which makes it easier to search for the issue using a regular
+ editor. In that case also avoid the ``-j`` flag so it's easier to see in what
+ order things are happening. To create a ``build.log`` file do: ``$ make 2>&1
+ | tee build.log``
+
+
+.. _build_flash:
+
+Step 6 - Flash the device
+=========================
+On **non-emulated** solutions (this means that you shouldn't do this step when
+you are running QEMU-v7/v8 and FVP), you will need to flash the software in some
+way. We've tried to "hide" that under the following make target:
+
+.. code-block:: bash
+
+ $ make flash
+
+But, since some devices are trickier to flash than others, please see the
+:ref:`device_specific`. See this just as a general instruction.
+
+Step 7 - Boot up the device
+===========================
+This is device specific (see :ref:`device_specific`).
+
+
+.. _build_tee_supplicant:
+
+Step 8 - Load tee-supplicant
+============================
+On **most** solutions tee-supplicant is already running (check by running ``$ ps
+aux | grep tee-supplicant``) on others not. If it's **not** running, then start
+it by running:
+
+.. code-block:: bash
+
+ $ tee-supplicant -d
+
+.. note::
+ If you've built using our manifest you should not need to modprobe any
+ OP-TEE/TEE kernel driver since it's built into the kernel in all our setups.
+
+
+.. _build_run_xtest:
+
+Step 9 - Run xtest
+==================
+The entire xtest test suite has been deployed when you we're making the builds
+in previous steps, i.e, in general there is no need to copy any binaries
+manually. Everything has been put into the :ref:`root_fs` automatically. So, to
+run xtest, you simply type:
+
+.. code-block:: bash
+
+ $ xtest
+
+If there are no regressions / issues found, xtest should end with something like
+this:
+
+.. code-block:: none
+
+ ...
+ +-----------------------------------------------------
+ 23476 subtests of which 0 failed
+ 67 test cases of which 0 failed
+ 0 test case was skipped
+ TEE test application done!
+
+.. hint::
+
+ For other ways to run xtest, please refer to the ":ref:`optee_test_run_xtest`"
+ page at :ref:`optee_test`.
+
+.. _tips_and_tricks:
+
+Tips and Tricks
+***************
+Reference existing project to speed up repo sync
+================================================
+Doing a ``repo init``, ``repo sync`` from scratch can take a fair amount of
+time. The main reason for that is simply because of the size of some of the gits
+we are using, like for the Linux kernel and EDK2. With repo you can reference an
+existing forest and by doing so you can speed up repo sync to taking 30 seconds
+instead of 15-30 minutes. The way to do this are as follows.
+
+ 1. Start by setup a clean forest that you will not touch, in this example,
+ let us call that ``optee-ref`` and put that under for
+ ``$HOME/devel/optee-ref``. This step will take somewhere between 15- to
+ 45 minutes, depending on your connection speed to internet.
+
+ 2. Then setup a cronjob (``crontab -e``) that does a ``repo sync`` in this
+ folder particular folder once a night (that is more than enough).
+
+ 3. Now you should setup your actual tree which you are going to use as your
+ working tree. The way to do this is almost the same as stated in the
+ instructions above (see the ":ref:`build_get_the_source`" section) , the
+ only difference is that you **also** reference the other local forest
+ when running ``repo init``, like this
+
+ .. code-block:: bash
+
+ $ repo init -u https://github.com/OP-TEE/manifest.git --reference $HOME/devel/optee-ref
+
+ 4. The rest is the same above, but now it will only take a couple of seconds
+ to clone a forest.
+
+Normally '1' and '2' above is something you will only do once. Also if you
+ignore step '2', then you will **still** get the latest from official git trees,
+since repo will also check for updates that aren't at the local reference.
+
+Use ccache
+==========
+ccache_ is a tool that caches build object-files etc locally on the disc and can
+speed up build time significantly in subsequent builds. On Debian-based systems
+(Ubuntu, Mint etc) you simply install it by running:
+
+.. code-block:: bash
+
+ $ sudo apt-get install ccache
+
+The makefiles in build.git are configured to automatically find and use ccache
+if ccache is installed on your system, so other than having it installed you
+don't have to think about anything.
+
+.. _Buildroot: https://buildroot.org
+.. _ccache: https://ccache.samba.org
+.. _git submodules: https://git-scm.com/book/en/v2/Git-Tools-Submodules
+.. _MAINTAINERS: https://github.com/OP-TEE/optee_os/blob/master/MAINTAINERS
+.. _repo: https://source.android.com/source/downloading.html
+
+.. Links to devices etc:
+.. _ARM Juno Board: http://www.arm.com/products/tools/development-boards/versatile-express/juno-arm-development-platform.php
+.. _ARM Foundation FVP: http://www.arm.com/fvp
+.. _HiKey Kirin 620: https://www.96boards.org/products/hikey
+.. _HiKey 960: https://www.96boards.org/product/hikey960
+.. _MediaTek MT8173 EVB Board: http://www.mediatek.com/en/products/mobile-communications/tablet/mt8173
+.. _Poplar: https://www.96boards.org/product/poplar/
+.. _QEMU: http://wiki.qemu.org/Main_Page
+.. _QEMUv8: http://wiki.qemu.org/Main_Page
+.. _Raspberry Pi 3: https://www.raspberrypi.org/products/raspberry-pi-3-model-b
+.. _Texas Instruments DRA7xx: http://www.ti.com/product/DRA746
+.. _Texas Instruments AM57xx: http://www.ti.com/product/AM5728
+.. _Texas Instruments AM43xx: http://www.ti.com/product/AM4379
diff --git a/building/gits/index.rst b/building/gits/index.rst
new file mode 100644
index 0000000..9826394
--- /dev/null
+++ b/building/gits/index.rst
@@ -0,0 +1,20 @@
+.. _optee_gits:
+
+###########
+OP-TEE gits
+###########
+
+These are the gits considered as the main OP-TEE gits which together makes up
+the entire TEE solution.
+
+.. toctree::
+ :maxdepth: 1
+
+ build
+ manifest
+ optee_benchmark
+ optee_client
+ optee_docs
+ optee_examples/optee_examples
+ optee_os
+ optee_test
diff --git a/building/gits/manifest.rst b/building/gits/manifest.rst
new file mode 100644
index 0000000..f49029c
--- /dev/null
+++ b/building/gits/manifest.rst
@@ -0,0 +1,112 @@
+.. _manifest:
+
+########
+manifest
+########
+This page contains a couple of guidelines and rules that we want to try to
+follow when it comes to managing the manifests.
+
+git location
+************
+https://github.com/OP-TEE/manifest
+
+Remotes
+*******
+Since most of our projects can be found on GitHub, we are using that as the main
+remote. If you need to include other remotes for some reason, then that is OK,
+but please double check of there is any **maintained** (and preferably official)
+mirror for the project at GitHub before adding a new remote.
+
+Sections
+********
+To have some kind of structure of the files, we have split them up in three
+sections, one for pure OP-TEE gits, one for OP-TEE supporting gits found at
+`linaro-swg`_ and then a third, ``misc`` section where everything else can be
+found. I.e., a template looks like this (this also includes the default remote
+for clarity):
+
+.. code-block:: xml
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <manifest>
+ <remote name="github" fetch="https://github.com" />
+
+ <default remote="github" revision="master" />
+
+ <!-- OP-TEE gits -->
+ <!-- linaro-swg gits -->
+ <!-- Misc gits -->
+ </manifest>
+
+Project XML elements
+********************
+All ``<projects ... >`` lines should be on the format as shown below with the
+attributes in this order. The reason for this is to have it uniformly done
+across all manifests and that it will make it easier when comparing various
+versions of manifests with diff tools. All three attributes are **mandatory**.
+The only exception is ``revision`` which does not have to be stated if it is
+``master`` that we are tracking.
+
+.. code-block:: xml
+
+ <project path="name_and_path_on_disk" name="upstream_name.git" revision="git_revsion" />
+
+Alphabetic order
+****************
+Within each of the three sections, all ``<project ... >`` lines **shall** be
+sorted in alphabetic order (this is again for making it easier to diff
+manifests). The only expection here is ``build.git`` which uses the ``linkfile``
+element. Having that at the end makes it look cleaner.
+
+Additional XML attributes
+*************************
+If you are using another remote than the default, then that should come
+**after** the ``revision`` attribute (this is true for all attributes other than
+the ``path``, ``name`` and ``revision``).
+
+Alignment of XML attributes
+***************************
+The three mandatory XML attributes ``path``, ``name`` and ``revision`` should be
+column aligned. Alignment of additional XML attributes are optional.
+
+When to use clone-depth="1"?
+****************************
+With ``clone-depth="1"`` you are telling ``repo`` and ``git`` that you only want
+a certain commit and not the entire git log history. You can only use this under
+two conditions and that is when ``revision`` is either a branch or a tag. Pure
+``SHA-1's`` does not work and will even raise ``repo`` and ``git`` sync errors
+in some cases. So, the rules are, if you use either
+``revision="refs/tags/my_tag"`` or ``revision="refs/heads/my_branch"``, then you
+shall add ``clone-depth="1"`` right after the ``revision`` attribute.
+
+Spaces or tabs?
+***************
+**Only** use spaces!
+
+Example
+*******
+Here is an example showing the basis for an OP-TEE manifest. The names are
+fictive etc, but it describes everything said above.
+
+.. code-block:: xml
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <manifest>
+ <remote name="github" fetch="https://github.com" />
+ <remote name="other" fetch="https://someotherlocation.com" />
+
+ <default remote="github" revision="master" />
+
+ <!-- OP-TEE gits -->
+ <project path="optee_abc" name="OP-TEE/optee_abc.git" />
+ <project path="optee_def" name="OP-TEE/optee_def.git" />
+
+ <!-- linaro-swg gits -->
+ <project path="lswg_abc" name="linaro-swg/lswg-abc.git" revision="aaaabbbbcccc93e64c2fdd6ae8b0be14a8c45719" />
+ <project path="lswg_def" name="linaro-swg/lswg-def.git" revision="ddddeeeeffff83e64c2fdd6ae8b0be14a8c45719" />
+
+ <!-- Misc gits -->
+ <project path="my_other" name="my_other.git" revision="refs/tags/2017.11" clone-depth="1" remote="other" />
+ </manifest>
+
+.. _linaro-swg: https://github.com/linaro-swg
diff --git a/building/gits/optee_benchmark.rst b/building/gits/optee_benchmark.rst
new file mode 100644
index 0000000..f099a2c
--- /dev/null
+++ b/building/gits/optee_benchmark.rst
@@ -0,0 +1,60 @@
+.. _optee_benchmark:
+
+###############
+optee_benchmark
+###############
+This page describes how to get and build the OP-TEE benchmark framework. For the
+architectural details, please refer to the :ref:`benchmark_framework` page
+instead.
+
+git location
+************
+https://github.com/linaro-swg/optee_benchmark
+
+License
+*******
+.. todo::
+
+ Joakim: Necessary to state that here? Changing the "License headers" page to
+ instead become a "License" page and add addtional sections.
+
+The software is provided under the `BSD 2-Clause`_ license.
+
+Build instructions
+******************
+The benchmark framework spans across different architectural layers and
+therefore it doesn't make much sense to build it as a standalone build.
+Therefore we only give guidance telling how to enable it in full OP-TEE
+developer builds. For general instructions for full OP-TEE developer builds,
+please refer to instructions at the :ref:`build` page. But otherwise follow the
+instructions below to enable the benchmark framework.
+
+Enable the benchmark framework
+==============================
+Before using Benchmark framework, OP-TEE should be rebuilt with the
+``CFG_TEE_BENCHMARK`` flag enabled so that the benchmark framework will be
+enabled in all architectural layers. You do that by:
+
+.. code-block:: bash
+
+ $ cd <optee-project>/build
+ $ make CFG_TEE_BENCHMARK=y
+
+Benchmark application usage
+===========================
+When everything has been built (flashed) and you have booted up the device and
+you have a console ready to accept command, then the next step is to run the
+actual benchmark application together with the host/TA application you intend to
+benchmark. You do this my giving the host applicant as argument to the
+optee_benchmark binary. Let's say for example that you intend to benchmark the
+:ref:`hello_world` example. Then you invoke the benchmark like this:
+
+.. code-block:: bash
+
+ $ benchmark hello_world
+
+When client_app finish the execution, optee_benchmark will generate
+``<client_app>.ts`` time stamp data file in the same directory, where Client
+Application is stored (i.e., relative to `hello_world` in this case).
+
+.. _BSD 2-Clause: http://opensource.org/licenses/BSD-2-Clause
diff --git a/building/gits/optee_client.rst b/building/gits/optee_client.rst
new file mode 100644
index 0000000..b9ba83f
--- /dev/null
+++ b/building/gits/optee_client.rst
@@ -0,0 +1,116 @@
+.. _optee_client:
+
+############
+optee_client
+############
+optee_client git contains the source code for the TEE client library in Linux.
+This component provides the TEE Client API as defined by the GlobalPlatform TEE
+standard. It is distributed under the BSD 2-clause open source license.
+
+In this git there are two main targets/binaries to build. There is
+``libteec.so``, which is the library that contains that API for communication
+with the Trusted OS. Then there is ``tee-supplicant`` which is a daemon serving
+the Trusted OS in secure world with miscellaneous features, such as file system
+access.
+
+git location
+************
+https://github.com/OP-TEE/optee_client
+
+License
+*******
+.. todo::
+
+ Joakim: Necessary to state that here? Changing the "License headers" page to
+ instead become a "License" page and add addtional sections.
+
+The software is provided under the `BSD 2-Clause`_ license.
+
+Build instructions
+******************
+You can build the code in this git only or build it as part of the entire
+system, i.e. as a part of a full OP-TEE developer setup. For the latter, please
+refer to instructions at the :ref:`build` page. For standalone builds we
+currently support building with both CMake as well as with regular GNU
+Makefiles.
+
+Configure the toolchain
+=======================
+First step is to download and configure a toolchain, see the :ref:`toolchains`
+page for instructions.
+
+Clone optee_client
+==================
+.. code-block:: bash
+
+ $ git clone https://github.com/OP-TEE/optee_client
+ $ cd optee_client
+
+Build using CMake
+=================
+.. code-block:: bash
+
+ $ mkdir build
+ $ cd build
+ $ cmake -DCMAKE_C_COMPILER=arm-linux-gnueabihf-gcc ..
+ $ make
+
+.. note::
+
+ This example uses the 32-bit toolchain (arm-linux-gnueabihf-), the same
+ works using the 64-bit toolchain (aarch64-linux-gnu-).
+
+After this step the compiled binaries can be sound in sub-folders of ``build``.
+If you have a need or preference to install the binaries at some specific
+location, then on the cmake line above add
+``-DCMAKE_INSTALL_PREFIX=<my-install-path>`` as an additional argument. With
+that you can then run ``make install`` and the binaries etc will be copied to
+the location that you gave as an argument. In this example
+``/tmp/optee_client``.
+
+.. code-block:: bash
+
+ $ cmake -DCMAKE_C_COMPILER=arm-linux-gnueabihf-gcc -DCMAKE_INSTALL_PREFIX=/tmp/optee_client ..
+ $ make
+ $ make install
+
+Build using GNU Make
+====================
+The ``Makefile`` is configured to use ``arm-linux-gnueabihf-`` by default.
+
+.. code-block:: bash
+
+ $ make
+
+.. note::
+
+ For a 64-bit builds (or any other toolchain) you will need to use
+ ``CROSS_COMPILE``.
+
+ ``$ make CROSS_COMPILE=aarch64-linux-gnu-``
+
+After this step the compiled binaries can be found in the sub-folder ``out``.
+
+
+Compiler flags
+**************
+To be able to see all commands when building you could build using following
+flags:
+
+**GNU Make**
+
+.. code-block:: bash
+
+ $ make V=1
+
+**CMake**
+
+.. code-block:: bash
+
+ $ make VERBOSE=1
+
+Coding standards
+****************
+See :ref:`coding_standards`.
+
+.. _BSD 2-Clause: http://opensource.org/licenses/BSD-2-Clause
diff --git a/building/gits/optee_docs.rst b/building/gits/optee_docs.rst
new file mode 100644
index 0000000..d002dac
--- /dev/null
+++ b/building/gits/optee_docs.rst
@@ -0,0 +1,135 @@
+.. _optee_docs:
+
+##########
+optee_docs
+##########
+This is the Git where all official OP-TEE documentation resides and this is what
+you are reading right now. Here we will give instructions on how to write and
+build the documentation as well as give some guidelines on what to do and not to
+do. Note that the documentation is written for Sphinx_. So, even though GitHub
+for example renders ``*.rst`` files somewhat OK, that is still not the preferred
+way to read and view the documentation. Instead head over to
+https://optee.readthedocs.io where the final output is stored and nicely
+rendered using Sphinx.
+
+git location
+************
+https://github.com/OP-TEE/optee_docs
+
+Install Sphinx
+**************
+Before doing anything else, first install Sphinx and the dependencies.
+
+.. code-block:: bash
+
+ $ sudo apt install graphviz python3-sphinx python3-sphinx-rtd-theme
+
+Build optee_docs
+****************
+.. code-block:: bash
+
+ $ git clone https://github.com/OP-TEE/optee_docs
+ $ cd optee_docs
+ $ make html
+
+After this step all documentation should have been built and you can open
+``<optee_docs>/_build/html/index.html`` in your browser to see the result and
+browse the documentation.
+
+.. hint::
+
+ By using a Linux tool called ``entr``. You can automatically rebuild the
+ pages your are working with. First get the package ``$ sudo apt install
+ entr``, then:
+
+ .. code-block:: bash
+
+ $ cd <optee_docs>
+ $ find . -name "*.rst" | entr -c make html
+
+ With this, ``entr`` will automatically rebuild the documentation everytime
+ you make change and save a file. Which means you only have to save the file
+ in your editor and refresh the browser page to see the changes locally.
+
+General guidelines
+******************
+
+Linking
+=======
+
+Internal links
+--------------
+Internally within a Sphinx project you can link various pages by referring to a
+keyword specified right above a section, chapter or subsection. This means that
+you don't have to make hardlinks to certain files. Instead Sphinx will just
+figure out where it is for you. Example I have to files, file `compiler.rst` and
+`toolchain.rst`. They could look like this:
+
+compiler.rst example
+^^^^^^^^^^^^^^^^^^^^
+.. code-block:: rst
+ :linenos:
+ :emphasize-lines: 6, 8
+
+ ########
+ Compiler
+ ########
+ Bla bla bla
+
+ .. _compiler_flags:
+
+ Compiler Flags
+ **************
+
+toolchain.rst example
+^^^^^^^^^^^^^^^^^^^^^
+.. code-block:: rst
+ :linenos:
+ :emphasize-lines: 5
+
+ ########
+ Toolchain
+ ########
+ Bla bla bla to see find out more about various flags, please refer
+ :ref:`compiler_flags`.
+
+
+What we can see in the example, is that on line 5 in ``toolchain.rst`` we refer
+to the keyword in ``compiler.rst`` by using ``:ref:`compiler_flags```. This
+would render a direct link to that section in ``compiler.rst``.
+
+General recommendation for OP-TEE internal linking
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ - Things about general things doesn't have to be prefixed with the "document
+ name".
+
+ - Things that are specific should be prefixed with the "document name".
+
+Example: the "Contact" section is generic so it's there is no need for prefix.
+But for example HiKey 620 build instructions are specific to HiKey 620, so there
+we shall prefix keyword for internal linking.
+
+rst files
+---------
+The rst files should have descriptive names, but even more important is where
+you decide to put the files. Even though it's not a problem to move files
+around, we have to remember that we tend to quite often give links to
+documentation from at GitHub, emails etc. If we move files, there is a high
+likelihood that they will become dead links in the future (404's). So think
+twice before adding a new file or moving an existing file.
+
+Sections, chapters
+------------------
+We have adopted the Sphinx recommended way of using sections, chapters,
+subsections etc, those are:
+
+ - # with overline, for parts
+ - \* with overline, for chapters
+ - =, for sections
+ - \-, for subsections
+ - ^, for subsubsections
+ - ", for paragraphs
+
+
+.. _Sphinx: http://www.sphinx-doc.org
diff --git a/building/gits/optee_examples/hotp.rst b/building/gits/optee_examples/hotp.rst
new file mode 100644
index 0000000..9503d73
--- /dev/null
+++ b/building/gits/optee_examples/hotp.rst
@@ -0,0 +1,61 @@
+**HMAC based One Time Password in OP-TEE**
+
+HMAC_ based One Time Passwords or shortly just 'HOTP' has been around for many
+years and was initially defined in RFC4226_ back in 2005. Since then it has been
+a popular choice for doing `two factor authentication`_. With the implementation
+here we are showing how one could leverage OP-TEE for generating such HMAC based
+One Time Passwords in a secure manner.
+
+Client (OP-TEE) / Server solution
+---------------------------------
+The most common way of using HOTP is in a client/server setup, where the client
+needs to authenticate itself to be able to get access to some resources on the
+server. In those cases the server will ask for an One Time Password, the client
+will generate that and send it over to the server and if the server is OK with
+the password it will grant access to the client.
+
+Technically how it is working is that the server and the client needs to agree
+on shared key ('``K``') and also start from the same counter ('``C``'). How that
+is done in practice is another topic, but RFC4226_ has some discussion about it.
+You should at least have a secure channel between the client and the server when
+sharing the key, but even better would be if you could establish a secure
+channel all the way down to the TEE (currently we have TCP/UDP support in
+OP-TEE, but not TLS).
+
+When both the server and the client knows about and use the same key and counter
+they can start doing client authentication using HOTP. In short what happens is
+that both the client and the server computes the same HOTP and the server
+compares the result of both computations (which should be the same to grant
+access). How that could work can be seen in the sequence diagram below.
+
+In the current implementation we have OP-TEE acting as a client and the server
+is a remote service running somewhere else. There is no server implemented, but
+that should be pretty easy to add in a real scenario. The important thing here
+is to be able to register the shared key in the TEE and to get HOTP values from
+the TEE on request.
+
+Since the current implementation works as a client we do not need to think about
+implementing the look-ahead synchronization window ('``s``') nor do we have to
+think about adding throttling (which prevents/slows down brute force attacks).
+
+Sequence diagram - Client / Server
+----------------------------------
+.. figure:: ../../../images/hotp/sequence_diagram_01.png
+
+Client / Server (OP-TEE)?
+-------------------------
+Even though the current implementation works as a HOTP client, there is nothing
+saying that the implementation cannot be updated to also work as the validating
+server. One could for example have a simple device (a [security token] only
+generating one time passwords) and use the TEE as a validating service to open
+up other secure services.
+
+.. _HMAC: https://en.wikipedia.org/wiki/Hash-based_message_authentication_code
+.. _RFC4226: https://www.ietf.org/rfc/rfc4226.txt
+.. _security token: https://en.wikipedia.org/wiki/Security_token
+.. _two factor authentication: https://en.wikipedia.org/wiki/Multi-factor_authentication
+
+.. todo::
+
+ <!--- The link below to mscgen.js.org should be updated when regenerating the image -->
+ [link to sequence diagram]: https://mscgen.js.org/?lang=xu&msc=msc%20%7B%0A%20%20wordwraparcs%3Doff%2C%0A%20%20hscale%3D%220.95%22%2C%0A%20%20watermark%3D%22HOTP%20OP-TEE%20%22%3B%0A%0A%20%20tee%20%5Blabel%3D%22TEE%20%2F%20TA%22%2C%20linecolor%3D%22darkgreen%22%2C%20textcolor%3D%22white%22%2C%20textbgcolor%3D%22darkgreen%22%2C%20arclinecolor%3D%22darkgreen%22%2C%20arctextcolor%3D%22darkgreen%22%5D%2C%0A%20%20client%20%5Blabel%3D%22Client%22%2C%20linecolor%3D%22darkgreen%22%2C%20textcolor%3D%22white%22%2C%20textbgcolor%3D%22darkgreen%22%2C%20arclinecolor%3D%22darkgreen%22%2C%20arctextcolor%3D%22darkgreen%22%5D%2C%0A%20%20server%20%5Blabel%3D%22Server%22%2C%20linecolor%3D%22%233a5795%22%2C%20textcolor%3D%22white%22%2C%20textbgcolor%3D%22%233a5795%22%2C%20arclinecolor%3D%22%233a5795%22%2C%20arctextcolor%3D%22%233a5795%22%5D%3B%0A%20%20%0A%20%20client%20note%20client%20%5Blabel%3D%22Shared%20key%20needs%5Cnto%20be%20handled%5Cnusing%20secure%5Cnchannels%20(TLS%2FSSL)%22%5D%3B%0A%20%20client%20%3C%3D%3E%20server%20%5Blabel%3D%22Agree%20on%20shared%20key%22%5D%3B%0A%20%20client%20%3D%3E%20tee%20%5Blabel%3D%22Store%20shared%20key%22%5D%3B%0A%20%20client%20%3D%3E%20server%20%5Blabel%3D%22Login%22%5D%3B%0A%20%20server%20%3D%3E%20client%20%5Blabel%3D%22Request%20HOTP%22%5D%3B%0A%20%20client%20%3D%3E%20tee%20%5Blabel%3D%22Get%20HOTP%20from%20TEE%22%5D%3B%0A%20%20tee%20%3E%3E%20tee%20%5Blabel%3D%22Calulate%20HOTP%22%5D%3B%0A%20%20tee%20%3E%3E%20client%20%5Blabel%3D%22HOPT%20value%22%5D%3B%0A%20%20client%20%3E%3E%20server%20%5Blabel%3D%22Send%20HTOP%20value%22%5D%3B%0A%20%20server%20%3E%3E%20server%20%5Blabel%3D%22Calulate%20HOTP%20locally%22%5D%3B%0A%20%20client%20alt%20server%20%5Blabel%3D%22Client%20HOTP%20%3D%3D%20Server%20HOTP%3F%22%2C%20linecolor%3D%22grey%22%2C%20textbgcolor%3D%22white%22%5D%20%7B%0A%20%20%09%0A%20%20%20%20---%20%5Blabel%3D%22Yes%22%2C%20linecolor%3Dgrey%2C%20textbgcolor%3Dwhite%5D%3B%0A%20%20%20%20server%20%3E%3E%20client%20%5Blabel%3D%22Grant%20access%22%5D%3B%0A%20%20%20%20%0A%20%20%20%20---%20%5Blabel%3D%22No%22%2C%20linecolor%3Dgrey%2C%20textbgcolor%3Dwhite%5D%3B%0A%20%20%20%20server%20%3E%3E%20client%20%5Blabel%3D%22Access%20denied%22%5D%3B%0A%20%20%7D%3B%0A%7D
diff --git a/building/gits/optee_examples/optee_examples.rst b/building/gits/optee_examples/optee_examples.rst
new file mode 100644
index 0000000..9bef9fb
--- /dev/null
+++ b/building/gits/optee_examples/optee_examples.rst
@@ -0,0 +1,186 @@
+.. _optee_examples:
+
+##############
+optee_examples
+##############
+This document describes the sample applications that are included in the OP-TEE,
+that aim to showcase specific functionality and use cases.
+
+For sake of simplicity, all OP-TEE example test application are prefixed with
+``optee_example_``. All of them works as standalone host and Trusted Application
+and can be found in separate directories.
+
+git location
+************
+https://github.com/linaro-swg/optee_examples
+
+License
+*******
+.. todo::
+
+ Joakim: Necessary to state that here? Changing the "License headers" page to
+ instead become a "License" page and add addtional sections.
+
+The software is provided under the `BSD 2-Clause`_ license.
+
+Build instructions
+******************
+You can build the code in this git only or build it as part of the entire
+system, i.e. as a part of a full OP-TEE developer setup. For the latter, please
+refer to instructions at the :ref:`build` page. For standalone builds we
+currently support building with both CMake as well as with regular GNU
+Makefiles. However, since the both the host and the Trusted Applications have
+dependencies to files in :ref:`optee_client` (libteec.so and headers) as well as
+:ref:`optee_os` (TA-devkit), one **must first** build those and then refer to
+various files. Below we will show to to build the **hello_world** example for
+Armv7-A using regular GNU Make.
+
+Configure the toolchain
+=======================
+First step is to download and configure a toolchain, see the :ref:`toolchains`
+page for instructions.
+
+Build the dependencies
+======================
+Then you must build :ref:`optee_os` as well as :ref:`optee_client` first. Build
+instructions for them can be found on their respective pages.
+
+Clone optee_examples
+====================
+.. code-block:: bash
+
+ $ git clone https://github.com/linaro-swg/optee_examples.git
+
+.. todo::
+
+ Joakim: We should add ...
+ Build using CMake
+ =================
+
+ But that is not really straight forward to do.
+
+Build using GNU Make
+====================
+
+Host application
+----------------
+.. code-block:: bash
+
+ $ cd optee_examples/hello_world/host
+ $ make \
+ CROSS_COMPILE=arm-linux-gnueabihf- \
+ TEEC_EXPORT=<optee_client>/out/export \
+ --no-builtin-variables
+
+With this you end up with a binary ``optee_example_hello_world`` in the host
+folder where you did the build.
+
+Trusted Application
+-------------------
+
+.. code-block:: bash
+
+ $ cd optee_examples/hello_world/ta
+ $ make \
+ CROSS_COMPILE=arm-linux-gnueabihf- \
+ PLATFORM=vexpress-qemu_virt \
+ TA_DEV_KIT_DIR=<optee_os>/out/arm/export-ta_arm32
+
+With this you end up with a files named ``uuid.{ta,elf,dmp,map}`` etc in the ta
+folder where you did the build.
+
+.. note::
+
+ For a 64-bit builds (or any other toolchain) you will need to change
+ ``CROSS_COMPILE`` (and also use a ``PLATFORM`` corresponding to an Armv8-A
+ configuration).
+
+
+Coding standards
+****************
+See :ref:`coding_standards`.
+
+
+Example applications
+********************
+
+acipher
+=======
+
+ ================================ ========================================
+ Application name UUID
+ ================================ ========================================
+ ``optee_example_acipher`` ``a734eed9-d6a1-4244-aa50-7c99719e7b7b``
+ ================================ ========================================
+
+Generates an RSA key pair of specified size and encrypts a supplied string with
+it using the GlobalPlatform TEE Internal Core API.
+
+aes
+===
+
+ ================================ ========================================
+ Application name UUID
+ ================================ ========================================
+ ``optee_example_aes`` ``5dbac793-f574-4871-8ad3-04331ec17f24``
+ ================================ ========================================
+
+Runs an AES encryption and decryption from a TA using the GlobalPlatform TEE
+Internal Core API. Non secure test application provides the key, initial vector
+and ciphered data.
+
+.. _hello_world:
+
+hello_world
+===========
+
+ ================================ ========================================
+ Application name UUID
+ ================================ ========================================
+ ``optee_example_hello_world`` ``8aaaf200-2450-11e4-abe2-0002a5d5c51b``
+ ================================ ========================================
+
+This is a very simple Trusted Application to answer a hello command and
+incrementing an integer value.
+
+hotp
+====
+
+ ================================ ========================================
+ Application name UUID
+ ================================ ========================================
+ ``optee_example_hotp`` ``484d4143-2d53-4841-3120-4a6f636b6542``
+ ================================ ========================================
+
+.. include:: hotp.rst
+
+random
+======
+
+ ================================ ========================================
+ Application name UUID
+ ================================ ========================================
+ ``optee_example_random`` ``b6c53aba-9669-4668-a7f2-205629d00f86``
+ ================================ ========================================
+
+Generates a random UUID using capabilities of TEE API
+(``TEE_GenerateRandom()``).
+
+secure_storage
+==============
+
+ ================================ ========================================
+ Application name UUID
+ ================================ ========================================
+ ``optee_example_secure_storage`` ``f4e750bb-1437-4fbf-8785-8d3580c34994``
+ ================================ ========================================
+
+A Trusted Application to read/write raw data into the OP-TEE secure storage
+using the GlobalPlatform TEE Internal Core API.
+
+Further reading
+***************
+Some additional information about how to write and compile Trusted Applications
+can be found at the :ref:`build_trusted_applications` page.
+
+.. _BSD 2-Clause: http://opensource.org/licenses/BSD-2-Clause
diff --git a/building/gits/optee_os.rst b/building/gits/optee_os.rst
new file mode 100644
index 0000000..f893ec2
--- /dev/null
+++ b/building/gits/optee_os.rst
@@ -0,0 +1,484 @@
+.. _optee_os:
+
+########
+optee_os
+########
+
+git location
+************
+https://github.com/OP-TEE/optee_os
+
+License
+*******
+.. todo::
+
+ Joakim: Necessary to state that here? Changing the "License headers" page to
+ instead become a "License" page and add addtional sections.
+
+The TEE core of optee_os is provided under the `BSD 2-Clause`_ license. But
+there are also other software such as libraries included in optee_os. This
+"other" software will have different licenses that are compatible with BSD
+2-Clause (i.e., non-contaminating licenses unlike GPL-v2 for example).
+
+.. _optee_os_build_system:
+
+Build instructions
+******************
+You can build the code in this git only or build it as part of the entire
+system, i.e. as a part of a full OP-TEE developer setup. For the latter, please
+refer to instructions at the :ref:`build` page. For standalone builds optee_os
+uses only regular GNU Makefiles (i.e. **no** CMake support here unlike the other
+OP-TEE gits).
+
+Configure the toolchain
+=======================
+First step is to download and configure a toolchain, see the :ref:`toolchains`
+page for instructions.
+
+Clone optee_os
+==============
+.. code-block:: bash
+
+ $ git clone https://github.com/OP-TEE/optee_os
+ $ cd optee_os
+
+Build using GNU Make
+====================
+Since optee_os supports many devices and configurations it's impossible to give
+a examples to all variants. But below is how you for example would build for
+QEMU running Armv7-A (AArch32), with debugging enabled and the benchmark
+framework disabled and will put all built files in a folder name `out/arm` in
+the root of the git.
+
+.. code-block:: bash
+ :linenos:
+
+ $ make \
+ CFG_TEE_BENCHMARK=n \
+ CFG_TEE_CORE_LOG_LEVEL=3 \
+ CROSS_COMPILE=arm-linux-gnueabihf- \
+ CROSS_COMPILE_core=arm-linux-gnueabihf- \
+ CROSS_COMPILE_ta_arm32=arm-linux-gnueabihf- \
+ CROSS_COMPILE_ta_arm64=aarch64-linux-gnu- \
+ DEBUG=1 \
+ O=out/arm \
+ PLATFORM=vexpress-qemu_virt
+
+The same for an QEMU Armv8-A (AArch64) would look like this:
+
+.. code-block:: bash
+ :linenos:
+ :emphasize-lines: 1,3,4,11
+
+ $ make \
+ CFG_ARM64_core=y \
+ CFG_TEE_BENCHMARK=n \
+ CFG_TEE_CORE_LOG_LEVEL=3 \
+ CROSS_COMPILE=aarch64-linux-gnu- \
+ CROSS_COMPILE_core=aarch64-linux-gnu- \
+ CROSS_COMPILE_ta_arm32=arm-linux-gnueabihf- \
+ CROSS_COMPILE_ta_arm64=aarch64-linux-gnu- \
+ DEBUG=1 \
+ O=out/arm \
+ PLATFORM=vexpress-qemu_armv8a
+
+.. hint::
+
+ To be able to see all commands when building you could build with:
+
+ .. code-block:: bash
+
+ $ make V=1
+
+Coding standards
+****************
+See :ref:`coding_standards`.
+
+Build system
+************
+The build system in optee_os consists of a main ``Makefile`` in the root of the
+project together with ``sub.mk`` files in all source directories. In addition,
+some supporting files are used to recursively process all ``sub.mk`` files and
+generate the build rules.
+
++------------------------------------------------+-------------------------------+
+| Name | Description |
++================================================+===============================+
+| ``core/core.mk`` | Included from ``Makefile`` to |
+| | build the TEE Core |
++------------------------------------------------+-------------------------------+
+| ``ta/ta.mk`` | Included from ``Makefile`` to |
+| | create the TA devkit |
++------------------------------------------------+-------------------------------+
+| ``mk/compile.mk`` | Create rules to make objects |
+| | from source files |
++------------------------------------------------+-------------------------------+
+| ``mk/lib.mk`` | Create rules to make a |
+| | libraries (.a) |
++------------------------------------------------+-------------------------------+
+| ``mk/subdir.mk`` | Process ``sub.mk`` files |
+| | recursively |
++------------------------------------------------+-------------------------------+
+| ``mk/config.mk`` | Global configuration variable |
++------------------------------------------------+-------------------------------+
+| ``core/arch/$(ARCH)/$(ARCH).mk`` | Arch-specific compiler flags |
++------------------------------------------------+-------------------------------+
+| ``core/arch/$(ARCH)/plat-$(PLATFORM)/conf.mk`` | Platform-specific compiler |
+| | flags and configuration |
+| | variables |
++------------------------------------------------+-------------------------------+
+| ``core/arch/$(ARCH)/plat-$(PLATFORM)/link.mk`` | Make recipes to link the TEE |
+| | Core |
++------------------------------------------------+-------------------------------+
+| ``ta/arch/arm/link.mk`` | Make recipes to link Trusted |
+| | Applications |
++------------------------------------------------+-------------------------------+
+| ``ta/mk/ta_dev_kit.mk`` | Main Makefile to be included |
+| | when building Trusted |
+| | Applications |
++------------------------------------------------+-------------------------------+
+| ``mk/checkconf.mk`` | Utility functions to |
+| | manipulate configuration |
+| | variables and generate |
+| | a C header file |
++------------------------------------------------+-------------------------------+
+| ``sub.mk`` | List source files and define |
+| | compiler flags |
++------------------------------------------------+-------------------------------+
+
+``make`` is always invoked from the top-level directory; there is no recursive
+invocation of make itself.
+
+Choosing the build target
+=========================
+The target architecture, platform and build directory may be selected by setting
+environment or make variables (``VAR=value make`` or ``make VAR=value``).
+
+ARCH - CPU architecture
+-----------------------
+``$(ARCH)`` is the CPU architecture to be built. Currently, the only supported
+value is ``arm`` for 32-bit or 64-bit Armv7-A or Armv8-A. Please note that
+contrary to the Linux kernel, ``$(ARCH)`` should **not** be set to ``arm64`` for
+64-bit builds. The ``ARCH`` variable does not need to be set explicitly before
+building either, because the proper instruction set is selected from the
+``$(PLATFORM)`` value. For platforms that support both 32-bit and 64-bit builds,
+``CFG_ARM64_core=y`` should be set to select 64-bit and not set (or set to
+``n``) to select 32-bit.
+
+Architecture-specific source code belongs to sub-directories that follow the
+``arch/$(ARCH)`` pattern, such as: ``core/arch/arm``, ``lib/libmpa/arch/arm``,
+``lib/libutee/arch/arm`` and so on.
+
+CROSS_COMPILE
+-------------
+``$(CROSS_COMPILE)`` is the prefix used to invoke the (32-bit) cross-compiler
+toolchain. The default value is ``arm-linux-gnueabihf-``. This is the variable
+you want to change in case you want to use ccache_ to speed you recompilations:
+
+.. code-block:: bash
+
+ $ make CROSS_COMPILE="ccache arm-linux-gnueabihf-"
+
+If the build includes a mix of 32-bit and 64-bit code, for instance if you set
+``CFG_ARM64_core=y`` to build a 64-bit secure kernel, then two different
+toolchains are used, that are controlled by ``$(CROSS_COMPILE32)`` and
+``$(CROSS_COMPILE64)``. The default value of ``$(CROSS_COMPILE32)`` is the value
+of ``CROSS_COMPILE``, which defaults to ``arm-linux-gnueabihf-`` as mentioned
+above. The default value of ``$(CROSS_COMPILE64)`` is ``aarch64-linux-gnu-``.
+Examples:
+
+.. code-block:: bash
+
+ # For this example, select HiKey which supports both 32- and 64-bit builds
+ $ export PLATFORM=hikey
+
+ # 1. Build everything 32-bit
+ $ make
+
+ # 2. Same as (1.) but override the toolchain
+ $ make CROSS_COMPILE="ccache arm-linux-gnueabihf-"
+
+ # 3. Same as (2.)
+ $ make CROSS_COMPILE32="ccache arm-linux-gnueabihf-"
+
+ # 4. Select 64-bit secure 'core' (and therefore both 32- and 64-bit
+ # Trusted Application libraries)
+ $ make CFG_ARM64_core=y
+
+ # 5. Same as (4.) but override the toolchains
+ $ make CFG_ARM64_core=y \
+ CROSS_COMPILE32="ccache arm-linux-gnueabihf-" \
+ CROSS_COMPILE64="ccache aarch64-linux-gnu-"
+
+
+.. _platform_flavor:
+
+PLATFORM / PLATFORM_FLAVOR
+--------------------------
+A `platform` is a family of closely related hardware configurations. A platform
+`flavor` is a variant of such configurations. When used together they define the
+target hardware on which OP-TEE will be run.
+
+For instance ``PLATFORM=stm PLATFORM_FLAVOR=b2260`` will build for the ST
+Microelectronics 96boards/cannes2 board, while ``PLATFORM=vexpress
+PLATFORM_FLAVOR=qemu_virt`` will generate code for a para-virtualized Arm
+Versatile Express board running on QEMU.
+
+For convenience, the flavor may be appended to the platform name with a dash, so
+``make PLATFORM=stm-b2260`` is a shortcut for ``make PLATFORM=stm
+PLATFORM_FLAVOR=b2260``. Note that in both cases the value of ``$(PLATFORM)`` is
+``stm`` in the makefiles.
+
+Platform-specific source code belongs to ``core/arch/$(ARCH)/plat-$(PLATFORM)``,
+for instance: ``core/arch/arm/plat-vexpress`` or ``core/arch/arm/plat-stm``.
+
+O - output directory
+--------------------
+All output files go into a platform-specific build directory, which is by
+default ``out/$(ARCH)-plat-$(PLATFORM)``.
+
+The output directory has basically the same structure as the source tree. For
+instance, assuming ``ARCH=arm PLATFORM=stm``, ``core/kernel/panic.c`` will
+compile into ``out/arm-plat-stm/core/kernel/panic.o``.
+
+However, some libraries are compiled several times: once or twice for user mode,
+and once for kernel mode. This is because they may be used by the TEE Core as
+well as by the Trusted Applications. As a result, the ``lib`` source directory
+gives two or three build directories: ``ta_arm{32,64}-lib`` and ``core-lib``.
+
+The output directory also has an ``export-ta_arm{32,64}`` directory, which
+contains:
+
+ - All the files needed to build Trusted Applications.
+
+ - In ``lib/``: ``libutee.a`` (the GlobalPlatform Internal API),
+ ``libutils.a`` (which implements a part of the standard C library),
+ and ``libmpa.a`` (which implements multiple precision arithmetic and
+ is required by ``libutee.a``).
+
+ - In ``include/``: header files for the above libraries
+
+ - In ``mk/``: ``ta_dev_kit.mk``, which is a Make include file with
+ suitable rules to build a TA, and its dependencies
+
+ - ``scripts/sign.py``: a Python script used by ``ta_dev_kit.mk`` to sign
+ TAs.
+
+ - In ``src``: ``user_ta_header.c``: source file to add a suitable header
+ to the Trusted Application (as expected by the loader code in the TEE
+ Core).
+
+ - Some files needed to build host applications (using the Client API), under
+ ``export-ta_arm{32,64}/host_include``.
+
+Finally, the build directory contains the auto-generated configuration file for
+the TEE Core: ``$(O)/include/generated/conf.h`` (see below).
+
+.. _configuration_and_flags:
+
+Configuration and flags
+=======================
+The following variables are defined in ``core/arch/$(ARCH)/$(ARCH).mk``:
+
+ - ``$(core-platform-aflags)``, ``$(core-platform-cflags)`` and
+ ``$(core-platform-cppflags)`` are added to the assembler / C compiler /
+ preprocessor flags for all source files compiled for TEE Core including
+ the kernel versions of ``libmpa.a`` and ``libutils.a``.
+
+ - ``$(ta_arm{32,64}-platform-aflags)``, ``$(ta_arm{32,64}-platform-cflags``)
+ and ``$(ta_arm{32,64}-platform-cppflags)`` are added to the assembler / C
+ compiler / preprocessor flags when building the user-mode libraries
+ (``libutee.a``, ``libutils.a``, ``libmpa.a``) or Trusted Applications.
+
+ The following variables are defined in
+ ``core/arch/$(ARCH)/plat-$(PLATFORM)/conf.mk``:
+
+ - If ``$(arm{32,64}-platform-cflags)``, ``$(arm{32,64}-platform-aflags)``
+ and ``$(arm{32,64}-platform-cppflags)`` are defined their content will be
+ added to ``$(\*-platform-\*flags)`` when they are are initialized in
+ ``core/arch/$(ARCH)/$(ARCH).mk`` as described above.
+
+ - ``$(core-platform-subdirs)`` is the list of the subdirectories that are
+ added to the TEE Core.
+
+Linker scripts
+==============
+The file ``core/arch/$(ARCH)/plat-$(PLATFORM)/link.mk`` contains the rules to
+link the TEE Core and perform any related tasks, such as running ``objdump`` to
+produce a dump file. ``link.mk`` adds files to the ``all:`` target.
+
+Source files
+============
+Each directory that contains source files has a file called ``sub.mk``. This
+makefile defines the source files that should be included in the build, as well
+as any subdirectories that should be processed, too. For example:
+
+.. code-block:: make
+
+ # core/arch/arm/sm/sub.mk
+ srcs-y += sm_asm.S
+ srcs-y += sm.c
+
+.. code-block:: make
+
+ # core/sub.mk
+ subdirs-y += kernel
+ subdirs-y += mm
+ subdirs-y += tee
+ subdirs-y += drivers
+
+The ``-y`` suffix is meant to facilitate conditional compilation. See
+section :ref:`configuration_variables` below.
+
+``srcs-y`` and ``subdirs-y`` are often not used together in the same ``sub.mk``,
+because source files are usually alone in leaf directories. But this is not a
+hard rule.
+
+In addition to source files, ``sub.mk`` may define compiler flags, include
+directories and/or configuration variables as explained below.
+
+Compiler flags
+==============
+Default compiler flags are defined in ``mk/compile.mk``. Note that
+platform-specific flags must not appear in this file which is common to all
+platforms.
+
+To add flags for a given source file, you may use the following variables in
+``sub.mk``:
+
+ - ``cflags-<filename>-y`` for C files (\*.c)
+
+ - ``aflags-<filename>-y`` for assembler files (\*.S)
+
+ - ``cppflags-<filename>-y`` for both C and assembler
+
+For instance:
+
+.. code-block:: make
+
+ # core/lib/libtomcrypt/src/pk/dh/sub.mk
+ srcs-y += dh.c
+ cflags-dh.c-y := -Wno-unused-variable
+
+Compiler flags may also be removed, as follows:
+
+.. code-block:: make
+
+ # lib/libutils/isoc/newlib/sub.mk
+ srcs-y += memmove.c
+ cflags-remove-memmove.c-y += -Wcast-align
+
+Some variables apply to libraries only (that is, when using ``mk/lib.mk``) and
+affect all the source files that belong to the library: ``cppflags-lib-y`` and
+``cflags-lib-y``.
+
+Include directories
+===================
+Include directories may be added to ``global-incdirs-y``, in which case they
+will be accessible from all the source files and will be copied to
+``export-ta_arm{32,64}/include`` and ``export-ta_arm{32,64}/host_include``.
+
+When ``sub.mk`` is used to build a library, ``incdirs-lib-y`` may receive
+additional directories that will be used for that library only.
+
+.. _configuration_variables:
+
+Configuration variables
+=======================
+Some features may be enabled, disabled or otherwise controlled at compile time
+through makefile variables. Default values are normally provided in makefiles
+with the ``?=`` operator so that their value may be easily overridden by
+environment variables. For instance:
+
+.. code-block:: make
+
+ PLATFORM ?= stm
+ PLATFORM_FLAVOR ?= default
+
+Some global configuration variables are defined in ``mk/config.mk``, but others
+may be defined in ``sub.mk`` when then pertain to a specific library for
+instance.
+
+Variables with the ``CFG_`` prefix are treated in a special way: their value is
+automatically reflected in the generated header file
+``$(out-dir)/include/generated/conf.h``, after all the included makefiles have
+been processed. ``conf.h`` is automatically included by the preprocessor when a
+source file is built.
+
+Depending on their value, variables may be considered either boolean or
+non-boolean, which affects how they are translated into ``conf.h``.
+
+Boolean configuration variables
+-------------------------------
+When a configuration variable controls the presence or absence of a feature,
+``y`` means **enabled**, while ``n``, empty value or an undefined variable means
+**disabled**. For instance, the following commands are equivalent and would
+disable feature ``CFG_CRYPTO_GCM``:
+
+.. code-block:: bash
+
+ $ make CFG_CRYPTO_GCM=n
+
+.. code-block:: bash
+
+ $ make CFG_CRYPTO_GCM=
+
+.. code-block:: bash
+
+ $ CFG_CRYPTO_GCM=n make
+
+.. code-block:: bash
+
+ $ export CFG_CRYPTO_GCM=n
+ $ make
+
+Configuration variables may then be used directly in ``sub.mk`` to trigger
+conditional compilation:
+
+.. code-block:: make
+
+ # core/lib/libtomcrypt/src/encauth/sub.mk
+ subdirs-$(CFG_CRYPTO_CCM) += ccm
+ subdirs-$(CFG_CRYPTO_GCM) += gcm
+
+When a configuration variable is **enabled** (``y``), ``<generated/conf.h>``
+contains a macro with the same name as the variable and the value ``1``. If it
+is **disabled**, however, no macro definition is output. This allows the C code
+to use constructs like:
+
+.. code-block:: c
+
+ /* core/lib/libtomcrypt/src/tee_ltc_provider.c */
+
+ /* ... */
+
+ #if defined(CFG_CRYPTO_GCM)
+ struct tee_gcm_state {
+ gcm_state ctx; /* the gcm state as defined by LTC */
+ size_t tag_len; /* tag length */
+ };
+ #endif
+
+Non-boolean configuration variables
+-----------------------------------
+Configuration variables that are not recognized as booleans are simply output
+unchanged into `<generated/conf.h>`. For instance:
+
+.. code-block:: bash
+
+ $ make CFG_TEE_CORE_LOG_LEVEL=4
+
+.. code-block:: c
+
+ /* out/arm-plat-vexpress/include/generated/conf.h */
+
+ #define CFG_TEE_CORE_LOG_LEVEL 4 /* '4' */
+
+Configuration dependencies
+--------------------------
+Some combinations of configuration variables may not be valid. This should be
+dealt with by custom checks in makefiles. ``mk/checkconf.h`` provides functions
+to help detect and deal with such situations.
+
+.. _BSD 2-Clause: http://opensource.org/licenses/BSD-2-Clause
+.. _ccache: https://ccache.samba.org/
diff --git a/building/gits/optee_test.rst b/building/gits/optee_test.rst
new file mode 100644
index 0000000..e595b16
--- /dev/null
+++ b/building/gits/optee_test.rst
@@ -0,0 +1,198 @@
+.. _optee_test:
+
+##########
+optee_test
+##########
+The optee_test.git contains the source code for the TEE sanity test suite in
+Linux using the ARM(R) TrustZone(R) technology. It is typically referred to as
+`xtest`. By default there are several thousands of tests when running the code
+that is in the git only. However, it is also possible to incorporate tests
+coming from GlobalPlatform (see :ref:`globalplatform_tests`). We typically refer
+to these to as:
+
+ - **Standard tests**: These are the test that are included in optee_test.
+ They are free and open source.
+
+ - **Extended tests**: Those are the tests that are written directly by
+ GlobalPlatform. They are **not** open source and they are **not** freely
+ available (it's free to members of GlobalPlatform and can otherwise be
+ purchased directly from GlobalPlatform).
+
+git location
+************
+https://github.com/OP-TEE/optee_test
+
+License
+*******
+.. todo::
+
+ Joakim: Necessary to state that here? Changing the "License headers" page to
+ instead become a "License" page and add addtional sections.
+
+The client applications (``optee_test/host/*``) are provided under the
+`GPL-2.0`_ license and the user Trusted Applications (``optee_test/ta/*``) are
+provided under the `BSD 2-Clause`_.
+
+Build instructions
+******************
+At the moment you can **only** build the code in this git as part of the entire
+system, i.e. as a part of a full OP-TEE developer setup. So, please refer to
+the instructions at the :ref:`build` page to learn how to build a full OP-TEE
+developer setup. Building purely standalone is **not** possible (*) because:
+
+ - the host code (``xtest``) have dependencies to the :ref:`optee_client` (it
+ links against ``libteec``, ``openssl`` and uses various headers)
+
+ - the Trusted Applications have dependencies to the TA-devkit built by
+ :ref:`optee_os`.
+
+.. note::
+
+ (*) It is of course possible to build this without a full OP-TEE
+ developer setup, but it will require a lot of tweaking with paths, flags
+ etc. I.e., one would need to do exactly the same as the full OP-TEE
+ developer setup does under the hood.
+
+.. _globalplatform_tests:
+
+Extended test (GlobalPlatform tests)
+************************************
+One can purchase the `GlobalPlatform Compliance Test suite`_ which comes with
+.xml files describing the tests and the Trusted Applications. The standard tests
+(xtest + TA's) that are free and open source can be extended to also include the
+GlobalPlatform test suite. This is done by:
+
+ - Install the GlobalPlatform ``xml`` files in ``$CFG_GP_PACKAGE_PATH``.
+
+ - Run ``make patch`` (or call make ``xtest-patch`` from the ``build``
+ repository) before compiling xtest. This must be run a single time after the
+ installation of OP-TEE.
+
+This will:
+
+ - Create new Trusted Applications, that can be found in ``ta/GP_xxx``
+ - Create new tests in ``host/xtest``, as for example ``xtest_9000.c``
+ - Patches ``xtest_7000.c``, adding new tests.
+
+Then the tests must be compiled with ``CFG_GP_PACKAGE_PATH=<path>``.
+
+It makes use of the following environment variable:
+
+ - ``COMPILE_NS_USER``: ``32`` or ``64`` if application shall be compiled in
+ 32 bits mode on in 64 bits mode. If ``COMPILE_NS_USER`` is not specified,
+ build relies on ``CFG_ARM32_core=y`` from OP-TEE core build to assume
+ applications are in 32 bits mode, Otherwise, 64 bits mode is assumed.
+
+.. _optee_test_run_xtest:
+
+Run xtest
+*********
+It's important to understand that you run ``xtest`` on the device itself, i.e.,
+this is nothing that you run on the host machine.
+
+xtest - default
+===============
+The most simple case is to run the default configuration:
+
+.. code-block:: bash
+
+ $ xtest
+
+xtest - all
+===========
+This runs all tests within the standard xtest. Using the ``-l`` parameter you
+can tweak the amount of tests you will run. ``15`` is the most and ``0`` is the
+least.
+
+.. code-block:: bash
+
+ $ xtest -l 15
+
+xtest - single
+==============
+To run a single test case, just specify its numbers, for example:
+
+.. code-block:: bash
+
+ $ xtest 1001
+
+xtest - family
+==============
+To run a family (``1xxx``, ``2xxx`` and so on), just specify its number prefixed
+with an underscore. This for example will run the 1xxx family.
+
+.. code-block:: bash
+
+ $ xtest _1
+
+xtest - benchmark
+=================
+To run the benchmark tests, run xtest like this:
+
+.. code-block:: bash
+
+ $ xtest -t benchmark
+
+Here it is also possible to state a number for a certain benchmark test, for
+example:
+
+.. code-block:: bash
+
+ $ xtest -t benchmark 2001
+
+xtest - regression
+==================
+To run the regression tests, run xtest like this:
+
+.. code-block:: bash
+
+ $ xtest -t regression
+
+Here it is also possible to state a number for a certain regression test, for
+example:
+
+.. code-block:: bash
+
+ $ xtest -t regression 2004
+
+xtest - aes-perf
+================
+This is benchmark test for AES and you run it like this:
+
+.. code-block:: bash
+
+ $ xtest --aes-perf
+
+.. note::
+
+ There is an individual help for ``--aes-perf``, i.e.
+
+ ``$ xtest --aes-perf -h``
+
+xtest - sha-perf
+================
+This is benchmark test for SHA-xxx and you run it like this:
+
+.. code-block:: bash
+
+ $ xtest --sha-perf
+
+.. note::
+
+ There is an individual help for ``--sha-perf``, i.e.
+
+ ``$ xtest --sha-perf -h``
+
+ There you can select other SHA algorithms etc.
+
+.. todo::
+
+ Joakim: Should have a section about --install-ta also.
+
+Coding standards
+****************
+See :ref:`coding_standards`.
+
+.. _BSD 2-Clause: http://opensource.org/licenses/BSD-2-Clause
+.. _GlobalPlatform Compliance Test suite: https://store.globalplatform.org/product/tee-initial-configuration-test-suite-with-excluded-tests-list-2/
+.. _GPL-2.0: http://opensource.org/licenses/GPL-2.0
diff --git a/building/index.rst b/building/index.rst
new file mode 100644
index 0000000..094cfe7
--- /dev/null
+++ b/building/index.rst
@@ -0,0 +1,22 @@
+#############
+Build and run
+#############
+
+In this part of the documentation you will find information telling you how to
+build OP-TEE as a whole developer setup or as individual components. Likewise it
+will also tell you how to run OP-TEE on various devices.
+
+Since you pressed this, it's likely that you want to know how to build a full
+OP-TEE developer setup. So a first place to start looking is probably at the
+":ref:`build`" page to get started.
+
+.. toctree::
+ :maxdepth: 2
+
+ aosp/aosp
+ devices/index
+ linux/tee_framework
+ gits/index
+ prerequisites
+ toolchains
+ trusted_applications
diff --git a/building/linux/tee_framework.rst b/building/linux/tee_framework.rst
new file mode 100644
index 0000000..05a85b2
--- /dev/null
+++ b/building/linux/tee_framework.rst
@@ -0,0 +1,48 @@
+.. _linux_kernel:
+
+##########################
+Linux kernel TEE framework
+##########################
+
+.. todo::
+
+ Joakim: Jens to fill in information in the following sections. Eventually
+ this should be split up as two files, one under "Build and Run" and one
+ under "Architecture documentation".
+
+ History
+ - Refer to the patch when it was merged.
+ - Mention old and deprecated optee_linux driver.
+
+ Maintainer
+ - Jens and ... ?
+
+ Maillists
+ - Mention the get_maintainer script in kernel.
+ - Tee-dev? (:ref:`contact`).
+
+ Build instructions
+ - How to enable it in kernel
+
+ KConfig flags
+ - What flags to enable to run OP-TEE.
+ - Reference to :ref:`optee_benchmark`.
+
+ Device Tree
+ - What nodes/thing are important for OP-TEE.
+ - Are OP-TEE DT things upstream? If not, why?
+
+ TEE kernel Internal Client API
+ - What is it?
+ - How can I use it?
+ - Is it upstream? If not, why?
+
+ Differences between kernel.org and linaro-swg/linux
+ - Why do we have a separate fork?
+ - Features being developed.
+ - Not meant to go upstream.
+ - Should people send patches to the mailinglist or create PRs at
+ linaro-swg/linux?
+
+ External references
+ - (Links to) Documentation in the official kernel?
diff --git a/building/prerequisites.rst b/building/prerequisites.rst
new file mode 100644
index 0000000..081c7fb
--- /dev/null
+++ b/building/prerequisites.rst
@@ -0,0 +1,20 @@
+.. _prerequisites:
+
+#############
+Prerequisites
+#############
+We believe that you can use any Linux distribution to build OP-TEE, but as
+maintainers of OP-TEE we are mainly using Ubuntu-based distributions and to be
+able to build and run OP-TEE there are a few packages that needs to be installed
+to start with. Therefore install the following packages regardless of what
+target you will use in the end.
+
+.. code-block:: bash
+
+ $ sudo apt-get install android-tools-adb android-tools-fastboot autoconf \
+ automake bc bison build-essential cscope curl device-tree-compiler \
+ expect flex ftp-upload gdisk iasl libattr1-dev libc6:i386 libcap-dev \
+ libfdt-dev libftdi-dev libglib2.0-dev libhidapi-dev libncurses5-dev \
+ libpixman-1-dev libssl-dev libstdc++6:i386 libtool libz1:i386 make \
+ mtools netcat python-crypto python-serial python-wand unzip uuid-dev \
+ xdg-utils xterm xz-utils zlib1g-dev
diff --git a/building/toolchains.rst b/building/toolchains.rst
new file mode 100644
index 0000000..1d24ad7
--- /dev/null
+++ b/building/toolchains.rst
@@ -0,0 +1,63 @@
+.. _toolchains:
+
+##########
+Toolchains
+##########
+OP-TEE uses both 32bit as well as 64bit toolchains and it is even possible to
+mix them in some configurations. In theory you should be able to compile OP-TEE
+with the Arm toolchains that are coming with your Linux distribution. But
+instead of using those directly, we instead download the toolchains directly
+from Arm.
+
+Download/install
+****************
+We propose two ways to download the toolchains, both will put the toolchains
+under the same path(s).
+
+1. Direct download
+==================
+Go the `Arm GCC download page`_ and download the "`AArch32 target with soft
+float (arm-linux-gnueabi)`" for 32bit builds and the "`AArch64 GNU/Linux target
+(aarch64-linux-gnu)`" for 64bit builds. When the downloads have finished, you
+will untar them to a location that you later on will export to your ``$PATH``.
+Here is an example
+
+.. code-block:: bash
+
+ $ mkdir -p $HOME/toolchains
+ $ cd $HOME/toolchains
+
+ # Download 32bit toolchain
+ $ wget https://developer.arm.com/-/media/Files/downloads/gnu-a/8.2-2019.01/gcc-arm-8.2-2019.01-x86_64-arm-linux-gnueabi.tar.xz
+ $ mkdir aarch32
+ $ tar xf gcc-arm-8.2-2019.01-x86_64-arm-linux-gnueabi.tar.xz -C aarch32 --strip-components=1
+
+ # Download 64bit toolchain
+ $ wget https://developer.arm.com/-/media/Files/downloads/gnu-a/8.2-2019.01/gcc-arm-8.2-2019.01-x86_64-aarch64-linux-gnu.tar.xz
+ $ mkdir aarch64
+ $ tar xf gcc-arm-8.2-2019.01-x86_64-aarch64-linux-gnu.tar.xz -C aarch64 --strip-components=1
+
+2. Using build.git
+==================
+As an alternative, you can let :ref:`build`.git download them for you, but this
+of course involves getting a git that you might not otherwise use.
+
+.. code-block:: bash
+
+ $ cd $HOME
+ $ git clone https://github.com/OP-TEE/build.git
+ $ cd build
+ $ make -f toolchain.mk -j2
+
+
+Export PATH
+***********
+If you have downloaded the toolchains as described above, you should have them
+at ``$HOME/toolchains/{aarch32/aarch64}``, so now we just need to export the
+paths and then you are ready to starting compiling OP-TEE components.
+
+.. code-block:: bash
+
+ $ export PATH=$PATH:$HOME/toolchains/aarch32/bin:$HOME/toolchains/aarch64/bin
+
+.. _Arm GCC download page: https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads
diff --git a/building/trusted_applications.rst b/building/trusted_applications.rst
new file mode 100644
index 0000000..03be0c1
--- /dev/null
+++ b/building/trusted_applications.rst
@@ -0,0 +1,301 @@
+.. _build_trusted_applications:
+
+####################
+Trusted Applications
+####################
+This document tells how to implement a Trusted Application for OP-TEE, using
+OP-TEE's so called `TA-devkit` to both build and sign the Trusted Application
+binary. In this document, a `Trusted Application` running in the OP-TEE os is
+referred to as a `TA`.
+
+TA Mandatory files
+******************
+The Makefile for a Trusted Application must be written to rely on OP-TEE
+TA-devkit resources in order to successfully build the target application.
+TA-devkit is built when one builds :ref:`optee_os`.
+
+.. todo::
+
+ Joakim: We need to add CMake instructions also.
+
+To build a TA, one must provide:
+
+ - **Makefile**, a make file that should set some configuration variables and
+ include the TA-devkit make file.
+
+ - **sub.mk**, a make file that lists the sources to build (local source
+ files, subdirectories to parse, source file specific build directives).
+
+ - **user_ta_header_defines.h**, a specific ANSI-C header file to define most
+ of the TA properties.
+
+ - A implementation of at least the TA entry points, as extern functions:
+ ``TA_CreateEntryPoint()``, ``TA_DestroyEntryPoint()``,
+ ``TA_OpenSessionEntryPoint()``, ``TA_CloseSessionEntryPoint()``,
+ ``TA_InvokeCommandEntryPoint()``
+
+TA file layout example
+======================
+As an example, :ref:`hello_world` looks like this:
+
+.. code-block:: none
+
+ hello_world/
+ ├── ...
+ └── ta
+ ├── Makefile BINARY=<uuid>
+ ├── Android.mk Android way to invoke the Makefile
+ ├── sub.mk srcs-y += hello_world_ta.c
+ ├── include
+ │ └── hello_world_ta.h Header exported to non-secure: TA commands API
+ ├── hello_world_ta.c Implementaion of TA entry points
+ └── user_ta_header_defines.h TA_UUID, TA_FLAGS, TA_DATA/STACK_SIZE, ...
+
+TA Makefile Basics
+******************
+Required variables
+==================
+The main TA-devkit make file is located in in :ref:`optee_os` at
+``ta/mk/ta_dev_kit.mk``. The make file supports make targets such as ``all`` and
+``clean`` to build a TA or a library and clean the built objects.
+
+The make file expects a couple of configuration variables:
+
+TA_DEV_KIT_DIR
+ Base directory of the TA-devkit. Used the TA-devkit itself to locate its tools.
+
+BINARY and LIBNAME
+ These are exclusive, meaning that you cannot use both at the same time. If
+ building a TA, ``BINARY`` shall provide the TA filename used to load the TA.
+ The built and signed TA binary file will be named ``${BINARY}.ta``. In
+ native OP-TEE, it is the TA UUID, used by tee-supplicant to identify TAs. If
+ one is building a static library (that will be later linked by a TA), then
+ ``LIBNAME`` shall provide the name of the library. The generated library
+ binary file will be named ``lib${LIBNAME}.a``
+
+CROSS_COMPILE and CROSS_COMPILE32
+ Cross compiler for the TA or the library source files. ``CROSS_COMPILE32``
+ is optional. It allows to target AArch32 builds on AArch64 capable systems.
+ On AArch32 systems, ``CROSS_COMPILE32`` defaults to ``CROSS_COMPILE``.
+
+Optional variables
+==================
+Some optional configuration variables can be supported, for example:
+
+O
+ Base directory for build objects filetree. If not set, TA-devkit defaults to
+ **./out** from the TA source tree base directory.
+
+Example Makefile
+================
+A typical Makefile for a TA looks something like this
+
+.. code-block:: Makefile
+
+ # Append specific configuration to the C source build (here log=info)
+ # The UUID for the Trusted Application
+ BINARY=8aaaf200-2450-11e4-abe2-0002a5d5c51b
+
+ # Source the TA-devkit make file
+ include $(TA_DEV_KIT_DIR)/mk/ta_dev_kit.mk
+
+.. _build_trusted_applications_submk:
+
+sub.mk directives
+=================
+The make file expects that current directory contains a file ``sub.mk`` that is
+the entry point for listing the source files to build and other specific build
+directives. Here are a couple of examples of directives one can implement in a
+sub.mk make file:
+
+.. code-block:: Makefile
+
+ # Adds /hello_world_ta.c from current directory to the list of the source
+ # file to build and link.
+ srcs-y += hello_world_ta.c
+
+ # Includes path **./include/** from the current directory to the include
+ # path.
+ global-incdirs-y += include/
+
+ # Adds directive -Wno-strict-prototypes only to the file hello_world_ta.c
+ cflags-hello_world_ta.c-y += -Wno-strict-prototypes
+
+ # Removes directive -Wno-strict-prototypes from the build directives for
+ # hello_world_ta.c only.
+ cflags-remove-hello_world_ta.c-y += -Wno-strict-prototypes
+
+ # Adds the static library foo to the list of the linker directive -lfoo.
+ libnames += foo
+
+ # Adds the directory path to the libraries pathes list. Archive file
+ # libfoo.a is expectd in this directory.
+ libdirs += path/to/libfoo/install/directory
+
+ # Adds the static library binary to the TA build dependencies.
+ libdeps += path/to/greatlib/libgreatlib.a
+
+Android Build Environment
+*************************
+.. todo::
+
+ Joakim: Move this to the AOSP page?
+
+OP-TEE's TA-devkit supports building in an Android build environment. One can
+write an ``Android.mk`` file for the TA (stored side by side with the Makefile).
+Android's build system will parse the ``Android.mk`` file for the TA which in
+turn will parse a TA-devkit Android make file to locate TA build resources. Then
+the Android build will execute a ``make`` command to built the TA through its
+generic Makefile file.
+
+A typical ``Android.mk`` file for a TA looks like this (``Android.mk`` for
+:ref:`hello_world` is used as an example here).
+
+.. code-block:: Makefile
+
+ # Define base path for the TA sources filetree
+ LOCAL_PATH := $(call my-dir)
+
+ # Define the module name as the signed TA binary filename.
+ local_module := 8aaaf200-2450-11e4-abe2-0002a5d5c51b.ta
+
+ # Include the devikt Android mak script
+ include $(OPTEE_OS_DIR)/mk/aosp_optee.mk
+
+TA Mandatory Entry Points
+*************************
+A TA must implement a couple of mandatory entry points, these are:
+
+.. code-block:: c
+
+ TEE_Result TA_CreateEntryPoint(void)
+ {
+ /* Allocate some resources, init something, ... */
+ ...
+
+ /* Return with a status */
+ return TEE_SUCCESS;
+ }
+
+ void TA_DestroyEntryPoint(void)
+ {
+ /* Release resources if required before TA destruction */
+ ...
+ }
+
+ TEE_Result TA_OpenSessionEntryPoint(uint32_t ptype,
+ TEE_Param param[4],
+ void **session_id_ptr)
+ {
+ /* Check client identity, and alloc/init some session resources if any */
+ ...
+
+ /* Return with a status */
+ return TEE_SUCCESS;
+ }
+
+ void TA_CloseSessionEntryPoint(void *sess_ptr)
+ {
+ /* check client and handle session resource release, if any */
+ ...
+ }
+
+ TEE_Result TA_InvokeCommandEntryPoint(void *session_id,
+ uint32_t command_id,
+ uint32_t parameters_type,
+ TEE_Param parameters[4])
+ {
+ /* Decode the command and process execution of the target service */
+ ...
+
+ /* Return with a status */
+ return TEE_SUCCESS;
+ }
+
+.. _build_ta_properties:
+
+TA Properties
+*************
+Trusted Application properties shall be defined in a header file named
+``user_ta_header_defines.h``, which should contain:
+
+ - ``TA_UUID`` defines the TA uuid value
+ - ``TA_FLAGS`` define some of the TA properties
+ - ``TA_STACK_SIZE`` defines the RAM size to be reserved for TA stack
+ - ``TA_DATA_SIZE`` defines the RAM size to be reserved for TA heap (TEE_Malloc()
+ pool)
+
+Refer to :ref:`ta_properties` to understand how to configure these macros.
+
+.. _user_ta_header_defines_h:
+
+Example of a property header file
+=================================
+
+.. code-block:: c
+
+ #ifndef USER_TA_HEADER_DEFINES_H
+ #define USER_TA_HEADER_DEFINES_H
+
+ #define TA_UUID
+ { 0x8aaaf200, 0x2450, 0x11e4, \
+ { 0xab, 0xe2, 0x00, 0x02, 0xa5, 0xd5, 0xc5, 0x1b} }
+
+ #define TA_FLAGS (TA_FLAG_EXEC_DDR | \
+ TA_FLAG_SINGLE_INSTANCE | \
+ TA_FLAG_MULTI_SESSION)
+ #define TA_STACK_SIZE (2 * 1024)
+ #define TA_DATA_SIZE (32 * 1024)
+
+ #define TA_CURRENT_TA_EXT_PROPERTIES \
+ { "gp.ta.description", USER_TA_PROP_TYPE_STRING, "Foo TA for some purpose." }, \
+ { "gp.ta.version", USER_TA_PROP_TYPE_U32, &(const uint32_t){ 0x0100 } }
+
+ #endif /* USER_TA_HEADER_DEFINES_H */
+
+.. note::
+
+ It is recommended to use the ``TA_CURRENT_TA_EXT_PROPERTIES`` as above to
+ define extra properties of the TA.
+
+Checking TA parameters
+**********************
+GlobalPlatforms TEE Client APIs ``TEEC_InvokeCommand()`` and
+``TEE_OpenSession()`` allow clients to invoke a TA with some invocation
+parameters: values or references to memory buffers. It is mandatory that TA's
+verify the parameters types before using the parameters themselves. For this a
+TA can rely on the macro ``TEE_PARAM_TYPE_GET(param_type, param_index)`` to get
+the type of a parameter and check its value according to the expected parameter.
+
+For example, if a TA expects that command ID 0 comes with ``params[0]`` being a
+input value, ``params[1]`` being a output value, and ``params[2]`` being a
+in/out memory reference (buffer), then the TA should implemented the following
+sequence:
+
+.. code-block:: c
+
+ TEE_Result handle_command_0(void *session, uint32_t cmd_id,
+ uint32_t param_types, TEE_Param params[4])
+ {
+ if ((TEE_PARAM_TYPE_GET(param_types, 0) != TEE_PARAM_TYPE_VALUE_IN) ||
+ (TEE_PARAM_TYPE_GET(param_types, 1) != TEE_PARAM_TYPE_VALUE_OUT) ||
+ (TEE_PARAM_TYPE_GET(param_types, 2) != TEE_PARAM_TYPE_MEMREF_INOUT) ||
+ (TEE_PARAM_TYPE_GET(param_types, 3) != TEE_PARAM_TYPE_NONE)) {
+ return TEE_ERROR_BAD_PARAMETERS
+ }
+
+ /* process command */
+ ...
+ }
+
+ TEE_Result TA_InvokeCommandEntryPoint(void *session, uint32_t command_id,
+ uint32_t param_types, TEE_Param params[4])
+ {
+ switch (command_id) {
+ case 0:
+ return handle_command_0(session, param_types, params);
+
+ default:
+ return TEE_ERROR_NOT_SUPPORTED;
+ }
+ }