vm_topology/processor/
aarch64.rs

1// Copyright (c) Microsoft Corporation.
2// Licensed under the MIT License.
3
4//! ARM64-specific topology definitions.
5
6use super::ArchTopology;
7use super::InvalidTopology;
8use super::ProcessorTopology;
9use super::TopologyBuilder;
10use super::VpIndex;
11use super::VpInfo;
12use super::VpTopologyInfo;
13use aarch64defs::MpidrEl1;
14
15/// ARM64-specific topology information.
16#[cfg_attr(feature = "inspect", derive(inspect::Inspect))]
17#[derive(Debug, Copy, Clone)]
18#[non_exhaustive]
19pub struct Aarch64Topology {
20    platform: Aarch64PlatformConfig,
21}
22
23impl ArchTopology for Aarch64Topology {
24    type ArchVpInfo = Aarch64VpInfo;
25    type BuilderState = Aarch64TopologyBuilderState;
26
27    fn vp_topology(_topology: &ProcessorTopology<Self>, info: &Self::ArchVpInfo) -> VpTopologyInfo {
28        VpTopologyInfo {
29            socket: info.mpidr.aff2().into(),
30            core: info.mpidr.aff1().into(),
31            thread: info.mpidr.aff0().into(),
32        }
33    }
34}
35
36/// Aarch64-specific [`TopologyBuilder`] state.
37pub struct Aarch64TopologyBuilderState {
38    platform: Aarch64PlatformConfig,
39}
40
41/// GIC version and version-specific addressing for the virtual machine.
42#[derive(Debug, Clone, Copy, PartialEq, Eq)]
43#[cfg_attr(feature = "inspect", derive(inspect::Inspect))]
44#[cfg_attr(feature = "inspect", inspect(external_tag))]
45pub enum GicVersion {
46    /// GICv2 — uses a shared CPU interface region instead of per-VP redistributors.
47    /// Required for platforms like Raspberry Pi 5 (GIC-400).
48    V2 {
49        /// Physical base address of the GIC CPU interface.
50        #[cfg_attr(feature = "inspect", inspect(hex))]
51        cpu_interface_base: u64,
52    },
53    /// GICv3 — uses per-VP redistributors. Default for most server/desktop platforms.
54    V3 {
55        /// Physical base address of the GIC redistributor region.
56        #[cfg_attr(feature = "inspect", inspect(hex))]
57        redistributors_base: u64,
58    },
59}
60
61/// ARM64 platform interrupt and GIC configuration.
62///
63/// Groups GIC base addresses, MSI frame info, and platform interrupt
64/// assignments (PMU, virtual timer) into a single struct so that the
65/// topology builder takes one value instead of several positional `u32`s.
66#[derive(Debug, Clone, Copy, PartialEq, Eq)]
67#[cfg_attr(feature = "inspect", derive(inspect::Inspect))]
68pub struct Aarch64PlatformConfig {
69    /// GIC distributor base address.
70    #[cfg_attr(feature = "inspect", inspect(hex))]
71    pub gic_distributor_base: u64,
72    /// GIC version and version-specific addresses.
73    pub gic_version: GicVersion,
74    /// MSI controller for PCIe interrupt delivery.
75    pub gic_msi: GicMsiController,
76    /// Performance Monitor Unit GSIV (GIC INTID). `None` if not available.
77    pub pmu_gsiv: Option<u32>,
78    /// Virtual timer PPI (GIC INTID, e.g. 20 for PPI 4).
79    pub virt_timer_ppi: u32,
80    /// Total number of GIC interrupts (SGIs + PPIs + SPIs).
81    ///
82    /// KVM requires: `64 <= gic_nr_irqs <= 1023` and a multiple of 32.
83    /// The maximum valid value is 992 (31 × 32).
84    pub gic_nr_irqs: u32,
85}
86
87/// GIC v2m MSI frame parameters.
88#[derive(Debug, Clone, Copy, PartialEq, Eq)]
89#[cfg_attr(feature = "inspect", derive(inspect::Inspect))]
90pub struct GicV2mInfo {
91    /// Physical base address of the v2m MSI frame.
92    #[cfg_attr(feature = "inspect", inspect(hex))]
93    pub frame_base: u64,
94    /// First GIC interrupt ID in the SPI range owned by this frame.
95    pub spi_base: u32,
96    /// Number of SPIs owned by this frame.
97    pub spi_count: u32,
98}
99
100/// GICv3 ITS (Interrupt Translation Service) parameters.
101#[derive(Debug, Clone, Copy, PartialEq, Eq)]
102#[cfg_attr(feature = "inspect", derive(inspect::Inspect))]
103pub struct GicItsInfo {
104    /// Physical base address of the ITS MMIO region (must be 64 KiB aligned).
105    #[cfg_attr(feature = "inspect", inspect(hex))]
106    pub its_base: u64,
107}
108
109/// MSI controller configuration for PCIe interrupt delivery.
110#[derive(Debug, Clone, Copy, PartialEq, Eq)]
111#[cfg_attr(feature = "inspect", derive(inspect::Inspect))]
112#[cfg_attr(feature = "inspect", inspect(external_tag))]
113pub enum GicMsiController {
114    /// No MSI controller configured.
115    None,
116    /// GICv2m — maps MSI writes to a fixed pool of SPIs.
117    V2m(GicV2mInfo),
118    /// GICv3 ITS — routes MSIs via LPIs using (DeviceID, EventID) lookup.
119    Its(GicItsInfo),
120}
121
122/// ARM64 specific VP info.
123#[cfg_attr(feature = "inspect", derive(inspect::Inspect))]
124#[derive(Debug, Copy, Clone)]
125pub struct Aarch64VpInfo {
126    /// The base info.
127    #[cfg_attr(feature = "inspect", inspect(flatten))]
128    pub base: VpInfo,
129    /// The MPIDR_EL1 value of the processor.
130    #[cfg_attr(feature = "inspect", inspect(hex, with = "|&x| u64::from(x)"))]
131    pub mpidr: MpidrEl1,
132    /// GIC Redistributor Address (GICv3 only; `None` for GICv2).
133    #[cfg_attr(feature = "inspect", inspect(hex))]
134    pub gicr: Option<u64>,
135    /// Performance Interrupt GSIV (PMU)
136    #[cfg_attr(feature = "inspect", inspect(hex))]
137    pub pmu_gsiv: Option<u32>,
138}
139
140impl AsRef<VpInfo> for Aarch64VpInfo {
141    fn as_ref(&self) -> &VpInfo {
142        &self.base
143    }
144}
145
146impl AsMut<VpInfo> for Aarch64VpInfo {
147    fn as_mut(&mut self) -> &mut VpInfo {
148        &mut self.base
149    }
150}
151
152impl TopologyBuilder<Aarch64Topology> {
153    /// Returns a builder for creating an aarch64 processor topology.
154    pub fn new_aarch64(platform: Aarch64PlatformConfig) -> Self {
155        Self {
156            vps_per_socket: 1,
157            smt_enabled: false,
158            arch: Aarch64TopologyBuilderState { platform },
159        }
160    }
161
162    /// Builds a processor topology with `proc_count` processors.
163    pub fn build(
164        &self,
165        proc_count: u32,
166    ) -> Result<ProcessorTopology<Aarch64Topology>, InvalidTopology> {
167        if proc_count >= 256 {
168            return Err(InvalidTopology::TooManyVps {
169                requested: proc_count,
170                max: u8::MAX.into(),
171            });
172        }
173        if let GicVersion::V2 { .. } = self.arch.platform.gic_version {
174            if proc_count > 8 {
175                return Err(InvalidTopology::TooManyCpusForGicV2(proc_count));
176            }
177        }
178        if !(16..32).contains(&self.arch.platform.virt_timer_ppi) {
179            return Err(InvalidTopology::InvalidPpiIntid(
180                self.arch.platform.virt_timer_ppi,
181            ));
182        }
183        if let Some(gsiv) = self.arch.platform.pmu_gsiv {
184            if !(16..32).contains(&gsiv) {
185                return Err(InvalidTopology::InvalidPpiIntid(gsiv));
186            }
187        }
188        let nr = self.arch.platform.gic_nr_irqs;
189        if !(64..=992).contains(&nr) || !nr.is_multiple_of(32) {
190            return Err(InvalidTopology::InvalidGicNrIrqs(nr));
191        }
192        let mpidrs = (0..proc_count).map(|vp_index| {
193            // TODO: construct mpidr appropriately for the specified
194            // topology.
195            let uni_proc = proc_count == 1;
196            let mut aff = (0..4).map(|i| (vp_index >> (8 * i)) as u8);
197            MpidrEl1::new()
198                .with_res1_31(true)
199                .with_u(uni_proc)
200                .with_aff0(aff.next().unwrap())
201                .with_aff1(aff.next().unwrap())
202                .with_aff2(aff.next().unwrap())
203                .with_aff3(aff.next().unwrap())
204        });
205        let gic_version = self.arch.platform.gic_version;
206        self.build_with_vp_info(mpidrs.enumerate().map(move |(id, mpidr)| {
207            // GICv3 assigns a per-VP redistributor region; GICv2 has no
208            // redistributors so the field is zero.
209            let gicr = match gic_version {
210                GicVersion::V3 {
211                    redistributors_base,
212                } => Some(redistributors_base + id as u64 * aarch64defs::GIC_REDISTRIBUTOR_SIZE),
213                GicVersion::V2 { .. } => None,
214            };
215            Aarch64VpInfo {
216                base: VpInfo {
217                    vp_index: VpIndex::new(id as u32),
218                    vnode: 0,
219                },
220                mpidr,
221                gicr,
222                pmu_gsiv: self.arch.platform.pmu_gsiv,
223            }
224        }))
225    }
226
227    /// Builds a processor topology with processors with the specified information.
228    pub fn build_with_vp_info(
229        &self,
230        vps: impl IntoIterator<Item = Aarch64VpInfo>,
231    ) -> Result<ProcessorTopology<Aarch64Topology>, InvalidTopology> {
232        let vps = Vec::from_iter(vps);
233        let mut smt_enabled = false;
234        for (i, vp) in vps.iter().enumerate() {
235            if i != vp.base.vp_index.index() as usize {
236                return Err(InvalidTopology::InvalidVpIndices);
237            }
238
239            if vp.mpidr.mt() {
240                smt_enabled = true;
241            }
242        }
243
244        Ok(ProcessorTopology {
245            vps,
246            smt_enabled,
247            vps_per_socket: self.vps_per_socket,
248            arch: Aarch64Topology {
249                platform: self.arch.platform,
250            },
251        })
252    }
253}
254
255impl ProcessorTopology<Aarch64Topology> {
256    /// Returns the GIC version and version-specific addresses.
257    pub fn gic_version(&self) -> GicVersion {
258        self.arch.platform.gic_version
259    }
260
261    /// Returns the GIC distributor base
262    pub fn gic_distributor_base(&self) -> u64 {
263        self.arch.platform.gic_distributor_base
264    }
265
266    /// Returns the PMU GSIV
267    pub fn pmu_gsiv(&self) -> Option<u32> {
268        self.arch.platform.pmu_gsiv
269    }
270
271    /// Returns the MSI controller configuration.
272    pub fn gic_msi(&self) -> GicMsiController {
273        self.arch.platform.gic_msi
274    }
275
276    /// Returns the virtual timer PPI (GIC INTID).
277    pub fn virt_timer_ppi(&self) -> u32 {
278        self.arch.platform.virt_timer_ppi
279    }
280
281    /// Returns the total number of GIC interrupts to configure.
282    pub fn gic_nr_irqs(&self) -> u32 {
283        self.arch.platform.gic_nr_irqs
284    }
285}
vm_topology/processor/aarch64.rs

vm_topology/processor/
aarch64.rs
