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