feat(cpu): introduce CPU topology configuration

This commit adds option `topology` to flag --cpu to allow users to
specify CPU topology.

On x86_64, the CPU topology is encoded in CPU x2APIC ID, as well CPUID
leaf 0xb, 0x1f (Intel Only), and 0x8000_0026 (AMD only). On aarch64, the
CPU topology is encoded in CPU MPIDR and the devicetree.

Signed-off-by: Changyuan Lyu <changyuanl@google.com>

Author: Lencerf

alioth-cli/src/boot.rs

@@ -390,6 +390,7 @@ pub fn boot(args: BootArgs) -> Result<(), Error> {
         eprintln!("Please update the cmd line to --cpu count={}", args.num_cpu);
         CpuConfig {
             count: args.num_cpu,
+            ..Default::default()
         }
     };
     let board_config = BoardConfig {

alioth/src/arch/aarch64/reg.rs

@@ -174,10 +174,10 @@ bitfield! {
     #[derive(Copy, Clone, Default, PartialEq, Eq, Hash)]
     pub struct MpidrEl1(u64);
     impl Debug;
-    pub aff3, set_aff3: 39, 32;
+    pub u8, aff3, set_aff3: 39, 32;
     pub u, set_u: 30;
     pub mt, set_mt: 24;
-    pub aff2, set_aff2: 23, 16;
-    pub aff1, set_aff1: 15, 8;
-    pub aff0, set_aff0: 7, 0;
+    pub u8, aff2, set_aff2: 23, 16;
+    pub u8, aff1, set_aff1: 15, 8;
+    pub u8, aff0, set_aff0: 7, 0;
 }

alioth/src/board/board.rs

@@ -70,6 +70,8 @@ pub enum Error {
     Memory { source: Box<crate::mem::Error> },
     #[snafu(display("Failed to load payload"), context(false))]
     Loader { source: Box<crate::loader::Error> },
+    #[snafu(display("Invalid CPU topology"))]
+    InvalidCpuTopology,
     #[snafu(display("Failed to create VCPU-{index}"))]
     CreateVcpu {
         index: u16,
@@ -99,6 +101,29 @@ pub enum Error {
 
 type Result<T, E = Error> = std::result::Result<T, E>;
 
+#[derive(Clone, Copy, Debug, PartialEq, Deserialize, Default, Help)]
+pub struct CpuTopology {
+    #[serde(default)]
+    /// Enable SMT (Hyperthreading)
+    pub smt: bool,
+    #[serde(default)]
+    /// Number of cores per socket.
+    pub cores: u16,
+    #[serde(default)]
+    /// Number of sockets.
+    pub sockets: u8,
+}
+
+impl CpuTopology {
+    pub fn encode(&self, index: u16) -> (u8, u16, u8) {
+        let total_cores = self.cores * self.sockets as u16;
+        let thread_id = index / total_cores;
+        let core_id = index % total_cores % self.cores;
+        let socket_id = index % total_cores / self.cores;
+        (thread_id as u8, core_id, socket_id as u8)
+    }
+}
+
 const fn default_cpu_count() -> u16 {
     1
 }
@@ -108,6 +133,27 @@ pub struct CpuConfig {
     /// Number of VCPUs assigned to the guest. [default: 1]
     #[serde(default = "default_cpu_count")]
     pub count: u16,
+    /// Architecture specific CPU topology
+    #[serde(default)]
+    pub topology: CpuTopology,
+}
+
+impl CpuConfig {
+    pub fn fixup(&mut self) -> Result<()> {
+        if self.topology.sockets == 0 {
+            self.topology.sockets = 1;
+        }
+        let vcpus_per_core = 1 + self.topology.smt as u16;
+        if self.topology.cores == 0 {
+            self.topology.cores = self.count / self.topology.sockets as u16 / vcpus_per_core;
+        }
+        let vcpus_per_socket = self.topology.cores * vcpus_per_core;
+        let count = self.topology.sockets as u16 * vcpus_per_socket;
+        if count != self.count {
+            return error::InvalidCpuTopology.fail();
+        }
+        Ok(())
+    }
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -137,6 +183,10 @@ impl BoardConfig {
     pub fn pcie_mmio_64_start(&self) -> u64 {
         (self.mem.size.saturating_sub(RAM_32_SIZE) + MEM_64_START).next_power_of_two()
     }
+
+    pub fn config_fixup(&mut self) -> Result<()> {
+        self.cpu.fixup()
+    }
 }
 
 type VcpuGuard<'a> = RwLockReadGuard<'a, Vec<(JoinHandle<Result<()>>, Sender<()>)>>;
@@ -457,3 +507,7 @@ where
         Ok(pages)
     }
 }
+
+#[cfg(test)]
+#[path = "board_test.rs"]
+mod tests;

alioth/src/board/board_aarch64.rs

@@ -24,7 +24,7 @@ use crate::arch::layout::{
     RAM_32_SIZE, RAM_32_START,
 };
 use crate::arch::reg::MpidrEl1;
-use crate::board::{Board, BoardConfig, PCIE_MMIO_64_SIZE, Result, VcpuGuard};
+use crate::board::{Board, BoardConfig, CpuTopology, PCIE_MMIO_64_SIZE, Result, VcpuGuard};
 use crate::firmware::dt::{DeviceTree, Node, PropVal};
 use crate::hv::{GicV2, GicV2m, GicV3, Hypervisor, Its, Vcpu, Vm};
 use crate::loader::{Executable, InitState, Payload};
@@ -91,22 +91,59 @@ impl<V: Vm> ArchBoard<V> {
     }
 }
 
-fn encode_mpidr(index: u16) -> MpidrEl1 {
+fn encode_mpidr(topology: &CpuTopology, index: u16) -> MpidrEl1 {
+    let (thread_id, core_id, socket_id) = topology.encode(index);
     let mut mpidr = MpidrEl1(0);
-    let index = index as u64;
-    mpidr.set_aff0(index & 0xf);
-    mpidr.set_aff1(index >> 4);
-    mpidr.set_aff2(index >> 12);
-    mpidr.set_aff3(index >> 20);
+    mpidr.set_aff0(thread_id);
+    mpidr.set_aff1(core_id as u8);
+    mpidr.set_aff2(socket_id);
     mpidr
 }
 
+fn dt_cpu_node(topology: &CpuTopology, socket: u8, core: u16) -> Node {
+    let mut mpidr = MpidrEl1(0);
+    mpidr.set_aff1(core as u8);
+    mpidr.set_aff2(socket);
+    if topology.smt {
+        Node {
+            props: HashMap::new(),
+            nodes: vec![
+                (
+                    "thread0".to_owned(),
+                    Node {
+                        props: HashMap::from([(
+                            "cpu",
+                            PropVal::PHandle(PHANDLE_CPU | mpidr.0 as u32),
+                        )]),
+                        nodes: Vec::new(),
+                    },
+                ),
+                (
+                    "thread1".to_owned(),
+                    Node {
+                        props: HashMap::from([(
+                            "cpu",
+                            PropVal::PHandle(PHANDLE_CPU | mpidr.0 as u32 | 1),
+                        )]),
+                        nodes: Vec::new(),
+                    },
+                ),
+            ],
+        }
+    } else {
+        Node {
+            nodes: Vec::new(),
+            props: HashMap::from([("cpu", PropVal::PHandle(PHANDLE_CPU | mpidr.0 as u32))]),
+        }
+    }
+}
+
 impl<V> Board<V>
 where
     V: Vm,
 {
     pub fn encode_cpu_identity(&self, index: u16) -> u64 {
-        encode_mpidr(index).0
+        encode_mpidr(&self.config.cpu.topology, index).0
     }
 
     pub fn setup_firmware(&self, _: &Path, _: &Payload) -> Result<InitState> {
@@ -233,42 +270,44 @@ where
                             ("compatible", PropVal::Str("arm,arm-v8")),
                             ("enable-method", PropVal::Str("psci")),
                             ("reg", PropVal::U64(mpidr)),
-                            ("phandle", PropVal::PHandle(PHANDLE_CPU | index as u32)),
+                            ("phandle", PropVal::PHandle(PHANDLE_CPU | mpidr as u32)),
                         ]),
                         nodes: Vec::new(),
                     },
                 )
             })
             .collect();
-        let cores = (0..(self.config.cpu.count))
-            .map(|index| {
-                (
-                    format!("core{index}"),
-                    Node {
-                        props: HashMap::from([(
-                            "cpu",
-                            PropVal::PHandle(PHANDLE_CPU | index as u32),
-                        )]),
-                        nodes: Vec::new(),
-                    },
-                )
-            })
-            .collect();
+
         let cpu_map = Node {
             props: HashMap::new(),
-            nodes: vec![(
-                "socket0".to_owned(),
-                Node {
-                    props: HashMap::new(),
-                    nodes: vec![(
-                        "cluster0".to_owned(),
+            nodes: (0..self.config.cpu.topology.sockets)
+                .map(|socket| {
+                    (
+                        format!("socket{socket}",),
                         Node {
                             props: HashMap::new(),
-                            nodes: cores,
+                            nodes: vec![(
+                                "cluster0".to_owned(),
+                                Node {
+                                    props: HashMap::new(),
+                                    nodes: (0..self.config.cpu.topology.cores)
+                                        .map(|core| {
+                                            (
+                                                format!("core{core}"),
+                                                dt_cpu_node(
+                                                    &self.config.cpu.topology,
+                                                    socket,
+                                                    core,
+                                                ),
+                                            )
+                                        })
+                                        .collect(),
+                                },
+                            )],
                         },
-                    )],
-                },
-            )],
+                    )
+                })
+                .collect(),
         };
         cpu_nodes.push(("cpu-map".to_owned(), cpu_map));
         let cpus = Node {

alioth/src/board/board_aarch64_test.rs

@@ -15,12 +15,13 @@
 use rstest::rstest;
 
 use crate::arch::reg::MpidrEl1;
+use crate::board::CpuTopology;
 use crate::board::aarch64::encode_mpidr;
 
 #[rstest]
-#[case(1, 1)]
-#[case(8, 8)]
-#[case(23, (1 << 8) | 7)]
-fn test_encode_mpidr(#[case] index: u16, #[case] mpidr: u64) {
-    assert_eq!(encode_mpidr(index), MpidrEl1(mpidr));
+#[case(CpuTopology{smt: false, cores: 1, sockets: 1}, 1, 1)]
+#[case(CpuTopology{smt: true, cores: 8, sockets: 1}, 8, 1)]
+#[case(CpuTopology{smt: true, cores: 8, sockets: 4}, 45, (1 << 16) | (5 << 8) | 1)]
+fn test_encode_mpidr(#[case] topology: CpuTopology, #[case] index: u16, #[case] mpidr: u64) {
+    assert_eq!(encode_mpidr(&topology, index), MpidrEl1(mpidr));
 }

alioth/src/board/board_test.rs

@@ -0,0 +1,47 @@
+// Copyright 2025 Google LLC
+//
+// 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
+//
+//     https://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.
+
+use assert_matches::assert_matches;
+
+use crate::board::{CpuConfig, CpuTopology, Error};
+
+#[test]
+fn test_cpu_topology_fixup() {
+    let mut empty = CpuConfig {
+        count: 2,
+        topology: CpuTopology::default(),
+    };
+    empty.fixup().unwrap();
+    assert_matches!(
+        empty,
+        CpuConfig {
+            count: 2,
+            topology: CpuTopology {
+                smt: false,
+                cores: 2,
+                sockets: 1
+            }
+        }
+    );
+
+    let mut invalid = CpuConfig {
+        count: 2,
+        topology: CpuTopology {
+            smt: true,
+            cores: 2,
+            sockets: 1,
+        },
+    };
+    assert_matches!(invalid.fixup(), Err(Error::InvalidCpuTopology { .. }))
+}