1 //===- llvm/Passes/PassPlugin.h - Public Plugin API -----------------------===// 2 // 3 // The LLVM Compiler Infrastructure 4 // 5 // This file is distributed under the University of Illinois Open Source 6 // License. See LICENSE.TXT for details. 7 // 8 //===----------------------------------------------------------------------===// 9 // 10 // This defines the public entry point for new-PM pass plugins. 11 // 12 //===----------------------------------------------------------------------===// 13 14 #ifndef LLVM_PASSES_PASSPLUGIN_H 15 #define LLVM_PASSES_PASSPLUGIN_H 16 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 llvm { 25 class PassBuilder; 26 27 /// \macro LLVM_PLUGIN_API_VERSION 28 /// Identifies the API version understood by this plugin. 29 /// 30 /// When a plugin is loaded, the driver will check it's supported plugin version 31 /// against that of the plugin. A mismatch is an error. The supported version 32 /// will be incremented for ABI-breaking changes to the \c PassPluginLibraryInfo 33 /// struct, i.e. when callbacks are added, removed, or reordered. 34 #define LLVM_PLUGIN_API_VERSION 1 35 36 extern "C" { 37 /// Information about the plugin required to load its passes 38 /// 39 /// This struct defines the core interface for pass plugins and is supposed to 40 /// be filled out by plugin implementors. LLVM-side users of a plugin are 41 /// expected to use the \c PassPlugin class below to interface with it. 42 struct PassPluginLibraryInfo { 43 /// The API version understood by this plugin, usually \c 44 /// LLVM_PLUGIN_API_VERSION 45 uint32_t APIVersion; 46 /// A meaningful name of the plugin. 47 const char *PluginName; 48 /// The version of the plugin. 49 const char *PluginVersion; 50 51 /// The callback for registering plugin passes with a \c PassBuilder 52 /// instance 53 void (*RegisterPassBuilderCallbacks)(PassBuilder &); 54 }; 55 } 56 57 /// A loaded pass plugin. 58 /// 59 /// An instance of this class wraps a loaded pass plugin and gives access to 60 /// its interface defined by the \c PassPluginLibraryInfo it exposes. 61 class PassPlugin { 62 public: 63 /// Attempts to load a pass plugin from a given file. 64 /// 65 /// \returns Returns an error if either the library cannot be found or loaded, 66 /// there is no public entry point, or the plugin implements the wrong API 67 /// version. 68 static Expected<PassPlugin> Load(const std::string &Filename); 69 70 /// Get the filename of the loaded plugin. getFilename()71 StringRef getFilename() const { return Filename; } 72 73 /// Get the plugin name getPluginName()74 StringRef getPluginName() const { return Info.PluginName; } 75 76 /// Get the plugin version getPluginVersion()77 StringRef getPluginVersion() const { return Info.PluginVersion; } 78 79 /// Get the plugin API version getAPIVersion()80 uint32_t getAPIVersion() const { return Info.APIVersion; } 81 82 /// Invoke the PassBuilder callback registration registerPassBuilderCallbacks(PassBuilder & PB)83 void registerPassBuilderCallbacks(PassBuilder &PB) const { 84 Info.RegisterPassBuilderCallbacks(PB); 85 } 86 87 private: PassPlugin(const std::string & Filename,const sys::DynamicLibrary & Library)88 PassPlugin(const std::string &Filename, const sys::DynamicLibrary &Library) 89 : Filename(Filename), Library(Library), Info() {} 90 91 std::string Filename; 92 sys::DynamicLibrary Library; 93 PassPluginLibraryInfo Info; 94 }; 95 } 96 97 /// The public entry point for a pass plugin. 98 /// 99 /// When a plugin is loaded by the driver, it will call this entry point to 100 /// obtain information about this plugin and about how to register its passes. 101 /// This function needs to be implemented by the plugin, see the example below: 102 /// 103 /// ``` 104 /// extern "C" ::llvm::PassPluginLibraryInfo LLVM_ATTRIBUTE_WEAK 105 /// llvmGetPassPluginInfo() { 106 /// return { 107 /// LLVM_PLUGIN_API_VERSION, "MyPlugin", "v0.1", [](PassBuilder &PB) { ... } 108 /// }; 109 /// } 110 /// ``` 111 extern "C" ::llvm::PassPluginLibraryInfo LLVM_ATTRIBUTE_WEAK 112 llvmGetPassPluginInfo(); 113 114 #endif /* LLVM_PASSES_PASSPLUGIN_H */ 115