Supporting fpgacapZero on the BRS-100-GW1NR9

Bringing fpgacapZero to the BRS-100-GW1NR9

We've all been there. The sim looks perfect, the bitstream loads first try, and then the board just... sits there, doing something weird and refusing to explain itself. At that point you either reach for a vendor debug tool and accept being chained to their IDE, or you start sprinkling LEDs across your design like breadcrumbs.

Neither is much fun.

So we're stoked to announce that our BRS-100-GW1NR9 FPGA development board now has out-of-the-box support for fpgacapZero — an open-source, vendor-agnostic FPGA debug core by Leonardo Capossio. If you haven't come across it before, fpgacapZero (or just "fcapZ") drops a tidy little Embedded Logic Analyzer and Embedded I/O block straight into your fabric, and lets you poke at it over JTAG via OpenOCD. No vendor blobs, no GUI gymnastics — just open tools talking to open tools.

Development

The first stage of adding support for fpgacapZero to the BRS-100-GW1NR9 was figuring out how to plumb JTAG to/from the general FPGA fabric. In order to remain coherent with the BRS-100-GW1NR9 example project philosophy of having a 'fully scripted workflow, this had to be implemented in a way that was pure HDL. We were aware of tools like GoWIN Analyzer Oscilloscope (GAO), which required the user to utilize the GUI, however possibly it could be used to determine how to have the GoWIN FPGA speak JTAG...

Going down this path, we created a dummy project, added basic counter, wired up and configured a GAO probe and then synthesized the project. Trolling through the generated files led us to an IP block called GW_JTAG! Its interface definition is as follows:

module GW_JTAG (
    input wire  tck_pad_i,
    input wire  tms_pad_i,
    input wire  tdi_pad_i,
    output wire tdo_pad_o,
    output wire tck_o,
    output wire tdi_o,
    output wire test_logic_reset_o,
    output wire run_test_idle_er1_o,
    output wire run_test_idle_er2_o,
    output wire shift_dr_capture_dr_o,
    output wire pause_dr_o,
    output wire update_dr_o,
    output wire enable_er1_o,
    output wire enable_er2_o,
    input  wire tdo_er1_i,
    input  wire tdo_er2_i
)
endmodule

This looked fairly familiar, given other JTAG IP cores... the main difference seemed to be combining 'shift' and 'capture' into a single strobe... and figuring out how to wire up the *_pad_* interface, as the actual JTAG pins / locations aren't defined in the constraints file. So the next stage was instantiating this module, outputting the strobes to a pin-header, and sampling them with a scope / logic analyzer (with the JTAG clock rate set to a reasonable frequency, for good measure).

Unfortunately, the initial attempt to synthesize a project with 'GW_JTAG' instantiated failed - the module was not found in the project. This led to a fair bit of head scratching - initially assumptions were that it was part of the default GoWIN library, and would be included automatically. We returned to trolling through the dummy project we created earlier, and voila! There is a stub which declares the module 'synthesis syn_black_box'. The GoWIN EDA must auto-magically wire up the JTAG IP core during the PnR stage... which turned out to be the case!

So the next stage was completed and the strobing of the GW_JTAG was ascertained. This led to the development of the specific GoWIN JTAG TAP module, 'jtag_tap_gowin.v', which interfaces the 'GW_JTAG' IP to the (somewhat) generic JTAG register interface module. This module is the pipeline between the JTAG TAP and the fpgacapZero debug cores!

After that, we were on the home stretch! All that remained was boilerplate code (i.e. build switch to enable the ELA, migrating the changes to Windows, setting up 'fpgacapZero' as a git submodule in order to avoid HDL duplication etc), as well as testing, as per the 'Trying it Out' section below.

The only other hiccup we came across was OpenOCD not supporting the default FTDI driver - we simply swapped it out for WINUSB using Zadig and all was well.

Trying It Out

From a user's point of view, the whole thing is a single build flag. Pull the repo, init the fpgaCapZero submodule, and run the following command to to bake an ELA core into the bitstream:

$ git clone https://github.com/BrisbaneSilicon/BRS-100-GW1NR9.git
$ cd BRS-100-GW1NR9/build
$ ./build.sh -e

And for your convenience, we've pre-wired it to a few signals that are handy out of the gate:

• An 8-bit free-running counter
• The state of Pushbutton 2
• The GPIO banks.

Next, program the board:

$ cd ../BRS-100-GW1NR9/program
$ ./program.sh

Kick off OpenOCD with the included brs_100_gw1nr9.cfg:

$ cd ../BRS-100-GW1NR9
$ openocd -f foreign/openocd/brs_100_gw1nr9.cfg &

And you can now ask the core to introduce itself:

$ fcapz --backend openocd --port 6666 --tap GW1NR-9C.tap probe

That spits out a JSON blob telling you the core's depth, channel count, trigger capabilities — everything you need to plan a capture. Then it's just a matter of running fcapz capture with your trigger settings, getting a VCD back, and opening it in your favourite waveform viewer:

$ fcapz --backend openocd --port 6666 --tap GW1NR-9C.tap capture --depth 64 --pretrigger 8 --posttrigger 16 --trigger-mode value_match --trigger-value 0 --trigger-mask 0xFF --channel 0 --format vcd --out capture.vcd

We're partial to Surfer, but anything that reads VCD will do:

$ surfer capture.vcd

The whole loop — build, program, probe, capture, view — is a handful of terminal commands on Linux or Windows. No IDE required, nothing to click through, and nothing tying you to a specific silicon vendor. That last bit matters to us: debug tooling that only lives inside one vendor's GUI is debug tooling that quietly breaks every time you change boards, share a project, or come back to something a year later.

Final Thoughts

If this sounds like your kind of thing, grab a BRS-100-GW1NR9 from BrisbaneSilicon, clone the example project, and follow the Embedded Logic Analyzer section of the README. And a big thanks to Leonardo for making fpgacapZero — it's exactly the kind of tool the FPGA scene has been missing.

Please report any issues here.