include/llvm/Analysis/DIBuilder.h

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