Merge pull request #15 from lcapossio/feature/multi-ela-design

Add managed multi-core debug slots with dual-clock Arty validation

Author: lcapossio

.gitignore

@@ -13,9 +13,12 @@ vivado/
 dfx_runtime.txt
 
 # Build artifacts
+dist/
+packages/
 *.bit
 *.bin
 !host/fcapz/gui/assets/default_window_state_v6.bin
+!host/fcapz/gui/assets/default_window_state_v7.bin
 
 # Simulation artifacts
 sim/*.vvp
@@ -28,3 +31,4 @@ Thumbs.db
 # Temp test outputs
 tests/_tmp/
 .codex_pytest_tmp*/
+.claude/

CHANGELOG.md

@@ -28,6 +28,14 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
   from the repo `VERSION` file before falling back to installed package
   metadata, so a stale wheel/editable install cannot mask the working-tree
   version.
+- **Debug manager:** Added a generic `"CM"` active-slot manager and Xilinx
+  `fcapz_debug_multi_xilinx7` wrapper so multiple ELAs and an EIO can share
+  one USER chain. The Arty reference now routes two ELA slots plus two EIO
+  slots through USER1; EIO CLI/API calls can pass `instance=N` for managed
+  slots.
+- **GUI:** ELA capture now pins itself to manager slot 0 when a USER1 core
+  manager is present, and the EIO dock can attach to managed EIO slots such as
+  Arty's USER1 slots 2 and 3.
 
 ### Fixed
 

README.md

@@ -547,12 +547,18 @@ for details.
 
 | Vendor | Primitive | User chains | ELA | EIO (needs 1) | EJTAG-AXI (needs 1) | EJTAG-UART (needs 1) |
 |--------|-----------|:-----------:|:---:|:---:|:---:|:---:|
-| **Xilinx** | BSCANE2 | 4 (USER1-4) | USER1 control + default burst; optional USER2 legacy burst | USER3 | USER4 | USER4 (shared) |
+| **Xilinx** | BSCANE2 | 4 (USER1-4) | USER1 control + default burst; optional USER2 legacy burst | USER3 standalone, or managed USER1 slot with `fcapz_debug_multi_xilinx7` | USER4 | USER4 (shared) |
 | **Intel** | sld_virtual_jtag | Unlimited | inst 0 by default; optional inst 1 | inst 2 | inst 3 | inst 5 |
 | **ECP5** | JTAGG | 2 (ER1+ER2) | ER1 by default; optional ER2 | `EIO_EN=1` on ER1 | *deferred to v2* | *deferred to v2* |
 | **Gowin** | GW_JTAG | One primitive; wrapper selects ER1 or ER2 | No burst | `EIO_EN=1` | *deferred to v2* | *deferred to v2* |
 | **PolarFire-family** | UJTAG | 2 (USER1+USER2) | USER1 control + USER2 burst | `EIO_EN=1` on USER1 | *deferred to v2* | *deferred to v2* |
 
+Single-core ELA/EIO wrappers are available across the vendor rows above.
+Managed multi-core wrappers are Xilinx 7-series only in this revision
+(`fcapz_debug_multi_xilinx7`); the portable `fcapz_core_manager` is shared,
+but ECP5, Gowin, Intel, PolarFire, and UltraScale wrappers still need their
+own TAP-specific shells.
+
 **Verified Xilinx 7-series IR codes** (xc7a100t, Arty A7):
 USER1=0x02, USER2=0x03, USER3=0x22, USER4=0x23.
 
@@ -633,7 +639,7 @@ the JTAG TAP/register/readout plumbing, not only `fcapz_ela.v`.
 | 32b x 1024, dual comparator, `REL_COMPARE=0` | 2,472 | 2,099 | 1.0 | Wider samples mainly add BRAM/FFs |
 | `arty_a7_top` (placed, pre-`DEBUG_EN` always-on debug) | 3,244 | 4,562 | 3.5 | Historical baseline for the same validation reference |
 | `arty_a7_top` (placed, `DEBUG_EN=0`) | 2,318 | 3,168 | 3.5 | Bridge debug telemetry disabled; previous reference before the EJTAG-AXI FIFO trim |
-| **`arty_a7_top` (placed, trimmed EJTAG-AXI FIFOs, `DEBUG_EN=0`)** | **2,371** | **3,356** | **1.5** | Current reference: ELA with `INPUT_PIPE=1`, `DECIM_EN`, `EXT_TRIG_EN`, `TIMESTAMP_W=32`, `NUM_SEGMENTS=4` + EIO 8/8 + EJTAG-AXI + `axi4_test_slave`; bridge debug telemetry disabled; EJTAG-AXI command/response queues set to 16 entries |
+| **`arty_a7_top` (placed, trimmed EJTAG-AXI FIFOs, `DEBUG_EN=0`)** | **2,371** | **3,356** | **1.5** | Current reference: USER1 debug manager with 2x ELA (`INPUT_PIPE=1`, `DECIM_EN`, `EXT_TRIG_EN`, `TIMESTAMP_W=32`, `NUM_SEGMENTS=4`) + 2x EIO 8/8 + EJTAG-AXI + `axi4_test_slave`; bridge debug telemetry disabled; EJTAG-AXI command/response queues set to 16 entries |
 
 Optional ELA parameters (`DECIM_EN`, `EXT_TRIG_EN`, `TIMESTAMP_W`,
 `NUM_SEGMENTS`, channel mux, etc.) add registers, comparators, and
@@ -688,14 +694,19 @@ GitHub Actions runs on every push and pull request to `main` or `master`:
 | `test-host` | `pytest tests/ -v --tb=short` with the default `not hw` marker filter, plus an explicit JTAG readback pipeline regression for burst and timestamp stabilization paths |
 | `lint-rtl` | `python sim/run_sim.py --lint-only` — shared `iverilog -Wall` elaboration for the core RTL, vendor wrappers, and simulation stubs |
 | `lint-rtl-verilator` | `python sim/run_verilator_lint.py --self-test` -- full-project Verilog RTL driver lint plus an intentional `MULTIDRIVEN` fixture proving the gate catches one reg driven by multiple always blocks |
-| `sim` | `python sim/run_sim.py` — runs the same `iverilog -Wall` lint pass, then the default RTL regression: ELA behavior, ELA focused regressions, ELA configuration matrix, burst readout, single-chain pipe readout, EIO, and channel mux testbenches |
+| `sim` | `python sim/run_sim.py` — runs the same `iverilog -Wall` lint pass, then the default RTL regression: ELA behavior, ELA focused regressions, ELA configuration matrix, burst readout, single-chain pipe readout, EIO, core manager, and channel mux testbenches |
 
 Hardware integration tests run manually (require physical Arty A7-100T + hw_server).
 Optional **GUI + hardware** checks in `tests/test_gui_hw_capture.py` are
 documented in [CONTRIBUTING.md](CONTRIBUTING.md) (`FPGACAP_GUI_HW=1`, not run in CI).
 Those board-level checks now require every adjacent Arty counter sample to
 increment by +1 when decimation is disabled, so partial burst readback
-corruption is caught instead of hidden by a shorter valid prefix.
+corruption is caught instead of hidden by a shorter valid prefix. The managed
+Arty bitstream exercises two ELAs on the same USER chain with independent
+sample domains: ELA0 captures a 150 MHz counter and ELA1 captures a 130 MHz
+xored counter. In the GUI History panel, select captures from both ELAs and
+open/export them as one merged VCD so Surfer or GTKWave can display the two
+waveforms together.
 
 [↑ Top](#readme-top)
 

core.json

@@ -1,6 +1,7 @@
 {
   "name": "fpgacapZero",
   "version": "0.1.0",
+  "manifest_note": "Source manifest for FuseSoC-style and external build tooling; keep in sync when adding or removing RTL files.",
   "description": "Open-source, vendor-agnostic FPGA debug cores: Embedded Logic Analyzer (ELA) for waveform capture and Embedded I/O (EIO) for runtime read/write of fabric signals, all over JTAG. Includes single-instantiation wrappers for Xilinx 7-series/UltraScale, Lattice ECP5, Intel/Altera, and Gowin.",
   "author": "Leonardo Capossio - bard0 design - <hello@bard0.com>",
   "license": "MIT",
@@ -47,6 +48,8 @@
   },
   "files": [
     "rtl/fcapz_ela.v",
+    "rtl/fcapz_core_manager.v",
+    "rtl/fcapz_debug_multi_xilinx7.v",
     "rtl/fcapz_eio.v",
     "rtl/jtag_burst_read.v",
     "rtl/jtag_reg_iface.v",

docs/01_overview.md

@@ -112,10 +112,13 @@ chapter 17 for details.
 
 ## How the cores fit together
 
-Each core uses a **separate JTAG USER chain** (USER1 through USER4
-on Xilinx 7-series / UltraScale, equivalent on other vendors), so
-multiple cores can coexist in the same bitstream and the host stack
-can talk to all of them in one xsdb / OpenOCD session.
+By default, each core uses a **separate JTAG USER chain** (USER1 through
+USER4 on Xilinx 7-series / UltraScale, equivalent on other vendors), so
+multiple cores can coexist in the same bitstream and the host stack can
+talk to all of them in one xsdb / OpenOCD session.  Xilinx 7-series
+designs can also put multiple ELA and EIO slots behind one USER1 core
+manager (`fcapz_debug_multi_xilinx7`) when you want more debug endpoints
+than free USER chains.
 
 | Core | Default chain | Default IR (7-series) | Default IR (UltraScale) |
 |------|---------------|-----------------------|-------------------------|
@@ -129,12 +132,13 @@ have to memorise either set: the Python transport ships named
 `IR_TABLE_XILINX7` and `IR_TABLE_XILINX_ULTRASCALE` (alias
 `IR_TABLE_US`) presets — see [chapter 14](14_transports.md).
 
-ELA and EIO are completely independent.  The two bridges (AXI and
-UART) can share USER4 by being instantiated at the same time only if
+ELA and EIO are independent cores, but they may be hosted either on
+separate chains or in managed slots on one chain.  The two bridges (AXI
+and UART) can share USER4 by being instantiated at the same time only if
 you arbitrate them externally; in practice you pick one bridge per
-bitstream.  The reference Arty A7 design includes ELA + EIO + AXI
-together, and a separate "uart loopback" bitstream includes ELA +
-EIO + UART.
+bitstream.  The reference Arty A7 design includes a USER1 manager with
+2x ELA and 2x EIO plus AXI on USER4, and a separate "uart loopback"
+bitstream includes ELA + EIO + UART.
 
 ## The host stack
 

docs/03_first_capture.md

@@ -16,9 +16,13 @@
 ## Step 1: build the reference bitstream
 
 The reference design is at [`../examples/arty_a7/`](../examples/arty_a7/).
-It instantiates one ELA core, one EIO core, and one EJTAG-AXI bridge,
-all wired into a free-running 8-bit counter and a small AXI test slave
-so you have something to look at.
+It instantiates a USER1 debug manager with two ELA slots and two EIO
+slots, plus one EJTAG-AXI bridge.  ELA0 captures a free-running 8-bit
+counter in a generated 150 MHz sample domain.  ELA1 captures a separate
+130 MHz counter xored with `0xA5`.  EIO0 drives the board LED/control
+test signals, and EIO1 gives a second managed I/O target for
+slot-selection checks.  The AXI bridge is wired to a small AXI test slave
+so you have something to look at from each host path.
 
 ```bash
 cd /path/to/fpgacapZero
@@ -166,6 +170,9 @@ waveform preview.
 
 In the **ELA** tab:
 
+- Leave **ELA core** set to `core 0` for the plain counter.  On the
+  Arty reference bitstream, `core 1` is a second managed ELA in a 130 MHz
+  sample domain capturing `counter_130 ^ 0xA5`.
 - Set **Pretrigger** to `8`.
 - Set **Posttrigger** to `16`.
 - Set **Trigger mode** to `value_match`.
@@ -189,6 +196,11 @@ happened before the event, not only after it.
 
 From the GUI you can also save the capture as JSON / CSV / VCD, or open the
 VCD in an external viewer if GTKWave, Surfer, or WaveTrace is installed.
+To compare the two managed ELAs, capture once with **ELA core** `core 0`,
+capture again with `core 1`, Ctrl/Shift-select both rows in History, then
+click **Open selected in viewer**.  The GUI writes one merged VCD with
+`fcapz.ela0.*` and `fcapz.ela1.*` scopes aligned at the trigger sample;
+Surfer and GTKWave can show both ELAs in the same waveform window.
 
 ## Step 5: repeat the same capture from the CLI
 
@@ -384,13 +396,18 @@ values 4 apart, because of `decimation=3` (store every N+1 = 4th).
 
 ### d. EIO read/write (chapter 06)
 
-The reference design wires the EIO core to a small register file you
-can poke at runtime:
+The reference design wires two managed EIO slots behind the USER1 core
+manager.  Slot 2 is EIO0, the board-control EIO used by the GUI; slot 3
+is EIO1, an independent second EIO for selection/readback checks.  Pass
+`--chain 1 --instance N` to select one:
 
 ```bash
-fcapz --backend hw_server --port 3121 --tap xc7a100t eio-read
-fcapz --backend hw_server --port 3121 --tap xc7a100t eio-write 0xA5
-fcapz --backend hw_server --port 3121 --tap xc7a100t eio-read
+fcapz --backend hw_server --port 3121 --tap xc7a100t \
+      eio-read --chain 1 --instance 2
+fcapz --backend hw_server --port 3121 --tap xc7a100t \
+      eio-write --chain 1 --instance 2 0xA5
+fcapz --backend hw_server --port 3121 --tap xc7a100t \
+      eio-read --chain 1 --instance 3
 ```
 
 ### e. AXI single read (chapter 07)

docs/04_rtl_integration.md

@@ -189,38 +189,37 @@ wrappers are available through `ela_rtl_sources()` for custom integration.
 
 ## Adding more cores in the same design
 
-The reference Arty A7 design uses three cores in one bitstream:
+The reference Arty A7 design uses one USER1 debug manager plus AXI on USER4:
 
 ```verilog
-// 1. ELA on USER1 (control + burst data by default)
-fcapz_ela_xilinx7 #(
-    .SAMPLE_W (8),
-    .DEPTH    (1024)
-) u_ela (
-    .sample_clk  (clk_100mhz),
-    .sample_rst  (rst),
-    .probe_in    (counter[7:0]),
-    .trigger_in  (1'b0),
-    .trigger_out ()
-);
-
-// 2. EIO on USER3
-fcapz_eio_xilinx7 #(
-    .IN_W  (8),
-    .OUT_W (8)
-) u_eio (
-    .probe_in  (gpio_in),
-    .probe_out (gpio_out)
+// 1. Managed USER1 debug chain: ELA0, ELA1, EIO0, EIO1.
+fcapz_debug_multi_xilinx7 #(
+    .NUM_ELAS(2),
+    .EIO_EN(1),
+    .NUM_EIOS(2),
+    .SAMPLE_W(8),
+    .DEPTH(1024),
+    .EIO_IN_W(8),
+    .EIO_OUT_W(8)
+) u_debug (
+    .ela_sample_clk({clk_130mhz, clk_150mhz}),
+    .ela_sample_rst({rst_130mhz, rst_150mhz}),
+    .ela_probe_in({counter_130 ^ 8'hA5, counter_150}),
+    .ela_trigger_in(2'b00),
+    .ela_trigger_out(),
+    .ela_armed_out(),
+    .eio_probe_in({eio1_in, eio0_in}),
+    .eio_probe_out({eio1_out, eio0_out})
 );
 
-// 3. EJTAG-AXI bridge on USER4
+// 2. EJTAG-AXI bridge on USER4
 fcapz_ejtagaxi_xilinx7 #(
     .ADDR_W     (32),
     .DATA_W     (32),
     .FIFO_DEPTH (16)
 ) u_axi (
-    .axi_clk      (clk_100mhz),
-    .axi_rst      (rst),
+    .axi_clk      (clk_150mhz),
+    .axi_rst      (rst_150mhz),
     // ... 30 AXI signals connected to your AXI slave or interconnect ...
 );
 ```
@@ -320,6 +319,7 @@ module fcapz_ela_xilinx7 #(
 | `CTRL_CHAIN` | int | 1..4 | BSCANE2 USER chain for the control register interface. |
 | `DATA_CHAIN` | int | 1..4 | BSCANE2 USER chain for the burst data readback. |
 | `EIO_EN` | bit | 0/1 | When `1`, the ELA wrapper also instantiates an EIO core and muxes it onto `CTRL_CHAIN` via an address decoder — ELA registers live at `0x0000..0x7FFF`, EIO registers at `0x8000..0xFFFF`.  Lets you use both cores on a single USER chain when you want to conserve BSCAN primitives or share a chain for deployment reasons.  The standalone `fcapz_eio_xilinx7` / `_xilinxus` wrappers cannot coexist with this — pick one. |
+| `NUM_EIOS` | int | 0..N | `fcapz_debug_multi_xilinx7` only. Number of managed EIO slots after the ELA slots. Defaults to `EIO_EN` for one-EIO compatibility. |
 | `EIO_IN_W` | int | 1..N | EIO input bus width when `EIO_EN=1`. |
 | `EIO_OUT_W` | int | 1..N | EIO output bus width when `EIO_EN=1`. |
 
@@ -414,8 +414,9 @@ eio.write_outputs(0x1)
 - You cannot also instantiate a standalone `fcapz_eio_xilinx7` /
   `_xilinxus` elsewhere in the same design (two BSCANE2s on the same
   USER chain).
-- A future third core on the same chain (EJTAG-AXI/UART) would need a
-  wider address mux or a hierarchical `fcapz_regbus_mux`.
+- For multiple ELAs plus EIO on one Xilinx 7-series chain, prefer
+  `fcapz_debug_multi_xilinx7`; it uses the descriptor-capable `"CM"`
+  active-slot manager instead of the older fixed `0x8000` EIO address window.
 
 ## EIO wrapper parameter reference