From a461be1beeeea7702208ea456f47393232affbdb Mon Sep 17 00:00:00 2001 From: Matt LaFayette Date: Tue, 3 Mar 2026 06:29:09 +0000 Subject: [PATCH 1/3] guide: add instructions for running linux direct --- Guide/src/user_guide/openvmm/run.md | 40 +++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/Guide/src/user_guide/openvmm/run.md b/Guide/src/user_guide/openvmm/run.md index 2ee9686b52..25989c6593 100644 --- a/Guide/src/user_guide/openvmm/run.md +++ b/Guide/src/user_guide/openvmm/run.md @@ -111,6 +111,46 @@ useful when iterating on OpenVMM code, since booting the VM becomes repeatable and you don't have to worry about shutting down properly. Use `file` instead for normal persistent storage. +### OpenHCL, via Linux Direct Boot + +This example will boot OpenHCL in Linux direct mode, running a minimal shell +inside VTL2. This is the same configuration used by the `openhcl_linux_direct_x64` +integration tests. + +First, build the test artifacts from Linux or WSL using `vmm-tests --build-only`. +The IGVM must be built on Linux: + +```shell +cargo xflowey vmm-tests --build-only --dir x64-openhcl-linux-direct-tests +``` + +This places `openvmm.exe` and `openhcl-x64-test-linux-direct.bin` in the +`` directory. Then, on Windows, from the `` directory: + +```powershell +.\openvmm.exe ` + --hv ` + --vtl2 ` + --igvm openhcl-x64-test-linux-direct.bin ` + -c "panic=-1 reboot=triple UNDERHILL_SERIAL_WAIT_FOR_RTS=1 UNDERHILL_CMDLINE_APPEND=rdinit=/bin/sh" ` + --com3 "term,name=VTL2 OpenHCL" ` + -m 2GB ` + --vmbus-com1-serial "term,name=VTL0 Linux" ` + --vmbus-com2-serial "term,name=COM2" ` + --vtl2-vsock-path $env:temp\ohcldiag-dev +``` + +```admonish warning +Serial terminals **must** be configured when using Linux direct boot with +`rdinit=/bin/sh`. The shell running as PID 1 requires a controlling terminal +(tty) to function. Without serial ports configured, the shell exits immediately, +causing a kernel panic — and because the cmdline includes `panic=-1 +reboot=triple`, the VM enters an infinite reboot loop with no visible output. +``` + +For more details on running OpenHCL on OpenVMM, including VMBus relay and device +assignment, see [Running OpenHCL: OpenVMM](../openhcl/run/openvmm.md). + ### DOS, via PCAT BIOS While DOS in particular is not a scenario that the OpenVMM has heavily invested From 799afa9b72bb508283240a8c971e03b80fd9bd49 Mon Sep 17 00:00:00 2001 From: "Matt LaFayette (Kurjanowicz)" Date: Tue, 3 Mar 2026 11:32:57 -0800 Subject: [PATCH 2/3] Update Guide/src/user_guide/openvmm/run.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- Guide/src/user_guide/openvmm/run.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Guide/src/user_guide/openvmm/run.md b/Guide/src/user_guide/openvmm/run.md index 25989c6593..1980d80c3c 100644 --- a/Guide/src/user_guide/openvmm/run.md +++ b/Guide/src/user_guide/openvmm/run.md @@ -121,7 +121,7 @@ First, build the test artifacts from Linux or WSL using `vmm-tests --build-only` The IGVM must be built on Linux: ```shell -cargo xflowey vmm-tests --build-only --dir x64-openhcl-linux-direct-tests +cargo xflowey vmm-tests --build-only --dir --target windows-x64 ``` This places `openvmm.exe` and `openhcl-x64-test-linux-direct.bin` in the From f6e06b8b2f942b9ee4e04dbdf18a95fed1eeb350 Mon Sep 17 00:00:00 2001 From: Matt Kurjanowicz Date: Mon, 9 Mar 2026 10:45:32 -0700 Subject: [PATCH 3/3] guide: address review feedback on linux-direct example - Simplify command: only --vmbus-com1-serial is required for VTL0 boot, --com3 is optional (for VTL2 debug output), --vmbus-com2-serial removed - Update admonish warning to clarify which flag is required and why - Add tip about cargo xflowey build-igvm as faster alternative Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- Guide/src/user_guide/openvmm/run.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/Guide/src/user_guide/openvmm/run.md b/Guide/src/user_guide/openvmm/run.md index 1980d80c3c..9cfb918530 100644 --- a/Guide/src/user_guide/openvmm/run.md +++ b/Guide/src/user_guide/openvmm/run.md @@ -124,6 +124,12 @@ The IGVM must be built on Linux: cargo xflowey vmm-tests --build-only --dir --target windows-x64 ``` +```admonish tip +If you only need the IGVM binary (and already have `openvmm.exe`), you can +use `cargo xflowey build-igvm` instead — it's faster than building the full +test suite. +``` + This places `openvmm.exe` and `openhcl-x64-test-linux-direct.bin` in the `` directory. Then, on Windows, from the `` directory: @@ -133,19 +139,19 @@ This places `openvmm.exe` and `openhcl-x64-test-linux-direct.bin` in the --vtl2 ` --igvm openhcl-x64-test-linux-direct.bin ` -c "panic=-1 reboot=triple UNDERHILL_SERIAL_WAIT_FOR_RTS=1 UNDERHILL_CMDLINE_APPEND=rdinit=/bin/sh" ` - --com3 "term,name=VTL2 OpenHCL" ` -m 2GB ` --vmbus-com1-serial "term,name=VTL0 Linux" ` - --vmbus-com2-serial "term,name=COM2" ` + --com3 "term,name=VTL2 OpenHCL" ` --vtl2-vsock-path $env:temp\ohcldiag-dev ``` ```admonish warning -Serial terminals **must** be configured when using Linux direct boot with -`rdinit=/bin/sh`. The shell running as PID 1 requires a controlling terminal -(tty) to function. Without serial ports configured, the shell exits immediately, -causing a kernel panic — and because the cmdline includes `panic=-1 -reboot=triple`, the VM enters an infinite reboot loop with no visible output. +The `--vmbus-com1-serial` flag is **required** when using `rdinit=/bin/sh`. +The shell running as PID 1 needs a controlling terminal (tty) — without one +it exits immediately, causing a kernel panic and infinite reboot loop. + +The `--com3` flag is optional but recommended — it gives you VTL2 (OpenHCL) +kernel console output for debugging. ``` For more details on running OpenHCL on OpenVMM, including VMBus relay and device