Skip to content

feat(esp32c2): onboard ESP32-C2 (ESP8684H4X); bare ELF and esp-hal 1.2 on the mask ROM - #1956

Open
w1ne wants to merge 5 commits into
mainfrom
feat/esp32c2-onboard
Open

w1ne wants to merge 5 commits into
mainfrom
feat/esp32c2-onboard

Conversation

@w1ne

@w1ne w1ne commented Nov 16, 2026

Copy link
Copy Markdown
Owner

Conclusion

Adds configs/chips/esp32c2.yaml: ESP32-C2 as the ESP8684H4X (RV32IMC, 120 MHz, 4 MB in-package flash). It boots a committed bare ELF that prints on UART0 and toggles GPIO10. No model code.

Demand rank #1 (ESP32 family, 38% in JetBrains State of Embedded 2025). Espressif lists the ESP8684 as the replacement for the NRND ESP8266EX / ESP8285.

Evidence

  • Live status: on the Espressif product selector API (2026-11-16), ESP8684H4X reads Mass Production (USD 1.32). ESP8266EX reads NRND, replaced by ESP8684H2X. LCSC lists ESP8684H4 as in stock.
  • Memory map: esp-idf v5.3 components/soc/esp32c2/include/soc/{soc.h,reg_base.h}.
  • Engine reuse: in esp-idf v5.3, the C2 and C3 versions of uart_reg.h, systimer_reg.h and timer_group_reg.h have identical offsets. gpio_reg.h is identical except for the C3-only GPIO21 registers. io_mux_reg.h differs above GPIO18, so IO_MUX is not declared.
  • cargo test -p labwired-core --test vendor esp32c2: 3 passed. The tests check that the UART0 output is exactly Hello from ESP32-C2\r\n, that GPIO10 toggles and GPIO9 stays idle (negative control), that 0x3FCE0000 is unmapped (DRAM end) and that the descriptor matches the product data.
  • labwired test --script examples/esp32c2/uart-smoke.yaml: PASS 2/2.
  • --test gates (chip_conformance, board_coverage, firmware_survival, chip_memory): 135 passed. --test bus bus_visibility::: 3 passed after the EXCLUSIONS row. Baselines and docs are regenerated.
  • Known failure that is not from this PR: labwired-config chip_pins_ratchet::every_chip_is_accounted_for reports atmega32u4 on main (8403837ba) too.

Not modelled

Mask ROM contents and ROM boot (so stock ESP-IDF/Arduino images do not run), IO_MUX, the interrupt matrix, SYSTEM/RTC clocking, I2C, SPI, LEDC, ADC, GDMA, crypto, Wi-Fi and BLE. This is local simulator evidence, not hosted model_verified.

🤖 Generated with Claude Code

github-actions Bot and others added 4 commits November 16, 2026 01:55
Demand rank #1 (ESP32 family, 38%). The ESP8684 is Espressif's listed
replacement for the NRND ESP8266EX/ESP8285; ESP8684H4X reads "Mass
Production" on the Espressif product selector (2026-11-16).

configs/chips/esp32c2.yaml takes its memory map from esp-idf v5.3
components/soc/esp32c2 soc.h/reg_base.h (IROM/DROM 4 MiB, DRAM
0x3FCA0000..0x3FCE0000, IRAM 272 KiB, ROM 576 KiB, 120 MHz). It reuses the
C3 UART, GPIO, SYSTIMER and TIMG engines only; their v5.3 register headers
are offset-identical between C2 and C3. IO_MUX is left out because the C2
pad offsets differ above GPIO18. No model code.

Evidence: a committed RV32IMC ELF (examples/esp32c2) checks MUL/DIVU and
the last DRAM word, prints "Hello from ESP32-C2" on UART0 and toggles
GPIO10 (GPIO9 negative control); a second test requires 0x3FCE0000 to be
unmapped. Registered in chip_conformance, board_coverage_ratchet,
chip_pins_ratchet, bus_visibility EXCLUSIONS, firmware_exercise, bus_proof,
docs-runnable, board_perf WAIVED and the coverage-matrix smoke.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: w1ne <41898282+w1ne@users.noreply.github.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: w1ne <41898282+w1ne@users.noreply.github.com>
esp_hal::init, esp-println on UART0, GPIO8 output and Delay on SYSTIMER
now run on the esp32c2 descriptor (examples/esp32c2/esp-hal, fixture
tests/fixtures/esp32c2-esp-hal-delay.elf, reproducible from the example).

- Vendored mask ROM from esp-rom-elfs 20260528 esp32c2_rev200_rom.elf,
  flattened by load address so the .data initialisers and .rodata are in
  the image (scripts/make_esp32c2_rom_bin.py, roms/esp32c2/README.md).
  The DROM window is an alias_of mirror of IROM 0x40040000.
- Fast boot replays the ROM's own _rom_store_table (boot/esp32c2_rom.rs);
  without it rom_i2c_readReg jumps through a zero rom_phyFuns to
  0xFFFFFFFE (negative-control test).
- SYSTEM, RTC_CNTL, EFUSE, INTERRUPT_CORE0, SENSITIVE, EXTMEM, IO_MUX,
  SPI0/1, APB_CTRL, ASSIST_DEBUG, BB, MODEM_CLKRST as declarative files
  generated by svd-ingestor from Espressif esp32c2.svd v10.
- Analog I2C master: the C6 model with a new ana_conf0_offset config
  (C2 ANA_CONF0 at 0x6004E840, esp32c2 PAC 0.30).
- Radio NRX/FE/FE2 power-up registers that esp-hal rtc_sleep_pu writes.

Measured: CLI esp-hal smoke PASS 2/2; vendor esp32c2 5/5; lib unit 6/6;
gates chip_conformance 8/8 (baseline regenerated); bus_visibility 3/3.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: w1ne <41898282+w1ne@users.noreply.github.com>
@w1ne w1ne changed the title feat(esp32c2): onboard ESP32-C2 (ESP8684H4X) bare-ELF slice feat(esp32c2): onboard ESP32-C2 (ESP8684H4X); bare ELF and esp-hal 1.2 on the mask ROM Nov 16, 2026
@w1ne

w1ne commented Nov 16, 2026

Copy link
Copy Markdown
Owner Author

Commit 4910854: esp-hal 1.2.2 (init, esp-println on UART0, GPIO8, SYSTIMER Delay) now boots on the esp32c2 descriptor.

  • Vendored mask ROM from esp-rom-elfs 20260528 esp32c2_rev200_rom.elf, flattened by load address (provenance in crates/core/roms/esp32c2/README.md); DROM is an alias_of mirror of IROM 0x40040000.
  • Fast boot replays the ROM's own _rom_store_table (boot/esp32c2_rom.rs). Negative-control test: without it, rom_i2c_readReg jumps to 0xFFFFFFFE.
  • System blocks as declarative files from Espressif esp32c2.svd v10 (svd-ingestor); analog I2C master = the C6 model with a new ana_conf0_offset key.

Local results: esp-hal CLI smoke PASS 2/2 (ticks 2052-2117 us); --test vendor esp32c2 5/5; lib unit 6/6; chip_conformance 8/8 (baseline regenerated); bus_visibility 3/3; model ratings current. Fixture rebuilds byte-identical from examples/esp32c2/esp-hal.

🤖 Generated with Claude Code

An esp-hal 1.2 FROM_CPU software interrupt and a 1 ms SYSTIMER alarm now
reach their #[handler]s on the esp32c2 fast boot (examples/esp32c2/
esp-hal-irq, fixture tests/fixtures/esp32c2-esp-hal-irq.elf). Before,
SoftwareInterrupt::raise spun forever on INTR_STATUS.

- The single-bank INTERRUPT_CORE0 control offsets (CPU_INT_ENABLE,
  CPU_INT_PRI_0, CPU_INT_THRESH, INTR_STATUS_REG_0, FROM_CPU_0 MAP) are
  read from the chip's register descriptor by ID (MatrixCtrlOffsets). The
  C3 descriptor yields the old constants; C2 gives 0xB8/0xC8/0x148/0xAC/36,
  which the C2 mask ROM _interrupt_handler also uses.
- The bus mirrors asserted source levels into INTR_STATUS_REG_0/1.
- `irq:` sets the matrix source of the C3-family GPIO and SYSTIMER models
  (C2: 13 and 26).
- C2 fast boot (builder, world node, `labwired test`) arms matrix routing,
  sets mstatus.MIE as the ROM's ets_intr_unlock leaves it, and parks
  mtimecmp (no CLINT).
- No new as_any(): the status write shares a poke helper with PMS.

The round-681 esp-hal smoke needs 3M steps now: routing disables CLI batch
mode, so the UART drain takes more steps.

Measured: vendor esp32c2 9/9 (4 new, with a not-armed negative control);
CLI smokes esp-hal-irq 2/2, esp-hal 2/2, uart 2/2; core lib
c3/c6/classic/pms/downcast subset 203 passed; gates 160 passed;
bus_visibility 3/3; model ratings --check current.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: w1ne <41898282+w1ne@users.noreply.github.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant