1 | //===- llvm/LLVMContext.h - Class for managing "global" state ---*- C++ -*-===// |
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 file declares LLVMContext, a container of "global" state in LLVM, such |
10 | // as the global type and constant uniquing tables. |
11 | // |
12 | //===----------------------------------------------------------------------===// |
13 | |
14 | #ifndef LLVM_IR_LLVMCONTEXT_H |
15 | #define LLVM_IR_LLVMCONTEXT_H |
16 | |
17 | #include "llvm-c/Types.h" |
18 | #include "llvm/IR/DiagnosticHandler.h" |
19 | #include "llvm/Support/CBindingWrapping.h" |
20 | #include <cstdint> |
21 | #include <memory> |
22 | #include <optional> |
23 | #include <string> |
24 | |
25 | namespace llvm { |
26 | |
27 | class DiagnosticInfo; |
28 | enum DiagnosticSeverity : char; |
29 | class Function; |
30 | class Instruction; |
31 | class LLVMContextImpl; |
32 | class Module; |
33 | class OptPassGate; |
34 | template <typename T> class SmallVectorImpl; |
35 | template <typename T> class StringMapEntry; |
36 | class StringRef; |
37 | class Twine; |
38 | class ; |
39 | |
40 | namespace remarks { |
41 | class ; |
42 | } |
43 | |
44 | namespace SyncScope { |
45 | |
46 | typedef uint8_t ID; |
47 | |
48 | /// Known synchronization scope IDs, which always have the same value. All |
49 | /// synchronization scope IDs that LLVM has special knowledge of are listed |
50 | /// here. Additionally, this scheme allows LLVM to efficiently check for |
51 | /// specific synchronization scope ID without comparing strings. |
52 | enum { |
53 | /// Synchronized with respect to signal handlers executing in the same thread. |
54 | SingleThread = 0, |
55 | |
56 | /// Synchronized with respect to all concurrently executing threads. |
57 | System = 1 |
58 | }; |
59 | |
60 | } // end namespace SyncScope |
61 | |
62 | /// This is an important class for using LLVM in a threaded context. It |
63 | /// (opaquely) owns and manages the core "global" data of LLVM's core |
64 | /// infrastructure, including the type and constant uniquing tables. |
65 | /// LLVMContext itself provides no locking guarantees, so you should be careful |
66 | /// to have one context per thread. |
67 | class LLVMContext { |
68 | public: |
69 | LLVMContextImpl *const pImpl; |
70 | LLVMContext(); |
71 | LLVMContext(const LLVMContext &) = delete; |
72 | LLVMContext &operator=(const LLVMContext &) = delete; |
73 | ~LLVMContext(); |
74 | |
75 | // Pinned metadata names, which always have the same value. This is a |
76 | // compile-time performance optimization, not a correctness optimization. |
77 | enum : unsigned { |
78 | #define LLVM_FIXED_MD_KIND(EnumID, Name, Value) EnumID = Value, |
79 | #include "llvm/IR/FixedMetadataKinds.def" |
80 | #undef LLVM_FIXED_MD_KIND |
81 | }; |
82 | |
83 | /// Known operand bundle tag IDs, which always have the same value. All |
84 | /// operand bundle tags that LLVM has special knowledge of are listed here. |
85 | /// Additionally, this scheme allows LLVM to efficiently check for specific |
86 | /// operand bundle tags without comparing strings. Keep this in sync with |
87 | /// LLVMContext::LLVMContext(). |
88 | enum : unsigned { |
89 | OB_deopt = 0, // "deopt" |
90 | OB_funclet = 1, // "funclet" |
91 | OB_gc_transition = 2, // "gc-transition" |
92 | OB_cfguardtarget = 3, // "cfguardtarget" |
93 | OB_preallocated = 4, // "preallocated" |
94 | OB_gc_live = 5, // "gc-live" |
95 | OB_clang_arc_attachedcall = 6, // "clang.arc.attachedcall" |
96 | OB_ptrauth = 7, // "ptrauth" |
97 | OB_kcfi = 8, // "kcfi" |
98 | OB_convergencectrl = 9, // "convergencectrl" |
99 | }; |
100 | |
101 | /// getMDKindID - Return a unique non-zero ID for the specified metadata kind. |
102 | /// This ID is uniqued across modules in the current LLVMContext. |
103 | unsigned getMDKindID(StringRef Name) const; |
104 | |
105 | /// getMDKindNames - Populate client supplied SmallVector with the name for |
106 | /// custom metadata IDs registered in this LLVMContext. |
107 | void getMDKindNames(SmallVectorImpl<StringRef> &Result) const; |
108 | |
109 | /// getOperandBundleTags - Populate client supplied SmallVector with the |
110 | /// bundle tags registered in this LLVMContext. The bundle tags are ordered |
111 | /// by increasing bundle IDs. |
112 | /// \see LLVMContext::getOperandBundleTagID |
113 | void getOperandBundleTags(SmallVectorImpl<StringRef> &Result) const; |
114 | |
115 | /// getOrInsertBundleTag - Returns the Tag to use for an operand bundle of |
116 | /// name TagName. |
117 | StringMapEntry<uint32_t> *getOrInsertBundleTag(StringRef TagName) const; |
118 | |
119 | /// getOperandBundleTagID - Maps a bundle tag to an integer ID. Every bundle |
120 | /// tag registered with an LLVMContext has an unique ID. |
121 | uint32_t getOperandBundleTagID(StringRef Tag) const; |
122 | |
123 | /// getOrInsertSyncScopeID - Maps synchronization scope name to |
124 | /// synchronization scope ID. Every synchronization scope registered with |
125 | /// LLVMContext has unique ID except pre-defined ones. |
126 | SyncScope::ID getOrInsertSyncScopeID(StringRef SSN); |
127 | |
128 | /// getSyncScopeNames - Populates client supplied SmallVector with |
129 | /// synchronization scope names registered with LLVMContext. Synchronization |
130 | /// scope names are ordered by increasing synchronization scope IDs. |
131 | void getSyncScopeNames(SmallVectorImpl<StringRef> &SSNs) const; |
132 | |
133 | /// Define the GC for a function |
134 | void setGC(const Function &Fn, std::string GCName); |
135 | |
136 | /// Return the GC for a function |
137 | const std::string &getGC(const Function &Fn); |
138 | |
139 | /// Remove the GC for a function |
140 | void deleteGC(const Function &Fn); |
141 | |
142 | /// Return true if the Context runtime configuration is set to discard all |
143 | /// value names. When true, only GlobalValue names will be available in the |
144 | /// IR. |
145 | bool shouldDiscardValueNames() const; |
146 | |
147 | /// Set the Context runtime configuration to discard all value name (but |
148 | /// GlobalValue). Clients can use this flag to save memory and runtime, |
149 | /// especially in release mode. |
150 | void setDiscardValueNames(bool Discard); |
151 | |
152 | /// Whether there is a string map for uniquing debug info |
153 | /// identifiers across the context. Off by default. |
154 | bool isODRUniquingDebugTypes() const; |
155 | void enableDebugTypeODRUniquing(); |
156 | void disableDebugTypeODRUniquing(); |
157 | |
158 | /// Defines the type of a yield callback. |
159 | /// \see LLVMContext::setYieldCallback. |
160 | using YieldCallbackTy = void (*)(LLVMContext *Context, void *OpaqueHandle); |
161 | |
162 | /// setDiagnosticHandlerCallBack - This method sets a handler call back |
163 | /// that is invoked when the backend needs to report anything to the user. |
164 | /// The first argument is a function pointer and the second is a context pointer |
165 | /// that gets passed into the DiagHandler. The third argument should be set to |
166 | /// true if the handler only expects enabled diagnostics. |
167 | /// |
168 | /// LLVMContext doesn't take ownership or interpret either of these |
169 | /// pointers. |
170 | void setDiagnosticHandlerCallBack( |
171 | DiagnosticHandler::DiagnosticHandlerTy DiagHandler, |
172 | void *DiagContext = nullptr, bool RespectFilters = false); |
173 | |
174 | /// setDiagnosticHandler - This method sets unique_ptr to object of |
175 | /// DiagnosticHandler to provide custom diagnostic handling. The first |
176 | /// argument is unique_ptr of object of type DiagnosticHandler or a derived |
177 | /// of that. The second argument should be set to true if the handler only |
178 | /// expects enabled diagnostics. |
179 | /// |
180 | /// Ownership of this pointer is moved to LLVMContextImpl. |
181 | void setDiagnosticHandler(std::unique_ptr<DiagnosticHandler> &&DH, |
182 | bool RespectFilters = false); |
183 | |
184 | /// getDiagnosticHandlerCallBack - Return the diagnostic handler call back set by |
185 | /// setDiagnosticHandlerCallBack. |
186 | DiagnosticHandler::DiagnosticHandlerTy getDiagnosticHandlerCallBack() const; |
187 | |
188 | /// getDiagnosticContext - Return the diagnostic context set by |
189 | /// setDiagnosticContext. |
190 | void *getDiagnosticContext() const; |
191 | |
192 | /// getDiagHandlerPtr - Returns const raw pointer of DiagnosticHandler set by |
193 | /// setDiagnosticHandler. |
194 | const DiagnosticHandler *getDiagHandlerPtr() const; |
195 | |
196 | /// getDiagnosticHandler - transfers ownership of DiagnosticHandler unique_ptr |
197 | /// to caller. |
198 | std::unique_ptr<DiagnosticHandler> getDiagnosticHandler(); |
199 | |
200 | /// Return if a code hotness metric should be included in optimization |
201 | /// diagnostics. |
202 | bool getDiagnosticsHotnessRequested() const; |
203 | /// Set if a code hotness metric should be included in optimization |
204 | /// diagnostics. |
205 | void setDiagnosticsHotnessRequested(bool Requested); |
206 | |
207 | bool getMisExpectWarningRequested() const; |
208 | void setMisExpectWarningRequested(bool Requested); |
209 | void setDiagnosticsMisExpectTolerance(std::optional<uint32_t> Tolerance); |
210 | uint32_t getDiagnosticsMisExpectTolerance() const; |
211 | |
212 | /// Return the minimum hotness value a diagnostic would need in order |
213 | /// to be included in optimization diagnostics. |
214 | /// |
215 | /// Three possible return values: |
216 | /// 0 - threshold is disabled. Everything will be printed out. |
217 | /// positive int - threshold is set. |
218 | /// UINT64_MAX - threshold is not yet set, and needs to be synced from |
219 | /// profile summary. Note that in case of missing profile |
220 | /// summary, threshold will be kept at "MAX", effectively |
221 | /// suppresses all remarks output. |
222 | uint64_t getDiagnosticsHotnessThreshold() const; |
223 | |
224 | /// Set the minimum hotness value a diagnostic needs in order to be |
225 | /// included in optimization diagnostics. |
226 | void setDiagnosticsHotnessThreshold(std::optional<uint64_t> Threshold); |
227 | |
228 | /// Return if hotness threshold is requested from PSI. |
229 | bool isDiagnosticsHotnessThresholdSetFromPSI() const; |
230 | |
231 | /// The "main remark streamer" used by all the specialized remark streamers. |
232 | /// This streamer keeps generic remark metadata in memory throughout the life |
233 | /// of the LLVMContext. This metadata may be emitted in a section in object |
234 | /// files depending on the format requirements. |
235 | /// |
236 | /// All specialized remark streamers should convert remarks to |
237 | /// llvm::remarks::Remark and emit them through this streamer. |
238 | remarks::RemarkStreamer *getMainRemarkStreamer(); |
239 | const remarks::RemarkStreamer *getMainRemarkStreamer() const; |
240 | void setMainRemarkStreamer( |
241 | std::unique_ptr<remarks::RemarkStreamer> MainRemarkStreamer); |
242 | |
243 | /// The "LLVM remark streamer" used by LLVM to serialize remark diagnostics |
244 | /// comming from IR and MIR passes. |
245 | /// |
246 | /// If it does not exist, diagnostics are not saved in a file but only emitted |
247 | /// via the diagnostic handler. |
248 | LLVMRemarkStreamer *(); |
249 | const LLVMRemarkStreamer *() const; |
250 | void |
251 | (std::unique_ptr<LLVMRemarkStreamer> ); |
252 | |
253 | /// Get the prefix that should be printed in front of a diagnostic of |
254 | /// the given \p Severity |
255 | static const char *getDiagnosticMessagePrefix(DiagnosticSeverity Severity); |
256 | |
257 | /// Report a message to the currently installed diagnostic handler. |
258 | /// |
259 | /// This function returns, in particular in the case of error reporting |
260 | /// (DI.Severity == \a DS_Error), so the caller should leave the compilation |
261 | /// process in a self-consistent state, even though the generated code |
262 | /// need not be correct. |
263 | /// |
264 | /// The diagnostic message will be implicitly prefixed with a severity keyword |
265 | /// according to \p DI.getSeverity(), i.e., "error: " for \a DS_Error, |
266 | /// "warning: " for \a DS_Warning, and "note: " for \a DS_Note. |
267 | void diagnose(const DiagnosticInfo &DI); |
268 | |
269 | /// Registers a yield callback with the given context. |
270 | /// |
271 | /// The yield callback function may be called by LLVM to transfer control back |
272 | /// to the client that invoked the LLVM compilation. This can be used to yield |
273 | /// control of the thread, or perform periodic work needed by the client. |
274 | /// There is no guaranteed frequency at which callbacks must occur; in fact, |
275 | /// the client is not guaranteed to ever receive this callback. It is at the |
276 | /// sole discretion of LLVM to do so and only if it can guarantee that |
277 | /// suspending the thread won't block any forward progress in other LLVM |
278 | /// contexts in the same process. |
279 | /// |
280 | /// At a suspend point, the state of the current LLVM context is intentionally |
281 | /// undefined. No assumptions about it can or should be made. Only LLVM |
282 | /// context API calls that explicitly state that they can be used during a |
283 | /// yield callback are allowed to be used. Any other API calls into the |
284 | /// context are not supported until the yield callback function returns |
285 | /// control to LLVM. Other LLVM contexts are unaffected by this restriction. |
286 | void setYieldCallback(YieldCallbackTy Callback, void *OpaqueHandle); |
287 | |
288 | /// Calls the yield callback (if applicable). |
289 | /// |
290 | /// This transfers control of the current thread back to the client, which may |
291 | /// suspend the current thread. Only call this method when LLVM doesn't hold |
292 | /// any global mutex or cannot block the execution in another LLVM context. |
293 | void yield(); |
294 | |
295 | /// emitError - Emit an error message to the currently installed error handler |
296 | /// with optional location information. This function returns, so code should |
297 | /// be prepared to drop the erroneous construct on the floor and "not crash". |
298 | /// The generated code need not be correct. The error message will be |
299 | /// implicitly prefixed with "error: " and should not end with a ".". |
300 | void emitError(uint64_t LocCookie, const Twine &ErrorStr); |
301 | void emitError(const Instruction *I, const Twine &ErrorStr); |
302 | void emitError(const Twine &ErrorStr); |
303 | |
304 | /// Access the object which can disable optional passes and individual |
305 | /// optimizations at compile time. |
306 | OptPassGate &getOptPassGate() const; |
307 | |
308 | /// Set the object which can disable optional passes and individual |
309 | /// optimizations at compile time. |
310 | /// |
311 | /// The lifetime of the object must be guaranteed to extend as long as the |
312 | /// LLVMContext is used by compilation. |
313 | void setOptPassGate(OptPassGate&); |
314 | |
315 | /// Set whether opaque pointers are enabled. The method may be called multiple |
316 | /// times, but only with the same value. Note that creating a pointer type or |
317 | /// otherwise querying the opaque pointer mode performs an implicit set to |
318 | /// the default value. |
319 | [[deprecated("Opaque pointers are always enabled" )]] |
320 | void setOpaquePointers(bool Enable) const; |
321 | |
322 | /// Whether typed pointers are supported. If false, all pointers are opaque. |
323 | [[deprecated("Always returns false" )]] |
324 | bool supportsTypedPointers() const; |
325 | |
326 | private: |
327 | // Module needs access to the add/removeModule methods. |
328 | friend class Module; |
329 | |
330 | /// addModule - Register a module as being instantiated in this context. If |
331 | /// the context is deleted, the module will be deleted as well. |
332 | void addModule(Module*); |
333 | |
334 | /// removeModule - Unregister a module from this context. |
335 | void removeModule(Module*); |
336 | }; |
337 | |
338 | // Create wrappers for C Binding types (see CBindingWrapping.h). |
339 | DEFINE_SIMPLE_CONVERSION_FUNCTIONS(LLVMContext, LLVMContextRef) |
340 | |
341 | /* Specialized opaque context conversions. |
342 | */ |
343 | inline LLVMContext **unwrap(LLVMContextRef* Tys) { |
344 | return reinterpret_cast<LLVMContext**>(Tys); |
345 | } |
346 | |
347 | inline LLVMContextRef *wrap(const LLVMContext **Tys) { |
348 | return reinterpret_cast<LLVMContextRef*>(const_cast<LLVMContext**>(Tys)); |
349 | } |
350 | |
351 | } // end namespace llvm |
352 | |
353 | #endif // LLVM_IR_LLVMCONTEXT_H |
354 | |