Grinch

Introduction

Grinch is a minimalist operating systems, mainly developed for educational and testing purposes. Grinch is designed to run on RISC-V platforms. It is able to run userspace processes (ELF format), and virtual machines. Userland applications shall have basic POSIX support. Therefore, grinch comes with its own minimalist libc implementation. For compatibility reasons, the syscall interface tries to be compatible with Linux as good as possible.

Grinch contains a minimalist Virtual Machine Monitor that is able to boot itself as virtual machine.

Anyway, don't expect anything to work.

General features

• Device Tree support
• Simple scheduler
• ELF Userland applications
• Minimalist driver model
• Minimalist VFS layer
• Virtual Machine Monitor
• GCOV support

Architectural support

RISC-V architecture

• RISC-V base platform:
  • RV64 and RV32 support
  • MMU support
    • SV32, SV39 and SV48 paging
    • SV39x and SV48x paging for VMs
  • SMP support (RV64 only)
  • RISC-V platform Timers
  • RISC-V PLIC interrupt controller
  • RISC-V SBI console
  • RISC-V H-Extension support
  • SBI support
  • H-Extensions

ARM64 architecture

• Work in Progress

General driver support

• UART
  • AXI uartlite
  • 8250/16550 UART
  • apbuart

Platform support

• Supported RISC-V boards:

  • riscv32
    • Virtual Target (qemu)
  • riscv64
    • Virtual Target (qemu)
    • Starfive VisionFive 2

• ARM64

  • Ongoing

Build & Installation

It is recommended to compile everything on your local machine with a cross compiler. You will need a cross toolchain and following requirements:

• dtc
• cpio
• qemu-system-riscv64
• riscv64-linux-gnu-
• Python3
• python-pillow

To clone grinch, run:

git clone https://github.com/lfd/grinch.git
cd grinch
git submodule update --init --recursive

For compiling grinch, simply run:

make

To select the target architecture (default riscv64):

make ARCH=riscv32

For additional debug output, run:

make DEBUG_OUTPUT=1

To enable GCOV coverage instrumentation, run:

make GCOV=1

To override the optimisation level (default is -O0), run:

make OPT=-O2

For verbose compiler output, run:

make V=1

This will create grinch.bin and user/initrd.cpio. grinch.bin is the loadable kernel image, which is directly loadable via Qemu on virtual targets, or via U-Boot on real platforms. user/initrd.cpio contains userland applications, as well as grinch itself (grinch is able to recursively boot itself as virtual machine).

Build settings (ARCH, OPT, GCOV, ...) passed on the command line are persisted to config.mk on the first invocation; subsequent invocations reuse them automatically. Hand-edit config.mk to change a setting, or run make mrproper to discard it (along with all build output).

For out-of-tree builds, pass O=:

make O=build ARCH=riscv32 OPT=-O2

A small Makefile shim is generated in build/, so afterwards you can work from the build directory directly:

cd build
make
make qemu
make mrproper

The source tree is checked for in-tree build artefacts and the OOT build refuses to proceed if any are found, to avoid VPATH silently picking them up. Run make mrproper in the source tree to clean it.

Demonstration in QEMU

For running grinch inside QEMU, simply run:

make qemu

For debugging grinch, you can attach with a debugger:

make qemudb

In a second terminal, run:

make debug

Grinch is also able to boot on Qemu via U-Boot. For booting grinch via U-Boot in Qemu, type:

make qemuu

Grinch Parameters

To pass parameters to grinch on real board, you can use the bootargs variable in U-Boot. Grinch parses those parameters. To pass parameters in Qemu, use:

make qemu QEMU_APPEND='"arg1=val1 arg2=val2"'

You can also adjust the number of Qemus CPUs:

make qemu QEMU_CPUS=4

Basic features:

Parameter	Values	Description
timer_hz	int	Timer frequency
loglevel	int	loglevel. Highest=0, Default=1
kheap_size	int	Kernel Heap size (e.g., 8M)
console	str	boot console (ttyS0)
init	str	init executable

Development features:

Parameter	Values	Description
memtest	/	Do memory test
malloc_fsck	/	Run sanity checker for kalloc
ttp_maxevents	int	No of maxevents for timed TPs

Authors & License

Grinch is developed by Ralf Ramsauer at OTH Regensburg. It is licensed under GPLv2. Parts of grinch are copied from Linux kernel sources. These parts involve:

• ctype implementation
• List implementation (list.h)
• Auxiliary headers (compiler_attributes.h, const.h, minmax.h)
• vsprintf support
• ELF headers
• strtox
• rwonce