include/llvm-c/DebugInfo.h

   1 //===------------ DebugInfo.h - LLVM C API Debug Info API -----------------===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8 ///
   9 /// This file declares the C API endpoints for generating DWARF Debug Info
  10 ///
  11 /// Note: This interface is experimental. It is *NOT* stable, and may be
  12 ///       changed without warning.
  13 ///
  14 //===----------------------------------------------------------------------===//
  15
  16 #ifndef LLVM_C_DEBUGINFO_H
  17 #define LLVM_C_DEBUGINFO_H
  18
  19 #include "llvm-c/Core.h"
  20
  21 #ifdef __cplusplus
  22 extern "C" {
  23 #endif
  24
  25 /**
  26  * Debug info flags.
  27  */
  28 typedef enum {
  29   LLVMDIFlagZero = 0,
  30   LLVMDIFlagPrivate = 1,
  31   LLVMDIFlagProtected = 2,
  32   LLVMDIFlagPublic = 3,
  33   LLVMDIFlagFwdDecl = 1 << 2,
  34   LLVMDIFlagAppleBlock = 1 << 3,
  35   LLVMDIFlagReservedBit4 = 1 << 4,
  36   LLVMDIFlagVirtual = 1 << 5,
  37   LLVMDIFlagArtificial = 1 << 6,
  38   LLVMDIFlagExplicit = 1 << 7,
  39   LLVMDIFlagPrototyped = 1 << 8,
  40   LLVMDIFlagObjcClassComplete = 1 << 9,
  41   LLVMDIFlagObjectPointer = 1 << 10,
  42   LLVMDIFlagVector = 1 << 11,
  43   LLVMDIFlagStaticMember = 1 << 12,
  44   LLVMDIFlagLValueReference = 1 << 13,
  45   LLVMDIFlagRValueReference = 1 << 14,
  46   LLVMDIFlagReserved = 1 << 15,
  47   LLVMDIFlagSingleInheritance = 1 << 16,
  48   LLVMDIFlagMultipleInheritance = 2 << 16,
  49   LLVMDIFlagVirtualInheritance = 3 << 16,
  50   LLVMDIFlagIntroducedVirtual = 1 << 18,
  51   LLVMDIFlagBitField = 1 << 19,
  52   LLVMDIFlagNoReturn = 1 << 20,
  53   LLVMDIFlagTypePassByValue = 1 << 22,
  54   LLVMDIFlagTypePassByReference = 1 << 23,
  55   LLVMDIFlagEnumClass = 1 << 24,
  56   LLVMDIFlagFixedEnum = LLVMDIFlagEnumClass, // Deprecated.
  57   LLVMDIFlagThunk = 1 << 25,
  58   LLVMDIFlagNonTrivial = 1 << 26,
  59   LLVMDIFlagBigEndian = 1 << 27,
  60   LLVMDIFlagLittleEndian = 1 << 28,
  61   LLVMDIFlagIndirectVirtualBase = (1 << 2) | (1 << 5),
  62   LLVMDIFlagAccessibility = LLVMDIFlagPrivate | LLVMDIFlagProtected |
  63                             LLVMDIFlagPublic,
  64   LLVMDIFlagPtrToMemberRep = LLVMDIFlagSingleInheritance |
  65                              LLVMDIFlagMultipleInheritance |
  66                              LLVMDIFlagVirtualInheritance
  67 } LLVMDIFlags;
  68
  69 /**
  70  * Source languages known by DWARF.
  71  */
  72 typedef enum {
  73   LLVMDWARFSourceLanguageC89,
  74   LLVMDWARFSourceLanguageC,
  75   LLVMDWARFSourceLanguageAda83,
  76   LLVMDWARFSourceLanguageC_plus_plus,
  77   LLVMDWARFSourceLanguageCobol74,
  78   LLVMDWARFSourceLanguageCobol85,
  79   LLVMDWARFSourceLanguageFortran77,
  80   LLVMDWARFSourceLanguageFortran90,
  81   LLVMDWARFSourceLanguagePascal83,
  82   LLVMDWARFSourceLanguageModula2,
  83   // New in DWARF v3:
  84   LLVMDWARFSourceLanguageJava,
  85   LLVMDWARFSourceLanguageC99,
  86   LLVMDWARFSourceLanguageAda95,
  87   LLVMDWARFSourceLanguageFortran95,
  88   LLVMDWARFSourceLanguagePLI,
  89   LLVMDWARFSourceLanguageObjC,
  90   LLVMDWARFSourceLanguageObjC_plus_plus,
  91   LLVMDWARFSourceLanguageUPC,
  92   LLVMDWARFSourceLanguageD,
  93   // New in DWARF v4:
  94   LLVMDWARFSourceLanguagePython,
  95   // New in DWARF v5:
  96   LLVMDWARFSourceLanguageOpenCL,
  97   LLVMDWARFSourceLanguageGo,
  98   LLVMDWARFSourceLanguageModula3,
  99   LLVMDWARFSourceLanguageHaskell,
 100   LLVMDWARFSourceLanguageC_plus_plus_03,
 101   LLVMDWARFSourceLanguageC_plus_plus_11,
 102   LLVMDWARFSourceLanguageOCaml,
 103   LLVMDWARFSourceLanguageRust,
 104   LLVMDWARFSourceLanguageC11,
 105   LLVMDWARFSourceLanguageSwift,
 106   LLVMDWARFSourceLanguageJulia,
 107   LLVMDWARFSourceLanguageDylan,
 108   LLVMDWARFSourceLanguageC_plus_plus_14,
 109   LLVMDWARFSourceLanguageFortran03,
 110   LLVMDWARFSourceLanguageFortran08,
 111   LLVMDWARFSourceLanguageRenderScript,
 112   LLVMDWARFSourceLanguageBLISS,
 113   // Vendor extensions:
 114   LLVMDWARFSourceLanguageMips_Assembler,
 115   LLVMDWARFSourceLanguageGOOGLE_RenderScript,
 116   LLVMDWARFSourceLanguageBORLAND_Delphi
 117 } LLVMDWARFSourceLanguage;
 118
 119 /**
 120  * The amount of debug information to emit.
 121  */
 122 typedef enum {
 123     LLVMDWARFEmissionNone = 0,
 124     LLVMDWARFEmissionFull,
 125     LLVMDWARFEmissionLineTablesOnly
 126 } LLVMDWARFEmissionKind;
 127
 128 /**
 129  * The kind of metadata nodes.
 130  */
 131 enum {
 132   LLVMMDStringMetadataKind,
 133   LLVMConstantAsMetadataMetadataKind,
 134   LLVMLocalAsMetadataMetadataKind,
 135   LLVMDistinctMDOperandPlaceholderMetadataKind,
 136   LLVMMDTupleMetadataKind,
 137   LLVMDILocationMetadataKind,
 138   LLVMDIExpressionMetadataKind,
 139   LLVMDIGlobalVariableExpressionMetadataKind,
 140   LLVMGenericDINodeMetadataKind,
 141   LLVMDISubrangeMetadataKind,
 142   LLVMDIEnumeratorMetadataKind,
 143   LLVMDIBasicTypeMetadataKind,
 144   LLVMDIDerivedTypeMetadataKind,
 145   LLVMDICompositeTypeMetadataKind,
 146   LLVMDISubroutineTypeMetadataKind,
 147   LLVMDIFileMetadataKind,
 148   LLVMDICompileUnitMetadataKind,
 149   LLVMDISubprogramMetadataKind,
 150   LLVMDILexicalBlockMetadataKind,
 151   LLVMDILexicalBlockFileMetadataKind,
 152   LLVMDINamespaceMetadataKind,
 153   LLVMDIModuleMetadataKind,
 154   LLVMDITemplateTypeParameterMetadataKind,
 155   LLVMDITemplateValueParameterMetadataKind,
 156   LLVMDIGlobalVariableMetadataKind,
 157   LLVMDILocalVariableMetadataKind,
 158   LLVMDILabelMetadataKind,
 159   LLVMDIObjCPropertyMetadataKind,
 160   LLVMDIImportedEntityMetadataKind,
 161   LLVMDIMacroMetadataKind,
 162   LLVMDIMacroFileMetadataKind,
 163   LLVMDICommonBlockMetadataKind
 164 };
 165 typedef unsigned LLVMMetadataKind;
 166
 167 /**
 168  * An LLVM DWARF type encoding.
 169  */
 170 typedef unsigned LLVMDWARFTypeEncoding;
 171
 172 /**
 173  * Describes the kind of macro declaration used for LLVMDIBuilderCreateMacro.
 174  * @see llvm::dwarf::MacinfoRecordType
 175  * @note Values are from DW_MACINFO_* constants in the DWARF specification.
 176  */
 177 typedef enum {
 178   LLVMDWARFMacinfoRecordTypeDefine = 0x01,
 179   LLVMDWARFMacinfoRecordTypeMacro = 0x02,
 180   LLVMDWARFMacinfoRecordTypeStartFile = 0x03,
 181   LLVMDWARFMacinfoRecordTypeEndFile = 0x04,
 182   LLVMDWARFMacinfoRecordTypeVendorExt = 0xff
 183 } LLVMDWARFMacinfoRecordType;
 184
 185 /**
 186  * The current debug metadata version number.
 187  */
 188 unsigned LLVMDebugMetadataVersion(void);
 189
 190 /**
 191  * The version of debug metadata that's present in the provided \c Module.
 192  */
 193 unsigned LLVMGetModuleDebugMetadataVersion(LLVMModuleRef Module);
 194
 195 /**
 196  * Strip debug info in the module if it exists.
 197  * To do this, we remove all calls to the debugger intrinsics and any named
 198  * metadata for debugging. We also remove debug locations for instructions.
 199  * Return true if module is modified.
 200  */
 201 LLVMBool LLVMStripModuleDebugInfo(LLVMModuleRef Module);
 202
 203 /**
 204  * Construct a builder for a module, and do not allow for unresolved nodes
 205  * attached to the module.
 206  */
 207 LLVMDIBuilderRef LLVMCreateDIBuilderDisallowUnresolved(LLVMModuleRef M);
 208
 209 /**
 210  * Construct a builder for a module and collect unresolved nodes attached
 211  * to the module in order to resolve cycles during a call to
 212  * \c LLVMDIBuilderFinalize.
 213  */
 214 LLVMDIBuilderRef LLVMCreateDIBuilder(LLVMModuleRef M);
 215
 216 /**
 217  * Deallocates the \c DIBuilder and everything it owns.
 218  * @note You must call \c LLVMDIBuilderFinalize before this
 219  */
 220 void LLVMDisposeDIBuilder(LLVMDIBuilderRef Builder);
 221
 222 /**
 223  * Construct any deferred debug info descriptors.
 224  */
 225 void LLVMDIBuilderFinalize(LLVMDIBuilderRef Builder);
 226
 227 /**
 228  * A CompileUnit provides an anchor for all debugging
 229  * information generated during this instance of compilation.
 230  * \param Lang          Source programming language, eg.
 231  *                      \c LLVMDWARFSourceLanguageC99
 232  * \param FileRef       File info.
 233  * \param Producer      Identify the producer of debugging information
 234  *                      and code.  Usually this is a compiler
 235  *                      version string.
 236  * \param ProducerLen   The length of the C string passed to \c Producer.
 237  * \param isOptimized   A boolean flag which indicates whether optimization
 238  *                      is enabled or not.
 239  * \param Flags         This string lists command line options. This
 240  *                      string is directly embedded in debug info
 241  *                      output which may be used by a tool
 242  *                      analyzing generated debugging information.
 243  * \param FlagsLen      The length of the C string passed to \c Flags.
 244  * \param RuntimeVer    This indicates runtime version for languages like
 245  *                      Objective-C.
 246  * \param SplitName     The name of the file that we'll split debug info
 247  *                      out into.
 248  * \param SplitNameLen  The length of the C string passed to \c SplitName.
 249  * \param Kind          The kind of debug information to generate.
 250  * \param DWOId         The DWOId if this is a split skeleton compile unit.
 251  * \param SplitDebugInlining    Whether to emit inline debug info.
 252  * \param DebugInfoForProfiling Whether to emit extra debug info for
 253  *                              profile collection.
 254  */
 255 LLVMMetadataRef LLVMDIBuilderCreateCompileUnit(
 256     LLVMDIBuilderRef Builder, LLVMDWARFSourceLanguage Lang,
 257     LLVMMetadataRef FileRef, const char *Producer, size_t ProducerLen,
 258     LLVMBool isOptimized, const char *Flags, size_t FlagsLen,
 259     unsigned RuntimeVer, const char *SplitName, size_t SplitNameLen,
 260     LLVMDWARFEmissionKind Kind, unsigned DWOId, LLVMBool SplitDebugInlining,
 261     LLVMBool DebugInfoForProfiling);
 262
 263 /**
 264  * Create a file descriptor to hold debugging information for a file.
 265  * \param Builder      The \c DIBuilder.
 266  * \param Filename     File name.
 267  * \param FilenameLen  The length of the C string passed to \c Filename.
 268  * \param Directory    Directory.
 269  * \param DirectoryLen The length of the C string passed to \c Directory.
 270  */
 271 LLVMMetadataRef
 272 LLVMDIBuilderCreateFile(LLVMDIBuilderRef Builder, const char *Filename,
 273                         size_t FilenameLen, const char *Directory,
 274                         size_t DirectoryLen);
 275
 276 /**
 277  * Creates a new descriptor for a module with the specified parent scope.
 278  * \param Builder         The \c DIBuilder.
 279  * \param ParentScope     The parent scope containing this module declaration.
 280  * \param Name            Module name.
 281  * \param NameLen         The length of the C string passed to \c Name.
 282  * \param ConfigMacros    A space-separated shell-quoted list of -D macro
 283                           definitions as they would appear on a command line.
 284  * \param ConfigMacrosLen The length of the C string passed to \c ConfigMacros.
 285  * \param IncludePath     The path to the module map file.
 286  * \param IncludePathLen  The length of the C string passed to \c IncludePath.
 287  * \param ISysRoot        The Clang system root (value of -isysroot).
 288  * \param ISysRootLen     The length of the C string passed to \c ISysRoot.
 289  */
 290 LLVMMetadataRef
 291 LLVMDIBuilderCreateModule(LLVMDIBuilderRef Builder, LLVMMetadataRef ParentScope,
 292                           const char *Name, size_t NameLen,
 293                           const char *ConfigMacros, size_t ConfigMacrosLen,
 294                           const char *IncludePath, size_t IncludePathLen,
 295                           const char *ISysRoot, size_t ISysRootLen);
 296
 297 /**
 298  * Creates a new descriptor for a namespace with the specified parent scope.
 299  * \param Builder          The \c DIBuilder.
 300  * \param ParentScope      The parent scope containing this module declaration.
 301  * \param Name             NameSpace name.
 302  * \param NameLen          The length of the C string passed to \c Name.
 303  * \param ExportSymbols    Whether or not the namespace exports symbols, e.g.
 304  *                         this is true of C++ inline namespaces.
 305  */
 306 LLVMMetadataRef
 307 LLVMDIBuilderCreateNameSpace(LLVMDIBuilderRef Builder,
 308                              LLVMMetadataRef ParentScope,
 309                              const char *Name, size_t NameLen,
 310                              LLVMBool ExportSymbols);
 311
 312 /**
 313  * Create a new descriptor for the specified subprogram.
 314  * \param Builder         The \c DIBuilder.
 315  * \param Scope           Function scope.
 316  * \param Name            Function name.
 317  * \param NameLen         Length of enumeration name.
 318  * \param LinkageName     Mangled function name.
 319  * \param LinkageNameLen  Length of linkage name.
 320  * \param File            File where this variable is defined.
 321  * \param LineNo          Line number.
 322  * \param Ty              Function type.
 323  * \param IsLocalToUnit   True if this function is not externally visible.
 324  * \param IsDefinition    True if this is a function definition.
 325  * \param ScopeLine       Set to the beginning of the scope this starts
 326  * \param Flags           E.g.: \c LLVMDIFlagLValueReference. These flags are
 327  *                        used to emit dwarf attributes.
 328  * \param IsOptimized     True if optimization is ON.
 329  */
 330 LLVMMetadataRef LLVMDIBuilderCreateFunction(
 331     LLVMDIBuilderRef Builder, LLVMMetadataRef Scope, const char *Name,
 332     size_t NameLen, const char *LinkageName, size_t LinkageNameLen,
 333     LLVMMetadataRef File, unsigned LineNo, LLVMMetadataRef Ty,
 334     LLVMBool IsLocalToUnit, LLVMBool IsDefinition,
 335     unsigned ScopeLine, LLVMDIFlags Flags, LLVMBool IsOptimized);
 336
 337 /**
 338  * Create a descriptor for a lexical block with the specified parent context.
 339  * \param Builder      The \c DIBuilder.
 340  * \param Scope        Parent lexical block.
 341  * \param File         Source file.
 342  * \param Line         The line in the source file.
 343  * \param Column       The column in the source file.
 344  */
 345 LLVMMetadataRef LLVMDIBuilderCreateLexicalBlock(
 346     LLVMDIBuilderRef Builder, LLVMMetadataRef Scope,
 347     LLVMMetadataRef File, unsigned Line, unsigned Column);
 348
 349 /**
 350  * Create a descriptor for a lexical block with a new file attached.
 351  * \param Builder        The \c DIBuilder.
 352  * \param Scope          Lexical block.
 353  * \param File           Source file.
 354  * \param Discriminator  DWARF path discriminator value.
 355  */
 356 LLVMMetadataRef
 357 LLVMDIBuilderCreateLexicalBlockFile(LLVMDIBuilderRef Builder,
 358                                     LLVMMetadataRef Scope,
 359                                     LLVMMetadataRef File,
 360                                     unsigned Discriminator);
 361
 362 /**
 363  * Create a descriptor for an imported namespace. Suitable for e.g. C++
 364  * using declarations.
 365  * \param Builder    The \c DIBuilder.
 366  * \param Scope      The scope this module is imported into
 367  * \param File       File where the declaration is located.
 368  * \param Line       Line number of the declaration.
 369  */
 370 LLVMMetadataRef
 371 LLVMDIBuilderCreateImportedModuleFromNamespace(LLVMDIBuilderRef Builder,
 372                                                LLVMMetadataRef Scope,
 373                                                LLVMMetadataRef NS,
 374                                                LLVMMetadataRef File,
 375                                                unsigned Line);
 376
 377 /**
 378  * Create a descriptor for an imported module that aliases another
 379  * imported entity descriptor.
 380  * \param Builder        The \c DIBuilder.
 381  * \param Scope          The scope this module is imported into
 382  * \param ImportedEntity Previous imported entity to alias.
 383  * \param File           File where the declaration is located.
 384  * \param Line           Line number of the declaration.
 385  */
 386 LLVMMetadataRef
 387 LLVMDIBuilderCreateImportedModuleFromAlias(LLVMDIBuilderRef Builder,
 388                                            LLVMMetadataRef Scope,
 389                                            LLVMMetadataRef ImportedEntity,
 390                                            LLVMMetadataRef File,
 391                                            unsigned Line);
 392
 393 /**
 394  * Create a descriptor for an imported module.
 395  * \param Builder    The \c DIBuilder.
 396  * \param Scope      The scope this module is imported into
 397  * \param M          The module being imported here
 398  * \param File       File where the declaration is located.
 399  * \param Line       Line number of the declaration.
 400  */
 401 LLVMMetadataRef
 402 LLVMDIBuilderCreateImportedModuleFromModule(LLVMDIBuilderRef Builder,
 403                                             LLVMMetadataRef Scope,
 404                                             LLVMMetadataRef M,
 405                                             LLVMMetadataRef File,
 406                                             unsigned Line);
 407
 408 /**
 409  * Create a descriptor for an imported function, type, or variable.  Suitable
 410  * for e.g. FORTRAN-style USE declarations.
 411  * \param Builder    The DIBuilder.
 412  * \param Scope      The scope this module is imported into.
 413  * \param Decl       The declaration (or definition) of a function, type,
 414                      or variable.
 415  * \param File       File where the declaration is located.
 416  * \param Line       Line number of the declaration.
 417  * \param Name       A name that uniquely identifies this imported declaration.
 418  * \param NameLen    The length of the C string passed to \c Name.
 419  */
 420 LLVMMetadataRef
 421 LLVMDIBuilderCreateImportedDeclaration(LLVMDIBuilderRef Builder,
 422                                        LLVMMetadataRef Scope,
 423                                        LLVMMetadataRef Decl,
 424                                        LLVMMetadataRef File,
 425                                        unsigned Line,
 426                                        const char *Name, size_t NameLen);
 427
 428 /**
 429  * Creates a new DebugLocation that describes a source location.
 430  * \param Line The line in the source file.
 431  * \param Column The column in the source file.
 432  * \param Scope The scope in which the location resides.
 433  * \param InlinedAt The scope where this location was inlined, if at all.
 434  *                  (optional).
 435  * \note If the item to which this location is attached cannot be
 436  *       attributed to a source line, pass 0 for the line and column.
 437  */
 438 LLVMMetadataRef
 439 LLVMDIBuilderCreateDebugLocation(LLVMContextRef Ctx, unsigned Line,
 440                                  unsigned Column, LLVMMetadataRef Scope,
 441                                  LLVMMetadataRef InlinedAt);
 442
 443 /**
 444  * Get the line number of this debug location.
 445  * \param Location     The debug location.
 446  *
 447  * @see DILocation::getLine()
 448  */
 449 unsigned LLVMDILocationGetLine(LLVMMetadataRef Location);
 450
 451 /**
 452  * Get the column number of this debug location.
 453  * \param Location     The debug location.
 454  *
 455  * @see DILocation::getColumn()
 456  */
 457 unsigned LLVMDILocationGetColumn(LLVMMetadataRef Location);
 458
 459 /**
 460  * Get the local scope associated with this debug location.
 461  * \param Location     The debug location.
 462  *
 463  * @see DILocation::getScope()
 464  */
 465 LLVMMetadataRef LLVMDILocationGetScope(LLVMMetadataRef Location);
 466
 467 /**
 468  * Get the "inline at" location associated with this debug location.
 469  * \param Location     The debug location.
 470  *
 471  * @see DILocation::getInlinedAt()
 472  */
 473 LLVMMetadataRef LLVMDILocationGetInlinedAt(LLVMMetadataRef Location);
 474
 475 /**
 476  * Get the metadata of the file associated with a given scope.
 477  * \param Scope     The scope object.
 478  *
 479  * @see DIScope::getFile()
 480  */
 481 LLVMMetadataRef LLVMDIScopeGetFile(LLVMMetadataRef Scope);
 482
 483 /**
 484  * Get the directory of a given file.
 485  * \param File     The file object.
 486  * \param Len      The length of the returned string.
 487  *
 488  * @see DIFile::getDirectory()
 489  */
 490 const char *LLVMDIFileGetDirectory(LLVMMetadataRef File, unsigned *Len);
 491
 492 /**
 493  * Get the name of a given file.
 494  * \param File     The file object.
 495  * \param Len      The length of the returned string.
 496  *
 497  * @see DIFile::getFilename()
 498  */
 499 const char *LLVMDIFileGetFilename(LLVMMetadataRef File, unsigned *Len);
 500
 501 /**
 502  * Get the source of a given file.
 503  * \param File     The file object.
 504  * \param Len      The length of the returned string.
 505  *
 506  * @see DIFile::getSource()
 507  */
 508 const char *LLVMDIFileGetSource(LLVMMetadataRef File, unsigned *Len);
 509
 510 /**
 511  * Create a type array.
 512  * \param Builder        The DIBuilder.
 513  * \param Data           The type elements.
 514  * \param NumElements    Number of type elements.
 515  */
 516 LLVMMetadataRef LLVMDIBuilderGetOrCreateTypeArray(LLVMDIBuilderRef Builder,
 517                                                   LLVMMetadataRef *Data,
 518                                                   size_t NumElements);
 519
 520 /**
 521  * Create subroutine type.
 522  * \param Builder        The DIBuilder.
 523  * \param File            The file in which the subroutine resides.
 524  * \param ParameterTypes  An array of subroutine parameter types. This
 525  *                        includes return type at 0th index.
 526  * \param NumParameterTypes The number of parameter types in \c ParameterTypes
 527  * \param Flags           E.g.: \c LLVMDIFlagLValueReference.
 528  *                        These flags are used to emit dwarf attributes.
 529  */
 530 LLVMMetadataRef
 531 LLVMDIBuilderCreateSubroutineType(LLVMDIBuilderRef Builder,
 532                                   LLVMMetadataRef File,
 533                                   LLVMMetadataRef *ParameterTypes,
 534                                   unsigned NumParameterTypes,
 535                                   LLVMDIFlags Flags);
 536
 537 /**
 538  * Create debugging information entry for a macro.
 539  * @param Builder         The DIBuilder.
 540  * @param ParentMacroFile Macro parent (could be NULL).
 541  * @param Line            Source line number where the macro is defined.
 542  * @param RecordType      DW_MACINFO_define or DW_MACINFO_undef.
 543  * @param Name            Macro name.
 544  * @param NameLen         Macro name length.
 545  * @param Value           Macro value.
 546  * @param ValueLen        Macro value length.
 547  */
 548 LLVMMetadataRef LLVMDIBuilderCreateMacro(LLVMDIBuilderRef Builder,
 549                                          LLVMMetadataRef ParentMacroFile,
 550                                          unsigned Line,
 551                                          LLVMDWARFMacinfoRecordType RecordType,
 552                                          const char *Name, size_t NameLen,
 553                                          const char *Value, size_t ValueLen);
 554
 555 /**
 556  * Create debugging information temporary entry for a macro file.
 557  * List of macro node direct children will be calculated by DIBuilder,
 558  * using the \p ParentMacroFile relationship.
 559  * @param Builder         The DIBuilder.
 560  * @param ParentMacroFile Macro parent (could be NULL).
 561  * @param Line            Source line number where the macro file is included.
 562  * @param File            File descriptor containing the name of the macro file.
 563  */
 564 LLVMMetadataRef
 565 LLVMDIBuilderCreateTempMacroFile(LLVMDIBuilderRef Builder,
 566                                  LLVMMetadataRef ParentMacroFile, unsigned Line,
 567                                  LLVMMetadataRef File);
 568
 569 /**
 570  * Create debugging information entry for an enumerator.
 571  * @param Builder        The DIBuilder.
 572  * @param Name           Enumerator name.
 573  * @param NameLen        Length of enumerator name.
 574  * @param Value          Enumerator value.
 575  * @param IsUnsigned     True if the value is unsigned.
 576  */
 577 LLVMMetadataRef LLVMDIBuilderCreateEnumerator(LLVMDIBuilderRef Builder,
 578                                               const char *Name, size_t NameLen,
 579                                               int64_t Value,
 580                                               LLVMBool IsUnsigned);
 581
 582 /**
 583  * Create debugging information entry for an enumeration.
 584  * \param Builder        The DIBuilder.
 585  * \param Scope          Scope in which this enumeration is defined.
 586  * \param Name           Enumeration name.
 587  * \param NameLen        Length of enumeration name.
 588  * \param File           File where this member is defined.
 589  * \param LineNumber     Line number.
 590  * \param SizeInBits     Member size.
 591  * \param AlignInBits    Member alignment.
 592  * \param Elements       Enumeration elements.
 593  * \param NumElements    Number of enumeration elements.
 594  * \param ClassTy        Underlying type of a C++11/ObjC fixed enum.
 595  */
 596 LLVMMetadataRef LLVMDIBuilderCreateEnumerationType(
 597     LLVMDIBuilderRef Builder, LLVMMetadataRef Scope, const char *Name,
 598     size_t NameLen, LLVMMetadataRef File, unsigned LineNumber,
 599     uint64_t SizeInBits, uint32_t AlignInBits, LLVMMetadataRef *Elements,
 600     unsigned NumElements, LLVMMetadataRef ClassTy);
 601
 602 /**
 603  * Create debugging information entry for a union.
 604  * \param Builder      The DIBuilder.
 605  * \param Scope        Scope in which this union is defined.
 606  * \param Name         Union name.
 607  * \param NameLen      Length of union name.
 608  * \param File         File where this member is defined.
 609  * \param LineNumber   Line number.
 610  * \param SizeInBits   Member size.
 611  * \param AlignInBits  Member alignment.
 612  * \param Flags        Flags to encode member attribute, e.g. private
 613  * \param Elements     Union elements.
 614  * \param NumElements  Number of union elements.
 615  * \param RunTimeLang  Optional parameter, Objective-C runtime version.
 616  * \param UniqueId     A unique identifier for the union.
 617  * \param UniqueIdLen  Length of unique identifier.
 618  */
 619 LLVMMetadataRef LLVMDIBuilderCreateUnionType(
 620     LLVMDIBuilderRef Builder, LLVMMetadataRef Scope, const char *Name,
 621     size_t NameLen, LLVMMetadataRef File, unsigned LineNumber,
 622     uint64_t SizeInBits, uint32_t AlignInBits, LLVMDIFlags Flags,
 623     LLVMMetadataRef *Elements, unsigned NumElements, unsigned RunTimeLang,
 624     const char *UniqueId, size_t UniqueIdLen);
 625
 626
 627 /**
 628  * Create debugging information entry for an array.
 629  * \param Builder      The DIBuilder.
 630  * \param Size         Array size.
 631  * \param AlignInBits  Alignment.
 632  * \param Ty           Element type.
 633  * \param Subscripts   Subscripts.
 634  * \param NumSubscripts Number of subscripts.
 635  */
 636 LLVMMetadataRef
 637 LLVMDIBuilderCreateArrayType(LLVMDIBuilderRef Builder, uint64_t Size,
 638                              uint32_t AlignInBits, LLVMMetadataRef Ty,
 639                              LLVMMetadataRef *Subscripts,
 640                              unsigned NumSubscripts);
 641
 642 /**
 643  * Create debugging information entry for a vector type.
 644  * \param Builder      The DIBuilder.
 645  * \param Size         Vector size.
 646  * \param AlignInBits  Alignment.
 647  * \param Ty           Element type.
 648  * \param Subscripts   Subscripts.
 649  * \param NumSubscripts Number of subscripts.
 650  */
 651 LLVMMetadataRef
 652 LLVMDIBuilderCreateVectorType(LLVMDIBuilderRef Builder, uint64_t Size,
 653                               uint32_t AlignInBits, LLVMMetadataRef Ty,
 654                               LLVMMetadataRef *Subscripts,
 655                               unsigned NumSubscripts);
 656
 657 /**
 658  * Create a DWARF unspecified type.
 659  * \param Builder   The DIBuilder.
 660  * \param Name      The unspecified type's name.
 661  * \param NameLen   Length of type name.
 662  */
 663 LLVMMetadataRef
 664 LLVMDIBuilderCreateUnspecifiedType(LLVMDIBuilderRef Builder, const char *Name,
 665                                    size_t NameLen);
 666
 667 /**
 668  * Create debugging information entry for a basic
 669  * type.
 670  * \param Builder     The DIBuilder.
 671  * \param Name        Type name.
 672  * \param NameLen     Length of type name.
 673  * \param SizeInBits  Size of the type.
 674  * \param Encoding    DWARF encoding code, e.g. \c LLVMDWARFTypeEncoding_float.
 675  * \param Flags       Flags to encode optional attribute like endianity
 676  */
 677 LLVMMetadataRef
 678 LLVMDIBuilderCreateBasicType(LLVMDIBuilderRef Builder, const char *Name,
 679                              size_t NameLen, uint64_t SizeInBits,
 680                              LLVMDWARFTypeEncoding Encoding,
 681                              LLVMDIFlags Flags);
 682
 683 /**
 684  * Create debugging information entry for a pointer.
 685  * \param Builder     The DIBuilder.
 686  * \param PointeeTy         Type pointed by this pointer.
 687  * \param SizeInBits        Size.
 688  * \param AlignInBits       Alignment. (optional, pass 0 to ignore)
 689  * \param AddressSpace      DWARF address space. (optional, pass 0 to ignore)
 690  * \param Name              Pointer type name. (optional)
 691  * \param NameLen           Length of pointer type name. (optional)
 692  */
 693 LLVMMetadataRef LLVMDIBuilderCreatePointerType(
 694     LLVMDIBuilderRef Builder, LLVMMetadataRef PointeeTy,
 695     uint64_t SizeInBits, uint32_t AlignInBits, unsigned AddressSpace,
 696     const char *Name, size_t NameLen);
 697
 698 /**
 699  * Create debugging information entry for a struct.
 700  * \param Builder     The DIBuilder.
 701  * \param Scope        Scope in which this struct is defined.
 702  * \param Name         Struct name.
 703  * \param NameLen      Struct name length.
 704  * \param File         File where this member is defined.
 705  * \param LineNumber   Line number.
 706  * \param SizeInBits   Member size.
 707  * \param AlignInBits  Member alignment.
 708  * \param Flags        Flags to encode member attribute, e.g. private
 709  * \param Elements     Struct elements.
 710  * \param NumElements  Number of struct elements.
 711  * \param RunTimeLang  Optional parameter, Objective-C runtime version.
 712  * \param VTableHolder The object containing the vtable for the struct.
 713  * \param UniqueId     A unique identifier for the struct.
 714  * \param UniqueIdLen  Length of the unique identifier for the struct.
 715  */
 716 LLVMMetadataRef LLVMDIBuilderCreateStructType(
 717     LLVMDIBuilderRef Builder, LLVMMetadataRef Scope, const char *Name,
 718     size_t NameLen, LLVMMetadataRef File, unsigned LineNumber,
 719     uint64_t SizeInBits, uint32_t AlignInBits, LLVMDIFlags Flags,
 720     LLVMMetadataRef DerivedFrom, LLVMMetadataRef *Elements,
 721     unsigned NumElements, unsigned RunTimeLang, LLVMMetadataRef VTableHolder,
 722     const char *UniqueId, size_t UniqueIdLen);
 723
 724 /**
 725  * Create debugging information entry for a member.
 726  * \param Builder      The DIBuilder.
 727  * \param Scope        Member scope.
 728  * \param Name         Member name.
 729  * \param NameLen      Length of member name.
 730  * \param File         File where this member is defined.
 731  * \param LineNo       Line number.
 732  * \param SizeInBits   Member size.
 733  * \param AlignInBits  Member alignment.
 734  * \param OffsetInBits Member offset.
 735  * \param Flags        Flags to encode member attribute, e.g. private
 736  * \param Ty           Parent type.
 737  */
 738 LLVMMetadataRef LLVMDIBuilderCreateMemberType(
 739     LLVMDIBuilderRef Builder, LLVMMetadataRef Scope, const char *Name,
 740     size_t NameLen, LLVMMetadataRef File, unsigned LineNo,
 741     uint64_t SizeInBits, uint32_t AlignInBits, uint64_t OffsetInBits,
 742     LLVMDIFlags Flags, LLVMMetadataRef Ty);
 743
 744 /**
 745  * Create debugging information entry for a
 746  * C++ static data member.
 747  * \param Builder      The DIBuilder.
 748  * \param Scope        Member scope.
 749  * \param Name         Member name.
 750  * \param NameLen      Length of member name.
 751  * \param File         File where this member is declared.
 752  * \param LineNumber   Line number.
 753  * \param Type         Type of the static member.
 754  * \param Flags        Flags to encode member attribute, e.g. private.
 755  * \param ConstantVal  Const initializer of the member.
 756  * \param AlignInBits  Member alignment.
 757  */
 758 LLVMMetadataRef
 759 LLVMDIBuilderCreateStaticMemberType(
 760     LLVMDIBuilderRef Builder, LLVMMetadataRef Scope, const char *Name,
 761     size_t NameLen, LLVMMetadataRef File, unsigned LineNumber,
 762     LLVMMetadataRef Type, LLVMDIFlags Flags, LLVMValueRef ConstantVal,
 763     uint32_t AlignInBits);
 764
 765 /**
 766  * Create debugging information entry for a pointer to member.
 767  * \param Builder      The DIBuilder.
 768  * \param PointeeType  Type pointed to by this pointer.
 769  * \param ClassType    Type for which this pointer points to members of.
 770  * \param SizeInBits   Size.
 771  * \param AlignInBits  Alignment.
 772  * \param Flags        Flags.
 773  */
 774 LLVMMetadataRef
 775 LLVMDIBuilderCreateMemberPointerType(LLVMDIBuilderRef Builder,
 776                                      LLVMMetadataRef PointeeType,
 777                                      LLVMMetadataRef ClassType,
 778                                      uint64_t SizeInBits,
 779                                      uint32_t AlignInBits,
 780                                      LLVMDIFlags Flags);
 781 /**
 782  * Create debugging information entry for Objective-C instance variable.
 783  * \param Builder      The DIBuilder.
 784  * \param Name         Member name.
 785  * \param NameLen      The length of the C string passed to \c Name.
 786  * \param File         File where this member is defined.
 787  * \param LineNo       Line number.
 788  * \param SizeInBits   Member size.
 789  * \param AlignInBits  Member alignment.
 790  * \param OffsetInBits Member offset.
 791  * \param Flags        Flags to encode member attribute, e.g. private
 792  * \param Ty           Parent type.
 793  * \param PropertyNode Property associated with this ivar.
 794  */
 795 LLVMMetadataRef
 796 LLVMDIBuilderCreateObjCIVar(LLVMDIBuilderRef Builder,
 797                             const char *Name, size_t NameLen,
 798                             LLVMMetadataRef File, unsigned LineNo,
 799                             uint64_t SizeInBits, uint32_t AlignInBits,
 800                             uint64_t OffsetInBits, LLVMDIFlags Flags,
 801                             LLVMMetadataRef Ty, LLVMMetadataRef PropertyNode);
 802
 803 /**
 804  * Create debugging information entry for Objective-C property.
 805  * \param Builder            The DIBuilder.
 806  * \param Name               Property name.
 807  * \param NameLen            The length of the C string passed to \c Name.
 808  * \param File               File where this property is defined.
 809  * \param LineNo             Line number.
 810  * \param GetterName         Name of the Objective C property getter selector.
 811  * \param GetterNameLen      The length of the C string passed to \c GetterName.
 812  * \param SetterName         Name of the Objective C property setter selector.
 813  * \param SetterNameLen      The length of the C string passed to \c SetterName.
 814  * \param PropertyAttributes Objective C property attributes.
 815  * \param Ty                 Type.
 816  */
 817 LLVMMetadataRef
 818 LLVMDIBuilderCreateObjCProperty(LLVMDIBuilderRef Builder,
 819                                 const char *Name, size_t NameLen,
 820                                 LLVMMetadataRef File, unsigned LineNo,
 821                                 const char *GetterName, size_t GetterNameLen,
 822                                 const char *SetterName, size_t SetterNameLen,
 823                                 unsigned PropertyAttributes,
 824                                 LLVMMetadataRef Ty);
 825
 826 /**
 827  * Create a uniqued DIType* clone with FlagObjectPointer and FlagArtificial set.
 828  * \param Builder   The DIBuilder.
 829  * \param Type      The underlying type to which this pointer points.
 830  */
 831 LLVMMetadataRef
 832 LLVMDIBuilderCreateObjectPointerType(LLVMDIBuilderRef Builder,
 833                                      LLVMMetadataRef Type);
 834
 835 /**
 836  * Create debugging information entry for a qualified
 837  * type, e.g. 'const int'.
 838  * \param Builder     The DIBuilder.
 839  * \param Tag         Tag identifying type,
 840  *                    e.g. LLVMDWARFTypeQualifier_volatile_type
 841  * \param Type        Base Type.
 842  */
 843 LLVMMetadataRef
 844 LLVMDIBuilderCreateQualifiedType(LLVMDIBuilderRef Builder, unsigned Tag,
 845                                  LLVMMetadataRef Type);
 846
 847 /**
 848  * Create debugging information entry for a c++
 849  * style reference or rvalue reference type.
 850  * \param Builder   The DIBuilder.
 851  * \param Tag       Tag identifying type,
 852  * \param Type      Base Type.
 853  */
 854 LLVMMetadataRef
 855 LLVMDIBuilderCreateReferenceType(LLVMDIBuilderRef Builder, unsigned Tag,
 856                                  LLVMMetadataRef Type);
 857
 858 /**
 859  * Create C++11 nullptr type.
 860  * \param Builder   The DIBuilder.
 861  */
 862 LLVMMetadataRef
 863 LLVMDIBuilderCreateNullPtrType(LLVMDIBuilderRef Builder);
 864
 865 /**
 866  * Create debugging information entry for a typedef.
 867  * \param Builder    The DIBuilder.
 868  * \param Type       Original type.
 869  * \param Name       Typedef name.
 870  * \param File       File where this type is defined.
 871  * \param LineNo     Line number.
 872  * \param Scope      The surrounding context for the typedef.
 873  */
 874 LLVMMetadataRef
 875 LLVMDIBuilderCreateTypedef(LLVMDIBuilderRef Builder, LLVMMetadataRef Type,
 876                            const char *Name, size_t NameLen,
 877                            LLVMMetadataRef File, unsigned LineNo,
 878                            LLVMMetadataRef Scope);
 879
 880 /**
 881  * Create debugging information entry to establish inheritance relationship
 882  * between two types.
 883  * \param Builder       The DIBuilder.
 884  * \param Ty            Original type.
 885  * \param BaseTy        Base type. Ty is inherits from base.
 886  * \param BaseOffset    Base offset.
 887  * \param VBPtrOffset  Virtual base pointer offset.
 888  * \param Flags         Flags to describe inheritance attribute, e.g. private
 889  */
 890 LLVMMetadataRef
 891 LLVMDIBuilderCreateInheritance(LLVMDIBuilderRef Builder,
 892                                LLVMMetadataRef Ty, LLVMMetadataRef BaseTy,
 893                                uint64_t BaseOffset, uint32_t VBPtrOffset,
 894                                LLVMDIFlags Flags);
 895
 896 /**
 897  * Create a permanent forward-declared type.
 898  * \param Builder             The DIBuilder.
 899  * \param Tag                 A unique tag for this type.
 900  * \param Name                Type name.
 901  * \param NameLen             Length of type name.
 902  * \param Scope               Type scope.
 903  * \param File                File where this type is defined.
 904  * \param Line                Line number where this type is defined.
 905  * \param RuntimeLang         Indicates runtime version for languages like
 906  *                            Objective-C.
 907  * \param SizeInBits          Member size.
 908  * \param AlignInBits         Member alignment.
 909  * \param UniqueIdentifier    A unique identifier for the type.
 910  * \param UniqueIdentifierLen Length of the unique identifier.
 911  */
 912 LLVMMetadataRef LLVMDIBuilderCreateForwardDecl(
 913     LLVMDIBuilderRef Builder, unsigned Tag, const char *Name,
 914     size_t NameLen, LLVMMetadataRef Scope, LLVMMetadataRef File, unsigned Line,
 915     unsigned RuntimeLang, uint64_t SizeInBits, uint32_t AlignInBits,
 916     const char *UniqueIdentifier, size_t UniqueIdentifierLen);
 917
 918 /**
 919  * Create a temporary forward-declared type.
 920  * \param Builder             The DIBuilder.
 921  * \param Tag                 A unique tag for this type.
 922  * \param Name                Type name.
 923  * \param NameLen             Length of type name.
 924  * \param Scope               Type scope.
 925  * \param File                File where this type is defined.
 926  * \param Line                Line number where this type is defined.
 927  * \param RuntimeLang         Indicates runtime version for languages like
 928  *                            Objective-C.
 929  * \param SizeInBits          Member size.
 930  * \param AlignInBits         Member alignment.
 931  * \param Flags               Flags.
 932  * \param UniqueIdentifier    A unique identifier for the type.
 933  * \param UniqueIdentifierLen Length of the unique identifier.
 934  */
 935 LLVMMetadataRef
 936 LLVMDIBuilderCreateReplaceableCompositeType(
 937     LLVMDIBuilderRef Builder, unsigned Tag, const char *Name,
 938     size_t NameLen, LLVMMetadataRef Scope, LLVMMetadataRef File, unsigned Line,
 939     unsigned RuntimeLang, uint64_t SizeInBits, uint32_t AlignInBits,
 940     LLVMDIFlags Flags, const char *UniqueIdentifier,
 941     size_t UniqueIdentifierLen);
 942
 943 /**
 944  * Create debugging information entry for a bit field member.
 945  * \param Builder             The DIBuilder.
 946  * \param Scope               Member scope.
 947  * \param Name                Member name.
 948  * \param NameLen             Length of member name.
 949  * \param File                File where this member is defined.
 950  * \param LineNumber          Line number.
 951  * \param SizeInBits          Member size.
 952  * \param OffsetInBits        Member offset.
 953  * \param StorageOffsetInBits Member storage offset.
 954  * \param Flags               Flags to encode member attribute.
 955  * \param Type                Parent type.
 956  */
 957 LLVMMetadataRef
 958 LLVMDIBuilderCreateBitFieldMemberType(LLVMDIBuilderRef Builder,
 959                                       LLVMMetadataRef Scope,
 960                                       const char *Name, size_t NameLen,
 961                                       LLVMMetadataRef File, unsigned LineNumber,
 962                                       uint64_t SizeInBits,
 963                                       uint64_t OffsetInBits,
 964                                       uint64_t StorageOffsetInBits,
 965                                       LLVMDIFlags Flags, LLVMMetadataRef Type);
 966
 967 /**
 968  * Create debugging information entry for a class.
 969  * \param Scope               Scope in which this class is defined.
 970  * \param Name                Class name.
 971  * \param NameLen             The length of the C string passed to \c Name.
 972  * \param File                File where this member is defined.
 973  * \param LineNumber          Line number.
 974  * \param SizeInBits          Member size.
 975  * \param AlignInBits         Member alignment.
 976  * \param OffsetInBits        Member offset.
 977  * \param Flags               Flags to encode member attribute, e.g. private.
 978  * \param DerivedFrom         Debug info of the base class of this type.
 979  * \param Elements            Class members.
 980  * \param NumElements         Number of class elements.
 981  * \param VTableHolder        Debug info of the base class that contains vtable
 982  *                            for this type. This is used in
 983  *                            DW_AT_containing_type. See DWARF documentation
 984  *                            for more info.
 985  * \param TemplateParamsNode  Template type parameters.
 986  * \param UniqueIdentifier    A unique identifier for the type.
 987  * \param UniqueIdentifierLen Length of the unique identifier.
 988  */
 989 LLVMMetadataRef LLVMDIBuilderCreateClassType(LLVMDIBuilderRef Builder,
 990     LLVMMetadataRef Scope, const char *Name, size_t NameLen,
 991     LLVMMetadataRef File, unsigned LineNumber, uint64_t SizeInBits,
 992     uint32_t AlignInBits, uint64_t OffsetInBits, LLVMDIFlags Flags,
 993     LLVMMetadataRef DerivedFrom,
 994     LLVMMetadataRef *Elements, unsigned NumElements,
 995     LLVMMetadataRef VTableHolder, LLVMMetadataRef TemplateParamsNode,
 996     const char *UniqueIdentifier, size_t UniqueIdentifierLen);
 997
 998 /**
 999  * Create a uniqued DIType* clone with FlagArtificial set.
1000  * \param Builder     The DIBuilder.
1001  * \param Type        The underlying type.
1002  */
1003 LLVMMetadataRef
1004 LLVMDIBuilderCreateArtificialType(LLVMDIBuilderRef Builder,
1005                                   LLVMMetadataRef Type);
1006
1007 /**
1008  * Get the name of this DIType.
1009  * \param DType     The DIType.
1010  * \param Length    The length of the returned string.
1011  *
1012  * @see DIType::getName()
1013  */
1014 const char *LLVMDITypeGetName(LLVMMetadataRef DType, size_t *Length);
1015
1016 /**
1017  * Get the size of this DIType in bits.
1018  * \param DType     The DIType.
1019  *
1020  * @see DIType::getSizeInBits()
1021  */
1022 uint64_t LLVMDITypeGetSizeInBits(LLVMMetadataRef DType);
1023
1024 /**
1025  * Get the offset of this DIType in bits.
1026  * \param DType     The DIType.
1027  *
1028  * @see DIType::getOffsetInBits()
1029  */
1030 uint64_t LLVMDITypeGetOffsetInBits(LLVMMetadataRef DType);
1031
1032 /**
1033  * Get the alignment of this DIType in bits.
1034  * \param DType     The DIType.
1035  *
1036  * @see DIType::getAlignInBits()
1037  */
1038 uint32_t LLVMDITypeGetAlignInBits(LLVMMetadataRef DType);
1039
1040 /**
1041  * Get the source line where this DIType is declared.
1042  * \param DType     The DIType.
1043  *
1044  * @see DIType::getLine()
1045  */
1046 unsigned LLVMDITypeGetLine(LLVMMetadataRef DType);
1047
1048 /**
1049  * Get the flags associated with this DIType.
1050  * \param DType     The DIType.
1051  *
1052  * @see DIType::getFlags()
1053  */
1054 LLVMDIFlags LLVMDITypeGetFlags(LLVMMetadataRef DType);
1055
1056 /**
1057  * Create a descriptor for a value range.
1058  * \param Builder    The DIBuilder.
1059  * \param LowerBound Lower bound of the subrange, e.g. 0 for C, 1 for Fortran.
1060  * \param Count      Count of elements in the subrange.
1061  */
1062 LLVMMetadataRef LLVMDIBuilderGetOrCreateSubrange(LLVMDIBuilderRef Builder,
1063                                                  int64_t LowerBound,
1064                                                  int64_t Count);
1065
1066 /**
1067  * Create an array of DI Nodes.
1068  * \param Builder        The DIBuilder.
1069  * \param Data           The DI Node elements.
1070  * \param NumElements    Number of DI Node elements.
1071  */
1072 LLVMMetadataRef LLVMDIBuilderGetOrCreateArray(LLVMDIBuilderRef Builder,
1073                                               LLVMMetadataRef *Data,
1074                                               size_t NumElements);
1075
1076 /**
1077  * Create a new descriptor for the specified variable which has a complex
1078  * address expression for its address.
1079  * \param Builder     The DIBuilder.
1080  * \param Addr        An array of complex address operations.
1081  * \param Length      Length of the address operation array.
1082  */
1083 LLVMMetadataRef LLVMDIBuilderCreateExpression(LLVMDIBuilderRef Builder,
1084                                               int64_t *Addr, size_t Length);
1085
1086 /**
1087  * Create a new descriptor for the specified variable that does not have an
1088  * address, but does have a constant value.
1089  * \param Builder     The DIBuilder.
1090  * \param Value       The constant value.
1091  */
1092 LLVMMetadataRef
1093 LLVMDIBuilderCreateConstantValueExpression(LLVMDIBuilderRef Builder,
1094                                            int64_t Value);
1095
1096 /**
1097  * Create a new descriptor for the specified variable.
1098  * \param Scope       Variable scope.
1099  * \param Name        Name of the variable.
1100  * \param NameLen     The length of the C string passed to \c Name.
1101  * \param Linkage     Mangled  name of the variable.
1102  * \param LinkLen     The length of the C string passed to \c Linkage.
1103  * \param File        File where this variable is defined.
1104  * \param LineNo      Line number.
1105  * \param Ty          Variable Type.
1106  * \param LocalToUnit Boolean flag indicate whether this variable is
1107  *                    externally visible or not.
1108  * \param Expr        The location of the global relative to the attached
1109  *                    GlobalVariable.
1110  * \param Decl        Reference to the corresponding declaration.
1111  *                    variables.
1112  * \param AlignInBits Variable alignment(or 0 if no alignment attr was
1113  *                    specified)
1114  */
1115 LLVMMetadataRef LLVMDIBuilderCreateGlobalVariableExpression(
1116     LLVMDIBuilderRef Builder, LLVMMetadataRef Scope, const char *Name,
1117     size_t NameLen, const char *Linkage, size_t LinkLen, LLVMMetadataRef File,
1118     unsigned LineNo, LLVMMetadataRef Ty, LLVMBool LocalToUnit,
1119     LLVMMetadataRef Expr, LLVMMetadataRef Decl, uint32_t AlignInBits);
1120
1121 /**
1122  * Retrieves the \c DIVariable associated with this global variable expression.
1123  * \param GVE    The global variable expression.
1124  *
1125  * @see llvm::DIGlobalVariableExpression::getVariable()
1126  */
1127 LLVMMetadataRef LLVMDIGlobalVariableExpressionGetVariable(LLVMMetadataRef GVE);
1128
1129 /**
1130  * Retrieves the \c DIExpression associated with this global variable expression.
1131  * \param GVE    The global variable expression.
1132  *
1133  * @see llvm::DIGlobalVariableExpression::getExpression()
1134  */
1135 LLVMMetadataRef LLVMDIGlobalVariableExpressionGetExpression(
1136     LLVMMetadataRef GVE);
1137
1138 /**
1139  * Get the metadata of the file associated with a given variable.
1140  * \param Var     The variable object.
1141  *
1142  * @see DIVariable::getFile()
1143  */
1144 LLVMMetadataRef LLVMDIVariableGetFile(LLVMMetadataRef Var);
1145
1146 /**
1147  * Get the metadata of the scope associated with a given variable.
1148  * \param Var     The variable object.
1149  *
1150  * @see DIVariable::getScope()
1151  */
1152 LLVMMetadataRef LLVMDIVariableGetScope(LLVMMetadataRef Var);
1153
1154 /**
1155  * Get the source line where this \c DIVariable is declared.
1156  * \param Var     The DIVariable.
1157  *
1158  * @see DIVariable::getLine()
1159  */
1160 unsigned LLVMDIVariableGetLine(LLVMMetadataRef Var);
1161
1162 /**
1163  * Create a new temporary \c MDNode.  Suitable for use in constructing cyclic
1164  * \c MDNode structures. A temporary \c MDNode is not uniqued, may be RAUW'd,
1165  * and must be manually deleted with \c LLVMDisposeTemporaryMDNode.
1166  * \param Ctx            The context in which to construct the temporary node.
1167  * \param Data           The metadata elements.
1168  * \param NumElements    Number of metadata elements.
1169  */
1170 LLVMMetadataRef LLVMTemporaryMDNode(LLVMContextRef Ctx, LLVMMetadataRef *Data,
1171                                     size_t NumElements);
1172
1173 /**
1174  * Deallocate a temporary node.
1175  *
1176  * Calls \c replaceAllUsesWith(nullptr) before deleting, so any remaining
1177  * references will be reset.
1178  * \param TempNode    The temporary metadata node.
1179  */
1180 void LLVMDisposeTemporaryMDNode(LLVMMetadataRef TempNode);
1181
1182 /**
1183  * Replace all uses of temporary metadata.
1184  * \param TempTargetMetadata    The temporary metadata node.
1185  * \param Replacement           The replacement metadata node.
1186  */
1187 void LLVMMetadataReplaceAllUsesWith(LLVMMetadataRef TempTargetMetadata,
1188                                     LLVMMetadataRef Replacement);
1189
1190 /**
1191  * Create a new descriptor for the specified global variable that is temporary
1192  * and meant to be RAUWed.
1193  * \param Scope       Variable scope.
1194  * \param Name        Name of the variable.
1195  * \param NameLen     The length of the C string passed to \c Name.
1196  * \param Linkage     Mangled  name of the variable.
1197  * \param LnkLen      The length of the C string passed to \c Linkage.
1198  * \param File        File where this variable is defined.
1199  * \param LineNo      Line number.
1200  * \param Ty          Variable Type.
1201  * \param LocalToUnit Boolean flag indicate whether this variable is
1202  *                    externally visible or not.
1203  * \param Decl        Reference to the corresponding declaration.
1204  * \param AlignInBits Variable alignment(or 0 if no alignment attr was
1205  *                    specified)
1206  */
1207 LLVMMetadataRef LLVMDIBuilderCreateTempGlobalVariableFwdDecl(
1208     LLVMDIBuilderRef Builder, LLVMMetadataRef Scope, const char *Name,
1209     size_t NameLen, const char *Linkage, size_t LnkLen, LLVMMetadataRef File,
1210     unsigned LineNo, LLVMMetadataRef Ty, LLVMBool LocalToUnit,
1211     LLVMMetadataRef Decl, uint32_t AlignInBits);
1212
1213 /**
1214  * Insert a new llvm.dbg.declare intrinsic call before the given instruction.
1215  * \param Builder     The DIBuilder.
1216  * \param Storage     The storage of the variable to declare.
1217  * \param VarInfo     The variable's debug info descriptor.
1218  * \param Expr        A complex location expression for the variable.
1219  * \param DebugLoc    Debug info location.
1220  * \param Instr       Instruction acting as a location for the new intrinsic.
1221  */
1222 LLVMValueRef LLVMDIBuilderInsertDeclareBefore(
1223   LLVMDIBuilderRef Builder, LLVMValueRef Storage, LLVMMetadataRef VarInfo,
1224   LLVMMetadataRef Expr, LLVMMetadataRef DebugLoc, LLVMValueRef Instr);
1225
1226 /**
1227  * Insert a new llvm.dbg.declare intrinsic call at the end of the given basic
1228  * block. If the basic block has a terminator instruction, the intrinsic is
1229  * inserted before that terminator instruction.
1230  * \param Builder     The DIBuilder.
1231  * \param Storage     The storage of the variable to declare.
1232  * \param VarInfo     The variable's debug info descriptor.
1233  * \param Expr        A complex location expression for the variable.
1234  * \param DebugLoc    Debug info location.
1235  * \param Block       Basic block acting as a location for the new intrinsic.
1236  */
1237 LLVMValueRef LLVMDIBuilderInsertDeclareAtEnd(
1238     LLVMDIBuilderRef Builder, LLVMValueRef Storage, LLVMMetadataRef VarInfo,
1239     LLVMMetadataRef Expr, LLVMMetadataRef DebugLoc, LLVMBasicBlockRef Block);
1240
1241 /**
1242  * Insert a new llvm.dbg.value intrinsic call before the given instruction.
1243  * \param Builder     The DIBuilder.
1244  * \param Val         The value of the variable.
1245  * \param VarInfo     The variable's debug info descriptor.
1246  * \param Expr        A complex location expression for the variable.
1247  * \param DebugLoc    Debug info location.
1248  * \param Instr       Instruction acting as a location for the new intrinsic.
1249  */
1250 LLVMValueRef LLVMDIBuilderInsertDbgValueBefore(LLVMDIBuilderRef Builder,
1251                                                LLVMValueRef Val,
1252                                                LLVMMetadataRef VarInfo,
1253                                                LLVMMetadataRef Expr,
1254                                                LLVMMetadataRef DebugLoc,
1255                                                LLVMValueRef Instr);
1256
1257 /**
1258  * Insert a new llvm.dbg.value intrinsic call at the end of the given basic
1259  * block. If the basic block has a terminator instruction, the intrinsic is
1260  * inserted before that terminator instruction.
1261  * \param Builder     The DIBuilder.
1262  * \param Val         The value of the variable.
1263  * \param VarInfo     The variable's debug info descriptor.
1264  * \param Expr        A complex location expression for the variable.
1265  * \param DebugLoc    Debug info location.
1266  * \param Block       Basic block acting as a location for the new intrinsic.
1267  */
1268 LLVMValueRef LLVMDIBuilderInsertDbgValueAtEnd(LLVMDIBuilderRef Builder,
1269                                               LLVMValueRef Val,
1270                                               LLVMMetadataRef VarInfo,
1271                                               LLVMMetadataRef Expr,
1272                                               LLVMMetadataRef DebugLoc,
1273                                               LLVMBasicBlockRef Block);
1274
1275 /**
1276  * Create a new descriptor for a local auto variable.
1277  * \param Builder         The DIBuilder.
1278  * \param Scope           The local scope the variable is declared in.
1279  * \param Name            Variable name.
1280  * \param NameLen         Length of variable name.
1281  * \param File            File where this variable is defined.
1282  * \param LineNo          Line number.
1283  * \param Ty              Metadata describing the type of the variable.
1284  * \param AlwaysPreserve  If true, this descriptor will survive optimizations.
1285  * \param Flags           Flags.
1286  * \param AlignInBits     Variable alignment.
1287  */
1288 LLVMMetadataRef LLVMDIBuilderCreateAutoVariable(
1289     LLVMDIBuilderRef Builder, LLVMMetadataRef Scope, const char *Name,
1290     size_t NameLen, LLVMMetadataRef File, unsigned LineNo, LLVMMetadataRef Ty,
1291     LLVMBool AlwaysPreserve, LLVMDIFlags Flags, uint32_t AlignInBits);
1292
1293 /**
1294  * Create a new descriptor for a function parameter variable.
1295  * \param Builder         The DIBuilder.
1296  * \param Scope           The local scope the variable is declared in.
1297  * \param Name            Variable name.
1298  * \param NameLen         Length of variable name.
1299  * \param ArgNo           Unique argument number for this variable; starts at 1.
1300  * \param File            File where this variable is defined.
1301  * \param LineNo          Line number.
1302  * \param Ty              Metadata describing the type of the variable.
1303  * \param AlwaysPreserve  If true, this descriptor will survive optimizations.
1304  * \param Flags           Flags.
1305  */
1306 LLVMMetadataRef LLVMDIBuilderCreateParameterVariable(
1307     LLVMDIBuilderRef Builder, LLVMMetadataRef Scope, const char *Name,
1308     size_t NameLen, unsigned ArgNo, LLVMMetadataRef File, unsigned LineNo,
1309     LLVMMetadataRef Ty, LLVMBool AlwaysPreserve, LLVMDIFlags Flags);
1310
1311 /**
1312  * Get the metadata of the subprogram attached to a function.
1313  *
1314  * @see llvm::Function::getSubprogram()
1315  */
1316 LLVMMetadataRef LLVMGetSubprogram(LLVMValueRef Func);
1317
1318 /**
1319  * Set the subprogram attached to a function.
1320  *
1321  * @see llvm::Function::setSubprogram()
1322  */
1323 void LLVMSetSubprogram(LLVMValueRef Func, LLVMMetadataRef SP);
1324
1325 /**
1326  * Get the line associated with a given subprogram.
1327  * \param Subprogram     The subprogram object.
1328  *
1329  * @see DISubprogram::getLine()
1330  */
1331 unsigned LLVMDISubprogramGetLine(LLVMMetadataRef Subprogram);
1332
1333 /**
1334  * Get the debug location for the given instruction.
1335  *
1336  * @see llvm::Instruction::getDebugLoc()
1337  */
1338 LLVMMetadataRef LLVMInstructionGetDebugLoc(LLVMValueRef Inst);
1339
1340 /**
1341  * Set the debug location for the given instruction.
1342  *
1343  * To clear the location metadata of the given instruction, pass NULL to \p Loc.
1344  *
1345  * @see llvm::Instruction::setDebugLoc()
1346  */
1347 void LLVMInstructionSetDebugLoc(LLVMValueRef Inst, LLVMMetadataRef Loc);
1348
1349 /**
1350  * Obtain the enumerated type of a Metadata instance.
1351  *
1352  * @see llvm::Metadata::getMetadataID()
1353  */
1354 LLVMMetadataKind LLVMGetMetadataKind(LLVMMetadataRef Metadata);
1355
1356 #ifdef __cplusplus
1357 } /* end extern "C" */
1358 #endif
1359
1360 #endif