wire / wire-format / kvm-run

KVM (Kernel Virtual Machine) ioctl interface

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).

wire-format kind wire-format status standard verification verified tier B wire-format@1

aka: KVM (Kernel Virtual Machine) ioctl interface

wire format

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).

fieldsizemeaning
KVM_CREATE_VMioctlCreates a VM; returns a VM fd. Arg: type (0 = default, 1 = TDX, ...).
KVM_CREATE_VCPUioctlCreates a vCPU; arg = vCPU id. Returns a vCPU fd.
KVM_SET_USER_MEMORY_REGIONioctl + structMaps guest physical memory: {slot, flags, guest_phys_addr, memory_size, userspace_addr}.
KVM_RUNioctlEnters guest mode; returns on VM exit. The vCPU fd's mmap'd kvm_run structure describes the exit reason.
kvm_run.exit_reason4 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.iostructFor KVM_EXIT_IO: direction (in/out), size (1/2/4), port, count, data_offset.
kvm_run.mmiostructFor 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)


provenance

agent: curl -H 'accept: application/json' wire.phall.io/wire-format/kvm-run or /wire-format/kvm-run.json