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