1 //===- DIBuilder.h - Debug Information Builder ------------------*- 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 defines a DIBuilder that is useful for creating debugging 10 // information entries in LLVM IR form. 11 // 12 //===----------------------------------------------------------------------===// 13 14 #ifndef LLVM_IR_DIBUILDER_H 15 #define LLVM_IR_DIBUILDER_H 16 17 #include "llvm/ADT/ArrayRef.h" 18 #include "llvm/ADT/DenseMap.h" 19 #include "llvm/ADT/MapVector.h" 20 #include "llvm/ADT/Optional.h" 21 #include "llvm/ADT/SetVector.h" 22 #include "llvm/ADT/SmallVector.h" 23 #include "llvm/ADT/StringRef.h" 24 #include "llvm/IR/DebugInfo.h" 25 #include "llvm/IR/DebugInfoMetadata.h" 26 #include "llvm/IR/TrackingMDRef.h" 27 #include "llvm/Support/Casting.h" 28 #include <algorithm> 29 #include <cstdint> 30 31 namespace llvm { 32 33 class BasicBlock; 34 class Constant; 35 class Function; 36 class Instruction; 37 class LLVMContext; 38 class Module; 39 class Value; 40 41 class DIBuilder { 42 Module &M; 43 LLVMContext &VMContext; 44 45 DICompileUnit *CUNode; ///< The one compile unit created by this DIBuiler. 46 Function *DeclareFn; ///< llvm.dbg.declare 47 Function *ValueFn; ///< llvm.dbg.value 48 Function *LabelFn; ///< llvm.dbg.label 49 50 SmallVector<Metadata *, 4> AllEnumTypes; 51 /// Track the RetainTypes, since they can be updated later on. 52 SmallVector<TrackingMDNodeRef, 4> AllRetainTypes; 53 SmallVector<Metadata *, 4> AllSubprograms; 54 SmallVector<Metadata *, 4> AllGVs; 55 SmallVector<TrackingMDNodeRef, 4> AllImportedModules; 56 /// Map Macro parent (which can be DIMacroFile or nullptr) to a list of 57 /// Metadata all of type DIMacroNode. 58 /// DIMacroNode's with nullptr parent are DICompileUnit direct children. 59 MapVector<MDNode *, SetVector<Metadata *>> AllMacrosPerParent; 60 61 /// Track nodes that may be unresolved. 62 SmallVector<TrackingMDNodeRef, 4> UnresolvedNodes; 63 bool AllowUnresolvedNodes; 64 65 /// Each subprogram's preserved local variables. 66 /// 67 /// Do not use a std::vector. Some versions of libc++ apparently copy 68 /// instead of move on grow operations, and TrackingMDRef is expensive to 69 /// copy. 70 DenseMap<MDNode *, SmallVector<TrackingMDNodeRef, 1>> PreservedVariables; 71 72 /// Each subprogram's preserved labels. 73 DenseMap<MDNode *, SmallVector<TrackingMDNodeRef, 1>> PreservedLabels; 74 75 /// Create a temporary. 76 /// 77 /// Create an \a temporary node and track it in \a UnresolvedNodes. 78 void trackIfUnresolved(MDNode *N); 79 80 /// Internal helper for insertDeclare. 81 Instruction *insertDeclare(llvm::Value *Storage, DILocalVariable *VarInfo, 82 DIExpression *Expr, const DILocation *DL, 83 BasicBlock *InsertBB, Instruction *InsertBefore); 84 85 /// Internal helper for insertLabel. 86 Instruction *insertLabel(DILabel *LabelInfo, const DILocation *DL, 87 BasicBlock *InsertBB, Instruction *InsertBefore); 88 89 /// Internal helper for insertDbgValueIntrinsic. 90 Instruction * 91 insertDbgValueIntrinsic(llvm::Value *Val, DILocalVariable *VarInfo, 92 DIExpression *Expr, const DILocation *DL, 93 BasicBlock *InsertBB, Instruction *InsertBefore); 94 95 public: 96 /// Construct a builder for a module. 97 /// 98 /// If \c AllowUnresolved, collect unresolved nodes attached to the module 99 /// in order to resolve cycles during \a finalize(). 100 /// 101 /// If \p CU is given a value other than nullptr, then set \p CUNode to CU. 102 explicit DIBuilder(Module &M, bool AllowUnresolved = true, 103 DICompileUnit *CU = nullptr); 104 DIBuilder(const DIBuilder &) = delete; 105 DIBuilder &operator=(const DIBuilder &) = delete; 106 107 /// Construct any deferred debug info descriptors. 108 void finalize(); 109 110 /// Finalize a specific subprogram - no new variables may be added to this 111 /// subprogram afterwards. 112 void finalizeSubprogram(DISubprogram *SP); 113 114 /// A CompileUnit provides an anchor for all debugging 115 /// information generated during this instance of compilation. 116 /// \param Lang Source programming language, eg. dwarf::DW_LANG_C99 117 /// \param File File info. 118 /// \param Producer Identify the producer of debugging information 119 /// and code. Usually this is a compiler 120 /// version string. 121 /// \param isOptimized A boolean flag which indicates whether optimization 122 /// is enabled or not. 123 /// \param Flags This string lists command line options. This 124 /// string is directly embedded in debug info 125 /// output which may be used by a tool 126 /// analyzing generated debugging information. 127 /// \param RV This indicates runtime version for languages like 128 /// Objective-C. 129 /// \param SplitName The name of the file that we'll split debug info 130 /// out into. 131 /// \param Kind The kind of debug information to generate. 132 /// \param DWOId The DWOId if this is a split skeleton compile unit. 133 /// \param SplitDebugInlining Whether to emit inline debug info. 134 /// \param DebugInfoForProfiling Whether to emit extra debug info for 135 /// profile collection. 136 /// \param NameTableKind Whether to emit .debug_gnu_pubnames, 137 /// .debug_pubnames, or no pubnames at all. 138 DICompileUnit * 139 createCompileUnit(unsigned Lang, DIFile *File, StringRef Producer, 140 bool isOptimized, StringRef Flags, unsigned RV, 141 StringRef SplitName = StringRef(), 142 DICompileUnit::DebugEmissionKind Kind = 143 DICompileUnit::DebugEmissionKind::FullDebug, 144 uint64_t DWOId = 0, bool SplitDebugInlining = true, 145 bool DebugInfoForProfiling = false, 146 DICompileUnit::DebugNameTableKind NameTableKind = 147 DICompileUnit::DebugNameTableKind::Default, 148 bool RangesBaseAddress = false); 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 /// \param AlignInBits Alignment. (optional) 241 DIDerivedType *createTypedef(DIType *Ty, StringRef Name, DIFile *File, 242 unsigned LineNo, DIScope *Context, 243 uint32_t AlignInBits = 0); 244 245 /// Create debugging information entry for a 'friend'. 246 DIDerivedType *createFriend(DIType *Ty, DIType *FriendTy); 247 248 /// Create debugging information entry to establish 249 /// inheritance relationship between two types. 250 /// \param Ty Original type. 251 /// \param BaseTy Base type. Ty is inherits from base. 252 /// \param BaseOffset Base offset. 253 /// \param VBPtrOffset Virtual base pointer offset. 254 /// \param Flags Flags to describe inheritance attribute, 255 /// e.g. private 256 DIDerivedType *createInheritance(DIType *Ty, DIType *BaseTy, 257 uint64_t BaseOffset, uint32_t VBPtrOffset, 258 DINode::DIFlags Flags); 259 260 /// Create debugging information entry for a member. 261 /// \param Scope Member scope. 262 /// \param Name Member name. 263 /// \param File File where this member is defined. 264 /// \param LineNo Line number. 265 /// \param SizeInBits Member size. 266 /// \param AlignInBits Member alignment. 267 /// \param OffsetInBits Member offset. 268 /// \param Flags Flags to encode member attribute, e.g. private 269 /// \param Ty Parent type. 270 DIDerivedType *createMemberType(DIScope *Scope, StringRef Name, 271 DIFile *File, unsigned LineNo, 272 uint64_t SizeInBits, 273 uint32_t AlignInBits, 274 uint64_t OffsetInBits, 275 DINode::DIFlags Flags, DIType *Ty); 276 277 /// Create debugging information entry for a variant. A variant 278 /// normally should be a member of a variant part. 279 /// \param Scope Member scope. 280 /// \param Name Member name. 281 /// \param File File where this member is defined. 282 /// \param LineNo Line number. 283 /// \param SizeInBits Member size. 284 /// \param AlignInBits Member alignment. 285 /// \param OffsetInBits Member offset. 286 /// \param Flags Flags to encode member attribute, e.g. private 287 /// \param Discriminant The discriminant for this branch; null for 288 /// the default branch 289 /// \param Ty Parent type. 290 DIDerivedType *createVariantMemberType(DIScope *Scope, StringRef Name, 291 DIFile *File, unsigned LineNo, 292 uint64_t SizeInBits, 293 uint32_t AlignInBits, 294 uint64_t OffsetInBits, 295 Constant *Discriminant, 296 DINode::DIFlags Flags, DIType *Ty); 297 298 /// Create debugging information entry for a bit field member. 299 /// \param Scope Member scope. 300 /// \param Name Member name. 301 /// \param File File where this member is defined. 302 /// \param LineNo Line number. 303 /// \param SizeInBits Member size. 304 /// \param OffsetInBits Member offset. 305 /// \param StorageOffsetInBits Member storage offset. 306 /// \param Flags Flags to encode member attribute. 307 /// \param Ty Parent type. 308 DIDerivedType *createBitFieldMemberType( 309 DIScope *Scope, StringRef Name, DIFile *File, unsigned LineNo, 310 uint64_t SizeInBits, uint64_t OffsetInBits, 311 uint64_t StorageOffsetInBits, DINode::DIFlags Flags, DIType *Ty); 312 313 /// Create debugging information entry for a 314 /// C++ static data member. 315 /// \param Scope Member scope. 316 /// \param Name Member name. 317 /// \param File File where this member is declared. 318 /// \param LineNo Line number. 319 /// \param Ty Type of the static member. 320 /// \param Flags Flags to encode member attribute, e.g. private. 321 /// \param Val Const initializer of the member. 322 /// \param AlignInBits Member alignment. 323 DIDerivedType *createStaticMemberType(DIScope *Scope, StringRef Name, 324 DIFile *File, unsigned LineNo, 325 DIType *Ty, DINode::DIFlags Flags, 326 Constant *Val, 327 uint32_t AlignInBits = 0); 328 329 /// Create debugging information entry for Objective-C 330 /// instance variable. 331 /// \param Name Member name. 332 /// \param File File where this member is defined. 333 /// \param LineNo Line number. 334 /// \param SizeInBits Member size. 335 /// \param AlignInBits Member alignment. 336 /// \param OffsetInBits Member offset. 337 /// \param Flags Flags to encode member attribute, e.g. private 338 /// \param Ty Parent type. 339 /// \param PropertyNode Property associated with this ivar. 340 DIDerivedType *createObjCIVar(StringRef Name, DIFile *File, unsigned LineNo, 341 uint64_t SizeInBits, uint32_t AlignInBits, 342 uint64_t OffsetInBits, DINode::DIFlags Flags, 343 DIType *Ty, MDNode *PropertyNode); 344 345 /// Create debugging information entry for Objective-C 346 /// property. 347 /// \param Name Property name. 348 /// \param File File where this property is defined. 349 /// \param LineNumber Line number. 350 /// \param GetterName Name of the Objective C property getter selector. 351 /// \param SetterName Name of the Objective C property setter selector. 352 /// \param PropertyAttributes Objective C property attributes. 353 /// \param Ty Type. 354 DIObjCProperty *createObjCProperty(StringRef Name, DIFile *File, 355 unsigned LineNumber, 356 StringRef GetterName, 357 StringRef SetterName, 358 unsigned PropertyAttributes, DIType *Ty); 359 360 /// Create debugging information entry for a class. 361 /// \param Scope Scope in which this class is defined. 362 /// \param Name class name. 363 /// \param File File where this member is defined. 364 /// \param LineNumber Line number. 365 /// \param SizeInBits Member size. 366 /// \param AlignInBits Member alignment. 367 /// \param OffsetInBits Member offset. 368 /// \param Flags Flags to encode member attribute, e.g. private 369 /// \param Elements class members. 370 /// \param VTableHolder Debug info of the base class that contains vtable 371 /// for this type. This is used in 372 /// DW_AT_containing_type. See DWARF documentation 373 /// for more info. 374 /// \param TemplateParms Template type parameters. 375 /// \param UniqueIdentifier A unique identifier for the class. 376 DICompositeType *createClassType( 377 DIScope *Scope, StringRef Name, DIFile *File, unsigned LineNumber, 378 uint64_t SizeInBits, uint32_t AlignInBits, uint64_t OffsetInBits, 379 DINode::DIFlags Flags, DIType *DerivedFrom, DINodeArray Elements, 380 DIType *VTableHolder = nullptr, MDNode *TemplateParms = nullptr, 381 StringRef UniqueIdentifier = ""); 382 383 /// Create debugging information entry for a struct. 384 /// \param Scope Scope in which this struct is defined. 385 /// \param Name Struct name. 386 /// \param File File where this member is defined. 387 /// \param LineNumber Line number. 388 /// \param SizeInBits Member size. 389 /// \param AlignInBits Member alignment. 390 /// \param Flags Flags to encode member attribute, e.g. private 391 /// \param Elements Struct elements. 392 /// \param RunTimeLang Optional parameter, Objective-C runtime version. 393 /// \param UniqueIdentifier A unique identifier for the struct. 394 DICompositeType *createStructType( 395 DIScope *Scope, StringRef Name, DIFile *File, unsigned LineNumber, 396 uint64_t SizeInBits, uint32_t AlignInBits, DINode::DIFlags Flags, 397 DIType *DerivedFrom, DINodeArray Elements, unsigned RunTimeLang = 0, 398 DIType *VTableHolder = nullptr, StringRef UniqueIdentifier = ""); 399 400 /// Create debugging information entry for an union. 401 /// \param Scope Scope in which this union is defined. 402 /// \param Name Union name. 403 /// \param File File where this member is defined. 404 /// \param LineNumber Line number. 405 /// \param SizeInBits Member size. 406 /// \param AlignInBits Member alignment. 407 /// \param Flags Flags to encode member attribute, e.g. private 408 /// \param Elements Union elements. 409 /// \param RunTimeLang Optional parameter, Objective-C runtime version. 410 /// \param UniqueIdentifier A unique identifier for the union. 411 DICompositeType *createUnionType(DIScope *Scope, StringRef Name, 412 DIFile *File, unsigned LineNumber, 413 uint64_t SizeInBits, uint32_t AlignInBits, 414 DINode::DIFlags Flags, 415 DINodeArray Elements, 416 unsigned RunTimeLang = 0, 417 StringRef UniqueIdentifier = ""); 418 419 /// Create debugging information entry for a variant part. A 420 /// variant part normally has a discriminator (though this is not 421 /// required) and a number of variant children. 422 /// \param Scope Scope in which this union is defined. 423 /// \param Name Union name. 424 /// \param File File where this member is defined. 425 /// \param LineNumber Line number. 426 /// \param SizeInBits Member size. 427 /// \param AlignInBits Member alignment. 428 /// \param Flags Flags to encode member attribute, e.g. private 429 /// \param Discriminator Discriminant member 430 /// \param Elements Variant elements. 431 /// \param UniqueIdentifier A unique identifier for the union. 432 DICompositeType *createVariantPart(DIScope *Scope, StringRef Name, 433 DIFile *File, unsigned LineNumber, 434 uint64_t SizeInBits, uint32_t AlignInBits, 435 DINode::DIFlags Flags, 436 DIDerivedType *Discriminator, 437 DINodeArray Elements, 438 StringRef UniqueIdentifier = ""); 439 440 /// Create debugging information for template 441 /// type parameter. 442 /// \param Scope Scope in which this type is defined. 443 /// \param Name Type parameter name. 444 /// \param Ty Parameter type. 445 DITemplateTypeParameter * 446 createTemplateTypeParameter(DIScope *Scope, StringRef Name, DIType *Ty); 447 448 /// Create debugging information for template 449 /// value parameter. 450 /// \param Scope Scope in which this type is defined. 451 /// \param Name Value parameter name. 452 /// \param Ty Parameter type. 453 /// \param Val Constant parameter value. 454 DITemplateValueParameter *createTemplateValueParameter(DIScope *Scope, 455 StringRef Name, 456 DIType *Ty, 457 Constant *Val); 458 459 /// Create debugging information for a template template parameter. 460 /// \param Scope Scope in which this type is defined. 461 /// \param Name Value parameter name. 462 /// \param Ty Parameter type. 463 /// \param Val The fully qualified name of the template. 464 DITemplateValueParameter *createTemplateTemplateParameter(DIScope *Scope, 465 StringRef Name, 466 DIType *Ty, 467 StringRef Val); 468 469 /// Create debugging information for a template parameter pack. 470 /// \param Scope Scope in which this type is defined. 471 /// \param Name Value parameter name. 472 /// \param Ty Parameter type. 473 /// \param Val An array of types in the pack. 474 DITemplateValueParameter *createTemplateParameterPack(DIScope *Scope, 475 StringRef Name, 476 DIType *Ty, 477 DINodeArray Val); 478 479 /// Create debugging information entry for an array. 480 /// \param Size Array size. 481 /// \param AlignInBits Alignment. 482 /// \param Ty Element type. 483 /// \param Subscripts Subscripts. 484 DICompositeType *createArrayType(uint64_t Size, uint32_t AlignInBits, 485 DIType *Ty, DINodeArray Subscripts); 486 487 /// Create debugging information entry for a vector type. 488 /// \param Size Array size. 489 /// \param AlignInBits Alignment. 490 /// \param Ty Element type. 491 /// \param Subscripts Subscripts. 492 DICompositeType *createVectorType(uint64_t Size, uint32_t AlignInBits, 493 DIType *Ty, DINodeArray Subscripts); 494 495 /// Create debugging information entry for an 496 /// enumeration. 497 /// \param Scope Scope in which this enumeration is defined. 498 /// \param Name Union name. 499 /// \param File File where this member is defined. 500 /// \param LineNumber Line number. 501 /// \param SizeInBits Member size. 502 /// \param AlignInBits Member alignment. 503 /// \param Elements Enumeration elements. 504 /// \param UnderlyingType Underlying type of a C++11/ObjC fixed enum. 505 /// \param UniqueIdentifier A unique identifier for the enum. 506 /// \param IsScoped Boolean flag indicate if this is C++11/ObjC 'enum class'. 507 DICompositeType *createEnumerationType( 508 DIScope *Scope, StringRef Name, DIFile *File, unsigned LineNumber, 509 uint64_t SizeInBits, uint32_t AlignInBits, DINodeArray Elements, 510 DIType *UnderlyingType, StringRef UniqueIdentifier = "", bool IsScoped = false); 511 512 /// Create subroutine type. 513 /// \param ParameterTypes An array of subroutine parameter types. This 514 /// includes return type at 0th index. 515 /// \param Flags E.g.: LValueReference. 516 /// These flags are used to emit dwarf attributes. 517 /// \param CC Calling convention, e.g. dwarf::DW_CC_normal 518 DISubroutineType * 519 createSubroutineType(DITypeRefArray ParameterTypes, 520 DINode::DIFlags Flags = DINode::FlagZero, 521 unsigned CC = 0); 522 523 /// Create a distinct clone of \p SP with FlagArtificial set. 524 static DISubprogram *createArtificialSubprogram(DISubprogram *SP); 525 526 /// Create a uniqued clone of \p Ty with FlagArtificial set. 527 static DIType *createArtificialType(DIType *Ty); 528 529 /// Create a uniqued clone of \p Ty with FlagObjectPointer and 530 /// FlagArtificial set. 531 static DIType *createObjectPointerType(DIType *Ty); 532 533 /// Create a permanent forward-declared type. 534 DICompositeType *createForwardDecl(unsigned Tag, StringRef Name, 535 DIScope *Scope, DIFile *F, unsigned Line, 536 unsigned RuntimeLang = 0, 537 uint64_t SizeInBits = 0, 538 uint32_t AlignInBits = 0, 539 StringRef UniqueIdentifier = ""); 540 541 /// Create a temporary forward-declared type. 542 DICompositeType *createReplaceableCompositeType( 543 unsigned Tag, StringRef Name, DIScope *Scope, DIFile *F, unsigned Line, 544 unsigned RuntimeLang = 0, uint64_t SizeInBits = 0, 545 uint32_t AlignInBits = 0, DINode::DIFlags Flags = DINode::FlagFwdDecl, 546 StringRef UniqueIdentifier = ""); 547 548 /// Retain DIScope* in a module even if it is not referenced 549 /// through debug info anchors. 550 void retainType(DIScope *T); 551 552 /// Create unspecified parameter type 553 /// for a subroutine type. 554 DIBasicType *createUnspecifiedParameter(); 555 556 /// Get a DINodeArray, create one if required. 557 DINodeArray getOrCreateArray(ArrayRef<Metadata *> Elements); 558 559 /// Get a DIMacroNodeArray, create one if required. 560 DIMacroNodeArray getOrCreateMacroArray(ArrayRef<Metadata *> Elements); 561 562 /// Get a DITypeRefArray, create one if required. 563 DITypeRefArray getOrCreateTypeArray(ArrayRef<Metadata *> Elements); 564 565 /// Create a descriptor for a value range. This 566 /// implicitly uniques the values returned. 567 DISubrange *getOrCreateSubrange(int64_t Lo, int64_t Count); 568 DISubrange *getOrCreateSubrange(int64_t Lo, Metadata *CountNode); 569 570 /// Create a new descriptor for the specified variable. 571 /// \param Context Variable scope. 572 /// \param Name Name of the variable. 573 /// \param LinkageName Mangled name of the variable. 574 /// \param File File where this variable is defined. 575 /// \param LineNo Line number. 576 /// \param Ty Variable Type. 577 /// \param IsLocalToUnit Boolean flag indicate whether this variable is 578 /// externally visible or not. 579 /// \param Expr The location of the global relative to the attached 580 /// GlobalVariable. 581 /// \param Decl Reference to the corresponding declaration. 582 /// \param AlignInBits Variable alignment(or 0 if no alignment attr was 583 /// specified) 584 DIGlobalVariableExpression *createGlobalVariableExpression( 585 DIScope *Context, StringRef Name, StringRef LinkageName, DIFile *File, 586 unsigned LineNo, DIType *Ty, bool IsLocalToUnit, bool isDefined = true, 587 DIExpression *Expr = nullptr, MDNode *Decl = nullptr, 588 MDTuple *TemplateParams = nullptr, uint32_t AlignInBits = 0); 589 590 /// Identical to createGlobalVariable 591 /// except that the resulting DbgNode is temporary and meant to be RAUWed. 592 DIGlobalVariable *createTempGlobalVariableFwdDecl( 593 DIScope *Context, StringRef Name, StringRef LinkageName, DIFile *File, 594 unsigned LineNo, DIType *Ty, bool IsLocalToUnit, MDNode *Decl = nullptr, 595 MDTuple *TemplateParams= nullptr, uint32_t AlignInBits = 0); 596 597 /// Create a new descriptor for an auto variable. This is a local variable 598 /// that is not a subprogram parameter. 599 /// 600 /// \c Scope must be a \a DILocalScope, and thus its scope chain eventually 601 /// leads to a \a DISubprogram. 602 /// 603 /// If \c AlwaysPreserve, this variable will be referenced from its 604 /// containing subprogram, and will survive some optimizations. 605 DILocalVariable * 606 createAutoVariable(DIScope *Scope, StringRef Name, DIFile *File, 607 unsigned LineNo, DIType *Ty, bool AlwaysPreserve = false, 608 DINode::DIFlags Flags = DINode::FlagZero, 609 uint32_t AlignInBits = 0); 610 611 /// Create a new descriptor for an label. 612 /// 613 /// \c Scope must be a \a DILocalScope, and thus its scope chain eventually 614 /// leads to a \a DISubprogram. 615 DILabel * 616 createLabel(DIScope *Scope, StringRef Name, DIFile *File, unsigned LineNo, 617 bool AlwaysPreserve = false); 618 619 /// Create a new descriptor for a parameter variable. 620 /// 621 /// \c Scope must be a \a DILocalScope, and thus its scope chain eventually 622 /// leads to a \a DISubprogram. 623 /// 624 /// \c ArgNo is the index (starting from \c 1) of this variable in the 625 /// subprogram parameters. \c ArgNo should not conflict with other 626 /// parameters of the same subprogram. 627 /// 628 /// If \c AlwaysPreserve, this variable will be referenced from its 629 /// containing subprogram, and will survive some optimizations. 630 DILocalVariable * 631 createParameterVariable(DIScope *Scope, StringRef Name, unsigned ArgNo, 632 DIFile *File, unsigned LineNo, DIType *Ty, 633 bool AlwaysPreserve = false, 634 DINode::DIFlags Flags = DINode::FlagZero); 635 636 /// Create a new descriptor for the specified 637 /// variable which has a complex address expression for its address. 638 /// \param Addr An array of complex address operations. 639 DIExpression *createExpression(ArrayRef<uint64_t> Addr = None); 640 DIExpression *createExpression(ArrayRef<int64_t> Addr); 641 642 /// Create an expression for a variable that does not have an address, but 643 /// does have a constant value. 644 DIExpression *createConstantValueExpression(uint64_t Val) { 645 return DIExpression::get( 646 VMContext, {dwarf::DW_OP_constu, Val, dwarf::DW_OP_stack_value}); 647 } 648 649 /// Create a new descriptor for the specified subprogram. 650 /// See comments in DISubprogram* for descriptions of these fields. 651 /// \param Scope Function scope. 652 /// \param Name Function name. 653 /// \param LinkageName Mangled function name. 654 /// \param File File where this variable is defined. 655 /// \param LineNo Line number. 656 /// \param Ty Function type. 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 SPFlags Additional flags specific to subprograms. 661 /// \param TParams Function template parameters. 662 /// \param ThrownTypes Exception types this function may throw. 663 DISubprogram * 664 createFunction(DIScope *Scope, StringRef Name, StringRef LinkageName, 665 DIFile *File, unsigned LineNo, DISubroutineType *Ty, 666 unsigned ScopeLine, DINode::DIFlags Flags = DINode::FlagZero, 667 DISubprogram::DISPFlags SPFlags = DISubprogram::SPFlagZero, 668 DITemplateParameterArray TParams = nullptr, 669 DISubprogram *Decl = nullptr, 670 DITypeArray ThrownTypes = nullptr); 671 672 /// Identical to createFunction, 673 /// except that the resulting DbgNode is meant to be RAUWed. 674 DISubprogram *createTempFunctionFwdDecl( 675 DIScope *Scope, StringRef Name, StringRef LinkageName, DIFile *File, 676 unsigned LineNo, DISubroutineType *Ty, unsigned ScopeLine, 677 DINode::DIFlags Flags = DINode::FlagZero, 678 DISubprogram::DISPFlags SPFlags = DISubprogram::SPFlagZero, 679 DITemplateParameterArray TParams = nullptr, 680 DISubprogram *Decl = nullptr, DITypeArray ThrownTypes = nullptr); 681 682 /// Create a new descriptor for the specified C++ method. 683 /// See comments in \a DISubprogram* for descriptions of these fields. 684 /// \param Scope Function scope. 685 /// \param Name Function name. 686 /// \param LinkageName Mangled function name. 687 /// \param File File where this variable is defined. 688 /// \param LineNo Line number. 689 /// \param Ty Function type. 690 /// \param VTableIndex Index no of this method in virtual table, or -1u if 691 /// unrepresentable. 692 /// \param ThisAdjustment 693 /// MS ABI-specific adjustment of 'this' that occurs 694 /// in the prologue. 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 SPFlags Additional flags specific to subprograms. 699 /// \param TParams Function template parameters. 700 /// \param ThrownTypes Exception types this function may throw. 701 DISubprogram * 702 createMethod(DIScope *Scope, StringRef Name, StringRef LinkageName, 703 DIFile *File, unsigned LineNo, DISubroutineType *Ty, 704 unsigned VTableIndex = 0, int ThisAdjustment = 0, 705 DIType *VTableHolder = nullptr, 706 DINode::DIFlags Flags = DINode::FlagZero, 707 DISubprogram::DISPFlags SPFlags = DISubprogram::SPFlagZero, 708 DITemplateParameterArray TParams = nullptr, 709 DITypeArray ThrownTypes = nullptr); 710 711 /// Create common block entry for a Fortran common block. 712 /// \param Scope Scope of this common block. 713 /// \param decl Global variable declaration. 714 /// \param Name The name of this common block. 715 /// \param File The file this common block is defined. 716 /// \param LineNo Line number. 717 DICommonBlock *createCommonBlock(DIScope *Scope, DIGlobalVariable *decl, 718 StringRef Name, DIFile *File, 719 unsigned LineNo); 720 721 /// This creates new descriptor for a namespace with the specified 722 /// parent scope. 723 /// \param Scope Namespace scope 724 /// \param Name Name of this namespace 725 /// \param ExportSymbols True for C++ inline namespaces. 726 DINamespace *createNameSpace(DIScope *Scope, StringRef Name, 727 bool ExportSymbols); 728 729 /// This creates new descriptor for a module with the specified 730 /// parent scope. 731 /// \param Scope Parent scope 732 /// \param Name Name of this module 733 /// \param ConfigurationMacros 734 /// A space-separated shell-quoted list of -D macro 735 /// definitions as they would appear on a command line. 736 /// \param IncludePath The path to the module map file. 737 /// \param SysRoot The clang system root (value of -isysroot). 738 DIModule *createModule(DIScope *Scope, StringRef Name, 739 StringRef ConfigurationMacros, 740 StringRef IncludePath, 741 StringRef SysRoot); 742 743 /// This creates a descriptor for a lexical block with a new file 744 /// attached. This merely extends the existing 745 /// lexical block as it crosses a file. 746 /// \param Scope Lexical block. 747 /// \param File Source file. 748 /// \param Discriminator DWARF path discriminator value. 749 DILexicalBlockFile *createLexicalBlockFile(DIScope *Scope, DIFile *File, 750 unsigned Discriminator = 0); 751 752 /// This creates a descriptor for a lexical block with the 753 /// specified parent context. 754 /// \param Scope Parent lexical scope. 755 /// \param File Source file. 756 /// \param Line Line number. 757 /// \param Col Column number. 758 DILexicalBlock *createLexicalBlock(DIScope *Scope, DIFile *File, 759 unsigned Line, unsigned Col); 760 761 /// Create a descriptor for an imported module. 762 /// \param Context The scope this module is imported into 763 /// \param NS The namespace being imported here. 764 /// \param File File where the declaration is located. 765 /// \param Line Line number of the declaration. 766 DIImportedEntity *createImportedModule(DIScope *Context, DINamespace *NS, 767 DIFile *File, unsigned Line); 768 769 /// Create a descriptor for an imported module. 770 /// \param Context The scope this module is imported into. 771 /// \param NS An aliased namespace. 772 /// \param File File where the declaration is located. 773 /// \param Line Line number of the declaration. 774 DIImportedEntity *createImportedModule(DIScope *Context, 775 DIImportedEntity *NS, DIFile *File, 776 unsigned Line); 777 778 /// Create a descriptor for an imported module. 779 /// \param Context The scope this module is imported into. 780 /// \param M The module being imported here 781 /// \param File File where the declaration is located. 782 /// \param Line Line number of the declaration. 783 DIImportedEntity *createImportedModule(DIScope *Context, DIModule *M, 784 DIFile *File, unsigned Line); 785 786 /// Create a descriptor for an imported function. 787 /// \param Context The scope this module is imported into. 788 /// \param Decl The declaration (or definition) of a function, type, or 789 /// variable. 790 /// \param File File where the declaration is located. 791 /// \param Line Line number of the declaration. 792 DIImportedEntity *createImportedDeclaration(DIScope *Context, DINode *Decl, 793 DIFile *File, unsigned Line, 794 StringRef Name = ""); 795 796 /// Insert a new llvm.dbg.declare intrinsic call. 797 /// \param Storage llvm::Value of the variable 798 /// \param VarInfo Variable's debug info descriptor. 799 /// \param Expr A complex location expression. 800 /// \param DL Debug info location. 801 /// \param InsertAtEnd Location for the new intrinsic. 802 Instruction *insertDeclare(llvm::Value *Storage, DILocalVariable *VarInfo, 803 DIExpression *Expr, const DILocation *DL, 804 BasicBlock *InsertAtEnd); 805 806 /// Insert a new llvm.dbg.declare intrinsic call. 807 /// \param Storage llvm::Value of the variable 808 /// \param VarInfo Variable's debug info descriptor. 809 /// \param Expr A complex location expression. 810 /// \param DL Debug info location. 811 /// \param InsertBefore Location for the new intrinsic. 812 Instruction *insertDeclare(llvm::Value *Storage, DILocalVariable *VarInfo, 813 DIExpression *Expr, const DILocation *DL, 814 Instruction *InsertBefore); 815 816 /// Insert a new llvm.dbg.label intrinsic call. 817 /// \param LabelInfo Label's debug info descriptor. 818 /// \param DL Debug info location. 819 /// \param InsertBefore Location for the new intrinsic. 820 Instruction *insertLabel(DILabel *LabelInfo, const DILocation *DL, 821 Instruction *InsertBefore); 822 823 /// Insert a new llvm.dbg.label intrinsic call. 824 /// \param LabelInfo Label's debug info descriptor. 825 /// \param DL Debug info location. 826 /// \param InsertAtEnd Location for the new intrinsic. 827 Instruction *insertLabel(DILabel *LabelInfo, const DILocation *DL, 828 BasicBlock *InsertAtEnd); 829 830 /// Insert a new llvm.dbg.value intrinsic call. 831 /// \param Val llvm::Value of the variable 832 /// \param VarInfo Variable's debug info descriptor. 833 /// \param Expr A complex location expression. 834 /// \param DL Debug info location. 835 /// \param InsertAtEnd Location for the new intrinsic. 836 Instruction *insertDbgValueIntrinsic(llvm::Value *Val, 837 DILocalVariable *VarInfo, 838 DIExpression *Expr, 839 const DILocation *DL, 840 BasicBlock *InsertAtEnd); 841 842 /// Insert a new llvm.dbg.value intrinsic call. 843 /// \param Val llvm::Value of the variable 844 /// \param VarInfo Variable's debug info descriptor. 845 /// \param Expr A complex location expression. 846 /// \param DL Debug info location. 847 /// \param InsertBefore Location for the new intrinsic. 848 Instruction *insertDbgValueIntrinsic(llvm::Value *Val, 849 DILocalVariable *VarInfo, 850 DIExpression *Expr, 851 const DILocation *DL, 852 Instruction *InsertBefore); 853 854 /// Replace the vtable holder in the given type. 855 /// 856 /// If this creates a self reference, it may orphan some unresolved cycles 857 /// in the operands of \c T, so \a DIBuilder needs to track that. 858 void replaceVTableHolder(DICompositeType *&T, 859 DIType *VTableHolder); 860 861 /// Replace arrays on a composite type. 862 /// 863 /// If \c T is resolved, but the arrays aren't -- which can happen if \c T 864 /// has a self-reference -- \a DIBuilder needs to track the array to 865 /// resolve cycles. 866 void replaceArrays(DICompositeType *&T, DINodeArray Elements, 867 DINodeArray TParams = DINodeArray()); 868 869 /// Replace a temporary node. 870 /// 871 /// Call \a MDNode::replaceAllUsesWith() on \c N, replacing it with \c 872 /// Replacement. 873 /// 874 /// If \c Replacement is the same as \c N.get(), instead call \a 875 /// MDNode::replaceWithUniqued(). In this case, the uniqued node could 876 /// have a different address, so we return the final address. 877 template <class NodeTy> 878 NodeTy *replaceTemporary(TempMDNode &&N, NodeTy *Replacement) { 879 if (N.get() == Replacement) 880 return cast<NodeTy>(MDNode::replaceWithUniqued(std::move(N))); 881 882 N->replaceAllUsesWith(Replacement); 883 return Replacement; 884 } 885 }; 886 887 // Create wrappers for C Binding types (see CBindingWrapping.h). 888 DEFINE_ISA_CONVERSION_FUNCTIONS(DIBuilder, LLVMDIBuilderRef) 889 890 } // end namespace llvm 891 892 #endif // LLVM_IR_DIBUILDER_H 893