Operation map

How Popcorn boots and runs in the v0.7 tree. UEFI (BOOTX64.EFI) or GRUB Multiboot2 loads the kernel, asm enters long mode, kmain / init bring up memory and Rust drivers, then the shell runs over the display and keyboard drives.

UEFI + GRUB ELF64 @ 0x100000 C core · Rust drivers PMM ≤16 GiB · VMM 4-level /dev + catalog CI test-uefi

Hierarchical map

Expand branches (▸). Each node updates the inspector.

Popcorn

Loading…

Flow diagrams

Interrupt delivery

flowchart TD
  PIT[PIT IRQ0] --> PIC1[PIC master]
  KB[Keyboard IRQ1] --> PIC1
  PIC1 --> CPU[CPU interrupt]
  CPU --> IDT[IDT / irq table]
  IDT --> T0[timer path]
  IDT --> K0[kbd trampoline]
  IDT --> S0[syscall int 0x80]
  T0 --> T1[timer_interrupt_handler]
  T1 --> TH[scheduler_tick]
  K0 --> K1[Rust /dev/kbd]
  K1 --> SH2[shell / Dolphin]
  S0 --> SD[syscall_dispatch]

Lifecycle: host to shell

flowchart TB
  subgraph Host["Host"]
    BUILD["core.sh / popcorn_build"] --> ART[ELF + ISO/img]
    ART --> QEMU[QEMU UEFI or GRUB]
  end
  subgraph Guest["Guest"]
    QEMU --> BOOT["UEFI BOOTX64 or GRUB"]
    BOOT --> ENTRY["kernel.asm start"]
    ENTRY --> KM[kmain / init]
    KM --> MEM[memory_init PMM+VMM]
    KM --> RUST[rust_init + drives]
    KM --> IDT[idt + PIC]
    KM --> SHELL[shell loop]
    RUST --> SCR[tty0 / fb0]
    RUST --> KBD[/dev/kbd]
    SHELL --> SCR
    SHELL --> KBD
  end
  Host --> Guest

Reference

Layout

Popcorn/
├── scripts/          # core.sh, popcorn_build/, QEMU helpers
├── src/
│   ├── link.ld
│   ├── core/         # C + asm kernel
│   ├── rust/         # popcorn_kernel crate
│   ├── uefi/         # BOOTX64.EFI loader
│   ├── pops/         # remaining C pops (Dolphin)
│   └── includes/
└── target/           # build outputs

Only the linked ELF (and UEFI loader) run in the guest. Scripts are host-side.

Boot

UEFI: BOOTX64.EFI → handoff → kernel
GRUB: Multiboot2 ISO → ELF @ 0x100000 → start

start (kernel.asm)
  identity / direct map
  long mode
  kmain → init → shell

CI runs test-uefi on both UEFI and GRUB smoke paths.

Init order

init / kmain bring-up (typical)
  multiboot / UEFI tags
  memory_init (PMM + VMM)
  idt + PIC
  rust_init → driver registry + screen/kbd/…
  timer + scheduler
  pops register
  console handoff → shell

Display drawing is Rust (tty0/fb0). Console UX stays in C as a client.

Syscalls

open, read, write, close, ioctl
gettime, sleep, yield
malloc / free (heap)
getcwd / chdir (where wired)

Device calls go through the drive registry. Full ring-3 ABI is still ahead.

Reading map

Concern	Primary files
Entry / long mode	core/kernel.asm, link.ld
UEFI loader	uefi/bootx64.c
Init / shell	core/init.c, core/shell.c, core/kernel.c
Memory	core/memory.c, core/vmm.c
IRQ / timer / sched	core/idt.c, irq.c, timer.c, scheduler.c
Syscalls	core/syscall.c
Rust drivers / pops	rust/popcorn_kernel/src/
Build / CI	scripts/core.sh, .github/workflows/ci.yml

Caveats

v0.7 is pre-1.0. User processes and full isolation are not done.

Internal disks stay locked until an explicit install unlock.

Scheduler still uses bootstrap guards around early PIT ticks.