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