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, 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. */
  41 typedef
  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. */
  54 typedef
  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 */
  94 typedef
  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. */
 133 extern 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. */
 139 extern 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. */
 143 extern 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. */
 151 extern 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). */
 155 extern 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. */
 159 extern SysRes VG_(am_munmap_valgrind)( Addr start, SizeT length );
 160
 161 #endif   // __PUB_TOOL_ASPACEMGR_H
 162
 163 /*--------------------------------------------------------------------*/
 164 /*--- end                                                          ---*/
 165 /*--------------------------------------------------------------------*/