DIBuilder.h revision 6588abf377b7381274236e651462ec83052f6013
1//===--- llvm/Analysis/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_ANALYSIS_DIBUILDER_H 16#define LLVM_ANALYSIS_DIBUILDER_H 17 18#include "llvm/Support/DataTypes.h" 19#include "llvm/ADT/ArrayRef.h" 20#include "llvm/ADT/StringRef.h" 21 22namespace llvm { 23 class BasicBlock; 24 class Instruction; 25 class Function; 26 class Module; 27 class Value; 28 class LLVMContext; 29 class MDNode; 30 class StringRef; 31 class DIDescriptor; 32 class DIFile; 33 class DIEnumerator; 34 class DIType; 35 class DIArray; 36 class DIGlobalVariable; 37 class DINameSpace; 38 class DIVariable; 39 class DISubrange; 40 class DILexicalBlockFile; 41 class DILexicalBlock; 42 class DISubprogram; 43 class DITemplateTypeParameter; 44 class DITemplateValueParameter; 45 class DIObjCProperty; 46 47 class DIBuilder { 48 private: 49 Module &M; 50 LLVMContext & VMContext; 51 MDNode *TheCU; 52 53 MDNode *TempEnumTypes; 54 MDNode *TempRetainTypes; 55 MDNode *TempSubprograms; 56 MDNode *TempGVs; 57 58 Function *DeclareFn; // llvm.dbg.declare 59 Function *ValueFn; // llvm.dbg.value 60 61 SmallVector<Value *, 4> AllEnumTypes; 62 SmallVector<Value *, 4> AllRetainTypes; 63 SmallVector<Value *, 4> AllSubprograms; 64 SmallVector<Value *, 4> AllGVs; 65 66 DIBuilder(const DIBuilder &); // DO NOT IMPLEMENT 67 void operator=(const DIBuilder &); // DO NOT IMPLEMENT 68 69 public: 70 explicit DIBuilder(Module &M); 71 const MDNode *getCU() { return TheCU; } 72 enum ComplexAddrKind { OpPlus=1, OpDeref }; 73 74 /// finalize - Construct any deferred debug info descriptors. 75 void finalize(); 76 77 /// createCompileUnit - A CompileUnit provides an anchor for all debugging 78 /// information generated during this instance of compilation. 79 /// @param Lang Source programming language, eg. dwarf::DW_LANG_C99 80 /// @param File File name 81 /// @param Dir Directory 82 /// @param Producer String identify producer of debugging information. 83 /// Usuall this is a compiler version string. 84 /// @param isOptimized A boolean flag which indicates whether optimization 85 /// is ON or not. 86 /// @param Flags This string lists command line options. This string is 87 /// directly embedded in debug info output which may be used 88 /// by a tool analyzing generated debugging information. 89 /// @param RV This indicates runtime version for languages like 90 /// Objective-C. 91 void createCompileUnit(unsigned Lang, StringRef File, StringRef Dir, 92 StringRef Producer, 93 bool isOptimized, StringRef Flags, unsigned RV); 94 95 /// createFile - Create a file descriptor to hold debugging information 96 /// for a file. 97 DIFile createFile(StringRef Filename, StringRef Directory); 98 99 /// createEnumerator - Create a single enumerator value. 100 DIEnumerator createEnumerator(StringRef Name, uint64_t Val); 101 102 /// createNullPtrType - Create C++0x nullptr type. 103 DIType createNullPtrType(StringRef Name); 104 105 /// createBasicType - Create debugging information entry for a basic 106 /// type. 107 /// @param Name Type name. 108 /// @param SizeInBits Size of the type. 109 /// @param AlignInBits Type alignment. 110 /// @param Encoding DWARF encoding code, e.g. dwarf::DW_ATE_float. 111 DIType createBasicType(StringRef Name, uint64_t SizeInBits, 112 uint64_t AlignInBits, unsigned Encoding); 113 114 /// createQualifiedType - Create debugging information entry for a qualified 115 /// type, e.g. 'const int'. 116 /// @param Tag Tag identifing type, e.g. dwarf::TAG_volatile_type 117 /// @param FromTy Base Type. 118 DIType createQualifiedType(unsigned Tag, DIType FromTy); 119 120 /// createPointerType - Create debugging information entry for a pointer. 121 /// @param PointeeTy Type pointed by this pointer. 122 /// @param SizeInBits Size. 123 /// @param AlignInBits Alignment. (optional) 124 /// @param Name Pointer type name. (optional) 125 DIType createPointerType(DIType PointeeTy, uint64_t SizeInBits, 126 uint64_t AlignInBits = 0, 127 StringRef Name = StringRef()); 128 129 /// createReferenceType - Create debugging information entry for a c++ 130 /// style reference. 131 DIType createReferenceType(DIType RTy); 132 133 /// createTypedef - Create debugging information entry for a typedef. 134 /// @param Ty Original type. 135 /// @param Name Typedef name. 136 /// @param File File where this type is defined. 137 /// @param LineNo Line number. 138 /// @param Context The surrounding context for the typedef. 139 DIType createTypedef(DIType Ty, StringRef Name, DIFile File, 140 unsigned LineNo, DIDescriptor Context); 141 142 /// createFriend - Create debugging information entry for a 'friend'. 143 DIType createFriend(DIType Ty, DIType FriendTy); 144 145 /// createInheritance - Create debugging information entry to establish 146 /// inheritance relationship between two types. 147 /// @param Ty Original type. 148 /// @param BaseTy Base type. Ty is inherits from base. 149 /// @param BaseOffset Base offset. 150 /// @param Flags Flags to describe inheritance attribute, 151 /// e.g. private 152 DIType createInheritance(DIType Ty, DIType BaseTy, uint64_t BaseOffset, 153 unsigned Flags); 154 155 /// createMemberType - Create debugging information entry for a member. 156 /// @param Scope Member scope. 157 /// @param Name Member name. 158 /// @param File File where this member is defined. 159 /// @param LineNo Line number. 160 /// @param SizeInBits Member size. 161 /// @param AlignInBits Member alignment. 162 /// @param OffsetInBits Member offset. 163 /// @param Flags Flags to encode member attribute, e.g. private 164 /// @param Ty Parent type. 165 DIType createMemberType(DIDescriptor Scope, StringRef Name, DIFile File, 166 unsigned LineNo, uint64_t SizeInBits, 167 uint64_t AlignInBits, uint64_t OffsetInBits, 168 unsigned Flags, DIType Ty); 169 170 /// createObjCIVar - Create debugging information entry for Objective-C 171 /// instance variable. 172 /// @param Name Member name. 173 /// @param File File where this member is defined. 174 /// @param LineNo Line number. 175 /// @param SizeInBits Member size. 176 /// @param AlignInBits Member alignment. 177 /// @param OffsetInBits Member offset. 178 /// @param Flags Flags to encode member attribute, e.g. private 179 /// @param Ty Parent type. 180 /// @param PropertyName Name of the Objective C property assoicated with 181 /// this ivar. 182 /// @param GetterName Name of the Objective C property getter selector. 183 /// @param SetterName Name of the Objective C property setter selector. 184 /// @param PropertyAttributes Objective C property attributes. 185 DIType createObjCIVar(StringRef Name, DIFile File, 186 unsigned LineNo, uint64_t SizeInBits, 187 uint64_t AlignInBits, uint64_t OffsetInBits, 188 unsigned Flags, DIType Ty, 189 StringRef PropertyName = StringRef(), 190 StringRef PropertyGetterName = StringRef(), 191 StringRef PropertySetterName = StringRef(), 192 unsigned PropertyAttributes = 0); 193 194 /// createObjCIVar - Create debugging information entry for Objective-C 195 /// instance variable. 196 /// @param Name Member name. 197 /// @param File File where this member is defined. 198 /// @param LineNo Line number. 199 /// @param SizeInBits Member size. 200 /// @param AlignInBits Member alignment. 201 /// @param OffsetInBits Member offset. 202 /// @param Flags Flags to encode member attribute, e.g. private 203 /// @param Ty Parent type. 204 /// @param Property Property associated with this ivar. 205 DIType createObjCIVar(StringRef Name, DIFile File, 206 unsigned LineNo, uint64_t SizeInBits, 207 uint64_t AlignInBits, uint64_t OffsetInBits, 208 unsigned Flags, DIType Ty, 209 MDNode *PropertyNode); 210 211 /// createObjCProperty - Create debugging information entry for Objective-C 212 /// property. 213 /// @param Name Property name. 214 /// @param GetterName Name of the Objective C property getter selector. 215 /// @param SetterName Name of the Objective C property setter selector. 216 /// @param PropertyAttributes Objective C property attributes. 217 DIObjCProperty createObjCProperty(StringRef Name, StringRef GetterName, 218 StringRef SetterName, 219 unsigned PropertyAttributes); 220 221 /// createClassType - Create debugging information entry for a class. 222 /// @param Scope Scope in which this class is defined. 223 /// @param Name class name. 224 /// @param File File where this member is defined. 225 /// @param LineNo Line number. 226 /// @param SizeInBits Member size. 227 /// @param AlignInBits Member alignment. 228 /// @param OffsetInBits Member offset. 229 /// @param Flags Flags to encode member attribute, e.g. private 230 /// @param Elements class members. 231 /// @param VTableHolder Debug info of the base class that contains vtable 232 /// for this type. This is used in 233 /// DW_AT_containing_type. See DWARF documentation 234 /// for more info. 235 /// @param TemplateParms Template type parameters. 236 DIType createClassType(DIDescriptor Scope, StringRef Name, DIFile File, 237 unsigned LineNumber, uint64_t SizeInBits, 238 uint64_t AlignInBits, uint64_t OffsetInBits, 239 unsigned Flags, DIType DerivedFrom, 240 DIArray Elements, MDNode *VTableHolder = 0, 241 MDNode *TemplateParms = 0); 242 243 /// createStructType - Create debugging information entry for a struct. 244 /// @param Scope Scope in which this struct is defined. 245 /// @param Name Struct name. 246 /// @param File File where this member is defined. 247 /// @param LineNo Line number. 248 /// @param SizeInBits Member size. 249 /// @param AlignInBits Member alignment. 250 /// @param Flags Flags to encode member attribute, e.g. private 251 /// @param Elements Struct elements. 252 /// @param RunTimeLang Optional parameter, Objective-C runtime version. 253 DIType createStructType(DIDescriptor Scope, StringRef Name, DIFile File, 254 unsigned LineNumber, uint64_t SizeInBits, 255 uint64_t AlignInBits, unsigned Flags, 256 DIArray Elements, unsigned RunTimeLang = 0); 257 258 /// createUnionType - Create debugging information entry for an union. 259 /// @param Scope Scope in which this union is defined. 260 /// @param Name Union 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 Flags Flags to encode member attribute, e.g. private 266 /// @param Elements Union elements. 267 /// @param RunTimeLang Optional parameter, Objective-C runtime version. 268 DIType createUnionType(DIDescriptor Scope, StringRef Name, DIFile File, 269 unsigned LineNumber, uint64_t SizeInBits, 270 uint64_t AlignInBits, unsigned Flags, 271 DIArray Elements, unsigned RunTimeLang = 0); 272 273 /// createTemplateTypeParameter - Create debugging information for template 274 /// type parameter. 275 /// @param Scope Scope in which this type is defined. 276 /// @param Name Type parameter name. 277 /// @param Ty Parameter type. 278 /// @param File File where this type parameter is defined. 279 /// @param LineNo Line number. 280 /// @param ColumnNo Column Number. 281 DITemplateTypeParameter 282 createTemplateTypeParameter(DIDescriptor Scope, StringRef Name, DIType Ty, 283 MDNode *File = 0, unsigned LineNo = 0, 284 unsigned ColumnNo = 0); 285 286 /// createTemplateValueParameter - Create debugging information for template 287 /// value parameter. 288 /// @param Scope Scope in which this type is defined. 289 /// @param Name Value parameter name. 290 /// @param Ty Parameter type. 291 /// @param Value Constant parameter value. 292 /// @param File File where this type parameter is defined. 293 /// @param LineNo Line number. 294 /// @param ColumnNo Column Number. 295 DITemplateValueParameter 296 createTemplateValueParameter(DIDescriptor Scope, StringRef Name, DIType Ty, 297 uint64_t Value, 298 MDNode *File = 0, unsigned LineNo = 0, 299 unsigned ColumnNo = 0); 300 301 /// createArrayType - Create debugging information entry for an array. 302 /// @param Size Array size. 303 /// @param AlignInBits Alignment. 304 /// @param Ty Element type. 305 /// @param Subscripts Subscripts. 306 DIType createArrayType(uint64_t Size, uint64_t AlignInBits, 307 DIType Ty, DIArray Subscripts); 308 309 /// createVectorType - Create debugging information entry for a vector type. 310 /// @param Size Array size. 311 /// @param AlignInBits Alignment. 312 /// @param Ty Element type. 313 /// @param Subscripts Subscripts. 314 DIType createVectorType(uint64_t Size, uint64_t AlignInBits, 315 DIType Ty, DIArray Subscripts); 316 317 /// createEnumerationType - Create debugging information entry for an 318 /// enumeration. 319 /// @param Scope Scope in which this enumeration is defined. 320 /// @param Name Union name. 321 /// @param File File where this member is defined. 322 /// @param LineNo Line number. 323 /// @param SizeInBits Member size. 324 /// @param AlignInBits Member alignment. 325 /// @param Elements Enumeration elements. 326 DIType createEnumerationType(DIDescriptor Scope, StringRef Name, 327 DIFile File, unsigned LineNumber, 328 uint64_t SizeInBits, 329 uint64_t AlignInBits, DIArray Elements); 330 331 /// createSubroutineType - Create subroutine type. 332 /// @param File File in which this subroutine is defined. 333 /// @param ParamterTypes An array of subroutine parameter types. This 334 /// includes return type at 0th index. 335 DIType createSubroutineType(DIFile File, DIArray ParameterTypes); 336 337 /// createArtificialType - Create a new DIType with "artificial" flag set. 338 DIType createArtificialType(DIType Ty); 339 340 /// createTemporaryType - Create a temporary forward-declared type. 341 DIType createTemporaryType(); 342 DIType createTemporaryType(DIFile F); 343 344 /// retainType - Retain DIType in a module even if it is not referenced 345 /// through debug info anchors. 346 void retainType(DIType T); 347 348 /// createUnspecifiedParameter - Create unspeicified type descriptor 349 /// for a subroutine type. 350 DIDescriptor createUnspecifiedParameter(); 351 352 /// getOrCreateArray - Get a DIArray, create one if required. 353 DIArray getOrCreateArray(ArrayRef<Value *> Elements); 354 355 /// getOrCreateSubrange - Create a descriptor for a value range. This 356 /// implicitly uniques the values returned. 357 DISubrange getOrCreateSubrange(int64_t Lo, int64_t Hi); 358 359 /// createGlobalVariable - Create a new descriptor for the specified global. 360 /// @param Name Name of the variable. 361 /// @param File File where this variable is defined. 362 /// @param LineNo Line number. 363 /// @param Ty Variable Type. 364 /// @param isLocalToUnit Boolean flag indicate whether this variable is 365 /// externally visible or not. 366 /// @param Val llvm::Value of the variable. 367 DIGlobalVariable 368 createGlobalVariable(StringRef Name, DIFile File, unsigned LineNo, 369 DIType Ty, bool isLocalToUnit, llvm::Value *Val); 370 371 372 /// createStaticVariable - Create a new descriptor for the specified 373 /// variable. 374 /// @param Conext Variable scope. 375 /// @param Name Name of the variable. 376 /// @param LinakgeName Mangled name of the variable. 377 /// @param File File where this variable is defined. 378 /// @param LineNo Line number. 379 /// @param Ty Variable Type. 380 /// @param isLocalToUnit Boolean flag indicate whether this variable is 381 /// externally visible or not. 382 /// @param Val llvm::Value of the variable. 383 DIGlobalVariable 384 createStaticVariable(DIDescriptor Context, StringRef Name, 385 StringRef LinkageName, DIFile File, unsigned LineNo, 386 DIType Ty, bool isLocalToUnit, llvm::Value *Val); 387 388 389 /// createLocalVariable - Create a new descriptor for the specified 390 /// local variable. 391 /// @param Tag Dwarf TAG. Usually DW_TAG_auto_variable or 392 /// DW_TAG_arg_variable. 393 /// @param Scope Variable scope. 394 /// @param Name Variable name. 395 /// @param File File where this variable is defined. 396 /// @param LineNo Line number. 397 /// @param Ty Variable Type 398 /// @param AlwaysPreserve Boolean. Set to true if debug info for this 399 /// variable should be preserved in optimized build. 400 /// @param Flags Flags, e.g. artificial variable. 401 /// @param ArgNo If this variable is an arugment then this argument's 402 /// number. 1 indicates 1st argument. 403 DIVariable createLocalVariable(unsigned Tag, DIDescriptor Scope, 404 StringRef Name, 405 DIFile File, unsigned LineNo, 406 DIType Ty, bool AlwaysPreserve = false, 407 unsigned Flags = 0, 408 unsigned ArgNo = 0); 409 410 411 /// createComplexVariable - Create a new descriptor for the specified 412 /// variable which has a complex address expression for its address. 413 /// @param Tag Dwarf TAG. Usually DW_TAG_auto_variable or 414 /// DW_TAG_arg_variable. 415 /// @param Scope Variable scope. 416 /// @param Name Variable name. 417 /// @param File File where this variable is defined. 418 /// @param LineNo Line number. 419 /// @param Ty Variable Type 420 /// @param Addr An array of complex address operations. 421 /// @param ArgNo If this variable is an arugment then this argument's 422 /// number. 1 indicates 1st argument. 423 DIVariable createComplexVariable(unsigned Tag, DIDescriptor Scope, 424 StringRef Name, DIFile F, unsigned LineNo, 425 DIType Ty, ArrayRef<Value *> Addr, 426 unsigned ArgNo = 0); 427 428 /// createFunction - Create a new descriptor for the specified subprogram. 429 /// See comments in DISubprogram for descriptions of these fields. 430 /// @param Scope Function scope. 431 /// @param Name Function name. 432 /// @param LinkageName Mangled function name. 433 /// @param File File where this variable is defined. 434 /// @param LineNo Line number. 435 /// @param Ty Function type. 436 /// @param isLocalToUnit True if this function is not externally visible.. 437 /// @param isDefinition True if this is a function definition. 438 /// @param Flags e.g. is this function prototyped or not. 439 /// This flags are used to emit dwarf attributes. 440 /// @param isOptimized True if optimization is ON. 441 /// @param Fn llvm::Function pointer. 442 /// @param TParam Function template parameters. 443 DISubprogram createFunction(DIDescriptor Scope, StringRef Name, 444 StringRef LinkageName, 445 DIFile File, unsigned LineNo, 446 DIType Ty, bool isLocalToUnit, 447 bool isDefinition, 448 unsigned Flags = 0, 449 bool isOptimized = false, 450 Function *Fn = 0, 451 MDNode *TParam = 0, 452 MDNode *Decl = 0); 453 454 /// createMethod - Create a new descriptor for the specified C++ method. 455 /// See comments in DISubprogram for descriptions of these fields. 456 /// @param Scope Function scope. 457 /// @param Name Function name. 458 /// @param LinkageName Mangled function name. 459 /// @param File File where this variable is defined. 460 /// @param LineNo Line number. 461 /// @param Ty Function type. 462 /// @param isLocalToUnit True if this function is not externally visible.. 463 /// @param isDefinition True if this is a function definition. 464 /// @param Virtuality Attributes describing virtualness. e.g. pure 465 /// virtual function. 466 /// @param VTableIndex Index no of this method in virtual table. 467 /// @param VTableHolder Type that holds vtable. 468 /// @param Flags e.g. is this function prototyped or not. 469 /// This flags are used to emit dwarf attributes. 470 /// @param isOptimized True if optimization is ON. 471 /// @param Fn llvm::Function pointer. 472 /// @param TParam Function template parameters. 473 DISubprogram createMethod(DIDescriptor Scope, StringRef Name, 474 StringRef LinkageName, 475 DIFile File, unsigned LineNo, 476 DIType Ty, bool isLocalToUnit, 477 bool isDefinition, 478 unsigned Virtuality = 0, unsigned VTableIndex = 0, 479 MDNode *VTableHolder = 0, 480 unsigned Flags = 0, 481 bool isOptimized = false, 482 Function *Fn = 0, 483 MDNode *TParam = 0); 484 485 /// createNameSpace - This creates new descriptor for a namespace 486 /// with the specified parent scope. 487 /// @param Scope Namespace scope 488 /// @param Name Name of this namespace 489 /// @param File Source file 490 /// @param LineNo Line number 491 DINameSpace createNameSpace(DIDescriptor Scope, StringRef Name, 492 DIFile File, unsigned LineNo); 493 494 495 /// createLexicalBlockFile - This creates a descriptor for a lexical 496 /// block with a new file attached. This merely extends the existing 497 /// lexical block as it crosses a file. 498 /// @param Scope Lexical block. 499 /// @param File Source file. 500 DILexicalBlockFile createLexicalBlockFile(DIDescriptor Scope, 501 DIFile File); 502 503 /// createLexicalBlock - This creates a descriptor for a lexical block 504 /// with the specified parent context. 505 /// @param Scope Parent lexical scope. 506 /// @param File Source file 507 /// @param Line Line number 508 /// @param Col Column number 509 DILexicalBlock createLexicalBlock(DIDescriptor Scope, DIFile File, 510 unsigned Line, unsigned Col); 511 512 /// insertDeclare - Insert a new llvm.dbg.declare intrinsic call. 513 /// @param Storage llvm::Value of the variable 514 /// @param VarInfo Variable's debug info descriptor. 515 /// @param InsertAtEnd Location for the new intrinsic. 516 Instruction *insertDeclare(llvm::Value *Storage, DIVariable VarInfo, 517 BasicBlock *InsertAtEnd); 518 519 /// insertDeclare - Insert a new llvm.dbg.declare intrinsic call. 520 /// @param Storage llvm::Value of the variable 521 /// @param VarInfo Variable's debug info descriptor. 522 /// @param InsertBefore Location for the new intrinsic. 523 Instruction *insertDeclare(llvm::Value *Storage, DIVariable VarInfo, 524 Instruction *InsertBefore); 525 526 527 /// insertDbgValueIntrinsic - Insert a new llvm.dbg.value intrinsic call. 528 /// @param Val llvm::Value of the variable 529 /// @param Offset Offset 530 /// @param VarInfo Variable's debug info descriptor. 531 /// @param InsertAtEnd Location for the new intrinsic. 532 Instruction *insertDbgValueIntrinsic(llvm::Value *Val, uint64_t Offset, 533 DIVariable VarInfo, 534 BasicBlock *InsertAtEnd); 535 536 /// insertDbgValueIntrinsic - Insert a new llvm.dbg.value intrinsic call. 537 /// @param Val llvm::Value of the variable 538 /// @param Offset Offset 539 /// @param VarInfo Variable's debug info descriptor. 540 /// @param InsertBefore Location for the new intrinsic. 541 Instruction *insertDbgValueIntrinsic(llvm::Value *Val, uint64_t Offset, 542 DIVariable VarInfo, 543 Instruction *InsertBefore); 544 545 }; 546} // end namespace llvm 547 548#endif 549