Mimiker: MIPS Micro-Kernel

An experiment with implementation of very simple operating system for Malta board.

Toolchain

To build Mimiker you will need a custom MIPS toolchain we use. You can download a binary debian package from here. It installs into /opt, so you'll need to add /opt/mipsel-mimiker-elf/bin to your PATH.

Otherwise, if you prefer to build the toolchain on your own, download crosstool-ng which we use for configuring the toolchain. You can get it from here. Then:

cd toolchain/mips/
ct-ng build

By default, this will build and install the mipsel-mimiker-elf toolchain to ~/local. Update your $PATH so that it provides mipsel-mimiker-elf-*, i.e. unless you've changed the install location you will need to append ~/local/mipsel-mimiker-elf/bin to your PATH.

Building

With toolchain in place, you are ready to compile Mimiker. Run

make

in project root. Currently two additional command-line options are supported:

• CLANG=1 - Use the Clang compiler instead of GCC (make sure you have it installed!).
• KASAN=1 - Compile the kernel with the KernelAddressSanitizer, which is a dynamic memory error detector.

For example, use make KASAN=1 command to create a GCC-KASAN build.

The result will be a mimiker.elf file containing the kernel image.

Running

We provide a Python script that simplifies running Mimiker OS. The kernel image is run with QEMU simulator. Several serial consoles are available for interaction. Optionally you can attach to simulator with gdb debugger. All of that is achieved by running all interactive sessions within tmux terminal multiplexer with default key bindings.

In project main directory, run command below that will start the kernel in test-run mode. To finish simulation simply detach from tmux session by pressing Ctrl+b and d (as in detach) keys. To switch between emulated serial consoles and debugger press Ctrl+b and corresponding terminal number.

./launch test=all

Some useful flags to the launch script:

• -h - Prints usage.
• -d - Starts simulation under a debugger.
• -D DEBUGGER - Selects debugger to use.
• -t - Bind simulator UART to current stdio.

Any other argument is passed to the kernel as a kernel command-line argument. Some useful kernel arguments:

• init=PROGRAM - Specifies the userspace program for PID 1. Browse bin and usr.bin directories for currently available programs.
• klog-quiet=1 - Turns off printing kernel diagnostic messages.

If you want to run tests please read this document.

Documentation

Useful sites:

• OSDev wiki

Toolchain documentation:

• Extensions to the C Language Family
• Debugging with GDB
• Linker scripts

MIPS documentation:

• MIPS® Architecture For Programmers Volume II-A: The MIPS32® Instruction Set
• MIPS® Architecture For Programmers Volume III: The MIPS32® and microMIPS32™ Privileged Resource Architecture
• MIPS32® 24KE™ Processor Core Family Software User’s Manual
• MIPS32® 24KEf™ Processor Core Datasheet
• Programming the MIPS32® 24KE™ Core Family
• MIPS® YAMON™ User’s Manual
• MIPS® YAMON™ Reference Manual
• MIPS ABI Project

Hardware documentation:

• MIPS® Malta™-R Development Platform User’s Manual
• Galileo GT–64120 System Controller
• Intel® 82371AB PCI-TO-ISA/IDE XCELERATOR (PIIX4)
• Am79C973: Single-Chip 10/100 Mbps PCI Ethernet Controller with Integrated PHY
• FDC37M81x: PC98/99 Compliant Enhanced Super I/O Controller with Keyboard/Mouse Wake-Up