Merge pull request #79 from ryanbreen/feature/cow-fork

feat(fork): Copy-on-Write page sharing with comprehensive test suite

Author: ryanbreen

kernel/src/interrupts.rs

@@ -723,6 +723,26 @@ fn kernel_main_continue() -> ! {
         log::info!("=== SIGNAL TEST: fork pending signal non-inheritance ===");
         test_exec::test_fork_pending_signal();
 
+        // Test CoW signal delivery (deadlock fix)
+        log::info!("=== COW TEST: signal delivery on CoW-shared stack ===");
+        test_exec::test_cow_signal();
+
+        // Test CoW cleanup on process exit
+        log::info!("=== COW TEST: cleanup on process exit ===");
+        test_exec::test_cow_cleanup();
+
+        // Test CoW sole owner optimization
+        log::info!("=== COW TEST: sole owner optimization ===");
+        test_exec::test_cow_sole_owner();
+
+        // Test CoW at scale with many pages
+        log::info!("=== COW TEST: stress test with many pages ===");
+        test_exec::test_cow_stress();
+
+        // Test CoW read-only page sharing (code sections)
+        log::info!("=== COW TEST: read-only page sharing (code sections) ===");
+        test_exec::test_cow_readonly();
+
         // Test argv support in exec syscall
         log::info!("=== EXEC TEST: argv support ===");
         test_exec::test_argv();

kernel/src/main.rs

@@ -1,5 +1,6 @@
+use alloc::vec::Vec;
 use bootloader_api::info::{MemoryRegionKind, MemoryRegions};
-use core::sync::atomic::{AtomicUsize, Ordering};
+use core::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
 use spin::Mutex;
 use x86_64::structures::paging::{FrameAllocator, PhysFrame, Size4KiB};
 use x86_64::PhysAddr;
@@ -31,6 +32,50 @@ struct MemoryInfo {
 static MEMORY_INFO: Mutex<Option<MemoryInfo>> = Mutex::new(None);
 static NEXT_FREE_FRAME: AtomicUsize = AtomicUsize::new(0);
 
+/// Free list for deallocated frames
+/// When frames are deallocated (e.g., after CoW copy reduces refcount to 0),
+/// they are added to this list for reuse
+static FREE_FRAMES: Mutex<Vec<PhysFrame>> = Mutex::new(Vec::new());
+
+/// Test-only flag to simulate OOM conditions
+///
+/// When set to true, allocate_frame() will return None to simulate out-of-memory.
+/// This is used to test that CoW fault handling gracefully terminates processes
+/// when memory allocation fails.
+///
+/// # Safety
+/// Only enable this flag briefly during testing. The flag affects ALL frame
+/// allocations, so enabling it for too long will crash the kernel.
+#[cfg(feature = "testing")]
+static SIMULATE_OOM: AtomicBool = AtomicBool::new(false);
+
+/// Enable OOM simulation for testing
+///
+/// After calling this, all frame allocations will return None until
+/// `disable_oom_simulation()` is called.
+///
+/// # Warning
+/// Only use this for brief tests! Extended OOM simulation will crash the kernel.
+#[cfg(feature = "testing")]
+pub fn enable_oom_simulation() {
+    log::warn!("OOM simulation ENABLED - all frame allocations will fail");
+    SIMULATE_OOM.store(true, Ordering::SeqCst);
+}
+
+/// Disable OOM simulation
+#[cfg(feature = "testing")]
+pub fn disable_oom_simulation() {
+    SIMULATE_OOM.store(false, Ordering::SeqCst);
+    log::info!("OOM simulation disabled - frame allocations restored");
+}
+
+/// Check if OOM simulation is currently active
+#[cfg(feature = "testing")]
+#[allow(dead_code)] // May be useful for future diagnostic output
+pub fn is_oom_simulation_active() -> bool {
+    SIMULATE_OOM.load(Ordering::SeqCst)
+}
+
 /// A simple frame allocator that returns usable frames from the bootloader's memory map
 pub struct BootInfoFrameAllocator;
 
@@ -185,17 +230,79 @@ pub fn init(memory_regions: &'static MemoryRegions) {
 }
 
 /// Allocate a physical frame
+///
+/// First checks the free list for previously deallocated frames,
+/// then falls back to sequential allocation from the memory map.
+///
+/// # OOM Behavior
+///
+/// When memory is exhausted (or OOM simulation is active in test builds),
+/// this function returns `None`. Callers must handle this gracefully:
+///
+/// - **CoW fault handler**: Returns `false`, causing the page fault handler
+///   to terminate the process with SIGSEGV (exit code -11). This is the
+///   correct POSIX behavior for processes that cannot allocate memory
+///   during page faults.
+///
+/// - **Other kernel code**: Should propagate the error or use fallback paths.
 pub fn allocate_frame() -> Option<PhysFrame> {
+    // Test-only: simulate OOM if flag is set
+    #[cfg(feature = "testing")]
+    if SIMULATE_OOM.load(Ordering::SeqCst) {
+        log::trace!("Frame allocator: OOM simulation active, returning None");
+        return None;
+    }
+
+    // First, try to reuse a frame from the free list
+    {
+        if let Some(mut free_list) = FREE_FRAMES.try_lock() {
+            if let Some(frame) = free_list.pop() {
+                log::trace!(
+                    "Frame allocator: Reused frame {:#x} from free list ({} remaining)",
+                    frame.start_address().as_u64(),
+                    free_list.len()
+                );
+                return Some(frame);
+            }
+        }
+        // If we couldn't get the lock, fall through to sequential allocation
+        // This avoids deadlock if called from interrupt context
+    }
+
+    // Fall back to sequential allocation from memory map
     let mut allocator = BootInfoFrameAllocator::new();
     allocator.allocate_frame()
 }
 
-/// Deallocate a physical frame (currently a no-op)
-/// TODO: Implement proper frame deallocation
-#[allow(dead_code)]
-pub fn deallocate_frame(_frame: PhysFrame) {
-    // For now, we don't reclaim frames
-    // A proper implementation would add the frame back to a free list
+/// Deallocate a physical frame, returning it to the free pool
+///
+/// The frame will be available for reuse by future allocations.
+/// This is called when a CoW page's reference count drops to zero.
+pub fn deallocate_frame(frame: PhysFrame) {
+    // Don't deallocate frames below the low memory floor
+    if frame.start_address().as_u64() < LOW_MEMORY_FLOOR {
+        log::warn!(
+            "Refusing to deallocate frame {:#x} below low memory floor",
+            frame.start_address().as_u64()
+        );
+        return;
+    }
+
+    if let Some(mut free_list) = FREE_FRAMES.try_lock() {
+        log::trace!(
+            "Frame allocator: Deallocated frame {:#x} (free list size: {})",
+            frame.start_address().as_u64(),
+            free_list.len() + 1
+        );
+        free_list.push(frame);
+    } else {
+        // If we can't get the lock (e.g., called from interrupt context),
+        // we lose this frame. This is a memory leak but prevents deadlock.
+        log::warn!(
+            "Frame allocator: Could not deallocate frame {:#x} - lock contention",
+            frame.start_address().as_u64()
+        );
+    }
 }
 
 /// A wrapper that allows using the global frame allocator with the mapper

kernel/src/memory/frame_allocator.rs

@@ -0,0 +1,167 @@
+//! Frame metadata for Copy-on-Write reference counting
+//!
+//! Each physical frame that can be shared needs metadata tracking:
+//! - Reference count (how many page tables point to this frame)
+//!
+//! Design decisions:
+//! - Uses BTreeMap for sparse storage (only track shared frames)
+//! - Untracked frames are assumed to have refcount=1 (private)
+//! - Single global lock (acceptable for initial implementation)
+
+use alloc::collections::BTreeMap;
+use core::sync::atomic::{AtomicU32, Ordering};
+use spin::Mutex;
+use x86_64::structures::paging::PhysFrame;
+
+/// Global frame metadata storage
+/// Uses BTreeMap for sparse storage - only frames that need tracking are stored
+static FRAME_METADATA: Mutex<BTreeMap<u64, FrameMetadata>> = Mutex::new(BTreeMap::new());
+
+/// Metadata for a single physical frame
+#[derive(Debug)]
+struct FrameMetadata {
+    /// Number of page tables referencing this frame
+    /// 0 = frame is free (should be removed from map)
+    /// 1 = frame is private (can be written directly)
+    /// >1 = frame is shared (CoW semantics apply)
+    refcount: AtomicU32,
+}
+
+impl FrameMetadata {
+    fn new(initial_count: u32) -> Self {
+        Self {
+            refcount: AtomicU32::new(initial_count),
+        }
+    }
+}
+
+/// Increment reference count for a frame
+/// Called when fork() shares a page between parent and child
+pub fn frame_incref(frame: PhysFrame) {
+    let addr = frame.start_address().as_u64();
+    let mut metadata = FRAME_METADATA.lock();
+
+    if let Some(meta) = metadata.get(&addr) {
+        meta.refcount.fetch_add(1, Ordering::SeqCst);
+    } else {
+        // First time tracking this frame - it's being shared
+        // When we start tracking, the frame is being shared between 2 processes
+        let meta = FrameMetadata::new(2);
+        metadata.insert(addr, meta);
+    }
+}
+
+/// Decrement reference count for a frame
+/// Returns true if frame can be freed (refcount reached 0)
+pub fn frame_decref(frame: PhysFrame) -> bool {
+    let addr = frame.start_address().as_u64();
+    let mut metadata = FRAME_METADATA.lock();
+
+    if let Some(meta) = metadata.get(&addr) {
+        let old_count = meta.refcount.fetch_sub(1, Ordering::SeqCst);
+        if old_count == 1 {
+            // Was 1, now 0 - remove from tracking and allow free
+            metadata.remove(&addr);
+            return true;
+        } else if old_count == 0 {
+            // This shouldn't happen - underflow protection
+            log::error!(
+                "frame_decref: underflow for frame {:#x}, restoring to 0",
+                addr
+            );
+            meta.refcount.store(0, Ordering::SeqCst);
+            metadata.remove(&addr);
+            return false;
+        }
+        // old_count > 1, still shared
+        false
+    } else {
+        // Frame wasn't tracked - this is the sole owner
+        // Return true to indicate it can be freed
+        true
+    }
+}
+
+/// Get current reference count for a frame
+/// Returns 1 if frame is not tracked (assumed private)
+pub fn frame_refcount(frame: PhysFrame) -> u32 {
+    let addr = frame.start_address().as_u64();
+    let metadata = FRAME_METADATA.lock();
+
+    metadata
+        .get(&addr)
+        .map(|m| m.refcount.load(Ordering::SeqCst))
+        .unwrap_or(1) // Untracked frames are private
+}
+
+/// Check if a frame is shared (refcount > 1)
+pub fn frame_is_shared(frame: PhysFrame) -> bool {
+    frame_refcount(frame) > 1
+}
+
+/// Get statistics about frame metadata tracking
+/// Returns (tracked_frames, total_refcount)
+#[allow(dead_code)] // Diagnostic API for future CoW debugging
+pub fn frame_metadata_stats() -> (usize, u64) {
+    let metadata = FRAME_METADATA.lock();
+    let tracked = metadata.len();
+    let total_refs: u64 = metadata
+        .values()
+        .map(|m| m.refcount.load(Ordering::Relaxed) as u64)
+        .sum();
+    (tracked, total_refs)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use x86_64::PhysAddr;
+
+    fn test_frame(addr: u64) -> PhysFrame {
+        PhysFrame::containing_address(PhysAddr::new(addr))
+    }
+
+    #[test_case]
+    fn test_untracked_frame_is_private() {
+        let frame = test_frame(0x1000_0000);
+        assert_eq!(frame_refcount(frame), 1);
+        assert!(!frame_is_shared(frame));
+    }
+
+    #[test_case]
+    fn test_incref_creates_shared() {
+        let frame = test_frame(0x2000_0000);
+        frame_incref(frame);
+        assert_eq!(frame_refcount(frame), 2);
+        assert!(frame_is_shared(frame));
+
+        // Cleanup
+        frame_decref(frame);
+        frame_decref(frame);
+    }
+
+    #[test_case]
+    fn test_multiple_incref() {
+        let frame = test_frame(0x3000_0000);
+        frame_incref(frame); // Now 2
+        frame_incref(frame); // Now 3
+        frame_incref(frame); // Now 4
+        assert_eq!(frame_refcount(frame), 4);
+
+        // Cleanup
+        while frame_refcount(frame) > 1 {
+            frame_decref(frame);
+        }
+        frame_decref(frame);
+    }
+
+    #[test_case]
+    fn test_decref_to_zero() {
+        let frame = test_frame(0x4000_0000);
+        frame_incref(frame); // Now 2
+
+        assert!(!frame_decref(frame)); // Now 1, not freeable
+        assert!(frame_decref(frame)); // Now 0, freeable
+        assert_eq!(frame_refcount(frame), 1); // Back to untracked
+    }
+}

kernel/src/memory/frame_metadata.rs

@@ -1,4 +1,5 @@
 pub mod frame_allocator;
+pub mod frame_metadata;
 pub mod heap;
 pub mod kernel_page_table;
 pub mod kernel_stack;