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