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-2019, 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_Address (C : Dwarf_Context)
79      return System.Address;
80   pragma Inline (Low_Address);
81   --  Return the lowest address of C, accounting for the module load address
82
83   procedure Dump (C : in out Dwarf_Context);
84   --  Dump each row found in the object's .debug_lines section to standard out
85
86   procedure Dump_Cache (C : Dwarf_Context);
87   --  Dump the cache (if present)
88
89   procedure Enable_Cache (C : in out Dwarf_Context);
90   --  Read symbols information to speed up Symbolic_Traceback.
91
92   procedure Symbolic_Traceback
93     (Cin          :        Dwarf_Context;
94      Traceback    :        AET.Tracebacks_Array;
95      Suppress_Hex :        Boolean;
96      Symbol_Found : in out Boolean;
97      Res          : in out System.Bounded_Strings.Bounded_String);
98   --  Generate a string for a traceback suitable for displaying to the user.
99   --  If one or more symbols are found, Symbol_Found is set to True. This
100   --  allows the caller to fall back to hexadecimal addresses.
101
102   Dwarf_Error : exception;
103   --  Raised if a problem is encountered parsing DWARF information. Can be a
104   --  result of a logic error or malformed DWARF information.
105
106private
107   --  The following section numbers reference
108
109   --    "DWARF Debugging Information Format, Version 3"
110
111   --  published by the Standards Group, http://freestandards.org.
112
113   --  6.2.2 State Machine Registers
114
115   type Line_Info_Registers is record
116      Address        : SOR.uint64;
117      File           : SOR.uint32;
118      Line           : SOR.uint32;
119      Column         : SOR.uint32;
120      Is_Stmt        : Boolean;
121      Basic_Block    : Boolean;
122      End_Sequence   : Boolean;
123      Prologue_End   : Boolean;
124      Epilogue_Begin : Boolean;
125      ISA            : SOR.uint32;
126      Is_Row         : Boolean;
127   end record;
128
129   --  6.2.4 The Line Number Program Prologue
130
131   MAX_OPCODE_LENGTHS : constant := 256;
132
133   type Opcodes_Lengths_Array is
134     array (SOR.uint32 range 1 .. MAX_OPCODE_LENGTHS) of SOR.uint8;
135
136   type Line_Info_Prologue is record
137      Unit_Length       : SOR.uint32;
138      Version           : SOR.uint16;
139      Prologue_Length   : SOR.uint32;
140      Min_Isn_Length    : SOR.uint8;
141      Default_Is_Stmt   : SOR.uint8;
142      Line_Base         : SOR.int8;
143      Line_Range        : SOR.uint8;
144      Opcode_Base       : SOR.uint8;
145      Opcode_Lengths    : Opcodes_Lengths_Array;
146      Includes_Offset   : SOR.Offset;
147      File_Names_Offset : SOR.Offset;
148   end record;
149
150   type Search_Entry is record
151      First : SOR.uint32;
152      Size  : SOR.uint32;
153      --  Function bounds as offset to the base address.
154
155      Sym : SOR.uint32;
156      --  Symbol offset to get the name.
157
158      Line : SOR.uint32;
159      --  Dwarf line offset.
160   end record;
161
162   type Search_Array is array (Natural range <>) of Search_Entry;
163
164   type Search_Array_Access is access Search_Array;
165
166   type Dwarf_Context (In_Exception : Boolean := False) is record
167      Low, High  : System.Storage_Elements.Storage_Offset;
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      Load_Address : System.Address := System.Null_Address;
174      --  The address at which the object file was loaded at run time
175
176      Has_Debug : Boolean;
177      --  True if all debug sections are available
178
179      Cache : Search_Array_Access;
180      --  Quick access to symbol and debug info (when present).
181
182      Lines   : SOR.Mapped_Stream;
183      Aranges : SOR.Mapped_Stream;
184      Info    : SOR.Mapped_Stream;
185      Abbrev  : SOR.Mapped_Stream;
186      --  Dwarf line, aranges, info and abbrev sections
187
188      Prologue      : Line_Info_Prologue;
189      Registers     : Line_Info_Registers;
190      Next_Prologue : SOR.Offset;
191      --  State for lines
192   end record;
193
194end System.Dwarf_Lines;
195