From 0ebe8e731ba20198c848ae7dda0769d9ff7dbe09 Mon Sep 17 00:00:00 2001 From: August Date: Thu, 13 Nov 2025 18:03:19 -0500 Subject: [PATCH] Documentation update --- docs/DESIGN.md | 48 ++++++++++++++++++++++++++++++++++++++++-------- docs/SECURITY.md | 29 +++++++++++++++++++++++++++++ 2 files changed, 69 insertions(+), 8 deletions(-) diff --git a/docs/DESIGN.md b/docs/DESIGN.md index 1f63f4f..3381b6b 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -6,17 +6,49 @@ functionality. The means by which processes will locate services is still up in the air as of right now, but I believe I want to implement something similar to (if not compatible with) D-Bus. +## Development Goals + +- No custom tooling: Gila should compile, build, and run, without any custom + languages, syntaxes, formats, emulators, build tools, frameworks, compilers, + etc. +- Easy to work on: Gila should be easy for developers to understand- not just + the kernel itself, but the way userspace works together, and the way an ISO + image is built by the build system. I want people to be able to easily write, + compile, install, and run a program within a bootable ISO. + +## Inspiration + +- [Linux](https://kernel.org): A highly featureful monolithic kernel, with + support for namespacing different kinds of resources. +- [The seL4 Microkernel](https://sel4.systems/): Formally verified, capability + based microkernel, setting the gold standard for secure kernels. Capable of + hosting virtual machines as well as normal processes. +- [Redox OS](https://www.redox-os.org/): Linux-compatible microkernel, written + almost entirely in Rust. +- [Fuchsia's Zircon Kernel](https://fuchsia.dev/): A new kernel and OS by + Google, which aims to replace the Linux kernel within Android. Features a + really cool component model for applications/system services. + ## Boot Process -Gila initializes as a bare kernel, with the bootloader providing an init RAM -filesystem in the form of a .tar.lzma archive. +After being initialized by the bootloader at a random address, the kernel will +perform some memory management work to start allocating memory for the userboot +binary. Userboot is a binary executable that will be loaded as a module, and +it will be initialized as the very first process. -To avoid having to implement things like LZMA, TAR, and ELF parsing into the -kernel proper, Gila will use a compiled-in stub program as its first process. -This process will perform the necessary functionality to scan the initramfs, -read config files, load executables into memory, and start processes. This is -inspired by the Zircon microkernel's userboot setup. This userboot binary is -responsible for starting the proper init system. +> [!INFO] +> The Userboot concept was taken from the Zircon kernel, used in Google's +> Fuchsia OS. + +Userboot has only one job, and that is to parse the compressed initramfs image +and start the true init system based on the contents of that image. After that, +it can exit. This approach eliminates a lot of code from the kernel, since we +don't have to parse ELF files or perform decompression in-kernel. + +The init system will rely only on a small set of kernel & userboot APIs to +bring up other "system software". Userboot will be treated as a part of the +kernel, effectively, allowing the user to build userspace initramfs archives +without having to recompile the kernel. The benefit of this approach is threefold: diff --git a/docs/SECURITY.md b/docs/SECURITY.md index a7e33b7..4c15aeb 100644 --- a/docs/SECURITY.md +++ b/docs/SECURITY.md @@ -73,6 +73,35 @@ introduces a serious security risk, as any compromise or failure of the login server could result in security failures, resource exhaustion, denial of service, or other undesirable events, affecting all other users on the system. +### Realms + +A complete OS using the Gila microkernel will consist of four "realms". Each +realm depends on the realm preceeding it. + +- Kernel Realm: The kernel itself, providing MMIO pages to the Driver Realm +- Driver Realm: Driver processes supplying interfaces to the Service Realm +- Service Realm: System services, supplying services like filesystems to the + User Realm +- User realm: User services/apps, running at the least privileged level + +Typically, for a secure deployment of an OS designed for a focused purpose, +one has no real need to dynamically modify the Service Realm, Driver Realm, or +Kernel Realm. So to simplify the deployment, the Driver and Service realms can +be contained in the kernel's initramfs. + +For embedded use, or for virtual appliances, the User Realm can additionally be +embedded in the initramfs. This eliminates the need for verifying or decrypting +a hard disk, or loading information from the network. Of course, volatile +information can still be stored on a hard drive, but the mission critical +pieces of code can be stored in a read-only format until the system needs to be +updated. + +Furthermore, the signatures of the kernel and any kernel modules can be +calculated and stored in the Limine config file, whose hash can be embedded in +the bootloader itself for use with Secure Boot. This quickly establishes +hardware-based root-of-trust for the kernel and all realms stored in the +initramfs. + ### Namespaces Namespaces will be a critical part of how process isolation works. Details are