MLIR  22.0.0git
Pass.h
Go to the documentation of this file.
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`.
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.
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.
89 mlirPassManagerEnableVerifier(MlirPassManager passManager, bool enable);
90 
91 /// Enable pass timing.
93 mlirPassManagerEnableTiming(MlirPassManager passManager);
94 
95 /// Nest an OpPassManager under the top-level PassManager, the nested
96 /// passmanager will only run on operations matching the provided name.
97 /// The returned OpPassManager will be destroyed when the parent is destroyed.
98 /// To further nest more OpPassManager under the newly returned one, see
99 /// `mlirOpPassManagerNest` below.
101  MlirPassManager passManager, MlirStringRef operationName);
102 
103 /// Nest an OpPassManager under the provided OpPassManager, the nested
104 /// passmanager will only run on operations matching the provided name.
105 /// The returned OpPassManager will be destroyed when the parent is destroyed.
107  MlirOpPassManager passManager, MlirStringRef operationName);
108 
109 /// Add a pass and transfer ownership to the provided top-level mlirPassManager.
110 /// If the pass is not a generic operation pass or a ModulePass, a new
111 /// OpPassManager is implicitly nested under the provided PassManager.
112 MLIR_CAPI_EXPORTED void mlirPassManagerAddOwnedPass(MlirPassManager passManager,
113  MlirPass pass);
114 
115 /// Add a pass and transfer ownership to the provided mlirOpPassManager. If the
116 /// pass is not a generic operation pass or matching the type of the provided
117 /// PassManager, a new OpPassManager is implicitly nested under the provided
118 /// PassManager.
120 mlirOpPassManagerAddOwnedPass(MlirOpPassManager passManager, MlirPass pass);
121 
122 /// Parse a sequence of textual MLIR pass pipeline elements and add them to the
123 /// provided OpPassManager. If parsing fails an error message is reported using
124 /// the provided callback.
126  MlirOpPassManager passManager, MlirStringRef pipelineElements,
127  MlirStringCallback callback, void *userData);
128 
129 /// Print a textual MLIR pass pipeline by sending chunks of the string
130 /// representation and forwarding `userData to `callback`. Note that the
131 /// callback may be called several times with consecutive chunks of the string.
132 MLIR_CAPI_EXPORTED void mlirPrintPassPipeline(MlirOpPassManager passManager,
133  MlirStringCallback callback,
134  void *userData);
135 
136 /// Parse a textual MLIR pass pipeline and assign it to the provided
137 /// OpPassManager. If parsing fails an error message is reported using the
138 /// provided callback.
140 mlirParsePassPipeline(MlirOpPassManager passManager, MlirStringRef pipeline,
141  MlirStringCallback callback, void *userData);
142 
143 //===----------------------------------------------------------------------===//
144 // External Pass API.
145 //
146 // This API allows to define passes outside of MLIR, not necessarily in
147 // C++, and register them with the MLIR pass management infrastructure.
148 //
149 //===----------------------------------------------------------------------===//
150 
151 /// Structure of external `MlirPass` callbacks.
152 /// All callbacks are required to be set unless otherwise specified.
154  /// This callback is called from the pass is created.
155  /// This is analogous to a C++ pass constructor.
156  void (*construct)(void *userData);
157 
158  /// This callback is called when the pass is destroyed
159  /// This is analogous to a C++ pass destructor.
160  void (*destruct)(void *userData);
161 
162  /// This callback is optional.
163  /// The callback is called before the pass is run, allowing a chance to
164  /// initialize any complex state necessary for running the pass.
165  /// See Pass::initialize(MLIRContext *).
166  MlirLogicalResult (*initialize)(MlirContext ctx, void *userData);
167 
168  /// This callback is called when the pass is cloned.
169  /// See Pass::clonePass().
170  void *(*clone)(void *userData);
171 
172  /// This callback is called when the pass is run.
173  /// See Pass::runOnOperation().
174  void (*run)(MlirOperation op, MlirExternalPass pass, void *userData);
175 };
177 
178 /// Creates an external `MlirPass` that calls the supplied `callbacks` using the
179 /// supplied `userData`. If `opName` is empty, the pass is a generic operation
180 /// pass. Otherwise it is an operation pass specific to the specified pass name.
182  MlirTypeID passID, MlirStringRef name, MlirStringRef argument,
183  MlirStringRef description, MlirStringRef opName,
184  intptr_t nDependentDialects, MlirDialectHandle *dependentDialects,
185  MlirExternalPassCallbacks callbacks, void *userData);
186 
187 /// This signals that the pass has failed. This is only valid to call during
188 /// the `run` callback of `MlirExternalPassCallbacks`.
189 /// See Pass::signalPassFailure().
190 MLIR_CAPI_EXPORTED void mlirExternalPassSignalFailure(MlirExternalPass pass);
191 
192 #ifdef __cplusplus
193 }
194 #endif
195 
196 #endif // MLIR_C_PASS_H
MLIR_CAPI_EXPORTED void mlirPrintPassPipeline(MlirOpPassManager passManager, MlirStringCallback callback, void *userData)
Print a textual MLIR pass pipeline by sending chunks of the string representation and forwarding user...
Definition: Pass.cpp:110
MLIR_CAPI_EXPORTED void mlirPassManagerEnableVerifier(MlirPassManager passManager, bool enable)
Enable / disable verify-each.
Definition: Pass.cpp:74
MLIR_CAPI_EXPORTED MlirOpPassManager mlirPassManagerGetNestedUnder(MlirPassManager passManager, MlirStringRef operationName)
Nest an OpPassManager under the top-level PassManager, the nested passmanager will only run on operat...
Definition: Pass.cpp:82
MLIR_CAPI_EXPORTED void mlirExternalPassSignalFailure(MlirExternalPass pass)
This signals that the pass has failed.
Definition: Pass.cpp:215
MLIR_CAPI_EXPORTED MlirOpPassManager mlirPassManagerGetAsOpPassManager(MlirPassManager passManager)
Cast a top-level PassManager to a generic OpPassManager.
Definition: Pass.cpp:38
MLIR_CAPI_EXPORTED MlirLogicalResult mlirPassManagerRunOnOp(MlirPassManager passManager, MlirOperation op)
Run the provided passManager on the given op.
Definition: Pass.cpp:42
MLIR_CAPI_EXPORTED void mlirPassManagerEnableTiming(MlirPassManager passManager)
Enable pass timing.
Definition: Pass.cpp:78
MLIR_CAPI_EXPORTED MlirPassManager mlirPassManagerCreate(MlirContext ctx)
Create a new top-level PassManager with the default anchor.
Definition: Pass.cpp:24
MLIR_CAPI_EXPORTED void mlirOpPassManagerAddOwnedPass(MlirOpPassManager passManager, MlirPass pass)
Add a pass and transfer ownership to the provided mlirOpPassManager.
Definition: Pass.cpp:96
MLIR_CAPI_EXPORTED void mlirPassManagerEnableIRPrinting(MlirPassManager passManager, bool printBeforeAll, bool printAfterAll, bool printModuleScope, bool printAfterOnlyOnChange, bool printAfterOnlyOnFailure, MlirOpPrintingFlags flags, MlirStringRef treePrintingPath)
Enable IR printing.
Definition: Pass.cpp:47
#define DEFINE_C_API_STRUCT(name, storage)
Definition: Pass.h:37
MLIR_CAPI_EXPORTED MlirLogicalResult mlirOpPassManagerAddPipeline(MlirOpPassManager passManager, MlirStringRef pipelineElements, MlirStringCallback callback, void *userData)
Parse a sequence of textual MLIR pass pipeline elements and add them to the provided OpPassManager.
Definition: Pass.cpp:101
MLIR_CAPI_EXPORTED MlirOpPassManager mlirOpPassManagerGetNestedUnder(MlirOpPassManager passManager, MlirStringRef operationName)
Nest an OpPassManager under the provided OpPassManager, the nested passmanager will only run on opera...
Definition: Pass.cpp:87
MLIR_CAPI_EXPORTED MlirPass mlirCreateExternalPass(MlirTypeID passID, MlirStringRef name, MlirStringRef argument, MlirStringRef description, MlirStringRef opName, intptr_t nDependentDialects, MlirDialectHandle *dependentDialects, MlirExternalPassCallbacks callbacks, void *userData)
Creates an external MlirPass that calls the supplied callbacks using the supplied userData.
Definition: Pass.cpp:200
MLIR_CAPI_EXPORTED void mlirPassManagerAddOwnedPass(MlirPassManager passManager, MlirPass pass)
Add a pass and transfer ownership to the provided top-level mlirPassManager.
Definition: Pass.cpp:92
static bool mlirPassManagerIsNull(MlirPassManager passManager)
Checks if a PassManager is null.
Definition: Pass.h:65
MLIR_CAPI_EXPORTED MlirLogicalResult mlirParsePassPipeline(MlirOpPassManager passManager, MlirStringRef pipeline, MlirStringCallback callback, void *userData)
Parse a textual MLIR pass pipeline and assign it to the provided OpPassManager.
Definition: Pass.cpp:116
MLIR_CAPI_EXPORTED MlirPassManager mlirPassManagerCreateOnOperation(MlirContext ctx, MlirStringRef anchorOp)
Create a new top-level PassManager anchored on anchorOp.
Definition: Pass.cpp:28
MLIR_CAPI_EXPORTED void mlirPassManagerDestroy(MlirPassManager passManager)
Destroy the provided PassManager.
Definition: Pass.cpp:33
struct MlirLogicalResult MlirLogicalResult
Definition: Support.h:119
#define MLIR_CAPI_EXPORTED
Definition: Support.h:46
void(* MlirStringCallback)(MlirStringRef, void *)
A callback for returning string references.
Definition: Support.h:105
Structure of external MlirPass callbacks.
Definition: Pass.h:153
void(* run)(MlirOperation op, MlirExternalPass pass, void *userData)
This callback is called when the pass is run.
Definition: Pass.h:174
MlirLogicalResult(* initialize)(MlirContext ctx, void *userData)
This callback is optional.
Definition: Pass.h:166
void(* destruct)(void *userData)
This callback is called when the pass is destroyed This is analogous to a C++ pass destructor.
Definition: Pass.h:160
void(* construct)(void *userData)
This callback is called from the pass is created.
Definition: Pass.h:156
A logical result value, essentially a boolean with named states.
Definition: Support.h:116
A pointer to a sized fragment of a string, not necessarily null-terminated.
Definition: Support.h:73