ahrightos-kernel 0.1.0

RISC-V 64 Rust teaching kernel for AhRightOS.
Documentation
//! Minimal RISC-V ELF64 user program embedded in the kernel.
//!
//! This is a hand-crafted ELF binary: it uses `ecall` to invoke
//! sys_write(1, msg, len) then sys_exit(0).

fn encode_beq(rs1: u32, rs2: u32, offset: i32) -> [u8; 4] {
    assert!(offset % 2 == 0);
    assert!((-4096..=4094).contains(&offset));

    let imm = (offset as u32) & 0x1fff;
    let encoded = (((imm >> 12) & 0x1) << 31)
        | (((imm >> 5) & 0x3f) << 25)
        | (rs2 << 20)
        | (rs1 << 15)
        | (((imm >> 1) & 0xf) << 8)
        | (((imm >> 11) & 0x1) << 7)
        | 0x63;
    encoded.to_le_bytes()
}

/// Build a fork + wait test RISC-V ELF64 executable.
///
/// The program:
/// 1. Prints "start"
/// 2. Calls fork()
/// 3. Child prints "child", exits 42
/// 4. Parent waits, prints "done", exits 0
///
/// Returns (elf_bytes, entry_point).
pub fn build_fork_test_elf() -> (alloc::vec::Vec<u8>, usize) {
    // Instructions (each line = 4 bytes, little-endian):
    // 00: addi a7, x0, 64   # write
    // 04: addi a0, x0, 1    # stdout
    // 08: auipc a1, 0
    // 0c: addi a1, a1, 120  # → "start\n" at 0x80
    // 10: addi a2, x0, 6    # len=6
    // 14: ecall
    // 18: addi a7, x0, 220  # fork
    // 1c: ecall
    // 20: beqz a0, child    # → child at 0x5c
    // 24: mv s0, a0          # parent: save child pid
    // 28: addi sp, sp, -16
    // 2c: mv a0, sp
    // 30: addi a7, x0, 260  # wait
    // 34: ecall
    // 38: addi a7, x0, 64   # write
    // 3c: addi a0, x0, 1
    // 40: auipc a1, 0
    // 44: addi a1, a1, 70   # → "done\n" at 0x86
    // 48: addi a2, x0, 5    # len=5
    // 4c: ecall
    // 50: addi a0, x0, 0    # exit 0
    // 54: addi a7, x0, 93
    // 58: ecall
    // 5c: addi a7, x0, 64   # child: write
    // 60: addi a0, x0, 1
    // 64: auipc a1, 0
    // 68: addi a1, a1, 39   # → "child\n" at 0x8b
    // 6c: addi a2, x0, 6    # len=6
    // 70: ecall
    // 74: addi a0, x0, 42   # exit 42
    // 78: addi a7, x0, 93
    // 7c: ecall
    // 80: "start\n"  (6 bytes)
    // 86: "done\n"   (5 bytes)
    // 8b: "child\n"  (6 bytes)

    fn emit(code: &mut [u8; 128], cursor: &mut usize, inst: u32) {
        let bytes = inst.to_le_bytes();
        code[*cursor..*cursor + 4].copy_from_slice(&bytes);
        *cursor += 4;
    }

    let mut code = [0u8; 128];
    let mut cursor = 0usize;

    // 0x00 - 0x14: write("start\n", 6)
    emit(&mut code, &mut cursor, 0x0400_0893); // addi a7, x0, 64
    emit(&mut code, &mut cursor, 0x0010_0513); // addi a0, x0, 1
    emit(&mut code, &mut cursor, 0x0000_0597); // auipc a1, 0
    emit(&mut code, &mut cursor, 0x0785_8593); // addi a1, a1, 120
    emit(&mut code, &mut cursor, 0x0060_0613); // addi a2, x0, 6
    emit(&mut code, &mut cursor, 0x0000_0073); // ecall

    // 0x18 - 0x1c: fork()
    emit(&mut code, &mut cursor, 0x0dc0_0893); // addi a7, x0, 220
    emit(&mut code, &mut cursor, 0x0000_0073); // ecall

    // 0x20: beqz a0, child (target = entry + 0x5c)
    emit(
        &mut code,
        &mut cursor,
        u32::from_le_bytes(encode_beq(10, 0, 0x5c - 0x20)),
    );

    // 0x24 - 0x34: parent: wait(&status)
    emit(&mut code, &mut cursor, 0x0005_0413); // mv s0, a0
    emit(&mut code, &mut cursor, 0xff01_0113); // addi sp, sp, -16
    emit(&mut code, &mut cursor, 0x0001_0513); // mv a0, sp
    emit(&mut code, &mut cursor, 0x1040_0893); // addi a7, x0, 260
    emit(&mut code, &mut cursor, 0x0000_0073); // ecall

    // 0x38 - 0x4c: write("done\n", 5)
    emit(&mut code, &mut cursor, 0x0400_0893); // addi a7, x0, 64
    emit(&mut code, &mut cursor, 0x0010_0513); // addi a0, x0, 1
    emit(&mut code, &mut cursor, 0x0000_0597); // auipc a1, 0
    emit(&mut code, &mut cursor, 0x0465_8593); // addi a1, a1, 70
    emit(&mut code, &mut cursor, 0x0050_0613); // addi a2, x0, 5
    emit(&mut code, &mut cursor, 0x0000_0073); // ecall

    // 0x50 - 0x58: exit(0)
    emit(&mut code, &mut cursor, 0x0000_0513); // addi a0, x0, 0
    emit(&mut code, &mut cursor, 0x05d0_0893); // addi a7, x0, 93
    emit(&mut code, &mut cursor, 0x0000_0073); // ecall

    // 0x5c - 0x70: child: write("child\n", 6)
    emit(&mut code, &mut cursor, 0x0400_0893); // addi a7, x0, 64
    emit(&mut code, &mut cursor, 0x0010_0513); // addi a0, x0, 1
    emit(&mut code, &mut cursor, 0x0000_0597); // auipc a1, 0
    emit(&mut code, &mut cursor, 0x0275_8593); // addi a1, a1, 39
    emit(&mut code, &mut cursor, 0x0060_0613); // addi a2, x0, 6
    emit(&mut code, &mut cursor, 0x0000_0073); // ecall

    // 0x74 - 0x7c: exit(42)
    emit(&mut code, &mut cursor, 0x02a0_0513); // addi a0, x0, 42
    emit(&mut code, &mut cursor, 0x05d0_0893); // addi a7, x0, 93
    emit(&mut code, &mut cursor, 0x0000_0073); // ecall
    assert_eq!(cursor, 128);

    let msgs = b"start\ndone\nchild\n";
    let code_and_data: [u8; 145] = {
        let mut buf = [0u8; 145];
        let mut i = 0;
        while i < 128 {
            buf[i] = code[i];
            i += 1;
        }
        while i < 145 {
            buf[i] = msgs[i - 128];
            i += 1;
        }
        buf
    };

    let entry: u64 = 0x10078;
    let phoff: u64 = 64;
    let phentsize: u16 = 56;
    let phnum: u16 = 1;
    let pagesz: u64 = 0x1000;
    let filesz: u64 = pagesz;

    let mut elf = alloc::vec::Vec::with_capacity(pagesz as usize);

    // ELF64 Header (64 bytes)
    elf.extend_from_slice(&[0x7f, b'E', b'L', b'F']);
    elf.push(2);
    elf.push(1);
    elf.push(1);
    elf.push(0);
    elf.extend_from_slice(&[0u8; 8]);
    elf.extend_from_slice(&2u16.to_le_bytes());
    elf.extend_from_slice(&243u16.to_le_bytes());
    elf.extend_from_slice(&1u32.to_le_bytes());
    elf.extend_from_slice(&entry.to_le_bytes());
    elf.extend_from_slice(&phoff.to_le_bytes());
    elf.extend_from_slice(&0u64.to_le_bytes());
    elf.extend_from_slice(&0u32.to_le_bytes());
    elf.extend_from_slice(&64u16.to_le_bytes());
    elf.extend_from_slice(&phentsize.to_le_bytes());
    elf.extend_from_slice(&phnum.to_le_bytes());
    elf.extend_from_slice(&0u16.to_le_bytes());
    elf.extend_from_slice(&0u16.to_le_bytes());
    elf.extend_from_slice(&0u16.to_le_bytes());

    // Program Header (56 bytes)
    elf.extend_from_slice(&1u32.to_le_bytes()); // PT_LOAD
    elf.extend_from_slice(&7u32.to_le_bytes()); // RWX
    elf.extend_from_slice(&0u64.to_le_bytes()); // p_offset
    elf.extend_from_slice(&0x10000u64.to_le_bytes()); // p_vaddr
    elf.extend_from_slice(&0x10000u64.to_le_bytes()); // p_paddr
    elf.extend_from_slice(&filesz.to_le_bytes());
    elf.extend_from_slice(&filesz.to_le_bytes());
    elf.extend_from_slice(&pagesz.to_le_bytes());

    // Code + data
    elf.extend_from_slice(&code_and_data);

    // Pad to full page
    while elf.len() < pagesz as usize {
        elf.push(0);
    }

    (elf, entry as usize)
}

/// Build a minimal RISC-V ELF64 executable at runtime.
///
/// The program:
/// 1. Calls sys_write(1, "Hello from User Mode!\n", 22)
/// 2. Calls sys_exit(0)
///
/// Returns (elf_bytes, entry_point).
pub fn build_user_elf() -> (alloc::vec::Vec<u8>, usize) {
    // RISC-V instructions (little-endian):
    // 0x00: addi a7, x0, 64   → 0x04000893 (syscall: write)
    // 0x04: addi a0, x0, 1    → 0x00100513 (fd = stdout)
    // 0x08: auipc a1, 0       → 0x00000597 (a1 = PC)
    // 0x0c: addi a1, a1, 28   → 0x01c58593 (a1 += offset to string)
    // 0x10: addi a2, x0, 22   → 0x01600613 (len = 22)
    // 0x14: ecall              → 0x00000073
    // 0x18: addi a7, x0, 93   → 0x05d00893 (syscall: exit)
    // 0x1c: addi a0, x0, 0    → 0x00000513 (exit code 0)
    // 0x20: ecall              → 0x00000073
    // 0x24: "Hello from User Mode!\n\0" (23 bytes)

    let code: [u8; 36] = [
        0x93, 0x08, 0x00, 0x04, // addi a7, x0, 64
        0x13, 0x05, 0x10, 0x00, // addi a0, x0, 1
        0x97, 0x05, 0x00, 0x00, // auipc a1, 0
        0x93, 0x85, 0xc5, 0x01, // addi a1, a1, 28
        0x13, 0x06, 0x60, 0x01, // addi a2, x0, 22
        0x73, 0x00, 0x00, 0x00, // ecall
        0x93, 0x08, 0xd0, 0x05, // addi a7, x0, 93
        0x13, 0x05, 0x00, 0x00, // addi a0, x0, 0
        0x73, 0x00, 0x00, 0x00, // ecall
    ];

    let msg = b"Hello from User Mode!\n\0"; // 23 bytes
    let code_and_data: [u8; 59] = {
        let mut buf = [0u8; 59];
        let mut i = 0;
        while i < 36 {
            buf[i] = code[i];
            i += 1;
        }
        while i < 59 {
            buf[i] = msg[i - 36];
            i += 1;
        }
        buf
    };

    let entry: u64 = 0x10078; // vaddr of first instruction
    let phoff: u64 = 64;
    let phentsize: u16 = 56;
    let phnum: u16 = 1;
    let pagesz: u64 = 0x1000;
    let filesz: u64 = pagesz; // one page

    let mut elf = alloc::vec::Vec::with_capacity(pagesz as usize);

    // --- ELF64 Header (64 bytes) ---
    elf.extend_from_slice(&[0x7f, b'E', b'L', b'F']); // e_ident[0..4]: magic
    elf.push(2); // EI_CLASS = ELFCLASS64
    elf.push(1); // EI_DATA = ELFDATA2LSB
    elf.push(1); // EI_VERSION
    elf.push(0); // EI_OSABI = SysV
    elf.extend_from_slice(&[0u8; 8]); // EI_ABIVERSION + padding
    elf.extend_from_slice(&2u16.to_le_bytes()); // e_type = ET_EXEC
    elf.extend_from_slice(&243u16.to_le_bytes()); // e_machine = EM_RISCV
    elf.extend_from_slice(&1u32.to_le_bytes()); // e_version
    elf.extend_from_slice(&entry.to_le_bytes()); // e_entry
    elf.extend_from_slice(&phoff.to_le_bytes()); // e_phoff
    elf.extend_from_slice(&0u64.to_le_bytes()); // e_shoff
    elf.extend_from_slice(&0u32.to_le_bytes()); // e_flags
    elf.extend_from_slice(&64u16.to_le_bytes()); // e_ehsize
    elf.extend_from_slice(&phentsize.to_le_bytes()); // e_phentsize
    elf.extend_from_slice(&phnum.to_le_bytes()); // e_phnum
    elf.extend_from_slice(&0u16.to_le_bytes()); // e_shentsize
    elf.extend_from_slice(&0u16.to_le_bytes()); // e_shnum
    elf.extend_from_slice(&0u16.to_le_bytes()); // e_shstrndx
                                                // Total: 64 bytes ✓

    // --- Program Header (56 bytes) ---
    elf.extend_from_slice(&1u32.to_le_bytes()); // p_type = PT_LOAD
    elf.extend_from_slice(&7u32.to_le_bytes()); // p_flags = RWX
    elf.extend_from_slice(&0u64.to_le_bytes()); // p_offset = 0
    elf.extend_from_slice(&0x10000u64.to_le_bytes()); // p_vaddr
    elf.extend_from_slice(&0x10000u64.to_le_bytes()); // p_paddr
    elf.extend_from_slice(&filesz.to_le_bytes()); // p_filesz
    elf.extend_from_slice(&filesz.to_le_bytes()); // p_memsz
    elf.extend_from_slice(&pagesz.to_le_bytes()); // p_align
                                                  // Total: 120 bytes so far

    // Pad to entry offset (0x78 = 120)
    // Already at 120, no padding needed

    // Code + data at offset 0x78
    elf.extend_from_slice(&code_and_data);

    // Pad to full page (4096 bytes)
    while elf.len() < pagesz as usize {
        elf.push(0);
    }

    (elf, entry as usize)
}

#[cfg(test)]
mod tests {
    use super::*;

    fn decode_branch_offset(inst: u32) -> i32 {
        let imm12 = ((inst >> 31) & 0x1) << 12;
        let imm11 = ((inst >> 7) & 0x1) << 11;
        let imm10_5 = ((inst >> 25) & 0x3f) << 5;
        let imm4_1 = ((inst >> 8) & 0xf) << 1;
        let imm = imm12 | imm11 | imm10_5 | imm4_1;

        if (imm & (1 << 12)) != 0 {
            (imm as i32) | !0x1fff
        } else {
            imm as i32
        }
    }

    #[test_case]
    fn fork_test_uses_beq_to_child_entry() {
        let (elf, entry) = build_fork_test_elf();
        let branch_offset_in_text = 0x20usize;
        let branch_file_offset = 0x78 + branch_offset_in_text;
        let inst = u32::from_le_bytes([
            elf[branch_file_offset],
            elf[branch_file_offset + 1],
            elf[branch_file_offset + 2],
            elf[branch_file_offset + 3],
        ]);

        assert_eq!((inst >> 12) & 0x7, 0, "branch must be BEQ");
        assert_eq!(decode_branch_offset(inst), 0x5c - 0x20);
        assert_eq!(entry + branch_offset_in_text + 0x5c - 0x20, entry + 0x5c);
    }
}