axvm 0.5.25

Virtual Machine resource management crate for ArceOS's hypervisor variant.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

// Copyright 2025 The Axvisor Team
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! Runtime-owned per-vCPU interrupt dispatch queue.
//!
//! The dispatcher is owned by `VmRuntimeHandle` and lives for the duration of
//! one Running/Paused/Stopping lifecycle. Locking inside every method keeps
//! critical sections short: no wake, IPI, or external callbacks are invoked
//! while a lock is held.

use alloc::{collections::BTreeMap, vec::Vec};

use ax_kspin::SpinNoIrq as Mutex;

use super::queue::VcpuInterruptQueue;
use crate::{AxTaskRef, AxVmResult, ax_err_type, irq::model::PendingVcpuInterrupt};

/// Runtime-owned vCPU interrupt queue.
///
/// Lifecycle is tied to one Running/Paused/Stopping runtime.
/// Locks are held sequentially (never simultaneously), and no wake, IPI, or
/// external callback is invoked inside a critical section.
///
/// Will be embedded in
/// [`VmRuntimeHandle`](crate::vm::VmRuntimeHandle) as the destination for
/// architecture interrupt router output.  The vCPU run loop drains pending
/// interrupts before each vCPU entry and injects them through the
/// architecture-specific injection path.
pub struct VcpuIrqDispatcher {
    queue: VcpuInterruptQueue,
    vcpu_tasks: Mutex<BTreeMap<usize, AxTaskRef>>,
    /// Test-only cpu_id registry so that round-trip tests can exercise
    /// enqueue / drain without a full ArceOS task infrastructure.
    #[cfg(all(test, feature = "host-test"))]
    test_vcpu_cpu_ids: Mutex<BTreeMap<usize, usize>>,
}

impl VcpuIrqDispatcher {
    /// Creates an empty dispatcher.
    ///
    /// Called by `VmRuntimeHandle::new` when a VM transitions into the
    /// Running state.
    pub fn new() -> Self {
        Self {
            queue: VcpuInterruptQueue::new(),
            vcpu_tasks: Mutex::new(BTreeMap::new()),
            #[cfg(all(test, feature = "host-test"))]
            test_vcpu_cpu_ids: Mutex::new(BTreeMap::new()),
        }
    }

    /// Registers a vCPU task so that [`enqueue`](Self::enqueue) can discover
    /// the target physical CPU.
    ///
    /// Called from `VmRuntimeHandle::add_vcpu_task` when a vCPU task is
    /// spawned and bound to the VM runtime.
    pub fn register_vcpu_task(&self, vcpu_id: usize, task: AxTaskRef) {
        self.vcpu_tasks.lock().insert(vcpu_id, task);
    }

    #[cfg(all(test, feature = "host-test"))]
    pub(crate) fn register_test_vcpu(&self, vcpu_id: usize, cpu_id: usize) {
        self.test_vcpu_cpu_ids.lock().insert(vcpu_id, cpu_id);
    }

    #[cfg(all(test, feature = "host-test"))]
    pub(crate) fn test_lookup_cpu_id(&self, vcpu_id: usize) -> AxVmResult<usize> {
        self.lookup_cpu_id(vcpu_id)
    }

    /// Unregisters a vCPU task after the vCPU powers off.
    pub fn unregister_vcpu_task(&self, vcpu_id: usize) {
        self.vcpu_tasks.lock().remove(&vcpu_id);
        self.queue.drain(vcpu_id);
        #[cfg(all(test, feature = "host-test"))]
        self.test_vcpu_cpu_ids.lock().remove(&vcpu_id);
    }

    /// Enqueues a pending interrupt for the given vCPU.
    ///
    /// Returns the physical CPU id the target vCPU task is currently running
    /// on. The two internal locks are held **sequentially** (never together):
    ///
    /// 1. Lock `vcpu_tasks`, obtain `task.cpu_id()`, release.
    /// 2. Lock `queue`, push the interrupt, release.
    ///
    /// A task migration window exists between steps 1 and 2 (the pCPU may
    /// change), but `notify_all()` + `send_ipi` in the caller guarantee
    /// eventual delivery regardless of the race.
    ///
    /// # Errors
    ///
    /// Returns `NotFound` when the vCPU task has not been registered via
    /// [`register_vcpu_task`](Self::register_vcpu_task).
    ///
    /// Called by `VmRuntimeHandle::dispatch_vcpu_interrupt` when an
    /// architecture interrupt router requests delivery to a vCPU.
    pub fn enqueue(&self, vcpu_id: usize, interrupt: PendingVcpuInterrupt) -> AxVmResult<usize> {
        let cpu_id = self.lookup_cpu_id(vcpu_id)?;
        self.queue.push(vcpu_id, interrupt);
        Ok(cpu_id)
    }

    fn lookup_cpu_id(&self, vcpu_id: usize) -> AxVmResult<usize> {
        #[cfg(all(test, feature = "host-test"))]
        {
            if let Some(&cpu_id) = self.test_vcpu_cpu_ids.lock().get(&vcpu_id) {
                return Ok(cpu_id);
            }
        }
        let tasks = self.vcpu_tasks.lock();
        tasks
            .get(&vcpu_id)
            .map(|t| t.cpu_id() as usize)
            .ok_or_else(|| ax_err_type!(NotFound, format_args!("vCPU {vcpu_id} task not found")))
    }

    /// Drains all pending interrupts for the given vCPU, leaving its queue
    /// empty.
    ///
    /// The caller (vCPU run loop) runs on the target pCPU and injects each
    /// returned interrupt through the architecture-specific vCPU injection
    /// path before entering the guest.
    pub fn drain(&self, vcpu_id: usize) -> Vec<PendingVcpuInterrupt> {
        self.queue.drain(vcpu_id)
    }
}