tiny.sys.kvm

1pub const DecodeError = error{2    InvalidDirection,3    InvalidPayload,4    MappingTooSmall,5};

1pub const Direction = enum(u8) {2    input = 0,3    output = 1,4};

1pub const Exit = union(enum) {2    unknown: Unknown,3    exception: Exception,4    io: Io,5    hypercall: Hypercall,6    debug: Debug,7    halted,8    mmio: Mmio,9    interrupt_window_open,10    shutdown,11    fail_entry: FailEntry,12    interrupted,13    set_task_priority,14    task_priority_access: TaskPriorityAccess,15    non_maskable_interrupt,16    internal_error: InternalError,17    watchdog,18    system_event: SystemEvent,19    ioapic_eoi: u8,20    msr_read: Msr,21    msr_write: Msr,22    dirty_ring_full,23    application_processor_reset_hold,24    bus_lock,25    notify: Notify,26    memory_fault: MemoryFault,27    unhandled: Reason,28};

1pub const Reason = enum(u32) {2    unknown = 0,3    exception = 1,4    io = 2,5    hypercall = 3,6    debug = 4,7    halted = 5,8    mmio = 6,9    interrupt_window_open = 7,10    shutdown = 8,11    fail_entry = 9,12    interrupted = 10,13    set_task_priority = 11,14    task_priority_access = 12,15    s390_intercept = 13,16    s390_reset = 14,17    dcr = 15,18    non_maskable_interrupt = 16,19    internal_error = 17,20    osi = 18,21    papr_hypercall = 19,22    s390_ucontrol = 20,23    watchdog = 21,24    s390_tsch = 22,25    epr = 23,26    system_event = 24,27    s390_stsi = 25,28    ioapic_eoi = 26,29    hyperv = 27,30    arm_nisv = 28,31    msr_read = 29,32    msr_write = 30,33    dirty_ring_full = 31,34    application_processor_reset_hold = 32,35    bus_lock = 33,36    xen = 34,37    riscv_sbi = 35,38    riscv_csr = 36,39    notify = 37,40    loongarch_iocsr = 38,41    memory_fault = 39,42    tdx = 40,43    arm_sea = 41,44    arm_ldst64b = 42,45    snp_request_certificates = 43,46    _,47};

1pub const SystemEventKind = enum(u32) {2    shutdown = 1,3    reset = 2,4    crash = 3,5    wakeup = 4,6    @"suspend" = 5,7    encrypted_guest_termination = 6,8    confidential_guest_fatal = 7,9    _,10};

1pub const OpenAttempt = union(enum) {2    ready: System,3    rejected: types.CapabilityReceipt,4};

1pub const System = struct {2    pub const descriptor_capacity: usize = 1;34    operations: types.Operations,5    descriptor: types.Descriptor,6    receipt: types.CapabilityReceipt,7    active: bool = true,89    pub fn deinit(self: *@This()) void {10        if (!self.active) return;11        std.debug.assert(self.descriptor >= 0);12        self.operations.close(self.descriptor);13        self.active = false;14    }1516    pub fn createVm(self: *@This(), machine_type: u32) types.CreateError!vm.Vm {17        if (!self.active) return error.Closed;18        const result = types.controlRetry(19            self.operations,20            self.descriptor,21            abi.request.create_vm,22            machine_type,23        );24        const descriptor = try types.createDescriptor(result);25        return .{26            .operations = self.operations,27            .descriptor = descriptor,28            .run_mapping_bytes = self.receipt.run_mapping_bytes,29            .extensions = self.receipt.extensions,30        };31    }3233    pub fn memorySlotCapacity(self: *const @This()) u32 {34        std.debug.assert(self.active);35        return self.receipt.extensions.memory_slots;36    }3738    pub fn supportsReadOnlyMemory(self: *const @This()) bool {39        std.debug.assert(self.active);40        return self.receipt.extensions.read_only_memory != 0;41    }4243    pub fn supportedCpuid(self: *@This(), buffer: anytype) types.StateError!void {44        if (!self.active) return error.Closed;45        if (self.receipt.extensions.extended_cpuid == 0) {46            return error.UnsupportedState;47        }48        validateCpuidBuffer(@TypeOf(buffer.*));49        if (buffer.count > buffer.entries.len) return error.CapacityExceeded;50        try types.stateControl(51            self.operations,52            self.descriptor,53            abi.request.get_supported_cpuid,54            @intFromPtr(buffer),55        );56    }57};

1pub const Availability = enum {2    available,3    unsupported,4    unavailable,5    denied,6    failed,7};

1pub const CapabilityReceipt = struct {2    availability: Availability = .failed,3    stage: CapabilityStage = .platform,4    errno_code: u16 = 0,5    api_version: u32 = 0,6    run_mapping_bytes: u32 = 0,7    extensions: Extensions = .{},8};

1pub const CapabilityStage = enum {2    platform,3    device,4    api_version,5    run_mapping,6    extensions,7    complete,8};

1pub const CreateError = error{2    AccessDenied,3    Closed,4    CreateFailed,5    ResourceLimit,6    UnsupportedOperation,7};

1pub const Extensions = struct {2    user_memory: u32 = 0,3    extended_cpuid: u32 = 0,4    recommended_vcpus: u32 = 0,5    memory_slots: u32 = 0,6    multiprocessor_state: u32 = 0,7    vcpu_events: u32 = 0,8    debug_registers: u32 = 0,9    xsave: u32 = 0,10    xcrs: u32 = 0,11    maximum_vcpus: u32 = 0,12    read_only_memory: u32 = 0,13    maximum_vcpu_id: u32 = 0,14    immediate_exit: u32 = 0,15    special_registers_2: u32 = 0,16    xsave_2: u32 = 0,17};

1pub const MapResult = union(enum) {2    mapping: []align(page_size) u8,3    failure: Errno,4};

1pub const MemoryError = error{2    AccessDenied,3    Closed,4    GuestRangeOverflow,5    InvalidAlignment,6    InvalidSlot,7    MemoryRegionFailed,8    UnsupportedFlags,9};

1pub const MemoryRegion = struct {2    slot: u32,3    guest_physical_address: u64,4    memory: []align(page_size) u8,5    flags: abi.MemoryFlags = .{},6};

1pub const Operations = struct {2    context: *anyopaque,3    platform_supported: *const fn (*anyopaque) bool,4    open_device: *const fn (*anyopaque) RawResult,5    control_descriptor: *const fn (*anyopaque, Descriptor, u32, usize) RawResult,6    map_run: *const fn (*anyopaque, Descriptor, usize) MapResult,7    unmap_run: *const fn (*anyopaque, []align(page_size) u8) void,8    close_descriptor: *const fn (*anyopaque, Descriptor) void,910    pub fn platformSupported(self: @This()) bool {11        return self.platform_supported(self.context);12    }1314    pub fn openDevice(self: @This()) RawResult {15        return self.open_device(self.context);16    }1718    pub fn control(19        self: @This(),20        descriptor: Descriptor,21        request: u32,22        argument: usize,23    ) RawResult {24        return self.control_descriptor(self.context, descriptor, request, argument);25    }2627    pub fn mapRun(self: @This(), descriptor: Descriptor, len: usize) MapResult {28        return self.map_run(self.context, descriptor, len);29    }3031    pub fn unmap(self: @This(), mapping: []align(page_size) u8) void {32        self.unmap_run(self.context, mapping);33    }3435    pub fn close(self: @This(), descriptor: Descriptor) void {36        self.close_descriptor(self.context, descriptor);37    }38};

1pub const RawResult = union(enum) {2    value: usize,3    failure: Errno,4};

1pub const RunError = error{2    AccessDenied,3    Closed,4    Interrupted,5    InvalidRunState,6    RunFailed,7    UnsupportedOperation,8    WouldBlock,9};

1pub const StateError = error{2    AccessDenied,3    CapacityExceeded,4    Closed,5    PartialTransfer,6    StateFailed,7    UnsupportedState,8};

1pub const RunControls = struct {2    request_interrupt_window: bool = false,3    cr8: u64 = 0,4    apic_base: u64 = 0,5};

1pub const RunStatus = struct {2    ready_for_interrupt_injection: bool,3    interrupts_enabled: bool,4    flags: u16,5    cr8: u64,6    apic_base: u64,7};

1pub const Vcpu = struct {2    pub const descriptor_capacity: usize = 1;3    pub const mapping_capacity: usize = 1;45    operations: types.Operations,6    descriptor: types.Descriptor,7    mapping: []align(types.page_size) u8,8    extensions: types.Extensions,9    active: bool = true,1011    pub fn deinit(self: *@This()) void {12        if (!self.active) return;13        std.debug.assert(self.descriptor >= 0);14        std.debug.assert(self.mapping.len >= abi.minimum_run_bytes);15        self.operations.unmap(self.mapping);16        self.operations.close(self.descriptor);17        self.active = false;18    }1920    pub fn run(self: *@This()) (types.RunError || run_exit.DecodeError)!run_exit.Exit {21        if (!self.active) return error.Closed;22        std.debug.assert(self.mapping.len >= abi.minimum_run_bytes);23        switch (self.operations.control(self.descriptor, abi.request.run, 0)) {24            .value => {},25            .failure => |code| return runError(code),26        }27        return run_exit.decode(self.mapping);28    }2930    pub fn setImmediateExit(self: *@This(), requested: bool) types.RunError!void {31        if (!self.active) return error.Closed;32        if (self.extensions.immediate_exit == 0) {33            return error.UnsupportedOperation;34        }35        std.debug.assert(self.mapping.len >= @sizeOf(abi.RunHeader));36        const header: *abi.RunHeader = @ptrCast(self.mapping.ptr);37        @atomicStore(u8, &header.immediate_exit, @intFromBool(requested), .monotonic);38    }3940    pub fn setRunControls(self: *@This(), controls: RunControls) types.RunError!void {41        if (!self.active) return error.Closed;42        const header = self.runHeader();43        header.request_interrupt_window = @intFromBool(controls.request_interrupt_window);44        header.cr8 = controls.cr8;45        header.apic_base = controls.apic_base;46    }4748    pub fn runStatus(self: *@This()) types.RunError!RunStatus {49        if (!self.active) return error.Closed;50        const header = self.runHeader();51        return .{52            .ready_for_interrupt_injection = header.ready_for_interrupt_injection != 0,53            .interrupts_enabled = header.interrupts_enabled != 0,54            .flags = header.flags,55            .cr8 = header.cr8,56            .apic_base = header.apic_base,57        };58    }5960    pub fn capture(self: *@This(), parts: state.Parts) types.StateError!state.Fixed {61        if (!self.active) return error.Closed;62        if (!fixedStateSupported(parts, self.extensions)) return error.UnsupportedState;63        var result = std.mem.zeroes(state.Fixed);64        result.valid = parts;65        try self.captureBasic(parts, &result);66        try self.captureExtended(parts, &result);67        return result;68    }6970    pub fn restore(self: *@This(), snapshot: *const state.Fixed) types.StateError!void {71        if (!self.active) return error.Closed;72        if (!fixedStateSupported(snapshot.valid, self.extensions)) {73            return error.UnsupportedState;74        }75        try self.restoreBasic(snapshot);76        try self.restoreExtended(snapshot);77    }7879    pub fn readMsrs(self: *@This(), buffer: anytype) types.StateError!void {80        if (!self.active) return error.Closed;81        validateMsrBuffer(@TypeOf(buffer.*));82        if (buffer.count > buffer.entries.len) return error.CapacityExceeded;83        const result = types.controlRetry(84            self.operations,85            self.descriptor,86            abi.request.get_msrs,87            @intFromPtr(buffer),88        );89        try expectTransfer(result, buffer.count);90    }9192    pub fn writeMsrs(self: *@This(), buffer: anytype) types.StateError!void {93        if (!self.active) return error.Closed;94        validateMsrBuffer(@TypeOf(buffer.*));95        if (buffer.count > buffer.entries.len) return error.CapacityExceeded;96        const result = types.controlRetry(97            self.operations,98            self.descriptor,99            abi.request.set_msrs,100            @intFromPtr(buffer),101        );102        try expectTransfer(result, buffer.count);103    }104105    pub fn readCpuid(self: *@This(), buffer: anytype) types.StateError!void {106        if (!self.active) return error.Closed;107        if (self.extensions.extended_cpuid == 0) return error.UnsupportedState;108        validateCpuidBuffer(@TypeOf(buffer.*));109        if (buffer.count > buffer.entries.len) return error.CapacityExceeded;110        try types.stateControl(111            self.operations,112            self.descriptor,113            abi.request.get_cpuid,114            @intFromPtr(buffer),115        );116    }117118    pub fn writeCpuid(self: *@This(), buffer: anytype) types.StateError!void {119        if (!self.active) return error.Closed;120        if (self.extensions.extended_cpuid == 0) return error.UnsupportedState;121        validateCpuidBuffer(@TypeOf(buffer.*));122        if (buffer.count > buffer.entries.len) return error.CapacityExceeded;123        try types.stateControl(124            self.operations,125            self.descriptor,126            abi.request.set_cpuid,127            @intFromPtr(buffer),128        );129    }130131    fn captureBasic(132        self: *@This(),133        parts: state.Parts,134        result: *state.Fixed,135    ) types.StateError!void {136        if (parts.registers) try self.get(abi.request.get_registers, &result.registers);137        if (parts.special_registers) {138            try self.get(abi.request.get_special_registers, &result.special_registers);139        }140        if (parts.fpu) try self.get(abi.request.get_fpu, &result.fpu);141    }142143    fn captureExtended(144        self: *@This(),145        parts: state.Parts,146        result: *state.Fixed,147    ) types.StateError!void {148        if (parts.events) try self.get(abi.request.get_vcpu_events, &result.events);149        if (parts.debug_registers) {150            try self.get(abi.request.get_debug_registers, &result.debug_registers);151        }152        if (parts.xsave) try self.get(abi.request.get_xsave, &result.xsave);153        if (parts.xcrs) try self.get(abi.request.get_xcrs, &result.xcrs);154        if (parts.multiprocessor) {155            try self.get(abi.request.get_mp_state, &result.multiprocessor);156        }157    }158159    fn restoreBasic(self: *@This(), snapshot: *const state.Fixed) types.StateError!void {160        if (snapshot.valid.special_registers) {161            try self.set(abi.request.set_special_registers, &snapshot.special_registers);162        }163        if (snapshot.valid.registers) {164            try self.set(abi.request.set_registers, &snapshot.registers);165        }166        if (snapshot.valid.fpu) try self.set(abi.request.set_fpu, &snapshot.fpu);167    }168169    fn restoreExtended(170        self: *@This(),171        snapshot: *const state.Fixed,172    ) types.StateError!void {173        if (snapshot.valid.events) {174            try self.set(abi.request.set_vcpu_events, &snapshot.events);175        }176        if (snapshot.valid.debug_registers) {177            try self.set(abi.request.set_debug_registers, &snapshot.debug_registers);178        }179        if (snapshot.valid.xsave) try self.set(abi.request.set_xsave, &snapshot.xsave);180        if (snapshot.valid.xcrs) try self.set(abi.request.set_xcrs, &snapshot.xcrs);181        if (snapshot.valid.multiprocessor) {182            try self.set(abi.request.set_mp_state, &snapshot.multiprocessor);183        }184    }185186    fn get(self: *@This(), request: u32, destination: anytype) types.StateError!void {187        std.debug.assert(request != 0);188        try types.stateControl(189            self.operations,190            self.descriptor,191            request,192            @intFromPtr(destination),193        );194    }195196    fn set(self: *@This(), request: u32, source: anytype) types.StateError!void {197        std.debug.assert(request != 0);198        try types.stateControl(199            self.operations,200            self.descriptor,201            request,202            @intFromPtr(source),203        );204    }205206    fn runHeader(self: *@This()) *abi.RunHeader {207        std.debug.assert(self.mapping.len >= @sizeOf(abi.RunHeader));208        return @ptrCast(self.mapping.ptr);209    }210};

1pub const Vm = struct {2    pub const descriptor_capacity: usize = 1;34    operations: types.Operations,5    descriptor: types.Descriptor,6    run_mapping_bytes: u32,7    extensions: types.Extensions,8    active: bool = true,910    pub fn deinit(self: *@This()) void {11        if (!self.active) return;12        std.debug.assert(self.descriptor >= 0);13        self.operations.close(self.descriptor);14        self.active = false;15    }1617    pub fn registerMemory(18        self: *@This(),19        region: types.MemoryRegion,20    ) types.MemoryError!void {21        if (!self.active) return error.Closed;22        try validateMemory(region, self.extensions);23        const raw: abi.UserMemoryRegion = .{24            .slot = region.slot,25            .flags = region.flags.bits(),26            .guest_physical_address = region.guest_physical_address,27            .memory_size = @intCast(region.memory.len),28            .userspace_address = @intFromPtr(region.memory.ptr),29        };30        try memoryControl(self.operations, self.descriptor, &raw);31    }3233    pub fn unregisterMemory(self: *@This(), slot: u32) types.MemoryError!void {34        if (!self.active) return error.Closed;35        if (self.extensions.memory_slots != 0 and slot >= self.extensions.memory_slots) {36            return error.InvalidSlot;37        }38        const raw: abi.UserMemoryRegion = .{39            .slot = slot,40            .flags = 0,41            .guest_physical_address = 0,42            .memory_size = 0,43            .userspace_address = 0,44        };45        try memoryControl(self.operations, self.descriptor, &raw);46    }4748    pub fn createVcpu(self: *@This(), identifier: u32) types.CreateError!vcpu.Vcpu {49        if (!self.active) return error.Closed;50        if (self.extensions.maximum_vcpu_id != 0 and51            identifier >= self.extensions.maximum_vcpu_id)52        {53            return error.UnsupportedOperation;54        }55        const result = types.controlRetry(56            self.operations,57            self.descriptor,58            abi.request.create_vcpu,59            identifier,60        );61        const descriptor = try types.createDescriptor(result);62        return createVcpuMapping(self, descriptor);63    }6465    pub fn getClock(self: *@This()) types.StateError!abi.Clock {66        if (!self.active) return error.Closed;67        var clock = std.mem.zeroes(abi.Clock);68        try types.stateControl(69            self.operations,70            self.descriptor,71            abi.request.get_clock,72            @intFromPtr(&clock),73        );74        return clock;75    }7677    pub fn setClock(self: *@This(), clock: *const abi.Clock) types.StateError!void {78        if (!self.active) return error.Closed;79        try types.stateControl(80            self.operations,81            self.descriptor,82            abi.request.set_clock,83            @intFromPtr(clock),84        );85    }8687    fn createVcpuMapping(88        self: *@This(),89        descriptor: types.Descriptor,90    ) types.CreateError!vcpu.Vcpu {91        std.debug.assert(self.run_mapping_bytes >= abi.minimum_run_bytes);92        const mapping = switch (self.operations.mapRun(93            descriptor,94            self.run_mapping_bytes,95        )) {96            .mapping => |value| value,97            .failure => |code| {98                self.operations.close(descriptor);99                return types.createError(code);100            },101        };102        std.debug.assert(mapping.len >= self.run_mapping_bytes);103        return .{104            .operations = self.operations,105            .descriptor = descriptor,106            .mapping = mapping,107            .extensions = self.extensions,108        };109    }110};

1pub fn decode(mapping: []align(std.heap.page_size_min) u8) DecodeError!Exit {2    if (mapping.len < abi.minimum_run_bytes) return error.MappingTooSmall;3    const header = view(abi.RunHeader, mapping);4    const reason: Reason = @fromBackingInt(@intCast(header.exit_reason));5    return switch (reason) {6        .unknown => decodeUnknown(mapping),7        .exception => decodeException(mapping),8        .io => decodeIo(mapping),9        .hypercall => decodeHypercall(mapping),10        .debug => decodeDebug(mapping),11        .halted => .halted,12        .mmio => decodeMmio(mapping),13        .interrupt_window_open => .interrupt_window_open,14        .shutdown => .shutdown,15        .fail_entry => decodeFailEntry(mapping),16        .interrupted => .interrupted,17        .set_task_priority => .set_task_priority,18        .task_priority_access => decodeTaskPriorityAccess(mapping),19        .non_maskable_interrupt => .non_maskable_interrupt,20        .internal_error => decodeInternalError(mapping),21        .watchdog => .watchdog,22        .system_event => decodeSystemEvent(mapping),23        .ioapic_eoi => decodeIoapicEoi(mapping),24        .msr_read => .{ .msr_read = decodeMsr(mapping) },25        .msr_write => .{ .msr_write = decodeMsr(mapping) },26        .dirty_ring_full => .dirty_ring_full,27        .application_processor_reset_hold => .application_processor_reset_hold,28        .bus_lock => .bus_lock,29        .notify => decodeNotify(mapping),30        .memory_fault => decodeMemoryFault(mapping),31        else => .{ .unhandled = reason },32    };33}

1pub const supported = builtin.os.tag == .linux and builtin.cpu.arch == .x86_64;

1pub fn acquire(operations: types.Operations) OpenAttempt {2    var receipt: types.CapabilityReceipt = .{};3    if (!operations.platformSupported()) {4        receipt.availability = .unsupported;5        return .{ .rejected = receipt };6    }7    receipt.stage = .device;8    const descriptor = openDescriptor(operations, &receipt) orelse {9        return .{ .rejected = receipt };10    };11    if (!readApiVersion(operations, descriptor, &receipt)) {12        operations.close(descriptor);13        return .{ .rejected = receipt };14    }15    if (!readRunMappingSize(operations, descriptor, &receipt)) {16        operations.close(descriptor);17        return .{ .rejected = receipt };18    }19    if (!readExtensions(operations, descriptor, &receipt)) {20        operations.close(descriptor);21        return .{ .rejected = receipt };22    }23    receipt.availability = .available;24    receipt.stage = .complete;25    return .{ .ready = .{26        .operations = operations,27        .descriptor = descriptor,28        .receipt = receipt,29    } };30}

1pub fn open() OpenAttempt {2    return acquire(linux.operations());3}

1pub fn probe() types.CapabilityReceipt {2    return switch (open()) {3        .ready => |value| result: {4            var system = value;5            const receipt = system.receipt;6            system.deinit();7            break :result receipt;8        },9        .rejected => |receipt| receipt,10    };11}

1pub const supported_cpuid_entries_max: usize = 256;

1pub fn operationsFor(implementation: anytype) Operations {2    const pointer = @typeInfo(@TypeOf(implementation)).pointer;3    const ImplementationAdapter = Adapter(pointer.child);4    return .{5        .context = implementation,6        .platform_supported = ImplementationAdapter.platformSupported,7        .open_device = ImplementationAdapter.openDevice,8        .control_descriptor = ImplementationAdapter.control,9        .map_run = ImplementationAdapter.mapRun,10        .unmap_run = ImplementationAdapter.unmap,11        .close_descriptor = ImplementationAdapter.close,12    };13}

1const sys = @import("../root.zig");2const linux = @import("linux.zig");3const run_exit = @import("exit.zig");4const system = @import("system.zig");5const types = @import("types.zig");6const vcpu = @import("vcpu.zig");7const vm = @import("vm.zig");89pub const abi = @import("abi.zig");10pub const state = @import("state.zig");1112pub const required_capabilities = sys.capabilities.noLibc(&.{13    .descriptors,14    .memory_mapping,15    .virtualization,16});1718pub const supported = linux.supported;19pub const Availability = types.Availability;20pub const CapabilityReceipt = types.CapabilityReceipt;21pub const CapabilityStage = types.CapabilityStage;22pub const Extensions = types.Extensions;23pub const MemoryRegion = types.MemoryRegion;24pub const MapResult = types.MapResult;25pub const OpenAttempt = system.OpenAttempt;26pub const Operations = types.Operations;27pub const System = system.System;28pub const Vm = vm.Vm;29pub const Vcpu = vcpu.Vcpu;30pub const RunControls = vcpu.RunControls;31pub const RunStatus = vcpu.RunStatus;32pub const RawResult = types.RawResult;33pub const CreateError = types.CreateError;34pub const MemoryError = types.MemoryError;35pub const RunError = types.RunError;36pub const StateError = types.StateError;3738pub const DecodeError = run_exit.DecodeError;39pub const Direction = run_exit.Direction;40pub const Exit = run_exit.Exit;41pub const ExitReason = run_exit.Reason;42pub const SystemEventKind = run_exit.SystemEventKind;4344pub const decode = run_exit.decode;45pub const acquire = system.acquire;46pub const open = system.open;47pub const operationsFor = types.operationsFor;48pub const probe = system.probe;49pub const supported_cpuid_entries_max = system.supported_cpuid_entries_max;

1pub const kvm = @import("kvm/root.zig");