# niclas3/frog architecture

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

- Interactive diagram: https://gitdiagram.com/niclas3/frog
- Repository: https://github.com/niclas3/frog

## Overview

#### Purpose and Execution Model
Frog is a self-teaching 32-bit x86 PC operating system: a bootloader loads a kernel that initializes hardware, memory, interrupts, processes, storage, and a desktop compositor. It is built for disk-image boot under QEMU/Bochs rather than hosted execution.

#### Boot and Kernel Entry
The boot chain begins in the MBR and loader assembly, then transfers into the protected-mode kernel assembly/C entry path. Core startup establishes the low-level runtime before subsystems are available.
- `booter/MBR.s`
- `booter/loader.s`
- `core/core.s`
- `core/bootpack.c`

#### CPU Protection, Interrupts, and Time
Descriptor/TSS setup defines x86 protected-mode execution context. PIC and interrupt code route hardware faults and IRQs; the PIT-backed timer drives timing and likely scheduling/timeout activity. Softirqs provide deferred interrupt work.
- `core/destab/descriptor.c`
- `core/destab/tss.c`
- `core/interrupt/int.c`
- `core/pic/pic.c`
- `core/frog/pit8253.c`

#### Process and System-Service Boundary
The thread/process subsystem owns task creation, context switching, scheduling, fork/exec/exit, and synchronization. User-facing syscall initialization and dispatch form the boundary from applications/system tasks into kernel services.
- `core/thread/sched.c`
- `core/thread/process.c`
- `core/thread/switch.s`
- `core/usr/syscall-init.c`
- `core/usr/syscall.c`

#### Memory, IPC, and Kernel Coordination
Physical/virtual memory management underpins process execution. IPC, pipes, semaphores, queues, and select-style readiness are the primary coordination mechanisms between processes and device/service code.
- `core/mm/memory.c`
- `core/ipc/ipc.c`
- `core/fs/pipe.c`
- `core/fs/select.c`
- `core/thread/semaphore.c`

#### Devices, Storage, and Filesystem
Hardware drivers cover CMOS, console, IDE disks, PS/2 keyboard/mouse, and linear-framebuffer video. IDE is the storage boundary; filesystem layers expose directories, files, inodes, and a package filesystem abstraction above it.
- `core/device/ide.c`
- `core/device/pc_kbd.c`
- `core/device/ps2hid.c`
- `core/fs/fs.c`
- `core/vfs/packagefs.c`

#### Graphics and Desktop Stack
Framebuffer video feeds graphics and GUI support libraries. The compositor and desktop applications consume these facilities; image decoders indicate desktop rendering can load BMP/JPEG assets. “Poudland” headers/library suggest an internal display-server/client protocol boundary.
- `core/video/lfbvideo.c`
- `core/apps/compositor.c`
- `core/apps/desktop.c`
- `core/lib/poudland.c`
- `core/lib/2d_graphics.c`

#### Build and Runtime Infrastructure
Makefiles partition bootloader, kernel, devices, filesystem, apps, libraries, and tools. Shell scripts build images and launch/debug QEMU; Bochs configs are also present. Required runtime artifacts are user-created `hd.img` and `hd80M.img` disk images. Networking currently exposes a socket-oriented kernel surface but README identifies TCP/IP as unfinished.
- `Makefile`
- `scripts/build.sh`
- `scripts/qemu.sh`
- `bochsrc`
- `core/net/socket.c`

Main entry points: [`core/bootpack.c`](https://github.com/niclas3/frog/blob/master/core/bootpack.c) (Kernel entry), [`core/usr/syscall.c`](https://github.com/niclas3/frog/blob/master/core/usr/syscall.c) (System call dispatch), [`core/thread/sched.c`](https://github.com/niclas3/frog/blob/master/core/thread/sched.c) (Processes and scheduler), [`core/interrupt/int.c`](https://github.com/niclas3/frog/blob/master/core/interrupt/int.c) (Interrupt routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot and kernel entry"]
  node_mbr["MBR boot sector<br/>x86 assembly<br/>[MBR.s]"]
  node_loader["Protected-mode loader<br/>x86 assembly<br/>[loader.s]"]
  node_kernel_entry["Kernel entry<br/>Assembly/C entry<br/>[bootpack.c]"]
end

subgraph group_kernel["Kernel core"]
  node_protection["Descriptors and TSS<br/>CPU protection<br/>[descriptor.c]"]
  node_interrupts["Interrupt routing<br/>IRQ subsystem<br/>[int.c]"]
  node_timer["PIT timer<br/>Clock driver<br/>[pit8253.c]"]
  node_processes["Processes and scheduler<br/>Task subsystem<br/>[sched.c]"]
  node_memory["Memory manager<br/>Physical/virtual memory<br/>[memory.c]"]
  node_syscalls["System call dispatch<br/>Kernel service boundary<br/>[syscall.c]"]
  node_ipc["IPC and synchronization<br/>Coordination primitives<br/>[ipc.c]"]
  node_sockets["Socket surface<br/>Networking API<br/>[socket.c]"]
end

subgraph group_io["Devices and storage"]
  node_input["Keyboard and mouse<br/>PS/2 drivers<br/>[pc_kbd.c]"]
  node_ide[("IDE disk driver<br/>Block storage<br/>[ide.c]")]
  node_filesystem[("Filesystem and package FS<br/>VFS/filesystem<br/>[fs.c]")]
end

subgraph group_desktop["Desktop stack"]
  node_framebuffer["Linear framebuffer<br/>Video driver<br/>[lfbvideo.c]"]
  node_graphics["2D graphics and Poudland<br/>GUI support library<br/>[poudland.c]"]
  node_compositor["Compositor<br/>[compositor.c]"]
  node_desktop_app["Desktop application<br/>Desktop shell<br/>[desktop.c]"]
end

subgraph group_runtime["Build and emulation"]
  node_build["Build orchestration<br/>Make build"]
  node_image_build["Disk image build<br/>Build script<br/>[build.sh]"]
  node_emulator["QEMU launch<br/>Emulator script<br/>[qemu.sh]"]
end

node_build -->|"invokes"| node_image_build
node_image_build -->|"packages"| node_mbr
node_emulator -->|"boots image at"| node_mbr
node_mbr -->|"loads"| node_loader
node_loader -->|"transfers control"| node_kernel_entry
node_kernel_entry -->|"initializes"| node_protection
node_kernel_entry -->|"initializes"| node_interrupts
node_kernel_entry -->|"initializes"| node_memory
node_interrupts -->|"routes timer IRQ"| node_timer
node_timer -->|"drives scheduling"| node_processes
node_protection -->|"provides task context"| node_processes
node_memory -->|"backs address spaces"| node_processes
node_interrupts -->|"dispatches device IRQs"| node_input
node_processes -->|"runs callers"| node_syscalls
node_syscalls -->|"exposes coordination"| node_ipc
node_syscalls -->|"exposes files"| node_filesystem
node_syscalls -.->|"exposes sockets"| node_sockets
node_filesystem -->|"reads and writes blocks"| node_ide
node_framebuffer -->|"renders through"| node_graphics
node_graphics -->|"supports"| node_compositor
node_input -->|"supplies input"| node_compositor
node_compositor -->|"composes desktop"| node_desktop_app
node_filesystem -->|"loads apps and assets"| node_desktop_app

click node_build "https://github.com/niclas3/frog/blob/master/Makefile"
click node_image_build "https://github.com/niclas3/frog/blob/master/scripts/build.sh"
click node_emulator "https://github.com/niclas3/frog/blob/master/scripts/qemu.sh"
click node_mbr "https://github.com/niclas3/frog/blob/master/booter/MBR.s"
click node_loader "https://github.com/niclas3/frog/blob/master/booter/loader.s"
click node_kernel_entry "https://github.com/niclas3/frog/blob/master/core/bootpack.c"
click node_protection "https://github.com/niclas3/frog/blob/master/core/destab/descriptor.c"
click node_interrupts "https://github.com/niclas3/frog/blob/master/core/interrupt/int.c"
click node_timer "https://github.com/niclas3/frog/blob/master/core/frog/pit8253.c"
click node_processes "https://github.com/niclas3/frog/blob/master/core/thread/sched.c"
click node_memory "https://github.com/niclas3/frog/blob/master/core/mm/memory.c"
click node_syscalls "https://github.com/niclas3/frog/blob/master/core/usr/syscall.c"
click node_ipc "https://github.com/niclas3/frog/blob/master/core/ipc/ipc.c"
click node_input "https://github.com/niclas3/frog/blob/master/core/device/pc_kbd.c"
click node_ide "https://github.com/niclas3/frog/blob/master/core/device/ide.c"
click node_filesystem "https://github.com/niclas3/frog/blob/master/core/fs/fs.c"
click node_framebuffer "https://github.com/niclas3/frog/blob/master/core/video/lfbvideo.c"
click node_graphics "https://github.com/niclas3/frog/blob/master/core/lib/poudland.c"
click node_compositor "https://github.com/niclas3/frog/blob/master/core/apps/compositor.c"
click node_desktop_app "https://github.com/niclas3/frog/blob/master/core/apps/desktop.c"
click node_sockets "https://github.com/niclas3/frog/blob/master/core/net/socket.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_mbr,node_loader,node_kernel_entry toneBlue
class node_protection,node_interrupts,node_timer,node_processes,node_memory,node_syscalls,node_ipc,node_sockets toneAmber
class node_input,node_ide,node_filesystem toneMint
class node_framebuffer,node_graphics,node_compositor,node_desktop_app toneRose
class node_build,node_image_build,node_emulator toneIndigo
```

## Components

### Boot and kernel entry

- [MBR boot sector](https://github.com/niclas3/frog/blob/master/booter/MBR.s): x86 assembly · `booter/MBR.s`
- [Protected-mode loader](https://github.com/niclas3/frog/blob/master/booter/loader.s): x86 assembly · `booter/loader.s`
- [Kernel entry](https://github.com/niclas3/frog/blob/master/core/bootpack.c): Assembly/C entry · `core/bootpack.c`

### Kernel core

- [Descriptors and TSS](https://github.com/niclas3/frog/blob/master/core/destab/descriptor.c): CPU protection · `core/destab/descriptor.c`
- [Interrupt routing](https://github.com/niclas3/frog/blob/master/core/interrupt/int.c): IRQ subsystem · `core/interrupt/int.c`
- [PIT timer](https://github.com/niclas3/frog/blob/master/core/frog/pit8253.c): Clock driver · Supplies periodic timing for kernel activity. · `core/frog/pit8253.c`
- [Processes and scheduler](https://github.com/niclas3/frog/blob/master/core/thread/sched.c): Task subsystem · Owns tasks, scheduling, fork/exec, and context switching. · `core/thread/sched.c`
- [Memory manager](https://github.com/niclas3/frog/blob/master/core/mm/memory.c): Physical/virtual memory · `core/mm/memory.c`
- [System call dispatch](https://github.com/niclas3/frog/blob/master/core/usr/syscall.c): Kernel service boundary · `core/usr/syscall.c`
- [IPC and synchronization](https://github.com/niclas3/frog/blob/master/core/ipc/ipc.c): Coordination primitives · IPC, pipes, readiness, and semaphores coordinate tasks. · `core/ipc/ipc.c`
- [Socket surface](https://github.com/niclas3/frog/blob/master/core/net/socket.c): Networking API · TCP/IP implementation remains unfinished. · `core/net/socket.c`

### Devices and storage

- [Keyboard and mouse](https://github.com/niclas3/frog/blob/master/core/device/pc_kbd.c): PS/2 drivers · `core/device/pc_kbd.c`
- [IDE disk driver](https://github.com/niclas3/frog/blob/master/core/device/ide.c): Block storage · `core/device/ide.c`
- [Filesystem and package FS](https://github.com/niclas3/frog/blob/master/core/fs/fs.c): VFS/filesystem · `core/fs/fs.c`

### Desktop stack

- [Linear framebuffer](https://github.com/niclas3/frog/blob/master/core/video/lfbvideo.c): Video driver · `core/video/lfbvideo.c`
- [2D graphics and Poudland](https://github.com/niclas3/frog/blob/master/core/lib/poudland.c): GUI support library · Provides drawing and an internal display protocol. · `core/lib/poudland.c`
- [Compositor](https://github.com/niclas3/frog/blob/master/core/apps/compositor.c): Desktop compositor · `core/apps/compositor.c`
- [Desktop application](https://github.com/niclas3/frog/blob/master/core/apps/desktop.c): Desktop shell · `core/apps/desktop.c`

### Build and emulation

- [Build orchestration](https://github.com/niclas3/frog/blob/master/Makefile): Make build · `Makefile`
- [Disk image build](https://github.com/niclas3/frog/blob/master/scripts/build.sh): Build script · Builds bootable disk artifacts. · `scripts/build.sh`
- [QEMU launch](https://github.com/niclas3/frog/blob/master/scripts/qemu.sh): Emulator script · `scripts/qemu.sh`

## Connections

- Build orchestration → Disk image build: invokes
- Disk image build → MBR boot sector: packages
- QEMU launch → MBR boot sector: boots image at
- MBR boot sector → Protected-mode loader: loads
- Protected-mode loader → Kernel entry: transfers control
- Kernel entry → Descriptors and TSS: initializes
- Kernel entry → Interrupt routing: initializes
- Kernel entry → Memory manager: initializes
- Interrupt routing → PIT timer: routes timer IRQ
- PIT timer → Processes and scheduler: drives scheduling
- Descriptors and TSS → Processes and scheduler: provides task context
- Memory manager → Processes and scheduler: backs address spaces
- Interrupt routing → Keyboard and mouse: dispatches device IRQs
- Processes and scheduler → System call dispatch: runs callers
- System call dispatch → IPC and synchronization: exposes coordination
- System call dispatch → Filesystem and package FS: exposes files
- System call dispatch → Socket surface: exposes sockets
- Filesystem and package FS → IDE disk driver: reads and writes blocks
- Linear framebuffer → 2D graphics and Poudland: renders through
- 2D graphics and Poudland → Compositor: supports
- Keyboard and mouse → Compositor: supplies input
- Compositor → Desktop application: composes desktop
- Filesystem and package FS → Desktop application: loads apps and assets