guide: comprehensive overhaul of the OpenVMM Guide (#28)

This PR comprehensively overhauls the OpenVMM Guide, rewriting it from
the ground-up to better reflect the current state of the project, and to
make it more accessible to new users and potential contributors.

I _strongly_ recommend reviewing this PR by checking out my branch
locally, and running `mdbook serve Guide` locally. It will be very hard
to judge some of the organizational choices and stylistic changes I've
made by looking at raw, un-rendered Markdown.

**At a macro level:** The Guide no longer assumes that all users are
also developers. Docs that explain how to run / interact with
OpenVMM/OpenHCL are now distinct from docs explaining how to build /
contribute to the project.

**At a micro level:** I've rewritten and shuffled around the content on
just about every existing Guide page, ensuring that information is
up-to-date, and presented in a logical order.

Some notable things _not_ included in this PR:

- Rewrites of the Introduction sections (that we absolutely must update
prior to open-source)
- Getting these right will require a bit more time, and will land in a
separate PR this week.
- Fleshing out the content under the "Developer Reference" section of
the guide
- Notably: adding some brief enumerations / stub articles discussing the
various Devices / Virtualization Backends we support
- Publishing OpenVMM's `rustdocs`s to GitHub Pages
- I've included a TODO link in SUMMARY.md right at the end ("OpenVMM
Crate Docs")
- This should be relatively straightforward, requiring a bit of flowey
plumbing in the existing "publish guide" job in CI. This should happen
in its own standalone PR.

Author: daprilik

Guide/book.toml

@@ -4,7 +4,12 @@
 language = "en"
 multilingual = false
 src = "src"
-title = "OpenVMM Developer Guide"
+title = "The OpenVMM Guide"
 
 [build]
 create-missing = false
+
+[output.html]
+git-repository-url = "https://github.com/microsoft/OpenVMM"
+git-repository-icon = "fa-github"
+edit-url-template = "https://github.com/microsoft/OpenVMM/edit/main/Guide/{path}"

Guide/docfx.json

@@ -1,44 +1,67 @@
 # Summary
 
-- [Introduction](./index.md)
-- [Getting started on Windows](./getting_started.md)
-- [Getting started on WSL](./getting_started_wsl.md)
-- [Development Environment Setup](./ide_setup.md)
-- [Developing in OpenVMM](./process/index.md)
-    - [Coding conventions](./process/conventions.md)
-    - [Documentation](./process/docs.md)
-    - [Tests](./process/tests.md)
-    - [Scripts](./process/scripts.md)
-- [Diagnostics](./diag/index.md)
-    - [Logging](./diag/logging.md)
-    - [Inspection](./diag/inspect.md)
-    - [Hardware Debugging (gdbstub)](./diag/gdbstub.md)
-    - [Kernel Debugging (KDNET)](./diag/kdnet.md)
-- [Devices](./devices/index.md)
-    - [Infrastructure](./devices/infra/index.md)
-        - [VmBus](./devices/infra/vmbus.md)
-        - [Virtio](./devices/infra/virtio.md)
-    - [Block storage](./devices/block.md)
-    - [VPMEM](./devices/pmem.md)
-    - [Networking](./devices/net.md)
-    - [File system](./devices/fs/index.md)
-        - [Plan 9](./devices/fs/9p.md)
-        - [Virtio-fs](./devices/fs/virtiofs.md)
-        - [LxUtil](./devices/fs/lxutil.md)
-- [OpenVMM](./openvmm/index.md)
-    - [Build and Run OpenVMM](./openvmm/build.md)
-- [OpenHCL](./openhcl/index.md)
-    - [Building OpenHCL](./openhcl/build.md)
-    - [Run OpenHCL using OpenVMM on WHP](./openhcl/run_with_openvmm.md)
-    - [Run OpenHCL via OpenVMM from within WSL2 with cross compilation](./openhcl/cross_compile.md)
-    - [Diagnostics](./openhcl/diag.md)
-        - [PCAP network packet capture](./openhcl/diag/packet_capture.md)
-        - [CVM restrictions](./openhcl/diag/cvm_restrictions.md)
-    - [Developer Features](./openhcl/dev_features.md)
-    - [Kernel development](./openhcl/kernel.md)
-    - [Performance analysis](./openhcl/perf.md)
-    - [Troubleshooting](./openhcl/troubleshoot.md)
-- [Vmgstool](./vmgstool.md)
-- [Fuzzing](./fuzzing/index.md)
-    - [Running Fuzzers](./fuzzing/running.md)
-    - [Writing Fuzzers](./fuzzing/writing.md)
+[Introduction](./index.md)
+
+# User Guide
+
+- [OpenVMM](./user_guide/openvmm.md)
+  - [Running OpenVMM](./user_guide/openvmm/run.md)
+    - [Examples](./user_guide/openvmm/run/examples.md)
+    - [CLI](./user_guide/openvmm/run/cli.md)
+    - [Interactive Console](./user_guide/openvmm/run/interactive_console.md)
+    - [Graphical Console](./user_guide/openvmm/run/graphical_console.md)
+    - [Logging](./user_guide/openvmm/run/logging.md)
+  - [Troubleshooting](./user_guide/openvmm/troubleshooting.md)
+- [OpenHCL](./user_guide/openhcl.md)
+  - [Running OpenHCL](./user_guide/openhcl/run.md)
+    - [On Windows - Hyper-V](./user_guide/openhcl/run/hyperv.md)
+    - [On Windows - OpenVMM](./user_guide/openhcl/run/openvmm.md)
+    - [On Linux - OpenVMM]()
+  - [Troubleshooting](./user_guide/openhcl/troubleshooting.md)
+  - [Diagnostics](./user_guide/openhcl/diag.md)
+    - [Preface: CVM restrictions](./user_guide/openhcl/diag/cvm_restrictions.md)
+    - [ohcldiag-dev](./user_guide/openhcl/diag/ohcldiag_dev.md)
+      - [Network packet capture (PCAP)](./user_guide/openhcl/diag/ohcldiag_dev/pcap.md)
+      - [Performance analysis](./user_guide/openhcl/diag/ohcldiag_dev/perf.md)
+    - [Tracing](./user_guide/openhcl/diag/tracing.md)
+
+# Developer Guide
+
+- [Getting Started](./dev_guide/getting_started.md)
+  - [On Linux / WSL2](./dev_guide/getting_started/linux.md)
+  - [On Windows](./dev_guide/getting_started/windows.md)
+  - [Building OpenVMM](./dev_guide/getting_started/build_openvmm.md)
+  - [Building OpenHCL](./dev_guide/getting_started/build_openhcl.md)
+    - [Building a Custom Kernel](./dev_guide/getting_started/build_ohcl_kernel.md)
+  - [Suggested Dev Environment](./dev_guide/getting_started/suggested_dev_env.md)
+- [Testing](./dev_guide/tests.md)
+  - [Unit Tests](./dev_guide/tests/unit.md)
+  - [VMM Tests](./dev_guide/tests/vmm.md)
+    - [Azure-hosted Test Images](./dev_guide/tests/vmm/azure_images.md)
+  - [Fuzzing](./dev_guide/tests/fuzzing.md)
+    - [Running Fuzzers](./dev_guide/tests/fuzzing/running.md)
+    - [Writing Fuzzers](./dev_guide/tests/fuzzing/writing.md)
+- [Developer Features](./dev_guide/dev_feats.md)
+  - [Hardware Debugging (gdbstub)](./dev_guide/dev_feats/gdbstub.md)
+  - [Kernel Debugging (KDNET)](./dev_guide/dev_feats/kdnet.md)
+- [Developer Tools / Utilities](./dev_guide/dev_tools.md)
+  - [`cargo xtask`](./dev_guide/dev_tools/xtask.md)
+  - [`cargo xflowey`](./dev_guide/dev_tools/xflowey.md)
+  - [VmgsTool](./dev_guide/dev_tools/vmgstool.md)
+  - [update-rootfs.py]()
+  - [igvmfilegen]()
+  - [guest_test_uefi](./dev_guide/dev_tools/guest_test_uefi.md)
+- [Contributing](./dev_guide/contrib.md)
+  - [Coding Conventions](./dev_guide/contrib/code.md)
+  - [Submitting Changes](./dev_guide/contrib/pr.md)
+  - [Guide Updates](./dev_guide/contrib/guide.md)
+
+# Developer Reference
+
+- [OpenVMM Architecture]()
+- [OpenHCL Architecture]()
+- [Devices]()
+
+---
+
+[OpenVMM Crate Docs]()

Guide/index.md

@@ -0,0 +1 @@
+# Contributing

Guide/src/SUMMARY.md

@@ -1,13 +1,14 @@
 # Coding conventions
 
-## Formatting
+One of our major goals with OpenVMM is to provide a high quality coding
+experience for contributors, starting first-and-foremost by having a consistent
+set of coding conventions in the project.
 
-**TL;DR:** Run [`cargo xtask fmt`](./scripts.md#cargo-xtask) to catch (and fix)
-formatting issues.
+[Do your part](https://youtu.be/-_7FaWnlhS4?t=10) and keep OpenVMM clean!
 
-### `rustfmt`
+## `rustfmt`
 
-(enforced using [`cargo xtask fmt rustfmt`](./scripts.md#cargo-xtask))
+_Checked Automatically:_ **Yes** (via [`cargo xtask fmt rustfmt`](../dev_tools/xtask.md))
 
 OpenVMM source must be formatted using
 [rustfmt](https://github.com/rust-lang/rustfmt), which automatically and
@@ -30,28 +31,32 @@ rules that are must be manually enforced:
 > If you're working in a file and notice that it isn't following a certain
 > convention, please take a moment to fix it!
 
-Assuming you've followed the guide and set up `rust-analyzer` to
-[format on save](../ide_setup.md#enabling-format-on-save), you should rarely have
-to think about formatting in `.rs` files.
-
-### Project-specific formatting rules
+Assuming you've followed the [suggested dev env setup](../getting_started/suggested_dev_env.md)
+and set up `rust-analyzer` to format-on-save, you should rarely have to think
+about formatting in `.rs` files.
 
-Aside from using ecosystem-standard `rustfmt` formatting, OpenVMM also includes a
-handful of (automatically enforced) project-specific formatting rules.
+## House Rules
 
-#### House Rules
+_Checked Automatically:_ **Yes** (via [`cargo xtask fmt house-rules`](../dev_tools/xtask.md))
 
-(enforced using [`cargo xtask fmt house-rules`](./scripts.md#cargo-xtask))
+"House-rules" are a set of misc code lints that are specific to OpenVMM, which
+are enforced using a custom in-house tool:
 
-These are a few minor bits of code-style that are specific to OpenVMM:
+- enforce the presence of the standard Microsoft copyright header
+- enforce in-repo crate names don't use '-' in their name (use '_' instead)
+- enforce Cargo.toml files don't include autogenerated "see more keys" comments
+- enforce Cargo.toml files don't contain author or version fields
+- enforce files end with a single trailing newline
+- deny usage of `#[repr(packed)]` (you want `#[repr(C, packed)]`)
+- justify usage of `cfg(target_arch = ...)` (use `guest_arch` instead!)
+- justify usage of `allow(unsafe_code)` with an UNSAFETY comment
 
-- Enforcing the standard Microsoft copyright header at the top of each file
-- Enforcing single-trailing-newlines in code
-- Ensuring crate names do not include `-` in their name (use `_` instead!)
+Some of these lints are self explanatory, whereas others are described in more
+detail elsewhere on this page.
 
-#### Unused `Cargo.toml` Dependencies
+## Unused `Cargo.toml` Dependencies
 
-(enforced using [`cargo xtask fmt unused-deps`](./scripts.md#cargo-xtask))
+_Checked Automatically:_ **Yes** (via [`cargo xtask fmt unused-deps`](../dev_tools/xtask.md))
 
 We have an in-repo fork of
 [`cargo-machete`](https://github.com/bnjbvr/cargo-machete) that ensures
@@ -61,9 +66,9 @@ Avoiding unused dependencies makes it easier to reason about what a crate is
 doing just by looking at its dependencies, and also helps cut-down on
 incremental compile times.
 
-#### Formatting `Cargo.toml`
+## Formatting (`Cargo.toml`)
 
-**Not yet enforced by `cargo xtask fmt`! Coming Soon™️**
+_Checked Automatically:_ **No**
 
 When defining dependencies in `Cargo.toml` files, please organize dependencies
 into the following groups:
@@ -89,11 +94,11 @@ So, for example:
 
 ```toml
 [package]
-name = "hvlite"
+name = "openvmm"
 
 [dependencies]
 # crate-specific subcrates
-hvlite_core.workspace = true
+openvmm_core.workspace = true
 ...
 
 # /vmcore
@@ -118,13 +123,15 @@ clap.workspace = true
 ...
 ```
 
-## Linting (`clippy`)
+## Linting (via `clippy`)
+
+_Checked Automatically:_ **Yes**
 
 OpenVMM uses [`cargo clippy`](https://github.com/rust-lang/rust-clippy) to
 supplement rustc's built-in lints.
 
 Assuming you've followed the guide and set up `rust-analyzer` to
-[use clippy](../ide_setup.md#enabling-clippy), you should see clippy lints
+[use clippy](../getting_started/suggested_dev_env.md#enabling-clippy), you should see clippy lints
 appear inline when working on Rust code.
 
 The CI runs `cargo clippy` on every crate in the repo prior to building the
@@ -154,18 +161,18 @@ libc::cmsghdr {
 }
 ```
 
-### OpenVMM's Project-Specific `clippy` Configuration
+### OpenVMM's `clippy` Configuration
 
 We stick fairly close to the default set of rustc / clippy lints, though there
 are some default lints that we've decided to disabled project wide, and other
 non-default lints which we've explicitly opted into.
 
-See
-[`.cargo/config.toml`](https://github.com/microsoft/openvmm?path=/.cargo/config.toml)
+See the `[workspace.lints]` sections of OpenVMM's root
+[`Cargo.toml`](https://github.com/microsoft/openvmm?path=/Cargo.toml)
 for a list of globally enabled/disabled lints, along with justification as to
 why certain lints have been enabled/disabled.
 
-## Unsafe Code
+## Unsafe Code Policy
 
 > _Preface:_ When possible, try to avoid introducing new `unsafe` code!
 >
@@ -198,29 +205,24 @@ Editing a file containing unsafe code will trigger CI to automatically add the
 OpenVMM Unsafe Approvers group to your PR. This is to ensure that all unsafe code
 is audited for correctness by area experts.
 
-## Additional special considerations
-
-The following rules are unique to the OpenVMM codebase, and may be unfamiliar to
-devs coming from other Rust open-source projects.
+## Uses of `cfg(target_arch = ...)` must be justified
 
-### Uses of `cfg(target_arch = ...)` must be justified
+_Checked Automatically:_ **Yes** (via [`cargo xtask fmt house-rules`](../dev_tools/xtask.md))
 
-**TL;DR:** Unless you're working on something that's *genuinely* tied to the
-host's CPU architecture, you almost certainly want to use `cfg(guest_arch =
-...)` instead.
+Unless you're working on something that's genuinely tied to the host's CPU
+architecture, you should use `cfg(guest_arch = ...)` instead of `cfg(target_arch = ...)`.
 
-OpenVMM is a multi-architecture VMM framework, capable of running both x86 and
-Aarch64 guests (and potentially others in the future).
+OpenVMM is a multi-architecture VMM framework, capable of running running x64
+guests on a x64 host, as well as Aarch64 guests on Aarch64 hosts (with the
+potential of adding additional platforms in the future).
 
-Often times, the host architecture and the guest architecture will match,
-thereby enabling the use of hardware-accelerated CPU virtualization backends
-(e.g: KVM on Linux, WHP in Windows, etc...). That said, it's probable that at
-some point in the future, OpenVMM will also support *mismatched* guest/host
-architectures via an emulated CPU virtualization backend (akin to what QEMU
-does).
+At the moment, OpenVMM requires that the host architecture and guest
+architecture match. That said, it's possible that at some point in the future,
+OpenVMM may also support _mismatched_ guest/host architectures, via an emulated
+CPU virtualization backend (akin to QEMU).
 
-Having an emulated CPU backend would enable
-OpenVMM to support such useful scenarios as:
+Having an emulated CPU backend would enable OpenVMM to support such useful
+scenarios as:
 
 - running Arch64 guests on x86 machines
 - running x86 guests on ARM
@@ -251,7 +253,9 @@ intrinsic (such as CPUID, or a SIMD instruction), or when implementing a
 
 ...otherwise, use `cfg(guest_arch = ...)`!
 
-### Avoid `Default` when using `zerocopy::FromZeroes`
+## Avoid `Default` when using `zerocopy::FromZeroes`
+
+_Checked Automatically:_ **No**
 
 The rule:
 
@@ -266,7 +270,7 @@ The why:
 - There are plenty of types that don't have a `Default` value, but _do_ have a
   valid all-zero repr
 
-#### Additional context
+### Additional context
 
 As per the Rust docs for [`Default::default`](https://doc.rust-lang.org/std/default/trait.Default.html#tymethod.default):
 
@@ -288,7 +292,7 @@ they are initially allocated as all-zero, and then get "filled in" by some
 secondary init code. Notably: it's quite rare for that initial "all-zero" struct
 to be a valid instance of the type!
 
-##### Example: C FFI
+#### Example: C FFI
 
 For example, a common pattern in C libraries might look something like:
 
@@ -372,7 +376,9 @@ impl Default for Handle {
 }
 ```
 
-### Avoid Requiring `Debug` on Traits
+## Avoid Requiring `Debug` on Traits
+
+_Checked Automatically:_ **No**
 
 **TL;DR:** Don't do this:
 
@@ -396,7 +402,9 @@ Moreover, it's usually not good form to leave tracing statements that log a
 struct's `Debug` representation in production. Prefer tracing just the fields
 you're interested in, and/or connecting objects to the `Inspect` graph.
 
-### Crate Naming
+## Crate Naming
+
+_Checked Automatically:_ **Yes** (via [`cargo xtask fmt house-rules`](../dev_tools/xtask.md))
 
 **Crates must be named with underscores, not dashes and underscores used in
 folder names.**