m5p

(matthew mirvish's miniature manipulator of many processes)

build

Uses CMake (the version on the 24.04 student servers is new enough), so something like

$ mkdir build
$ cd build
$ cmake ..  # (or -GNinja or -DCMAKE_BUILD_TYPE=Debug)
$ make      # (or ninja)
$ # do something with kernel8.img

will get you a kernel8.img file in the build/ folder (or wherever you decided to run cmake).

For more detailed usage/build instructions, see the report PDF submitted on LEARN. In particular:

• -DM5P_INITRD_BOOTSCRIPT=bootscript_train.inc will run the train demo required for K4. This should be the default, but if you are using an old checkout the default will only apply in a fresh build folder, so you may need to explicitly set this parameter.
• -DM5P_ASSUME_QEMU will fix bugs in QEMU (in case you decide to test on that platform). Note that since the clock server relies on SYSTIMER interrupts, you will need a version of QEMU that has been patched to forward these into the GIC (also the train UART will need to be wired up, as will an emulator...)
• -DM5P_LOG_LEVEL=log_verb or log_dbg will get you lots more debug prints. They should not directly interfere with performance measurements as the logs are sent via a separate userspace process and should not block (if messages come in fast enough, old ones are simply discarded.) The logs will not appear on screen - only when explicitly requested via dmesg (which will show all logs in the ringbuffer since boot.)
• -DFE_CONSOLE_WIDTH=<width> and -DFE_CONSOLE_HEIGHT=<height> set the console size

organization

• cmake/: assorted make helpers (toolchain definitions, linker nonsense)
• arch/: common headers related to AARCH64 (system register definitions; translation table helpers)
• boot/: initial boot routines (collectively the 'bootstub')
• kernel/: core microkernel
  • arch/: interrupt handling
  • common/: shared with boot/ for communicating memory layout
  • dbg/: infrastructure related to debugging, presently just the console
  • hw/: BCM2711-specific peripheral access/init
  • mt/: multi-tasking; context-switching, scheduling, synchronization, etc.
  • util/: helper datastructures (some of which are shared with userspace)
  • vm/: memory management, page table handling, allocators, etc.
• minlibc/: my very minimal libc. used by the kernel and bootstub, and currently also userspace
• user/: userspace programs + libraries
  • libm5p/: kernel library (syscall wrappers + some stuff from the kernel that's safe)
  • core/: core userspace programs, like the nameserver, clockserver, uart, and logwriter
  • marklin/: process controlling the trains
  • frontend/: process controlling the TUI
  • tests/: tools for testing the kernel or userspace, like the K3 clock demo
    • rps/: the RPS client/server
    • perf/: tools for measuring performance, like the send-reply-receive benchmark
  • ipl/: initial program loader; first process bootstrapped by kernel
    • initrd/: routines for packing userspace executables into the image, also a basic sever for "filesystem" contents
    • mod/: the kernel module it loads to handle process mappings
• report/: the source files for the report PDF

In general, the actual true "kernel" interface is in user/libm5p/include/m5p/sys.h, while the "global services" are provided around user/core/include/srv/*.h and other folders called srv/.