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