1
2/*--------------------------------------------------------------------*/
3/*--- Address space manager.                  pub_tool_aspacemgr.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_ASPACEMGR_H
32#define __PUB_TOOL_ASPACEMGR_H
33
34#include "pub_tool_basics.h"   // VG_ macro
35
36//--------------------------------------------------------------
37// Definition of address-space segments
38
39/* Describes segment kinds. Enumerators are one-hot encoded so they
40   can be or'ed together. */
41typedef
42   enum {
43      SkFree  = 0x01,  // unmapped space
44      SkAnonC = 0x02,  // anonymous mapping belonging to the client
45      SkAnonV = 0x04,  // anonymous mapping belonging to valgrind
46      SkFileC = 0x08,  // file mapping belonging to the client
47      SkFileV = 0x10,  // file mapping belonging to valgrind
48      SkShmC  = 0x20,  // shared memory segment belonging to the client
49      SkResvn = 0x40   // reservation
50   }
51   SegKind;
52
53/* Describes how a reservation segment can be resized. */
54typedef
55   enum {
56      SmLower,  // lower end can move up
57      SmFixed,  // cannot be shrunk
58      SmUpper   // upper end can move down
59   }
60   ShrinkMode;
61
62/* Describes a segment.  Invariants:
63
64     kind == SkFree:
65        // the only meaningful fields are .start and .end
66
67     kind == SkAnon{C,V}:
68        // smode==SmFixed
69        // there's no associated file:
70        dev==ino==foff = 0, fnidx == -1
71        // segment may have permissions
72
73     kind == SkFile{C,V}:
74        // smode==SmFixed
75        // there is an associated file
76        // segment may have permissions
77
78     kind == SkShmC:
79        // smode==SmFixed
80        // there's no associated file:
81        dev==ino==foff = 0, fnidx == -1
82        // segment may have permissions
83
84     kind == SkResvn
85        // the segment may be resized if required
86        // there's no associated file:
87        dev==ino==foff = 0, fnidx == -1
88        // segment has no permissions
89        hasR==hasW==hasX == False
90
91     Also: hasT==True is only allowed in SkFileC, SkAnonC, and SkShmC
92           (viz, not allowed to make translations from non-client areas)
93*/
94typedef
95   struct {
96      SegKind kind;
97      /* Extent */
98      Addr    start;    // lowest address in range
99      Addr    end;      // highest address in range
100      /* Shrinkable? (SkResvn only) */
101      ShrinkMode smode;
102      /* Associated file (SkFile{C,V} only) */
103      ULong   dev;
104      ULong   ino;
105      Off64T  offset;
106      UInt    mode;
107      Int     fnIdx;    // file name table index, if name is known
108      /* Permissions (SkAnon{C,V}, SkFile{C,V} only) */
109      Bool    hasR;
110      Bool    hasW;
111      Bool    hasX;
112      Bool    hasT;     // True --> translations have (or MAY have)
113                        // been taken from this segment
114      Bool    isCH;     // True --> is client heap (SkAnonC ONLY)
115   }
116   NSegment;
117
118
119/* Collect up the start addresses of segments whose kind matches one of
120   the kinds specified in kind_mask.
121   The interface is a bit strange in order to avoid potential
122   segment-creation races caused by dynamic allocation of the result
123   buffer *starts.
124
125   The function first computes how many entries in the result
126   buffer *starts will be needed.  If this number <= nStarts,
127   they are placed in starts[0..], and the number is returned.
128   If nStarts is not large enough, nothing is written to
129   starts[0..], and the negation of the size is returned.
130
131   Correct use of this function may mean calling it multiple times in
132   order to establish a suitably-sized buffer. */
133extern Int VG_(am_get_segment_starts)( UInt kind_mask, Addr* starts,
134                                       Int nStarts );
135
136/* Finds the segment containing 'a'.  Only returns file/anon/resvn
137   segments.  This returns a 'NSegment const *' - a pointer to
138   readonly data. */
139extern NSegment const * VG_(am_find_nsegment) ( Addr a );
140
141/* Get the filename corresponding to this segment, if known and if it
142   has one. The function may return NULL if the file name is not known. */
143extern const HChar* VG_(am_get_filename)( NSegment const * );
144
145/* Is the area [start .. start+len-1] validly accessible by the
146   client with at least the permissions 'prot' ?  To find out
147   simply if said area merely belongs to the client, pass
148   VKI_PROT_NONE as 'prot'.  Will return False if any part of the
149   area does not belong to the client or does not have at least
150   the stated permissions. */
151extern Bool VG_(am_is_valid_for_client) ( Addr start, SizeT len,
152                                          UInt prot );
153
154/* Really just a wrapper around VG_(am_mmap_anon_float_valgrind). */
155extern void* VG_(am_shadow_alloc)(SizeT size);
156
157/* Unmap the given address range and update the segment array
158   accordingly.  This fails if the range isn't valid for valgrind. */
159extern SysRes VG_(am_munmap_valgrind)( Addr start, SizeT length );
160
161#endif   // __PUB_TOOL_ASPACEMGR_H
162
163/*--------------------------------------------------------------------*/
164/*--- end                                                          ---*/
165/*--------------------------------------------------------------------*/
166