aosp: add AOSP content

Signed-off-by: Joakim Bech <joakim.bech@linaro.org>

building/aosp/aosp.rst

@@ -1,12 +1,193 @@
+.. 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 ``-squashfs`` 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.
+
+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{960}/install/README`` in the tree (available after running
+the sync scripts).
+
+    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 ``adb shell``, 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
 
-AOSP builds yada yada
+    $ su setprop sys.usb.configfs 1
+    $ stop adbd
+    $ start adbd
 
-General builds
-**************
+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.
 
-Keymaster and GateKeeper
-************************
+.. _AOSP Hikey build instructions: https://source.android.com/source/devices.html