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-2013 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
36/*====================================================================*/
37/*=== Obtaining information about an address                       ===*/
38/*====================================================================*/
39
40// Different kinds of blocks.
41// Block_Mallocd is used by tools that maintain detailed information about
42//   Client allocated heap blocks.
43// Block_Freed is used by tools such as memcheck that maintain a 'quarantine'
44//   list of blocks freed by the Client but not yet physically freed.
45// Block_MempoolChunk and Block_UserG are used for mempool or user defined heap
46//   blocks.
47// Block_ClientArenaMallocd and Block_ClientArenaFree are used when the tool
48//   replaces the malloc/free/... functions but does not maintain detailed
49//   information about Client allocated heap blocks.
50// Block_ValgrindArenaMallocd and Block_ValgrindArenaFree are used for heap
51//   blocks of Valgrind internal heap.
52typedef enum {
53   Block_Mallocd = 111,
54   Block_Freed,
55   Block_MempoolChunk,
56   Block_UserG,
57   Block_ClientArenaMallocd,
58   Block_ClientArenaFree,
59   Block_ValgrindArenaMallocd,
60   Block_ValgrindArenaFree,
61} BlockKind;
62
63/* ------------------ Addresses -------------------- */
64
65/* The classification of a faulting address. */
66typedef
67   enum {
68      Addr_Undescribed, // as-yet unclassified
69      Addr_Unknown,     // classification yielded nothing useful
70      Addr_Block,       // in malloc'd/free'd block
71      Addr_Stack,       // on a thread's stack
72      Addr_DataSym,     // in a global data sym
73      Addr_Variable,    // variable described by the debug info
74      Addr_SectKind     // last-ditch classification attempt
75   }
76   AddrTag;
77
78typedef
79   struct _AddrInfo
80   AddrInfo;
81
82struct _AddrInfo {
83   AddrTag tag;
84   union {
85      // As-yet unclassified.
86      struct { } Undescribed;
87
88      // On a stack.
89      struct {
90         ThreadId tid;        // Which thread's stack?
91      } Stack;
92
93      // This covers heap blocks (normal and from mempools), user-defined
94      // blocks and Arena blocks.
95      struct {
96         BlockKind   block_kind;
97         const HChar* block_desc;   // "block","mempool","user-defined",arena
98         SizeT       block_szB;
99         PtrdiffT    rwoffset;
100         ExeContext* allocated_at;  // might be null_ExeContext.
101         ExeContext* freed_at;      // might be null_ExeContext.
102      } Block;
103
104      // In a global .data symbol.  This holds the first 127 chars of
105      // the variable's name (zero terminated), plus a (memory) offset.
106      struct {
107         HChar    name[128];
108         PtrdiffT offset;
109      } DataSym;
110
111      // Is described by Dwarf debug info.  XArray*s of HChar.
112      struct {
113         XArray* /* of HChar */ descr1;
114         XArray* /* of HChar */ descr2;
115      } Variable;
116
117      // Could only narrow it down to be the PLT/GOT/etc of a given
118      // object.  Better than nothing, perhaps.
119      struct {
120         HChar      objname[128];
121         VgSectKind kind;
122      } SectKind;
123
124      // Classification yielded nothing useful.
125      struct { } Unknown;
126
127   } Addr;
128};
129
130
131/* Describe an address as best you can, putting the result in ai.
132   On entry, ai->tag must be equal to Addr_Undescribed.
133   This might allocate some memory, that can be cleared with
134   VG_(clear_addrinfo). */
135extern void VG_(describe_addr) ( Addr a, /*OUT*/AddrInfo* ai );
136
137extern void VG_(clear_addrinfo) ( AddrInfo* ai);
138
139/* Prints the AddrInfo ai describing a. */
140extern void VG_(pp_addrinfo) ( Addr a, AddrInfo* ai );
141
142/* Same as VG_(pp_addrinfo) but provides some memcheck specific behaviour:
143   * maybe_gcc indicates Addr a was just below the stack ptr when the error
144     with a was encountered.
145   * the message for Unknown tag is slightly different, as memcheck
146     has a recently freed list. */
147extern void VG_(pp_addrinfo_mc) ( Addr a, AddrInfo* ai, Bool maybe_gcc );
148
149#endif   // __PUB_TOOL_ADDRINFO_H
150
151/*--------------------------------------------------------------------*/
152/*--- end                                                          ---*/
153/*--------------------------------------------------------------------*/
154