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