'seq' Dialect

Types and operations for seq dialect

The seq dialect is intended to model digital sequential logic.

Operations

seq.clock_div (::circt::seq::ClockDividerOp)

Produces a clock divided by a power of two

Syntax:

operation ::= `seq.clock_div` $input `by` $pow2 attr-dict

The output clock is phase-aligned to the input clock.

%div_clock = seq.clock_div %clock by 1

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Attributes:

Operands:

Results:

seq.clock_gate (::circt::seq::ClockGateOp)

Safely gates a clock with an enable signal

Syntax:

operation ::= `seq.clock_gate` $input `,` $enable (`,` $test_enable^)? (`sym` $inner_sym^)? attr-dict

The seq.clock_gate enables and disables a clock safely, without glitches, based on a boolean enable value. If the enable operand is 1, the output clock produced by the clock gate is identical to the input clock. If the enable operand is 0, the output clock is a constant zero.

The enable operand is sampled at the rising edge of the input clock; any changes on the enable before or after that edge are ignored and do not affect the output clock.

The test_enable operand is optional and if present is OR’d together with the enable operand to determine whether the output clock is gated or not.

The op can be referred to using an inner symbol. Upon translation, the symbol will target the instance to the external module it lowers to.

%gatedClock = seq.clock_gate %clock, %enable
%gatedClock = seq.clock_gate %clock, %enable, %test_enable

Traits: AlwaysSpeculatableImplTrait

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

Effects: MemoryEffects::Effect{}

Attributes:

Operands:

Results:

seq.clock_inv (::circt::seq::ClockInverterOp)

Inverts the clock signal

Syntax:

operation ::= `seq.clock_inv` $input attr-dict

Note that the compiler can optimize inverters away, preventing their use as part of explicit clock buffers.

%inv_clock = seq.clock_inv %clock

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands:

Results:

seq.clock_mux (::circt::seq::ClockMuxOp)

Safely selects a clock based on a condition

Syntax:

operation ::= `seq.clock_mux` $cond `,` $trueClock `,` $falseClock attr-dict

The seq.clock_mux op selects a clock from two options. If cond is true, the first clock operand is selected to drive downstream logic. Otherwise, the second clock is used.

%clock = seq.clock_mux %cond, %trueClock, %falseClock

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands:

Results:

seq.compreg (::circt::seq::CompRegOp)

Register a value, storing it for one cycle

Syntax:

operation ::= `seq.compreg` (`sym` $inner_sym^)? `` custom<ImplicitSSAName>($name) $input `,` $clk
              (`reset` $reset^ `,` $resetValue)?
              (`initial` $initialValue^)? attr-dict `:` type($data)
              custom<OptionalTypeMatch>(ref(type($data)), ref($resetValue), type($resetValue))
              custom<OptionalImmutableTypeMatch>(ref(type($data)), ref($initialValue), type($initialValue))

See the Seq dialect rationale for a longer description

Traits: AlwaysSpeculatableImplTrait, AttrSizedOperandSegments

Interfaces: Clocked, ConditionallySpeculatable, InferTypeOpInterface, InnerSymbolOpInterface, NoMemoryEffect (MemoryEffectOpInterface), OpAsmOpInterface, Resettable

Effects: MemoryEffects::Effect{}

Attributes:

Operands:

Results:

seq.compreg.ce (::circt::seq::CompRegClockEnabledOp)

When enabled, register a value

Syntax:

operation ::= `seq.compreg.ce` (`sym` $inner_sym^)? `` custom<ImplicitSSAName>($name) $input `,` $clk `,` $clockEnable
              (`reset` $reset^ `,` $resetValue)?
              (`initial` $initialValue^)? attr-dict `:` type($data)
              custom<OptionalTypeMatch>(ref(type($data)), ref($resetValue), type($resetValue))
              custom<OptionalImmutableTypeMatch>(ref(type($data)), ref($initialValue), type($initialValue))

See the Seq dialect rationale for a longer description

Traits: AlwaysSpeculatableImplTrait, AttrSizedOperandSegments

Interfaces: Clocked, ConditionallySpeculatable, InferTypeOpInterface, InnerSymbolOpInterface, NoMemoryEffect (MemoryEffectOpInterface), OpAsmOpInterface, Resettable

Effects: MemoryEffects::Effect{}

Attributes:

Operands:

Results:

seq.const_clock (::circt::seq::ConstClockOp)

Produce constant clock value

Syntax:

operation ::= `seq.const_clock` $value attr-dict

The constant operation produces a constant clock value.

  %clock = seq.const_clock low

Traits: AlwaysSpeculatableImplTrait, ConstantLike

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Attributes:

Results:

seq.fifo (::circt::seq::FIFOOp)

A high-level FIFO operation

Syntax:

operation ::= `seq.fifo` `depth` $depth
              (`rd_latency` $rdLatency^)?
              custom<FIFOAFThreshold>($almostFullThreshold, type($almostFull))
              custom<FIFOAEThreshold>($almostEmptyThreshold, type($almostEmpty))
              `in` $input `rdEn` $rdEn `wrEn` $wrEn `clk` $clk `rst` $rst attr-dict `:` type($input)

This operation represents a high-level abstraction of a FIFO. Access to the FIFO is structural, and thus may be composed with other core RTL dialect operations. The fifo operation is configurable with the following parameters:

1. Depth (cycles)
2. Read latency (cycles) is the number of cycles it takes for a read to return data after the read enable signal is asserted.
3. Almost full/empty thresholds (optional). If not provided, these will be asserted when the FIFO is full/empty.

Like seq.hlmem there are no guarantees that all possible fifo configuration are able to be lowered. Available lowering passes will pattern match on the requested fifo configuration and attempt to provide a legal lowering.

Traits: AttrSizedResultSegments

Interfaces: OpAsmOpInterface

Attributes:

Operands:

Results:

seq.firmem (::circt::seq::FirMemOp)

A FIRRTL-flavored memory

Syntax:

operation ::= `seq.firmem` (`sym` $inner_sym^)? `` custom<ImplicitSSAName>($name)
              $readLatency `,` $writeLatency `,` $ruw `,` $wuw
              attr-dict `:` type($memory)

The seq.firmem op represents memories lowered from the FIRRTL dialect. It is used to capture some of the peculiarities of what FIRRTL expects from memories, while still representing them at the HW dialect level.

A seq.firmem declares the memory and captures the memory-level parameters such as width and depth or how read/write collisions are resolved. The read, write, and read-write ports are expressed as separate operations that take the declared memory as an operand.

Interfaces: InnerSymbolOpInterface, MemoryEffectOpInterface (MemoryEffectOpInterface), OpAsmOpInterface

Effects: MemoryEffects::Effect{MemoryEffects::Allocate on ::mlir::SideEffects::DefaultResource}

Attributes:

Results:

seq.firmem.read_port (::circt::seq::FirMemReadOp)

A memory read port

Syntax:

operation ::= `seq.firmem.read_port` $memory `[` $address `]` `,` `clock` $clk
              (`enable` $enable^)?
              attr-dict `:` type($memory)

The seq.firmem.read_port op represents a read port on a seq.firmem memory. It takes the memory as an operand, together with the address to be read, the clock on which the read is synchronized, and an optional enable. Omitting the enable operand has the same effect as passing a constant true to it.

Interfaces: Clocked, InferTypeOpInterface, MemoryEffectOpInterface (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{MemoryEffects::Read on ::mlir::SideEffects::DefaultResource}

Operands:

Results:

seq.firmem.read_write_port (::circt::seq::FirMemReadWriteOp)

A memory read-write port

Syntax:

operation ::= `seq.firmem.read_write_port` $memory `[` $address `]` `=` $writeData `if` $mode `,` `clock` $clk
              (`enable` $enable^)? (`mask` $mask^)?
              attr-dict `:` type($memory) (`,` type($mask)^)?

The seq.firmem.read_write_port op represents a read-write port on a seq.firmem memory. It takes the memory as an operand, together with the address and data to be written, a mode operand indicating whether the port should perform a read (mode=0) or a write (mode=1), the clock on which the read and write is synchronized, an optional enable, and and optional write mask. Omitting the enable operand has the same effect as passing a constant true to it. Omitting the write mask operand has the same effect as passing an all-ones value to it. A write mask operand can only be present if the seq.firmem specifies a mask width; otherwise it must be omitted.

Traits: AttrSizedOperandSegments

Interfaces: Clocked, InferTypeOpInterface, MemoryEffectOpInterface (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{MemoryEffects::Read on ::mlir::SideEffects::DefaultResource, MemoryEffects::Write on ::mlir::SideEffects::DefaultResource}

Operands:

Results:

seq.firmem.write_port (::circt::seq::FirMemWriteOp)

A memory write port

Syntax:

operation ::= `seq.firmem.write_port` $memory `[` $address `]` `=` $data `,` `clock` $clk
              (`enable` $enable^)? (`mask` $mask^)?
              attr-dict `:` type($memory) (`,` type($mask)^)?

The seq.firmem.write_port op represents a write port on a seq.firmem memory. It takes the memory as an operand, together with the address and data to be written, the clock on which the write is synchronized, an optional enable, and and optional write mask. Omitting the enable operand has the same effect as passing a constant true to it. Omitting the write mask operand has the same effect as passing an all-ones value to it. A write mask operand can only be present if the seq.firmem specifies a mask width; otherwise it must be omitted.

Traits: AttrSizedOperandSegments

Interfaces: Clocked, MemoryEffectOpInterface (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{MemoryEffects::Write on ::mlir::SideEffects::DefaultResource}

Operands:

seq.firreg (::circt::seq::FirRegOp)

Register with preset and sync or async reset

firreg represents registers originating from FIRRTL after the lowering of the IR to HW. The register is used as an intermediary in the process of lowering to SystemVerilog to facilitate optimisation at the HW level, compactly representing a register with a single operation instead of composing it from register definitions, always blocks and if statements.

The data output of the register accesses the value it stores. On the rising edge of the clk input, the register takes a new value provided by the next signal. Optionally, the register can also be provided with a synchronous or an asynchronous reset signal and resetValue, as shown in the example below.

%name = seq.firreg %next clock %clk [ sym @sym ]
    [ reset (sync|async) %reset, %value ]
    [ preset value ] : type

Implicitly, all registers are pre-set to a randomized value.

A register implementing a counter starting at 0 from reset can be defined as follows:

%zero = hw.constant 0 : i32
%reg = seq.firreg %next clock %clk reset sync %reset, %zero : i32
%one = hw.constant 1 : i32
%next = comb.add %reg, %one : i32

Traits: AlwaysSpeculatableImplTrait, SameVariadicOperandSize

Interfaces: Clocked, ConditionallySpeculatable, InferTypeOpInterface, InnerSymbolOpInterface, MemoryEffectOpInterface (MemoryEffectOpInterface), NoMemoryEffect (MemoryEffectOpInterface), OpAsmOpInterface, Resettable

Effects: MemoryEffects::Effect{MemoryEffects::Write on ::mlir::SideEffects::DefaultResource, MemoryEffects::Read on ::mlir::SideEffects::DefaultResource, MemoryEffects::Allocate on ::mlir::SideEffects::DefaultResource}, MemoryEffects::Effect{}

Attributes:

Operands:

Results:

seq.from_clock (::circt::seq::FromClockOp)

Cast from a clock type to a wire type

Syntax:

operation ::= `seq.from_clock` $input attr-dict

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands:

Results:

seq.from_immutable (::circt::seq::FromImmutableOp)

Cast from an immutable type to a wire type

Syntax:

operation ::= `seq.from_immutable` $input attr-dict `:` functional-type(operands, results)

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands:

Results:

seq.hlmem (::circt::seq::HLMemOp)

Instantiate a high-level memory.

Syntax:

operation ::= `seq.hlmem` $name $clk `,` $rst attr-dict `:` type($handle)

See the Seq dialect rationale for a longer description

Interfaces: Clocked, OpAsmOpInterface

Attributes:

Operands:

Results:

seq.initial (::circt::seq::InitialOp)

Operation that produces values for initialization

Syntax:

operation ::= `seq.initial` `(` $inputs `)` $body attr-dict `:` functional-type($inputs, results)

seq.initial op creates values wrapped types with !seq.immutable. See the Seq dialect rationale for a longer description.

Traits: IsolatedFromAbove, RecursiveMemoryEffects, RecursivelySpeculatableImplTrait, SingleBlockImplicitTerminator<YieldOp>, SingleBlock

Interfaces: ConditionallySpeculatable

Operands:

Results:

seq.read (::circt::seq::ReadPortOp)

Structural read access to a seq.hlmem, with an optional read enable signal.

Traits: AttrSizedOperandSegments

Interfaces: OpAsmOpInterface

Attributes:

Operands:

Results:

seq.shiftreg (::circt::seq::ShiftRegOp)

Shift register

Syntax:

operation ::= `seq.shiftreg` `[` $numElements `]`
              (`sym` $inner_sym^)? `` custom<ImplicitSSAName>($name) $input `,` $clk `,` $clockEnable
              (`reset` $reset^ `,` $resetValue)?
              (`powerOn` $powerOnValue^)? attr-dict `:` type($data)
              custom<OptionalTypeMatch>(ref(type($data)), ref($resetValue), type($resetValue))
              custom<OptionalTypeMatch>(ref(type($data)), ref($powerOnValue), type($powerOnValue))

The seq.shiftreg op represents a shift register. It takes the input value and shifts it every cycle when clockEnable is asserted. The reset and resetValue operands are optional and if present, every entry in the shift register will be initialized to resetValue upon assertion of the reset signal. Exact reset behavior (sync/async) is implementation defined.

Traits: AlwaysSpeculatableImplTrait, AttrSizedOperandSegments

Interfaces: Clocked, ConditionallySpeculatable, InferTypeOpInterface, InnerSymbolOpInterface, NoMemoryEffect (MemoryEffectOpInterface), OpAsmOpInterface, Resettable

Effects: MemoryEffects::Effect{}

Attributes:

Operands:

Results:

seq.to_clock (::circt::seq::ToClockOp)

Cast from a wire type to a clock type

Syntax:

operation ::= `seq.to_clock` $input attr-dict

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands:

Results:

seq.write (::circt::seq::WritePortOp)

Structural write access to a seq.hlmem

Attributes:

Operands:

seq.yield (::circt::seq::YieldOp)

Yield values

Syntax:

operation ::= `seq.yield` attr-dict ($operands^ `:` type($operands))?

Traits: AlwaysSpeculatableImplTrait, HasParent<InitialOp>, Terminator

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands:

Attributes

ClockConstAttr

clock constant

Syntax:

#seq.clock_constant<
  circt::seq::ClockConst   # value
>

Enum cases:

• low (Low)
• high (High)

Parameters:

FirMemInitAttr

Memory initialization information

Syntax:

#seq.firmem.init<
  mlir::StringAttr,   # filename
  bool,   # isBinary
  bool   # isInline
>

This attribute captures what the initial contents of a memory should be. At the moment this is modeled primarily with simulation in mind, where the memory contents are pre-loaded from a file at simulation startup.

The filename specifies a file on disk that contains the initial contents for this memory. If isBinary is set, the file is interpreted as a binary file, otherwise it is treated as hexadecimal. This is modeled after the $readmemh and $readmemb SystemVerilog functions. If isInline is set, the initialization is emitted directly in the memory model; otherwise it is split out into a separate module that can be bound in.

Parameters:

Type constraints

an ImmutableType

Types

ClockType

A type for clock-carrying wires

Syntax: !seq.clock

The !seq.clock type represents signals which can be used to drive the clock input of sequential operations.

FirMemType

A FIRRTL-flavored memory

Syntax:

!seq.firmem<
  uint64_t,   # depth
  uint32_t,   # width
  std::optional<uint32_t>   # maskWidth
>

The !seq.firmem type represents a FIRRTL-flavored memory declared by a seq.firmem operation. It captures the parameters of the memory that are relevant to the read, write, and read-write ports, such as width and depth.

Parameters:

HLMemType

Multi-dimensional memory type

Syntax:

hlmem-type ::== `hlmem` `<` dim-list element-type `>`

The HLMemType represents the type of an addressable memory structure. The type is inherently multidimensional. Dimensions must be known integer values.

Note: unidimensional memories are represented as <1x{element type}> - <{element type}> is illegal.

Parameters:

ImmutableType

Value type that is immutable after initialization

Syntax:

!seq.immutable<
  ::mlir::Type   # innerType
>

Parameters:

Enums

ClockConst

clock constant

Cases:

RUW

Read-Under-Write Behavior

Cases:

WUW

Write-Under-Write Behavior

Cases:

'seq' Dialect Docs

• Seq(uential) Dialect Rationale