Documentation on Analyzing Circuits with Python Bindings

[tymcauley]

Following up from a discussion in today's Dev Meeting (cc @mikeurbach).

I'm trying to do some analysis of circuits (starting from Chisel in my case), and am having trouble getting started with the CIRCT Python Bindings. One use-case I have in mind is finding all of the modules (as well as the output files) associated with a Public module. Once I have an instance graph of my circuit, I'm hoping that this would be reasonably straightforward.

There's currently a docs/PythonBindings.md file with some getting-started information for the Python Bindings, but after reading it, I'm left with a few questions:

• What dialect should I use to do this analysis? firtool has the --output-final-mlir=<filename> option for creating another .mlir output file in addition to the -o output (SystemVerilog in my case). Should I be using that? Or should I be invoking firtool once to generate SystemVerilog, and another time to emit HW dialect (--ir-hw)?
• Once I have one of these .mlir files, what entry point should I use in the Python Bindings to parse those files? Is something like this the right direction?

import circt
from circt.ir import Context, Module


if __name__ == "__main__":
    ctx = Context()
    circt.register_dialects(ctx)
    with open("path/to/my/circuit.mlir") as f:
        module = Module.parse(f.read(), ctx)
    # ...

• Once I have a Module loaded, what are some of the primitives that I should use to walk the Module's operations?

I really appreciate any help with getting started on all of this! If someone points me in the right direction with answering these questions, I'm happy to contribute additions to the docs.

[mikeurbach]

I will get back with some quick answers below. I think these questions could be best answered by a few new documents, probably in tutorial form. I can take a crack at these.

• How to load and visit MLIR, tuned for CIRCT dialects
• How to use the visitor pattern to build up an instance graph
• How to use the visitor pattern to trace fanout

We should also just add some standard IR traversal helpers here in CIRCT as well for doing such things. We have a couple base visitors in a downstream repo, and they're useful. We have also started exploring an opinionated data model on top of the basic helpers... but honestly it is not the most useful yet.

A few quick tips:

What dialect should I use to do this analysis? firtool has the --output-final-mlir= option for creating another .mlir output file in addition to the -o output (SystemVerilog in my case). Should I be using that?

This is a good question, and yes, I use --output-final-mlir. It was designed for this. The analyses we have done based on MLIR need to know they are working with the final verilog names, and unfortunately the CIRCT pipeline can't currently guarantee that until verilog is exported.

@uenoku is actually adding a new --output-hw-mlir to firtool, which could be interesting as well: #8169. If you don't need guarantees about the final verilog names, this will allow you to perform your analyses on CIRCT "core" IRs--the ones designed to be good for analysis and transformation. The SV IRs is very much catered to emission. It can be analyzed, but it is tedious.

Once I have one of these .mlir files, what entry point should I use in the Python Bindings to parse those files? Is something like this the right direction?

Yep that's exactly right.

Once I have a Module loaded, what are some of the primitives that I should use to walk the Module's operations?

I would check out this whole page, but specifically this is where I'd look: https://mlir.llvm.org/docs/Bindings/Python/#inspecting-ir-objects. This is akin to the original C++ MLIR tutorial here: https://mlir.llvm.org/docs/Tutorials/UnderstandingTheIRStructure/.

You can iterate through the body of the builtin.ModuleOp, and you will find hw.HWModuleOps, etc., and can iterate through their bodies, inspect their attributes, etc.