Add docs for Microdroid vendor modules
Bug: 325991735
Test: n/a
Change-Id: I313c5c19b7ed87d30067d85f50ae87b8c772172a
diff --git a/README.md b/README.md
index 7560a45..f417b00 100644
--- a/README.md
+++ b/README.md
@@ -32,4 +32,5 @@
* [Debugging](docs/debug)
* [Using custom VM](docs/custom_vm.md)
* [Device assignment](docs/device_assignment.md)
+* [Microdroid vendor modules](docs/microdroid_vendor_modules.md)
* [Huge Pages](docs/hugepages.md)
diff --git a/docs/abl.md b/docs/abl.md
index b08464e..7139d26 100644
--- a/docs/abl.md
+++ b/docs/abl.md
@@ -22,7 +22,9 @@
* DICE chain (also known as BCC Handover)
* DTBO describing [debug policy](debug/README.md#debug-policy) (if available)
* DTBO describing [assignable devices](device_assignment.md) (if available)
-* Reference DT carrying extra information that needs to be passed to the guest VM
+* Reference DT carrying extra information that needs to be passed to the guest VM, e.g.:
+ * Hashtree digest of the
+ [microdroid-vendor.img](microdroid_vendor_modules.md#changes-in-abl).
See [Configuration Data](../pvmfw/README.md#configuration-data) for more detail.
diff --git a/docs/microdroid_vendor_modules.md b/docs/microdroid_vendor_modules.md
new file mode 100644
index 0000000..ef55225
--- /dev/null
+++ b/docs/microdroid_vendor_modules.md
@@ -0,0 +1,178 @@
+# Microdroid vendor modules
+
+Starting with Android V it is possible to start a Microdroid VM with a
+vendor-prodived kernel modules. This feature is part of the bigger
+[device assignment](device_assignmnent.md) effort.
+
+The vendor kernel modules should be packaged inside a `microdroid-vendor.img`
+dm-verity protected partition, inside a Microdroid VM this will be mounted as
+`/vendor` partition.
+
+Currently the following features are supported:
+* Kernel modules;
+* init .rc scripts with basic triggers (e.g. `on early-init`);
+* `ueventd.rc` file;
+* `/vendor/etc/selinux/vendor_file_contexts` file.
+
+
+Additionallity, starting with android15-6.6 it is possible to start a Microdroid
+VM with GKI as guest kernel. This is **required** when launching a Microdroid VM with
+vendor provided kernel modules.
+
+**Note:** in Android V, the 'Microdroid vendor modules' is considered an experimental
+feature to provide our partners a reference implementation that they can start
+integrating with to flesh out missing pieces.
+We **do not recommened** launching user-facing features that depend on using
+vendor modules in a pVM.
+
+
+## Integrating into a product {#build-system-integration}
+
+You can define microdroid vendor partition using `android_filesystem` soong
+module, here is an example:
+
+```
+android_filesystem {
+ name: "microdroid_vendor_example_image",
+ partition_name: "microdroid-vendor",
+ type: "ext4",
+ file_contexts: "file_contexts",
+ use_avb: true,
+ avb_private_key: ":microdroid_vendor_example_sign_key",
+ mount_point: "vendor",
+ deps: [
+ "microdroid_vendor_example_ueventd",
+ "microdroid_vendor_example_file_contexts",
+ "microdroid_vendor_example_kernel_modules",
+ "microdroid_vendor_example.rc",
+ ],
+}
+
+prebuilt_etc {
+ name: "microdroid_vendor_example",
+ src: ":microdroid_vendor_example_image",
+ relative_install_path: "avf/microdroid",
+ filename: "microdroid_vendor.img",
+ vendor: true,
+}
+```
+
+In order to integrate the microdroid vendor partition into a product, add the
+following lines to the corresponding device makefile:
+
+```
+PRODUCT_PACKAGES += microdroid_vendor_example
+MICRODROID_VENDOR_IMAGE_MODULE := microdroid_vendor_example
+```
+
+**Note**: it is important that the microdroid-vendor.img is installed into
+`/vendor/etc/avf/microdroid/microdroid_vendor.img` on the device.
+
+
+## Launching a Microdroid VM wirth vendor partition
+
+### Non-protected VMs
+
+You can launch a non-protected Microdroid VM with vendor partition by adding the
+`--vendor` argument to the `/apex/com.android.virt/bin/vm run-app` or
+`/apex/com.android.virt/bin/vm run-microdroid` CLI commands, e.g.:
+
+```
+adb shell /apex/com.android.virt/bin/vm/run-microdroid \
+ --debug full \
+ --vendor /vendor/etc/avf/microdroid/microdroid_vendor.img
+```
+
+On the Android host side, the `virtmgr` will append the
+`vendor_hashtree_descriptor_root_digest` property to the `/avf` node of the
+guest device tree overlay. Value of this property will contain the hashtree
+digest of the `microdroid_vendor.img` provided via the `--vendor` argument.
+
+Inside the Microdroid guest VM, the `first_stage_init` will use the
+`/proc/device-tree/avf/vendor_hashtree_descriptor_root_digest` to create a
+`dm-verity` device on top of the `/dev/block/by-name/microdroid-vendor` block
+device. The `/vendor` partition will be mounted on top of the created
+`dm-verity` device.
+
+TODO(ioffe): create drawings and add them here.
+
+
+### Protected VMs
+
+As of now, only **debuggable** Microdroid pVMs support running with the
+Microdroid vendor partition, e.g.:
+
+```
+adb shell /apex/com.android.virt/bin/vm/run-microdroid \
+ --debug full \
+ --protected \
+ --vendor /vendor/etc/avf/microdroid/microdroid_vendor.img
+```
+
+The execution flow is very similar to the non-protected case above, however
+there is one important addition. The `pvmfw` binary will use the
+[VM reference DT blob](#../pvmfw/README.md#pvmfw-data-v1-2) passed from the
+Android Bootloader (ABL), to validate the guest DT overlay passed from the host.
+
+See [Changes in Android Bootloader](#changes-in-abl) section below for more
+details.
+
+### Reflecting microdroid vendor partition in the guest DICE chain
+
+The microdroid vendor partition will be reflected as a separate
+`Microdroid vendor` node in the Microdroid DICE chain.
+
+TODO(ioffe): drawing of DICE chain here.
+
+This node derivation happens in the `derive_microdroid_vendor_dice_node`, which
+is executed by `first_stage_init`. The binary will write the new DICE chain into
+the `/microdroid_resources/dice_chain.raw` file, which will be then read by
+`microdroid_manager` to derive the final `Microdroid payload` DICE node.
+
+TODO(ioffe): another drawing here.
+
+## Changes in the Android Bootloader {#changes-in-abl}
+
+In order for a Microdroid pVM with the
+`/vendor/etc/avf/microdroid/microdroid_vendor.img` to successfully boot, the
+ABL is required to pass the correct value of the
+`/vendor/etc/avf/microdroid/microdroid_vendor.img` hashtree digest in the
+`vendor_hashtree_descriptor_root_digest` property of `the /avf/reference` node.
+
+The `MICRODROID_VENDOR_IMAGE_MODULE` make variable mentioned in the
+[section above](#build-system-integration) configures build system to inject
+the value of the `microdroid-vendor.img` hashtree digest into the
+`com.android.build.microdroid-vendor.root_digest ` property of the footer of
+the host's `vendor.img`.
+
+The Android Bootloader can read that property when construction the
+[VM reference DT blob](#../pvmfw/README.md#pvmfw-data-v1-2) passed to pvmfw.
+
+## GKI as Microdroid guest kernel
+
+In order to enable running Microdroid with GKI as guest kernel, specify the
+`PRODUCT_AVF_MICRODROID_GUEST_GKI_VERSION ` variable in a product makefile:
+
+```
+PRODUCT_AVF_MICRODROID_GUEST_GKI_VERSION := android15_66
+```
+
+Note: currently this will alter the content of the `com.android.virt` APEX by
+installing the corresponding GKI image into it. In the future, the GKI image
+will be installed on the `/system_ext` partition.
+
+The following changes to the `gki_defconfig` were made to support running as
+guest kernel:
+
+```
+CONFIG_VIRTIO_VSOCKETS=m
+CONFIG_VIRTIO_BLK=m
+CONFIG_OPEN_DICE=m
+CONFIG_VCPU_STALL_DETECTOR=m
+CONFIG_VIRTIO_CONSOLE=m
+CONFIG_HW_RANDOM_CCTRNG=m
+CONFIG_VIRTIO_PCI=m
+CONFIG_VIRTIO_BALLOON=m
+CONFIG_DMA_RESTRICTED_POOL=y
+```
+