Merge pull request #2883 from rn/qemu-doc

docs: Add initial qemu documentation

docs/platform-qemu.md

@@ -1,15 +1,36 @@
 # LinuxKit with qemu/kvm
 
-TBD
+The `qemu` backend is the most versatile `run` backend for
+`linuxkit`. It can boot both `x86_64` and `arm64` images, runs on
+macOS and Linux (and possibly Windows), and can boot most types of
+output formats. On Linux, `kvm` acceleration is enabled by default if
+available.
+
 
 ## Boot
 
-TBD: Describe the different boot modes (kernel+initrd, iso, efi, disk etc)
+By default `linuxkit run qemu` will boot with the host architecture
+(`x86_64` on `x86_64` machines and `aarch64` on `arm64` systems). The
+architecture can be specified with `-arch` and currently accepts
+`x86_64` and `aarch64` as arguments.
+
+`linuxkit run qemu` can boot in different types of images:
+
+- `kernel+initrd`: This is the default mode of `linuxkit run qemu` [`x86_64`, `arm64`]
+- `iso-bios`: `linuxkit run qemu -iso <path to iso>` [`x86_64`]
+- `iso-efi`: `linuxkit run qemu -iso -uefi <path to iso>`. This looks in `/usr/share/ovmf/bios.bin` for the EFI firmware by default. Can be overwritten with `-fw`. [`x86_64`, `arm64`]
+- `qcow-bios`: `linuxkit run qemu disk.qcow2` [`x86_64`]
+- `raw-bios`:  `linuxkit run qemu disk.img` [`x86_64`]
+- `aws`: `linuxkit run qemu disk.img` boots a raw AWS disk image. [`x86_64`]
+
+The formats `qcow-efi` and `raw-efi` may also work, but are currently not tested.
 
 
 ## Console
 
-TBD: 
+With `linuxkit run qemu` the serial console is redirected to stdio,
+providing interactive access to the VM. You can specify `-gui` to get
+a console window.
 
 
 ## Disks
@@ -21,13 +42,32 @@ supports a number of different disk formats.
 
 ## Networking
 
-TBD
+The `qemu` backend supports a number of networking options, depending
+on the platform you are running. The default is the userspace
+networking which provides the VM with a internal DHCP server and
+network connectivity, but does not provide access to the VMs network
+from the outside.
+
+With user mode networking you can publish selected VM ports on the
+host, using the `-publish` option. It uses the same syntax as the
+`qemu` binary. For example `linuxkit run qemu -publish 8080:80
+linuxkit` exposes port `80` from the VM as port `8080` on the host.
+
+On Linux, you can attach the VM either to an existing bridge or tap
+interface. These require root privileges and you may want to use the
+[`qemu-bridge-helper`](http://wiki.qemu.org/Features/HelperNetworking). To
+attach to an existing bridge `br0` (e.g., one created with
+`virt-manager`) you can use `linuxkit run qemu -networking
+bridge,br0 linuxkit`.
 
-Also explain port forwarding
 
 ## Integration services and Metadata
 
-TBD: Integration services
+The `qemu` backend also allows passing custom userdata into the
+[metadata package](./metadata.md) using either the `-data` or
+`-data-file` command-line option. This attaches a CD device with the
+data on.
 
-The qemu backend currently does not support passing metadata/userdata
+If the `linuxkit/qemu-ga` package is added to the YAML the [Qemu Guest
-to the VM.
+Agent](https://wiki.libvirt.org/page/Qemu_guest_agent) will be
+enabled. This provides better integration with `libvirt`.