Documentation: copy-edit and integrate ADRs

This makes the ADRs accessible from the documentation site, and adds
an index page for them, into which I moved the explanation of what
they are.

Signed-off-by: Alyssa Ross <hi@alyssa.is>

12 files changed, 205 insertions, 124 deletions

diff --git a/Documentation/decisions/001-host-update-mechanism.adoc b/Documentation/decisions/001-host-update-mechanism.adoc
index 56a37fc..574deb4 100644
--- a/Documentation/decisions/001-host-update-mechanism.adoc
+++ b/Documentation/decisions/001-host-update-mechanism.adoc
@@ -1,22 +1,31 @@
-# Host update mechanism
+= 001 Host Update Mechanism
+:page-parent: Architecture Decision Records
+:page-grand_parent: Explanation
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
 
-## Status
+== Status
+
 Proposed
 
-## Context
-Spectrum OS has no implementation for software update. The host - consisting of
-Linux kernel, KVM, cloud-hypervisor and minimal user space tools - software
-updates are required to support feature development and security fixes.
+== Context
+
+Spectrum currently has no implementation for software update. The host --
+consisting of the Linux kernel, KVM, cloud-hypervisor and minimal user space
+tools -- will require software updates to support feature development and
+security fixes.
+
+== Decision
+
+The Spectrum installer will set up the system on partition A of the block
+device, as part of an A/B update scheme where user (or installer) writes the
+update image to partition B.
+
+The bootloader will provide four boot options: _A_, _A (mutable)_, _B_, _B
+(mutable)_.
 
-## Decision
-A-B partitioning created by Spectrum installer Installer sets up the system on
-partition A of the block device A-B update scheme where user (or installer)
-writes the update image to partition B Bootloader provides four boot options:
-A, A mutable, B, B mutable
+== Consequences
 
-## Consequences
-Default boot selection, incremental updates (e.g. overlays), network update
-postponed for later.
+Default boot selection, incremental updates (e.g. overlays), and over-the-air
+updates are postponed for later.
diff --git a/Documentation/decisions/002-install-options.adoc b/Documentation/decisions/002-install-options.adoc
index 79b5a64..4412b53 100644
--- a/Documentation/decisions/002-install-options.adoc
+++ b/Documentation/decisions/002-install-options.adoc
@@ -1,21 +1,28 @@
-# Install options
+= 002 Install options
+:page-parent: Architecture Decision Records
+:page-grand_parent: Explanation
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
 
-## Status
+== Status
+
 Proposed
 
-## Context
-Based on identified different audiences for the Spectrum OS release it is
-proposed we support three base configurations to use with Spectrum OS in the
-first boot.
+== Context
+
+Based on identified different audiences for the Spectrum release it is
+proposed we support three base configurations to use with Spectrum, to
+be chosen from at the first boot.
+
+== Decision
+
+Minimal :: Spectrum host + system VMs: network VM, GUI VM, USB VM.
+xref:004-data-at-rest-encryption.adoc[Encrypted] user data partition.
+Common :: Minimal + browser app VM + 2-3 selected application VMs.
+Power :: Common + NixOS VM.
 
-## Decision
-* Minimal - Spectrum OS host + system VMs: netvm, guivm, usbvm + home-directory
-  encrypted (see 004-disk-encryption.md)
-* Common - Minimal + browser app VM + 2-3 selected app VMs
-* Power - Common + NixOS VM
+== Consequences
 
-## Consequences
-Requires first-boot-vm (like wizard) to support user to get started.
+Requires a first boot VM (like a wizard) to allow the user to choose
+their configuration and get started.
diff --git a/Documentation/decisions/003-partitioning.adoc b/Documentation/decisions/003-partitioning.adoc
index a78641f..8494ea4 100644
--- a/Documentation/decisions/003-partitioning.adoc
+++ b/Documentation/decisions/003-partitioning.adoc
@@ -1,15 +1,21 @@
-# Partitioning
+= 003 Partitioning
+:page-parent: Architecture Decision Records
+:page-grand_parent: Explanation
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
 
-## Status
+== Status
+
 Proposed
 
-## Context
-Partitions are required to install the Spectrum OS, VMs and store user data.
+== Context
+
+Partitions are required to install the Spectrum operating system, VMs
+and store user data.
+
+== Decision
 
-## Decision
 ----
 <blockdevice>                        # EFI system partition
 <blockdevice>                        # XBOOTLDR
@@ -21,8 +27,10 @@ Partitions are required to install the Spectrum OS, VMs and store user data.
 <blockdevice>n to the end of disk    # user data
 ----
 
-## Consequences
-LVM may support resizing - both increasing and decreasing with some limitation
-when there's alreay data on volume(s). Does LVM work with all disk types? We
-have to implement XBOOTLDR to support EFI system partition created by Windows -
-to support dual boot
+== Consequences
+
+- LVM may support resizing - both increasing and decreasing with some limitation
+when there's alreay data on volume(s).
+- Does LVM work with all disk types?
+- We have to implement XBOOTLDR to support EFI system partition
+  created by Windows -- to support dual boot.
diff --git a/Documentation/decisions/004-data-at-rest-encryption.adoc b/Documentation/decisions/004-data-at-rest-encryption.adoc
index 43eb52c..26fe273 100644
--- a/Documentation/decisions/004-data-at-rest-encryption.adoc
+++ b/Documentation/decisions/004-data-at-rest-encryption.adoc
@@ -1,19 +1,24 @@
-# Data at rest encryption
+= 004 Data at Rest Encryption
+:page-parent: Architecture Decision Records
+:page-grand_parent: Explanation
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
 
-## Status
+== Status
+
 Proposed
 
-## Context
-To support user data and privacy protection, encryption of data at rest is
-required.
+== Context
+
+For privacy protection, encryption of user data at rest is required.
+
+== Decision
 
-## Decision
 User data is encrypted.
 
-## Consequences
-Spectrum OS needs to come with enough SW to get the encryption key via different
-methods (password, usb, fido, etc.) Can we use dm-crypt for everything instead
-of LUKS?
+== Consequences
+
+Spectrum needs to come with enough software to get the encryption key
+via different methods (password, usb, fido, etc.)  Can we use dm-crypt
+for everything instead of LUKS?
diff --git a/Documentation/decisions/005-virtual-machine-manager.adoc b/Documentation/decisions/005-virtual-machine-manager.adoc
deleted file mode 100644
index 501db24..0000000
--- a/Documentation/decisions/005-virtual-machine-manager.adoc
+++ /dev/null
@@ -1,27 +0,0 @@
-# Virtual Machine Manager
-
-// SPDX-FileCopyrightText: 2022 Unikie
-// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
-
-## Status
-Accepted
-
-## Context
-rust-vmm-based VMM provides memory and concurrency safe solution.
-cloud-hypervisor was chosen because firecracker does not support other
-virtio-devices than net or block. crosvm was not chosen because cloud-hypervisor
-has more flexible IPC mechanisms, more engaging community as LF-project.
-cloud-hypervisor has more core features - such as snapshotting, live migration
-and more general hot plugging. crosvm supports more devices we will also need.
-It was seen easier to port devices from crosvm to cloud-hypervisor than to port
-core features from cloud-hypervisor to crosvm.
-
-## Decision
-Spectrum OS design and implementation decision is to use cloud-hypervisor as the
-primary VMM.
-
-## Consequences
-We gotta port some stuff from crosvm to cloud-hypervisor. It's easier for
-Spectrum to handle virtualization dynamically with cloud-hypervisor. If the
-primary VMM, cloud-hypervisor, is exchanged for trials etc. functionality is
-expected to break or not supported.
diff --git a/Documentation/decisions/005-virtual-machine-monitor.adoc b/Documentation/decisions/005-virtual-machine-monitor.adoc
new file mode 100644
index 0000000..db81c72
--- /dev/null
+++ b/Documentation/decisions/005-virtual-machine-monitor.adoc
@@ -0,0 +1,42 @@
+= 005 Virtual Machine Monitor
+:page-parent: Architecture Decision Records
+:page-grand_parent: Explanation
+
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+== Status
+
+Accepted
+
+== Context
+
+The https://github.com/rust-vmm[rust-vmm] project provides shared components for
+building Virtual Machine Monitors (VMMs) in the Rust programming language.
+Rust's focus on memory safety makes it a very compelling choice for
+Spectrum's VMM.
+
+The extant rust-vmm-based VMMs are https://google.github.io/crosvm/[crosvm]
+https://firecracker-microvm.github.io/[Firecracker], and
+https://www.cloudhypervisor.org/[Cloud Hypervisor].
+
+Firecracker does not support other virtio-devices than net or block.
+
+In comparision to crosvm, Cloud Hypervisor has a more flexible IPC mechanisms,
+better hotplugging support, and a more engaging community as a Linux Foundation
+project.  Cloud Hypervisor additionally has more core features - such as
+snapshotting, live migration. crosvm supports more devices we will also need.
+
+It will be easier to port devices from crosvm to cloud-hypervisor than to port
+core features from cloud-hypervisor to crosvm.
+
+== Decision
+
+Spectrum will use cloud-hypervisor as the primary VMM.
+
+== Consequences
+
+- Some devices need to be ported from crosvm to cloud-hypervisor.
+
+- Spectrum functionality is expected to break and not supported if the
+  primary VMM is swapped out.
diff --git a/Documentation/decisions/006-drivers-on-host.adoc b/Documentation/decisions/006-drivers-on-host.adoc
index f05e634..872044e 100644
--- a/Documentation/decisions/006-drivers-on-host.adoc
+++ b/Documentation/decisions/006-drivers-on-host.adoc
@@ -1,20 +1,27 @@
-# Drivers on host
+= 006 Drivers on Host
+:page-parent: Architecture Decision Records
+:page-grand_parent: Explanation
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
 
-## Status
+== Status
+
 Accepted
 
-## Context
-To harden the trusted computing base and make it more minimal, the target is to
-minimize the amount of drivers on the Spectrum host kernel.
+== Context
+
+It's important to minimize the amount of software in Spectrum's Trusted
+Computing Base (TCB).
+
+== Decision
+
+As few drivers as possible should be running on the Spectrum host.
 
-## Decision
-We are aiming to have as few drivers as possible on the host.
+== Consequences
 
-## Consequences
-No networking on the host. Responsibilities of the host are expected to get
-smaller over time. More flexible management of devices. We need to decouple
-device classes - like net, usb, bluetooth and gui - from host to their
-respective VMs.
+- No networking on the host.
+- Responsibilities of the host are expected to get smaller over time.
+- More flexible management of devices. We need to decouple devices from the host
+  based on their class -- like net, usb, bluetooth and GUI -- and pass them
+  through to their respective device VMs.
diff --git a/Documentation/decisions/007-USB-virtual-machine.adoc b/Documentation/decisions/007-USB-virtual-machine.adoc
deleted file mode 100644
index d87b35b..0000000
--- a/Documentation/decisions/007-USB-virtual-machine.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-# USB Virtual Machine
-
-// SPDX-FileCopyrightText: 2022 Unikie
-// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
-
-## Status
-Proposed
-
-## Context
-To support specific USB devices on specific VMs
-
-## Decision
-The decision is to pass-through USB controller to a VM with authorization
-controls inside the VMs to forward a specific USB device using USBIP.
-
-## Consequences
-We need to modify the upstream USBIP daemon to support authorization.
diff --git a/Documentation/decisions/007-usb-virtual-machines.adoc b/Documentation/decisions/007-usb-virtual-machines.adoc
new file mode 100644
index 0000000..3bdf78b
--- /dev/null
+++ b/Documentation/decisions/007-usb-virtual-machines.adoc
@@ -0,0 +1,24 @@
+= 007 USB Virtual Machine
+:page-parent: Architecture Decision Records
+:page-grand_parent: Explanation
+
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+== Status
+
+Proposed
+
+== Context
+
+Certain VMs will need access to specific USB devices, but with passthrough from
+the host we can only pass through whole USB controllers, not individual devices.
+
+== Decision
+
+USB controllers will be passed through to a VM with authorization controls
+inside the VMs to forward a specific USB device using USBIP.
+
+== Consequences
+
+We need to modify the upstream USBIP daemon to support authorization.
diff --git a/Documentation/decisions/008-Inter-VM-communication-mechanisms.adoc b/Documentation/decisions/008-Inter-VM-communication-mechanisms.adoc
deleted file mode 100644
index 0a238d8..0000000
--- a/Documentation/decisions/008-Inter-VM-communication-mechanisms.adoc
+++ /dev/null
@@ -1,21 +0,0 @@
-### Inter VM communication mechanisms
-
-// SPDX-FileCopyrightText: 2022 Unikie
-// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
-
-### Status
-Proposed
-
-### Context
-Guest VM software needs to communicate with software in other guest VMs
-
-### Decision
-Spectrum provides two mechanism
-- TCP/IP with virtio-net
-- Wayland with virtio-gpu (nevermind the semantics) for streamed IPC protocol to
-  send references to shared memory
-
-
-### Consequences
-- Examples required on how to write applications which communicate over
-  virtio-gpu
diff --git a/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc b/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc
new file mode 100644
index 0000000..a1b7d49
--- /dev/null
+++ b/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc
@@ -0,0 +1,27 @@
+= 008 Inter-VM Communication Mechanisms
+:page-parent: Architecture Decision Records
+:page-grand_parent: Explanation
+
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+== Status
+
+Proposed
+
+== Context
+
+Guest VM software needs to communicate with software in other guest VMs.
+
+== Decision
+
+Spectrum provides two mechanisms for inter-guest communication:
+
+- TCP/IP with virtio-net
+- Cross-domain virtio-gpu which can send references to shared memory
+  and be used as a transport for a stream protocol, e.g. Wayland.
+
+== Consequences
+
+- Examples will be required on how to write applications which
+  communicate over virtio-gpu.
diff --git a/Documentation/decisions/index.adoc b/Documentation/decisions/index.adoc
new file mode 100644
index 0000000..61f20fc
--- /dev/null
+++ b/Documentation/decisions/index.adoc
@@ -0,0 +1,17 @@
+= Architecture Decision Records
+:page-has_children: true
+:page-parent: Explanation
+
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+https://en.wikipedia.org/wiki/Architectural_decision[Architecturally
+significant decisions] are recorded as lightweight
+https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions/[ADRs].
+
+Statuses Spectrum ADRs can be in are:
+
+Accepted :: Implemented and likely not to change.
+Proposed :: Designed and possibly partially implemented.  May change.
+
+Comments and contributions to ADRs are welcome.