1# `cloud-hypervisor` debug IO port 2 3`cloud-hypervisor` uses the [`0x80`](https://www.intel.com/content/www/us/en/support/articles/000005500/boards-and-kits.html) 4I/O port to trace user defined guest events. 5 6Whenever the guest write one byte between `0x0` and `0xF` on this particular 7I/O port, `cloud-hypervisor` will log and timestamp that event at the `debug` 8log level. 9 10It is up to the guest stack to decide when and what to write to the 0x80 port 11in order to signal the host about specific events and have `cloud-hypervisor` 12log it. 13 14`cloud-hypervisor` defines several debug port code ranges that should be used 15for debugging specific components of the guest software stack. When logging a 16write of one of those codes to the debug port, `cloud-hypervisor` adds a 17pre-defined string to the logs. 18 19| Code Range | Component | Log string | 20| ---------------- | ----------- | ------------ | 21| `0x00` to `0x1f` | Firmware | `Firmware` | 22| `0x20` to `0x3f` | Bootloader | `Bootloader` | 23| `0x40` to `0x5f` | Kernel | `Kernel` | 24| `0x60` to `0x7f` | Userspace | `Userspace` | 25| `0x80` to `0xff` | Custom | `Custom` | 26 27One typical use case is guest boot time measurement and tracing. By writing 28different values to the debug I/O port at different boot process steps, the 29guest will have `cloud-hypervisor` generate timestamped logs of all those steps. 30That provides a basic but convenient way of measuring not only the overall guest 31boot time but all intermediate steps as well. 32 33## Logging 34 35Assuming parts of the guest software stack have been instrumented to use the 36`cloud-hypervisor` debug I/O port, we may want to gather the related logs. 37 38To do so we need to start `cloud-hypervisor` with the right debug level 39(`-vvv`). It is also recommended to have it log into a dedicated file in order 40to easily grep for the tracing logs (e.g. 41`--log-file /tmp/cloud-hypervisor.log`): 42 43``` 44./target/debug/cloud-hypervisor \ 45 --kernel ~/rust-hypervisor-firmware/target/target/release/hypervisor-fw \ 46 --disk path=~/hypervisor/images/focal-server-cloudimg-amd64.raw \ 47 --cpus 4 \ 48 --memory size=1024M \ 49 --rng \ 50 --log-file /tmp/ch-fw.log \ 51 -vvv 52``` 53 54After booting the guest, we then have to grep for the debug I/O port traces in 55the log file: 56 57```Shell 58$ grep "Debug I/O port" /tmp/ch-fw.log 59cloud-hypervisor: 19.762449ms: DEBUG:vmm/src/vm.rs:510 -- [Debug I/O port: Firmware code 0x0] 0.019004 seconds 60cloud-hypervisor: 403.499628ms: DEBUG:vmm/src/vm.rs:510 -- [Debug I/O port: Firmware code 0x1] 0.402744 seconds 61``` 62