include/pub_tool_addrinfo.h

   1
   2 /*--------------------------------------------------------------------*/
   3 /*--- Obtaining information about an address.  pub_tool_addrinfo.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_ADDRINFO_H
  32 #define __PUB_TOOL_ADDRINFO_H
  33
  34 #include "pub_tool_basics.h"   // VG_ macro
  35 #include "pub_tool_aspacemgr.h"  // SegKind
  36
  37 /*====================================================================*/
  38 /*=== Obtaining information about an address                       ===*/
  39 /*====================================================================*/
  40
  41 // Different kinds of blocks.
  42 // Block_Mallocd is used by tools that maintain detailed information about
  43 //   Client allocated heap blocks.
  44 // Block_Freed is used by tools such as memcheck that maintain a 'quarantine'
  45 //   list of blocks freed by the Client but not yet physically freed.
  46 // Block_MempoolChunk and Block_UserG are used for mempool or user defined heap
  47 //   blocks.
  48 // Block_ClientArenaMallocd and Block_ClientArenaFree are used when the tool
  49 //   replaces the malloc/free/... functions but does not maintain detailed
  50 //   information about Client allocated heap blocks.
  51 // Block_ValgrindArenaMallocd and Block_ValgrindArenaFree are used for heap
  52 //   blocks of Valgrind internal heap.
  53 typedef enum {
  54    Block_Mallocd = 111,
  55    Block_Freed,
  56    Block_MempoolChunk,
  57    Block_UserG,
  58    Block_ClientArenaMallocd,
  59    Block_ClientArenaFree,
  60    Block_ValgrindArenaMallocd,
  61    Block_ValgrindArenaFree,
  62 } BlockKind;
  63
  64 /* ------------------ Addresses -------------------- */
  65
  66 /* The classification of a faulting address. */
  67 typedef
  68    enum {
  69       Addr_Undescribed, // as-yet unclassified
  70       Addr_Unknown,     // classification yielded nothing useful
  71       Addr_Block,       // in malloc'd/free'd block
  72       Addr_Stack,       // on a thread's stack
  73       Addr_DataSym,     // in a global data sym
  74       Addr_Variable,    // variable described by the debug info
  75       Addr_SectKind,    // Section from a mmap-ed object file
  76       Addr_BrkSegment,  // address in brk data segment
  77       Addr_SegmentKind  // Client segment (mapped memory)
  78    }
  79    AddrTag;
  80
  81 /* For an address in a stack, gives the address position in this stack. */
  82 typedef
  83    enum {
  84       StackPos_stacked,         // Addressable and 'active' stack zone.
  85       StackPos_below_stack_ptr, // Below stack ptr
  86       StackPos_guard_page       // In the guard page
  87    }
  88    StackPos;
  89
  90
  91 /* Note about ThreadInfo tid and tnr in various parts of _Addrinfo:
  92    A tid is an index in the VG_(threads)[] array. The entries
  93    in  VG_(threads) array are re-used, so the tid in an 'old' _Addrinfo
  94    might be misleading: if the thread that was using tid has been terminated
  95    and the tid was re-used by another thread, the tid will very probably
  96    be wrongly interpreted by the user.
  97    So, such an _Addrinfo should be printed just after it has been produced,
  98    before the tid could possibly be re-used by another thread.
  99
 100    A tool such as helgrind is uniquely/unambiguously identifying each thread
 101    by a number. If the tool sets tnr between the call to
 102    VG_(describe_addr) and the call to VG_(pp_addrinfo), then VG_(pp_addrinfo)
 103    will by preference print tnr instead of tid.
 104    Visually, a tid will be printed as   thread %d
 105    while a tnr will be printed as       thread #%d
 106 */
 107
 108 typedef
 109    struct _ThreadInfo {
 110       ThreadId tid;   // 0 means thread not known.
 111       UInt     tnr;   // 0 means no tool specific thread nr, or not known.
 112    } ThreadInfo;
 113
 114 /* Zeroes/clear all the fields of *tinfo. */
 115 extern void VG_(initThreadInfo) (ThreadInfo *tinfo);
 116
 117 typedef
 118    struct _AddrInfo
 119    AddrInfo;
 120
 121 struct _AddrInfo {
 122    AddrTag tag;
 123    union {
 124       // As-yet unclassified.
 125       struct { } Undescribed;
 126
 127       // On a stack. tinfo indicates which thread's stack?
 128       // IP is the address of an instruction of the function where the
 129       // stack address was. 0 if not found. IP can be symbolised using epoch.
 130       // frameNo is the frame nr of the call where the stack address was.
 131       // -1 if not found.
 132       // stackPos describes the address 'position' in the stack.
 133       // If stackPos is StackPos_below_stack_ptr or StackPos_guard_page,
 134       // spoffset gives the offset from the thread stack pointer.
 135       // (spoffset will be negative, as stacks are assumed growing down).
 136       struct {
 137          ThreadInfo tinfo;
 138          DiEpoch  epoch;
 139          Addr     IP;
 140          Int      frameNo;
 141          StackPos stackPos;
 142          PtrdiffT spoffset;
 143       } Stack;
 144
 145       // This covers heap blocks (normal and from mempools), user-defined
 146       // blocks and Arena blocks.
 147       // alloc_tinfo identifies the thread that has allocated the block.
 148       // This is used by tools such as helgrind that maintain
 149       // more detailed information about client blocks.
 150       struct {
 151          BlockKind   block_kind;
 152          const HChar* block_desc;   // "block","mempool","user-defined",arena
 153          SizeT       block_szB;
 154          PtrdiffT    rwoffset;
 155          ExeContext* allocated_at; // might contain null_ExeContext.
 156          ThreadInfo  alloc_tinfo;  // which thread alloc'd this block.
 157          ExeContext* freed_at;     // might contain null_ExeContext.
 158       } Block;
 159
 160       // In a global .data symbol.  This holds
 161       // the variable's name (zero terminated), plus a (memory) offset.
 162       struct {
 163          HChar   *name;
 164          PtrdiffT offset;
 165       } DataSym;
 166
 167       // Is described by Dwarf debug info.  XArray*s of HChar.
 168       struct {
 169          XArray* /* of HChar */ descr1;
 170          XArray* /* of HChar */ descr2;
 171       } Variable;
 172
 173       // Could only narrow it down to be the PLT/GOT/etc of a given
 174       // object.  Better than nothing, perhaps.
 175       struct {
 176          HChar      *objname;
 177          VgSectKind kind;
 178       } SectKind;
 179
 180       // Described address is or was in the brk data segment.
 181       // brk_limit is the limit that was in force
 182       // at the time address was described.
 183       // If address is >= brk_limit, it means address is in a zone
 184       // of the data segment that was shrinked.
 185       struct {
 186          Addr brk_limit; // limit in force when address was described.
 187       } BrkSegment;
 188
 189       struct {
 190          SegKind segkind;   // SkAnonC, SkFileC or SkShmC.
 191          HChar   *filename; // NULL if segkind != SkFileC
 192          Bool    hasR;
 193          Bool    hasW;
 194          Bool    hasX;
 195       } SegmentKind;
 196
 197       // Classification yielded nothing useful.
 198       struct { } Unknown;
 199
 200    } Addr;
 201 };
 202
 203
 204 /* Describe an address as best you can, putting the result in ai.
 205    On entry, ai->tag must be equal to Addr_Undescribed.
 206    This might allocate some memory, that can be cleared with
 207    VG_(clear_addrinfo). */
 208 extern void VG_(describe_addr) ( DiEpoch ep, Addr a, /*OUT*/AddrInfo* ai );
 209
 210 extern void VG_(clear_addrinfo) ( AddrInfo* ai);
 211
 212 /* Prints the AddrInfo ai describing a.
 213    Note that an ai with tag Addr_Undescribed will cause an assert.*/
 214 extern void VG_(pp_addrinfo) ( Addr a, const AddrInfo* ai );
 215
 216 /* Same as VG_(pp_addrinfo) but provides some memcheck specific behaviour:
 217    * maybe_gcc indicates Addr a was just below the stack ptr when the error
 218      with a was encountered.
 219    * the message for Unknown tag is slightly different, as memcheck
 220      has a recently freed list. */
 221 extern void VG_(pp_addrinfo_mc) ( Addr a, const AddrInfo* ai, Bool maybe_gcc );
 222
 223 #endif   // __PUB_TOOL_ADDRINFO_H
 224
 225 /*--------------------------------------------------------------------*/
 226 /*--- end                                                          ---*/
 227 /*--------------------------------------------------------------------*/