fud: The Calyx Driver

Working with Calyx involves a lot of command-line tools. For example, an incomplete yet daunting list of CLI tools used by Calyx is:

  • All the Calyx frontends.
  • Calyx compiler and its various command line tools
  • Verilator, the Verilog simulation framework used to test Calyx-generated designs.
  • Waveform viewers to see the results of simulation

fud aims to provide a simple interface for using these toolchains and executing them in a pipeline. The source for fud is here.

Installation

You need Flit to install fud. Install it with pip3 install flit.

You can then install fud with

flit install

(If using this method to install fud, pip3 should be version >= 20)

If you are working on fud itself, you can install it with a symlink with:

flit install --symlink

You can also install fud with

flit build
pip3 install dist/fud-0.1.0-py3-none-any.whl

Finally, point fud to the root of the repository:

fud config global.futil_directory <full path to Calyx repository>

Configuration

Fud uses a global configuration file to locate tool paths and default values. To view the configuration, use fud c or fud config.

Check. Fud can automatically check if your configuration is valid and can help you set certain variables. Perform this check with:

fud check

Viewing keys. To view the current value of a key, use fud config key. For example, the following shows the path to the Calyx compiler.

fud config stages.futil.exec

Updating keys. Keys can be updated using fud config key value. For example, the following command updates the path to the Calyx compiler.

fud config stages.futil.exec ./target/debug/futil

Adding Backends

fud wraps both frontends and backends for Calyx. For a minimally useful fud installation, you need to configure the Verilator backend and accompanying tools.

Verilator. We use the open source Verilator tool to simulate Verilog programs generated by the Calyx compiler. Install Verilator by following the instructions.

By default, fud will use the verilator executable to run Verilator. To use a different binary, configure the path by:

fud config stages.verilog.exec <binary>

Vcdump. Vcdump is a tool for converting vcd (Value Change Dump) files to JSON for easier analysis with the command line.

Install it with:

cargo install vcdump

Dahlia Frontend

In order to use the Dahlia frontend with Fud, first install Dahlia. Once Dahlia is compiled, point fud to the Dahlia compiler binary:

fud config stages.dahlia.exec <full path to dahlia repo>/fuse

Python frontends (Systolic array, NTT, MrXL, TVM Relay)

You need flit to install our Python frontends.

pip3 install flit

Our Python frontends use a Calyx ast library written in Python. Install with:

cd calyx-py && flit install -s

Frontend specific instructions:

  • Systolic array: Nothing else needed.
  • NTT:
    • Install dependencies: pip3 install prettytable
    • Install external fud stage: fud register ntt -p frontends/ntt-pipeline/fud/ntt.py
  • MrXL:
    • Install mrxl binary: cd frontends/mrxl && flit install -s
    • Install mrxl external stage for fud: fud register mrxl -p frontends/mrxl/fud/mrxl.py
  • TVM Relay: See instructions.

Adding Synthesis Backends

fud supports wraps the Vivado (synth-verilog) and Vivado HLS (vivado-hls) tools to generate area and resource estimates for Calyx designs. See the instructions to configure them.

Working with Stages

Fud is structured as a sequence of stages that transform inputs of one form to outputs.

Stages. fud transforms a file in one stage into a file in a later stage. The --from and --to options specify the input and output stages to the fud exec subcommand. Use fud info to view all possible stages.

Guessing stages. fud will try to guess the starting stage by looking at the extension of the input file and output file (if specified using the -o flag). If it fails to guess correctly or doesn't know about the extension, you can manually set the stages using --to and --from.