feat: real active-low data_ready_n sticky IRQ pin (EXP-0085)

User-requested hardware notification so the ESP32 can be
interrupt-driven instead of polling STATUS in a loop.

spi_host_bridge_v3.v: new job_out_done input (wired from
neural_director_packed.v, already available at the top level) and new
data_ready_n output. A sticky irq_pending register sets on job_out_done
(latched, survives the pulse itself deasserting) and clears when the
host completes a real STATUS (0x20) or REG_READ(0x02) transaction -
reusing cs_rose, the same real transaction-complete event the module
already relies on elsewhere, not a new mechanism. dir_error is ORed in
live/combinational, not latched. SET has priority over CLEAR on the
rare cycle both coincide.

Real pin: D14, bank 15 (already 3.3V, alongside the SPI bus and
sys_rst) - tentative, not yet a final board decision. Deliberately
added after EXP-0084's own P&R iterations settled, so it didn't
complicate that already-tight I/O/VCCO budget mid-fix. Its own real
P&R verification is deferred to the next real P&R run (already needed
to close EXP-0084's clock-period timing gap), not run separately
against a config already known to fail timing for unrelated reasons.

Real verification: tb_spi_host_bridge_v3.v extended with 10 new checks
(idle state, sticky set, mid-transaction hold, real-acknowledge clear,
unrelated-register non-acknowledge, dir_error live assert/clear).
49/49 PASS.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MUG92aM9m68TRc4rG55BcC
This commit is contained in:
2026-09-20 16:33:46 +02:00
co-authored by Claude Sonnet 5
parent 9dead54ebf
commit bdc821222f
6 changed files with 196 additions and 7 deletions
+21 -6
View File
@@ -87,6 +87,8 @@ Bank 15, package edge column A/B, physically adjacent (short traces), `LVCMOS33`
| mosi | B16 | input |
| miso | B17 | output |
| cs_n | A16 | input |
| sys_rst | G13 | input (EXP-0084, tentative — see §7) |
| data_ready_n | D14 | output (EXP-0085, active-low sticky IRQ — see §6, tentative — see §7) |
**Bank 15 VCCO**: assumed **3.3V** — change the XDC's IOSTANDARD if your
board power plan uses a different rail for this bank.
@@ -334,6 +336,19 @@ Full byte-level field layouts are documented in `spi_host_bridge_v3.v`'s own
header comment — treat that file as the authoritative protocol spec, this
table is a summary/index.
**Real out-of-band notification (EXP-0085)**: `data_ready_n`, a real,
**active-low, sticky** top-level pin (D14, bank 15, 3.3V — see §2.2) —
lets the ESP32 be interrupt-driven instead of polling STATUS in a loop.
Asserted (driven low) when a job/pair completes (`job_out_done`) or while
a real Director error is active (`dir_error`); the job-completion latch
is **sticky** (stays low even after the underlying pulse ends) until the
host acknowledges by completing a real STATUS (0x20) or REG_READ(0x02)
transaction — a REG_READ of any *other* register does not acknowledge it.
The `dir_error` contribution is live/combinational, not latched — it
clears the moment `dir_error` itself does. Real firmware implication: the
ESP32 can wire this to a GPIO interrupt and only bother reading STATUS
when it actually fires, instead of polling every loop iteration.
## 7. Known-open items (honestly disclosed, not hidden)
- Scaling past N=2 compute cores (silicon budget allows up to ~30 per the
@@ -359,9 +374,9 @@ table is a summary/index.
`docs/ARCHITECTURE_ANALYSIS.md` §5.2 for the honest number and why. The
larger multi-slot DDRManager is not built. Its own real benefit should be
re-measured once the 32-bit channel's timing actually closes.
- User-requested, not yet built: an active-low `data_ready_n`/IRQ pin so
the ESP32 can be interrupt-driven (job completion or error pending)
instead of polling the STATUS register — planned as a sticky bit (set on
`job_out_done`/`dir_error`, cleared when the ESP32 reads STATUS),
deliberately deferred until the §3.1 timing-closure work lands so it
doesn't further complicate the currently-tight I/O/VCCO budget mid-fix.
- `data_ready_n` (EXP-0085, user-requested active-low sticky IRQ) is real,
built, and functionally verified (49/49 including 10 new checks,
`tb_spi_host_bridge_v3.v`) — see §6. Its own real P&R verification is
deferred to the same next real P&R run already needed to close §3.1's
timing gap, not run separately against a config already known to fail
timing for unrelated reasons.