Repository files navigation

Open source tools andDocumentation for the Gowin FPGA bitstream format.

Project Apicula uses a combination of fuzzing and parsing of the vendor data files to provide Python tools for generating bitstreams.

Install the latest gityosys,nextpnr-himbaechel,openFPGALoader, and Python 3.8 or higher.Yowasp versions of Yosys and Nextpnr are also supported.

Currently supported boards are

• Trenz TEC0117: GW1NR-UV9QN881C6/I5
• Sipeed Tang Nano: GW1N-LV1QN48C6/I5
• Sipeed Tang Nano 1K: GW1NZ-LV1QN48C6/I5
• Sipeed Tang Nano 4K: GW1NSR-LV4CQN48PC7/I6
• Sipeed Tang Nano 9K: GW1NR-LV9QN88PC6/I5¹
• Sipeed Tang Nano 20K: GW2AR-LV18QN88C8/I7¹
• Sipeed Tang Primer 20K: GW2A-LV18PG256C8/I7¹
• Seeed RUNBER: GW1N-UV4LQ144C6/I5
• @Disasm honeycomb: GW1NS-UX2CQN48C5/I4
• szfpga: GW1NR-LV9LQ144PC6/I5

Install the tools with pip.

pip install apycula

Note that on some systems the installed binaries might not be on the path. Either add the binaries to the path, or use the path of theinstalled binary directly. (running the source files will lead to import errors)

which gowin_bba# check if binaries are on the pathpython -m site --user-base# find the site packages base directoryls$HOME/.local/bin# confirm the binaries are installed in this folderexport PATH="$HOME/.local/bin:$PATH"# add binaries to the path

From there, compile a blinky.

The example below is for the Trenz TEC0117. For other devices, use the model numbers listed above for--device, and replacetec0117 withrunber,tangnano,tangnano4k orhoneycomb accordingly. Also note the number of LEDs on your board: 8 for tec0117 and runber, 3 for honeycomb and tangnano.You can also use the Makefile in the examples folder to build the examples.

cd examplesyosys -D LEDS_NR=8 -p"read_verilog blinky.v; synth_gowin -json blinky.json"DEVICE='GW1NR-UV9QN881C6/I5'# change to your deviceBOARD='tec0117'# change to your boardnextpnr-himbaechel --json blinky.json \                   --write pnrblinky.json \                   --device$DEVICE \                   --vopt cst=$BOARD.cstgowin_pack -d$DEVICE -o pack.fs pnrblinky.json# chango to your device# gowin_unpack -d $DEVICE -o unpack.v pack.fs# yosys -p "read_verilog -lib +/gowin/cells_sim.v; clean -purge; show" unpack.vopenFPGALoader -b$BOARD pack.fs

For the Tangnano9k board, you need to call nextpnr and gowin_pack with the chip family as follows:

nextpnr-himbaechel --json blinky.json \                   --write pnrblinky.json \                   --device $DEVICE \                   --vopt family=GW1N-9C \                   --vopt cst=$BOARD.cstgowin_pack -d GW1N-9C -o pack.fs pnrblinky.json

In addition to the above, to run the fuzzers and build the ChipDB, the following additional dependencies are needed.

Version 1.9.8 of the Gowin vendor tools. Newer versions may work, but have not been tested.

Alternatively, you can use theDockerfile to run the fuzzers in a container.

To run the fuzzers, do the following in a checkout of this repo

pip install -e.export GOWINHOME=/gowin/installationmake

Check out thedoc folder for documentation about the FPGA architecture, vendor file structure, and bitstream structure.

My internship report about this projectcan be downloaded here.

My presentations atFPT2020 andRC3.

I did a fewlivestreams on twitch working on this project, which are collectedon this playlist I've also started to write Jupyter notebooks of my explorations that are more condensed than a video.

You can also come chat onMatrix orIRC

This project was funded through theNGI0 PET andNGI Zero Entrust Fund, a fund established byNLnet with financial support from the European Commission'sNext Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement N^o 825310 and 101069594.