1 //===- DIBuilder.h - Debug Information Builder ------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 // This file defines a DIBuilder that is useful for creating debugging
11 // information entries in LLVM IR form.
13 //===----------------------------------------------------------------------===//
15 #ifndef LLVM_IR_DIBUILDER_H
16 #define LLVM_IR_DIBUILDER_H
18 #include "llvm/ADT/ArrayRef.h"
19 #include "llvm/ADT/DenseMap.h"
20 #include "llvm/ADT/MapVector.h"
21 #include "llvm/ADT/Optional.h"
22 #include "llvm/ADT/SetVector.h"
23 #include "llvm/ADT/SmallVector.h"
24 #include "llvm/ADT/StringRef.h"
25 #include "llvm/IR/DebugInfo.h"
26 #include "llvm/IR/DebugInfoMetadata.h"
27 #include "llvm/IR/TrackingMDRef.h"
28 #include "llvm/Support/Casting.h"
44 LLVMContext &VMContext;
46 DICompileUnit *CUNode; ///< The one compile unit created by this DIBuiler.
47 Function *DeclareFn; ///< llvm.dbg.declare
48 Function *ValueFn; ///< llvm.dbg.value
49 Function *LabelFn; ///< llvm.dbg.label
51 SmallVector<Metadata *, 4> AllEnumTypes;
52 /// Track the RetainTypes, since they can be updated later on.
53 SmallVector<TrackingMDNodeRef, 4> AllRetainTypes;
54 SmallVector<Metadata *, 4> AllSubprograms;
55 SmallVector<Metadata *, 4> AllGVs;
56 SmallVector<TrackingMDNodeRef, 4> AllImportedModules;
57 /// Map Macro parent (which can be DIMacroFile or nullptr) to a list of
58 /// Metadata all of type DIMacroNode.
59 /// DIMacroNode's with nullptr parent are DICompileUnit direct children.
60 MapVector<MDNode *, SetVector<Metadata *>> AllMacrosPerParent;
62 /// Track nodes that may be unresolved.
63 SmallVector<TrackingMDNodeRef, 4> UnresolvedNodes;
64 bool AllowUnresolvedNodes;
66 /// Each subprogram's preserved local variables.
68 /// Do not use a std::vector. Some versions of libc++ apparently copy
69 /// instead of move on grow operations, and TrackingMDRef is expensive to
71 DenseMap<MDNode *, SmallVector<TrackingMDNodeRef, 1>> PreservedVariables;
73 /// Each subprogram's preserved labels.
74 DenseMap<MDNode *, SmallVector<TrackingMDNodeRef, 1>> PreservedLabels;
76 /// Create a temporary.
78 /// Create an \a temporary node and track it in \a UnresolvedNodes.
79 void trackIfUnresolved(MDNode *N);
81 /// Internal helper for insertDeclare.
82 Instruction *insertDeclare(llvm::Value *Storage, DILocalVariable *VarInfo,
83 DIExpression *Expr, const DILocation *DL,
84 BasicBlock *InsertBB, Instruction *InsertBefore);
86 /// Internal helper for insertLabel.
87 Instruction *insertLabel(DILabel *LabelInfo, const DILocation *DL,
88 BasicBlock *InsertBB, Instruction *InsertBefore);
90 /// Internal helper for insertDbgValueIntrinsic.
92 insertDbgValueIntrinsic(llvm::Value *Val, DILocalVariable *VarInfo,
93 DIExpression *Expr, const DILocation *DL,
94 BasicBlock *InsertBB, Instruction *InsertBefore);
97 /// Construct a builder for a module.
99 /// If \c AllowUnresolved, collect unresolved nodes attached to the module
100 /// in order to resolve cycles during \a finalize().
102 /// If \p CU is given a value other than nullptr, then set \p CUNode to CU.
103 explicit DIBuilder(Module &M, bool AllowUnresolved = true,
104 DICompileUnit *CU = nullptr);
105 DIBuilder(const DIBuilder &) = delete;
106 DIBuilder &operator=(const DIBuilder &) = delete;
108 /// Construct any deferred debug info descriptors.
111 /// Finalize a specific subprogram - no new variables may be added to this
112 /// subprogram afterwards.
113 void finalizeSubprogram(DISubprogram *SP);
115 /// A CompileUnit provides an anchor for all debugging
116 /// information generated during this instance of compilation.
117 /// \param Lang Source programming language, eg. dwarf::DW_LANG_C99
118 /// \param File File info.
119 /// \param Producer Identify the producer of debugging information
120 /// and code. Usually this is a compiler
122 /// \param isOptimized A boolean flag which indicates whether optimization
123 /// is enabled or not.
124 /// \param Flags This string lists command line options. This
125 /// string is directly embedded in debug info
126 /// output which may be used by a tool
127 /// analyzing generated debugging information.
128 /// \param RV This indicates runtime version for languages like
130 /// \param SplitName The name of the file that we'll split debug info
132 /// \param Kind The kind of debug information to generate.
133 /// \param DWOId The DWOId if this is a split skeleton compile unit.
134 /// \param SplitDebugInlining Whether to emit inline debug info.
135 /// \param DebugInfoForProfiling Whether to emit extra debug info for
136 /// profile collection.
137 /// \param GnuPubnames Whether to emit .debug_gnu_pubnames section instead
138 /// of .debug_pubnames.
140 createCompileUnit(unsigned Lang, DIFile *File, StringRef Producer,
141 bool isOptimized, StringRef Flags, unsigned RV,
142 StringRef SplitName = StringRef(),
143 DICompileUnit::DebugEmissionKind Kind =
144 DICompileUnit::DebugEmissionKind::FullDebug,
145 uint64_t DWOId = 0, bool SplitDebugInlining = true,
146 bool DebugInfoForProfiling = false,
147 bool GnuPubnames = false);
149 /// Create a file descriptor to hold debugging information for a file.
150 /// \param Filename File name.
151 /// \param Directory Directory.
152 /// \param Checksum Optional checksum kind (e.g. CSK_MD5, CSK_SHA1, etc.)
154 /// \param Source Optional source text.
156 createFile(StringRef Filename, StringRef Directory,
157 Optional<DIFile::ChecksumInfo<StringRef>> Checksum = None,
158 Optional<StringRef> Source = None);
160 /// Create debugging information entry for a macro.
161 /// \param Parent Macro parent (could be nullptr).
162 /// \param Line Source line number where the macro is defined.
163 /// \param MacroType DW_MACINFO_define or DW_MACINFO_undef.
164 /// \param Name Macro name.
165 /// \param Value Macro value.
166 DIMacro *createMacro(DIMacroFile *Parent, unsigned Line, unsigned MacroType,
167 StringRef Name, StringRef Value = StringRef());
169 /// Create debugging information temporary entry for a macro file.
170 /// List of macro node direct children will be calculated by DIBuilder,
171 /// using the \p Parent relationship.
172 /// \param Parent Macro file parent (could be nullptr).
173 /// \param Line Source line number where the macro file is included.
174 /// \param File File descriptor containing the name of the macro file.
175 DIMacroFile *createTempMacroFile(DIMacroFile *Parent, unsigned Line,
178 /// Create a single enumerator value.
179 DIEnumerator *createEnumerator(StringRef Name, int64_t Val, bool IsUnsigned = false);
181 /// Create a DWARF unspecified type.
182 DIBasicType *createUnspecifiedType(StringRef Name);
184 /// Create C++11 nullptr type.
185 DIBasicType *createNullPtrType();
187 /// Create debugging information entry for a basic
189 /// \param Name Type name.
190 /// \param SizeInBits Size of the type.
191 /// \param Encoding DWARF encoding code, e.g. dwarf::DW_ATE_float.
192 DIBasicType *createBasicType(StringRef Name, uint64_t SizeInBits,
195 /// Create debugging information entry for a qualified
196 /// type, e.g. 'const int'.
197 /// \param Tag Tag identifing type, e.g. dwarf::TAG_volatile_type
198 /// \param FromTy Base Type.
199 DIDerivedType *createQualifiedType(unsigned Tag, DIType *FromTy);
201 /// Create debugging information entry for a pointer.
202 /// \param PointeeTy Type pointed by this pointer.
203 /// \param SizeInBits Size.
204 /// \param AlignInBits Alignment. (optional)
205 /// \param DWARFAddressSpace DWARF address space. (optional)
206 /// \param Name Pointer type name. (optional)
207 DIDerivedType *createPointerType(DIType *PointeeTy, uint64_t SizeInBits,
208 uint32_t AlignInBits = 0,
209 Optional<unsigned> DWARFAddressSpace =
211 StringRef Name = "");
213 /// Create debugging information entry for a pointer to member.
214 /// \param PointeeTy Type pointed to by this pointer.
215 /// \param SizeInBits Size.
216 /// \param AlignInBits Alignment. (optional)
217 /// \param Class Type for which this pointer points to members of.
219 createMemberPointerType(DIType *PointeeTy, DIType *Class,
220 uint64_t SizeInBits, uint32_t AlignInBits = 0,
221 DINode::DIFlags Flags = DINode::FlagZero);
223 /// Create debugging information entry for a c++
224 /// style reference or rvalue reference type.
225 DIDerivedType *createReferenceType(unsigned Tag, DIType *RTy,
226 uint64_t SizeInBits = 0,
227 uint32_t AlignInBits = 0,
228 Optional<unsigned> DWARFAddressSpace =
231 /// Create debugging information entry for a typedef.
232 /// \param Ty Original type.
233 /// \param Name Typedef name.
234 /// \param File File where this type is defined.
235 /// \param LineNo Line number.
236 /// \param Context The surrounding context for the typedef.
237 DIDerivedType *createTypedef(DIType *Ty, StringRef Name, DIFile *File,
238 unsigned LineNo, DIScope *Context);
240 /// Create debugging information entry for a 'friend'.
241 DIDerivedType *createFriend(DIType *Ty, DIType *FriendTy);
243 /// Create debugging information entry to establish
244 /// inheritance relationship between two types.
245 /// \param Ty Original type.
246 /// \param BaseTy Base type. Ty is inherits from base.
247 /// \param BaseOffset Base offset.
248 /// \param VBPtrOffset Virtual base pointer offset.
249 /// \param Flags Flags to describe inheritance attribute,
251 DIDerivedType *createInheritance(DIType *Ty, DIType *BaseTy,
252 uint64_t BaseOffset, uint32_t VBPtrOffset,
253 DINode::DIFlags Flags);
255 /// Create debugging information entry for a member.
256 /// \param Scope Member scope.
257 /// \param Name Member name.
258 /// \param File File where this member is defined.
259 /// \param LineNo Line number.
260 /// \param SizeInBits Member size.
261 /// \param AlignInBits Member alignment.
262 /// \param OffsetInBits Member offset.
263 /// \param Flags Flags to encode member attribute, e.g. private
264 /// \param Ty Parent type.
265 DIDerivedType *createMemberType(DIScope *Scope, StringRef Name,
266 DIFile *File, unsigned LineNo,
268 uint32_t AlignInBits,
269 uint64_t OffsetInBits,
270 DINode::DIFlags Flags, DIType *Ty);
272 /// Create debugging information entry for a variant. A variant
273 /// normally should be a member of a variant part.
274 /// \param Scope Member scope.
275 /// \param Name Member name.
276 /// \param File File where this member is defined.
277 /// \param LineNo Line number.
278 /// \param SizeInBits Member size.
279 /// \param AlignInBits Member alignment.
280 /// \param OffsetInBits Member offset.
281 /// \param Flags Flags to encode member attribute, e.g. private
282 /// \param Discriminant The discriminant for this branch; null for
283 /// the default branch
284 /// \param Ty Parent type.
285 DIDerivedType *createVariantMemberType(DIScope *Scope, StringRef Name,
286 DIFile *File, unsigned LineNo,
288 uint32_t AlignInBits,
289 uint64_t OffsetInBits,
290 Constant *Discriminant,
291 DINode::DIFlags Flags, DIType *Ty);
293 /// Create debugging information entry for a bit field member.
294 /// \param Scope Member scope.
295 /// \param Name Member name.
296 /// \param File File where this member is defined.
297 /// \param LineNo Line number.
298 /// \param SizeInBits Member size.
299 /// \param OffsetInBits Member offset.
300 /// \param StorageOffsetInBits Member storage offset.
301 /// \param Flags Flags to encode member attribute.
302 /// \param Ty Parent type.
303 DIDerivedType *createBitFieldMemberType(
304 DIScope *Scope, StringRef Name, DIFile *File, unsigned LineNo,
305 uint64_t SizeInBits, uint64_t OffsetInBits,
306 uint64_t StorageOffsetInBits, DINode::DIFlags Flags, DIType *Ty);
308 /// Create debugging information entry for a
309 /// C++ static data member.
310 /// \param Scope Member scope.
311 /// \param Name Member name.
312 /// \param File File where this member is declared.
313 /// \param LineNo Line number.
314 /// \param Ty Type of the static member.
315 /// \param Flags Flags to encode member attribute, e.g. private.
316 /// \param Val Const initializer of the member.
317 /// \param AlignInBits Member alignment.
318 DIDerivedType *createStaticMemberType(DIScope *Scope, StringRef Name,
319 DIFile *File, unsigned LineNo,
320 DIType *Ty, DINode::DIFlags Flags,
322 uint32_t AlignInBits = 0);
324 /// Create debugging information entry for Objective-C
325 /// instance variable.
326 /// \param Name Member name.
327 /// \param File File where this member is defined.
328 /// \param LineNo Line number.
329 /// \param SizeInBits Member size.
330 /// \param AlignInBits Member alignment.
331 /// \param OffsetInBits Member offset.
332 /// \param Flags Flags to encode member attribute, e.g. private
333 /// \param Ty Parent type.
334 /// \param PropertyNode Property associated with this ivar.
335 DIDerivedType *createObjCIVar(StringRef Name, DIFile *File, unsigned LineNo,
336 uint64_t SizeInBits, uint32_t AlignInBits,
337 uint64_t OffsetInBits, DINode::DIFlags Flags,
338 DIType *Ty, MDNode *PropertyNode);
340 /// Create debugging information entry for Objective-C
342 /// \param Name Property name.
343 /// \param File File where this property is defined.
344 /// \param LineNumber Line number.
345 /// \param GetterName Name of the Objective C property getter selector.
346 /// \param SetterName Name of the Objective C property setter selector.
347 /// \param PropertyAttributes Objective C property attributes.
349 DIObjCProperty *createObjCProperty(StringRef Name, DIFile *File,
351 StringRef GetterName,
352 StringRef SetterName,
353 unsigned PropertyAttributes, DIType *Ty);
355 /// Create debugging information entry for a class.
356 /// \param Scope Scope in which this class is defined.
357 /// \param Name class name.
358 /// \param File File where this member is defined.
359 /// \param LineNumber Line number.
360 /// \param SizeInBits Member size.
361 /// \param AlignInBits Member alignment.
362 /// \param OffsetInBits Member offset.
363 /// \param Flags Flags to encode member attribute, e.g. private
364 /// \param Elements class members.
365 /// \param VTableHolder Debug info of the base class that contains vtable
366 /// for this type. This is used in
367 /// DW_AT_containing_type. See DWARF documentation
369 /// \param TemplateParms Template type parameters.
370 /// \param UniqueIdentifier A unique identifier for the class.
371 DICompositeType *createClassType(
372 DIScope *Scope, StringRef Name, DIFile *File, unsigned LineNumber,
373 uint64_t SizeInBits, uint32_t AlignInBits, uint64_t OffsetInBits,
374 DINode::DIFlags Flags, DIType *DerivedFrom, DINodeArray Elements,
375 DIType *VTableHolder = nullptr, MDNode *TemplateParms = nullptr,
376 StringRef UniqueIdentifier = "");
378 /// Create debugging information entry for a struct.
379 /// \param Scope Scope in which this struct is defined.
380 /// \param Name Struct name.
381 /// \param File File where this member is defined.
382 /// \param LineNumber Line number.
383 /// \param SizeInBits Member size.
384 /// \param AlignInBits Member alignment.
385 /// \param Flags Flags to encode member attribute, e.g. private
386 /// \param Elements Struct elements.
387 /// \param RunTimeLang Optional parameter, Objective-C runtime version.
388 /// \param UniqueIdentifier A unique identifier for the struct.
389 DICompositeType *createStructType(
390 DIScope *Scope, StringRef Name, DIFile *File, unsigned LineNumber,
391 uint64_t SizeInBits, uint32_t AlignInBits, DINode::DIFlags Flags,
392 DIType *DerivedFrom, DINodeArray Elements, unsigned RunTimeLang = 0,
393 DIType *VTableHolder = nullptr, StringRef UniqueIdentifier = "");
395 /// Create debugging information entry for an union.
396 /// \param Scope Scope in which this union is defined.
397 /// \param Name Union name.
398 /// \param File File where this member is defined.
399 /// \param LineNumber Line number.
400 /// \param SizeInBits Member size.
401 /// \param AlignInBits Member alignment.
402 /// \param Flags Flags to encode member attribute, e.g. private
403 /// \param Elements Union elements.
404 /// \param RunTimeLang Optional parameter, Objective-C runtime version.
405 /// \param UniqueIdentifier A unique identifier for the union.
406 DICompositeType *createUnionType(DIScope *Scope, StringRef Name,
407 DIFile *File, unsigned LineNumber,
408 uint64_t SizeInBits, uint32_t AlignInBits,
409 DINode::DIFlags Flags,
410 DINodeArray Elements,
411 unsigned RunTimeLang = 0,
412 StringRef UniqueIdentifier = "");
414 /// Create debugging information entry for a variant part. A
415 /// variant part normally has a discriminator (though this is not
416 /// required) and a number of variant children.
417 /// \param Scope Scope in which this union is defined.
418 /// \param Name Union name.
419 /// \param File File where this member is defined.
420 /// \param LineNumber Line number.
421 /// \param SizeInBits Member size.
422 /// \param AlignInBits Member alignment.
423 /// \param Flags Flags to encode member attribute, e.g. private
424 /// \param Discriminator Discriminant member
425 /// \param Elements Variant elements.
426 /// \param UniqueIdentifier A unique identifier for the union.
427 DICompositeType *createVariantPart(DIScope *Scope, StringRef Name,
428 DIFile *File, unsigned LineNumber,
429 uint64_t SizeInBits, uint32_t AlignInBits,
430 DINode::DIFlags Flags,
431 DIDerivedType *Discriminator,
432 DINodeArray Elements,
433 StringRef UniqueIdentifier = "");
435 /// Create debugging information for template
437 /// \param Scope Scope in which this type is defined.
438 /// \param Name Type parameter name.
439 /// \param Ty Parameter type.
440 DITemplateTypeParameter *
441 createTemplateTypeParameter(DIScope *Scope, StringRef Name, DIType *Ty);
443 /// Create debugging information for template
445 /// \param Scope Scope in which this type is defined.
446 /// \param Name Value parameter name.
447 /// \param Ty Parameter type.
448 /// \param Val Constant parameter value.
449 DITemplateValueParameter *createTemplateValueParameter(DIScope *Scope,
454 /// Create debugging information for a template template parameter.
455 /// \param Scope Scope in which this type is defined.
456 /// \param Name Value parameter name.
457 /// \param Ty Parameter type.
458 /// \param Val The fully qualified name of the template.
459 DITemplateValueParameter *createTemplateTemplateParameter(DIScope *Scope,
464 /// Create debugging information for a template parameter pack.
465 /// \param Scope Scope in which this type is defined.
466 /// \param Name Value parameter name.
467 /// \param Ty Parameter type.
468 /// \param Val An array of types in the pack.
469 DITemplateValueParameter *createTemplateParameterPack(DIScope *Scope,
474 /// Create debugging information entry for an array.
475 /// \param Size Array size.
476 /// \param AlignInBits Alignment.
477 /// \param Ty Element type.
478 /// \param Subscripts Subscripts.
479 DICompositeType *createArrayType(uint64_t Size, uint32_t AlignInBits,
480 DIType *Ty, DINodeArray Subscripts);
482 /// Create debugging information entry for a vector type.
483 /// \param Size Array size.
484 /// \param AlignInBits Alignment.
485 /// \param Ty Element type.
486 /// \param Subscripts Subscripts.
487 DICompositeType *createVectorType(uint64_t Size, uint32_t AlignInBits,
488 DIType *Ty, DINodeArray Subscripts);
490 /// Create debugging information entry for an
492 /// \param Scope Scope in which this enumeration is defined.
493 /// \param Name Union name.
494 /// \param File File where this member is defined.
495 /// \param LineNumber Line number.
496 /// \param SizeInBits Member size.
497 /// \param AlignInBits Member alignment.
498 /// \param Elements Enumeration elements.
499 /// \param UnderlyingType Underlying type of a C++11/ObjC fixed enum.
500 /// \param UniqueIdentifier A unique identifier for the enum.
501 /// \param IsFixed Boolean flag indicate if this is C++11/ObjC fixed enum.
502 DICompositeType *createEnumerationType(
503 DIScope *Scope, StringRef Name, DIFile *File, unsigned LineNumber,
504 uint64_t SizeInBits, uint32_t AlignInBits, DINodeArray Elements,
505 DIType *UnderlyingType, StringRef UniqueIdentifier = "", bool IsFixed = false);
507 /// Create subroutine type.
508 /// \param ParameterTypes An array of subroutine parameter types. This
509 /// includes return type at 0th index.
510 /// \param Flags E.g.: LValueReference.
511 /// These flags are used to emit dwarf attributes.
512 /// \param CC Calling convention, e.g. dwarf::DW_CC_normal
514 createSubroutineType(DITypeRefArray ParameterTypes,
515 DINode::DIFlags Flags = DINode::FlagZero,
518 /// Create a distinct clone of \p SP with FlagArtificial set.
519 static DISubprogram *createArtificialSubprogram(DISubprogram *SP);
521 /// Create a uniqued clone of \p Ty with FlagArtificial set.
522 static DIType *createArtificialType(DIType *Ty);
524 /// Create a uniqued clone of \p Ty with FlagObjectPointer and
525 /// FlagArtificial set.
526 static DIType *createObjectPointerType(DIType *Ty);
528 /// Create a permanent forward-declared type.
529 DICompositeType *createForwardDecl(unsigned Tag, StringRef Name,
530 DIScope *Scope, DIFile *F, unsigned Line,
531 unsigned RuntimeLang = 0,
532 uint64_t SizeInBits = 0,
533 uint32_t AlignInBits = 0,
534 StringRef UniqueIdentifier = "");
536 /// Create a temporary forward-declared type.
537 DICompositeType *createReplaceableCompositeType(
538 unsigned Tag, StringRef Name, DIScope *Scope, DIFile *F, unsigned Line,
539 unsigned RuntimeLang = 0, uint64_t SizeInBits = 0,
540 uint32_t AlignInBits = 0, DINode::DIFlags Flags = DINode::FlagFwdDecl,
541 StringRef UniqueIdentifier = "");
543 /// Retain DIScope* in a module even if it is not referenced
544 /// through debug info anchors.
545 void retainType(DIScope *T);
547 /// Create unspecified parameter type
548 /// for a subroutine type.
549 DIBasicType *createUnspecifiedParameter();
551 /// Get a DINodeArray, create one if required.
552 DINodeArray getOrCreateArray(ArrayRef<Metadata *> Elements);
554 /// Get a DIMacroNodeArray, create one if required.
555 DIMacroNodeArray getOrCreateMacroArray(ArrayRef<Metadata *> Elements);
557 /// Get a DITypeRefArray, create one if required.
558 DITypeRefArray getOrCreateTypeArray(ArrayRef<Metadata *> Elements);
560 /// Create a descriptor for a value range. This
561 /// implicitly uniques the values returned.
562 DISubrange *getOrCreateSubrange(int64_t Lo, int64_t Count);
563 DISubrange *getOrCreateSubrange(int64_t Lo, Metadata *CountNode);
565 /// Create a new descriptor for the specified variable.
566 /// \param Context Variable scope.
567 /// \param Name Name of the variable.
568 /// \param LinkageName Mangled name of the variable.
569 /// \param File File where this variable is defined.
570 /// \param LineNo Line number.
571 /// \param Ty Variable Type.
572 /// \param isLocalToUnit Boolean flag indicate whether this variable is
573 /// externally visible or not.
574 /// \param Expr The location of the global relative to the attached
576 /// \param Decl Reference to the corresponding declaration.
577 /// \param AlignInBits Variable alignment(or 0 if no alignment attr was
579 DIGlobalVariableExpression *createGlobalVariableExpression(
580 DIScope *Context, StringRef Name, StringRef LinkageName, DIFile *File,
581 unsigned LineNo, DIType *Ty, bool isLocalToUnit,
582 DIExpression *Expr = nullptr, MDNode *Decl = nullptr,
583 uint32_t AlignInBits = 0);
585 /// Identical to createGlobalVariable
586 /// except that the resulting DbgNode is temporary and meant to be RAUWed.
587 DIGlobalVariable *createTempGlobalVariableFwdDecl(
588 DIScope *Context, StringRef Name, StringRef LinkageName, DIFile *File,
589 unsigned LineNo, DIType *Ty, bool isLocalToUnit, MDNode *Decl = nullptr,
590 uint32_t AlignInBits = 0);
592 /// Create a new descriptor for an auto variable. This is a local variable
593 /// that is not a subprogram parameter.
595 /// \c Scope must be a \a DILocalScope, and thus its scope chain eventually
596 /// leads to a \a DISubprogram.
598 /// If \c AlwaysPreserve, this variable will be referenced from its
599 /// containing subprogram, and will survive some optimizations.
601 createAutoVariable(DIScope *Scope, StringRef Name, DIFile *File,
602 unsigned LineNo, DIType *Ty, bool AlwaysPreserve = false,
603 DINode::DIFlags Flags = DINode::FlagZero,
604 uint32_t AlignInBits = 0);
606 /// Create a new descriptor for an label.
608 /// \c Scope must be a \a DILocalScope, and thus its scope chain eventually
609 /// leads to a \a DISubprogram.
611 createLabel(DIScope *Scope, StringRef Name, DIFile *File, unsigned LineNo,
612 bool AlwaysPreserve = false);
614 /// Create a new descriptor for a parameter variable.
616 /// \c Scope must be a \a DILocalScope, and thus its scope chain eventually
617 /// leads to a \a DISubprogram.
619 /// \c ArgNo is the index (starting from \c 1) of this variable in the
620 /// subprogram parameters. \c ArgNo should not conflict with other
621 /// parameters of the same subprogram.
623 /// If \c AlwaysPreserve, this variable will be referenced from its
624 /// containing subprogram, and will survive some optimizations.
626 createParameterVariable(DIScope *Scope, StringRef Name, unsigned ArgNo,
627 DIFile *File, unsigned LineNo, DIType *Ty,
628 bool AlwaysPreserve = false,
629 DINode::DIFlags Flags = DINode::FlagZero);
631 /// Create a new descriptor for the specified
632 /// variable which has a complex address expression for its address.
633 /// \param Addr An array of complex address operations.
634 DIExpression *createExpression(ArrayRef<uint64_t> Addr = None);
635 DIExpression *createExpression(ArrayRef<int64_t> Addr);
637 /// Create an expression for a variable that does not have an address, but
638 /// does have a constant value.
639 DIExpression *createConstantValueExpression(uint64_t Val) {
640 return DIExpression::get(
641 VMContext, {dwarf::DW_OP_constu, Val, dwarf::DW_OP_stack_value});
644 /// Create a new descriptor for the specified subprogram.
645 /// See comments in DISubprogram* for descriptions of these fields.
646 /// \param Scope Function scope.
647 /// \param Name Function name.
648 /// \param LinkageName Mangled function name.
649 /// \param File File where this variable is defined.
650 /// \param LineNo Line number.
651 /// \param Ty Function type.
652 /// \param isLocalToUnit True if this function is not externally visible.
653 /// \param isDefinition True if this is a function definition.
654 /// \param ScopeLine Set to the beginning of the scope this starts
655 /// \param Flags e.g. is this function prototyped or not.
656 /// These flags are used to emit dwarf attributes.
657 /// \param isOptimized True if optimization is ON.
658 /// \param TParams Function template parameters.
659 /// \param ThrownTypes Exception types this function may throw.
660 DISubprogram *createFunction(
661 DIScope *Scope, StringRef Name, StringRef LinkageName, DIFile *File,
662 unsigned LineNo, DISubroutineType *Ty, bool isLocalToUnit,
663 bool isDefinition, unsigned ScopeLine,
664 DINode::DIFlags Flags = DINode::FlagZero, bool isOptimized = false,
665 DITemplateParameterArray TParams = nullptr,
666 DISubprogram *Decl = nullptr, DITypeArray ThrownTypes = nullptr);
668 /// Identical to createFunction,
669 /// except that the resulting DbgNode is meant to be RAUWed.
670 DISubprogram *createTempFunctionFwdDecl(
671 DIScope *Scope, StringRef Name, StringRef LinkageName, DIFile *File,
672 unsigned LineNo, DISubroutineType *Ty, bool isLocalToUnit,
673 bool isDefinition, unsigned ScopeLine,
674 DINode::DIFlags Flags = DINode::FlagZero, bool isOptimized = false,
675 DITemplateParameterArray TParams = nullptr,
676 DISubprogram *Decl = nullptr, DITypeArray ThrownTypes = nullptr);
678 /// Create a new descriptor for the specified C++ method.
679 /// See comments in \a DISubprogram* for descriptions of these fields.
680 /// \param Scope Function scope.
681 /// \param Name Function name.
682 /// \param LinkageName Mangled function name.
683 /// \param File File where this variable is defined.
684 /// \param LineNo Line number.
685 /// \param Ty Function type.
686 /// \param isLocalToUnit True if this function is not externally visible..
687 /// \param isDefinition True if this is a function definition.
688 /// \param Virtuality Attributes describing virtualness. e.g. pure
689 /// virtual function.
690 /// \param VTableIndex Index no of this method in virtual table, or -1u if
692 /// \param ThisAdjustment
693 /// MS ABI-specific adjustment of 'this' that occurs
695 /// \param VTableHolder Type that holds vtable.
696 /// \param Flags e.g. is this function prototyped or not.
697 /// This flags are used to emit dwarf attributes.
698 /// \param isOptimized True if optimization is ON.
699 /// \param TParams Function template parameters.
700 /// \param ThrownTypes Exception types this function may throw.
701 DISubprogram *createMethod(
702 DIScope *Scope, StringRef Name, StringRef LinkageName, DIFile *File,
703 unsigned LineNo, DISubroutineType *Ty, bool isLocalToUnit,
704 bool isDefinition, unsigned Virtuality = 0, unsigned VTableIndex = 0,
705 int ThisAdjustment = 0, DIType *VTableHolder = nullptr,
706 DINode::DIFlags Flags = DINode::FlagZero, bool isOptimized = false,
707 DITemplateParameterArray TParams = nullptr,
708 DITypeArray ThrownTypes = nullptr);
710 /// This creates new descriptor for a namespace with the specified
712 /// \param Scope Namespace scope
713 /// \param Name Name of this namespace
714 /// \param ExportSymbols True for C++ inline namespaces.
715 DINamespace *createNameSpace(DIScope *Scope, StringRef Name,
718 /// This creates new descriptor for a module with the specified
720 /// \param Scope Parent scope
721 /// \param Name Name of this module
722 /// \param ConfigurationMacros
723 /// A space-separated shell-quoted list of -D macro
724 /// definitions as they would appear on a command line.
725 /// \param IncludePath The path to the module map file.
726 /// \param ISysRoot The clang system root (value of -isysroot).
727 DIModule *createModule(DIScope *Scope, StringRef Name,
728 StringRef ConfigurationMacros,
729 StringRef IncludePath,
732 /// This creates a descriptor for a lexical block with a new file
733 /// attached. This merely extends the existing
734 /// lexical block as it crosses a file.
735 /// \param Scope Lexical block.
736 /// \param File Source file.
737 /// \param Discriminator DWARF path discriminator value.
738 DILexicalBlockFile *createLexicalBlockFile(DIScope *Scope, DIFile *File,
739 unsigned Discriminator = 0);
741 /// This creates a descriptor for a lexical block with the
742 /// specified parent context.
743 /// \param Scope Parent lexical scope.
744 /// \param File Source file.
745 /// \param Line Line number.
746 /// \param Col Column number.
747 DILexicalBlock *createLexicalBlock(DIScope *Scope, DIFile *File,
748 unsigned Line, unsigned Col);
750 /// Create a descriptor for an imported module.
751 /// \param Context The scope this module is imported into
752 /// \param NS The namespace being imported here.
753 /// \param File File where the declaration is located.
754 /// \param Line Line number of the declaration.
755 DIImportedEntity *createImportedModule(DIScope *Context, DINamespace *NS,
756 DIFile *File, unsigned Line);
758 /// Create a descriptor for an imported module.
759 /// \param Context The scope this module is imported into.
760 /// \param NS An aliased namespace.
761 /// \param File File where the declaration is located.
762 /// \param Line Line number of the declaration.
763 DIImportedEntity *createImportedModule(DIScope *Context,
764 DIImportedEntity *NS, DIFile *File,
767 /// Create a descriptor for an imported module.
768 /// \param Context The scope this module is imported into.
769 /// \param M The module being imported here
770 /// \param File File where the declaration is located.
771 /// \param Line Line number of the declaration.
772 DIImportedEntity *createImportedModule(DIScope *Context, DIModule *M,
773 DIFile *File, unsigned Line);
775 /// Create a descriptor for an imported function.
776 /// \param Context The scope this module is imported into.
777 /// \param Decl The declaration (or definition) of a function, type, or
779 /// \param File File where the declaration is located.
780 /// \param Line Line number of the declaration.
781 DIImportedEntity *createImportedDeclaration(DIScope *Context, DINode *Decl,
782 DIFile *File, unsigned Line,
783 StringRef Name = "");
785 /// Insert a new llvm.dbg.declare intrinsic call.
786 /// \param Storage llvm::Value of the variable
787 /// \param VarInfo Variable's debug info descriptor.
788 /// \param Expr A complex location expression.
789 /// \param DL Debug info location.
790 /// \param InsertAtEnd Location for the new intrinsic.
791 Instruction *insertDeclare(llvm::Value *Storage, DILocalVariable *VarInfo,
792 DIExpression *Expr, const DILocation *DL,
793 BasicBlock *InsertAtEnd);
795 /// Insert a new llvm.dbg.declare intrinsic call.
796 /// \param Storage llvm::Value of the variable
797 /// \param VarInfo Variable's debug info descriptor.
798 /// \param Expr A complex location expression.
799 /// \param DL Debug info location.
800 /// \param InsertBefore Location for the new intrinsic.
801 Instruction *insertDeclare(llvm::Value *Storage, DILocalVariable *VarInfo,
802 DIExpression *Expr, const DILocation *DL,
803 Instruction *InsertBefore);
805 /// Insert a new llvm.dbg.label intrinsic call.
806 /// \param LabelInfo Label's debug info descriptor.
807 /// \param DL Debug info location.
808 /// \param InsertBefore Location for the new intrinsic.
809 Instruction *insertLabel(DILabel *LabelInfo, const DILocation *DL,
810 Instruction *InsertBefore);
812 /// Insert a new llvm.dbg.label intrinsic call.
813 /// \param LabelInfo Label's debug info descriptor.
814 /// \param DL Debug info location.
815 /// \param InsertAtEnd Location for the new intrinsic.
816 Instruction *insertLabel(DILabel *LabelInfo, const DILocation *DL,
817 BasicBlock *InsertAtEnd);
819 /// Insert a new llvm.dbg.value intrinsic call.
820 /// \param Val llvm::Value of the variable
821 /// \param VarInfo Variable's debug info descriptor.
822 /// \param Expr A complex location expression.
823 /// \param DL Debug info location.
824 /// \param InsertAtEnd Location for the new intrinsic.
825 Instruction *insertDbgValueIntrinsic(llvm::Value *Val,
826 DILocalVariable *VarInfo,
828 const DILocation *DL,
829 BasicBlock *InsertAtEnd);
831 /// Insert a new llvm.dbg.value intrinsic call.
832 /// \param Val llvm::Value of the variable
833 /// \param VarInfo Variable's debug info descriptor.
834 /// \param Expr A complex location expression.
835 /// \param DL Debug info location.
836 /// \param InsertBefore Location for the new intrinsic.
837 Instruction *insertDbgValueIntrinsic(llvm::Value *Val,
838 DILocalVariable *VarInfo,
840 const DILocation *DL,
841 Instruction *InsertBefore);
843 /// Replace the vtable holder in the given type.
845 /// If this creates a self reference, it may orphan some unresolved cycles
846 /// in the operands of \c T, so \a DIBuilder needs to track that.
847 void replaceVTableHolder(DICompositeType *&T,
848 DIType *VTableHolder);
850 /// Replace arrays on a composite type.
852 /// If \c T is resolved, but the arrays aren't -- which can happen if \c T
853 /// has a self-reference -- \a DIBuilder needs to track the array to
855 void replaceArrays(DICompositeType *&T, DINodeArray Elements,
856 DINodeArray TParams = DINodeArray());
858 /// Replace a temporary node.
860 /// Call \a MDNode::replaceAllUsesWith() on \c N, replacing it with \c
863 /// If \c Replacement is the same as \c N.get(), instead call \a
864 /// MDNode::replaceWithUniqued(). In this case, the uniqued node could
865 /// have a different address, so we return the final address.
866 template <class NodeTy>
867 NodeTy *replaceTemporary(TempMDNode &&N, NodeTy *Replacement) {
868 if (N.get() == Replacement)
869 return cast<NodeTy>(MDNode::replaceWithUniqued(std::move(N)));
871 N->replaceAllUsesWith(Replacement);
876 // Create wrappers for C Binding types (see CBindingWrapping.h).
877 DEFINE_ISA_CONVERSION_FUNCTIONS(DIBuilder, LLVMDIBuilderRef)
879 } // end namespace llvm
881 #endif // LLVM_IR_DIBUILDER_H