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/ADT/Optional.h" 19 #include "llvm/IR/DiagnosticHandler.h" 20 #include "llvm/Support/CBindingWrapping.h" 21 #include <cstdint> 22 #include <memory> 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(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 }; 97 98 /// getMDKindID - Return a unique non-zero ID for the specified metadata kind. 99 /// This ID is uniqued across modules in the current LLVMContext. 100 unsigned getMDKindID(StringRef Name) const; 101 102 /// getMDKindNames - Populate client supplied SmallVector with the name for 103 /// custom metadata IDs registered in this LLVMContext. 104 void getMDKindNames(SmallVectorImpl<StringRef> &Result) const; 105 106 /// getOperandBundleTags - Populate client supplied SmallVector with the 107 /// bundle tags registered in this LLVMContext. The bundle tags are ordered 108 /// by increasing bundle IDs. 109 /// \see LLVMContext::getOperandBundleTagID 110 void getOperandBundleTags(SmallVectorImpl<StringRef> &Result) const; 111 112 /// getOrInsertBundleTag - Returns the Tag to use for an operand bundle of 113 /// name TagName. 114 StringMapEntry<uint32_t> *getOrInsertBundleTag(StringRef TagName) const; 115 116 /// getOperandBundleTagID - Maps a bundle tag to an integer ID. Every bundle 117 /// tag registered with an LLVMContext has an unique ID. 118 uint32_t getOperandBundleTagID(StringRef Tag) const; 119 120 /// getOrInsertSyncScopeID - Maps synchronization scope name to 121 /// synchronization scope ID. Every synchronization scope registered with 122 /// LLVMContext has unique ID except pre-defined ones. 123 SyncScope::ID getOrInsertSyncScopeID(StringRef SSN); 124 125 /// getSyncScopeNames - Populates client supplied SmallVector with 126 /// synchronization scope names registered with LLVMContext. Synchronization 127 /// scope names are ordered by increasing synchronization scope IDs. 128 void getSyncScopeNames(SmallVectorImpl<StringRef> &SSNs) const; 129 130 /// Define the GC for a function 131 void setGC(const Function &Fn, std::string GCName); 132 133 /// Return the GC for a function 134 const std::string &getGC(const Function &Fn); 135 136 /// Remove the GC for a function 137 void deleteGC(const Function &Fn); 138 139 /// Return true if the Context runtime configuration is set to discard all 140 /// value names. When true, only GlobalValue names will be available in the 141 /// IR. 142 bool shouldDiscardValueNames() const; 143 144 /// Set the Context runtime configuration to discard all value name (but 145 /// GlobalValue). Clients can use this flag to save memory and runtime, 146 /// especially in release mode. 147 void setDiscardValueNames(bool Discard); 148 149 /// Whether there is a string map for uniquing debug info 150 /// identifiers across the context. Off by default. 151 bool isODRUniquingDebugTypes() const; 152 void enableDebugTypeODRUniquing(); 153 void disableDebugTypeODRUniquing(); 154 155 /// Defines the type of a yield callback. 156 /// \see LLVMContext::setYieldCallback. 157 using YieldCallbackTy = void (*)(LLVMContext *Context, void *OpaqueHandle); 158 159 /// setDiagnosticHandlerCallBack - This method sets a handler call back 160 /// that is invoked when the backend needs to report anything to the user. 161 /// The first argument is a function pointer and the second is a context pointer 162 /// that gets passed into the DiagHandler. The third argument should be set to 163 /// true if the handler only expects enabled diagnostics. 164 /// 165 /// LLVMContext doesn't take ownership or interpret either of these 166 /// pointers. 167 void setDiagnosticHandlerCallBack( 168 DiagnosticHandler::DiagnosticHandlerTy DiagHandler, 169 void *DiagContext = nullptr, bool RespectFilters = false); 170 171 /// setDiagnosticHandler - This method sets unique_ptr to object of 172 /// DiagnosticHandler to provide custom diagnostic handling. The first 173 /// argument is unique_ptr of object of type DiagnosticHandler or a derived 174 /// of that. The second argument should be set to true if the handler only 175 /// expects enabled diagnostics. 176 /// 177 /// Ownership of this pointer is moved to LLVMContextImpl. 178 void setDiagnosticHandler(std::unique_ptr<DiagnosticHandler> &&DH, 179 bool RespectFilters = false); 180 181 /// getDiagnosticHandlerCallBack - Return the diagnostic handler call back set by 182 /// setDiagnosticHandlerCallBack. 183 DiagnosticHandler::DiagnosticHandlerTy getDiagnosticHandlerCallBack() const; 184 185 /// getDiagnosticContext - Return the diagnostic context set by 186 /// setDiagnosticContext. 187 void *getDiagnosticContext() const; 188 189 /// getDiagHandlerPtr - Returns const raw pointer of DiagnosticHandler set by 190 /// setDiagnosticHandler. 191 const DiagnosticHandler *getDiagHandlerPtr() const; 192 193 /// getDiagnosticHandler - transfers ownership of DiagnosticHandler unique_ptr 194 /// to caller. 195 std::unique_ptr<DiagnosticHandler> getDiagnosticHandler(); 196 197 /// Return if a code hotness metric should be included in optimization 198 /// diagnostics. 199 bool getDiagnosticsHotnessRequested() const; 200 /// Set if a code hotness metric should be included in optimization 201 /// diagnostics. 202 void setDiagnosticsHotnessRequested(bool Requested); 203 204 /// Return the minimum hotness value a diagnostic would need in order 205 /// to be included in optimization diagnostics. 206 /// 207 /// Three possible return values: 208 /// 0 - threshold is disabled. Everything will be printed out. 209 /// positive int - threshold is set. 210 /// UINT64_MAX - threshold is not yet set, and needs to be synced from 211 /// profile summary. Note that in case of missing profile 212 /// summary, threshold will be kept at "MAX", effectively 213 /// suppresses all remarks output. 214 uint64_t getDiagnosticsHotnessThreshold() const; 215 216 /// Set the minimum hotness value a diagnostic needs in order to be 217 /// included in optimization diagnostics. 218 void setDiagnosticsHotnessThreshold(Optional<uint64_t> Threshold); 219 220 /// Return if hotness threshold is requested from PSI. 221 bool isDiagnosticsHotnessThresholdSetFromPSI() const; 222 223 /// The "main remark streamer" used by all the specialized remark streamers. 224 /// This streamer keeps generic remark metadata in memory throughout the life 225 /// of the LLVMContext. This metadata may be emitted in a section in object 226 /// files depending on the format requirements. 227 /// 228 /// All specialized remark streamers should convert remarks to 229 /// llvm::remarks::Remark and emit them through this streamer. 230 remarks::RemarkStreamer *getMainRemarkStreamer(); 231 const remarks::RemarkStreamer *getMainRemarkStreamer() const; 232 void setMainRemarkStreamer( 233 std::unique_ptr<remarks::RemarkStreamer> MainRemarkStreamer); 234 235 /// The "LLVM remark streamer" used by LLVM to serialize remark diagnostics 236 /// comming from IR and MIR passes. 237 /// 238 /// If it does not exist, diagnostics are not saved in a file but only emitted 239 /// via the diagnostic handler. 240 LLVMRemarkStreamer *getLLVMRemarkStreamer(); 241 const LLVMRemarkStreamer *getLLVMRemarkStreamer() const; 242 void 243 setLLVMRemarkStreamer(std::unique_ptr<LLVMRemarkStreamer> RemarkStreamer); 244 245 /// Get the prefix that should be printed in front of a diagnostic of 246 /// the given \p Severity 247 static const char *getDiagnosticMessagePrefix(DiagnosticSeverity Severity); 248 249 /// Report a message to the currently installed diagnostic handler. 250 /// 251 /// This function returns, in particular in the case of error reporting 252 /// (DI.Severity == \a DS_Error), so the caller should leave the compilation 253 /// process in a self-consistent state, even though the generated code 254 /// need not be correct. 255 /// 256 /// The diagnostic message will be implicitly prefixed with a severity keyword 257 /// according to \p DI.getSeverity(), i.e., "error: " for \a DS_Error, 258 /// "warning: " for \a DS_Warning, and "note: " for \a DS_Note. 259 void diagnose(const DiagnosticInfo &DI); 260 261 /// Registers a yield callback with the given context. 262 /// 263 /// The yield callback function may be called by LLVM to transfer control back 264 /// to the client that invoked the LLVM compilation. This can be used to yield 265 /// control of the thread, or perform periodic work needed by the client. 266 /// There is no guaranteed frequency at which callbacks must occur; in fact, 267 /// the client is not guaranteed to ever receive this callback. It is at the 268 /// sole discretion of LLVM to do so and only if it can guarantee that 269 /// suspending the thread won't block any forward progress in other LLVM 270 /// contexts in the same process. 271 /// 272 /// At a suspend point, the state of the current LLVM context is intentionally 273 /// undefined. No assumptions about it can or should be made. Only LLVM 274 /// context API calls that explicitly state that they can be used during a 275 /// yield callback are allowed to be used. Any other API calls into the 276 /// context are not supported until the yield callback function returns 277 /// control to LLVM. Other LLVM contexts are unaffected by this restriction. 278 void setYieldCallback(YieldCallbackTy Callback, void *OpaqueHandle); 279 280 /// Calls the yield callback (if applicable). 281 /// 282 /// This transfers control of the current thread back to the client, which may 283 /// suspend the current thread. Only call this method when LLVM doesn't hold 284 /// any global mutex or cannot block the execution in another LLVM context. 285 void yield(); 286 287 /// emitError - Emit an error message to the currently installed error handler 288 /// with optional location information. This function returns, so code should 289 /// be prepared to drop the erroneous construct on the floor and "not crash". 290 /// The generated code need not be correct. The error message will be 291 /// implicitly prefixed with "error: " and should not end with a ".". 292 void emitError(uint64_t LocCookie, const Twine &ErrorStr); 293 void emitError(const Instruction *I, const Twine &ErrorStr); 294 void emitError(const Twine &ErrorStr); 295 296 /// Access the object which can disable optional passes and individual 297 /// optimizations at compile time. 298 OptPassGate &getOptPassGate() const; 299 300 /// Set the object which can disable optional passes and individual 301 /// optimizations at compile time. 302 /// 303 /// The lifetime of the object must be guaranteed to extend as long as the 304 /// LLVMContext is used by compilation. 305 void setOptPassGate(OptPassGate&); 306 307 /// Enable opaque pointers. Can only be called before creating the first 308 /// pointer type. 309 void enableOpaquePointers() const; 310 311 /// Whether typed pointers are supported. If false, all pointers are opaque. 312 bool supportsTypedPointers() const; 313 314 private: 315 // Module needs access to the add/removeModule methods. 316 friend class Module; 317 318 /// addModule - Register a module as being instantiated in this context. If 319 /// the context is deleted, the module will be deleted as well. 320 void addModule(Module*); 321 322 /// removeModule - Unregister a module from this context. 323 void removeModule(Module*); 324 }; 325 326 // Create wrappers for C Binding types (see CBindingWrapping.h). 327 DEFINE_SIMPLE_CONVERSION_FUNCTIONS(LLVMContext, LLVMContextRef) 328 329 /* Specialized opaque context conversions. 330 */ 331 inline LLVMContext **unwrap(LLVMContextRef* Tys) { 332 return reinterpret_cast<LLVMContext**>(Tys); 333 } 334 335 inline LLVMContextRef *wrap(const LLVMContext **Tys) { 336 return reinterpret_cast<LLVMContextRef*>(const_cast<LLVMContext**>(Tys)); 337 } 338 339 } // end namespace llvm 340 341 #endif // LLVM_IR_LLVMCONTEXT_H 342