1 //===-- mlir-c/Pass.h - C API to Pass Management ------------------*- C -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM 4 // Exceptions. 5 // See https://llvm.org/LICENSE.txt for license information. 6 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 7 // 8 //===----------------------------------------------------------------------===// 9 // 10 // This header declares the C interface to MLIR pass manager. 11 // 12 //===----------------------------------------------------------------------===// 13 14 #ifndef MLIR_C_PASS_H 15 #define MLIR_C_PASS_H 16 17 #include "mlir-c/IR.h" 18 #include "mlir-c/Support.h" 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 //===----------------------------------------------------------------------===// 25 // Opaque type declarations. 26 // 27 // Types are exposed to C bindings as structs containing opaque pointers. They 28 // are not supposed to be inspected from C. This allows the underlying 29 // representation to change without affecting the API users. The use of structs 30 // instead of typedefs enables some type safety as structs are not implicitly 31 // convertible to each other. 32 // 33 // Instances of these types may or may not own the underlying object. The 34 // ownership semantics is defined by how an instance of the type was obtained. 35 //===----------------------------------------------------------------------===// 36 37 #define DEFINE_C_API_STRUCT(name, storage) \ 38 struct name { \ 39 storage *ptr; \ 40 }; \ 41 typedef struct name name 42 43 DEFINE_C_API_STRUCT(MlirPass, void); 44 DEFINE_C_API_STRUCT(MlirExternalPass, void); 45 DEFINE_C_API_STRUCT(MlirPassManager, void); 46 DEFINE_C_API_STRUCT(MlirOpPassManager, void); 47 48 #undef DEFINE_C_API_STRUCT 49 50 //===----------------------------------------------------------------------===// 51 // PassManager/OpPassManager APIs. 52 //===----------------------------------------------------------------------===// 53 54 /// Create a new top-level PassManager with the default anchor. 55 MLIR_CAPI_EXPORTED MlirPassManager mlirPassManagerCreate(MlirContext ctx); 56 57 /// Create a new top-level PassManager anchored on `anchorOp`. 58 MLIR_CAPI_EXPORTED MlirPassManager 59 mlirPassManagerCreateOnOperation(MlirContext ctx, MlirStringRef anchorOp); 60 61 /// Destroy the provided PassManager. 62 MLIR_CAPI_EXPORTED void mlirPassManagerDestroy(MlirPassManager passManager); 63 64 /// Checks if a PassManager is null. 65 static inline bool mlirPassManagerIsNull(MlirPassManager passManager) { 66 return !passManager.ptr; 67 } 68 69 /// Cast a top-level PassManager to a generic OpPassManager. 70 MLIR_CAPI_EXPORTED MlirOpPassManager 71 mlirPassManagerGetAsOpPassManager(MlirPassManager passManager); 72 73 /// Run the provided `passManager` on the given `op`. 74 MLIR_CAPI_EXPORTED MlirLogicalResult 75 mlirPassManagerRunOnOp(MlirPassManager passManager, MlirOperation op); 76 77 /// Enable IR printing. 78 /// The treePrintingPath argument is an optional path to a directory 79 /// where the dumps will be produced. If it isn't provided then dumps 80 /// are produced to stderr. 81 MLIR_CAPI_EXPORTED void mlirPassManagerEnableIRPrinting( 82 MlirPassManager passManager, bool printBeforeAll, bool printAfterAll, 83 bool printModuleScope, bool printAfterOnlyOnChange, 84 bool printAfterOnlyOnFailure, MlirOpPrintingFlags flags, 85 MlirStringRef treePrintingPath); 86 87 /// Enable / disable verify-each. 88 MLIR_CAPI_EXPORTED void 89 mlirPassManagerEnableVerifier(MlirPassManager passManager, bool enable); 90 91 /// Nest an OpPassManager under the top-level PassManager, the nested 92 /// passmanager will only run on operations matching the provided name. 93 /// The returned OpPassManager will be destroyed when the parent is destroyed. 94 /// To further nest more OpPassManager under the newly returned one, see 95 /// `mlirOpPassManagerNest` below. 96 MLIR_CAPI_EXPORTED MlirOpPassManager mlirPassManagerGetNestedUnder( 97 MlirPassManager passManager, MlirStringRef operationName); 98 99 /// Nest an OpPassManager under the provided OpPassManager, the nested 100 /// passmanager will only run on operations matching the provided name. 101 /// The returned OpPassManager will be destroyed when the parent is destroyed. 102 MLIR_CAPI_EXPORTED MlirOpPassManager mlirOpPassManagerGetNestedUnder( 103 MlirOpPassManager passManager, MlirStringRef operationName); 104 105 /// Add a pass and transfer ownership to the provided top-level mlirPassManager. 106 /// If the pass is not a generic operation pass or a ModulePass, a new 107 /// OpPassManager is implicitly nested under the provided PassManager. 108 MLIR_CAPI_EXPORTED void mlirPassManagerAddOwnedPass(MlirPassManager passManager, 109 MlirPass pass); 110 111 /// Add a pass and transfer ownership to the provided mlirOpPassManager. If the 112 /// pass is not a generic operation pass or matching the type of the provided 113 /// PassManager, a new OpPassManager is implicitly nested under the provided 114 /// PassManager. 115 MLIR_CAPI_EXPORTED void 116 mlirOpPassManagerAddOwnedPass(MlirOpPassManager passManager, MlirPass pass); 117 118 /// Parse a sequence of textual MLIR pass pipeline elements and add them to the 119 /// provided OpPassManager. If parsing fails an error message is reported using 120 /// the provided callback. 121 MLIR_CAPI_EXPORTED MlirLogicalResult mlirOpPassManagerAddPipeline( 122 MlirOpPassManager passManager, MlirStringRef pipelineElements, 123 MlirStringCallback callback, void *userData); 124 125 /// Print a textual MLIR pass pipeline by sending chunks of the string 126 /// representation and forwarding `userData to `callback`. Note that the 127 /// callback may be called several times with consecutive chunks of the string. 128 MLIR_CAPI_EXPORTED void mlirPrintPassPipeline(MlirOpPassManager passManager, 129 MlirStringCallback callback, 130 void *userData); 131 132 /// Parse a textual MLIR pass pipeline and assign it to the provided 133 /// OpPassManager. If parsing fails an error message is reported using the 134 /// provided callback. 135 MLIR_CAPI_EXPORTED MlirLogicalResult 136 mlirParsePassPipeline(MlirOpPassManager passManager, MlirStringRef pipeline, 137 MlirStringCallback callback, void *userData); 138 139 //===----------------------------------------------------------------------===// 140 // External Pass API. 141 // 142 // This API allows to define passes outside of MLIR, not necessarily in 143 // C++, and register them with the MLIR pass management infrastructure. 144 // 145 //===----------------------------------------------------------------------===// 146 147 /// Structure of external `MlirPass` callbacks. 148 /// All callbacks are required to be set unless otherwise specified. 149 struct MlirExternalPassCallbacks { 150 /// This callback is called from the pass is created. 151 /// This is analogous to a C++ pass constructor. 152 void (*construct)(void *userData); 153 154 /// This callback is called when the pass is destroyed 155 /// This is analogous to a C++ pass destructor. 156 void (*destruct)(void *userData); 157 158 /// This callback is optional. 159 /// The callback is called before the pass is run, allowing a chance to 160 /// initialize any complex state necessary for running the pass. 161 /// See Pass::initialize(MLIRContext *). 162 MlirLogicalResult (*initialize)(MlirContext ctx, void *userData); 163 164 /// This callback is called when the pass is cloned. 165 /// See Pass::clonePass(). 166 void *(*clone)(void *userData); 167 168 /// This callback is called when the pass is run. 169 /// See Pass::runOnOperation(). 170 void (*run)(MlirOperation op, MlirExternalPass pass, void *userData); 171 }; 172 typedef struct MlirExternalPassCallbacks MlirExternalPassCallbacks; 173 174 /// Creates an external `MlirPass` that calls the supplied `callbacks` using the 175 /// supplied `userData`. If `opName` is empty, the pass is a generic operation 176 /// pass. Otherwise it is an operation pass specific to the specified pass name. 177 MLIR_CAPI_EXPORTED MlirPass mlirCreateExternalPass( 178 MlirTypeID passID, MlirStringRef name, MlirStringRef argument, 179 MlirStringRef description, MlirStringRef opName, 180 intptr_t nDependentDialects, MlirDialectHandle *dependentDialects, 181 MlirExternalPassCallbacks callbacks, void *userData); 182 183 /// This signals that the pass has failed. This is only valid to call during 184 /// the `run` callback of `MlirExternalPassCallbacks`. 185 /// See Pass::signalPassFailure(). 186 MLIR_CAPI_EXPORTED void mlirExternalPassSignalFailure(MlirExternalPass pass); 187 188 #ifdef __cplusplus 189 } 190 #endif 191 192 #endif // MLIR_C_PASS_H 193