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