1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
5 -- S Y S T E M . D W A R F _ L I N E S --
9 -- Copyright (C) 2009-2017, Free Software Foundation, Inc. --
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. --
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. --
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/>. --
27 -- GNAT was originally developed by the GNAT team at New York University. --
28 -- Extensive contributions were provided by Ada Core Technologies Inc. --
30 ------------------------------------------------------------------------------
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.
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.
42 -- We must turn polling off for this unit, because otherwise we can get
43 -- elaboration circularities when polling is turned on
45 with Ada
.Exceptions
.Traceback
;
47 with System
.Object_Reader
;
48 with System
.Storage_Elements
;
49 with System
.Bounded_Strings
;
51 package System
.Dwarf_Lines
is
53 package AET
renames Ada
.Exceptions
.Traceback
;
54 package SOR
renames System
.Object_Reader
;
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
65 C
: out Dwarf_Context
;
66 Success
: out Boolean);
67 procedure Close
(C
: in out Dwarf_Context
);
68 -- Open and close files
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.
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
78 function Low
(C
: Dwarf_Context
) return Address
;
80 -- Return the lowest address of C
82 procedure Dump
(C
: in out Dwarf_Context
);
83 -- Dump each row found in the object's .debug_lines section to standard out
85 procedure Dump_Cache
(C
: Dwarf_Context
);
86 -- Dump the cache (if present)
88 procedure Enable_Cache
(C
: in out Dwarf_Context
);
89 -- Read symbols information to speed up Symbolic_Traceback.
91 procedure Symbolic_Traceback
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.
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.
106 -- The following section numbers reference
108 -- "DWARF Debugging Information Format, Version 3"
110 -- published by the Standards Group, http://freestandards.org.
112 -- 6.2.2 State Machine Registers
114 type Line_Info_Registers
is record
115 Address
: SOR
.uint64
;
120 Basic_Block
: Boolean;
121 End_Sequence
: Boolean;
122 Prologue_End
: Boolean;
123 Epilogue_Begin
: Boolean;
128 -- 6.2.4 The Line Number Program Prologue
130 MAX_OPCODE_LENGTHS
: constant := 256;
132 type Opcodes_Lengths_Array
is
133 array (SOR
.uint32
range 1 .. MAX_OPCODE_LENGTHS
) of SOR
.uint8
;
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
;
149 type Search_Entry
is record
152 -- Function bounds as offset to the base address.
155 -- Symbol offset to get the name.
158 -- Dwarf line offset.
161 type Search_Array
is array (Natural range <>) of Search_Entry
;
163 type Search_Array_Access
is access Search_Array
;
165 type Dwarf_Context
(In_Exception
: Boolean := False) is record
166 Load_Slide
: System
.Storage_Elements
.Integer_Address
:= 0;
168 -- Bounds of the module
170 Obj
: SOR
.Object_File_Access
;
171 -- The object file containing dwarf sections
174 -- True if all debug sections are available
176 Cache
: Search_Array_Access
;
177 -- Quick access to symbol and debug info (when present).
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
185 Prologue
: Line_Info_Prologue
;
186 Registers
: Line_Info_Registers
;
187 Next_Prologue
: SOR
.Offset
;
191 end System
.Dwarf_Lines
;