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