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