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
  • Set up Chisel compiler and get it to emit LoFIRRTL code
  • Write one primitive in Chisel (translate from Verilog)
  • 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
  • Add discussion to suggest differential testing
  • test test test!!!
    • Problem: FIRRTL compiler and ESSENT both optimize away the non-inputs.
    • Use annotation to read memories from file --> No writememh equivalent in Chisel/FIRRTL
    • Write testbench mechanism that exposes all of the memories we need to deal with (using refs) and supply memories as inputs and outputs.
    • Debug language-tutorial-iterate being stuck (combinational loop?)
    • Write C++ test harness to read memory and write memory
  • Automate process of text-replacing from FIRRTL template
    • Create Calyx backend to find all of the primitive uses across the entire program and produces JSON
    • Write a python script to read the JSON and call m4 accordingly to create the primitives in question
    • Write a bash script to use cat (or something of the sort) to concatenate the generated FIRRTL and the necessary primitives
    • Add fud2 support for primitives-inst (temporary name) backend
    • Add option to FIRRTL backend to differentiate between extmodule generation and not.
    • Add fud2 support for the whole pipeline of generating FIRRTL
• Cleanup after deadline
  • 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: (Change the simulation harness to not use readmemh and writememh #1603 (comment)) --> Deferred to [fud2] Switch to custom testbench generation #2086.
  • Better handle invalidating output ports
  • Investigate why we get more clock cycles in FIRRTL land
• Other
  • Benchmark btwn original Calyx, FIRRTL + Verilog primitives, FIRRTL + FIRRTL primitives
• Things that I need to fix
  • 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

• 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 :)
  • Conditionals
  • Default value/invalid statements before the first guarded assignment.
• Cells
  • Non-primitive cells
  • Primitive cells
    • Function converting cell declaration to an identifier string
    • Create extmodules for all of the identifiers created
    • FIX: need to add inputs and outputs to extmodule definition.
• Cleaner solutions relating to attributes
  • 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.
  • 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).
  • Using TopLevel attribute to find the top level component

---

Archived: Manual Testing and Execution via fud

• 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:
    • 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?
    • Understand tb.sv
    • Need to figure out a simple testbench I can use to harness a simple program.
    • Make testbench for simple program that involves the clock.
    • Make testbench work for program that uses primitives (no std_mem).
    • 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
    • Write bash script to do all of this?
    • Figure out why language-tutorial-compute is not working...
      • FIRRTL optimizes the assignment with only one conditional.
      • Try manually adding other conditionals, or else block.
• FIRRTL Execution
  • Linking FIRRTL into fud2.
    • Something like

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

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