include/llvm/IR/DIBuilder.h

   1 //===- 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_IR_DIBUILDER_H
  16 #define LLVM_IR_DIBUILDER_H
  17
  18 #include "llvm/ADT/ArrayRef.h"
  19 #include "llvm/ADT/StringRef.h"
  20 #include "llvm/IR/DebugInfo.h"
  21 #include "llvm/IR/ValueHandle.h"
  22 #include "llvm/Support/DataTypes.h"
  23
  24 namespace llvm {
  25   class BasicBlock;
  26   class Instruction;
  27   class Function;
  28   class Module;
  29   class Value;
  30   class LLVMContext;
  31   class MDNode;
  32   class StringRef;
  33   class DIBasicType;
  34   class DICompileUnit;
  35   class DICompositeType;
  36   class DIDerivedType;
  37   class DIDescriptor;
  38   class DIFile;
  39   class DIEnumerator;
  40   class DIType;
  41   class DIGlobalVariable;
  42   class DIImportedEntity;
  43   class DINameSpace;
  44   class DIVariable;
  45   class DISubrange;
  46   class DILexicalBlockFile;
  47   class DILexicalBlock;
  48   class DIScope;
  49   class DISubprogram;
  50   class DITemplateTypeParameter;
  51   class DITemplateValueParameter;
  52   class DIObjCProperty;
  53
  54   class DIBuilder {
  55     private:
  56     Module &M;
  57     LLVMContext &VMContext;
  58
  59     MDNode *TempEnumTypes;
  60     MDNode *TempRetainTypes;
  61     MDNode *TempSubprograms;
  62     MDNode *TempGVs;
  63     MDNode *TempImportedModules;
  64
  65     Function *DeclareFn;     // llvm.dbg.declare
  66     Function *ValueFn;       // llvm.dbg.value
  67
  68     SmallVector<Value *, 4> AllEnumTypes;
  69     /// Use TrackingVH to collect RetainTypes, since they can be updated
  70     /// later on.
  71     SmallVector<TrackingVH<MDNode>, 4> AllRetainTypes;
  72     SmallVector<Value *, 4> AllSubprograms;
  73     SmallVector<Value *, 4> AllGVs;
  74     SmallVector<TrackingVH<MDNode>, 4> AllImportedModules;
  75
  76     // Private use for multiple types of template parameters.
  77     DITemplateValueParameter
  78     createTemplateValueParameter(unsigned Tag, DIDescriptor Scope,
  79                                  StringRef Name, DIType Ty, Value *Val,
  80                                  MDNode *File = nullptr, unsigned LineNo = 0,
  81                                  unsigned ColumnNo = 0);
  82
  83     DIBuilder(const DIBuilder &) LLVM_DELETED_FUNCTION;
  84     void operator=(const DIBuilder &) LLVM_DELETED_FUNCTION;
  85
  86     public:
  87     explicit DIBuilder(Module &M);
  88     enum DebugEmissionKind { FullDebug=1, LineTablesOnly };
  89
  90     /// finalize - Construct any deferred debug info descriptors.
  91     void finalize();
  92
  93     /// createCompileUnit - A CompileUnit provides an anchor for all debugging
  94     /// information generated during this instance of compilation.
  95     /// @param Lang     Source programming language, eg. dwarf::DW_LANG_C99
  96     /// @param File     File name
  97     /// @param Dir      Directory
  98     /// @param Producer Identify the producer of debugging information and code.
  99     ///                 Usually this is a compiler version string.
 100     /// @param isOptimized A boolean flag which indicates whether optimization
 101     ///                    is ON or not.
 102     /// @param Flags    This string lists command line options. This string is
 103     ///                 directly embedded in debug info output which may be used
 104     ///                 by a tool analyzing generated debugging information.
 105     /// @param RV       This indicates runtime version for languages like
 106     ///                 Objective-C.
 107     /// @param SplitName The name of the file that we'll split debug info out
 108     ///                  into.
 109     /// @param Kind     The kind of debug information to generate.
 110     /// @param EmitDebugInfo   A boolean flag which indicates whether debug
 111     ///                        information should be written to the final
 112     ///                        output or not. When this is false, debug
 113     ///                        information annotations will be present in
 114     ///                        the IL but they are not written to the final
 115     ///                        assembly or object file. This supports tracking
 116     ///                        source location information in the back end
 117     ///                        without actually changing the output (e.g.,
 118     ///                        when using optimization remarks).
 119     DICompileUnit createCompileUnit(unsigned Lang, StringRef File,
 120                                     StringRef Dir, StringRef Producer,
 121                                     bool isOptimized, StringRef Flags,
 122                                     unsigned RV,
 123                                     StringRef SplitName = StringRef(),
 124                                     DebugEmissionKind Kind = FullDebug,
 125                                     bool EmitDebugInfo = true);
 126
 127     /// createFile - Create a file descriptor to hold debugging information
 128     /// for a file.
 129     DIFile createFile(StringRef Filename, StringRef Directory);
 130
 131     /// createEnumerator - Create a single enumerator value.
 132     DIEnumerator createEnumerator(StringRef Name, int64_t Val);
 133
 134     /// \brief Create a DWARF unspecified type.
 135     DIBasicType createUnspecifiedType(StringRef Name);
 136
 137     /// \brief Create C++11 nullptr type.
 138     DIBasicType createNullPtrType();
 139
 140     /// createBasicType - Create debugging information entry for a basic
 141     /// type.
 142     /// @param Name        Type name.
 143     /// @param SizeInBits  Size of the type.
 144     /// @param AlignInBits Type alignment.
 145     /// @param Encoding    DWARF encoding code, e.g. dwarf::DW_ATE_float.
 146     DIBasicType createBasicType(StringRef Name, uint64_t SizeInBits,
 147                                 uint64_t AlignInBits, unsigned Encoding);
 148
 149     /// createQualifiedType - Create debugging information entry for a qualified
 150     /// type, e.g. 'const int'.
 151     /// @param Tag         Tag identifing type, e.g. dwarf::TAG_volatile_type
 152     /// @param FromTy      Base Type.
 153     DIDerivedType createQualifiedType(unsigned Tag, DIType FromTy);
 154
 155     /// createPointerType - Create debugging information entry for a pointer.
 156     /// @param PointeeTy   Type pointed by this pointer.
 157     /// @param SizeInBits  Size.
 158     /// @param AlignInBits Alignment. (optional)
 159     /// @param Name        Pointer type name. (optional)
 160     DIDerivedType
 161     createPointerType(DIType PointeeTy, uint64_t SizeInBits,
 162                       uint64_t AlignInBits = 0, StringRef Name = StringRef());
 163
 164     /// \brief Create debugging information entry for a pointer to member.
 165     /// @param PointeeTy Type pointed to by this pointer.
 166     /// @param Class Type for which this pointer points to members of.
 167     DIDerivedType createMemberPointerType(DIType PointeeTy, DIType Class);
 168
 169     /// createReferenceType - Create debugging information entry for a c++
 170     /// style reference or rvalue reference type.
 171     DIDerivedType createReferenceType(unsigned Tag, DIType RTy);
 172
 173     /// createTypedef - Create debugging information entry for a typedef.
 174     /// @param Ty          Original type.
 175     /// @param Name        Typedef name.
 176     /// @param File        File where this type is defined.
 177     /// @param LineNo      Line number.
 178     /// @param Context     The surrounding context for the typedef.
 179     DIDerivedType createTypedef(DIType Ty, StringRef Name, DIFile File,
 180                                 unsigned LineNo, DIDescriptor Context);
 181
 182     /// createFriend - Create debugging information entry for a 'friend'.
 183     DIDerivedType createFriend(DIType Ty, DIType FriendTy);
 184
 185     /// createInheritance - Create debugging information entry to establish
 186     /// inheritance relationship between two types.
 187     /// @param Ty           Original type.
 188     /// @param BaseTy       Base type. Ty is inherits from base.
 189     /// @param BaseOffset   Base offset.
 190     /// @param Flags        Flags to describe inheritance attribute,
 191     ///                     e.g. private
 192     DIDerivedType createInheritance(DIType Ty, DIType BaseTy,
 193                                     uint64_t BaseOffset, unsigned Flags);
 194
 195     /// createMemberType - Create debugging information entry for a member.
 196     /// @param Scope        Member scope.
 197     /// @param Name         Member name.
 198     /// @param File         File where this member is defined.
 199     /// @param LineNo       Line number.
 200     /// @param SizeInBits   Member size.
 201     /// @param AlignInBits  Member alignment.
 202     /// @param OffsetInBits Member offset.
 203     /// @param Flags        Flags to encode member attribute, e.g. private
 204     /// @param Ty           Parent type.
 205     DIDerivedType
 206     createMemberType(DIDescriptor Scope, StringRef Name, DIFile File,
 207                      unsigned LineNo, uint64_t SizeInBits, uint64_t AlignInBits,
 208                      uint64_t OffsetInBits, unsigned Flags, DIType Ty);
 209
 210     /// createStaticMemberType - Create debugging information entry for a
 211     /// C++ static data member.
 212     /// @param Scope      Member scope.
 213     /// @param Name       Member name.
 214     /// @param File       File where this member is declared.
 215     /// @param LineNo     Line number.
 216     /// @param Ty         Type of the static member.
 217     /// @param Flags      Flags to encode member attribute, e.g. private.
 218     /// @param Val        Const initializer of the member.
 219     DIDerivedType
 220     createStaticMemberType(DIDescriptor Scope, StringRef Name,
 221                            DIFile File, unsigned LineNo, DIType Ty,
 222                            unsigned Flags, llvm::Value *Val);
 223
 224     /// createObjCIVar - Create debugging information entry for Objective-C
 225     /// instance variable.
 226     /// @param Name         Member name.
 227     /// @param File         File where this member is defined.
 228     /// @param LineNo       Line number.
 229     /// @param SizeInBits   Member size.
 230     /// @param AlignInBits  Member alignment.
 231     /// @param OffsetInBits Member offset.
 232     /// @param Flags        Flags to encode member attribute, e.g. private
 233     /// @param Ty           Parent type.
 234     /// @param PropertyNode Property associated with this ivar.
 235     DIDerivedType createObjCIVar(StringRef Name, DIFile File,
 236                                  unsigned LineNo, uint64_t SizeInBits,
 237                                  uint64_t AlignInBits, uint64_t OffsetInBits,
 238                                  unsigned Flags, DIType Ty,
 239                                  MDNode *PropertyNode);
 240
 241     /// createObjCProperty - Create debugging information entry for Objective-C
 242     /// property.
 243     /// @param Name         Property name.
 244     /// @param File         File where this property is defined.
 245     /// @param LineNumber   Line number.
 246     /// @param GetterName   Name of the Objective C property getter selector.
 247     /// @param SetterName   Name of the Objective C property setter selector.
 248     /// @param PropertyAttributes Objective C property attributes.
 249     /// @param Ty           Type.
 250     DIObjCProperty createObjCProperty(StringRef Name,
 251                                       DIFile File, unsigned LineNumber,
 252                                       StringRef GetterName,
 253                                       StringRef SetterName,
 254                                       unsigned PropertyAttributes,
 255                                       DIType Ty);
 256
 257     /// createClassType - Create debugging information entry for a class.
 258     /// @param Scope        Scope in which this class is defined.
 259     /// @param Name         class name.
 260     /// @param File         File where this member is defined.
 261     /// @param LineNumber   Line number.
 262     /// @param SizeInBits   Member size.
 263     /// @param AlignInBits  Member alignment.
 264     /// @param OffsetInBits Member offset.
 265     /// @param Flags        Flags to encode member attribute, e.g. private
 266     /// @param Elements     class members.
 267     /// @param VTableHolder Debug info of the base class that contains vtable
 268     ///                     for this type. This is used in
 269     ///                     DW_AT_containing_type. See DWARF documentation
 270     ///                     for more info.
 271     /// @param TemplateParms Template type parameters.
 272     /// @param UniqueIdentifier A unique identifier for the class.
 273     DICompositeType createClassType(DIDescriptor Scope, StringRef Name,
 274                                     DIFile File, unsigned LineNumber,
 275                                     uint64_t SizeInBits, uint64_t AlignInBits,
 276                                     uint64_t OffsetInBits, unsigned Flags,
 277                                     DIType DerivedFrom, DIArray Elements,
 278                                     DIType VTableHolder = DIType(),
 279                                     MDNode *TemplateParms = nullptr,
 280                                     StringRef UniqueIdentifier = StringRef());
 281
 282     /// createStructType - Create debugging information entry for a struct.
 283     /// @param Scope        Scope in which this struct is defined.
 284     /// @param Name         Struct name.
 285     /// @param File         File where this member is defined.
 286     /// @param LineNumber   Line number.
 287     /// @param SizeInBits   Member size.
 288     /// @param AlignInBits  Member alignment.
 289     /// @param Flags        Flags to encode member attribute, e.g. private
 290     /// @param Elements     Struct elements.
 291     /// @param RunTimeLang  Optional parameter, Objective-C runtime version.
 292     /// @param UniqueIdentifier A unique identifier for the struct.
 293     DICompositeType createStructType(DIDescriptor Scope, StringRef Name,
 294                                      DIFile File, unsigned LineNumber,
 295                                      uint64_t SizeInBits, uint64_t AlignInBits,
 296                                      unsigned Flags, DIType DerivedFrom,
 297                                      DIArray Elements, unsigned RunTimeLang = 0,
 298                                      DIType VTableHolder = DIType(),
 299                                      StringRef UniqueIdentifier = StringRef());
 300
 301     /// createUnionType - Create debugging information entry for an union.
 302     /// @param Scope        Scope in which this union is defined.
 303     /// @param Name         Union name.
 304     /// @param File         File where this member is defined.
 305     /// @param LineNumber   Line number.
 306     /// @param SizeInBits   Member size.
 307     /// @param AlignInBits  Member alignment.
 308     /// @param Flags        Flags to encode member attribute, e.g. private
 309     /// @param Elements     Union elements.
 310     /// @param RunTimeLang  Optional parameter, Objective-C runtime version.
 311     /// @param UniqueIdentifier A unique identifier for the union.
 312     DICompositeType createUnionType(
 313         DIDescriptor Scope, StringRef Name, DIFile File, unsigned LineNumber,
 314         uint64_t SizeInBits, uint64_t AlignInBits, unsigned Flags,
 315         DIArray Elements, unsigned RunTimeLang = 0,
 316         StringRef UniqueIdentifier = StringRef());
 317
 318     /// createTemplateTypeParameter - Create debugging information for template
 319     /// type parameter.
 320     /// @param Scope        Scope in which this type is defined.
 321     /// @param Name         Type parameter name.
 322     /// @param Ty           Parameter type.
 323     /// @param File         File where this type parameter is defined.
 324     /// @param LineNo       Line number.
 325     /// @param ColumnNo     Column Number.
 326     DITemplateTypeParameter
 327     createTemplateTypeParameter(DIDescriptor Scope, StringRef Name, DIType Ty,
 328                                 MDNode *File = nullptr, unsigned LineNo = 0,
 329                                 unsigned ColumnNo = 0);
 330
 331     /// createTemplateValueParameter - Create debugging information for template
 332     /// value parameter.
 333     /// @param Scope        Scope in which this type is defined.
 334     /// @param Name         Value parameter name.
 335     /// @param Ty           Parameter type.
 336     /// @param Val          Constant parameter value.
 337     /// @param File         File where this type parameter is defined.
 338     /// @param LineNo       Line number.
 339     /// @param ColumnNo     Column Number.
 340     DITemplateValueParameter
 341     createTemplateValueParameter(DIDescriptor Scope, StringRef Name,
 342                                  DIType Ty, Value *Val, MDNode *File = nullptr,
 343                                  unsigned LineNo = 0, unsigned ColumnNo = 0);
 344
 345     /// \brief Create debugging information for a template template parameter.
 346     /// @param Scope        Scope in which this type is defined.
 347     /// @param Name         Value parameter name.
 348     /// @param Ty           Parameter type.
 349     /// @param Val          The fully qualified name of the template.
 350     /// @param File         File where this type parameter is defined.
 351     /// @param LineNo       Line number.
 352     /// @param ColumnNo     Column Number.
 353     DITemplateValueParameter
 354     createTemplateTemplateParameter(DIDescriptor Scope, StringRef Name,
 355                                     DIType Ty, StringRef Val,
 356                                     MDNode *File = nullptr, unsigned LineNo = 0,
 357                                     unsigned ColumnNo = 0);
 358
 359     /// \brief Create debugging information for a template parameter pack.
 360     /// @param Scope        Scope in which this type is defined.
 361     /// @param Name         Value parameter name.
 362     /// @param Ty           Parameter type.
 363     /// @param Val          An array of types in the pack.
 364     /// @param File         File where this type parameter is defined.
 365     /// @param LineNo       Line number.
 366     /// @param ColumnNo     Column Number.
 367     DITemplateValueParameter
 368     createTemplateParameterPack(DIDescriptor Scope, StringRef Name,
 369                                 DIType Ty, DIArray Val, MDNode *File = nullptr,
 370                                 unsigned LineNo = 0, unsigned ColumnNo = 0);
 371
 372     /// createArrayType - Create debugging information entry for an array.
 373     /// @param Size         Array size.
 374     /// @param AlignInBits  Alignment.
 375     /// @param Ty           Element type.
 376     /// @param Subscripts   Subscripts.
 377     DICompositeType createArrayType(uint64_t Size, uint64_t AlignInBits,
 378                                     DIType Ty, DIArray Subscripts);
 379
 380     /// createVectorType - Create debugging information entry for a vector type.
 381     /// @param Size         Array size.
 382     /// @param AlignInBits  Alignment.
 383     /// @param Ty           Element type.
 384     /// @param Subscripts   Subscripts.
 385     DICompositeType createVectorType(uint64_t Size, uint64_t AlignInBits,
 386                                      DIType Ty, DIArray Subscripts);
 387
 388     /// createEnumerationType - Create debugging information entry for an
 389     /// enumeration.
 390     /// @param Scope          Scope in which this enumeration is defined.
 391     /// @param Name           Union name.
 392     /// @param File           File where this member is defined.
 393     /// @param LineNumber     Line number.
 394     /// @param SizeInBits     Member size.
 395     /// @param AlignInBits    Member alignment.
 396     /// @param Elements       Enumeration elements.
 397     /// @param UnderlyingType Underlying type of a C++11/ObjC fixed enum.
 398     /// @param UniqueIdentifier A unique identifier for the enum.
 399     DICompositeType createEnumerationType(DIDescriptor Scope, StringRef Name,
 400         DIFile File, unsigned LineNumber, uint64_t SizeInBits,
 401         uint64_t AlignInBits, DIArray Elements, DIType UnderlyingType,
 402         StringRef UniqueIdentifier = StringRef());
 403
 404     /// createSubroutineType - Create subroutine type.
 405     /// @param File            File in which this subroutine is defined.
 406     /// @param ParameterTypes  An array of subroutine parameter types. This
 407     ///                        includes return type at 0th index.
 408     /// @param Flags           E.g.: LValueReference.
 409     ///                        These flags are used to emit dwarf attributes.
 410     DISubroutineType createSubroutineType(DIFile File,
 411                                           DITypeArray ParameterTypes,
 412                                           unsigned Flags = 0);
 413
 414     /// createArtificialType - Create a new DIType with "artificial" flag set.
 415     DIType createArtificialType(DIType Ty);
 416
 417     /// createObjectPointerType - Create a new DIType with the "object pointer"
 418     /// flag set.
 419     DIType createObjectPointerType(DIType Ty);
 420
 421     /// \brief Create a permanent forward-declared type.
 422     DICompositeType createForwardDecl(unsigned Tag, StringRef Name,
 423                                       DIDescriptor Scope, DIFile F,
 424                                       unsigned Line, unsigned RuntimeLang = 0,
 425                                       uint64_t SizeInBits = 0,
 426                                       uint64_t AlignInBits = 0,
 427                                       StringRef UniqueIdentifier = StringRef());
 428
 429     /// \brief Create a temporary forward-declared type.
 430     DICompositeType createReplaceableForwardDecl(
 431         unsigned Tag, StringRef Name, DIDescriptor Scope, DIFile F,
 432         unsigned Line, unsigned RuntimeLang = 0, uint64_t SizeInBits = 0,
 433         uint64_t AlignInBits = 0, StringRef UniqueIdentifier = StringRef());
 434
 435     /// retainType - Retain DIType in a module even if it is not referenced
 436     /// through debug info anchors.
 437     void retainType(DIType T);
 438
 439     /// createUnspecifiedParameter - Create unspecified parameter type
 440     /// for a subroutine type.
 441     DIBasicType createUnspecifiedParameter();
 442
 443     /// getOrCreateArray - Get a DIArray, create one if required.
 444     DIArray getOrCreateArray(ArrayRef<Value *> Elements);
 445
 446     /// getOrCreateTypeArray - Get a DITypeArray, create one if required.
 447     DITypeArray getOrCreateTypeArray(ArrayRef<Value *> Elements);
 448
 449     /// getOrCreateSubrange - Create a descriptor for a value range.  This
 450     /// implicitly uniques the values returned.
 451     DISubrange getOrCreateSubrange(int64_t Lo, int64_t Count);
 452
 453
 454     /// createGlobalVariable - Create a new descriptor for the specified
 455     /// variable.
 456     /// @param Context     Variable scope.
 457     /// @param Name        Name of the variable.
 458     /// @param LinkageName Mangled  name of the variable.
 459     /// @param File        File where this variable is defined.
 460     /// @param LineNo      Line number.
 461     /// @param Ty          Variable Type.
 462     /// @param isLocalToUnit Boolean flag indicate whether this variable is
 463     ///                      externally visible or not.
 464     /// @param Val         llvm::Value of the variable.
 465     /// @param Decl        Reference to the corresponding declaration.
 466     DIGlobalVariable
 467     createGlobalVariable(DIDescriptor Context, StringRef Name,
 468                          StringRef LinkageName, DIFile File, unsigned LineNo,
 469                          DITypeRef Ty, bool isLocalToUnit, llvm::Value *Val,
 470                          MDNode *Decl = nullptr);
 471
 472     /// createTempGlobalVariableFwdDecl - Identical to createGlobalVariable
 473     /// except that the resulting DbgNode is temporary and meant to be RAUWed.
 474     DIGlobalVariable
 475     createTempGlobalVariableFwdDecl(DIDescriptor Context, StringRef Name,
 476                                     StringRef LinkageName, DIFile File,
 477                                     unsigned LineNo, DITypeRef Ty,
 478                                     bool isLocalToUnit, llvm::Value *Val,
 479                                     MDNode *Decl = nullptr);
 480
 481
 482     /// createLocalVariable - Create a new descriptor for the specified
 483     /// local variable.
 484     /// @param Tag         Dwarf TAG. Usually DW_TAG_auto_variable or
 485     ///                    DW_TAG_arg_variable.
 486     /// @param Scope       Variable scope.
 487     /// @param Name        Variable name.
 488     /// @param File        File where this variable is defined.
 489     /// @param LineNo      Line number.
 490     /// @param Ty          Variable Type
 491     /// @param AlwaysPreserve Boolean. Set to true if debug info for this
 492     ///                       variable should be preserved in optimized build.
 493     /// @param Flags       Flags, e.g. artificial variable.
 494     /// @param ArgNo       If this variable is an argument then this argument's
 495     ///                    number. 1 indicates 1st argument.
 496     DIVariable createLocalVariable(unsigned Tag, DIDescriptor Scope,
 497                                    StringRef Name,
 498                                    DIFile File, unsigned LineNo,
 499                                    DITypeRef Ty, bool AlwaysPreserve = false,
 500                                    unsigned Flags = 0,
 501                                    unsigned ArgNo = 0);
 502
 503     /// createExpression - Create a new descriptor for the specified
 504     /// variable which has a complex address expression for its address.
 505     /// @param Addr        An array of complex address operations.
 506     DIExpression createExpression(ArrayRef<Value *> Addr = None);
 507
 508     /// createPieceExpression - Create a descriptor to describe one part
 509     /// of aggregate variable that is fragmented across multiple Values.
 510     ///
 511     /// @param OffsetInBytes Offset of the piece in bytes.
 512     /// @param SizeInBytes   Size of the piece in bytes.
 513     DIExpression createPieceExpression(unsigned OffsetInBytes,
 514                                        unsigned SizeInBytes);
 515
 516     /// createFunction - Create a new descriptor for the specified subprogram.
 517     /// See comments in DISubprogram for descriptions of these fields.
 518     /// @param Scope         Function scope.
 519     /// @param Name          Function name.
 520     /// @param LinkageName   Mangled function name.
 521     /// @param File          File where this variable is defined.
 522     /// @param LineNo        Line number.
 523     /// @param Ty            Function type.
 524     /// @param isLocalToUnit True if this function is not externally visible.
 525     /// @param isDefinition  True if this is a function definition.
 526     /// @param ScopeLine     Set to the beginning of the scope this starts
 527     /// @param Flags         e.g. is this function prototyped or not.
 528     ///                      These flags are used to emit dwarf attributes.
 529     /// @param isOptimized   True if optimization is ON.
 530     /// @param Fn            llvm::Function pointer.
 531     /// @param TParam        Function template parameters.
 532     DISubprogram createFunction(DIDescriptor Scope, StringRef Name,
 533                                 StringRef LinkageName,
 534                                 DIFile File, unsigned LineNo,
 535                                 DICompositeType Ty, bool isLocalToUnit,
 536                                 bool isDefinition,
 537                                 unsigned ScopeLine,
 538                                 unsigned Flags = 0,
 539                                 bool isOptimized = false,
 540                                 Function *Fn = nullptr,
 541                                 MDNode *TParam = nullptr,
 542                                 MDNode *Decl = nullptr);
 543
 544     /// createTempFunctionFwdDecl - Identical to createFunction,
 545     /// except that the resulting DbgNode is meant to be RAUWed.
 546     DISubprogram createTempFunctionFwdDecl(DIDescriptor Scope, StringRef Name,
 547                                            StringRef LinkageName,
 548                                            DIFile File, unsigned LineNo,
 549                                            DICompositeType Ty, bool isLocalToUnit,
 550                                            bool isDefinition,
 551                                            unsigned ScopeLine,
 552                                            unsigned Flags = 0,
 553                                            bool isOptimized = false,
 554                                            Function *Fn = nullptr,
 555                                            MDNode *TParam = nullptr,
 556                                            MDNode *Decl = nullptr);
 557
 558
 559     /// FIXME: this is added for dragonegg. Once we update dragonegg
 560     /// to call resolve function, this will be removed.
 561     DISubprogram createFunction(DIScopeRef Scope, StringRef Name,
 562                                 StringRef LinkageName,
 563                                 DIFile File, unsigned LineNo,
 564                                 DICompositeType Ty, bool isLocalToUnit,
 565                                 bool isDefinition,
 566                                 unsigned ScopeLine,
 567                                 unsigned Flags = 0,
 568                                 bool isOptimized = false,
 569                                 Function *Fn = nullptr,
 570                                 MDNode *TParam = nullptr,
 571                                 MDNode *Decl = nullptr);
 572
 573     /// createMethod - Create a new descriptor for the specified C++ method.
 574     /// See comments in DISubprogram for descriptions of these fields.
 575     /// @param Scope         Function scope.
 576     /// @param Name          Function name.
 577     /// @param LinkageName   Mangled function name.
 578     /// @param File          File where this variable is defined.
 579     /// @param LineNo        Line number.
 580     /// @param Ty            Function type.
 581     /// @param isLocalToUnit True if this function is not externally visible..
 582     /// @param isDefinition  True if this is a function definition.
 583     /// @param Virtuality    Attributes describing virtualness. e.g. pure
 584     ///                      virtual function.
 585     /// @param VTableIndex   Index no of this method in virtual table.
 586     /// @param VTableHolder  Type that holds vtable.
 587     /// @param Flags         e.g. is this function prototyped or not.
 588     ///                      This flags are used to emit dwarf attributes.
 589     /// @param isOptimized   True if optimization is ON.
 590     /// @param Fn            llvm::Function pointer.
 591     /// @param TParam        Function template parameters.
 592     DISubprogram createMethod(DIDescriptor Scope, StringRef Name,
 593                               StringRef LinkageName,
 594                               DIFile File, unsigned LineNo,
 595                               DICompositeType Ty, bool isLocalToUnit,
 596                               bool isDefinition,
 597                               unsigned Virtuality = 0, unsigned VTableIndex = 0,
 598                               DIType VTableHolder = DIType(),
 599                               unsigned Flags = 0,
 600                               bool isOptimized = false,
 601                               Function *Fn = nullptr,
 602                               MDNode *TParam = nullptr);
 603
 604     /// createNameSpace - This creates new descriptor for a namespace
 605     /// with the specified parent scope.
 606     /// @param Scope       Namespace scope
 607     /// @param Name        Name of this namespace
 608     /// @param File        Source file
 609     /// @param LineNo      Line number
 610     DINameSpace createNameSpace(DIDescriptor Scope, StringRef Name,
 611                                 DIFile File, unsigned LineNo);
 612
 613
 614     /// createLexicalBlockFile - This creates a descriptor for a lexical
 615     /// block with a new file attached. This merely extends the existing
 616     /// lexical block as it crosses a file.
 617     /// @param Scope       Lexical block.
 618     /// @param File        Source file.
 619     /// @param Discriminator DWARF path discriminator value.
 620     DILexicalBlockFile createLexicalBlockFile(DIDescriptor Scope, DIFile File,
 621                                               unsigned Discriminator = 0);
 622
 623     /// createLexicalBlock - This creates a descriptor for a lexical block
 624     /// with the specified parent context.
 625     /// @param Scope         Parent lexical scope.
 626     /// @param File          Source file.
 627     /// @param Line          Line number.
 628     /// @param Col           Column number.
 629     DILexicalBlock createLexicalBlock(DIDescriptor Scope, DIFile File,
 630                                       unsigned Line, unsigned Col);
 631
 632     /// \brief Create a descriptor for an imported module.
 633     /// @param Context The scope this module is imported into
 634     /// @param NS The namespace being imported here
 635     /// @param Line Line number
 636     DIImportedEntity createImportedModule(DIScope Context, DINameSpace NS,
 637                                           unsigned Line);
 638
 639     /// \brief Create a descriptor for an imported module.
 640     /// @param Context The scope this module is imported into
 641     /// @param NS An aliased namespace
 642     /// @param Line Line number
 643     DIImportedEntity createImportedModule(DIScope Context, DIImportedEntity NS,
 644                                           unsigned Line);
 645
 646     /// \brief Create a descriptor for an imported function.
 647     /// @param Context The scope this module is imported into
 648     /// @param Decl The declaration (or definition) of a function, type, or
 649     ///             variable
 650     /// @param Line Line number
 651     DIImportedEntity createImportedDeclaration(DIScope Context, DIScope Decl,
 652                                                unsigned Line,
 653                                                StringRef Name = StringRef());
 654     DIImportedEntity createImportedDeclaration(DIScope Context,
 655                                                DIImportedEntity NS,
 656                                                unsigned Line,
 657                                                StringRef Name = StringRef());
 658
 659     /// insertDeclare - Insert a new llvm.dbg.declare intrinsic call.
 660     /// @param Storage     llvm::Value of the variable
 661     /// @param VarInfo     Variable's debug info descriptor.
 662     /// @param Expr         A complex location expression.
 663     /// @param InsertAtEnd Location for the new intrinsic.
 664     Instruction *insertDeclare(llvm::Value *Storage, DIVariable VarInfo,
 665                                DIExpression Expr, BasicBlock *InsertAtEnd);
 666
 667     /// insertDeclare - Insert a new llvm.dbg.declare intrinsic call.
 668     /// @param Storage      llvm::Value of the variable
 669     /// @param VarInfo      Variable's debug info descriptor.
 670     /// @param Expr         A complex location expression.
 671     /// @param InsertBefore Location for the new intrinsic.
 672     Instruction *insertDeclare(llvm::Value *Storage, DIVariable VarInfo,
 673                                DIExpression Expr, Instruction *InsertBefore);
 674
 675     /// insertDbgValueIntrinsic - Insert a new llvm.dbg.value intrinsic call.
 676     /// @param Val          llvm::Value of the variable
 677     /// @param Offset       Offset
 678     /// @param VarInfo      Variable's debug info descriptor.
 679     /// @param Expr         A complex location expression.
 680     /// @param InsertAtEnd Location for the new intrinsic.
 681     Instruction *insertDbgValueIntrinsic(llvm::Value *Val, uint64_t Offset,
 682                                          DIVariable VarInfo, DIExpression Expr,
 683                                          BasicBlock *InsertAtEnd);
 684
 685     /// insertDbgValueIntrinsic - Insert a new llvm.dbg.value intrinsic call.
 686     /// @param Val          llvm::Value of the variable
 687     /// @param Offset       Offset
 688     /// @param VarInfo      Variable's debug info descriptor.
 689     /// @param Expr         A complex location expression.
 690     /// @param InsertBefore Location for the new intrinsic.
 691     Instruction *insertDbgValueIntrinsic(llvm::Value *Val, uint64_t Offset,
 692                                          DIVariable VarInfo, DIExpression Expr,
 693                                          Instruction *InsertBefore);
 694   };
 695 } // end namespace llvm
 696
 697 #endif