Merge pull request #23 from lcapossio/feature/gowin-support

Gowin (BRS-100-GW1NR9) support: EIO reference design, GUI/CLI over OpenOCD, and a hardware test suite

Author: lcapossio

docs/06_eio_core.md

@@ -161,6 +161,18 @@ EIO wrapper with a non-default `CHAIN` parameter (see
 [chapter 04](04_rtl_integration.md)).  The host's `chain` argument
 must match the RTL `CHAIN` parameter.
 
+**Shared-chain EIO.** When EIO is address-muxed onto another core's chain
+instead of having its own, pass `base_addr` (the mux offset) so every register
+access is routed to the EIO window.  The common case is Gowin `EIO_EN=1`, which
+muxes EIO onto the ELA chain at offset `0x8000`:
+
+```python
+eio = EioController(transport, chain=1, base_addr=0x8000)
+```
+
+The CLI equivalent is `--base-addr 0x8000`, and the desktop GUI discovers this
+location automatically on connect.
+
 After `connect()`, the controller has cached `IN_W` and `OUT_W` from
 the bitstream's identity registers, so subsequent reads/writes know
 exactly how many words to scan.

docs/10_cli_reference.md

@@ -359,11 +359,17 @@ wrote 0x55
 All three EIO subcommands take `--chain N` (default 3) to override
 the BSCANE2 USER chain. For mixed-manager designs where EIO shares USER1,
 also pass `--instance N` to select the EIO slot before each register access.
+For a **shared-chain** EIO that is address-muxed onto another core's chain
+(e.g. Gowin `EIO_EN=1` at offset `0x8000`), pass `--base-addr` instead:
 
 ```bash
 fcapz --backend hw_server --tap xc7a100t eio-probe --chain 1 --instance 2
 fcapz --backend hw_server --tap xc7a100t eio-write --chain 1 --instance 2 0x11
 fcapz --backend hw_server --tap xc7a100t eio-read --chain 1 --instance 2
+
+# Gowin shared-chain EIO (chain 1, mux offset 0x8000):
+fcapz --backend openocd --tap GW1NR-9C.tap eio-read  --chain 1 --base-addr 0x8000
+fcapz --backend openocd --tap GW1NR-9C.tap eio-write --chain 1 --base-addr 0x8000 0x15
 ```
 
 ## AXI subcommands

docs/12_gui.md

@@ -81,11 +81,18 @@ The leftmost (or topmost, depending on layout) panel.  Holds:
 | **Backend** | Dropdown: `hw_server` (default) or `openocd` |
 | **Host** | TCP host of the transport, default `127.0.0.1` |
 | **Port** | TCP port, default `3121` for hw_server / `6666` for openocd |
-| **FPGA target** | hw_server target name (e.g. `xc7a100t`) or openocd TAP name |
+| **FPGA target / TAP** | hw_server target name (e.g. `xc7a100t`) or OpenOCD TAP name. For OpenOCD you can enter `auto` to use the first tap OpenOCD reports |
+| **[Scan]** | hw_server: lists XSDB JTAG targets. OpenOCD: lists tap names via `jtag names`. Click to fill the **TAP** field instead of typing it |
 | **Bitfile** | Optional path to a `.bit` file; if set, the GUI runs `fpga -file <bitfile>` and waits for the readiness probe before declaring "connected" |
-| **IR table** | Dropdown: `Xilinx 7-series` (default) or `Xilinx UltraScale / UltraScale+`.  Maps to the `IR_TABLE_*` presets in [chapter 14](14_transports.md) |
+| **IR table** | Dropdown: `Xilinx 7-series` (default), `Xilinx UltraScale / UltraScale+`, or `Gowin (OpenOCD)`.  Maps to the `IR_TABLE_*` presets in [chapter 14](14_transports.md) |
 | **[Connect] / [Disconnect]** | Open or close the underlying transport |
 
+> **Gowin boards** connect over the **OpenOCD** backend (the FTDI/Gowin cable
+> driven by an already-running `openocd`): set Backend = `openocd`, Port `6666`,
+> TAP = your tap name or `auto`, IR table = **Gowin (OpenOCD)**. The ELA tab
+> works immediately, and **EIO is auto-discovered and attached** on connect (see
+> the EIO panel below) — no USER chain or mux offset to enter.
+
 When you click **Connect**:
 
 1. The GUI builds a `XilinxHwServerTransport` (or `OpenOcdTransport`)
@@ -266,15 +273,22 @@ adjacent identical values render as a flat line, not a sawtooth.
 
 ### EIO panel
 
+On connect the GUI **auto-discovers and attaches** the EIO core: it probes the
+known locations — core-manager slots, then each USER chain at register offsets
+`0x0000` and `0x8000` — and attaches the first that reports the EIO identity
+(`'IO'`). You normally do not touch the controls below; they are a manual
+override.
+
 For managed designs, the **Core** selector lists detected EIO cores as
 `core 2`, `core 3`, and so on, with the selected USER chain and manager
 slot shown beside it.  Choosing a core attaches it immediately and shows
 the EIO identity / bus widths.  The Arty multi-core reference uses chain
 **1**, slots **2** and **3**.
 
-For legacy standalone EIO designs with no detected manager slot, the panel
-falls back to manual **JTAG chain**, optional **Managed slot**, and
-**Attach EIO** controls.
+For standalone or shared-chain EIO designs, the panel exposes manual
+**JTAG chain**, optional **Managed slot**, and a **Base** offset.  A
+**shared-chain** EIO — e.g. Gowin `EIO_EN=1`, which muxes EIO onto the ELA
+chain — lives at chain **1**, Base **0x8000** (discovery fills that in for you).
 
 For each input bit, **read-only checkboxes** update from
 `EioController.read_inputs()` while **Poll inputs** is checked.

docs/14_transports.md

@@ -182,6 +182,24 @@ OpenOCD does **not** program the FPGA from this transport — you do
 that separately with `pld load`, an `init`-time script, or your own
 `openocd -c "...; init; pld load 0 my.bit; exit"`.
 
+#### Tap auto-detect
+
+The tap name must match a tap defined in the running OpenOCD config.  Pass
+`tap="auto"` (or leave it empty) and `connect()` resolves it to the first name
+OpenOCD reports from `jtag names` — handy for single-FPGA chains where you don't
+want to hard-code the name.  The helper `fcapz.transport.list_openocd_taps()`
+returns that list; the GUI's **Scan** button uses it to populate the TAP field
+for the OpenOCD backend.
+
+#### Gowin over OpenOCD
+
+Gowin boards use this transport with `ir_table=OpenOcdTransport.IR_TABLE_GOWIN`
+(ER1/ER2 → chains 1/2).  The CLI auto-selects it for `--tap GW...`; in code,
+pass it explicitly.  The ELA sits on chain 1; a shared-chain EIO (`EIO_EN=1`) is
+reached on chain 1 at base offset `0x8000`
+(`EioController(t, chain=1, base_addr=0x8000)`).  See the
+[BRS-100-GW1NR9 example](../examples/brs_100_gw1nr9/README.md).
+
 ## IR table presets
 
 Different Xilinx families use different IR opcodes for the BSCANE2

examples/brs_100_gw1nr9/README.md

@@ -5,9 +5,12 @@ BRS-100-GW1NR9 board. It targets the `GW1NR-LV9QN88PC7/I6` device and
 instantiates the fpgacapZero Gowin ELA wrapper through the `GW_JTAG`
 primitive.
 
-The design is deliberately small: it builds one ELA, drives the board LEDs
-from simple local status signals, and captures internal counters, buttons, and
-header I/O through a six-channel probe mux.
+The design is deliberately small but exercises two cores over the single
+`GW_JTAG` primitive: an **ELA** that captures internal counters, the user
+buttons, and header I/O through a six-channel probe mux, and an **EIO** that
+exposes the two user buttons (host-readable) and drives the six board LEDs
+(host-controlled over JTAG). The EIO shares the ELA's JTAG chain through the
+register-bus mux at offset `0x8000`.
 
 ## Files
 
@@ -29,7 +32,8 @@ header I/O through a six-channel probe mux.
 - ELA sample width: 8 bits
 - ELA depth: 64 samples
 - ELA channels: 6
-- EIO: disabled in this example
+- EIO: enabled — 2 inputs (user buttons), 6 outputs (board LEDs)
+- EIO location: shares the ELA chain (chain 1) at register-bus mux offset `0x8000`
 
 The ELA probe bus is split into six 8-bit channels:
 
@@ -44,20 +48,13 @@ The ELA probe bus is split into six 8-bit channels:
 
 ## Board I/O
 
-The LEDs are active-low at the pads and are driven from these internal status
-signals:
+The six LEDs are **driven by the EIO output register** — the host controls them
+over JTAG (`eio.write_outputs`). They are active-low at the pads; EIO
+`probe_out[5:0]` maps to LED[5:0].
 
-| LED | Meaning |
-| --- | --- |
-| 0 | 1 Hz heartbeat |
-| 1 | JTAG activity indicator |
-| 2 | User button 0 |
-| 3 | User button 1 |
-| 4 | `pad_io[1]` |
-| 5 | `pad_io[2]` |
-
-The two user buttons are active-low on the board and are sampled into the
-60 MHz domain before being exposed through ELA channel 1.
+The two user buttons are active-low on the board, sampled into the 60 MHz
+domain, and exposed two ways: through **EIO `probe_in[1:0]`** (host-readable via
+`eio.read_inputs`) and through **ELA channel 1** (captured into a waveform).
 
 ## Build
 
@@ -133,13 +130,67 @@ fcapz --backend openocd --host 127.0.0.1 --port 6666 \
 For VCD output, change `--format json` to `--format vcd` and use a `.vcd`
 output path.
 
+## Embedded I/O (EIO)
+
+The EIO core shares the ELA's JTAG chain (chain 1) at register-bus mux offset
+`0x8000`. Read the buttons via `probe_in`, drive the LEDs via `probe_out`.
+
+**Desktop GUI** (easiest): connect with backend **OpenOCD**, tap `GW1NR-9C.tap`
+(or `auto`), IR table **Gowin** — the GUI **auto-discovers and attaches** the
+EIO, so there is no chain or offset to enter. Toggle the six output bits to
+drive the LEDs, and enable *Poll inputs* to watch the buttons.
+
+**CLI** — pass the shared-chain location explicitly (`--chain 1 --base-addr
+0x8000`):
+
+```sh
+# Read the two buttons (probe_in)
+fcapz --backend openocd --host 127.0.0.1 --port 6666 \
+  --tap GW1NR-9C.tap eio-read --chain 1 --base-addr 0x8000
+
+# Drive the six LEDs (probe_out): light LED0/2/4
+fcapz --backend openocd --host 127.0.0.1 --port 6666 \
+  --tap GW1NR-9C.tap eio-write --chain 1 --base-addr 0x8000 0x15
+```
+
+**Python API:**
+
+```python
+from fcapz.transport import OpenOcdTransport
+from fcapz.eio import EioController
+
+t = OpenOcdTransport(port=6666, tap="GW1NR-9C.tap",
+                     ir_table=OpenOcdTransport.IR_TABLE_GOWIN)
+t.connect()
+eio = EioController(t, chain=1, base_addr=0x8000)
+eio.attach()
+print(eio.read_inputs())   # buttons (probe_in[1:0])
+eio.write_outputs(0x3F)    # all six LEDs on
+```
+
+## Hardware tests
+
+`test_hw_integration.py` is an opt-in regression that drives the board over
+OpenOCD. Build + load the bitstream, start OpenOCD, then:
+
+```sh
+openocd -f examples/brs_100_gw1nr9/brs_100_gw1nr9.cfg &
+python -m pytest examples/brs_100_gw1nr9/test_hw_integration.py -v
+```
+
+It covers the ELA (identity, a counter capture with `+1` per-sample checks,
+trigger match, register roundtrip, JSON/VCD export) and the shared-chain EIO
+(identity/widths, auto-discovery, LED output roundtrip, button reads). Without a
+board the tests **skip** (OpenOCD unreachable or no fcapz design loaded); set
+`FPGACAP_SKIP_HW=1` to skip unconditionally. Override the port/tap with
+`FPGACAP_OPENOCD_PORT` / `FPGACAP_OPENOCD_TAP`.
+
 ## Notes
 
 - This example uses Gowin register-path ELA readback, not Xilinx-style burst
   readback.
 - OpenOCD must already be running; the fpgacapZero OpenOCD transport does not
   program the FPGA.
-- The example does not include hardware regression tests yet.
 
 ## More Detail
 

examples/brs_100_gw1nr9/brs_100_gw1nr9_top.v

@@ -28,7 +28,7 @@ localparam int DEPTH                = 64;
     //  Internal signals
     // ----------------------------------------------
 
-    reg [5:0]                       i_leds;
+    wire [5:0]                      i_eio_leds;     // host-driven LEDs (EIO out)
     reg [1:0]                       i_buttons;
     reg [32-1:0]                    i_pad;
 
@@ -85,7 +85,12 @@ localparam int DEPTH                = 64;
         .SAMPLE_W       (SAMPLE_W),
         .DEPTH          (DEPTH),
         .NUM_CHANNELS   (CHANNELS),
-        .EIO_EN         (0)
+        .EIO_EN         (1),
+            // NOTE: EIO shares the single GW_JTAG primitive with the ELA
+            // (mux offset 0x8000).  Host: EioController(t, chain=1,
+            // base_addr=0x8000).
+        .EIO_IN_W       (2),    // read the 2 user buttons
+        .EIO_OUT_W      (6)     // drive the 6 LEDs
     ) u_ela (
         .clk            (i_jtagclk),
             // NOTE: this is a separate clock
@@ -98,10 +103,8 @@ localparam int DEPTH                = 64;
         .sample_rst     (i_sysclk_reset),
         .probe_in       (i_probe),
 
-        .eio_probe_in   (0),
-        .eio_probe_out  (),
-            // NOTE: external trigger ports
-            // tie off if not used
+        .eio_probe_in   (i_buttons),   // host reads button state
+        .eio_probe_out  (i_eio_leds),  // host drives LED state
 
         .tms_pad_i      (tms_pad_i),
         .tck_pad_i      (tck_pad_i),
@@ -219,37 +222,12 @@ localparam int DEPTH                = 64;
 
     // NOTE: Leds
     // ------------
+    //
+    // EIO demo: all 6 LEDs are driven by the EIO output register, so the
+    // host controls them directly over JTAG (eio.write_outputs).  LEDs are
+    // active-low on this board.
 
-    always @(posedge i_sysclk) begin
-        if (i_second_tick == 1'b1) begin
-            i_leds[0] <= ~i_leds[0];
-        end
-
-        if (i_jtag_activity_jtagclk == 1'b1) begin
-            // NOTE: this isn't proper CDC...
-            // fit for demonstration only.
-
-            i_leds[1] <= 1'b1;
-        end
-        if (|i_millisecond_counter[6:0] == 1'b0) begin
-            i_leds[1] <= 0;
-        end
-
-        i_leds[3:2] <= i_buttons[1:0];
-        i_leds[4]   <= i_pad[0];
-        i_leds[5]   <= i_pad[1];
-
-        if (i_sysclk_resetn == 1'b0) begin
-            i_leds <= 0;
-        end
-    end
-    assign pad_leds_n = ~i_leds;
-        // NOTE:
-        //          led[5]: i_pad[1]
-        //          led[4]: i_pad[0]
-        //          led[3]: i_buttons[1]
-        //          led[2]: i_buttons[0]
-        //          led[1]: JTAG Activity
-        //          led[0]: Heartbeat
+    assign pad_leds_n = ~i_eio_leds;
+        // NOTE: led[5:0] = EIO probe_out[5:0] (host-driven)
 
 endmodule

examples/brs_100_gw1nr9/build_brs_100_gw1nr9.tcl

@@ -85,4 +85,6 @@ run pnr
 
 puts "Deploying Bitstream"
 file mkdir $output_dir
-file copy -force ${project_dir}/impl/pnr/${project_name}.fs ${output_dir}/fcapz_brs_100_gw1nr9.fs
+# Gowin create_project nests the project under ${project_dir}/${project_name},
+# so PnR writes the bitstream to ${project_dir}/${project_name}/impl/pnr/.
+file copy -force ${project_dir}/${project_name}/impl/pnr/${project_name}.fs ${output_dir}/fcapz_brs_100_gw1nr9.fs