RFE: Skeleton for DMA layer

openhcl/underhill_core/src/dma_client.rs

@@ -0,0 +1,89 @@
+use std::sync::{Arc, Weak};
+use crate::dma_manager::GlobalDmaManager;
+use user_driver::dma;
+
+// DMA Client structure, representing a specific client instance
+pub struct DmaClient {
+    manager: Weak<GlobalDmaManager>,
+}
+
+impl DmaClient {
+    pub fn new(manager: Weak<GlobalDmaManager>) -> Self {
+        Self { manager }
+    }
+
+    fn pin_memory(&self, range: &MemoryRange) -> Result<usize, DmaError> {
+        let manager = self.manager.upgrade().ok_or(DmaError::InitializationFailed)?;
+        let threshold = manager.get_client_threshold(self).ok_or(DmaError::InitializationFailed)?;
+
+        if range.size <= threshold && manager.is_pinned(range) {
+            Ok(range.start)
+        } else {
+            Err(DmaError::PinFailed)
+        }
+    }
+
+    pub fn map_dma_ranges(
+        &self,
+        ranges: &[MemoryRange],
+    ) -> Result<DmaTransactionHandler, DmaError> {
+        let manager = self.manager.upgrade().ok_or(DmaError::InitializationFailed)?;
+        let mut dma_transactions = Vec::new();
+
+        let threshold = manager.get_client_threshold(self).ok_or(DmaError::InitializationFailed)?;
+
+        for range in ranges {
+            let (dma_addr, is_pinned, is_bounce_buffer) = if range.size <= threshold {
+                match self.pin_memory(range) {
+                    Ok(pinned_addr) => (pinned_addr, true, false),
+                    Err(_) => {
+                        let bounce_addr = manager.allocate_bounce_buffer(range.size)?;
+                        (bounce_addr, false, true)
+                    }
+                }
+            } else {
+                let bounce_addr = manager.allocate_bounce_buffer(range.size)?;
+                (bounce_addr, false, true)
+            };
+
+            dma_transactions.push(DmaTransaction {
+                original_addr: range.start,
+                dma_addr,
+                size: range.size,
+                is_pinned,
+                is_bounce_buffer,
+                is_physical: !is_bounce_buffer,
+                is_prepinned: manager.is_pinned(range),
+            });
+        }
+
+        Ok(DmaTransactionHandler {
+            transactions: dma_transactions,
+        })
+    }
+
+    pub fn unmap_dma_ranges(&self, dma_transactions: &[DmaTransaction]) -> Result<(), DmaError> {
+        let manager = self.manager.upgrade().ok_or(DmaError::InitializationFailed)?;
+
+        for transaction in dma_transactions {
+            if transaction.is_bounce_buffer {
+                // Code to release bounce buffer
+            } else if transaction.is_pinned && !transaction.is_prepinned {
+                // Code to unpin memory
+            }
+        }
+        Ok(())
+    }
+}
+
+
+// Implementation of the DMA interface for `DmaClient`
+impl DmaInterface for DmaClient {
+    fn map_dma_ranges(&self, ranges: &[MemoryRange]) -> Result<DmaTransactionHandler, DmaError> {
+        self.map_dma_ranges(ranges)
+    }
+
+    fn unmap_dma_ranges(&self, dma_transactions: &[DmaTransaction]) -> Result<(), DmaError> {
+        self.unmap_dma_ranges(dma_transactions)
+    }
+}

openhcl/underhill_core/src/dma_manager.rs

@@ -0,0 +1,85 @@
+use std::sync::{Arc, Mutex, Weak};
+use memory_range::MemoryRange;
+use once_cell::sync::OnceCell;
+
+pub use dma_client::{DmaClient, DmaInterface, DmaTransaction, DmaTransactionHandler};
+
+pub enum DmaError {
+    InitializationFailed,
+    MapFailed,
+    UnmapFailed,
+    PinFailed,
+    BounceBufferFailed,
+}
+
+static GLOBAL_DMA_MANAGER: OnceCell<Arc<GlobalDmaManager>> = OnceCell::new();
+
+/// Global DMA Manager to handle resources and manage clients
+pub struct GlobalDmaManager {
+    physical_ranges: Vec<MemoryRange>,
+    bounce_buffers: Vec<MemoryRange>,
+    clients: Mutex<Vec<Weak<DmaClient>>>,
+    client_thresholds: Mutex<Vec<(Weak<DmaClient>, usize)>>,
+}
+
+impl GlobalDmaManager {
+    /// Initializes the global DMA manager with physical ranges and bounce buffers
+    pub fn initialize(
+        physical_ranges: Vec<MemoryRange>,
+        bounce_buffers: Vec<MemoryRange>,
+    ) -> Result<(), DmaError> {
+        let manager = Arc::new(Self {
+            physical_ranges,
+            bounce_buffers,
+            clients: Mutex::new(Vec::new()),
+            client_thresholds: Mutex::new(Vec::new()),
+        });
+
+        GLOBAL_DMA_MANAGER.set(manager).map_err(|_| DmaError::InitializationFailed)
+    }
+
+    /// Accesses the singleton instance of the global manager
+    pub fn get_instance() -> Arc<GlobalDmaManager> {
+        GLOBAL_DMA_MANAGER
+            .get()
+            .expect("GlobalDmaManager has not been initialized")
+            .clone()
+    }
+
+    /// Creates a new `DmaClient` and registers it with the global manager, along with its threshold
+    pub fn create_client(&self, pinning_threshold: usize) -> Arc<DmaClient> {
+        let client = Arc::new(DmaClient::new(Arc::downgrade(&self.get_instance())));
+        self.register_client(&client, pinning_threshold);
+        client
+    }
+
+    /// Adds a new client to the list and stores its pinning threshold
+    fn register_client(&self, client: &Arc<DmaClient>, threshold: usize) {
+        let mut clients = self.clients.lock().unwrap();
+        clients.push(Arc::downgrade(client));
+
+        let mut thresholds = self.client_thresholds.lock().unwrap();
+        thresholds.push((Arc::downgrade(client), threshold));
+    }
+
+    /// Retrieves the pinning threshold for a given client
+    pub fn get_client_threshold(&self, client: &Arc<DmaClient>) -> Option<usize> {
+        let thresholds = self.client_thresholds.lock().unwrap();
+        thresholds.iter().find_map(|(weak_client, threshold)| {
+            weak_client
+                .upgrade()
+                .filter(|c| Arc::ptr_eq(c, client))
+                .map(|_| *threshold)
+        })
+    }
+
+    /// Checks if the given memory range is already pinned
+    pub fn is_pinned(&self, range: &MemoryRange) -> bool {
+        false // Placeholder
+    }
+
+    /// Allocates a bounce buffer if available, otherwise returns an error
+    pub fn allocate_bounce_buffer(&self, size: usize) -> Result<usize, DmaError> {
+        Err(DmaError::BounceBufferFailed) // Placeholder
+    }
+}

openhcl/underhill_core/src/lib.rs

@@ -25,6 +25,8 @@ mod vp;
 mod vpci;
 mod worker;
 mod wrapped_partition;
+mod dma_manager;
+mod dma_client;
 
 // `pub` so that the missing_docs warning fires for options without
 // documentation.

vm/devices/user_driver/src/dma.rs

@@ -0,0 +1,31 @@
+
+#[derive(Debug)]
+pub enum DmaError {
+    InitializationFailed,
+    MapFailed,
+    UnmapFailed,
+    PinFailed,
+    BounceBufferFailed,
+}
+
+// Structure encapsulating the result of a DMA mapping operation
+pub struct DmaTransactionHandler {
+    pub transactions: Vec<DmaTransaction>,
+}
+
+// Structure representing a DMA transaction with address and metadata
+pub struct DmaTransaction {
+    pub original_addr: usize,
+    pub dma_addr: usize,
+    pub size: usize,
+    pub is_pinned: bool,
+    pub is_bounce_buffer: bool,
+    pub is_physical: bool,
+    pub is_prepinned: bool,
+}
+
+// Trait for the DMA interface
+pub trait DmaInterface {
+    fn map_dma_ranges(&self, ranges: &[MemoryRange]) -> Result<DmaTransactionHandler, DmaError>;
+    fn unmap_dma_ranges(&self, dma_transactions: &[DmaTransaction]) -> Result<(), DmaError>;
+}

vm/devices/user_driver/src/lib.rs

@@ -16,6 +16,7 @@ pub mod interrupt;
 pub mod lockmem;
 pub mod memory;
 pub mod vfio;
+pub mod dma;
 
 pub type DmaAllocator<T> = <T as DeviceBacking>::DmaAllocator;