Skip to content

'util' Dialectlink

A dialect used for types common across IREE subdialects.

Operationslink

Address/offset arithmetic opslink

util.align (Util::AlignOp)link

Aligns up to a power-of-two alignment if required

Syntax:

operation ::= `util.align` $value `,` $alignment attr-dict `:` type($result)

Aligns |value| up to the given power-of-two |alignment| if required.

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands:link
Operand Description
value signless-integer-like
alignment signless-integer-like
Results:link
Result Description
result signless-integer-like

util.sizeof (Util::SizeOfOp)link

Returns the size in bytes of a datatype

Syntax:

operation ::= `util.sizeof` $sizedType attr-dict-with-keyword

Most datatypes have a static size at all layers of the compilation stack. However, those that only have a size for certain lowering flows can be challenging. This op represents such sizes in a way that can be specialized later.

Returns the size in bytes, rounded up to the next whole byte of the specified type. This op will fold to a constant index value for IntegerType and FloatType. All others are not folded.

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Attributes:link
AttributeMLIR TypeDescription
sizedType::mlir::TypeAttrany type attribute
Results:link
Result Description
size index

Buffer opslink

util.buffer.alloc (Util::BufferAllocOp)link

Allocates a buffer with undefined contents

Syntax:

operation ::= `util.buffer.alloc` `uninitialized`
              attr-dict
              `:`
              type($result) `` `{` $storage_size `}`

Allocates a buffer with undefined contents. Consumers of the allocated result must assume nothing of the contents.

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, MemoryEffectOpInterface (MemoryEffectOpInterface), NoMemoryEffect (MemoryEffectOpInterface), OpAsmOpInterface, Util_SizeAwareOp

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

Attributes:link
AttributeMLIR TypeDescription
alignment::mlir::IntegerAttrindex attribute
Operands:link
Operand Description
storage_size index
Results:link
Result Description
result a reference counted byte buffer

util.buffer.compare (Util::BufferCompareOp)link

Compares a range of two buffers

Syntax:

operation ::= `util.buffer.compare` $lhs `[` $lhs_offset `]` `,`
              $rhs `[` $rhs_offset `]` `,`
              $length `:`
              type($lhs) `` `{` $lhs_size `}` `,`
              type($rhs) `` `{` $rhs_size `}`
              attr-dict-with-keyword

Returns true if the two ranges are bitwise equivalent, somewhat like memcmp.

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, MemoryEffectOpInterface (MemoryEffectOpInterface), NoMemoryEffect (MemoryEffectOpInterface), SubrangeOperandOpInterface, Util_SizeAwareOp

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

Operands:link
Operand Description
lhs a reference counted byte buffer
lhs_size index
lhs_offset index
rhs a reference counted byte buffer
rhs_size index
rhs_offset index
length index
Results:link
Result Description
result 1-bit signless integer

util.buffer.constant (Util::BufferConstantOp)link

Constant host-side byte buffer

Syntax:

operation ::= `util.buffer.constant` ($name^)? attr-dict `:` type($result) `=` $value

Defines a compile-time byte buffer based on the given attribute value. The attribute will be serialized into the canonical IREE format for the chosen host target.

Traits: AlwaysSpeculatableImplTrait

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

Effects: MemoryEffects::Effect{}

Attributes:link
AttributeMLIR TypeDescription
name::mlir::StringAttrstring attribute
value::mlir::Attributebuffer-like constant attribute values
alignment::mlir::IntegerAttrindex attribute
mime_type::mlir::StringAttrstring attribute
Results:link
Result Description
result a reference counted byte buffer

util.buffer.copy (Util::BufferCopyOp)link

Copies a range of bytes between buffers

Syntax:

operation ::= `util.buffer.copy` $source `[` $source_offset `]` `,`
              $target `[` $target_offset `]` `,`
              $length `:`
              type($source) `` `{` $source_size `}` `->`
              type($target) `` `{` $target_size `}`
              attr-dict-with-keyword

Copies a range of bytes as with memcpy (no overlapping).

Interfaces: MemoryEffectOpInterface (MemoryEffectOpInterface), SubrangeOperandOpInterface, Util_SizeAwareOp

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

Operands:link
Operand Description
source a reference counted byte buffer
source_size index
source_offset index
target a reference counted byte buffer
target_size index
target_offset index
length index

util.buffer.dealloc (Util::BufferDeallocOp)link

Deallocates a buffer

Syntax:

operation ::= `util.buffer.dealloc` $operand `:` type($operand) `{` $operand_size `}`
              attr-dict-with-keyword

Hints that the buffer contents can be discarded. Buffers are reference counted and other owners may keep it live beyond the dealloc.

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, MemoryEffectOpInterface (MemoryEffectOpInterface), NoMemoryEffect (MemoryEffectOpInterface), Util_SizeAwareOp

Effects: MemoryEffects::Effect{MemoryEffects::Free on ::mlir::SideEffects::DefaultResource}, MemoryEffects::Effect{}

Operands:link
Operand Description
operand a reference counted byte buffer
operand_size index

util.buffer.fill (Util::BufferFillOp)link

Fills a range of bytes with a value

Syntax:

operation ::= `util.buffer.fill` $pattern `,`
              $target `[` $target_offset `for` $length `]` `:`
              type($pattern) `->`
              type($target) `` `{` $target_size `}`
              attr-dict-with-keyword

Fills the contents of the buffer in the given byte range with a pattern. The offset and length must match the natural alignment of the pattern type.

Interfaces: MemoryEffectOpInterface (MemoryEffectOpInterface), SubrangeOperandOpInterface, Util_SizeAwareOp

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

Operands:link
Operand Description
pattern integer or floating-point or index
target a reference counted byte buffer
target_size index
target_offset index
length index

util.buffer.hash (Util::BufferHashOp)link

Computes the hash of a byte range of a buffer

Syntax:

operation ::= `util.buffer.hash` $source `[` $source_offset `for` $length `]`
              `:` type($source) `` `{` $source_size `}` `->` type($result)
              attr-dict-with-keyword

Computes the SipHash-2-4 of a value at a byte offset with the given length. This always uses a seed of 0x0001020304...0e0f and produces a single 64 bit value.

Interfaces: InferTypeOpInterface, MemoryEffectOpInterface (MemoryEffectOpInterface), SubrangeOperandOpInterface, Util_SizeAwareOp

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

Operands:link
Operand Description
source a reference counted byte buffer
source_size index
source_offset index
length index
Results:link
Result Description
result 64-bit signless integer

util.buffer.load (Util::BufferLoadOp)link

Loads a value from a buffer

Syntax:

operation ::= `util.buffer.load` $source `[` $source_offset `for` $length `]`
              `:` type($source) `` `{` $source_size `}` `->` type($result)
              attr-dict-with-keyword

Loads a value at a byte offset. Must be aligned to the natural size of the result type.

Interfaces: MemoryEffectOpInterface (MemoryEffectOpInterface), SubrangeOperandOpInterface, Util_SizeAwareOp

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

Operands:link
Operand Description
source a reference counted byte buffer
source_size index
source_offset index
length index
Results:link
Result Description
result index or integer or floating-point

util.buffer.size (Util::BufferSizeOp)link

Returns the total buffer storage size in bytes

Syntax:

operation ::= `util.buffer.size` $operand
              `:` type($operand)
              attr-dict-with-keyword

Returns the total length of the buffer in bytes from its base offset.

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), OpAsmOpInterface, Util_SizeAwareOp

Effects: MemoryEffects::Effect{}

Operands:link
Operand Description
operand a reference counted byte buffer
Results:link
Result Description
result index

util.buffer.slice (Util::BufferSliceOp)link

Clones a subregion of a buffer

Syntax:

operation ::= `util.buffer.slice` $source `[` $source_offset `]` attr-dict `:`
              type($source) `` `{` $source_size `}` `->`
              type($result) `` `{` $result_size `}`

Returns a copy of the contents from the source buffer.

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, MemoryEffectOpInterface (MemoryEffectOpInterface), NoMemoryEffect (MemoryEffectOpInterface), OpAsmOpInterface, SubrangeOperandOpInterface, Util_SizeAwareOp

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

Attributes:link
AttributeMLIR TypeDescription
alignment::mlir::IntegerAttrindex attribute
Operands:link
Operand Description
source a reference counted byte buffer
source_size index
source_offset index
result_size index
Results:link
Result Description
result a reference counted byte buffer

util.buffer.storage (Util::BufferStorageOp)link

Returns the underlying buffer storage range

Syntax:

operation ::= `util.buffer.storage` $operand
              `:` type($operand) `` `{` $operand_size `}` `->` `(` type($result) `,` type($offset) `)`
              attr-dict-with-keyword

Returns the buffer storage as a memref that must be offset and restricted to the returned range. The memref may be of any type and the user is responsible for ensuring that the reinterpret_cast-like behavior makes sense for the data they are accessing.

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface), OpAsmOpInterface, Util_SizeAwareOp

Effects: MemoryEffects::Effect{}

Operands:link
Operand Description
operand a reference counted byte buffer
operand_size index
Results:link
Result Description
result memref of any type values
offset index

util.buffer.store (Util::BufferStoreOp)link

Stores a value into a buffer

Syntax:

operation ::= `util.buffer.store` $source `,`
              $target `[` $target_offset `for` $length `]`
              `:` type($source) `->` type($target) `` `{` $target_size `}`
              attr-dict-with-keyword

Stores a value at a byte offset. Must be aligned to the natural size of the source type.

Interfaces: MemoryEffectOpInterface (MemoryEffectOpInterface), SubrangeOperandOpInterface, Util_SizeAwareOp

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

Operands:link
Operand Description
source index or integer or floating-point
target a reference counted byte buffer
target_size index
target_offset index
length index

util.buffer.subspan (Util::BufferSubspanOp)link

Returns a reference to a subrange of a buffer

Syntax:

operation ::= `util.buffer.subspan` $source `[` $source_offset `]` `:`
              type($source) `` `{` $source_size `}` `->`
              type($result) `` `{` $result_size `}`
              attr-dict-with-keyword

Returns a logical view into an underlying source buffer. This induces aliasing and multiple SSA values may allow access to the same underlying buffer storage.

Subspans are a compiler-only concept and are propagated by an analysis pass to result in absolute offsets on accesses any place the subrange would have been used.

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface), OpAsmOpInterface, SubrangeOperandOpInterface, TiedOpInterface, Util_SizeAwareOp, Util_SubrangeOp, ViewLikeOpInterface

Effects: MemoryEffects::Effect{}

Operands:link
Operand Description
source a reference counted byte buffer
source_size index
source_offset index
result_size index
Results:link
Result Description
result a reference counted byte buffer

Compiler hint opslink

util.assume.int (Util::AssumeIntOp)link

Memorializes assumptions about index/integer values.

This op is used to memorialize the result of some integer analysis or outside knowledge across a boundary beyond which such information can not be easily recovered. Assumptions are made per op/result pair.

Assumptions are tied to operands as rows of permutations of an #util.assume.int per operand. The number of permutations is the rank. Typically multiple permutations record a specific subset of assumptions broken down per call-site in some way that is meaningful to the receiver. Implementations can use this information to specialize on each permutation if it is meaninful to do so (i.e. vs unioning across them). In such cases, there will typically be one such op at the top of a function or scope which passes all covered operands through it.

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferIntDivisibilityOpInterface, InferIntRangeInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Attributes:link
AttributeMLIR TypeDescription
assumptions::mlir::ArrayAttrlist of int attribute assumptions for multiple values
Operands:link
Operand Description
operands variadic of signless integer or index
Results:link
Result Description
results variadic of signless integer or index

util.optimization_barrier (Util::OptimizationBarrierOp)link

Prevents compiler optimizations across a value.

Syntax:

operation ::= `util.optimization_barrier` attr-dict
              ($operands^ `:` type($operands))?

Wraps any operands in an unoptimizable identity to prevent its results from being folded. It will be dropped during the final step in compilation and has no effect at runtime.

Traits: SameOperandsAndResultType

Operands:link
Operand Description
operands variadic of any type
Results:link
Result Description
results variadic of any type

util.unfoldable_constant (Util::UnfoldableConstantOp)link

A constant that cannot be folded by the compiler.

Similar to a std.constant, but is declared as having a side effect and has no folder. This is really just syntactic sugar as it is canonicalized to a std.constant wrapped in an util.optimization_barrier.

Attributes:link
AttributeMLIR TypeDescription
value::mlir::Attributeany attribute
Results:link
Result Description
«unnamed» any type

util.unreachable (Util::UnreachableOp)link

Unreachable assertion op

Syntax:

operation ::= `util.unreachable` $message attr-dict

Signals to the compiler that the parent block should not be reachable. This may be converted into a runtime assertion, though ideally they are stripped during translation.

^bb0:
  %true = arith.constant true
  cond_br %true, ^bb2, ^bb1
^bb1:
  // Indicates that this branch should never be taken.
  util.unreachable "shouldn't be here"
^bb2:
  ...

Traits: ReturnLike, Terminator

Interfaces: NoMemoryEffect (MemoryEffectOpInterface), RegionBranchTerminatorOpInterface

Effects: MemoryEffects::Effect{}

Attributes:link
AttributeMLIR TypeDescription
message::mlir::StringAttrstring attribute

Data type conversion opslink

util.numeric.optional_narrow (Util::NumericOptionalNarrowOp)link

Memorializes an optional numeric narrowing that is valid

Syntax:

operation ::= `util.numeric.optional_narrow` $operand `:` type($operand) `as` $semantic_type attr-dict

Serves as a placeholder for points in the computation where an optional numeric narrowing can be performed without loss of information. Such ops can guide optimization passes wishing to perform precision reduction.

In addition to the operand and result type, this op takes an additional semantic_type attribute representing the semantic target type which can be: * FloatType * Signed IntegerType * Unsigned IntegerType

Note that this semantic_type must be a sign-carrying integer if using an integer type and cannot be IndexType (i.e. it can be used to indicate a possible narrowing of an IndexType to a specific integer).

If the operand is a TensorType, then the result must be a TensorType. The semantic_type constrains the element type.

Optionally, the minimum and maximum integer values (for integer semantic types) are tracked if known.

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Attributes:link
AttributeMLIR TypeDescription
semantic_type::mlir::TypeAttrany type attribute
min_value::mlir::IntegerAttrarbitrary integer attribute
max_value::mlir::IntegerAttrarbitrary integer attribute
Operands:link
Operand Description
operand signless integer or floating-point or tensor of signless integer or floating-point values
Results:link
Result Description
result signless integer or floating-point or tensor of signless integer or floating-point values

Global opslink

util.global.address (Util::GlobalAddressOp)link

Returns an address reference to a global

Syntax:

operation ::= `util.global.address` (`immutable` $is_immutable^)?
              $global attr-dict `:` qualified(type($result))

Returns the address of a global as a typed reference. Can be used with the global load and store indirect ops.

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface), OpAsmOpInterface, SymbolUserOpInterface, Util_GlobalAddressOpInterface

Effects: MemoryEffects::Effect{}

Attributes:link
AttributeMLIR TypeDescription
global::mlir::FlatSymbolRefAttrflat symbol reference attribute
is_immutable::mlir::UnitAttrunit attribute
Results:link
Result Description
result a pointer-like reference

util.global.load.indirect (Util::GlobalLoadIndirectOp)link

Loads a value from a global variable

Syntax:

operation ::= `util.global.load.indirect` (`immutable` $is_immutable^)?
              $global attr-dict `:` qualified(type($global)) `->` type($result)

Returns a copy of the global variable value.

Interfaces: Util_GlobalLoadIndirectOpInterface

Attributes:link
AttributeMLIR TypeDescription
is_immutable::mlir::UnitAttrunit attribute
Operands:link
Operand Description
global a pointer-like reference
Results:link
Result Description
result any type

util.global.load (Util::GlobalLoadOp)link

Loads a value from a global variable

Syntax:

operation ::= `util.global.load` (`immutable` $is_immutable^)?
              $global attr-dict `:` type($result)

Returns a global variable value.

Interfaces: MemoryEffectOpInterface, OpAsmOpInterface, SymbolUserOpInterface, Util_GlobalLoadOpInterface

Attributes:link
AttributeMLIR TypeDescription
global::mlir::FlatSymbolRefAttrflat symbol reference attribute
is_immutable::mlir::UnitAttrunit attribute
Results:link
Result Description
result any type

util.global (Util::GlobalOp)link

Stateful global variable declaration

Syntax:

operation ::= `util.global` custom<SymbolVisibility>($sym_visibility)
              (`mutable` $is_mutable^)?
              $sym_name
              attr-dict
              custom<TypeOrAttr>($type, $initial_value)

Declares a global variable that maintains its value across invocations. The value is tied to the execution context of the module and different contexts will have different variable storage.

Interfaces: Symbol, Util_GlobalOpInterface

Attributes:link
AttributeMLIR TypeDescription
sym_visibility::mlir::StringAttrstring attribute
sym_name::mlir::StringAttrstring attribute
type::mlir::TypeAttrany type attribute
is_mutable::mlir::UnitAttrunit attribute
initial_value::mlir::TypedAttrTypedAttr instance
inlining_policy::mlir::iree_compiler::IREE::Util::InliningPolicyAttrInterfaceInliningPolicyAttrInterface instance

util.global.store.indirect (Util::GlobalStoreIndirectOp)link

Stores a value into a global variable

Syntax:

operation ::= `util.global.store.indirect` $value `,` $global attr-dict `:` type($value) `->` qualified(type($global))

Stores a copy of the value into a global variable.

Interfaces: Util_GlobalStoreIndirectOpInterface

Operands:link
Operand Description
value any type
global a pointer-like reference

util.global.store (Util::GlobalStoreOp)link

Stores a value into a global variable

Syntax:

operation ::= `util.global.store` $value `,` $global attr-dict `:` type($value)

Stores a copy of the value into a global variable.

Interfaces: SymbolUserOpInterface, Util_GlobalStoreOpInterface

Attributes:link
AttributeMLIR TypeDescription
global::mlir::FlatSymbolRefAttrflat symbol reference attribute
Operands:link
Operand Description
value any type

List opslink

Ops for !util.list<T> (mostly just a placeholder for now).

util.list.create (Util::ListCreateOp)link

Creates a new empty list

Syntax:

operation ::= `util.list.create` ($initial_capacity^)? attr-dict `:` qualified(type($result))

Creates a new empty list with an optional initial capacity.

Traits: AlwaysSpeculatableImplTrait

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

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

Operands:link
Operand Description
initial_capacity index
Results:link
Result Description
result dense list container type

util.list.get (Util::ListGetOp)link

Element accessor

Syntax:

operation ::= `util.list.get` $list `[` $index `]` attr-dict `:` custom<ListTypeGet>(type($list), type($result))

Returns the value of the element at the given index. Note that the value may be null if the element is null or the type does not match.

Interfaces: MemoryEffectOpInterface (MemoryEffectOpInterface)

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

Operands:link
Operand Description
list dense list container type
index index
Results:link
Result Description
result any type

util.list.resize (Util::ListResizeOp)link

Resizes the list to a new count in elements

Syntax:

operation ::= `util.list.resize` operands attr-dict `:` qualified(type($list))

Resizes the list to contain new_size elements. This will either truncate the list if the existing size is greater than new_size or extend the list with the default list value of the element type.

Interfaces: MemoryEffectOpInterface (MemoryEffectOpInterface)

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

Operands:link
Operand Description
list dense list container type
new_size index

util.list.set (Util::ListSetOp)link

Element mutator

Syntax:

operation ::= `util.list.set` $list `[` $index `]` `,` $value attr-dict `:` custom<ListTypeSet>(type($list), type($value))

Sets the element at the given index to the new value.

Interfaces: MemoryEffectOpInterface (MemoryEffectOpInterface)

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

Operands:link
Operand Description
list dense list container type
index index
value any type

util.list.size (Util::ListSizeOp)link

The size of the list in elements

Syntax:

operation ::= `util.list.size` operands attr-dict `:` qualified(type($list))

Returns the current size of the list in elements.

Interfaces: InferTypeOpInterface, MemoryEffectOpInterface (MemoryEffectOpInterface)

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

Operands:link
Operand Description
list dense list container type
Results:link
Result Description
result index

Range arithmetic opslink

util.range.extents (Util::RangeExtentsOp)link

Returns the min/max of a union of a set of ranges

Syntax:

operation ::= `util.range.extents` custom<RangeList>($offsets, $lengths) attr-dict `:` type($min)

Computes min(offsets) and max(offsets + lengths). Though it's possible to express this with standard arithmetic this op enables more semantically meaningful folding/optimizations.

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType, SameVariadicOperandSize

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands:link
Operand Description
offsets variadic of index or integer
lengths variadic of index or integer
Results:link
Result Description
min index or integer
max index or integer

util.range.max (Util::RangeMaxOp)link

Returns the max of all values

Syntax:

operation ::= `util.range.max` $operands attr-dict `:` type($result)

Computes the max of a variadic list of operands. Though it's possible to express this with standard arithmetic this op enables more semantically meaningful folding/optimizations.

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType, SameVariadicOperandSize

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands:link
Operand Description
operands variadic of index or integer
Results:link
Result Description
result index or integer

util.range.min (Util::RangeMinOp)link

Returns the min of all values

Syntax:

operation ::= `util.range.min` $operands attr-dict `:` type($result)

Computes the min of a variadic list of operands. Though it's possible to express this with standard arithmetic this op enables more semantically meaningful folding/optimizations.

Traits: AlwaysSpeculatableImplTrait, SameOperandsAndResultType, SameVariadicOperandSize

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands:link
Operand Description
operands variadic of index or integer
Results:link
Result Description
result index or integer

Status opslink

util.status.check_ok (Util::StatusCheckOkOp)link

Raises a global failure if a status is not 'ok'

Syntax:

operation ::= `util.status.check_ok` $status (`,` $message^)? attr-dict

When the status is not 'ok' this signals a runtime failure that causes the entire active invocation - and possibly all in-flight and pending invocations - to fail with the given status. The status will be propagated back via the available runtime error handling mechanisms such as semaphores or synchronous invocation results.

As the IREE execution model is deeply pipelined it's possible that failures have a latency between when they are emitted and when the application can observe the failure. It's also possible that other work that is in-flight or pending when the failure occurs will complete.

Attributes:link
AttributeMLIR TypeDescription
message::mlir::StringAttrstring attribute
Operands:link
Operand Description
status 32-bit signless integer

Structural opslink

util.call (Util::CallOp)link

Function call operation

Syntax:

operation ::= `util.call` $callee `(` $operands `)`
              attr-dict `:`
              custom<OperandTypeList>(type($operands))
              `->`
              custom<TiedFunctionResultList>(ref($operands),
              ref(type($operands)),
              type($results),
              $tied_operands)

Represents a direct call to a function that is within the same symbol scope as the call. The operands and result types of the call must match the specified function type.

Calls support tied operands which indicate that specific results alias a specific operand. The operand and result types are allowed to differ if a cast is performed within the callee.

Example:

util.func @fn(%arg0: i32, %arg1: tensor<f32>) -> (f32, %arg1 as tensor<i32>)
...
%0 = util.call @fn(%0, %1) : (i32, tensor<f32>) -> (f32, %1 as tensor<i32>)

Interfaces: CallOpInterface, SymbolUserOpInterface, Util_TiedOpInterface

Attributes:link
AttributeMLIR TypeDescription
callee::mlir::FlatSymbolRefAttrflat symbol reference attribute
tied_operands::mlir::ArrayAttr64-bit integer array attribute
Operands:link
Operand Description
operands variadic of any type
Results:link
Result Description
results variadic of any type

util.func (Util::FuncOp)link

Function operation containing a CFG region

An operation declaring a callable function.

An external function declaration (used when referring to a function declared in some other module) has no body.

Traits: AffineScope, AutomaticAllocationScope, IsolatedFromAbove

Interfaces: CallableOpInterface, FunctionOpInterface, OpAsmOpInterface, Symbol

Attributes:link
AttributeMLIR TypeDescription
sym_name::mlir::StringAttrstring attribute
function_type::mlir::TypeAttrtype attribute of function type
tied_operands::mlir::ArrayAttr64-bit integer array attribute
sym_visibility::mlir::StringAttrstring attribute
arg_attrs::mlir::ArrayAttrArray of dictionary attributes
res_attrs::mlir::ArrayAttrArray of dictionary attributes
inlining_policy::mlir::iree_compiler::IREE::Util::InliningPolicyAttrInterfaceInliningPolicyAttrInterface instance

util.initializer (Util::InitializerOp)link

Global initialization function

A function that is called in definition order upon module initialization. Must not load any globals that are defined or initialized after it in the module.

Traits: IsolatedFromAbove

Interfaces: CallableOpInterface, FunctionOpInterface, Symbol, Util_InitializerOpInterface

Attributes:link
AttributeMLIR TypeDescription
function_type::mlir::TypeAttrtype attribute of function type
arg_attrs::mlir::ArrayAttrArray of dictionary attributes
res_attrs::mlir::ArrayAttrArray of dictionary attributes

util.return (Util::ReturnOp)link

Return from a util.initializer

Syntax:

operation ::= `util.return` attr-dict
              ($operands^ `:` type($operands))?

Returns control from an initializer function.

Traits: AlwaysSpeculatableImplTrait, HasParent<IREE::Util::InitializerOp, IREE::Util::FuncOp>, ReturnLike, Terminator

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface), RegionBranchTerminatorOpInterface

Effects: MemoryEffects::Effect{}

Operands:link
Operand Description
operands variadic of any type

Type manipulation opslink

util.cast (Util::CastOp)link

Casts one util type to another ala static_cast/dynamic_cast

Syntax:

operation ::= `util.cast` $operand attr-dict `:` type($operand) `to` type($result)

Performs a type cast between object types known to the util dialect.

Traits: AlwaysSpeculatableImplTrait

Interfaces: CastOpInterface, ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface), TiedOpInterface

Effects: MemoryEffects::Effect{}

Operands:link
Operand Description
operand any type
Results:link
Result Description
result any type

util.cmp.eq (Util::CmpEQOp)link

Compares two values for equality

Syntax:

operation ::= `util.cmp.eq` operands attr-dict `:` type($lhs)

Compares two operands for equality. This is intended for comparing IREE reference types (like !util.buffer) that cannot be used with std.cmpi.

Traits: AlwaysSpeculatableImplTrait, Commutative

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands:link
Operand Description
lhs any type
rhs any type
Results:link
Result Description
result 1-bit signless integer

util.cmp.ne (Util::CmpNEOp)link

Compares two values for inequality

Syntax:

operation ::= `util.cmp.ne` operands attr-dict `:` type($lhs)

Compares two operands for inequality. This is intended for comparing IREE reference types (like !util.buffer) that cannot be used with std.cmpi.

Traits: AlwaysSpeculatableImplTrait, Commutative

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands:link
Operand Description
lhs any type
rhs any type
Results:link
Result Description
result 1-bit signless integer

util.null (Util::NullOp)link

Returns a null type value

Syntax:

operation ::= `util.null` attr-dict `:` type($result)

Defines an SSA value that is lowered into dialects supporting null/undefined/optional/etc values.

Traits: AlwaysSpeculatableImplTrait, ConstantLike

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Results:link
Result Description
result any type

Value utility opslink

util.switch (Util::SwitchOp)link

Primitive switch operation

Syntax:

operation ::= `util.switch` type($default_value) `from`
              custom<TypedValueList>(ref(type($default_value)), $values, type($values))
              `at` $index
              `else` $default_value
              attr-dict
              `:` type($result)

Returns the value with the given index in values or default_value if the index is out of bounds.

// Switch %index to cases of %c100/%c200/%c300 if index==0, ==1, ==2.
// If %index is out of range (<0 or >2) then default to %c5.
%0 = util.switch %index[%c100, %c200, %c300] else %c5 : i32

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands:link
Operand Description
index index
default_value index or integer or floating-point
values variadic of index or integer or floating-point
Results:link
Result Description
result index or integer or floating-point

Attributeslink

BytePatternAttrlink

an attribute containing a filled byte pattern

Syntax:

#util.byte_pattern<
  ::mlir::Type,   # type
  int64_t   # pattern
>

A dense serializable attribute with the given byte pattern.

Parameters:link
Parameter C++ type Description
type ::mlir::Type
pattern int64_t

ByteRangeAttrlink

defines a range of bytes

Specifies a starting offset and total length in bytes.

Parameters:link
Parameter C++ type Description
offset int64_t
length int64_t

CompositeAttrlink

an attribute composed of a sequence of attributes

Models a concatenated set of serializable attributes that when combined form a single sequence of i8 elements. As each value references the uniqued storage of the composite element this attribute is cheap to construct. When the full flattened range is required it can be efficiently streamed via the SerializableAttrInterface. All values must also be serializable.

All values are tightly packed to byte boundaries. If padding is required it can be inserted as splat elements attributes with the padding value (usually 0). Sub-byte aligned element types will have their individual components padded to byte alignment.

Parameters:link
Parameter C++ type Description
totalLength int64_t
values ArrayAttr

InlineAlwaysAttrlink

forces inlining on the associated function when possible

Syntax: #util.inline.always

Skips any cost-model decisions as to whether a function should be inlined into call-sites and allows the inlining to happen. Any policies that prevent inlining will still be observed and inlining may fail if any are not satisfied.

InlineNeverAttrlink

disables inlining on the associated function

Syntax: #util.inline.never

Disables inlining of the function the attribute is associated with into any call-site.

IntAssumptionAttrlink

specifies assumptions that can be made about an integer's value

Syntax:

#util.int.assumption<
  std::optional<uint64_t>,   # umin
  std::optional<uint64_t>,   # umax
  std::optional<uint64_t>   # udiv
>

This is typically used to memorialize the result of some integer analysis or outside knowledge. All components of the attribute are optional.

See the op util.assume.int for binding assumptions to values.

Parameters:link
Parameter C++ type Description
umin std::optional<uint64_t>
umax std::optional<uint64_t>
udiv std::optional<uint64_t>

NullAttrlink

an attribute specifying a null reference

Syntax:

#util.null<
  ::mlir::Type   # type
>

A null reference value.

Parameters:link
Parameter C++ type Description
type ::mlir::Type

UninitializedAttrlink

an attribute specifying uninitialized storage

Syntax:

#util.uninitialized<
  ::mlir::Type   # type
>

The contents of the storage backing this attribute may be uninitialized at runtime. This is a hint to implementations that if policy allows memory allocated for the storage of this attribute type is allowed to have undefined contents upon return.

Parameters:link
Parameter C++ type Description
type ::mlir::Type

Typeslink

BufferTypelink

a reference counted byte buffer

Syntax: !util.buffer

A reference counted byte buffer that models a pointer, offset, and length.

ListTypelink

dense list container type

Syntax:

!util.list<
  Type   # element_type
>

Typed container supporting variant storage.

Parameters:link
Parameter C++ type Description
element_type Type

ObjectTypelink

a placeholder for an unspecified object type

Syntax: !util.object

Describes a runtime object type. These may be reference counted or garbage collected at runtime.

PtrTypelink

a pointer-like reference

Syntax:

!util.ptr<
  Type   # target_type
>

A typed indirect reference to a value. These define a runtime addressable value that is strongly referenced.

Parameters:link
Parameter C++ type Description
target_type Type

VariantTypelink

a placeholder for a variant type (?)

Syntax: !util.variant

Describes a runtime variant type. These may be primitives (i32, f32, etc) or object types.