moss-kernel/README.md

moss

moss is a Unix-like, Linux-compatible kernel written in Rust and Aarch64 assembly.

It features a modern, asynchronous core, a modular architecture abstraction layer, and binary compatibility with Linux userspace applications (currently capable of running most BusyBox commands).

Features

Architecture & Memory

• Full support for aarch64.
• A well-defined HAL allowing for easy porting to other architectures (e.g., x86_64, RISC-V).
• Memory Management:
  • Full MMU enablement and page table management.
  • Copy-on-Write (CoW) pages.
  • Safe copy to/from userspace async functions.
  • Kernel and userspace page fault management.
  • Buddy allocator for physical addresses and smalloc for boot allocations and tracking memory reservations.

Async Core

One of the defining features of moss is its usage of Rust's async/await model within the kernel context:

• All non-trivial system calls are written as async functions, sleep-able functions are prefixed with .await.
• The compiler enforces that spinlocks cannot be held over sleep points, eliminating a common class of kernel deadlocks.

Process Management

• Full task management including scheduling and task migration via IPIs.
• Currently implements 49 Linux syscalls; sufficient to execute most BusyBox commands.
• Advanced forking capabilities via clone().
• Process and thread signal delivery and raising support.

VFS & Filesystems

• Virtual File System with full async abstractions.
• Drivers:
  • Ramdisk block device implementation.
  • FAT32 filesystem driver (ro).
  • devtmpfs driver for kernel character device access.

libkernel & Testing

moss is built on top of libkernel, a utility library designed to be architecture-agnostic. This allows logic to be tested on a host machine (e.g., x86) before running on bare metal.

• Address Types: Strong typing for VA (Virtual), PA (Physical), and UA (User) addresses.
• Containers: VMA management, generic page-based ring buffer (kbuf), and waker sets.
• Sync Primitives: spinlock, mutex, condvar, per_cpu.
• Test Suite: A comprehensive suite of 230+ tests ensuring functionality across architectures (e.g., validating Aarch64 page table parsing logic on an x86 host).

Building and Running

Prerequisites

You will need a nightly Rust toolchain and QEMU for aarch64 emulation.

# Install Rust Nightly
rustup toolchain install nightly
rustup component add rust-src llvm-tools-preview

# Install QEMU (Ubuntu/Debian)
sudo apt install qemu-system-aarch64

Additionally you will need a version of the aarch64-none-elf toolchain installed.

Any OS

To install aarch64-none-elf on any os, download the correct release of aarch64-none-elf onto your computer, unpack it, then export the bin folder to path.

NixOS

Run the following command

nix shell nixpkgs#pkgsCross.aarch64-embedded.stdenv.cc nixpkgs#pkgsCross.aarch64-embedded.stdenv.cc.bintools

Running via QEMU

To build the kernel and launch it in QEMU:

cargo run --release

Running the Test Suite

Because libkernel is architecturally decoupled, you can run the logic tests on your host machine:

cargo test -p libkernel --target x86_64-unknown-linux-gnu

Roadmap & Status

moss is under active development. Current focus areas include:

• Basic Linux Syscall Compatibility (Testing through BusyBox).
• Networking Stack: TCP/IP implementation.
• Scheduler Improvements: Task load balancing.
• A fully read/write capable filesystem driver (e.g., ext2/4).
• Expanding coverage beyond the current 49 calls.

Contributing

Contributions are welcome! Whether you are interested in writing a driver, porting to x86, or adding syscalls.

License

Distributed under the MIT License. See LICENSE for more information.