Add Getting Started guide am: dd56510556
Original change: https://android-review.googlesource.com/c/platform/packages/modules/Virtualization/+/1471867
Change-Id: I61b0015e24a1f2542a2f964de916594eda585e42
diff --git a/docs/getting_started/goldfish.md b/docs/getting_started/goldfish.md
new file mode 100644
index 0000000..0705982
--- /dev/null
+++ b/docs/getting_started/goldfish.md
@@ -0,0 +1,46 @@
+# Android Emulator (goldfish)
+
+The built-in local emulator is the quickest way how to get started with KVM and Android.
+
+## x86_64
+
+KVM on x86_64 does not provide the same guest protection as arm64 but you will be able to spawn
+virtual machines and use the same APIs to communicate with the guest. The main reason for choosing
+the x86_64 emulator over its arm64 counterpart is performance. With native virtualization it is
+easily 10x faster than arm64 emulation.
+
+For optimal performance make sure to
+[enable nested virtualization](https://www.linux-kvm.org/page/Nested_Guests) on your machine.
+Don't forget to add your user account into the `kvm` group, then re-login for it to take effect.
+``` shell
+$ sudo gpasswd -a $USER kvm
+```
+
+Build Android for the emulator:
+``` shell
+$ . build/envsetup.sh
+$ lunch sdk_phone_x86_64-eng
+$ m -j$(nproc)
+```
+
+Once you have an Android image, invoke `emulator`. The script will automatically find the image you
+just built and run it in QEMU.
+``` shell
+$ emulator -no-window -show-kernel -writable-system -qemu -cpu host
+```
+Explanation of the arguments:
+ * `-no-window`: run headless
+ * `-show-kernel`: print kernel UART logs to the console (useful for debugging),
+ * `-writable-system`: support remounting `system/` as writable, needed for `adb sync`,
+ * `-qemu -cpu host`: needed to enable nested virtualization, instructs QEMU to allow Android
+ access CPU features of the host kernel
+
+If you get an error saying “x86_64 emulation currently requires hardware acceleration!”, your
+user account is not in the `kvm` group (see above).
+
+You should now see the virtual device when you run:
+``` shell
+$ adb devices
+List of devices attached
+emulator-5554 device
+```
diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md
new file mode 100644
index 0000000..022831b
--- /dev/null
+++ b/docs/getting_started/index.md
@@ -0,0 +1,76 @@
+# 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.
+
+Here are instructions for select devices:
+
+ * [yukawa: Khadas VIM3L](yukawa.md) (arm64)
+ * [goldfish: Android Emulator](goldfish.md) (x86_64)
+
+## Running tests
+
+Virtualization source code and relevant tests are located in
+[packages/modules/Virtualization](https://android.googlesource.com/platform/packages/modules/Virtualization)
+of the AOSP repository.
+
+### Host-side tests
+
+These are tests where the test driver runs on the "host" (your computer) and it issues commands to
+the "target" (the connected device or emulator) over ADB. The tests spawn guest VMs and test
+different aspects of the architecture.
+
+You can build and run them with:
+``` shell
+atest VirtualizationHostTestCases
+```
+
+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.
+
+## CrosVM
+
+[CrosVM](https://android.googlesource.com/platform/external/crosvm/) is a Rust-based Virtual Machine
+Monitor (VMM) originally built for ChromeOS and ported to Android.
+
+It is not installed in `release` builds of Android but you will find it in `userdebug` and `eng`
+builds.
+
+### Spawning your own VMs
+
+You can spawn your own VMs by running CrosVM directly on a rooted KVM-enabled device. If your
+device is attached over ADB, you can run:
+``` shell
+$ adb root
+$ adb push <kernel> /data/local/tmp/kernel
+$ adb push <ramdisk> /data/local/tmp/ramdisk
+$ adb shell crosvm run --initrd /data/local/tmp/ramdisk /data/local/tmp/kernel
+```
+
+### Syncing system files
+
+When you're developing CrosVM, it is handy to update the system files using `adb sync` instead of
+flashing the device each time. It requires root and mounting the system image as writable.
+
+If you're using the emulator (goldfish), the following instructions will only work if it was
+started with `-writable-system`.
+
+First, disable verity checks on your device, reboot and remount the system partition.
+This is only needed once:
+``` shell
+$ adb root
+$ adb disable-verity
+$ adb reboot
+$ adb wait-for-device root
+$ adb remount
+```
+
+Now (re-)build CrosVM and sync the system files:
+``` shell
+$ m crosvm
+$ adb shell stop
+$ adb sync
+$ adb shell start
+```
diff --git a/docs/getting_started/yukawa.md b/docs/getting_started/yukawa.md
new file mode 100644
index 0000000..11f6b73
--- /dev/null
+++ b/docs/getting_started/yukawa.md
@@ -0,0 +1,30 @@
+# Khadas VIM3L (yukawa)
+
+The [Khadas VIM3L](https://www.khadas.com/vim3l) is an extremely hackable development board with an
+Amlogic Armv8.2 SoC and complete upstream support in U-boot, Linux and even
+[AOSP](https://android.googlesource.com/device/amlogic/yukawa/+/refs/heads/master).
+That makes it a compelling target for testing virtualization.
+
+The [prebuilt kernel](https://android.googlesource.com/device/amlogic/yukawa-kernel/+/refs/heads/master)
+in AOSP is currently not GKI, but it is close and kept up to date.
+
+Note that the `yukawa` target has SELinux policy set to `permissive`.
+
+Resources:
+ * [AOSP instructions](https://android.googlesource.com/device/amlogic/yukawa/+/refs/heads/master/sei610/README)
+ for flashing a bootloader with `fastboot` support
+ * [Manufaturer's wiki](https://docs.khadas.com/vim3/index.html) for things like setting up UART
+ and entering recovery mode
+ * [go/vim3l](https://goto.google.com/vim3l) is a more detailed document but only accessible to
+ Google employees
+
+Build Android for the board:
+``` shell
+$ . build/envsetup.sh
+$ lunch yukawa-userdebug
+$ export TARGET_VIM3L=true
+$ export TARGET_KERNEL_USE=5.4
+$ m -j$(nproc)
+```
+
+Flash your device and reboot.