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. */
43extern 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)
66extern ULong VG_(di_notify_mmap)( Addr a, Bool allow_SkFileV, Int use_fd );
67
68extern void VG_(di_notify_munmap)( Addr a, SizeT len );
69
70extern void VG_(di_notify_mprotect)( Addr a, SizeT len, UInt prot );
71
72/* this should really return ULong, as per VG_(di_notify_mmap). */
73extern 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 */
78extern void VG_(di_notify_vm_protect)( Addr a, SizeT len, UInt prot );
79#endif
80
81extern 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. */
88extern
89Bool VG_(get_fnname_raw) ( 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. */
94extern
95Bool VG_(get_fnname_no_cxx_demangle) ( 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*/
101extern
102Bool VG_(get_inst_offset_in_function)( Addr a, /*OUT*/PtrdiffT* offset );
103
104
105/* Use DWARF2/3 CFA information to do one step of stack unwinding.
106   D3UnwindRegs holds the current register values, and is
107   arch-specific.  Note that the x86 and amd64 definitions are shared
108   and so the regs are named 'xip' etc rather than 'eip' and 'rip'. */
109#if defined(VGA_amd64) || defined(VGA_x86)
110typedef
111   struct { Addr xip; Addr xsp; Addr xbp; }
112   D3UnwindRegs;
113#elif defined(VGA_arm)
114typedef
115   struct { Addr r15; Addr r14; Addr r13; Addr r12; Addr r11; Addr r7; }
116   D3UnwindRegs;
117#elif defined(VGA_arm64)
118typedef
119   struct { Addr pc; Addr sp; Addr x30; Addr x29; } /* PC, SP, LR, FP */
120   D3UnwindRegs;
121#elif defined(VGA_ppc32) || defined(VGA_ppc64be) || defined(VGA_ppc64le)
122typedef
123   UChar  /* should be void, but gcc complains at use points */
124   D3UnwindRegs;
125#elif defined(VGA_s390x)
126typedef
127   struct { Addr ia; Addr sp; Addr fp; Addr lr;}
128   D3UnwindRegs;
129#elif defined(VGA_mips32) || defined(VGA_mips64)
130typedef
131   struct { Addr pc; Addr sp; Addr fp; Addr ra; }
132   D3UnwindRegs;
133#else
134#  error "Unsupported arch"
135#endif
136
137extern Bool VG_(use_CF_info) ( /*MOD*/D3UnwindRegs* uregs,
138                               Addr min_accessible,
139                               Addr max_accessible );
140
141/* returns the "generation" of the debug info.
142   Each time some debuginfo is changed (e.g. loaded or unloaded),
143   the VG_(debuginfo_generation)() value returned will be increased.
144   This can be used to flush cached information derived from debug
145   info (e.g. CFI info or FPO info or ...). */
146extern UInt VG_(debuginfo_generation) (void);
147
148
149
150/* True if some FPO information is loaded.
151   It is useless to call VG_(use_FPO_info) if this returns False.
152   Note that the return value should preferably be cached in
153   the stack unwind code, and re-queried when the debug info generation
154   changes. */
155extern Bool VG_(FPO_info_present)(void);
156
157/* Use MSVC FPO data to do one step of stack unwinding. */
158extern Bool VG_(use_FPO_info) ( /*MOD*/Addr* ipP,
159                                /*MOD*/Addr* spP,
160                                /*MOD*/Addr* fpP,
161                                Addr min_accessible,
162                                Addr max_accessible );
163
164/* Print the unwind info (if there is some) for the given address
165   range [from,to]. */
166extern void VG_(ppUnwindInfo) (Addr from, Addr to);
167
168/* AVMAs for a symbol. Usually only the lowest address of the entity.
169   On ppc64 platforms, also contains tocptr and local_ep.
170   These fields should only be accessed using the macros
171   GET_TOCPTR_AVMA/SET_TOCPTR_AVMA/GET_LOCAL_EP_AVMA/SET_LOCAL_EP_AVMA. */
172typedef
173   struct {
174      Addr main;      /* lowest address of entity */
175#     if defined(VGA_ppc64be) || defined(VGA_ppc64le)
176      Addr tocptr;    /* ppc64be/le-linux only: value that R2 should have */
177#     endif
178#     if defined(VGA_ppc64le)
179      Addr local_ep;  /* address for local entry point, ppc64le only */
180#     endif
181   }
182   SymAVMAs;
183
184#if defined(VGA_ppc64be) || defined(VGA_ppc64le)
185# define GET_TOCPTR_AVMA(_sym_avmas)          (_sym_avmas).tocptr
186# define SET_TOCPTR_AVMA(_sym_avmas, _val)    (_sym_avmas).tocptr = (_val)
187#else
188# define GET_TOCPTR_AVMA(_sym_avmas)          ((Addr)0)
189# define SET_TOCPTR_AVMA(_sym_avmas, _val)    /* */
190#endif
191
192#if defined(VGA_ppc64le)
193# define GET_LOCAL_EP_AVMA(_sym_avmas)        (_sym_avmas).local_ep
194# define SET_LOCAL_EP_AVMA(_sym_avmas, _val)  (_sym_avmas).local_ep = (_val)
195#else
196# define GET_LOCAL_EP_AVMA(_sym_avmas)        ((Addr)0)
197# define SET_LOCAL_EP_AVMA(_sym_avmas, _val)  /* */
198#endif
199
200/* Functions for traversing all the symbols in a DebugInfo.  _howmany
201   tells how many symbol table entries there are.  _getidx retrieves
202   the n'th entry, for n in 0 .. _howmany-1.  You may not modify the
203   function names thereby acquired; if you want to do so, first strdup
204   them.  The primary name is returned in *pri_name, and *sec_names is
205   set either to NULL or to a NULL terminated vector containing
206   pointers to the secondary names. */
207Int  VG_(DebugInfo_syms_howmany) ( const DebugInfo *di );
208void VG_(DebugInfo_syms_getidx)  ( const DebugInfo *di,
209                                   Int idx,
210                                   /*OUT*/SymAVMAs* ad,
211                                   /*OUT*/UInt*     size,
212                                   /*OUT*/const HChar**   pri_name,
213                                   /*OUT*/const HChar***  sec_names,
214                                   /*OUT*/Bool*     isText,
215                                   /*OUT*/Bool*     isIFunc,
216                                   /*OUT*/Bool*     isGlobal );
217/* ppc64-linux only: find the TOC pointer (R2 value) that should be in
218   force at the entry point address of the function containing
219   guest_code_addr.  Returns 0 if not known. */
220extern Addr VG_(get_tocptr) ( Addr guest_code_addr );
221
222/* Map a function name to its SymAVMAs.  Is done by
223   sequential search of all symbol tables, so is very slow.  To
224   mitigate the worst performance effects, you may specify a soname
225   pattern, and only objects matching that pattern are searched.
226   Therefore specify "*" to search all the objects.  On TOC-afflicted
227   platforms, a symbol is deemed to be found only if it has a nonzero
228   TOC pointer.  */
229extern
230Bool VG_(lookup_symbol_SLOW)(const HChar* sopatt, const HChar* name,
231                             SymAVMAs* avmas);
232
233#endif   // __PUB_CORE_DEBUGINFO_H
234
235/*--------------------------------------------------------------------*/
236/*--- end                                                          ---*/
237/*--------------------------------------------------------------------*/
238