mlir/include/mlir-c/Pass.h

   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