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