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