Struct AxVCpu 

pub struct AxVCpu<A: AxArchVCpu> { /* private fields */ }

Architecture-independent virtual CPU implementation.

This is the main VCpu abstraction that provides a unified interface for managing virtual CPUs across different architectures. It delegates architecture-specific operations to implementations of the AxArchVCpu trait.

Note that:

• This struct handles internal mutability itself, almost all the methods are &self.
• This struct is not thread-safe. It’s caller’s responsibility to ensure the safety.

Implementations

impl<A: AxArchVCpu> AxVCpu<A>

pub fn new( vm_id: VMId, vcpu_id: VCpuId, favor_phys_cpu: usize, phys_cpu_set: Option<usize>, arch_config: A::CreateConfig, ) -> AxResult<Self>

Creates a new virtual CPU instance.

Initializes a VCpu with the given configuration and creates the underlying architecture-specific implementation. The VCpu starts in the Created state.

Arguments

• vm_id - Unique identifier of the VM this VCpu belongs to
• vcpu_id - Unique identifier for this VCpu within the VM
• favor_phys_cpu - Physical CPU ID that should preferentially run this VCpu
• phys_cpu_set - Optional bitmask of allowed physical CPUs (None = no restriction)
• arch_config - Architecture-specific configuration for VCpu creation

Returns

Returns Ok(AxVCpu) on success, or an error if architecture-specific creation fails.

pub fn setup( &self, entry: GuestPhysAddr, ept_root: HostPhysAddr, arch_config: A::SetupConfig, ) -> AxResult

Sets up the VCpu for execution.

Configures the VCpu’s entry point, memory management (EPT root), and any architecture-specific setup. Transitions the VCpu from Created to Free state.

pub const fn id(&self) -> VCpuId

Returns the unique identifier of this VCpu.

pub const fn vm_id(&self) -> VMId

Get the id of the VM this vcpu belongs to.

pub const fn favor_phys_cpu(&self) -> usize

Returns the preferred physical CPU for this VCpu.

This is used for CPU affinity optimization - the scheduler should preferentially run this VCpu on the returned physical CPU ID.

Note

Currently unused in the implementation but reserved for future scheduler optimizations.

pub const fn phys_cpu_set(&self) -> Option<usize>

Returns the set of physical CPUs that can run this VCpu.

pub const fn is_bsp(&self) -> bool

Checks if this VCpu is the Bootstrap Processor (BSP).

By convention, the VCpu with ID 0 is always considered the BSP, which is responsible for system initialization in multi-core VMs.

pub fn state(&self) -> VCpuState

Gets the current execution state of the VCpu.

pub unsafe fn set_state(&self, state: VCpuState)

Set the state of the VCpu.

Safety

This method is unsafe because it may break the state transition model. Use it with caution.

pub fn with_state_transition<F, T>( &self, from: VCpuState, to: VCpuState, f: F, ) -> AxResult<T>

where F: FnOnce() -> AxResult<T>,

Execute a block with the state of the VCpu transitioned from from to to. If the current state is not from, return an error.

The state will be set to VCpuState::Invalid if an error occurs (including the case that the current state is not from).

The state will be set to to if the block is executed successfully.

pub fn with_current_cpu_set<F, T>(&self, f: F) -> T

where F: FnOnce() -> T,

Execute a block with the current VCpu set to &self.

pub fn manipulate_arch_vcpu<F, T>( &self, from: VCpuState, to: VCpuState, f: F, ) -> AxResult<T>

where F: FnOnce(&mut A) -> AxResult<T>,

Execute an operation on the architecture-specific VCpu, with the state transitioned from from to to and the current VCpu set to &self.

This method is a combination of AxVCpu::with_state_transition and AxVCpu::with_current_cpu_set.

pub fn transition_state(&self, from: VCpuState, to: VCpuState) -> AxResult

Transition the state of the VCpu. If the current state is not from, return an error.

pub fn get_arch_vcpu(&self) -> &mut A

Get the architecture-specific VCpu.

pub fn run(&self) -> AxResult<AxVCpuExitReason>

Run the VCpu.

pub fn bind(&self) -> AxResult

Bind the VCpu to the current physical CPU.

pub fn unbind(&self) -> AxResult

Unbind the VCpu from the current physical CPU.

pub fn set_entry(&self, entry: GuestPhysAddr) -> AxResult

Sets the entry address of the VCpu.

pub fn set_gpr(&self, reg: usize, val: usize)

Sets the value of a general-purpose register according to the given index.

pub fn inject_interrupt(&self, vector: usize) -> AxResult

Inject an interrupt to the VCpu.

pub fn set_return_value(&self, val: usize)

Sets the return value of the VCpu.