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