[FIRRTL] Documentation and cleanup for the FIRRTL backend (#2096)

This PR contains some small follow-ons to the FIRRTL backend:
- We now use
[firtool](https://github.com/llvm/circt/releases/tag/firtool-1.75.0)
instead of the deprecated FIRRTL compiler in fud2 (thanks @ekiwi!). Note
that I changed fud2's configurations for FIRRTL.
- We also use the `external-to-ref` pass instead of a `sed`-based hack
for converting `@external`s to `ref`s.
- I wrote some documentation on running the FIRRTL backend!

Other than some relatively minor things (like playing around with
firtool arguments), I'm hoping this will tie a small bow around the
FIRRTL backend work until we want to pick it back again for ESSENT
simulation :)

docs/SUMMARY.md

@@ -26,6 +26,7 @@
   - [Scripting](./running-calyx/fud2/scripts.md)
 - [Interfacing with Calyx RTL](./running-calyx/interfacing.md)
 - [The Calyx Interpreter](./running-calyx/interpreter.md)
+- [FIRRTL Backend](./running-calyx/firrtl.md)
 
 # Compiler Development Guide
 

docs/running-calyx/firrtl.md

@@ -0,0 +1,71 @@
+# FIRRTL Backend
+
+Calyx programs can be translated into the [FIRRTL](https://bar.eecs.berkeley.edu/projects/firrtl.html) intermediate language. <!-- TODO: Link OSDA paper when it goes on arxiv -->
+
+## Basic Use
+
+To translate an example program to FIRRTL, try:
+
+    $ cargo run examples/tutorial/language-tutorial-iterate.futil -p external-to-ref -p all -b firrtl
+
+## Running with `fud2`
+
+The FIRRTL backend can also be run through fud2, which we recommend using.
+
+### Setup
+
+To run FIRRTL-translated programs, we need to set up [Firtool](https://github.com/llvm/circt) for use by fud2. We recommend using [Firtool version 1.75.0](https://github.com/llvm/circt/releases/tag/firtool-1.75.0).
+
+First, download and extract the Firtool binary. Then, edit `fud2`'s configuration file:
+
+    $ fud2 edit-config
+
+Add these lines:
+
+```toml
+[firrtl]
+firtool = "<path to extracted firtool directory>/bin/firtool"
+```
+
+[fud2]: ./fud2.md
+
+### Obtaining FIRRTL
+
+> The FIRRTL backend on fud2 currently requires Calyx with the YXI feature to be built. (Refer to the above)
+
+The FIRRTL backend offers two options based on how Calyx primitives are handled: (1) use Calyx's existing Verilog implementations, and (2) generate FIRRTL implementations.
+
+To generate FIRRTL-version of the Calyx program that will use Verilog primitives, run fud2 with `--to firrtl`:
+```
+fud2 examples/tutorial/language-tutorial-iterate.futil --to firrtl
+```
+
+To generate FIRRTL-version of the Calyx program containing FIRRTL primitives, run fud2 with `--to firrtl-with-primitives`:
+```
+fud2 examples/tutorial/language-tutorial-iterate.futil --to firrtl-with-primitives
+```
+
+### Simulating FIRRTL-translated programs
+
+To simulate a FIRRTL-translated Calyx program using Verilog primitives, run fud2 with `--through firrtl`:
+```
+fud2 examples/tutorial/language-tutorial-iterate.futil --to dat -s sim.data=examples/tutorial/data.json --through firrtl
+```
+
+To simulate a FIRRTL-translated Calyx program using FIRRTL primitives, run fud2 with `--through firrtl-with-primitives`:
+
+```
+fud2 examples/tutorial/language-tutorial-iterate.futil --to dat -s sim.data=examples/tutorial/data.json --through firrtl-with-primitives
+```
+
+Both examples will yield
+```
+{
+  "cycles": 76,
+  "memories": {
+    "mem": [
+      42
+    ]
+  }
+}
+```

fud2/scripts/axi.rhai

@@ -2,6 +2,7 @@ import "calyx" as c;
 
 export const yxi = state("yxi", ["yxi"]);
 
+export let yxi_setup = yxi_setup;
 fn yxi_setup(e) {
    e.config_var_or("yxi", "yxi", "$calyx-base/target/debug/yxi");
    e.rule("yxi", "$yxi -l $calyx-base $in > $out");

fud2/scripts/firrtl.rhai

@@ -1,3 +1,4 @@
+import "axi" as a;
 import "calyx" as c;
 import "testbench" as tb;
 
@@ -93,24 +94,27 @@ let firrtl_with_primitives = state("firrtl-with-primitives", ["fir"]); // using
 op(
     // use Verilog
     "calyx-to-firrtl",
-    [c::calyx_setup, tb::custom_setup],
+    [c::calyx_setup, a::yxi_setup, tb::custom_setup],
     c::calyx_state,
     firrtl,
     |e, input, output| calyx_to_firrtl_helper(e, input, output, false),
 );
 
 op(
     "firrtl-with-primitives",
-    [c::calyx_setup, firrtl_primitives_setup, tb::custom_setup],
+    [c::calyx_setup, firrtl_primitives_setup, a::yxi_setup, tb::custom_setup],
     c::calyx_state,
     firrtl_with_primitives,
     |e, input, output| calyx_to_firrtl_helper(e, input, output, true),
 );
 
 // The FIRRTL compiler.
 fn firrtl_setup(e) {
-    e.config_var("firrtl-exe", "firrtl.exe");
-    e.rule("firrtl", "$firrtl-exe -i $in -o $out -X sverilog");
+    e.config_var("firrtl-exe", "firrtl.firtool");
+    e.rule(
+        "firrtl",
+        "$firrtl-exe $in -o $out --disable-all-randomization",
+    );    
 
     e.rsrc("primitives-for-firrtl.sv");
     // adding Verilog implementations of primitives to FIRRTL --> Verilog compiled code