LLVM  9.0.0svn
LLVMContext.h
Go to the documentation of this file.
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"
20 #include "llvm/Support/Options.h"
21 #include <cstdint>
22 #include <memory>
23 #include <string>
24 
25 namespace llvm {
26 
27 class DiagnosticInfo;
29 class Function;
30 class Instruction;
31 class LLVMContextImpl;
32 class Module;
33 class OptPassGate;
34 template <typename T> class SmallVectorImpl;
35 class SMDiagnostic;
36 class StringRef;
37 class Twine;
38 class RemarkStreamer;
39 class raw_ostream;
40 
41 namespace SyncScope {
42 
43 typedef uint8_t ID;
44 
45 /// Known synchronization scope IDs, which always have the same value. All
46 /// synchronization scope IDs that LLVM has special knowledge of are listed
47 /// here. Additionally, this scheme allows LLVM to efficiently check for
48 /// specific synchronization scope ID without comparing strings.
49 enum {
50  /// Synchronized with respect to signal handlers executing in the same thread.
52 
53  /// Synchronized with respect to all concurrently executing threads.
54  System = 1
55 };
56 
57 } // end namespace SyncScope
58 
59 /// This is an important class for using LLVM in a threaded context. It
60 /// (opaquely) owns and manages the core "global" data of LLVM's core
61 /// infrastructure, including the type and constant uniquing tables.
62 /// LLVMContext itself provides no locking guarantees, so you should be careful
63 /// to have one context per thread.
64 class LLVMContext {
65 public:
67  LLVMContext();
68  LLVMContext(LLVMContext &) = delete;
69  LLVMContext &operator=(const LLVMContext &) = delete;
70  ~LLVMContext();
71 
72  // Pinned metadata names, which always have the same value. This is a
73  // compile-time performance optimization, not a correctness optimization.
74  enum : unsigned {
75  MD_dbg = 0, // "dbg"
76  MD_tbaa = 1, // "tbaa"
77  MD_prof = 2, // "prof"
78  MD_fpmath = 3, // "fpmath"
79  MD_range = 4, // "range"
80  MD_tbaa_struct = 5, // "tbaa.struct"
81  MD_invariant_load = 6, // "invariant.load"
82  MD_alias_scope = 7, // "alias.scope"
83  MD_noalias = 8, // "noalias",
84  MD_nontemporal = 9, // "nontemporal"
85  MD_mem_parallel_loop_access = 10, // "llvm.mem.parallel_loop_access"
86  MD_nonnull = 11, // "nonnull"
87  MD_dereferenceable = 12, // "dereferenceable"
88  MD_dereferenceable_or_null = 13, // "dereferenceable_or_null"
89  MD_make_implicit = 14, // "make.implicit"
90  MD_unpredictable = 15, // "unpredictable"
91  MD_invariant_group = 16, // "invariant.group"
92  MD_align = 17, // "align"
93  MD_loop = 18, // "llvm.loop"
94  MD_type = 19, // "type"
95  MD_section_prefix = 20, // "section_prefix"
96  MD_absolute_symbol = 21, // "absolute_symbol"
97  MD_associated = 22, // "associated"
98  MD_callees = 23, // "callees"
99  MD_irr_loop = 24, // "irr_loop"
100  MD_access_group = 25, // "llvm.access.group"
101  MD_callback = 26, // "callback"
102  };
103 
104  /// Known operand bundle tag IDs, which always have the same value. All
105  /// operand bundle tags that LLVM has special knowledge of are listed here.
106  /// Additionally, this scheme allows LLVM to efficiently check for specific
107  /// operand bundle tags without comparing strings.
108  enum : unsigned {
109  OB_deopt = 0, // "deopt"
110  OB_funclet = 1, // "funclet"
111  OB_gc_transition = 2, // "gc-transition"
112  };
113 
114  /// getMDKindID - Return a unique non-zero ID for the specified metadata kind.
115  /// This ID is uniqued across modules in the current LLVMContext.
116  unsigned getMDKindID(StringRef Name) const;
117 
118  /// getMDKindNames - Populate client supplied SmallVector with the name for
119  /// custom metadata IDs registered in this LLVMContext.
120  void getMDKindNames(SmallVectorImpl<StringRef> &Result) const;
121 
122  /// getOperandBundleTags - Populate client supplied SmallVector with the
123  /// bundle tags registered in this LLVMContext. The bundle tags are ordered
124  /// by increasing bundle IDs.
125  /// \see LLVMContext::getOperandBundleTagID
126  void getOperandBundleTags(SmallVectorImpl<StringRef> &Result) const;
127 
128  /// getOperandBundleTagID - Maps a bundle tag to an integer ID. Every bundle
129  /// tag registered with an LLVMContext has an unique ID.
130  uint32_t getOperandBundleTagID(StringRef Tag) const;
131 
132  /// getOrInsertSyncScopeID - Maps synchronization scope name to
133  /// synchronization scope ID. Every synchronization scope registered with
134  /// LLVMContext has unique ID except pre-defined ones.
135  SyncScope::ID getOrInsertSyncScopeID(StringRef SSN);
136 
137  /// getSyncScopeNames - Populates client supplied SmallVector with
138  /// synchronization scope names registered with LLVMContext. Synchronization
139  /// scope names are ordered by increasing synchronization scope IDs.
140  void getSyncScopeNames(SmallVectorImpl<StringRef> &SSNs) const;
141 
142  /// Define the GC for a function
143  void setGC(const Function &Fn, std::string GCName);
144 
145  /// Return the GC for a function
146  const std::string &getGC(const Function &Fn);
147 
148  /// Remove the GC for a function
149  void deleteGC(const Function &Fn);
150 
151  /// Return true if the Context runtime configuration is set to discard all
152  /// value names. When true, only GlobalValue names will be available in the
153  /// IR.
154  bool shouldDiscardValueNames() const;
155 
156  /// Set the Context runtime configuration to discard all value name (but
157  /// GlobalValue). Clients can use this flag to save memory and runtime,
158  /// especially in release mode.
159  void setDiscardValueNames(bool Discard);
160 
161  /// Whether there is a string map for uniquing debug info
162  /// identifiers across the context. Off by default.
163  bool isODRUniquingDebugTypes() const;
164  void enableDebugTypeODRUniquing();
165  void disableDebugTypeODRUniquing();
166 
167  using InlineAsmDiagHandlerTy = void (*)(const SMDiagnostic&, void *Context,
168  unsigned LocCookie);
169 
170  /// Defines the type of a yield callback.
171  /// \see LLVMContext::setYieldCallback.
172  using YieldCallbackTy = void (*)(LLVMContext *Context, void *OpaqueHandle);
173 
174  /// setInlineAsmDiagnosticHandler - This method sets a handler that is invoked
175  /// when problems with inline asm are detected by the backend. The first
176  /// argument is a function pointer and the second is a context pointer that
177  /// gets passed into the DiagHandler.
178  ///
179  /// LLVMContext doesn't take ownership or interpret either of these
180  /// pointers.
181  void setInlineAsmDiagnosticHandler(InlineAsmDiagHandlerTy DiagHandler,
182  void *DiagContext = nullptr);
183 
184  /// getInlineAsmDiagnosticHandler - Return the diagnostic handler set by
185  /// setInlineAsmDiagnosticHandler.
186  InlineAsmDiagHandlerTy getInlineAsmDiagnosticHandler() const;
187 
188  /// getInlineAsmDiagnosticContext - Return the diagnostic context set by
189  /// setInlineAsmDiagnosticHandler.
190  void *getInlineAsmDiagnosticContext() const;
191 
192  /// setDiagnosticHandlerCallBack - This method sets a handler call back
193  /// that is invoked when the backend needs to report anything to the user.
194  /// The first argument is a function pointer and the second is a context pointer
195  /// that gets passed into the DiagHandler. The third argument should be set to
196  /// true if the handler only expects enabled diagnostics.
197  ///
198  /// LLVMContext doesn't take ownership or interpret either of these
199  /// pointers.
200  void setDiagnosticHandlerCallBack(
202  void *DiagContext = nullptr, bool RespectFilters = false);
203 
204  /// setDiagnosticHandler - This method sets unique_ptr to object of DiagnosticHandler
205  /// to provide custom diagnostic handling. The first argument is unique_ptr of object
206  /// of type DiagnosticHandler or a derived of that. The third argument should be
207  /// set to true if the handler only expects enabled diagnostics.
208  ///
209  /// Ownership of this pointer is moved to LLVMContextImpl.
210  void setDiagnosticHandler(std::unique_ptr<DiagnosticHandler> &&DH,
211  bool RespectFilters = false);
212 
213  /// getDiagnosticHandlerCallBack - Return the diagnostic handler call back set by
214  /// setDiagnosticHandlerCallBack.
215  DiagnosticHandler::DiagnosticHandlerTy getDiagnosticHandlerCallBack() const;
216 
217  /// getDiagnosticContext - Return the diagnostic context set by
218  /// setDiagnosticContext.
219  void *getDiagnosticContext() const;
220 
221  /// getDiagHandlerPtr - Returns const raw pointer of DiagnosticHandler set by
222  /// setDiagnosticHandler.
223  const DiagnosticHandler *getDiagHandlerPtr() const;
224 
225  /// getDiagnosticHandler - transfers owenership of DiagnosticHandler unique_ptr
226  /// to caller.
227  std::unique_ptr<DiagnosticHandler> getDiagnosticHandler();
228 
229  /// Return if a code hotness metric should be included in optimization
230  /// diagnostics.
231  bool getDiagnosticsHotnessRequested() const;
232  /// Set if a code hotness metric should be included in optimization
233  /// diagnostics.
234  void setDiagnosticsHotnessRequested(bool Requested);
235 
236  /// Return the minimum hotness value a diagnostic would need in order
237  /// to be included in optimization diagnostics. If there is no minimum, this
238  /// returns None.
239  uint64_t getDiagnosticsHotnessThreshold() const;
240 
241  /// Set the minimum hotness value a diagnostic needs in order to be
242  /// included in optimization diagnostics.
243  void setDiagnosticsHotnessThreshold(uint64_t Threshold);
244 
245  /// Return the streamer used by the backend to save remark diagnostics. If it
246  /// does not exist, diagnostics are not saved in a file but only emitted via
247  /// the diagnostic handler.
248  RemarkStreamer *getRemarkStreamer();
249  const RemarkStreamer *getRemarkStreamer() const;
250 
251  /// Set the diagnostics output used for optimization diagnostics.
252  /// This filename may be embedded in a section for tools to find the
253  /// diagnostics whenever they're needed.
254  ///
255  /// If a remark streamer is already set, it will be replaced with
256  /// \p RemarkStreamer.
257  ///
258  /// By default, diagnostics are not saved in a file but only emitted via the
259  /// diagnostic handler. Even if an output file is set, the handler is invoked
260  /// for each diagnostic message.
261  void setRemarkStreamer(std::unique_ptr<RemarkStreamer> RemarkStreamer);
262 
263  /// Get the prefix that should be printed in front of a diagnostic of
264  /// the given \p Severity
265  static const char *getDiagnosticMessagePrefix(DiagnosticSeverity Severity);
266 
267  /// Report a message to the currently installed diagnostic handler.
268  ///
269  /// This function returns, in particular in the case of error reporting
270  /// (DI.Severity == \a DS_Error), so the caller should leave the compilation
271  /// process in a self-consistent state, even though the generated code
272  /// need not be correct.
273  ///
274  /// The diagnostic message will be implicitly prefixed with a severity keyword
275  /// according to \p DI.getSeverity(), i.e., "error: " for \a DS_Error,
276  /// "warning: " for \a DS_Warning, and "note: " for \a DS_Note.
277  void diagnose(const DiagnosticInfo &DI);
278 
279  /// Registers a yield callback with the given context.
280  ///
281  /// The yield callback function may be called by LLVM to transfer control back
282  /// to the client that invoked the LLVM compilation. This can be used to yield
283  /// control of the thread, or perform periodic work needed by the client.
284  /// There is no guaranteed frequency at which callbacks must occur; in fact,
285  /// the client is not guaranteed to ever receive this callback. It is at the
286  /// sole discretion of LLVM to do so and only if it can guarantee that
287  /// suspending the thread won't block any forward progress in other LLVM
288  /// contexts in the same process.
289  ///
290  /// At a suspend point, the state of the current LLVM context is intentionally
291  /// undefined. No assumptions about it can or should be made. Only LLVM
292  /// context API calls that explicitly state that they can be used during a
293  /// yield callback are allowed to be used. Any other API calls into the
294  /// context are not supported until the yield callback function returns
295  /// control to LLVM. Other LLVM contexts are unaffected by this restriction.
296  void setYieldCallback(YieldCallbackTy Callback, void *OpaqueHandle);
297 
298  /// Calls the yield callback (if applicable).
299  ///
300  /// This transfers control of the current thread back to the client, which may
301  /// suspend the current thread. Only call this method when LLVM doesn't hold
302  /// any global mutex or cannot block the execution in another LLVM context.
303  void yield();
304 
305  /// emitError - Emit an error message to the currently installed error handler
306  /// with optional location information. This function returns, so code should
307  /// be prepared to drop the erroneous construct on the floor and "not crash".
308  /// The generated code need not be correct. The error message will be
309  /// implicitly prefixed with "error: " and should not end with a ".".
310  void emitError(unsigned LocCookie, const Twine &ErrorStr);
311  void emitError(const Instruction *I, const Twine &ErrorStr);
312  void emitError(const Twine &ErrorStr);
313 
314  /// Query for a debug option's value.
315  ///
316  /// This function returns typed data populated from command line parsing.
317  template <typename ValT, typename Base, ValT(Base::*Mem)>
318  ValT getOption() const {
319  return OptionRegistry::instance().template get<ValT, Base, Mem>();
320  }
321 
322  /// Access the object which can disable optional passes and individual
323  /// optimizations at compile time.
324  OptPassGate &getOptPassGate() const;
325 
326  /// Set the object which can disable optional passes and individual
327  /// optimizations at compile time.
328  ///
329  /// The lifetime of the object must be guaranteed to extend as long as the
330  /// LLVMContext is used by compilation.
331  void setOptPassGate(OptPassGate&);
332 
333 private:
334  // Module needs access to the add/removeModule methods.
335  friend class Module;
336 
337  /// addModule - Register a module as being instantiated in this context. If
338  /// the context is deleted, the module will be deleted as well.
339  void addModule(Module*);
340 
341  /// removeModule - Unregister a module from this context.
342  void removeModule(Module*);
343 };
344 
345 // Create wrappers for C Binding types (see CBindingWrapping.h).
347 
348 /* Specialized opaque context conversions.
349  */
351  return reinterpret_cast<LLVMContext**>(Tys);
352 }
353 
354 inline LLVMContextRef *wrap(const LLVMContext **Tys) {
355  return reinterpret_cast<LLVMContextRef*>(const_cast<LLVMContext**>(Tys));
356 }
357 
358 } // end namespace llvm
359 
360 #endif // LLVM_IR_LLVMCONTEXT_H
This is the base class for diagnostic handling in LLVM.
LLVMContext & Context
This class represents lattice values for constants.
Definition: AllocatorList.h:23
A Module instance is used to store all the information related to an LLVM module. ...
Definition: Module.h:65
Extensions to this class implement mechanisms to disable passes and individual optimizations at compi...
Definition: OptBisect.h:25
amdgpu Simplify well known AMD library false FunctionCallee Value const Twine & Name
void(*)(LLVMContext *Context, void *OpaqueHandle) YieldCallbackTy
Defines the type of a yield callback.
Definition: LLVMContext.h:172
DiagnosticSeverity
Defines the different supported severity of a diagnostic.
#define DEFINE_SIMPLE_CONVERSION_FUNCTIONS(ty, ref)
Twine - A lightweight data structure for efficiently representing the concatenation of temporary valu...
Definition: Twine.h:80
Attribute unwrap(LLVMAttributeRef Attr)
Definition: Attributes.h:194
Synchronized with respect to signal handlers executing in the same thread.
Definition: LLVMContext.h:51
Synchronized with respect to all concurrently executing threads.
Definition: LLVMContext.h:54
static void DiagHandler(const SMDiagnostic &Diag, void *Context)
Definition: TextStub.cpp:611
static OptionRegistry & instance()
Returns a reference to the singleton instance.
Definition: Options.cpp:32
struct LLVMOpaqueContext * LLVMContextRef
The top-level container for all LLVM global data.
Definition: Types.h:54
void(*)(const DiagnosticInfo &DI, void *Context) DiagnosticHandlerTy
This is the base abstract class for diagnostic reporting in the backend.
This is an important class for using LLVM in a threaded context.
Definition: LLVMContext.h:64
amdgpu inline
LLVMContextImpl *const pImpl
Definition: LLVMContext.h:66
ValT getOption() const
Query for a debug option&#39;s value.
Definition: LLVMContext.h:318
This file declares helper objects for defining debug options that can be configured via the command l...
void(*)(const SMDiagnostic &, void *Context, unsigned LocCookie) InlineAsmDiagHandlerTy
Definition: LLVMContext.h:168
static cl::opt< unsigned > Threshold("loop-unswitch-threshold", cl::desc("Max loop size to unswitch"), cl::init(100), cl::Hidden)
Streamer for remarks.
LLVMAttributeRef wrap(Attribute Attr)
Definition: Attributes.h:189
#define I(x, y, z)
Definition: MD5.cpp:58
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:48
Instances of this class encapsulate one diagnostic report, allowing printing to a raw_ostream as a ca...
Definition: SourceMgr.h:259