Simulation Dialect

This dialect provides a high-level representation for simulator-specific operations. The purpose of the dialect is to provide a high-level representation for constructs which interact with simulators (Verilator, VCS, Arc, …) that are easy to analyze and transform in the compiler.

Rationale ¶

Plusargs ¶

The sim.plusarg_test and sim.plusarg_value operations are wrappers around the SystemVerilog built-ins which access command-line arguments. They are cleaner from a data-flow perspective, as they package the wires and if-statements involved into compact operations that can be trivially handled by analyses.

Types ¶

FormatStringType ¶

Format string type

Syntax: !sim.fstring

A format string type represents either a single formatting fragment or the concatenation of an arbitrary but finite number of fragments. A formatting fragment is either a static string literal or the association of a dynamic hardware value with a format specifier.

Operations ¶

sim.func.dpi.call (::circt::sim::DPICallOp) ¶

A call option for DPI function with an optional clock and enable

Syntax:

operation ::= `sim.func.dpi.call` $callee `(` $inputs `)` (`clock` $clock^)? (`enable` $enable^)?
              attr-dict `:` functional-type($inputs, results)

sim.func.dpi.call represents SystemVerilog DPI function call. There are two optional operands clock and enable.

If clock is not provided, the callee is invoked when input values are changed. If provided, the DPI function is called at clock’s posedge. The result values behave like registers and the DPI function is used as a state transfer function of them.

enable operand is used to conditionally call the DPI since DPI call could be quite more expensive than native constructs. When enable is low, results of unclocked calls are undefined and in SV results they are lowered into X. Users are expected to gate result values by another enable to model a default value of results.

For clocked calls, a low enable means that its register state transfer function is not called. Hence their values will not be modify in that clock.

Traits: AttrSizedOperandSegments

Interfaces: CallOpInterface, SymbolUserOpInterface

Attributes: ¶

Operands: ¶

Results: ¶

sim.func.dpi (::circt::sim::DPIFuncOp) ¶

A System Verilog function

sim.func.dpi models an external function in a core dialect.

Traits: IsolatedFromAbove

Interfaces: CallableOpInterface, FunctionOpInterface, OpAsmOpInterface, Symbol

Attributes: ¶

sim.fatal (::circt::sim::FatalOp) ¶

Simulation failure condition

Syntax:

operation ::= `sim.fatal` $clk `,` $cond attr-dict

Operands: ¶

sim.finish (::circt::sim::FinishOp) ¶

Simulation finish condition

Syntax:

operation ::= `sim.finish` $clk `,` $cond attr-dict

Operands: ¶

sim.fmt.bin (::circt::sim::FormatBinOp) ¶

Binary format specifier

Syntax:

operation ::= `sim.fmt.bin` $value attr-dict `:` qualified(type($value))

Format the given integer value as binary (base two) string.

The printed value will be left-padded with ‘0’ up to the number of bits of the argument’s type. Zero width values will produce the empty string. No further prefix will be added.

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

sim.fmt.char (::circt::sim::FormatCharOp) ¶

Character format specifier

Syntax:

operation ::= `sim.fmt.char` $value attr-dict `:` qualified(type($value))

Format the given integer value as a single character.

For integer values up to 127, ASCII compatible encoding is assumed. For larger values, the encoding is unspecified.

If the argument’s type width is less than eight bits, the value is zero extended. If the width is greater than eight bits, the resulting formatted string is undefined.

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

sim.fmt.dec (::circt::sim::FormatDecOp) ¶

Decimal format specifier

Syntax:

operation ::= `sim.fmt.dec` (`signed` $isSigned^)? $value attr-dict `:` qualified(type($value))

Format the given integer value as signed or unsigned decimal string.

Leading zeros are omitted. Non-negative or unsigned values will not be prefixed with a ‘+’.

For unsigned formatting, the printed value will be left-padded with spaces up to at least the length required to print the maximum unsigned value of the argument’s type. For signed formatting, the printed value will be left-padded with spaces up to at least the length required to print the minimum signed value of the argument’s type including the ‘-’ character. E.g., a zero value of type i1 requires no padding for unsigned formatting and one leading space for signed formatting. Format specifiers of same argument type and signedness must be padded to the same width. Zero width values will produce a single ‘0’.

Backends are recommended to not exceed the required amount of padding.

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Attributes: ¶

Operands: ¶

Results: ¶

sim.fmt.hex (::circt::sim::FormatHexOp) ¶

Hexadecimal format specifier

Syntax:

operation ::= `sim.fmt.hex` $value attr-dict `:` qualified(type($value))

Format the given integer value as lower-case hexadecimal string.

The printed value will be left-padded with ‘0’ up to the length required to print the maximum value of the argument’s type. Zero width values will produce the empty string. No further prefix will be added.

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

sim.fmt.lit (::circt::sim::FormatLitOp) ¶

Literal string fragment

Syntax:

operation ::= `sim.fmt.lit` $literal attr-dict

Creates a constant, raw ASCII string literal for formatted printing. The given string attribute will be outputted as is, including non-printable characters. The literal may be empty or contain null characters (’\0’) which must not be interpreted as string terminators by backends.

Traits: AlwaysSpeculatableImplTrait, ConstantLike

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Attributes: ¶

Results: ¶

sim.fmt.concat (::circt::sim::FormatStringConcatOp) ¶

Concatenate format strings

Syntax:

operation ::= `sim.fmt.concat` ` ` `(` $inputs `)` attr-dict

Concatenates an arbitrary number of format strings from left to right. If the argument list is empty, the empty string literal is produced.

Concatenations must not be recursive. I.e., a concatenated string should not contain itself directly or indirectly.

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

sim.plusargs.test (::circt::sim::PlusArgsTestOp) ¶

SystemVerilog $test$plusargs call

Syntax:

operation ::= `sim.plusargs.test` $formatString attr-dict

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Attributes: ¶

Results: ¶

sim.plusargs.value (::circt::sim::PlusArgsValueOp) ¶

SystemVerilog $value$plusargs call

Syntax:

operation ::= `sim.plusargs.value` $formatString attr-dict `:` type($result)

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Attributes: ¶

Results: ¶

sim.print (::circt::sim::PrintFormattedOp) ¶

Print a formatted string on a given clock and condition

Syntax:

operation ::= `sim.print` $input `on` $clock `if` $condition attr-dict

Evaluate a format string and print it to the simulation console on the rising edge of the given clock, if, and only if, the condition argument is ’true’.

Multiple print operations in the same module and on the same clock edge are performed according to their order of occurence in the IR. The order of printing for operations in different modules, instances or on different clocks is undefined.

Operands: ¶

sim.proc.print (::circt::sim::PrintFormattedProcOp) ¶

Print a formatted string within a procedural region

Syntax:

operation ::= `sim.proc.print` $input attr-dict

Evaluate a format string and print it to the simulation console.

This operation must be within a procedural region.

Operands: ¶