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