3. Running BitVisor

Boot on real hardware via USB + EFI Shell, or test quickly with QEMU

Running on Real Hardware (USB Drive + EFI Shell)

The simplest way to run BitVisor on real hardware is to prepare a USB drive with an EFI Shell and launch BitVisor from it.

Prepare the USB Drive

Format the USB drive as FAT32 and create the following directory structure:

USB drive/
├── EFI/
│   └── boot/
│       └── bootx64.efi     ← EFI Shell binary renamed to bootx64.efi
└── bitvisor/
    ├── loadvmm.efi          ← UEFI loader
    └── bitvisor.elf         ← Hypervisor core

A pre-built EFI Shell for x86_64 is available from distributions such as Arch Linux (UEFI Shell — Arch Wiki).

UEFI firmware looks for EFI\boot\bootx64.efi when booting from an external drive by default. Rename the shell binary to bootx64.efi and place it there.

Boot from the USB Drive

Plug in the USB drive and boot from it. The EFI Shell will appear. The shell shows available file systems (fs0, fs1, etc.) — internal drives typically appear first, followed by external drives.

Switch to the USB drive and launch BitVisor:

Shell> fs1:              ← adjust the number for your USB drive
fs1:\> cd bitvisor
fs1:\bitvisor\> loadvmm.efi

On success, you will see output similar to:

Copyright (c) 2007, 2008 University of Tsukuba
All rights reserved.
ACPI DMAR not found.
...
Starting a virtual machine.

And on the syslog receiver (/var/log/bitvisor.log):

Feb  3 17:30:45 host bitvisor: Starting a virtual machine.
Feb  3 17:30:45 host bitvisor: IP address changed: 0.0.0.0 -> 192.168.0.7
Feb  3 17:30:45 host bitvisor: telnet server "dbgsh" ready

Type exit to leave the shell and continue booting the OS normally, or launch the OS loader manually:

  • Linux: EFI\distro_name\grubx64.efi
  • Windows: EFI\Microsoft\Boot\bootmgfw.efi

Running on QEMU (x86_64)

Place loadvmm.efi and bitvisor.elf in the same directory (e.g., ~/x86_test/):

qemu-system-x86_64 \
  -cpu host -enable-kvm \
  -bios /path/to/OVMF.fd \
  -drive file=fat:rw:~/x86_test/,format=raw \
  -cdrom /path/to/bootable.iso \
  -nic user,model=e1000e \
  -M q35 -m 4096
  • -bios: specify OVMF.fd (UEFI firmware image)
  • NIC is e1000e (Intel emulation), so enable NET_PRO1000 in Kconfig
  • Press ESC repeatedly during boot to enter the UEFI setup menu and launch the EFI Shell (add -boot menu=on for more delay)

KVM Notes

On recent Intel CPUs, kvm_intel’s enable_apicv=Y can cause timer panics or SMP bring-up stalls in the guest after BitVisor starts. To temporarily disable it:

sudo modprobe -r kvm-intel && sudo modprobe kvm-intel enable_apicv=N

Alternatively, set .localapic_intercept = 1 in defconfig to enable BitVisor’s built-in INIT-SIPI emulation workaround for QEMU + KVM.

Running AArch64 BitVisor on QEMU (Experimental)

Place AArch64 loadvmm.efi and bitvisor.elf in the same directory, then run:

qemu-system-aarch64 \
  -m 8G \
  -M virt,gic-version=3,virtualization=true \
  -cpu neoverse-n1 \
  -bios /path/to/aarch64/qemu_efi.fd \
  -drive file=fat:rw:/path/to/bitvisor_dir/,format=raw \
  -cdrom /path/to/aarch64/linux.iso \
  -nic user,model=e1000e \
  -serial vc:1024x768 \
  -smp 4

AArch64 BitVisor currently runs on -cpu neoverse-n1 or -cpu a64fx. -cpu max is not supported as it enables optional features not yet implemented.

Press ESC repeatedly during boot to enter the EFI Shell, then launch BitVisor as described above.

To use devicetree instead of ACPI for device discovery, add acpi=off to the -M parameter and enable CONFIG_DEVICETREE=y in Kconfig.