Line data Source code
1 : //===- DIBuilder.h - Debug Information Builder ------------------*- C++ -*-===//
2 : //
3 : // The LLVM Compiler Infrastructure
4 : //
5 : // This file is distributed under the University of Illinois Open Source
6 : // License. See LICENSE.TXT for details.
7 : //
8 : //===----------------------------------------------------------------------===//
9 : //
10 : // This file defines a DIBuilder that is useful for creating debugging
11 : // information entries in LLVM IR form.
12 : //
13 : //===----------------------------------------------------------------------===//
14 :
15 : #ifndef LLVM_IR_DIBUILDER_H
16 : #define LLVM_IR_DIBUILDER_H
17 :
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"
29 : #include <algorithm>
30 : #include <cstdint>
31 :
32 : namespace llvm {
33 :
34 : class BasicBlock;
35 : class Constant;
36 : class Function;
37 : class Instruction;
38 : class LLVMContext;
39 : class Module;
40 : class Value;
41 :
42 : class DIBuilder {
43 : Module &M;
44 : LLVMContext &VMContext;
45 :
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
50 :
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;
61 :
62 : /// Track nodes that may be unresolved.
63 : SmallVector<TrackingMDNodeRef, 4> UnresolvedNodes;
64 : bool AllowUnresolvedNodes;
65 :
66 : /// Each subprogram's preserved local variables.
67 : ///
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
70 : /// copy.
71 : DenseMap<MDNode *, SmallVector<TrackingMDNodeRef, 1>> PreservedVariables;
72 :
73 : /// Each subprogram's preserved labels.
74 : DenseMap<MDNode *, SmallVector<TrackingMDNodeRef, 1>> PreservedLabels;
75 :
76 : /// Create a temporary.
77 : ///
78 : /// Create an \a temporary node and track it in \a UnresolvedNodes.
79 : void trackIfUnresolved(MDNode *N);
80 :
81 : /// Internal helper for insertDeclare.
82 : Instruction *insertDeclare(llvm::Value *Storage, DILocalVariable *VarInfo,
83 : DIExpression *Expr, const DILocation *DL,
84 : BasicBlock *InsertBB, Instruction *InsertBefore);
85 :
86 : /// Internal helper for insertLabel.
87 : Instruction *insertLabel(DILabel *LabelInfo, const DILocation *DL,
88 : BasicBlock *InsertBB, Instruction *InsertBefore);
89 :
90 : /// Internal helper for insertDbgValueIntrinsic.
91 : Instruction *
92 : insertDbgValueIntrinsic(llvm::Value *Val, DILocalVariable *VarInfo,
93 : DIExpression *Expr, const DILocation *DL,
94 : BasicBlock *InsertBB, Instruction *InsertBefore);
95 :
96 : public:
97 : /// Construct a builder for a module.
98 : ///
99 : /// If \c AllowUnresolved, collect unresolved nodes attached to the module
100 : /// in order to resolve cycles during \a finalize().
101 : ///
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;
107 :
108 : /// Construct any deferred debug info descriptors.
109 : void finalize();
110 :
111 : /// Finalize a specific subprogram - no new variables may be added to this
112 : /// subprogram afterwards.
113 : void finalizeSubprogram(DISubprogram *SP);
114 :
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
121 : /// version string.
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
129 : /// Objective-C.
130 : /// \param SplitName The name of the file that we'll split debug info
131 : /// out into.
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 NameTableKind Whether to emit .debug_gnu_pubnames,
138 : /// .debug_pubnames, or no pubnames at all.
139 : DICompileUnit *
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 : DICompileUnit::DebugNameTableKind NameTableKind =
148 : DICompileUnit::DebugNameTableKind::Default);
149 :
150 : /// Create a file descriptor to hold debugging information for a file.
151 : /// \param Filename File name.
152 : /// \param Directory Directory.
153 : /// \param Checksum Optional checksum kind (e.g. CSK_MD5, CSK_SHA1, etc.)
154 : /// and value.
155 : /// \param Source Optional source text.
156 : DIFile *
157 : createFile(StringRef Filename, StringRef Directory,
158 : Optional<DIFile::ChecksumInfo<StringRef>> Checksum = None,
159 : Optional<StringRef> Source = None);
160 :
161 : /// Create debugging information entry for a macro.
162 : /// \param Parent Macro parent (could be nullptr).
163 : /// \param Line Source line number where the macro is defined.
164 : /// \param MacroType DW_MACINFO_define or DW_MACINFO_undef.
165 : /// \param Name Macro name.
166 : /// \param Value Macro value.
167 : DIMacro *createMacro(DIMacroFile *Parent, unsigned Line, unsigned MacroType,
168 : StringRef Name, StringRef Value = StringRef());
169 :
170 : /// Create debugging information temporary entry for a macro file.
171 : /// List of macro node direct children will be calculated by DIBuilder,
172 : /// using the \p Parent relationship.
173 : /// \param Parent Macro file parent (could be nullptr).
174 : /// \param Line Source line number where the macro file is included.
175 : /// \param File File descriptor containing the name of the macro file.
176 : DIMacroFile *createTempMacroFile(DIMacroFile *Parent, unsigned Line,
177 : DIFile *File);
178 :
179 : /// Create a single enumerator value.
180 : DIEnumerator *createEnumerator(StringRef Name, int64_t Val, bool IsUnsigned = false);
181 :
182 : /// Create a DWARF unspecified type.
183 : DIBasicType *createUnspecifiedType(StringRef Name);
184 :
185 : /// Create C++11 nullptr type.
186 : DIBasicType *createNullPtrType();
187 :
188 : /// Create debugging information entry for a basic
189 : /// type.
190 : /// \param Name Type name.
191 : /// \param SizeInBits Size of the type.
192 : /// \param Encoding DWARF encoding code, e.g., dwarf::DW_ATE_float.
193 : /// \param Flags Optional DWARF attributes, e.g., DW_AT_endianity.
194 : DIBasicType *createBasicType(StringRef Name, uint64_t SizeInBits,
195 : unsigned Encoding,
196 : DINode::DIFlags Flags = DINode::FlagZero);
197 :
198 : /// Create debugging information entry for a qualified
199 : /// type, e.g. 'const int'.
200 : /// \param Tag Tag identifing type, e.g. dwarf::TAG_volatile_type
201 : /// \param FromTy Base Type.
202 : DIDerivedType *createQualifiedType(unsigned Tag, DIType *FromTy);
203 :
204 : /// Create debugging information entry for a pointer.
205 : /// \param PointeeTy Type pointed by this pointer.
206 : /// \param SizeInBits Size.
207 : /// \param AlignInBits Alignment. (optional)
208 : /// \param DWARFAddressSpace DWARF address space. (optional)
209 : /// \param Name Pointer type name. (optional)
210 : DIDerivedType *createPointerType(DIType *PointeeTy, uint64_t SizeInBits,
211 : uint32_t AlignInBits = 0,
212 : Optional<unsigned> DWARFAddressSpace =
213 : None,
214 : StringRef Name = "");
215 :
216 : /// Create debugging information entry for a pointer to member.
217 : /// \param PointeeTy Type pointed to by this pointer.
218 : /// \param SizeInBits Size.
219 : /// \param AlignInBits Alignment. (optional)
220 : /// \param Class Type for which this pointer points to members of.
221 : DIDerivedType *
222 : createMemberPointerType(DIType *PointeeTy, DIType *Class,
223 : uint64_t SizeInBits, uint32_t AlignInBits = 0,
224 : DINode::DIFlags Flags = DINode::FlagZero);
225 :
226 : /// Create debugging information entry for a c++
227 : /// style reference or rvalue reference type.
228 : DIDerivedType *createReferenceType(unsigned Tag, DIType *RTy,
229 : uint64_t SizeInBits = 0,
230 : uint32_t AlignInBits = 0,
231 : Optional<unsigned> DWARFAddressSpace =
232 : None);
233 :
234 : /// Create debugging information entry for a typedef.
235 : /// \param Ty Original type.
236 : /// \param Name Typedef name.
237 : /// \param File File where this type is defined.
238 : /// \param LineNo Line number.
239 : /// \param Context The surrounding context for the typedef.
240 : DIDerivedType *createTypedef(DIType *Ty, StringRef Name, DIFile *File,
241 : unsigned LineNo, DIScope *Context);
242 :
243 : /// Create debugging information entry for a 'friend'.
244 : DIDerivedType *createFriend(DIType *Ty, DIType *FriendTy);
245 :
246 : /// Create debugging information entry to establish
247 : /// inheritance relationship between two types.
248 : /// \param Ty Original type.
249 : /// \param BaseTy Base type. Ty is inherits from base.
250 : /// \param BaseOffset Base offset.
251 : /// \param VBPtrOffset Virtual base pointer offset.
252 : /// \param Flags Flags to describe inheritance attribute,
253 : /// e.g. private
254 : DIDerivedType *createInheritance(DIType *Ty, DIType *BaseTy,
255 : uint64_t BaseOffset, uint32_t VBPtrOffset,
256 : DINode::DIFlags Flags);
257 :
258 : /// Create debugging information entry for a member.
259 : /// \param Scope Member scope.
260 : /// \param Name Member name.
261 : /// \param File File where this member is defined.
262 : /// \param LineNo Line number.
263 : /// \param SizeInBits Member size.
264 : /// \param AlignInBits Member alignment.
265 : /// \param OffsetInBits Member offset.
266 : /// \param Flags Flags to encode member attribute, e.g. private
267 : /// \param Ty Parent type.
268 : DIDerivedType *createMemberType(DIScope *Scope, StringRef Name,
269 : DIFile *File, unsigned LineNo,
270 : uint64_t SizeInBits,
271 : uint32_t AlignInBits,
272 : uint64_t OffsetInBits,
273 : DINode::DIFlags Flags, DIType *Ty);
274 :
275 : /// Create debugging information entry for a variant. A variant
276 : /// normally should be a member of a variant part.
277 : /// \param Scope Member scope.
278 : /// \param Name Member name.
279 : /// \param File File where this member is defined.
280 : /// \param LineNo Line number.
281 : /// \param SizeInBits Member size.
282 : /// \param AlignInBits Member alignment.
283 : /// \param OffsetInBits Member offset.
284 : /// \param Flags Flags to encode member attribute, e.g. private
285 : /// \param Discriminant The discriminant for this branch; null for
286 : /// the default branch
287 : /// \param Ty Parent type.
288 : DIDerivedType *createVariantMemberType(DIScope *Scope, StringRef Name,
289 : DIFile *File, unsigned LineNo,
290 : uint64_t SizeInBits,
291 : uint32_t AlignInBits,
292 : uint64_t OffsetInBits,
293 : Constant *Discriminant,
294 : DINode::DIFlags Flags, DIType *Ty);
295 :
296 : /// Create debugging information entry for a bit field member.
297 : /// \param Scope Member scope.
298 : /// \param Name Member name.
299 : /// \param File File where this member is defined.
300 : /// \param LineNo Line number.
301 : /// \param SizeInBits Member size.
302 : /// \param OffsetInBits Member offset.
303 : /// \param StorageOffsetInBits Member storage offset.
304 : /// \param Flags Flags to encode member attribute.
305 : /// \param Ty Parent type.
306 : DIDerivedType *createBitFieldMemberType(
307 : DIScope *Scope, StringRef Name, DIFile *File, unsigned LineNo,
308 : uint64_t SizeInBits, uint64_t OffsetInBits,
309 : uint64_t StorageOffsetInBits, DINode::DIFlags Flags, DIType *Ty);
310 :
311 : /// Create debugging information entry for a
312 : /// C++ static data member.
313 : /// \param Scope Member scope.
314 : /// \param Name Member name.
315 : /// \param File File where this member is declared.
316 : /// \param LineNo Line number.
317 : /// \param Ty Type of the static member.
318 : /// \param Flags Flags to encode member attribute, e.g. private.
319 : /// \param Val Const initializer of the member.
320 : /// \param AlignInBits Member alignment.
321 : DIDerivedType *createStaticMemberType(DIScope *Scope, StringRef Name,
322 : DIFile *File, unsigned LineNo,
323 : DIType *Ty, DINode::DIFlags Flags,
324 : Constant *Val,
325 : uint32_t AlignInBits = 0);
326 :
327 : /// Create debugging information entry for Objective-C
328 : /// instance variable.
329 : /// \param Name Member name.
330 : /// \param File File where this member is defined.
331 : /// \param LineNo Line number.
332 : /// \param SizeInBits Member size.
333 : /// \param AlignInBits Member alignment.
334 : /// \param OffsetInBits Member offset.
335 : /// \param Flags Flags to encode member attribute, e.g. private
336 : /// \param Ty Parent type.
337 : /// \param PropertyNode Property associated with this ivar.
338 : DIDerivedType *createObjCIVar(StringRef Name, DIFile *File, unsigned LineNo,
339 : uint64_t SizeInBits, uint32_t AlignInBits,
340 : uint64_t OffsetInBits, DINode::DIFlags Flags,
341 : DIType *Ty, MDNode *PropertyNode);
342 :
343 : /// Create debugging information entry for Objective-C
344 : /// property.
345 : /// \param Name Property name.
346 : /// \param File File where this property is defined.
347 : /// \param LineNumber Line number.
348 : /// \param GetterName Name of the Objective C property getter selector.
349 : /// \param SetterName Name of the Objective C property setter selector.
350 : /// \param PropertyAttributes Objective C property attributes.
351 : /// \param Ty Type.
352 : DIObjCProperty *createObjCProperty(StringRef Name, DIFile *File,
353 : unsigned LineNumber,
354 : StringRef GetterName,
355 : StringRef SetterName,
356 : unsigned PropertyAttributes, DIType *Ty);
357 :
358 : /// Create debugging information entry for a class.
359 : /// \param Scope Scope in which this class is defined.
360 : /// \param Name class name.
361 : /// \param File File where this member is defined.
362 : /// \param LineNumber Line number.
363 : /// \param SizeInBits Member size.
364 : /// \param AlignInBits Member alignment.
365 : /// \param OffsetInBits Member offset.
366 : /// \param Flags Flags to encode member attribute, e.g. private
367 : /// \param Elements class members.
368 : /// \param VTableHolder Debug info of the base class that contains vtable
369 : /// for this type. This is used in
370 : /// DW_AT_containing_type. See DWARF documentation
371 : /// for more info.
372 : /// \param TemplateParms Template type parameters.
373 : /// \param UniqueIdentifier A unique identifier for the class.
374 : DICompositeType *createClassType(
375 : DIScope *Scope, StringRef Name, DIFile *File, unsigned LineNumber,
376 : uint64_t SizeInBits, uint32_t AlignInBits, uint64_t OffsetInBits,
377 : DINode::DIFlags Flags, DIType *DerivedFrom, DINodeArray Elements,
378 : DIType *VTableHolder = nullptr, MDNode *TemplateParms = nullptr,
379 : StringRef UniqueIdentifier = "");
380 :
381 : /// Create debugging information entry for a struct.
382 : /// \param Scope Scope in which this struct is defined.
383 : /// \param Name Struct name.
384 : /// \param File File where this member is defined.
385 : /// \param LineNumber Line number.
386 : /// \param SizeInBits Member size.
387 : /// \param AlignInBits Member alignment.
388 : /// \param Flags Flags to encode member attribute, e.g. private
389 : /// \param Elements Struct elements.
390 : /// \param RunTimeLang Optional parameter, Objective-C runtime version.
391 : /// \param UniqueIdentifier A unique identifier for the struct.
392 : DICompositeType *createStructType(
393 : DIScope *Scope, StringRef Name, DIFile *File, unsigned LineNumber,
394 : uint64_t SizeInBits, uint32_t AlignInBits, DINode::DIFlags Flags,
395 : DIType *DerivedFrom, DINodeArray Elements, unsigned RunTimeLang = 0,
396 : DIType *VTableHolder = nullptr, StringRef UniqueIdentifier = "");
397 :
398 : /// Create debugging information entry for an union.
399 : /// \param Scope Scope in which this union is defined.
400 : /// \param Name Union name.
401 : /// \param File File where this member is defined.
402 : /// \param LineNumber Line number.
403 : /// \param SizeInBits Member size.
404 : /// \param AlignInBits Member alignment.
405 : /// \param Flags Flags to encode member attribute, e.g. private
406 : /// \param Elements Union elements.
407 : /// \param RunTimeLang Optional parameter, Objective-C runtime version.
408 : /// \param UniqueIdentifier A unique identifier for the union.
409 : DICompositeType *createUnionType(DIScope *Scope, StringRef Name,
410 : DIFile *File, unsigned LineNumber,
411 : uint64_t SizeInBits, uint32_t AlignInBits,
412 : DINode::DIFlags Flags,
413 : DINodeArray Elements,
414 : unsigned RunTimeLang = 0,
415 : StringRef UniqueIdentifier = "");
416 :
417 : /// Create debugging information entry for a variant part. A
418 : /// variant part normally has a discriminator (though this is not
419 : /// required) and a number of variant children.
420 : /// \param Scope Scope in which this union is defined.
421 : /// \param Name Union name.
422 : /// \param File File where this member is defined.
423 : /// \param LineNumber Line number.
424 : /// \param SizeInBits Member size.
425 : /// \param AlignInBits Member alignment.
426 : /// \param Flags Flags to encode member attribute, e.g. private
427 : /// \param Discriminator Discriminant member
428 : /// \param Elements Variant elements.
429 : /// \param UniqueIdentifier A unique identifier for the union.
430 : DICompositeType *createVariantPart(DIScope *Scope, StringRef Name,
431 : DIFile *File, unsigned LineNumber,
432 : uint64_t SizeInBits, uint32_t AlignInBits,
433 : DINode::DIFlags Flags,
434 : DIDerivedType *Discriminator,
435 : DINodeArray Elements,
436 : StringRef UniqueIdentifier = "");
437 :
438 : /// Create debugging information for template
439 : /// type parameter.
440 : /// \param Scope Scope in which this type is defined.
441 : /// \param Name Type parameter name.
442 : /// \param Ty Parameter type.
443 : DITemplateTypeParameter *
444 : createTemplateTypeParameter(DIScope *Scope, StringRef Name, DIType *Ty);
445 :
446 : /// Create debugging information for template
447 : /// value parameter.
448 : /// \param Scope Scope in which this type is defined.
449 : /// \param Name Value parameter name.
450 : /// \param Ty Parameter type.
451 : /// \param Val Constant parameter value.
452 : DITemplateValueParameter *createTemplateValueParameter(DIScope *Scope,
453 : StringRef Name,
454 : DIType *Ty,
455 : Constant *Val);
456 :
457 : /// Create debugging information for a template template parameter.
458 : /// \param Scope Scope in which this type is defined.
459 : /// \param Name Value parameter name.
460 : /// \param Ty Parameter type.
461 : /// \param Val The fully qualified name of the template.
462 : DITemplateValueParameter *createTemplateTemplateParameter(DIScope *Scope,
463 : StringRef Name,
464 : DIType *Ty,
465 : StringRef Val);
466 :
467 : /// Create debugging information for a template parameter pack.
468 : /// \param Scope Scope in which this type is defined.
469 : /// \param Name Value parameter name.
470 : /// \param Ty Parameter type.
471 : /// \param Val An array of types in the pack.
472 : DITemplateValueParameter *createTemplateParameterPack(DIScope *Scope,
473 : StringRef Name,
474 : DIType *Ty,
475 : DINodeArray Val);
476 :
477 : /// Create debugging information entry for an array.
478 : /// \param Size Array size.
479 : /// \param AlignInBits Alignment.
480 : /// \param Ty Element type.
481 : /// \param Subscripts Subscripts.
482 : DICompositeType *createArrayType(uint64_t Size, uint32_t AlignInBits,
483 : DIType *Ty, DINodeArray Subscripts);
484 :
485 : /// Create debugging information entry for a vector type.
486 : /// \param Size Array size.
487 : /// \param AlignInBits Alignment.
488 : /// \param Ty Element type.
489 : /// \param Subscripts Subscripts.
490 : DICompositeType *createVectorType(uint64_t Size, uint32_t AlignInBits,
491 : DIType *Ty, DINodeArray Subscripts);
492 :
493 : /// Create debugging information entry for an
494 : /// enumeration.
495 : /// \param Scope Scope in which this enumeration is defined.
496 : /// \param Name Union name.
497 : /// \param File File where this member is defined.
498 : /// \param LineNumber Line number.
499 : /// \param SizeInBits Member size.
500 : /// \param AlignInBits Member alignment.
501 : /// \param Elements Enumeration elements.
502 : /// \param UnderlyingType Underlying type of a C++11/ObjC fixed enum.
503 : /// \param UniqueIdentifier A unique identifier for the enum.
504 : /// \param IsFixed Boolean flag indicate if this is C++11/ObjC fixed enum.
505 : DICompositeType *createEnumerationType(
506 : DIScope *Scope, StringRef Name, DIFile *File, unsigned LineNumber,
507 : uint64_t SizeInBits, uint32_t AlignInBits, DINodeArray Elements,
508 : DIType *UnderlyingType, StringRef UniqueIdentifier = "", bool IsFixed = false);
509 :
510 : /// Create subroutine type.
511 : /// \param ParameterTypes An array of subroutine parameter types. This
512 : /// includes return type at 0th index.
513 : /// \param Flags E.g.: LValueReference.
514 : /// These flags are used to emit dwarf attributes.
515 : /// \param CC Calling convention, e.g. dwarf::DW_CC_normal
516 : DISubroutineType *
517 : createSubroutineType(DITypeRefArray ParameterTypes,
518 : DINode::DIFlags Flags = DINode::FlagZero,
519 : unsigned CC = 0);
520 :
521 : /// Create a distinct clone of \p SP with FlagArtificial set.
522 : static DISubprogram *createArtificialSubprogram(DISubprogram *SP);
523 :
524 : /// Create a uniqued clone of \p Ty with FlagArtificial set.
525 : static DIType *createArtificialType(DIType *Ty);
526 :
527 : /// Create a uniqued clone of \p Ty with FlagObjectPointer and
528 : /// FlagArtificial set.
529 : static DIType *createObjectPointerType(DIType *Ty);
530 :
531 : /// Create a permanent forward-declared type.
532 : DICompositeType *createForwardDecl(unsigned Tag, StringRef Name,
533 : DIScope *Scope, DIFile *F, unsigned Line,
534 : unsigned RuntimeLang = 0,
535 : uint64_t SizeInBits = 0,
536 : uint32_t AlignInBits = 0,
537 : StringRef UniqueIdentifier = "");
538 :
539 : /// Create a temporary forward-declared type.
540 : DICompositeType *createReplaceableCompositeType(
541 : unsigned Tag, StringRef Name, DIScope *Scope, DIFile *F, unsigned Line,
542 : unsigned RuntimeLang = 0, uint64_t SizeInBits = 0,
543 : uint32_t AlignInBits = 0, DINode::DIFlags Flags = DINode::FlagFwdDecl,
544 : StringRef UniqueIdentifier = "");
545 :
546 : /// Retain DIScope* in a module even if it is not referenced
547 : /// through debug info anchors.
548 : void retainType(DIScope *T);
549 :
550 : /// Create unspecified parameter type
551 : /// for a subroutine type.
552 : DIBasicType *createUnspecifiedParameter();
553 :
554 : /// Get a DINodeArray, create one if required.
555 : DINodeArray getOrCreateArray(ArrayRef<Metadata *> Elements);
556 :
557 : /// Get a DIMacroNodeArray, create one if required.
558 : DIMacroNodeArray getOrCreateMacroArray(ArrayRef<Metadata *> Elements);
559 :
560 : /// Get a DITypeRefArray, create one if required.
561 : DITypeRefArray getOrCreateTypeArray(ArrayRef<Metadata *> Elements);
562 :
563 : /// Create a descriptor for a value range. This
564 : /// implicitly uniques the values returned.
565 : DISubrange *getOrCreateSubrange(int64_t Lo, int64_t Count);
566 : DISubrange *getOrCreateSubrange(int64_t Lo, Metadata *CountNode);
567 :
568 : /// Create a new descriptor for the specified variable.
569 : /// \param Context Variable scope.
570 : /// \param Name Name of the variable.
571 : /// \param LinkageName Mangled name of the variable.
572 : /// \param File File where this variable is defined.
573 : /// \param LineNo Line number.
574 : /// \param Ty Variable Type.
575 : /// \param isLocalToUnit Boolean flag indicate whether this variable is
576 : /// externally visible or not.
577 : /// \param Expr The location of the global relative to the attached
578 : /// GlobalVariable.
579 : /// \param Decl Reference to the corresponding declaration.
580 : /// \param AlignInBits Variable alignment(or 0 if no alignment attr was
581 : /// specified)
582 : DIGlobalVariableExpression *createGlobalVariableExpression(
583 : DIScope *Context, StringRef Name, StringRef LinkageName, DIFile *File,
584 : unsigned LineNo, DIType *Ty, bool isLocalToUnit,
585 : DIExpression *Expr = nullptr, MDNode *Decl = nullptr,
586 : MDTuple *templateParams = nullptr, uint32_t AlignInBits = 0);
587 :
588 : /// Identical to createGlobalVariable
589 : /// except that the resulting DbgNode is temporary and meant to be RAUWed.
590 : DIGlobalVariable *createTempGlobalVariableFwdDecl(
591 : DIScope *Context, StringRef Name, StringRef LinkageName, DIFile *File,
592 : unsigned LineNo, DIType *Ty, bool isLocalToUnit, MDNode *Decl = nullptr,
593 : MDTuple *templateParams = nullptr, uint32_t AlignInBits = 0);
594 :
595 : /// Create a new descriptor for an auto variable. This is a local variable
596 : /// that is not a subprogram parameter.
597 : ///
598 : /// \c Scope must be a \a DILocalScope, and thus its scope chain eventually
599 : /// leads to a \a DISubprogram.
600 : ///
601 : /// If \c AlwaysPreserve, this variable will be referenced from its
602 : /// containing subprogram, and will survive some optimizations.
603 : DILocalVariable *
604 : createAutoVariable(DIScope *Scope, StringRef Name, DIFile *File,
605 : unsigned LineNo, DIType *Ty, bool AlwaysPreserve = false,
606 : DINode::DIFlags Flags = DINode::FlagZero,
607 : uint32_t AlignInBits = 0);
608 :
609 : /// Create a new descriptor for an label.
610 : ///
611 : /// \c Scope must be a \a DILocalScope, and thus its scope chain eventually
612 : /// leads to a \a DISubprogram.
613 : DILabel *
614 : createLabel(DIScope *Scope, StringRef Name, DIFile *File, unsigned LineNo,
615 : bool AlwaysPreserve = false);
616 :
617 : /// Create a new descriptor for a parameter variable.
618 : ///
619 : /// \c Scope must be a \a DILocalScope, and thus its scope chain eventually
620 : /// leads to a \a DISubprogram.
621 : ///
622 : /// \c ArgNo is the index (starting from \c 1) of this variable in the
623 : /// subprogram parameters. \c ArgNo should not conflict with other
624 : /// parameters of the same subprogram.
625 : ///
626 : /// If \c AlwaysPreserve, this variable will be referenced from its
627 : /// containing subprogram, and will survive some optimizations.
628 : DILocalVariable *
629 : createParameterVariable(DIScope *Scope, StringRef Name, unsigned ArgNo,
630 : DIFile *File, unsigned LineNo, DIType *Ty,
631 : bool AlwaysPreserve = false,
632 : DINode::DIFlags Flags = DINode::FlagZero);
633 :
634 : /// Create a new descriptor for the specified
635 : /// variable which has a complex address expression for its address.
636 : /// \param Addr An array of complex address operations.
637 : DIExpression *createExpression(ArrayRef<uint64_t> Addr = None);
638 : DIExpression *createExpression(ArrayRef<int64_t> Addr);
639 :
640 : /// Create an expression for a variable that does not have an address, but
641 : /// does have a constant value.
642 0 : DIExpression *createConstantValueExpression(uint64_t Val) {
643 31 : return DIExpression::get(
644 0 : VMContext, {dwarf::DW_OP_constu, Val, dwarf::DW_OP_stack_value});
645 : }
646 :
647 : /// Create a new descriptor for the specified subprogram.
648 : /// See comments in DISubprogram* for descriptions of these fields.
649 : /// \param Scope Function scope.
650 : /// \param Name Function name.
651 : /// \param LinkageName Mangled function name.
652 : /// \param File File where this variable is defined.
653 : /// \param LineNo Line number.
654 : /// \param Ty Function type.
655 : /// \param isLocalToUnit True if this function is not externally visible.
656 : /// \param isDefinition True if this is a function definition.
657 : /// \param ScopeLine Set to the beginning of the scope this starts
658 : /// \param Flags e.g. is this function prototyped or not.
659 : /// These flags are used to emit dwarf attributes.
660 : /// \param isOptimized True if optimization is ON.
661 : /// \param TParams Function template parameters.
662 : /// \param ThrownTypes Exception types this function may throw.
663 : DISubprogram *createFunction(
664 : DIScope *Scope, StringRef Name, StringRef LinkageName, DIFile *File,
665 : unsigned LineNo, DISubroutineType *Ty, bool isLocalToUnit,
666 : bool isDefinition, unsigned ScopeLine,
667 : DINode::DIFlags Flags = DINode::FlagZero, bool isOptimized = false,
668 : DITemplateParameterArray TParams = nullptr,
669 : DISubprogram *Decl = nullptr, DITypeArray ThrownTypes = nullptr);
670 :
671 : /// Identical to createFunction,
672 : /// except that the resulting DbgNode is meant to be RAUWed.
673 : DISubprogram *createTempFunctionFwdDecl(
674 : DIScope *Scope, StringRef Name, StringRef LinkageName, DIFile *File,
675 : unsigned LineNo, DISubroutineType *Ty, bool isLocalToUnit,
676 : bool isDefinition, unsigned ScopeLine,
677 : DINode::DIFlags Flags = DINode::FlagZero, bool isOptimized = false,
678 : DITemplateParameterArray TParams = nullptr,
679 : DISubprogram *Decl = nullptr, DITypeArray ThrownTypes = nullptr);
680 :
681 : /// Create a new descriptor for the specified C++ method.
682 : /// See comments in \a DISubprogram* for descriptions of these fields.
683 : /// \param Scope Function scope.
684 : /// \param Name Function name.
685 : /// \param LinkageName Mangled function name.
686 : /// \param File File where this variable is defined.
687 : /// \param LineNo Line number.
688 : /// \param Ty Function type.
689 : /// \param isLocalToUnit True if this function is not externally visible..
690 : /// \param isDefinition True if this is a function definition.
691 : /// \param Virtuality Attributes describing virtualness. e.g. pure
692 : /// virtual function.
693 : /// \param VTableIndex Index no of this method in virtual table, or -1u if
694 : /// unrepresentable.
695 : /// \param ThisAdjustment
696 : /// MS ABI-specific adjustment of 'this' that occurs
697 : /// in the prologue.
698 : /// \param VTableHolder Type that holds vtable.
699 : /// \param Flags e.g. is this function prototyped or not.
700 : /// This flags are used to emit dwarf attributes.
701 : /// \param isOptimized True if optimization is ON.
702 : /// \param TParams Function template parameters.
703 : /// \param ThrownTypes Exception types this function may throw.
704 : DISubprogram *createMethod(
705 : DIScope *Scope, StringRef Name, StringRef LinkageName, DIFile *File,
706 : unsigned LineNo, DISubroutineType *Ty, bool isLocalToUnit,
707 : bool isDefinition, unsigned Virtuality = 0, unsigned VTableIndex = 0,
708 : int ThisAdjustment = 0, DIType *VTableHolder = nullptr,
709 : DINode::DIFlags Flags = DINode::FlagZero, bool isOptimized = false,
710 : DITemplateParameterArray TParams = nullptr,
711 : DITypeArray ThrownTypes = nullptr);
712 :
713 : /// This creates new descriptor for a namespace with the specified
714 : /// parent scope.
715 : /// \param Scope Namespace scope
716 : /// \param Name Name of this namespace
717 : /// \param ExportSymbols True for C++ inline namespaces.
718 : DINamespace *createNameSpace(DIScope *Scope, StringRef Name,
719 : bool ExportSymbols);
720 :
721 : /// This creates new descriptor for a module with the specified
722 : /// parent scope.
723 : /// \param Scope Parent scope
724 : /// \param Name Name of this module
725 : /// \param ConfigurationMacros
726 : /// A space-separated shell-quoted list of -D macro
727 : /// definitions as they would appear on a command line.
728 : /// \param IncludePath The path to the module map file.
729 : /// \param ISysRoot The clang system root (value of -isysroot).
730 : DIModule *createModule(DIScope *Scope, StringRef Name,
731 : StringRef ConfigurationMacros,
732 : StringRef IncludePath,
733 : StringRef ISysRoot);
734 :
735 : /// This creates a descriptor for a lexical block with a new file
736 : /// attached. This merely extends the existing
737 : /// lexical block as it crosses a file.
738 : /// \param Scope Lexical block.
739 : /// \param File Source file.
740 : /// \param Discriminator DWARF path discriminator value.
741 : DILexicalBlockFile *createLexicalBlockFile(DIScope *Scope, DIFile *File,
742 : unsigned Discriminator = 0);
743 :
744 : /// This creates a descriptor for a lexical block with the
745 : /// specified parent context.
746 : /// \param Scope Parent lexical scope.
747 : /// \param File Source file.
748 : /// \param Line Line number.
749 : /// \param Col Column number.
750 : DILexicalBlock *createLexicalBlock(DIScope *Scope, DIFile *File,
751 : unsigned Line, unsigned Col);
752 :
753 : /// Create a descriptor for an imported module.
754 : /// \param Context The scope this module is imported into
755 : /// \param NS The namespace being imported here.
756 : /// \param File File where the declaration is located.
757 : /// \param Line Line number of the declaration.
758 : DIImportedEntity *createImportedModule(DIScope *Context, DINamespace *NS,
759 : DIFile *File, unsigned Line);
760 :
761 : /// Create a descriptor for an imported module.
762 : /// \param Context The scope this module is imported into.
763 : /// \param NS An aliased namespace.
764 : /// \param File File where the declaration is located.
765 : /// \param Line Line number of the declaration.
766 : DIImportedEntity *createImportedModule(DIScope *Context,
767 : DIImportedEntity *NS, DIFile *File,
768 : unsigned Line);
769 :
770 : /// Create a descriptor for an imported module.
771 : /// \param Context The scope this module is imported into.
772 : /// \param M The module being imported here
773 : /// \param File File where the declaration is located.
774 : /// \param Line Line number of the declaration.
775 : DIImportedEntity *createImportedModule(DIScope *Context, DIModule *M,
776 : DIFile *File, unsigned Line);
777 :
778 : /// Create a descriptor for an imported function.
779 : /// \param Context The scope this module is imported into.
780 : /// \param Decl The declaration (or definition) of a function, type, or
781 : /// variable.
782 : /// \param File File where the declaration is located.
783 : /// \param Line Line number of the declaration.
784 : DIImportedEntity *createImportedDeclaration(DIScope *Context, DINode *Decl,
785 : DIFile *File, unsigned Line,
786 : StringRef Name = "");
787 :
788 : /// Insert a new llvm.dbg.declare intrinsic call.
789 : /// \param Storage llvm::Value of the variable
790 : /// \param VarInfo Variable's debug info descriptor.
791 : /// \param Expr A complex location expression.
792 : /// \param DL Debug info location.
793 : /// \param InsertAtEnd Location for the new intrinsic.
794 : Instruction *insertDeclare(llvm::Value *Storage, DILocalVariable *VarInfo,
795 : DIExpression *Expr, const DILocation *DL,
796 : BasicBlock *InsertAtEnd);
797 :
798 : /// Insert a new llvm.dbg.declare intrinsic call.
799 : /// \param Storage llvm::Value of the variable
800 : /// \param VarInfo Variable's debug info descriptor.
801 : /// \param Expr A complex location expression.
802 : /// \param DL Debug info location.
803 : /// \param InsertBefore Location for the new intrinsic.
804 : Instruction *insertDeclare(llvm::Value *Storage, DILocalVariable *VarInfo,
805 : DIExpression *Expr, const DILocation *DL,
806 : Instruction *InsertBefore);
807 :
808 : /// Insert a new llvm.dbg.label intrinsic call.
809 : /// \param LabelInfo Label's debug info descriptor.
810 : /// \param DL Debug info location.
811 : /// \param InsertBefore Location for the new intrinsic.
812 : Instruction *insertLabel(DILabel *LabelInfo, const DILocation *DL,
813 : Instruction *InsertBefore);
814 :
815 : /// Insert a new llvm.dbg.label intrinsic call.
816 : /// \param LabelInfo Label's debug info descriptor.
817 : /// \param DL Debug info location.
818 : /// \param InsertAtEnd Location for the new intrinsic.
819 : Instruction *insertLabel(DILabel *LabelInfo, const DILocation *DL,
820 : BasicBlock *InsertAtEnd);
821 :
822 : /// Insert a new llvm.dbg.value intrinsic call.
823 : /// \param Val llvm::Value of the variable
824 : /// \param VarInfo Variable's debug info descriptor.
825 : /// \param Expr A complex location expression.
826 : /// \param DL Debug info location.
827 : /// \param InsertAtEnd Location for the new intrinsic.
828 : Instruction *insertDbgValueIntrinsic(llvm::Value *Val,
829 : DILocalVariable *VarInfo,
830 : DIExpression *Expr,
831 : const DILocation *DL,
832 : BasicBlock *InsertAtEnd);
833 :
834 : /// Insert a new llvm.dbg.value intrinsic call.
835 : /// \param Val llvm::Value of the variable
836 : /// \param VarInfo Variable's debug info descriptor.
837 : /// \param Expr A complex location expression.
838 : /// \param DL Debug info location.
839 : /// \param InsertBefore Location for the new intrinsic.
840 : Instruction *insertDbgValueIntrinsic(llvm::Value *Val,
841 : DILocalVariable *VarInfo,
842 : DIExpression *Expr,
843 : const DILocation *DL,
844 : Instruction *InsertBefore);
845 :
846 : /// Replace the vtable holder in the given type.
847 : ///
848 : /// If this creates a self reference, it may orphan some unresolved cycles
849 : /// in the operands of \c T, so \a DIBuilder needs to track that.
850 : void replaceVTableHolder(DICompositeType *&T,
851 : DIType *VTableHolder);
852 :
853 : /// Replace arrays on a composite type.
854 : ///
855 : /// If \c T is resolved, but the arrays aren't -- which can happen if \c T
856 : /// has a self-reference -- \a DIBuilder needs to track the array to
857 : /// resolve cycles.
858 : void replaceArrays(DICompositeType *&T, DINodeArray Elements,
859 : DINodeArray TParams = DINodeArray());
860 :
861 : /// Replace a temporary node.
862 : ///
863 : /// Call \a MDNode::replaceAllUsesWith() on \c N, replacing it with \c
864 : /// Replacement.
865 : ///
866 : /// If \c Replacement is the same as \c N.get(), instead call \a
867 : /// MDNode::replaceWithUniqued(). In this case, the uniqued node could
868 : /// have a different address, so we return the final address.
869 : template <class NodeTy>
870 0 : NodeTy *replaceTemporary(TempMDNode &&N, NodeTy *Replacement) {
871 0 : if (N.get() == Replacement)
872 : return cast<NodeTy>(MDNode::replaceWithUniqued(std::move(N)));
873 :
874 : N->replaceAllUsesWith(Replacement);
875 : return Replacement;
876 : }
877 : };
878 :
879 : // Create wrappers for C Binding types (see CBindingWrapping.h).
880 : DEFINE_ISA_CONVERSION_FUNCTIONS(DIBuilder, LLVMDIBuilderRef)
881 :
882 : } // end namespace llvm
883 :
884 : #endif // LLVM_IR_DIBUILDER_H
|
