README

esp-units.pas — Pascal utilities and compiler-verification programs for ESP32 MCUs

A light, readable project: FreePascal source only. The compiler (fpc), the SDK (esp-idf) and the emulator (qemu-system-xtensa, Espressif build) are external tools — this repo ships none of them.

It contains two kinds of things:

1. Test programs — verify and demonstrate what this compiler can do on real ESP32 MCUs: a curated subset of the FPC trunk regression suite (t_*.pas, provenance embedded line-by-line), capability demos (t_generics_collections_tstack.pas, t_encoding_roundtrip.pas), and designed-failure demos of the threading contract (tests/thread-stubs/). tests/run-tests.sh compiles each one with the cross compiler and boots it in QEMU, classifying the result (PASS = clean boot, clean exit).
2. Utility units — one subdirectory per unit under units/, programmer conveniences dedicated to ESP32:
   • idfheap (units/idfheap.pp) — bridge to the IDF heap manager: all Pascal dynamic memory flows into the IDF pool (PSRAM-eligible once enabled) instead of a compiler-baked static block.
   • an atomics unit pair — atomic operations for ESP32 dual-core (and other ESP family) SoCs, shipping as a frozen unit directory: an Interlocked-style baseline that the freertos RTL lacks, fetch/CAS/acquire-release machine-level atomics on top of the chip's compare-and-swap instruction, and an atomic spin lock. Multi-SoC by construction: an xtensa backend (S3/S2/classic), an RV32A backend (C3/C6), an ARM32 backend, and a stock fallback; the active backend is selected at compile time. Unit directories and APIs (including the frozen atomics directory) are documented in units/README.md.

Quickstart

Scripts take no host-path defaults. Export the toolchain locations first (scripts/build.sh --help prints the same contract with concrete examples):

export ESP_IDF_VERSION=6.1                 # whatever -WP your RTL expects
export ESP_IDF_PATH=/path/to/esp-idf       # or set ESP_PYTHON_BIN
# optional: ESP_TOOLCHAIN_BIN, ESP_PYTHON_BIN, ESP_QEMU, ESP_EMU

# ESP_FPC_ROOT = install for *this* build. Switch it when you switch SoC.
# --soc only selects ppcrossxtensa vs ppcrossrv32 + MCU flags inside that root.

export ESP_FPC_ROOT=/path/to/fpc-cross-xtensa
export ESP32_SDK_PROJECT=/path/to/built-idf-project-for-s3
scripts/build.sh examples/idfheap-smoke.pas
scripts/run-qemu.sh examples/idfheap-smoke.elf

export ESP_FPC_ROOT=/path/to/fpc-cross-riscv32
export ESP32_SDK_PROJECT=/path/to/built-idf-project-for-s31
scripts/build.sh --soc esp32s31 examples/idfheap-smoke.pas
scripts/run-esp-emu.sh examples/idfheap-smoke.elf

A Pascal program that calls C needs no separate build step and no change to the IDF project: name the C sources on the same command line.

scripts/build.sh my-prog.pas --c my-module.c     # --obj / --lib also accepted

--c compiles with the derived cross gcc, reusing the compile command IDF recorded for the project's main/ component (build/compile_commands.json), so the headers and chip flags match the rest of the build; the object is linked along with the Pascal one. See AGENTS.md §4 for the details.

SoC support

Prerequisites (all external, all required via env)

Layout