1# Microdroid vendor modules
2
3Starting with Android V it is possible to start a Microdroid VM with a
4vendor-prodived kernel modules. This feature is part of the bigger
5[device assignment](device_assignmnent.md) effort.
6
7The vendor kernel modules should be packaged inside a `microdroid-vendor.img`
8dm-verity protected partition, inside a Microdroid VM this will be mounted as
9`/vendor` partition.
10
11Currently the following features are supported:
12* Kernel modules;
13* init .rc scripts with basic triggers (e.g. `on early-init`);
14* `ueventd.rc` file;
15* `/vendor/etc/selinux/vendor_file_contexts` file.
16
17
18Additionallity, starting with android15-6.6 it is possible to start a Microdroid
19VM with GKI as guest kernel. This is **required** when launching a Microdroid VM with
20vendor provided kernel modules.
21
22**Note:** in Android V, the 'Microdroid vendor modules' is considered an experimental
23feature to provide our partners a reference implementation that they can start
24integrating with to flesh out missing pieces.
25We **do not recommened** launching user-facing features that depend on using
26vendor modules in a pVM.
27
28
29## Integrating into a product {#build-system-integration}
30
31You can define microdroid vendor partition using `android_filesystem` soong
32module, here is an example:
33
34```
35android_filesystem {
36    name: "microdroid_vendor_example_image",
37    partition_name: "microdroid-vendor",
38    type: "ext4",
39    file_contexts: "file_contexts",
40    use_avb: true,
41    avb_private_key: ":microdroid_vendor_example_sign_key",
42    mount_point: "vendor",
43    deps: [
44        "microdroid_vendor_example_ueventd",
45        "microdroid_vendor_example_file_contexts",
46        "microdroid_vendor_example_kernel_modules",
47        "microdroid_vendor_example.rc",
48    ],
49}
50
51prebuilt_etc {
52    name: "microdroid_vendor_example",
53    src: ":microdroid_vendor_example_image",
54    relative_install_path: "avf/microdroid",
55    filename: "microdroid_vendor.img",
56    vendor: true,
57}
58```
59
60In order to integrate the microdroid vendor partition into a product, add the
61following lines to the corresponding device makefile:
62
63```
64PRODUCT_PACKAGES += microdroid_vendor_example
65MICRODROID_VENDOR_IMAGE_MODULE := microdroid_vendor_example
66```
67
68**Note**: it is important that the microdroid-vendor.img is installed into
69`/vendor/etc/avf/microdroid/microdroid_vendor.img` on the device.
70
71
72## Launching a Microdroid VM wirth vendor partition
73
74### Non-protected VMs
75
76You can launch a non-protected Microdroid VM with vendor partition by adding the
77`--vendor` argument to the `/apex/com.android.virt/bin/vm run-app` or
78`/apex/com.android.virt/bin/vm run-microdroid` CLI commands, e.g.:
79
80```
81adb shell /apex/com.android.virt/bin/vm/run-microdroid \
82  --debug full \
83  --vendor /vendor/etc/avf/microdroid/microdroid_vendor.img
84```
85
86On the Android host side, the `virtmgr` will append the
87`vendor_hashtree_descriptor_root_digest` property to the `/avf` node of the
88guest device tree overlay. Value of this property will contain the hashtree
89digest of the `microdroid_vendor.img` provided via the `--vendor` argument.
90
91Inside the Microdroid guest VM, the `first_stage_init` will use the
92`/proc/device-tree/avf/vendor_hashtree_descriptor_root_digest` to create a
93`dm-verity` device on top of the `/dev/block/by-name/microdroid-vendor` block
94device. The `/vendor` partition will be mounted on top of the created
95`dm-verity` device.
96
97TODO(ioffe): create drawings and add them here.
98
99
100### Protected VMs
101
102As of now, only **debuggable** Microdroid pVMs support running with the
103Microdroid vendor partition, e.g.:
104
105```
106adb shell /apex/com.android.virt/bin/vm/run-microdroid \
107  --debug full \
108  --protected \
109  --vendor /vendor/etc/avf/microdroid/microdroid_vendor.img
110```
111
112The execution flow is very similar to the non-protected case above, however
113there is one important addition. The `pvmfw` binary will use the
114[VM reference DT blob](#../guest/pvmfw/README.md#pvmfw-data-v1-2) passed from the
115Android Bootloader (ABL), to validate the guest DT overlay passed from the host.
116
117See [Changes in Android Bootloader](#changes-in-abl) section below for more
118details.
119
120### Reflecting microdroid vendor partition in the guest DICE chain
121
122The microdroid vendor partition will be reflected as a separate
123`Microdroid vendor` node in the Microdroid DICE chain.
124
125TODO(ioffe): drawing of DICE chain here.
126
127This node derivation happens in the `derive_microdroid_vendor_dice_node`, which
128is executed by `first_stage_init`. The binary will write the new DICE chain into
129the `/microdroid_resources/dice_chain.raw` file, which will be then read by
130`microdroid_manager` to derive the final `Microdroid payload` DICE node.
131
132TODO(ioffe): another drawing here.
133
134## Changes in the Android Bootloader {#changes-in-abl}
135
136In order for a Microdroid pVM with the
137`/vendor/etc/avf/microdroid/microdroid_vendor.img` to successfully boot, the
138ABL is required to pass the correct value of the
139`/vendor/etc/avf/microdroid/microdroid_vendor.img` hashtree digest in the
140`vendor_hashtree_descriptor_root_digest` property of `the /avf/reference` node.
141
142The `MICRODROID_VENDOR_IMAGE_MODULE` make variable mentioned in the
143[section above](#build-system-integration) configures build system to inject
144the value of the `microdroid-vendor.img` hashtree digest into the
145`com.android.build.microdroid-vendor.root_digest ` property of the footer of
146the host's `vendor.img`.
147
148The Android Bootloader can read that property when construction the
149[VM reference DT blob](#../guest/pvmfw/README.md#pvmfw-data-v1-2) passed to pvmfw.
150
151## GKI as Microdroid guest kernel
152
153In order to enable running Microdroid with GKI as guest kernel, specify the
154`PRODUCT_AVF_MICRODROID_GUEST_GKI_VERSION ` variable in a product makefile:
155
156```
157PRODUCT_AVF_MICRODROID_GUEST_GKI_VERSION := android15_66
158```
159
160Note: currently this will alter the content of the `com.android.virt` APEX by
161installing the corresponding GKI image into it. In the future, the GKI image
162will be installed on the `/system_ext` partition.
163
164The following changes to the `gki_defconfig` were made to support running as
165guest kernel:
166
167```
168CONFIG_VIRTIO_VSOCKETS=m
169CONFIG_VIRTIO_BLK=m
170CONFIG_OPEN_DICE=m
171CONFIG_VCPU_STALL_DETECTOR=m
172CONFIG_VIRTIO_CONSOLE=m
173CONFIG_HW_RANDOM_CCTRNG=m
174CONFIG_VIRTIO_PCI=m
175CONFIG_VIRTIO_BALLOON=m
176CONFIG_DMA_RESTRICTED_POOL=y
177```
178
179