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
233