A minimal RISC-V operating system kernel written in Zig, demonstrating modern systems programming practices with clean modular architecture.

• RISC-V 32-bit Architecture: Native support for RISC-V with SV32 virtual memory
• Process Management: Process creation, scheduling, and context switching with user mode support
• Memory Management: Page-based virtual memory with SV32 paging and memory protection
• User Mode Execution: Successful kernel/user privilege separation with sret transitions
• SBI Interface: Clean abstraction over RISC-V Supervisor Binary Interface
• Modular Design: Well-organized codebase following Zig best practices
• Error Handling: Proper error propagation and type safety
• Trap Handling: RISC-V exception and interrupt framework

• Zig 0.15.1+: The Zig compiler
• QEMU: For RISC-V emulation (qemu-system-riscv32)
• LLVM tools: For binary conversion (llvm-objcopy)

# Install QEMU and LLVM tools
sudo apt update
sudo apt install qemu-system-misc llvm

# Verify QEMU RISC-V support
qemu-system-riscv32 --version

# Install QEMU and LLVM
brew install qemu llvm

# Add LLVM to PATH (for objcopy)
export PATH="/opt/homebrew/opt/llvm/bin:$PATH"

# Install QEMU and LLVM
sudo pacman -S qemu-system-riscv llvm

# Verify installation
qemu-system-riscv32 --version

# Download Zig 0.15.1+ from https://ziglang.org/download/
# For Linux x86_64:
wget https://ziglang.org/download/0.15.1/zig-linux-x86_64-0.15.1.tar.xz
tar -xf zig-linux-x86_64-0.15.1.tar.xz
sudo mv zig-linux-x86_64-0.15.1 /opt/zig
export PATH="/opt/zig:$PATH"

# For macOS (or use brew install zig):
# wget https://ziglang.org/download/0.15.1/zig-macos-x86_64-0.15.1.tar.xz

# Verify Zig installation
zig version

# Clone the repository
git clone https://github.com/botirk38/OS-1000-lines-zig.git
cd OS-1000-lines-zig

# Build the kernel and user program
zig build

# Run in QEMU
zig build run

src/
├── arch/           # Architecture-specific code
│   └── riscv32.zig # RISC-V 32-bit implementation
├── hal/            # Hardware Abstraction Layer
│   └── console.zig # Console I/O abstraction
├── mm/             # Memory Management
│   ├── allocator.zig # Page allocator
│   └── paging.zig    # Virtual memory management
├── proc/           # Process Management
│   └── process.zig   # Process creation and scheduling
├── platform/       # Platform-specific interfaces
│   └── sbi.zig      # RISC-V SBI interface
├── debug/          # Debug utilities
│   └── panic.zig    # Panic and assertion handling
├── common.zig      # Common utilities
├── kernel.zig      # Main kernel entry point
└── user.zig        # Simple user program

• Kernel Space: Virtual addresses 0x80000000+
• User Space: Virtual addresses 0x01000000+
• Page Size: 4KB with SV32 paging

• Simple round-robin scheduler
• Process creation with ELF loading
• Context switching via RISC-V CSRs

• SBI calls for console I/O and system services
• Trap handling for exceptions and interrupts
• Virtual memory management with page tables

• Kernel Foundation: Complete boot process, memory management, and trap handling
• Process Management: Working process creation, scheduling, and context switching
• User Mode Support: Successfully transitions to user mode with sret instruction
• Memory Protection: SV32 paging with proper kernel/user separation
• Architecture: Clean modular design with proper separation of concerns

• User Program Security: Current user program imports kernel modules (security violation)
• System Calls: No syscall interface implemented yet
• Trap Handler: Limited to panic on all traps (needs syscall support)

1. Fix user program to remove kernel imports
2. Implement system calls (ecall instruction handling)
3. Add user library for safe user-space operations
4. Enhanced trap handling to distinguish syscalls from faults

# Build only
zig build

# Build and run in QEMU
zig build run

# Clean build artifacts
rm -rf zig-cache zig-out

The kernel includes panic handling and debug assertions. Monitor output shows:

• Boot messages with detailed initialization steps
• Memory allocation and page mapping operations
• Process creation and user mode transition
• Trap information when user space violates memory protection

# Run any Zig tests (if present)
zig test src/common.zig

The kernel runs in QEMU with the following configuration:

• Architecture: RISC-V 32-bit (qemu-system-riscv32)
• Machine: virt (RISC-V virtual platform)
• BIOS: Default OpenSBI firmware
• Memory: 128MB default
• Serial: Console output via UART (stdio)
• Monitor: Telnet interface on port 55556

# Automated run (recommended)
zig build run

# Manual QEMU invocation (equivalent to above)
qemu-system-riscv32 \
  -machine virt \
  -bios default \
  -serial mon:stdio \
  -monitor telnet:127.0.0.1:55556,server,nowait \
  --no-reboot \
  -nographic \
  -kernel zig-out/bin/kernel.elf

• Exit QEMU: Ctrl+A, X
• Monitor interface: Connect to telnet localhost 55556
• Pause/Resume: Ctrl+A, S / Ctrl+A, R
• Reset: Ctrl+A, R (or use monitor command system_reset)

When running successfully, you should see:

OpenSBI v1.3.1
...
[rk] booting kernel...
[rk] setting trap vector...
[rk] initializing allocator...
[rk] initializing scheduler...
[rk] initProcess: starting...
[rk] initProcess: setting up stack...
[rk] initProcess: allocating page table...
[rk] kernel_base=80200000, free_ram_end=84245000
[rk] starting memory mapping loop...
[rk] memory mapping complete
[allocator] allocPages: n=1, PAGE_SIZE=4096
...
[paging] mapPage: vaddr=0x1000000, paddr=0x80265000, flags=0x1f
...
[PANIC] trap: scause=0xf, stval=0x80218c64, sepc=0x100000a

Note: The current panic is expected behavior - it demonstrates successful user mode execution with memory protection working correctly. The user process runs at sepc=0x100000a (user space) but triggers a page fault when trying to access kernel memory, which is the intended security behavior.

# Verify QEMU is installed with RISC-V support
qemu-system-riscv32 --version
which qemu-system-riscv32

# On some systems, try:
sudo apt install qemu-system-riscv32  # Debian-based
brew install qemu                     # macOS

# Clean and rebuild
rm -rf zig-cache zig-out
zig build

# Check Zig version (needs 0.15.1+)
zig version

• Ensure your terminal supports the console output
• Try running with -serial stdio instead of -serial mon:stdio
• Check that OpenSBI loads (you should see OpenSBI banner)

# On some Linux systems, add user to kvm group for better performance
sudo usermod -a -G kvm $USER
# Logout and login again

This project demonstrates clean systems programming in Zig. Contributions should:

1. Follow Zig coding standards
2. Maintain modular architecture
3. Include proper error handling
4. Add documentation for new features

MIT License - see LICENSE file for details.

• RISC-V Specification
• Zig Language Reference
• SBI Specification