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-2018, 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 (C : Dwarf_Context) return Address; 79 pragma Inline (Low); 80 -- Return the lowest address of C, from the module object file 81 82 procedure Dump (C : in out Dwarf_Context); 83 -- Dump each row found in the object's .debug_lines section to standard out 84 85 procedure Dump_Cache (C : Dwarf_Context); 86 -- Dump the cache (if present) 87 88 procedure Enable_Cache (C : in out Dwarf_Context); 89 -- Read symbols information to speed up Symbolic_Traceback. 90 91 procedure Symbolic_Traceback 92 (Cin : Dwarf_Context; 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. 100 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. 104 105private 106 -- The following section numbers reference 107 108 -- "DWARF Debugging Information Format, Version 3" 109 110 -- published by the Standards Group, http://freestandards.org. 111 112 -- 6.2.2 State Machine Registers 113 114 type Line_Info_Registers is record 115 Address : SOR.uint64; 116 File : SOR.uint32; 117 Line : SOR.uint32; 118 Column : SOR.uint32; 119 Is_Stmt : Boolean; 120 Basic_Block : Boolean; 121 End_Sequence : Boolean; 122 Prologue_End : Boolean; 123 Epilogue_Begin : Boolean; 124 ISA : SOR.uint32; 125 Is_Row : Boolean; 126 end record; 127 128 -- 6.2.4 The Line Number Program Prologue 129 130 MAX_OPCODE_LENGTHS : constant := 256; 131 132 type Opcodes_Lengths_Array is 133 array (SOR.uint32 range 1 .. MAX_OPCODE_LENGTHS) of SOR.uint8; 134 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; 147 end record; 148 149 type Search_Entry is record 150 First : SOR.uint32; 151 Size : SOR.uint32; 152 -- Function bounds as offset to the base address. 153 154 Sym : SOR.uint32; 155 -- Symbol offset to get the name. 156 157 Line : SOR.uint32; 158 -- Dwarf line offset. 159 end record; 160 161 type Search_Array is array (Natural range <>) of Search_Entry; 162 163 type Search_Array_Access is access Search_Array; 164 165 type Dwarf_Context (In_Exception : Boolean := False) is record 166 Load_Slide : System.Storage_Elements.Integer_Address := 0; 167 Low, High : Address; 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 Has_Debug : Boolean; 174 -- True if all debug sections are available 175 176 Cache : Search_Array_Access; 177 -- Quick access to symbol and debug info (when present). 178 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 184 185 Prologue : Line_Info_Prologue; 186 Registers : Line_Info_Registers; 187 Next_Prologue : SOR.Offset; 188 -- State for lines 189 end record; 190 191end System.Dwarf_Lines; 192