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-2011 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/*====================================================================*/
35/*=== Obtaining debug information                                  ===*/
36/*====================================================================*/
37
38/* Get the file/function/line number of the instruction at address
39   'a'.  For these four, if debug info for the address is found, it
40   copies the info into the buffer/UInt and returns True.  If not, it
41   returns False and nothing is copied.  VG_(get_fnname) always
42   demangles C++ function names.  VG_(get_fnname_w_offset) is the
43   same, except it appends "+N" to symbol names to indicate offsets.  */
44extern Bool VG_(get_filename) ( Addr a, Char* filename, Int n_filename );
45extern Bool VG_(get_fnname)   ( Addr a, Char* fnname,   Int n_fnname   );
46extern Bool VG_(get_linenum)  ( Addr a, UInt* linenum );
47extern Bool VG_(get_fnname_w_offset)
48                              ( Addr a, Char* fnname,   Int n_fnname   );
49
50/* This one is the most general.  It gives filename, line number and
51   optionally directory name.  filename and linenum may not be NULL.
52   dirname may be NULL, meaning that the caller does not want
53   directory name info, in which case dirname_available must also be
54   NULL.  If dirname is non-null, directory info is written to it, if
55   it is available; if not available, '\0' is written to the first
56   byte.  In either case *dirname_available is set to indicate whether
57   or not directory information was available.
58
59   Returned value indicates whether any filename/line info could be
60   found. */
61extern Bool VG_(get_filename_linenum)
62                              ( Addr a,
63                                /*OUT*/Char* filename, Int n_filename,
64                                /*OUT*/Char* dirname,  Int n_dirname,
65                                /*OUT*/Bool* dirname_available,
66                                /*OUT*/UInt* linenum );
67
68/* Succeeds only if we find from debug info that 'a' is the address of the
69   first instruction in a function -- as opposed to VG_(get_fnname) which
70   succeeds if we find from debug info that 'a' is the address of any
71   instruction in a function.  Use this to instrument the start of
72   a particular function.  Nb: if an executable/shared object is stripped
73   of its symbols, this function will not be able to recognise function
74   entry points within it. */
75extern Bool VG_(get_fnname_if_entry) ( Addr a, Char* fnname, Int n_fnname );
76
77typedef
78   enum {
79      Vg_FnNameNormal,        // A normal function.
80      Vg_FnNameMain,          // "main"
81      Vg_FnNameBelowMain      // Something below "main", eg. __libc_start_main.
82   } Vg_FnNameKind;           //   Such names are often filtered.
83
84/* Indicates what kind of fnname it is. */
85extern Vg_FnNameKind VG_(get_fnname_kind) ( Char* name );
86
87/* Like VG_(get_fnname_kind), but takes a code address. */
88extern Vg_FnNameKind VG_(get_fnname_kind_from_IP) ( Addr ip );
89
90/* Looks up data_addr in the collection of data symbols, and if found
91   puts its name (or as much as will fit) into dname[0 .. n_dname-1],
92   which is guaranteed to be zero terminated.  Also data_addr's offset
93   from the symbol start is put into *offset. */
94extern Bool VG_(get_datasym_and_offset)( Addr data_addr,
95                                         /*OUT*/Char* dname, Int n_dname,
96                                         /*OUT*/PtrdiffT* offset );
97
98/* Try to form some description of DATA_ADDR by looking at the DWARF3
99   debug info we have.  This considers all global variables, and all
100   frames in the stacks of all threads.  Result is written at the ends
101   of DNAME{1,2}V, which are XArray*s of HChar, that have been
102   initialised by the caller, and True is returned.  If no description
103   is created, False is returned.  Regardless of the return value,
104   DNAME{1,2}V are guaranteed to be zero terminated after the call.
105
106   Note that after the call, DNAME{1,2} may have more than one
107   trailing zero, so callers should establish the useful text length
108   using VG_(strlen) on the contents, rather than VG_(sizeXA) on the
109   XArray itself.
110*/
111Bool VG_(get_data_description)(
112        /*MOD*/ void* /* really, XArray* of HChar */ dname1v,
113        /*MOD*/ void* /* really, XArray* of HChar */ dname2v,
114        Addr data_addr
115     );
116
117/* Succeeds if the address is within a shared object or the main executable.
118   It doesn't matter if debug info is present or not. */
119extern Bool VG_(get_objname)  ( Addr a, Char* objname, Int n_objname );
120
121/* Puts into 'buf' info about the code address %eip:  the address, function
122   name (if known) and filename/line number (if known), like this:
123
124      0x4001BF05: realloc (vg_replace_malloc.c:339)
125
126   'n_buf' gives length of 'buf'.  Returns 'buf'.
127*/
128extern Char* VG_(describe_IP)(Addr eip, Char* buf, Int n_buf);
129
130
131/* Get an XArray of StackBlock which describe the stack (auto) blocks
132   for this ip.  The caller is expected to free the XArray at some
133   point.  If 'arrays_only' is True, only array-typed blocks are
134   returned; otherwise blocks of all types are returned. */
135
136typedef
137   struct {
138      PtrdiffT base;       /* offset from sp or fp */
139      SizeT    szB;        /* size in bytes */
140      Bool     spRel;      /* True => sp-rel, False => fp-rel */
141      Bool     isVec;      /* does block have an array type, or not? */
142      HChar    name[16];   /* first 15 chars of name (asciiz) */
143   }
144   StackBlock;
145
146extern void* /* really, XArray* of StackBlock */
147             VG_(di_get_stack_blocks_at_ip)( Addr ip, Bool arrays_only );
148
149
150/* Get an array of GlobalBlock which describe the global blocks owned
151   by the shared object characterised by the given di_handle.  Asserts
152   if the handle is invalid.  The caller is responsible for freeing
153   the array at some point.  If 'arrays_only' is True, only
154   array-typed blocks are returned; otherwise blocks of all types are
155   returned. */
156
157typedef
158   struct {
159      Addr  addr;
160      SizeT szB;
161      Bool  isVec;      /* does block have an array type, or not? */
162      HChar name[16];   /* first 15 chars of name (asciiz) */
163      HChar soname[16]; /* first 15 chars of name (asciiz) */
164   }
165   GlobalBlock;
166
167extern void* /* really, XArray* of GlobalBlock */
168VG_(di_get_global_blocks_from_dihandle) ( ULong di_handle,
169                                          Bool  arrays_only );
170
171
172/*====================================================================*/
173/*=== Obtaining debug information                                  ===*/
174/*====================================================================*/
175
176/* A way to make limited debuginfo queries on a per-mapped-object
177   basis. */
178typedef  struct _DebugInfo  DebugInfo;
179
180/* Returns NULL if the DebugInfo isn't found.  It doesn't matter if
181   debug info is present or not. */
182DebugInfo* VG_(find_DebugInfo) ( Addr a );
183
184/* Fish bits out of DebugInfos. */
185Addr          VG_(DebugInfo_get_text_avma)   ( const DebugInfo *di );
186SizeT         VG_(DebugInfo_get_text_size)   ( const DebugInfo *di );
187Addr          VG_(DebugInfo_get_plt_avma)    ( const DebugInfo *di );
188SizeT         VG_(DebugInfo_get_plt_size)    ( const DebugInfo *di );
189Addr          VG_(DebugInfo_get_gotplt_avma) ( const DebugInfo *di );
190SizeT         VG_(DebugInfo_get_gotplt_size) ( const DebugInfo *di );
191const UChar*  VG_(DebugInfo_get_soname)      ( const DebugInfo *di );
192const UChar*  VG_(DebugInfo_get_filename)    ( const DebugInfo *di );
193PtrdiffT      VG_(DebugInfo_get_text_bias)   ( const DebugInfo *di );
194
195/* Function for traversing the DebugInfo list.  When called with NULL
196   it returns the first element; otherwise it returns the given
197   element's successor.  Note that the order of elements in the list
198   changes in response to most of the queries listed in this header,
199   that explicitly or implicitly have to search the list for a
200   particular code address.  So it isn't safe to assume that the order
201   of the list stays constant. */
202const DebugInfo* VG_(next_DebugInfo)    ( const DebugInfo *di );
203
204/* Functions for traversing all the symbols in a DebugInfo.  _howmany
205   tells how many symbol table entries there are.  _getidx retrieves
206   the n'th entry, for n in 0 .. _howmany-1.  You may not modify the
207   function names thereby acquired; if you want to do so, first strdup
208   them.  The primary name is returned in *pri_name, and *sec_names is
209   set either to NULL or to a NULL terminated vector containing
210   pointers to the secondary names. */
211Int  VG_(DebugInfo_syms_howmany) ( const DebugInfo *di );
212void VG_(DebugInfo_syms_getidx)  ( const DebugInfo *di,
213                                   Int idx,
214                                   /*OUT*/Addr*    avma,
215                                   /*OUT*/Addr*    tocptr,
216                                   /*OUT*/UInt*    size,
217                                   /*OUT*/UChar**  pri_name,
218                                   /*OUT*/UChar*** sec_names,
219                                   /*OUT*/Bool*    isText,
220                                   /*OUT*/Bool*    isIFunc );
221
222/* A simple enumeration to describe the 'kind' of various kinds of
223   segments that arise from the mapping of object files. */
224typedef
225   enum {
226      Vg_SectUnknown,
227      Vg_SectText,
228      Vg_SectData,
229      Vg_SectBSS,
230      Vg_SectGOT,
231      Vg_SectPLT,
232      Vg_SectGOTPLT,
233      Vg_SectOPD
234   }
235   VgSectKind;
236
237/* Convert a VgSectKind to a string, which must be copied if you want
238   to change it. */
239const HChar* VG_(pp_SectKind)( VgSectKind kind );
240
241/* Given an address 'a', make a guess of which section of which object
242   it comes from.  If name is non-NULL, then the last n_name-1
243   characters of the object's name is put in name[0 .. n_name-2], and
244   name[n_name-1] is set to zero (guaranteed zero terminated). */
245VgSectKind VG_(DebugInfo_sect_kind)( /*OUT*/UChar* name, SizeT n_name,
246                                     Addr a);
247
248
249#endif   // __PUB_TOOL_DEBUGINFO_H
250
251/*--------------------------------------------------------------------*/
252/*--- end                                                          ---*/
253/*--------------------------------------------------------------------*/
254