include/valgrind/pub_tool_addrinfo.h

0001
0002 /*--------------------------------------------------------------------*/
0003 /*--- Obtaining information about an address.  pub_tool_addrinfo.h ---*/
0004 /*--------------------------------------------------------------------*/
0005
0006 /*
0007    This file is part of Valgrind, a dynamic binary instrumentation
0008    framework.
0009
0010    Copyright (C) 2000-2017 Julian Seward
0011       jseward@acm.org
0012
0013    This program is free software; you can redistribute it and/or
0014    modify it under the terms of the GNU General Public License as
0015    published by the Free Software Foundation; either version 2 of the
0016    License, or (at your option) any later version.
0017
0018    This program is distributed in the hope that it will be useful, but
0019    WITHOUT ANY WARRANTY; without even the implied warranty of
0020    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0021    General Public License for more details.
0022
0023    You should have received a copy of the GNU General Public License
0024    along with this program; if not, see <http://www.gnu.org/licenses/>.
0025
0026    The GNU General Public License is contained in the file COPYING.
0027 */
0028
0029 #ifndef __PUB_TOOL_ADDRINFO_H
0030 #define __PUB_TOOL_ADDRINFO_H
0031
0032 #include "pub_tool_basics.h"   // VG_ macro
0033 #include "pub_tool_aspacemgr.h"  // SegKind
0034
0035 /*====================================================================*/
0036 /*=== Obtaining information about an address                       ===*/
0037 /*====================================================================*/
0038
0039 // Different kinds of blocks.
0040 // Block_Mallocd is used by tools that maintain detailed information about
0041 //   Client allocated heap blocks.
0042 // Block_Freed is used by tools such as memcheck that maintain a 'quarantine'
0043 //   list of blocks freed by the Client but not yet physically freed.
0044 // Block_MempoolChunk and Block_UserG are used for mempool or user defined heap
0045 //   blocks.
0046 // Block_ClientArenaMallocd and Block_ClientArenaFree are used when the tool
0047 //   replaces the malloc/free/... functions but does not maintain detailed
0048 //   information about Client allocated heap blocks.
0049 // Block_ValgrindArenaMallocd and Block_ValgrindArenaFree are used for heap
0050 //   blocks of Valgrind internal heap.
0051 typedef enum {
0052    Block_Mallocd = 111,
0053    Block_Freed,
0054    Block_MempoolChunk,
0055    Block_UserG,
0056    Block_ClientArenaMallocd,
0057    Block_ClientArenaFree,
0058    Block_ValgrindArenaMallocd,
0059    Block_ValgrindArenaFree,
0060 } BlockKind;
0061
0062 /* ------------------ Addresses -------------------- */
0063
0064 /* The classification of a faulting address. */
0065 typedef
0066    enum {
0067       Addr_Undescribed, // as-yet unclassified
0068       Addr_Unknown,     // classification yielded nothing useful
0069       Addr_Block,       // in malloc'd/free'd block
0070       Addr_Stack,       // on a thread's stack
0071       Addr_DataSym,     // in a global data sym
0072       Addr_Variable,    // variable described by the debug info
0073       Addr_SectKind,    // Section from a mmap-ed object file
0074       Addr_BrkSegment,  // address in brk data segment
0075       Addr_SegmentKind  // Client segment (mapped memory)
0076    }
0077    AddrTag;
0078
0079 /* For an address in a stack, gives the address position in this stack. */
0080 typedef
0081    enum {
0082       StackPos_stacked,         // Addressable and 'active' stack zone.
0083       StackPos_below_stack_ptr, // Below stack ptr
0084       StackPos_guard_page       // In the guard page
0085    }
0086    StackPos;
0087
0088
0089 /* Note about ThreadInfo tid and tnr in various parts of _Addrinfo:
0090    A tid is an index in the VG_(threads)[] array. The entries
0091    in  VG_(threads) array are re-used, so the tid in an 'old' _Addrinfo
0092    might be misleading: if the thread that was using tid has been terminated
0093    and the tid was re-used by another thread, the tid will very probably
0094    be wrongly interpreted by the user.
0095    So, such an _Addrinfo should be printed just after it has been produced,
0096    before the tid could possibly be re-used by another thread.
0097
0098    A tool such as helgrind is uniquely/unambiguously identifying each thread
0099    by a number. If the tool sets tnr between the call to
0100    VG_(describe_addr) and the call to VG_(pp_addrinfo), then VG_(pp_addrinfo)
0101    will by preference print tnr instead of tid.
0102    Visually, a tid will be printed as   thread %d
0103    while a tnr will be printed as       thread #%d
0104 */
0105
0106 typedef
0107    struct _ThreadInfo {
0108       ThreadId tid;   // 0 means thread not known.
0109       UInt     tnr;   // 0 means no tool specific thread nr, or not known.
0110    } ThreadInfo;
0111
0112 /* Zeroes/clear all the fields of *tinfo. */
0113 extern void VG_(initThreadInfo) (ThreadInfo *tinfo);
0114
0115 typedef
0116    struct _AddrInfo
0117    AddrInfo;
0118
0119 struct _AddrInfo {
0120    AddrTag tag;
0121    union {
0122       // As-yet unclassified.
0123       struct { } Undescribed;
0124
0125       // On a stack. tinfo indicates which thread's stack?
0126       // IP is the address of an instruction of the function where the
0127       // stack address was. 0 if not found. IP can be symbolised using epoch.
0128       // frameNo is the frame nr of the call where the stack address was.
0129       // -1 if not found.
0130       // stackPos describes the address 'position' in the stack.
0131       // If stackPos is StackPos_below_stack_ptr or StackPos_guard_page,
0132       // spoffset gives the offset from the thread stack pointer.
0133       // (spoffset will be negative, as stacks are assumed growing down).
0134       struct {
0135          ThreadInfo tinfo;
0136          DiEpoch  epoch;
0137          Addr     IP;
0138          Int      frameNo;
0139          StackPos stackPos;
0140          PtrdiffT spoffset;
0141       } Stack;
0142
0143       // This covers heap blocks (normal and from mempools), user-defined
0144       // blocks and Arena blocks.
0145       // alloc_tinfo identifies the thread that has allocated the block.
0146       // This is used by tools such as helgrind that maintain
0147       // more detailed information about client blocks.
0148       struct {
0149          BlockKind   block_kind;
0150          const HChar* block_desc;   // "block","mempool","user-defined",arena
0151          SizeT       block_szB;
0152          PtrdiffT    rwoffset;
0153          ExeContext* allocated_at; // might contain null_ExeContext.
0154          ThreadInfo  alloc_tinfo;  // which thread alloc'd this block.
0155          ExeContext* freed_at;     // might contain null_ExeContext.
0156       } Block;
0157
0158       // In a global .data symbol.  This holds
0159       // the variable's name (zero terminated), plus a (memory) offset.
0160       struct {
0161          HChar   *name;
0162          PtrdiffT offset;
0163       } DataSym;
0164
0165       // Is described by Dwarf debug info.  XArray*s of HChar.
0166       struct {
0167          XArray* /* of HChar */ descr1;
0168          XArray* /* of HChar */ descr2;
0169       } Variable;
0170
0171       // Could only narrow it down to be the PLT/GOT/etc of a given
0172       // object.  Better than nothing, perhaps.
0173       struct {
0174          HChar      *objname;
0175          VgSectKind kind;
0176       } SectKind;
0177
0178       // Described address is or was in the brk data segment.
0179       // brk_limit is the limit that was in force
0180       // at the time address was described.
0181       // If address is >= brk_limit, it means address is in a zone
0182       // of the data segment that was shrinked.
0183       struct {
0184          Addr brk_limit; // limit in force when address was described.
0185       } BrkSegment;
0186
0187       struct {
0188          SegKind segkind;   // SkAnonC, SkFileC or SkShmC.
0189          HChar   *filename; // NULL if segkind != SkFileC
0190          Bool    hasR;
0191          Bool    hasW;
0192          Bool    hasX;
0193       } SegmentKind;
0194
0195       // Classification yielded nothing useful.
0196       struct { } Unknown;
0197
0198    } Addr;
0199 };
0200
0201
0202 /* Describe an address as best you can, putting the result in ai.
0203    On entry, ai->tag must be equal to Addr_Undescribed.
0204    This might allocate some memory, that can be cleared with
0205    VG_(clear_addrinfo). */
0206 extern void VG_(describe_addr) ( DiEpoch ep, Addr a, /*OUT*/AddrInfo* ai );
0207
0208 extern void VG_(clear_addrinfo) ( AddrInfo* ai);
0209
0210 /* Prints the AddrInfo ai describing a.
0211    Note that an ai with tag Addr_Undescribed will cause an assert.*/
0212 extern void VG_(pp_addrinfo) ( Addr a, const AddrInfo* ai );
0213
0214 /* Same as VG_(pp_addrinfo) but provides some memcheck specific behaviour:
0215    * maybe_gcc indicates Addr a was just below the stack ptr when the error
0216      with a was encountered.
0217    * the message for Unknown tag is slightly different, as memcheck
0218      has a recently freed list. */
0219 extern void VG_(pp_addrinfo_mc) ( Addr a, const AddrInfo* ai, Bool maybe_gcc );
0220
0221 #endif   // __PUB_TOOL_ADDRINFO_H
0222
0223 /*--------------------------------------------------------------------*/
0224 /*--- end                                                          ---*/
0225 /*--------------------------------------------------------------------*/