LLVM API Documentation

DwarfWriter.h

Go to the documentation of this file.
00001 //===-- llvm/CodeGen/DwarfWriter.h - Dwarf Framework ------------*- C++ -*-===//
00002 //
00003 //                     The LLVM Compiler Infrastructure
00004 //
00005 // This file was developed by James M. Laskey and is distributed under the
00006 // University of Illinois Open Source License. See LICENSE.TXT for details.
00007 //
00008 //===----------------------------------------------------------------------===//
00009 //
00010 // This file contains support for writing Dwarf debug info into asm files.  For
00011 // Details on the Dwarf 3 specfication see DWARF Debugging Information Format
00012 // V.3 reference manual http://dwarf.freestandards.org ,
00013 //
00014 // The role of the Dwarf Writer class is to extract debug information from the
00015 // MachineDebugInfo object, organize it in Dwarf form and then emit it into asm
00016 // the current asm file using data and high level Dwarf directives.
00017 // 
00018 //===----------------------------------------------------------------------===//
00019 
00020 #ifndef LLVM_CODEGEN_DWARFWRITER_H
00021 #define LLVM_CODEGEN_DWARFWRITER_H
00022 
00023 #include "llvm/ADT/UniqueVector.h"
00024 #include "llvm/Support/DataTypes.h"
00025 
00026 #include <iosfwd>
00027 #include <string>
00028 
00029 
00030 namespace llvm {
00031 
00032 // Forward declarations.
00033 
00034 class AsmPrinter;
00035 class CompileUnit;
00036 class CompileUnitDesc;
00037 class DebugInfoDesc;
00038 class DebugVariable;
00039 class DebugScope;
00040 class DIE;
00041 class DIEAbbrev;
00042 class GlobalVariableDesc;
00043 class MachineDebugInfo;
00044 class MachineFunction;
00045 class MachineLocation;
00046 class MachineMove;
00047 class Module;
00048 class MRegisterInfo;
00049 class SubprogramDesc;
00050 class SourceLineInfo;
00051 class TargetData;
00052 class Type;
00053 class TypeDesc;
00054   
00055 //===----------------------------------------------------------------------===//
00056 // DWLabel - Labels are used to track locations in the assembler file.
00057 // Labels appear in the form <prefix>debug_<Tag><Number>, where the tag is a
00058 // category of label (Ex. location) and number is a value unique in that
00059 // category.
00060 class DWLabel {
00061 public:
00062   const char *Tag;                    // Label category tag. Should always be
00063                                       // a staticly declared C string.
00064   unsigned    Number;                 // Unique number.
00065 
00066   DWLabel(const char *T, unsigned N) : Tag(T), Number(N) {}
00067 };
00068 
00069 //===----------------------------------------------------------------------===//
00070 // DwarfWriter - Emits Dwarf debug and exception handling directives.
00071 //
00072 class DwarfWriter {
00073 protected:
00074 
00075   //===--------------------------------------------------------------------===//
00076   // Core attributes used by the Dwarf  writer.
00077   //
00078   
00079   //
00080   /// O - Stream to .s file.
00081   ///
00082   std::ostream &O;
00083 
00084   /// Asm - Target of Dwarf emission.
00085   ///
00086   AsmPrinter *Asm;
00087   
00088   /// TD - Target data.
00089   const TargetData *TD;
00090   
00091   /// RI - Register Information.
00092   const MRegisterInfo *RI;
00093   
00094   /// M - Current module.
00095   ///
00096   Module *M;
00097   
00098   /// MF - Current machine function.
00099   ///
00100   MachineFunction *MF;
00101   
00102   /// DebugInfo - Collected debug information.
00103   ///
00104   MachineDebugInfo *DebugInfo;
00105   
00106   /// didInitial - Flag to indicate if initial emission has been done.
00107   ///
00108   bool didInitial;
00109   
00110   /// shouldEmit - Flag to indicate if debug information should be emitted.
00111   ///
00112   bool shouldEmit;
00113   
00114   /// SubprogramCount - The running count of functions being compiled.
00115   ///
00116   unsigned SubprogramCount;
00117   
00118   //===--------------------------------------------------------------------===//
00119   // Attributes used to construct specific Dwarf sections.
00120   //
00121   
00122   /// CompileUnits - All the compile units involved in this build.  The index
00123   /// of each entry in this vector corresponds to the sources in DebugInfo.
00124   std::vector<CompileUnit *> CompileUnits;
00125 
00126   /// Abbreviations - A UniqueVector of TAG structure abbreviations.
00127   ///
00128   UniqueVector<DIEAbbrev> Abbreviations;
00129   
00130   /// StringPool - A UniqueVector of strings used by indirect references.
00131   /// UnitMap - Map debug information descriptor to compile unit.
00132    ///
00133   UniqueVector<std::string> StringPool;
00134 
00135   /// UnitMap - Map debug information descriptor to compile unit.
00136   ///
00137   std::map<DebugInfoDesc *, CompileUnit *> DescToUnitMap;
00138   
00139   /// DescToDieMap - Tracks the mapping of top level debug informaton
00140   /// descriptors to debug information entries.
00141   std::map<DebugInfoDesc *, DIE *> DescToDieMap;
00142   
00143   /// SectionMap - Provides a unique id per text section.
00144   ///
00145   UniqueVector<std::string> SectionMap;
00146   
00147   /// SectionSourceLines - Tracks line numbers per text section.
00148   ///
00149   std::vector<std::vector<SourceLineInfo *> > SectionSourceLines;
00150   
00151   //===--------------------------------------------------------------------===//
00152   // Properties to be set by the derived class ctor, used to configure the
00153   // Dwarf writer.
00154   //
00155   
00156   /// AddressSize - Size of addresses used in file.
00157   ///
00158   unsigned AddressSize;
00159 
00160   /// hasLEB128 - True if target asm supports leb128 directives.
00161   ///
00162   bool hasLEB128; /// Defaults to false.
00163   
00164   /// hasDotLoc - True if target asm supports .loc directives.
00165   ///
00166   bool hasDotLoc; /// Defaults to false.
00167   
00168   /// hasDotFile - True if target asm supports .file directives.
00169   ///
00170   bool hasDotFile; /// Defaults to false.
00171   
00172   /// needsSet - True if target asm can't compute addresses on data
00173   /// directives.
00174   bool needsSet; /// Defaults to false.
00175   
00176   /// DwarfAbbrevSection - Section directive for Dwarf abbrev.
00177   ///
00178   const char *DwarfAbbrevSection; /// Defaults to ".debug_abbrev".
00179 
00180   /// DwarfInfoSection - Section directive for Dwarf info.
00181   ///
00182   const char *DwarfInfoSection; /// Defaults to ".debug_info".
00183 
00184   /// DwarfLineSection - Section directive for Dwarf info.
00185   ///
00186   const char *DwarfLineSection; /// Defaults to ".debug_line".
00187   
00188   /// DwarfFrameSection - Section directive for Dwarf info.
00189   ///
00190   const char *DwarfFrameSection; /// Defaults to ".debug_frame".
00191   
00192   /// DwarfPubNamesSection - Section directive for Dwarf info.
00193   ///
00194   const char *DwarfPubNamesSection; /// Defaults to ".debug_pubnames".
00195   
00196   /// DwarfPubTypesSection - Section directive for Dwarf info.
00197   ///
00198   const char *DwarfPubTypesSection; /// Defaults to ".debug_pubtypes".
00199   
00200   /// DwarfStrSection - Section directive for Dwarf info.
00201   ///
00202   const char *DwarfStrSection; /// Defaults to ".debug_str".
00203 
00204   /// DwarfLocSection - Section directive for Dwarf info.
00205   ///
00206   const char *DwarfLocSection; /// Defaults to ".debug_loc".
00207 
00208   /// DwarfARangesSection - Section directive for Dwarf info.
00209   ///
00210   const char *DwarfARangesSection; /// Defaults to ".debug_aranges".
00211 
00212   /// DwarfRangesSection - Section directive for Dwarf info.
00213   ///
00214   const char *DwarfRangesSection; /// Defaults to ".debug_ranges".
00215 
00216   /// DwarfMacInfoSection - Section directive for Dwarf info.
00217   ///
00218   const char *DwarfMacInfoSection; /// Defaults to ".debug_macinfo".
00219 
00220   /// TextSection - Section directive for standard text.
00221   ///
00222   const char *TextSection; /// Defaults to ".text".
00223   
00224   /// DataSection - Section directive for standard data.
00225   ///
00226   const char *DataSection; /// Defaults to ".data".
00227 
00228   //===--------------------------------------------------------------------===//
00229   // Emission and print routines
00230   //
00231 
00232 public:
00233   /// getAddressSize - Return the size of a target address in bytes.
00234   ///
00235   unsigned getAddressSize() const { return AddressSize; }
00236 
00237   /// PrintHex - Print a value as a hexidecimal value.
00238   ///
00239   void PrintHex(int Value) const;
00240 
00241   /// EOL - Print a newline character to asm stream.  If a comment is present
00242   /// then it will be printed first.  Comments should not contain '\n'.
00243   void EOL(const std::string &Comment) const;
00244   
00245   /// EmitAlign - Print a align directive.
00246   ///
00247   void EmitAlign(unsigned Alignment) const;
00248                                         
00249   /// EmitULEB128Bytes - Emit an assembler byte data directive to compose an
00250   /// unsigned leb128 value.
00251   void EmitULEB128Bytes(unsigned Value) const;
00252   
00253   /// EmitSLEB128Bytes - print an assembler byte data directive to compose a
00254   /// signed leb128 value.
00255   void EmitSLEB128Bytes(int Value) const;
00256   
00257   /// PrintULEB128 - Print a series of hexidecimal values (separated by
00258   /// commas) representing an unsigned leb128 value.
00259   void PrintULEB128(unsigned Value) const;
00260 
00261   /// SizeULEB128 - Compute the number of bytes required for an unsigned
00262   /// leb128 value.
00263   static unsigned SizeULEB128(unsigned Value);
00264   
00265   /// PrintSLEB128 - Print a series of hexidecimal values (separated by
00266   /// commas) representing a signed leb128 value.
00267   void PrintSLEB128(int Value) const;
00268   
00269   /// SizeSLEB128 - Compute the number of bytes required for a signed leb128
00270   /// value.
00271   static unsigned SizeSLEB128(int Value);
00272   
00273   /// EmitInt8 - Emit a byte directive and value.
00274   ///
00275   void EmitInt8(int Value) const;
00276 
00277   /// EmitInt16 - Emit a short directive and value.
00278   ///
00279   void EmitInt16(int Value) const;
00280 
00281   /// EmitInt32 - Emit a long directive and value.
00282   ///
00283   void EmitInt32(int Value) const;
00284   
00285   /// EmitInt64 - Emit a long long directive and value.
00286   ///
00287   void EmitInt64(uint64_t Value) const;
00288   
00289   /// EmitString - Emit a string with quotes and a null terminator.
00290   /// Special characters are emitted properly. 
00291   /// \literal (Eg. '\t') \endliteral
00292   void EmitString(const std::string &String) const;
00293 
00294   /// PrintLabelName - Print label name in form used by Dwarf writer.
00295   ///
00296   void PrintLabelName(DWLabel Label) const {
00297     PrintLabelName(Label.Tag, Label.Number);
00298   }
00299   void PrintLabelName(const char *Tag, unsigned Number) const;
00300   
00301   /// EmitLabel - Emit location label for internal use by Dwarf.
00302   ///
00303   void EmitLabel(DWLabel Label) const {
00304     EmitLabel(Label.Tag, Label.Number);
00305   }
00306   void EmitLabel(const char *Tag, unsigned Number) const;
00307   
00308   /// EmitReference - Emit a reference to a label.
00309   ///
00310   void EmitReference(DWLabel Label) const {
00311     EmitReference(Label.Tag, Label.Number);
00312   }
00313   void EmitReference(const char *Tag, unsigned Number) const;
00314   void EmitReference(const std::string &Name) const;
00315 
00316   /// EmitDifference - Emit the difference between two labels.  Some
00317   /// assemblers do not behave with absolute expressions with data directives,
00318   /// so there is an option (needsSet) to use an intermediary set expression.
00319   void EmitDifference(DWLabel LabelHi, DWLabel LabelLo) const {
00320     EmitDifference(LabelHi.Tag, LabelHi.Number, LabelLo.Tag, LabelLo.Number);
00321   }
00322   void EmitDifference(const char *TagHi, unsigned NumberHi,
00323                       const char *TagLo, unsigned NumberLo) const;
00324                       
00325   /// NewAbbreviation - Add the abbreviation to the Abbreviation vector.
00326   ///  
00327   unsigned NewAbbreviation(DIEAbbrev *Abbrev);
00328   
00329   /// NewString - Add a string to the constant pool and returns a label.
00330   ///
00331   DWLabel NewString(const std::string &String);
00332   
00333   /// getDieMapSlotFor - Returns the debug information entry map slot for the
00334   /// specified debug descriptor.
00335   DIE *&getDieMapSlotFor(DebugInfoDesc *DD);
00336                                  
00337 private:
00338 
00339   /// AddSourceLine - Add location information to specified debug information
00340   /// entry. 
00341   void AddSourceLine(DIE *Die, CompileUnitDesc *File, unsigned Line);
00342 
00343   /// AddAddress - Add an address attribute to a die based on the location
00344   /// provided.
00345   void AddAddress(DIE *Die, unsigned Attribute,
00346                   const MachineLocation &Location);
00347 
00348   /// NewType - Create a new type DIE.
00349   ///
00350   DIE *NewType(DIE *Context, TypeDesc *TyDesc, CompileUnit *Unit);
00351   
00352   /// NewCompileUnit - Create new compile unit and it's die.
00353   ///
00354   CompileUnit *NewCompileUnit(CompileUnitDesc *UnitDesc, unsigned ID);
00355   
00356   /// FindCompileUnit - Get the compile unit for the given descriptor.
00357   ///
00358   CompileUnit *FindCompileUnit(CompileUnitDesc *UnitDesc);
00359   
00360   /// NewGlobalVariable - Make a new global variable DIE.
00361   ///
00362   DIE *NewGlobalVariable(GlobalVariableDesc *GVD);
00363 
00364   /// NewSubprogram - Add a new subprogram DIE.
00365   ///
00366   DIE *NewSubprogram(SubprogramDesc *SPD);
00367 
00368   /// NewScopeVariable - Create a new scope variable.
00369   ///
00370   DIE *NewScopeVariable(DebugVariable *DV, CompileUnit *Unit);
00371 
00372   /// ConstructScope - Construct the components of a scope.
00373   ///
00374   void ConstructScope(DebugScope *ParentScope, DIE *ParentDie,
00375                       CompileUnit *Unit);
00376 
00377   /// ConstructRootScope - Construct the scope for the subprogram.
00378   ///
00379   void ConstructRootScope(DebugScope *RootScope);
00380 
00381   /// EmitInitial - Emit initial Dwarf declarations.
00382   ///
00383   void EmitInitial();
00384   
00385   /// EmitDIE - Recusively Emits a debug information entry.
00386   ///
00387   void EmitDIE(DIE *Die) const;
00388   
00389   /// SizeAndOffsetDie - Compute the size and offset of a DIE.
00390   ///
00391   unsigned SizeAndOffsetDie(DIE *Die, unsigned Offset, bool Last);
00392 
00393   /// SizeAndOffsets - Compute the size and offset of all the DIEs.
00394   ///
00395   void SizeAndOffsets();
00396   
00397   /// EmitFrameMoves - Emit frame instructions to describe the layout of the
00398   /// frame.
00399   void EmitFrameMoves(const char *BaseLabel, unsigned BaseLabelID,
00400                       std::vector<MachineMove *> &Moves);
00401 
00402   /// EmitDebugInfo - Emit the debug info section.
00403   ///
00404   void EmitDebugInfo() const;
00405   
00406   /// EmitAbbreviations - Emit the abbreviation section.
00407   ///
00408   void EmitAbbreviations() const;
00409   
00410   /// EmitDebugLines - Emit source line information.
00411   ///
00412   void EmitDebugLines() const;
00413 
00414   /// EmitInitialDebugFrame - Emit common frame info into a debug frame section.
00415   ///
00416   void EmitInitialDebugFrame();
00417     
00418   /// EmitFunctionDebugFrame - Emit per function frame info into a debug frame
00419   /// section.
00420   void EmitFunctionDebugFrame();
00421 
00422   /// EmitDebugPubNames - Emit info into a debug pubnames section.
00423   ///
00424   void EmitDebugPubNames();
00425   
00426   /// EmitDebugStr - Emit info into a debug str section.
00427   ///
00428   void EmitDebugStr();
00429   
00430   /// EmitDebugLoc - Emit info into a debug loc section.
00431   ///
00432   void EmitDebugLoc();
00433   
00434   /// EmitDebugARanges - Emit info into a debug aranges section.
00435   ///
00436   void EmitDebugARanges();
00437   
00438   /// EmitDebugRanges - Emit info into a debug ranges section.
00439   ///
00440   void EmitDebugRanges();
00441   
00442   /// EmitDebugMacInfo - Emit info into a debug macinfo section.
00443   ///
00444   void EmitDebugMacInfo();
00445   
00446   /// ConstructCompileUnitDIEs - Create a compile unit DIE for each source and
00447   /// header file.
00448   void ConstructCompileUnitDIEs();
00449   
00450   /// ConstructGlobalDIEs - Create DIEs for each of the externally visible
00451   /// global variables.
00452   void ConstructGlobalDIEs();
00453 
00454   /// ConstructSubprogramDIEs - Create DIEs for each of the externally visible
00455   /// subprograms.
00456   void ConstructSubprogramDIEs();
00457 
00458   /// ShouldEmitDwarf - Returns true if Dwarf declarations should be made.
00459   ///
00460   bool ShouldEmitDwarf() const { return shouldEmit; }
00461 
00462 public:
00463   
00464   DwarfWriter(std::ostream &OS, AsmPrinter *A);
00465   virtual ~DwarfWriter();
00466   
00467   /// SetDebugInfo - Set DebugInfo when it's known that pass manager has
00468   /// created it.  Set by the target AsmPrinter.
00469   void SetDebugInfo(MachineDebugInfo *DI);
00470 
00471   //===--------------------------------------------------------------------===//
00472   // Main entry points.
00473   //
00474   
00475   /// BeginModule - Emit all Dwarf sections that should come prior to the
00476   /// content.
00477   void BeginModule(Module *M);
00478   
00479   /// EndModule - Emit all Dwarf sections that should come after the content.
00480   ///
00481   void EndModule();
00482   
00483   /// BeginFunction - Gather pre-function debug information.  Assumes being 
00484   /// emitted immediately after the function entry point.
00485   void BeginFunction(MachineFunction *MF);
00486   
00487   /// EndFunction - Gather and emit post-function debug information.
00488   ///
00489   void EndFunction();
00490   
00491   /// NonFunction - Function does not have a true body.
00492   ///
00493   void NonFunction();
00494 };
00495 
00496 } // end llvm namespace
00497 
00498 #endif