FIRRTL dialect rationale doc

Incubator CIRCT
1

I’m planning to make some changes to the FIRRTL dialect to make it more MLIR native (e.g. having firrtl.instance utilize multiple results). When doing so, we will diverge from the FIRRTL spec. As such, I thought it would be useful to add a rationale doc describing our design choices.

I’d appreciate any thoughts, feedback, additions, corrections. I’ll aim to keep it up to date as the implementation shifts.

-Chris

2

Awesome!

The type canonicalization I had to grok from reading the code. This document helps a lot. (And I’m volunteering to update this!)

Two additions:

  1. I think there’s one additional canonicalization rule for bundles: flips are pulled out of bundles when all bundle elements are flipped and the elements are passive under the element flips. This appeared to be implemented because flips are tentatively removed if all elements are flipped and then canonicalized by the addition of the outer flip.

  2. It should be mentioned that the FIRRTL spec defines type equivalence as requiring flips to match. If types are equivalent after canonicalization, MLIR will accept this while the FIRRTL Spec will not.

As an example of (2), the following will canonicalize a to an input, but the Scala FIRRTL Compiler (SFC) will reject this due to a type mismatch between a and b.

circuit Foo:
  module Foo:
    output a: { flip a: UInt<1> }
    output b: { a: UInt<1> }

    b <= a

The type discussion can also be generalized even further. The FIRRTL spec defines flippedness as a property of a bundle field as opposed to a property of a type. This was probably a mistake. Limiting flippedness to fields has the following implications:

  1. direction (input and output) become necessary to specify flippedness of ports
  2. flows and kinds become necessary to determine the validity of a connection

The SFC treates connectability as a function of type, kind, and flow—roughly the “the types match” and “the flows are opposite or the flows are the same if the kind is a port or instance”.

Canonicalized types in MLIR aims to coalesce all the information in the FIRRTL Spec’s type, kind, orientation, and flow.

3

Ah, great point! I added the missing canonicalization in this patch: c8c78ca. Would you mind adding a new section talking about type equivalence? You know the rules here much better than I do, thank you!

I agree that the SFC rules are a bit confused here and probably not the best formulation of the directionality properties that they’re seeking. In practice, the SFC seems to support some dubious things.

4

I’ve added some language around these points in 1a71cf0.

5

Awesome, thank you @seldridge !!