# agf-b/badlands architecture

> Architecture diagram of the GitHub repository agf-b/badlands, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agf-b/badlands
- Repository: https://github.com/agf-b/badlands

## Overview

BadLands is an experimental x86-64 UEFI operating system. Its principal flow is firmware boot, bootloader preparation and kernel handoff, then kernel initialization and hardware/runtime services; users interact through keyboard input and the shell. The README documents memory management, ACPI, interrupts, PCIe/USB, storage, filesystems, scheduling, and framebuffer output. Several connections below are dashed because the relevant implementation excerpts were not provided; the shown xHCI-to-scheduler relationship is visible in the excerpt.

Main entry points: [`kernel/src/entry.cpp`](https://github.com/agf-b/badlands/blob/main/kernel/src/entry.cpp) (Kernel Entry), [`bootloader/src/entry.cpp`](https://github.com/agf-b/badlands/blob/main/bootloader/src/entry.cpp) (Boot Entry), [`kernel/src/devices/USB/xHCI/Controller.cpp`](https://github.com/agf-b/badlands/blob/main/kernel/src/devices/USB/xHCI/Controller.cpp) (xHCI Controller), [`bootloader/src/loader/kernel_loader.cpp`](https://github.com/agf-b/badlands/blob/main/bootloader/src/loader/kernel_loader.cpp) (Kernel Loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["UEFI Boot"]
  node_boot_entry["Boot Entry<br/>[entry.cpp]"]
  node_efi_fs["EFI Filesystem<br/>[efi_fs.cpp]"]
  node_kernel_loader["Kernel Loader<br/>[kernel_loader.cpp]"]
  node_loader_paging["Loader Paging<br/>[paging.cpp]"]
  node_acpi_probe["ACPI Discovery<br/>[acpi_check.cpp]"]
end

subgraph group_platform["Kernel Platform"]
  node_vm["Virtual Memory<br/>[VirtualMemory.cpp]"]
  node_physical_memory["Physical Memory<br/>[PhysicalMemory.cpp]"]
  node_acpi["ACPI Tables<br/>[Interface.cpp]"]
  node_pci["PCIe Enumeration<br/>[PCI.cpp]"]
  node_apic["APIC Interrupts<br/>[APIC.cpp]"]
  node_shared_memory["Shared Memory Primitives<br/>[defs.hpp]"]
end

subgraph group_devices["Device Drivers"]
  node_xhci["xHCI Controller<br/>[Controller.cpp]"]
  node_usb_hid["USB HID<br/>[Driver.cpp]"]
  node_usb_keyboard["USB Keyboard<br/>[Keyboard.cpp]"]
  node_ps2["PS/2 Keyboard<br/>[Controller.cpp]"]
  node_key_dispatch["Keyboard Dispatch<br/>[Multiplexer.cpp]"]
  node_storage["Block Storage<br/>[Device.cpp]"]
  node_usb_storage["USB Mass Storage<br/>[Driver.cpp]"]
end

subgraph group_runtime["Kernel Runtime"]
  node_kernel_entry["Kernel Entry<br/>[entry.cpp]"]
  node_scheduler["Task Scheduler<br/>[TaskManager.cpp]"]
end

subgraph group_io["Storage and Interface"]
  node_vfs["Virtual Filesystem<br/>[VFS.cpp]"]
  node_npfs["Nonpersistent FS<br/>[NPFS.cpp]"]
  node_shell["Shell Service<br/>[entry.cpp]"]
  node_framebuffer["Framebuffer Output<br/>[Framebuffer.cpp]"]
end

node_firmware(("UEFI Firmware"))
node_user(("System User"))

node_firmware -.->|"starts bootloader"| node_boot_entry
node_boot_entry -.->|"uses filesystem"| node_efi_fs
node_boot_entry -.->|"loads kernel"| node_kernel_loader
node_kernel_loader -.->|"maps kernel"| node_loader_paging
node_boot_entry -.->|"discovers ACPI"| node_acpi_probe
node_kernel_loader -.->|"hands off"| node_kernel_entry
node_kernel_entry -.->|"initializes memory"| node_vm
node_kernel_entry -.->|"initializes interrupts"| node_apic
node_kernel_entry -.->|"starts enumeration"| node_pci
node_kernel_entry -.->|"reads tables"| node_acpi
node_pci -.->|"detects controller"| node_xhci
node_xhci -->|"schedules updater"| node_scheduler
node_xhci -.->|"initializes devices"| node_usb_hid
node_usb_hid -.->|"handles keyboard"| node_usb_keyboard
node_ps2 -.->|"forwards key events"| node_key_dispatch
node_usb_keyboard -.->|"forwards key events"| node_key_dispatch
node_pci -.->|"discovers storage"| node_storage
node_xhci -.->|"supports mass storage"| node_usb_storage
node_usb_storage -.->|"provides block device"| node_storage
node_storage -.->|"serves filesystem"| node_vfs
node_vfs -.->|"mounts filesystem"| node_npfs
node_user -.->|"uses shell"| node_shell
node_shell -.->|"accesses files"| node_vfs
node_kernel_entry -.->|"initializes display"| node_framebuffer
node_kernel_entry -.->|"starts scheduling"| node_scheduler

click node_boot_entry "https://github.com/agf-b/badlands/blob/main/bootloader/src/entry.cpp"
click node_efi_fs "https://github.com/agf-b/badlands/blob/main/bootloader/src/efi/efi_fs.cpp"
click node_kernel_loader "https://github.com/agf-b/badlands/blob/main/bootloader/src/loader/kernel_loader.cpp"
click node_loader_paging "https://github.com/agf-b/badlands/blob/main/bootloader/src/loader/paging.cpp"
click node_acpi_probe "https://github.com/agf-b/badlands/blob/main/bootloader/src/loader/acpi_check.cpp"
click node_kernel_entry "https://github.com/agf-b/badlands/blob/main/kernel/src/entry.cpp"
click node_vm "https://github.com/agf-b/badlands/blob/main/kernel/src/mm/VirtualMemory.cpp"
click node_physical_memory "https://github.com/agf-b/badlands/blob/main/kernel/src/mm/PhysicalMemory.cpp"
click node_acpi "https://github.com/agf-b/badlands/blob/main/kernel/src/acpi/Interface.cpp"
click node_pci "https://github.com/agf-b/badlands/blob/main/kernel/src/pci/PCI.cpp"
click node_apic "https://github.com/agf-b/badlands/blob/main/kernel/src/interrupts/APIC.cpp"
click node_xhci "https://github.com/agf-b/badlands/blob/main/kernel/src/devices/USB/xHCI/Controller.cpp"
click node_usb_hid "https://github.com/agf-b/badlands/blob/main/kernel/src/devices/USB/HID/Driver.cpp"
click node_usb_keyboard "https://github.com/agf-b/badlands/blob/main/kernel/src/devices/USB/HID/Keyboard.cpp"
click node_ps2 "https://github.com/agf-b/badlands/blob/main/kernel/src/devices/PS2/Controller.cpp"
click node_key_dispatch "https://github.com/agf-b/badlands/blob/main/kernel/src/devices/KeyboardDispatcher/Multiplexer.cpp"
click node_storage "https://github.com/agf-b/badlands/blob/main/kernel/src/devices/Block/Device.cpp"
click node_usb_storage "https://github.com/agf-b/badlands/blob/main/kernel/src/devices/USB/MassStorage/BBB/Driver.cpp"
click node_scheduler "https://github.com/agf-b/badlands/blob/main/kernel/src/sched/TaskManager.cpp"
click node_vfs "https://github.com/agf-b/badlands/blob/main/kernel/src/fs/VFS.cpp"
click node_npfs "https://github.com/agf-b/badlands/blob/main/kernel/src/fs/NPFS.cpp"
click node_shell "https://github.com/agf-b/badlands/blob/main/kernel/src/services/shell/entry.cpp"
click node_framebuffer "https://github.com/agf-b/badlands/blob/main/kernel/src/screen/Framebuffer.cpp"
click node_shared_memory "https://github.com/agf-b/badlands/blob/main/common/include/shared/memory/defs.hpp"

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_entry,node_efi_fs,node_kernel_loader,node_loader_paging,node_acpi_probe,node_user toneBlue
class node_vm,node_physical_memory,node_acpi,node_pci,node_apic,node_shared_memory toneAmber
class node_xhci,node_usb_hid,node_usb_keyboard,node_ps2,node_key_dispatch,node_storage,node_usb_storage toneMint
class node_kernel_entry,node_scheduler toneRose
class node_vfs,node_npfs,node_shell,node_framebuffer,node_firmware toneIndigo
```

## Components

### UEFI Boot

- [Boot Entry](https://github.com/agf-b/badlands/blob/main/bootloader/src/entry.cpp): `bootloader/src/entry.cpp`
- [EFI Filesystem](https://github.com/agf-b/badlands/blob/main/bootloader/src/efi/efi_fs.cpp): `bootloader/src/efi/efi_fs.cpp`
- [Kernel Loader](https://github.com/agf-b/badlands/blob/main/bootloader/src/loader/kernel_loader.cpp): `bootloader/src/loader/kernel_loader.cpp`
- [Loader Paging](https://github.com/agf-b/badlands/blob/main/bootloader/src/loader/paging.cpp): `bootloader/src/loader/paging.cpp`
- [ACPI Discovery](https://github.com/agf-b/badlands/blob/main/bootloader/src/loader/acpi_check.cpp): `bootloader/src/loader/acpi_check.cpp`

### Kernel Platform

- [Virtual Memory](https://github.com/agf-b/badlands/blob/main/kernel/src/mm/VirtualMemory.cpp): `kernel/src/mm/VirtualMemory.cpp`
- [Physical Memory](https://github.com/agf-b/badlands/blob/main/kernel/src/mm/PhysicalMemory.cpp): `kernel/src/mm/PhysicalMemory.cpp`
- [ACPI Tables](https://github.com/agf-b/badlands/blob/main/kernel/src/acpi/Interface.cpp): `kernel/src/acpi/Interface.cpp`
- [PCIe Enumeration](https://github.com/agf-b/badlands/blob/main/kernel/src/pci/PCI.cpp): `kernel/src/pci/PCI.cpp`
- [APIC Interrupts](https://github.com/agf-b/badlands/blob/main/kernel/src/interrupts/APIC.cpp): `kernel/src/interrupts/APIC.cpp`
- [Shared Memory Primitives](https://github.com/agf-b/badlands/blob/main/common/include/shared/memory/defs.hpp): `common/include/shared/memory/defs.hpp`

### Device Drivers

- [xHCI Controller](https://github.com/agf-b/badlands/blob/main/kernel/src/devices/USB/xHCI/Controller.cpp): `kernel/src/devices/USB/xHCI/Controller.cpp`
- [USB HID](https://github.com/agf-b/badlands/blob/main/kernel/src/devices/USB/HID/Driver.cpp): `kernel/src/devices/USB/HID/Driver.cpp`
- [USB Keyboard](https://github.com/agf-b/badlands/blob/main/kernel/src/devices/USB/HID/Keyboard.cpp): `kernel/src/devices/USB/HID/Keyboard.cpp`
- [PS/2 Keyboard](https://github.com/agf-b/badlands/blob/main/kernel/src/devices/PS2/Controller.cpp): `kernel/src/devices/PS2/Controller.cpp`
- [Keyboard Dispatch](https://github.com/agf-b/badlands/blob/main/kernel/src/devices/KeyboardDispatcher/Multiplexer.cpp): `kernel/src/devices/KeyboardDispatcher/Multiplexer.cpp`
- [Block Storage](https://github.com/agf-b/badlands/blob/main/kernel/src/devices/Block/Device.cpp): `kernel/src/devices/Block/Device.cpp`
- [USB Mass Storage](https://github.com/agf-b/badlands/blob/main/kernel/src/devices/USB/MassStorage/BBB/Driver.cpp): `kernel/src/devices/USB/MassStorage/BBB/Driver.cpp`

### Kernel Runtime

- [Kernel Entry](https://github.com/agf-b/badlands/blob/main/kernel/src/entry.cpp): `kernel/src/entry.cpp`
- [Task Scheduler](https://github.com/agf-b/badlands/blob/main/kernel/src/sched/TaskManager.cpp): `kernel/src/sched/TaskManager.cpp`

### Storage and Interface

- [Virtual Filesystem](https://github.com/agf-b/badlands/blob/main/kernel/src/fs/VFS.cpp): `kernel/src/fs/VFS.cpp`
- [Nonpersistent FS](https://github.com/agf-b/badlands/blob/main/kernel/src/fs/NPFS.cpp): `kernel/src/fs/NPFS.cpp`
- [Shell Service](https://github.com/agf-b/badlands/blob/main/kernel/src/services/shell/entry.cpp): `kernel/src/services/shell/entry.cpp`
- [Framebuffer Output](https://github.com/agf-b/badlands/blob/main/kernel/src/screen/Framebuffer.cpp): `kernel/src/screen/Framebuffer.cpp`

### Other components

- **UEFI Firmware**
- **System User**

## Connections

- UEFI Firmware → Boot Entry: starts bootloader
- Boot Entry → EFI Filesystem: uses filesystem
- Boot Entry → Kernel Loader: loads kernel
- Kernel Loader → Loader Paging: maps kernel
- Boot Entry → ACPI Discovery: discovers ACPI
- Kernel Loader → Kernel Entry: hands off
- Kernel Entry → Virtual Memory: initializes memory
- Kernel Entry → APIC Interrupts: initializes interrupts
- Kernel Entry → PCIe Enumeration: starts enumeration
- Kernel Entry → ACPI Tables: reads tables
- PCIe Enumeration → xHCI Controller: detects controller
- xHCI Controller → Task Scheduler: schedules updater (evidence: `kernel/src/devices/USB/xHCI/Controller.cpp`)
- xHCI Controller → USB HID: initializes devices
- USB HID → USB Keyboard: handles keyboard
- PS/2 Keyboard → Keyboard Dispatch: forwards key events
- USB Keyboard → Keyboard Dispatch: forwards key events
- PCIe Enumeration → Block Storage: discovers storage
- xHCI Controller → USB Mass Storage: supports mass storage
- USB Mass Storage → Block Storage: provides block device
- Block Storage → Virtual Filesystem: serves filesystem
- Virtual Filesystem → Nonpersistent FS: mounts filesystem
- System User → Shell Service: uses shell
- Shell Service → Virtual Filesystem: accesses files
- Kernel Entry → Framebuffer Output: initializes display
- Kernel Entry → Task Scheduler: starts scheduling
