coregrind/pub_core_debuginfo.h

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