From 7eab5901adf733932d0e856b9cd5595e220e4e20 Mon Sep 17 00:00:00 2001
From: Philipp Schuster <philipp.schuster@cyberus-technology.de>
Date: Thu, 9 Apr 2026 22:24:50 +0200
Subject: [PATCH] vmm: improve misc documentation

This improves the documentation at various places.

On-behalf-of: SAP philipp.schuster@sap.com
Signed-off-by: Philipp Schuster <philipp.schuster@cyberus-technology.de>
---
 vm-device/src/bus.rs |  3 +++
 vmm/src/cpu.rs       | 17 ++++++++++++++---
 2 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/vm-device/src/bus.rs b/vm-device/src/bus.rs
index 2897ac303..eacca2498 100644
--- a/vm-device/src/bus.rs
+++ b/vm-device/src/bus.rs
@@ -147,6 +147,9 @@ impl Bus {
         None
     }
 
+    /// Inserts a bus device into the bus.
+    ///
+    /// The bus will only hold a weak reference to the object.
     #[allow(clippy::needless_pass_by_value)]
     pub fn insert(&self, device: Arc<dyn BusDeviceSync>, base: u64, len: u64) -> Result<()> {
         if len == 0 {
diff --git a/vmm/src/cpu.rs b/vmm/src/cpu.rs
index eb892552b..1450e0a8e 100644
--- a/vmm/src/cpu.rs
+++ b/vmm/src/cpu.rs
@@ -729,13 +729,17 @@ impl TryFrom<i32> for CoreSchedulingLeader {
     }
 }
 
+/// Management structure for a vCPU (thread).
 #[derive(Default)]
 struct VcpuState {
     inserting: bool,
     removing: bool,
     pending_removal: Arc<AtomicBool>,
+    /// Handle to the vCPU thread.
     handle: Option<thread::JoinHandle<()>>,
+    /// Instructs the thread to exit the run-vCPU loop.
     kill: Arc<AtomicBool>,
+    /// Used to ACK interruption from the run vCPU loop to the CPU Manager.
     vcpu_run_interrupted: Arc<AtomicBool>,
     /// Used to ACK state changes from the run vCPU loop to the CPU Manager.
     paused: Arc<AtomicBool>,
@@ -750,6 +754,13 @@ impl VcpuState {
     ///
     /// Please call [`Self::wait_until_signal_acknowledged`] afterward to block
     /// until the vCPU thread has acknowledged the signal.
+    ///
+    /// If the thread is in KVM_RUN (or MSHV_RUN_VP or equivalent), this kicks
+    /// the thread out of kernel space. If the thread is in user-space, the
+    /// thread will just handle the event eventually. If the thread is in
+    /// user-space but about to enter kernel-space, the user-space signal
+    /// handler will make sure that the next kernel entry of the given
+    /// vCPU thread immediately exits to handle the event in user-space.
     fn signal_thread(&self) {
         if let Some(handle) = self.handle.as_ref() {
             // SAFETY: FFI call with correct arguments
@@ -1532,10 +1543,10 @@ impl CpuManager {
         }
     }
 
-    /// Signal to the spawned threads (vCPUs and console signal handler).
+    /// Signals all vCPU threads and waits for them to ACK the interruption.
     ///
-    /// For the vCPU threads this will interrupt the KVM_RUN ioctl() allowing
-    /// the loop to check the shared state booleans.
+    /// Calls [`VcpuState::signal_thread`] and
+    /// [`VcpuState::wait_until_signal_acknowledged`] for each vCPU.
     fn signal_vcpus(&mut self) -> Result<()> {
         // Holding the lock for the whole operation is correct:
         let vcpu_states = self.vcpu_states.lock().unwrap();