Skip to content

guide: add instructions for running linux direct #2875

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mattkur merged 5 commits into from
Mar 9, 2026
+46 −0
Merged

guide: add instructions for running linux direct #2875

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a461be1
guide: add instructions for running linux direct
mattkur Mar 3, 2026
799afa9
Update Guide/src/user_guide/openvmm/run.md
mattkur Mar 3, 2026
4cead98
Merge branch 'main' into guide-run-direct
mattkur Mar 3, 2026
8bca0c2
Merge branch 'main' into guide-run-direct
mattkur Mar 4, 2026
f6e06b8
guide: address review feedback on linux-direct example
mattkur Mar 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions Guide/src/user_guide/openvmm/run.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,52 @@ 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 <out> --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
Copy link
Contributor

@smalis-msft smalis-msft Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At some point we need to rewrite xflowey vmm-tests to only rebuild the things needed for the tests you specify instead of building the world. All the wiring is there, someone just needs to do it...

Copy link
Contributor Author

@mattkur mattkur Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think @chris-oo has something like this in progress. I will say: a rebuild of vmm-tests is pretty quick. It's the initial build (and downloading the vhd deps) that gets ya.

Copy link
Contributor

@smalis-msft smalis-msft Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We've had two people get to 'in progress', but nobody's gotten to 'done' yet lol

test suite.
```

This places `openvmm.exe` and `openhcl-x64-test-linux-direct.bin` in the
`<out>` directory. Then, on Windows, from the `<out>` 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" `
-m 2GB `
--vmbus-com1-serial "term,name=VTL0 Linux" `
--com3 "term,name=VTL2 OpenHCL" `
--vtl2-vsock-path $env:temp\ohcldiag-dev
```

```admonish warning
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
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
Expand Down