gila/README.md

Gila v0.2.2 - 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

• Kernel command line parameters
• Display console (work in progress)
• Serial console (unstarted)
• Multi-architecture support:
  • aarch64: in progress
  • loongarch64: in progress
  • riscv64: in progress
  • x86_64: mostly complete

Licensing

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

Navigating

• arch/: Architecture specific features like the display, serial, and interrupts. Each architecture is a subfolder, containing a file or module for each feature.
• boot.rs: Handles bootloader-managed data structures. Gila uses Limine. Other bootloaders are NOT supported.
• lib.rs: Glue to make all files accessible from main.rs.
• log.rs: Logging structures and singletons for logging to serial or the display.
• 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.
• params.rs: Kernel parameter handler code.
• process.rs: Process types and functions.
• resources.rs: Resources that are accessible from multiple parts of the code.

Building and running

Building a bootable kernel is easy. All you need to do is run cargo build gila, and a valid, bootable Limine executable will be generated. However, it cannot be booted without installing it in a bootable Limine filesystem.

To build an ISO image that you can boot, there are several prerequisites:

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

Then run make to invoke the Makefile.

• make prepare: Installs needed Rust toolchain.
• make clean: Cleans all built files.
• make gila: Builds the kernel ELF file.
• make iso: Builds the bootable ISO with Limine installed.
• make run: Builds the ISO and boots it in QEMU.

By supplying TARGET=(rustc target triple) as an additional argument, you can change the architecture that gila will be compiled & run for. The default is x86_64-unknown-none.

You can install all these dependencies automatically by using nix-shell and supplying shell.nix as an argument.

TODO: The dockerfile is kinda broken and display forwarding does not work.

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.
• -logdev: A sequence of one or more values representing devices to log to. Current options are display and serial.

The default cmdline is:

-loglevel=INFO -logdev=display,serial

Credits

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