209 lines · c
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 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 C interface to MLIR pass manager.11//12//===----------------------------------------------------------------------===//13 14#ifndef MLIR_C_PASS_H15#define MLIR_C_PASS_H16 17#include "mlir-c/IR.h"18#include "mlir-c/Support.h"19 20#ifdef __cplusplus21extern "C" {22#endif23 24//===----------------------------------------------------------------------===//25// Opaque type declarations.26//27// Types are exposed to C bindings as structs containing opaque pointers. They28// are not supposed to be inspected from C. This allows the underlying29// representation to change without affecting the API users. The use of structs30// instead of typedefs enables some type safety as structs are not implicitly31// convertible to each other.32//33// Instances of these types may or may not own the underlying object. The34// 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 name42 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_STRUCT49 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 MlirPassManager59mlirPassManagerCreateOnOperation(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 MlirOpPassManager71mlirPassManagerGetAsOpPassManager(MlirPassManager passManager);72 73/// Run the provided `passManager` on the given `op`.74MLIR_CAPI_EXPORTED MlirLogicalResult75mlirPassManagerRunOnOp(MlirPassManager passManager, MlirOperation op);76 77/// Enable IR printing.78/// The treePrintingPath argument is an optional path to a directory79/// where the dumps will be produced. If it isn't provided then dumps80/// 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 void89mlirPassManagerEnableVerifier(MlirPassManager passManager, bool enable);90 91/// Enable pass timing.92MLIR_CAPI_EXPORTED void93mlirPassManagerEnableTiming(MlirPassManager passManager);94 95/// Enumerated type of pass display modes.96/// Mainly used in mlirPassManagerEnableStatistics.97typedef enum {98 MLIR_PASS_DISPLAY_MODE_LIST,99 MLIR_PASS_DISPLAY_MODE_PIPELINE,100} MlirPassDisplayMode;101 102/// Enable pass statistics.103MLIR_CAPI_EXPORTED void104mlirPassManagerEnableStatistics(MlirPassManager passManager,105 MlirPassDisplayMode displayMode);106 107/// Nest an OpPassManager under the top-level PassManager, the nested108/// passmanager will only run on operations matching the provided name.109/// The returned OpPassManager will be destroyed when the parent is destroyed.110/// To further nest more OpPassManager under the newly returned one, see111/// `mlirOpPassManagerNest` below.112MLIR_CAPI_EXPORTED MlirOpPassManager mlirPassManagerGetNestedUnder(113 MlirPassManager passManager, MlirStringRef operationName);114 115/// Nest an OpPassManager under the provided OpPassManager, the nested116/// passmanager will only run on operations matching the provided name.117/// The returned OpPassManager will be destroyed when the parent is destroyed.118MLIR_CAPI_EXPORTED MlirOpPassManager mlirOpPassManagerGetNestedUnder(119 MlirOpPassManager passManager, MlirStringRef operationName);120 121/// Add a pass and transfer ownership to the provided top-level mlirPassManager.122/// If the pass is not a generic operation pass or a ModulePass, a new123/// OpPassManager is implicitly nested under the provided PassManager.124MLIR_CAPI_EXPORTED void mlirPassManagerAddOwnedPass(MlirPassManager passManager,125 MlirPass pass);126 127/// Add a pass and transfer ownership to the provided mlirOpPassManager. If the128/// pass is not a generic operation pass or matching the type of the provided129/// PassManager, a new OpPassManager is implicitly nested under the provided130/// PassManager.131MLIR_CAPI_EXPORTED void132mlirOpPassManagerAddOwnedPass(MlirOpPassManager passManager, MlirPass pass);133 134/// Parse a sequence of textual MLIR pass pipeline elements and add them to the135/// provided OpPassManager. If parsing fails an error message is reported using136/// the provided callback.137MLIR_CAPI_EXPORTED MlirLogicalResult mlirOpPassManagerAddPipeline(138 MlirOpPassManager passManager, MlirStringRef pipelineElements,139 MlirStringCallback callback, void *userData);140 141/// Print a textual MLIR pass pipeline by sending chunks of the string142/// representation and forwarding `userData to `callback`. Note that the143/// callback may be called several times with consecutive chunks of the string.144MLIR_CAPI_EXPORTED void mlirPrintPassPipeline(MlirOpPassManager passManager,145 MlirStringCallback callback,146 void *userData);147 148/// Parse a textual MLIR pass pipeline and assign it to the provided149/// OpPassManager. If parsing fails an error message is reported using the150/// provided callback.151MLIR_CAPI_EXPORTED MlirLogicalResult152mlirParsePassPipeline(MlirOpPassManager passManager, MlirStringRef pipeline,153 MlirStringCallback callback, void *userData);154 155//===----------------------------------------------------------------------===//156// External Pass API.157//158// This API allows to define passes outside of MLIR, not necessarily in159// C++, and register them with the MLIR pass management infrastructure.160//161//===----------------------------------------------------------------------===//162 163/// Structure of external `MlirPass` callbacks.164/// All callbacks are required to be set unless otherwise specified.165struct MlirExternalPassCallbacks {166 /// This callback is called from the pass is created.167 /// This is analogous to a C++ pass constructor.168 void (*construct)(void *userData);169 170 /// This callback is called when the pass is destroyed171 /// This is analogous to a C++ pass destructor.172 void (*destruct)(void *userData);173 174 /// This callback is optional.175 /// The callback is called before the pass is run, allowing a chance to176 /// initialize any complex state necessary for running the pass.177 /// See Pass::initialize(MLIRContext *).178 MlirLogicalResult (*initialize)(MlirContext ctx, void *userData);179 180 /// This callback is called when the pass is cloned.181 /// See Pass::clonePass().182 void *(*clone)(void *userData);183 184 /// This callback is called when the pass is run.185 /// See Pass::runOnOperation().186 void (*run)(MlirOperation op, MlirExternalPass pass, void *userData);187};188typedef struct MlirExternalPassCallbacks MlirExternalPassCallbacks;189 190/// Creates an external `MlirPass` that calls the supplied `callbacks` using the191/// supplied `userData`. If `opName` is empty, the pass is a generic operation192/// pass. Otherwise it is an operation pass specific to the specified pass name.193MLIR_CAPI_EXPORTED MlirPass mlirCreateExternalPass(194 MlirTypeID passID, MlirStringRef name, MlirStringRef argument,195 MlirStringRef description, MlirStringRef opName,196 intptr_t nDependentDialects, MlirDialectHandle *dependentDialects,197 MlirExternalPassCallbacks callbacks, void *userData);198 199/// This signals that the pass has failed. This is only valid to call during200/// the `run` callback of `MlirExternalPassCallbacks`.201/// See Pass::signalPassFailure().202MLIR_CAPI_EXPORTED void mlirExternalPassSignalFailure(MlirExternalPass pass);203 204#ifdef __cplusplus205}206#endif207 208#endif // MLIR_C_PASS_H209