More build

aethelos-source/heartwood/src/attunement/idt_handlers.rs

···
 }
 
 extern "C" fn keyboard_inner() {
-    // Will be connected to keyboard driver
-    // For now, just read and discard the scancode
-    unsafe {
-        let scancode: u8;
-        asm!("in al, 0x60", out("al") scancode, options(nostack, preserves_flags));
-        // TODO: Send to keyboard driver via Nexus
-    }
+    // Handle keyboard interrupt via the keyboard driver
+    crate::attunement::keyboard::on_interrupt();
 }
 
 // Stub handlers for other hardware interrupts

aethelos-source/heartwood/src/attunement/keyboard.rs

···
+//! # PS/2 Keyboard Driver
+//!
+//! The voice of the user - how humans commune with AethelOS.
+//! Each keystroke is a word in the conversation between human and machine.
+//!
+//! ## Philosophy
+//! Input is not commands to be obeyed, but intentions to be understood.
+//! We listen to the keyboard not as servants awaiting orders,
+//! but as partners engaged in dialogue.
+//!
+//! ## Technical Details
+//! The PS/2 keyboard controller uses IRQ 1 (interrupt 33 after remapping).
+//! Scancodes arrive as single or multi-byte sequences via port 0x60.
+//! We translate scan codes (Set 1) into meaningful key events.
+
+use core::arch::asm;
+use lazy_static::lazy_static;
+use spin::Mutex;
+
+/// PS/2 keyboard data port
+const KEYBOARD_DATA: u16 = 0x60;
+
+/// PS/2 keyboard status/command port
+const KEYBOARD_STATUS: u16 = 0x64;
+
+/// Status register flags
+const STATUS_OUTPUT_FULL: u8 = 0x01;
+
+lazy_static! {
+    /// Global keyboard state
+    pub static ref KEYBOARD: Mutex<Keyboard> = Mutex::new(Keyboard::new());
+}
+
+/// Keyboard modifier state
+#[derive(Debug, Clone, Copy, Default)]
+pub struct Modifiers {
+    pub left_shift: bool,
+    pub right_shift: bool,
+    pub left_ctrl: bool,
+    pub right_ctrl: bool,
+    pub left_alt: bool,
+    pub right_alt: bool,
+    pub caps_lock: bool,
+    pub num_lock: bool,
+    pub scroll_lock: bool,
+}
+
+impl Modifiers {
+    /// Check if any shift key is pressed
+    pub fn shift(&self) -> bool {
+        self.left_shift || self.right_shift
+    }
+
+    /// Check if any ctrl key is pressed
+    pub fn ctrl(&self) -> bool {
+        self.left_ctrl || self.right_ctrl
+    }
+
+    /// Check if any alt key is pressed
+    pub fn alt(&self) -> bool {
+        self.left_alt || self.right_alt
+    }
+}
+
+/// A keyboard event
+#[derive(Debug, Clone, Copy)]
+pub enum KeyEvent {
+    /// Key was pressed
+    Pressed(Key),
+    /// Key was released
+    Released(Key),
+}
+
+/// Represents a key on the keyboard
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Key {
+    // Letters
+    A, B, C, D, E, F, G, H, I, J, K, L, M,
+    N, O, P, Q, R, S, T, U, V, W, X, Y, Z,
+
+    // Numbers
+    Num0, Num1, Num2, Num3, Num4,
+    Num5, Num6, Num7, Num8, Num9,
+
+    // Function keys
+    F1, F2, F3, F4, F5, F6,
+    F7, F8, F9, F10, F11, F12,
+
+    // Special keys
+    Escape,
+    Backspace,
+    Tab,
+    Enter,
+    Space,
+
+    // Modifiers
+    LeftShift,
+    RightShift,
+    LeftCtrl,
+    RightCtrl,
+    LeftAlt,
+    RightAlt,
+
+    // Lock keys
+    CapsLock,
+    NumLock,
+    ScrollLock,
+
+    // Navigation
+    Insert,
+    Delete,
+    Home,
+    End,
+    PageUp,
+    PageDown,
+    ArrowUp,
+    ArrowDown,
+    ArrowLeft,
+    ArrowRight,
+
+    // Punctuation and symbols
+    Minus,        // -
+    Equal,        // =
+    LeftBracket,  // [
+    RightBracket, // ]
+    Backslash,    // \
+    Semicolon,    // ;
+    Quote,        // '
+    Grave,        // `
+    Comma,        // ,
+    Period,       // .
+    Slash,        // /
+
+    // Numpad
+    NumpadDivide,
+    NumpadMultiply,
+    NumpadMinus,
+    NumpadPlus,
+    NumpadEnter,
+    NumpadPeriod,
+    Numpad0, Numpad1, Numpad2, Numpad3, Numpad4,
+    Numpad5, Numpad6, Numpad7, Numpad8, Numpad9,
+
+    // Unknown key
+    Unknown(u8),
+}
+
+impl Key {
+    /// Convert key to ASCII character if possible
+    pub fn to_ascii(&self, modifiers: &Modifiers) -> Option<char> {
+        let shift = modifiers.shift() ^ modifiers.caps_lock;
+
+        match self {
+            // Letters
+            Key::A => Some(if shift { 'A' } else { 'a' }),
+            Key::B => Some(if shift { 'B' } else { 'b' }),
+            Key::C => Some(if shift { 'C' } else { 'c' }),
+            Key::D => Some(if shift { 'D' } else { 'd' }),
+            Key::E => Some(if shift { 'E' } else { 'e' }),
+            Key::F => Some(if shift { 'F' } else { 'f' }),
+            Key::G => Some(if shift { 'G' } else { 'g' }),
+            Key::H => Some(if shift { 'H' } else { 'h' }),
+            Key::I => Some(if shift { 'I' } else { 'i' }),
+            Key::J => Some(if shift { 'J' } else { 'j' }),
+            Key::K => Some(if shift { 'K' } else { 'k' }),
+            Key::L => Some(if shift { 'L' } else { 'l' }),
+            Key::M => Some(if shift { 'M' } else { 'm' }),
+            Key::N => Some(if shift { 'N' } else { 'n' }),
+            Key::O => Some(if shift { 'O' } else { 'o' }),
+            Key::P => Some(if shift { 'P' } else { 'p' }),
+            Key::Q => Some(if shift { 'Q' } else { 'q' }),
+            Key::R => Some(if shift { 'R' } else { 'r' }),
+            Key::S => Some(if shift { 'S' } else { 's' }),
+            Key::T => Some(if shift { 'T' } else { 't' }),
+            Key::U => Some(if shift { 'U' } else { 'u' }),
+            Key::V => Some(if shift { 'V' } else { 'v' }),
+            Key::W => Some(if shift { 'W' } else { 'w' }),
+            Key::X => Some(if shift { 'X' } else { 'x' }),
+            Key::Y => Some(if shift { 'Y' } else { 'y' }),
+            Key::Z => Some(if shift { 'Z' } else { 'z' }),
+
+            // Numbers
+            Key::Num0 => Some(if modifiers.shift() { ')' } else { '0' }),
+            Key::Num1 => Some(if modifiers.shift() { '!' } else { '1' }),
+            Key::Num2 => Some(if modifiers.shift() { '@' } else { '2' }),
+            Key::Num3 => Some(if modifiers.shift() { '#' } else { '3' }),
+            Key::Num4 => Some(if modifiers.shift() { '$' } else { '4' }),
+            Key::Num5 => Some(if modifiers.shift() { '%' } else { '5' }),
+            Key::Num6 => Some(if modifiers.shift() { '^' } else { '6' }),
+            Key::Num7 => Some(if modifiers.shift() { '&' } else { '7' }),
+            Key::Num8 => Some(if modifiers.shift() { '*' } else { '8' }),
+            Key::Num9 => Some(if modifiers.shift() { '(' } else { '9' }),
+
+            // Special keys
+            Key::Space => Some(' '),
+            Key::Enter => Some('\n'),
+            Key::Tab => Some('\t'),
+            Key::Backspace => Some('\x08'),
+
+            // Punctuation
+            Key::Minus => Some(if modifiers.shift() { '_' } else { '-' }),
+            Key::Equal => Some(if modifiers.shift() { '+' } else { '=' }),
+            Key::LeftBracket => Some(if modifiers.shift() { '{' } else { '[' }),
+            Key::RightBracket => Some(if modifiers.shift() { '}' } else { ']' }),
+            Key::Backslash => Some(if modifiers.shift() { '|' } else { '\\' }),
+            Key::Semicolon => Some(if modifiers.shift() { ':' } else { ';' }),
+            Key::Quote => Some(if modifiers.shift() { '"' } else { '\'' }),
+            Key::Grave => Some(if modifiers.shift() { '~' } else { '`' }),
+            Key::Comma => Some(if modifiers.shift() { '<' } else { ',' }),
+            Key::Period => Some(if modifiers.shift() { '>' } else { '.' }),
+            Key::Slash => Some(if modifiers.shift() { '?' } else { '/' }),
+
+            // Numpad (when numlock is on)
+            Key::Numpad0 => if modifiers.num_lock { Some('0') } else { None },
+            Key::Numpad1 => if modifiers.num_lock { Some('1') } else { None },
+            Key::Numpad2 => if modifiers.num_lock { Some('2') } else { None },
+            Key::Numpad3 => if modifiers.num_lock { Some('3') } else { None },
+            Key::Numpad4 => if modifiers.num_lock { Some('4') } else { None },
+            Key::Numpad5 => if modifiers.num_lock { Some('5') } else { None },
+            Key::Numpad6 => if modifiers.num_lock { Some('6') } else { None },
+            Key::Numpad7 => if modifiers.num_lock { Some('7') } else { None },
+            Key::Numpad8 => if modifiers.num_lock { Some('8') } else { None },
+            Key::Numpad9 => if modifiers.num_lock { Some('9') } else { None },
+            Key::NumpadPeriod => if modifiers.num_lock { Some('.') } else { None },
+            Key::NumpadDivide => Some('/'),
+            Key::NumpadMultiply => Some('*'),
+            Key::NumpadMinus => Some('-'),
+            Key::NumpadPlus => Some('+'),
+            Key::NumpadEnter => Some('\n'),
+
+            // Non-printable keys
+            _ => None,
+        }
+    }
+}
+
+/// PS/2 Keyboard state machine
+pub struct Keyboard {
+    modifiers: Modifiers,
+    extended_scancode: bool,
+}
+
+impl Keyboard {
+    /// Create a new keyboard state
+    pub const fn new() -> Self {
+        Keyboard {
+            modifiers: Modifiers {
+                left_shift: false,
+                right_shift: false,
+                left_ctrl: false,
+                right_ctrl: false,
+                left_alt: false,
+                right_alt: false,
+                caps_lock: false,
+                num_lock: false,
+                scroll_lock: false,
+            },
+            extended_scancode: false,
+        }
+    }
+
+    /// Get current modifiers
+    pub fn modifiers(&self) -> Modifiers {
+        self.modifiers
+    }
+
+    /// Process a scancode byte and return a key event
+    pub fn process_scancode(&mut self, scancode: u8) -> Option<KeyEvent> {
+        // Handle extended scancodes (0xE0 prefix)
+        if scancode == 0xE0 {
+            self.extended_scancode = true;
+            return None;
+        }
+
+        // Check if this is a key release (high bit set)
+        let released = (scancode & 0x80) != 0;
+        let code = scancode & 0x7F;
+
+        // Translate scancode to key
+        let key = if self.extended_scancode {
+            self.extended_scancode = false;
+            match code {
+                0x1D => Key::RightCtrl,
+                0x38 => Key::RightAlt,
+                0x48 => Key::ArrowUp,
+                0x50 => Key::ArrowDown,
+                0x4B => Key::ArrowLeft,
+                0x4D => Key::ArrowRight,
+                0x49 => Key::PageUp,
+                0x51 => Key::PageDown,
+                0x47 => Key::Home,
+                0x4F => Key::End,
+                0x52 => Key::Insert,
+                0x53 => Key::Delete,
+                0x35 => Key::NumpadDivide,
+                _ => Key::Unknown(scancode),
+            }
+        } else {
+            scancode_to_key(code)
+        };
+
+        // Update modifier state
+        self.update_modifiers(&key, released);
+
+        // Return the event
+        if released {
+            Some(KeyEvent::Released(key))
+        } else {
+            Some(KeyEvent::Pressed(key))
+        }
+    }
+
+    /// Update modifier key states
+    fn update_modifiers(&mut self, key: &Key, released: bool) {
+        match key {
+            Key::LeftShift => self.modifiers.left_shift = !released,
+            Key::RightShift => self.modifiers.right_shift = !released,
+            Key::LeftCtrl => self.modifiers.left_ctrl = !released,
+            Key::RightCtrl => self.modifiers.right_ctrl = !released,
+            Key::LeftAlt => self.modifiers.left_alt = !released,
+            Key::RightAlt => self.modifiers.right_alt = !released,
+
+            // Toggle lock keys on press
+            Key::CapsLock if !released => self.modifiers.caps_lock = !self.modifiers.caps_lock,
+            Key::NumLock if !released => self.modifiers.num_lock = !self.modifiers.num_lock,
+            Key::ScrollLock if !released => self.modifiers.scroll_lock = !self.modifiers.scroll_lock,
+
+            _ => {}
+        }
+    }
+}
+
+/// Translate a scancode (Set 1) to a Key
+fn scancode_to_key(code: u8) -> Key {
+    match code {
+        // Row 1
+        0x01 => Key::Escape,
+        0x3B => Key::F1,
+        0x3C => Key::F2,
+        0x3D => Key::F3,
+        0x3E => Key::F4,
+        0x3F => Key::F5,
+        0x40 => Key::F6,
+        0x41 => Key::F7,
+        0x42 => Key::F8,
+        0x43 => Key::F9,
+        0x44 => Key::F10,
+        0x57 => Key::F11,
+        0x58 => Key::F12,
+
+        // Row 2
+        0x29 => Key::Grave,
+        0x02 => Key::Num1,
+        0x03 => Key::Num2,
+        0x04 => Key::Num3,
+        0x05 => Key::Num4,
+        0x06 => Key::Num5,
+        0x07 => Key::Num6,
+        0x08 => Key::Num7,
+        0x09 => Key::Num8,
+        0x0A => Key::Num9,
+        0x0B => Key::Num0,
+        0x0C => Key::Minus,
+        0x0D => Key::Equal,
+        0x0E => Key::Backspace,
+
+        // Row 3
+        0x0F => Key::Tab,
+        0x10 => Key::Q,
+        0x11 => Key::W,
+        0x12 => Key::E,
+        0x13 => Key::R,
+        0x14 => Key::T,
+        0x15 => Key::Y,
+        0x16 => Key::U,
+        0x17 => Key::I,
+        0x18 => Key::O,
+        0x19 => Key::P,
+        0x1A => Key::LeftBracket,
+        0x1B => Key::RightBracket,
+        0x2B => Key::Backslash,
+
+        // Row 4
+        0x3A => Key::CapsLock,
+        0x1E => Key::A,
+        0x1F => Key::S,
+        0x20 => Key::D,
+        0x21 => Key::F,
+        0x22 => Key::G,
+        0x23 => Key::H,
+        0x24 => Key::J,
+        0x25 => Key::K,
+        0x26 => Key::L,
+        0x27 => Key::Semicolon,
+        0x28 => Key::Quote,
+        0x1C => Key::Enter,
+
+        // Row 5
+        0x2A => Key::LeftShift,
+        0x2C => Key::Z,
+        0x2D => Key::X,
+        0x2E => Key::C,
+        0x2F => Key::V,
+        0x30 => Key::B,
+        0x31 => Key::N,
+        0x32 => Key::M,
+        0x33 => Key::Comma,
+        0x34 => Key::Period,
+        0x35 => Key::Slash,
+        0x36 => Key::RightShift,
+
+        // Row 6
+        0x1D => Key::LeftCtrl,
+        0x38 => Key::LeftAlt,
+        0x39 => Key::Space,
+
+        // Numpad
+        0x45 => Key::NumLock,
+        0x46 => Key::ScrollLock,
+        0x47 => Key::Numpad7,
+        0x48 => Key::Numpad8,
+        0x49 => Key::Numpad9,
+        0x4A => Key::NumpadMinus,
+        0x4B => Key::Numpad4,
+        0x4C => Key::Numpad5,
+        0x4D => Key::Numpad6,
+        0x4E => Key::NumpadPlus,
+        0x4F => Key::Numpad1,
+        0x50 => Key::Numpad2,
+        0x51 => Key::Numpad3,
+        0x52 => Key::Numpad0,
+        0x53 => Key::NumpadPeriod,
+        0x37 => Key::NumpadMultiply,
+
+        // Unknown
+        _ => Key::Unknown(code),
+    }
+}
+
+/// Read a scancode from the keyboard data port
+///
+/// # Safety
+/// Reads from I/O port 0x60. Should only be called from keyboard interrupt handler.
+pub unsafe fn read_scancode() -> u8 {
+    inb(KEYBOARD_DATA)
+}
+
+/// Check if keyboard data is available
+pub unsafe fn data_available() -> bool {
+    (inb(KEYBOARD_STATUS) & STATUS_OUTPUT_FULL) != 0
+}
+
+/// Helper function to input a byte from an I/O port
+#[inline]
+unsafe fn inb(port: u16) -> u8 {
+    let value: u8;
+    asm!("in al, dx", out("al") value, in("dx") port, options(nomem, nostack, preserves_flags));
+    value
+}
+
+/// Initialize the keyboard
+pub fn init() {
+    // The PS/2 keyboard is initialized by the BIOS
+    // We just need to enable IRQ 1 and start receiving scancodes
+    unsafe {
+        super::PIC.lock().enable_irq(1);
+    }
+}
+
+/// Handle a keyboard interrupt (called from IRQ 1 handler)
+pub fn on_interrupt() {
+    unsafe {
+        if data_available() {
+            let scancode = read_scancode();
+            let mut keyboard = KEYBOARD.lock();
+
+            if let Some(event) = keyboard.process_scancode(scancode) {
+                handle_key_event(event, &keyboard.modifiers());
+            }
+        }
+    }
+}
+
+/// Handle a key event (override this for custom behavior)
+fn handle_key_event(event: KeyEvent, modifiers: &Modifiers) {
+    match event {
+        KeyEvent::Pressed(key) => {
+            if let Some(ch) = key.to_ascii(modifiers) {
+                // Echo printable characters to screen
+                if ch.is_ascii() && !ch.is_ascii_control() {
+                    crate::print!("{}", ch);
+                } else if ch == '\n' {
+                    crate::println!();
+                } else if ch == '\x08' {
+                    // Backspace - would need VGA driver support
+                    crate::print!("\x08 \x08");
+                }
+            } else {
+                // Non-ASCII key pressed
+                // Could log special keys for debugging
+            }
+        }
+        KeyEvent::Released(_) => {
+            // Usually we don't care about key releases for typing
+        }
+    }
+}

aethelos-source/heartwood/src/attunement/mod.rs

···
 
 pub mod gdt;
 pub mod idt;
+pub mod keyboard;
 pub mod pic;
 pub mod pit;
 
···
     // Initialize system timer (PIT)
     crate::println!("    ∴ Starting system heartbeat (PIT @ {} Hz)...", PIT.frequency());
     timer::init();
+
+    // Initialize keyboard
+    crate::println!("    ∴ Listening for keystrokes (PS/2)...");
+    keyboard::init();
 
     crate::println!("  ◈ Hardware attunement complete");
 }

aethelos-source/heartwood/src/loom_of_fate/context.rs

···
+//! # Thread Context
+//!
+//! The essence of a thread - its complete state at a moment in time.
+//! When we preserve context, we capture the thread's entire being:
+//! every register, every thought, every intention.
+//!
+//! ## Philosophy
+//! Context switches are not interruptions, but transitions.
+//! We preserve the current moment with reverence, knowing we will
+//! restore it faithfully when the thread's turn returns.
+
+use core::arch::asm;
+
+/// The complete state of a thread
+///
+/// This structure holds all CPU registers needed to resume execution
+/// exactly where the thread left off. The layout matches x86-64 calling
+/// conventions and interrupt frames.
+#[repr(C)]
+#[derive(Debug, Clone, Copy)]
+pub struct ThreadContext {
+    // General purpose registers (callee-saved)
+    pub r15: u64,
+    pub r14: u64,
+    pub r13: u64,
+    pub r12: u64,
+    pub rbp: u64,
+    pub rbx: u64,
+
+    // Additional general purpose registers
+    pub r11: u64,
+    pub r10: u64,
+    pub r9: u64,
+    pub r8: u64,
+    pub rax: u64,
+    pub rcx: u64,
+    pub rdx: u64,
+    pub rsi: u64,
+    pub rdi: u64,
+
+    // Special registers
+    pub rip: u64,      // Instruction pointer - where to resume
+    pub cs: u64,       // Code segment
+    pub rflags: u64,   // CPU flags
+    pub rsp: u64,      // Stack pointer
+    pub ss: u64,       // Stack segment
+}
+
+impl ThreadContext {
+    /// Create a new context for a thread starting at the given entry point
+    ///
+    /// # Arguments
+    /// * `entry_point` - The function pointer where the thread will begin
+    /// * `stack_top` - The top of the thread's stack (high address)
+    ///
+    /// # Returns
+    /// A context ready to be restored, which will begin executing at the entry point
+    pub fn new(entry_point: u64, stack_top: u64) -> Self {
+        ThreadContext {
+            // General purpose registers start at zero
+            r15: 0,
+            r14: 0,
+            r13: 0,
+            r12: 0,
+            rbp: 0,
+            rbx: 0,
+            r11: 0,
+            r10: 0,
+            r9: 0,
+            r8: 0,
+            rax: 0,
+            rcx: 0,
+            rdx: 0,
+            rsi: 0,
+            rdi: 0,
+
+            // Special registers
+            rip: entry_point,
+            cs: 0x08,  // Kernel code segment (from GDT)
+            rflags: 0x202,  // Interrupts enabled (IF flag)
+            rsp: stack_top,
+            ss: 0x10,  // Kernel data segment (from GDT)
+        }
+    }
+
+    /// Create an empty context (all zeros)
+    pub const fn empty() -> Self {
+        ThreadContext {
+            r15: 0, r14: 0, r13: 0, r12: 0,
+            rbp: 0, rbx: 0, r11: 0, r10: 0,
+            r9: 0, r8: 0, rax: 0, rcx: 0,
+            rdx: 0, rsi: 0, rdi: 0,
+            rip: 0, cs: 0, rflags: 0,
+            rsp: 0, ss: 0,
+        }
+    }
+}
+
+/// Switch from the current thread context to a new thread context
+///
+/// This is the heart of cooperative multitasking. It saves the current
+/// thread's state and restores the new thread's state in one atomic operation.
+///
+/// # Arguments
+/// * `old_context` - Where to save the current thread's state
+/// * `new_context` - The context to restore and resume
+///
+/// # Safety
+/// This function performs raw register manipulation and must only be called
+/// from the scheduler with interrupts disabled.
+#[unsafe(naked)]
+pub unsafe extern "C" fn switch_context(_old_context: *mut ThreadContext, _new_context: *const ThreadContext) {
+    core::arch::naked_asm!(
+        // Save current context
+        // rdi = old_context pointer (first argument)
+        // rsi = new_context pointer (second argument)
+
+        // Save general purpose registers
+        "mov [rdi + 0x00], r15",
+        "mov [rdi + 0x08], r14",
+        "mov [rdi + 0x10], r13",
+        "mov [rdi + 0x18], r12",
+        "mov [rdi + 0x20], rbp",
+        "mov [rdi + 0x28], rbx",
+        "mov [rdi + 0x30], r11",
+        "mov [rdi + 0x38], r10",
+        "mov [rdi + 0x40], r9",
+        "mov [rdi + 0x48], r8",
+        "mov [rdi + 0x50], rax",
+        "mov [rdi + 0x58], rcx",
+        "mov [rdi + 0x60], rdx",
+        "mov [rdi + 0x68], rsi",
+        "mov [rdi + 0x70], rdi",
+
+        // Save RIP (return address is on stack)
+        "mov rax, [rsp]",
+        "mov [rdi + 0x78], rax",
+
+        // Save CS
+        "mov ax, cs",
+        "mov [rdi + 0x80], rax",
+
+        // Save RFLAGS
+        "pushfq",
+        "pop rax",
+        "mov [rdi + 0x88], rax",
+
+        // Save RSP (before return address was pushed)
+        "lea rax, [rsp + 8]",
+        "mov [rdi + 0x90], rax",
+
+        // Save SS
+        "mov ax, ss",
+        "mov [rdi + 0x98], rax",
+
+        // Now restore new context
+        // rsi = new_context pointer
+
+        // Restore general purpose registers
+        "mov r15, [rsi + 0x00]",
+        "mov r14, [rsi + 0x08]",
+        "mov r13, [rsi + 0x10]",
+        "mov r12, [rsi + 0x18]",
+        "mov rbp, [rsi + 0x20]",
+        "mov rbx, [rsi + 0x28]",
+        "mov r11, [rsi + 0x30]",
+        "mov r10, [rsi + 0x38]",
+        "mov r9,  [rsi + 0x40]",
+        "mov r8,  [rsi + 0x48]",
+        "mov rax, [rsi + 0x50]",
+        "mov rcx, [rsi + 0x58]",
+        "mov rdx, [rsi + 0x60]",
+
+        // Restore RSP first (we'll need it)
+        "mov rsp, [rsi + 0x90]",
+
+        // Push new context's RIP onto the new stack (for ret)
+        "push qword ptr [rsi + 0x78]",
+
+        // Restore RFLAGS
+        "push qword ptr [rsi + 0x88]",
+        "popfq",
+
+        // Restore remaining registers
+        "mov rdi, [rsi + 0x70]",
+        "mov rsi, [rsi + 0x68]",
+
+        // Return to new thread's RIP
+        "ret",
+    );
+}
+
+/// Initialize a new thread's stack with the proper frame for first execution
+///
+/// This sets up the stack so that when we "restore" the context for the first time,
+/// it will cleanly jump to the thread's entry point.
+///
+/// # Arguments
+/// * `stack_top` - The top of the stack (high address)
+/// * `entry_point` - The function where the thread starts
+///
+/// # Returns
+/// The adjusted stack pointer after initialization
+#[allow(dead_code)]
+pub unsafe fn init_thread_stack(stack_top: u64, _entry_point: fn() -> !) -> u64 {
+    // The stack grows downward, so we work backward from the top
+    // When context is restored, ret will pop RIP from stack
+    // So we don't need to push anything here - the context struct handles it
+
+    stack_top
+}
+
+/// Helper wrapper for thread entry points
+///
+/// This function is called when a new thread is first scheduled.
+/// It handles any setup needed before calling the actual entry point.
+pub extern "C" fn thread_entry_wrapper(entry_point: fn() -> !) -> ! {
+    // Enable interrupts for this new thread
+    unsafe {
+        asm!("sti", options(nomem, nostack));
+    }
+
+    // Call the actual entry point
+    entry_point()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_context_creation() {
+        let ctx = ThreadContext::new(0x1000, 0x5000);
+        assert_eq!(ctx.rip, 0x1000);
+        assert_eq!(ctx.rsp, 0x5000);
+        assert_eq!(ctx.cs, 0x08);
+        assert_eq!(ctx.ss, 0x10);
+        assert_ne!(ctx.rflags & 0x200, 0); // IF flag set
+    }
+
+    #[test]
+    fn test_empty_context() {
+        let ctx = ThreadContext::empty();
+        assert_eq!(ctx.rip, 0);
+        assert_eq!(ctx.rsp, 0);
+        assert_eq!(ctx.rax, 0);
+    }
+}

aethelos-source/heartwood/src/loom_of_fate/mod.rs

···
 //! - Resource negotiation based on system-wide harmony
 //! - Parasite detection and throttling (not killing)
 
+pub mod context;
 pub mod scheduler;
+pub mod stack;
 pub mod thread;
 pub mod harmony;
 
···
     OutOfThreads,
     ThreadNotFound,
     InvalidPriority,
+    StackAllocationFailed,
 }

aethelos-source/heartwood/src/loom_of_fate/scheduler.rs

···
 //! The Scheduler - The core of the Loom of Fate
 
+use super::context::{switch_context, ThreadContext};
 use super::harmony::{HarmonyAnalyzer, HarmonyMetrics};
+use super::stack::Stack;
 use super::thread::{Thread, ThreadId, ThreadPriority, ThreadState};
 use super::LoomError;
 use alloc::collections::VecDeque;
···
 /// The harmony-based cooperative scheduler
 pub struct Scheduler {
     threads: Vec<Thread>,
+    stacks: Vec<Stack>,  // Stack storage (owned by scheduler)
     ready_queue: VecDeque<ThreadId>,
     current_thread: Option<ThreadId>,
     next_thread_id: u64,
     harmony_analyzer: HarmonyAnalyzer,
     /// Latest harmony metrics from the analyzer
     latest_metrics: HarmonyMetrics,
+    /// Total number of context switches performed
+    context_switches: u64,
 }
 
 impl Default for Scheduler {
···
     pub fn new() -> Self {
         Self {
             threads: Vec::new(),
+            stacks: Vec::new(),
             ready_queue: VecDeque::new(),
             current_thread: None,
             next_thread_id: 1,
             harmony_analyzer: HarmonyAnalyzer::new(),
             latest_metrics: HarmonyMetrics::default(),
+            context_switches: 0,
         }
     }
 
···
         let thread_id = ThreadId(self.next_thread_id);
         self.next_thread_id += 1;
 
-        let thread = Thread::new(thread_id, entry_point, priority);
+        // Allocate a stack for this thread
+        let stack = Stack::new().ok_or(LoomError::StackAllocationFailed)?;
+        let stack_bottom = stack.bottom();
+        let stack_top = stack.top();
+
+        // Create the thread with its stack
+        let thread = Thread::new(thread_id, entry_point, priority, stack_bottom, stack_top);
+
         self.threads.push(thread);
+        self.stacks.push(stack);  // Keep stack alive
         self.ready_queue.push_back(thread_id);
 
         Ok(thread_id)
     }
 
-    /// Yield the current thread
+    /// Yield the current thread and switch to the next one
+    ///
+    /// This is the heart of cooperative multitasking. The current thread
+    /// voluntarily gives up the CPU, and we select the next thread based
+    /// on harmony and priority.
+    ///
+    /// # Safety
+    /// This function performs context switching which involves raw register
+    /// manipulation. It should only be called from safe contexts where
+    /// the scheduler state is valid.
     pub fn yield_current(&mut self) {
-        if let Some(current_id) = self.current_thread {
-            if let Some(thread) = self.find_thread_mut(current_id) {
-                thread.record_yield();
-                thread.set_state(ThreadState::Resting);
-            }
-
-            self.ready_queue.push_back(current_id);
-            self.current_thread = None;
-        }
-
-        self.schedule_next();
-    }
-
-    /// Schedule the next thread to run
-    fn schedule_next(&mut self) {
         // Analyze harmony before scheduling
         let metrics = self.harmony_analyzer.analyze(&mut self.threads);
         self.latest_metrics = metrics;
···
         // Adaptive scheduling based on system harmony
         if metrics.system_harmony < 0.5 {
             // System is in disharmony - prioritize cooperative threads
-            // and deprioritize parasites more aggressively
             self.rebalance_for_harmony();
         }
 
-        // Find the next thread to run based on harmony
+        // Find the next thread to run
         let next_thread_id = self.select_next_thread();
 
-        if let Some(thread_id) = next_thread_id {
-            // Check if thread is parasitic and get soothe factor before mutable borrow
-            let (is_parasitic, soothe_factor) = self.find_thread(thread_id)
-                .map(|t| {
-                    let parasitic = self.harmony_analyzer.should_soothe(t);
-                    let factor = if parasitic {
-                        self.harmony_analyzer.soothe_factor(t)
-                    } else {
-                        1.0
-                    };
-                    (parasitic, factor)
-                })
-                .unwrap_or((false, 1.0));
+        if next_thread_id.is_none() {
+            // No threads ready - this shouldn't happen in a well-designed system
+            // but if it does, we just return (stay on current thread if any)
+            return;
+        }
+
+        let next_id = next_thread_id.unwrap();
 
-            if let Some(thread) = self.find_thread_mut(thread_id) {
-                thread.set_state(ThreadState::Weaving);
-                thread.record_time_slice();
+        // If we're switching to a different thread, perform context switch
+        if self.current_thread.is_some() && self.current_thread != Some(next_id) {
+            let current_id = self.current_thread.unwrap();
 
-                // If this thread is parasitic, soothe it based on harmony score
-                if is_parasitic {
-                    // In a real implementation, we would:
-                    // 1. Reduce time slice based on soothe_factor (lower = more throttling)
-                    // 2. Insert deliberate pauses/delays
-                    // 3. Lower its effective priority
-                    // For now, this documents the intent for future implementation
-                    let _ = soothe_factor; // Acknowledge we have the factor
-                }
+            // Update current thread state
+            if let Some(current_thread) = self.find_thread_mut(current_id) {
+                current_thread.record_yield();
+                current_thread.set_state(ThreadState::Resting);
             }
 
-            self.current_thread = Some(thread_id);
+            // Add current thread back to ready queue
+            self.ready_queue.push_back(current_id);
+
+            // Update next thread state
+            if let Some(next_thread) = self.find_thread_mut(next_id) {
+                next_thread.set_state(ThreadState::Weaving);
+                next_thread.record_time_slice();
+                next_thread.last_run_time = crate::attunement::timer::ticks();
+            }
+
+            // Perform the actual context switch
+            self.context_switches += 1;
+            self.perform_context_switch(current_id, next_id);
+
+            // After we return from context switch, we're running as the "next" thread
+            // (which may actually be this thread again after future switches)
+        } else if self.current_thread.is_none() {
+            // First thread to run - just start it (no context to save)
+            if let Some(next_thread) = self.find_thread_mut(next_id) {
+                next_thread.set_state(ThreadState::Weaving);
+                next_thread.record_time_slice();
+                next_thread.last_run_time = crate::attunement::timer::ticks();
+            }
+
+            self.current_thread = Some(next_id);
+            // Jump to the first thread (this will not return)
+            self.jump_to_thread(next_id);
         }
+
+        // Update current thread ID
+        self.current_thread = Some(next_id);
+    }
+
+    /// Perform a context switch between two threads
+    ///
+    /// # Safety
+    /// Assumes both thread IDs are valid and the threads exist
+    fn perform_context_switch(&mut self, from_id: ThreadId, to_id: ThreadId) {
+        // Get raw pointers to the contexts before borrowing
+        let from_idx = self.threads.iter().position(|t| t.id() == from_id).unwrap();
+        let to_idx = self.threads.iter().position(|t| t.id() == to_id).unwrap();
+
+        let from_ctx_ptr = &mut self.threads[from_idx].context as *mut ThreadContext;
+        let to_ctx_ptr = &self.threads[to_idx].context as *const ThreadContext;
+
+        // Perform the context switch
+        // This will save the current state to from_ctx and restore to_ctx
+        unsafe {
+            switch_context(from_ctx_ptr, to_ctx_ptr);
+        }
+
+        // When we return here, we're running as the "to" thread
+        // (or possibly some other thread that later switched back to us)
+    }
+
+    /// Jump to a thread for the first time (no context to save)
+    ///
+    /// # Safety
+    /// This function never returns - it jumps to the thread's entry point
+    fn jump_to_thread(&mut self, to_id: ThreadId) -> ! {
+        // Find the thread's context
+        let to_idx = self.threads.iter().position(|t| t.id() == to_id).unwrap();
+        let to_ctx_ptr = &self.threads[to_idx].context as *const ThreadContext;
+
+        // Create a dummy context for the "from" side (we won't use it)
+        let mut dummy_ctx = ThreadContext::empty();
+        let dummy_ctx_ptr = &mut dummy_ctx as *mut ThreadContext;
+
+        // Jump to the new thread
+        // Note: switch_context will try to save our state to dummy_ctx,
+        // but since we're never coming back, that's fine
+        unsafe {
+            switch_context(dummy_ctx_ptr, to_ctx_ptr);
+        }
+
+        // Never reached
+        unreachable!("jump_to_thread should never return");
     }
 
     /// Rebalance the ready queue when system harmony is low
···
             average_harmony: self.latest_metrics.average_harmony,
             system_harmony: self.latest_metrics.system_harmony,
             parasite_count: self.latest_metrics.parasite_count,
+            context_switches: self.context_switches,
         }
     }
 
···
     pub average_harmony: f32,
     pub system_harmony: f32,
     pub parasite_count: usize,
+    pub context_switches: u64,
 }

aethelos-source/heartwood/src/loom_of_fate/stack.rs

···
+//! # Stack Allocation
+//!
+//! Each thread needs its own stack - a space for its local thoughts.
+//! We allocate stacks from the heap, giving each thread room to breathe.
+//!
+//! ## Philosophy
+//! A thread's stack is its private sanctuary. We provide generous space
+//! (default 64KB) so threads never feel cramped or anxious.
+
+use alloc::alloc::{alloc, dealloc, Layout};
+use core::ptr::NonNull;
+
+/// Default stack size: 64 KB
+/// This is generous enough for most threads while being conservative with memory
+pub const DEFAULT_STACK_SIZE: usize = 64 * 1024;
+
+/// Minimum stack size: 4 KB (one page)
+pub const MIN_STACK_SIZE: usize = 4 * 1024;
+
+/// Maximum stack size: 1 MB
+pub const MAX_STACK_SIZE: usize = 1024 * 1024;
+
+/// A thread's stack allocation
+pub struct Stack {
+    bottom: NonNull<u8>,
+    size: usize,
+}
+
+// Safety: Stack pointers can be safely sent between threads
+// as they represent heap-allocated memory
+unsafe impl Send for Stack {}
+unsafe impl Sync for Stack {}
+
+impl Stack {
+    /// Allocate a new stack with the default size
+    pub fn new() -> Option<Self> {
+        Self::with_size(DEFAULT_STACK_SIZE)
+    }
+
+    /// Allocate a new stack with a specific size
+    ///
+    /// # Arguments
+    /// * `size` - Size in bytes (will be clamped to MIN/MAX and aligned to 16 bytes)
+    ///
+    /// # Returns
+    /// Some(Stack) if allocation succeeds, None otherwise
+    pub fn with_size(size: usize) -> Option<Self> {
+        // Clamp size to valid range and align to 16 bytes
+        let size = size.clamp(MIN_STACK_SIZE, MAX_STACK_SIZE);
+        let size = (size + 15) & !15; // Align to 16 bytes
+
+        // Create layout for allocation
+        let layout = Layout::from_size_align(size, 16).ok()?;
+
+        // Allocate the stack
+        let ptr = unsafe { alloc(layout) };
+
+        NonNull::new(ptr).map(|bottom| Stack { bottom, size })
+    }
+
+    /// Get the bottom (low address) of the stack
+    pub fn bottom(&self) -> u64 {
+        self.bottom.as_ptr() as u64
+    }
+
+    /// Get the top (high address) of the stack
+    ///
+    /// The stack grows downward, so this is bottom + size
+    pub fn top(&self) -> u64 {
+        self.bottom() + self.size as u64
+    }
+
+    /// Get the size of the stack in bytes
+    pub fn size(&self) -> usize {
+        self.size
+    }
+
+    /// Check if an address is within this stack
+    pub fn contains(&self, addr: u64) -> bool {
+        addr >= self.bottom() && addr < self.top()
+    }
+}
+
+impl Drop for Stack {
+    fn drop(&mut self) {
+        // Deallocate the stack when it's no longer needed
+        let layout = Layout::from_size_align(self.size, 16)
+            .expect("Invalid layout during stack deallocation");
+
+        unsafe {
+            dealloc(self.bottom.as_ptr(), layout);
+        }
+    }
+}
+
+/// Guard page support (for future implementation)
+///
+/// A guard page is a page marked as non-accessible that sits at the bottom
+/// of the stack. If a stack overflow occurs, accessing the guard page will
+/// trigger a page fault, allowing us to detect the overflow gracefully.
+#[allow(dead_code)]
+pub struct GuardedStack {
+    stack: Stack,
+    guard_page_addr: u64,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_stack_allocation() {
+        let stack = Stack::new().expect("Failed to allocate stack");
+        assert_eq!(stack.size(), DEFAULT_STACK_SIZE);
+        assert!(stack.top() > stack.bottom());
+        assert_eq!(stack.top() - stack.bottom(), DEFAULT_STACK_SIZE as u64);
+    }
+
+    #[test]
+    fn test_custom_size() {
+        let stack = Stack::with_size(8192).expect("Failed to allocate");
+        assert_eq!(stack.size(), 8192);
+    }
+
+    #[test]
+    fn test_size_clamping() {
+        // Too small - should clamp to MIN_STACK_SIZE
+        let stack = Stack::with_size(100).expect("Failed to allocate");
+        assert_eq!(stack.size(), MIN_STACK_SIZE);
+
+        // Too large - should clamp to MAX_STACK_SIZE
+        let stack = Stack::with_size(10 * 1024 * 1024).expect("Failed to allocate");
+        assert_eq!(stack.size(), MAX_STACK_SIZE);
+    }
+
+    #[test]
+    fn test_contains() {
+        let stack = Stack::new().expect("Failed to allocate");
+        let bottom = stack.bottom();
+        let top = stack.top();
+
+        assert!(stack.contains(bottom));
+        assert!(stack.contains(bottom + 100));
+        assert!(stack.contains(top - 1));
+        assert!(!stack.contains(top));
+        assert!(!stack.contains(bottom - 1));
+    }
+}

aethelos-source/heartwood/src/loom_of_fate/thread.rs

···
 //! Thread definitions - The Threads of Fate
 
+use super::context::ThreadContext;
+
 /// A unique identifier for a thread
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct ThreadId(pub u64);
···
     pub(crate) priority: ThreadPriority,
     pub(crate) entry_point: fn() -> !,
 
+    // CPU state (for context switching)
+    pub(crate) context: ThreadContext,
+    pub(crate) stack_bottom: u64,
+    pub(crate) stack_top: u64,
+
     // Harmony tracking
     pub(crate) resource_usage: ResourceUsage,
     pub(crate) harmony_score: f32,
···
     // Execution context
     pub(crate) time_slices_used: u64,
     pub(crate) yields: u64,
+    pub(crate) last_run_time: u64,
 }
 
 impl Thread {
-    pub fn new(id: ThreadId, entry_point: fn() -> !, priority: ThreadPriority) -> Self {
+    /// Create a new thread with allocated stack
+    ///
+    /// # Arguments
+    /// * `id` - Unique thread identifier
+    /// * `entry_point` - Function where thread begins execution
+    /// * `priority` - Thread priority level
+    /// * `stack_bottom` - Low address of thread's stack
+    /// * `stack_top` - High address of thread's stack
+    pub fn new(
+        id: ThreadId,
+        entry_point: fn() -> !,
+        priority: ThreadPriority,
+        stack_bottom: u64,
+        stack_top: u64,
+    ) -> Self {
+        // Create initial context for this thread
+        let context = ThreadContext::new(entry_point as u64, stack_top);
+
         Self {
             id,
             state: ThreadState::Resting,
             priority,
             entry_point,
+            context,
+            stack_bottom,
+            stack_top,
             resource_usage: ResourceUsage::default(),
             harmony_score: 1.0, // Start in perfect harmony
             time_slices_used: 0,
             yields: 0,
+            last_run_time: 0,
         }
+    }
+
+    /// Get a mutable reference to the thread's context
+    pub fn context_mut(&mut self) -> &mut ThreadContext {
+        &mut self.context
+    }
+
+    /// Get a reference to the thread's context
+    pub fn context(&self) -> &ThreadContext {
+        &self.context
     }
 
     pub fn id(&self) -> ThreadId {