contrib/llvm/include/llvm/Passes/PassPlugin.h

   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.
  71   StringRef getFilename() const { return Filename; }
  72
  73   /// Get the plugin name
  74   StringRef getPluginName() const { return Info.PluginName; }
  75
  76   /// Get the plugin version
  77   StringRef getPluginVersion() const { return Info.PluginVersion; }
  78
  79   /// Get the plugin API version
  80   uint32_t getAPIVersion() const { return Info.APIVersion; }
  81
  82   /// Invoke the PassBuilder callback registration
  83   void registerPassBuilderCallbacks(PassBuilder &PB) const {
  84     Info.RegisterPassBuilderCallbacks(PB);
  85   }
  86
  87 private:
  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 */