First attempt at some documentation
Signed-off-by: Marc Zyngier <marc.zyngier@arm.com>
diff --git a/README b/README
new file mode 100644
index 0000000..cc2d482
--- /dev/null
+++ b/README
@@ -0,0 +1,90 @@
+TiNLV: This is Not LibVirt
+
+This repository contains a bag of scripts I cobbled together to easily
+install and run KVM/arm64 UEFI based VMs, acting as a middle ground
+between the full complexity of the QEMU command line and the awkward
+abstraction provided by LibVirt. The VMs can either be ephemeral (they
+are destroyed on exit) or made persistent (though no effort is made to
+keep them running).
+
+There are essentially three major scripts here:
+
+- runefivm.sh runs a guest, taking a bunch of parameters such as the
+ disk image, the EFI binary, the number of CPUs...
+
+- runinstallvm.sh is a very simple wrapper for runefivm.sh, creating
+ the storage for the VM, and either destroying it once it ends, or
+ moving it into a safe location for later reuse.
+
+- build-cd-image is only slightly related to the above. It takes a
+ Debian or Ubuntu CD/DVD image, and messes with it enough that it
+ becomes an unattended installer.
+
+All the scripts are expected to be run from the vminstall
+directory. Yes, this is a braindead expectation, and maybe I'll fix it
+at some point. Maybe.
+
+* runefivm.sh [QEMU args]
+
+ runefivm.sh is entirely driven by environment variables, and
+ provides more or less sensible defaults when the variable is not
+ defined:
+
+ - EFI: The EFI (AAVMF) binary. Defaults to
+ /usr/share/AAVMF/AAVMF_CODE.fd
+
+ - EFIVAR: The per-VM EFI variable container. Defauts to no variables.
+
+ - DISK: The raw file containing the VM mass storage. Defaults to
+ none.
+
+ - BUS: The bus on which the virtio devices are created. Can be
+ "device" or "pci", defaults to "pci".
+
+ - NETIF: The host network interface for this VM. Can be a tap or
+ macvtap interface (which enables vhost), or "none" (which
+ indicates that no networking is to be provided). When absent,
+ userspace networking is provided to the guest.
+
+ - GIC: The GIC version. Use "2" to force GICv2, "3" for GICv3+ITS,
+ "3,noits" for GICv3 without an ITS. Defaults to "host", which is
+ whichever is physically present.
+
+ - BIT: 32 or 64, defaults to 64. There is no UEFI/GRUB installer for
+ 32bit, so that's all a bit moot.
+
+ - CPUS: Number of CPUs, defaults to 4.
+
+ - RAM: Memory size, defaults to 1G.
+
+ - CDROM: A cdrom image provided to the guest, defaults to no cdrom
+ at all.
+
+ - QEMU: The QEMU binary, defaults to /usr/bin/qemu-system-aarch64.
+
+ Any additional parameter is directly passed to QEMU.
+
+* runinstallvm.sh [QEMU args]
+
+ All the environment variables used by runefivm.sh are equaly valid
+ for runinstallvm.sh, with the exception of DISK and EFIVAR (which it
+ overrides). In addition, it provides the following:
+
+ - KEEPME: When provided, create a directory with that name, and
+ store the VM disk and EFI variables in that directory. Also
+ generate a "runvm.sh" script in the same directory, which calls
+ runefivm.sh with the right environment variables.
+
+* build-cd-image source.iso target.iso
+
+ Takes source.iso, add preseed.cfg to it, add a new grub entry for
+ unattended installation, repack the whole thing as target.iso. The
+ only VM user is root, password is root. Don't try this on a publicly
+ visible box... Depends on the xorriso package being installed.
+
+Example:
+
+ $ ./build-cd-image ../debian-9.0.0-arm64-netinst.iso ../debian-9.0.0-arm64-netinst-preseed.iso
+ $ CDROM=../debian-9.0.0-arm64-netinst-preseed.iso RAM=2G KEEPME=stretch ./runinstallvm.sh
+ [halt the VM]
+ $ ./stretch/runvm.sh
