1# 'memref' Dialect
2
3This dialect provides documentation for operations within the MemRef dialect.
4
5**Please post an RFC on the [forum](https://llvm.discourse.group/c/mlir/31)
6before adding or changing any operation in this dialect.**
7
8[TOC]
9
10## Operations
11
12[include "Dialects/MemRefOps.md"]
13
14### 'dma_start' operation
15
16Syntax:
17
18```
19operation ::= `memref.dma_start` ssa-use`[`ssa-use-list`]` `,`
20               ssa-use`[`ssa-use-list`]` `,` ssa-use `,`
21               ssa-use`[`ssa-use-list`]` (`,` ssa-use `,` ssa-use)?
22              `:` memref-type `,` memref-type `,` memref-type
23```
24
25Starts a non-blocking DMA operation that transfers data from a source memref to
26a destination memref. The operands include the source and destination memref's
27each followed by its indices, size of the data transfer in terms of the number
28of elements (of the elemental type of the memref), a tag memref with its
29indices, and optionally two additional arguments corresponding to the stride (in
30terms of number of elements) and the number of elements to transfer per stride.
31The tag location is used by a dma_wait operation to check for completion. The
32indices of the source memref, destination memref, and the tag memref have the
33same restrictions as any load/store operation in an affine context (whenever DMA
34operations appear in an affine context). See
35[restrictions on dimensions and symbols](Affine.md/#restrictions-on-dimensions-and-symbols)
36in affine contexts. This allows powerful static analysis and transformations in
37the presence of such DMAs including rescheduling, pipelining / overlap with
38computation, and checking for matching start/end operations. The source and
39destination memref need not be of the same dimensionality, but need to have the
40same elemental type.
41
42For example, a `memref.dma_start` operation that transfers 32 vector elements
43from a memref `%src` at location `[%i, %j]` to memref `%dst` at `[%k, %l]` would
44be specified as shown below.
45
46Example:
47
48```mlir
49%size = arith.constant 32 : index
50%tag = memref.alloc() : memref<1 x i32, affine_map<(d0) -> (d0)>, 4>
51%idx = arith.constant 0 : index
52memref.dma_start %src[%i, %j], %dst[%k, %l], %size, %tag[%idx] :
53     memref<40 x 8 x vector<16xf32>, affine_map<(d0, d1) -> (d0, d1)>, 0>,
54     memref<2 x 4 x vector<16xf32>, affine_map<(d0, d1) -> (d0, d1)>, 2>,
55     memref<1 x i32>, affine_map<(d0) -> (d0)>, 4>
56```
57
58### 'dma_wait' operation
59
60Syntax:
61
62```
63operation ::= `memref.dma_wait` ssa-use`[`ssa-use-list`]` `,` ssa-use `:` memref-type
64```
65
66Blocks until the completion of a DMA operation associated with the tag element
67specified with a tag memref and its indices. The operands include the tag memref
68followed by its indices and the number of elements associated with the DMA being
69waited on. The indices of the tag memref have the same restrictions as
70load/store indices.
71
72Example:
73
74```mlir
75memref.dma_wait %tag[%idx], %size : memref<1 x i32, affine_map<(d0) -> (d0)>, 4>
76```
77