Docs: proofread PR 422

Signed-off-by: Jenni Nikolaenko <evgeniia.nikolaenko@unikie.com>

docs/src/appendices/glossary.md

@@ -86,6 +86,10 @@ Source: [NVIDIA Orin Series System-on-Chip, Technical Reference Manual, Version:
 
 _A board support package is a collection of software used to boot and run the embedded system._
 
+### CA
+
+_A certificate authority or certification authority is an entity that stores, signs, issues digital certificates, and bind them to cryptographic keys._
+
 ### DHCP
 
 _The Dynamic Host Configuration Protocol is a network protocol that automatically sets IP addresses and other attributes to enable information transfer between network nodes._  
@@ -194,6 +198,10 @@ _A stock keeping unit, is a unique code used by sellers to identify and track pr
 
 _A system on chip, a microchip that contains the necessary electronic circuits for a fully functional system on a single integrated circuit (IC)._
 
+### SPKI
+
+_simple public-key infrastructure_
+
 ### SSD
 
 _solid-state drive_
@@ -301,3 +309,6 @@ Source: <https://slsa.dev/spec/v0.1/terminology>
 
 _Supply chain Levels for Software Artifacts is a security framework, a check-list of standards and controls to prevent tampering, improve integrity, and secure packages and infrastructure in your projects, businesses or enterprises._  
 Source: <https://slsa.dev/>
+
+[Back to Top ⏫](./glossary.md#glossary)
+---

docs/src/architecture/adr.md

@@ -12,9 +12,9 @@ The Ghaf platform decision log:
 | Decision Record | Status |
 | -------- | ----------- |
 | [Minimal Host](../architecture/adr/minimal-host.md) | Proposed. |
-| [netvm—Networking Virtual Machine](../architecture/adr/netvm.md) | Proposed, partially implemented for development and testing. |
-| [idsvm—Intrusion Detection System Virtual Machine](../architecture/adr/idsvm.md) | Proposed, partially implemented for development and testing. |
-| [Platform Bus for RustVMM](../architecture/adr/platform-bus-passthrough-support.md) | Proposed, WIP. |
+| [Networking VM](../architecture/adr/netvm.md) | Proposed, partially implemented for development and testing. |
+| [IDS VM](../architecture/adr/idsvm.md) | Proposed, partially implemented for development and testing. |
+| [Platform Bus for Rust VMM](../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.

docs/src/architecture/adr/idsvm.md

@@ -3,38 +3,35 @@
     SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
-# idsvm-Itrusion Detection System Virtual Machine
+# Intrusion Detection System Virtual Machine
+
 
 ## Status
 
 Proposed, partially implemented for development and testing.
 
-*idsvm* reference declaration will be available at [microvm/idsvm.nix]
-(https://github.com/tiiuae/ghaf/blob/main/modules/virtualization/microvm/idsvm.nix)
+Intrusion Detection VM (IDS VM) reference declaration will be available at [microvm/idsvm.nix](https://github.com/tiiuae/ghaf/blob/main/modules/microvm/virtualization/microvm/idsvm/idsvm.nix).
+
 
 ## Context
 
-Ghaf high-level design target is to secure a monolithic OS by modularizing
-the OS to networked VMs. The key security target is to detect intrusions by
-analyzing the network traffic in the internal network of the OS.
+Ghaf's high-level design target is to secure a monolithic OS by modularizing the OS to networked VMs. The key security target is to detect intrusions by analyzing the network traffic in the internal network of the OS.
+
 
 ## Decision
 
-The main goal is to have networking entity in Ghaf internal network so that
-all network traffic goes via that entity. Traffic then can be analysed to
-detect possible intrusions in inter VM communication and outgoing network 
-traffic (from VM to internet). This goal is achieved itroducing a dedicated
-virtual machine and route all networking from other virtual machines to go
-through it. Then it is possible to use various IDS software solutions in 
-idsvm to detect possible suspicious network activities.
+The main goal is to have a networking entity in Ghaf's internal network so that all network traffic goes through that entity. Traffic then can be analyzed to detect possible intrusions in inter VM communication and outgoing network traffic (from VM to the Internet). This goal is achieved by introducing a dedicated VM and routing all networking from other VMs to go through it. Then it is possible to use various IDS software solutions in IDS VM to detect possible suspicious network activities.
+
+![Scope!](../../img/idsvm.drawio.png "IDS VM Solution")
 
-![Scope!](../../img/idsvm.drawio.png "idsvm Solution")
 
 ## Consequences
 
-A dedicated idsvm provides a single checkpoint to detect intrusions
-and anomalies in the internal network of the OS and to initiate required
-countermeasures.
+A dedicated IDS VM provides a single checkpoint to detect intrusions and anomalies in the internal network of the OS and to initiate required countermeasures.
+
+Routing and analyzing the network traffic in a separate VM will reduce network performance.
+
+
+## References
 
-Routing and analysing the network traffic in separate VM will reduce network
-performance.
+[IDS VM Further Development](/docs/src/ref_impl/idsvm-development.md)

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

@@ -85,8 +85,8 @@ No networking may have impact on how the guest-to-guest inter virtual machine co
 
 ### No graphics (MH04)
 
-Ghaf minimal host profile for release target has no graphics. Graphics will be compartmentalized to GUIVM.
-All graphics and display output related components and dependencies, including kernel drivers, must be removed from kernel configuration. Those are to be passed through to GUIVM.
+Ghaf minimal host profile for release target has no graphics. Graphics will be compartmentalized to GUI VM.
+All graphics and display output related components and dependencies, including kernel drivers, must be removed from kernel configuration. Those are to be passed through to GUI VM.
 
 ### No getty (MH05)
 

docs/src/architecture/adr/netvm.md

@@ -3,45 +3,50 @@
     SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
-# netvm—Networking Virtual Machine
+# Networking Virtual Machine
+
 
 ## Status
 
 Proposed, partially implemented for development and testing.
 
-*netvm* reference declaration is available at [netvm/default.nix](https://github.com/tiiuae/ghaf/blob/main/microvmConfigurations/netvm/default.nix).
+Networking VM (Net VM) reference declaration is available at [microvm/netvm.nix](https://github.com/tiiuae/ghaf/blob/main/modules/microvm/virtualization/microvm/netvm.nix).
+
 
 ## Context
 
-Ghaf high-level design target is to secure a monolithic OS by modularizing the OS to networked VMs. The key security target is to not expose the trusted host directly to the Internet. This isolates the attack surface from the Internet to *netvm*.
+Ghaf's high-level design target is to secure a monolithic OS by modularizing the OS to networked VMs. The key security target is to not expose the trusted host directly to the Internet. This isolates the attack surface from the Internet to Net VM.
 
 The following context diagram illustrates development and secure scenarios:
 
-![Scope!](../../img/netvm.drawio.png "netvm Context")
+![Scope!](../../img/netvm.drawio.png "Net VM Context")
 
 **Left**: An insecure development scenario. The host is directly connected to the Internet, and the network is bridged from the host to other parts of the system.
 
-**Right**: A secure scenario. The network is passed through to *netvm* and routed to other parts of the system.
+**Right**: A secure scenario. The network is passed through to Net VM and routed to other parts of the system.
+
 
 ## Decision
 
-The development scenario simplifies the target system network access and configuration. This ADR proposes the development *netvm* configuration is maintained to support system development.
+The development scenario simplifies the target system network access and configuration. This ADR proposes the development Net VM configuration is maintained to support system development.
 
-The secure scenario is proposed to be implemented with the use of passthrough to DMA and remap the host physical network interface card (PHY NIC) to *netvm*. This cannot be generalized for all hardware targets as it requires:
-- Low-level device tree configuration for bootloader and host (at least on platform NIC).
-- VMM host user space NIC bus mapping from the host to *netvm*.
-- Native network interface driver (not virtual) in *netvm*. Native driver is bound the vendor BSP supported kernel version.
+The secure scenario is proposed to be implemented with the use of passthrough to DMA and remap the host physical network interface card (PHY NIC) to Net VM. This cannot be generalized for all hardware targets as it requires:
+
+* Low-level device tree configuration for bootloader and host (at least on platform NIC).
+* VMM host user space NIC bus mapping from the host to Net VM.
+* Native network interface driver (not virtual) in Net VM. Native driver is bound the vendor BSP supported kernel version.
 
 These depend on the hardware setup. The proposed target setup is that the passthrough network device(s) are implemented as declarative nix-modules for easier user hardware-specific configuration. In practice, a user may configure the declaration of a PCI or USB network card that is available to the available hardware setup.
 
-*netvm* will provide:
-- dynamic network configuration:
-  - A DHCP server for *netvm* to provide IP addresses for the other parts of the system, both static and dynamic.
-  - Routing from *netvm* to the Internet and/or inter VM.
+Net VM will provide a dynamic network configuration:
+
+* A DHCP server for Net VM to provide IP addresses for the other parts of the system, both static and dynamic.
+* Routing from Net VM to the Internet and/or Inter VM.
 
 For common reference hardware with platform NIC, the configured modules for network interface passthrough are provided. For more information, see [i.MX 8QM Ethernet Passthrough](https://tiiuae.github.io/ghaf/research/passthrough/ethernet.html).
 
-Details of other network components, such as default firewall rules, DHCP (static and dynamic client addresses), routing, reverse proxies and security monitoring are to be described in their respective architecture decision records. In this context, these are illustrated in the context diagram on the right side of the *netvm* network interface driver. 
+Details of other network components, such as default firewall rules, DHCP (static and dynamic client addresses), routing, reverse proxies and security monitoring are to be described in their respective architecture decision records. In this context, these are illustrated in the context diagram on the right side of the Net VM network interface driver. 
+
 
 ## Consequences
 

docs/src/architecture/adr/template.md

@@ -3,19 +3,17 @@
     SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
-# Decision record template
-<!-- based on simple template by Michael Nygard - https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/templates/decision-record-template-by-michael-nygard/index.md -->
+# Decision Record Template
 
-This is the template for managing the ADR files.
-
-In each ADR file, write these sections:
+This is the template[^note1] for managing the ADR files. Use the following sections in each ADR file:
 
 
 # Title
 
+
 ## Status
 
-What is the status: proposed, accepted, rejected, deprecated, superseded, etc.?
+What is the status? *Proposed*, *Accepted*, *Rejected*, *Deprecated*, *Superseded*, etc.
 
 
 ## Context
@@ -31,3 +29,6 @@ What is the change that we are proposing and/or doing?
 ## Consequences
 
 What becomes easier or more difficult to do because of this change?
+
+
+[^note1]: This template is based on a [template by Michael Nygard](https://github.com/joelparkerhenderson/architecture-decision-record/tree/main/locales/en/templates/decision-record-template-by-michael-nygard). For more suggestions on writing good ADRs, see the [Architecture decision record (ADR)](https://github.com/joelparkerhenderson/architecture-decision-record/tree/main?tab=readme-ov-file#suggestions-for-writing-good-adrs) public repository.

docs/src/architecture/variants.md

@@ -8,10 +8,10 @@
 The main scope of the Ghaf platform is edge virtualization. However, to support modular development and testing of the platform, variants are supported with the following definitions:
 
 * `Default`  
-    A default variant. Supports [minimal host](./adr/minimal-host.md), GUI VM[^note] and [netvm](./adr/netvm.md). May host other VMs. For more information, see [Stack](./stack.md).
+    A default variant. Supports [minimal host](./adr/minimal-host.md), GUI VM[^note1] and [netvm](./adr/netvm.md). May host other VMs. For more information, see [Stack](./stack.md).
 
 * `Headless`  
-    A variant with [minimal host](./adr/minimal-host.md) and [netvm](./adr/netvm.md). May host other VMs but does not have GUI VM or graphics stack on a host.
+    A variant with [minimal host](./adr/minimal-host.md) and [netvm](./adr/netvm.md). May host other VMs but does not have a GUI VM or graphics stack on a host.
 
 * `Host only`
     A variant with [minimal host](./adr/minimal-host.md) *only*. A user can manually install software to a host, including VMs (if supported by hardware).
@@ -22,9 +22,9 @@ The main scope of the Ghaf platform is edge virtualization. However, to support
 
 | Variant Name       | Headless           | Graphics         | VMs                               | Devices  |
 |---                 |---                 |---               | ---                               | ---                  |
-| `Default`          | No                 | GUI VM [^note]   | Supported                         | Jetson, generic x86  |
+| `Default`          | No                 | GUI VM           | Supported                         | Jetson, generic x86  |
 | `Headless`         | Yes                | No               | Supported                         | Jetson, generic x86  |
 | `Host Only`        | Yes                | No               | May be supported but not included | Jetson, generic x86  |
 | `No Virtualization`| Yes or no          | Native on host   | Not supported                     | Raspberry Pi, RISC-V |
 
-[^note] As of early 2023, the graphics stack is deployed on a host to support application development. Work is ongoing to define the GUI VM and isolate graphics with GPU passthrough.
+[^note1]: As of early 2023, the graphics stack is deployed on a host to support application development. Work is ongoing to define the GUI VM and isolate graphics with GPU passthrough.

docs/src/features/features.md

@@ -26,7 +26,7 @@ Ghaf demo desktop and applications are illustrated in the screen capture below:
 - `aarch64`—generic AArch64; tested on an ARM server, laptop (e.g. Apple MacBook's), or NVIDIA Jetson AGX Orin.
 - `All variants`—supported devices from [Architectural Variants](https://tiiuae.github.io/ghaf/architecture/variants.html).
 
-The following tables show the status of Ghaf Platform features:
+The following tables show the status of the Ghaf Platform features:
 
 
 ## Release Builds and Hardware Architecture Support
@@ -53,25 +53,25 @@ The following tables show the status of Ghaf Platform features:
 | root filesystem flashing | ✅   | `x86, imx8mp`  | `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 |
+| Compartmentalized environment     | 🚧      | `Lenovo X1` | Net VM, GUI VM (with GPU passthrough) plus some App VMs |
 
 
 ## Target Architecture
 
 | Feature           | Status      | Reference Device | Details                             |
 |-------------------|-------------|------------------|----------------------------------------------|
-| `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`, `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 |
+| 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). |
+| Net VM           |  ✅ | `Orin`  | See [Net VM](https://tiiuae.github.io/ghaf/architecture/adr/netvm.html). Passthrough with Wi-Fi works but requires SSID/password configuration. |
+| IDS VM           |  ✅ | `Orin`, `Lenovo X1`  | [Defensive networking mechanism](/docs/src/architecture/adr/idsvm.md). |
+| GUI VM | 🚧 | `All`, `Lenovo X1`| Implemented for Lenovo X1 reference device, other devices have Wayland compositor running on the host.|
+| App VM | 🚧 | `All`, `Lenovo X1`| Implemented for Lenovo X1 reference device: Chromium, GALA and Zathura VMs. Requires GUI VM in place. |
+| Admin VM           | ✅ | `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` | 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` |
+| 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 Net VM on `Orin`. |
 | UART passthrough  | 🚧 | `Orin`  | See [NVIDIA Jetson AGX Orin: UART Passthrough](https://tiiuae.github.io/ghaf/build_config/passthrough/nvidia_agx_pt_uart.html). Not integrated to any VM. |
 | ARM platform bus devices passthrough  | 🚧 | `Orin`  | NVIDIA BPMP virtualization being developed |