Line data    Source code

       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           2 : 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           0 :   StringRef getPluginName() const { return Info.PluginName; }
      75             : 
      76             :   /// Get the plugin version
      77           0 :   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           0 :   void registerPassBuilderCallbacks(PassBuilder &PB) const {
      84           1 :     Info.RegisterPassBuilderCallbacks(PB);
      85           0 :   }
      86             : 
      87             : private:
      88             :   PassPlugin(const std::string &Filename, const sys::DynamicLibrary &Library)
      89           1 :       : 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 */