Docs: proofreading

Signed-off-by: Jenni Nikolaenko <[email protected]>

docs/src/SUMMARY.md

@@ -25,7 +25,7 @@
     - [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)
+  - [Ghaf as Library: Templates](ref_impl/ghaf-based-project.md)
     - [Example Project](ref_impl/example_project.md)
     - [Modules Options](ref_impl/modules_options.md)
 - [Technologies](technologies/technologies.md)
@@ -47,6 +47,8 @@
     - [Public Key Infrastructure](scs/pki.md)
     - [Security Fix Automation](scs/ghaf-security-fix-automation.md)
 - [Release Notes](release_notes/release_notes.md)
+    - [Release ghaf-23.05](release_notes/ghaf-23.05.md)
+    - [Release ghaf-23.06](release_notes/ghaf-23.06.md)
 
 # Ghaf Usage Scenarios
 
@@ -57,6 +59,8 @@
 
 -----------
 
+# Appendices
+
 - [Glossary](appendices/glossary.md)
 - [Research Notes](research/research.md)
     - [i.MX 8QM Ethernet Passthrough](research/passthrough/ethernet.md)

docs/src/architecture/architecture.md

@@ -22,4 +22,5 @@ The Ghaf Platform components are used in reference configurations to build image
 - [Architecture Decision Records](./adr.md)
   - [Minimal Host](./adr/minimal-host.md)
   - [Networking VM](./adr/netvm.md)
+  - [Platform Bus for Rust VMM](./adr/platform-bus-passthrough-support.md)
 - [Stack](./stack.md)

docs/src/ref_impl/creating_appvm.md

@@ -3,22 +3,25 @@
     SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
-# Creating an Application VM
+# Creating Application VM
 
-## What is AppVM?
+Application VM (AppVM) is a VM that improves trust in system components by isolating applications from the host OS and other applications. Virtualization with hardware-backed mechanisms provides better resource protection than traditional OS. This lets users use applications of different trust levels within the same system without compromising system security. While the VMs have overhead, it is acceptable as a result of improved security and usability that makes the application seem like it is running inside an ordinary OS.
 
-AppVM is a virtual machine that is used to improve trust in system components by isolating the applications from both host OS and other applications. This way user can use applications of different trust levels within the same system and without compromising system security. This is because virtualization with hardware backed mechanisms provides better resource protection than traditional OS. While the VMs have overhead, it's acceptable via improved security and usability that makes the application seem like it is running inside an ordinary OS.
+As a result, both highly trusted applications and untrusted applications can be hosted in the same secure system when the concerns are separated in their own AppVMs.
 
-As a result - both highly trusted applications and untrusted applications can be hosted in the same secure system when the concerns are separated in their own AppVMs.
+To create an AppVM:
+1. Add AppVM description.
+2. Add an app launcher in GUI VM.
 
-## How to add a new AppVM
 
-### 1. AppVM description
+## Adding AppVM Description
 
 Add the VM description in the target configuration.
+
 [lenovo-x1.nix](../../../targets/lenovo-x1.nix) already has AppVMs inside for Chromium, Gala, and Zathura applications.
 
-#### Example of the current AppVMs
+
+#### AppVMs Example
 
 ```
 vms = with pkgs; [
@@ -54,20 +57,21 @@ Each VM has the following properties:
 
 | **Property** | **Type**                  | **Unique** | **Description**                                                                                               | **Example**         |
 | -------------- | --------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------- | --------------------- |
-| name         | str                       | yes        | This name is prefixed with `vm-` and will be shown in microvm list. The prefixed name - e.g. `vm-chromium` will be also the VM hostname                                     | “chromium”        |
-| packages     | list of types.package     | no         | Packages to include in a VM. It’s possible to make it empty or add several packages                          | [chromium top]    |
-| ipAddress    | str                       | yes        | This IP will be used to access a VM from the host. Should has the same subnetwork, as other VMs: Net, GUI VMs | "192.168.101.5/24"  |
-| macAddress   | str                       | yes        | Needed for network configuration                                                                              | "02:00:00:03:03:05" |
-| ramMb        | int, [1, …, host memory] | no         | Memory in MB                                                                                                  | 3072                |
-| cores        | int,  [1, …, host cores] | no         | Virtual CPU cores                                                                                             | 4                   |
+| name         | str                       | yes        | This name is prefixed with `vm-` and will be shown in microvm list. The prefixed name - e.g. `vm-chromium` will be also the VM hostname.                                     | “chromium”        |
+| packages     | list of types.package     | no         | Packages to include in a VM. It is possible to make it empty or add several packages.                          | [chromium top]    |
+| ipAddress    | str                       | yes        | This IP will be used to access a VM from the host. Should has the same subnetwork, as other VMs: Net, GUI VMs. | "192.168.101.5/24"  |
+| macAddress   | str                       | yes        | Needed for network configuration.                                                                              | "02:00:00:03:03:05" |
+| ramMb        | int, [1, …, host memory] | no         | Memory in MB.                                                                                                  | 3072                |
+| cores        | int,  [1, …, host cores] | no         | Virtual CPU cores.                                                                                             | 4                   |
 
 
-### 2. Add an app launcher in GUI VM
+## Adding Application Launcher in GUI VM
 
 To add an app launcher, add an element in the [guivm.nix](../../../modules/virtualization/microvm/guivm.nix) file to the **graphics.weston.launchers** list.
+
 A launcher element has 2 properties:
 
 1. **path** – path to the executable you want to run, like a graphical application.
 2. **icon** – path to an icon to show.
 
-You may want to check the example launchers [here](../../../modules/virtualization/microvm/guivm.nix)
+Check the example launchers at [guivm.nix](../../../modules/virtualization/microvm/guivm.nix).

docs/src/ref_impl/development.md

@@ -5,16 +5,18 @@
 
 # Development
 
-Ghaf Framework is free software, currently under active development.
+Ghaf Framework is free software, currently under active development. The scope of target support is updated with development progress:
 
-Scope of target support is updated with development progress.
+- [Build and Run](./build_and_run.md)
+- [Cross-Compilation](./cross_compilation.md)
+- [Creating Application VM](./creating_appvm.md)
 
 Once you are up and running, you can participate in the collaborative development process by building a development build with additional options. For example, with the development username and password that are defined in the [authentication.nix](https://github.com/tiiuae/ghaf/blob/main/modules/development/authentication.nix#L4-L5) module.
 
 If you set up development SSH keys in the [ssh.nix](https://github.com/tiiuae/ghaf/blob/main/modules/development/ssh.nix#L4) module, you can use `nixos-rebuild switch` to quickly deploy your configuration changes to the development board over the network using SSH:
 
     nixos-rebuild --flake .#packages.aarch64-linux.nvidia-jetson-orin-agx-debug --target-host root@ghaf-host --fast switch
 
+Pull requests are the way for contributors to submit code to the Ghaf project. For more information, see [Contribution Guidelines](../appendices/contributing_general.md).
 
 
-Pull requests are the way for contributors to submit code to the Ghaf project. For more information, see [Contribution Guidelines](../appendices/contributing_general.md).

docs/src/ref_impl/example_project.md

@@ -5,16 +5,19 @@
 
 # Example Project
 
-The compartmentalization could be applied to many specific x86_64 computers and laptops with some customization applied to the Ghaf. The best way of the Ghaf customization is using Ghaf templates.
+The compartmentalization could be applied to many specific x86_64 computers and laptops with some customization applied to the Ghaf.
 
-1. Create a template project as described in [Ghaf as Library](../ref_impl/ghaf-based-project.md) section
-2. Adjust your system configuration with accordance to your HW specification. Determine all VIDs and PIDs of the devices that are passed to the VMs
+The best way to do the Ghaf customization is by using Ghaf templates:
 
-3. Add GUIVM configuration, NetworkVM configuration and optionally some AppVMs
-4. Set up weston panel shortcuts.
-Refer to the existing [project example for Lenovo T14 and Lenovo X1 laptops](https://github.com/unbel13ver/ghaf-lib)
+1. Create a template project as described in the [Ghaf as Library](../ref_impl/ghaf-based-project.md) section.
+2. Adjust your system configuration in accordance with your HW specification. Determine all VIDs and PIDs of the devices that are passed to the VMs.
+3. Add GUIVM configuration, NetworkVM configuration, and optionally some AppVMs.
+4. Set up Weston panel shortcuts.
+
+You can refer to the existing [project example for Lenovo T14 and Lenovo X1 laptops](https://github.com/unbel13ver/ghaf-lib).
 
 Creating the structure that includes all necessary data for the device passthrough:
+
 ```
 # File 'my-hardware/lenovo-t14.nix':
 # Copyright 2022-2023 TII (SSRC) and the Ghaf contributors
@@ -33,4 +36,5 @@ Creating the structure that includes all necessary data for the device passthrou
   usbInputPid = "c52b";
 }
 ```
-The fields of that structure are self-explanatory. Use `lspci -nnk` command to get this data from any Linux OS running on the device.
+
+The fields of that structure are self-explanatory. Use the `lspci -nnk` command to get this data from any Linux OS running on the device.

docs/src/ref_impl/ghaf-based-project.md

@@ -7,14 +7,14 @@
 
 Ghaf is a framework for creating virtualized edge devices, it is therefore expected that projects wishing to use Ghaf should import it to create a derived work for the specific use case.
 
-In practise, projects should import Ghaf and its dependencies into an external version control (git) repository. Ghaf provides templates for the reference hardware to ease this process. In this section:
+In practice, projects should import Ghaf and its dependencies into an external version control (git) repository. Ghaf provides templates for the reference hardware to ease this process. In this section:
 
  * overview of Ghaf usage and upstream dependencies
  * required steps to create a Ghaf-based project
  * updating the project to get the latest changes
  * customization of the project using Ghaf-modules and Nix-supported mechanisms
 
-Ghaf usage in your project is illustrated in the following diagram:
+The possible Ghaf usage in your project is illustrated in the following diagram:
 
 ![Ghaf Usage Overview](../img/usage_overview.drawio.png "Your project and example inputs from Ghaf and other repositories")
 
@@ -65,15 +65,16 @@ External repositories help make various HW options, system image generators, and
 
 ## Updating Ghaf Revision
 
-To update your project, run `nix flake update`. This check the inputs for updates and based on availability of the updates, generate an updated `flake.lock` which locks the specific versions to support the reproducible builds without side effects.
+To update your project, run `nix flake update`. This checks the inputs for updates and based on the availability of the updates, and then generates an updated `flake.lock` which locks the specific versions to support the reproducible builds without side effects.
 
-In practice, nix flake will not allow floating inputs but all the inputs and declared packages must be mapped to specific hashes to get exact revisions of your inputs. This mechanism also supports the supply-chain security - if someone changes the upstream project e.g. by over-writing a part of the input so that the hash changes, you will notice. (Believe it or not, this happens even with large HW vendors). 
+In practice, a Nix flake does not allow floating inputs but all the inputs and declared packages must be mapped to specific hashes to get exact revisions of your inputs. This mechanism also supports the supply-chain security: if someone changes the upstream project, for example, by overwriting a part of the input so that the hash changes, you will notice.
+
+After updating, reviewing, and testing: commit the updated `flake.lock` to your version history to share reproducible builds within your project.
 
-After update, review and testing - commit the updated `flake.lock` to your version history to share reproducible builds within your project.
 
 ## Customizing Ghaf Modules
 
-To use the Ghaf declarative module system, check what you need in your system and choose the [modules options](./modules_options.md) you need. For example, import the ghaf `graphics`-module and declare that you won't need the reference Wayland-compositor Weston and the demo applications:
+To use the Ghaf declarative module system, check what you need in your system and choose the [modules options](./modules_options.md) you need. For example, import the ghaf `graphics`-module and declare that you will need the reference Wayland compositor Weston and the demo applications:
 
 ```
           {
@@ -83,4 +84,4 @@ To use the Ghaf declarative module system, check what you need in your system an
             };
           }
 ```
-After the change, rebuild the system and switch it into use in your target device and it will run with the GUI and apps removed. After testing, you can commit the changes and share them for your colleagues to be able to build the exactly same system - even system image - as needed in your project.
+After the change, rebuild the system and switch it into use in your target device and it will run with the GUI and apps removed. After testing, you can commit the changes and share them with your colleagues to build the same system (even a system image) as needed in your project.

docs/src/ref_impl/modules_options.md

@@ -5,4 +5,4 @@
 
 <!--
     If you want to change this file, check https://github.com/tiiuae/ghaf/pull/183.
--->
+-->

docs/src/ref_impl/reference_implementations.md

@@ -37,7 +37,10 @@ The same goes with the architectural variants as headless devices or end-user de
 
 ## In This Chapter
 
-- [Build and Run](./build_and_run.md)
 - [Development](./development.md)
+   - [Build and Run](./build_and_run.md)
    - [Cross-Compilation](./cross_compilation.md)
-- [Define a Custom Project from Ghaf](./custom_product.md)
+   - [Creating Application VM](./creating_appvm.md)
+- [Ghaf as Library: Templates](./ghaf-based-project.md)
+   - [Example Project](./example_project.md)
+   - [Modules Options](./modules_options.md)

docs/src/technologies/compartment.md

@@ -4,10 +4,13 @@
 -->
 
 # Compartmentalization
-Compartmentalization is the technique of separating parts of a system to decrease attack surface and prevent malfunctions from cascading in the system. In Ghaf architecture, there is a separate Virtual Machine (VM) for every vital function of the system.
 
-Current implementation supports Graphic User Interface (GUI) VM, Networking VM and a couple of Application VMs, such as Chromium web-browser and Zathura pdf reader.
+Compartmentalization is the technique of separating parts of a system to decrease attack surface and prevent malfunctions from cascading in the system. In Ghaf architecture, there is a separate VM for every vital function of the system.
 
-The GUI VM owns computer's GPU and performs desktop environment and application windows rendering. Wayland protocol for applications in this case is proxified by `waypipe` over SSH. This approach is used temporarly before moving to more sophisticated solutions.
+Current implementation supports GUI VM, [Networking VM](../architecture/adr/netvm.md) and a couple of Application VMs, such as the Chromium web browser and the Zathura document viewer.
 
-VM compartmentalization requires all necessary devices passthrough in place. More specifically, you need to know PCI VID and PID of a device and also it's number on the PCI bus. In case of USB device passthrough, it is enough to know device's VID and PID. See [Ghaf as Library](../ref_impl/ghaf-based-project.md) and [Creating Application VM](../ref_impl/creating_appvm.md) sections to know more about the actual implementation.
+The GUI VM owns a computer's GPU and performs desktop environment and application windows rendering. Wayland protocol for applications in this case is proxified by `waypipe` over SSH. This approach is used temporarily before moving to more sophisticated solutions.
+
+A VM compartmentalization requires all necessary devices passthrough in place. More specifically, you need to know the PCI VID and PID of a device and also its number on the PCI bus. In the case of a USB device passthrough, it is enough to know the device's VID and PID.
+
+For more information on actual implementation, see [Ghaf as Library](../ref_impl/ghaf-based-project.md) and [Creating Application VM](../ref_impl/creating_appvm.md).

docs/src/technologies/technologies.md

@@ -30,7 +30,10 @@ In addition, we have also experimental, Aarch64 demonstrated support for a KVM v
 
 ## In This Chapter
 
+- [Compartmentalization](./compartment.md)
 - [Passthrough](./passthrough.md)
+  - [Binding Device to VFIO Driver](./vfio.md)
   - [NVIDIA Jetson AGX Orin: UART Passthrough](./nvidia_agx_pt_uart.md)
-  - [Nvidia Jetson AGX Orin: PCIe Passthrough](./nvidia_agx_pt_pcie.md)
+  - [NVIDIA Jetson AGX Orin: PCIe Passthrough](./nvidia_agx_pt_pcie.md)
+  - [Generic x86: PCIe Passthrough on crosvm](./x86_pcie_crosvm.md)
 - [Hypervisor Options](./hypervisor_options.md)