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-2018, 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
41pragma 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
45with Ada.Exceptions.Traceback;
46
47with System.Object_Reader;
48with System.Storage_Elements;
49with System.Bounded_Strings;
50
51package 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 a run-time address 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, from the module object file
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
105private
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, per the module object file
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
191end System.Dwarf_Lines;
192