MLIR  21.0.0git
LinalgInterfaces.h
Go to the documentation of this file.
1 //===- LinalgInterface.h - Linalg operations interfaces -------------------===//
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 implements the operation interfaces for Linalg operations.
10 //
11 //===----------------------------------------------------------------------===//
12 
13 #ifndef MLIR_DIALECT_LINALG_IR_LINALGINTERFACES_H_
14 #define MLIR_DIALECT_LINALG_IR_LINALGINTERFACES_H_
15 
17 #include "mlir/IR/AffineMap.h"
18 #include "mlir/IR/BuiltinTypes.h"
19 #include "mlir/IR/IRMapping.h"
21 #include "mlir/IR/OpDefinition.h"
27 
28 namespace mlir {
29 namespace linalg {
30 class IteratorTypeAttr;
31 class LinalgOp;
32 class GenericOp;
33 
34 namespace detail {
35 /// Implementation of the method that check if given operands
36 /// can be dropped, i.e. the remaining operands can compute the loop
37 /// bounds of the op.
38 bool canOpOperandsBeDroppedImpl(linalg::LinalgOp linalgOp,
39  ArrayRef<OpOperand *> droppedOperands);
40 } // namespace detail
41 
42 /// Positions of a Linalg op loops that correspond to different kinds of a
43 /// contraction dimension.
49 };
50 
51 /// Find at least 2 parallel (m and n) and 1 reduction (k) dimension candidates
52 /// that form a matmul subcomputation within `linalgOp`.
53 /// These dimensions are such that:
54 /// 1. The m dimension is involved in an outer-product along LHS
55 /// (i.e. it is a permutation on RES and LHS and does not appear in RHS).
56 /// 2. The n dimension is involved in an outer-product along RHS
57 /// (i.e. it is a permutation on RES and RHS and does not appear in LHS).
58 /// 3. The k dimension appears as a permutation on LHS and RHS.
59 /// 4. m, n and k appear only once in any given indexing.
60 /// 5. Optional batch dimensions that appear in all operands are captured.
61 /// This allows e.g. detecting that some contraction is embedded within
62 /// `linalgOp` with some orthogonal heuristic.
63 /// When multiple dimension occurrences exist that match `batch`, `m`, `n`, or
64 /// `k`, indices are returned in sorted order.
65 /// Returns a failure if any of `m`, `n` or `k` is empty.
66 FailureOr<ContractionDimensions> inferContractionDims(LinalgOp linalgOp);
67 FailureOr<ContractionDimensions>
69 
70 /// Checks whether `linalgOp` conforms to ContractionOpInterface.
71 // TODO: embed within `isa<ContractionOpInterface>` if possible / natural.
72 bool isaContractionOpInterface(LinalgOp linalgOp);
73 
74 /// Positions of a Linalg op loops that correspond to different kinds of a
75 /// convolution dimension.
85 };
86 
87 /// Find at least 1 parallel (output_image) and reduction (filter_loop)
88 /// dimension candidates that form a convolution subcomputation within
89 /// `linalgOp`. The LHS is assumed to be the convolution input while the
90 /// RHS is assumed as the filter.
91 /// These dimensions are such that:
92 /// 1. Optional batch dimensions that appear in the input and filter.
93 /// 2. The output_image dimension is involved in a cross-correlation along LHS
94 /// (i.e. it is a permutation on RES and LHS and has an associated
95 /// filter_loop in RHS).
96 /// 3. Optional output_channel dimension is involved in an outer-product along
97 /// RHS (i.e. it is a permutation on RES and RHS and does not appear in
98 /// LHS).
99 /// 4. Optional input_channel dimension appears as a permutation on LHS and
100 /// RHS.
101 /// 5. The filter_loop dimension appears as a permutation on the RHS and
102 /// represents the shape of the kernel cross-correlated along a
103 /// corresponding output_image dim.
104 /// 6. The input_channel dimension appears as a permutation on LHS and RHS.
105 /// 7. All dimensions appear only once in any given indexing map.
106 /// This allows e.g. detecting that some convolution is embedded within
107 /// `linalgOp` with some orthogonal heuristic.
108 /// When multiple dimension occurrences exist that match any classification
109 /// indices are returned in sorted order.
110 /// Returns a failure if `output_image` (and implicitly `filter_loop`) is empty.
111 FailureOr<ConvolutionDimensions> inferConvolutionDims(LinalgOp linalgOp);
112 
113 /// Checks whether `linalgOp` conforms to ConvolutionOpInterface.
114 /// By default, we require the `linalgOp` to have non-empty convolved dims
115 /// (implicitly non-empty `output_image` and `filter_loop`).
116 /// Users can loosen the constraint by setting `allowEmptyConvolvedDims` to true
117 // TODO: embed within `isa<ConvolutionOpInterface>` if possible / natural.
118 bool isaConvolutionOpInterface(LinalgOp linalgOp,
119  bool allowEmptyConvolvedDims = false);
120 
121 /// Checks whether `linalgOp` is semantically equivalent to a `linalg.copyOp`.
122 bool isaCopyOpInterface(LinalgOp linalgOp);
123 
124 /// Checks whether `genericOp` is semantically equivalent to a
125 /// `linalg.broadcast`. Returns broadcast dimensions if true.
126 std::optional<SmallVector<int64_t>>
127 isaBroadcastOpInterface(GenericOp genericOp);
128 
129 /// Checks whether `genericOp` is semantically equivalent to a
130 /// `linalg.transpose`. Returns permuted dimensions if true.
131 std::optional<SmallVector<int64_t>>
132 isaTransposeOpInterface(GenericOp genericOp);
133 
134 /// Checks whether a given `genericOp` is semantically equivalent to a single
135 /// linalgelementwise unary op. e.g. linalg.exp.
136 /// A linalg.generic body could be a series of unary elementwise ops e.g.
137 /// `exp(neg(x))`, such as formed by linalg op fusion. Here we restrict it to
138 /// detecting cases where body is is a single computation op.
139 bool isaElemwiseSingleUnaryOpInterface(GenericOp genericOp);
140 
141 /// Checks whether `genericOp` is semantically equivalent to a single linalg
142 /// elementwise binary op e.g. linalg.sub.
143 bool isaElemwiseSingleBinaryOpInterface(GenericOp genericOp);
144 
145 /// Checks whether `genericOp` is semantically equivalent to a `linalg.fill`.
146 /// Supports two patterns:
147 /// 1. External: linalg.generic ins(%scalar) outs(%tensor) { yield %scalar }
148 /// 2. Inlined: linalg.generic outs(%tensor) { yield %constant }
149 /// Returns the scalar fill value if true.
150 std::optional<Value> isaFillOpInterface(GenericOp genericOp);
151 
152 namespace detail {
153 
154 /// Returns true if the block contains a contraction of the following form:
155 ///
156 /// %0 = <elemwise>(permutation-of(cu(block-argument-0),
157 /// cu(block-argument-1)))
158 /// %1 = <reduce>(permutation-of(cu(%0), cu(block-argument-2)))
159 /// return-like cu(%1)
160 ///
161 /// where <elemwise> and <reduce> are binary operations constituting a
162 /// contraction (in the canonical case, <elemwise> is a multiplication and
163 /// <reduce> is an addition). The name and other properties of these operations
164 /// are checked by `isaPair`. All operands of all operations may be supplied
165 /// through a chain of side effect-free unary operations, such as casts, which
166 /// is denoted as `cu` above.
167 ///
168 /// When the body does not contain a contraction, a more precise description of
169 /// the failed precondition is send to the `errs` stream, if provided.
170 bool isContractionBody(Block &block,
171  function_ref<bool(Operation *, Operation *)> isaPair,
172  llvm::raw_ostream &errs = mlir::thread_safe_nulls());
173 
174 /// Result of matching a Linalg generic against the predicates of it being a
175 /// contraction.
176 enum class MatchContractionResult;
177 
178 /// Checks whether `op` conforms to ContractionOpInterface and populates
179 /// `dimensions` with indexes of the different kinds of dimensions when
180 /// present.
183  ContractionDimensions *dimensions = nullptr);
184 
185 /// Returns the error message corresponding to the contraction checking return
186 /// code.
188 
189 /// Result of matching a Linalg generic against the predicates of it being a
190 /// convolution.
191 enum class MatchConvolutionResult;
192 
193 /// Checks whether `op` conforms to ConvolutionOpInterface and populates
194 /// `dimensions` with indexes of the different kinds of dimensions when
195 /// present.
196 /// If `allowEmptyConvolvedDims` is not set, we further checks whether the `op`
197 /// contains convolved dims.
200  ConvolutionDimensions *dimensions = nullptr,
201  bool allowEmptyConvolvedDims = false);
202 
203 /// Returns the error message corresponding to the convolution checking return
204 /// code.
206 
207 /// Verify that `op` conforms to ContractionOpInterface.
208 LogicalResult verifyContractionInterface(Operation *op);
209 
210 /// Verify that `op` conforms to the ConvolutionOpInterface.
211 LogicalResult verifyConvolutionInterface(Operation *op);
212 
213 /// Verify that `op` conforms to the FillOpInterface.
214 LogicalResult verifyFillInterface(Operation *op);
215 
216 /// Verify that `op` conforms to the invariants of StructuredOpInterface
217 LogicalResult verifyStructuredOpInterface(Operation *op);
218 
219 } // namespace detail
220 } // namespace linalg
221 } // namespace mlir
222 
223 #include "mlir/Dialect/Linalg/IR/LinalgStructuredOps.h.inc"
224 
225 /// Include the generated interface declarations.
226 #include "mlir/Dialect/Linalg/IR/LinalgInterfaces.h.inc"
227 
228 /// Include the generated relayout interface declarations.
229 #include "mlir/Dialect/Linalg/IR/RelayoutOpInterface.h.inc"
230 
231 #endif // MLIR_DIALECT_LINALG_IR_LINALGINTERFACES_H_
Block represents an ordered list of Operations.
Definition: Block.h:33
Operation is the basic unit of execution within MLIR.
Definition: Operation.h:88
MatchConvolutionResult isConvolutionInterfaceImpl(Operation *op, ConvolutionDimensions *dimensions=nullptr, bool allowEmptyConvolvedDims=false)
Checks whether op conforms to ConvolutionOpInterface and populates dimensions with indexes of the dif...
bool isContractionBody(Block &block, function_ref< bool(Operation *, Operation *)> isaPair, llvm::raw_ostream &errs=mlir::thread_safe_nulls())
Returns true if the block contains a contraction of the following form:
StringRef getMatchConvolutionMessage(MatchConvolutionResult res)
Returns the error message corresponding to the convolution checking return code.
bool canOpOperandsBeDroppedImpl(linalg::LinalgOp linalgOp, ArrayRef< OpOperand * > droppedOperands)
Implementation of the method that check if given operands can be dropped, i.e.
MatchContractionResult isContractionInterfaceImpl(Operation *op, ContractionDimensions *dimensions=nullptr)
Checks whether op conforms to ContractionOpInterface and populates dimensions with indexes of the dif...
LogicalResult verifyContractionInterface(Operation *op)
Verify that op conforms to ContractionOpInterface.
LogicalResult verifyFillInterface(Operation *op)
Verify that op conforms to the FillOpInterface.
StringRef getMatchContractionMessage(MatchContractionResult res)
Returns the error message corresponding to the contraction checking return code.
LogicalResult verifyStructuredOpInterface(Operation *op)
Verify that op conforms to the invariants of StructuredOpInterface.
LogicalResult verifyConvolutionInterface(Operation *op)
Verify that op conforms to the ConvolutionOpInterface.
std::optional< SmallVector< int64_t > > isaTransposeOpInterface(GenericOp genericOp)
Checks whether genericOp is semantically equivalent to a linalg.transpose.
bool isaElemwiseSingleUnaryOpInterface(GenericOp genericOp)
Checks whether a given genericOp is semantically equivalent to a single linalgelementwise unary op.
bool isaCopyOpInterface(LinalgOp linalgOp)
Checks whether linalgOp is semantically equivalent to a linalg.copyOp.
FailureOr< ConvolutionDimensions > inferConvolutionDims(LinalgOp linalgOp)
Find at least 1 parallel (output_image) and reduction (filter_loop) dimension candidates that form a ...
bool isaConvolutionOpInterface(LinalgOp linalgOp, bool allowEmptyConvolvedDims=false)
Checks whether linalgOp conforms to ConvolutionOpInterface.
std::optional< SmallVector< int64_t > > isaBroadcastOpInterface(GenericOp genericOp)
Checks whether genericOp is semantically equivalent to a linalg.broadcast.
FailureOr< ContractionDimensions > inferContractionDims(LinalgOp linalgOp)
Find at least 2 parallel (m and n) and 1 reduction (k) dimension candidates that form a matmul subcom...
bool isaContractionOpInterface(LinalgOp linalgOp)
Checks whether linalgOp conforms to ContractionOpInterface.
std::optional< Value > isaFillOpInterface(GenericOp genericOp)
Checks whether genericOp is semantically equivalent to a linalg.fill.
bool isaElemwiseSingleBinaryOpInterface(GenericOp genericOp)
Checks whether genericOp is semantically equivalent to a single linalg elementwise binary op e....
Include the generated interface declarations.
llvm::raw_ostream & thread_safe_nulls()
Returns a raw output stream that simply discards the output, but in a thread-safe manner.
Positions of a Linalg op loops that correspond to different kinds of a contraction dimension.
SmallVector< unsigned, 2 > batch
SmallVector< unsigned, 2 > m
SmallVector< unsigned, 2 > n
SmallVector< unsigned, 2 > k
Positions of a Linalg op loops that correspond to different kinds of a convolution dimension.
SmallVector< unsigned, 2 > depth
SmallVector< unsigned, 2 > outputImage
SmallVector< unsigned, 2 > outputChannel
SmallVector< int64_t, 2 > dilations
SmallVector< int64_t, 2 > strides
SmallVector< unsigned, 2 > inputChannel
SmallVector< unsigned, 2 > batch
SmallVector< unsigned, 2 > filterLoop