File : 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-2015, 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 -- --
19 -- --
20 -- --
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
38 -- where object size is a consideration it's possible to strip all
39 -- other .debug sections, which will decrease the size of the object
40 -- significantly.
41
42 pragma Polling (Off);
43 -- We must turn polling off for this unit, because otherwise we can get
44 -- elaboration circularities when polling is turned on
45
46 with Ada.Exceptions.Traceback;
47
48 with System.Object_Reader;
49 with System.Storage_Elements;
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
59 -- do not want an exception to be raised, the parsing is done safely
60 -- skipping DWARF file that cannot be read or with stripped debug section
61 -- for example.
62
63 procedure Open (File_Name : String; C : in out Dwarf_Context);
64 procedure Close (C : in out Dwarf_Context);
65 -- Open and close files
66
67 procedure Set_Load_Address (C : in out Dwarf_Context; Addr : Address);
68 -- Set the load address of a file. This is used to rebase PIE (Position
69 -- Independant Executable) binaries.
70
71 function Is_Open (C : Dwarf_Context) return Boolean;
72 -- Returns True if the context is opened, this is required for non
73 -- exception mode.
74
75 procedure Dump (C : in out Dwarf_Context);
76 -- Dump each row found in the object's .debug_lines section to standard out
77
78 function Symbolic_Traceback
79 (Cin : Dwarf_Context;
80 Traceback : AET.Tracebacks_Array;
81 Symbol_Found : in out Boolean) return String;
82 -- Generate a string for a traceback suitable for displaying to the user.
83 -- If one or more symbols are found, Symbol_Found is set to True. This
84 -- allows the caller to fall back to hexadecimal addresses.
85
86 Dwarf_Error : exception;
87 -- Raised if a problem is encountered parsing DWARF information. Can be a
88 -- result of a logic error or malformed DWARF information.
89
90 private
91 -- The following section numbers reference
92
93 -- "DWARF Debugging Information Format, Version 3"
94
95 -- published by the Standards Group, http://freestandards.org.
96
97 -- 6.2.2 State Machine Registers
98
99 type Line_Info_Registers is record
100 Address : SOR.uint64;
101 File : SOR.uint32;
102 Line : SOR.uint32;
103 Column : SOR.uint32;
104 Is_Stmt : Boolean;
105 Basic_Block : Boolean;
106 End_Sequence : Boolean;
107 Prologue_End : Boolean;
108 Epilogue_Begin : Boolean;
109 ISA : SOR.uint32;
110 Is_Row : Boolean;
111 end record;
112
113 -- 6.2.4 The Line Number Program Prologue
114
115 MAX_OPCODE_LENGTHS : constant := 256;
116
117 type Opcodes_Lengths_Array is array
118 (SOR.uint32 range 1 .. MAX_OPCODE_LENGTHS) of SOR.uint8;
119
120 type Line_Info_Prologue is record
121 Unit_Length : SOR.uint32;
122 Version : SOR.uint16;
123 Prologue_Length : SOR.uint32;
124 Min_Isn_Length : SOR.uint8;
125 Default_Is_Stmt : SOR.uint8;
126 Line_Base : SOR.int8;
127 Line_Range : SOR.uint8;
128 Opcode_Base : SOR.uint8;
129 Opcode_Lengths : Opcodes_Lengths_Array;
130 Includes_Offset : SOR.Offset;
131 File_Names_Offset : SOR.Offset;
132 end record;
133
134 type Dwarf_Context (In_Exception : Boolean := False) is record
135 Valid : Boolean := False;
136 -- True if DWARF context is properly initialized
137
138 Load_Slide : System.Storage_Elements.Integer_Address := 0;
139 Obj : SOR.Object_File_Access;
140 Prologue : Line_Info_Prologue;
141 Registers : Line_Info_Registers;
142 Next_Prologue : SOR.Offset;
143 End_Of_Section : SOR.Offset;
144 end record;
145
146 end System.Dwarf_Lines;