contrib/llvm/include/llvm-c/DebugInfo.h

   1 //===------------ DebugInfo.h - LLVM C API Debug Info API -----------------===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 ///
  10 /// This file declares the C API endpoints for generating DWARF Debug Info
  11 ///
  12 /// Note: This interface is experimental. It is *NOT* stable, and may be
  13 ///       changed without warning.
  14 ///
  15 //===----------------------------------------------------------------------===//
  16
  17 #ifndef LLVM_C_DEBUGINFO_H
  18 #define LLVM_C_DEBUGINFO_H
  19
  20 #include "llvm-c/Core.h"
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 /**
  27  * Debug info flags.
  28  */
  29 typedef enum {
  30   LLVMDIFlagZero = 0,
  31   LLVMDIFlagPrivate = 1,
  32   LLVMDIFlagProtected = 2,
  33   LLVMDIFlagPublic = 3,
  34   LLVMDIFlagFwdDecl = 1 << 2,
  35   LLVMDIFlagAppleBlock = 1 << 3,
  36   LLVMDIFlagBlockByrefStruct = 1 << 4,
  37   LLVMDIFlagVirtual = 1 << 5,
  38   LLVMDIFlagArtificial = 1 << 6,
  39   LLVMDIFlagExplicit = 1 << 7,
  40   LLVMDIFlagPrototyped = 1 << 8,
  41   LLVMDIFlagObjcClassComplete = 1 << 9,
  42   LLVMDIFlagObjectPointer = 1 << 10,
  43   LLVMDIFlagVector = 1 << 11,
  44   LLVMDIFlagStaticMember = 1 << 12,
  45   LLVMDIFlagLValueReference = 1 << 13,
  46   LLVMDIFlagRValueReference = 1 << 14,
  47   LLVMDIFlagReserved = 1 << 15,
  48   LLVMDIFlagSingleInheritance = 1 << 16,
  49   LLVMDIFlagMultipleInheritance = 2 << 16,
  50   LLVMDIFlagVirtualInheritance = 3 << 16,
  51   LLVMDIFlagIntroducedVirtual = 1 << 18,
  52   LLVMDIFlagBitField = 1 << 19,
  53   LLVMDIFlagNoReturn = 1 << 20,
  54   LLVMDIFlagMainSubprogram = 1 << 21,
  55   LLVMDIFlagIndirectVirtualBase = (1 << 2) | (1 << 5),
  56   LLVMDIFlagAccessibility = LLVMDIFlagPrivate | LLVMDIFlagProtected |
  57                             LLVMDIFlagPublic,
  58   LLVMDIFlagPtrToMemberRep = LLVMDIFlagSingleInheritance |
  59                              LLVMDIFlagMultipleInheritance |
  60                              LLVMDIFlagVirtualInheritance
  61 } LLVMDIFlags;
  62
  63 /**
  64  * Source languages known by DWARF.
  65  */
  66 typedef enum {
  67   LLVMDWARFSourceLanguageC89,
  68   LLVMDWARFSourceLanguageC,
  69   LLVMDWARFSourceLanguageAda83,
  70   LLVMDWARFSourceLanguageC_plus_plus,
  71   LLVMDWARFSourceLanguageCobol74,
  72   LLVMDWARFSourceLanguageCobol85,
  73   LLVMDWARFSourceLanguageFortran77,
  74   LLVMDWARFSourceLanguageFortran90,
  75   LLVMDWARFSourceLanguagePascal83,
  76   LLVMDWARFSourceLanguageModula2,
  77   // New in DWARF v3:
  78   LLVMDWARFSourceLanguageJava,
  79   LLVMDWARFSourceLanguageC99,
  80   LLVMDWARFSourceLanguageAda95,
  81   LLVMDWARFSourceLanguageFortran95,
  82   LLVMDWARFSourceLanguagePLI,
  83   LLVMDWARFSourceLanguageObjC,
  84   LLVMDWARFSourceLanguageObjC_plus_plus,
  85   LLVMDWARFSourceLanguageUPC,
  86   LLVMDWARFSourceLanguageD,
  87   // New in DWARF v4:
  88   LLVMDWARFSourceLanguagePython,
  89   // New in DWARF v5:
  90   LLVMDWARFSourceLanguageOpenCL,
  91   LLVMDWARFSourceLanguageGo,
  92   LLVMDWARFSourceLanguageModula3,
  93   LLVMDWARFSourceLanguageHaskell,
  94   LLVMDWARFSourceLanguageC_plus_plus_03,
  95   LLVMDWARFSourceLanguageC_plus_plus_11,
  96   LLVMDWARFSourceLanguageOCaml,
  97   LLVMDWARFSourceLanguageRust,
  98   LLVMDWARFSourceLanguageC11,
  99   LLVMDWARFSourceLanguageSwift,
 100   LLVMDWARFSourceLanguageJulia,
 101   LLVMDWARFSourceLanguageDylan,
 102   LLVMDWARFSourceLanguageC_plus_plus_14,
 103   LLVMDWARFSourceLanguageFortran03,
 104   LLVMDWARFSourceLanguageFortran08,
 105   LLVMDWARFSourceLanguageRenderScript,
 106   LLVMDWARFSourceLanguageBLISS,
 107   // Vendor extensions:
 108   LLVMDWARFSourceLanguageMips_Assembler,
 109   LLVMDWARFSourceLanguageGOOGLE_RenderScript,
 110   LLVMDWARFSourceLanguageBORLAND_Delphi
 111 } LLVMDWARFSourceLanguage;
 112
 113 /**
 114  * The amount of debug information to emit.
 115  */
 116 typedef enum {
 117     LLVMDWARFEmissionNone = 0,
 118     LLVMDWARFEmissionFull,
 119     LLVMDWARFEmissionLineTablesOnly
 120 } LLVMDWARFEmissionKind;
 121
 122 /**
 123  * The current debug metadata version number.
 124  */
 125 unsigned LLVMDebugMetadataVersion(void);
 126
 127 /**
 128  * The version of debug metadata that's present in the provided \c Module.
 129  */
 130 unsigned LLVMGetModuleDebugMetadataVersion(LLVMModuleRef Module);
 131
 132 /**
 133  * Strip debug info in the module if it exists.
 134  * To do this, we remove all calls to the debugger intrinsics and any named
 135  * metadata for debugging. We also remove debug locations for instructions.
 136  * Return true if module is modified.
 137  */
 138 LLVMBool LLVMStripModuleDebugInfo(LLVMModuleRef Module);
 139
 140 /**
 141  * Construct a builder for a module, and do not allow for unresolved nodes
 142  * attached to the module.
 143  */
 144 LLVMDIBuilderRef LLVMCreateDIBuilderDisallowUnresolved(LLVMModuleRef M);
 145
 146 /**
 147  * Construct a builder for a module and collect unresolved nodes attached
 148  * to the module in order to resolve cycles during a call to
 149  * \c LLVMDIBuilderFinalize.
 150  */
 151 LLVMDIBuilderRef LLVMCreateDIBuilder(LLVMModuleRef M);
 152
 153 /**
 154  * Deallocates the \c DIBuilder and everything it owns.
 155  * @note You must call \c LLVMDIBuilderFinalize before this
 156  */
 157 void LLVMDisposeDIBuilder(LLVMDIBuilderRef Builder);
 158
 159 /**
 160  * Construct any deferred debug info descriptors.
 161  */
 162 void LLVMDIBuilderFinalize(LLVMDIBuilderRef Builder);
 163
 164 /**
 165  * A CompileUnit provides an anchor for all debugging
 166  * information generated during this instance of compilation.
 167  * \param Lang          Source programming language, eg.
 168  *                      \c LLVMDWARFSourceLanguageC99
 169  * \param FileRef       File info.
 170  * \param Producer      Identify the producer of debugging information
 171  *                      and code.  Usually this is a compiler
 172  *                      version string.
 173  * \param ProducerLen   The length of the C string passed to \c Producer.
 174  * \param isOptimized   A boolean flag which indicates whether optimization
 175  *                      is enabled or not.
 176  * \param Flags         This string lists command line options. This
 177  *                      string is directly embedded in debug info
 178  *                      output which may be used by a tool
 179  *                      analyzing generated debugging information.
 180  * \param FlagsLen      The length of the C string passed to \c Flags.
 181  * \param RuntimeVer    This indicates runtime version for languages like
 182  *                      Objective-C.
 183  * \param SplitName     The name of the file that we'll split debug info
 184  *                      out into.
 185  * \param SplitNameLen  The length of the C string passed to \c SplitName.
 186  * \param Kind          The kind of debug information to generate.
 187  * \param DWOId         The DWOId if this is a split skeleton compile unit.
 188  * \param SplitDebugInlining    Whether to emit inline debug info.
 189  * \param DebugInfoForProfiling Whether to emit extra debug info for
 190  *                              profile collection.
 191  */
 192 LLVMMetadataRef LLVMDIBuilderCreateCompileUnit(
 193     LLVMDIBuilderRef Builder, LLVMDWARFSourceLanguage Lang,
 194     LLVMMetadataRef FileRef, const char *Producer, size_t ProducerLen,
 195     LLVMBool isOptimized, const char *Flags, size_t FlagsLen,
 196     unsigned RuntimeVer, const char *SplitName, size_t SplitNameLen,
 197     LLVMDWARFEmissionKind Kind, unsigned DWOId, LLVMBool SplitDebugInlining,
 198     LLVMBool DebugInfoForProfiling);
 199
 200 /**
 201  * Create a file descriptor to hold debugging information for a file.
 202  * \param Builder      The \c DIBuilder.
 203  * \param Filename     File name.
 204  * \param FilenameLen  The length of the C string passed to \c Filename.
 205  * \param Directory    Directory.
 206  * \param DirectoryLen The length of the C string passed to \c Directory.
 207  */
 208 LLVMMetadataRef
 209 LLVMDIBuilderCreateFile(LLVMDIBuilderRef Builder, const char *Filename,
 210                         size_t FilenameLen, const char *Directory,
 211                         size_t DirectoryLen);
 212
 213 /**
 214  * Creates a new DebugLocation that describes a source location.
 215  * \param Line The line in the source file.
 216  * \param Column The column in the source file.
 217  * \param Scope The scope in which the location resides.
 218  * \param InlinedAt The scope where this location was inlined, if at all.
 219  *                  (optional).
 220  * \note If the item to which this location is attached cannot be
 221  *       attributed to a source line, pass 0 for the line and column.
 222  */
 223 LLVMMetadataRef
 224 LLVMDIBuilderCreateDebugLocation(LLVMContextRef Ctx, unsigned Line,
 225                                  unsigned Column, LLVMMetadataRef Scope,
 226                                  LLVMMetadataRef InlinedAt);
 227
 228 #ifdef __cplusplus
 229 } /* end extern "C" */
 230 #endif
 231
 232 #endif