MLIR

Multi-Level IR Compiler Framework

'std' Dialect

This dialect provides documentation for operations within the Standard dialect.

Note: This dialect is a collection of operations for several different concepts, and should be split into multiple more-focused dialects accordingly.

Please post an RFC on the forum before adding or changing any operation in this dialect.

Operations 

std.absf (AbsFOp) 

floating point absolute-value operation

The absf operation computes the absolute value. It takes one operand and returns one result of the same type. This type may be a float scalar type, a vector whose element type is float, or a tensor of floats.

Example:

// Scalar absolute value.
%a = absf %b : f64

// SIMD vector element-wise absolute value.
%f = absf %g : vector<4xf32>

// Tensor element-wise absolute value.
%x = absf %y : tensor<4x?xf8>

Operands: 

OperandDescription
operandfloating-point-like

Results: 

ResultDescription
«unnamed»any type

std.addf (AddFOp) 

floating point addition operation

Syntax:

operation ::= ssa-id `=` `std.addf` ssa-use `,` ssa-use `:` type

The addf operation takes two operands and returns one result, each of these is required to be the same type. This type may be a floating point scalar type, a vector whose element type is a floating point type, or a floating point tensor.

Example:

// Scalar addition.
%a = addf %b, %c : f64

// SIMD vector addition, e.g. for Intel SSE.
%f = addf %g, %h : vector<4xf32>

// Tensor addition.
%x = addf %y, %z : tensor<4x?xbf16>

TODO: In the distant future, this will accept optional attributes for fast math, contraction, rounding mode, and other controls.

Operands: 

OperandDescription
lhsfloating-point-like
rhsfloating-point-like

Results: 

ResultDescription
resultany type

std.addi (AddIOp) 

integer addition operation

Syntax:

operation ::= ssa-id `=` `std.addi` ssa-use `,` ssa-use `:` type

The addi operation takes two operands and returns one result, each of these is required to be the same type. This type may be an integer scalar type, a vector whose element type is integer, or a tensor of integers. It has no standard attributes.

Example:

// Scalar addition.
%a = addi %b, %c : i64

// SIMD vector element-wise addition, e.g. for Intel SSE.
%f = addi %g, %h : vector<4xi32>

// Tensor element-wise addition.
%x = addi %y, %z : tensor<4x?xi8>

Operands: 

OperandDescription
lhssignless-integer-like
rhssignless-integer-like

Results: 

ResultDescription
resultany type

std.and (AndOp) 

integer binary and

Syntax:

operation ::= ssa-id `=` `std.and` ssa-use `,` ssa-use `:` type

The and operation takes two operands and returns one result, each of these is required to be the same type. This type may be an integer scalar type, a vector whose element type is integer, or a tensor of integers. It has no standard attributes.

Example:

// Scalar integer bitwise and.
%a = and %b, %c : i64

// SIMD vector element-wise bitwise integer and.
%f = and %g, %h : vector<4xi32>

// Tensor element-wise bitwise integer and.
%x = and %y, %z : tensor<4x?xi8>

Operands: 

OperandDescription
lhssignless-integer-like
rhssignless-integer-like

Results: 

ResultDescription
resultany type

std.assert (AssertOp) 

Assert operation with message attribute

Syntax:

operation ::= `std.assert` $arg `,` $msg attr-dict

Assert operation with single boolean operand and an error message attribute. If the argument is true this operation has no effect. Otherwise, the program execution will abort. The provided error message may be used by a runtime to propagate the error to the user.

Example:

assert %b, "Expected ... to be true"

Attributes: 

AttributeMLIR TypeDescription
msg::mlir::StringAttrstring attribute

Operands: 

OperandDescription
arg1-bit signless integer

std.atomic_rmw (AtomicRMWOp) 

atomic read-modify-write operation

Syntax:

operation ::= `std.atomic_rmw` $kind $value `,` $memref `[` $indices `]` attr-dict `:` `(` type($value) `,`
              type($memref) `)` `->` type($result)

The atomic_rmw operation provides a way to perform a read-modify-write sequence that is free from data races. The kind enumeration specifies the modification to perform. The value operand represents the new value to be applied during the modification. The memref operand represents the buffer that the read and write will be performed against, as accessed by the specified indices. The arity of the indices is the rank of the memref. The result represents the latest value that was stored.

Example:

%x = atomic_rmw "addf" %value, %I[%i] : (f32, memref<10xf32>) -> f32

Attributes: 

AttributeMLIR TypeDescription
kind::mlir::AtomicRMWKindAttrallowed 64-bit signless integer cases: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10

Operands: 

OperandDescription
valuesignless integer or floating-point
memrefmemref of signless integer or floating-point values
indicesindex

Results: 

ResultDescription
resultsignless integer or floating-point

std.atomic_yield (AtomicYieldOp) 

yield operation for GenericAtomicRMWOp

Syntax:

operation ::= `std.atomic_yield` $result attr-dict `:` type($result)

“atomic_yield” yields an SSA value from a GenericAtomicRMWOp region.

Operands: 

OperandDescription
resultany type

std.br (BranchOp) 

branch operation

Syntax:

operation ::= `std.br` $dest (`(` $destOperands^ `:` type($destOperands) `)`)? attr-dict

The br operation represents a branch operation in a function. The operation takes variable number of operands and produces no results. The operand number and types for each successor must match the arguments of the block successor.

Example:

^bb2:
  %2 = call @someFn()
  br ^bb3(%2 : tensor<*xf32>)
^bb3(%3: tensor<*xf32>):

Operands: 

OperandDescription
destOperandsany type

Successors: 

SuccessorDescription
destany successor

std.call_indirect (CallIndirectOp) 

indirect call operation

Syntax:

operation ::= `std.call_indirect` $callee `(` $operands `)` attr-dict `:` type($callee)

The call_indirect operation represents an indirect call to a value of function type. Functions are first class types in MLIR, and may be passed as arguments and merged together with block arguments. The operands and result types of the call must match the specified function type.

Function values can be created with the constant operation .

Example:

%31 = call_indirect %15(%0, %1)
        : (tensor<16xf32>, tensor<16xf32>) -> tensor<16xf32>

Operands: 

OperandDescription
calleefunction type
operandsany type

Results: 

ResultDescription
resultsany type

std.call (CallOp) 

call operation

Syntax:

operation ::= `std.call` $callee `(` $operands `)` attr-dict `:` functional-type($operands, results)

The call operation 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. The callee is encoded as a symbol reference attribute named “callee”.

Example:

%2 = call @my_add(%0, %1) : (f32, f32) -> f32

Attributes: 

AttributeMLIR TypeDescription
callee::mlir::FlatSymbolRefAttrflat symbol reference attribute

Operands: 

OperandDescription
operandsany type

Results: 

ResultDescription
«unnamed»any type

std.ceilf (CeilFOp) 

ceiling of the specified value

Syntax:

operation ::= ssa-id `=` `std.ceilf` ssa-use `:` type

The ceilf operation computes the ceiling of a given value. It takes one operand and returns one result of the same type. This type may be a float scalar type, a vector whose element type is float, or a tensor of floats. It has no standard attributes.

Example:

// Scalar ceiling value.
%a = ceilf %b : f64

// SIMD vector element-wise ceiling value.
%f = ceilf %g : vector<4xf32>

// Tensor element-wise ceiling value.
%x = ceilf %y : tensor<4x?xf8>

Operands: 

OperandDescription
operandfloating-point-like

Results: 

ResultDescription
«unnamed»any type

std.cmpf (CmpFOp) 

floating-point comparison operation

Syntax:

operation ::= `std.cmpf` $predicate `,` $lhs `,` $rhs attr-dict `:` type($lhs)

The cmpf operation compares its two operands according to the float comparison rules and the predicate specified by the respective attribute. The predicate defines the type of comparison: (un)orderedness, (in)equality and signed less/greater than (or equal to) as well as predicates that are always true or false. The operands must have the same type, and this type must be a float type, or a vector or tensor thereof. The result is an i1, or a vector/tensor thereof having the same shape as the inputs. Unlike cmpi, the operands are always treated as signed. The u prefix indicates unordered comparison, not unsigned comparison, so “une” means unordered or not equal. For the sake of readability by humans, custom assembly form for the operation uses a string-typed attribute for the predicate. The value of this attribute corresponds to lower-cased name of the predicate constant, e.g., “one” means “ordered not equal”. The string representation of the attribute is merely a syntactic sugar and is converted to an integer attribute by the parser.

Example:

%r1 = cmpf "oeq" %0, %1 : f32
%r2 = cmpf "ult" %0, %1 : tensor<42x42xf64>
%r3 = "std.cmpf"(%0, %1) {predicate: 0} : (f8, f8) -> i1

Attributes: 

AttributeMLIR TypeDescription
predicate::mlir::CmpFPredicateAttrallowed 64-bit signless integer cases: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15

Operands: 

OperandDescription
lhsfloating-point-like
rhsfloating-point-like

Results: 

ResultDescription
resultbool-like

std.cmpi (CmpIOp) 

integer comparison operation

Syntax:

operation ::= `std.cmpi` $predicate `,` $lhs `,` $rhs attr-dict `:` type($lhs)

The cmpi operation is a generic comparison for integer-like types. Its two arguments can be integers, vectors or tensors thereof as long as their types match. The operation produces an i1 for the former case, a vector or a tensor of i1 with the same shape as inputs in the other cases.

Its first argument is an attribute that defines which type of comparison is performed. The following comparisons are supported:

  • equal (mnemonic: "eq"; integer value: 0)
  • not equal (mnemonic: "ne"; integer value: 1)
  • signed less than (mnemonic: "slt"; integer value: 2)
  • signed less than or equal (mnemonic: "sle"; integer value: 3)
  • signed greater than (mnemonic: "sgt"; integer value: 4)
  • signed greater than or equal (mnemonic: "sge"; integer value: 5)
  • unsigned less than (mnemonic: "ult"; integer value: 6)
  • unsigned less than or equal (mnemonic: "ule"; integer value: 7)
  • unsigned greater than (mnemonic: "ugt"; integer value: 8)
  • unsigned greater than or equal (mnemonic: "uge"; integer value: 9)

The result is 1 if the comparison is true and 0 otherwise. For vector or tensor operands, the comparison is performed elementwise and the element of the result indicates whether the comparison is true for the operand elements with the same indices as those of the result.

Note: while the custom assembly form uses strings, the actual underlying attribute has integer type (or rather enum class in C++ code) as seen from the generic assembly form. String literals are used to improve readability of the IR by humans.

This operation only applies to integer-like operands, but not floats. The main reason being that comparison operations have diverging sets of attributes: integers require sign specification while floats require various floating point-related particularities, e.g., -ffast-math behavior, IEEE754 compliance, etc ( rationale ). The type of comparison is specified as attribute to avoid introducing ten similar operations, taking into account that they are often implemented using the same operation downstream ( rationale ). The separation between signed and unsigned order comparisons is necessary because of integers being signless. The comparison operation must know how to interpret values with the foremost bit being set: negatives in two’s complement or large positives ( rationale ).

Example:

// Custom form of scalar "signed less than" comparison.
%x = cmpi "slt", %lhs, %rhs : i32

// Generic form of the same operation.
%x = "std.cmpi"(%lhs, %rhs) {predicate = 2 : i64} : (i32, i32) -> i1

// Custom form of vector equality comparison.
%x = cmpi "eq", %lhs, %rhs : vector<4xi64>

// Generic form of the same operation.
%x = "std.cmpi"(%lhs, %rhs) {predicate = 0 : i64}
    : (vector<4xi64>, vector<4xi64>) -> vector<4xi1>

Attributes: 

AttributeMLIR TypeDescription
predicate::mlir::CmpIPredicateAttrallowed 64-bit signless integer cases: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9

Operands: 

OperandDescription
lhssignless-integer-like
rhssignless-integer-like

Results: 

ResultDescription
resultbool-like

std.cond_br (CondBranchOp) 

conditional branch operation

Syntax:

operation ::= `std.cond_br` $condition `,`
              $trueDest (`(` $trueDestOperands^ `:` type($trueDestOperands) `)`)? `,`
              $falseDest (`(` $falseDestOperands^ `:` type($falseDestOperands) `)`)?
              attr-dict

The cond_br terminator operation represents a conditional branch on a boolean (1-bit integer) value. If the bit is set, then the first destination is jumped to; if it is false, the second destination is chosen. The count and types of operands must align with the arguments in the corresponding target blocks.

The MLIR conditional branch operation is not allowed to target the entry block for a region. The two destinations of the conditional branch operation are allowed to be the same.

The following example illustrates a function with a conditional branch operation that targets the same block.

Example:

func @select(%a: i32, %b: i32, %flag: i1) -> i32 {
  // Both targets are the same, operands differ
  cond_br %flag, ^bb1(%a : i32), ^bb1(%b : i32)

^bb1(%x : i32) :
  return %x : i32
}

Operands: 

OperandDescription
condition1-bit signless integer
trueDestOperandsany type
falseDestOperandsany type

Successors: 

SuccessorDescription
trueDestany successor
falseDestany successor

std.constant (ConstantOp) 

constant

Syntax:

operation ::= ssa-id `=` `std.constant` attribute-value `:` type

The constant operation produces an SSA value equal to some constant specified by an attribute. This is the way that MLIR uses to form simple integer and floating point constants, as well as more exotic things like references to functions and tensor/vector constants.

Example:

// Integer constant
%1 = constant 42 : i32

// Reference to function @myfn.
%3 = constant @myfn : (tensor<16xf32>, f32) -> tensor<16xf32>

// Equivalent generic forms
%1 = "std.constant"() {value = 42 : i32} : () -> i32
%3 = "std.constant"() {value = @myfn}
   : () -> ((tensor<16xf32>, f32) -> tensor<16xf32>)

MLIR does not allow direct references to functions in SSA operands because the compiler is multithreaded, and disallowing SSA values to directly reference a function simplifies this ( rationale ).

Attributes: 

AttributeMLIR TypeDescription
value::mlir::Attributeany attribute

Results: 

ResultDescription
«unnamed»any type

std.copysign (CopySignOp) 

A copysign operation

Syntax:

operation ::= ssa-id `=` `std.copysign` ssa-use `,` ssa-use `:` type

The copysign returns a value with the magnitude of the first operand and the sign of the second operand. It takes two operands and returns one result of the same type. This type may be a float scalar type, a vector whose element type is float, or a tensor of floats. It has no standard attributes.

Example:

// Scalar copysign value.
%a = copysign %b, %c : f64

// SIMD vector element-wise copysign value.
%f = copysign %g, %h : vector<4xf32>

// Tensor element-wise copysign value.
%x = copysign %y, %z : tensor<4x?xf8>

Operands: 

OperandDescription
lhsfloating-point-like
rhsfloating-point-like

Results: 

ResultDescription
resultany type

std.divf (DivFOp) 

floating point division operation

Operands: 

OperandDescription
lhsfloating-point-like
rhsfloating-point-like

Results: 

ResultDescription
resultany type

std.fpext (FPExtOp) 

cast from floating-point to wider floating-point

Cast a floating-point value to a larger floating-point-typed value. The destination type must to be strictly wider than the source type. Only scalars are currently supported.

Operands: 

OperandDescription
inany type

Results: 

ResultDescription
«unnamed»any type

std.fptosi (FPToSIOp) 

cast from floating-point type to integer type

Cast from a value interpreted as floating-point to the nearest (rounding towards zero) signed integer value.

Operands: 

OperandDescription
inany type

Results: 

ResultDescription
«unnamed»any type

std.fptoui (FPToUIOp) 

cast from floating-point type to integer type

Cast from a value interpreted as floating-point to the nearest (rounding towards zero) unsigned integer value.

Operands: 

OperandDescription
inany type

Results: 

ResultDescription
«unnamed»any type

std.fptrunc (FPTruncOp) 

cast from floating-point to narrower floating-point

Truncate a floating-point value to a smaller floating-point-typed value. The destination type must be strictly narrower than the source type. If the value cannot be exactly represented, it is rounded using the default rounding mode. Only scalars are currently supported.

Operands: 

OperandDescription
inany type

Results: 

ResultDescription
«unnamed»any type

std.floorf (FloorFOp) 

floor of the specified value

Syntax:

operation ::= ssa-id `=` `std.floorf` ssa-use `:` type

The floorf operation computes the floor of a given value. It takes one operand and returns one result of the same type. This type may be a float scalar type, a vector whose element type is float, or a tensor of floats. It has no standard attributes.

Example:

// Scalar floor value.
%a = floorf %b : f64

// SIMD vector element-wise floor value.
%f = floorf %g : vector<4xf32>

// Tensor element-wise floor value.
%x = floorf %y : tensor<4x?xf8>

Operands: 

OperandDescription
operandfloating-point-like

Results: 

ResultDescription
«unnamed»any type

std.fmaf (FmaFOp) 

floating point fused multipy-add operation

Syntax:

operation ::= ssa-id `=` `std.fmaf` ssa-use `,` ssa-use `,` ssa-use `:` type

The fmaf operation takes three operands and returns one result, each of these is required to be the same type. This type may be a floating point scalar type, a vector whose element type is a floating point type, or a floating point tensor.

Example:

// Scalar fused multiply-add: d = a*b + c
%d = fmaf %a, %b, %c : f64

// SIMD vector fused multiply-add, e.g. for Intel SSE.
%i = fmaf %f, %g, %h : vector<4xf32>

// Tensor fused multiply-add.
%w = fmaf %x, %y, %z : tensor<4x?xbf16>

The semantics of the operation correspond to those of the llvm.fma intrinsic . In the particular case of lowering to LLVM, this is guaranteed to lower to the llvm.fma.* intrinsic.

Operands: 

OperandDescription
afloating-point-like
bfloating-point-like
cfloating-point-like

Results: 

ResultDescription
resultany type

std.generic_atomic_rmw (GenericAtomicRMWOp) 

atomic read-modify-write operation with a region

The generic_atomic_rmw operation provides a way to perform a read-modify-write sequence that is free from data races. The memref operand represents the buffer that the read and write will be performed against, as accessed by the specified indices. The arity of the indices is the rank of the memref. The result represents the latest value that was stored. The region contains the code for the modification itself. The entry block has a single argument that represents the value stored in memref[indices] before the write is performed. No side-effecting ops are allowed in the body of GenericAtomicRMWOp.

Example:

%x = generic_atomic_rmw %I[%i] : memref<10xf32> {
  ^bb0(%current_value : f32):
    %c1 = constant 1.0 : f32
    %inc = addf %c1, %current_value : f32
    atomic_yield %inc : f32
}

Operands: 

OperandDescription
memrefmemref of signless integer or floating-point values
indicesindex

Results: 

ResultDescription
resultsignless integer or floating-point

std.index_cast (IndexCastOp) 

cast between index and integer types

Casts between integer scalars and ‘index’ scalars. Index is an integer of platform-specific bit width. If casting to a wider integer, the value is sign-extended. If casting to a narrower integer, the value is truncated.

Operands: 

OperandDescription
inany type

Results: 

ResultDescription
«unnamed»any type

std.mulf (MulFOp) 

floating point multiplication operation

Syntax:

operation ::= ssa-id `=` `std.mulf` ssa-use `,` ssa-use `:` type

The mulf operation takes two operands and returns one result, each of these is required to be the same type. This type may be a floating point scalar type, a vector whose element type is a floating point type, or a floating point tensor.

Example:

// Scalar multiplication.
%a = mulf %b, %c : f64

// SIMD pointwise vector multiplication, e.g. for Intel SSE.
%f = mulf %g, %h : vector<4xf32>

// Tensor pointwise multiplication.
%x = mulf %y, %z : tensor<4x?xbf16>

TODO: In the distant future, this will accept optional attributes for fast math, contraction, rounding mode, and other controls.

Operands: 

OperandDescription
lhsfloating-point-like
rhsfloating-point-like

Results: 

ResultDescription
resultany type

std.muli (MulIOp) 

integer multiplication operation

Operands: 

OperandDescription
lhssignless-integer-like
rhssignless-integer-like

Results: 

ResultDescription
resultany type

std.negf (NegFOp) 

floating point negation

Syntax:

operation ::= ssa-id `=` `negf` ssa-use `:` type

The negf operation computes the negation of a given value. It takes one operand and returns one result of the same type. This type may be a float scalar type, a vector whose element type is float, or a tensor of floats. It has no standard attributes.

Example:

// Scalar negation value.
%a = negf %b : f64

// SIMD vector element-wise negation value.
%f = negf %g : vector<4xf32>

// Tensor element-wise negation value.
%x = negf %y : tensor<4x?xf8>

Operands: 

OperandDescription
operandfloating-point-like

Results: 

ResultDescription
«unnamed»any type

std.or (OrOp) 

integer binary or

Syntax:

operation ::= ssa-id `=` `or` ssa-use `,` ssa-use `:` type

The or operation takes two operands and returns one result, each of these is required to be the same type. This type may be an integer scalar type, a vector whose element type is integer, or a tensor of integers. It has no standard attributes.

Example:

// Scalar integer bitwise or.
%a = or %b, %c : i64

// SIMD vector element-wise bitwise integer or.
%f = or %g, %h : vector<4xi32>

// Tensor element-wise bitwise integer or.
%x = or %y, %z : tensor<4x?xi8>

Operands: 

OperandDescription
lhssignless-integer-like
rhssignless-integer-like

Results: 

ResultDescription
resultany type

std.rank (RankOp) 

rank operation

Syntax:

operation ::= `std.rank` $memrefOrTensor attr-dict `:` type($memrefOrTensor)

The rank operation takes a memref/tensor operand and returns its rank.

Example:

%1 = rank %arg0 : tensor<*xf32>
%2 = rank %arg1 : memref<*xf32>

Operands: 

OperandDescription
memrefOrTensorany memref or tensor type

Results: 

ResultDescription
«unnamed»index

std.remf (RemFOp) 

floating point division remainder operation

Operands: 

OperandDescription
lhsfloating-point-like
rhsfloating-point-like

Results: 

ResultDescription
resultany type

std.return (ReturnOp) 

return operation

Syntax:

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

The return operation represents a return operation within a function. The operation takes variable number of operands and produces no results. The operand number and types must match the signature of the function that contains the operation.

Example:

func @foo() : (i32, f8) {
  ...
  return %0, %1 : i32, f8
}

Operands: 

OperandDescription
operandsany type

std.sitofp (SIToFPOp) 

cast from integer type to floating-point

Cast from a value interpreted as signed or vector of signed integers to the corresponding floating-point scalar or vector value. If the value cannot be exactly represented, it is rounded using the default rounding mode. Scalars and vector types are currently supported.

Operands: 

OperandDescription
inany type

Results: 

ResultDescription
«unnamed»any type

std.select (SelectOp) 

select operation

The select operation chooses one value based on a binary condition supplied as its first operand. If the value of the first operand is 1, the second operand is chosen, otherwise the third operand is chosen. The second and the third operand must have the same type.

The operation applies to vectors and tensors elementwise given the shape of all operands is identical. The choice is made for each element individually based on the value at the same position as the element in the condition operand. If an i1 is provided as the condition, the entire vector or tensor is chosen.

The select operation combined with cmpi can be used to implement min and max with signed or unsigned comparison semantics.

Example:

// Custom form of scalar selection.
%x = select %cond, %true, %false : i32

// Generic form of the same operation.
%x = "std.select"(%cond, %true, %false) : (i1, i32, i32) -> i32

// Element-wise vector selection.
%vx = std.select %vcond, %vtrue, %vfalse : vector<42xi1>, vector<42xf32>

// Full vector selection.
%vx = std.select %cond, %vtrue, %vfalse : vector<42xf32>

Operands: 

OperandDescription
conditionbool-like
true_valueany type
false_valueany type

Results: 

ResultDescription
resultany type

std.shift_left (ShiftLeftOp) 

integer left-shift

The shift_left operation shifts an integer value to the left by a variable amount. The low order bits are filled with zeros.

Example:

%1 = constant 5 : i8                       // %1 is 0b00000101
%2 = constant 3 : i8
%3 = shift_left %1, %2 : (i8, i8) -> i8    // %3 is 0b00101000

Operands: 

OperandDescription
lhssignless-integer-like
rhssignless-integer-like

Results: 

ResultDescription
resultany type

std.sexti (SignExtendIOp) 

integer sign extension operation

The integer sign extension operation takes an integer input of width M and an integer destination type of width N. The destination bit-width must be larger than the input bit-width (N > M). The top-most (N - M) bits of the output are filled with copies of the most-significant bit of the input.

Example:

%1 = constant 5 : i3            // %1 is 0b101
%2 = sexti %1 : i3 to i6        // %2 is 0b111101
%3 = constant 2 : i3            // %3 is 0b010
%4 = sexti %3 : i3 to i6        // %4 is 0b000010

%5 = sexti %0 : vector<2 x i32> to vector<2 x i64>

Operands: 

OperandDescription
valuesignless-integer-like

Results: 

ResultDescription
«unnamed»signless-integer-like

std.ceildivi_signed (SignedCeilDivIOp) 

signed ceil integer division operation

Syntax:

operation ::= ssa-id `=` `ceildivi_signed` ssa-use `,` ssa-use `:` type

Signed integer division. Rounds towards positive infinity, i.e. 7 / -2 = -3.

Note: the semantics of division by zero or signed division overflow (minimum value divided by -1) is TBD; do NOT assume any specific behavior.

Example:

// Scalar signed integer division.
%a = ceildivi_signed %b, %c : i64

Operands: 

OperandDescription
lhssignless-integer-like
rhssignless-integer-like

Results: 

ResultDescription
resultany type

std.divi_signed (SignedDivIOp) 

signed integer division operation

Syntax:

operation ::= ssa-id `=` `divi_signed` ssa-use `,` ssa-use `:` type

Signed integer division. Rounds towards zero. Treats the leading bit as sign, i.e. 6 / -2 = -3.

Note: the semantics of division by zero or signed division overflow (minimum value divided by -1) is TBD; do NOT assume any specific behavior.

Example:

// Scalar signed integer division.
%a = divis %b, %c : i64

// SIMD vector element-wise division.
%f = divis %g, %h : vector<4xi32>

// Tensor element-wise integer division.
%x = divis %y, %z : tensor<4x?xi8>

Operands: 

OperandDescription
lhssignless-integer-like
rhssignless-integer-like

Results: 

ResultDescription
resultany type

std.floordivi_signed (SignedFloorDivIOp) 

signed floor integer division operation

Syntax:

operation ::= ssa-id `=` `floordivi_signed` ssa-use `,` ssa-use `:` type

Signed integer division. Rounds towards negative infinity, i.e. 5 / -2 = -3.

Note: the semantics of division by zero or signed division overflow (minimum value divided by -1) is TBD; do NOT assume any specific behavior.

Example:

// Scalar signed integer division.
%a = floordivi_signed %b, %c : i64

Operands: 

OperandDescription
lhssignless-integer-like
rhssignless-integer-like

Results: 

ResultDescription
resultany type

std.remi_signed (SignedRemIOp) 

signed integer division remainder operation

Syntax:

operation ::= ssa-id `=` `std.remi_signed` ssa-use `,` ssa-use `:` type

Signed integer division remainder. Treats the leading bit as sign, i.e. 6 % -2 = 0.

Note: the semantics of division by zero is TBD; do NOT assume any specific behavior.

Example:

// Scalar signed integer division remainder.
%a = remis %b, %c : i64

// SIMD vector element-wise division remainder.
%f = remis %g, %h : vector<4xi32>

// Tensor element-wise integer division remainder.
%x = remis %y, %z : tensor<4x?xi8>

Operands: 

OperandDescription
lhssignless-integer-like
rhssignless-integer-like

Results: 

ResultDescription
resultany type

std.shift_right_signed (SignedShiftRightOp) 

signed integer right-shift

The shift_right_signed operation shifts an integer value to the right by a variable amount. The integer is interpreted as signed. The high order bits in the output are filled with copies of the most-significant bit of the shifted value (which means that the sign of the value is preserved).

Example:

%1 = constant 160 : i8                             // %1 is 0b10100000
%2 = constant 3 : i8
%3 = shift_right_signed %1, %2 : (i8, i8) -> i8    // %3 is 0b11110100
%4 = constant 96 : i8                              // %4 is 0b01100000
%5 = shift_right_signed %4, %2 : (i8, i8) -> i8    // %5 is 0b00001100

Operands: 

OperandDescription
lhssignless-integer-like
rhssignless-integer-like

Results: 

ResultDescription
resultany type

std.splat (SplatOp) 

splat or broadcast operation

Syntax:

operation ::= `std.splat` $input attr-dict `:` type($aggregate)

Broadcast the operand to all elements of the result vector or tensor. The operand has to be of integer/index/float type. When the result is a tensor, it has to be statically shaped.

Example:

%s = load %A[%i] : memref<128xf32>
%v = splat %s : vector<4xf32>
%t = splat %s : tensor<8x16xi32>

TODO: This operation is easy to extend to broadcast to dynamically shaped tensors in the same way dynamically shaped memrefs are handled.

// Broadcasts %s to a 2-d dynamically shaped tensor, with %m, %n binding
// to the sizes of the two dynamic dimensions.
%m = "foo"() : () -> (index)
%n = "bar"() : () -> (index)
%t = splat %s [%m, %n] : tensor<?x?xi32>

Operands: 

OperandDescription
inputinteger/index/float type

Results: 

ResultDescription
aggregatevector of any type values or statically shaped tensor of any type values

std.subf (SubFOp) 

floating point subtraction operation

Operands: 

OperandDescription
lhsfloating-point-like
rhsfloating-point-like

Results: 

ResultDescription
resultany type

std.subi (SubIOp) 

integer subtraction operation

Operands: 

OperandDescription
lhssignless-integer-like
rhssignless-integer-like

Results: 

ResultDescription
resultany type

std.subtensor_insert (SubTensorInsertOp) 

subtensor_insert operation

Syntax:

operation ::= `std.subtensor_insert` $source `into` $dest ``
              custom<OperandsOrIntegersOffsetsOrStridesList>($offsets, $static_offsets)
              custom<OperandsOrIntegersSizesList>($sizes, $static_sizes)
              custom<OperandsOrIntegersOffsetsOrStridesList>($strides, $static_strides)
              attr-dict `:` type($source) `into` type($dest)

The “subtensor_insert” operation insert a tensor source into another tensor dest as specified by the operation’s offsets, sizes and strides arguments.

It returns a copy of dest with the proper subtensor updated with the value of source.

The subtensor_insert operation has the encodes the following information:

  • source: the tensor that is inserted.
  • dest: the tensor into which the source tensor is inserted.
  • offsets: tensor-rank number of offsets into the “base” tensor from which to extract the subtensor.
  • sizes: tensor-rank number of sizes which specify the sizes of the result tensor type.
  • strides: tensor-rank number of strides that specify subsampling in each dimension.

The representation based on offsets, sizes and strides support a partially-static specification via attributes specified through the static_offsets, static_sizes and static_strides arguments. A special sentinel value ShapedType::kDynamicSize and ShapedType::kDynamicStrideOrOffset encodes that the corresponding entry has a dynamic value.

After buffer-allocation, the “subtensor_insert” op is expected to become an in-place buffer update.

Attributes: 

AttributeMLIR TypeDescription
static_offsets::mlir::ArrayAttr64-bit integer array attribute
static_sizes::mlir::ArrayAttr64-bit integer array attribute
static_strides::mlir::ArrayAttr64-bit integer array attribute

Operands: 

OperandDescription
sourceranked tensor of any type values
destranked tensor of any type values
offsetsindex
sizesindex
stridesindex

Results: 

ResultDescription
resultranked tensor of any type values

std.subtensor (SubTensorOp) 

subtensor operation

Syntax:

operation ::= `std.subtensor` $source ``
              custom<OperandsOrIntegersOffsetsOrStridesList>($offsets, $static_offsets)
              custom<OperandsOrIntegersSizesList>($sizes, $static_sizes)
              custom<OperandsOrIntegersOffsetsOrStridesList>($strides, $static_strides)
              attr-dict `:` type($source) `to` type($result)

The “subtensor” operation extract a tensor from another tensor as specified by the operation’s offsets, sizes and strides arguments.

The subtensor operation supports the following arguments:

  • source: the “base” tensor from which to extract a subtensor.
  • offsets: tensor-rank number of offsets into the “base” tensor from which to extract the subtensor.
  • sizes: tensor-rank number of sizes which specify the sizes of the result tensor type.
  • strides: tensor-rank number of strides specifying subsampling in each dimension.

The representation based on offsets, sizes and strides support a partially-static specification via attributes specified through the static_offsets, static_sizes and static_strides arguments. A special sentinel value ShapedType::kDynamicSize and ShapedType::kDynamicStrideOrOffset encodes that the corresponding entry has a dynamic value.

After buffer-allocation, the “subtensor” op is expected to lower into a “subview” op.

A subtensor operation may additionally reduce the rank of the resulting tensor by removing dimensions that are statically known to be of size 1.

Example:

// Rank-reducing subtensor.
%1 = subtensor %0[0, 0, 0][1, 16, 4][1, 1, 1] :
  tensor<8x16x4xf32> to tensor<16x4xf32>
%3 = subtensor %2[3, 4, 2][1, 6, 3][1, 1, 1] :
  tensor<8x16x4xf32> to tensor<6x3xf32>

Attributes: 

AttributeMLIR TypeDescription
static_offsets::mlir::ArrayAttr64-bit integer array attribute
static_sizes::mlir::ArrayAttr64-bit integer array attribute
static_strides::mlir::ArrayAttr64-bit integer array attribute

Operands: 

OperandDescription
sourceranked tensor of any type values
offsetsindex
sizesindex
stridesindex

Results: 

ResultDescription
resultranked tensor of any type values

std.trunci (TruncateIOp) 

integer truncation operation

The integer truncation operation takes an integer input of width M and an integer destination type of width N. The destination bit-width must be smaller than the input bit-width (N < M). The top-most (N - M) bits of the input are discarded.

Example:

  %1 = constant 21 : i5           // %1 is 0b10101
  %2 = trunci %1 : i5 to i4       // %2 is 0b0101
  %3 = trunci %1 : i5 to i3       // %3 is 0b101

  %5 = trunci %0 : vector<2 x i32> to vector<2 x i16>

Operands: 

OperandDescription
valuesignless-integer-like

Results: 

ResultDescription
«unnamed»signless-integer-like

std.uitofp (UIToFPOp) 

cast from unsigned integer type to floating-point

Cast from a value interpreted as unsigned integer or vector of unsigned integers to the corresponding scalar or vector floating-point value. If the value cannot be exactly represented, it is rounded using the default rounding mode. Scalars and vector types are currently supported.

Operands: 

OperandDescription
inany type

Results: 

ResultDescription
«unnamed»any type

std.divi_unsigned (UnsignedDivIOp) 

unsigned integer division operation

Syntax:

operation ::= ssa-id `=` `std.divi_unsigned` ssa-use `,` ssa-use `:` type

Unsigned integer division. Rounds towards zero. Treats the leading bit as the most significant, i.e. for i16 given two’s complement representation, 6 / -2 = 6 / (2^16 - 2) = 0.

Note: the semantics of division by zero is TBD; do NOT assume any specific behavior.

Example:

// Scalar unsigned integer division.
%a = diviu %b, %c : i64

// SIMD vector element-wise division.
%f = diviu %g, %h : vector<4xi32>

// Tensor element-wise integer division.
%x = diviu %y, %z : tensor<4x?xi8>

Operands: 

OperandDescription
lhssignless-integer-like
rhssignless-integer-like

Results: 

ResultDescription
resultany type

std.remi_unsigned (UnsignedRemIOp) 

unsigned integer division remainder operation

Syntax:

operation ::= ssa-id `=` `std.remi_unsigned` ssa-use `,` ssa-use `:` type

Unsigned integer division remainder. Treats the leading bit as the most significant, i.e. for i16, 6 % -2 = 6 % (2^16 - 2) = 6.

Note: the semantics of division by zero is TBD; do NOT assume any specific behavior.

Example:

// Scalar unsigned integer division remainder.
%a = remiu %b, %c : i64

// SIMD vector element-wise division remainder.
%f = remiu %g, %h : vector<4xi32>

// Tensor element-wise integer division remainder.
%x = remiu %y, %z : tensor<4x?xi8>

Operands: 

OperandDescription
lhssignless-integer-like
rhssignless-integer-like

Results: 

ResultDescription
resultany type

std.shift_right_unsigned (UnsignedShiftRightOp) 

unsigned integer right-shift

The shift_right_unsigned operation shifts an integer value to the right by a variable amount. The integer is interpreted as unsigned. The high order bits are always filled with zeros.

Example:

%1 = constant 160 : i8                               // %1 is 0b10100000
%2 = constant 3 : i8
%3 = shift_right_unsigned %1, %2 : (i8, i8) -> i8    // %3 is 0b00010100

Operands: 

OperandDescription
lhssignless-integer-like
rhssignless-integer-like

Results: 

ResultDescription
resultany type

std.xor (XOrOp) 

integer binary xor

The xor operation takes two operands and returns one result, each of these is required to be the same type. This type may be an integer scalar type, a vector whose element type is integer, or a tensor of integers. It has no standard attributes.

Example:

// Scalar integer bitwise xor.
%a = xor %b, %c : i64

// SIMD vector element-wise bitwise integer xor.
%f = xor %g, %h : vector<4xi32>

// Tensor element-wise bitwise integer xor.
%x = xor %y, %z : tensor<4x?xi8>

Operands: 

OperandDescription
lhssignless-integer-like
rhssignless-integer-like

Results: 

ResultDescription
resultany type

std.zexti (ZeroExtendIOp) 

integer zero extension operation

The integer zero extension operation takes an integer input of width M and an integer destination type of width N. The destination bit-width must be larger than the input bit-width (N > M). The top-most (N - M) bits of the output are filled with zeros.

Example:

  %1 = constant 5 : i3            // %1 is 0b101
  %2 = zexti %1 : i3 to i6        // %2 is 0b000101
  %3 = constant 2 : i3            // %3 is 0b010
  %4 = zexti %3 : i3 to i6        // %4 is 0b000010

  %5 = zexti %0 : vector<2 x i32> to vector<2 x i64>

Operands: 

OperandDescription
valuesignless-integer-like

Results: 

ResultDescription
«unnamed»signless-integer-like