include/pub_tool_debuginfo.h

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