ESP32: Compiler-Directed ISR and IRAM Support

• Type: feature
• Status: DONE 2026-06-21 (iram; done 2026-06-18; interrupt; Call0 done both ISAs 2026-06-21; windowed interrupt; ruled out-of-scope by design with a sharpened compile-error — see Decision below). User-facing peripheral callbacks split to feature-esp-peripheral-callback-api (Track B).
• Owner: —
• Opened: 2026-06-14 (from ESP32 ISR analysis)

Decision 2026-06-21 — windowed interrupt; is out of scope BY DESIGN (not a gap)

interrupt; is a raw hardware-vector directive: the proc is entered directly by the CPU as a vector, saves its own context, and returns via the exception-return insn (riscv mret, xtensa rfe). Two independent axes decide where that is valid:

The windowed + raw-vector cell has no valid configuration: bare-metal xtensa can't boot windowed, and under IDF you never install a raw vector — you register a normal callback via esp_intr_alloc, and FreeRTOS does the window spill for you. A windowed raw interrupt; would have to emit a Tensilica-style window-spill loop inside the ISR — duplicating the FreeRTOS dispatcher, untestable here (bare windowed doesn't boot; IDF wouldn't use it), and a loop-in-ISR hazard. Rejected.

Resolution:

• Windowed interrupt; stays a compile error; sharpen the message to route to the two real paths (bare → Call0 interrupt;; IDF → iram; + esp_intr_alloc). (This is the only remaining code change; then this ticket → done.)
• The user-facing "interrupt" (a timer/ADC/GPIO callback, which most users mean when they say "interrupt") is a library concern, not this keyword → filed as feature-esp-peripheral-callback-api (Track B). The interrupt; keyword serves only the bare-metal raw-vector author.
• interrupt; (Call0) on riscv32 + xtensa is DONE and is the complete, correct scope for this keyword.

Status 2026-06-18 — iram; DONE (both ISAs)

procedure foo; iram; places the routine's machine code in a new ELF .iram1.text section (the IDF linker script routes it to internal IRAM). Validated: readelf -S shows .iram1.text PROGBITS / AX (ALLOC|EXECINSTR) on esp32s3 (xtensa) + esp32c3 (riscv32); test_esp_iram runs under qemu == x86-64 oracle (S/ABC/ABCDE/E). make test + cross-bootstrap byte-identical.

Design (single Code[] buffer, low-risk): .text = the full Code[] verbatim (each iram proc keeps a dead twin there so flash PC-relative call offsets computed at emit time stay valid); .iram1.text = a live duplicate of each iram proc's contiguous byte-range (internal relative branches + xtensa l32r literal pools survive because the whole proc moves as a unit). Cross-section calls (flash↔iram) can't stay PC-relative, so EmitCallProc lowers them to an indirect literal-slot call (same shape as an external call) recorded as an IramCallFix and relocated R_*_32 against the callee proc's own local symbol. The extended writer (writeELF32RelIram, gated on any iram proc so the proven non-iram path is byte-identical) partitions relocations by which text section their CodePos lands in and emits proc symbols with st_shndx = .iram1.text for iram procs. On non-ESP targets iram; is an accepted no-op (same source builds as the x86-64 oracle).

Status 2026-06-21 — interrupt; DONE on riscv32 (esp32c3); structurally verified

procedure foo; interrupt; now compiles a raw hardware trap handler on riscv32 (9ab4304). Prologue saves the interrupted caller-saved context (t0-t6, a0-a7; ra/s0 via the normal frame, 64-byte save area above the frame), the body runs, the epilogue restores that context and returns via mret (added rv32_mret). interrupt implies iram, so the handler lands in .iram1.text (existing placement + cross-section call lowering). Gated on ProcIsInterrupt → non-interrupt riscv codegen byte-identical, self-host unchanged.

Verified structurally (test/test_esp_interrupt.pas + --emit-obj, riscv32-esp-elf-{readelf,objdump}): MyIsr sits in .iram1.text; the disasm shows the full t0-t6/a0-a7 save, the normal ra/s0 frame, a working cross-section indirect call into flash (esp_rom_printf), the mirrored restore, and mret.

Remaining:

• Live trap validation. Installing the handler in mtvec + triggering a real trap isn't expressible in PXX yet — the rv32 inline-asm dialect has no CSR ops (csrw mtvec, csrrs mstatus) and @isr/ProcAddrFix (below) still errors, so nothing in PXX can point the vector at the handler. Options: add CSR ops + mret/wfi to asmtext_rv32.inc for a self-contained bare trap test; or fix ProcAddrFix so the handler address can be handed to a setup routine; or run on real esp32c3 hardware. (This is the "not qemu-validatable without a vector table" the deferral noted.)
• xtensa interrupt; (Call0) — DONE 2026-06-21; structurally verified. procedure foo; interrupt; now compiles a raw level-1 exception handler on xtensa Call0. Prologue saves the interrupted caller-saved a-regs the body clobbers (a2-a8, a10-a13) in a 48-byte area above the normal Call0 frame (a0/a15 via that frame; a9/a14 never touched by codegen); the body runs; the epilogue restores them and returns via rfe (general level-1, PC<-EPC1, PS.EXCM cleared) — added xtensa_rfe ($003000, oracle-verified) to xtensaenc.inc. Gated on ProcIsInterrupt (inline check; symtab can't call backend helpers) → non-interrupt xtensa codegen byte-identical, self-host fixedpoint unchanged. Verified structurally (test/test_esp_interrupt.pas xtensa arm, --emit-obj, xtensa-esp32s3-elf-{readelf,objdump}): MyIsr sits in .iram1.text with the full a2-a13 save, the normal a0/a15 frame, a working cross-section indirect call into flash (callx0 a8 via a relocated literal → esp_rom_printf), the mirrored restore, and rfe. Windowed ABI still errors with a clear message (--xtensa-abi=windowed): mid-window register-file spill is the deferred hard part. Live-fire still needs a vector-table install (no Xtensa CSR/inline-asm from PXX) — same QEMU-unvalidatable gap as riscv below. Historical plan kept below:
• xtensa interrupt; — original plan (now implemented above). Was erroring (parser.inc, the isInterrupt and TargetArch <> TARGET_RISCV32 guard). Mirror the riscv shape but for the Xtensa exception/interrupt model:
  • Where: EmitProcPrologue / EmitProcEpilog xtensa branches (symtab.inc, same ProcIsInterrupt[CurProc] gate as riscv). interrupt already implies iram so .iram1.text placement is free.
  • Save/restore: preserve the interrupted caller-saved context. On the bare Call0 profile (start here, simplest — --esp-profile=bare forces Call0) save the a-regs the body clobbers (a2-a15 less the frame regs; codegen uses a2-a8, a10-a13) to a fixed save area above the frame, mirror on exit. The windowed ABI is the hard part — an interrupt can hit mid-window; needs the window spilled (or a dedicated interrupt stack) — defer windowed until Call0 works.
  • Return: not a normal ret. Level-1 interrupt/exception returns via rfe (return-from-exception, PS.EXCM) for the general exception, or rfi 1 for a high-priority level-1 interrupt; EPC1/EPS1 hold the restart PC/state (set by HW). Pick rfe for the general-exception vector path; document the level assumption.
  • Encoders: add xtensa_rfe/xtensa_rfi/wsr/rsr to xtensaenc.inc (encoding oracle: xtensa-esp32s3-elf-as — same one used for the FP insns; llvm-mc-18 lacks Xtensa FP/CSR). rfe=0x003000, rfi n=0x003010|(n<<4) (verify with the oracle).
  • Validate: structural only, same as riscv (--emit-obj + xtensa-esp32s3-elf-objdump: handler in .iram1.text, save/restore + rfe). Live-fire needs a vector-table install (no Xtensa inline-asm/CSR from PXX yet), so it's QEMU-unvalidatable without that scaffolding — same gap as riscv below.
  • Reference: the riscv implementation (9ab4304) is the template; arm32's register-pair save shapes are unrelated here.
• @isr proc-address fixups in the .o — DONE 2026-06-21 (fef87c2) for the iram-writer path (writeELF32RelIram): each IR_PROCADDR literal gets an absolute R_*_32 reloc against the target proc symbol, so @MyIsr handed to esp_intr_alloc resolves to the linked handler. ISR/@isr programs always have an iram routine -> that writer. (Non-iram --emit-obj @proc still guards.) Verified: test_esp_isr_register --emit-obj shows R_RISCV_32 vs MyIsr + vs esp_intr_alloc. KNOWN MINOR wart: IR_PROCADDR lowers a single source @ twice (idempotent literals, one dead) — pre-existing, target-independent, separate cleanup.

@proc on bare riscv32 — DONE 2026-06-21 (38242eb)

@Routine now yields the absolute code address on the bare ET_EXEC image: IR_PROCADDR emits a PC-relative inline-literal load (auipc/jal/literal/lw) recorded as a ProcAddrFix, patched to entry+BodyAddr by writeELF32 (the generic patch loop already existed; the esp32 guard was relaxed for riscv32). test_esp_procaddr matches the x86-64 oracle on esp32c3. This is the first half of the @isr path; the .o relocatable writers still need it (above), as does a self-contained live trap test (still also blocked on CSR setup: no rv32 inline asm / CSR ops to write mtvec).

Motivation

To support safe execution of Interrupt Service Routines (ISRs) under both bare-metal (esp32-bare) and SDK-hosted (esp32-idf) profiles. Code executing in an interrupt context must reside in internal Instruction RAM (IRAM) to prevent cache fetch exceptions when the flash cache is disabled. The compiler needs language-level keywords to route specific procedure code to IRAM and wrap raw bare-metal hardware interrupt registers.

Scope

• Language Directives:
  • iram;: Compiles the procedure normally (matching the target's default ABI calling convention) but places its machine instructions in the .iram1.text section. Suitable for ESP-IDF registered ISRs and helper functions.
  • interrupt;: Compiles the procedure as a raw hardware interrupt vector handler. Emits an assembly prologue/epilogue to save and restore all CPU registers, returns via the target's hardware interrupt return instruction (e.g., mret on RISC-V), and places the code in the .iram1.text section. Suitable for bare-metal vector tables.
• Pascal Standards Alignment:
  • Free Pascal (FPC) and Delphi define the interrupt; directive to denote a hardware interrupt routine that handles its own register saving/restoring and interrupt return sequence. We adopt this standard behavior.
  • We introduce iram; as a custom compiler attribute/directive to designate RAM-resident functions without modifying the standard calling conventions.
• Calling Conventions:
  • For procedures decorated with iram;, the compiler automatically matches the active target's standard C calling convention (e.g., RISC-V 32-bit ilp32 / cdecl or Xtensa windowed/call0 ABI as configured by target flags). The programmer does not need to specify manual calling conventions in the procedure signature.
• ELF Relocatable Object Writer:
  • Update writeELF32Rel in [elfwriter.inc](file:///home/rene/frankonpiler/compiler/elfwriter.inc) to define and output the .iram1.text section.
  • Partition the compiler's unified Code buffer by section, adjusting internal symbol offsets and relocation targets dynamically.

Non-goals

• Enforcing FreeRTOS/ISR-safe API calling limits at compile time.
• Generating automated vector table routing from the compiler (handled by developer code or SDK APIs).

Acceptance

• Compiler accepts procedure declarations with the new directives:

  procedure my_gpio_isr(arg: pointer); cdecl; iram;
  procedure my_raw_hw_isr; interrupt;
  
  

• Executing ./pascal26 --target=riscv32 --emit-obj produces an ELF object containing both .text (Flash) and .iram1.text (IRAM) sections.
• readelf -S verified correct section headers, flags (SHF_ALLOC | SHF_EXECINSTR), and offsets.
• Linking with ESP-IDF puts .iram1.text in IRAM, and the application runs safely in cache-disable states.