1//===- TilingInterface.td - Interface for tiling operations *- tablegen -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9// This file contains an interface to allow operations to generate a tiled
10// implementation of themselves.
11//
12//===----------------------------------------------------------------------===//
13
14#ifndef MLIR_TILINGINTERFACE
15#define MLIR_TILINGINTERFACE
16
17include "mlir/IR/OpBase.td"
18
19def TilingInterface : OpInterface<"TilingInterface"> {
20  let description = [{
21    Interface for allowing operations to expose information needed to
22    tile them (similar to LinalgOp, but without having access to
23    indexing maps)
24  }];
25  let cppNamespace = "::mlir";
26  let methods = [
27      InterfaceMethod<
28        /*desc=*/[{
29          Returns a list of operands into which the result of the
30          tiled implementation is written into. With `tensor`
31          operands, this will be used as the initial tensor into which
32          the tiled results are inserted into. With `memref` operands,
33          this will be the operand into which the result of the tiled
34          operation is written into.
35        }],
36        /*retType=*/"SmallVector<Value>",
37        /*methodName=*/"getDestinationOperands",
38        /*args=*/(ins "OpBuilder &":$b),
39        /*methodBody=*/"",
40        /*defaultImplementation=*/"return ValueRange{};"
41      >,
42      InterfaceMethod<
43        /*desc=*/[{
44          Returns a list of `StringRef`s that describe the number of
45          loops and the iterator types of the operation. The list is
46          expected to use
47          `getParallelIteratorTypeName()`/`getReductionIteratorTypeName()`
48          from MLIR Structured Op Utils.
49        }],
50        /*retType=*/"SmallVector<StringRef>",
51        /*methodName=*/"getLoopIteratorTypes",
52        /*args=*/(ins),
53        /*methodBody=*/"",
54        /*defaultImplementation=*/"return {};"
55      >,
56      InterfaceMethod<
57        /*desc=*/[{
58          Returns a list of ranges that describe the loop bounds and
59          step for the loops of the operation.
60        }],
61        /*retTy=*/"SmallVector<Range>",
62        /*methodName=*/"getIterationDomain",
63        /*args=*/(ins "OpBuilder &":$b),
64        /*methodBody=*/"",
65        /*defaultImplementation=*/"return {};"
66      >,
67      InterfaceMethod<
68        /*desc=*/[{
69          Method to generate the tiled implementation of an operation.
70
71          The iteration space of the operation is returned by
72          `getIterationDomain`. The caller provides the information of the
73          tile within this iteration space whose implementation the
74          caller needs.
75          - `dest` are the Value into which the result of the tiled
76            operation is to be inserted into. The type of the `dest`
77            Values is same as the types returned by
78            `getDestinationOperands` method.
79          - `offsets` provides the offset of the tile within the
80            iteration space
81          - `sizes` provides the size of the tile.
82          - `tileDestOperands` specifies whether to also tile `dest` operands
83            or not. Avoiding tiling `dest` operands can be useful for
84            composition with various looping container ops.
85
86          The method returns the operation that is the tiled
87          implementation.
88        }],
89        /*retType=*/"SmallVector<Operation *>",
90        /*methodName=*/"getTiledImplementation",
91        /*args=*/(ins
92            "OpBuilder &":$b,
93            "ValueRange ":$dest,
94            "ArrayRef<OpFoldResult> ":$offsets,
95            "ArrayRef<OpFoldResult> ":$sizes,
96            "bool ":$tileDestOperands),
97        /*methodBody=*/"",
98        /*defaultImplementation=*/[{
99          return {};
100        }]
101      >,
102      InterfaceMethod<
103        /*desc=*/[{
104          Method to return the position of the result tile computed by the tiled operation.
105
106          Specifies what tile of the result of the original tensor is computed
107          by the tiled implementation. Expects the same `offsets` and `sizes` as
108          used to obtain the tiled implementation of the operation.
109        }],
110        /*retType=*/"LogicalResult",
111        /*methodName=*/"getResultTilePosition",
112        /*args=*/(ins
113          "OpBuilder &":$b,
114          "unsigned":$resultNumber,
115          "ArrayRef<OpFoldResult> ":$offsets,
116          "ArrayRef<OpFoldResult> ":$sizes,
117          "SmallVector<OpFoldResult> &":$resultOffsets,
118          "SmallVector<OpFoldResult> &":$resultSizes),
119        /*methodBody=*/"",
120        /*defaultImplementation=*/[{
121          return failure();
122        }]
123      >,
124      InterfaceMethod<
125        /*desc=*/[{
126          Method to generate the code that produces a tile of the result.
127
128          Generates the IR that computes the tile of a result of the
129          operation.  The `offsets` and `sizes` describe the tile of
130          the output required. This is different from
131          `getTiledImplementation` which generates the tiled
132          implementation of the operation given a tile of the
133          iteration space. This method generates a tiled
134          implementation of the operation based on the tile of the
135          result required. This method enables fusion by using tile
136          and fuse. The method returns failure if the operation can't be
137          tiled to generate the result tile. In practical terms this
138          implies it cannot be tiled and fused with its consumers.
139
140          - `dest` are the Value into which the result of the tiled
141            operation is to be inserted into. The type of the `dest`
142            Values is same as the types returned by
143            `getDestinationOperands` method.
144          - `offsets` provides the offset of the tile within the
145            iteration space
146          - `sizes` provides the size of the tile.
147          - `tileDestOperands` specifies whether to also tile `dest` operands
148            or not. Avoiding tiling `dest` operands can be useful for
149            composition with various looping container ops.
150        }],
151        /*retType=*/"FailureOr<Value>",
152        /*methodName=*/"generateResultTileValue",
153        /*args=*/(ins
154          "OpBuilder &":$b,
155          "unsigned":$resultNumber,
156          "ValueRange":$dest,
157          "ArrayRef<OpFoldResult>":$offsets,
158          "ArrayRef<OpFoldResult>":$sizes,
159          "bool":$tileDestOperands),
160        /*methodBody=*/"",
161        /*defaultImplementation=*/[{
162          return failure();
163        }]
164      >
165  ];
166}
167#endif // MLIR_TILINGINTERFACE
168