llvm/Passes/PassPlugin.h

0001 //===- llvm/Passes/PassPlugin.h - Public Plugin API -----------------------===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008 //
0009 // This defines the public entry point for new-PM pass plugins.
0010 //
0011 //===----------------------------------------------------------------------===//
0012
0013 #ifndef LLVM_PASSES_PASSPLUGIN_H
0014 #define LLVM_PASSES_PASSPLUGIN_H
0015
0016 #include "llvm/ADT/StringRef.h"
0017 #include "llvm/Support/Compiler.h"
0018 #include "llvm/Support/DynamicLibrary.h"
0019 #include "llvm/Support/Error.h"
0020 #include <cstdint>
0021 #include <string>
0022
0023 namespace llvm {
0024 class PassBuilder;
0025
0026 /// \macro LLVM_PLUGIN_API_VERSION
0027 /// Identifies the API version understood by this plugin.
0028 ///
0029 /// When a plugin is loaded, the driver will check it's supported plugin version
0030 /// against that of the plugin. A mismatch is an error. The supported version
0031 /// will be incremented for ABI-breaking changes to the \c PassPluginLibraryInfo
0032 /// struct, i.e. when callbacks are added, removed, or reordered.
0033 #define LLVM_PLUGIN_API_VERSION 1
0034
0035 extern "C" {
0036 /// Information about the plugin required to load its passes
0037 ///
0038 /// This struct defines the core interface for pass plugins and is supposed to
0039 /// be filled out by plugin implementors. LLVM-side users of a plugin are
0040 /// expected to use the \c PassPlugin class below to interface with it.
0041 struct PassPluginLibraryInfo {
0042   /// The API version understood by this plugin, usually \c
0043   /// LLVM_PLUGIN_API_VERSION
0044   uint32_t APIVersion;
0045   /// A meaningful name of the plugin.
0046   const char *PluginName;
0047   /// The version of the plugin.
0048   const char *PluginVersion;
0049
0050   /// The callback for registering plugin passes with a \c PassBuilder
0051   /// instance
0052   void (*RegisterPassBuilderCallbacks)(PassBuilder &);
0053 };
0054 }
0055
0056 /// A loaded pass plugin.
0057 ///
0058 /// An instance of this class wraps a loaded pass plugin and gives access to
0059 /// its interface defined by the \c PassPluginLibraryInfo it exposes.
0060 class PassPlugin {
0061 public:
0062   /// Attempts to load a pass plugin from a given file.
0063   ///
0064   /// \returns Returns an error if either the library cannot be found or loaded,
0065   /// there is no public entry point, or the plugin implements the wrong API
0066   /// version.
0067   static Expected<PassPlugin> Load(const std::string &Filename);
0068
0069   /// Get the filename of the loaded plugin.
0070   StringRef getFilename() const { return Filename; }
0071
0072   /// Get the plugin name
0073   StringRef getPluginName() const { return Info.PluginName; }
0074
0075   /// Get the plugin version
0076   StringRef getPluginVersion() const { return Info.PluginVersion; }
0077
0078   /// Get the plugin API version
0079   uint32_t getAPIVersion() const { return Info.APIVersion; }
0080
0081   /// Invoke the PassBuilder callback registration
0082   void registerPassBuilderCallbacks(PassBuilder &PB) const {
0083     Info.RegisterPassBuilderCallbacks(PB);
0084   }
0085
0086 private:
0087   PassPlugin(const std::string &Filename, const sys::DynamicLibrary &Library)
0088       : Filename(Filename), Library(Library), Info() {}
0089
0090   std::string Filename;
0091   sys::DynamicLibrary Library;
0092   PassPluginLibraryInfo Info;
0093 };
0094 }
0095
0096 /// The public entry point for a pass plugin.
0097 ///
0098 /// When a plugin is loaded by the driver, it will call this entry point to
0099 /// obtain information about this plugin and about how to register its passes.
0100 /// This function needs to be implemented by the plugin, see the example below:
0101 ///
0102 /// ```
0103 /// extern "C" ::llvm::PassPluginLibraryInfo LLVM_ATTRIBUTE_WEAK
0104 /// llvmGetPassPluginInfo() {
0105 ///   return {
0106 ///     LLVM_PLUGIN_API_VERSION, "MyPlugin", "v0.1", [](PassBuilder &PB) { ... }
0107 ///   };
0108 /// }
0109 /// ```
0110 extern "C" ::llvm::PassPluginLibraryInfo LLVM_ATTRIBUTE_WEAK
0111 llvmGetPassPluginInfo();
0112
0113 #endif /* LLVM_PASSES_PASSPLUGIN_H */