diff --git a/README.md b/README.md
index e674ca4d749c51d2299849340bcf2223b3f8f4ba..c9423cc0500257563f477aec32d5810934bfdb48 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,250 @@
-Contains the necessary build files to handle OP-TEE for various setups, for now,
-please see
-[manifest/README.md](https://github.com/OP-TEE/manifest/blob/master/README.md)
-and [OP-TEE/README.md](https://github.com/OP-TEE/optee_os/blob/master/README.md) for instructions.
+# OP-TEE build.git
+## Contents
+1. [Introduction](#1-introduction)
+2. [Why repo?](#2-why-repo)
+3. [Here is bunch of other stuff in this git to, why?](#3-here-is-bunch-of-other-stuff-in-this-git-to-why)
+4. [How do I build using AOSP / OpenEmbedded?](#4-how-do-i-build-using-aosp--openembedded)
+5. [Platforms supported by build.git](#5-platforms-supported-by-buildgit)
+6. [Manifests](#6-manifests)
+7. [Get and build the solution](#7-get-and-build-the-solution)
+8. [FAQ](#8-faq)
+
+# 1. Introduction
+Why this particular git? Well, 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, ARM-TF, TianoCore, QEMU, BusyBox 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:<br>
+**Make it easy for newcomers to get started with OP-TEE using the devices we've
+listed in this document.**
+
+# 2. 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.
+
+# 3. Here is bunch of other stuff in this git to, why?
+If we count the number of gits used in for example a QEMU based OP-TEE setup we
+have 14 different gits in use. Either we document tiny bits in each git or we
+try to combine as much as possible in a common place. We believe it's better to
+combine as much as possible, so that it should be easy for the user of OP-TEE to
+know where to look for information. We've discussed the option of having some
+information at optee.org, but we concluded that it's quite nice to have it in
+some of our source code gits, so that the documentation is accurate for a
+certain version of OP-TEE. I.e, step back to an older stable release and the
+documentation in the git will reflect the current state at that point in time.
+So, this particular git, will contain information about how to build, deploy
+and test OP-TEE on some devices that we have in our possession. The builds that
+we cover here are as small as possible and is based on an initramfs based
+filesystem (using BusyBox) and the least amount of gits needed to boot up and
+run xtest. Since we are using repo, we will also list and describe the
+manifests we are using here.
+
+Besides that, this git also contains information that are device specific, it
+could be as simple as some tips and tricks or for example how to run JTAG on a
+certain device. We've also put the entire [FAQ] in this git.
+
+# 4. How do I build using AOSP / OpenEmbedded?
+It's possible, we have teams in Linaro doing that and we even have some limited
+experience doing such builds in the OP-TEE team. But, both of those builds are
+rather big and is a bit too much for us on daily basis. AOSP easily ends up with
++80GB builds which takes hours and OE builds we've tried ends up with 15-20GB
+and also takes quite some time. Eventually we will point to some guide in the
+future or we will include it as a subsection or something in this git.
+
+# 5. 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.md] file for contact
+information.
+
+<!-- Please keep this list sorted in alphabetic order -->
+| Platform | Composite PLATFORM flag | Publicly available? |
+|----------|-------------------------|---------------------|
+| [ARM Juno Board](http://www.arm.com/products/tools/development-boards/versatile-express/juno-arm-development-platform.php) |`PLATFORM=vexpress-juno`| Yes |
+| [ARM Foundation FVP](http://www.arm.com/fvp) |`PLATFORM=vexpress-fvp`| Yes |
+| [HiKey Board (HiSilicon Kirin 620)](https://www.96boards.org/products/hikey)|`PLATFORM=hikey`| Yes |
+| [MediaTek MT8173 EVB Board](http://www.mediatek.com/en/products/mobile-communications/tablet/mt8173)|`PLATFORM=mediatek-mt8173`| No |
+| [QEMU](http://wiki.qemu.org/Main_Page) |`PLATFORM=vexpress-qemu_virt`| Yes |
+| [QEMUv8](http://wiki.qemu.org/Main_Page) |`PLATFORM=vexpress-qemu_armv8a`| Yes |
+| [Raspberry Pi 3](https://www.raspberrypi.org/products/raspberry-pi-3-model-b) |`PLATFORM=rpi3`| Yes |
+| [Texas Instruments DRA7xx](http://www.ti.com/product/DRA746)|`PLATFORM=ti-dra7xx`| Yes |
+
+# 6. Manifests
+Here is a list of manifests for the devices currently supported.
+
+| Target | Latest (non-stable) | Stable |
+|--------|---------------------|--------|
+| QEMU | `default.xml` | `default_stable.xml` |
+| QEMUv8 | `qemu_v8.xml` | `qemu_v8_stable.xml` |
+| FVP | `fvp.xml` | `fvp_stable.xml` |
+| HiKey | `hikey.xml` | `hikey_stable.xml` |
+| HiKey Debian | `hikey_debian.xml` | `hikey_debian_stable.xml` |
+| MediaTek MT8173 EVB Board | `mt8173-evb.xml` | `mt8173-evb_stable.xml` |
+| ARM Juno board| `juno.xml` | `juno_stable.xml` |
+| Raspberry Pi 3 | `rpi3.xml` | `rpi3_stable.xml` |
+
+# 7. Get and build the solution
+Below we will describe the general way of getting the source, building the
+solution and how to run xtest on the device. For device specific instructions,
+see the respective `device.md` file in the [devices] folder.
+
+## 7.1 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.
+
+```bash
+$ sudo apt-get install android-tools-adb android-tools-fastboot autoconf bc \
+	bison build-essential cscope curl flex ftp-upload gdisk libattr1-dev \
+	libc6:i386 libcap-dev libfdt-dev libftdi-dev libglib2.0-dev \
+	libhidapi-dev libncurses5-dev libpixman-1-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
+```
+
+## 7.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,
+could be found in the Google [repo] pages, so follow those instructions before
+continuing.
+
+## 7.3 Get the source code
+Choose the manifest corresponding to the platform you intend to use. For
+example, if you intend to use Raspberry Pi3, then `${TARGET}.xml` should be
+`rpi3.xml`. The `repo sync` step will take some time if you aren't referencing
+an existing tree (see Tips and Tricks below).
+
+```bash
+$ mkdir -p $HOME/devel/optee
+$ cd $HOME/devel/optee
+$ repo init -u https://github.com/OP-TEE/manifest.git -m ${TARGET}.xml [-b ${BRANCH}]
+$ repo sync
+```
+## 7.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:
+```bash
+$ cd build
+$ make toolchains
+```
+
+## 7.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:
+
+```bash
+$ make all run
+```
+This step will also take some time, but you can speed up subsequent builds by
+enabling [ccache] (again see Tips and Tricks).
+
+## 7.6 Flash the device
+On non-emulated solutions, you will need to flash the software in some way.
+We've tried to "hide" that under the following make target:
+```bash
+$ make flash
+```
+But, since some devices are trickier to flash than others, please see the device
+specific files. See this just as a general instruction.
+
+## 7.7 Boot up the device
+This is device specific.
+
+## 7.8 Load tee-supplicant
+On some solutions tee-supplicant is already loaded (`$ ps aux | grep
+tee-supplicant`) on other not. If it's not loaded, then start it by running:
+```bash
+$ tee-supplicant &
+```
+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.
+
+## 7.9 Run xtest
+The entire xtest test suite has been deployed when you we're running `$ make
+run` in previous step, i.e, in general there is no need to copy any binaries
+manually. Everything has been put into the root FS automatically. So, to run
+xtest, you simply type:
+```bash
+$ xtest
+```
+
+If there are no regressions / issues found, xtest should end with something like
+this:
+```bash
++-----------------------------------------------------
+23476 subtests of which 0 failed
+67 test cases of which 0 failed
+0 test case was skipped
+TEE test application done!
+```
+
+## 7.10 Tips and Tricks
+### 7.10.1 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 20 seconds
+instead of an hour. 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 roughly an hour.
+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, the only difference is that you reference the other local
+   forest when running `repo init`, like this
+   ```
+   repo init -u https://github.com/OP-TEE/manifest.git --reference /home/jbech/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 step 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.
+
+### 7.10.2 Use ccache
+ccache isfaqa 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:
+```
+$ 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.
+
+# 8. FAQ
+Please have a look at out [FAQ] file for a list of questions commonly asked.
+
+[ccache]: https://ccache.samba.org
+[devices]: devices
+[FAQ]: faq.md
+[git submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
+[manifest/README.md]: https://github.com/OP-TEE/manifest/blob/master/README.md
+[MAINTAINERS.md]: https://github.com/OP-TEE/optee_os/blob/master/MAINTAINERS.md
+[OP-TEE/README.md]: https://github.com/OP-TEE/optee_os/blob/master/README.md
+[repo]: https://source.android.com/source/downloading.html