SBUnix

A RISC-V 64-bit kernel (Sv39) built for CSE 506. SBUnix boots on QEMU's virt machine, implements physical memory management, virtual memory with identity mapping, trap handling, and basic syscalls (read, write, exit).

---

Quick Start

Prerequisites

• RISC-V toolchain: riscv64-unknown-elf-gcc, riscv64-unknown-elf-ld, riscv64-unknown-elf-objcopy
• QEMU: qemu-system-riscv64

# macOS (Homebrew)
brew install riscv64-unknown-elf-gcc qemu

# Ubuntu/Debian
sudo apt install gcc-riscv64-unknown-elf qemu-system-misc

Build & Run

make
make qemu

What You'll See

On main (trap handling):

SBUnix is booting...
Course: CSE506
Kernel Base: 0x80200000
System ready. Humans > Bots.

Type: 

Type text and press Enter. The kernel echoes it back (32-byte buffer). The flow: user program → ecall → trap handler → sys_read/sys_write → UART → back to user.

On feat/phys-mem-manager (physical memory + virtual memory):

SBUnix is booting...
...
--- MEMORY LAYOUT ---
Kernel End (Raw):   0x8020xxxx
Kernel End (Align): 0x8020xxxx
Physical Stop:      0x88000000
Free RAM Size:      xxx MB

kinit: Ledger initialized with xxxxx free pages.
SUCCESS: Allocated p1 at 0x8xxxxxxx and p2 at 0x8xxxxxxx
kvminit: Kernel Page Table built and Identity Mapped.
kvminithart: MMU is now ON. Welcome to Virtual Memory.
Post-MMU: If you see this, your identity mapping worked!

---

Project Layout

sbuunix/
├── kernel/           # Kernel code
│   ├── start.S       # Entry point, stvec setup
│   ├── kernel.c      # Boot sequence
│   ├── trap.S        # Trap handler (ecall → handle_syscall)
│   ├── syscall.c     # sys_read, sys_write, sys_exit
│   ├── uart.c        # UART driver (putc/getc)
│   ├── printk.c      # printf-style kernel logging
│   ├── vm.c          # Sv39 page tables, kvminit, kvminithart
│   ├── kalloc.c      # Physical page allocator (mem_map ledger)
│   ├── user.c        # enter_user (sret to user mode)
│   └── include/      # Headers (riscv.h, memlayout.h, syscall.h, etc.)
├── user/             # User-space assembly (user_test.S)
├── libc/             # Minimal libc (read, write, syscall wrappers)
├── bin/              # User binaries (echo, etc.)
├── tools/            # mkfs for disk image
├── rootfs/           # Root filesystem layout
└── docs/             # Architecture & design docs

---

Branches

Branch	Description
main	Trap handling, syscalls, user program echo demo
feat/phys-mem-manager	Physical memory ledger + Sv39 virtual memory (MMU on)
shell	Shell work in progress

---

Contributors

Component	Author
Trap handling (trap.S, syscall.c, uart read/write, user echo)	Matthew Beck
Physical memory manager (kalloc.c, mem_map ledger)	Angad Singh
Virtual memory (vm.c, Sv39 page tables, kvminit, kvminithart)	Angad Singh
printk, types.h, riscv.h, memlayout.h	Angad Singh

---

Syscall Interface

Syscall	Number	Args	Description
read	63	fd, buf, count	Reads from fd (0=stdin → UART)
write	64	fd, buf, count	Writes to fd (1/2=stdout/stderr → UART)
exit	93	status	Exits process (prints status, halts)

---

Further Reading

• docs/ARCHITECTURE.md — Data flow, trap path, memory layout, and design decisions