Skip to main content

Open Source tools for Gowin FPGAs

Project description

Project Apicula

Open source tools and Documentation 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.

Getting Started

Install the latest git yosys, 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 [^1]
  • Sipeed Tang Nano 20K: GW2AR-LV18QN88C8/I7 [^1]
  • Sipeed Tang Primer 20K: GW2A-LV18PG256C8/I7 [^1]
  • Seeed RUNBER: GW1N-UV4LQ144C6/I5
  • @Disasm honeycomb: GW1NS-UX2CQN48C5/I4
  • szfpga: GW1NR-LV9LQ144PC6/I5

[^1]: C devices require passing the --family flag as well as --device to Nextpnr, and stating the family in place of device when passing -d to gowin_pack because the C isn't part of the device ID but only present in the date code. Check examples/himbaechel/Makefile for the correct command.

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 the installed binary directly. (running the source files will lead to import errors)

which gowin_bba # check if binaries are on the path
python -m site --user-base # find the site packages base directory
ls $HOME/.local/bin # confirm the binaries are installed in this folder
export 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 replace tec0117 with runber, tangnano, tangnano4k or honeycomb 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 examples
yosys -D LEDS_NR=8 -p "read_verilog blinky.v; synth_gowin -json blinky.json"
DEVICE='GW1NR-UV9QN881C6/I5'  # change to your device
BOARD='tec0117' # change to your board
nextpnr-himbaechel --json blinky.json \
                   --write pnrblinky.json \
                   --device $DEVICE \
                   --vopt cst=$BOARD.cst
gowin_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.v
openFPGALoader -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.cst
gowin_pack -d GW1N-9C -o pack.fs pnrblinky.json

Getting started for contributors

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 the Dockerfile 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/installation
make

Resources

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

My internship report about this project can be downloaded here.

My presentations at FPT2020 and RC3.

I did a few livestreams on twitch working on this project, which are collected on 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 on Matrix or IRC

Funding

This project was funded through the NGI0 PET and NGI Zero Entrust Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 825310 and 101069594.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

Apycula-0.20.tar.gz (16.1 MB view details)

Uploaded Source

Built Distribution

Apycula-0.20-py3-none-any.whl (9.6 MB view details)

Uploaded Python 3

File details

Details for the file Apycula-0.20.tar.gz.

File metadata

  • Download URL: Apycula-0.20.tar.gz
  • Upload date:
  • Size: 16.1 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.8.18

File hashes

Hashes for Apycula-0.20.tar.gz
Algorithm Hash digest
SHA256 df87240c39b62fa38e87c3a11047210f1d1683955825253fc14cd8e62709d1b7
MD5 89b2d5ba95f761453773fc21eaa8be5e
BLAKE2b-256 3207e4d8c9f51fa5a520060888a118269bc361d9526b031199757b9cbbd7a5ea

See more details on using hashes here.

File details

Details for the file Apycula-0.20-py3-none-any.whl.

File metadata

  • Download URL: Apycula-0.20-py3-none-any.whl
  • Upload date:
  • Size: 9.6 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.8.18

File hashes

Hashes for Apycula-0.20-py3-none-any.whl
Algorithm Hash digest
SHA256 9acda60db7d9d8a4d4eab4058c5d5bb99f1e4e998aa25b36677700d0cc23502a
MD5 5b81a9e81c7a898331d4f147ae1931e2
BLAKE2b-256 d1330eb3624e70d09350356a428315b8aa0efa6132af91d93b8f6520fde5f058

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page