Home | History | Annotate | Download | only in include
      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-2012 Julian Seward
     11       jseward (at) 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.  */
     44 extern Bool VG_(get_filename) ( Addr a, Char* filename, Int n_filename );
     45 extern Bool VG_(get_fnname)   ( Addr a, Char* fnname,   Int n_fnname   );
     46 extern Bool VG_(get_linenum)  ( Addr a, UInt* linenum );
     47 extern 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. */
     61 extern 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. */
     75 extern Bool VG_(get_fnname_if_entry) ( Addr a, Char* fnname, Int n_fnname );
     76 
     77 typedef
     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. */
     85 extern Vg_FnNameKind VG_(get_fnname_kind) ( Char* name );
     86 
     87 /* Like VG_(get_fnname_kind), but takes a code address. */
     88 extern 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. */
     94 extern 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 */
    111 Bool 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. */
    119 extern 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 */
    128 extern 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 
    136 typedef
    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 
    146 extern 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 
    157 typedef
    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 
    167 extern void* /* really, XArray* of GlobalBlock */
    168 VG_(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. */
    178 typedef  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. */
    182 DebugInfo* VG_(find_DebugInfo) ( Addr a );
    183 
    184 /* Fish bits out of DebugInfos. */
    185 Addr          VG_(DebugInfo_get_text_avma)   ( const DebugInfo *di );
    186 SizeT         VG_(DebugInfo_get_text_size)   ( const DebugInfo *di );
    187 Addr          VG_(DebugInfo_get_plt_avma)    ( const DebugInfo *di );
    188 SizeT         VG_(DebugInfo_get_plt_size)    ( const DebugInfo *di );
    189 Addr          VG_(DebugInfo_get_gotplt_avma) ( const DebugInfo *di );
    190 SizeT         VG_(DebugInfo_get_gotplt_size) ( const DebugInfo *di );
    191 const UChar*  VG_(DebugInfo_get_soname)      ( const DebugInfo *di );
    192 const UChar*  VG_(DebugInfo_get_filename)    ( const DebugInfo *di );
    193 PtrdiffT      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. */
    202 const 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. */
    211 Int  VG_(DebugInfo_syms_howmany) ( const DebugInfo *di );
    212 void 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. */
    224 typedef
    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. */
    239 const 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). */
    245 VgSectKind 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