/Users/buildslave/jenkins/workspace/clang-stage2-coverage-R/llvm/include/llvm/Passes/PassPlugin.h
Line | Count | Source (jump to first uncovered line) |
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" |
17 | | #include "llvm/Support/Compiler.h" |
18 | | #include "llvm/Support/DynamicLibrary.h" |
19 | | #include "llvm/Support/Error.h" |
20 | | #include <cstdint> |
21 | | #include <string> |
22 | | |
23 | | namespace llvm { |
24 | | class 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 | 2 | #define LLVM_PLUGIN_API_VERSION 1 |
34 | | |
35 | | extern "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. |
41 | | struct PassPluginLibraryInfo { |
42 | | /// The API version understood by this plugin, usually \c |
43 | | /// LLVM_PLUGIN_API_VERSION |
44 | | uint32_t APIVersion; |
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 |
52 | | void (*RegisterPassBuilderCallbacks)(PassBuilder &); |
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. |
60 | | class PassPlugin { |
61 | | public: |
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 | 0 | 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 | 0 | uint32_t getAPIVersion() const { return Info.APIVersion; } |
80 | | |
81 | | /// Invoke the PassBuilder callback registration |
82 | 1 | void registerPassBuilderCallbacks(PassBuilder &PB) const { |
83 | 1 | Info.RegisterPassBuilderCallbacks(PB); |
84 | 1 | } |
85 | | |
86 | | private: |
87 | | PassPlugin(const std::string &Filename, const sys::DynamicLibrary &Library) |
88 | 1 | : 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 | | /// ``` |
110 | | extern "C" ::llvm::PassPluginLibraryInfo LLVM_ATTRIBUTE_WEAK |
111 | | llvmGetPassPluginInfo(); |
112 | | |
113 | | #endif /* LLVM_PASSES_PASSPLUGIN_H */ |