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