managarm / managarm

Pragmatic microkernel-based OS with fully asynchronous I/O

The managarm Operating System

What is this about?

This is the main repository of managarm, a microkernel-based operating system.

What is special about managarm? Some notable properties of managarm are: (i) managarm is based on a microkernel while common Desktop operating systems like Linux and Windows use monolithic kernels, (ii) managarm uses a completely asynchronous API for I/O and (iii) despite those internal differences, managarm provides good compatibility with Linux at the user space level.

Aren't microkernels slow? Microkernels do have some performance disadvantages over monolithic kernels. managarm tries to mitigate some of those issues by providing good abstractions (at the driver and system call levels) that allow efficient implementations of common user space functionality (like POSIX).

Is this a Linux distribution? No, managarm runs its own kernel that does not originate from Linux. While the managarm user space API supports many Linux APIs (e.g. epoll, timerfd, signalfd or tmpfs), managarm does not share any source code (or binaries) with the Linux kernel.

Official Discord server: https://discord.gg/7WB6Ur3. This is our primary real-time communication channel.

Official IRC channel: #managarm on irc.libera.chat, with many more available! Type /msg alis list managarm to find them.

Features

• 64-bit operating system with SMP (i.e., multicore) and ACPI support.
• Fully asynchronous microkernel and servers.
• Support for many modern hardware devices such as USB 3 controllers.
• Networking support.
• POSIX and Linux API compatibility.
• Support for Linux-style special files (epoll, signalfd, ...) and pseudo file systems (/sys, /proc, ...).

Trying out managarm

If you want to try out managarm without building the whole OS, you can download a xz-compressed nightly image; these images are automatically compiled on our build server and reflect the current state of Managarm development. To run the (uncompressed) image using qemu, we recommend the following flags:

qemu-system-x86_64 -enable-kvm -m 2048 -cpu host,migratable=off -device qemu-xhci -device usb-kbd -device usb-tablet -drive id=hdd,file=image,format=raw,if=none -device virtio-blk-pci,drive=hdd -vga vmware -debugcon stdio

Supported Software

Programs supported on managarm include Weston (the Wayland reference compositor), kmscon (a system console), GNU Coreutils, Bash, nano and others.

Supported Hardware

General USB (UHCI, EHCI)
Graphics Generic VBE graphics, Intel G45, virtio GPU, Bochs VBE interface, VMWare SVGA
Input USB human interface devices, PS/2 keyboard and mouse
Storage USB mass storage devices, NVMe, AHCI, ATA, virtio block

Building managarm

While this repository contains managarm's kernel, its drivers and other core functionality, it is not enough to build a full managarm distribution. Instead, we refer to the Managarm Handbook for build instructions.

managarm's Issues

thor: WorkQueue should be per-cpu

The current approach is not thread-safe and cannot be made thread-safe without compromising scalability. Make WorkQueue per-cpu and let it handle priorities.

core/drm: Implement universal planes

This is a requirement for atomic modesetting. Weston 4.0 uses this feature if it is available.

thor: Implement PCIDs

PCIDs should give a significant performance boost to the OS as task switches are very frequent.

posix: VFS and device support

The posix subsystem lacks the following features:

• Character and block device allocation
• Proper VFS + mounts
• tmpfs and devtmpfs
• Process specific file system information (i.e. root, current directory and umask)
• Mount namespaces
• Proper support for major and minor numbers in device allocation
• Bind mounts

general: Write a README.md

Include a pretty screenshot, some explanation what managarm is (not), an overview of the programs that it can run and an overview of the hardware that we support.

thor: Implement a proper scheduler

Currently we only schedule cooperatively. We need to implement a scheduler that pays attention to different priorities and enables real-time tasks. This is required for timing-sensitive drivers.

hel: Missing futex features

We lack a bunch of important futex features:

• The futex API currently only accepts int futexes. Use unsigned int instead? Allow other data types / operation sizes?
• FutexWake does not have a "count" parameter (currently it wakes up all waiters).
• We do not have futex requeue operations.
• We do not have PI or robust futexes.
• Implement non-PI kernel based lock/trylock/unlock primitives? That would avoid possible starvation on NUMA system.
• Do we need asynchronous wait operations?

posix: Signals need to save FPU state

Currently, we only save GPRs; however, it is quite easy to call memcpy() from signal handlers (e.g. by calling mlibc POSIX primitives). memcpy() clobbers the FPU state.

posix: Implement SO_PEERCRED

wayland-server uses SO_PEERCRED to get the remote PID of a Wayland socket. Weston's desktop shell needs this information for correct Meta+k force killing.

posix: Private file mappings do not work

Private file mappings should be handled via CoW. While the kernel supports CoW, it is only invoked after fork(). Add a flag to helMapMemory to allow the construction of CoW mappings with fork.

thor: Implement remapping memory views

Implement memory views that can be dynamically remapped from user space. This allows us to implement complex device files (e.g. in the DRM core) as single memory views. In turn, this allows us to get rid of one context switch in the common Mesa/libgbm render path.

thor: Dispatch PCI interrupts in the kernel

Improve PCI interrupt handling by letting the kernel read all possible ISRs when a PCI interrupt happens. Then, provide a separate IRQ object to each driver that only reports the IRQs of the specific device.

thor: Uncached memory

The kernel needs to provide support for uncached and write-combining memory regions.

posix: Implement poll cancellation

pollStatus() cancellation would make epoll, poll and select interfaces more scalable.

thor: Handle page pinning - copy-on-write interaction

We had to disable CoW during the queue rework. Disable CoW only for pinned mappings or pages.

thor: Optimize insertion into current work queue

Currently, we lock the work queue on post(). That is not necessary for the work queue of the current thread. As wakeup() is not necessary either, tracking the current work queue properly in every context would be a good performance improvement.

posix: Support inotify for tmpfs

inotify is required for udevadm settle. An implementation for tmpfs would be sufficient for now.

drivers/libevbackend: Buffer events on a per-file basis

For correctness (i.e. Linux compatibility) we need to store one event buffer per open file.

core/virtio: Interpret ISR correctly and handle configuration changes

• Do not ack the interrupt if the ISR bit is zero
• Propagate configuration changes to the device driver
• Handle DEVICE_NEEDS_RESET configuration change

hel: Refactor queue construction interface

Currently, constant queue parameters are extracted from HelQueue which is unnecessary and requires an expensive user-space memory access from the kernel. Pass the constant values to the construction function instead.

general: Use libarch API to allocate DMA buffers

Inspect the drivers to check where this makes sense.

Some locations that need to be refactored:

• core/virtio: Performs manual contiguous allocations
• drivers/virtio: Use DMA API inside the block driver

thor: Log early boot messages to framebuffer

Currently, thor can log to VGA textmode, bochs' debugging port or the serial port. Add another option to log to a VBE framebuffer. This would require the inclusion of a nice (e.g. 8x16) bitmap font and possibly a two-column layout to be able to display more messages on one screen.

thor: Refactor HelQueue to avoid memory leak

The current HelQueue has various problems. This issue tracks the rework progress.

drivers: Support VTs

Virtual terminals (VTs) are not supported at the moment. Add a driver to provide a Linux-compatible ioctl() interface for VTs. Display the kernel log on one of the VTs.

thor: Implement reentrant logging from NMI handler

We currently deadlock if an NMI interrupts code that owns the logging mutex.

posix: Implement SIGCHLD and wait()

This is required for closing windows in Weston and for proper bash usage.

thor: Support variable chunk size

Currently, the HelChunk buffer size is fixed to the page size.

thor: Thread safety

Several kernel data structures and algorithms are not thread-safe.

• Memory objects are not protected by locks.
• Mapping objects need a better interface or need to be protected by RCU.
• The kernel does not perform proper TLB shootdown.
• Thread switching code needs to be safe in presence of maskable interrupts, NMI and MCE.

posix: Implement direct polling from mlibc over the FS protocol

This would allow us to get rid of one context switch for poll() operations that affect only one FD.

drivers/virtio: Block driver needs to check status code

We currently assume that all requests succeed. Check the status code and (in case of a non-legacy virtio transport) the number of bytes written.

thor: Reenable IRQ watchdog

Commit 333dc9e broke the IRQ watchdog: It was disabled because it runs in fiber; fibers are not available during early boot anymore. Fix this by starting the watchdog later in the boot process.

libarch: Make variable memory order strong by default

The current weak ordering (i.e. allowing the C compiler to reorder accesses) is not intuitive and should not be the default.

drivers/usb-hid: Respect maximal report size

Currently, we limit packets to the maximum packet size which can be smaller than the maximum report size. In other words, reports consisting of multiple packets are not supported right now.

posix: Signal support

Signal support is the most important ingredient that is missing for a fully functional shell.

thor: IRQ sequences can be lost

IRQ sequences are currently lost if the IRQ object is constructed after IRQs already happened.

general: Relative mouse movement is broken in some qemu versions

In particular, this happens with qemu 2.8.1 and the USB mouse and PS/2 devices.

thor: Measure RTC read time

The delay between update-in-progress clear and read completion should be measured. In theory, IRQs can interrupt the kernel fiber that performs the read, leading to a stale result. Warn and/or reread the RTC time if the delay was too large.

posix: Missing mkdir() and chroot()

We are missing quite a few important POSIX functions.

• File system: mkdir, chroot

posix: Refactor uevent framework

In particular, provide a general function to set basic uevent variables and handle the sequence numbering.

posix: Support SIG_DFL and SIG_IGN

This is required for proper signal handling, e.g. in bash.

drivers: Fallback DRM driver for VBE framebuffers

So far, we have no fallback driver in case none of our "real" graphics drivers are applicable.

thor: Perform ACPI enumeration of legacy devices

This allows us to completely avoid (system bus) device enumeration from user space.

core/drm: Implement cursor planes

This would increase performance on drivers like gfx/virtio.

thor: Implement cancelable timers

This feature would greatly improve timerfd performance.

thor: Interrupt NAK mechanism?

Implement some mechanism that determines if an interrupt was not accepted by any consumer. This should not happen in normal situations but will aid in debugging interrupt issues.

thor: Report OOM to user space

Currently we panic if the kernel runs OOM - this is certainly not the desired behavior.

general: USB tablet mouse clicks do not work correctly on all versions of qemu

How to reproduce: On qemu 2.8.1, windows cannot be moved in Weston when the USB tablet is used.

posix: Support flock() file locks

flock() is used to implement lock files (e.g. in wayland-server). We need an implementation to support this feature.

drivers/usb-hid: Support absolute input devices

Support absolute input devices (e.g. touchscreens, tablets). This is a major advantage for VMs as absolute devices allow seamless mouse integration.

For this to work, we need to support the EVIOCGABS ioctl in libevbackend. Some work on the USB HCDs might also be necessary.

core/drm: Consistently sort modes in all drivers

Currently, the order of the mode list depends on the driver. This affects the default resolution that Weston enters if no resolution is previously set.