LLVM 20.0.0git
PassPlugin.h
Go to the documentation of this file.
1//===- llvm/Passes/PassPlugin.h - Public Plugin API -----------------------===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9// This defines the public entry point for new-PM pass plugins.
10//
11//===----------------------------------------------------------------------===//
12
13#ifndef LLVM_PASSES_PASSPLUGIN_H
14#define LLVM_PASSES_PASSPLUGIN_H
15
16#include "llvm/ADT/StringRef.h"
19#include "llvm/Support/Error.h"
20#include <cstdint>
21#include <string>
22
23namespace llvm {
24class PassBuilder;
25
26/// \macro LLVM_PLUGIN_API_VERSION
27/// Identifies the API version understood by this plugin.
28///
29/// When a plugin is loaded, the driver will check it's supported plugin version
30/// against that of the plugin. A mismatch is an error. The supported version
31/// will be incremented for ABI-breaking changes to the \c PassPluginLibraryInfo
32/// struct, i.e. when callbacks are added, removed, or reordered.
33#define LLVM_PLUGIN_API_VERSION 1
34
35extern "C" {
36/// Information about the plugin required to load its passes
37///
38/// This struct defines the core interface for pass plugins and is supposed to
39/// be filled out by plugin implementors. LLVM-side users of a plugin are
40/// expected to use the \c PassPlugin class below to interface with it.
42 /// The API version understood by this plugin, usually \c
43 /// LLVM_PLUGIN_API_VERSION
45 /// A meaningful name of the plugin.
46 const char *PluginName;
47 /// The version of the plugin.
48 const char *PluginVersion;
49
50 /// The callback for registering plugin passes with a \c PassBuilder
51 /// instance
53};
54}
55
56/// A loaded pass plugin.
57///
58/// An instance of this class wraps a loaded pass plugin and gives access to
59/// its interface defined by the \c PassPluginLibraryInfo it exposes.
61public:
62 /// Attempts to load a pass plugin from a given file.
63 ///
64 /// \returns Returns an error if either the library cannot be found or loaded,
65 /// there is no public entry point, or the plugin implements the wrong API
66 /// version.
67 static Expected<PassPlugin> Load(const std::string &Filename);
68
69 /// Get the filename of the loaded plugin.
70 StringRef getFilename() const { return Filename; }
71
72 /// Get the plugin name
73 StringRef getPluginName() const { return Info.PluginName; }
74
75 /// Get the plugin version
76 StringRef getPluginVersion() const { return Info.PluginVersion; }
77
78 /// Get the plugin API version
79 uint32_t getAPIVersion() const { return Info.APIVersion; }
80
81 /// Invoke the PassBuilder callback registration
84 }
85
86private:
87 PassPlugin(const std::string &Filename, const sys::DynamicLibrary &Library)
88 : Filename(Filename), Library(Library), Info() {}
89
90 std::string Filename;
91 sys::DynamicLibrary Library;
92 PassPluginLibraryInfo Info;
93};
94}
95
96/// The public entry point for a pass plugin.
97///
98/// When a plugin is loaded by the driver, it will call this entry point to
99/// obtain information about this plugin and about how to register its passes.
100/// This function needs to be implemented by the plugin, see the example below:
101///
102/// ```
103/// extern "C" ::llvm::PassPluginLibraryInfo LLVM_ATTRIBUTE_WEAK
104/// llvmGetPassPluginInfo() {
105/// return {
106/// LLVM_PLUGIN_API_VERSION, "MyPlugin", "v0.1", [](PassBuilder &PB) { ... }
107/// };
108/// }
109/// ```
112
113#endif /* LLVM_PASSES_PASSPLUGIN_H */
#define LLVM_ATTRIBUTE_WEAK
Definition: Compiler.h:207
PassBuilder PB(Machine, PassOpts->PTO, std::nullopt, &PIC)
::llvm::PassPluginLibraryInfo LLVM_ATTRIBUTE_WEAK llvmGetPassPluginInfo()
The public entry point for a pass plugin.
Tagged union holding either a T or a Error.
Definition: Error.h:481
This class provides access to building LLVM's passes.
Definition: PassBuilder.h:106
A loaded pass plugin.
Definition: PassPlugin.h:60
static Expected< PassPlugin > Load(const std::string &Filename)
Attempts to load a pass plugin from a given file.
Definition: PassPlugin.cpp:16
uint32_t getAPIVersion() const
Get the plugin API version.
Definition: PassPlugin.h:79
void registerPassBuilderCallbacks(PassBuilder &PB) const
Invoke the PassBuilder callback registration.
Definition: PassPlugin.h:82
StringRef getPluginVersion() const
Get the plugin version.
Definition: PassPlugin.h:76
StringRef getPluginName() const
Get the plugin name.
Definition: PassPlugin.h:73
StringRef getFilename() const
Get the filename of the loaded plugin.
Definition: PassPlugin.h:70
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:50
This class provides a portable interface to dynamic libraries which also might be known as shared lib...
This is an optimization pass for GlobalISel generic memory operations.
Definition: AddressRanges.h:18
Information about the plugin required to load its passes.
Definition: PassPlugin.h:41
const char * PluginName
A meaningful name of the plugin.
Definition: PassPlugin.h:46
uint32_t APIVersion
The API version understood by this plugin, usually LLVM_PLUGIN_API_VERSION.
Definition: PassPlugin.h:44
void(* RegisterPassBuilderCallbacks)(PassBuilder &)
The callback for registering plugin passes with a PassBuilder instance.
Definition: PassPlugin.h:52
const char * PluginVersion
The version of the plugin.
Definition: PassPlugin.h:48