Initial pass at documenting primitives

[leonardt]

@phanrahan @rdaly525 here is the initial pass at documenting the mantle primitives.

I started with documenting the interface to the generators, organized by modules. In mantle we have

• arith
• logic
• compare
• mux
• FF
• LUT
• Memory

The major issues I found are:

• Inconsistent parameter names across mantle implementations (e.g. n vs width)
• cin, cout parameters in mantle versus coreir add/sub primitives (no cin/cout)
• height, width parameters in mantle logic primitives versus coreir logic primitives which are binary
• Some missing Define+Instance variants in mantle40 (e.g. DefineUGT but no UGT). The fix for this is simple, once we have consistent interfaces across implementations, they should be able to reuse the same Define+Instance variants.
• FF primitives have way more parameters than coreir (has_ce, has_reset, ...).

It seems like most of the consistency issues between mantle primitives and coreir primitives can be resolved by defining simpler mantle primitives (e.g. a basic FF that matches the coreir primitive, a basic add/sub that matches the coreir primitives). Then, the richer generator interfaces can be implemented in terms of these primitives.

I'm not sure what's the best way to organize this. For example, we could have Add match the coreir primitive interface, and then define an AddC which extends it with carry logic. Similarly for flipflops.

A complex issue is the logic primitives, which currently define height and width parameters. We could define a binary Or to match coreir, but how do we name a more general Or? We could invert the solution, and have explicit primitive circuits, e.g. OrPrim, then preserve the current semantics of Or. A final option is to have coreir introduce a height parameter.

@rdaly525 can you review the list of generators and see if there's anything missing in mantle that coreir supports?

@phanrahan can you review the list of generators and see if there's anything that is missing or should be in common. Also, what do you think about the proposed resolution of defining the basic primitives that match coreir, and building the higher level constructs out of the primitives? Seems like a clean design. Major issue here is how to design/organize the logic primitives with the height and width parameters (reconciling them with the binary coreir primitives).

[phanrahan]

This seems like a good analysis. Thanks for organizing all this material.

I suggest as a first pass we allow mantle primitives with optional keyword arguments. That would handle the extra arguments like in the Add and FF case. We should make the required arguments the same.

[leonardt]

I like that idea. So the subset of parameters that match the coreir primitives should exhibit the same behavior. Then, they can provide any other parameters, which, in the case of the coreir mantle implementation, may generate a wrapper circuit around the corresponding primitive to handle extra logic.

@rdaly525 can you envision any issues with this scheme w.r.t linking? In particular, if someone wants to use the mantle primitives for synthesis, I think it should be sufficient if the generators implement the subset matching the coreir primitives interfaces.

[rdaly525]

To understand more explicitly, you are suggesting:

Add(width,has_cin=False,has_cout=False) will directly use the coreir primitive, whereas any other combination of has_cin, and has_cout will need to be generated in terms of Add(width,has_cin=False,has_cout=False)?

If this is the case, then yeah it should be easy. If this is not the case and you want to specialize (synthesize the Add(width,has_cin=True) directly to LUTs), then this is a little bit tricker, especially with our formal verification goals. It seems like we would want to define a CoreIR extension primitive that exactly matches the parameters of the mantle add generator.

[rdaly525]

At a glance I do not see anything missing here that CoreIR supports. Ill do a more thorough review on Thursday.

Biggest mismatches:
-CoreIR does not have LUTs as coreir primtives. These are viewed as technology-specific primitives.
-FFs. CoreIR has only two primitives (Reg, and Reg with async reset). Both of these do have initialization parameters along with clock/reset polarity parameters. I again see all specific types of FFs as technology-specific primitives.
-Memories: We should discuss this in person.
-height and width for logic primitives. @phanrahan, what is the reason for having a height parameter? It seems like a pretty obscure use case to ever have height larger than 2 if width is greater than 1 (for And/Nand/Or/Nor). Maybe I am not thinking of something.

[phanrahan]

Perhaps we should add an FPGA extension that includes LUT? How do you program LUTs on the CGRA?

The main reason I added height was that the synthesis algorithms are much more efficient if they are aware of height. Thus, it makes a good low-level primitive. Same with Muxes. I am happy to add this as an extension and not as a standard operator.

[rdaly525]

Muxes make the most sense to have a height in my opinion. Although we could further discuss mux primitives as we may want to describe different mux schemes (priority, one-hot, etc...)

I have a CGRA-specific primitive I call a LUT and I map all coreir boolean logic to these LUTs. That being said a generic LUT possibly makes sense since all FPGA backends would use it.

[leonardt]

It looks like progress stalled on this effort, we should schedule a meeting when we get a chance to sync back up on the goal of unifying the mantle/coreir primitive interfaces