• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 //===--- llvm/Analysis/DIBuilder.h - Debug Information Builder --*- C++ -*-===//
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 defines a DIBuilder that is useful for creating debugging
11 // information entries in LLVM IR form.
12 //
13 //===----------------------------------------------------------------------===//
14 
15 #ifndef LLVM_ANALYSIS_DIBUILDER_H
16 #define LLVM_ANALYSIS_DIBUILDER_H
17 
18 #include "llvm/Support/DataTypes.h"
19 #include "llvm/ADT/ArrayRef.h"
20 #include "llvm/ADT/StringRef.h"
21 
22 namespace llvm {
23   class BasicBlock;
24   class Instruction;
25   class Function;
26   class Module;
27   class Value;
28   class LLVMContext;
29   class MDNode;
30   class StringRef;
31   class DIDescriptor;
32   class DIFile;
33   class DIEnumerator;
34   class DIType;
35   class DIArray;
36   class DIGlobalVariable;
37   class DINameSpace;
38   class DIVariable;
39   class DISubrange;
40   class DILexicalBlockFile;
41   class DILexicalBlock;
42   class DISubprogram;
43   class DITemplateTypeParameter;
44   class DITemplateValueParameter;
45 
46   class DIBuilder {
47     private:
48     Module &M;
49     LLVMContext & VMContext;
50     MDNode *TheCU;
51 
52     MDNode *TempEnumTypes;
53     MDNode *TempRetainTypes;
54     MDNode *TempSubprograms;
55     MDNode *TempGVs;
56 
57     Function *DeclareFn;     // llvm.dbg.declare
58     Function *ValueFn;       // llvm.dbg.value
59 
60     SmallVector<Value *, 4> AllEnumTypes;
61     SmallVector<Value *, 4> AllRetainTypes;
62     SmallVector<Value *, 4> AllSubprograms;
63     SmallVector<Value *, 4> AllGVs;
64 
65     DIBuilder(const DIBuilder &);       // DO NOT IMPLEMENT
66     void operator=(const DIBuilder &);  // DO NOT IMPLEMENT
67 
68     public:
69     explicit DIBuilder(Module &M);
getCU()70     const MDNode *getCU() { return TheCU; }
71     enum ComplexAddrKind { OpPlus=1, OpDeref };
72 
73     /// finalize - Construct any deferred debug info descriptors.
74     void finalize();
75 
76     /// createCompileUnit - A CompileUnit provides an anchor for all debugging
77     /// information generated during this instance of compilation.
78     /// @param Lang     Source programming language, eg. dwarf::DW_LANG_C99
79     /// @param File     File name
80     /// @param Dir      Directory
81     /// @param Producer String identify producer of debugging information.
82     ///                 Usuall this is a compiler version string.
83     /// @param isOptimized A boolean flag which indicates whether optimization
84     ///                    is ON or not.
85     /// @param Flags    This string lists command line options. This string is
86     ///                 directly embedded in debug info output which may be used
87     ///                 by a tool analyzing generated debugging information.
88     /// @param RV       This indicates runtime version for languages like
89     ///                 Objective-C.
90     void createCompileUnit(unsigned Lang, StringRef File, StringRef Dir,
91                            StringRef Producer,
92                            bool isOptimized, StringRef Flags, unsigned RV);
93 
94     /// createFile - Create a file descriptor to hold debugging information
95     /// for a file.
96     DIFile createFile(StringRef Filename, StringRef Directory);
97 
98     /// createEnumerator - Create a single enumerator value.
99     DIEnumerator createEnumerator(StringRef Name, uint64_t Val);
100 
101     /// createNullPtrType - Create C++0x nullptr type.
102     DIType createNullPtrType(StringRef Name);
103 
104     /// createBasicType - Create debugging information entry for a basic
105     /// type.
106     /// @param Name        Type name.
107     /// @param SizeInBits  Size of the type.
108     /// @param AlignInBits Type alignment.
109     /// @param Encoding    DWARF encoding code, e.g. dwarf::DW_ATE_float.
110     DIType createBasicType(StringRef Name, uint64_t SizeInBits,
111                            uint64_t AlignInBits, unsigned Encoding);
112 
113     /// createQualifiedType - Create debugging information entry for a qualified
114     /// type, e.g. 'const int'.
115     /// @param Tag         Tag identifing type, e.g. dwarf::TAG_volatile_type
116     /// @param FromTy      Base Type.
117     DIType createQualifiedType(unsigned Tag, DIType FromTy);
118 
119     /// createPointerType - Create debugging information entry for a pointer.
120     /// @param PointeeTy   Type pointed by this pointer.
121     /// @param SizeInBits  Size.
122     /// @param AlignInBits Alignment. (optional)
123     /// @param Name        Pointer type name. (optional)
124     DIType createPointerType(DIType PointeeTy, uint64_t SizeInBits,
125                              uint64_t AlignInBits = 0,
126                              StringRef Name = StringRef());
127 
128     /// createReferenceType - Create debugging information entry for a c++
129     /// style reference.
130     DIType createReferenceType(DIType RTy);
131 
132     /// createTypedef - Create debugging information entry for a typedef.
133     /// @param Ty          Original type.
134     /// @param Name        Typedef name.
135     /// @param File        File where this type is defined.
136     /// @param LineNo      Line number.
137     /// @param Context     The surrounding context for the typedef.
138     DIType createTypedef(DIType Ty, StringRef Name, DIFile File,
139                          unsigned LineNo, DIDescriptor Context);
140 
141     /// createFriend - Create debugging information entry for a 'friend'.
142     DIType createFriend(DIType Ty, DIType FriendTy);
143 
144     /// createInheritance - Create debugging information entry to establish
145     /// inheritance relationship between two types.
146     /// @param Ty           Original type.
147     /// @param BaseTy       Base type. Ty is inherits from base.
148     /// @param BaseOffset   Base offset.
149     /// @param Flags        Flags to describe inheritance attribute,
150     ///                     e.g. private
151     DIType createInheritance(DIType Ty, DIType BaseTy, uint64_t BaseOffset,
152                              unsigned Flags);
153 
154     /// createMemberType - Create debugging information entry for a member.
155     /// @param Scope        Member scope.
156     /// @param Name         Member name.
157     /// @param File         File where this member is defined.
158     /// @param LineNo       Line number.
159     /// @param SizeInBits   Member size.
160     /// @param AlignInBits  Member alignment.
161     /// @param OffsetInBits Member offset.
162     /// @param Flags        Flags to encode member attribute, e.g. private
163     /// @param Ty           Parent type.
164     DIType createMemberType(DIDescriptor Scope, StringRef Name, DIFile File,
165                             unsigned LineNo, uint64_t SizeInBits,
166                             uint64_t AlignInBits, uint64_t OffsetInBits,
167                             unsigned Flags, DIType Ty);
168 
169     /// createObjCIVar - Create debugging information entry for Objective-C
170     /// instance variable.
171     /// @param Name         Member name.
172     /// @param File         File where this member is defined.
173     /// @param LineNo       Line number.
174     /// @param SizeInBits   Member size.
175     /// @param AlignInBits  Member alignment.
176     /// @param OffsetInBits Member offset.
177     /// @param Flags        Flags to encode member attribute, e.g. private
178     /// @param Ty           Parent type.
179     /// @param PropertyName Name of the Objective C property assoicated with
180     ///                     this ivar.
181     /// @param GetterName   Name of the Objective C property getter selector.
182     /// @param SetterName   Name of the Objective C property setter selector.
183     /// @param PropertyAttributes Objective C property attributes.
184     DIType createObjCIVar(StringRef Name, DIFile File,
185                           unsigned LineNo, uint64_t SizeInBits,
186                           uint64_t AlignInBits, uint64_t OffsetInBits,
187                           unsigned Flags, DIType Ty,
188                           StringRef PropertyName = StringRef(),
189                           StringRef PropertyGetterName = StringRef(),
190                           StringRef PropertySetterName = StringRef(),
191                           unsigned PropertyAttributes = 0);
192 
193     /// createClassType - Create debugging information entry for a class.
194     /// @param Scope        Scope in which this class is defined.
195     /// @param Name         class name.
196     /// @param File         File where this member is defined.
197     /// @param LineNo       Line number.
198     /// @param SizeInBits   Member size.
199     /// @param AlignInBits  Member alignment.
200     /// @param OffsetInBits Member offset.
201     /// @param Flags        Flags to encode member attribute, e.g. private
202     /// @param Elements     class members.
203     /// @param VTableHolder Debug info of the base class that contains vtable
204     ///                     for this type. This is used in
205     ///                     DW_AT_containing_type. See DWARF documentation
206     ///                     for more info.
207     /// @param TemplateParms Template type parameters.
208     DIType createClassType(DIDescriptor Scope, StringRef Name, DIFile File,
209                            unsigned LineNumber, uint64_t SizeInBits,
210                            uint64_t AlignInBits, uint64_t OffsetInBits,
211                            unsigned Flags, DIType DerivedFrom,
212                            DIArray Elements, MDNode *VTableHolder = 0,
213                            MDNode *TemplateParms = 0);
214 
215     /// createStructType - Create debugging information entry for a struct.
216     /// @param Scope        Scope in which this struct is defined.
217     /// @param Name         Struct name.
218     /// @param File         File where this member is defined.
219     /// @param LineNo       Line number.
220     /// @param SizeInBits   Member size.
221     /// @param AlignInBits  Member alignment.
222     /// @param Flags        Flags to encode member attribute, e.g. private
223     /// @param Elements     Struct elements.
224     /// @param RunTimeLang  Optional parameter, Objective-C runtime version.
225     DIType createStructType(DIDescriptor Scope, StringRef Name, DIFile File,
226                             unsigned LineNumber, uint64_t SizeInBits,
227                             uint64_t AlignInBits, unsigned Flags,
228                             DIArray Elements, unsigned RunTimeLang = 0);
229 
230     /// createUnionType - Create debugging information entry for an union.
231     /// @param Scope        Scope in which this union is defined.
232     /// @param Name         Union name.
233     /// @param File         File where this member is defined.
234     /// @param LineNo       Line number.
235     /// @param SizeInBits   Member size.
236     /// @param AlignInBits  Member alignment.
237     /// @param Flags        Flags to encode member attribute, e.g. private
238     /// @param Elements     Union elements.
239     /// @param RunTimeLang  Optional parameter, Objective-C runtime version.
240     DIType createUnionType(DIDescriptor Scope, StringRef Name, DIFile File,
241                            unsigned LineNumber, uint64_t SizeInBits,
242                            uint64_t AlignInBits, unsigned Flags,
243                            DIArray Elements, unsigned RunTimeLang = 0);
244 
245     /// createTemplateTypeParameter - Create debugging information for template
246     /// type parameter.
247     /// @param Scope        Scope in which this type is defined.
248     /// @param Name         Type parameter name.
249     /// @param Ty           Parameter type.
250     /// @param File         File where this type parameter is defined.
251     /// @param LineNo       Line number.
252     /// @param ColumnNo     Column Number.
253     DITemplateTypeParameter
254     createTemplateTypeParameter(DIDescriptor Scope, StringRef Name, DIType Ty,
255                                 MDNode *File = 0, unsigned LineNo = 0,
256                                 unsigned ColumnNo = 0);
257 
258     /// createTemplateValueParameter - Create debugging information for template
259     /// value parameter.
260     /// @param Scope        Scope in which this type is defined.
261     /// @param Name         Value parameter name.
262     /// @param Ty           Parameter type.
263     /// @param Value        Constant parameter value.
264     /// @param File         File where this type parameter is defined.
265     /// @param LineNo       Line number.
266     /// @param ColumnNo     Column Number.
267     DITemplateValueParameter
268     createTemplateValueParameter(DIDescriptor Scope, StringRef Name, DIType Ty,
269                                  uint64_t Value,
270                                  MDNode *File = 0, unsigned LineNo = 0,
271                                  unsigned ColumnNo = 0);
272 
273     /// createArrayType - Create debugging information entry for an array.
274     /// @param Size         Array size.
275     /// @param AlignInBits  Alignment.
276     /// @param Ty           Element type.
277     /// @param Subscripts   Subscripts.
278     DIType createArrayType(uint64_t Size, uint64_t AlignInBits,
279                            DIType Ty, DIArray Subscripts);
280 
281     /// createVectorType - Create debugging information entry for a vector type.
282     /// @param Size         Array size.
283     /// @param AlignInBits  Alignment.
284     /// @param Ty           Element type.
285     /// @param Subscripts   Subscripts.
286     DIType createVectorType(uint64_t Size, uint64_t AlignInBits,
287                             DIType Ty, DIArray Subscripts);
288 
289     /// createEnumerationType - Create debugging information entry for an
290     /// enumeration.
291     /// @param Scope        Scope in which this enumeration is defined.
292     /// @param Name         Union name.
293     /// @param File         File where this member is defined.
294     /// @param LineNo       Line number.
295     /// @param SizeInBits   Member size.
296     /// @param AlignInBits  Member alignment.
297     /// @param Elements     Enumeration elements.
298     DIType createEnumerationType(DIDescriptor Scope, StringRef Name,
299                                  DIFile File, unsigned LineNumber,
300                                  uint64_t SizeInBits,
301                                  uint64_t AlignInBits, DIArray Elements);
302 
303     /// createSubroutineType - Create subroutine type.
304     /// @param File          File in which this subroutine is defined.
305     /// @param ParamterTypes An array of subroutine parameter types. This
306     ///                      includes return type at 0th index.
307     DIType createSubroutineType(DIFile File, DIArray ParameterTypes);
308 
309     /// createArtificialType - Create a new DIType with "artificial" flag set.
310     DIType createArtificialType(DIType Ty);
311 
312     /// createTemporaryType - Create a temporary forward-declared type.
313     DIType createTemporaryType();
314     DIType createTemporaryType(DIFile F);
315 
316     /// retainType - Retain DIType in a module even if it is not referenced
317     /// through debug info anchors.
318     void retainType(DIType T);
319 
320     /// createUnspecifiedParameter - Create unspeicified type descriptor
321     /// for a subroutine type.
322     DIDescriptor createUnspecifiedParameter();
323 
324     /// getOrCreateArray - Get a DIArray, create one if required.
325     DIArray getOrCreateArray(ArrayRef<Value *> Elements);
326 
327     /// getOrCreateSubrange - Create a descriptor for a value range.  This
328     /// implicitly uniques the values returned.
329     DISubrange getOrCreateSubrange(int64_t Lo, int64_t Hi);
330 
331     /// createGlobalVariable - Create a new descriptor for the specified global.
332     /// @param Name        Name of the variable.
333     /// @param File        File where this variable is defined.
334     /// @param LineNo      Line number.
335     /// @param Ty          Variable Type.
336     /// @param isLocalToUnit Boolean flag indicate whether this variable is
337     ///                      externally visible or not.
338     /// @param Val         llvm::Value of the variable.
339     DIGlobalVariable
340     createGlobalVariable(StringRef Name, DIFile File, unsigned LineNo,
341                          DIType Ty, bool isLocalToUnit, llvm::Value *Val);
342 
343 
344     /// createStaticVariable - Create a new descriptor for the specified
345     /// variable.
346     /// @param Conext      Variable scope.
347     /// @param Name        Name of the variable.
348     /// @param LinakgeName Mangled  name of the variable.
349     /// @param File        File where this variable is defined.
350     /// @param LineNo      Line number.
351     /// @param Ty          Variable Type.
352     /// @param isLocalToUnit Boolean flag indicate whether this variable is
353     ///                      externally visible or not.
354     /// @param Val         llvm::Value of the variable.
355     DIGlobalVariable
356     createStaticVariable(DIDescriptor Context, StringRef Name,
357                          StringRef LinkageName, DIFile File, unsigned LineNo,
358                          DIType Ty, bool isLocalToUnit, llvm::Value *Val);
359 
360 
361     /// createLocalVariable - Create a new descriptor for the specified
362     /// local variable.
363     /// @param Tag         Dwarf TAG. Usually DW_TAG_auto_variable or
364     ///                    DW_TAG_arg_variable.
365     /// @param Scope       Variable scope.
366     /// @param Name        Variable name.
367     /// @param File        File where this variable is defined.
368     /// @param LineNo      Line number.
369     /// @param Ty          Variable Type
370     /// @param AlwaysPreserve Boolean. Set to true if debug info for this
371     ///                       variable should be preserved in optimized build.
372     /// @param Flags          Flags, e.g. artificial variable.
373     /// @param ArgNo       If this variable is an arugment then this argument's
374     ///                    number. 1 indicates 1st argument.
375     DIVariable createLocalVariable(unsigned Tag, DIDescriptor Scope,
376                                    StringRef Name,
377                                    DIFile File, unsigned LineNo,
378                                    DIType Ty, bool AlwaysPreserve = false,
379                                    unsigned Flags = 0,
380                                    unsigned ArgNo = 0);
381 
382 
383     /// createComplexVariable - Create a new descriptor for the specified
384     /// variable which has a complex address expression for its address.
385     /// @param Tag         Dwarf TAG. Usually DW_TAG_auto_variable or
386     ///                    DW_TAG_arg_variable.
387     /// @param Scope       Variable scope.
388     /// @param Name        Variable name.
389     /// @param File        File where this variable is defined.
390     /// @param LineNo      Line number.
391     /// @param Ty          Variable Type
392     /// @param Addr        An array of complex address operations.
393     /// @param ArgNo       If this variable is an arugment then this argument's
394     ///                    number. 1 indicates 1st argument.
395     DIVariable createComplexVariable(unsigned Tag, DIDescriptor Scope,
396                                      StringRef Name, DIFile F, unsigned LineNo,
397                                      DIType Ty, ArrayRef<Value *> Addr,
398                                      unsigned ArgNo = 0);
399 
400     /// createFunction - Create a new descriptor for the specified subprogram.
401     /// See comments in DISubprogram for descriptions of these fields.
402     /// @param Scope         Function scope.
403     /// @param Name          Function name.
404     /// @param LinkageName   Mangled function name.
405     /// @param File          File where this variable is defined.
406     /// @param LineNo        Line number.
407     /// @param Ty            Function type.
408     /// @param isLocalToUnit True if this function is not externally visible..
409     /// @param isDefinition  True if this is a function definition.
410     /// @param Flags         e.g. is this function prototyped or not.
411     ///                      This flags are used to emit dwarf attributes.
412     /// @param isOptimized   True if optimization is ON.
413     /// @param Fn            llvm::Function pointer.
414     /// @param TParam        Function template parameters.
415     DISubprogram createFunction(DIDescriptor Scope, StringRef Name,
416                                 StringRef LinkageName,
417                                 DIFile File, unsigned LineNo,
418                                 DIType Ty, bool isLocalToUnit,
419                                 bool isDefinition,
420                                 unsigned Flags = 0,
421                                 bool isOptimized = false,
422                                 Function *Fn = 0,
423                                 MDNode *TParam = 0,
424                                 MDNode *Decl = 0);
425 
426     /// createMethod - Create a new descriptor for the specified C++ method.
427     /// See comments in DISubprogram for descriptions of these fields.
428     /// @param Scope         Function scope.
429     /// @param Name          Function name.
430     /// @param LinkageName   Mangled function name.
431     /// @param File          File where this variable is defined.
432     /// @param LineNo        Line number.
433     /// @param Ty            Function type.
434     /// @param isLocalToUnit True if this function is not externally visible..
435     /// @param isDefinition  True if this is a function definition.
436     /// @param Virtuality    Attributes describing virtualness. e.g. pure
437     ///                      virtual function.
438     /// @param VTableIndex   Index no of this method in virtual table.
439     /// @param VTableHolder  Type that holds vtable.
440     /// @param Flags         e.g. is this function prototyped or not.
441     ///                      This flags are used to emit dwarf attributes.
442     /// @param isOptimized   True if optimization is ON.
443     /// @param Fn            llvm::Function pointer.
444     /// @param TParam        Function template parameters.
445     DISubprogram createMethod(DIDescriptor Scope, StringRef Name,
446                               StringRef LinkageName,
447                               DIFile File, unsigned LineNo,
448                               DIType Ty, bool isLocalToUnit,
449                               bool isDefinition,
450                               unsigned Virtuality = 0, unsigned VTableIndex = 0,
451                               MDNode *VTableHolder = 0,
452                               unsigned Flags = 0,
453                               bool isOptimized = false,
454                               Function *Fn = 0,
455                               MDNode *TParam = 0);
456 
457     /// createNameSpace - This creates new descriptor for a namespace
458     /// with the specified parent scope.
459     /// @param Scope       Namespace scope
460     /// @param Name        Name of this namespace
461     /// @param File        Source file
462     /// @param LineNo      Line number
463     DINameSpace createNameSpace(DIDescriptor Scope, StringRef Name,
464                                 DIFile File, unsigned LineNo);
465 
466 
467     /// createLexicalBlockFile - This creates a descriptor for a lexical
468     /// block with a new file attached. This merely extends the existing
469     /// lexical block as it crosses a file.
470     /// @param Scope       Lexical block.
471     /// @param File        Source file.
472     DILexicalBlockFile createLexicalBlockFile(DIDescriptor Scope,
473 					      DIFile File);
474 
475     /// createLexicalBlock - This creates a descriptor for a lexical block
476     /// with the specified parent context.
477     /// @param Scope       Parent lexical scope.
478     /// @param File        Source file
479     /// @param Line        Line number
480     /// @param Col         Column number
481     DILexicalBlock createLexicalBlock(DIDescriptor Scope, DIFile File,
482                                       unsigned Line, unsigned Col);
483 
484     /// insertDeclare - Insert a new llvm.dbg.declare intrinsic call.
485     /// @param Storage     llvm::Value of the variable
486     /// @param VarInfo     Variable's debug info descriptor.
487     /// @param InsertAtEnd Location for the new intrinsic.
488     Instruction *insertDeclare(llvm::Value *Storage, DIVariable VarInfo,
489                                BasicBlock *InsertAtEnd);
490 
491     /// insertDeclare - Insert a new llvm.dbg.declare intrinsic call.
492     /// @param Storage      llvm::Value of the variable
493     /// @param VarInfo      Variable's debug info descriptor.
494     /// @param InsertBefore Location for the new intrinsic.
495     Instruction *insertDeclare(llvm::Value *Storage, DIVariable VarInfo,
496                                Instruction *InsertBefore);
497 
498 
499     /// insertDbgValueIntrinsic - Insert a new llvm.dbg.value intrinsic call.
500     /// @param Val          llvm::Value of the variable
501     /// @param Offset       Offset
502     /// @param VarInfo      Variable's debug info descriptor.
503     /// @param InsertAtEnd Location for the new intrinsic.
504     Instruction *insertDbgValueIntrinsic(llvm::Value *Val, uint64_t Offset,
505                                          DIVariable VarInfo,
506                                          BasicBlock *InsertAtEnd);
507 
508     /// insertDbgValueIntrinsic - Insert a new llvm.dbg.value intrinsic call.
509     /// @param Val          llvm::Value of the variable
510     /// @param Offset       Offset
511     /// @param VarInfo      Variable's debug info descriptor.
512     /// @param InsertBefore Location for the new intrinsic.
513     Instruction *insertDbgValueIntrinsic(llvm::Value *Val, uint64_t Offset,
514                                          DIVariable VarInfo,
515                                          Instruction *InsertBefore);
516 
517   };
518 } // end namespace llvm
519 
520 #endif
521