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