include/pub_tool_aspacemgr.h

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