# haribytecode/blackpeakos architecture

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

- Interactive diagram: https://gitdiagram.com/haribytecode/blackpeakos
- Repository: https://github.com/haribytecode/blackpeakos

## Overview

#### Purpose and Boot Entry

MyOS is a freestanding 32-bit i386 educational kernel, packaged as a BIOS/GRUB bootable ISO. GRUB loads the kernel entry assembly, which establishes initial CPU state and transfers control to C kernel initialization.

- Boot entry: `boot.S`
- Kernel linker layouts: `link.ld`, `linker.ld`
- GRUB ISO configuration: `iso_root/boot/grub/grub.cfg`

#### Kernel Initialization and Console Boundary

The kernel initialization routine brings up descriptor tables, interrupt handling, devices, memory/task infrastructure, and initial execution. Early diagnostics are exposed through VGA text mode and serial UART; fatal failures terminate through the panic path.

- Main kernel control path: `kernel.c`
- VGA console: `console.c`, `console.h`
- Serial and fatal reporting: `uart.c`, `panic.c`

#### CPU Protection and Privilege State

Segmentation and task-state infrastructure define the protected-mode CPU environment. The GDT provides kernel descriptors, while the TSS supports task/privilege-transition state. Small assembly stubs perform CPU instructions that cannot be expressed directly in C.

- GDT setup and load: `gdt.c`, `gdt_flush.s`
- Task State Segment: `tss.c`, `tss_flush.s`
- Low-level context mechanisms: `context.c`, `context_switch.s`

#### Interrupt and IRQ Dispatch Pipeline

Hardware and CPU events enter assembly interrupt stubs, are normalized into C-level ISR/IRQ dispatch, then routed to device or scheduler handlers. The PIC is configured to remap and acknowledge legacy IRQs, separating CPU exception handling from external hardware interrupts.

- IDT and assembly gates: `idt.c`, `idt_asm.s`
- Exception/IRQ dispatch: `isr.c`, `irq.c`
- PIC control: `pic.c`, `interrupt.h`

#### Timer, Keyboard, and Device I/O

The PIT timer provides the periodic interrupt source used for preemption. Keyboard IRQ handling translates input for kernel consumption. Hardware register access is centralized around x86 port-I/O primitives, with VGA and UART as primary output devices.

- Timer/preemption source: `timer.c`, `timer.h`
- Keyboard driver: `keyboard.c`, `keyboard.h`
- Port I/O interface: `io.h`

#### Tasks, Threads, and Scheduling

The multitasking subsystem models executable work as tasks and threads, manages CPU context, and selects runnable execution on timer-driven preemption. The scheduler is the control boundary between an IRQ tick and a context switch; task/thread code owns lifecycle and execution-state structures.

- Scheduler policy and dispatch: `scheduler.c`, `scheduler.h`
- Task representation/lifecycle: `task.c`, `task.h`
- Thread and context state: `thread.c`, `context.c`

#### Memory Management and Image Delivery

The kernel includes basic physical heap/memory management. Paging sources exist, but the stated runtime model does not yet depend on virtual memory. The Makefile produces an ELF kernel and places it into the GRUB ISO tree for QEMU or compatible BIOS virtualization.

- Heap/physical allocation: `heap.c`, `heap.h`
- Paging foundation: `paging.c`, `paging.h`
- Build artifacts and delivery root: `Makefile`, `iso_root/boot/kernel.elf`

Main entry points: [`kernel.c`](https://github.com/haribytecode/blackpeakos/blob/main/kernel.c) (Kernel initialization), [`isr.c`](https://github.com/haribytecode/blackpeakos/blob/main/isr.c) (ISR / IRQ dispatch), [`scheduler.c`](https://github.com/haribytecode/blackpeakos/blob/main/scheduler.c) (Scheduler), [`iso_root/boot/kernel.elf`](https://github.com/haribytecode/blackpeakos/blob/main/iso_root/boot/kernel.elf) (Kernel ELF)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot & Image"]
  node_build["Kernel build<br/>build pipeline"]
  node_grub["GRUB boot config<br/>boot configuration<br/>[grub.cfg]"]
  node_kernel_elf["Kernel ELF<br/>boot artifact<br/>[kernel.elf]"]
  node_boot_entry{{"Boot entry<br/>i386 assembly entry<br/>[boot.S]"}}
end

subgraph group_cpu["CPU Protection"]
  node_gdt["GDT setup<br/>descriptor tables<br/>[gdt.c]"]
  node_tss["TSS state<br/>privilege-transition state<br/>[tss.c]"]
  node_context["CPU context<br/>context switching<br/>[context.c]"]
end

subgraph group_interrupts["Interrupts &amp; Devices"]
  node_idt["IDT gates<br/>interrupt descriptor table<br/>[idt.c]"]
  node_dispatch["ISR / IRQ dispatch<br/>interrupt routing<br/>[isr.c]"]
  node_pic["PIC control<br/>legacy IRQ controller<br/>[pic.c]"]
  node_timer["PIT timer<br/>preemption source<br/>[timer.c]"]
  node_keyboard["Keyboard driver<br/>IRQ device driver<br/>[keyboard.c]"]
end

subgraph group_runtime["Kernel Runtime"]
  node_kernel_init["Kernel initialization<br/>kernel control path<br/>[kernel.c]"]
  node_console["Console output<br/>VGA console<br/>[console.c]"]
  node_uart_panic["Serial &amp; panic<br/>fatal reporting<br/>[panic.c]"]
  node_scheduler["Scheduler<br/>runnable-task dispatch<br/>[scheduler.c]"]
  node_tasks["Tasks &amp; threads<br/>execution lifecycle<br/>[task.c]"]
  node_heap[("Physical heap<br/>memory allocator<br/>[heap.c]")]
  node_paging["Paging foundation<br/>virtual-memory groundwork<br/>[paging.c]"]
end

node_build -->|"produces"| node_kernel_elf
node_grub -->|"loads"| node_kernel_elf
node_kernel_elf -->|"enters"| node_boot_entry
node_boot_entry -->|"transfers control"| node_kernel_init
node_kernel_init -->|"initializes"| node_gdt
node_kernel_init -->|"initializes"| node_tss
node_kernel_init -->|"installs"| node_idt
node_kernel_init -->|"configures"| node_pic
node_kernel_init -->|"starts"| node_timer
node_kernel_init -->|"initializes"| node_keyboard
node_kernel_init -->|"initializes"| node_heap
node_kernel_init -.->|"initializes"| node_paging
node_kernel_init -->|"diagnostics"| node_console
node_kernel_init -->|"fatal diagnostics"| node_uart_panic
node_idt -->|"routes events"| node_dispatch
node_pic -->|"delivers IRQs"| node_dispatch
node_dispatch -->|"timer IRQ"| node_timer
node_dispatch -->|"keyboard IRQ"| node_keyboard
node_timer -->|"preemption tick"| node_scheduler
node_scheduler -->|"selects runnable work"| node_tasks
node_tasks -->|"owns execution state"| node_context
node_scheduler -->|"switches context"| node_context
node_tss -->|"supports privilege state"| node_context

click node_build "https://github.com/haribytecode/blackpeakos/blob/main/Makefile"
click node_grub "https://github.com/haribytecode/blackpeakos/blob/main/iso_root/boot/grub/grub.cfg"
click node_kernel_elf "https://github.com/haribytecode/blackpeakos/blob/main/iso_root/boot/kernel.elf"
click node_boot_entry "https://github.com/haribytecode/blackpeakos/blob/main/boot.S"
click node_kernel_init "https://github.com/haribytecode/blackpeakos/blob/main/kernel.c"
click node_console "https://github.com/haribytecode/blackpeakos/blob/main/console.c"
click node_uart_panic "https://github.com/haribytecode/blackpeakos/blob/main/panic.c"
click node_gdt "https://github.com/haribytecode/blackpeakos/blob/main/gdt.c"
click node_tss "https://github.com/haribytecode/blackpeakos/blob/main/tss.c"
click node_context "https://github.com/haribytecode/blackpeakos/blob/main/context.c"
click node_idt "https://github.com/haribytecode/blackpeakos/blob/main/idt.c"
click node_dispatch "https://github.com/haribytecode/blackpeakos/blob/main/isr.c"
click node_pic "https://github.com/haribytecode/blackpeakos/blob/main/pic.c"
click node_timer "https://github.com/haribytecode/blackpeakos/blob/main/timer.c"
click node_keyboard "https://github.com/haribytecode/blackpeakos/blob/main/keyboard.c"
click node_scheduler "https://github.com/haribytecode/blackpeakos/blob/main/scheduler.c"
click node_tasks "https://github.com/haribytecode/blackpeakos/blob/main/task.c"
click node_heap "https://github.com/haribytecode/blackpeakos/blob/main/heap.c"
click node_paging "https://github.com/haribytecode/blackpeakos/blob/main/paging.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_build,node_grub,node_kernel_elf,node_boot_entry toneBlue
class node_gdt,node_tss,node_context toneAmber
class node_idt,node_dispatch,node_pic,node_timer,node_keyboard toneMint
class node_kernel_init,node_console,node_uart_panic,node_scheduler,node_tasks,node_heap,node_paging toneRose
```

## Components

### Boot & Image

- [Kernel build](https://github.com/haribytecode/blackpeakos/blob/main/Makefile): build pipeline · Builds the ELF and ISO layout. · `Makefile`
- [GRUB boot config](https://github.com/haribytecode/blackpeakos/blob/main/iso_root/boot/grub/grub.cfg): boot configuration · `iso_root/boot/grub/grub.cfg`
- [Kernel ELF](https://github.com/haribytecode/blackpeakos/blob/main/iso_root/boot/kernel.elf): boot artifact · `iso_root/boot/kernel.elf`
- [Boot entry](https://github.com/haribytecode/blackpeakos/blob/main/boot.S): i386 assembly entry · Establishes initial CPU state before C initialization. · `boot.S`

### CPU Protection

- [GDT setup](https://github.com/haribytecode/blackpeakos/blob/main/gdt.c): descriptor tables · `gdt.c`
- [TSS state](https://github.com/haribytecode/blackpeakos/blob/main/tss.c): privilege-transition state · `tss.c`
- [CPU context](https://github.com/haribytecode/blackpeakos/blob/main/context.c): context switching · `context.c`

### Interrupts & Devices

- [IDT gates](https://github.com/haribytecode/blackpeakos/blob/main/idt.c): interrupt descriptor table · `idt.c`
- [ISR / IRQ dispatch](https://github.com/haribytecode/blackpeakos/blob/main/isr.c): interrupt routing · Separates exceptions from external IRQs. · `isr.c`
- [PIC control](https://github.com/haribytecode/blackpeakos/blob/main/pic.c): legacy IRQ controller · Remaps and acknowledges hardware IRQs. · `pic.c`
- [PIT timer](https://github.com/haribytecode/blackpeakos/blob/main/timer.c): preemption source · `timer.c`
- [Keyboard driver](https://github.com/haribytecode/blackpeakos/blob/main/keyboard.c): IRQ device driver · `keyboard.c`

### Kernel Runtime

- [Kernel initialization](https://github.com/haribytecode/blackpeakos/blob/main/kernel.c): kernel control path · `kernel.c`
- [Console output](https://github.com/haribytecode/blackpeakos/blob/main/console.c): VGA console · `console.c`
- [Serial & panic](https://github.com/haribytecode/blackpeakos/blob/main/panic.c): fatal reporting · `panic.c`
- [Scheduler](https://github.com/haribytecode/blackpeakos/blob/main/scheduler.c): runnable-task dispatch · Chooses execution at timer-driven preemption points. · `scheduler.c`
- [Tasks & threads](https://github.com/haribytecode/blackpeakos/blob/main/task.c): execution lifecycle · `task.c`
- [Physical heap](https://github.com/haribytecode/blackpeakos/blob/main/heap.c): memory allocator · `heap.c`
- [Paging foundation](https://github.com/haribytecode/blackpeakos/blob/main/paging.c): virtual-memory groundwork · Present but not required by the current runtime model. · `paging.c`

## Connections

- Kernel build → Kernel ELF: produces
- GRUB boot config → Kernel ELF: loads
- Kernel ELF → Boot entry: enters
- Boot entry → Kernel initialization: transfers control
- Kernel initialization → GDT setup: initializes
- Kernel initialization → TSS state: initializes
- Kernel initialization → IDT gates: installs
- Kernel initialization → PIC control: configures
- Kernel initialization → PIT timer: starts
- Kernel initialization → Keyboard driver: initializes
- Kernel initialization → Physical heap: initializes
- Kernel initialization → Paging foundation: initializes
- Kernel initialization → Console output: diagnostics
- Kernel initialization → Serial & panic: fatal diagnostics
- IDT gates → ISR / IRQ dispatch: routes events
- PIC control → ISR / IRQ dispatch: delivers IRQs
- ISR / IRQ dispatch → PIT timer: timer IRQ
- ISR / IRQ dispatch → Keyboard driver: keyboard IRQ
- PIT timer → Scheduler: preemption tick
- Scheduler → Tasks & threads: selects runnable work
- Tasks & threads → CPU context: owns execution state
- Scheduler → CPU context: switches context
- TSS state → CPU context: supports privilege state