doc: Add introduction of launching Celadon User OS

Add introduction of launching Celadon User OS Signed-off-by: ruix.li <ruix.li@intel.com>
2019-06-25 18:33:55 +08:00 · 2019-06-25 18:33:55 +08:00 · 93659f0160
parent 4b6dc0255f
commit 93659f0160
1 changed files with 96 additions and 0 deletions
--- a/doc/tutorials/using_celadon_as_uos.rst
+++ b/doc/tutorials/using_celadon_as_uos.rst
@ -0,0 +1,96 @@
+.. _using_celadon_as_uos:
+
+Using Celadon as User OS
+########################
+
+`Celadon <https://01.org/projectceladon/>`_ is an open source Android* software reference stack
+for Intel architecture. It builds upon a vanilla Android stack and incorporates open sourced components
+that are optimized for the hardware. This tutorial describes how to run Celadon as the User OS
+on the ACRN hypervisor. We are using Kaby Lake-based NUC (model NUC7i7DNHE) in this tutorial.
+
+Prerequisites
+*************
+
+* Ubuntu 18.04 or higher with at least 150G free disk space
+* Intel Kaby Lake NUC7ixDNHE ( Reference Platforms: :ref:`ACRN supported platforms <hardware>` )
+* BIOS version 0059 or later firmware should be flashed on the NUC system,
+  and the ``Device Mode`` option is selected on the USB category of the Devices tab,
+  in order to enable USB device function through the internal USB 3.0 port header.
+* Two HDMI monitors
+* A USB dongle (e.g. `Dawson Canyon USB 3.0 female
+  to 10-pin header cable <https://www.gorite.com/dawson-canyon-usb-3-0-female-to-10-pin-header-cable>`_)
+  is optional if you plan to use the ``adb`` and ``fastboot`` tools in the Celadon User OS for debugging.
+  Refer to the `Technical Product Specification
+  <https://www.intel.com/content/dam/support/us/en/documents/mini-pcs/nuc-kits/NUC7i5DN_TechProdSpec.pdf>`_
+  to identify the USB 3.0 port header on the main board.
+
+Build Celadon from source
+*************************
+
+#. Follow the instructions in the `Build Celadon from source
+   <https://01.org/projectceladon/documentation/getting_started/build-source>`_ guide
+   to set up the Celadon project source code.
+
+#. Select Celadon build target::
+
+      $ cd <Celadon project directory>
+      $ source build/envsetup.sh
+      $ lunch cel_apl-userdebug
+
+   .. note:: You can run ``lunch`` with no arguments to manually choose your Celadon build variants.
+
+#. Download these additional patches and apply each one individually with the command::
+
+       $ git apply <patch-filename>
+
+   .. table:: ACRN patch list
+      :widths: auto
+      :name: ACRN patch list
+
+      +--------------------------------------------------------------------+-------------------------------------------+
+      | Patch link                                                         | Description                               |
+      +====================================================================+===========================================+
+      | https://github.com/projectceladon/device-androidia/pull/458        | kernel config: Add the support of ACRN    |
+      +--------------------------------------------------------------------+-------------------------------------------+
+      | https://github.com/projectceladon/device-androidia-mixins/pull/293 | graphic/mesa: Add the support of ACRN     |
+      +--------------------------------------------------------------------+-------------------------------------------+
+      | https://github.com/projectceladon/device-androidia/pull/441        | cel_apl: use ttyS0 instead of ttyUSB0     |
+      +--------------------------------------------------------------------+-------------------------------------------+
+      | https://github.com/projectceladon/device-androidia/pull/439        | Disable trusty and pstore                 |
+      +--------------------------------------------------------------------+-------------------------------------------+
+
+   .. note:: If the ``git apply`` command shows an error, you may need to modify
+      the source code manually instead.
+
+#. Build Celadon image::
+
+   $ device/intel/mixins/mixin-update
+   $ make SPARSE_IMG=true gptimage -j $(nproc)
+
+.. note:: Replace the ``$(nproc)`` argument with the number of processor threads on your workstation
+   in order to build the source code with parallel tasks. The Celadon gptimage will be
+   generated to ``out/target/product/cel_apl/cel_apl_gptimage.img``
+
+Steps for Using Celadon as User OS
+**********************************
+
+#. Follow :ref:`getting-started-apl-nuc` to boot the "ACRN Service OS"
+
+#. Prepare dependencies on your NUC::
+
+   # mkdir ~/celadon && cd ~/celadon
+   # cp /usr/share/acrn/bios/OVMF.fd ./
+   # cp /usr/share/acrn/samples/nuc/launch_win.sh ./launch_android.sh
+   # sed -i "s/win10-ltsc/android/" launch_android.sh
+   # scp <cel_apl_gptimage.img from your host> ./android.img
+   # sh launch_android.sh
+
+#. You will see the shell console after Celadon boots. Check the build info using the ``getprop`` command:
+
+   .. code-block:: bash
+
+      console:/ $
+      console:/ $ getprop | grep finger
+      [ro.bootimage.build.fingerprint]: [cel_apl/cel_apl/cel_apl:9/PPR2.181005.003.A1/rui06241613:userdebug/test-keys]
+      [ro.build.fingerprint]: [cel_apl/cel_apl/cel_apl:9/PPR2.181005.003.A1/rui06241613:userdebug/test-keys]
+      [ro.vendor.build.fingerprint]: [cel_apl/cel_apl/cel_apl:9/PPR2.181005.003.A1/rui06241613:userdebug/test-keys]