Documentation: Architecture Decision Record

* ADRs based on discussions with Alyssa
* A note on ADRs to architecture.adoc
* Addressed devel review comments:
  - copyright + reuse lint
  - drop "optional" on encryption

Signed-off-by: Ville Ilvonen <ville.ilvonen@unikie.com>
Message-Id: <CAP-nJwHX11dzQ+aoWsbOx4DzVRYE3LOp7eKV1cU9_ykpFssA3g@mail.gmail.com>
Reviewed-by: Alyssa Ross <hi@alyssa.is>
Signed-off-by: Alyssa Ross <hi@alyssa.is>

10 files changed, 204 insertions, 0 deletions

diff --git a/Documentation/architecture.adoc b/Documentation/architecture.adoc
index 157907f..185740c 100644
--- a/Documentation/architecture.adoc
+++ b/Documentation/architecture.adoc
@@ -20,6 +20,19 @@ devices and provides network services to application VMs).  Refer to
 xref:creating-vms.adoc[Creating VMs] and xref:running-vms.adoc[Running
 VMs] for more information about using VMs in Spectrum.
 
+== Architecture Decision Record (ADR)
+
+https://adr.github.io/[Architecturally significant decisions] are
+recorded as https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/templates/decision-record-template-by-michael-nygard/index.md[light-weight ADRs]
+
+Status of Spectrum OS ADRs:
+Accepted - Implemented and likely not to change.
+Proposed - Designed and possibly partially implmented. May change.
+Other - Not yet in use.
+
+Comments and contributions to ADRs are welcome. ADRs can be found at
+Documentation/decisions
+
 == The Spectrum host system
 
 Compartmentalization is implemented using
diff --git a/Documentation/decisions/000-lightweight-architecture-decision-record-template.adoc b/Documentation/decisions/000-lightweight-architecture-decision-record-template.adoc
new file mode 100644
index 0000000..2535cb3
--- /dev/null
+++ b/Documentation/decisions/000-lightweight-architecture-decision-record-template.adoc
@@ -0,0 +1,16 @@
+# Title
+
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+## Status
+What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.?
+
+## Context
+What is the issue that we're seeing that is motivating this decision or change?
+
+## Decision
+What is the change that we're proposing and/or doing?
+
+## Consequences
+What becomes easier or more difficult to do because of this change?
diff --git a/Documentation/decisions/001-host-update-mechanism.adoc b/Documentation/decisions/001-host-update-mechanism.adoc
new file mode 100644
index 0000000..56a37fc
--- /dev/null
+++ b/Documentation/decisions/001-host-update-mechanism.adoc
@@ -0,0 +1,22 @@
+# Host update mechanism
+
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+## 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.
+
+## 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
+Default boot selection, incremental updates (e.g. overlays), network update
+postponed for later.
diff --git a/Documentation/decisions/002-install-options.adoc b/Documentation/decisions/002-install-options.adoc
new file mode 100644
index 0000000..79b5a64
--- /dev/null
+++ b/Documentation/decisions/002-install-options.adoc
@@ -0,0 +1,21 @@
+# Install options
+
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+## 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.
+
+## 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
+Requires first-boot-vm (like wizard) to support user to get started.
diff --git a/Documentation/decisions/003-partitioning.adoc b/Documentation/decisions/003-partitioning.adoc
new file mode 100644
index 0000000..a78641f
--- /dev/null
+++ b/Documentation/decisions/003-partitioning.adoc
@@ -0,0 +1,28 @@
+# Partitioning
+
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+## Status
+Proposed
+
+## Context
+Partitions are required to install the Spectrum OS, VMs and store user data.
+
+## Decision
+----
+<blockdevice>                        # EFI system partition
+<blockdevice>                        # XBOOTLDR
+<blockdevice>                        # A
+<blockdevice>                        # B
+# first 32 GB are reserved for Spectrum system
+# rest of the disk is reserved for user data
+<blockdevice>n-1                     # bootstrap 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
diff --git a/Documentation/decisions/004-data-at-rest-encryption.adoc b/Documentation/decisions/004-data-at-rest-encryption.adoc
new file mode 100644
index 0000000..43eb52c
--- /dev/null
+++ b/Documentation/decisions/004-data-at-rest-encryption.adoc
@@ -0,0 +1,19 @@
+# Data at rest encryption
+
+// 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 user data and privacy protection, encryption of data at rest is
+required.
+
+## 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?
diff --git a/Documentation/decisions/005-virtual-machine-manager.adoc b/Documentation/decisions/005-virtual-machine-manager.adoc
new file mode 100644
index 0000000..501db24
--- /dev/null
+++ b/Documentation/decisions/005-virtual-machine-manager.adoc
@@ -0,0 +1,27 @@
+# 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/006-drivers-on-host.adoc b/Documentation/decisions/006-drivers-on-host.adoc
new file mode 100644
index 0000000..f05e634
--- /dev/null
+++ b/Documentation/decisions/006-drivers-on-host.adoc
@@ -0,0 +1,20 @@
+# Drivers on host
+
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+## 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.
+
+## Decision
+We are aiming to have as few drivers as possible on the host.
+
+## 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.
diff --git a/Documentation/decisions/007-USB-virtual-machine.adoc b/Documentation/decisions/007-USB-virtual-machine.adoc
new file mode 100644
index 0000000..d87b35b
--- /dev/null
+++ b/Documentation/decisions/007-USB-virtual-machine.adoc
@@ -0,0 +1,17 @@
+# 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/008-Inter-VM-communication-mechanisms.adoc b/Documentation/decisions/008-Inter-VM-communication-mechanisms.adoc
new file mode 100644
index 0000000..0a238d8
--- /dev/null
+++ b/Documentation/decisions/008-Inter-VM-communication-mechanisms.adoc
@@ -0,0 +1,21 @@
+### 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