Gila v0.3.0 - a Rust Microkernel

Gila is a Rust microkernel OS, inspired by the Xinu embedded OS, as well as Linux. I aim to implement multitasking and different users for processes, and eventually a filesystem. I do not aim to make it POSIX-compatible, but it will likely end up sharing many features with POSIX operating systems.

Features

Complete

• Builds for AArch64, RISCV64, x86_64, and LoongArch64
• Valid Limine kernel
• Boots on x86_64
• Kernel command line parameters
• initramfs loading
• Logging
  • Serial output

In-Progress

• Display console
• Serial console
• Device discovery & APIs
• Power management
• Paging

Future/Desired

• Userspace binaries/processes
• Interprocess communication
• Driver server interface
• Interrupts and timers
• Context switching
• Process scheduling
• System calls (multi-convention?)
• Capability access control
• Simultaneous multiprocessing support
• Hypervisor functionality

Additional Future Features (Userspace)

• Device drivers
• Filesystem drivers
• Shell
• Standard system API
• Rust and C stdlib port
• Display/windowing
• Application sandboxing

Licensing

Licensed under the GNU Public License v3. See LICENSE for details.

Navigating

• kernel/: Kernel-specific code.
  • arch/: Architecture specific features like the display, serial, and interrupts. Each architecture is a subfolder, containing a file or module for each feature.
  • boot/: Handles bootloader-managed data structures. Gila uses Limine. Other bootloaders are NOT supported.
    • params.rs: Command line parameter parsing.
    • modules.rs: Kernel module handling.
  • constants.rs: Constants referenced elsewhere in the kernel.
  • device/: Functions for discovering hardware and assigning drivers. -acpi.rs: ACPI handling functions and structures.
  • log.rs: Logging structures, macros, and singletons for logging to serial or the display.
  • interrupt/: Interrupt handlers with platform-agnostic APIs.
  • main.rs: The entry point that gets called by the bootloader.
  • memory.rs: Types relating to memory regions and allocation.
  • panic.rs: The panic handler and associated functionality.
  • process.rs: Process types and functions.
  • syscall_runner.rs: Chooses a system call by its ID and defers actual syscall execution to code in src/lib/.
• lib/: Library that all Gila's binary programs will be built against. Some of this code is shared with the kernel.
  • arch/: Architecture specific functionality like system call register storing/loading.
  • syscall.rs: System call types common to apps and the kernel.

Building and running

Building a bootable kernel is easy. All you need to do is run cargo build --bin kernel, and a valid, bootable Limine executable will be generated. However, it cannot be booted without installing it in a bootable Limine filesystem, and it cannot do anything useful without an initramfs containing system servers, such as the init server and device drivers.

This project uses cargo-make to handle building ISOs and managing files not associated with Cargo. You need to install it before you can build an ISO automatically. To do so, you can run cargo install cargo-make. In addition, you will also need:

• rustup command installed
• limine command installed
• xorriso command installed
• qemu-system-{your target architecture} command installed (for running)

Then run cargo make to invoke the Makefile.toml.

• cargo make clean_all: Cleans all built binaries, libraries, initramfs files, and ISOs.
• cargo make lib: Builds libgila, the library that the kernel and user code are linked against.
• cargo make kernel: Builds the kernel ELF file.
• cargo make initramfs: Build the init archive.
• cargo make iso: Builds the bootable ISO with Limine installed.
• cargo make run: Builds the ISO and boots it in QEMU.
• cargo make debug: Launch the kernel in QEMU with debugging enabled, and start and connect GDB.

You do not need to clean any files after making changes. The lib, kernel, and iso tasks will automatically be rerun if their input files change.

Configuration

• Variable LIMINEDIR: Location of binary files for limine. Default is /usr/share/limine.
• Variable TARGET: rustc target triple to compile for. Default is x86_64-unknown-none.
• Argument -p: Rust build profile to use. Default is dev. Options are dev and release.

Note

The -p {profile} argument must go between cargo make and the task argument.

Kernel Parameters

Kernel parameters are passed as part of the cmdline through limine.conf. The parameters are passed as a space-delimited list of keys and values. Keys begin with a hyphen (-), and keys are separated from their values with equals signs (=). Keys can have a set of multiple values, separated by a comma (,). Gila does not currently support parameter values with spaces. That would require an actual parser.

List of current extant kernel parameters:

• -loglevel: Can be a number or string corresponding to a log level. Only one value supported. Current options are Disabled, Trace, Info, Warning, Error, and Critical. This parameter is case insensitive.
• -logdev: A sequence of one or more values representing devices to log to. Current options are display and serial. This parameter is case insensitive.
• -initramfs: A valid path to a module to serve as the initramfs (containing the init binary). Only one value supported. This parameter is case sensitive.

The default behavior for each parameter, when not supplied, is:

-loglevel=Info -initramfs=/boot/initramfs.tar.lzma

Credits

The linker script stuff is from limine-rust-template, which is available under the BSD 0-Clause License.