Repo: Add documentation for binaries

[Steven Malis (smalis-msft)]

We're getting a lot of new developers, and we have a lot of custom tools. Add Guide pages for all of the ones new developers may want to interact with. Also add expanded top level doccomments to all binaries. Also update and expand a few more general Guide pages.

Also remove the code/guide mapping table in the SKILL, it was out of date and does not appear to be working. Just tell AI to scan the guide instead.

[github-actions]

⚠️ Unsafe Code Detected

This PR modifies files containing unsafe Rust code. Extra scrutiny is required during review.

For more on why we check whole files, instead of just diffs, check out the Rustonomicon

[Copilot]

🟡 Changes recommended

Fix the broken and incomplete Guide navigation/link references and retain the required maintenance mapping sections.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds developer documentation for repository binaries, tools, tests, OpenHCL components, and workflows.

Changes:

• Expands top-level Rust binary documentation.
• Adds and updates Guide pages and navigation.
• Updates documentation-maintenance guidance.

File summaries

File	Summary
xtask/src/main.rs	Documents xtask responsibilities.
vmm_tests/vmm_perf/src/main.rs	Documents VMM.Perf usage.
vmm_tests/prep_steps/src/main.rs	Documents image preparation.
vm/vmgs/vmgstool/src/main.rs	Documents VMGS tooling.
vm/loader/snp_bootshim/src/main.rs	Documents SNP bootshim behavior.
vm/loader/igvmfilegen/src/main.rs	Documents IGVM generation.
vm/devices/tpm/tpm_guest_tests/src/main.rs	Documents TPM guest tests.
vm/devices/get/test_igvm_agent_rpc_server/src/main.rs	Documents the test RPC server.
tmk/tmk_vmm/src/main.rs	Documents TMK VMM.
tmk/simple_tmk/src/main.rs	Documents the TMK payload.
petri/pipette/src/main.rs	Documents Pipette.
petri/petri-tool/src/main.rs	Documents Petri tooling.
petri/make_imc_hive/src/main.rs	Documents hive generation.
petri/incubator/src/main.rs	Documents Incubator.
petri/burette/src/main.rs	Documents performance testing.
openvmm/openvmm/src/main.rs	Documents OpenVMM startup.
openvmm_vhost/openvmm_vhost/src/main.rs	Documents the vhost backend.
opentmk/src/main.rs	Documents OpenTMK.
opentmk/opentmk_executor/src/main.rs	Documents the OpenTMK executor.
openhcl/sidecar/src/main.rs	Documents Sidecar.
openhcl/openvmm_hcl/src/main.rs	Documents the OpenHCL VMM.
openhcl/openhcl_boot/src/main.rs	Documents the boot loader.
openhcl/ohcldiag-dev/src/main.rs	Documents diagnostics tooling.
hyperv/tools/hypestv/src/main.rs	Documents Hypestv.
Guide/src/user_guide/openvmm.md	Adds OpenVMM lifecycle references.
Guide/src/SUMMARY.md	Adds Guide navigation entries.
Guide/src/reference/openhcl/diag/ohcldiag_dev.md	Expands diagnostics guidance.
Guide/src/reference/architecture/openhcl/sidecar.md	Expands Sidecar architecture.
Guide/src/reference/architecture/openhcl/processes.md	Updates process documentation.
Guide/src/reference/architecture/openhcl/openvmm_hcl.md	Adds OpenHCL VMM reference.
Guide/src/reference/architecture/openhcl/igvm.md	Updates IGVM documentation.
Guide/src/reference/architecture/openhcl/boot.md	Expands boot-flow documentation.
Guide/src/dev_guide/tests/vmm_perf.md	Adds VMM.Perf guidance.
Guide/src/dev_guide/tests/tpm_guest_tests.md	Adds TPM test guidance.
Guide/src/dev_guide/tests/tmk_vmm.md	Adds TMK VMM guidance.
Guide/src/dev_guide/tests/test_igvm_agent_rpc_server.md	Documents the test server.
Guide/src/dev_guide/tests/simple_tmk.md	Documents simple TMK.
Guide/src/dev_guide/tests/prep_steps.md	Documents image preparation.
Guide/src/dev_guide/tests/pipette.md	Documents Pipette integration.
Guide/src/dev_guide/tests/perf.md	Expands performance guidance.
Guide/src/dev_guide/tests/opentmk.md	Documents OpenTMK.
Guide/src/dev_guide/tests/opentmk_executor.md	Documents the executor.
Guide/src/dev_guide/tests/make_imc_hive.md	Documents hive generation.
Guide/src/dev_guide/tests/incubator.md	Documents Incubator.
Guide/src/dev_guide/dev_tools/xtask.md	Expands xtask guidance.
Guide/src/dev_guide/dev_tools/xflowey.md	Expands Flowey guidance.
Guide/src/dev_guide/dev_tools/vmgstool.md	Expands VMGS guidance.
Guide/src/dev_guide/dev_tools/igvmfilegen.md	Documents the IGVM generator.
Guide/src/dev_guide/dev_tools/hypestv.md	Expands Hypestv guidance.
Guide/src/dev_guide/dev_tools/guest_test_uefi.md	Expands UEFI test guidance.
guest_test_uefi/src/main.rs	Documents the UEFI test payload.
flowey/flowey_hvlite/src/main.rs	Documents the Flowey frontend.
.github/skills/guide-maintenance/SKILL.md	Updates maintenance guidance.

Review details

Suppressed comments (1)

Guide/src/user_guide/openvmm.md:22

• This adds a link to ../reference/openvmm/binary_lifecycle.md, but that file is not present in Guide/src/reference/openvmm, so the new Guide page renders a broken link. Either add the referenced page and include it in SUMMARY.md, or remove this link and point readers only to the existing openvmm/run.md page.

The [OpenVMM binary lifecycle](../reference/openvmm/binary_lifecycle.md)
describes what that executable links, how it resolves a command line into a VM,
and how to diagnose startup and shutdown. For practical launch commands, begin
with [Running OpenVMM](./openvmm/run.md).

• Files reviewed: 53/53 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approval recommended

The reviewed findings are minor documentation nits and do not block approval.

Review details

Suppressed comments (11)

Guide/src/SUMMARY.md:50

• This section now has real child pages, but the parent remains an empty placeholder link. In the generated Guide navigation, Performance Benchmarks is therefore not clickable and the existing perf.md page is not the section landing page; link the heading to the performance overview.

  - [Performance Benchmarks]()

Guide/src/dev_guide/tests/perf.md:99

• This replacement drops the only Guide documentation for the memory benchmark's emitted metrics (memory_rss_kib, memory_private_kib, memory_vmm_overhead_kib, memory_process_count, and memory_pss_kib), even though petri/burette/src/tests/memory.rs:147-170 still produces them. Please retain a metric list under the memory section so developers can interpret the JSON reports; the new network paragraph does not cover those fields.

The report records TCP throughput and UDP packet-rate metrics. Keep the NIC,
network backend, host CPU placement, and MTU constant between compared runs.

Guide/src/reference/architecture/openhcl/processes.md:13

• Each wrapped source/rustdoc reference in this file has the same stray leading | before Docs:. It renders literal pipe characters throughout the page instead of the intended label; remove the pipe from this line and the corresponding wrapped labels below.

| **Docs:**

Guide/src/reference/architecture/openhcl/processes.md:47

• The wrapped rustdoc reference repeats the same stray leading |, which renders literally in the page. Remove it from the Docs: label.

| **Docs:**

Guide/src/reference/architecture/openhcl/processes.md:64

• The wrapped rustdoc reference repeats the same stray leading |, which renders literally in the page. Remove it from the Docs: label.

| **Docs:**

Guide/src/reference/architecture/openhcl/processes.md:83

• The wrapped rustdoc reference repeats the same stray leading |, which renders literally in the page. Remove it from the Docs: label.

| **Docs:**

Guide/src/reference/architecture/openhcl/processes.md:100

• The wrapped rustdoc reference repeats the same stray leading |, which renders literally in the page. Remove it from the Docs: label.

| **Docs:**

Guide/src/reference/architecture/openhcl/processes.md:117

• The wrapped rustdoc reference repeats the same stray leading |, which renders literally in the page. Remove it from the Docs: label.

| **Docs:**

Guide/src/reference/architecture/openhcl/processes.md:133

• The wrapped rustdoc reference repeats the same stray leading |, which renders literally in the page. Remove it from the Docs: label.

| **Docs:**

Guide/src/reference/architecture/openhcl/processes.md:149

• The wrapped rustdoc reference repeats the same stray leading |, which renders literally in the page. Remove it from the Docs: label.

| **Docs:**

Guide/src/reference/architecture/openhcl/sidecar.md:8

• The leading | is left over from the previous same-line Source code | Docs formatting. Because Docs: is now on its own line, Markdown renders this character literally before the label; remove it so the reference renders as normal text.

| **Docs:**

• Files reviewed: 54/54 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

One or more issues must be addressed before approval.

Review details

Suppressed comments (9)

Guide/src/reference/architecture/openhcl/processes.md:13

• These newly split source/doc reference blocks retain the table separator from the old one-line form. In this context the line is not a table row, so the leading | renders as stray text in the guide. Remove the leading pipe from each Docs: line (or keep the reference on one line).

| **Docs:**

Guide/src/reference/architecture/openhcl/processes.md:47

• The split reference block retains a leading table pipe even though these lines are not a Markdown table, so the guide renders a stray | before Docs:. Remove the leading pipe here and in the other similarly split reference blocks.

| **Docs:**

Guide/src/reference/architecture/openhcl/processes.md:64

• The split reference block retains a leading table pipe even though these lines are not a Markdown table, so the guide renders a stray | before Docs:. Remove the leading pipe here and in the other similarly split reference blocks.

| **Docs:**

Guide/src/reference/architecture/openhcl/processes.md:83

• The split reference block retains a leading table pipe even though these lines are not a Markdown table, so the guide renders a stray | before Docs:. Remove the leading pipe here and in the other similarly split reference blocks.

| **Docs:**

Guide/src/reference/architecture/openhcl/processes.md:100

• The split reference block retains a leading table pipe even though these lines are not a Markdown table, so the guide renders a stray | before Docs:. Remove the leading pipe here and in the other similarly split reference blocks.

| **Docs:**

Guide/src/reference/architecture/openhcl/processes.md:117

• The split reference block retains a leading table pipe even though these lines are not a Markdown table, so the guide renders a stray | before Docs:. Remove the leading pipe here and in the other similarly split reference blocks.

| **Docs:**

Guide/src/reference/architecture/openhcl/processes.md:133

• The split reference block retains a leading table pipe even though these lines are not a Markdown table, so the guide renders a stray | before Docs:. Remove the leading pipe here and in the other similarly split reference blocks.

| **Docs:**

Guide/src/reference/architecture/openhcl/processes.md:149

• The split reference block retains a leading table pipe even though these lines are not a Markdown table, so the guide renders a stray | before Docs:. Remove the leading pipe here and in the other similarly split reference blocks.

| **Docs:**

Guide/src/reference/architecture/openhcl/sidecar.md:8

• This leading | is left over from the former single-line Source code | Docs layout. Because the preceding line is not a table row, Markdown renders this as a literal pipe instead of a separator, so the reference block displays incorrectly. Remove the leading pipe (or keep both labels on one line).

| **Docs:**

• Files reviewed: 54/54 changed files
• Comments generated: 0 new
• Review effort level: Lite

[github-actions]

2 Petri tests failed (0 unstable)

[Copilot]

Copilot review overview

🟡 Changes recommended

Several documentation links, examples, and maintenance instructions need correction before approval.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1

Open (1)

• Performance Benchmarks navigation duplicates the same page · New

[Copilot]

Copilot review overview

🔵 Needs a closer look

Final review comments identify unresolved documentation issues that should be corrected before approval.

Review effort: Lite
Findings: None

Resolved since last review (1)

• Performance Benchmarks navigation duplicates the same page

Previously missed (3)

In code that hasn't changed since last review

Use the kebab-case CLI value for TestConfig

Guide/​src/​dev_guide/​tests/​test_igvm_agent_rpc_server.md:43

TestConfig derives clap::ValueEnum without explicit names, so this value is exposed as ak-cert-request-failure-and-retry (kebab-case), not the Rust variant spelling shown here. The documented command currently fails argument parsing.

Fix malformed Docs separators throughout the architecture page

Guide/​src/​reference/​architecture/​openhcl/​processes.md:36

The leading | is rendered as literal text rather than the separator used by the surrounding architecture pages, so the Docs label is malformed. Put the separator at the end of the source link, as in Guide/src/reference/architecture/openvmm/mesh.md:15-17.

This issue also appears in the following locations of the same file:

• line 52
• line 69
• line 85
• line 101

Fix the malformed Docs separator

Guide/​src/​reference/​architecture/​openhcl/​sidecar.md:9

The leading | is rendered as literal text rather than the separator used by the surrounding architecture pages, so the Docs label is malformed. Put the separator at the end of the source link, as in Guide/src/reference/architecture/openvmm/mesh.md:15-17.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Documentation inaccuracies and incomplete binary coverage remain.

Review effort: Lite
Findings: None

Previously missed (2)

In code that hasn't changed since last review

Memory metric definitions were removed from the documentation

Guide/​src/​dev_guide/​tests/​perf.md:98

This replacement removes the definitions of the memory metrics while the rest of the page still tells developers to compare memory overhead. burette continues to emit memory_rss_kib, memory_private_kib, memory_vmm_overhead_kib, memory_pss_kib, and memory_process_count (see petri/burette/src/tests/memory.rs), so please restore these definitions or link to an authoritative schema.

TestConfig example uses an invalid non-kebab-case value

Guide/​src/​dev_guide/​tests/​test_igvm_agent_rpc_server.md:43

TestConfig derives Clap's default ValueEnum names, which are kebab-case, so AkCertRequestFailureAndRetry is not an accepted value for --test-config. This example exits with an invalid-value error; use the generated kebab-case value instead.

[github-actions]

1 Petri tests failed (0 unstable)