1 2 /*--------------------------------------------------------------------*/ 3 /*--- DebugInfo. pub_tool_debuginfo.h ---*/ 4 /*--------------------------------------------------------------------*/ 5 6 /* 7 This file is part of Valgrind, a dynamic binary instrumentation 8 framework. 9 10 Copyright (C) 2000-2013 Julian Seward 11 jseward (at) acm.org 12 13 This program is free software; you can redistribute it and/or 14 modify it under the terms of the GNU General Public License as 15 published by the Free Software Foundation; either version 2 of the 16 License, or (at your option) any later version. 17 18 This program is distributed in the hope that it will be useful, but 19 WITHOUT ANY WARRANTY; without even the implied warranty of 20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 21 General Public License for more details. 22 23 You should have received a copy of the GNU General Public License 24 along with this program; if not, write to the Free Software 25 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 26 02111-1307, USA. 27 28 The GNU General Public License is contained in the file COPYING. 29 */ 30 31 #ifndef __PUB_TOOL_DEBUGINFO_H 32 #define __PUB_TOOL_DEBUGINFO_H 33 34 #include "pub_tool_basics.h" // VG_ macro 35 36 /*====================================================================*/ 37 /*=== Obtaining debug information ===*/ 38 /*====================================================================*/ 39 40 /* Get the file/function/line number of the instruction at address 41 'a'. For these four, if debug info for the address is found, it 42 copies the info into the buffer/UInt and returns True. If not, it 43 returns False and nothing is copied. VG_(get_fnname) always 44 demangles C++ function names. VG_(get_fnname_w_offset) is the 45 same, except it appends "+N" to symbol names to indicate offsets. */ 46 extern Bool VG_(get_filename) ( Addr a, HChar* filename, Int n_filename ); 47 extern Bool VG_(get_fnname) ( Addr a, HChar* fnname, Int n_fnname ); 48 extern Bool VG_(get_linenum) ( Addr a, UInt* linenum ); 49 extern Bool VG_(get_fnname_w_offset) 50 ( Addr a, HChar* fnname, Int n_fnname ); 51 52 /* This one is the most general. It gives filename, line number and 53 optionally directory name. filename and linenum may not be NULL. 54 dirname may be NULL, meaning that the caller does not want 55 directory name info, in which case dirname_available must also be 56 NULL. If dirname is non-null, directory info is written to it, if 57 it is available; if not available, '\0' is written to the first 58 byte. In either case *dirname_available is set to indicate whether 59 or not directory information was available. 60 61 Returned value indicates whether any filename/line info could be 62 found. */ 63 extern Bool VG_(get_filename_linenum) 64 ( Addr a, 65 /*OUT*/HChar* filename, Int n_filename, 66 /*OUT*/HChar* dirname, Int n_dirname, 67 /*OUT*/Bool* dirname_available, 68 /*OUT*/UInt* linenum ); 69 70 /* Succeeds only if we find from debug info that 'a' is the address of the 71 first instruction in a function -- as opposed to VG_(get_fnname) which 72 succeeds if we find from debug info that 'a' is the address of any 73 instruction in a function. Use this to instrument the start of 74 a particular function. Nb: if an executable/shared object is stripped 75 of its symbols, this function will not be able to recognise function 76 entry points within it. */ 77 extern Bool VG_(get_fnname_if_entry) ( Addr a, HChar* fnname, Int n_fnname ); 78 79 typedef 80 enum { 81 Vg_FnNameNormal, // A normal function. 82 Vg_FnNameMain, // "main" 83 Vg_FnNameBelowMain // Something below "main", eg. __libc_start_main. 84 } Vg_FnNameKind; // Such names are often filtered. 85 86 /* Indicates what kind of fnname it is. */ 87 extern Vg_FnNameKind VG_(get_fnname_kind) ( HChar* name ); 88 89 /* Like VG_(get_fnname_kind), but takes a code address. */ 90 extern Vg_FnNameKind VG_(get_fnname_kind_from_IP) ( Addr ip ); 91 92 /* Looks up data_addr in the collection of data symbols, and if found 93 puts its name (or as much as will fit) into dname[0 .. n_dname-1], 94 which is guaranteed to be zero terminated. Also data_addr's offset 95 from the symbol start is put into *offset. */ 96 extern Bool VG_(get_datasym_and_offset)( Addr data_addr, 97 /*OUT*/HChar* dname, Int n_dname, 98 /*OUT*/PtrdiffT* offset ); 99 100 /* Try to form some description of DATA_ADDR by looking at the DWARF3 101 debug info we have. This considers all global variables, and 8 102 frames in the stacks of all threads. Result is written at the ends 103 of DNAME{1,2}V, which are XArray*s of HChar, that have been 104 initialised by the caller, and True is returned. If no description 105 is created, False is returned. Regardless of the return value, 106 DNAME{1,2}V are guaranteed to be zero terminated after the call. 107 108 Note that after the call, DNAME{1,2} may have more than one 109 trailing zero, so callers should establish the useful text length 110 using VG_(strlen) on the contents, rather than VG_(sizeXA) on the 111 XArray itself. 112 */ 113 Bool VG_(get_data_description)( 114 /*MOD*/ void* /* really, XArray* of HChar */ dname1v, 115 /*MOD*/ void* /* really, XArray* of HChar */ dname2v, 116 Addr data_addr 117 ); 118 119 /* Succeeds if the address is within a shared object or the main executable. 120 It doesn't matter if debug info is present or not. */ 121 extern Bool VG_(get_objname) ( Addr a, HChar* objname, Int n_objname ); 122 123 /* Puts into 'buf' info about the code address %eip: the address, function 124 name (if known) and filename/line number (if known), like this: 125 126 0x4001BF05: realloc (vg_replace_malloc.c:339) 127 128 'n_buf' gives length of 'buf'. Returns 'buf'. 129 */ 130 extern HChar* VG_(describe_IP)(Addr eip, HChar* buf, Int n_buf); 131 132 133 /* Get an XArray of StackBlock which describe the stack (auto) blocks 134 for this ip. The caller is expected to free the XArray at some 135 point. If 'arrays_only' is True, only array-typed blocks are 136 returned; otherwise blocks of all types are returned. */ 137 138 typedef 139 struct { 140 PtrdiffT base; /* offset from sp or fp */ 141 SizeT szB; /* size in bytes */ 142 Bool spRel; /* True => sp-rel, False => fp-rel */ 143 Bool isVec; /* does block have an array type, or not? */ 144 HChar name[16]; /* first 15 chars of name (asciiz) */ 145 } 146 StackBlock; 147 148 extern void* /* really, XArray* of StackBlock */ 149 VG_(di_get_stack_blocks_at_ip)( Addr ip, Bool arrays_only ); 150 151 152 /* Get an array of GlobalBlock which describe the global blocks owned 153 by the shared object characterised by the given di_handle. Asserts 154 if the handle is invalid. The caller is responsible for freeing 155 the array at some point. If 'arrays_only' is True, only 156 array-typed blocks are returned; otherwise blocks of all types are 157 returned. */ 158 159 typedef 160 struct { 161 Addr addr; 162 SizeT szB; 163 Bool isVec; /* does block have an array type, or not? */ 164 HChar name[16]; /* first 15 chars of name (asciiz) */ 165 HChar soname[16]; /* first 15 chars of name (asciiz) */ 166 } 167 GlobalBlock; 168 169 extern void* /* really, XArray* of GlobalBlock */ 170 VG_(di_get_global_blocks_from_dihandle) ( ULong di_handle, 171 Bool arrays_only ); 172 173 174 /*====================================================================*/ 175 /*=== Obtaining debug information ===*/ 176 /*====================================================================*/ 177 178 /* A way to make limited debuginfo queries on a per-mapped-object 179 basis. */ 180 typedef struct _DebugInfo DebugInfo; 181 182 /* Returns NULL if the DebugInfo isn't found. It doesn't matter if 183 debug info is present or not. */ 184 DebugInfo* VG_(find_DebugInfo) ( Addr a ); 185 186 /* Fish bits out of DebugInfos. */ 187 Addr VG_(DebugInfo_get_text_avma) ( const DebugInfo *di ); 188 SizeT VG_(DebugInfo_get_text_size) ( const DebugInfo *di ); 189 Addr VG_(DebugInfo_get_bss_avma) ( const DebugInfo *di ); 190 SizeT VG_(DebugInfo_get_bss_size) ( const DebugInfo *di ); 191 Addr VG_(DebugInfo_get_plt_avma) ( const DebugInfo *di ); 192 SizeT VG_(DebugInfo_get_plt_size) ( const DebugInfo *di ); 193 Addr VG_(DebugInfo_get_gotplt_avma) ( const DebugInfo *di ); 194 SizeT VG_(DebugInfo_get_gotplt_size) ( const DebugInfo *di ); 195 Addr VG_(DebugInfo_get_got_avma) ( const DebugInfo *di ); 196 SizeT VG_(DebugInfo_get_got_size) ( const DebugInfo *di ); 197 const HChar* VG_(DebugInfo_get_soname) ( const DebugInfo *di ); 198 const HChar* VG_(DebugInfo_get_filename) ( const DebugInfo *di ); 199 PtrdiffT VG_(DebugInfo_get_text_bias) ( const DebugInfo *di ); 200 201 /* Function for traversing the DebugInfo list. When called with NULL 202 it returns the first element; otherwise it returns the given 203 element's successor. Note that the order of elements in the list 204 changes in response to most of the queries listed in this header, 205 that explicitly or implicitly have to search the list for a 206 particular code address. So it isn't safe to assume that the order 207 of the list stays constant. */ 208 const DebugInfo* VG_(next_DebugInfo) ( const DebugInfo *di ); 209 210 /* Functions for traversing all the symbols in a DebugInfo. _howmany 211 tells how many symbol table entries there are. _getidx retrieves 212 the n'th entry, for n in 0 .. _howmany-1. You may not modify the 213 function names thereby acquired; if you want to do so, first strdup 214 them. The primary name is returned in *pri_name, and *sec_names is 215 set either to NULL or to a NULL terminated vector containing 216 pointers to the secondary names. */ 217 Int VG_(DebugInfo_syms_howmany) ( const DebugInfo *di ); 218 void VG_(DebugInfo_syms_getidx) ( const DebugInfo *di, 219 Int idx, 220 /*OUT*/Addr* avma, 221 /*OUT*/Addr* tocptr, 222 /*OUT*/UInt* size, 223 /*OUT*/HChar** pri_name, 224 /*OUT*/HChar*** sec_names, 225 /*OUT*/Bool* isText, 226 /*OUT*/Bool* isIFunc ); 227 228 /* A simple enumeration to describe the 'kind' of various kinds of 229 segments that arise from the mapping of object files. */ 230 typedef 231 enum { 232 Vg_SectUnknown, 233 Vg_SectText, 234 Vg_SectData, 235 Vg_SectBSS, 236 Vg_SectGOT, 237 Vg_SectPLT, 238 Vg_SectGOTPLT, 239 Vg_SectOPD 240 } 241 VgSectKind; 242 243 /* Convert a VgSectKind to a string, which must be copied if you want 244 to change it. */ 245 const HChar* VG_(pp_SectKind)( VgSectKind kind ); 246 247 /* Given an address 'a', make a guess of which section of which object 248 it comes from. If name is non-NULL, then the last n_name-1 249 characters of the object's name is put in name[0 .. n_name-2], and 250 name[n_name-1] is set to zero (guaranteed zero terminated). */ 251 VgSectKind VG_(DebugInfo_sect_kind)( /*OUT*/HChar* name, SizeT n_name, 252 Addr a); 253 254 255 #endif // __PUB_TOOL_DEBUGINFO_H 256 257 /*--------------------------------------------------------------------*/ 258 /*--- end ---*/ 259 /*--------------------------------------------------------------------*/ 260
