1.. _using_celadon_as_user_vm:
2
3Run Celadon as the User VM OS
4#############################
5
6Introduction to Celadon
7***********************
8`Celadon`_ ---- An open source Android software reference stack for Intel architecture.
9
10This tutorial describes how to run Celadon Android as the User VM OS on ACRN hypervisor.
11
12If you want to learn more about Celadon, refer to the
13official `Celadon documentation <https://projectceladon.github.io>`__.
14
15.. _Celadon:
16   http://github.com/projectceladon
17
18
19Build Celadon Image from Source
20*******************************
21
22Before building the Celadon image, please make sure your development workstation
23meets the following requirements: A 64-bit workstation running Ubuntu with **64GB memory** and
24**350GB of free disk space**. If your workstation does not meet these requirements,
25you may encouter unexpected errors.
26
27Follow these instructions to build the Celadon images:
28
29#. Install the repo tools:
30
31   .. code-block:: none
32
33      mkdir -p ~/bin
34      curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
35      chmod a+x ~/bin/repo
36      export PATH=~/bin:$PATH
37
38#. Install the required building packages:
39
40   .. code-block:: none
41
42      sudo apt update
43      sudo apt install openjdk-8-jdk git ccache automake \
44       lzop bison gperf build-essential zip curl \
45       zlib1g-dev g++-multilib python3-networkx \
46       libxml2-utils bzip2 libbz2-dev libbz2-1.0 \
47       libghc-bzlib-dev squashfs-tools pngcrush \
48       schedtool dpkg-dev liblz4-tool make optipng maven \
49       libssl-dev bc bsdmainutils gettext python3-mako \
50       libelf-dev sbsigntool dosfstools mtools efitools \
51       python3-pystache git-lfs python3 flex clang libncurses5 \
52       fakeroot ncurses-dev xz-utils python3-pip ninja-build \
53       cryptsetup-bin cutils cmake pkg-config xorriso mtools
54      sudo pip3 install mako==1.1.0 meson==0.60.0 dataclasses
55      sudo su
56      cd /usr/local/
57      wget https://github.com/KhronosGroup/glslang/releases/download/SDK-candidate-26-Jul-2020/glslang-master-linux-Release.zip && \
58      unzip glslang-master-linux-Release.zip bin/glslangValidator
59
60#. Download the source code
61
62   .. code-block:: none
63
64      mkdir ~/civ
65      cd ~/civ
66
67   We choose Celadon Android 14 Base Releases `CIV_00.23.04.51_A14 <https://projectceladon.github.io/celadon-documentation/release-notes/base-releases-A14.html#civ-00-23-04-51-a14>`__.
68   Repo tool will download the entire source code into your local environments and it will cost several hours depending on your network.
69
70   .. code-block:: none
71
72      repo init -u https://github.com/projectceladon/manifest -b master -m stable-build/CIV_00.23.04.51_A14.xml
73      repo sync -c -q -j5
74
75#. Disable Trusty:
76
77   Trusty is a mandatory component since Android Oreo Desert onwards. However, it's easier to boot Celadon as VM without Trusty feature.
78   So we recommend to **disable trusty**. To disable, set the 'trusty' and 'tpm' options to false in the mixins config file
79   ``civ/device/intel/projectceladon/caas/mixins.spec`` as follows:
80
81   .. code-block:: none
82
83      [groups]
84      device-specific: celadon
85      treble: true
86      ....
87      tpm: false
88      ....
89      trusty: false
90
91   After modifing ``mixins.spec``, you must run the ``civ/device/intel/mixins/mixin-update`` script to apply the changes.
92
93   Enter the following commands to initialize your build variables and specifiy your celadon lunch target using ``lunch`` target:
94
95   .. code-block:: none
96
97      source build/envsetup.sh
98      lunch caas
99
100   Meanwhile, the following trusty related configs in **Android kernel** at
101   ``device/intel/mixins/groups/kernel/gmin64/config-lts/linux-intel-lts2022/x86_64_defconfig``
102   should be disabled as:
103
104   .. code-block:: none
105
106      # CONFIG_TCG_TPM is not set
107      # CONFIG_HW_RANDOM_TPM is not set
108      # CONFIG_TRUSTY is not set
109      # CONFIG_TRUSTY_LOG is not set
110      # CONFIG_TRUSTY_VIRTIO is not set
111      # CONFIG_TRUSTY_VIRTIO_IPC is not set
112      # CONFIG_TRUSTY_X86_64 is not set
113      # CONFIG_TRUSTY_BACKUP_TIMER is not set
114
115   Run `mixin` command to apply this changes:
116
117   .. code-block:: none
118
119      cd ~/civ
120      mixin
121
122#. Build Celadon flash image:
123
124   Then you are ready to build Celadon images. Build progress may cost several hours or even more depends on your building system:
125
126   .. code-block:: none
127
128      make flashfiles -j $(nproc)
129
130
131#. Flash Celadon image into disk:
132
133   Caution: Please **remain only one hard disk** (the disk will be entirely removed and flashed) in your destination platform, otherwise
134   Celadon may flash into the wrong disk and cause data loss. There are two ways to do: i. Physically
135   remove the hard disk. ii. Disable the sata(or nvme) slot in the BIOS settings.
136
137   We test this VM in an ASUS MiniPC with two disk slots: one is a m.2 nvme slot and one is a sata slot. We run service OS
138   (Ubuntu) on a sata disk and run guest OS(Celadon Android) on a nvme disk.
139
140   Prepare an empty USB disk and plug it into your **development platform**, run ``lsblk`` command to find it. Assume it's ``/dev/sdc`` here.
141
142   .. code-block:: none
143
144      cd ~/civ/out/target/product/caas
145      unzip caas-flashfile-eng.dot.iso.zip
146      sudo dd if=~/civ/caas-flashfile-eng.dot.iso of=/dev/sdc status=progress
147      sudo eject /dev/sdc
148
149   Unplug the USB disk and plug it into your **destination platform**. Power on your destination platform and boot into this USB disk via BIOS settings. The flash progress
150   will require you press :kbd:`UP` or :kbd:`PgUp` to continue. When flash done, you can boot into Celadon Android.
151
152#. ACRN Service VM Setup
153
154   Follow the steps in this :ref:`gsg` to set up ACRN based Ubuntu and launch the Service VM.
155   Modifiy the ACRN device model parameters in ``launch_user_vm_id1.sh`` as follows:
156
157   .. code-block:: none
158
159      dm_params=(
160         `add_cpus                                 8 9 16 17`
161         -m 8192M
162         --ovmf /usr/share/acrn/bios/OVMF.fd
163         `add_virtual_device                       1:0 lpc`
164         `add_virtual_device                       0:0 hostbridge`
165         `add_virtual_device                       3 virtio-console @stdio:stdio_port`
166         `add_passthrough_device                   2 0000:00:02.0`
167         `add_passthrough_device                   4 0000:00:14.0`
168         `add_interrupt_storm_monitor              10000 10 1 100`
169         `add_passthrough_device                   5 0000:01:00.0`
170         `add_logger_settings                      console=4 kmsg=3 disk=5`
171         VM1
172      )
173
174#. Boot Celadon VM
175
176   Remotely connect to the target system via SSH and Boot Celadon VM via the launch script ``launch_user_vm_id1``:
177
178   .. code-block:: none
179
180      sudo chmod +x ./launch_user_vm_id1.sh
181      sudo ./launch_user_vm_id1.sh
182
183   Then the screen will temperatory go off. Wait for about one minute and the Android UI will appear as:
184
185   .. figure:: images/celadon_uservm_01.png
186      :align: center
187      :name: Android-screenlock
188      :class: drop-shadow
189
190   .. figure:: images/celadon_uservm_02.png
191      :align: center
192      :name: Android-desktop
193      :class: drop-shadow
194
195
196
197
198