docs/custom_vm.md

# Custom VM

## Headless VMs

If your VM is headless (i.e. console in/out is the primary way of interacting
with it), you can spawn it 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.

# Terminal app
## Run GUI apps
Click Display button above to enable display.
And then, go back to the terminal, and run GUI apps.

## Mouse passthrough
There is a button for mouse passthrough in a display activity. With that, external
mouse event is directly delivered to a VM instance.

## Hardware acceleration
If a device supports gfxstream, a user can enable hardware acceleration in Terminal
app's settings menu. If you want to test in the userdebug device, create
`/sdcard/linux/gfxstream` file, which enables gfxstream for VM. Note: on HSUM
(Headless System User Mode) devices like some tablets and laptops, use the path
`/mnt/user/10/emulated/10/linux/gfxstream` instead.

## Connect to console via ADB
Run `adb shell vm console` which returns the command to attach console of an existing
VM instance.

## (Experimental) Use other desktop environment
We recommend a user to use weston with kiosk mode for single-app experience.
If you want to experiment with other desktop environment, please remove the line
including `systemctl --user start weston` in `/usr/local/bin/enable_display` and
`usr/local/bin/enable_gfxstream` to avoid conflict with newly installed display
manager with existing weston.

## Connect to host Android device with ADB
To establish ADB connection from the VM at terminal app to the host Android
device, check if `adbd` of the host Android device is listening to any vsock
ports in advance.

There are some properties to make `adbd` listening to the vsock port. To check
whether those properties exist or not, connect your Android device with USB by
following instruction at https://developer.android.com/tools/adb#Enabling, and
execute `adb shell getprop | grep adb` on your computer. If execution result
contains one or more lines below, continue to the later steps with the first
`PORT_NUMBER` ordered below.
1. `[service.adb.listen_addrs]: [vsock:<PORT_NUMBER>]`
1. `[service.adb.tcp.port]: [<PORT_NUMBER>]`
1. `[persist.adb.tcp.port]: [<PORT_NUMBER>]`

If none of the properties above is set, execute `adb tcpip <PORT_NUMBER>` on
your computer with picking any new `PORT_NUMBER`, to set the property with that
`PORT_NUMBER` and restart `adbd` with that property.

Then, execute commands below at terminal app to install `adb` and establish ADB
connection.

```bash
sudo apt update
sudo apt install adb
adb connect vsock:2:<PORT_NUMBER> # 2 is CID of the host Android device
```