shibedrill/gila
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

Reorganize documentation

Browse Source
This commit is contained in:
August 2025-07-07 00:43:31 -04:00
parent d279e193ab
commit 2a7ececad1
Signed by: shibedrill
GPG Key ID: 5FE0CB25945EFAA2
9 changed files with 155 additions and 127 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
Makefile.toml
View File

@ -97,6 +97,7 @@ dependencies = []
condition = { files_modified = { input = [
# This will not depend on *every* binary we build.
# If we mount a disk later in boot we can store other binaries there.
"configs/server_config.toml"
], output = ["build/initramfs.tar.lzma"] }, fail_message = "(inputs unchanged)" }
dependencies = ["bins"]
script = '''
@ -107,7 +108,7 @@ script = '''
do
cp ${ARTIFACTDIR}/$bin build/initramfs/system/bin/
done
cp server_config.toml build/initramfs/system/cfg/
cp configs/server_config.toml build/initramfs/system/cfg/
tar -c --lzma -f build/initramfs.tar.lzma build/initramfs
'''
@ -115,7 +116,7 @@ script = '''
[tasks.iso]
condition = { files_modified = { input = [
"${ARTIFACTDIR}/kernel",
"limine.conf",
"configs/limine.conf",
"${LIMINEDIR}/limine-bios.sys",
"${LIMINEDIR}/limine-bios-cd.bin",
"${LIMINEDIR}/limine-uefi-cd.bin",
@ -126,7 +127,7 @@ script = '''
mkdir -p build/iso/boot/limine
mkdir -p build/iso/EFI/BOOT
cp -f limine.conf build/iso/
cp -f configs/limine.conf build/iso/
cp -f ${LIMINEDIR}/limine-bios.sys build/iso/boot/limine/
cp -f ${LIMINEDIR}/limine-bios-cd.bin build/iso/boot/limine/
cp -f ${LIMINEDIR}/limine-uefi-cd.bin build/iso/boot/limine/

88
README.md
View File

@ -3,13 +3,17 @@
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.
## Development
Information on the build system, repo structure, features, configuration options, supported architectures, design philosophies, and more, is available in the [docs](docs/) folder. If you want to build Gila for yourself, consider reading [DEVELOPMENT.md](docs/DEVELOPMENT.MD) for explicit instructions.
## Features
### Complete
- Builds for AArch64, RISCV64, x86_64, and LoongArch64
- Builds for `aarch64`, `riscv64`, `x86_64`, and `loongarch64`
- Valid Limine kernel
- Boots on `x86_64`
- Boots on `x86_64` (both UEFI and BIOS)
- Kernel command line parameters
- initramfs loading
- Logging
@ -22,6 +26,7 @@ Gila is a Rust microkernel OS, inspired by the Xinu embedded OS, as well as Linu
- Device discovery & APIs
- Power management
- Paging
- initramfs decompression & manifest parsing
### Future/Desired
@ -50,85 +55,6 @@ Gila is a Rust microkernel OS, inspired by the Xinu embedded OS, as well as Linu
Licensed under the GNU Public License v3. See [LICENSE](LICENSE) for details.
## Navigating
- [kernel/](src/kernel/): Kernel-specific code.
- [arch/](src/kernel/arch/): Architecture specific features like the display, serial, and interrupts. Each architecture is a subfolder, containing a file or module for each feature.
- [boot/](src/kernel/boot/mod.rs): Handles bootloader-managed data structures. Gila uses Limine. Other bootloaders are NOT supported.
- [params.rs](src/kernel/boot/params.rs): Command line parameter parsing.
- [modules.rs](src/kernel/boot/modules.rs): Kernel module handling.
- [constants.rs](src/kernel/constants.rs): Constants referenced elsewhere in the kernel.
- [device/](src/kernel/device/mod.rs): Functions for discovering hardware and assigning drivers.
-[acpi.rs](src/kernel/device/acpi.rs): ACPI handling functions and structures.
- [log.rs](src/kernel/log.rs): Logging structures, macros, and singletons for logging to serial or the display.
- [interrupt/](src/kernel/interrupt/mod.rs): Interrupt handlers with platform-agnostic APIs.
- [main.rs](src/kernel/main.rs): The entry point that gets called by the bootloader.
- [memory.rs](src/kernel/memory.rs): Types relating to memory regions and allocation.
- [panic.rs](src/kernel/panic.rs): The panic handler and associated functionality.
- [process.rs](src/kernel/process.rs): Process types and functions.
- [syscall_runner.rs](src/kernel/syscall_runner.rs): Chooses a system call by its ID and defers actual syscall execution to code in `src/lib/`.
- [lib/](src/lib/lib.rs): Library that all Gila's binary programs will be built against. Some of this code is shared with the kernel.
- [arch/](src/lib/arch/mod.rs): Architecture specific functionality like system call register storing/loading.
- [syscall.rs](src/lib/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](https://github.com/sagiegurari/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](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.
### Features
Gila has four optional features, which I made optional in anticipation of a potential future port to older systems like i686 which might not support modern standards like UEFI or ACPI. They are all enabled by default. Disabling them reduces kernel size and forces the kernel to fall back to other implementations for some functionality like device discovery.
- `acpi`: Advanced Configuration and Power Interface, for device discovery & power management
- `dtb`: Device Tree Blob, for device discovery in embedded systems
- `compression`: Compressed initramfs archive
- `uefi`: UEFI-specific bootloader features
## Kernel Parameters
Kernel parameters are passed as part of the `cmdline` through [limine.conf](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`
The `.lzma` extension is removed from the default initramfs name when compression is disabled.
## Credits
The linker script stuff is from [limine-rust-template](https://github.com/jasondyoungberg/limine-rust-template),

42
SECURITY.md
View File

@ -1,42 +0,0 @@
# Security
Part of the design philosophy that drives my inspiration for Gila is the idea of creating a new, fast, and safe kernel with security as a central focus. Kernels such as Linux, Mach, and NT have been around for too long to work perfectly with today's system security model. Gila is brand-new, and built almost exclusively in Rust for the utmost memory safety.
## Goals
- Distrustful by default
- Small, simple, and transparent
- Performant
- Capability based
- Highly isolated
## Gila's security model
### Microkernel architecture
Gila is a microkernel. Only the most important functionality runs at Ring 0 (Protected Mode) to reduce attack surface. This functionality includes:
- Modifying and reading kernel configurations
- Process creation and destruction
- Scheduling
- Memory allocation and management
- Inter-process communication
- Hardware communication interfaces
User processes perform complex functionality by interacting with server processes. Servers perform many different things:
- PCI(e)
- USB
- Security policy
- Filesystems
- Logins
A user process can be registered as a server by any process with the `ServerRegister` capability. The kernel takes the process's ID and a functionality type as arguments to the registration function. Registering is important, because it allows processes to discover the PIDs of server processes for IPC.
### Capabilities
Every process in Gila has a set of capabilities. These capabilities define the ways it may interact with the kernel's limited functions, and do not govern what it can do with any other userspace process.
### Access control
Access control will be accomplished by means of a "policy server" process, which is registered as a system server by the init process, and is given the authority (by means of its registration with the kernel being readable) to allow or deny specific resource accesses. The relevant server will submit the PID of the requesting process & the resource it desires to the security server, which will check the request against the process's rights, and return a verdict to the issuing server.

0
limine.conf → configs/limine.conf
View File

0
server_config.toml → configs/server_config.toml
View File

4
DESIGN.md → docs/DESIGN.md
View File

@ -11,7 +11,9 @@ Gila initializes as a bare kernel, with the bootloader providing an init RAM
filesystem in the form of a .tar.lzma archive. The kernel reads this file, and
launches an init process (`/system/bin/init`). The init process has its own
configuration file located at `/system/cfg/init.toml`, which should detail the
steps needed to bring the system up to a multi-user status.
steps needed to bring the system up to a multi-user status. This config file
will also contain versioning information for compatibility, detailing which
kernel version and architecture it is compatible with.
If the init system needs to access a filesystem, it must first get the handle
of the filesystem server. If the filesystem server is not running when this

98
docs/DEVELOPMENT.MD Normal file
View File

@ -0,0 +1,98 @@
# Developer Resources
## Design Goals & Philosophy
General design goals are outlined in [DESIGN.md](DESIGN.md). Security-relevant design details can be found in [SECURITY.md](SECURITY.md).
## Navigating
- [kernel/](src/kernel/): Kernel-specific code.
- [arch/](src/kernel/arch/): Architecture specific features like the display, serial, and interrupts. Each architecture is a subfolder, containing a file or module for each feature.
- [boot/](src/kernel/boot/mod.rs): Handles bootloader-managed data structures. Gila uses Limine. Other bootloaders are NOT supported.
- [params.rs](src/kernel/boot/params.rs): Command line parameter parsing.
- [modules.rs](src/kernel/boot/modules.rs): Kernel module handling.
- [constants.rs](src/kernel/constants.rs): Constants referenced elsewhere in the kernel.
- [device/](src/kernel/device/mod.rs): Functions for discovering hardware and assigning drivers.
-[acpi.rs](src/kernel/device/acpi.rs): ACPI handling functions and structures.
- [log.rs](src/kernel/log.rs): Logging structures, macros, and singletons for logging to serial or the display.
- [interrupt/](src/kernel/interrupt/mod.rs): Interrupt handlers with platform-agnostic APIs.
- [main.rs](src/kernel/main.rs): The entry point that gets called by the bootloader.
- [memory.rs](src/kernel/memory.rs): Types relating to memory regions and allocation.
- [panic.rs](src/kernel/panic.rs): The panic handler and associated functionality.
- [process.rs](src/kernel/process.rs): Process types and functions.
- [syscall_runner.rs](src/kernel/syscall_runner.rs): Chooses a system call by its ID and defers actual syscall execution to code in `src/lib/`.
- [lib/](src/lib/lib.rs): Library that all Gila's binary programs will be built against. Some of this code is shared with the kernel.
- [arch/](src/lib/arch/mod.rs): Architecture specific functionality like system call register storing/loading.
- [syscall.rs](src/lib/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](https://github.com/sagiegurari/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](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`. Options are listed [here](#targets).
- 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.
### Features
Gila has four optional features, which I made optional in anticipation of a potential future port to older systems which might not support modern standards like UEFI or ACPI. They are all enabled by default. Disabling them reduces kernel size and forces the kernel to fall back to other implementations for some functionality like device discovery.
- `acpi`: Advanced Configuration and Power Interface, for device discovery & power management
- `dtb`: Device Tree Blob, for device discovery in embedded systems
- `compression`: Compressed initramfs archive
- `uefi`: Universal Extensible Firmware Interface specific bootloader features
### Targets
Gila currently supports four different CPU architectures:
- `x86_64`
- `aarch64`
- `riscv64`
- `loongarch64`
All these architectures are supported by Limine, and the appropriate backends are present in the Makefile to compile and build bootable images for each. While Limine and rustc also support `IA32` (also referred to as `i686`), support is missing from the [Limine crate](https://crates.io/crates/limine). Compilation will fail if a build for an unsupported target is attempted.
EFI boot is presently supported, at least on `x86_64`. No features depend on EFI, and as such, the `uefi` feature can be safely disabled when booting through BIOS.
## Kernel Parameters
Kernel parameters are passed as part of the `cmdline` through [limine.conf](configs/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`
The `.lzma` extension is removed from the default initramfs name when compression is disabled. It must also be changed in [limine.conf](configs/limine.conf) or else Limine will not load it.

40
docs/SECURITY.md Normal file
View File

@ -0,0 +1,40 @@
# Security
Part of the design philosophy that drives my inspiration for Gila is the idea of creating a new, fast, and safe kernel with security as a central focus. Kernels such as Linux, Mach, and NT have been around for too long to work perfectly with today's system security model. Gila is brand-new, and built almost exclusively in Rust for the utmost memory safety.
## Goals
- Distrustful by default
- Small, simple, and transparent
- Performant
- Capability based
- Highly isolated
## Gila's security model
### Microkernel architecture
Gila is a microkernel. Only the most important functionality runs at Ring 0
(Protected Mode) to reduce attack surface. This functionality includes:
- Modifying and reading kernel configurations
- Process creation and destruction
- Scheduling
- Memory allocation and management
- Inter-process communication
- Hardware communication interfaces
User processes perform complex functionality by interacting with server
processes. Servers perform many different things:
- PCI(e)
- USB
- Security policy
- Filesystems
- Logins
### Capability based MAC
Eventually, once Gila is complex enough to need access control, I would like to
implement support for capability-based mandatory access control. Details will
be decided on once more APIs are stabilized.

3
src/kernel/arch/mod.rs
View File

@ -1,6 +1,9 @@
// Copyright (c) 2025 shibedrill
// SPDX-License-Identifier: GPL-3.0-or-later
#[cfg(not(any(target_arch = "x86_64", target_arch = "aarch64", target_arch = "riscv64", target_arch = "loongarch64")))]
compile_error!("Gila does not support compiling for this architecture! Supported architectures are: x86_64, aarch64, riscv64, loongarch64");
#[cfg(target_arch = "x86_64")]
pub mod x86_64;
#[cfg(target_arch = "x86_64")]