* ADRs based on discussions with Alyssa
* A note on ADRs to architecture.adoc
Signed-off-by: Ville Ilvonen <ville.ilvonen(a)unikie.com>
---
Documentation/architecture.adoc | 13 ++++++++++
...architecture-decision-record-template.adoc | 13 ++++++++++
.../decisions/001-host-update-mechanism.adoc | 19 ++++++++++++++
.../decisions/002-install-options.adoc | 18 +++++++++++++
Documentation/decisions/003-partitioning.adoc | 25 +++++++++++++++++++
.../004-data-at-rest-encryption.adoc | 16 ++++++++++++
.../005-virtual-machine-manager.adoc | 24 ++++++++++++++++++
.../decisions/006-drivers-on-host.adoc | 17 +++++++++++++
.../decisions/007-USB-virtual-machine.adoc | 14 +++++++++++
...008-Inter-VM-communication-mechanisms.adoc | 18 +++++++++++++
10 files changed, 177 insertions(+)
create mode 100644 Documentation/decisions/000-lightweight-architecture-decision-record-template.adoc
create mode 100644 Documentation/decisions/001-host-update-mechanism.adoc
create mode 100644 Documentation/decisions/002-install-options.adoc
create mode 100644 Documentation/decisions/003-partitioning.adoc
create mode 100644 Documentation/decisions/004-data-at-rest-encryption.adoc
create mode 100644 Documentation/decisions/005-virtual-machine-manager.adoc
create mode 100644 Documentation/decisions/006-drivers-on-host.adoc
create mode 100644 Documentation/decisions/007-USB-virtual-machine.adoc
create mode 100644 Documentation/decisions/008-Inter-VM-communication-mechanisms.adoc
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/ma… 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..087ec44
--- /dev/null
+++ b/Documentation/decisions/000-lightweight-architecture-decision-record-template.adoc
@@ -0,0 +1,13 @@
+# Title
+
+## 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..03bbae2
--- /dev/null
+++ b/Documentation/decisions/001-host-update-mechanism.adoc
@@ -0,0 +1,19 @@
+# Host update mechanism
+
+## 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..f5857c5
--- /dev/null
+++ b/Documentation/decisions/002-install-options.adoc
@@ -0,0 +1,18 @@
+# Install options
+
+## 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
+(optionally 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..345619f
--- /dev/null
+++ b/Documentation/decisions/003-partitioning.adoc
@@ -0,0 +1,25 @@
+# Partitioning
+
+## 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..3ed9abb
--- /dev/null
+++ b/Documentation/decisions/004-data-at-rest-encryption.adoc
@@ -0,0 +1,16 @@
+# Data at rest encryption
+
+## 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..b4af595
--- /dev/null
+++ b/Documentation/decisions/005-virtual-machine-manager.adoc
@@ -0,0 +1,24 @@
+# Virtual Machine Manager
+
+## Status
+Accepted
+
+## Context
+rust-vmm-based VMM provides memory and concurrency safe solution.
+cloud-hypervisor was chosen because firecrack 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..052b596
--- /dev/null
+++ b/Documentation/decisions/006-drivers-on-host.adoc
@@ -0,0 +1,17 @@
+# Drivers on host
+
+## 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..2072427
--- /dev/null
+++ b/Documentation/decisions/007-USB-virtual-machine.adoc
@@ -0,0 +1,14 @@
+# USB Virtual Machine
+
+## 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..1007037
--- /dev/null
+++ b/Documentation/decisions/008-Inter-VM-communication-mechanisms.adoc
@@ -0,0 +1,18 @@
+### Inter VM communication mechanisms
+
+### 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
--
2.36.0
Hi all,
As Ivan (@jonne) updated earlier this week on #spectrum, we've got initial cross-compilation support for aarch64 available in Spectrum development fork. It still needs some TLC before Spectrum PRs but is a great step forward. Our current ref. board is NXP i.MX8 but rootfs build should be fairly easy to modify for RPi4 configs already in nixpkgs for anyone who cares to try.
Quick how-to for non-nixos host like Ubuntu:
git clone -b aarch64-imx8-crosscompile https://github.com/tiiuae/nixpkgs-spectrum.git
git clone -b aarch64-imx8-crosscompile https://github.com/tiiuae/spectrum.git
cd spectrum/host/rootfs
nix-build -I nixpkgs=../../../nixpkgs-spectrum
Know issue:
- crossSystem from https://github.com/tiiuae/spectrum/commit/aad5f90cf2ec931f2af5c8d5111a9fac1… is ignored on NixOS host but not on Ubuntu - maybe someone can point us why.
Thanks,
-Ville
