include/llvm/Analysis/DebugInfo.h

   1 //===--- llvm/Analysis/DebugInfo.h - Debug Information Helpers --*- 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 bunch of datatypes that are useful for creating and
  11 // walking debug info in LLVM IR form.
  12 //
  13 //===----------------------------------------------------------------------===//
  14
  15 #ifndef LLVM_SUPPORT_DEBUGINFO_H
  16 #define LLVM_SUPPORT_DEBUGINFO_H
  17
  18 #include "llvm/ADT/StringMap.h"
  19 #include "llvm/ADT/DenseMap.h"
  20 #include "llvm/Support/Dwarf.h"
  21
  22 namespace llvm {
  23   class BasicBlock;
  24   class Constant;
  25   class Function;
  26   class GlobalVariable;
  27   class Module;
  28   class Type;
  29   class Value;
  30   class DbgStopPointInst;
  31   class DbgDeclareInst;
  32   class Instruction;
  33
  34   class DIDescriptor {
  35   public:
  36     enum {
  37       Version7    = 7 << 16,     // Current version of debug information.
  38       Version6    = 6 << 16,     // Constant for version 6.
  39       Version5    = 5 << 16,     // Constant for version 5.
  40       Version4    = 4 << 16,     // Constant for version 4.
  41       VersionMask = 0xffff0000   // Mask for version number.
  42     };
  43
  44   protected:
  45     GlobalVariable *GV;
  46
  47     /// DIDescriptor constructor.  If the specified GV is non-null, this checks
  48     /// to make sure that the tag in the descriptor matches 'RequiredTag'.  If
  49     /// not, the debug info is corrupt and we ignore it.
  50     DIDescriptor(GlobalVariable *GV, unsigned RequiredTag);
  51
  52     std::string getStringField(unsigned Elt) const;
  53     unsigned getUnsignedField(unsigned Elt) const {
  54       return (unsigned)getUInt64Field(Elt);
  55     }
  56     uint64_t getUInt64Field(unsigned Elt) const;
  57     DIDescriptor getDescriptorField(unsigned Elt) const;
  58
  59     template <typename DescTy>
  60     DescTy getFieldAs(unsigned Elt) const {
  61       return DescTy(getDescriptorField(Elt).getGV());
  62     }
  63
  64     GlobalVariable *getGlobalVariableField(unsigned Elt) const;
  65
  66   public:
  67     explicit DIDescriptor() : GV(0) {}
  68     explicit DIDescriptor(GlobalVariable *gv) : GV(gv) {}
  69
  70     bool isNull() const { return GV == 0; }
  71
  72     GlobalVariable *getGV() const { return GV; }
  73
  74     unsigned getVersion() const {
  75       return getUnsignedField(0) & VersionMask;
  76     }
  77
  78     unsigned getTag() const {
  79       return getUnsignedField(0) & ~VersionMask;
  80     }
  81
  82   };
  83
  84   /// DIAnchor - A wrapper for various anchor descriptors.
  85   class DIAnchor : public DIDescriptor {
  86   public:
  87     explicit DIAnchor(GlobalVariable *GV = 0);
  88
  89     unsigned getAnchorTag() const { return getUnsignedField(1); }
  90   };
  91
  92   /// DISubrange - This is used to represent ranges, for array bounds.
  93   class DISubrange : public DIDescriptor {
  94   public:
  95     explicit DISubrange(GlobalVariable *GV = 0);
  96
  97     int64_t getLo() const { return (int64_t)getUInt64Field(1); }
  98     int64_t getHi() const { return (int64_t)getUInt64Field(2); }
  99   };
 100
 101   /// DIArray - This descriptor holds an array of descriptors.
 102   class DIArray : public DIDescriptor {
 103   public:
 104     explicit DIArray(GlobalVariable *GV = 0) : DIDescriptor(GV) {}
 105
 106     unsigned getNumElements() const;
 107     DIDescriptor getElement(unsigned Idx) const {
 108       return getDescriptorField(Idx);
 109     }
 110   };
 111
 112   /// DICompileUnit - A wrapper for a compile unit.
 113   class DICompileUnit : public DIDescriptor {
 114   public:
 115     explicit DICompileUnit(GlobalVariable *GV = 0);
 116
 117     unsigned getLanguage() const     { return getUnsignedField(2); }
 118     std::string getFilename() const  { return getStringField(3); }
 119     std::string getDirectory() const { return getStringField(4); }
 120     std::string getProducer() const  { return getStringField(5); }
 121
 122     /// Verify - Verify that a compile unit is well formed.
 123     bool Verify() const;
 124   };
 125
 126   /// DIEnumerator - A wrapper for an enumerator (e.g. X and Y in 'enum {X,Y}').
 127   /// FIXME: it seems strange that this doesn't have either a reference to the
 128   /// type/precision or a file/line pair for location info.
 129   class DIEnumerator : public DIDescriptor {
 130   public:
 131     explicit DIEnumerator(GlobalVariable *GV = 0);
 132
 133     std::string getName() const  { return getStringField(1); }
 134     uint64_t getEnumValue() const { return getUInt64Field(2); }
 135   };
 136
 137   /// DIType - This is a wrapper for a type.
 138   /// FIXME: Types should be factored much better so that CV qualifiers and
 139   /// others do not require a huge and empty descriptor full of zeros.
 140   class DIType : public DIDescriptor {
 141   protected:
 142     DIType(GlobalVariable *GV, unsigned Tag) : DIDescriptor(GV, Tag) {}
 143     // This ctor is used when the Tag has already been validated by a derived
 144     // ctor.
 145     DIType(GlobalVariable *GV, bool, bool) : DIDescriptor(GV) {}
 146
 147   public:
 148     /// isDerivedType - Return true if the specified tag is legal for
 149     /// DIDerivedType.
 150     static bool isDerivedType(unsigned TAG);
 151
 152     /// isCompositeType - Return true if the specified tag is legal for
 153     /// DICompositeType.
 154     static bool isCompositeType(unsigned TAG);
 155
 156     /// isBasicType - Return true if the specified tag is legal for
 157     /// DIBasicType.
 158     static bool isBasicType(unsigned TAG) {
 159       return TAG == dwarf::DW_TAG_base_type;
 160     }
 161
 162     /// Verify - Verify that a type descriptor is well formed.
 163     bool Verify() const;
 164   public:
 165     explicit DIType(GlobalVariable *GV);
 166     explicit DIType() {}
 167     virtual ~DIType() {}
 168
 169     DIDescriptor getContext() const     { return getDescriptorField(1); }
 170     std::string getName() const         { return getStringField(2); }
 171     DICompileUnit getCompileUnit() const{ return getFieldAs<DICompileUnit>(3); }
 172     unsigned getLineNumber() const      { return getUnsignedField(4); }
 173     uint64_t getSizeInBits() const      { return getUInt64Field(5); }
 174     uint64_t getAlignInBits() const     { return getUInt64Field(6); }
 175     // FIXME: Offset is only used for DW_TAG_member nodes.  Making every type
 176     // carry this is just plain insane.
 177     uint64_t getOffsetInBits() const    { return getUInt64Field(7); }
 178     unsigned getFlags() const           { return getUnsignedField(8); }
 179
 180     virtual std::string getFilename() const {
 181       assert (0 && "Invalid DIDescriptor");
 182       return "";
 183     }
 184
 185     virtual std::string getDirectory() const {
 186       assert (0 && "Invalid DIDescriptor");
 187       return "";
 188     }
 189   };
 190
 191   /// DIBasicType - A basic type, like 'int' or 'float'.
 192   class DIBasicType : public DIType {
 193   public:
 194     explicit DIBasicType(GlobalVariable *GV);
 195
 196     unsigned getEncoding() const { return getUnsignedField(9); }
 197     std::string getFilename() const { return getStringField(10); }
 198     std::string getDirectory() const { return getStringField(11); }
 199   };
 200
 201   /// DIDerivedType - A simple derived type, like a const qualified type,
 202   /// a typedef, a pointer or reference, etc.
 203   class DIDerivedType : public DIType {
 204   protected:
 205     explicit DIDerivedType(GlobalVariable *GV, bool, bool)
 206       : DIType(GV, true, true) {}
 207   public:
 208     explicit DIDerivedType(GlobalVariable *GV);
 209
 210     DIType getTypeDerivedFrom() const { return getFieldAs<DIType>(9); }
 211     std::string getFilename() const { return getStringField(10); }
 212     std::string getDirectory() const { return getStringField(11); }
 213   };
 214
 215
 216   /// DICompositeType - This descriptor holds a type that can refer to multiple
 217   /// other types, like a function or struct.
 218   /// FIXME: Why is this a DIDerivedType??
 219   class DICompositeType : public DIDerivedType {
 220   public:
 221     explicit DICompositeType(GlobalVariable *GV);
 222
 223     DIArray getTypeArray() const { return getFieldAs<DIArray>(10); }
 224     std::string getFilename() const { return getStringField(11); }
 225     std::string getDirectory() const { return getStringField(12); }
 226
 227     /// Verify - Verify that a composite type descriptor is well formed.
 228     bool Verify() const;
 229   };
 230
 231   /// DIGlobal - This is a common class for global variables and subprograms.
 232   class DIGlobal : public DIDescriptor {
 233   protected:
 234     explicit DIGlobal(GlobalVariable *GV, unsigned RequiredTag)
 235       : DIDescriptor(GV, RequiredTag) {}
 236
 237     /// isSubprogram - Return true if the specified tag is legal for
 238     /// DISubprogram.
 239     static bool isSubprogram(unsigned TAG) {
 240       return TAG == dwarf::DW_TAG_subprogram;
 241     }
 242
 243     /// isGlobalVariable - Return true if the specified tag is legal for
 244     /// DIGlobalVariable.
 245     static bool isGlobalVariable(unsigned TAG) {
 246       return TAG == dwarf::DW_TAG_variable;
 247     }
 248
 249   public:
 250     virtual ~DIGlobal() {}
 251
 252     DIDescriptor getContext() const     { return getDescriptorField(2); }
 253     std::string getName() const         { return getStringField(3); }
 254     std::string getDisplayName() const  { return getStringField(4); }
 255     std::string getLinkageName() const  { return getStringField(5); }
 256
 257     DICompileUnit getCompileUnit() const{ return getFieldAs<DICompileUnit>(6); }
 258     unsigned getLineNumber() const      { return getUnsignedField(7); }
 259     DIType getType() const              { return getFieldAs<DIType>(8); }
 260
 261     /// isLocalToUnit - Return true if this subprogram is local to the current
 262     /// compile unit, like 'static' in C.
 263     unsigned isLocalToUnit() const      { return getUnsignedField(9); }
 264     unsigned isDefinition() const       { return getUnsignedField(10); }
 265
 266     virtual std::string getFilename() const {
 267       assert (0 && "Invalid DIDescriptor");
 268       return "";
 269     }
 270
 271     virtual std::string getDirectory() const {
 272       assert (0 && "Invalid DIDescriptor");
 273       return "";
 274     }
 275   };
 276
 277
 278   /// DISubprogram - This is a wrapper for a subprogram (e.g. a function).
 279   class DISubprogram : public DIGlobal {
 280   public:
 281     explicit DISubprogram(GlobalVariable *GV = 0);
 282     std::string getFilename() const { return getStringField(11); }
 283     std::string getDirectory() const { return getStringField(12); }
 284     DICompositeType getType() const { return getFieldAs<DICompositeType>(8); }
 285
 286     /// Verify - Verify that a subprogram descriptor is well formed.
 287     bool Verify() const;
 288   };
 289
 290   /// DIGlobalVariable - This is a wrapper for a global variable.
 291   class DIGlobalVariable : public DIGlobal {
 292   public:
 293     explicit DIGlobalVariable(GlobalVariable *GV = 0);
 294
 295     GlobalVariable *getGlobal() const { return getGlobalVariableField(11); }
 296     std::string getFilename() const { return getStringField(12); }
 297     std::string getDirectory() const { return getStringField(13); }
 298
 299     /// Verify - Verify that a global variable descriptor is well formed.
 300     bool Verify() const;
 301   };
 302
 303
 304   /// DIVariable - This is a wrapper for a variable (e.g. parameter, local,
 305   /// global etc).
 306   class DIVariable : public DIDescriptor {
 307   public:
 308     explicit DIVariable(GlobalVariable *GV = 0);
 309
 310     DIDescriptor getContext() const { return getDescriptorField(1); }
 311     std::string getName() const { return getStringField(2); }
 312
 313     DICompileUnit getCompileUnit() const{ return getFieldAs<DICompileUnit>(3); }
 314     unsigned getLineNumber() const      { return getUnsignedField(4); }
 315     DIType getType() const              { return getFieldAs<DIType>(5); }
 316     std::string getFilename() const { return getStringField(6); }
 317     std::string getDirectory() const { return getStringField(7); }
 318
 319     /// isVariable - Return true if the specified tag is legal for DIVariable.
 320     static bool isVariable(unsigned Tag);
 321
 322     /// Verify - Verify that a variable descriptor is well formed.
 323     bool Verify() const;
 324   };
 325
 326
 327   /// DIBlock - This is a wrapper for a block (e.g. a function, scope, etc).
 328   class DIBlock : public DIDescriptor {
 329   public:
 330     explicit DIBlock(GlobalVariable *GV = 0);
 331
 332     DIDescriptor getContext() const { return getDescriptorField(1); }
 333   };
 334
 335   /// DIFactory - This object assists with the construction of the various
 336   /// descriptors.
 337   class DIFactory {
 338     Module &M;
 339     // Cached values for uniquing and faster lookups.
 340     DIAnchor CompileUnitAnchor, SubProgramAnchor, GlobalVariableAnchor;
 341     const Type *EmptyStructPtr; // "{}*".
 342     Function *StopPointFn;   // llvm.dbg.stoppoint
 343     Function *FuncStartFn;   // llvm.dbg.func.start
 344     Function *RegionStartFn; // llvm.dbg.region.start
 345     Function *RegionEndFn;   // llvm.dbg.region.end
 346     Function *DeclareFn;     // llvm.dbg.declare
 347     StringMap<Constant*> StringCache;
 348     DenseMap<Constant*, DIDescriptor> SimpleConstantCache;
 349
 350     DIFactory(const DIFactory &);     // DO NOT IMPLEMENT
 351     void operator=(const DIFactory&); // DO NOT IMPLEMENT
 352   public:
 353     explicit DIFactory(Module &m);
 354
 355     /// GetOrCreateCompileUnitAnchor - Return the anchor for compile units,
 356     /// creating a new one if there isn't already one in the module.
 357     DIAnchor GetOrCreateCompileUnitAnchor();
 358
 359     /// GetOrCreateSubprogramAnchor - Return the anchor for subprograms,
 360     /// creating a new one if there isn't already one in the module.
 361     DIAnchor GetOrCreateSubprogramAnchor();
 362
 363     /// GetOrCreateGlobalVariableAnchor - Return the anchor for globals,
 364     /// creating a new one if there isn't already one in the module.
 365     DIAnchor GetOrCreateGlobalVariableAnchor();
 366
 367     /// GetOrCreateArray - Create an descriptor for an array of descriptors.
 368     /// This implicitly uniques the arrays created.
 369     DIArray GetOrCreateArray(DIDescriptor *Tys, unsigned NumTys);
 370
 371     /// GetOrCreateSubrange - Create a descriptor for a value range.  This
 372     /// implicitly uniques the values returned.
 373     DISubrange GetOrCreateSubrange(int64_t Lo, int64_t Hi);
 374
 375
 376     /// CreateCompileUnit - Create a new descriptor for the specified compile
 377     /// unit.
 378     DICompileUnit CreateCompileUnit(unsigned LangID,
 379                                     const std::string &Filename,
 380                                     const std::string &Directory,
 381                                     const std::string &Producer);
 382
 383     /// CreateEnumerator - Create a single enumerator value.
 384     DIEnumerator CreateEnumerator(const std::string &Name, uint64_t Val);
 385
 386     /// CreateBasicType - Create a basic type like int, float, etc.
 387     DIBasicType CreateBasicType(DIDescriptor Context, const std::string &Name,
 388                                 DICompileUnit CompileUnit, unsigned LineNumber,
 389                                 uint64_t SizeInBits, uint64_t AlignInBits,
 390                                 uint64_t OffsetInBits, unsigned Flags,
 391                                 unsigned Encoding,
 392                                 const std::string *FileName = 0,
 393                                 const std::string *Directory = 0);
 394
 395     /// CreateDerivedType - Create a derived type like const qualified type,
 396     /// pointer, typedef, etc.
 397     DIDerivedType CreateDerivedType(unsigned Tag, DIDescriptor Context,
 398                                     const std::string &Name,
 399                                     DICompileUnit CompileUnit,
 400                                     unsigned LineNumber,
 401                                     uint64_t SizeInBits, uint64_t AlignInBits,
 402                                     uint64_t OffsetInBits, unsigned Flags,
 403                                     DIType DerivedFrom,
 404                                     const std::string *FileName = 0,
 405                                     const std::string *Directory = 0);
 406
 407     /// CreateCompositeType - Create a composite type like array, struct, etc.
 408     DICompositeType CreateCompositeType(unsigned Tag, DIDescriptor Context,
 409                                         const std::string &Name,
 410                                         DICompileUnit CompileUnit,
 411                                         unsigned LineNumber,
 412                                         uint64_t SizeInBits,
 413                                         uint64_t AlignInBits,
 414                                         uint64_t OffsetInBits, unsigned Flags,
 415                                         DIType DerivedFrom,
 416                                         DIArray Elements,
 417                                         const std::string *FileName = 0,
 418                                         const std::string *Directory = 0);
 419
 420     /// CreateSubprogram - Create a new descriptor for the specified subprogram.
 421     /// See comments in DISubprogram for descriptions of these fields.
 422     DISubprogram CreateSubprogram(DIDescriptor Context, const std::string &Name,
 423                                   const std::string &DisplayName,
 424                                   const std::string &LinkageName,
 425                                   DICompileUnit CompileUnit, unsigned LineNo,
 426                                   DIType Type, bool isLocalToUnit,
 427                                   bool isDefinition,
 428                                   const std::string *FileName = 0,
 429                                   const std::string *Directory = 0);
 430
 431     /// CreateGlobalVariable - Create a new descriptor for the specified global.
 432     DIGlobalVariable
 433     CreateGlobalVariable(DIDescriptor Context, const std::string &Name,
 434                          const std::string &DisplayName,
 435                          const std::string &LinkageName,
 436                          DICompileUnit CompileUnit,
 437                          unsigned LineNo, DIType Type, bool isLocalToUnit,
 438                          bool isDefinition, llvm::GlobalVariable *GV,
 439                          const std::string *FileName = 0,
 440                          const std::string *Directory = 0);
 441
 442
 443     /// CreateVariable - Create a new descriptor for the specified variable.
 444     DIVariable CreateVariable(unsigned Tag, DIDescriptor Context,
 445                               const std::string &Name,
 446                               DICompileUnit CompileUnit, unsigned LineNo,
 447                               DIType Type,
 448                               const std::string *FileName = 0,
 449                               const std::string *Directory = 0);
 450
 451     /// CreateBlock - This creates a descriptor for a lexical block with the
 452     /// specified parent context.
 453     DIBlock CreateBlock(DIDescriptor Context);
 454
 455     /// InsertStopPoint - Create a new llvm.dbg.stoppoint intrinsic invocation,
 456     /// inserting it at the end of the specified basic block.
 457     void InsertStopPoint(DICompileUnit CU, unsigned LineNo, unsigned ColNo,
 458                          BasicBlock *BB);
 459
 460     /// InsertSubprogramStart - Create a new llvm.dbg.func.start intrinsic to
 461     /// mark the start of the specified subprogram.
 462     void InsertSubprogramStart(DISubprogram SP, BasicBlock *BB);
 463
 464     /// InsertRegionStart - Insert a new llvm.dbg.region.start intrinsic call to
 465     /// mark the start of a region for the specified scoping descriptor.
 466     void InsertRegionStart(DIDescriptor D, BasicBlock *BB);
 467
 468     /// InsertRegionEnd - Insert a new llvm.dbg.region.end intrinsic call to
 469     /// mark the end of a region for the specified scoping descriptor.
 470     void InsertRegionEnd(DIDescriptor D, BasicBlock *BB);
 471
 472     /// InsertDeclare - Insert a new llvm.dbg.declare intrinsic call.
 473     void InsertDeclare(llvm::Value *Storage, DIVariable D, BasicBlock *BB);
 474
 475   private:
 476     Constant *GetTagConstant(unsigned TAG);
 477     Constant *GetStringConstant(const std::string &String);
 478     DIAnchor GetOrCreateAnchor(unsigned TAG, const char *Name);
 479
 480     /// getCastToEmpty - Return the descriptor as a Constant* with type '{}*'.
 481     Constant *getCastToEmpty(DIDescriptor D);
 482   };
 483
 484   /// Finds the stoppoint coressponding to this instruction, that is the
 485   /// stoppoint that dominates this instruction
 486   const DbgStopPointInst *findStopPoint(const Instruction *Inst);
 487
 488   /// Finds the stoppoint corresponding to first real (non-debug intrinsic)
 489   /// instruction in this Basic Block, and returns the stoppoint for it.
 490   const DbgStopPointInst *findBBStopPoint(const BasicBlock *BB);
 491
 492   /// Finds the dbg.declare intrinsic corresponding to this value if any.
 493   /// It looks through pointer casts too.
 494   const DbgDeclareInst *findDbgDeclare(const Value *V, bool stripCasts = true);
 495 } // end namespace llvm
 496
 497 #endif