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-2020, 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
41with Ada.Exceptions.Traceback;
42
43with System.Object_Reader;
44with System.Storage_Elements;
45with System.Bounded_Strings;
46
47package System.Dwarf_Lines is
48
49   package AET renames Ada.Exceptions.Traceback;
50   package SOR renames System.Object_Reader;
51
52   type Dwarf_Context (In_Exception : Boolean := False) is private;
53   --  Type encapsulation the state of the Dwarf reader. When In_Exception
54   --  is True we are parsing as part of a exception handler decorator, we do
55   --  not want an exception to be raised, the parsing is done safely skipping
56   --  DWARF file that cannot be read or with stripped debug section for
57   --  example.
58
59   procedure Open
60     (File_Name :     String;
61      C         : out Dwarf_Context;
62      Success   : out Boolean);
63   procedure Close (C : in out Dwarf_Context);
64   --  Open and close files
65
66   procedure Set_Load_Address (C : in out Dwarf_Context; Addr : Address);
67   --  Set the load address of a file. This is used to rebase PIE (Position
68   --  Independant Executable) binaries.
69
70   function Is_Inside (C : Dwarf_Context; Addr : Address) return Boolean;
71   pragma Inline (Is_Inside);
72   --  Return true iff a run-time address Addr is within the module
73
74   function Low_Address (C : Dwarf_Context)
75      return System.Address;
76   pragma Inline (Low_Address);
77   --  Return the lowest address of C, accounting for the module load address
78
79   procedure Dump (C : in out Dwarf_Context);
80   --  Dump each row found in the object's .debug_lines section to standard out
81
82   procedure Dump_Cache (C : Dwarf_Context);
83   --  Dump the cache (if present)
84
85   procedure Enable_Cache (C : in out Dwarf_Context);
86   --  Read symbols information to speed up Symbolic_Traceback.
87
88   procedure Symbolic_Traceback
89     (Cin          :        Dwarf_Context;
90      Traceback    :        AET.Tracebacks_Array;
91      Suppress_Hex :        Boolean;
92      Symbol_Found :    out Boolean;
93      Res          : in out System.Bounded_Strings.Bounded_String);
94   --  Generate a string for a traceback suitable for displaying to the user.
95   --  If one or more symbols are found, Symbol_Found is set to True. This
96   --  allows the caller to fall back to hexadecimal addresses.
97
98   Dwarf_Error : exception;
99   --  Raised if a problem is encountered parsing DWARF information. Can be a
100   --  result of a logic error or malformed DWARF information.
101
102private
103   --  The following section numbers reference
104
105   --    "DWARF Debugging Information Format, Version 3"
106
107   --  published by the Standards Group, http://freestandards.org.
108
109   --  6.2.2 State Machine Registers
110
111   type Line_Info_Registers is record
112      Address        : SOR.uint64;
113      File           : SOR.uint32;
114      Line           : SOR.uint32;
115      Column         : SOR.uint32;
116      Is_Stmt        : Boolean;
117      Basic_Block    : Boolean;
118      End_Sequence   : Boolean;
119      Prologue_End   : Boolean;
120      Epilogue_Begin : Boolean;
121      ISA            : SOR.uint32;
122      Is_Row         : Boolean;
123   end record;
124
125   --  6.2.4 The Line Number Program Prologue
126
127   MAX_OPCODE_LENGTHS : constant := 256;
128
129   type Opcodes_Lengths_Array is
130     array (SOR.uint32 range 1 .. MAX_OPCODE_LENGTHS) of SOR.uint8;
131
132   type Line_Info_Prologue is record
133      Unit_Length       : SOR.uint32;
134      Version           : SOR.uint16;
135      Prologue_Length   : SOR.uint32;
136      Min_Isn_Length    : SOR.uint8;
137      Default_Is_Stmt   : SOR.uint8;
138      Line_Base         : SOR.int8;
139      Line_Range        : SOR.uint8;
140      Opcode_Base       : SOR.uint8;
141      Opcode_Lengths    : Opcodes_Lengths_Array;
142      Includes_Offset   : SOR.Offset;
143      File_Names_Offset : SOR.Offset;
144   end record;
145
146   type Search_Entry is record
147      First : SOR.uint32;
148      Size  : SOR.uint32;
149      --  Function bounds as offset to the base address.
150
151      Sym : SOR.uint32;
152      --  Symbol offset to get the name.
153
154      Line : SOR.uint32;
155      --  Dwarf line offset.
156   end record;
157
158   type Search_Array is array (Natural range <>) of Search_Entry;
159
160   type Search_Array_Access is access Search_Array;
161
162   type Dwarf_Context (In_Exception : Boolean := False) is record
163      Low, High  : System.Storage_Elements.Storage_Offset;
164      --  Bounds of the module, per the module object file
165
166      Obj : SOR.Object_File_Access;
167      --  The object file containing dwarf sections
168
169      Load_Address : System.Address := System.Null_Address;
170      --  The address at which the object file was loaded at run time
171
172      Has_Debug : Boolean;
173      --  True if all debug sections are available
174
175      Cache : Search_Array_Access;
176      --  Quick access to symbol and debug info (when present).
177
178      Lines   : SOR.Mapped_Stream;
179      Aranges : SOR.Mapped_Stream;
180      Info    : SOR.Mapped_Stream;
181      Abbrev  : SOR.Mapped_Stream;
182      --  Dwarf line, aranges, info and abbrev sections
183
184      Prologue      : Line_Info_Prologue;
185      Registers     : Line_Info_Registers;
186      Next_Prologue : SOR.Offset;
187      --  State for lines
188   end record;
189
190end System.Dwarf_Lines;
191