microsoft/openvmm
Publicmirrored from https://github.com/microsoft/openvmmAvailable
Guide/src/dev_guide/dev_tools/hypestv.md
102lines · modecode
| 1 | # hypestv |
| 2 | |
| 3 | `hypestv` is an interactive command-line interface for Hyper-V VMs, designed for |
| 4 | making OpenHCL developers' lives easier. |
| 5 | |
| 6 | Similar to [`ohcldiag-dev`][], it can interact with the OpenHCL paravisor |
| 7 | running inside a Hyper-V VM. But unlike `ohcldiag-dev`, it sports an interactive |
| 8 | terminal interface (with history and tab completion), and it is specifically |
| 9 | designed to interact with Hyper-VMs. |
| 10 | |
| 11 | [`ohcldiag-dev`]: ../../reference/openhcl/diag/ohcldiag_dev.md |
| 12 | |
| 13 | In many ways, it is similar to the OpenVMM interactive console. In time, it may |
| 14 | end up sharing code and capabilities with it and with `ohcldiag-dev`, but it |
| 15 | will always be a Hyper-V specific tool. |
| 16 | |
| 17 | Currently, it can: |
| 18 | |
| 19 | * Change VM state (starting/stopping/resetting) |
| 20 | * Enable serial port output |
| 21 | * Inspect paravisor state |
| 22 | |
| 23 | In the future, it might be able to: |
| 24 | |
| 25 | * Enable paravisor and Hyper-V log output |
| 26 | * Enable serial port input |
| 27 | * Capture serial port output to another terminal window or file |
| 28 | * Inspect host state |
| 29 | * Persistence workspaces (save/restore configured serial ports and logs) |
| 30 | |
| 31 | ## Example session |
| 32 | |
| 33 | `hypestv` launches into a detached mode, unless you specify a VM name on the |
| 34 | command line. To select a VM to work on, the VM named `tdxvm` in this example, |
| 35 | use the `select` command. If successful, you will now see the name and VM state |
| 36 | in the prompt: |
| 37 | |
| 38 | ``` |
| 39 | > select tdxvm |
| 40 | tdxvm [off]> |
| 41 | ``` |
| 42 | |
| 43 | After this, all commands will implicitly operate on `tdxvm`. Use `select` again |
| 44 | to work on another VM. |
| 45 | |
| 46 | To enable serial port output, use the `serial` command. This can be used at any |
| 47 | time, even while the VM is not running. E.g., to open a separate window for |
| 48 | interactive use of COM1 and enable logging serial port output for COM2: |
| 49 | |
| 50 | ``` |
| 51 | tdxvm [off]> serial 1 term |
| 52 | tdxvm [off]> serial 2 log |
| 53 | ``` |
| 54 | |
| 55 | Start a VM with `start`. This is an asynchronous command: you can continue to |
| 56 | type other commands at the prompt while the VM starts. You should see an output |
| 57 | message when the VM finishes starting, as well as output about any configured |
| 58 | serial ports connecting. |
| 59 | |
| 60 | Note that, due to limitations of the `rustyline` crate, the displayed VM state |
| 61 | on the prompt may not be accurate until you type another command or press Enter. |
| 62 | |
| 63 | ``` |
| 64 | tdxvm [off]> start |
| 65 | serial port 1 connected |
| 66 | serial port 2 connected |
| 67 | VM started |
| 68 | tdxvm [off]> |
| 69 | tdxvm [running]> |
| 70 | ``` |
| 71 | |
| 72 | At this point, the VM is running, including the paravisor (if one is |
| 73 | configured). As in the OpenVMM interactive console, you can inspect paravisor |
| 74 | state with the `inspect` or `x` command, passing `-p` to specify that you want |
| 75 | to inspect paravisor state: |
| 76 | |
| 77 | ``` |
| 78 | tdxvm [running]> x -p |
| 79 | { |
| 80 | build_info: _, |
| 81 | control_state: "started", |
| 82 | mesh: _, |
| 83 | proc: _, |
| 84 | trace: _, |
| 85 | uhdiag: _, |
| 86 | vm: _, |
| 87 | } |
| 88 | ``` |
| 89 | |
| 90 | You can terminate the VM with `kill`. This will disconnect any connected serial |
| 91 | ports as well, but they will reconnect next time the VM starts. Killing a VM |
| 92 | does not detach/deselect it; subsequent commands will continue to operate on the |
| 93 | VM. |
| 94 | |
| 95 | ``` |
| 96 | tdxvm [running]> kill |
| 97 | serial port 1 disconnected |
| 98 | serial port 2 disconnected |
| 99 | VM killed |
| 100 | tdxvm [stopping]> |
| 101 | tdxvm [off]> |
| 102 | ``` |
| 103 | |