microsoft/openvmm
Publicmirrored fromhttps://github.com/microsoft/openvmmAvailable
Guide/src/dev_guide/dev_tools/hypestv.md
108lines · 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 to standard output, or input/output to another |
| 21 | terminal window |
| 22 | * Enable paravisor log output to standard output or another terminal window |
| 23 | * Inspect paravisor state |
| 24 | |
| 25 | In the future, it might be able to: |
| 26 | |
| 27 | * Enable Hyper-V log output |
| 28 | * Capture serial port output to a file |
| 29 | * Inspect host state |
| 30 | * Persistence workspaces (save/restore configured serial ports and logs) |
| 31 | |
| 32 | ## Example session |
| 33 | |
| 34 | `hypestv` launches into a detached mode, unless you specify a VM name on the |
| 35 | command line. To select a VM to work on, the VM named `tdxvm` in this example, |
| 36 | use the `select` command. If successful, you will now see the name and VM state |
| 37 | in the prompt: |
| 38 | |
| 39 | ``` |
| 40 | > select tdxvm |
| 41 | tdxvm [off]> |
| 42 | ``` |
| 43 | |
| 44 | After this, all commands will implicitly operate on `tdxvm`. Use `select` again |
| 45 | to work on another VM. |
| 46 | |
| 47 | To enable serial port output, use the `serial` command. This can be used at any |
| 48 | time, even while the VM is not running. E.g., to open a separate window for |
| 49 | interactive use of COM1 and enable logging serial port output for COM2: |
| 50 | |
| 51 | ``` |
| 52 | tdxvm [off]> serial 1 term |
| 53 | tdxvm [off]> serial 2 log |
| 54 | ``` |
| 55 | |
| 56 | You can also enable paravisor log output at any time: |
| 57 | |
| 58 | ``` |
| 59 | tdxvm [off]> paravisor kmsg log |
| 60 | ``` |
| 61 | |
| 62 | Start a VM with `start`. This is an asynchronous command: you can continue to |
| 63 | type other commands at the prompt while the VM starts. You should see an output |
| 64 | message when the VM finishes starting, as well as output about any configured |
| 65 | serial ports connecting. |
| 66 | |
| 67 | Note that, due to limitations of the `rustyline` crate, the displayed VM state |
| 68 | on the prompt may not be accurate until you type another command or press Enter. |
| 69 | |
| 70 | ``` |
| 71 | tdxvm [off]> start |
| 72 | com1 connected |
| 73 | com2 connected |
| 74 | VM started |
| 75 | tdxvm [off]> |
| 76 | tdxvm [running]> |
| 77 | ``` |
| 78 | |
| 79 | At this point, the VM is running, including the paravisor (if one is |
| 80 | configured). As in the OpenVMM interactive console, you can inspect paravisor |
| 81 | state with the `inspect` or `x` command, but under the `paravisor`/`pv` command: |
| 82 | |
| 83 | ``` |
| 84 | tdxvm [running]> pv x |
| 85 | { |
| 86 | build_info: _, |
| 87 | control_state: "started", |
| 88 | mesh: _, |
| 89 | proc: _, |
| 90 | trace: _, |
| 91 | uhdiag: _, |
| 92 | vm: _, |
| 93 | } |
| 94 | ``` |
| 95 | |
| 96 | You can terminate the VM with `kill`. This will disconnect any connected serial |
| 97 | ports as well, but they will reconnect next time the VM starts. Killing a VM |
| 98 | does not detach/deselect it; subsequent commands will continue to operate on the |
| 99 | VM. |
| 100 | |
| 101 | ``` |
| 102 | tdxvm [running]> kill |
| 103 | com1 disconnected |
| 104 | com2 disconnected |
| 105 | VM killed |
| 106 | tdxvm [stopping]> |
| 107 | tdxvm [off]> |
| 108 | ``` |
| 109 | |