Random readme change

README.md

@@ -3,14 +3,29 @@
     SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
+Another change for existing PR
+
+Change by mnokka-unikie
+
 # TII SSRC Secure Technologies: Ghaf Framework
 
-[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0) [![License: CC-BY-SA 4.0](https://img.shields.io/badge/License-CC--BY--SA--4.0-lightgrey.svg)](https://creativecommons.org/licenses/by-sa/4.0/legalcode) [![Style Guide](https://img.shields.io/badge/docs-Style%20Guide-blueviolet)](https://github.com/tiiuae/ghaf/blob/main/docs/style_guide.md)
+<p align="center">
+  <img src="./docs/src/img/1600px-Ghaf_logo.svg" alt="Ghaf Logo" width="50%" height="50%" />
+</p>
+
+<div align="center">
+
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-darkgreen.svg)](./LICENSES/LICENSE.Apache-2.0) [![License: CC-BY-SA 4.0](https://img.shields.io/badge/License-CC--BY--SA--4.0-orange.svg)](./LICENSES/LICENSE.CC-BY-SA-4.0) [![Style Guide](https://img.shields.io/badge/docs-Style%20Guide-yellow)](https://github.com/tiiuae/ghaf/blob/main/docs/style_guide.md)
+
+</div>
 
 This repository contains the source files (code and documentation) of Ghaf Framework — an open-source project for enhancing security through compartmentalization on edge devices.
 
 For information on build instructions and supported hardware, see the [Reference Implementations](https://tiiuae.github.io/ghaf/ref_impl/reference_implementations.html) section of Ghaf documentation.
 
+
+### Other Project Repositories
+
 Other repositories that are a part of the Ghaf project:
 
 * <https://github.com/tiiuae/sbomnix>: a utility that generates SBOMs given Nix derivations or out paths

docs/README-docs.md

@@ -76,7 +76,9 @@ To add new pages to the book:
 
 2. Put images into the `src/img` folder. We make diagrams with [diagrams.net](https://www.diagrams.net/) (use it online) or [draw.io](https://drawio-app.com/blog/use-draw-io-offline/) (use it offline and on a tablet).
 
-    To embed a diagram, make sure that you use the Editable Bitmap Image format `<imagename>.drawio.png`. When creating a new diagram, choose *Editable Bitmap Image format (.png)* from the list. When editing the existing diagram, select **File > Export as > PNG...** and select the **Include a copy of my diagram** check box.
+    * To embed a diagram, make sure that you use the Editable Bitmap Image format `<imagename>.drawio.png`. When creating a new diagram, choose *Editable Bitmap Image format (.png)* from the list. When editing the existing diagram, select **File > Export as > PNG...** and select the **Include a copy of my diagram** check box.
+
+    * Try to use main colors according to brand colors: [Fonts and Colors](./style_guide.md#fonts-and-colors).
 
 3. Add new structure elements (chapters, sections, subsections) to **SUMMARY.md** to update the table of contents. Otherwise, the files that you added will not be visible on GitHub Pages. Example:
 

docs/book.toml

@@ -10,3 +10,5 @@ src = "src"
 default-theme = "light"
 git-repository-url = "https://github.com/tiiuae/ghaf"
 git-repository-icon = "fa-github"
+
+[preprocessor.footnote]

docs/default.nix

@@ -0,0 +1,40 @@
+# Copyright 2022-2023 TII (SSRC) and the Ghaf contributors
+# SPDX-License-Identifier: CC-BY-SA-4.0
+{
+  pkgs,
+  lib,
+  callPackage,
+  runCommandLocal,
+  nixosOptionsDoc,
+  mdbook,
+  revision ? "",
+  options ? {},
+}: let
+  optionsDocMd =
+    (nixosOptionsDoc {
+      inherit revision options;
+      transformOptions = x:
+        if lib.strings.hasPrefix "ghaf" x.name
+        then x
+        else x // {visible = false;};
+      markdownByDefault = true;
+    })
+    .optionsCommonMark;
+  combinedSrc = runCommandLocal "ghaf-doc-src" {} ''
+    mkdir $out
+    cp -r ${./.}/* $out
+    chmod +w $out/src/ref_impl/modules_options.md
+
+    # Refer to master branch files in github
+    sed 's/\(file:\/\/\)\?\/nix\/store\/[^/]*-source/https:\/\/github.com\/tiiuae\/ghaf\/blob\/main/g' ${optionsDocMd}  >> $out/src/ref_impl/modules_options.md
+  '';
+in
+  runCommandLocal "ghaf-doc"
+  {
+    nativeBuildInputs = let
+      footnote = callPackage ./plugins/mdbook-footnote.nix {};
+    in [mdbook footnote];
+    src = combinedSrc;
+  } ''
+    ${mdbook}/bin/mdbook build -d $out $src
+  ''

docs/plugins/mdbook-footnote.nix

@@ -0,0 +1,19 @@
+# Copyright 2022-2023 TII (SSRC) and the Ghaf contributors
+# SPDX-License-Identifier: CC-BY-SA-4.0
+{
+  fetchFromGitHub,
+  rustPlatform,
+}:
+rustPlatform.buildRustPackage rec {
+  pname = "mdbook-footnote";
+  version = "0.1.1";
+
+  src = fetchFromGitHub {
+    owner = "daviddrysdale";
+    repo = "mdbook-footnote";
+    rev = "refs/tags/v${version}";
+    sha256 = "sha256-WUMgm1hwsU9BeheLfb8Di0AfvVQ6j92kXxH2SyG3ses=";
+  };
+
+  cargoHash = "sha256-Ig+uVCO5oHIkkvFsKiBiUFzjUgH/Pydn4MVJHb2wKGc=";
+}

docs/src/SUMMARY.md

@@ -1,35 +1,62 @@
+<!--
+    Copyright 2022-2023 TII (SSRC) and the Ghaf contributors
+    SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
 # Summary
 
+# Overview
+
 - [About Ghaf](index.md)
 - [Features](features/features.md)
 - [Architecture](architecture/architecture.md)
   - [Architectural Variants](architecture/variants.md)
   - [Architecture Decision Records](architecture/adr.md)
     - [Minimal Host](architecture/adr/minimal-host.md)
     - [Networking VM](architecture/adr/netvm.md)
+    - [Platform Bus for Rust VMM](architecture/adr/platform-bus-passthrough-support.md)
   - [Stack](architecture/stack.md)
+
+# For Developers
+
+- [Contributing](appendices/contributing_general.md)
+- [Reference Implementations](ref_impl/reference_implementations.md)
+  - [Development](ref_impl/development.md)
+    - [Build and Run](ref_impl/build_and_run.md)
+    - [Cross-Compilation](ref_impl/cross_compilation.md)
+    - [Creating Application VM](ref_impl/creating_appvm.md)
+  - [Ghaf as Library](ref_impl/ghaf-based-project.md)
+    - [Example Project](ref_impl/example_project.md)
+    - [Modules Options](ref_impl/modules_options.md)
 - [Technologies](technologies/technologies.md)
+    - [Compartmentalization](technologies/compartment.md)
     - [Passthrough](technologies/passthrough.md)
+        - [Binding Device to VFIO Driver](technologies/vfio.md)
         - [NVIDIA Jetson AGX Orin: UART Passthrough](technologies/nvidia_agx_pt_uart.md)
         - [NVIDIA Jetson AGX Orin: PCIe Passthrough](technologies/nvidia_agx_pt_pcie.md)
+        - [Generic x86: PCIe Passthrough on crosvm](technologies/x86_pcie_crosvm.md)
     - [Hypervisor Options](technologies/hypervisor_options.md)
-- [Reference Implementations](ref_impl/reference_implementations.md)
-  - [Usage](ref_impl/usage.md)
-  - [Development](ref_impl/development.md)
-    - [Build and Run](ref_impl/build_and_run.md)
-    - [Cross-Compilation](ref_impl/cross_compilation.md)
+
+# Build System and Supply Chain
+
+- [CI/CD System]()
 - [Supply Chain Security](scs/scs.md)
     - [SLSA Framework](scs/slsa-framework.md)
     - [Basic Security Measures](scs/basics.md)
     - [Software Bill of Materials](scs/sbom.md)
     - [Public Key Infrastructure](scs/pki.md)
-    - [Patch Management Automation](scs/patching-automation.md)
-- [Research Notes](research/research.md)
-    - [i.MX 8QM Ethernet Passthrough](research/passthrough/ethernet.md)
-    - [Running Windows VM on Ghaf](research/run_win_vm.md)
+    - [Security Fix Automation](scs/ghaf-security-fix-automation.md)
+- [Release Notes](release_notes/release_notes.md)
 
------------
+# Ghaf Usage Scenarios
+
+- [Showcases](scenarios/showcases.md)
+  - [Running Windows VM on Ghaf](scenarios/run_win_vm.md)
+  - [Running Cuttlefish on Ghaf](scenarios/run_cuttlefish.md)
+- [Build Your Environment]()
 
-[Glossary](appendices/glossary.md)
+-----------
 
-[Contributing](appendices/contributing_general.md)
+- [Glossary](appendices/glossary.md)
+- [Research Notes](research/research.md)
+    - [i.MX 8QM Ethernet Passthrough](research/passthrough/ethernet.md)

docs/src/architecture/adr.md

@@ -13,6 +13,7 @@ The Ghaf platform decision log:
 | -------- | ----------- |
 | [Minimal Host](../architecture/adr/minimal-host.md) | Proposed. |
 | [netvm—Networking Virtual Machine](../architecture/adr/netvm.md) | Proposed, partially implemented for development and testing. |
+| [Platform Bus for RustVMM](../architecture/adr/platform-bus-passthrough-support.md) | Proposed, WIP. |
 
 
-To create an architectural decision proposal, open [a pull request](https://github.com/tiiuae/ghaf/blob/main/CONTRIBUTING.md#contributing-documentation) and use the [decision record template](https://github.com/tiiuae/ghaf/blob/main/docs/src/architecture/adr/template.md). Contributions to the Ghaf architecture decisions are welcome.
+To create an architectural decision proposal, open [a pull request](https://github.com/tiiuae/ghaf/blob/main/CONTRIBUTING.md#contributing-documentation) and use the [decision record template](https://github.com/tiiuae/ghaf/blob/main/docs/src/architecture/adr/template.md). Contributions to the Ghaf architecture decisions are welcome.

docs/src/architecture/adr/minimal-host.md

@@ -7,7 +7,7 @@
 
 ## Status
 
-Proposed
+Proposed.
 
 ## Context
 

docs/src/architecture/adr/platform-bus-passthrough-support.md

@@ -0,0 +1,41 @@
+<!--
+    Copyright 2023 TII (SSRC) and the Ghaf contributors
+    SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# rust-vmm—Bus Passthrough Support for Rust VMMs
+
+## Status
+
+Proposed, work in progress.
+
+
+## Context
+
+This ADR is a work-in-progress note for Ghaf bus passthrough implementation that will support rust-vmm-based hypervisors.
+
+> *rust-vmm* is an open-source project that empowers the community to build custom Virtual Machine Monitors (VMMs) and hypervisors. For more information, see <https://github.com/rust-vmm/community>.
+
+It is crucial to have bus devices passthrough support for ARM-based hardware as the bus is mainly used to connect the peripherals. Nowadays, the only hypervisor with some support for Platform bus is QEMU but the code is dated 2013 and not frequently used.
+
+On the other hand, one of the target hardware devices for Ghaf is NVIDIA Orin with an ARM core. To achieve Ghaf's security and hardware isolation goals, devices should support passthrough mode. Production-ready rust-vmm-based hypervisors ([crosvm](https://github.com/google/crosvm), [Firecracker](https://github.com/firecracker-microvm/firecracker), [Cloud Hypervisor](https://www.cloudhypervisor.org/)) do not have support for Platform bus.
+
+
+## Decision
+
+Implementation of Platform bus passthrough is a base framework for Rust VMM. This will make it possible to use this mode within production-ready rust-vmm-based hypervisors. The main candidate here is crosvm. The necessity to support Platform bus in other hypervisors is subject to discussion. Technically, the Platform bus is rather a simple bus: it manages memory mapping and interrupts. Information about devices is not dynamic but is read from the device tree during the boot stage.
+
+The current status:
+
+| Required Components     |  Status of Readiness     |
+|---                      |---                       |
+| Host kernel side:       |                          |
+| VFIO drivers (to substitute real driver in host kernel) | -/+ |
+| Host support for device trees | + |
+| Guest kernel side:      |                          |
+| Device drivers for passthrough devices | + |
+| Guest support for device trees | + |
+| Rust VMM side:      | 
+| Bus support | Needs to be developed. |
+| VMM support for device trees | Rudimental, needs improvement. |
+

docs/src/architecture/adr/template.md

@@ -5,19 +5,23 @@ This is the template for managing the ADR files.
 
 In each ADR file, write these sections:
 
+
 # Title
 
 ## Status
 
-What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.?
+What is the status: proposed, accepted, rejected, deprecated, superseded, etc.?
+
 
 ## Context
 
-What is the issue that we're seeing that is motivating this decision or change?
+What is the issue that we are seeing that is motivating this decision or change?
+
 
 ## Decision
 
-What is the change that we're proposing and/or doing?
+What is the change that we are proposing and/or doing?
+
 
 ## Consequences
 

docs/src/features/features.md

@@ -8,7 +8,7 @@
 The vision for the Ghaf platform is to create a virtualized, scalable reference platform that enables the building of secure products leveraging trusted, reusable, and portable software for edge devices. For more information on reference implementation for several devices, see [Reference Implementations](../ref_impl/reference_implementations.md).
 
 Ghaf demo desktop and applications are illustrated in the screen capture below:
-![Ghaf demo desktop and application](../img/ghaf_demo_desktop.png) 
+![Ghaf demo desktop and application](../img/ghaf_demo_desktop.png)
 ## Status
 
 * ✅ - integrated and tested in the `main` branch. No known regression.
@@ -19,6 +19,7 @@ Ghaf demo desktop and applications are illustrated in the screen capture below:
 
 - `Orin`—NVIDIA Jetson AGX Orin as the main reference device.
 - `x86`—generic x86_64; tested on Intel NUC (Next Unit of Computing) or laptop.
+- `Lenovo X1`—Lenovo X1 Carbon Gen11 laptop. 
 - `aarch64`—generic AArch64; tested on an ARM server, laptop (e.g. Apple M's), or NVIDIA Jetson AGX Orin.
 - `All variants`—supported devices from [Architectural Variants](https://tiiuae.github.io/ghaf/architecture/variants.html).
 
@@ -32,8 +33,9 @@ The following tables show the status of Ghaf Platform features:
 | `aarch64` reference image | ✅ | `Orin`  | Based on [Jetson Linux](https://developer.nvidia.com/embedded/jetson-linux), [OE4T](https://github.com/OE4T) and [jetpack-nixos](https://github.com/anduril/jetpack-nixos). |
 | `aarch64` reference image | ✅ | `imx8qm`  | Based on NXP BSP, implemented as [nixos-hardware module](https://github.com/NixOS/nixos-hardware/tree/master/nxp)|
 | `x86` generic image | ✅ | `x86` | Generic x86 computer, based on generic [NixOS](https://nixos.org/). NOTE: requires device specific configuration.|
+| `Lenovo X1` reference image | ✅ | `Lenovo X1` | x86_64 laptop computer, supports basic compartmentalized environment |
 | Native build      | ✅         | `aarch64, x86`   | Remote `aarc64` nixos builders recommended |
-| Cross-compilation | 🚧 | `aarch64`  | Depends on NixOS `nixpkgs 23.05` support for cross-compilation |
+| Cross-compilation | 🚧 | `aarch64, riscv64`  | Depends on NixOS `nixpkgs 23.05` support for cross-compilation |
 | CI builds         | ✅ | `All`  | [Only `main`-branch, not for all PRs](https://vedenemo.dev/). |
 | Emulated build    | ❌ | `aarch64`  | `binfmt`, may freeze the build machine. Not recommended. [See instructions.](https://tiiuae.github.io/ghaf/ref_impl/cross_compilation.html#binfmt)|
 
@@ -47,6 +49,7 @@ The following tables show the status of Ghaf Platform features:
 | root filesystem flashing | ✅   | `x86, imx8qm`  | `dd` image to bootable media - [see](https://tiiuae.github.io/ghaf/ref_impl/build_and_run.html#running-ghaf-image-for-x86-computer) |
 | Debug: SSH        | ✅      | `Orin`, `x86` | Host access only in `-debug`-target, see [authentication.nix](https://github.com/tiiuae/ghaf/blob/main/modules/development/authentication.nix) |
 | Debug: Serial     | ✅      | `all` | Host access only in `-debug`-target - e.g. `screen /dev/ttyACM0 115200` |
+| Compartmentalized environment     | 🚧      | `Lenovo X1` | NetVM, GUI VM (with GPU passthrough) plus some Application VMs |
 
 ## Target architecture
 
@@ -55,11 +58,12 @@ The following tables show the status of Ghaf Platform features:
 | `minimal host`    | 🚧   | [`all`](https://tiiuae.github.io/ghaf/architecture/variants.html) | See [Minimal Host](https://tiiuae.github.io/ghaf/architecture/adr/minimal-host.html) and [PR #140](https://github.com/tiiuae/ghaf/pull/140). |
 | `netvm`           |  ✅ | `Orin`  | See [netvm](https://tiiuae.github.io/ghaf/architecture/adr/netvm.html). Passthrough with Wifi works but requires SSID/password configuration |
 | `idsvm`           |  ✅ | `Orin`  | [Defensive security VM placeholder PR open](https://github.com/tiiuae/ghaf/pull/146) |
-| `guivm` | 🚧 | `All`| Currently Wayland stack and apps on host for demos. Graphics are host-only for now. [PCI GPU passthrough and guivm PR open](https://github.com/tiiuae/ghaf/pull/118)|
+| `guivm` | 🚧 | `All`, `Lenovo-X1`| Implemented for Lenovo X1 reference device, other devices have Wayland compositor running on the host.|
+| `appvm` | 🚧 | `All`, `Lenovo-X1`| Implemented for Lenovo X1 reference device: chromium, GALA and zathura VMs. Requires `guivm` in place |
 | `adminvm`           | ✅ | `All`  | Not started |
 | Inter VM comms - IP-based  | 🚧 | `All` |`-debug`-targets have network bridges to access VMs from host |
 | Inter VM comms - shared memory  |  🚧 | `All` |  |
-| Inter VM Wayland  |  🚧 | `All` | Being ported from previous work |
+| Inter VM Wayland  |  🚧 | `All` | Currently it is `waypipe` over SSH, for test and demo purpose only |
 | SW update | 🚧 | `All` | A/B update tooling being evaluated |
 | USB passthrough   | 🚧 | `Orin`  | No reference implementation integrated yet |
 | PCI passthrough   | ✅ | `All`  | Used for reference in `netvm` on `Orin` |
@@ -70,15 +74,15 @@ The following tables show the status of Ghaf Platform features:
 
 | Feature           | Status      | Reference Device | Details                             |
 |-------------------|-------------|------------------|----------------------------------------------|
-| Wayland-compositor | 🚧 | `Orin`, `x86` | On host |
-| Chromium | 🚧 | `Orin`, `x86` | On host |
+| Wayland-compositor | 🚧 | `Orin`, `x86` | Implemented for `Lenovo-X1` |
+| Chromium | 🚧 | `Orin`, `x86` | Implemented for `Lenovo-X1` |
 | Element | 🚧 | `Orin`, `x86` | On host |
-| Cloud Android (CVD) client app (GALA )| 🚧 | `Orin`, `x86` | On host |
+| Cloud Android (CVD) client app (GALA )| 🚧 | `Orin`, `x86` | Implemented for `Lenovo-X1` |
 | Virtualization control | 🚧 | [`All`](https://tiiuae.github.io/ghaf/architecture/variants.html) | See [vmd design](https://github.com/tiiuae/vmd/blob/main/doc/design.md). |
 
 ## Next steps
 
-[See discussion for the outline of next steps](https://github.com/tiiuae/ghaf/issues/150#issuecomment-1564061850) 
+[See discussion for the outline of next steps](https://github.com/tiiuae/ghaf/issues/150#issuecomment-1564061850)
 
-![Outline of next phases](https://user-images.githubusercontent.com/1027150/241167552-bcb3a3f9-72f3-4b96-af8b-e9df6d1f3d5e.png) 
+![Outline of next phases](https://user-images.githubusercontent.com/1027150/241167552-bcb3a3f9-72f3-4b96-af8b-e9df6d1f3d5e.png)