petitstrawberry/scarlet

1. Repository shape

This is a monorepo for an operating-system stack, not just a kernel. The top-level split is: kernel/ for the OS core, user/ for userspace libraries and programs, drivers/ for reusable device-driver crates, modules/ for loadable kernel modules, bundles/ and projects/ for bootable image definitions, and tools/ / scripts/ for build and deployment automation.

2. Boot and system image boundary

Scarlet boots through the Limine boot protocol on both AArch64 and RISC-V 64. The projects/* and bundles/* trees define the bootable layouts: kernel + initramfs/rootfs + system configuration + userspace binaries. The kernel/lds/ and project-specific linker scripts control final image layout, while docs/boot/ and docs/architecture/ describe the target boot and memory model.

3. Kernel core responsibilities

The kernel/ crate is the central runtime. It contains task scheduling, memory management, VFS, IPC, networking, syscalls, signal/process handling, and device management. This kernel is designed to host multiple ABIs natively and to expose the same underlying kernel objects to all of them.

4. Multi-ABI execution model

A key architectural boundary is the ABI layer under kernel/src/abi/. Scarlet native, xv6, and partial Linux support are implemented as separate ABI modules, but they share common kernel subsystems such as VFS, task objects, pipes, sockets, and memory mappings. The kernel selects behavior based on the binary format / ABI being launched, which is what enables cross-ABI piping and container-like coexistence.

5. Architecture-specific execution paths

kernel/src/arch/aarch64/ and kernel/src/arch/riscv64/ hold CPU-specific boot, trap, interrupt, timer, MMU, FPU, and context-switch logic. These platform layers adapt the shared kernel to the actual machine. The repo also includes architecture-specific targets under kernel/targets/ and user/targets/, indicating separate build outputs for kernel and userspace.

6. Device model and driver split

The kernel has an internal device abstraction layer under kernel/src/device/, while reusable low-level driver implementations live under kernel/src/drivers/ and the standalone drivers/ workspace crates. This separation lets the kernel talk to generic devices like block, char, graphics, input, network, USB, PCI, and power while arch- or platform-specific drivers bind to actual hardware or virtio devices.

7. Filesystem and container isolation

VFS v2 is a major subsystem (kernel/src/fs/vfs_v2/) with drivers for tmpfs, cpiofs, devfs, devpts, ext2, fat32, overlayfs, and initramfs. The filesystem layer is tied to container isolation through mount namespaces, bind mounts, and overlay behavior. In practice, this is where rootfs images, initramfs content, and per-task filesystem views converge.

8. Task, object, and IPC layer

Process-like execution is managed by kernel/src/task/ and kernel/src/sched/, while kernel/src/object/ provides capability-oriented handles for files, sockets, memory mappings, selectable objects, streams, and introspection. IPC is a first-class subsystem (pipe, event, shared_memory, counter), and user-space programs depend on these shared kernel objects for composition across ABI boundaries.

9. Networking stack

The kernel includes a full protocol stack under kernel/src/network/ with Ethernet, ARP, IPv4, ICMP, UDP, TCP, local sockets, and syscall bindings. Driver integration is primarily through virtio networking and the common socket/file abstractions, which makes networking part of the same cross-ABI resource model as files and pipes.

10. Graphics, input, and desktop pipeline

Graphics support flows from device drivers into the kernel graphics manager and framebuffer/display abstractions, then out to userspace windowing services. The desktop stack is split across user/bin/src/sws*, user/bin/src/sas*, user/bin/src/stemd/desktop.rs, and client libraries under user/lib/sws-client and user/lib/slint-scarlet. This forms the window compositor, input routing, and UI protocol boundary.

11. Userspace platform libraries and apps

user/lib/ contains the runtime and system libraries used by applications: Scarlet OS FFI and handles, syscalls, sockets, IPC, polling, time, hypervisor support, GUI/windowing clients, and package management. user/bin/ contains the actual executables and services: shell, login, networking tools, desktop components, compositor, resolver, package manager, and various demo/test programs. These binaries are the main consumers of the kernel ABI surface.

12. Service management and system initialization

System startup is coordinated by stemd and service definitions in bundles/*/fs/system/scarlet/etc/stemd.d/ and corresponding userspace implementations in user/bin/src/stemd/. Services include networking configuration, login, resolver, desktop compositor, and input/bridge services. The architecture resembles a small service graph rather than a single monolithic init process.

13. Hypervisor and guest support

Scarlet also contains an experimental built-in hypervisor under kernel/src/hypervisor/ and architecture-specific virtual-machine support in kernel/src/arch/*/hv/. The guest_tests/ directory and user/bin/src/ushv/ show the guest-facing and device-model side of this subsystem. This is a distinct boundary from normal process execution: the kernel can run guests with separate virtual CPUs, memory, and device emulation.

14. Build, packaging, and deployment

The repo is built as a reproducible system with Nix flakes, cargo-make, and Docker support, while projects/ and bundles/ define concrete runtime images. tools/ holds image-building, guest-image, and deployment scripts; test-pkg/ and tools/scpm-pack/ support package creation; and CI workflows in .github/workflows/ automate build, test, and deployment. For an architecture diagram, these are the outer orchestration layers feeding the kernel/userspace images.