Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
91 lines (66 loc) · 2.57 KB

ARCHITECTURE.md

File metadata and controls

91 lines (66 loc) · 2.57 KB
Raw

Architecture

Components

Build system

Makefile downloads pinned PongoOS, cctools-port, and DoomGeneric revisions. It cross-compiles DoomGeneric and the DFUoom platform layer for ARM64 and links them as a Mach-O KEXT bundle that the PongoOS module loader understands. A small tracked DoomGeneric patch removes unsupported filesystem writes and routes WAD existence checks to the in-memory runtime.

Host controller

tools/dfuoomctl.py uses PyUSB to:

  • find Apple DFU or PongoOS USB devices;
  • write PongoOS shell commands with a USB control request;
  • upload modules and WAD data through the PongoOS loader protocol;
  • convert terminal or Linux evdev events into Doom key edges.

PongoOS module

src/dfuoom_pongo.c registers these commands:

dfuoom
dfuoom-key
dfuoom-keys-reset
dfuoom-stop
dfuoom-status

The start command validates the uploaded WAD, binds the loader buffer as the active game-data source, clears the screen, suppresses PongoOS input echo, and creates a cooperative Doom task.

DoomGeneric lifecycle

The task calls:

doomgeneric_Create(argc, argv);

while (!doom_stop_requested)
{
    doomgeneric_Tick();
    task_yield();
}

doomgeneric_Create() allocates a 320x200 32-bit screen buffer and initializes the original Doom subsystems. Each tick advances simulation time, consumes input events, and renders the current frame.

In-memory WAD

src/dfuoom_runtime.c validates the WAD header and directory bounds. src/w_file_memory.c implements Doom's file interface over the PongoOS upload buffer, so the engine reads the user-supplied WAD without a filesystem.

Display

PongoOS exports:

gFramebuffer
gWidth
gHeight
gRowPixels

The destination dimensions are discovered at runtime. The renderer rotates the 320x200 Doom frame clockwise and independently scales both axes to fill the portrait physical framebuffer as a landscape image. It uses rational error accumulation rather than division for every pixel, then cleans the affected CPU cache so the display controller sees the completed frame.

The source resolution and clockwise orientation are fixed; the destination resolution and stride are not hardcoded.

Input

Host key-down/key-up edges are sent as PongoOS commands and placed in a bounded ring buffer. A 256-entry state table coalesces repeated states such as two consecutive fire down events. DoomGeneric consumes the queued events through DG_GetKey().

While Doom is running, PongoOS serial RX echo is disabled. USB command input continues to work, but command text and new shell prompts are not drawn over the game.