PassPlugin.h

Go to the documentation of this file.

//===----------------------------------------------------------------------===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
//
// This defines the public entry point for new-PM pass plugins.
//
//===----------------------------------------------------------------------===//
 
#ifndef LLVM_PLUGINS_PASSPLUGIN_H
#define LLVM_PLUGINS_PASSPLUGIN_H
 
#include "llvm/ADT/ArrayRef.h"
#include "llvm/ADT/StringRef.h"
#include "llvm/Support/CodeGen.h"
#include "llvm/Support/Compiler.h"
#include "llvm/Support/DynamicLibrary.h"
#include "llvm/Support/Error.h"
#include <cstdint>
#include <string>
 
namespace llvm {
class Module;
class PassBuilder;
class TargetMachine;
 
/// \macro LLVM_PLUGIN_API_VERSION
/// Identifies the API version understood by this plugin.
///
/// When a plugin is loaded, the driver will check it's supported plugin version
/// against that of the plugin. A mismatch is an error. The supported version
/// will be incremented for ABI-breaking changes to the \c PassPluginLibraryInfo
/// struct, i.e. when callbacks are added, removed, or reordered.
#define LLVM_PLUGIN_API_VERSION 3
 
extern "C" {
/// Information about the plugin required to load its passes
///
/// This struct defines the core interface for pass plugins and is supposed to
/// be filled out by plugin implementors. Unused function pointers can be set to
/// nullptr. LLVM-side users of a plugin are expected to use the \c PassPlugin
/// class below to interface with it.
struct PassPluginLibraryInfo {
  /// The API version understood by this plugin, usually \c
  /// LLVM_PLUGIN_API_VERSION
  uint32_t APIVersion;
  /// A meaningful name of the plugin. -plugin-arg=<PluginName>,<arg> passes
  /// <arg> to the plugin with this name.
  const char *PluginName;
  /// The version of the plugin.
  const char *PluginVersion;
 
  /// The callback for registering plugin passes with a \c PassBuilder
  /// instance
  void (*RegisterPassBuilderCallbacks)(PassBuilder &) = nullptr;
 
  /// Callback called before running the back-end passes on the module. The
  /// callback can generate code itself by writing the expected output to OS and
  /// returning true to prevent the default pipeline and further plugin
  /// callbacks from running.
  bool (*PreCodeGenCallback)(Module &, TargetMachine &, CodeGenFileType,
                             raw_pwrite_stream &OS) = nullptr;
 
  /// Callback receiving the arguments given to the plugin, e.g. by
  /// -plugin-arg=<PluginName>,<arg>, in order.
  Error (*ParseArguments)(ArrayRef<const char *> Args) = nullptr;
};
}
 
/// A loaded pass plugin.
///
/// An instance of this class wraps a loaded pass plugin and gives access to
/// its interface defined by the \c PassPluginLibraryInfo it exposes.
class PassPlugin {
public:
  /// Attempts to load a pass plugin from a given file.
  ///
  /// \returns Returns an error if either the library cannot be found or loaded,
  /// there is no public entry point, or the plugin implements the wrong API
  /// version.
  LLVM_ABI static Expected<PassPlugin> load(StringRef Filename);
 
  /// Get the filename of the loaded plugin.
  StringRef getFilename() const { return Filename; }
 
  /// Get the plugin name
  StringRef getPluginName() const { return Info.PluginName; }
 
  /// Get the plugin version
  StringRef getPluginVersion() const { return Info.PluginVersion; }
 
  /// Get the plugin API version
  uint32_t getAPIVersion() const { return Info.APIVersion; }
 
  const PassPluginLibraryInfo &getInfo() const { return Info; }
 
  /// Invoke the PassBuilder callback registration
  void registerPassBuilderCallbacks(PassBuilder &PB) const {
    if (Info.RegisterPassBuilderCallbacks)
      Info.RegisterPassBuilderCallbacks(PB);
  }
 
  /// Invoke the pre-codegen callback.
  bool invokePreCodeGenCallback(Module &M, TargetMachine &TM,
                                CodeGenFileType CGFT,
                                raw_pwrite_stream &OS) const {
    if (Info.PreCodeGenCallback)
      return Info.PreCodeGenCallback(M, TM, CGFT, OS);
    return false;
  }
 
private:
  PassPlugin(const std::string &Filename, const sys::DynamicLibrary &Library)
      : Filename(Filename), Library(Library), Info() {}
 
  std::string Filename;
  sys::DynamicLibrary Library;
  PassPluginLibraryInfo Info;
};
 
/// Passes each "<PluginName>,<arg>" in \p Args to the \c ParseArguments
/// callback of the extension in \p Infos with that name. Two extensions with
/// the same name are an error.
LLVM_ABI Error passPluginArguments(ArrayRef<PassPluginLibraryInfo> Infos,
                                   ArrayRef<std::string> Args);
} // namespace llvm
 
// The function returns a struct with default initializers.
#ifdef __clang__
#pragma clang diagnostic push
#pragma clang diagnostic ignored "-Wreturn-type-c-linkage"
#endif
/// The public entry point for a pass plugin.
///
/// When a plugin is loaded by the driver, it will call this entry point to
/// obtain information about this plugin and about how to register its passes.
/// This function needs to be implemented by the plugin, see the example below:
///
/// ```
/// extern "C" ::llvm::PassPluginLibraryInfo LLVM_ATTRIBUTE_WEAK
/// llvmGetPassPluginInfo() {
///   return {
///     LLVM_PLUGIN_API_VERSION, "MyPlugin", "v0.1", [](PassBuilder &PB) { ... }
///   };
/// }
/// ```
extern "C" LLVM_ABI_NOT_EXPORTED ::llvm::PassPluginLibraryInfo
    LLVM_ATTRIBUTE_WEAK
    llvmGetPassPluginInfo();
#ifdef __clang__
#pragma clang diagnostic pop
#endif
 
#endif /* LLVM_PLUGINS_PASSPLUGIN_H */