About Popcorn Kernel Framework

What is Popcorn?

Target: x86-64 ELF linked at 0x100000 with a Multiboot2 header (link.ld, kernel.asm entry start → identity map → long mode → kmain). Runtime: ring-0 VGA at 0xB8000, PIC + IDT (timer 0x20, keyboard 0x21, syscall 0x80), VMM (boot 1 GiB identity map, per-task PML4, CR3 on switch), PMM (4 KiB frames + bitmap from Multiboot2 mmap), IRQ1 scancode queue consumed by the shell with HLT, PIT re-enabled at console handoff with scheduler bootstrap guards, static task stacks, ~21 syscalls, nine pops. Host loop: src/build/ scripts and popcorn_build/ produce kernel + ISO; QEMU boots GRUB → your image. Version 0.6 is pre-1.0 and educational—not a production OS.

Key Features

Console System

VGA text-mode console with cursor management, color styling, scrolling, status regions, scrollback-oriented structures, command history, and tab completion—with ongoing hardening for input edge cases and consistent error reporting.

Pop Modules

Extend kernel functionality through modular “pops” that register with the kernel and use shared console utilities for consistent behavior and less duplication.

Utilities Framework

Shared helpers across modules and refactors toward constants and consolidated utilities (0.5 includes a focused cleanup pass alongside feature work).

Minimal Assembly

Written primarily in C with only essential assembly (boot, IDT/ISR plumbing, context switch paths), keeping the project approachable while still teaching real low-level mechanics.

Cross-platform dev (Linux / WSL / macOS)

Linux and WSL use src/build/linux.sh and the shared popcorn_build/ Python package. macOS uses src/build/macos.sh or gui-macos.py with the same cross toolchain expectations (x86_64-elf-gcc, GRUB mkrescue, QEMU).

Keyboard input (0.6)

IRQ1 pushes scancodes into a ring queue; kmain and Dolphin dequeue asynchronously (with HLT when idle) instead of polling port 0x60 in the main loop—fixes input stalling after several shell commands when the PIT is active.

Virtual & physical memory (0.6)

vmm.c manages page tables; boot identity mapping covers the first gibibyte; PMM allocates 4 KiB frames using Multiboot2 region types; per-task address spaces reload CR3 on context switch.

Timers, scheduling & syscalls

PIT-driven preemption with bootstrap guards (bootstrap_on_kmain_stack, first-tick skip, context_looks_sane); syscall table from 0.5 (fork/wait/mmap/munmap/stat/ioctl and related handlers) remains experimental.

Hardware introspection

Extended memory map handling, CPUID-based CPU reporting, frequency detection, multiboot information persistence, and sysinfo-style surfacing through pops and kernel paths.

ISO + QEMU workflow

Kernel is linked into a bootable ISO and run under QEMU separately from compilation, with Python-oriented builder support (Fedora-oriented) and shell build helpers aligned with the project’s build monitor tooling.

Pop Module System

The core of Popcorn's extensibility lies in its Pop Module system. Each "pop" is a self-contained module that can register itself with the kernel and uses the console system for consistent behavior:

typedef struct {
    const char* name;       /* module id */
    const char* message;    /* banner / HUD text */
    void (*pop_function)(unsigned int start_pos);
} PopModule;

All pop modules must save and restore console state (cursor position and color) to prevent interference with user input. The system maintains a registry of modules and executes them in registration order.

Current Pop Modules

Spinner Pop

Animated loading indicator displaying "Running... |/-\" with rotating animation in the top-right corner.

Uptime Pop

Real-time system tick counter showing "Ticks: XXXXXX" in the top-left corner.

Filesystem Pop

In-memory filesystem with commands: create, write, read, delete, mkdir, go, back, listsys.

Halt Pop

Visual halt screen with green screen effect, rainbow colors, and fade to black animations.

Shimjapii Pop

Example pop module for developers, displaying in the bottom right corner.

Sysinfo Pop

Surfaces hardware and boot information (memory map / CPU / frequency style details), complementing the 0.5 hardware introspection work.

Memory Pop

Memory-oriented reporting and interaction aligned with the kernel’s memory-management bring-up.

CPU Pop

CPU-oriented reporting built around CPUID-backed detection work in the 0.5 timeframe.

Dolphin Pop

In-kernel text editor; 0.6 reads keys from the shared IRQ queue like the shell.

Building and Running

Popcorn provides multiple build system options for different environments:

✦ src/build/linux.sh and macos.sh entry points (Unix / WSL / native Linux / macOS with cross toolchain)
✦ popcorn_build/ Python package (toolchain, compile, ISO, QEMU runner)
✦ Optional macOS GUI (src/build/gui-macos.py) with local web UI under popcorn_build/ui/
✦ Legacy build.ps1 may exist for Windows; Linux/macOS paths above are the maintained 0.6 flow
✦ QEMU system emulation support (x86-64; CD/ISO boot)
✦ Customizable memory and core allocation (where exposed by your launcher / scripts)

Note: All build systems are provided AS-IS without warranties. Use at your own risk. Versions below v1.0 are considered trial versions.

Technical Requirements

To build and run Popcorn, you'll need:

✦ NASM (Netwide Assembler)
✦ A working C toolchain that produces a 64-bit ELF kernel (commonly gcc + GNU ld on Linux/WSL; on macOS use a cross compiler such as x86_64-elf-gcc + x86_64-elf-ld)
✦ QEMU for system emulation (qemu-system-x86_64)
✦ ISO creation tooling (for example xorriso / mtools plus a GRUB mkrescue tool appropriate to your platform; BIOS boot under QEMU often uses an i686-elf-grub-mkrescue-style workflow on macOS Homebrew)
✦ WSL or Linux strongly recommended for the historical Fedora-oriented Python builder path; macOS is supported with the cross toolchain + ISO tooling above

Computer Prerequisites

To work on Popcorn at a fluid level, you'll need:

✦ 16GB RAM recommended (8GB RAM minimum)
✦ 8th Gen i5 or higher with at least 4 cores, recommended 6
✦ No graphics requirements
✦ 1GB free space assuming WSL installed

WSL is strongly recommended for Windows developers. Native Linux is fully viable. macOS uses src/build/macos.sh or gui-macos.py with Homebrew cross compilers and GRUB ISO tooling; QEMU behavior may differ by host. Windows 11 and WSL 2.0 remain the recommended Windows stack.

Current Status & Limitations

Popcorn is currently in version 0.6 (pre-release on branch 1.6) and marked as unstable below v1.0. This release adds:

✦ Everything from 0.5: console, pops, ISO/QEMU loop, syscalls, hardware introspection
✦ VMM + PMM rewrite (identity boot map, frame bitmap, per-task PML4)
✦ IRQ keyboard queue + shell HLT wait path (no main-loop port polling)
✦ Timer re-enabled at console handoff with scheduler bootstrap guardrails
✦ Unified src/build/ tooling (linux.sh, macos.sh, popcorn_build package)
✦ Scrollback fix on macOS QEMU builds

Work in Progress: User processes, full demand paging, and production-grade scheduling are still future work. Soak-test locally (boot → many shell commands → Dolphin) before treating 0.6 as demo-stable.

Contributions: Special thanks to Swarnim A for the Intel book reference that made keyboard inputs possible for this kernel.