gcc/ada/libgnat/s-dwalin.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                   S Y S T E M . D W A R F _ L I N E S                    --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --           Copyright (C) 2009-2017, Free Software Foundation, Inc.        --
  10 --                                                                          --
  11 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  12 -- terms of the  GNU General Public License as published  by the Free Soft- --
  13 -- ware  Foundation;  either version 3,  or (at your option) any later ver- --
  14 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  15 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  16 -- or FITNESS FOR A PARTICULAR PURPOSE.                                     --
  17 --                                                                          --
  18 -- As a special exception under Section 7 of GPL version 3, you are granted --
  19 -- additional permissions described in the GCC Runtime Library Exception,   --
  20 -- version 3.1, as published by the Free Software Foundation.               --
  21 --                                                                          --
  22 -- You should have received a copy of the GNU General Public License and    --
  23 -- a copy of the GCC Runtime Library Exception along with this program;     --
  24 -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
  25 -- <http://www.gnu.org/licenses/>.                                          --
  26 --                                                                          --
  27 -- GNAT was originally developed  by the GNAT team at  New York University. --
  28 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  29 --                                                                          --
  30 ------------------------------------------------------------------------------
  31
  32 --  This package provides routines to read DWARF line number information from
  33 --  a generic object file with as little overhead as possible. This allows
  34 --  conversions from PC addresses to human readable source locations.
  35 --
  36 --  Objects must be built with debugging information, however only the
  37 --  .debug_line section of the object file is referenced. In cases where object
  38 --  size is a consideration it's possible to strip all other .debug sections,
  39 --  which will decrease the size of the object significantly.
  40
  41 pragma Polling (Off);
  42 --  We must turn polling off for this unit, because otherwise we can get
  43 --  elaboration circularities when polling is turned on
  44
  45 with Ada.Exceptions.Traceback;
  46
  47 with System.Object_Reader;
  48 with System.Storage_Elements;
  49 with System.Bounded_Strings;
  50
  51 package System.Dwarf_Lines is
  52
  53    package AET renames Ada.Exceptions.Traceback;
  54    package SOR renames System.Object_Reader;
  55
  56    type Dwarf_Context (In_Exception : Boolean := False) is private;
  57    --  Type encapsulation the state of the Dwarf reader. When In_Exception
  58    --  is True we are parsing as part of a exception handler decorator, we do
  59    --  not want an exception to be raised, the parsing is done safely skipping
  60    --  DWARF file that cannot be read or with stripped debug section for
  61    --  example.
  62
  63    procedure Open
  64      (File_Name :     String;
  65       C         : out Dwarf_Context;
  66       Success   : out Boolean);
  67    procedure Close (C : in out Dwarf_Context);
  68    --  Open and close files
  69
  70    procedure Set_Load_Address (C : in out Dwarf_Context; Addr : Address);
  71    --  Set the load address of a file. This is used to rebase PIE (Position
  72    --  Independant Executable) binaries.
  73
  74    function Is_Inside (C : Dwarf_Context; Addr : Address) return Boolean;
  75    pragma Inline (Is_Inside);
  76    --  Return true iff Addr is within the module
  77
  78    function Low (C : Dwarf_Context) return Address;
  79    pragma Inline (Low);
  80    --  Return the lowest address of C
  81
  82    procedure Dump (C : in out Dwarf_Context);
  83    --  Dump each row found in the object's .debug_lines section to standard out
  84
  85    procedure Dump_Cache (C : Dwarf_Context);
  86    --  Dump the cache (if present)
  87
  88    procedure Enable_Cache (C : in out Dwarf_Context);
  89    --  Read symbols information to speed up Symbolic_Traceback.
  90
  91    procedure Symbolic_Traceback
  92      (Cin          :        Dwarf_Context;
  93       Traceback    :        AET.Tracebacks_Array;
  94       Suppress_Hex :        Boolean;
  95       Symbol_Found : in out Boolean;
  96       Res          : in out System.Bounded_Strings.Bounded_String);
  97    --  Generate a string for a traceback suitable for displaying to the user.
  98    --  If one or more symbols are found, Symbol_Found is set to True. This
  99    --  allows the caller to fall back to hexadecimal addresses.
 100
 101    Dwarf_Error : exception;
 102    --  Raised if a problem is encountered parsing DWARF information. Can be a
 103    --  result of a logic error or malformed DWARF information.
 104
 105 private
 106    --  The following section numbers reference
 107
 108    --    "DWARF Debugging Information Format, Version 3"
 109
 110    --  published by the Standards Group, http://freestandards.org.
 111
 112    --  6.2.2 State Machine Registers
 113
 114    type Line_Info_Registers is record
 115       Address        : SOR.uint64;
 116       File           : SOR.uint32;
 117       Line           : SOR.uint32;
 118       Column         : SOR.uint32;
 119       Is_Stmt        : Boolean;
 120       Basic_Block    : Boolean;
 121       End_Sequence   : Boolean;
 122       Prologue_End   : Boolean;
 123       Epilogue_Begin : Boolean;
 124       ISA            : SOR.uint32;
 125       Is_Row         : Boolean;
 126    end record;
 127
 128    --  6.2.4 The Line Number Program Prologue
 129
 130    MAX_OPCODE_LENGTHS : constant := 256;
 131
 132    type Opcodes_Lengths_Array is
 133      array (SOR.uint32 range 1 .. MAX_OPCODE_LENGTHS) of SOR.uint8;
 134
 135    type Line_Info_Prologue is record
 136       Unit_Length       : SOR.uint32;
 137       Version           : SOR.uint16;
 138       Prologue_Length   : SOR.uint32;
 139       Min_Isn_Length    : SOR.uint8;
 140       Default_Is_Stmt   : SOR.uint8;
 141       Line_Base         : SOR.int8;
 142       Line_Range        : SOR.uint8;
 143       Opcode_Base       : SOR.uint8;
 144       Opcode_Lengths    : Opcodes_Lengths_Array;
 145       Includes_Offset   : SOR.Offset;
 146       File_Names_Offset : SOR.Offset;
 147    end record;
 148
 149    type Search_Entry is record
 150       First : SOR.uint32;
 151       Size  : SOR.uint32;
 152       --  Function bounds as offset to the base address.
 153
 154       Sym : SOR.uint32;
 155       --  Symbol offset to get the name.
 156
 157       Line : SOR.uint32;
 158       --  Dwarf line offset.
 159    end record;
 160
 161    type Search_Array is array (Natural range <>) of Search_Entry;
 162
 163    type Search_Array_Access is access Search_Array;
 164
 165    type Dwarf_Context (In_Exception : Boolean := False) is record
 166       Load_Slide : System.Storage_Elements.Integer_Address := 0;
 167       Low, High  : Address;
 168       --  Bounds of the module
 169
 170       Obj : SOR.Object_File_Access;
 171       --  The object file containing dwarf sections
 172
 173       Has_Debug : Boolean;
 174       --  True if all debug sections are available
 175
 176       Cache : Search_Array_Access;
 177       --  Quick access to symbol and debug info (when present).
 178
 179       Lines   : SOR.Mapped_Stream;
 180       Aranges : SOR.Mapped_Stream;
 181       Info    : SOR.Mapped_Stream;
 182       Abbrev  : SOR.Mapped_Stream;
 183       --  Dwarf line, aranges, info and abbrev sections
 184
 185       Prologue      : Line_Info_Prologue;
 186       Registers     : Line_Info_Registers;
 187       Next_Prologue : SOR.Offset;
 188       --  State for lines
 189    end record;
 190
 191 end System.Dwarf_Lines;