Merge "Standardise safety comments for virtualizationmanager and vmclient." into main
diff --git a/README.md b/README.md
index eb28e94..eaa2579 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,29 @@
-# Virtualization
+# Android Virtualization Framework (AVF)
-This repository contains userspace services related to running virtual machines on Android,
-especially protected virtual machines. See the
-[getting started documentation](docs/getting_started/index.md) and
-[Microdroid README](microdroid/README.md) for more information.
+Android Virtualization Framework (AVF) provides secure and private execution environments for
+executing code. AVF is ideal for security-oriented use cases that require stronger isolation
+assurances over those offered by Android’s app sandbox.
+
+Visit [our public doc site](https://source.android.com/docs/core/virtualization) to learn more about
+what AVF is, what it is for, and how it is structured. This repository contains source code for
+userspace components of AVF.
+
+If you want a quick start, see the [getting started guideline](docs/getting_started.md)
+and follow the steps there.
+
+For in-depth explanations about individual topics and components, visit the following links.
+
+AVF components:
+
+* [pVM firmware](pvmfw/README.md)
+* [Microdroid](microdroid/README.md)
+* [Microdroid kernel](microdroid/kernel/README.md)
+* [Microdroid payload](microdroid/payload/README.md)
+* [vmbase](vmbase/README.md)
+* [VM Payload API](vm_payload/README.md)
+
+How-Tos:
+* [Building and running a demo app in Java](demo/README.md)
+* [Building and running a demo app in C++](demo_native/README.md)
+* [Debugging](docs/debug)
+* [Using custom VM](docs/custom_vm.md)
diff --git a/docs/custom_vm.md b/docs/custom_vm.md
new file mode 100644
index 0000000..270ea36
--- /dev/null
+++ b/docs/custom_vm.md
@@ -0,0 +1,23 @@
+# Custom VM
+
+You can spawn your own custom VMs by passing a JSON config file to the
+VirtualizationService via the `vm` tool on a rooted AVF-enabled device. If your
+device is attached over ADB, you can run:
+
+```shell
+cat > vm_config.json <<EOF
+{
+ "kernel": "/data/local/tmp/kernel",
+ "initrd": "/data/local/tmp/ramdisk",
+ "params": "rdinit=/bin/init"
+}
+EOF
+adb root
+adb push <kernel> /data/local/tmp/kernel
+adb push <ramdisk> /data/local/tmp/ramdisk
+adb push vm_config.json /data/local/tmp/vm_config.json
+adb shell "/apex/com.android.virt/bin/vm run /data/local/tmp/vm_config.json"
+```
+
+The `vm` command also has other subcommands for debugging; run
+`/apex/com.android.virt/bin/vm help` for details.
diff --git a/docs/debug/README.md b/docs/debug/README.md
new file mode 100644
index 0000000..b7729a4
--- /dev/null
+++ b/docs/debug/README.md
@@ -0,0 +1,119 @@
+# Debugging protected VMs
+
+AVF is largely about protected VMs. This in turn means that anything that is
+happening inside the VM cannot be observed from outside of the VM. But as a
+developer, you need to be able to look into it when there’s an error in your
+VM. To satisfy such contradictory needs, AVF allows you to start a protected VM
+in a debuggable mode and provides a bunch of debugging mechanisms you can use
+to better understand the behavior of the VM and diagnose issues.
+
+Note: running a protected VM in a debuggable mode introduces many loopholes
+which can be used to nullify the protection provided by the hypervisor.
+Therefore, the debugable mode should never be used in production.
+
+## Enable debugging
+
+The following sections describe the two ways debugging can be enabled.
+
+### Debug level
+
+Debug level is a per-VM property which indicates how debuggable the VM is.
+There currently are two levels defined: NONE and FULL. NONE means that the VM
+is not debuggable at all, and FULL means that [all the debugging
+features](#debugging-features) are supported.
+
+Debug level is by default NONE. You can set it to FULL either via a Java API
+call in your app or via a command line argument `--debug` as follows:
+
+```java
+VirtualMachineConfig.Builder.setDebugLevel(DEBUG_LEVEL_FULL);
+```
+
+or
+
+```shell
+adb shell /apex/com.android.virt/bin/vm run-microdroid --debug full
+```
+
+or
+
+```shell
+m vm_shell
+vm_shell start-microdroid --auto-connect -- --protected --debug full
+```
+
+Note: `--debug full` is the default option when omitted. You need to explicitly
+use `--debug none` to set the debug level to NONE.
+
+### Debug policy
+
+Debug policy is a per-device property which forcibly enables selected debugging
+features, even for the VMs with debug level NONE.
+
+The main purpose of debug policy is in-field debugging by the platform
+developers (device makers, SoC vendors, etc.) To understand it, let’s imagine
+that you have an application of pVM. It’s configured as debug level NONE
+because you finished the development and the team-level testing. However, you
+get a bug report from your QA team or from beta testers. To fix the bug, you
+should be able to look into the pVM but you do not want to change the source
+code to make the VM debuggable and rebuild the entire software, because that
+may hurt the reproducibility of the bug.
+
+Note: Not every devices is guaranteed to support debug policy. It is up to the
+device manufacturer to implement this in their bootloader. Google Pixel
+devices for example support this after Pixel 7 and 7 Pro. Pixel 6 and 6 Pro
+don't support debug policy.
+
+In the Pixel phones supporting debug policy, it is provisioned by installing a
+device tree overlay like below to the Pixel-specific partition `dpm`.
+
+```
+/ {
+ fragment@avf {
+ target-path = "/";
+
+ __overlay__ {
+ avf {
+ common {
+ log = <1>; // Enable kernel log and logcat
+ ramdump = <1>; // Enable ramdump
+ }
+ microdroid {
+ adb = <1>; // Enable ADB connection
+ }
+ };
+ };
+ };
+}; /* end of avf */
+```
+
+To not enable a specific debugging feature, set the corresponding property
+value to other than `<1>`, or delete the property.
+
+As a reference, in Pixel phones, debug policy is loaded as below:
+
+1. Bootloader loads it from the `dpm` partition and verifies it.
+1. Bootloader appends the loaded debug policy as the [configuration
+ data](../../pvmfw/README.md#configuration-data) of the pvmfw.
+1. When a pVM is started, pvmfw [overlays][apply_debug_policy] the debug policy to the baseline
+ device tree from crosvm.
+1. OS payload (e.g. Microdroid) [reads][read_debug_policy] the device tree and enables specific
+ debugging feature accordingly.
+
+**Note**: Bootloader MUST NOT load debug policy when the bootloader is in LOCKED state.
+
+[apply_debug_policy]: https://cs.android.com/android/platform/superproject/main/+/main:packages/modules/Virtualization/pvmfw/src/fdt.rs;drc=0d52747770baa14d44c0779b5505095b4251f2e9;l=790
+[read_debug_policy]: https://cs.android.com/android/platform/superproject/main/+/main:packages/modules/Virtualization/microdroid_manager/src/main.rs;drc=65c9f1f0eee4375535f2025584646a0dbb0ea25c;l=834
+
+## Debugging features
+
+AVF currently supports the following debugging features:
+
+* ADB connection (only for Microdroid)
+* Capturing console output
+* Capturing logcat output (only for Microdroid)
+* [Capturing kernel ramdump](ramdump.md) (only for Microdroid)
+* Capturing userspace crash dump (only for Microdroid)
+* [Attaching GDB to the kernel](gdb_kernel.md)
+* [Attaching GDB to the userspace process](gdb_userspace.md) (only for Microdroid)
+* [Tracing hypervisor events](tracing.md)
diff --git a/docs/debug/gdb.md b/docs/debug/gdb_kernel.md
similarity index 100%
rename from docs/debug/gdb.md
rename to docs/debug/gdb_kernel.md
diff --git a/docs/debug/gdb_userspace.md b/docs/debug/gdb_userspace.md
new file mode 100644
index 0000000..c8af702
--- /dev/null
+++ b/docs/debug/gdb_userspace.md
@@ -0,0 +1,18 @@
+# Debugging the payload on microdroid
+
+Like a normal adb device, you can debug native processes running on a
+Microdroid-base VM using [`lldbclient.py`][lldbclient] script, either by
+running a new process, or attaching to an existing process. Use `vm_shell`
+tool above, and then run `lldbclient.py`.
+
+```sh
+adb -s localhost:8000 shell 'mount -o remount,exec /data'
+development/scripts/lldbclient.py -s localhost:8000 --chroot . --user '' \
+ (-p PID | -n NAME | -r ...)
+```
+
+**Note:** We need to pass `--chroot .` to skip verifying device, because
+microdroid doesn't match with the host's lunch target. We need to also pass
+`--user ''` as there is no `su` binary in microdroid.
+
+[lldbclient]: https://android.googlesource.com/platform/development/+/refs/heads/main/scripts/lldbclient.py
diff --git a/docs/getting_started.md b/docs/getting_started.md
new file mode 100644
index 0000000..d970c12
--- /dev/null
+++ b/docs/getting_started.md
@@ -0,0 +1,156 @@
+# Getting started with Android Virtualization Framework
+
+## Step 1: Prepare a device
+
+We support the following devices:
+
+* aosp\_panther (Pixel 7)
+* aosp\_cheetah (Pixel 7 Pro)
+* aosp\_oriole (Pixel 6)
+* aosp\_raven (Pixel 6 Pro)
+* aosp\_felix (Pixel Fold)
+* aosp\_tangopro (Pixel Tablet)
+* aosp\_cf\_x86\_64\_phone (Cuttlefish a.k.a. Cloud Android). Follow [this
+ instruction](https://source.android.com/docs/setup/create/cuttlefish-use) to
+ use.
+
+### Note on Pixel 6 and 6 Pro
+AVF is shipped in Pixel 6 and 6 Pro, but isn't enabled by default. To enable
+it, follow the instructions below:
+
+1. If the device is running Android 13 or earlier, upgrade to Android 14.
+
+1. Once upgraded to Android 14, execute the following command to enable pKVM.
+ ```shell
+ adb reboot bootloader
+ fastboot flashing unlock
+ fastboot oem pkvm enable
+ fastboot reboot
+ ```
+### Note on Cuttlefish
+Cuttlefish does not support protected VMs. Only non-protected VMs are
+supported.
+
+## Step 2: Build Android image
+
+This step is optional unless you want to build AVF by yourself or try the
+in-development version of AVF.
+
+AVF is implemented as an APEX named `com.android.virt`. However, in order for
+you to install it to your device (be it Pixel or Cuttlefish), you first need to
+re-build the entire Android from AOSP. This is because the official Android
+build you have in your device is release-key signed and therefore you can't
+install your custom-built AVF APEX to it - because it is test-key signed.
+
+### Pixel
+
+1. [Download](https://source.android.com/docs/setup/download/downloading)
+ source code from AOSP. Use the `main` branch.
+
+1. [Download](https://developers.google.com/android/blobs-preview) the preview
+ vendor blob that matches your device.
+
+1. [Build](https://source.android.com/docs/setup/build/building) the `aosp_`
+ variant of your device. For example, if your device is Pixel 7 (`panther`),
+ build `aosp_panther`.
+
+1. [Flash](https://source.android.com/docs/setup/build/running) the built
+ images to the device.
+
+
+### Cuttlefish
+
+1. [Download](https://source.android.com/docs/setup/download/downloading)
+ source code from AOSP. Use the `main` branch.
+
+1. Build Cuttlefish:
+ ```shell
+ source build/envsetup.sh
+ lunch aosp_cf_x86_64_phone-userdebug
+ m
+ ```
+
+1. Run Cuttlefish:
+ ```shell
+ cvd start
+ ```
+
+## Step 3: Build AVF
+
+Then you can repeat building and installing AVF to the device as follows:
+
+1. Build the AVF APEX.
+ ```sh
+ banchan com.android.virt aosp_arm64
+ UNBUNDLED_BUILD_SDKS_FROM_SOURCE=true m apps_only dist
+ ```
+ Replace `aosp_arm64` with `aosp_x86_64` if you are building for Cuttlefish.
+
+1. Install the AVF APEX to the device.
+ ```sh
+ adb install out/dist/com.android.virt.apex
+ adb reboot; adb wait-for-device
+ ```
+
+## Step 4: Run a Microdroid VM
+
+[Microdroid](../../microdroid/README.md) is a lightweight version of Android
+that is intended to run on pVM. You can run a Microdroid-based VM with an empty
+payload using the following command:
+
+```shell
+package/modules/Virtualization/vm/vm_shell.sh start-microdroid --auto-connect -- --protected
+```
+
+You will see the log messages like the below.
+
+```
+found path /apex/com.android.virt/app/EmptyPayloadAppGoogle@MASTER/EmptyPayloadAppGoogle.apk
+creating work dir /data/local/tmp/microdroid/7CI6QtktSluD3OZgv
+apk.idsig path: /data/local/tmp/microdroid/7CI6QtktSluD3OZgv/apk.idsig
+instance.img path: /data/local/tmp/microdroid/7CI6QtktSluD3OZgv/instance.img
+Created VM from "/apex/com.android.virt/app/EmptyPayloadAppGoogle@MASTER/EmptyPayloadAppGoogle.apk"!PayloadConfig(VirtualMachinePayloadConfig { payloadBinaryName: "MicrodroidEmptyPayloadJniLib.so" }) with CID 2052, state is STARTING.
+[2023-07-07T14:50:43.420766770+09:00 INFO crosvm] crosvm started.
+[2023-07-07T14:50:43.422545090+09:00 INFO crosvm] CLI arguments parsed.
+[2023-07-07T14:50:43.440984015+09:00 INFO crosvm::crosvm::sys::unix::device_helpers] Trying to attach block device: /proc/self/fd/49
+[2023-07-07T14:50:43.441730922+09:00 INFO crosvm::crosvm::sys::unix::device_helpers] Trying to attach block device: /proc/self/fd/54
+[2023-07-07T14:50:43.462055141+09:00 INFO crosvm::crosvm::sys::unix::device_helpers] Trying to attach block device: /proc/self/fd/63
+[WARN] Config entry DebugPolicy uses non-zero offset with zero size
+[WARN] Config entry DebugPolicy uses non-zero offset with zero size
+[INFO] pVM firmware
+avb_slot_verify.c:443: ERROR: initrd_normal: Hash of data does not match digest in descriptor.
+[INFO] device features: SEG_MAX | RO | BLK_SIZE | RING_EVENT_IDX | VERSION_1 | ACCESS_PLATFORM
+[INFO] config: 0x201a000
+[INFO] found a block device of size 50816KB
+[INFO] device features: SEG_MAX | BLK_SIZE | FLUSH | DISCARD | WRITE_ZEROES | RING_EVENT_IDX | VERSION_1 | ACCESS_PLATFORM
+[INFO] config: 0x2022000
+[INFO] found a block device of size 10304KB
+[INFO] No debug policy found.
+[INFO] Starting payload...
+<omitted>
+07-07 05:52:01.322 69 69 I vm_payload: vm_payload: Notified host payload ready successfully
+07-07 05:52:01.364 70 70 I adbd : persist.adb.watchdog set to ''
+07-07 05:52:01.364 70 70 I adbd : persist.sys.test_harness set to ''
+07-07 05:52:01.365 70 70 I adbd : adb watchdog timeout set to 600 seconds
+07-07 05:52:01.366 70 70 I adbd : Setup mdns on port= 5555
+07-07 05:52:01.366 70 70 I adbd : adbd listening on vsock:5555
+07-07 05:52:01.366 70 70 I adbd : adbd started
+#
+```
+
+The `--auto-connect` option provides you an adb-shell connection to the VM. The
+shell promot (`#`) at the end of the log is for that.
+
+## Step 5: Run tests
+
+There are various tests that spawn guest VMs and check different aspects of the
+architecture. They all can run via `atest`.
+
+```shell
+atest MicrodroidHostTestCases
+atest MicrodroidTestApp
+```
+
+If you run into problems, inspect the logs produced by `atest`. Their location
+is printed at the end. The `host_log_*.zip` file should contain the output of
+individual commands as well as VM logs.
diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md
deleted file mode 100644
index 9dcd4fa..0000000
--- a/docs/getting_started/index.md
+++ /dev/null
@@ -1,126 +0,0 @@
-# Getting started with Protected Virtual Machines
-
-## Prepare a device
-
-First you will need a device that is capable of running virtual machines. On arm64, this means a
-device which boots the kernel in EL2 and the kernel was built with KVM enabled. Unfortunately at the
-moment, we don't have an arm64 device in AOSP which does that. Instead, use cuttlefish which
-provides the same functionalities except that the virtual machines are not protected from the host
-(i.e. Android). This however should be enough for functional testing.
-
-We support the following device:
-
-* aosp_cf_x86_64_phone (Cuttlefish a.k.a. Cloud Android)
-* oriole/raven (Pixel 6, and 6 Pro)
-* panther/cheetah (Pixel 7, and 7 Pro)
-
-### Cuttlefish
-
-Building Cuttlefish
-
-```shell
-source build/envsetup.sh
-lunch aosp_cf_x86_64_phone-userdebug
-m
-```
-
-Run Cuttlefish locally by
-
-```shell
-acloud create --local-instance --local-image
-```
-
-### Google Pixel phones
-
-If the device is running Android 13 or earlier, join the [Android Beta
-Program](https://developer.android.com/about/versions/14/get#on_pixel) to upgrade to Android 14
-Beta.
-
-Once upgraded to Android 14, and if you are using Pixel 6 or 6 Pro, execute the following command to
-enable pKVM. You don't need to do this for Pixel 7 and 7 Pro.
-
-```shell
-adb reboot bootloader
-fastboot flashing unlock
-fastboot oem pkvm enable
-fastboot reboot
-```
-
-## Running demo app
-
-The instruction is [here](../../demo/README.md).
-
-## Running tests
-
-There are various tests that spawn guest VMs and check different aspects of the architecture. They
-all can run via `atest`.
-
-```shell
-atest MicrodroidHostTestCases
-atest MicrodroidTestApp
-```
-
-If you run into problems, inspect the logs produced by `atest`. Their location is printed at the
-end. The `host_log_*.zip` file should contain the output of individual commands as well as VM logs.
-
-## Spawning your own VMs with custom kernel
-
-You can spawn your own VMs by passing a JSON config file to the VirtualizationService via the `vm`
-tool on a rooted KVM-enabled device. If your device is attached over ADB, you can run:
-
-```shell
-cat > vm_config.json
-{
- "kernel": "/data/local/tmp/kernel",
- "initrd": "/data/local/tmp/ramdisk",
- "params": "rdinit=/bin/init"
-}
-adb root
-adb push <kernel> /data/local/tmp/kernel
-adb push <ramdisk> /data/local/tmp/ramdisk
-adb push vm_config.json /data/local/tmp/vm_config.json
-adb shell "start virtualizationservice"
-adb shell "/apex/com.android.virt/bin/vm run /data/local/tmp/vm_config.json"
-```
-
-The `vm` command also has other subcommands for debugging; run `/apex/com.android.virt/bin/vm help`
-for details.
-
-## Spawning your own VMs with custom pvmfw
-
-Set system property `hypervisor.pvmfw.path` to custom `pvmfw` on the device before using `vm` tool.
-`virtualizationservice` will pass the specified `pvmfw` to `crosvm` for protected VMs.
-
-```shell
-adb push pvmfw.img /data/local/tmp/pvmfw.img
-adb root # required for setprop
-adb shell setprop hypervisor.pvmfw.path /data/local/tmp/pvmfw.img
-```
-
-## Spawning your own VMs with Microdroid
-
-[Microdroid](../../microdroid/README.md) is a lightweight version of Android that is intended to run
-on pVM. You can run a Microdroid with empty payload using the following command:
-
-```shell
-adb shell /apex/com.android.virt/bin/vm run-microdroid
-```
-
-which spawns a "debuggable" VM by default to allow access to guest kernel logs.
-To run a production non-debuggable VM, pass `--debug none`.
-
-## Building and updating CrosVM and VirtualizationService {#building-and-updating}
-
-You can update CrosVM and the VirtualizationService by updating the `com.android.virt` APEX instead
-of rebuilding the entire image.
-
-```shell
-banchan com.android.virt aosp_arm64 // or aosp_x86_64 if the device is cuttlefish
-UNBUNDLED_BUILD_SDKS_FROM_SOURCE=true m apps_only dist
-adb install out/dist/com.android.virt.apex
-adb reboot
-```
-
-## Building and updating kernel inside Microdroid
-
-The instruction is [here](../../microdroid/kernel/README.md).
diff --git a/microdroid/README.md b/microdroid/README.md
index 5e3f586..dd1505f 100644
--- a/microdroid/README.md
+++ b/microdroid/README.md
@@ -138,73 +138,6 @@
If you are looking for an example usage of the APIs, you may refer to the [demo
app](https://android.googlesource.com/platform/packages/modules/Virtualization/+/refs/heads/master/demo/).
-## Debuggable microdroid
+## Debugging Microdroid
-### Debugging features
-Microdroid supports following debugging features:
-
-- VM log
-- console output
-- kernel output
-- logcat output
-- [ramdump](../docs/debug/ramdump.md)
-- crashdump
-- [adb](#adb)
-- [gdb](#debugging-the-payload-on-microdroid)
-
-### Enabling debugging features
-There's two ways to enable the debugging features:
-
-#### Option 1) Running microdroid on AVF debug policy configured device
-
-microdroid can be started with debugging features by debug policies from the
-host. Host bootloader may provide debug policies to host OS's device tree for
-VMs. Host bootloader MUST NOT provide debug policies for locked devices for
-security reasons.
-
-For protected VM, such device tree will be available in microdroid. microdroid
-can check which debuging features is enabled.
-
-Here are list of device tree properties for debugging features.
-
-- `/avf/guest/common/log`: `<1>` to enable kernel log and logcat. Ignored
- otherwise.
-- `/avf/guest/common/ramdump`: `<1>` to enable ramdump. Ignored otherwise.
-- `/avf/guest/microdroid/adb`: `<1>` to enable `adb`. Ignored otherwise.
-
-#### Option 2) Lauching microdroid with debug level.
-
-microdroid can be started with debugging features. To do so, first, delete
-`$TEST_ROOT/instance.img`; this is because changing debug settings requires a
-new instance. Then add the `--debug=full` flag to the
-`/apex/com.android.virt/bin/vm run-app` command. This will enable all debugging
-features.
-
-### ADB
-
-If `adb` connection is enabled, launch following command.
-
-```sh
-vm_shell
-```
-
-Done. Now you are logged into Microdroid. Have fun!
-
-Once you have an adb connection with `vm_shell`, `localhost:8000` will be the
-serial of microdroid.
-
-### Debugging the payload on microdroid
-
-Like a normal adb device, you can debug native processes using `lldbclient.py`
-script, either by running a new process, or attaching to an existing process.
-Use `vm_shell` tool above, and then run `lldbclient.py`.
-
-```sh
-adb -s localhost:8000 shell 'mount -o remount,exec /data'
-development/scripts/lldbclient.py -s localhost:8000 --chroot . --user '' \
- (-p PID | -n NAME | -r ...)
-```
-
-**Note:** We need to pass `--chroot .` to skip verifying device, because
-microdroid doesn't match with the host's lunch target. We need to also pass
-`--user ''` as there is no `su` binary in microdroid.
+Refer to [Debugging protected VMs](../docs/debug/README.md).
diff --git a/pvmfw/README.md b/pvmfw/README.md
index 4e93648..386036d 100644
--- a/pvmfw/README.md
+++ b/pvmfw/README.md
@@ -174,10 +174,12 @@
blos it refers to. In version 1.0, it describes two blobs:
- entry 0 must point to a valid BCC Handover (see below)
-- entry 1 may point to a [DTBO] to be applied to the pVM device tree
+- entry 1 may point to a [DTBO] to be applied to the pVM device tree. See
+ [debug policy][debug_policy] for an example.
[header]: src/config.rs
[DTBO]: https://android.googlesource.com/platform/external/dtc/+/refs/heads/master/Documentation/dt-object-internal.txt
+[debug_policy]: ../docs/debug/README.md#debug-policy
#### Virtual Platform Boot Certificate Chain Handover
@@ -240,37 +242,6 @@
[Layering]: https://pigweed.googlesource.com/open-dice/+/refs/heads/main/docs/specification.md#layering-details
[Trusty-BCC]: https://android.googlesource.com/trusty/lib/+/1696be0a8f3a7103/lib/hwbcc/common/swbcc.c#554
-#### pVM Device Tree Overlay
-
-Config header can provide a DTBO to be overlaid on top of the baseline device
-tree from crosvm.
-
-The DTBO may contain debug policies. Debug policies MUST NOT be provided for
-locked devices for security reasons.
-
-Here are an example of DTBO.
-
-```
-/ {
- fragment@avf {
- target-path = "/";
-
- __overlay__ {
- avf {
- /* your debug policy here */
- };
- };
- };
-}; /* end of avf */
-```
-
-For specifying DTBO, host bootloader should apply the DTBO to both host
-OS's device tree and config header of `pvmfw`. Both `virtualizationmanager` and
-`pvmfw` will prepare for debugging features.
-
-For details about device tree properties for debug policies, see
-[microdroid's debugging policy guide](../microdroid/README.md#option-1-running-microdroid-on-avf-debug-policy-configured-device).
-
### Platform Requirements
pvmfw is intended to run in a virtualized environment according to the `crosvm`
@@ -433,3 +404,25 @@
kernel][soong-udroid]).
[soong-udroid]: https://cs.android.com/android/platform/superproject/+/master:packages/modules/Virtualization/microdroid/Android.bp;l=427;drc=ca0049be4d84897b8c9956924cfae506773103eb
+
+## Development
+
+For faster iteration, you can build pvmfw, adb-push it to the device, and use
+it directly for a new pVM, without having to flash it to the physical
+partition. To do that, set the system property `hypervisor.pvmfw.path` to point
+to the pvmfw image you pushed as shown below:
+
+```shell
+m pvmfw_img
+adb push out/target/product/generic_arm64/system/etc/pvmfw.img /data/local/tmp/pvmfw.img
+adb root
+adb shell setprop hypervisor.pvmfw.path /data/local/tmp/pvmfw.img
+```
+
+Then run a protected VM, for example:
+
+```shell
+adb shell /apex/com.android.virt/bin/vm run-microdroid --protected
+```
+
+Note: `adb root` is required to set the system property.
diff --git a/tests/testapk/src/java/com/android/microdroid/test/MicrodroidTests.java b/tests/testapk/src/java/com/android/microdroid/test/MicrodroidTests.java
index 15cb450..f6dc1b8 100644
--- a/tests/testapk/src/java/com/android/microdroid/test/MicrodroidTests.java
+++ b/tests/testapk/src/java/com/android/microdroid/test/MicrodroidTests.java
@@ -2106,6 +2106,31 @@
assertThat(testResults.mMountFlags & expectedFlags).isEqualTo(expectedFlags);
}
+ @Test
+ public void systemPartitionMountFlags() throws Exception {
+ assumeSupportedDevice();
+
+ VirtualMachineConfig config =
+ newVmConfigBuilder()
+ .setPayloadBinaryName("MicrodroidTestNativeLib.so")
+ .setDebugLevel(DEBUG_LEVEL_FULL)
+ .build();
+
+ VirtualMachine vm = forceCreateNewVirtualMachine("test_system_mount_flags", config);
+
+ TestResults testResults =
+ runVmTestService(
+ TAG,
+ vm,
+ (ts, tr) -> {
+ tr.mMountFlags = ts.getMountFlags("/");
+ });
+
+ assertThat(testResults.mException).isNull();
+ int expectedFlags = MS_NOATIME | MS_RDONLY;
+ assertThat(testResults.mMountFlags & expectedFlags).isEqualTo(expectedFlags);
+ }
+
private static class VmShareServiceConnection implements ServiceConnection {
private final CountDownLatch mLatch = new CountDownLatch(1);