User-oriented Documentation for Firtool-lib C-API

[SpriteOvO]

trafficstars

A well-documented Firtool-lib C-API would be great for downstreams (e.g. chisel) references. There is a lack of such a thing at the moment.

So I opened the issue to discuss how this might be implemented. Any thoughts and opinions are welcome :)

---

Things that need to be documented:

• All populate- functions.

• The effect of each option (shared the same doc for both function setter and command-line opt)

Possible implementations:

• Write a Markdown file and place it under ./docs in the git repository, then render as HTML and host it on https://circt.llvm.org/.

• Write code comments in the header files.

• Anything else?

[sequencer]

At Chisel dev meeting this week, this issue was discussed at Chisel Dev meeting this Monday, @sequencer, @jackkoenig, @seldridge, @darthscsi. here is the meeting note:

[schuyler] Firtool.cpp options for C-API. How do we want to proceed? #6435 #6438 #6439 [jiuyang] Want to run firtool from Chisel without shelling out (from the C-API) Need to be able to control the options This is potentially a wide and hard-to-maintain API Also want to do things like generate ARC dialect directly from Chisel/Scala (ie. things not part of firtool) Similarly would like to emit LTL dialect directly, going through intmodules is expensive in IR size We also need to make using firtool [lenharth] C-API has longer-term backwards compatibility compared to other APIs which move quickly Defaults on setting options sometimes live longer than the options themselves One motivation of going through intmodules is to force things through firrtl (well-defined) APIs rather than touching unstable internals Adding intmodules is easier development effort than adding C-APIs It’s not clear to me that we want to directly expose ARC, rather we should focus on FIRRTL to ARC pipelines Populate FIRRTL-to-ARC functionality (in CIRCT) rather than trying to generate ARC from Scala [jiuyang] We just want a way for the user to add this option from the C-API How do we expose pipeline configurations via the C-API? [lenharth] What is the use case for overriding the defaults? Specifically, what options do you want the user to be able to change? [schuyler] Most people do customize firtool options There is support for custom passes that you point firtool to, is this something you need to be doing from Scala? Another option is to use the Binder to construct FIRRTL that can then emit MLIR bytecode or .fir and then run firtool on the serialized form MLIR bytecode will parse a lot faster (.fir parsing takes some time) [jack] Biggest usability issue is that we make you install firtool Need to finish: https://github.com/jackkoenig/firtool-resolver [jiuyang] Some options to control firtool via Chisel are not great [schuyler] Some options are hard to expose so are wrapped in Chisel (eg. split-verilog) But we do just expose firtoolOpts to the user Sometimes this does break (causing closer relationship between Chisel and firtool versions) [lenharth] Current firtool options expose a lot of things that are basically internal development options that should not be exposed Ticket on CIRCT is to figure out what the actual useful options are [jack] The actual useful options are the only ones that should be exposed to Chisel [jiuyang] We still need the ability to create a pipeline to Verilog with the reasonable options (This involves generating TCL along with the generated Verilog) Generating SDC We are able to map the specific Data objects from the Chisel design to the emitted Verilog for generating our SDC [lenhath] CIRCT has a lot of the infrastructure to do this [jiuyang] We want to use it as simply as possible [lenharth] There is a language problem we need to fix that Chisel can’t express the information needed for SDC directly [lenharth] I have no objection to exposing setters on important options in C-API But we have to figure out what things need to be exposed [jiuyang] The work on this is part of why I don’t want to release binder flow yet, while we figure this stuff out Need a README/doc describing the main options (and hide the other options) [lenharth] Would be useful to move Arc to a library so it can be instantiated as a pipeline, etc. [schuyler] Do we want to be able to run firtool or Arc pipeline from C-API Increase options decoupling at the Chisel-level [jiuyang] We need to be able to replace memories with our own transform This involves a custom firtool transform [jiuyang] So what’s the path forward? [lenharth] Exposing more setters: https://github.com/llvm/circt/pull/6438 But let’s make sure to prune down what we’re exposing

As a conclusion, CIRCT needs to provide a comprehensive documentation for both firtool lib and command line option, Chisel and firtool binary should both design API base on it.