# `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](https://github.com/cucapra/futil/tree/master/fud).

## Installation
You need [Flit](https://flit.readthedocs.io/en/latest/) to install `fud`. Install it with `pip3 install flit`.

You can then install `fud` with

```bash
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:
```bash
flit install --symlink
```

You can also install `fud` with

```bash
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 config`.

**Check.**
Fud can automatically check if your configuration is valid and can help you set
certain variables. Perform this check with:
```bash
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.
```bash
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.
```bash
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](https://www.veripool.org/projects/verilator/wiki/Installing).

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:
```bash
cargo install vcdump
```

## Dahlia Frontend

In order to use the Dahlia frontend with Fud, first [install
Dahlia](../frontends/dahlia.md).
Once Dahlia is compiled, point `fud` to the Dahlia compiler binary:
```bash
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](../frontends) use a Calyx ast library written in Python. Install with:
```
cd calyx-py && flit install -s
```

Frontend specific instructions:
 - [Systolic array](../frontends/systolic-array.md): Nothing else needed.
 - [NTT](../frontends/ntt.md): `pip3 install prettytable`
 - [MrXL](../frontends/mrxl.md): `cd frontends/mrxl && flit install -s`
 - [TVM Relay](../frontends/tvm-relay.md): 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](./synthesis.md) to configure them.

## Adding External Stages

`fud` supports using stages that aren't defined in it's main source tree.
These are known as 'external stages' and the provide a mechanism
for projects using Calyx to take advantage of `fud`. You can register an
external stage with:
```
fud register stage_name -p /path/to/stage.py
```
Once an external stage is registered, it behaves exactly like any other stage.

You can remove an external stage with:
```
fud register stage_name --delete
```

## 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`.

[frontends]: ./frontends/index.md
[calyx-py]: ./calyx-py.md
[flit]: https://flit.readthedocs.io/en/latest/
[verilator]: https://www.veripool.org/wiki/verilator