Merge pull request #12 from lcapossio/feature/ejtagaxi-resource-trim

Trim EJTAG-AXI FIFO BRAM usage

Author: lcapossio

CHANGELOG.md

@@ -9,6 +9,12 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Added
 
+- **EJTAG-AXI RTL:** Vendor wrappers now expose `CMD_FIFO_DEPTH` and
+  `RESP_FIFO_DEPTH` independently from burst `FIFO_DEPTH`; the Arty
+  reference sets both command/response queues to 16 and forces the small
+  command queue to distributed XPM storage to trim BRAM usage while
+  keeping the 16-beat burst FIFO. The placed Arty A7 reference now reports
+  1.5 BRAM tiles total, and the EJTAG-AXI hierarchy itself reports 0 BRAM.
 - **EJTAG-AXI RTL:** `DEBUG_EN` parameter on the core and vendor wrappers,
   defaulting off to prune bridge-only debug buses, capture records, and
   counters from production builds; RTL reset regression now sweeps

README.md

@@ -594,7 +594,7 @@ from the RTL.
 | Microchip PolarFire-family TAP wrappers | Implemented in RTL, host validation still limited |
 | Runtime channel mux | Implemented in RTL and host API/CLI/RPC |
 | EIO over real transports | Implemented — USER3 on Xilinx; wrapper-shared chain on ECP5, Gowin, and PolarFire-family devices |
-| EJTAG-AXI bridge | Hardware-validated on Arty A7 (single, auto-inc, and burst modes); `DEBUG_EN=0` reference build is synthesis/place/route validated, hardware rerun pending |
+| EJTAG-AXI bridge | Hardware-validated on Arty A7 (single, auto-inc, burst, strobe, and error paths) with the trimmed FIFO / `DEBUG_EN=0` reference build |
 | EJTAG-UART bridge | Hardware-validated on Arty A7 (loopback: send, recv, recv_line, status) |
 | Sample decimation | Implemented in RTL and host API/CLI |
 | External trigger I/O | Implemented in RTL and host API/CLI |
@@ -625,7 +625,8 @@ the JTAG TAP/register/readout plumbing, not only `fcapz_ela.v`.
 | 8b x 1024, 4-stage sequencer | 2,954 | 2,788 | 0.5 | `TRIG_STAGES=4`, `STOR_QUAL=0` |
 | 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** | 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 |
+| `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 |
 
 Optional ELA parameters (`DECIM_EN`, `EXT_TRIG_EN`, `TIMESTAMP_W`,
 `NUM_SEGMENTS`, channel mux, etc.) add registers, comparators, and
@@ -634,10 +635,14 @@ authoritative “full validation” footprint for that combination.
 Per-core deltas are not additive in synthesis because Vivado optimises
 across hierarchy.
 
-The EJTAG-AXI `DEBUG_EN=0` row comes from the Arty A7-100T Vivado
-2025.2 post-place report after gating bridge-only debug telemetry:
-`-926` slice LUTs and `-1,394` FFs versus the previous always-on
-debug baseline, with BRAM unchanged.
+The trimmed EJTAG-AXI row comes from the Arty A7-100T Vivado 2025.2
+post-place report after gating bridge-only debug telemetry and reducing
+small bridge queues to their XPM minimum depth. Versus the previous
+always-on debug baseline, the current reference is `-873` slice LUTs,
+`-1,206` FFs, and `-2.0` BRAM tiles. Versus the earlier `DEBUG_EN=0`
+reference, the FIFO trim trades about `+53` LUTs and `+188` FFs for
+`-2.0` BRAM tiles; placed hierarchy reports `u_ejtagaxi` at 883 LUTs,
+1,270 FFs, and 0 BRAM.
 
 **Fmax (reference build):** `sys_clk` @ 100 MHz with WNS positive after
 route on `arty_a7_top` (xc7a100t, same build). JTAG `tck_bscan` is

docs/04_rtl_integration.md

@@ -443,8 +443,13 @@ module fcapz_ejtagaxi_xilinx7 #(
     parameter ADDR_W     = 32,
     parameter DATA_W     = 32,
     parameter FIFO_DEPTH = 16,
+    parameter CMD_FIFO_DEPTH  = FIFO_DEPTH * 2,
+    parameter RESP_FIFO_DEPTH = FIFO_DEPTH * 2,
     parameter TIMEOUT    = 4096,
     parameter DEBUG_EN   = 0,
+    parameter CMD_FIFO_MEMORY_TYPE   = "auto",
+    parameter RESP_FIFO_MEMORY_TYPE  = "auto",
+    parameter BURST_FIFO_MEMORY_TYPE = "auto",
     parameter CHAIN      = 4
 ) ( ... );
 ```
@@ -454,8 +459,13 @@ module fcapz_ejtagaxi_xilinx7 #(
 | `ADDR_W` | 32, 64 | AXI address width.  64 is supported but not hardware-validated. |
 | `DATA_W` | 32 | AXI data width.  Only 32 is supported today. |
 | `FIFO_DEPTH` | 1..256, **power of 2** | Async FIFO depth for burst reads.  Limits the maximum burst length the host can request — the host caches this from `FEATURES[23:16]` and rejects oversized requests at the API boundary.  See [chapter 07](07_ejtag_axi_bridge.md). |
+| `CMD_FIFO_DEPTH` | power of 2 | TCK-to-AXI command queue depth. The wrapper default follows the core (`2*FIFO_DEPTH`) for compatibility; Xilinx XPM FIFO builds require at least 16. |
+| `RESP_FIFO_DEPTH` | power of 2 | AXI-to-TCK response queue depth. The wrapper default follows the core (`2*FIFO_DEPTH`) for compatibility; Xilinx XPM FIFO builds require at least 16. |
 | `TIMEOUT` | int | AXI handshake timeout in `axi_clk` cycles.  Applies to `wready`/`bvalid`/`arready`/`rvalid` waits, **not** between burst beats. |
 | `DEBUG_EN` | 0, 1 | Enables the 256-bit debug buses and debug CONFIG capture records. Defaults off to let synthesis prune debug-only storage and counters. |
+| `CMD_FIFO_MEMORY_TYPE` | `"auto"`, `"block"`, `"distributed"` | Xilinx XPM storage selector for the command queue. Ignored by the portable behavioral FIFO. |
+| `RESP_FIFO_MEMORY_TYPE` | `"auto"`, `"block"`, `"distributed"` | Xilinx XPM storage selector for the response queue. Ignored by the portable behavioral FIFO. |
+| `BURST_FIFO_MEMORY_TYPE` | `"auto"`, `"block"`, `"distributed"` | Xilinx XPM storage selector for the burst read FIFO. Ignored by the portable behavioral FIFO. |
 | `CHAIN` | 1..4 | BSCANE2 USER chain. |
 
 ## EJTAG-UART wrapper parameter reference

docs/05_ela_core.md

@@ -652,7 +652,8 @@ Rows that mention readout include the wrapper/TAP/register plumbing.
 The [Arty reference design](../examples/arty_a7/arty_a7_top.v) enables
 `DECIM_EN`, `EXT_TRIG_EN`, `TIMESTAMP_W=32`, and `NUM_SEGMENTS=4` together
 with EIO and EJTAG-AXI — **post-place** that top-level uses about **3.2k
-slice LUTs** and **3.5 BRAM tiles** (see [README.md](../README.md#resource-usage)).
+slice LUTs** and **1.5 BRAM tiles** after the EJTAG-AXI FIFO trim
+(see [README.md](../README.md#resource-usage)).
 Your tool and family will vary.
 
 ## What's next

docs/07_ejtag_axi_bridge.md

@@ -320,8 +320,32 @@ fcapz_ejtagaxi_xilinx7 #(
 
 The default 16 is a deliberate compromise: enough for most CSR
 register dumps and small block transfers, small enough that the
-LUT/FF cost is negligible (~150 LUTs for the FIFO).  Bumping to
-256 costs ~1200 LUTs but lets you do full AXI4 max bursts.
+default burst FIFO remains small. On Xilinx XPM builds, bumping to
+256 moves the burst buffer into BRAM rather than exploding LUT use,
+but it does spend another RAMB18 tile to enable full AXI4 max bursts.
+
+`CMD_FIFO_DEPTH` and `RESP_FIFO_DEPTH` size the separate command and
+response queues between TCK and `axi_clk`. Their wrapper defaults track
+the core default (`2*FIFO_DEPTH`) for compatibility with aggressively
+batched host traffic, but they can be set independently when BRAM is
+tighter than queue depth. On Xilinx XPM FIFO builds, the minimum legal
+depth is 16. The Arty A7 reference uses:
+
+```verilog
+.FIFO_DEPTH      (16),
+.CMD_FIFO_DEPTH  (16),
+.RESP_FIFO_DEPTH (16),
+.CMD_FIFO_MEMORY_TYPE("distributed")
+```
+
+This keeps the same 16-beat burst limit while avoiding the extra BRAM
+tiles that Vivado otherwise spends on the default 32-deep response queue
+and the wide command queue. Leave the memory-type selectors at `"auto"`
+unless you have checked the target tool's utilization result; forcing
+large FIFOs into distributed RAM can quickly cost more LUTs than it saves.
+In the Arty reference, the 16-entry response queue already maps out of
+BRAM with `"auto"`, so only the command queue needs an explicit
+`"distributed"` override.
 
 `DEBUG_EN` defaults to `0` on the core and vendor wrappers. Leave it
 off for production builds so synthesis can prune the 256-bit debug

examples/arty_a7/arty_a7_top.v

@@ -191,7 +191,12 @@ module arty_a7_top (
     // USER4 validation uses host AXI reads/writes, and no ILA consumes the
     // bridge's internal 256-bit telemetry buses here.
     fcapz_ejtagaxi_xilinx7 #(
-        .ADDR_W(32), .DATA_W(32), .FIFO_DEPTH(16), .TIMEOUT(4096),
+        .ADDR_W(32), .DATA_W(32),
+        .FIFO_DEPTH(16),
+        .CMD_FIFO_DEPTH(16),
+        .RESP_FIFO_DEPTH(16),
+        .CMD_FIFO_MEMORY_TYPE("distributed"),
+        .TIMEOUT(4096),
         .DEBUG_EN(0)
     ) u_ejtagaxi (
         .axi_clk(clk),

rtl/fcapz_async_fifo.v

@@ -25,12 +25,14 @@
 //   DEPTH   - FIFO depth in entries, must be power of 2 (default 16)
 //   USE_BEHAV_ASYNC_FIFO - legacy selector, 1=behavioral, 0=XPM
 //   ASYNC_FIFO_IMPL      - 0=behavioral, 1=AMD/Xilinx XPM
+//   XPM_FIFO_MEMORY_TYPE - XPM storage selector ("auto", "block", "distributed")
 
 module fcapz_async_fifo #(
     parameter DATA_W  = 32,
     parameter DEPTH   = 16,
     parameter USE_BEHAV_ASYNC_FIFO = 1,
-    parameter ASYNC_FIFO_IMPL = (USE_BEHAV_ASYNC_FIFO ? 0 : 1)
+    parameter ASYNC_FIFO_IMPL = (USE_BEHAV_ASYNC_FIFO ? 0 : 1),
+    parameter XPM_FIFO_MEMORY_TYPE = "auto"
 ) (
     // Write side (wr_clk domain)
     input  wire                      wr_clk,
@@ -78,12 +80,19 @@ if (ASYNC_FIFO_IMPL == 1) begin : gen_xpm
     //  Vendor primitive (Xilinx XPM) implementation
     // =================================================================
 
+    if (DEPTH < 16)
+        XPM_FIFO_DEPTH_must_be_at_least_16 _xpm_depth_check_FAILED();
+    initial begin
+        if (DEPTH < 16)
+            $error("fcapz_async_fifo: XPM FIFO depth must be >= 16 (got %0d)", DEPTH);
+    end
+
     wire [AW:0] xpm_rd_count;
     wire [AW:0] xpm_wr_count;
 
     xpm_fifo_async #(
         .CDC_SYNC_STAGES     (2),
-        .FIFO_MEMORY_TYPE    ("auto"),
+        .FIFO_MEMORY_TYPE    (XPM_FIFO_MEMORY_TYPE),
         .FIFO_READ_LATENCY   (0),
         .FIFO_WRITE_DEPTH    (DEPTH),
         .READ_DATA_WIDTH     (DATA_W),

rtl/fcapz_ejtagaxi.v

@@ -17,6 +17,7 @@
 //   CMD_FIFO_DEPTH  - async command FIFO depth (default 2*FIFO_DEPTH)
 //   RESP_FIFO_DEPTH - async response FIFO depth (default 2*FIFO_DEPTH)
 //   TIMEOUT    - AXI ready timeout in axi_clk cycles   (default 4096)
+//   *_FIFO_MEMORY_TYPE - XPM storage selectors ("auto", "block", "distributed")
 //
 // 72-bit DR format (LSB first):
 //   Shift-in:  [31:0] addr, [63:32] payload, [67:64] wstrb, [71:68] cmd
@@ -31,7 +32,10 @@ module fcapz_ejtagaxi #(
     parameter TIMEOUT    = 4096,
     parameter DEBUG_EN   = 0,
     parameter USE_BEHAV_ASYNC_FIFO    = 1,
-    parameter ASYNC_FIFO_IMPL = (USE_BEHAV_ASYNC_FIFO ? 0 : 1)
+    parameter ASYNC_FIFO_IMPL = (USE_BEHAV_ASYNC_FIFO ? 0 : 1),
+    parameter CMD_FIFO_MEMORY_TYPE   = "auto",
+    parameter RESP_FIFO_MEMORY_TYPE  = "auto",
+    parameter BURST_FIFO_MEMORY_TYPE = "auto"
 ) (
     // TAP signals (from vendor-specific wrapper)
     input  wire        tck,
@@ -343,7 +347,8 @@ module fcapz_ejtagaxi #(
         .DATA_W  (CMDQ_W),
         .DEPTH   (CMD_FIFO_DEPTH),
         .USE_BEHAV_ASYNC_FIFO (USE_BEHAV_ASYNC_FIFO),
-        .ASYNC_FIFO_IMPL      (ASYNC_FIFO_IMPL)
+        .ASYNC_FIFO_IMPL      (ASYNC_FIFO_IMPL),
+        .XPM_FIFO_MEMORY_TYPE (CMD_FIFO_MEMORY_TYPE)
     ) u_cmd_fifo (
         .wr_clk   (tck),
         .wr_rst   (axi_rst | cmdq_rst_tck),
@@ -365,7 +370,8 @@ module fcapz_ejtagaxi #(
         .DATA_W  (RESPQ_W),
         .DEPTH   (RESP_FIFO_DEPTH),
         .USE_BEHAV_ASYNC_FIFO (USE_BEHAV_ASYNC_FIFO),
-        .ASYNC_FIFO_IMPL      (ASYNC_FIFO_IMPL)
+        .ASYNC_FIFO_IMPL      (ASYNC_FIFO_IMPL),
+        .XPM_FIFO_MEMORY_TYPE (RESP_FIFO_MEMORY_TYPE)
     ) u_resp_fifo (
         .wr_clk   (axi_clk),
         .wr_rst   (axi_rst | respq_rst_axi),
@@ -387,7 +393,8 @@ module fcapz_ejtagaxi #(
         .DATA_W  (DATA_W),
         .DEPTH   (FIFO_DEPTH),
         .USE_BEHAV_ASYNC_FIFO (USE_BEHAV_ASYNC_FIFO),
-        .ASYNC_FIFO_IMPL      (ASYNC_FIFO_IMPL)
+        .ASYNC_FIFO_IMPL      (ASYNC_FIFO_IMPL),
+        .XPM_FIFO_MEMORY_TYPE (BURST_FIFO_MEMORY_TYPE)
     ) u_burst_fifo (
         .wr_clk   (axi_clk),
         .wr_rst   (axi_rst | fifo_rst_axi),

rtl/fcapz_ejtagaxi_intel.v

@@ -19,8 +19,13 @@ module fcapz_ejtagaxi_intel #(
     parameter ADDR_W     = 32,
     parameter DATA_W     = 32,
     parameter FIFO_DEPTH = 16,
+    parameter CMD_FIFO_DEPTH  = FIFO_DEPTH * 2,
+    parameter RESP_FIFO_DEPTH = FIFO_DEPTH * 2,
     parameter TIMEOUT    = 4096,
     parameter DEBUG_EN   = 0,
+    parameter CMD_FIFO_MEMORY_TYPE   = "auto",
+    parameter RESP_FIFO_MEMORY_TYPE  = "auto",
+    parameter BURST_FIFO_MEMORY_TYPE = "auto",
     parameter ASYNC_FIFO_IMPL = 0, // 0=portable behavioral
     parameter CHAIN      = 4       // sld_instance_index (1-3 used by ELA+EIO)
 ) (
@@ -79,8 +84,14 @@ module fcapz_ejtagaxi_intel #(
     // ---- JTAG-to-AXI core ----
     fcapz_ejtagaxi #(
         .ADDR_W(ADDR_W), .DATA_W(DATA_W),
-        .FIFO_DEPTH(FIFO_DEPTH), .TIMEOUT(TIMEOUT),
+        .FIFO_DEPTH(FIFO_DEPTH),
+        .CMD_FIFO_DEPTH(CMD_FIFO_DEPTH),
+        .RESP_FIFO_DEPTH(RESP_FIFO_DEPTH),
+        .TIMEOUT(TIMEOUT),
         .DEBUG_EN(DEBUG_EN),
+        .CMD_FIFO_MEMORY_TYPE(CMD_FIFO_MEMORY_TYPE),
+        .RESP_FIFO_MEMORY_TYPE(RESP_FIFO_MEMORY_TYPE),
+        .BURST_FIFO_MEMORY_TYPE(BURST_FIFO_MEMORY_TYPE),
         .ASYNC_FIFO_IMPL(ASYNC_FIFO_IMPL)
     ) u_ejtagaxi (
         .tck(tap_tck), .tdi(tap_tdi), .tdo(tap_tdo),

rtl/fcapz_ejtagaxi_xilinx7.v

@@ -19,8 +19,13 @@ module fcapz_ejtagaxi_xilinx7 #(
     parameter ADDR_W     = 32,
     parameter DATA_W     = 32,
     parameter FIFO_DEPTH = 16,
+    parameter CMD_FIFO_DEPTH  = FIFO_DEPTH * 2,
+    parameter RESP_FIFO_DEPTH = FIFO_DEPTH * 2,
     parameter TIMEOUT    = 4096,
     parameter DEBUG_EN   = 0,
+    parameter CMD_FIFO_MEMORY_TYPE   = "auto",
+    parameter RESP_FIFO_MEMORY_TYPE  = "auto",
+    parameter BURST_FIFO_MEMORY_TYPE = "auto",
     parameter ASYNC_FIFO_IMPL = 1, // 1=AMD/Xilinx XPM, 0=portable behavioral
     parameter CHAIN      = 4       // USER4 (USER1-3 used by ELA+EIO)
 ) (
@@ -79,8 +84,14 @@ module fcapz_ejtagaxi_xilinx7 #(
     // ---- JTAG-to-AXI core ----
     fcapz_ejtagaxi #(
         .ADDR_W(ADDR_W), .DATA_W(DATA_W),
-        .FIFO_DEPTH(FIFO_DEPTH), .TIMEOUT(TIMEOUT),
+        .FIFO_DEPTH(FIFO_DEPTH),
+        .CMD_FIFO_DEPTH(CMD_FIFO_DEPTH),
+        .RESP_FIFO_DEPTH(RESP_FIFO_DEPTH),
+        .TIMEOUT(TIMEOUT),
         .DEBUG_EN(DEBUG_EN),
+        .CMD_FIFO_MEMORY_TYPE(CMD_FIFO_MEMORY_TYPE),
+        .RESP_FIFO_MEMORY_TYPE(RESP_FIFO_MEMORY_TYPE),
+        .BURST_FIFO_MEMORY_TYPE(BURST_FIFO_MEMORY_TYPE),
         .USE_BEHAV_ASYNC_FIFO(0),
         .ASYNC_FIFO_IMPL(ASYNC_FIFO_IMPL)
     ) u_ejtagaxi (