# differrari/redactedos architecture

> Architecture diagram of the GitHub repository differrari/redactedos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/differrari/redactedos
- Repository: https://github.com/differrari/redactedos

## Overview

##### Project type and purpose
– This is a monolithic, hobby operating system targeting 64-bit ARM hardware, currently running in QEMU.
– It consists of three main “layers”:
- Kernel (drivers, scheduler, syscalls, built-in processes)
- Shared library (static std, UI, math, syscalls wrappers)
- User processes (statically linked .elf binaries loaded from a disk image)

##### File structure
Top‐level:
- kernel/ – everything under the kernel executable: boot loader, subsystems (memory, filesystem, graphics, input, networking, PCI/virtio, process & syscall handling), built-in kernel processes
- shared/ – static library code (std containers, UI primitives, math, syscall stubs) used by both kernel processes and user processes
- user/ – sample user processes, linker script, Makefile; linked with shared/libshared.a into user.elf
- createfs, run, debug, rundebug scripts & Makefile – orchestrate build, disk image creation (fs/ → disk.img), QEMU invocation, GDB attachment

##### Extract architectural insights from the README
– Boot: boot.S + linker.ld → set up stack & memory map → jump to kernel_main in kernel/kernel.c
– Kernel_init in kernel_main sets up drivers (GPU via virtio, XHCI USB, console, timer/IRQ, memory allocator, filesystem layer), then spawns initial “kernel processes” (boot, monitor, window manager).
– User processes: built into fs image via createfs, loaded at runtime via ELF loader in kernel/process/loading
– Shared library is statically linked; syscalls form the ABI boundary between user and kernel.

a. Main components (use rectangular blocks):
1. Host Environment (macOS/Linux)
– ARM toolchain, Makefile, createfs/run/debug scripts
2. Build Pipeline
– gcc-aarch64 for kernel & user, linker (linker.ld), ar → libshared.a, createfs → disk.img
3. QEMU Virtual Hardware
– Emulated ARM64 CPU, RAM, PCI bus, virtio-blk, virtio-gpu, virtio-net, XHCI, serial console
4. Boot Loader
– kernel/boot.S + aboutboot.txt (DTB parsing)
5. Kernel (monolithic)
– Subsystems: Memory (MMU, page allocator, DMA), Filesystem (virtio_blk, exFAT driver), Graphics (framebuffer, GPU driver), Input (XHCI managers), Networking (virtio_net), PCI, Process & Syscall interface
6. Kernel Processes
– bootprocess, monitor, window_manager, desktop, login_screen, etc. (all under kernel/kernel_processes)
7. Shared Library (libshared.a)
– std containers & allocators, lightweight UI, math, syscall stubs
8. User Processes
– default_process and any .elf in fs/redos/user/ loaded by kernel at runtime

– Build Pipeline → kernel.elf & libshared.a & user.elf → QEMU
– QEMU → Boot Loader → Kernel_init
– Kernel → hardware subsystems (Memory, PCI/virtio, console, GPU, USB, network)
– Kernel ↔ Kernel Processes (invocation + in‐kernel scheduling)
– Kernel → ELF loader → User Processes
– User Processes → Syscall interface → Kernel
– Shared Library is linked at compile time into both kernel processes and user processes

c. Architectural patterns & design principles
– Monolithic kernel: all drivers & core services compiled into one image
– Single address space for kernel, strict syscall ABI boundary for userland
– Static linking for shared code → simple deployment on bare metal
– Use of Device Tree Blob (virt.dtb) for hardware description

d. Key technologies & frameworks
– ARM GNU toolchain (gcc, ld, as, objcopy)
– QEMU (ARM virtualization)
– VirtIO drivers for block, GPU, network
– ELF format for executables & dynamic loading
– exFAT filesystem driver
– C + C++ (kernel is predominantly C with some C++ drivers; shared & user use C++)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host Environment & Orchestration
    subgraph "Host Environment & Orchestration"
        BuildYML[".github/workflows/build.yml"]:::build
        TopMakefile["Makefile"]:::build
        CreateFS["createfs"]:::build
        RunScript["run"]:::build
        DebugScript["debug"]:::build
        RunDebug["rundebug"]:::build
    end

    %% Build Pipeline
    subgraph "Build Pipeline"
        KernelMake["kernel/Makefile"]:::build
        SharedMake["shared/Makefile"]:::build
        UserMake["user/Makefile"]:::build
        LinkerKernel["kernel/linker.ld"]:::build
        LinkerUser["user/linker.ld"]:::build
        Toolchain["ARM GNU toolchain"]:::build
        Artifacts["Artifacts:\nkernel.elf,\nlibshared.a,\nuser.elf"]:::build
    end

    %% Disk Image
    Disk["disk.img"]:::disk

    %% QEMU Hardware
    QEMU["QEMU Virtual Hardware"]:::hardware
    DTB["Device Tree Blob\n(virt.dtb,\nvirt.dts)"]:::dtb

    %% Boot Loader & Kernel Init
    BootLoader["Boot Loader\n(kernel/boot.S,\naboutboot.txt)"]:::kernel
    KernelInit["Kernel Init\n(kernel/kernel.c)"]:::kernel

    %% Kernel Monolithic
    subgraph "Kernel Subsystems"
        Memory["Memory Subsystem"]:::kernel
        Filesys["Filesystem Subsystem"]:::kernel
        Graphics["Graphics Subsystem"]:::kernel
        Input["Input Subsystem"]:::kernel
        Networking["Networking & PCI"]:::kernel
        ProcSys["Process & Syscall\n(kernels/process)"]:::kernel
    end

    %% Kernel Processes
    KernelProcs["Kernel Processes\n(boot, monitor,\nwindow_manager, etc.)"]:::kernelProc

    %% Shared Library & User
    SharedLib["Shared Library\n(libshared.a)"]:::shared
    UserProcs["User Processes\n(default_process, etc.)"]:::user

    %% Relationships
    BuildYML -->|invokes| TopMakefile
    TopMakefile -->|calls| KernelMake
    TopMakefile --> SharedMake
    TopMakefile --> UserMake
    KernelMake --> Toolchain
    SharedMake --> Toolchain
    UserMake --> Toolchain
    KernelMake --> LinkerKernel
    UserMake --> LinkerUser
    LinkerKernel --> Artifacts
    SharedMake --> Artifacts
    LinkerUser --> Artifacts
    Artifacts -->|createfs| Disk

    Disk -->|load FS| QEMU
    QEMU -->|provide DTB| DTB
    QEMU -->|boot| BootLoader
    DTB --> BootLoader
    BootLoader -->|jump to| KernelInit

    KernelInit --> Memory
    KernelInit --> Filesys
    KernelInit --> Graphics
    KernelInit --> Input
    KernelInit --> Networking
    KernelInit --> ProcSys
    KernelInit -->|spawn| KernelProcs

    ProcSys -->|ELF loader| UserProcs
    UserProcs -->|syscalls| ProcSys

    SharedLib -->|static link| KernelProcs
    SharedLib -->|static link| UserProcs

    %% Click Events
    click BuildYML "https://github.com/differrari/redactedos/blob/main/.github/workflows/build.yml"
    click TopMakefile "https://github.com/differrari/redactedos/tree/main/Makefile"
    click CreateFS "https://github.com/differrari/redactedos/tree/main/createfs"
    click RunScript "https://github.com/differrari/redactedos/tree/main/run"
    click DebugScript "https://github.com/differrari/redactedos/tree/main/debug"
    click RunDebug "https://github.com/differrari/redactedos/tree/main/rundebug"
    click KernelMake "https://github.com/differrari/redactedos/tree/main/kernel/Makefile"
    click SharedMake "https://github.com/differrari/redactedos/tree/main/shared/Makefile"
    click UserMake "https://github.com/differrari/redactedos/tree/main/user/Makefile"
    click LinkerKernel "https://github.com/differrari/redactedos/blob/main/kernel/linker.ld"
    click LinkerUser "https://github.com/differrari/redactedos/blob/main/user/linker.ld"
    click DTB "https://github.com/differrari/redactedos/blob/main/virt.dtb"
    click DTB "https://github.com/differrari/redactedos/blob/main/virt.dts"
    click BootLoader "https://github.com/differrari/redactedos/blob/main/kernel/boot.S"
    click BootLoader "https://github.com/differrari/redactedos/blob/main/kernel/aboutboot.txt"
    click KernelInit "https://github.com/differrari/redactedos/blob/main/kernel/kernel.c"
    click Memory "https://github.com/differrari/redactedos/blob/main/kernel/memory/mmu.c"
    click Memory "https://github.com/differrari/redactedos/blob/main/kernel/memory/page_allocator.c"
    click Memory "https://github.com/differrari/redactedos/blob/main/kernel/memory/kalloc.c"
    click Memory "https://github.com/differrari/redactedos/blob/main/kernel/memory/dma.c"
    click Memory "https://github.com/differrari/redactedos/blob/main/kernel/memory/memory_access.c"
    click Filesys "https://github.com/differrari/redactedos/blob/main/kernel/filesystem/disk.c"
    click Filesys "https://github.com/differrari/redactedos/blob/main/kernel/filesystem/exfat.c"
    click Filesys "https://github.com/differrari/redactedos/blob/main/kernel/filesystem/virtio_blk_pci.c"
    click Graphics "https://github.com/differrari/redactedos/blob/main/kernel/graph/graphics.cpp"
    click Graphics "https://github.com/differrari/redactedos/blob/main/kernel/graph/font8x8_bridge.c"
    click Graphics "https://github.com/differrari/redactedos/blob/main/kernel/graph/drivers/virtio_gpu_pci/virtio_gpu_pci.cpp"
    click Graphics "https://github.com/differrari/redactedos/blob/main/kernel/graph/drivers/ramfb_driver/ramfb.cpp"
    click Input "https://github.com/differrari/redactedos/blob/main/kernel/input/xhci.c"
    click Input "https://github.com/differrari/redactedos/blob/main/kernel/input/input_dispatch.c"
    click Input "https://github.com/differrari/redactedos/blob/main/kernel/input/xHCIDevice.cpp"
    click Input "https://github.com/differrari/redactedos/blob/main/kernel/input/xHCIManager.cpp"
    click Networking "https://github.com/differrari/redactedos/blob/main/kernel/networking/virtio_net_pci.c"
    click Networking "https://github.com/differrari/redactedos/blob/main/kernel/pci.c"
    click Networking "https://github.com/differrari/redactedos/blob/main/kernel/virtio/virtio_pci.c"
    click ProcSys "https://github.com/differrari/redactedos/blob/main/kernel/process/context_switch.S"
    click ProcSys "https://github.com/differrari/redactedos/blob/main/kernel/process/scheduler.c"
    click ProcSys "https://github.com/differrari/redactedos/blob/main/kernel/process/syscall.c"
    click ProcSys "https://github.com/differrari/redactedos/blob/main/kernel/process/syscall_as.S"
    click ProcSys "https://github.com/differrari/redactedos/blob/main/kernel/process/loading/elf_file.c"
    click ProcSys "https://github.com/differrari/redactedos/blob/main/kernel/process/loading/process_loader.c"
    click KernelProcs "https://github.com/differrari/redactedos/tree/main/kernel/kernel_processes/boot/"
    click KernelProcs "https://github.com/differrari/redactedos/tree/main/kernel/kernel_processes/monitor/"
    click KernelProcs "https://github.com/differrari/redactedos/tree/main/kernel/kernel_processes/windows/"
    click KernelProcs "https://github.com/differrari/redactedos/blob/main/kernel/kernel_processes/kprocess_loader.c"
    click SharedLib "https://github.com/differrari/redactedos/blob/main/shared/std/array.hpp"
    click SharedLib "https://github.com/differrari/redactedos/blob/main/shared/ui/UIElement.hpp"
    click SharedLib "https://github.com/differrari/redactedos/blob/main/shared/math/math.h"
    click SharedLib "https://github.com/differrari/redactedos/blob/main/shared/syscalls/syscalls.c"
    click UserProcs "https://github.com/differrari/redactedos/blob/main/user/default_process.c"
    click UserProcs "https://github.com/differrari/redactedos/blob/main/user/linker.ld"

    %% Styles
    classDef build fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef hardware fill:#F0F0F0,stroke:#888888,color:#444444
    classDef kernel fill:#FDDDDD,stroke:#D9534F,color:#D43F3A
    classDef kernelProc fill:#FDDDDD,stroke:#D9534F,color:#D43F3A
    classDef shared fill:#DFFFE0,stroke:#5CB85C,color:#4F8A10
    classDef user fill:#DFFFE0,stroke:#5CB85C,color:#4F8A10
    classDef disk fill:#FFEFD5,stroke:#D2691E,color:#8B4513
    classDef dtb fill:#FFF4E0,stroke:#E67E22,color:#D35400
```
