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
21extern "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
43DEFINE_C_API_STRUCT(MlirPass, void);
44DEFINE_C_API_STRUCT(MlirExternalPass, void);
45DEFINE_C_API_STRUCT(MlirPassManager, void);
46DEFINE_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.
55MLIR_CAPI_EXPORTED MlirPassManager mlirPassManagerCreate(MlirContext ctx);
56
57/// Create a new top-level PassManager anchored on `anchorOp`.
58MLIR_CAPI_EXPORTED MlirPassManager
59mlirPassManagerCreateOnOperation(MlirContext ctx, MlirStringRef anchorOp);
60
61/// Destroy the provided PassManager.
62MLIR_CAPI_EXPORTED void mlirPassManagerDestroy(MlirPassManager passManager);
63
64/// Checks if a PassManager is null.
65static inline bool mlirPassManagerIsNull(MlirPassManager passManager) {
66 return !passManager.ptr;
67}
68
69/// Cast a top-level PassManager to a generic OpPassManager.
70MLIR_CAPI_EXPORTED MlirOpPassManager
71mlirPassManagerGetAsOpPassManager(MlirPassManager passManager);
72
73/// Run the provided `passManager` on the given `op`.
74MLIR_CAPI_EXPORTED MlirLogicalResult
75mlirPassManagerRunOnOp(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.
81MLIR_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.
88MLIR_CAPI_EXPORTED void
89mlirPassManagerEnableVerifier(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.
96MLIR_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.
102MLIR_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.
108MLIR_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.
115MLIR_CAPI_EXPORTED void
116mlirOpPassManagerAddOwnedPass(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.
121MLIR_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.
128MLIR_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.
135MLIR_CAPI_EXPORTED MlirLogicalResult
136mlirParsePassPipeline(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.
149struct 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};
172typedef 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.
177MLIR_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().
186MLIR_CAPI_EXPORTED void mlirExternalPassSignalFailure(MlirExternalPass pass);
187
188#ifdef __cplusplus
189}
190#endif
191
192#endif // MLIR_C_PASS_H
193

source code of mlir/include/mlir-c/Pass.h