[PATCH] doc: addressing architecture.adoc review changes

Ville Ilvonen
2022-06-07T06:43:36Z

* page-parent set
* updated copyright sloppiness
* hard wrapped to 80 characters
* updated reference app vm names in the diagram
* used proposed emphasis on kernel hardening
(a topic which would warrant a doc of its' own)
* added the missing definite article mentioned as
an example (don't mind a native English speaker to
spell/grammar check, though)
* Linked to comparison of C/POSIX standard library
implementations for Linux on musl arguments
* updated wayland-console to virtio-console
* used AsciiDoctor's xref
* added missing newline in adoc

Signed-off-by: Ville Ilvonen <ville.ilvonen@unikie.com>
---
Documentation/architecture.adoc | 63 +++++++++++++++++++++++------
Documentation/diagrams/stack.drawio | 2 +-
2 files changed, 51 insertions(+), 14 deletions(-)

diff --git a/Documentation/architecture.adoc b/Documentation/architecture.adoc
index 2f89e68..60b3baf 100644
--- a/Documentation/architecture.adoc
+++ b/Documentation/architecture.adoc
@@ -1,39 +1,76 @@
= Architecture
-// SPDX-FileCopyrightText: 2022 Ville Ilvonen <ville.ilvonen@unikie.com>
+:page-parent: Explanation
+
+// SPDX-FileCopyrightText: 2022 Unikie
// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0

== Introduction

-Spectrum operating system stack is based on the principle of security by compartmentalization. The high level system stack is illustrated in the following diagram.
+Spectrum operating system stack is based on the principle of security by
+compartmentalization. The high level system stack is illustrated in the
+following diagram.

image::diagrams/stack.svg[]

=== Kernel space

-In the stack, kernel space security by compartmentalization is supported with linux kernel that includes kernel-based virtual machine (KVM) module enabling the kernel to work as virtual-machine manager, hypervisor. Kernel side hypervisor supports virtualization of hardware resources - computational cores, memory and devices - securely. Userspace virtual machine guests are managed with cloud-hypervisor. Linux with KVM also supports portability to several hardware architectures. Currently Spectrum is supported only on x86_64 but ARM64 is under works. In addition, hardened kernel is to be enabled.
+In the stack, kernel space security by compartmentalization is supported with
+linux kernel that includes kernel-based virtual machine (KVM) module enabling
+the kernel to work as virtual-machine manager, hypervisor. The kernel-side
+hypervisor supports virtualization of hardware resources - computational cores,
+memory and devices - securely. User space virtual machine guests are managed
+with cloud-hypervisor. Linux with KVM also supports portability to several
+hardware architectures. Currently Spectrum is supported only on x86_64 but ARM64
+is under work. In addition, hardened kernel will be investigated.

=== Host user space

-This section provides high level overview of host user space tools and libraries.
+This section provides high level overview of host user space tools and
+libraries.

-User space stack is build on musl standard C library with added safety on resource exhaustion and security hardening on memory allocation.
+User space stack is build on musl standard C library with
+https://www.etalabs.net/compare_libcs.html[added safety on resource exhaustion
+and security hardening on memory allocation].

-https://skarnet.org/software/s6-rc/overview.html[s6-rc] service manager is used for services. kmod, util-linux and busybox are provided for essential system administration.
+https://skarnet.org/software/s6-rc/overview.html[s6-rc] service manager is used
+for services. kmod, util-linux and busybox are provided for essential system
+administration.

-https://github.com/cloud-hypervisor/cloud-hypervisor[cloud-hypervisor] is a host tooling for virtual machine management, written in Rust with a strong focus on security.
+https://github.com/cloud-hypervisor/cloud-hypervisor[cloud-hypervisor] is a host
+tooling for virtual machine management, written in Rust with a strong focus on
+security.

-Wayland refers to whole display stack providing communication with compositor (weston) for desktop services, including libraries and drivers for direct rendering and event devices. Clients are implemented as application virtual machines (see next section). Minimal host provides only Wayland terminal client, foot. Wayland, a simpler and more secure, protocol for compositor could provide support for legacy X applications as well but as of now none are provided. https://wayland.freedesktop.org/architecture.html[Wayland architecture] is well documented here.
+Wayland refers to whole display stack providing communication with compositor
+(weston) for desktop services, including libraries and drivers for direct
+rendering and event devices. Clients are implemented as application virtual
+machines (see next section). Minimal host provides only Wayland terminal client,
+foot. Wayland, a simpler and more secure, protocol for compositor could provide
+support for legacy X applications as well but as of now none are provided.
+https://wayland.freedesktop.org/architecture.html[Wayland architecture] is well
+documented here.

=== Application and system virtual machines

-Security by compartmentalization in Spectrum is implemented with virtual machines. Virtual machines currently launch using terminal and support only wayland-console. Wayland graphics support for appvms is under work. Please refer to https://spectrum-os.org/doc/running-vms.html[running VMs] for more information.
+Security by compartmentalization in Spectrum is implemented with virtual
+machines. Virtual machines currently launch using terminal and support only
+virtio-console. Wayland graphics support for appvms is under work. Please refer
+to xref:running-vms.html[running VMs] for more
+information.

-Reference set of virtual machines includes system machine, netvm, and application VMs, appvm-catgirl and appvm-elinks. Please refer to https://spectrum-os.org/doc/creating-vms.html[creating VMs] for more information.
+Reference set of virtual machines includes system machine, netvm, and
+application VMs, appvm-catgirl and appvm-elinks. Please refer to
+xref:creating-vms.html[creating VMs] for more
+information.

== Details of Spectrum dependency tree

-High level overview of Spectrum stack is limited view to the system. For detailed, interactive view to dependencies please use `nix-tree` under the spectrum repository:
+High level overview of Spectrum stack is limited view to the system. For
+detailed, interactive view to dependencies please use `nix-tree` under the
+spectrum repository:

-`nix-build img/live -I nixpkgs=https://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.gz --no-out-link | xargs -o nix-tree`
+`nix-build img/live -I
+nixpkgs=https://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.gz
+--no-out-link | xargs -o nix-tree`

-https://diode.zone/w/8DBDQ6HQUe5UUdLkpDuL35[See video of Spectrum live image interactive analysis with nix-tree]
\ No newline at end of file
+https://diode.zone/w/8DBDQ6HQUe5UUdLkpDuL35[See video of Spectrum live image
+interactive analysis with nix-tree]
diff --git a/Documentation/diagrams/stack.drawio b/Documentation/diagrams/stack.drawio
index 23feae7..bb42c1b 100644
--- a/Documentation/diagrams/stack.drawio
+++ b/Documentation/diagrams/stack.drawio
@@ -1 +1 @@
-<mxfile host="Electron" modified="2022-05-24T12:19:30.186Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/15.7.3 Chrome/91.0.4472.164 Electron/13.6.1 Safari/537.36" etag="8D9FBMK4C5lWSHGzQpql" version="15.7.3" type="device"><diagram id="C5RBs43oDa-KdzZeNtuy" name="Page-1">7VrbcuI4EP0aqiYPTPkOPBIyJJtkdneSnUnmaUtggVWRLUeSueTrV7JljC8ZHArjhZoXbLdal+5z1FJLdMyRv7qmIPS+EhfijqG5q4551TEMXdcM8ZCStZJohp1I5hS5SpYJHtEbTBWVNEIuZDlFTgjmKMwLpyQI4JTnZIBSssyrzQjO9xqCOSwJHqcAl6VPyOVeIu0bvUx+A9HcS3vWnUFS4oNUWVnCPOCS5ZbI/NIxR5QQnrz5qxHE0nupX57+WD/h+xfn+vYbewXfL+/++fNHN2ls/JEqGxMoDPjeTU+e7/r61e34/vvPt8Xz8hX2//qmqmgLgCPlr47hYNHJ5YyIvoS/wTQpcF4jaejlA5kQTrJv6Ri+xnklWbnLYi4MhYJhhKvtGs5cPm8AdZfCJqHwadV3LtKehQlJ54macv6mD4OSKHChtEoTxUsPcfgYJsNcChILmcd9LL70Te2drlMuXkDK4WqLOMqV15D4kNO1UFGlG36reeFY6nuZkcx2lMzbIlgqA4rX803TGXbiRcH3ASj1FqG8R0G0io0Xthva3Y+vJw2m3W8bTKNFMKeYRG7XW4eQLhAj9KSgNPt5KC2tDKWhHRNKswTlHaRBvMyy2D1FPwpLed5ZjFPyAkcECzDMq4AEUGKJMC6IAEbzQHxOhVOhkF9KvyGxFg5VgY9cV3ZTiU4ePwn1GPgIS0cqciVStcZLFJJvEtG4HY9zsagbtuSWLXwmf6QC+zwnZI4hCBH7PCV+XDBlsep4lvQhXrNeGiNHYZoP7BI39KppbjbFDavEjRvC5PSOmMDvN0FaJojVa5sgdovrgB8xMT4H+BL7YMLkoyu0R0XhuwtEIhYkDt4fhYI3Hsem4Y5hmlbMOGVMXixV499adjAOAlfsNX8x7GSI+WE372CMJhRIkpzQ+lraKhltb5V6FVOk4DkYuEOZSmaBcMtTtaPawaNYMVa6gHnxQD4OIHRzWXAZvm14KtBJZRRiwNEinztXQaZ6+JugeJak7HhnH522wGIfqkrbuWqhHX2woyEO6BzyUkMxgTZW1+LUM354ewrGV7fL4XDQ5Xr47+T+IGnxR4LgzhDmdOl0R7xqIHyUwkJdQtYOH5ZTDh+DhqJHJdLl3Xm7SC/BGovl6hywtmukYrp+TLDL2+12wZ5EbD0hq3MA29F2T2y9d0ywD7F1PiTYM3lQHO9x48YmNC34JFIx/+IsSDDYPeP7x+SA8z/jwItPziK0m3Vmu3VMpAcHQHpfVCOOcBcnR+Clye2jAPkAX5SLTgpxy6qBeFN5XyXiepsXHkwkILy78E8Kw9Lmu2pDdtQ1Wm/zniOAPANwa8ayNVv4pz5fi1hvMvxtrKsyLd1uDOyqXOtsTmoKJzD7A3ikkxo7Rw9zMMi3UP+kZkdDDZ/U6IfI6faNIIgyhioiCAjD048gllYjglStFg1GkDavQ6DY4b2wc0Xb7u1Gu/LevEG0y9nbA5xBYaa8E9UWiPII4LLffTD1UABZydG/702bYk/h3tTUayYHe9ybis/sL3fJKpL9c9H88h8=</diagram></mxfile>
\ No newline at end of file
+<mxfile host="Electron" modified="2022-06-07T05:42:17.682Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/15.7.3 Chrome/91.0.4472.164 Electron/13.6.1 Safari/537.36" etag="_9gN0vdoL1l32oJlLSGM" version="15.7.3" type="device"><diagram id="C5RBs43oDa-KdzZeNtuy" name="Page-1">7Vpbc5s6EP41nmke3OFu+9Fx6uQk6WmbnDY5Tx0ZZNBEICIJX/LrjwTCGEOOnYwxtScvBlaLpN3v25UWuWOOwsUlBXHwlXgQdwzNW3TMi45h6LpmiIuULJVEM+xM4lPkKVkhuEcvMFdU0gR5kJUUOSGYo7gsdEkUQZeXZIBSMi+rTQkujxoDH1YE9y7AVekD8niQSftGr5BfQeQH+ci6M8haQpArK0tYADwyXxOZXzrmiBLCs7twMYJYei/3y8Nfywd8++RcXv9gz+Dn+c0/f//qZp2N3/LKygQKI/7uriePN3394np8+/Pfl9nj/Bn2v/1Qr2gzgBPlr47hYDHI+ZSIsYS/gZs1OM+JNPT8jkwIJ8WzdAxf4rKSfLnLUi4MhYJhxIv1NxxfXq8A9ebCJqHwadF3zvKRhQnZ4Jmacv5qDIOSJPKgtEoTzfMAcXgfZ9OcCxILWcBDLJ701dtbXadcPIOUw8UacZQrLyEJIadLoaJaV/xWceFY6nlekMx2lCxYI1guA4rX/qrrAjtxo+B7A5R6i1DeoihZpMYL2w3t5tfXowbT7rcNptEimC4midcNljGkM8QIPSoozX4ZSkurQmloh4TSrEB5A2mULrMsdc+mH4WlvOwsxil5giOCBRjmRUQiKLFEGG+IAEZ+JB5d4VQo5OfSb0ishUPVECLPk8PUolPGT0I9BiHC0pGKXJlUrfESheyZJDTtJ+BcLOqGLbllC5/JH6nAPvuE+BiCGLHPLgnTBpelquNpNoa4LUZpjBwbYT6wK9zQ68LcbIobVoUbV4TJ8E6YwO+DIC0TxOq1TRC7xXUgTJiYnwNCiX00YfLSFdqjTeGrC0QmFiSOXp+Fgjedx6rjjmGaVso4ZUxZLFXT353sYBxEnthr/s+0symWp928gzGaUCBJckTra2WrZLS9VerVhMiG52DkDWUpWSTCNU/tnNX2nsU2c6UHWJBO5O0AQq9UBVfhW4enBp1cRiEGHM3KtXMdZGqE7wSlUZKz45V9dN4DS32oXlqvVTf60QdbOuKA+pBXOkoJtLJ6J0494ruXh2h8cT0fDgddrse/J7d7KYvfkgS3pjCnS90t+eoo04flVNPHoKHsUYt0dXfeLtJzsMRiuToFrO0dSjFdPyTY1e12u2BPErackMUpgO1o2wNb7x0S7H1snfcJ9lR+KE73uGlnE5o3fBKlWHh2EiQYbI/4/iE54PxhHHgKyUmkdnOXaLcOifRgD0i/F9WEI9zF2SfwSnCHKEIhwGfVpqNC3LJ2QLypuq8Wcb3NAw8mChDenYVHhWFl8123ITvoGq23ec4RQV4AuBaxbMlm4bHH6ybWqwp/Heu6Sku3GwO7rtb6+FLT0pcau0QPczAo97D7l5otHTX8pUbfR0337pNSwH1EcU0OAXF8/DnE0nbIIXXrRYM5pM0DEbyM6nZ4J4G13duOde25eYNYV6u3OziFwnJ5JqrNEOUJqAm+ELgBiiCrOPrj3LQp9mycm5r6jsXBO85NxWPxl7tsFSn+uWh++Q8=</diagram></mxfile>
\ No newline at end of file
--
2.33.3