Crate arm_vcpu 

arm_vcpu

OS-neutral AArch64 vCPU core

English | 中文

Introduction

arm_vcpu provides an OS-neutral AArch64 vCPU core. It owns EL2 guest entry/exit, guest register state, trap decode, and hardware virtualization register semantics. Host OS and VMM policy is supplied through ArmHostOps; AxVM integration lives in virtualization/axvm/src/arch/aarch64.

Quick Start

Installation

Add this crate to your Cargo.toml:

[dependencies]
arm_vcpu = "0.5.0"

Run Check and Test

# Enter the crate directory
cd virtualization/arm_vcpu

# Format code
cargo fmt --all

# Run the workspace clippy flow
cargo xtask clippy --package arm_vcpu

# Run host-runnable contract tests
cargo test -p arm_vcpu --test dependency_contract_test

# Build documentation
cargo doc --no-deps

Integration

Example

use arm_vcpu::{ArmHostOps, ArmVcpu, ArmVcpuCreateConfig, ArmVcpuResult};

struct MyHost;

impl ArmHostOps for MyHost {
    fn inject_virtual_interrupt(_vector: u32) -> ArmVcpuResult {
        Ok(())
    }

    fn fetch_pending_host_irq() -> Option<usize> {
        None
    }

    fn handle_current_host_irq() {}
}

fn build_vcpu() -> ArmVcpuResult<ArmVcpu<MyHost>> {
    ArmVcpu::<MyHost>::new(0, 0, ArmVcpuCreateConfig::default())
}

Documentation

Generate and view API documentation:

cargo doc --no-deps --open

Online documentation: docs.rs/arm_vcpu

Contributing

1. Fork the repository and create a branch
2. Run local format and checks
3. Run local tests relevant to this crate
4. Submit a PR and ensure CI passes

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Structs

ArmGuestPhysAddr

Guest physical address.

ArmHostIrqConfig

Host interrupt-controller interface used by the assembly-only IRQ-exit transaction.

ArmHostIrqGuard

Proof that host IRQ delivery is masked on the current physical CPU.

ArmNestedPagingConfig

Stage-2 page table configuration selected by the embedding VMM.

ArmPerCpu

Per-CPU AArch64 virtualization state.

ArmSysRegAddr

AArch64 system-register address encoding used by trapped MRS/MSR exits.

ArmTimerContext

Canonical writable state of one vCPU timer.

ArmTimerSnapshot

Immutable vCPU timer state sampled after a world switch.

ArmTimerVmConfig

Immutable generic-timer configuration shared by every vCPU in one VM.

ArmVcpu

A virtual CPU within a guest.

ArmVcpuCreateConfig

Configuration for creating a new ArmVcpu.

ArmVcpuSetupConfig

Fixed EL2 setup policy for a new ArmVcpu.

ArmVcpuTimer

Timer state owned by one vCPU.

Enums

ArmAccessWidth

Width of a trapped guest memory access.

ArmGicCpuInterfaceRegister

Common GICv3 CPU-interface register trapped by the vCPU core.

ArmTimerKind

One architectural generic-timer instance owned by a vCPU.

ArmVcpuError

Errors produced by the OS-neutral AArch64 vCPU core.

ArmVmExit

VM-exit reason returned by the AArch64 vCPU core.

Constants

ARM_VCPU_HOST_SP_EL0_OFFSET

Offset of [HostRuntimeContext::sp_el0] within ArmVcpu.

ARM_VCPU_HOST_STACK_TOP_OFFSET

Offset of [HostRuntimeContext::stack_top] within ArmVcpu.

ARM_VCPU_TRAP_FRAME_SIZE

Size of the guest trap frame used by the EL2 entry/exit assembly.

Traits

ArmHostOps

Host operations required by AArch64 virtualization code.

ArmTimerRegisters

Register operations required by a generic-timer world switch.

Functions

has_hardware_support

Returns whether the current platform supports the virtualization extension.

max_guest_page_table_levels

Returns the maximum guest page-table levels supported by the current CPU.

pa_bits

Returns the physical-address width reported by the current CPU.

Type Aliases

ArmVcpuResult

Result type returned by the OS-neutral AArch64 vCPU core.

TrapFrame

Context frame saved on an AArch64 guest exception.