Structured op contract

The contract

A structured op declares four things: its inputs (ins), its destinations (outs), an iterator type per loop dimension, and one indexing map per operand. The payload region takes one block argument per operand at the operand’s element type and yields one value per output. For matmul that is %a, %b, %c and a single linalg.yield.

Named and generic ops are two spellings of that contract. linalg.matmul fixes the maps, iterators and payload; linalg.generic writes them out. Both implement linalg::LinalgOp, so one pass handles either: getDpsInputs(), getDpsInits(), getIteratorTypesArray(), getIndexingMapsArray(), getNumLoops().

Outs are read-modify-write

outs is a destination, not a write-only result. linalg.matmul reads the current value of C and adds into it, which is why a call on an uninitialised buffer accumulates onto garbage. On tensors the op returns one result per destination; on memrefs it writes in place and returns nothing. The contract is the same and the memory model is not.

Iterator types

["parallel", "parallel", "reduction"] has one entry per loop dimension. Parallel dimensions may be reordered, split, or distributed. Reduction dimensions carry the accumulation and bound what reordering is legal. Passes read the declaration rather than deriving intent from the payload, so declaring k parallel is a claim you can make and a wrong answer you can get.

Things that break

A region whose argument count does not match the operand count fails verification with a signature error; a missing linalg.yield fails as a missing terminator. The subtle one is treating outs as write-only. Rewriting a linalg.matmul as a generic that ignores %c and yields only the product turns accumulation into overwrite, and no verifier objects, because the op is still well formed.