Tasks for Calyx-to-FIRRTL backend

[ayakayorihiro]

This issue lists out the next steps for implementing and testing a Calyx-to-FIRRTL backend, as described in #1552 .

Current status: I added fud2 support for the FIRRTL backend!

• [ ] Primitives
  • [x] Set up Chisel compiler and get it to emit LoFIRRTL code
  • [x] Write one primitive in Chisel (translate from Verilog)
  • [x] Implement primitives in FIRRTL
    • Troubling ones!
      • std_slice
      • std_pad
      • std_mem_*: Double check how 2,3,4 dimensional memories work? <-- Focus on 1 for now, maybe implement 2 via a one-dimensional array and calculating the array element we want to get the data from
  • [x] Add discussion to suggest differential testing
  • [ ] test test test!!!
    • [ ] Problem: FIRRTL compiler and ESSENT both optimize away the non-inputs.
    • [x] Use annotation to read memories from file --> No writememh equivalent in Chisel/FIRRTL
    • [x] Write testbench mechanism that exposes all of the memories we need to deal with (using refs) and supply memories as inputs and outputs.
    • [x] Debug language-tutorial-iterate being stuck (combinational loop?)
    • [ ] Write C++ test harness to read memory and write memory
  • [x] Automate process of text-replacing from FIRRTL template
    • [x] Create Calyx backend to find all of the primitive uses across the entire program and produces JSON
    • [x] Write a python script to read the JSON and call m4 accordingly to create the primitives in question
    • [x] Write a bash script to use cat (or something of the sort) to concatenate the generated FIRRTL and the necessary primitives
    • [x] Add fud2 support for primitives-inst (temporary name) backend
    • [x] Add option to FIRRTL backend to differentiate between extmodule generation and not.
    • [x] Add fud2 support for the whole pipeline of generating FIRRTL
• Cleanup after deadline
  • [x] Write a backend to obtain all of the ref usages and their inputs into a JSON file instead of the extreme hack of splitting on commas. --> Using the yxi backend for this.
  • [ ] Use firtool instead of the deprecated FIRRTL compiler.
  • [ ] Put Usage comments into a formal documentation about the FIRRTL backend
  • [ ] Clean up fud2 to not have a bazillion states for verilog. Relevant: (https://github.com/calyxir/calyx/issues/1603#issuecomment-1937020425) --> Deferred to #2086.
  • [x] Better handle invalidating output ports
  • [x] Investigate why we get more clock cycles in FIRRTL land
• Other
  • [x] Benchmark btwn original Calyx, FIRRTL + Verilog primitives, FIRRTL + FIRRTL primitives
• Things that I need to fix
  • [x] Memories - the current "implementation" of std_mem_* in verilog reads memories from a hardcoded location.
  • [ ] Primitives - we may need to translate more primitives based on what tests we want to run

---

Archived: Translating Calyx language features

• [x] Guards
  • This can be implemented either by recursively going down the guard tree, or via flattening as done in verilog.rs. Either way it'll be a good exercise in learning Rust :)
  • [x] Conditionals
  • [x] Default value/invalid statements before the first guarded assignment.
• [x] Cells
  • [x] Non-primitive cells
  • [x] Primitive cells
    • [x] Function converting cell declaration to an identifier string
    • [x] Create extmodules for all of the identifiers created
    • [x] FIX: need to add inputs and outputs to extmodule definition.
• [x] Cleaner solutions relating to attributes
  • [x] Properly identifying clocks via @clk
    • We want to make sure that the clock port is given the FIRRTL Clock type. As a first pass attempt, I have a hack that checks for the name clk (that Calyx autogenerates), but I want to check for the @clk attribute instead for a cleaner solution.
  • [x] Identifying @control attributes instead of @data attributes for default value/invalid statements
    • Currently I use the is_data_port() function from verilog.rs to check whether a port is a data or a control port. But, what I actually want to say is x is invalid for all non-control ports (this may not matter much since is invalid gets sugared down to zero assignments anyhow).
  • [x] Using TopLevel attribute to find the top level component

---

Archived: Manual Testing and Execution via fud

• [x] Manual Testing
  • Calyx compiler will emit FIRRTL, get FIRRTL converted to Verilog. We also have Calyx primitives written in Verilog
  • Writing a test bench in Verilog that runs the FIRRTL.
  • Maybe it's nice to have a small bash script to do all of this once I write out the test bench?
  • Refer to tb.sv from fud.
  • Local TODOs:
    • [x] Get verilator working on my local. Confirmed that using the docker image works so maybe it's a problem with versioning. Use icarus verilog for now?
    • [x] Understand tb.sv
    • [x] Need to figure out a simple testbench I can use to harness a simple program.
    • [x] Make testbench for simple program that involves the clock.
    • [x] Make testbench work for program that uses primitives (no std_mem).
    • [x] Make testbench work for programs that uses std_mem.
      • The idea here is to create an ad-hoc verilog module that is hard-coded to get a memory from a specific dat file.
      • Use the readmemh and writememh constructs in the ad-hoc module
    • [x] Write bash script to do all of this?
    • [x] Figure out why language-tutorial-compute is not working...
      • FIRRTL optimizes the assignment with only one conditional.
      • [x] Try manually adding other conditionals, or else block.
• [x] FIRRTL Execution
  • [x] Linking FIRRTL into fud2.
    • Something like

    fud e --from calyx --to verilog --through firrtl
    

  • [x] Produce FIRRTL via fud2
  • [x] Run the FIRRTL → System-Verilog compiler via fud2.
  • [x] Simulate the resulting System-Verilog
    • Need to figure out how to bring the primitives into the picture.