1# `cloud-hypervisor` debug IO ports 2 3When running x86 guests, `cloud-hypervisor` provides different kinds of debug ports: 4 5- [`0x80` debug port](https://web.archive.org/web/20211028033025/https://www.intel.com/content/www/us/en/support/articles/000005500/boards-and-kits.html) 6- Debug console (by default at `0xe9`). 7- Firmware debug port at `0x402`. 8 9All of them can be used to trace user-defined guest events and all of them can 10be used simultaneously. 11 12## Debug Ports Overview 13 14### `0x80` I/O port 15 16Whenever the guest write one byte between `0x0` and `0xF` on this particular 17I/O port, `cloud-hypervisor` will log and timestamp that event at the `debug` 18log level. 19 20It is up to the guest stack to decide when and what to write to the 0x80 port 21in order to signal the host about specific events and have `cloud-hypervisor` 22log it. 23 24`cloud-hypervisor` defines several debug port code ranges that should be used 25for debugging specific components of the guest software stack. When logging a 26write of one of those codes to the debug port, `cloud-hypervisor` adds a 27pre-defined string to the logs. 28 29| Code Range | Component | Log string | 30| ---------------- | ---------- | ------------ | 31| `0x00` to `0x1f` | Firmware | `Firmware` | 32| `0x20` to `0x3f` | Bootloader | `Bootloader` | 33| `0x40` to `0x5f` | Kernel | `Kernel` | 34| `0x60` to `0x7f` | Userspace | `Userspace` | 35| `0x80` to `0xff` | Custom | `Custom` | 36 37One typical use case is guest boot time measurement and tracing. By writing 38different values to the debug I/O port at different boot process steps, the 39guest will have `cloud-hypervisor` generate timestamped logs of all those steps. 40That provides a basic but convenient way of measuring not only the overall guest 41boot time but all intermediate steps as well. 42 43#### Logging 44 45Assuming parts of the guest software stack have been instrumented to use the 46`cloud-hypervisor` debug I/O port, we may want to gather the related logs. 47 48To do so we need to start `cloud-hypervisor` with the right debug level 49(`-vvv`). It is also recommended to have it log into a dedicated file in order 50to easily grep for the tracing logs (e.g. 51`--log-file /tmp/cloud-hypervisor.log`): 52 53``` 54./target/debug/cloud-hypervisor \ 55 --kernel ~/rust-hypervisor-firmware/target/target/release/hypervisor-fw \ 56 --disk path=~/hypervisor/images/focal-server-cloudimg-amd64.raw \ 57 --cpus 4 \ 58 --memory size=1024M \ 59 --rng \ 60 --log-file /tmp/ch-fw.log \ 61 -vvv 62``` 63 64After booting the guest, we then have to grep for the debug I/O port traces in 65the log file: 66 67```Shell 68$ grep "Debug I/O port" /tmp/ch-fw.log 69cloud-hypervisor: 19.762449ms: DEBUG:vmm/src/vm.rs:510 -- [Debug I/O port: Firmware code 0x0] 0.019004 seconds 70cloud-hypervisor: 403.499628ms: DEBUG:vmm/src/vm.rs:510 -- [Debug I/O port: Firmware code 0x1] 0.402744 seconds 71``` 72 73### Debug console port 74 75The debug console is inspired by QEMU and Bochs, which have a similar feature. 76By default, the I/O port `0xe9` is used. This port can be configured like a 77console. Thus, it can print to a tty, a file, or a pty, for example. 78 79### Firmware debug port 80 81The firmware debug port is also a simple port that prints all bytes written to 82it. The firmware debug port only prints to stdout. 83 84## When do I need these ports? 85 86The ports are on the one hand interesting for firmware or kernel developers, as 87they provide an easy way to print debug information from within a guest. 88Furthermore, you can patch "normal" software to measure certain events, such as 89the boot time of a guest. 90 91## Which port should I choose? 92 93The `0x80` debug port and the port of the firmware debug device are always 94available. The debug console must be activated via the command line, but 95provides more configuration options. 96 97You can use different ports for different aspect of your logging messages. 98