Skip to content

Model classic ESP32 UART idle timeout and nonempty-FIFO clear behavior - #6

Merged
levkropp merged 1 commit into
levkropp:masterfrom
bgates747:codex/uart-idle-timeout
Nov 9, 2026
Merged

levkropp merged 1 commit into
levkropp:masterfrom
bgates747:codex/uart-idle-timeout

Conversation

@bgates747

@bgates747 bgates747 commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Prepared by Codex on behalf of Brandon

This PR fixes classic ESP32 RX timeouts firing immediately and being cleared
while unread bytes remain. The first timeout now waits for the configured idle
interval, then stays asserted until the receive FIFO is drained and the
interrupt is acknowledged.

The classic UART descriptor
does not specify a timeout threshold register, so
uart_rx_timeout_modeled
selects the legacy behavior for that chip. This revision enables the classic
port in the shared model introduced in a20c094. Its APB and REF_TICK threshold
units follow Espressif's classic UART HAL.

The regression injects three bytes and waits for
the first timeout, then tries to clear it with zero, one or two bytes read.
Raw status, masked status and CPU interrupt delivery must remain asserted
until the final drain and acknowledgement. It covers all three classic UARTs,
APB/REF_TICK deadlines, fractional dividers, new-input restart and timeout
disable/re-enable. A shared reset check and existing S3 tests are also included.

The revised patch passes all four new regression tests and all 13 existing
UART/S3/system-clock/deferred-event tests: 815 assertions, zero failures.
Tested against 9372d98c30289d3f3576e720d645553f2133747e on Linux x86_64,
GCC 15.2, Release with LTO/native tuning disabled.

The standalone reproducer
runs the same regression against the unmodified base and the corrected code.
It includes the test-only and source-only patches so the before/after behavior
can be checked independently.

To run the four new regression tests:

cmake -S . -B build -DNATIVE_ARCH=OFF -DFLEXE_LTO=OFF -DFLEXE_CCACHE=OFF
cmake --build build --target xtensa-tests --parallel 2
./build/xtensa-tests --quiet classic_uart_timeout_ shared_uart_timeout_reset_cancels_pending

@levkropp

levkropp commented Nov 7, 2026 •

Copy link
Copy Markdown
Owner

I tested the re-fire case on real hardware. On two ESP32-S3 boards (rev v0.2, UART1 in internal loopback, interrupts off, polling INT_RAW), RXFIFO_TOUT can't be cleared while the RX FIFO holds data: after INT_CLR the raw bit reads set again within about 1 µs, whether 1, 2 or none of 3 bytes were read. The clear only holds after a full drain. The first timeout does wait for the threshold: 73, 421, 854 and 1721 µs for 10, 50, 100 and 200 bit times at 115200 baud.

For the original ESP32, the TRM says the same thing: RXFIFO_TOUT_INT_CLR "can be set only when both rxfifo_cnt and rx_mem_cnt are 0", and an Espressif engineer confirmed it in espressif/esp-idf#2204. I haven't measured a classic chip.

So the delayed first timeout in this PR is right, but instead of re-arming after another idle interval, clearing TOUT should have no effect while the FIFO is non-empty. I landed that model for the S3 in a20c094. The threshold register is described per target in flexe_uart_ip_desc_t, so the classic ESP32 can use the same path by filling in its CONF1 threshold and your unit conversion. Could you rebase onto that and switch the classic port over?

@bgates747
bgates747 force-pushed the codex/uart-idle-timeout branch from 614deb5 to 6bdfc6f Compare November 8, 2026 01:29
@bgates747 bgates747 changed the title Rearm classic ESP32 UART RX idle interrupts while unread bytes remain Model classic ESP32 UART idle timeout and nonempty-FIFO clear behavior Nov 8, 2026
@bgates747

Copy link
Copy Markdown
Contributor Author

Prepared by Codex on behalf of Brandon.

Thanks for testing this on hardware. I've rebased this PR onto 9372d98c and switched classic ESP32 to your shared timeout path, with its CONF1 threshold and timeout-unit conversion. Clearing the timeout while bytes remain in the FIFO now leaves it set.

The revised patch passes all four new regression tests and all 13 existing neighboring tests: 815 assertions, zero failures.

@levkropp
levkropp merged commit 82917d1 into levkropp:master Nov 9, 2026
6 checks passed
@levkropp

levkropp commented Nov 9, 2026

Copy link
Copy Markdown
Owner

Thanks, merged as 82917d1. I checked it locally against master as well: the full unit suite, and both Agon gates in both engines, with identical pixels and UART traffic and no timing change.

One open question for the record: in REF_TICK mode this follows ESP-IDF's ×8, i.e. 1/8 bit per RX_TOUT_THRHD unit. The ESP32 TRM's register description gives 8 × REF_TICK / APB = 0.1 bit instead, and ESP-IDF's original 2018 workaround used a factor of 10 before v4.1 switched to a literal 8 with no stated reason (its comment still says "10 times"). Espressif's QEMU and esp-hal ignore REF_TICK altogether, and I couldn't find anyone who has measured it. Since Arduino-ESP32 3.1+ selects REF_TICK at 250000 baud and below, it's worth settling: a loopback test that writes the raw register at two thresholds and takes the slope would do it, if you have a classic board handy.

For comparison, on two ESP32-S3 boards one threshold unit measured as one bit time of the selected source clock (APB, XTAL and RC_FAST, at 115200 and 9600 baud), with the timeout firing about 1.5 bit times before the transmitter's idle point.

@levkropp

levkropp commented Nov 9, 2026

Copy link
Copy Markdown
Owner

Follow-up on the REF_TICK question, measured on an ESP32-S2 (S2FNR2, rev v1.0), which shares the classic ESP32's APB/REF_TICK UART clocking. Same method as before: UART1 in internal loopback, interrupts off, the raw RX_TOUT_THRHD register written at 20 and 200, and the time per unit taken from the slope.

Source Baud Bit time Time per unit Units in bits
APB 115200 8.680 µs 8.672 µs 0.999
APB 9600 104.167 µs 104.161 µs 1.000
REF_TICK 115200 8.625 µs 8.000 µs 0.927
REF_TICK 9600 104.134 µs 104.000 µs 0.999

So on the S2 one unit is one bit time in both modes. There is no REF_TICK anomaly: not the TRM's 0.1 bit, and not ESP-IDF's 1/8 bit (ESP-IDF's S2 code applies no factor, which matches). The counter also ignores the baud divider's fractional part. With REF_TICK at 115200 the divider is 8.625, and one unit is exactly 8 REF_TICK periods (8.000 µs); at 9600 it is exactly 104 µs. The APB results fit the same rule (694/80 MHz = 8.675 µs).

This doesn't settle the classic ESP32: ESP-IDF's 2018 "hardware issue workaround" suggests the classic chip has a REF_TICK problem the S2 may not share. The open candidates for classic REF_TICK are 8 bits per unit (what Espressif's QEMU and esp-hal assume, and what an S2-like counter would give), 1/8 bit (current ESP-IDF, which Flexe follows), or 0.1 bit (the TRM). A loopback measurement on a classic board would decide it.

@bgates747

Copy link
Copy Markdown
Contributor Author

Thanks, Lev, for merging the fix and checking it against the Agon tests. — Written by Codex on behalf of Brandon.

@bgates747

Copy link
Copy Markdown
Contributor Author

I’m tied up until early next week, but I’ll look at the classic ESP32 loopback test then. — Written by Codex on behalf of Brandon.

@bgates747

Copy link
Copy Markdown
Contributor Author

Written by Codex on behalf of Brandon.

Lev, we ran the UART1 internal-loopback test on two classic ESP32s: a
D0WD-V3 rev 3.0 devkit and the Agon Light2’s PICO-D4 rev 1.1. Both measured
about 10.40 µs per raw REF_TICK threshold step at 9,600 baud and
0.801 µs at 115,200. That’s one tenth of a bit time using the integer
divider (104 and 8). At the faster rate the fractional divider instead
predicts 0.8625 µs, and the current eighth-bit model predicts 1.078 µs.
The APB control measured about eight bit times per step on both chips.

We wrote raw CONF1 thresholds 20, 40, 80 and 120 and polled the raw
RX timeout flag. We ran 32 trials per threshold, clock and baud on each
of two boots per chip.

@levkropp

Copy link
Copy Markdown
Owner

Thanks Brandon, that settles it. Two chips, 32 trials per point, and the slope agrees at both rates: on the classic ESP32 one REF_TICK threshold unit is a tenth of a bit using the integer divider. That's the TRM's 8 × REF_TICK / APB, not ESP-IDF's eighth. Together with your APB control, both clocks fit one rule: a unit is 8 × the integer part of CLKDIV in APB cycles, and the fraction is ignored, as on the S2. Landed in acf79cd with your measured points pinned in the tests.

@bgates747

Copy link
Copy Markdown
Contributor Author

Thanks, Lev, for applying both UART fixes. We’ve integrated them into Alexe. Your UART regressions passed, and our Agon smoke checks passed in both JIT and interpreter modes.

Written by Codex on behalf of Brandon.

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.

2 participants