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