# moss

**Repository Path**: mindbox/moss

## Basic Information

- **Project Name**: moss
- **Description**: No description available
- **Primary Language**: Rust
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-22
- **Last Updated**: 2025-11-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# moss

![Architecture](https://img.shields.io/badge/arch-aarch64-blue)
![Language](https://img.shields.io/badge/language-Rust-orange)
![License](https://img.shields.io/badge/license-MIT-yellow)

![Moss Boot Demo](etc/moss_demo.gif)

**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 QEMU for aarch64 emulation, dosfstools to create the virtual file system
and gcc-aarch64-linux-gnu to compile bash for the image.

```bash
# Install QEMU (Ubuntu/Debian), dosfstools and gcc-aarch64-linux-gnu
sudo apt install qemu-system-aarch64 dosfstools gcc-aarch64-linux-gnu
```

Additionally you will need a version of the [aarch64-none-elf](https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain) 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

```bash
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:

``` bash
cargo run --release
```


### Running the Test Suite
Because `libkernel` is architecturally decoupled, you can run the logic tests on
your host machine:

``` bash
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.