1 //===- mlir/Tools/Plugins/PassPlugin.h - Public Plugin API ----------------===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 // 9 // This defines the public entry point for pass plugins. 10 // 11 //===----------------------------------------------------------------------===// 12 13 #ifndef MLIR_TOOLS_PLUGINS_PASSPLUGIN_H 14 #define MLIR_TOOLS_PLUGINS_PASSPLUGIN_H 15 16 #include "mlir/Support/LLVM.h" 17 #include "llvm/ADT/StringRef.h" 18 #include "llvm/Support/Compiler.h" 19 #include "llvm/Support/DynamicLibrary.h" 20 #include "llvm/Support/Error.h" 21 #include <cstdint> 22 #include <string> 23 24 namespace mlir { 25 /// \macro MLIR_PLUGIN_API_VERSION 26 /// Identifies the API version understood by this plugin. 27 /// 28 /// When a plugin is loaded, the driver will check it's supported plugin version 29 /// against that of the plugin. A mismatch is an error. The supported version 30 /// will be incremented for ABI-breaking changes to the \c PassPluginLibraryInfo 31 /// struct, i.e. when callbacks are added, removed, or reordered. 32 #define MLIR_PLUGIN_API_VERSION 1 33 34 extern "C" { 35 /// Information about the plugin required to load its passes 36 /// 37 /// This struct defines the core interface for pass plugins and is supposed to 38 /// be filled out by plugin implementors. LLVM-side users of a plugin are 39 /// expected to use the \c PassPlugin class below to interface with it. 40 struct PassPluginLibraryInfo { 41 /// The API version understood by this plugin, usually \c 42 /// MLIR_PLUGIN_API_VERSION 43 uint32_t apiVersion; 44 /// A meaningful name of the plugin. 45 const char *pluginName; 46 /// The version of the plugin. 47 const char *pluginVersion; 48 49 /// The callback for registering plugin passes. 50 void (*registerPassRegistryCallbacks)(); 51 }; 52 } 53 54 /// A loaded pass plugin. 55 /// 56 /// An instance of this class wraps a loaded pass plugin and gives access to 57 /// its interface defined by the \c PassPluginLibraryInfo it exposes. 58 class PassPlugin { 59 public: 60 /// Attempts to load a pass plugin from a given file. 61 /// 62 /// \returns Returns an error if either the library cannot be found or loaded, 63 /// there is no public entry point, or the plugin implements the wrong API 64 /// version. 65 static llvm::Expected<PassPlugin> load(const std::string &filename); 66 67 /// Get the filename of the loaded plugin. getFilename()68 StringRef getFilename() const { return filename; } 69 70 /// Get the plugin name getPluginName()71 StringRef getPluginName() const { return info.pluginName; } 72 73 /// Get the plugin version getPluginVersion()74 StringRef getPluginVersion() const { return info.pluginVersion; } 75 76 /// Get the plugin API version getAPIVersion()77 uint32_t getAPIVersion() const { return info.apiVersion; } 78 79 /// Invoke the PassRegistry callback registration registerPassRegistryCallbacks()80 void registerPassRegistryCallbacks() const { 81 info.registerPassRegistryCallbacks(); 82 } 83 84 private: PassPlugin(const std::string & filename,const llvm::sys::DynamicLibrary & library)85 PassPlugin(const std::string &filename, 86 const llvm::sys::DynamicLibrary &library) 87 : filename(filename), library(library), info() {} 88 89 std::string filename; 90 llvm::sys::DynamicLibrary library; 91 PassPluginLibraryInfo info; 92 }; 93 } // namespace mlir 94 95 /// The public entry point for a pass plugin. 96 /// 97 /// When a plugin is loaded by the driver, it will call this entry point to 98 /// obtain information about this plugin and about how to register its passes. 99 /// This function needs to be implemented by the plugin, see the example below: 100 /// 101 /// ``` 102 /// extern "C" ::mlir::PassPluginLibraryInfo LLVM_ATTRIBUTE_WEAK 103 /// mlirGetPassPluginInfo() { 104 /// return { 105 /// MLIR_PLUGIN_API_VERSION, "MyPlugin", "v0.1", []() { ... } 106 /// }; 107 /// } 108 /// ``` 109 extern "C" ::mlir::PassPluginLibraryInfo LLVM_ATTRIBUTE_WEAK 110 mlirGetPassPluginInfo(); 111 112 #endif /* MLIR_TOOLS_PLUGINS_PASSPLUGIN_H */ 113