docs: Document how to build and install Android drivers.

This is what I've been using so far.

Reviewed-by: Kristian H. Kristensen <hoegsberg@google.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/7227>

diff --git a/docs/android.rst b/docs/android.rst
new file mode 100644 (file)
index 0000000..1d41d32
--- /dev/null
+++ b/docs/android.rst
@@ -0,0 +1,167 @@
+Android
+=======
+
+Mesa hardware drivers can be built for Android one of two ways: built
+into the Android OS using the Android.mk build sytem on older versions
+of Android, or out-of-tree using the Meson build system and the
+Android NDK.
+
+The Android.mk build system has proven to be hard to maintain, as one
+needs a built Android tree to build against, and it has never been
+tested in CI.  The meson build system flow is frequently used by
+Chrome OS developers for building and testing Android drivers.
+
+Building using the Android NDK
+------------------------------
+
+Download and install the NDK using whatever method you normally would.
+Then, create your meson cross file to use it, something like this
+``~/.local/share/meson/cross/android-aarch64`` file::
+
+    [binaries]
+    ar = 'NDKDIR/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android-ar'
+    c = ['ccache', 'NDKDIR/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android29-clang', '-fuse-ld=lld']
+    cpp = ['ccache', 'NDKDIR/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android29-clang++', '-fuse-ld=lld', '-fno-exceptions', '-fno-unwind-tables', '-fno-asynchronous-unwind-tables', '-static-libstdc++']
+    strip = 'NDKDIR/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android-strip'
+    # Android doesn't come with a pkg-config, but we need one for meson to be happy not
+    # finding all the optional deps it looks for.  Use system pkg-config pointing at a
+    # directory we get to populate with any .pc files we want to add for Android
+    pkgconfig = ['env', 'PKG_CONFIG_LIBDIR=NDKDIR/pkgconfig', '/usr/bin/pkg-config']
+
+    [host_machine]
+    system = 'linux'
+    cpu_family = 'arm'
+    cpu = 'armv8'
+    endian = 'little'
+
+Now, use that cross file for your Android build directory (as in this
+one cross-compiling the turnip driver for a stock Pixel phone)
+
+.. code-block:: console
+
+    meson build-android-aarch64 \
+        --cross-file android-aarch64 \
+       -Dplatforms=android \
+       -Dplatform-sdk-version=26 \
+       -Dandroid-stub=true \
+       -Dgallium-drivers= \
+       -Dvulkan-drivers=freedreno \
+       -Dfreedreno-kgsl=true
+    ninja -C build-android-aarch64
+
+Replacing Android drivers on stock Android
+------------------------------------------
+
+The vendor partition with the drivers is normally mounted from a
+read-only disk image on ``/vendor``.  To be able to replace them for
+driver development, we need to unlock the device and remount
+``/vendor`` read/write.
+
+.. code-block:: console
+
+    adb disable-verity
+    adb reboot
+    adb remount -R
+
+Now you can replace drivers as in:
+
+.. code-block:: console
+
+    adb push build-android-aarch64/src/freedreno/vulkan/libvulkan_freedreno.so /vendor/lib64/hw/vulkan.sdm710.so
+
+Note this command doesn't quite work because libvulkan wants the
+SONAME to match.  For now, in turnip we have been using a hack to the
+meson.build to change the SONAME.
+
+Replacing Android drivers on Chrome OS
+--------------------------------------
+
+Chrome OS's ARC++ is an Android container with hardware drivers inside
+of it.  The vendor partition with the drivers is normally mounted from
+a read-only squashfs image on disk.  For doing rapid driver
+development, you don't want to regenerate that image.  So, we'll take
+the existing squashfs image, copy it out on the host, and then use a
+bind mount instead of a loopback mount so we can update our drivers
+using scp from outside the container.
+
+On your device, you'll want to make ``/`` read-write.  ssh in as root
+and run:
+
+.. code-block:: console
+
+    crossystem dev_boot_signed_only=0
+    /usr/share/vboot/bin/make_dev_ssd.sh --remove_rootfs_verification --partitions 4
+    reboot
+
+Then, we'll switch Android from using an image for ``/vendor`` to using a
+bind-mount from a directory we control.
+
+.. code-block:: console
+
+    cd /opt/google/containers/android/
+    mkdir vendor-ro
+    mount -o loop vendor.raw.img vendor-ro
+    cp -a vendor-ro vendor-rw
+    emacs config.json
+
+In the ``config.json``, you want to find the block for ``/vendor`` and
+change it to::
+
+            {
+                "destination": "/vendor",
+                "type": "bind",
+                "source": "/opt/google/containers/android/vendor-rw",
+                "options": [
+                    "bind",
+                    "rw"
+                ]
+            },
+
+Now, restart the UI to do a full reload:
+
+.. code-block:: console
+
+    restart ui
+
+At this point, your android container is restarted with your new
+bind-mount ``/vendor``, and if you use ``android-sh`` to shell into it
+then the ``mount`` command should show::
+
+    /dev/root on /vendor type ext2 (rw,seclabel,relatime)
+
+Now, replacing your DRI driver with a new one built for Android should
+be a matter of:
+
+.. code-block:: console
+
+    scp msm_dri.so $HOST:/opt/google/containers/android/vendor-rw/lib64/dri/
+
+You can do your build of your DRI driver using ``emerge-$BOARD
+arc-mesa-freedreno`` (for example) if you have a source tree with
+ARC++, but it should also be possible to build using the NDK as
+described above.  There are currently rough edges with this, for
+example the build will require that you have your arc-libdrm build
+available to the NDK, assuming you're building anything but the
+freedreno vulkan driver for KGSL.  You can mostly put things in place
+with:
+
+.. code-block:: console
+
+    scp $HOST:/opt/google/containers/android/vendor-rw/lib64/libdrm.so \
+        NDKDIR/sysroot/usr/lib/aarch64-linux-android/lib/
+
+    ln -s \
+        /usr/include/xf86drm.h \
+       /usr/include/libsync.h \
+       /usr/include/libdrm \
+       NDKDIR/sysroot/usr/include/
+
+It seems that new invocations of an application will often reload the
+DRI driver, but depending on the component you're working on you may
+find you need to reload the whole Android container.  To do so without
+having to log in to Chrome again every time, you can just kill the
+container and let it restart:
+
+.. code-block:: console
+
+    kill $(cat /run/containers/android-run_oci/container.pid )

diff --git a/docs/contents.rst b/docs/contents.rst
index 4e2e458..f7fd50d 100644 (file)
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -64,6 +64,7 @@
    sourcedocs
    dispatch
    gallium/index
+   android
 
 .. toctree::
    :maxdepth: 1