465 lines · c
1//===-- mlir-c/Rewrite.h - Helpers for C API to Rewrites ----------*- C -*-===//2//3// Part of the LLVM Project, under the Apache License v2.0 with LLVM4// Exceptions.5// See https://llvm.org/LICENSE.txt for license information.6// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception7//8//===----------------------------------------------------------------------===//9//10// This header declares the registration and creation method for11// rewrite patterns.12//13//===----------------------------------------------------------------------===//14 15#ifndef MLIR_C_REWRITE_H16#define MLIR_C_REWRITE_H17 18#include "mlir-c/IR.h"19#include "mlir-c/Support.h"20#include "mlir/Config/mlir-config.h"21 22#ifdef __cplusplus23extern "C" {24#endif25 26//===----------------------------------------------------------------------===//27/// Opaque type declarations (see mlir-c/IR.h for more details).28//===----------------------------------------------------------------------===//29 30#define DEFINE_C_API_STRUCT(name, storage) \31 struct name { \32 storage *ptr; \33 }; \34 typedef struct name name35 36DEFINE_C_API_STRUCT(MlirRewriterBase, void);37DEFINE_C_API_STRUCT(MlirFrozenRewritePatternSet, void);38DEFINE_C_API_STRUCT(MlirGreedyRewriteDriverConfig, void);39DEFINE_C_API_STRUCT(MlirRewritePatternSet, void);40DEFINE_C_API_STRUCT(MlirPatternRewriter, void);41DEFINE_C_API_STRUCT(MlirRewritePattern, const void);42 43//===----------------------------------------------------------------------===//44/// RewriterBase API inherited from OpBuilder45//===----------------------------------------------------------------------===//46 47/// Get the MLIR context referenced by the rewriter.48MLIR_CAPI_EXPORTED MlirContext49mlirRewriterBaseGetContext(MlirRewriterBase rewriter);50 51//===----------------------------------------------------------------------===//52/// Insertion points methods53//===----------------------------------------------------------------------===//54 55// These do not include functions using Block::iterator or Region::iterator, as56// they are not exposed by the C API yet. Similarly for methods using57// `InsertPoint` directly.58 59/// Reset the insertion point to no location. Creating an operation without a60/// set insertion point is an error, but this can still be useful when the61/// current insertion point a builder refers to is being removed.62MLIR_CAPI_EXPORTED void63mlirRewriterBaseClearInsertionPoint(MlirRewriterBase rewriter);64 65/// Sets the insertion point to the specified operation, which will cause66/// subsequent insertions to go right before it.67MLIR_CAPI_EXPORTED void68mlirRewriterBaseSetInsertionPointBefore(MlirRewriterBase rewriter,69 MlirOperation op);70 71/// Sets the insertion point to the node after the specified operation, which72/// will cause subsequent insertions to go right after it.73MLIR_CAPI_EXPORTED void74mlirRewriterBaseSetInsertionPointAfter(MlirRewriterBase rewriter,75 MlirOperation op);76 77/// Sets the insertion point to the node after the specified value. If value78/// has a defining operation, sets the insertion point to the node after such79/// defining operation. This will cause subsequent insertions to go right80/// after it. Otherwise, value is a BlockArgument. Sets the insertion point to81/// the start of its block.82MLIR_CAPI_EXPORTED void83mlirRewriterBaseSetInsertionPointAfterValue(MlirRewriterBase rewriter,84 MlirValue value);85 86/// Sets the insertion point to the start of the specified block.87MLIR_CAPI_EXPORTED void88mlirRewriterBaseSetInsertionPointToStart(MlirRewriterBase rewriter,89 MlirBlock block);90 91/// Sets the insertion point to the end of the specified block.92MLIR_CAPI_EXPORTED void93mlirRewriterBaseSetInsertionPointToEnd(MlirRewriterBase rewriter,94 MlirBlock block);95 96/// Return the block the current insertion point belongs to. Note that the97/// insertion point is not necessarily the end of the block.98MLIR_CAPI_EXPORTED MlirBlock99mlirRewriterBaseGetInsertionBlock(MlirRewriterBase rewriter);100 101/// Returns the current block of the rewriter.102MLIR_CAPI_EXPORTED MlirBlock103mlirRewriterBaseGetBlock(MlirRewriterBase rewriter);104 105/// Returns the operation right after the current insertion point106/// of the rewriter. A null MlirOperation will be returned107// if the current insertion point is at the end of the block.108MLIR_CAPI_EXPORTED MlirOperation109mlirRewriterBaseGetOperationAfterInsertion(MlirRewriterBase rewriter);110 111//===----------------------------------------------------------------------===//112/// Block and operation creation/insertion/cloning113//===----------------------------------------------------------------------===//114 115// These functions do not include the IRMapper, as it is not yet exposed by the116// C API.117 118/// Add new block with 'argTypes' arguments and set the insertion point to the119/// end of it. The block is placed before 'insertBefore'. `locs` contains the120/// locations of the inserted arguments, and should match the size of121/// `argTypes`.122MLIR_CAPI_EXPORTED MlirBlock mlirRewriterBaseCreateBlockBefore(123 MlirRewriterBase rewriter, MlirBlock insertBefore, intptr_t nArgTypes,124 MlirType const *argTypes, MlirLocation const *locations);125 126/// Insert the given operation at the current insertion point and return it.127MLIR_CAPI_EXPORTED MlirOperation128mlirRewriterBaseInsert(MlirRewriterBase rewriter, MlirOperation op);129 130/// Creates a deep copy of the specified operation.131MLIR_CAPI_EXPORTED MlirOperation132mlirRewriterBaseClone(MlirRewriterBase rewriter, MlirOperation op);133 134/// Creates a deep copy of this operation but keep the operation regions135/// empty.136MLIR_CAPI_EXPORTED MlirOperation mlirRewriterBaseCloneWithoutRegions(137 MlirRewriterBase rewriter, MlirOperation op);138 139/// Clone the blocks that belong to "region" before the given position in140/// another region "parent".141MLIR_CAPI_EXPORTED void142mlirRewriterBaseCloneRegionBefore(MlirRewriterBase rewriter, MlirRegion region,143 MlirBlock before);144 145//===----------------------------------------------------------------------===//146/// RewriterBase API147//===----------------------------------------------------------------------===//148 149/// Move the blocks that belong to "region" before the given position in150/// another region "parent". The two regions must be different. The caller151/// is responsible for creating or updating the operation transferring flow152/// of control to the region and passing it the correct block arguments.153MLIR_CAPI_EXPORTED void154mlirRewriterBaseInlineRegionBefore(MlirRewriterBase rewriter, MlirRegion region,155 MlirBlock before);156 157/// Replace the results of the given (original) operation with the specified158/// list of values (replacements). The result types of the given op and the159/// replacements must match. The original op is erased.160MLIR_CAPI_EXPORTED void161mlirRewriterBaseReplaceOpWithValues(MlirRewriterBase rewriter, MlirOperation op,162 intptr_t nValues, MlirValue const *values);163 164/// Replace the results of the given (original) operation with the specified165/// new op (replacement). The result types of the two ops must match. The166/// original op is erased.167MLIR_CAPI_EXPORTED void168mlirRewriterBaseReplaceOpWithOperation(MlirRewriterBase rewriter,169 MlirOperation op, MlirOperation newOp);170 171/// Erases an operation that is known to have no uses.172MLIR_CAPI_EXPORTED void mlirRewriterBaseEraseOp(MlirRewriterBase rewriter,173 MlirOperation op);174 175/// Erases a block along with all operations inside it.176MLIR_CAPI_EXPORTED void mlirRewriterBaseEraseBlock(MlirRewriterBase rewriter,177 MlirBlock block);178 179/// Inline the operations of block 'source' before the operation 'op'. The180/// source block will be deleted and must have no uses. 'argValues' is used to181/// replace the block arguments of 'source'182///183/// The source block must have no successors. Otherwise, the resulting IR184/// would have unreachable operations.185MLIR_CAPI_EXPORTED void186mlirRewriterBaseInlineBlockBefore(MlirRewriterBase rewriter, MlirBlock source,187 MlirOperation op, intptr_t nArgValues,188 MlirValue const *argValues);189 190/// Inline the operations of block 'source' into the end of block 'dest'. The191/// source block will be deleted and must have no uses. 'argValues' is used to192/// replace the block arguments of 'source'193///194/// The dest block must have no successors. Otherwise, the resulting IR would195/// have unreachable operation.196MLIR_CAPI_EXPORTED void mlirRewriterBaseMergeBlocks(MlirRewriterBase rewriter,197 MlirBlock source,198 MlirBlock dest,199 intptr_t nArgValues,200 MlirValue const *argValues);201 202/// Unlink this operation from its current block and insert it right before203/// `existingOp` which may be in the same or another block in the same204/// function.205MLIR_CAPI_EXPORTED void mlirRewriterBaseMoveOpBefore(MlirRewriterBase rewriter,206 MlirOperation op,207 MlirOperation existingOp);208 209/// Unlink this operation from its current block and insert it right after210/// `existingOp` which may be in the same or another block in the same211/// function.212MLIR_CAPI_EXPORTED void mlirRewriterBaseMoveOpAfter(MlirRewriterBase rewriter,213 MlirOperation op,214 MlirOperation existingOp);215 216/// Unlink this block and insert it right before `existingBlock`.217MLIR_CAPI_EXPORTED void218mlirRewriterBaseMoveBlockBefore(MlirRewriterBase rewriter, MlirBlock block,219 MlirBlock existingBlock);220 221/// This method is used to notify the rewriter that an in-place operation222/// modification is about to happen. A call to this function *must* be223/// followed by a call to either `finalizeOpModification` or224/// `cancelOpModification`. This is a minor efficiency win (it avoids creating225/// a new operation and removing the old one) but also often allows simpler226/// code in the client.227MLIR_CAPI_EXPORTED void228mlirRewriterBaseStartOpModification(MlirRewriterBase rewriter,229 MlirOperation op);230 231/// This method is used to signal the end of an in-place modification of the232/// given operation. This can only be called on operations that were provided233/// to a call to `startOpModification`.234MLIR_CAPI_EXPORTED void235mlirRewriterBaseFinalizeOpModification(MlirRewriterBase rewriter,236 MlirOperation op);237 238/// This method cancels a pending in-place modification. This can only be239/// called on operations that were provided to a call to240/// `startOpModification`.241MLIR_CAPI_EXPORTED void242mlirRewriterBaseCancelOpModification(MlirRewriterBase rewriter,243 MlirOperation op);244 245/// Find uses of `from` and replace them with `to`. Also notify the listener246/// about every in-place op modification (for every use that was replaced).247MLIR_CAPI_EXPORTED void248mlirRewriterBaseReplaceAllUsesWith(MlirRewriterBase rewriter, MlirValue from,249 MlirValue to);250 251/// Find uses of `from` and replace them with `to`. Also notify the listener252/// about every in-place op modification (for every use that was replaced).253MLIR_CAPI_EXPORTED void mlirRewriterBaseReplaceAllValueRangeUsesWith(254 MlirRewriterBase rewriter, intptr_t nValues, MlirValue const *from,255 MlirValue const *to);256 257/// Find uses of `from` and replace them with `to`. Also notify the listener258/// about every in-place op modification (for every use that was replaced)259/// and that the `from` operation is about to be replaced.260MLIR_CAPI_EXPORTED void261mlirRewriterBaseReplaceAllOpUsesWithValueRange(MlirRewriterBase rewriter,262 MlirOperation from, intptr_t nTo,263 MlirValue const *to);264 265/// Find uses of `from` and replace them with `to`. Also notify the listener266/// about every in-place op modification (for every use that was replaced)267/// and that the `from` operation is about to be replaced.268MLIR_CAPI_EXPORTED void mlirRewriterBaseReplaceAllOpUsesWithOperation(269 MlirRewriterBase rewriter, MlirOperation from, MlirOperation to);270 271/// Find uses of `from` within `block` and replace them with `to`. Also notify272/// the listener about every in-place op modification (for every use that was273/// replaced). The optional `allUsesReplaced` flag is set to "true" if all274/// uses were replaced.275MLIR_CAPI_EXPORTED void mlirRewriterBaseReplaceOpUsesWithinBlock(276 MlirRewriterBase rewriter, MlirOperation op, intptr_t nNewValues,277 MlirValue const *newValues, MlirBlock block);278 279/// Find uses of `from` and replace them with `to` except if the user is280/// `exceptedUser`. Also notify the listener about every in-place op281/// modification (for every use that was replaced).282MLIR_CAPI_EXPORTED void283mlirRewriterBaseReplaceAllUsesExcept(MlirRewriterBase rewriter, MlirValue from,284 MlirValue to, MlirOperation exceptedUser);285 286//===----------------------------------------------------------------------===//287/// IRRewriter API288//===----------------------------------------------------------------------===//289 290/// Create an IRRewriter and transfer ownership to the caller.291MLIR_CAPI_EXPORTED MlirRewriterBase mlirIRRewriterCreate(MlirContext context);292 293/// Create an IRRewriter and transfer ownership to the caller. Additionally294/// set the insertion point before the operation.295MLIR_CAPI_EXPORTED MlirRewriterBase296mlirIRRewriterCreateFromOp(MlirOperation op);297 298/// Takes an IRRewriter owned by the caller and destroys it. It is the299/// responsibility of the user to only pass an IRRewriter class.300MLIR_CAPI_EXPORTED void mlirIRRewriterDestroy(MlirRewriterBase rewriter);301 302//===----------------------------------------------------------------------===//303/// FrozenRewritePatternSet API304//===----------------------------------------------------------------------===//305 306/// Freeze the given MlirRewritePatternSet to a MlirFrozenRewritePatternSet.307/// Note that the ownership of the input set is transferred into the frozen set308/// after this call.309MLIR_CAPI_EXPORTED MlirFrozenRewritePatternSet310mlirFreezeRewritePattern(MlirRewritePatternSet set);311 312/// Destroy the given MlirFrozenRewritePatternSet.313MLIR_CAPI_EXPORTED void314mlirFrozenRewritePatternSetDestroy(MlirFrozenRewritePatternSet set);315 316MLIR_CAPI_EXPORTED MlirLogicalResult mlirApplyPatternsAndFoldGreedilyWithOp(317 MlirOperation op, MlirFrozenRewritePatternSet patterns,318 MlirGreedyRewriteDriverConfig);319 320MLIR_CAPI_EXPORTED MlirLogicalResult mlirApplyPatternsAndFoldGreedily(321 MlirModule op, MlirFrozenRewritePatternSet patterns,322 MlirGreedyRewriteDriverConfig);323 324//===----------------------------------------------------------------------===//325/// PatternRewriter API326//===----------------------------------------------------------------------===//327 328/// Cast the PatternRewriter to a RewriterBase329MLIR_CAPI_EXPORTED MlirRewriterBase330mlirPatternRewriterAsBase(MlirPatternRewriter rewriter);331 332//===----------------------------------------------------------------------===//333/// RewritePattern API334//===----------------------------------------------------------------------===//335 336/// Callbacks to construct a rewrite pattern.337typedef struct {338 /// Optional constructor for the user data.339 /// Set to nullptr to disable it.340 void (*construct)(void *userData);341 /// Optional destructor for the user data.342 /// Set to nullptr to disable it.343 void (*destruct)(void *userData);344 /// The callback function to match against code rooted at the specified345 /// operation, and perform the rewrite if the match is successful,346 /// corresponding to RewritePattern::matchAndRewrite.347 MlirLogicalResult (*matchAndRewrite)(MlirRewritePattern pattern,348 MlirOperation op,349 MlirPatternRewriter rewriter,350 void *userData);351} MlirRewritePatternCallbacks;352 353/// Create a rewrite pattern that matches the operation354/// with the given rootName, corresponding to mlir::OpRewritePattern.355MLIR_CAPI_EXPORTED MlirRewritePattern mlirOpRewritePatternCreate(356 MlirStringRef rootName, unsigned benefit, MlirContext context,357 MlirRewritePatternCallbacks callbacks, void *userData,358 size_t nGeneratedNames, MlirStringRef *generatedNames);359 360//===----------------------------------------------------------------------===//361/// RewritePatternSet API362//===----------------------------------------------------------------------===//363 364/// Create an empty MlirRewritePatternSet.365MLIR_CAPI_EXPORTED MlirRewritePatternSet366mlirRewritePatternSetCreate(MlirContext context);367 368/// Destruct the given MlirRewritePatternSet.369MLIR_CAPI_EXPORTED void mlirRewritePatternSetDestroy(MlirRewritePatternSet set);370 371/// Add the given MlirRewritePattern into a MlirRewritePatternSet.372/// Note that the ownership of the pattern is transferred to the set after this373/// call.374MLIR_CAPI_EXPORTED void mlirRewritePatternSetAdd(MlirRewritePatternSet set,375 MlirRewritePattern pattern);376 377//===----------------------------------------------------------------------===//378/// PDLPatternModule API379//===----------------------------------------------------------------------===//380 381#if MLIR_ENABLE_PDL_IN_PATTERNMATCH382DEFINE_C_API_STRUCT(MlirPDLPatternModule, void);383DEFINE_C_API_STRUCT(MlirPDLValue, const void);384DEFINE_C_API_STRUCT(MlirPDLResultList, void);385 386MLIR_CAPI_EXPORTED MlirPDLPatternModule387mlirPDLPatternModuleFromModule(MlirModule op);388 389MLIR_CAPI_EXPORTED void mlirPDLPatternModuleDestroy(MlirPDLPatternModule op);390 391MLIR_CAPI_EXPORTED MlirRewritePatternSet392mlirRewritePatternSetFromPDLPatternModule(MlirPDLPatternModule op);393 394/// Cast the MlirPDLValue to an MlirValue.395/// Return a null value if the cast fails, just like llvm::dyn_cast.396MLIR_CAPI_EXPORTED MlirValue mlirPDLValueAsValue(MlirPDLValue value);397 398/// Cast the MlirPDLValue to an MlirType.399/// Return a null value if the cast fails, just like llvm::dyn_cast.400MLIR_CAPI_EXPORTED MlirType mlirPDLValueAsType(MlirPDLValue value);401 402/// Cast the MlirPDLValue to an MlirOperation.403/// Return a null value if the cast fails, just like llvm::dyn_cast.404MLIR_CAPI_EXPORTED MlirOperation mlirPDLValueAsOperation(MlirPDLValue value);405 406/// Cast the MlirPDLValue to an MlirAttribute.407/// Return a null value if the cast fails, just like llvm::dyn_cast.408MLIR_CAPI_EXPORTED MlirAttribute mlirPDLValueAsAttribute(MlirPDLValue value);409 410/// Push the MlirValue into the given MlirPDLResultList.411MLIR_CAPI_EXPORTED void412mlirPDLResultListPushBackValue(MlirPDLResultList results, MlirValue value);413 414/// Push the MlirType into the given MlirPDLResultList.415MLIR_CAPI_EXPORTED void mlirPDLResultListPushBackType(MlirPDLResultList results,416 MlirType value);417 418/// Push the MlirOperation into the given MlirPDLResultList.419MLIR_CAPI_EXPORTED void420mlirPDLResultListPushBackOperation(MlirPDLResultList results,421 MlirOperation value);422 423/// Push the MlirAttribute into the given MlirPDLResultList.424MLIR_CAPI_EXPORTED void425mlirPDLResultListPushBackAttribute(MlirPDLResultList results,426 MlirAttribute value);427 428/// This function type is used as callbacks for PDL native rewrite functions.429/// Input values can be accessed by `values` with its size `nValues`;430/// output values can be added into `results` by `mlirPDLResultListPushBack*`431/// APIs. And the return value indicates whether the rewrite succeeds.432typedef MlirLogicalResult (*MlirPDLRewriteFunction)(433 MlirPatternRewriter rewriter, MlirPDLResultList results, size_t nValues,434 MlirPDLValue *values, void *userData);435 436/// Register a rewrite function into the given PDL pattern module.437/// `userData` will be provided as an argument to the rewrite function.438MLIR_CAPI_EXPORTED void mlirPDLPatternModuleRegisterRewriteFunction(439 MlirPDLPatternModule pdlModule, MlirStringRef name,440 MlirPDLRewriteFunction rewriteFn, void *userData);441 442/// This function type is used as callbacks for PDL native constraint functions.443/// Input values can be accessed by `values` with its size `nValues`;444/// output values can be added into `results` by `mlirPDLResultListPushBack*`445/// APIs. And the return value indicates whether the constraint holds.446typedef MlirLogicalResult (*MlirPDLConstraintFunction)(447 MlirPatternRewriter rewriter, MlirPDLResultList results, size_t nValues,448 MlirPDLValue *values, void *userData);449 450/// Register a constraint function into the given PDL pattern module.451/// `userData` will be provided as an argument to the constraint function.452MLIR_CAPI_EXPORTED void mlirPDLPatternModuleRegisterConstraintFunction(453 MlirPDLPatternModule pdlModule, MlirStringRef name,454 MlirPDLConstraintFunction constraintFn, void *userData);455 456#endif // MLIR_ENABLE_PDL_IN_PATTERNMATCH457 458#undef DEFINE_C_API_STRUCT459 460#ifdef __cplusplus461}462#endif463 464#endif // MLIR_C_REWRITE_H465