ohcldiag-dev

OpenHCL includes a "diag server", which provides an interface to diagnose and interact with the OpenHCL binary and user-mode state.

ohcldiag-dev is the "move-fast, break things" tool used by the core OpenHCL dev team, and as such, it makes NO stability guarantees as to the specific format of the CLI, output via stdout/stderr, etc...

That is to say: ANY AUTOMATION THAT ATTEMPTS TO USE ohcldiag-dev WILL EVENTUALLY BREAK!

ochldiag-dev is designed to work no matter where you run OpenHCL: in a Hyper-V VM, an OpenVMM VM using VSM or nested virtualization, or in other VMMs that support paravisors. Consider the hypestv tool for an interactive dev/test tool specifically for Hyper-V VMs.

Examples

Check `OpenHCL` version

You can inspect a running OpenHCL VM with ohcldiag-dev.

PS > .\ohcldiag-dev.exe <vm name> inspect build_info
{
   crate_name: "underhill_core",
   scm_revision: "bd7d6a98b7ca8365acdfd5fa2b10a17e62ffa766",
}

You can use that to validate your VM is running with the OpenHCL image you intended by checking the scm-revision output matches the commit hash of the OpenHCL repo (if building OpenHCL, you can get the commit hash of your repo using git log --max-count=1).

The detailed kernel version information is available from the initial RAM filesystem only:

PS > .\ohcldiag-dev.exe <vm name> run -- cat /etc/kernel-build-info.json
{
  "git_branch": "rolling-lts/underhill/5.15.90.7",
  "git_revision": "55792e0aa5e92ac4450dc10bf032caadc019fd84",
  "build_id": "74486489",
  "build_name": "5.15.90.7-hcl.1"
}

The OpenHCL version information can be read from the filesystem, too:

PS > .\ohcldiag-dev.exe <vm name> run -- cat /etc/underhill-build-info.json
{
    "git_branch": "user/romank/kernel_build_info",
    "git_revision": "a7c4ba3ffcd8708346d33a608f25b9287ac89f8b"
}

Interactive Shell

To get an interactive shell into the VM, try:

ohcldiag-dev.exe <vm name> shell

Interactive shell is only available in debug builds of OpenHCL.

Running a command

To run a command non-interactively:

ohcldiag-dev.exe <vm name> run cat /proc/interrupts

Using `inspect`

To inspect OpenHCL state (via the Inspect trait):

ohcldiag-dev.exe <vm name> inspect -r

`kmsg` log

The kernel kmsg log currently contains both the kernel log output and the OpenHCL log output. You can see this output via the console, if you have it configured, or via ohcldiag-dev:

ohcldiag-dev.exe <vm name> kmsg

If you want a continuous stream of output as new messages arrive, pass the -f flag:

ohcldiag-dev.exe <vm name> kmsg -f

By default, the OpenHCL logs will only contain traces at info level and higher. You can adjust this globally or on a module-by-module basis. And you can set the tracing configuration at startup or dynamically with ohcldiag-dev.

To set the trace filter at startup, add a kernel command line option OPENVMM_LOG=<filter>. To update it on a running VM, run:

ohcldiag-dev.exe <vm name> inspect trace/filter -u <filter>

The format of <filter> is a series of comma-separated key-value pairs, plus an optional default, <default-level>,<target>=<level>,<target>=<level>. <level> can be one of:

trace
debug
info
warn
error
off

<target> specifies the event or span's target, which defaults to the fully qualified module name (including the crate name) that contains the event, but it can be overridden on individual trace statements.

So to enable warning traces by default, but debug level for storvsp traces, try:

ohcldiag-dev.exe <vm name> inspect trace/filter -u warn,storvsp=debug

If successful, the new filter will take effect immediately, even if you have an open kmsg session already.

The OpenVMM Guide