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