dma-cpu

CPU made of DMA on Raspberry Pi Pico.

The DMA controller in the RP2 microcontroller family (RP2040, RP2350, and compatible chips) is Turing-complete. This project builds a full toolchain for it: an emulator, an assembler/linker, a program loader, a C compiler riding stock clang, and an xv6-derived kernel that runs entirely on DMA channels. See prompts/overview.md for the design analysis, the phased development plan, and references.

Layout

The tree is split by where code runs: host/ is the Go toolchain that runs on your dev machine, target/ is the C that runs on the Pico. Everything else is docs, examples, and vendored dependencies.

host/ — the Go toolchain

• host/emu/ — dmaemu core: a deterministic, DMA-machine-level emulator of the RP2 DMA subsystem (channels, triggers, chaining, DREQ credits, pacing timers, sniffer, atomic register aliases). Both SKUs are supported via emu.Variant (emu.RP2040, emu.RP2350) — the CTRL bit layout, register offsets, sizes, and DREQ numbers differ between them, so programs are assembled per SKU. The golden tests in host/emu/machine_test.go build the machine's ALU and control-flow idioms block by block, run the whole suite on both SKUs, and prove out the interrupt-dispatch design from prompts/overview.md §3.2.
• host/dmaasm/ — the assembler: SKU-portable .dasm sources (labels, literal pools, instruction-field addressing, the ABI v0 register file and macro instruction set — see references/design_docs/abi.md) assembled into SKU-specific DMX executables with a symbol table. Validated on silicon: the HIL firmware runs assembler-produced binaries.
• host/dmacc/ + host/llir/ — the C toolchain: llir parses clang's LLVM IR, dmacc lowers it to SKU-portable .dasm. Differential tests in host/dmacc/testdata/ pin it against host clang.
• host/trace/ + host/pgo/ — the measurement side: trace attributes the emulator's per-word read counts back to code (compiled function, block, comparison site, runtime/millicode helper) through the .dasm label stream and prints a ranked report; pgo holds the generated profile-guided settings those measurements produce (make pgo). host/dmacc/testdata/ratchet.txt pins the resulting sizes and cycle counts, and make test fails on any drift (make ratchet).
• host/img/ — the DMX executable format (references/design_docs/dmx.md): builder, encoder/decoder, and the reference loader with Tier-2 relocation (same image runs at any placement). host/fsimg/ builds xv6 filesystem images and the golden vfat volumes.
• host/boards/ — deployable-target descriptors (SKU, memory partition, flash sections, installed apps); host/prog/hil/ holds the HIL test programs as embedded .dasm assets.
• host/cmd/ — the CLIs: dmaemu (runs a raw block image or DMX executable under a JSON config, reporting JSON), dmaasm, dmacc, dmxgen (builds a board's images and bakes them, with their emulator expectations, into the firmware header), and sldgen (converts images into slides for the viewer).

target/ — bare-metal C for the Pico

• target/loader/ — the DMX loader for the RP2 side; parses DMX, relocates, and starts the machine. No SDK dependency; build with -DDMX_TARGET_RP2350 for RP2350 (RP2040 is the default). Validated on both SKUs' silicon.
• target/firmware/ — the ARM-side bootloader: it sets the clocks, stages the flash-resident images, loads the SRAM segments through the loader, starts the DMA machine and parks. Built with HIL_DEV=1 it also carries the hardware-in-the-loop battery, where dmxgen bakes emulator-computed expectations into the firmware and the boot run reports expected-vs-observed over UART. The emulator is silicon-calibrated against a Pico 2; see prompts/004-hw-calibration.md for the results (all golden tests pass on hardware at ~10 M blocks/s).
• target/libc/ — the DMA machine's C library: DMA-specific config and glue (committed) plus the vendored picolibc submodule (target/libc/picolibc) it is compiled from. make libc turns the curated picolibc sources into the IR goldens in target/libc/ll/, which dmacc links into programs — see target/libc/README.md. target/game/ is the DMA-driven game console; target/xv6/ is the xv6-derived kernel port (target/xv6/PORT.md).

Everything else

• docs/ — human-facing guides: how to build the firmware (building-firmware.md) and how to wire the hardware (building-hardware.md).
• prompts/ — the phased design log: the analysis in overview.md and a per-phase results document for each step.
• references/ — material to consult, none of it compiled here: datasheets/ (the RP2040/RP2350 and peripheral datasheets), design_docs/ (the project's own specs — abi.md and dmx.md), and source trees read rather than built — some of them the origin of a port that now lives under target/, each attributed in LICENSE. Contrast target/libc/picolibc, which is compiled and linked. The reference article stays untracked (see Coding rules in prompts/overview.md).
• examples/ — standalone programs built through the toolchain.

Build and test

$ make build   # builds bin/dmaemu, bin/dmaasm, bin/dmacc
$ make test    # go vet + golden tests

Requires Go ≥ 1.26. No dependencies outside the standard library.

Special Thanks

This project is heavily inspired by the original idea published by the authors in Cornell University.