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