GateMate Toolchain: Quickstart

This tutorial guides you through all toolchain components with an example project.

Get the latest Toolchain Builds

The GateMate FPGA toolchain is based on the open-source OSS CAD Suite, which bundles together essential tools such as:

• Yosys – synthesis framework for Verilog/VHDL
• nextpnr-himbaechel – place-and-route tool for GateMate devices
• gmpack – bitstream generation utility
• openFPGALoader – programming utility for JTAG and SPI configuration

You can always find the latest pre-built toolchain packages for all major platforms on the official release page:

🔗 https://github.com/YosysHQ/oss-cad-suite-build/releases/

Available Builds

Select the archive that matches your operating system and architecture:

• darwin-arm64 – macOS on Apple Silicon
• darwin-x64 – macOS on Intel
• linux-arm64 – Linux on ARM (e.g. Raspberry Pi, embedded devices)
• linux-x64 – Linux on standard x86_64 systems
• windows-x64 – Windows 10/11 (x86_64)

Installation Steps

Download and extract the archive to a convenient directory, then initialize the environment in your shell:

$ tar -xvf oss-cad-suite-<arch>-<build>.tgz
$ chmod +x environment
$ source environment

After sourcing, your $PATH will include all toolchain executables (yosys, nextpnr-himbaechel, gmpack, openFPGALoader, etc.).

To verify that everything is set up correctly:

$ yosys -V
Yosys 0.58+ (git sha1 ...)

If you prefer a permanent setup, you can add the environment initialization line to your shell configuration file (e.g. .bashrc, .zshrc):

source /path/to/oss-cad-suite/environment

Notes

• Windows users: Use a Unix-compatible shell (e.g., Git Bash or WSL) for the best experience.
• Linux users: Ensure you have libtinfo, libffi, and libz installed.
• macOS users: On first run, macOS may prompt you to allow execution of unsigned binaries—approve them in System Preferences → Security & Privacy.

Synthesize the Design

Synthesis converts your HDL source files (VHDL, Verilog, or SystemVerilog) into a technology-specific netlist that can be mapped to the FPGA fabric. The GateMate synthesis flow uses GHDL for VHDL sources and Yosys for Verilog/SystemVerilog sources.

Synthesize VHDL sources

For VHDL-based projects, use GHDL with Yosys integration to generate a Verilog netlist:

$ ghdl synth -fexplicit -fsynopsys --out=verilog <FILES> -e <top_entity>

• -fexplicit ensures all signals and generics are explicitly defined.
• -fsynopsys enables Synopsys-compatible VHDL parsing.
• <FILES> refers to all your VHDL sources (space-separated).
• <top_entity> defines the top-level design unit to synthesize.

Once completed, you will obtain a Verilog output that can be passed directly to Yosys for synthesis.

Synthesize Verilog or SystemVerilog sources

Yosys supports both Verilog and SystemVerilog. The synth_gatemate command within Yosys ensures the output is optimized for the GateMate FPGA architecture.

$ yosys \
    -ql <logfile> \
    -p '
        read_verilog -sv <sources>; # read verilog files with sv support
        synth_gatemate \
            -top <topmodule>        # top module name
            -luttree                # mandatory: enable luttree support
            -nomx8                  # mandatory: disable MUX8 support
        write_json <netlist>.json;  # write JSON netlist for implementation
        write_verilog <netlist>.v   # optional: write verilog netlist
    '

synth_gatemate Parameters

• -top <module> – use the specified module as top module.
• -vlog <file> – write the design to the specified Verilog file. Writing of an output file is omitted if this parameter is not specified.
• -json <file> – write the design to the specified JSON file. Writing of an output file is omitted if this parameter is not specified.
• -run <from_label>:<to_label> – only run the commands between the labels. An empty from label is synonymous to ‘begin’, and an empty to label is synonymous to the end of the command list.
• -noflatten – do not flatten design before synthesis.
• -nobram – do not use CC_BRAM_20K or CC_BRAM_40K cells in the output netlist.
• -noaddf – do not use CC_ADDF full adder cells in the output netlist.
• -nomult – do not use CC_MULT multiplier cells in the output netlist.
• -nomx8, -nomx4 – do not use CC_MX{8,4} multiplexer cells in the output netlist.
• -luttree – use new LUT tree mapping approach.
• -noiopad – disable I/O buffer insertion (useful for hierarchical or out-of-context flows).
• -noclkbuf – disable automatic clock buffer insertion.

Tips

• Always verify the synthesis log for warnings or errors.
• Use the stat command inside Yosys to check resource utilization.
• The resulting .json file is used as input for place and route.

Implement the Design

Implementation maps the synthesized netlist to the physical FPGA resources, performing placement, routing, and timing analysis. This is handled by nextpnr-himbaechel, the backend optimized for GateMate devices.

$ nextpnr-himbaechel \
    --device=CCGM1A1        # GateMate device, select CCGM1A1 or CCGM1A2
    --json <netlist>.json   # input netlist after `yosys`
    -o ccf=olimex.ccf       # input CCF pin constraints file
    -o out=impl.txt         # output textfile for bitstream generation
    --sdc <constraints>     # optional: input SDC constraints file
    --router router2        # router, always select `router2`

Notes

• Use --gui to launch the graphical interface and visually inspect the design.
• The .sdc (Synopsys Design Constraints) file defines timing requirements such as clocks and paths.

nextpnr-himbaechel Architecture-Specific Parameters

• -o ccf=<file> – name of the constraint file (CCF) defining pin assignments and I/O standards.
• --allow-unconstrained – allows unconstrained I/Os to remain unassigned (use with caution).
• -o fpga_mode <lowpower|economy|speed> – sets FPGA operation mode.
• -o time_mode <best|typical|wors> – defines timing analysis mode.
• -o strategy <mirror|full|clk1> – multi-die clock placement strategy.
• mirror: mirrored placement for symmetry.
• full: full clock network placement.
• clk1: single-clock-die routing only.
• -o force_die <ID> – forces place-and-route on a specific die (e.g. 1A, 1B, etc.).

After successful implementation, a placement and routing report is generated. Review it to ensure timing closure and resource efficiency.

Next, convert the implementation file into a bitstream using gmpack:

$ gmpack \
    --spimode <arg>     # optional: flash SPI mode (single, dual, quad)
    --crcmode <arg>     # optional: CRC error behaviour (check, ignore, unused)
    --reconfig          # optional: enable reconfiguration interface
    --bootaddr <arg>    # optional: boot address for secondary bitstream in flash
    --background        # optional: enables background reconfiguration in flash mode
    <input>.txt         # input textfile after `nextpnr`
    <output>.bit        # output bitfile for programmer

Configure the FPGA

The final step is to load the generated bitstream onto the FPGA. You can program the device using openFPGALoader, either via JTAG or SPI.

Configure FPGA via JTAG

JTAG configuration is suitable for development and debugging since it provides quick reprogramming without requiring flash memory.

$ openFPGALoader \
    --index-chain <arg> # optional: device index in JTAG chain
    --freq <arg>        # optional: programmer frequency in Hz (default 6M)
    -b <arg>            # gatemate_evb_jtag: jtag, olimex_gatemateebb: dirtyJtag
    <bitfile>           # input bitfile after `gmpack`

Configure FPGA via SPI

SPI mode allows configuration directly from a serial interface or flash device.

$ openFPGALoader \
    --freq <arg>        # optional: programmer frequency in Hz (default 6M)
    -b <arg>            # gatemate_evb_spi: spi
    -m                  # write bitstream in SRAM
    <bitfile>           # input bitfile after `gmpack`

Store Bitstream in External Flash

To make your design persistent (i.e., automatically loaded at power-up), program it into the onboard flash memory:

$ openFPGALoader \
    --index-chain <arg> # optional: device index in JTAG chain
    --freq <arg>        # optional: programmer frequency in Hz (default 6M)
    -b <arg>            # gatemate_evb_jtag: jtag, gatemate_evb_spi: spi, olimex_gatemateebb: dirtyJtag
    -f                  # write bitstream in flash
    <bitfile>           # input bitfile after `gmpack`

After programming, power-cycle the board or press the reset button to verify that your FPGA design boots automatically from flash.