# guillembrasco-sudo/oss architecture

> Architecture diagram of the GitHub repository guillembrasco-sudo/oss, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/guillembrasco-sudo/oss
- Repository: https://github.com/guillembrasco-sudo/oss

## Overview

This repository is a custom operating system. Its principal boot workflow initializes CPU and interrupt support, physical and virtual memory, firmware and devices, then starts scheduling and user initialization before entering an interruptible polling loop. The tree also shows distinct filesystem, networking, graphics, and window-system capabilities. Relationships are limited to calls visible in the boot excerpt, the PMM excerpt, and the HAL memory excerpts; unsampled subsystems are shown without speculative links.

Main entry points: [`kernel/main.c`](https://github.com/guillembrasco-sudo/oss/blob/main/kernel/main.c) (Kernel initialization), [`mm/pmm.c`](https://github.com/guillembrasco-sudo/oss/blob/main/mm/pmm.c) (Physical memory), [`hal/cpu/cpuid.h`](https://github.com/guillembrasco-sudo/oss/blob/main/hal/cpu/cpuid.h) (CPU detection), [`include/mm/pmm.h`](https://github.com/guillembrasco-sudo/oss/blob/main/include/mm/pmm.h) (PMM interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Platform and boot"]
  node_boot["Kernel initialization<br/>[main.c]"]
  node_hal["Hardware abstraction<br/>[hal.c]"]
  node_cpu_features["CPU features<br/>[cpu_features.h]"]
  node_cpu_probe["CPU detection<br/>[cpuid.h]"]
  node_hal_memory["Memory routines<br/>[hal_mem.c]"]
  node_interrupts["Interrupt support<br/>[interrupt.h]"]
  node_firmware["ACPI firmware<br/>[acpi.c]"]
end

subgraph group_memory["Memory management"]
  node_pmm["Physical memory<br/>[pmm.c]"]
  node_pmm_api["PMM interface<br/>[pmm.h]"]
  node_paging["Architecture paging<br/>[paging.c]"]
  node_vmm["Virtual memory<br/>[vmm.c]"]
  node_heap["Kernel heap<br/>[kheap.c]"]
end

subgraph group_kernel["Kernel services"]
  node_scheduler["Scheduler<br/>[sched.c]"]
  node_processes["Processes and syscalls<br/>[process.c]"]
end

subgraph group_devices["Devices and networking"]
  node_pci["PCI bus<br/>[pci.c]"]
  node_network["Network stack<br/>[stack.c]"]
  node_virtio_net["VirtIO networking<br/>[virtio_net.c]"]
  node_gpu["GPU and DRM<br/>[drm.c]"]
end

subgraph group_user["Filesystems and user interface"]
  node_filesystem["VFS and filesystems<br/>[vfs.c]"]
  node_ramfs["RAM filesystem<br/>[ramfs.c]"]
  node_window_system["Window system<br/>[window_system.c]"]
  node_compositor["User compositor<br/>[compositor.c]"]
  node_user_init["User initialization<br/>[init.c]"]
end

node_bootloader(("Bootloader"))

node_bootloader -->|"enters"| node_boot
node_boot -->|"initializes"| node_hal
node_hal_memory -->|"detects features"| node_cpu_probe
node_cpu_probe -->|"fills"| node_cpu_features
node_boot -->|"sets up"| node_interrupts
node_boot -->|"initializes"| node_pmm
node_pmm -->|"implements"| node_pmm_api
node_boot -->|"initializes"| node_vmm
node_boot -->|"uses address mapping"| node_paging
node_boot -->|"initializes"| node_heap
node_boot -->|"initializes"| node_firmware
node_boot -->|"scans"| node_pci
node_boot -->|"initializes runtime"| node_network
node_boot -->|"initializes and polls"| node_virtio_net
node_boot -->|"initializes GPU"| node_gpu
node_boot -->|"initializes VFS"| node_filesystem
node_boot -->|"initializes"| node_ramfs
node_boot -->|"initializes windows"| node_window_system
node_boot -->|"initializes"| node_scheduler
node_boot -->|"starts user services"| node_user_init
node_pmm -->|"exposes"| node_pmm_api

click node_boot "https://github.com/guillembrasco-sudo/oss/blob/main/kernel/main.c"
click node_hal "https://github.com/guillembrasco-sudo/oss/blob/main/hal/hal.c"
click node_cpu_features "https://github.com/guillembrasco-sudo/oss/blob/main/include/hal/cpu_features.h"
click node_cpu_probe "https://github.com/guillembrasco-sudo/oss/blob/main/hal/cpu/cpuid.h"
click node_hal_memory "https://github.com/guillembrasco-sudo/oss/blob/main/include/hal/hal_mem.c"
click node_interrupts "https://github.com/guillembrasco-sudo/oss/blob/main/include/kernel/interrupt.h"
click node_pmm "https://github.com/guillembrasco-sudo/oss/blob/main/mm/pmm.c"
click node_pmm_api "https://github.com/guillembrasco-sudo/oss/blob/main/include/mm/pmm.h"
click node_paging "https://github.com/guillembrasco-sudo/oss/blob/main/arch/x86_64/paging.c"
click node_vmm "https://github.com/guillembrasco-sudo/oss/blob/main/mm/vmm.c"
click node_heap "https://github.com/guillembrasco-sudo/oss/blob/main/mm/kheap.c"
click node_scheduler "https://github.com/guillembrasco-sudo/oss/blob/main/kernel/sched.c"
click node_processes "https://github.com/guillembrasco-sudo/oss/blob/main/kernel/process.c"
click node_firmware "https://github.com/guillembrasco-sudo/oss/blob/main/firmware/acpi/acpi.c"
click node_pci "https://github.com/guillembrasco-sudo/oss/blob/main/drivers/bus/pci.c"
click node_network "https://github.com/guillembrasco-sudo/oss/blob/main/drivers/net/stack.c"
click node_virtio_net "https://github.com/guillembrasco-sudo/oss/blob/main/drivers/net/virtio_net.c"
click node_gpu "https://github.com/guillembrasco-sudo/oss/blob/main/drivers/gpu/drm/drm.c"
click node_filesystem "https://github.com/guillembrasco-sudo/oss/blob/main/fs/vfs.c"
click node_ramfs "https://github.com/guillembrasco-sudo/oss/blob/main/fs/ramfs.c"
click node_window_system "https://github.com/guillembrasco-sudo/oss/blob/main/kernel/window/window_system.c"
click node_compositor "https://github.com/guillembrasco-sudo/oss/blob/main/user/display/compositor.c"
click node_user_init "https://github.com/guillembrasco-sudo/oss/blob/main/user/init.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_boot,node_hal,node_cpu_features,node_cpu_probe,node_hal_memory,node_interrupts,node_firmware toneBlue
class node_pmm,node_pmm_api,node_paging,node_vmm,node_heap toneAmber
class node_scheduler,node_processes toneMint
class node_pci,node_network,node_virtio_net,node_gpu toneRose
class node_filesystem,node_ramfs,node_window_system,node_compositor,node_user_init,node_bootloader toneIndigo
```

## Components

### Platform and boot

- [Kernel initialization](https://github.com/guillembrasco-sudo/oss/blob/main/kernel/main.c): `kernel/main.c`
- [Hardware abstraction](https://github.com/guillembrasco-sudo/oss/blob/main/hal/hal.c): `hal/hal.c`
- [CPU features](https://github.com/guillembrasco-sudo/oss/blob/main/include/hal/cpu_features.h): `include/hal/cpu_features.h`
- [CPU detection](https://github.com/guillembrasco-sudo/oss/blob/main/hal/cpu/cpuid.h): `hal/cpu/cpuid.h`
- [Memory routines](https://github.com/guillembrasco-sudo/oss/blob/main/include/hal/hal_mem.c): `include/hal/hal_mem.c`
- [Interrupt support](https://github.com/guillembrasco-sudo/oss/blob/main/include/kernel/interrupt.h): `include/kernel/interrupt.h`
- [ACPI firmware](https://github.com/guillembrasco-sudo/oss/blob/main/firmware/acpi/acpi.c): `firmware/acpi/acpi.c`

### Memory management

- [Physical memory](https://github.com/guillembrasco-sudo/oss/blob/main/mm/pmm.c): `mm/pmm.c`
- [PMM interface](https://github.com/guillembrasco-sudo/oss/blob/main/include/mm/pmm.h): `include/mm/pmm.h`
- [Architecture paging](https://github.com/guillembrasco-sudo/oss/blob/main/arch/x86_64/paging.c): `arch/x86_64/paging.c`
- [Virtual memory](https://github.com/guillembrasco-sudo/oss/blob/main/mm/vmm.c): `mm/vmm.c`
- [Kernel heap](https://github.com/guillembrasco-sudo/oss/blob/main/mm/kheap.c): `mm/kheap.c`

### Kernel services

- [Scheduler](https://github.com/guillembrasco-sudo/oss/blob/main/kernel/sched.c): `kernel/sched.c`
- [Processes and syscalls](https://github.com/guillembrasco-sudo/oss/blob/main/kernel/process.c): `kernel/process.c`

### Devices and networking

- [PCI bus](https://github.com/guillembrasco-sudo/oss/blob/main/drivers/bus/pci.c): `drivers/bus/pci.c`
- [Network stack](https://github.com/guillembrasco-sudo/oss/blob/main/drivers/net/stack.c): `drivers/net/stack.c`
- [VirtIO networking](https://github.com/guillembrasco-sudo/oss/blob/main/drivers/net/virtio_net.c): `drivers/net/virtio_net.c`
- [GPU and DRM](https://github.com/guillembrasco-sudo/oss/blob/main/drivers/gpu/drm/drm.c): `drivers/gpu/drm/drm.c`

### Filesystems and user interface

- [VFS and filesystems](https://github.com/guillembrasco-sudo/oss/blob/main/fs/vfs.c): `fs/vfs.c`
- [RAM filesystem](https://github.com/guillembrasco-sudo/oss/blob/main/fs/ramfs.c): `fs/ramfs.c`
- [Window system](https://github.com/guillembrasco-sudo/oss/blob/main/kernel/window/window_system.c): `kernel/window/window_system.c`
- [User compositor](https://github.com/guillembrasco-sudo/oss/blob/main/user/display/compositor.c): `user/display/compositor.c`
- [User initialization](https://github.com/guillembrasco-sudo/oss/blob/main/user/init.c): `user/init.c`

### Other components

- **Bootloader**

## Connections

- Bootloader → Kernel initialization: enters (evidence: `kernel/main.c`)
- Kernel initialization → Hardware abstraction: initializes (evidence: `kernel/main.c`)
- Memory routines → CPU detection: detects features (evidence: `include/hal/hal_mem.c`)
- CPU detection → CPU features: fills (evidence: `hal/cpu/cpuid.h`)
- Kernel initialization → Interrupt support: sets up (evidence: `kernel/main.c`)
- Kernel initialization → Physical memory: initializes (evidence: `kernel/main.c`)
- Physical memory → PMM interface: implements (evidence: `mm/pmm.c`)
- Kernel initialization → Virtual memory: initializes (evidence: `kernel/main.c`)
- Kernel initialization → Architecture paging: uses address mapping (evidence: `kernel/main.c`)
- Kernel initialization → Kernel heap: initializes (evidence: `kernel/main.c`)
- Kernel initialization → ACPI firmware: initializes (evidence: `kernel/main.c`)
- Kernel initialization → PCI bus: scans (evidence: `kernel/main.c`)
- Kernel initialization → Network stack: initializes runtime (evidence: `kernel/main.c`)
- Kernel initialization → VirtIO networking: initializes and polls (evidence: `kernel/main.c`)
- Kernel initialization → GPU and DRM: initializes GPU (evidence: `kernel/main.c`)
- Kernel initialization → VFS and filesystems: initializes VFS (evidence: `kernel/main.c`)
- Kernel initialization → RAM filesystem: initializes (evidence: `kernel/main.c`)
- Kernel initialization → Window system: initializes windows (evidence: `kernel/main.c`)
- Kernel initialization → Scheduler: initializes (evidence: `kernel/main.c`)
- Kernel initialization → User initialization: starts user services (evidence: `kernel/main.c`)
- Physical memory → PMM interface: exposes (evidence: `mm/pmm.c`)
