CIRCT

Circuit IR Compilers and Tools

'msft' Dialect

Microsoft internal support dialect Umbrella dialect for everything needed to support Microsoft development but not thoroughly discussed. Most (if not everything) in this dialect is a candidate for generalization and re-homing.

Operation definition 

msft.constructs.channel (::circt::msft::ChannelOp) 

A pipeline-able connection

Syntax:

operation ::= `msft.constructs.channel` $input $clk $sym_name `(` $defaultStages `)` attr-dict `:` type($input)

A logical, feed-forward connection between a producer and consumer. Can be pipelined with a number of stages (cycle delay) on a per-instance basis. defaultStages is used when stages isn’t specified by a DynamicInstance. Non-resettable, for now.

Per-instance specification is not yet supported, so the default pipelining is always used.

Traits: AlwaysSpeculatableImplTrait, HasParent

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), Symbol

Effects: MemoryEffects::Effect{}

Attributes: 

AttributeMLIR TypeDescription
sym_name::mlir::StringAttrstring attribute
defaultStages::mlir::IntegerAttr64-bit unsigned integer attribute

Operands: 

OperandDescription
inputany type
clk1-bit signless integer

Results: 

ResultDescription
outputany type

msft.physical_region (::circt::msft::DeclPhysicalRegionOp) 

Syntax:

operation ::= `msft.physical_region` $sym_name `,` $bounds attr-dict

Traits: HasParent mlir::ModuleOp

Interfaces: Symbol

Attributes: 

AttributeMLIR TypeDescription
sym_name::mlir::StringAttrstring attribute
bounds::mlir::ArrayAttrarray of PhysicalBounds

msft.partition (::circt::msft::DesignPartitionOp) 

A target “module” for moving entities

Syntax:

operation ::= `msft.partition` $sym_name `,` $verilogName attr-dict

Sometimes EDA tools require designs to have a module hierarchy which doesn’t match the logical structure a designer would like to have. “Design partitions” allow the designer to “tag” entities (instances, registers, etc.) with a target design partition. During lowering, CIRCT will modify the hierarchy to move the tagged entities into the design partition module. The target design partition can then be used by subsequent EDA tools.

Traits: HasParent msft::MSFTModuleOp

Interfaces: Symbol

Attributes: 

AttributeMLIR TypeDescription
sym_name::mlir::StringAttrstring attribute
verilogName::mlir::StringAttrstring attribute

msft.instance.dynamic (::circt::msft::DynamicInstanceOp) 

A module instance in the instance hierarchy

Syntax:

operation ::= `msft.instance.dynamic` custom<ImplicitInnerRef>($instanceRef) $body attr-dict

Represents an instance (as in instance in the instance hierarchy) referred to henceforth as a dynamic instance. Specified with a path through the instance hierarchy (which in the future will be replaced with an AppID). Lowers to a hw.globalref but unlike a global ref, does not require all of the ops participating in the globalref to contain a back pointer attribute. Allows users to efficiently add placements to a large number of dynamic instances which happen to map to a small number of static instances by bulk-adding the necessary hw.globalref attributes.

During the lowering, moves the operations in the body to the top level and gives them the symbol of the globalref which was created to replace the dynamic instance.

Traits: HasParent<circt::msft::InstanceHierarchyOp, circt::msft::DynamicInstanceOp>, NoTerminator

Attributes: 

AttributeMLIR TypeDescription
instanceRef::circt::hw::InnerRefAttrname reference attribute

msft.instance.verb_attr (::circt::msft::DynamicInstanceVerbatimAttrOp) 

Specify an arbitrary attribute attached to a dynamic instance

Syntax:

operation ::= `msft.instance.verb_attr` ($ref^)? `name` `:` $name `value` `:` $value (`path` `:` $subPath^)? attr-dict

Allows a user to specify a custom attribute name and value which is attached to a dynamic instance.

For Quartus tcl, translates to: set_instance_assignment -name $name $value -to $parent|<instance_path>

Interfaces: DynInstDataOpInterface

Attributes: 

AttributeMLIR TypeDescription
name::mlir::StringAttrstring attribute
value::mlir::StringAttrstring attribute
subPath::mlir::StringAttrstring attribute
ref::mlir::FlatSymbolRefAttrflat symbol reference attribute

msft.entity.extern (::circt::msft::EntityExternOp) 

Syntax:

operation ::= `msft.entity.extern` $sym_name $metadata attr-dict

Traits: HasParent mlir::ModuleOp

Interfaces: Symbol

Attributes: 

AttributeMLIR TypeDescription
sym_name::mlir::StringAttrstring attribute
metadata::mlir::Attributeany attribute

msft.instance.hierarchy (::circt::msft::InstanceHierarchyOp) 

The root of an instance hierarchy

Syntax:

operation ::= `msft.instance.hierarchy` $topModuleRef ($instName^)? $body attr-dict

Models the “root” / “top” of an instance hierarchy. DynamicInstanceOps must be contained by this op. Specifies the top module and (optionally) an “instance” name in the case where there are multiple instances of a particular module in a design. (As is often the case where one isn’t producing the design’s “top” module but a subdesign.)

Traits: HasParent mlir::ModuleOp, NoTerminator

Attributes: 

AttributeMLIR TypeDescription
topModuleRef::mlir::FlatSymbolRefAttrflat symbol reference attribute
instName::mlir::StringAttrstring attribute

msft.instance (::circt::msft::InstanceOp) 

Instantiate a module

Syntax:

operation ::= `msft.instance` $sym_name $moduleName `(` $inputs `)` custom<ParameterList>($parameters)
              attr-dict `:` functional-type($inputs, results)

Traits: HasParent

Interfaces: HWInstanceLike, OpAsmOpInterface, Symbol, SymbolUserOpInterface

Attributes: 

AttributeMLIR TypeDescription
sym_name::mlir::StringAttrstring attribute
moduleName::mlir::FlatSymbolRefAttrflat symbol reference attribute
parameters::mlir::ArrayAttrparameter array
targetDesignPartition::mlir::SymbolRefAttrsymbol reference attribute

Operands: 

OperandDescription
inputsany type

Results: 

ResultDescription
«unnamed»any type

msft.hlc.linear (::circt::msft::LinearOp) 

Model of a linear datapath which can be arbitrarily pipelined

Syntax:

operation ::= `msft.hlc.linear` `clock` $clock attr-dict `:` type($outs) $datapath

Defines a feed-forward datapath which can be scheduled into a pipeline. Due to the feed-forwardness, the inner region is NOT a graph region. Internally, only combinational operations (comb, msft, hw) are allowed.

Example:

msft.module @foo(%in0 : i32, %in1 : i32, %in2 : i32, %clk : i1) -> (out: i32) -> {
  %0 = msft.hlc.linear(%a = %in0, %b = %in1, %c = %in2) clock %clk (i32, i32, i32) -> (i32) {
    %0 = comb.mul %a, %b : i32
    %1 = comb.add %0, %c : i32
    msft.output %1 : i32
  }
}

Traits: SingleBlockImplicitTerminator

Operands: 

OperandDescription
clock1-bit signless integer

Results: 

ResultDescription
outsany type

msft.module.extern (::circt::msft::MSFTModuleExternOp) 

MSFT external Module

Identical to hw.module.extern, and trivially lowers to that. This op exists so that we can use msft.instance to refer to both msft.module and msft.module.extern, rather than mixing hw.instance with msft.instance.

Traits: HasParent mlir::ModuleOp

Interfaces: FunctionOpInterface, Symbol

Attributes: 

AttributeMLIR TypeDescription
argNames::mlir::ArrayAttrstring array attribute
resultNames::mlir::ArrayAttrstring array attribute
parameters::mlir::ArrayAttrparameter array
verilogName::mlir::StringAttrstring attribute

msft.module (::circt::msft::MSFTModuleOp) 

MSFT HW Module

A lot like hw.module, but with a few differences:

  • Can exist without a body. The body is filled in by a generator post op creation.
  • Provides methods for mutation.

Traits: HasParent mlir::ModuleOp, IsolatedFromAbove, SingleBlockImplicitTerminator

Interfaces: FunctionOpInterface, HWModuleLike, HWMutableModuleLike, OpAsmOpInterface, RegionKindInterface, Symbol

Attributes: 

AttributeMLIR TypeDescription
argNames::mlir::ArrayAttrstring array attribute
resultNames::mlir::ArrayAttrstring array attribute
parameters::mlir::DictionaryAttrdictionary of named attribute values
fileName::mlir::StringAttrstring attribute
childAppIDBases::mlir::ArrayAttrstring array attribute

msft.output (::circt::msft::OutputOp) 

termination operation

Syntax:

operation ::= `msft.output` attr-dict ($operands^ `:` qualified(type($operands)))?

Traits: AlwaysSpeculatableImplTrait, HasParent<MSFTModuleOp, LinearOp>, ReturnLike, Terminator

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands: 

OperandDescription
operandsany type

msft.pd.location (::circt::msft::PDPhysLocationOp) 

Specify a location for an instance

Syntax:

operation ::= `msft.pd.location` ($ref^)? custom<PhysLoc>($loc) (`path` `:` $subPath^)? attr-dict

Used to specify a specific location on an FPGA to place a dynamic instance. Supports specifying the location of a subpath for extern modules and device primitives. Intended to live as a child of instance.dynamic initially without the ref field. The dynamic instance lowering will fill in ref with the symol of the hw.globalref op corresponding to the lowered dynamic instance.

Interfaces: DynInstDataOpInterface

Attributes: 

AttributeMLIR TypeDescription
loc::circt::msft::PhysLocationAttrDescibes a physical location on a device
subPath::mlir::StringAttrstring attribute
ref::mlir::FlatSymbolRefAttrflat symbol reference attribute

msft.pd.physregion (::circt::msft::PDPhysRegionOp) 

Specify a physical region for an instance

Syntax:

operation ::= `msft.pd.physregion` ($ref^)? $physRegionRef (`path` `:` $subPath^)? attr-dict

Annotate a particular entity within an op with the region of the devices on an FPGA to which it should mapped. The physRegionRef must refer to a DeclPhysicalRegion operation.

Interfaces: DynInstDataOpInterface

Attributes: 

AttributeMLIR TypeDescription
physRegionRef::mlir::FlatSymbolRefAttrflat symbol reference attribute
subPath::mlir::StringAttrstring attribute
ref::mlir::FlatSymbolRefAttrflat symbol reference attribute

msft.pd.reg_location (::circt::msft::PDRegPhysLocationOp) 

Specify register locations

Syntax:

operation ::= `msft.pd.reg_location` (`ref` $ref^)? custom<ListOptionalRegLocList>($locs) attr-dict

A version of “PDPhysLocationOp” specialized for registers, which have one location per bit.

Interfaces: DynInstDataOpInterface

Attributes: 

AttributeMLIR TypeDescription
locs::circt::msft::LocationVectorAttrVector of optional locations corresponding to bits in a type
ref::mlir::FlatSymbolRefAttrflat symbol reference attribute

msft.pe.output (::circt::msft::PEOutputOp) 

Set the outputs from a PE block

Syntax:

operation ::= `msft.pe.output` $output attr-dict `:` type($output)

Traits: Terminator

Operands: 

OperandDescription
outputany type

msft.systolic.array (::circt::msft::SystolicArrayOp) 

Model of a row/column broadcast systolic array

Note: the PE region is NOT a graph region. This was intentional since systolic arrays are entirely feed-forward.

Traits: SingleBlockImplicitTerminator

Operands: 

OperandDescription
rowInputsan ArrayType
colInputsan ArrayType

Results: 

ResultDescription
peOutputsan array of arrays

Attribute definition 

AppIDAttr 

An application relevant instance identifier

Syntax:

!msft.appid<
  StringAttr,   # name
  uint64_t   # index
>

Identifies an instance which is visible through multiple hierarchy levels. Indended to make locating an instance easier in the instance hierarchy.

Parameters: 

ParameterC++ typeDescription
nameStringAttr
indexuint64_t

LocationVectorAttr 

Vector of optional locations corresponding to bits in a type

Parameters: 

ParameterC++ typeDescription
type::mlir::TypeAttr
locs::llvm::ArrayRef<::circt::msft::PhysLocationAttr>

PhysLocationAttr 

Descibes a physical location on a device

Annotate a particular entity within an op with the location of the device on an FPGA to which it should mapped. The coordinates in this attribute are absolute locations on the device, so if there are two instances of a module with this annotation incorrect results will be generated. How to solve this is a more general, open problem.

Parameters: 

ParameterC++ typeDescription
primitiveTypePrimitiveTypeAttr
xuint64_t
yuint64_t
numuint64_t

PhysicalBoundsAttr 

Describes a rectangle bounding a physical region on a device

Describes a rectangular bound within a device. The lower and upper bounds must be specified for both the X and Y axis. The bounds are inclusive.

Parameters: 

ParameterC++ typeDescription
xMinuint64_t
xMaxuint64_t
yMinuint64_t
yMaxuint64_t