[Calyx] Lack of Documentation for Calyx Lowering Passes and Recommended Order

[ManelMCCS]

I have encountered difficulties understanding and applying the appropriate flags for lowering the Calyx dialect in my project. Specifically, I am unsure about when to use the following flags:

--calyx-remove-comb-groups
--calyx-remove-groups
--calyx-remove-groups-fsm
--canonicalize

The lack of comprehensive documentation regarding the available Calyx passes and their recommended order makes it challenging to determine the appropriate usage.

[rachitnigam]

It depends on your use case but if you're okay with using the native Calyx compiler, you follow [these instruction](https://docs.calyxir.org/fud/circt.html#mlir-to-native-representation] to generate the native representation and transform that into Verilog. @mortbopet is there a canonical set of commands to run to compile Calyx programs in the CIRCT flow? I can add that information to our documentation page and also update the CIRCT for Calyx with that information

[mortbopet]

I think the most canonical way is the set of commands executed here. Although i think it would aid users a lot if a calyx pipeline would be embedded into the hlstool so newcomers have a one-stop-shop for these things.

[rachitnigam]

@mortbopet what would be the best place to put this documentation? Also, I can work on adding the Calyx lowering flow to hlstool

[mortbopet]

@rachitnigam thank you for taking a look at this - for more elaborate pass documentation, the description tag in the .td pass definitions will be automatically placed here, although i honestly don't think that that many people find that to be a useful reference (it's just too many passes bundled into one webpage with no proper ordering.

Instead, I would personally prefer if a rationale document was added to Calyx, and then place a more cohesive story about the lowering flow in there.

[rachitnigam]

I can take a shot at that! Another dumb question: where exactly do the rationale files go? Is it okay to make a standalone one like the static scheduling page?

[mortbopet]

Just duplicate the folder structure for the other dialect rationales, e.g. https://github.com/llvm/circt/blob/main/docs/Dialects/Handshake/RationaleHandshake.md.

Is it okay to make a standalone one like the static scheduling page?

To follow the style of the other dialects, i think it is most appropriate that dialect rationales are nested under the autogenerated dialect docs.

I also just added this PR which should serve as a place where you can write generally about the Calyx flow.