Add Getting Started guide
Basic instructions on how to set up VIM3L and the emulator and how to
run tests. Written in Markdown and kept in tree so they are public.
Test: n/a
Change-Id: I3bf3aed5f6bc6a9a93f8937d6a7bd885a475097d
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.