1 2 /*--------------------------------------------------------------------*/ 3 /*--- Debug info. pub_core_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_CORE_DEBUGINFO_H 32 #define __PUB_CORE_DEBUGINFO_H 33 34 //-------------------------------------------------------------------- 35 // PURPOSE: This module deals with reading debug info and symbol tables 36 // to get file and function names, line numbers, variable types, and 37 // to help stack unwinding. 38 //-------------------------------------------------------------------- 39 40 #include "pub_tool_debuginfo.h" 41 42 /* Initialise the entire module. Must be called first of all. */ 43 extern void VG_(di_initialise) ( void ); 44 45 /* LINUX: Notify the debuginfo system about a new mapping, or the 46 disappearance of such, or a permissions change on an existing 47 mapping. This is the way new debug information gets loaded. If 48 allow_SkFileV is True, it will try load debug info if the mapping 49 at 'a' belongs to Valgrind; whereas normally (False) it will not do 50 that. This allows us to carefully control when the thing will read 51 symbols from the Valgrind executable itself. 52 53 If a call to VG_(di_notify_mmap) causes debug info to be read, then 54 the returned ULong is an abstract handle which can later be used to 55 refer to the debuginfo read as a result of this specific mapping, 56 in later queries to m_debuginfo. In this case the handle value 57 will be one or above. If the returned value is zero, no debug info 58 was read. 59 60 For VG_(di_notify_mmap), if use_fd is not -1, that is used instead 61 of the filename; this avoids perturbing fcntl locks, which are 62 released by simply re-opening and closing the same file (even via 63 different fd!). 64 */ 65 #if defined(VGO_linux) || defined(VGO_darwin) || defined(VGO_solaris) || defined(VGO_dragonfly) 66 extern ULong VG_(di_notify_mmap)( Addr a, Bool allow_SkFileV, Int use_fd ); 67 68 extern void VG_(di_notify_munmap)( Addr a, SizeT len ); 69 70 extern void VG_(di_notify_mprotect)( Addr a, SizeT len, UInt prot ); 71 72 /* this should really return ULong, as per VG_(di_notify_mmap). */ 73 extern void VG_(di_notify_pdb_debuginfo)( Int fd, Addr avma, 74 SizeT total_size, 75 PtrdiffT bias ); 76 77 /* this should also really return ULong */ 78 extern void VG_(di_notify_vm_protect)( Addr a, SizeT len, UInt prot ); 79 #endif 80 81 extern void VG_(di_discard_ALL_debuginfo)( void ); 82 83 /* Like VG_(get_fnname), but it does not do C++ demangling nor Z-demangling 84 * nor below-main renaming. 85 * It should not be used for any names that will be shown to users. 86 * It should only be used in cases where the names of interest will have 87 * particular (ie. non-mangled) forms, or the mangled form is acceptable. */ 88 extern 89 Bool VG_(get_fnname_raw) ( DiEpoch ep, Addr a, const HChar** buf ); 90 91 /* Like VG_(get_fnname), but without C++ demangling. (But it does 92 Z-demangling and below-main renaming.) 93 iipc argument: same usage as in VG_(describe_IP) in pub_tool_debuginfo.h. */ 94 extern 95 Bool VG_(get_fnname_no_cxx_demangle) ( DiEpoch ep, Addr a, const HChar** buf, 96 const InlIPCursor* iipc ); 97 98 /* mips-linux only: find the offset of current address. This is needed for 99 stack unwinding for MIPS. 100 */ 101 extern 102 Bool VG_(get_inst_offset_in_function)( DiEpoch ep, Addr a, 103 /*OUT*/PtrdiffT* offset ); 104 105 106 /* Use DWARF2/3 CFA information to do one step of stack unwinding. 107 D3UnwindRegs holds the current register values, and is 108 arch-specific. Note that the x86 and amd64 definitions are shared 109 and so the regs are named 'xip' etc rather than 'eip' and 'rip'. */ 110 #if defined(VGA_amd64) || defined(VGA_x86) 111 typedef 112 struct { Addr xip; Addr xsp; Addr xbp; } 113 D3UnwindRegs; 114 #elif defined(VGA_arm) 115 typedef 116 struct { Addr r15; Addr r14; Addr r13; Addr r12; Addr r11; Addr r7; } 117 D3UnwindRegs; 118 #elif defined(VGA_arm64) 119 typedef 120 struct { Addr pc; Addr sp; Addr x30; Addr x29; } /* PC, SP, LR, FP */ 121 D3UnwindRegs; 122 #elif defined(VGA_ppc32) || defined(VGA_ppc64be) || defined(VGA_ppc64le) 123 typedef 124 UChar /* should be void, but gcc complains at use points */ 125 D3UnwindRegs; 126 #elif defined(VGA_s390x) 127 typedef 128 struct { Addr ia; Addr sp; Addr fp; Addr lr;} 129 D3UnwindRegs; 130 #elif defined(VGA_mips32) || defined(VGA_mips64) 131 typedef 132 struct { Addr pc; Addr sp; Addr fp; Addr ra; } 133 D3UnwindRegs; 134 #else 135 # error "Unsupported arch" 136 #endif 137 138 extern Bool VG_(use_CF_info) ( /*MOD*/D3UnwindRegs* uregs, 139 Addr min_accessible, 140 Addr max_accessible ); 141 142 /* returns the "generation" of the debug info. 143 Each time some debuginfo is changed (e.g. loaded or unloaded), 144 the VG_(debuginfo_generation)() value returned will be increased. 145 This can be used to flush cached information derived from debug 146 info (e.g. CFI info or FPO info or ...). */ 147 extern UInt VG_(debuginfo_generation) (void); 148 149 150 151 /* True if some FPO information is loaded. 152 It is useless to call VG_(use_FPO_info) if this returns False. 153 Note that the return value should preferably be cached in 154 the stack unwind code, and re-queried when the debug info generation 155 changes. */ 156 extern Bool VG_(FPO_info_present)(void); 157 158 /* Use MSVC FPO data to do one step of stack unwinding. */ 159 extern Bool VG_(use_FPO_info) ( /*MOD*/Addr* ipP, 160 /*MOD*/Addr* spP, 161 /*MOD*/Addr* fpP, 162 DiEpoch ep, 163 Addr min_accessible, 164 Addr max_accessible ); 165 166 /* Print the unwind info (if there is some) for the given address 167 range [from,to]. */ 168 extern void VG_(ppUnwindInfo) (Addr from, Addr to); 169 170 /* AVMAs for a symbol. Usually only the lowest address of the entity. 171 On ppc64 platforms, also contains tocptr and local_ep. 172 These fields should only be accessed using the macros 173 GET_TOCPTR_AVMA/SET_TOCPTR_AVMA/GET_LOCAL_EP_AVMA/SET_LOCAL_EP_AVMA. */ 174 typedef 175 struct { 176 Addr main; /* lowest address of entity */ 177 # if defined(VGA_ppc64be) || defined(VGA_ppc64le) 178 Addr tocptr; /* ppc64be/le-linux only: value that R2 should have */ 179 # endif 180 # if defined(VGA_ppc64le) 181 Addr local_ep; /* address for local entry point, ppc64le only */ 182 # endif 183 } 184 SymAVMAs; 185 186 #if defined(VGA_ppc64be) || defined(VGA_ppc64le) 187 # define GET_TOCPTR_AVMA(_sym_avmas) (_sym_avmas).tocptr 188 # define SET_TOCPTR_AVMA(_sym_avmas, _val) (_sym_avmas).tocptr = (_val) 189 #else 190 # define GET_TOCPTR_AVMA(_sym_avmas) ((Addr)0) 191 # define SET_TOCPTR_AVMA(_sym_avmas, _val) /* */ 192 #endif 193 194 #if defined(VGA_ppc64le) 195 # define GET_LOCAL_EP_AVMA(_sym_avmas) (_sym_avmas).local_ep 196 # define SET_LOCAL_EP_AVMA(_sym_avmas, _val) (_sym_avmas).local_ep = (_val) 197 #else 198 # define GET_LOCAL_EP_AVMA(_sym_avmas) ((Addr)0) 199 # define SET_LOCAL_EP_AVMA(_sym_avmas, _val) /* */ 200 #endif 201 202 /* Functions for traversing all the symbols in a DebugInfo. _howmany 203 tells how many symbol table entries there are. _getidx retrieves 204 the n'th entry, for n in 0 .. _howmany-1. You may not modify the 205 function names thereby acquired; if you want to do so, first strdup 206 them. The primary name is returned in *pri_name, and *sec_names is 207 set either to NULL or to a NULL terminated vector containing 208 pointers to the secondary names. */ 209 Int VG_(DebugInfo_syms_howmany) ( const DebugInfo *di ); 210 void VG_(DebugInfo_syms_getidx) ( const DebugInfo *di, 211 Int idx, 212 /*OUT*/SymAVMAs* ad, 213 /*OUT*/UInt* size, 214 /*OUT*/const HChar** pri_name, 215 /*OUT*/const HChar*** sec_names, 216 /*OUT*/Bool* isText, 217 /*OUT*/Bool* isIFunc, 218 /*OUT*/Bool* isGlobal ); 219 /* ppc64-linux only: find the TOC pointer (R2 value) that should be in 220 force at the entry point address of the function containing 221 guest_code_addr. Returns 0 if not known. */ 222 extern Addr VG_(get_tocptr) ( DiEpoch ep, Addr guest_code_addr ); 223 224 /* Map a function name to its SymAVMAs. Is done by 225 sequential search of all symbol tables, so is very slow. To 226 mitigate the worst performance effects, you may specify a soname 227 pattern, and only objects matching that pattern are searched. 228 Therefore specify "*" to search all the objects. On TOC-afflicted 229 platforms, a symbol is deemed to be found only if it has a nonzero 230 TOC pointer. */ 231 extern 232 Bool VG_(lookup_symbol_SLOW)(DiEpoch ep, 233 const HChar* sopatt, const HChar* name, 234 SymAVMAs* avmas); 235 236 #endif // __PUB_CORE_DEBUGINFO_H 237 238 /*--------------------------------------------------------------------*/ 239 /*--- end ---*/ 240 /*--------------------------------------------------------------------*/ 241