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    }
 114    NSegment;
 115
 116
 117 /* Collect up the start addresses of segments whose kind matches one of
 118    the kinds specified in kind_mask.
 119    The interface is a bit strange in order to avoid potential
 120    segment-creation races caused by dynamic allocation of the result
 121    buffer *starts.
 122
 123    The function first computes how many entries in the result
 124    buffer *starts will be needed.  If this number <= nStarts,
 125    they are placed in starts[0..], and the number is returned.
 126    If nStarts is not large enough, nothing is written to
 127    starts[0..], and the negation of the size is returned.
 128
 129    Correct use of this function may mean calling it multiple times in
 130    order to establish a suitably-sized buffer. */
 131 extern Int VG_(am_get_segment_starts)( UInt kind_mask, Addr* starts,
 132                                        Int nStarts );
 133
 134 /* Finds the segment containing 'a'.  Only returns file/anon/resvn
 135    segments.  This returns a 'NSegment const *' - a pointer to
 136    readonly data. */
 137 extern NSegment const * VG_(am_find_nsegment) ( Addr a );
 138
 139 /* Get the filename corresponding to this segment, if known and if it
 140    has one. The function may return NULL if the file name is not known. */
 141 extern const HChar* VG_(am_get_filename)( NSegment const * );
 142
 143 /* Is the area [start .. start+len-1] validly accessible by the
 144    client with at least the permissions 'prot' ?  To find out
 145    simply if said area merely belongs to the client, pass
 146    VKI_PROT_NONE as 'prot'.  Will return False if any part of the
 147    area does not belong to the client or does not have at least
 148    the stated permissions. */
 149 extern Bool VG_(am_is_valid_for_client) ( Addr start, SizeT len,
 150                                           UInt prot );
 151
 152 /* Really just a wrapper around VG_(am_mmap_anon_float_valgrind). */
 153 extern void* VG_(am_shadow_alloc)(SizeT size);
 154
 155 /* Unmap the given address range and update the segment array
 156    accordingly.  This fails if the range isn't valid for valgrind. */
 157 extern SysRes VG_(am_munmap_valgrind)( Addr start, SizeT length );
 158
 159 #endif   // __PUB_TOOL_ASPACEMGR_H
 160
 161 /*--------------------------------------------------------------------*/
 162 /*--- end                                                          ---*/
 163 /*--------------------------------------------------------------------*/