Setup

1. The Basics

To build, simulate and flash Tiliqua bitstreams you only need:

  • A build system: pdm (LINK)

    • You will see installation instructions for Linux / Mac / Windows.

    • This is used for managing Python dependencies in a virtual environment, so that they are A) guaranteed to be exactly the same version as in CI and B) don’t affect the installed packages on your computer.

  • An FPGA tool suite: oss-cad-suite (LINK)

    • You will see installation instructions for Linux / Mac / Windows.

    • If you are paranoid, it might be worth installing the same version as we are using in CI

Note

By default, synthesis will use yowasp-yosys and yowasp-nextpnr-ecp5 (python packages), rather than any oss-cad-suite you have installed. When running locally, builds are often faster if you point to your own installation - modify gateware/.env.toolchain (simply deleting it will try to find yosys in your PATH).

2. Check Installation

Before continuing, it’s worth checking everything is installed okay and is correctly in your PATH:

$ pdm --version
PDM, version 2.26.0
$ openFPGALoader -V
openFPGALoader v0.12.1
$ verilator --version
Verilator 5.031 devel rev v5.030-75-gc98744b91

3. Check USB device permissions

With Tiliqua powered on and the dbg USB port connected, you want to see something like this (without using sudo!):

$ openFPGALoader --scan-usb
Bus device vid:pid       probe type      manufacturer serial               product
007 006    0x1209:0xc0ca dirtyJtag       apf.audio    E463A8574B2D2632     Tiliqua R5 apfbug-beta4-dirty

On Linux, you may need to install a udev rule for this to work. The exact procedure depends on your distro so I can only provide an example. On Arch Linux, I use the following rule:

# Placed at `/etc/udev/rules.d/50-tiliqua.rules`
SUBSYSTEM=="usb", ATTRS{idVendor}=="1209", ATTRS{idProduct}=="c0ca", MODE="0666", GROUP="users", TAG+="uaccess"

You want this configured correctly as some of the Tiliqua build scripts call openFPGALoader under the hood (without sudo).

4. Initialize submodules

After cloning the main repository, you should also initialize all the submodules:

cd gateware
git submodule update --init --recursive

5. Set up python environment

Finally, install all python dependencies in a PDM-managed virtual environment:

# from the `gateware` directory
pdm install

Now you are ready to build some bitstreams!

6. (optional, for CPU Bitstreams) A Rust toolchain

The above tools are sufficient for simple bitstreams. More advanced bitstreams include an SoC and CPU that runs Rust firmware for the menu system and graphics. To build these bitstreams, you will also need a Rust toolchain.

  • Install rustup (LINK)

    • Install the following Rust components:

      rustup target add riscv32im-unknown-none-elf
rustup target add riscv32imafc-unknown-none-elf # for `macro_osc` only, it uses an FPU
rustup component add rustfmt clippy llvm-tools
cargo install cargo-binutils svd2rust form

    • Make sure the tools like svd2rust, form and so on are available in your PATH after installing them. You may need to add a .cargo/bin-like directory to your path.

Warning

Building bitstreams that include an SoC is currently only supported on Linux and Mac. For Windows, the easiest path is probably doing this under WSL.

Note

All examples are built in CI. If you’re having trouble setting up your environment or missing a dependency, it may also be worth checking the Dockerfile.