Neptune Kernel

Inspired by xv6

For a quick reference on RISC-V assembly:

• https://risc-v.guru/instructions/

Some low-level string format routines borrowed from mini-printf

Directory outline

The planned directory outline is as follows:

root
├── kern           # General kernel sources
│   ├── libkern    # Kernel specific library routines
│   ├── memory     # Memory related code (kalloc, buddy and friends)
│   └── arch       # Architecture specific functionality
├── libc           # Userspace C library
└── user           # Userspace programs

Quick Start

On a linux machine, make sure that you have make and curl in path. The rest of the tooling (gcc, qemu) will be handled by the build system. For extra convenience, you could also use bear for generating "compile_commands.json". This is useful for helping clangd pick up the correct paths, and will result in better in-editor diagnostics and warnings. For development, clang-format and find will also be useful.

In short, for debian/redhat:

sudo apt install bear make curl clang-format find
sudo dnf install bear make curl clang-format find

Im sure its the same on alpine/arch and friends. You're a linux user, put on those big boy pants and figure it out. For more info you can check make help.

make get_toolchain # Dont worry, is will land locally inside project directory
make -j$(nproc)
make qemu

To generate "compile_commands.json":

make clean # To get a full build
bear -- make -j$(nproc)

The project can be cleaned with:

make clean     # Wipes .o, .d, .elf
make distclean # Wipes the above, but also removes toolchain

Toolchains:

• https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack
• https://github.com/xpack-dev-tools/qemu-riscv-xpack/

---

A word on terminology: Although the official x86 term is exception, xv6 uses the term trap, largely because it was the term used by the PDP11/40 and therefore is the conventional Unix term.

Notes/Misc

Register	Name	Privilege Level	Description
mstatus	Machine Status Register	Machine	Holds global interrupt enable, previous privilege mode, etc.
mtvec	Machine Trap-Vector Base	Machine	Holds the base address of the trap handler (exception/interrupt entry).
mepc	Machine Exception PC	Machine	Stores the program counter at the time of the last trap.
mcause	Machine Cause Register	Machine	Indicates the cause of the last trap (interrupt or exception).
satp	Supervisor Address Translation and Protection	Supervisor	Controls page table base address and mode (e.g., Sv39, Sv48).
sstatus	Supervisor Status Register	Supervisor	Like mstatus, but accessible from supervisor mode.
stvec	Supervisor Trap-Vector Base	Supervisor	Like mtvec, but for supervisor mode traps.
sepc	Supervisor Exception PC	Supervisor	Like mepc, but for supervisor mode.
scause	Supervisor Cause Register	Supervisor	Like mcause, but for supervisor mode traps.
sscratch	Supervisor Scratch	Supervisor	Can be used to store temporary state across traps in supervisor mode.
mscratch	Machine Scratch	Machine	Like sscratch, but in machine mode.
mcycle	Machine Cycle Counter	Machine	Counts the number of cycles executed.
mtime	Machine Timer Register	Machine (via memory-mapped)	Used for timing and scheduling (not a CSR, but a memory-mapped register).
mip	Machine Interrupt Pending	Machine	Indicates pending interrupts.
mie	Machine Interrupt Enable	Machine	Controls which interrupts are enabled.

TODO

• Kassert, some macro in the form of ASSERT(condition, "This went wrong")
• FatFs
• Integrate Kconfig
• Klog, or some form of logging that is directable and more than just kprintf

Libc Implementations

• Libc reference

• uClibc

• musl libc

• dietlibc

Comparison of C/POSIX standard library implementations for Linux (by musl author)