Enum AxVCpuExitReason

Source

#[non_exhaustive]pub enum AxVCpuExitReason {
Show 16 variants    Hypercall {
        nr: u64,
        args: [u64; 6],
    },
    MmioRead {
        addr: GuestPhysAddr,
        width: AccessWidth,
        reg: usize,
        reg_width: AccessWidth,
        signed_ext: bool,
    },
    MmioWrite {
        addr: GuestPhysAddr,
        width: AccessWidth,
        data: u64,
    },
    SysRegRead {
        addr: SysRegAddr,
        reg: usize,
    },
    SysRegWrite {
        addr: SysRegAddr,
        value: u64,
    },
    IoRead {
        port: Port,
        width: AccessWidth,
    },
    IoWrite {
        port: Port,
        width: AccessWidth,
        data: u64,
    },
    ExternalInterrupt {
        vector: u64,
    },
    NestedPageFault {
        addr: GuestPhysAddr,
        access_flags: MappingFlags,
    },
    Halt,
    CpuUp {
        target_cpu: u64,
        entry_point: GuestPhysAddr,
        arg: u64,
    },
    CpuDown {
        _state: u64,
    },
    SystemDown,
    Nothing,
    FailEntry {
        hardware_entry_failure_reason: u64,
    },
    SendIPI {
        target_cpu: u64,
        target_cpu_aux: u64,
        send_to_all: bool,
        send_to_self: bool,
        vector: u64,
    },
}

Expand description

Reasons for VM-Exits returned by AxArchVCpu::run.

When a guest virtual CPU executes, various conditions can cause control to be transferred back to the hypervisor. This enum represents all possible exit reasons that can occur during VCpu execution.

§VM Exit Categories

I/O Operations: MMIO reads/writes, port I/O, system register access
System Events: Hypercalls, interrupts, nested page faults
Power Management: CPU power state changes, system shutdown
Multiprocessing: IPI sending, secondary CPU bring-up
Error Conditions: Entry failures, invalid states

§Compatibility Note

This enum draws inspiration from kvm-ioctls for consistency with existing virtualization frameworks.

Variants (Non-exhaustive)§

This enum is marked as non-exhaustive

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

§

Hypercall

A guest instruction triggered a hypercall to the hypervisor.

Hypercalls are a mechanism for the guest OS to request services from the hypervisor, similar to system calls in a traditional OS.

Fields

§nr: u64

The hypercall number identifying the requested service

§args: [u64; 6]

Arguments passed to the hypercall (up to 6 parameters)

§

MmioRead

The guest performed a Memory-Mapped I/O (MMIO) read operation.

MMIO reads occur when the guest accesses device registers or other hardware-mapped memory regions that require hypervisor emulation.

Fields

§addr: GuestPhysAddr

Guest physical address being read from

§width: AccessWidth

Width/size of the memory access (8, 16, 32, or 64 bits)

§reg: usize

Index of the guest register that will receive the read value

§reg_width: AccessWidth

Width of the destination register

§signed_ext: bool

Whether to sign-extend the read value to fill the register

§

MmioWrite

The guest performed a Memory-Mapped I/O (MMIO) write operation.

MMIO writes occur when the guest writes to device registers or other hardware-mapped memory regions that require hypervisor emulation.

Fields

§addr: GuestPhysAddr

Guest physical address being written to

§width: AccessWidth

Width/size of the memory access (8, 16, 32, or 64 bits)

§data: u64

Data being written to the memory location

§

SysRegRead

The guest performed a system register read operation.

System registers are architecture-specific control and status registers:

x86_64: Model-Specific Registers (MSRs)
RISC-V: Control and Status Registers (CSRs)
AArch64: System registers accessible via MRS instruction

Fields

§addr: SysRegAddr

Address/identifier of the system register being read

x86_64/RISC-V: Direct register address
AArch64: ESR_EL2.ISS format (<op0><op2><op1><CRn>00000<CRm>0) compatible with the aarch64_sysreg crate numbering scheme

§reg: usize

Index of the guest register that will receive the read value

Note: Unused on x86_64 where the result is always stored in [edx:eax]

§

SysRegWrite

The guest performed a system register write operation.

System registers are architecture-specific control and status registers:

x86_64: Model-Specific Registers (MSRs)
RISC-V: Control and Status Registers (CSRs)
AArch64: System registers accessible via MSR instruction

Fields

§addr: SysRegAddr

Address/identifier of the system register being written

x86_64/RISC-V: Direct register address
AArch64: ESR_EL2.ISS format (<op0><op2><op1><CRn>00000<CRm>0) compatible with the aarch64_sysreg crate numbering scheme

§value: u64

Data being written to the system register

§

IoRead

The guest performed a port-based I/O read operation.

Architecture: x86-specific (other architectures don’t have port I/O)

The destination register is implicitly al/ax/eax based on the access width.

Fields

§port: Port

I/O port number being read from

§width: AccessWidth

Width of the I/O access (8, 16, or 32 bits)

§

IoWrite

The guest performed a port-based I/O write operation.

Architecture: x86-specific (other architectures don’t have port I/O)

The source register is implicitly al/ax/eax based on the access width.

Fields

§port: Port

I/O port number being written to

§width: AccessWidth

Width of the I/O access (8, 16, or 32 bits)

§data: u64

Data being written to the I/O port

§

ExternalInterrupt

An external interrupt was delivered to the VCpu.

This represents hardware interrupts from external devices that need to be processed by the guest or hypervisor.

Note: This enum may be extended with additional fields in the future. Use .. in pattern matching to ensure forward compatibility.

Fields

§vector: u64

Hardware interrupt vector number

§

NestedPageFault

A nested page fault occurred during guest memory access.

Also known as EPT violations on x86. These faults occur when:

Guest accesses unmapped memory regions
Access permissions are violated (e.g., writing to read-only pages)
Page table entries need to be populated or updated

Note: This enum may be extended with additional fields in the future. Use .. in pattern matching to ensure forward compatibility.

Fields

§addr: GuestPhysAddr

Guest physical address that caused the fault

§access_flags: MappingFlags

Type of access that was attempted (read/write/execute)

§

Halt

The guest VCpu has executed a halt instruction and is now idle.

This typically occurs when the guest OS has no work to do and is waiting for interrupts or other events to wake it up.

§

CpuUp

Request to bring up a secondary CPU core.

This exit reason is used during the multi-core VM boot process when the primary CPU requests that a secondary CPU be started. The specific mechanism varies by architecture:

ARM: PSCI (Power State Coordination Interface) calls
x86: SIPI (Startup Inter-Processor Interrupt)
RISC-V: SBI (Supervisor Binary Interface) calls

Fields

§target_cpu: u64

Target CPU identifier to be started

Format varies by architecture:

AArch64: MPIDR register affinity fields
x86_64: APIC ID of the target CPU
RISC-V: Hart ID of the target CPU

§entry_point: GuestPhysAddr

Guest physical address where the secondary CPU should begin execution

§arg: u64

Argument to pass to the secondary CPU

AArch64: Value to set in x0 register at startup
RISC-V: Value to set in a1 register (a0 gets the hartid)
x86_64: Currently unused

§

CpuDown

The guest VCpu has been powered down.

This indicates the VCpu has executed a power-down instruction or hypercall and should be suspended. The VCpu may be resumed later.

Fields

§_state: u64

Power state information (currently unused)

Reserved for future use with PSCI_POWER_STATE or similar mechanisms

§

SystemDown

The guest has requested system-wide shutdown.

This indicates the entire virtual machine should be powered off, not just the current VCpu.

§

Nothing

No special handling required - the VCpu handled the exit internally.

This provides an opportunity for the hypervisor to:

Check virtual device states
Process pending interrupts
Handle background tasks
Perform scheduling decisions

The VCpu can typically be resumed immediately after these checks.

§

FailEntry

VM entry failed due to invalid VCpu state or configuration.

This corresponds to KVM_EXIT_FAIL_ENTRY in KVM and indicates that the hardware virtualization layer could not successfully enter the guest.

The failure reason contains architecture-specific diagnostic information.

Fields

§hardware_entry_failure_reason: u64

Hardware-specific failure reason code

Interpretation depends on the underlying virtualization technology and CPU architecture. Consult architecture documentation for details.

§

SendIPI

The guest is attempting to send an Inter-Processor Interrupt (IPI).

IPIs are used for inter-CPU communication in multi-core systems. This does not include Startup IPIs (SIPI), which are handled by the AxVCpuExitReason::CpuUp variant.