ahrightos-kernel 0.1.0

RISC-V 64 Rust teaching kernel for AhRightOS.
Documentation
//! User-mode task creation and address space management.

use crate::memory::paging::map_page;
use crate::memory::{
    AddressSpace, PageTableFlags, PhysAddr, SimpleFrameAllocator, VirtAddr, PAGE_SIZE,
};
use crate::process::elf::{Elf, ElfSegment};
use crate::process::{ProcessControlBlock, ProcessId};
use alloc::boxed::Box;

/// Default user stack size: 8 pages (32 KB)
const USER_STACK_PAGES: usize = 8;
/// Default user stack top (grows downward from here)
const USER_STACK_TOP: usize = 0x7FFF_F000;

/// Create a user address space by privately cloning kernel mappings and loading
/// ELF segments.
///
/// Kernel/MMIO leaf mappings still point at the same physical pages so trap
/// handlers and kernel code remain accessible during exceptions/syscalls, but
/// the intermediate page-table pages are not shared with the boot kernel root.
/// User pages are mapped with the U flag set.
pub fn create_user_address_space(
    elf: &Elf,
    raw_elf: &[u8],
    allocator: &mut SimpleFrameAllocator,
    kernel_page_table_paddr: PhysAddr,
) -> Result<AddressSpace, &'static str> {
    let mut addr_space = AddressSpace::new(allocator)?;

    // Clone kernel mappings into private page-table pages so traps/syscalls
    // work without letting user ELF mappings pollute the boot kernel root.
    addr_space.copy_kernel_mappings_from(kernel_page_table_paddr, allocator)?;

    crate::serial_println!(
        "[USER] Kernel mappings cloned to user page table (root at {:#x})",
        addr_space.page_table_paddr().as_usize()
    );

    // Load each PT_LOAD segment into user address space
    for seg in &elf.segments {
        load_segment(seg, raw_elf, &mut addr_space, allocator)?;
    }

    // Map user stack (grows downward from USER_STACK_TOP)
    let stack_start = USER_STACK_TOP - USER_STACK_PAGES * PAGE_SIZE;
    let stack_flags = PageTableFlags::Valid as usize
        | PageTableFlags::Read as usize
        | PageTableFlags::Write as usize
        | PageTableFlags::User as usize;

    for i in 0..USER_STACK_PAGES {
        let vaddr = VirtAddr::new(stack_start + i * PAGE_SIZE);
        let frame = allocator.allocate().ok_or("Out of memory for user stack")?;
        let paddr = frame.start_address();
        unsafe {
            let root = &mut *addr_space.page_table_ptr();
            map_page(root, vaddr, paddr, stack_flags, allocator)?;
        }
    }

    crate::serial_println!(
        "[USER] Stack mapped: {:#x} - {:#x}",
        stack_start,
        USER_STACK_TOP
    );
    crate::serial_println!("[USER] Entry point: {:#x}", elf.entry);

    Ok(addr_space)
}

/// Load a single ELF segment into the user address space.
fn load_segment(
    seg: &ElfSegment,
    raw_elf: &[u8],
    addr_space: &mut AddressSpace,
    allocator: &mut SimpleFrameAllocator,
) -> Result<(), &'static str> {
    let seg_start = seg.vaddr;
    let seg_end = seg
        .vaddr
        .checked_add(seg.memsz)
        .ok_or("ELF segment address overflow")?;
    let page_start = seg_start & !(PAGE_SIZE - 1);
    let page_end = seg_end
        .checked_add(PAGE_SIZE - 1)
        .ok_or("ELF segment page range overflow")?
        & !(PAGE_SIZE - 1);

    if seg.filesz > seg.memsz {
        return Err("ELF segment file size exceeds memory size");
    }
    let file_end = seg
        .offset
        .checked_add(seg.filesz)
        .ok_or("ELF segment file range overflow")?;
    let file_data = raw_elf
        .get(seg.offset..file_end)
        .ok_or("ELF segment file data out of bounds")?;
    let file_vaddr_end = seg_start
        .checked_add(seg.filesz)
        .ok_or("ELF segment file address overflow")?;

    // Build flags from ELF PF_ flags + User
    let mut prot = PageTableFlags::Valid as usize | PageTableFlags::User as usize;
    if seg.flags & 1 != 0 {
        prot |= PageTableFlags::Execute as usize;
    } // PF_X
    if seg.flags & 2 != 0 {
        prot |= PageTableFlags::Write as usize;
    } // PF_W
    if seg.flags & 4 != 0 {
        prot |= PageTableFlags::Read as usize;
    } // PF_R

    crate::serial_println!(
        "[USER] Loading segment: vaddr={:#x}..{:#x} filesz={} memsz={} prot={:#x}",
        seg_start,
        seg_end,
        seg.filesz,
        seg.memsz,
        prot
    );

    let root = unsafe { &mut *addr_space.page_table_ptr() };

    for page_off in (0..(page_end - page_start)).step_by(PAGE_SIZE) {
        let vaddr = VirtAddr::new(page_start + page_off);
        let frame = allocator
            .allocate()
            .ok_or("Out of memory for user segment")?;
        let paddr = frame.start_address();

        map_page(root, vaddr, paddr, prot, allocator)?;

        let dst = paddr.as_usize() as *mut u8;
        unsafe {
            for i in 0..PAGE_SIZE {
                *dst.add(i) = 0;
            }
        }

        let page_vaddr_start = vaddr.as_usize();
        let page_vaddr_end = core::cmp::min(page_vaddr_start + PAGE_SIZE, seg_end);
        let copy_vaddr_start = core::cmp::max(page_vaddr_start, seg_start);
        let copy_vaddr_end = core::cmp::min(page_vaddr_end, file_vaddr_end);

        if copy_vaddr_start < copy_vaddr_end {
            let src_start = copy_vaddr_start - seg_start;
            let dst_start = copy_vaddr_start - page_vaddr_start;
            let len = copy_vaddr_end - copy_vaddr_start;
            let src = &file_data[src_start..src_start + len];
            unsafe {
                for (idx, byte) in src.iter().enumerate() {
                    *dst.add(dst_start + idx) = *byte;
                }
            }
        }
    }

    Ok(())
}

/// Create a user-mode task PCB.
///
/// The task will start in U-mode at `entry` with `sp` set to `stack_top`.
/// The user page table (`satp`) is set so the CPU can access user memory
/// while kernel trap handlers remain reachable.
pub fn create_user_task(
    pid: ProcessId,
    name: &'static str,
    entry: usize,
    stack_top: usize,
    satp: usize,
) -> Box<ProcessControlBlock> {
    let mut pcb = ProcessControlBlock::new(pid, name, None);
    let ctx = pcb.context_mut();

    ctx.set_ra(entry);
    ctx.set_sp(stack_top);
    ctx.set_sepc(entry);

    // U-mode sstatus: SPP=0 (User), SPIE=1, SUM=1, SIE=0
    let raw_sstatus: usize;
    unsafe {
        core::arch::asm!("csrr {}, sstatus", out(reg) raw_sstatus);
    }
    let user_sstatus = (raw_sstatus | (1 << 5) | (1 << 18)) & !((1 << 8) | (1 << 1));
    ctx.set_sstatus(user_sstatus);

    ctx.set_satp(satp);

    Box::new(pcb)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::memory::paging::walk_page_table;
    use crate::memory::{MemoryAreaType, PageTable, PAGE_SIZE};
    use crate::process::user_elf::build_user_elf;

    #[test_case]
    fn create_user_address_space_does_not_pollute_kernel_low_uart_subtree() {
        let mut allocator = SimpleFrameAllocator::new(0x8060_0000, 0x8080_0000);
        let mut kernel_space = AddressSpace::new(&mut allocator).expect("kernel address space");

        // UART is deliberately low (VPN[2] == 0), the same root slot used by
        // the teaching user ELF at 0x10000.  This used to expose a shallow-copy
        // bug where mapping the user ELF mutated the boot kernel root subtree.
        kernel_space
            .map_region_identity(
                PhysAddr::new(0x1000_0000),
                PAGE_SIZE,
                MemoryAreaType::Data,
                &mut allocator,
            )
            .expect("map UART");
        let kernel_root_paddr = kernel_space.page_table_paddr();

        let (elf_bytes, _) = build_user_elf();
        let elf = Elf::parse(&elf_bytes).expect("embedded ELF parses");

        let first = create_user_address_space(&elf, &elf_bytes, &mut allocator, kernel_root_paddr)
            .expect("first user address space");
        assert!(
            walk_page_table(kernel_root_paddr, VirtAddr::new(0x10000)).is_none(),
            "creating a user address space must not add user ELF mappings to the kernel root"
        );

        let _second =
            create_user_address_space(&elf, &elf_bytes, &mut allocator, kernel_root_paddr)
                .expect("second user address space should not see stale user mappings");
        assert!(
            walk_page_table(kernel_root_paddr, VirtAddr::new(0x10000)).is_none(),
            "repeated user address-space creation must leave the kernel root clean"
        );

        let kernel_root = unsafe { &*(kernel_root_paddr.as_usize() as *const PageTable) };
        let user_root = unsafe { &*(first.page_table_ptr() as *const PageTable) };
        assert_ne!(
            kernel_root
                .get_entry(VirtAddr::new(0x1000_0000).vpn2())
                .phys_addr(),
            user_root
                .get_entry(VirtAddr::new(0x1000_0000).vpn2())
                .phys_addr(),
            "kernel and user roots must not share the low UART intermediate page table"
        );
    }
}