wire / wire-format / kvm-run
KVM exposes a /dev/kvm character device. The VMM (QEMU, Firecracker, Cloud Hypervisor) uses ioctls: KVM_CREATE_VM, KVM_CREATE_VCPU, KVM_SET_USER_MEMORY_REGION, KVM_RUN (enters guest mode), KVM_GET_REGS/KVM_SET_REGS, KVM_GET_SREGS, KVM_TRANSLATE, KVM_INTERRUPT, KVM_SIGNAL_MASK, KVM_IRQ_LINE, etc. The VMM maps guest memory into its address space and handles VM exits (I/O, MMIO, hypercalls, interrupts).
aka: KVM (Kernel Virtual Machine) ioctl interface
spec: Linux kernel (KVM)
KVM exposes a /dev/kvm character device. The VMM (QEMU, Firecracker, Cloud Hypervisor) uses ioctls: KVM_CREATE_VM, KVM_CREATE_VCPU, KVM_SET_USER_MEMORY_REGION, KVM_RUN (enters guest mode), KVM_GET_REGS/KVM_SET_REGS, KVM_GET_SREGS, KVM_TRANSLATE, KVM_INTERRUPT, KVM_SIGNAL_MASK, KVM_IRQ_LINE, etc. The VMM maps guest memory into its address space and handles VM exits (I/O, MMIO, hypercalls, interrupts).
| field | size | meaning |
|---|---|---|
| KVM_CREATE_VM | ioctl | Creates a VM; returns a VM fd. Arg: type (0 = default, 1 = TDX, ...). |
| KVM_CREATE_VCPU | ioctl | Creates a vCPU; arg = vCPU id. Returns a vCPU fd. |
| KVM_SET_USER_MEMORY_REGION | ioctl + struct | Maps guest physical memory: {slot, flags, guest_phys_addr, memory_size, userspace_addr}. |
| KVM_RUN | ioctl | Enters guest mode; returns on VM exit. The vCPU fd's mmap'd kvm_run structure describes the exit reason. |
| kvm_run.exit_reason | 4 bytes (__u32) | Exit reason: 0 (unknown), 2 (exception), 3 (I/O), 4 (hypercall), 5 (debug), 6 (HLT), 7 (MMIO), 8 (IRQ window open), 9 (shutdown), 10 (fail entry), 11 (intr), 12 (set TPR), 13 (TPR access), 14 (S390 SIEIC), 15 (S390 reset), 16 (DFC), 17 (PAPR hcall), 18 (S390 UCTRL), 19 (ROP (watchdog)), 20 (X86 RDMSR), 21 (X86 WRMSR), 22 (dirty ring full), 23 (APIC write), 24 (HV (Hyper-V)), 25 (ARM NISV), 26 (X86 BUS_LOCK), 27 (XEN), 28 (RISC-V SBI), 29 (RISC-V CSR), 30 (NOTIFY). |
| kvm_run.io | struct | For KVM_EXIT_IO: direction (in/out), size (1/2/4), port, count, data_offset. |
| kvm_run.mmio | struct | For KVM_EXIT_MMIO: phys_addr, data (8 bytes), len, is_write. |
example:
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
kvm_run structure header (exit_reason=0 unknown)
agent: curl -H 'accept: application/json' wire.phall.io/wire-format/kvm-run
or /wire-format/kvm-run.json