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 LLVMRemarkStreamer; 39 40 namespace remarks { 41 class RemarkStreamer; 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 *getLLVMRemarkStreamer(); 249 const LLVMRemarkStreamer *getLLVMRemarkStreamer() const; 250 void 251 setLLVMRemarkStreamer(std::unique_ptr<LLVMRemarkStreamer> RemarkStreamer); 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