MunkOS

MunkOS is an attempt to write a primarily educative, real-time operating system, which attempts to provide a playground for implementing simplified adaptations of state-of-the-art kernel design concepts found in publicly available research artifacts, for AMD64 based computers (and experimental support for ARMv8-A), that actually operates on real hardware successfully.

MunkOS's core consists of a preemptively multi-tasked, smp-enabled kernel. To improve code organization and portability, arch-specific is isolated from arch-agnostic code as much as reasonably possible. Various kernel subsystems are seperated from each other aswell, which helps with maintainability and makes debugging substantially easier.

Since I'm currently in the progress of rewriting the majority of the codebase, only the kernel (with yet quite little functionality), is being worked on, but you can look forward to userspace components soon.

Building

To make sure git submodules are correctly being fetched, clone the repo via

git clone --recurse-submodules https://github.com/Ruediga/MunkOS.git

or optionally, if you have cloned it shallowly beforehand, run

git submodule update --init --recursive

You're going to have the least problems using Linux distro (WSL may work too) to build from source yourself. Building requires the following packages, which you can install with your distros package manager (e.g. pacman or apt):

Arch / Manjaro (pacman)

sudo pacman -S git gcc make cmake xorriso gdisk curl python3 libtool meson pkg-config

Ubuntu / Debian / Mint (apt)

sudo apt install git gcc build-essential make cmake gdisk curl python3 libtool meson pkg-config

Another required package is xbstrap, which is available with pip:

pip install xbstrap

Debugging common issues

In case the xorriso installation fails under ubuntu hosts, try running sudo add-apt-repository universe and then sudo apt install xorriso again. In case pip complains about externally managed dependencies, refer to https://docs.python.org/3/library/venv.html.

You can then build for either armv8-a or amd64 by setting the environment variable MUNKOS_ARCH:

export MUNKOS_ARCH=x86_64
# or
export MUNKOS_ARCH=aarch64

make

in the projects root directory.

Images and qemu

To run munkos in a virtual machine, you can use these Make targets:

make run

I recommend looking at the qemu flags in Makefile if qemu decides to not work.

If the kernel crashes or something doesn't work for you when testing on real hardware, and you don't have the same hardware as I do, your pc is broken and you should demand a refund from the manufacturer.

Third party

Structure

.
├── build           -> per arch sysroot and binaries
├── kernel          -> kernel sources, includes and arch specific code
├── mlibc           -> a portable C standard library
├── patches         -> patches to be applied by xbstrap
├── tools           -> self explanatory
├── subprojects     -> meson subprojects
└── third-party     -> dependencies

Development Overview

Kernel

page frame descriptor table (pfdt)
buddy page frame allocator (pfa_)
slab kernel heap allocator (kha_)

Hardware

TODO

FIXME

Features

VM subsystem
IPL's
sched
processes

Long Term Goals

This project is intended as a platform to learn about hardware and conceptual ideas employed by many major operating systems and implement variations of these in a reduced manner.

"Just read the docs"
- A wise man

Ruediga / MunkOS