1# Microdroid
2
3Microdroid is a (very) lightweight version of Android that is intended to run on
4on-device virtual machines. It is built from the same source code as the regular
5Android, but it is much smaller; no system server, no HALs, no GUI, etc. It is
6intended to host headless & native workloads only.
7
8## Building
9
10You need a VIM3L board. Instructions for building Android for the target, and
11flashing the image can be found [here](../docs/getting_started/yukawa.md).
12
13Then you install `com.android.virt` APEX. All files needed to run microdroid are
14included in the APEX, which is already in the `yukawa` (VIM3L) target. You can
15of course build and install the APEX manually.
16
17```sh
18$ source build/envsetup.sh
19$ choosecombo 1 aosp_arm64 userdebug // actually, any arm64-based target is ok
20$ m com.android.virt
21$ adb install $ANDROID_PRODUCT_OUT/system/apex/com.android.virt.apex
22$ adb reboot
23```
24
25## Running
26
27Create a config file, `microdroid.json`:
28
29```json
30{
31  "bootloader": "/data/local/tmp/microdroid/bootloader",
32  "disks": [
33    {
34      "image": "/data/local/tmp/microdroid/os_composite.img",
35      "writable": false
36    },
37    {
38      "image": "/data/local/tmp/microdroid/env_composite.img",
39      "writable": false
40    },
41    {
42      "image": "/data/local/tmp/microdroid/payload.img",
43      "writable": false
44    },
45    {
46      "image": "/data/local/tmp/microdroid/userdata_composite.qcow2",
47      "writable": true
48    }
49  ]
50}
51```
52
53Copy the artifacts to the temp directory, create the composite image using
54`mk_cdisk` and copy the VM config file. For now, some other files have to be
55manually created. In the future, you won't need these, and this shall be done
56via [`virtmanager`](../virtmanager/).
57
58```sh
59$ adb root
60$ adb shell 'mkdir /data/local/tmp/microdroid'
61$ adb shell 'cp /apex/com.android.virt/etc/microdroid_bootloader /data/local/tmp/microdroid/bootloader'
62$ adb shell 'cp /apex/com.android.virt/etc/fs/*.img /data/local/tmp/microdroid'
63$ adb shell 'cp /apex/com.android.virt/etc/uboot_env.img /data/local/tmp/microdroid'
64$ adb shell 'dd if=/dev/zero of=/data/local/tmp/microdroid/misc.img bs=4k count=256'
65$ adb shell 'dd if=/dev/zero of=/data/local/tmp/microdroid/userdata.img bs=1 count=0 seek=4G'
66$ adb shell 'mkfs.ext4 /data/local/tmp/microdroid/userdata.img'
67$ adb shell 'cd /data/local/tmp/microdroid; /apex/com.android.virt/bin/mk_cdisk /apex/com.android.virt/etc/microdroid_cdisk.json os_composite.img'
68$ adb shell 'cd /data/local/tmp/microdroid; /apex/com.android.virt/bin/mk_cdisk /apex/com.android.virt/etc/microdroid_cdisk_env.json env_composite.img'
69$ adb shell 'cd /data/local/tmp/microdroid; /apex/com.android.virt/bin/mk_cdisk /apex/com.android.virt/etc/microdroid_cdisk_userdata.json userdata_composite.img'
70$ adb shell '/apex/com.android.virt/bin/crosvm create_qcow2 --backing_file=/data/local/tmp/microdroid/userdata_composite.img /data/local/tmp/microdroid/userdata_composite.qcow2'
71$ adb shell 'cd /data/local/tmp/microdroid; /apex/com.android.virt/bin/mk_payload /apex/com.android.virt/etc/microdroid_payload.json payload.img'
72$ adb shell 'chmod go+r /data/local/tmp/microdroid/*-header.img /data/local/tmp/microdroid/*-footer.img'
73$ adb push microdroid.json /data/local/tmp/microdroid/microdroid.json
74```
75
76Ensure SELinux is in permissive mode to allow virtmanager and crosvm to open
77files from `/data/local/tmp`. Opening files from this directory is
78neverallow-ed and file descriptors should be passed instead but, before that is
79supported, `adb shell setenforce 0` will put the device in permissive mode.
80
81Now, run the VM and look for `adbd` starting in the logs.
82
83```sh
84$ adb shell "start virtmanager"
85$ adb shell "RUST_BACKTRACE=1 RUST_LOG=trace /apex/com.android.virt/bin/vm run /data/local/tmp/microdroid/microdroid.json"
86```
87
88## ADB
89
90```sh
91$ CID=10
92$ adb forward tcp:8000 vsock:$CID:5555
93$ adb connect localhost:8000
94```
95
96`CID` should be the CID that `vm` reported was assigned to the VM. You can also
97check it with `adb shell "/apex/com.android.virt/bin/vm list"`. `5555` must be
98the value. `8000` however can be any port in the development machine.
99
100Done. Now you can log into microdroid. Have fun!
101
102```sh
103$ adb -s localhost:8000 shell
104```
105