[RFC] Adding ConnectionGraph altering and irEmiting APIs

Type of issue: feature request

What is the use case for changing the behavior?

Impact: API addition (no impact on existing code)

Development Phase: proposal

I’m using this CircuitGraph from this branch to write my own Transform.(cherry pick from this branch.) It’s really convenience to trace the sink and source of the register. However, I found there might still need some APIs to modify the graph(not just analysis). Currently I need to pass Statement to ConnectionGraph.asTarget(if we can provide a targetLookup like irLookup might be more convenient) maping Statement to Target in the CircuitGraph. After this, I use some methods of CircuitGraph to trace the sinks and sources, analyze them and finally use irLookup to map Target to FirrtlNode, constructing a new FirrtlNode by hand. I think it might cost a lot to find each Statement in Circuit again and again. I wonder if it is possible for us to provide a set of APIs to alter CircuitGraph directly? I only find API mapping Circuit to ConnectionGraph

def buildCircuitGraph(circuit: Circuit): ConnectionGraph

while not exist

def buildCircuit(circuit: ConnectionGraph): Circuit

and we might also need some new ideas to provide a higher API to operate ConnectionGraph. This can provide a new way for Transform, like altIR tried, I think this can provide a higher abstraction level than DiGraph, to make Transform, which need connection analysis(like ConstantPropogation), more simple and elegance.

[seldridge]

I’m still concerned about shifting the ground truth from the IR to some other data structure. I get nervous about adding additional converters to and from the IR. I tend to view this activity as equivalent to writing a new backend and frontend.

It’s a lot simpler to assume we have one ground truth, the IR, and then “analyses” that produce data structures derived from the IR. The user then uses @azidar’s approach of:

1. Perform the analysis
2. Build up data structures necessary to apply modifications
3. Apply all modifications

The problem with this approach is that it’s low-level. A transform writer has to deal with manipulating the IR.

One way to help with this, and as an alternative way of viewing what this RFC is asking for, would be to build out a type hierarchy under Transform of classes that expose higher-level APIs for transform writers. These may require analyses passes to be run earlier (which the dependency API allows us to codify). E.g., a certain transform may provide APIs for manipulating the IR that require CircuitGraph information. These APIs are really manipulating the IR, but they provide a more targeted functionality for transform writers (and potentially less bugs in transforms).

LLVM does something like this with it’s different types of passes, e.g., ones for manipulating basic blocks or functions only. Note: LLVM’s aim here, I believe, is more to have passes expose what they’re doing so that it can group and chain passes together. For passes manipulating functions, the optimizations can’t cross a function boundary, so you can take two function passes, make a larger pass, and then apply the optimizations of the first and the second to each function serially.

In summary:

• How can we make transform writing easier?
• What APIs can we expose to users and what analyses do they require?
• Can we do this without introducing another IR?

[sequencer]

closed since #1603 merged.