jspngh / mnemos

An Operating System for Building Small Computers

MnemOS (mnɛːmos) is a hobby-grade, experimental operating system for small computers (and bigger ones, too). The MnemOS kernel and userspace use a design based on asynchronous message passing, inspired by Erlang and microkernels, although MnemOS is not a true microkernel.

This repository contains the cross-platform core of the MnemOS kernel, which is implemented as a Rust library crate, platform-specific implementation for supported hardware and simulator targets, development tools for working on MnemOS, and reusable libraries which the kernel, tools, and platform implementations depend on.

Folder Layout

The project layout contains the following folders:

• assets/ - images and files used for READMEs and other documentation
• book/ - This is the source of "the mnemOS book"
• hardware/ - Hardware designs for MnemOS systems, including CAD files and documentation
• source/ - This folder contains the source code of the cross-platform kernel, userspace, and related libraries
• platforms/ - This folder contains code specific to each targeted hardware and simulation platform
• rfcs/ - MnemOS design RFCs
• tools/ - This folder contains desktop tools used for working with MnemOS

Getting Started

Currently, the primary supported hardware platform for MnemOS is the Allwinner D1, a RISC-V system-on-chip (SOC). Instructions for running MnemOS on D1 single-board computer can be found in platforms/allwinner-d1/README.md.

If you don't have access to a supported D1 board, or want a quicker development workflow for testing cross-platform changes, MnemOS also has a software simulator, called Melpomene. Melpomene runs as a userspace application binary on a development machine, and runs the MnemOS kernel with simulated hardware. Melpomene can be run using the just melpomene just recipe, or using cargo run --bin melpomene.

Pomelo is a web-based simulator, which runs the MnemOS kernel in the browser using WebAssembly. A hosted version of Pomelo can be found at https://anatol.versteht.es/mlem/.

Note

Some just recipes in the Justfile have additional build-time dependencies which must be installed on the user's system in order to run those recipes.

In order to automate installing (most of) these dependencies, the manganese tool provides a wrapper for just recipes that depends on all Rust build dependencies from crates.io as normal cargo deps. To run a just recipe using manganese, run:

cargo mn $RECIPE

rather than

just $RECIPE

where $RECIPE is the name of the desired just recipe.

Learn More

Development and API Docs

rustdoc output for the current main branch can be built locally with cargo doc --open.

• the MnemOS book, a high-level discussion of MnemOS' design
• hosted main branch API documentation for the kernel and other MnemOS crates
• a series of automatically-generated weekly updates, which track MnemOS implementation progress over time

Development Blogs

We've written a series of development blogs following the story of MnemOS' implementation. You can find them here:

• MnemOS Moment 1, by James Munns (2023-06-02)
• MnemOS Moment 2: Search for a Shell, by James Munns (2023-07-10)

Getting Involved

Join us on Matrix: #mnemos-dev:beeper.com

License

MIT + Apache 2.0.

Code of Conduct

The MnemOS project follows the Contributor Covenant Code of Conduct.