llvm-project/mlir/docs/ConversionToLLVMDialect.md

# Conversion to the LLVM Dialect

Conversion from several dialects that rely on
[built-in types](LangRef.md/#builtin-types) to the
[LLVM Dialect](Dialects/LLVM.md) is expected to be performed through the
[Dialect Conversion](DialectConversion.md) infrastructure.

The conversion of types and that of the overall module structure is described in
this document. Individual conversion passes provide a set of conversion patterns
for ops in different dialects, such as `-convert-std-to-llvm` for ops in the
[Standard dialect](Dialects/Standard.md) and `-convert-vector-to-llvm` in the
[Vector dialect](Dialects/Vector.md). *Note that some conversions subsume the
others.*

We use the terminology defined by the
[LLVM Dialect description](Dialects/LLVM.md) throughout this document.

[TOC]

## Type Conversion

### Scalar Types

Scalar types are converted to their LLVM counterparts if they exist. The
following conversions are currently implemented:

-   `i*` converts to `!llvm.i*`
-   `bf16` converts to `bf16`
-   `f16` converts to `f16`
-   `f32` converts to `f32`
-   `f64` converts to `f64`
-   `f80` converts to `f80`
-   `f128` converts to `f128`

### Index Type

Index type is converted to an LLVM dialect integer type with bitwidth equal to
the bitwidth of the pointer size as specified by the
[data layout](Dialects/LLVM.md/#data-layout-and-triple) of the closest module.
For example, on x86-64 CPUs it converts to `i64`. This behavior can be
overridden by the type converter configuration, which is often exposed as a pass
option by conversion passes.

### Vector Types

LLVM IR only supports *one-dimensional* vectors, unlike MLIR where vectors can
be multi-dimensional. Vector types cannot be nested in either IR. In the
one-dimensional case, MLIR vectors are converted to LLVM IR vectors of the same
size with element type converted using these conversion rules. In the
n-dimensional case, MLIR vectors are converted to (n-1)-dimensional array types
of one-dimensional vectors.

For example, `vector<4xf32>` converts to `vector<4xf32>` and `vector<4 x 8 x 16
x f32>` converts to `!llvm.array<4 x array<8 x vec<16 x f32>>>`.

### Ranked Memref Types

Memref types in MLIR have both static and dynamic information associated with
them. In the general case, the dynamic information describes dynamic sizes in
the logical indexing space and any symbols bound to the memref. This dynamic
information must be present at runtime in the LLVM dialect equivalent type.

In practice, the conversion supports two conventions:

-   the default convention for memrefs in the
    **[strided form](Dialects/Builtin.md/#strided-memref)**;
-   a "bare pointer" conversion for statically-shaped memrefs with default
    layout.

The choice between conventions is specified at type converter construction time
and is often exposed as an option by conversion passes.

Memrefs with arbitrary layouts are not supported. Instead, these layouts can be
factored out of the type and used as part of index computation for operations
that read and write into a memref with the default layout.

#### Default Convention

The dynamic information comprises the buffer pointer as well as sizes and
strides of any dynamically-sized dimensions. Memref types are normalized and
converted to a _descriptor_ that is only dependent on the rank of the memref.
The descriptor contains the following fields in order:

1.  The pointer to the data buffer as allocated, referred to as "allocated
    pointer". This is only useful for deallocating the memref.
2.  The pointer to the properly aligned data pointer that the memref indexes,
    referred to as "aligned pointer".
3.  A lowered converted `index`-type integer containing the distance in number
    of elements between the beginning of the (aligned) buffer and the first
    element to be accessed through the memref, referred to as "offset".
4.  An array containing as many converted `index`-type integers as the rank of
    the memref: the array represents the size, in number of elements, of the
    memref along the given dimension. For constant memref dimensions, the
    corresponding size entry is a constant whose runtime value must match the
    static value.
5.  A second array containing as many converted `index`-type integers as the
    rank of memref: the second array represents the "stride" (in tensor
    abstraction sense), i.e. the number of consecutive elements of the
    underlying buffer one needs to jump over to get to the next logically
    indexed element.

For constant memref dimensions, the corresponding size entry is a constant whose
runtime value matches the static value. This normalization serves as an ABI for
the memref type to interoperate with externally linked functions. In the
particular case of rank `0` memrefs, the size and stride arrays are omitted,
resulting in a struct containing two pointers + offset.

Examples:

```mlir
memref<f32> -> !llvm.struct<(ptr<f32> , ptr<f32>, i64)>
memref<1 x f32> -> !llvm.struct<(ptr<f32>, ptr<f32>, i64,
                                 array<1 x 64>, array<1 x i64>)>
memref<? x f32> -> !llvm.struct<(ptr<f32>, ptr<f32>, i64
                                 array<1 x 64>, array<1 x i64>)>
memref<10x42x42x43x123 x f32> -> !llvm.struct<(ptr<f32>, ptr<f32>, i64
                                               array<5 x 64>, array<5 x i64>)>
memref<10x?x42x?x123 x f32> -> !llvm.struct<(ptr<f32>, ptr<f32>, i64
                                             array<5 x 64>, array<5 x i64>)>

// Memref types can have vectors as element types
memref<1x? x vector<4xf32>> -> !llvm.struct<(ptr<vec<4 x f32>>,
                                             ptr<vec<4 x float>>, i64,
                                             array<1 x i64>, array<1 x i64>)>
```

#### Bare Pointer Convention

Ranked memrefs with static shape and default layout can be converted into an
LLVM dialect pointer to their element type. Only the default alignment is
supported in such cases, e.g. the `alloc` operation cannot have an alignment
attribute.

Examples:

```mlir
memref<f32> -> !llvm.ptr<f32>
memref<10x42 x f32> -> !llvm.ptr<f32>

// Memrefs with vector types are also supported.
memref<10x42 x vector<4xf32>> -> !llvm.ptr<vec<4 x f32>>
```

### Unranked Memref types

Unranked memrefs are converted to an unranked descriptor that contains:

1.  a converted `index`-typed integer representing the dynamic rank of the
    memref;
2.  a type-erased pointer (`!llvm.ptr<i8>`) to a ranked memref descriptor with
    the contents listed above.

This descriptor is primarily intended for interfacing with rank-polymorphic
library functions. The pointer to the ranked memref descriptor points to memory
_allocated on stack_ of the function in which it is used.

Note that stack allocations may be emitted at a location where the unranked
memref first appears, e.g., a cast operation, and remain live throughout the
lifetime of the function; this may lead to stack exhaustion if used in a loop.

Examples:

```mlir
// Unranked descriptor.
memref<*xf32> -> !llvm.struct<(i64, ptr<i8>)>
```

Bare pointer convention does not support unranked memrefs.

### Function Types

Function types get converted to LLVM dialect function types. The arguments are
converted individually according to these rules, except for `memref` types in
function arguments and high-order functions, which are described below. The
result types need to accommodate the fact that LLVM functions always have a
return type, which may be an `!llvm.void` type. The converted function always
has a single result type. If the original function type had no results, the
converted function will have one result of the `!llvm.void` type. If the
original function type had one result, the converted function will also have one
result converted using these rules. Otherwise, the result type will be an LLVM
dialect structure type where each element of the structure corresponds to one of
the results of the original function, converted using these rules.

Examples:

```mlir
// Zero-ary function type with no results:
() -> ()
// is converted to a zero-ary function with `void` result.
!llvm.func<void ()>

// Unary function with one result:
(i32) -> (i64)
// has its argument and result type converted, before creating the LLVM dialect
// function type.
!llvm.func<i64 (i32)>

// Binary function with one result:
(i32, f32) -> (i64)
// has its arguments handled separately
!llvm.func<i64 (i32, f32)>

// Binary function with two results:
(i32, f32) -> (i64, f64)
// has its result aggregated into a structure type.
!llvm.func<struct<(i64, f64)> (i32, f32)>
```

#### Functions as Function Arguments or Results

High-order function types, i.e. types of functions that have other functions as
arguments or results, are converted differently to accommodate the fact that
LLVM IR does not allow for function-typed values. Instead, functions are
expected to be passed into and return from other functions _by pointer_.
Therefore, function-typed function arguments are results are converted to
pointer-to-the-function type. The pointee type is converted using these rules.

Examples:

```mlir
// Function-typed arguments or results in higher-order functions:
(() -> ()) -> (() -> ())
// are converted into pointers to functions.
!llvm.func<ptr<func<void ()>> (ptr<func<void ()>>)>

// These rules apply recursively: a function type taking a function that takes
// another function
( ( (i32) -> (i64) ) -> () ) -> ()
// is converted into a function type taking a pointer-to-function that takes
// another point-to-function.
!llvm.func<void (ptr<func<void (ptr<func<i64 (i32)>>)>>)>
```

#### Memrefs as Function Arguments

When used as function arguments, both ranked and unranked memrefs are converted
into a list of arguments that represents each _scalar_ component of their
descriptor. This is intended for some compatibility with C ABI, in which
structure types would need to be passed by-pointer leading to the need for
allocations and related issues, as well as for aliasing annotations, which are
currently attached to pointer in function arguments. Having scalar components
means that each size and stride is passed as an individual value.

When used as function results, memrefs are converted as usual, i.e. each memref
is converted to a descriptor struct (default convention) or to a pointer (bare
pointer convention).

Examples:

```mlir
// A memref descriptor appearing as function argument:
(memref<f32>) -> ()
// gets converted into a list of individual scalar components of a descriptor.
!llvm.func<void (ptr<f32>, ptr<f32>, i64)>

// The list of arguments is linearized and one can freely mix memref and other
// types in this list:
(memref<f32>, f32) -> ()
// which gets converted into a flat list.
!llvm.func<void (ptr<f32>, ptr<f32>, i64, f32)>

// For nD ranked memref descriptors:
(memref<?x?xf32>) -> ()
// the converted signature will contain 2n+1 `index`-typed integer arguments,
// offset, n sizes and n strides, per memref argument type.
!llvm.func<void (ptr<f32>, ptr<f32>, i64, i64, i64, i64, i64)>

// Same rules apply to unranked descriptors:
(memref<*xf32>) -> ()
// which get converted into their components.
!llvm.func<void (i64, ptr<i8>)>

// However, returning a memref from a function is not affected:
() -> (memref<?xf32>)
// gets converted to a function returning a descriptor structure.
!llvm.func<struct<(ptr<f32>, ptr<f32>, i64, array<1xi64>, array<1xi64>)> ()>

// If multiple memref-typed results are returned:
() -> (memref<f32>, memref<f64>)
// their descriptor structures are additionally packed into another structure,
// potentially with other non-memref typed results.
!llvm.func<struct<(struct<(ptr<f32>, ptr<f32>, i64)>,
                   struct<(ptr<double>, ptr<double>, i64)>)> ()>
```