27 Dialect Conversion
Dialect conversion is MLIR’s framework for changing one IR vocabulary into another while enforcing a legality boundary. It is used for lowering, raising, legalization, and migrations where ordinary greedy rewriting is not enough.
27.1 Conversion Starts With A Target
A ConversionTarget classifies operations and sometimes types as legal, illegal, or dynamically legal. The target is the postcondition: after conversion, no illegal IR may remain. This differs from canonicalization, which may leave a valid operation unchanged because no preferred rewrite applies.
A target can say that an entire dialect is legal, that one operation is illegal, or that legality depends on an attribute or type. Dynamic legality is powerful but must be precise; a vague predicate makes it difficult to know whether the pipeline has actually reached its intended representation.
27.2 Patterns Rewrite Under A Type Mapping
Conversion patterns receive operands that have already been adapted according to a TypeConverter. They create legal replacement operations using converted types, and the framework manages value mappings and materializations where permitted. A conversion pattern is therefore not a normal rewrite pattern with a different name: it operates under a global representation change.
For example, a tensor-to-buffer conversion may turn a tensor result into a memref-like representation. Every user must be converted or bridged by an explicit materialization. Rewriting only the producer leaves a type boundary the rest of the IR cannot consume.
27.3 Partial And Full Conversion
Full conversion fails if any illegal operation remains. Partial conversion rewrites what it can and permits selected illegal operations to remain; this is useful in staged pipelines but requires a clear later pass that owns the remaining boundary. Analysis conversion checks whether a conversion would succeed without mutating the IR.
Choose full conversion when the next stage requires a closed dialect set. Choose partial conversion only when mixed IR is an intentional, verified intermediate state. Accidental partial lowering is a common source of confusing later errors.
27.4 Materializations Are Semantics
Source, target, and argument materializations bridge old and new types at conversion boundaries. They are not free casts. Each one must mean something in the relevant dialects and must be legal to insert where the framework requests it. If no valid bridge exists, redesign the conversion order or rewrite the surrounding operation rather than inventing an unchecked cast.