include/valgrind/pub_tool_aspacemgr.h

0001
0002 /*--------------------------------------------------------------------*/
0003 /*--- Address space manager.                  pub_tool_aspacemgr.h ---*/
0004 /*--------------------------------------------------------------------*/
0005
0006 /*
0007    This file is part of Valgrind, a dynamic binary instrumentation
0008    framework.
0009
0010    Copyright (C) 2000-2017 Julian Seward
0011       jseward@acm.org
0012
0013    This program is free software; you can redistribute it and/or
0014    modify it under the terms of the GNU General Public License as
0015    published by the Free Software Foundation; either version 2 of the
0016    License, or (at your option) any later version.
0017
0018    This program is distributed in the hope that it will be useful, but
0019    WITHOUT ANY WARRANTY; without even the implied warranty of
0020    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0021    General Public License for more details.
0022
0023    You should have received a copy of the GNU General Public License
0024    along with this program; if not, see <http://www.gnu.org/licenses/>.
0025
0026    The GNU General Public License is contained in the file COPYING.
0027 */
0028
0029 #ifndef __PUB_TOOL_ASPACEMGR_H
0030 #define __PUB_TOOL_ASPACEMGR_H
0031
0032 #include "pub_tool_basics.h"   // VG_ macro
0033
0034 //--------------------------------------------------------------
0035 // Definition of address-space segments
0036
0037 /* Describes segment kinds. Enumerators are one-hot encoded so they
0038    can be or'ed together. */
0039 typedef
0040    enum {
0041       SkFree  = 0x01,  // unmapped space
0042       SkAnonC = 0x02,  // anonymous mapping belonging to the client
0043       SkAnonV = 0x04,  // anonymous mapping belonging to valgrind
0044       SkFileC = 0x08,  // file mapping belonging to the client
0045       SkFileV = 0x10,  // file mapping belonging to valgrind
0046       SkShmC  = 0x20,  // shared memory segment belonging to the client
0047       SkResvn = 0x40   // reservation
0048    }
0049    SegKind;
0050
0051 /* Describes how a reservation segment can be resized. */
0052 typedef
0053    enum {
0054       SmLower,  // lower end can move up
0055       SmFixed,  // cannot be shrunk
0056       SmUpper   // upper end can move down
0057    }
0058    ShrinkMode;
0059
0060 /* Describes a segment.  Invariants:
0061
0062      kind == SkFree:
0063         // the only meaningful fields are .start and .end
0064
0065      kind == SkAnon{C,V}:
0066         // smode==SmFixed
0067         // there's no associated file:
0068         dev==ino==foff = 0, fnidx == -1
0069         // segment may have permissions
0070
0071      kind == SkFile{C,V}:
0072         // smode==SmFixed
0073         // there is an associated file
0074         // segment may have permissions
0075
0076      kind == SkShmC:
0077         // smode==SmFixed
0078         // there's no associated file:
0079         dev==ino==foff = 0, fnidx == -1
0080         // segment may have permissions
0081
0082      kind == SkResvn
0083         // the segment may be resized if required
0084         // there's no associated file:
0085         dev==ino==foff = 0, fnidx == -1
0086         // segment has no permissions
0087         hasR==hasW==hasX == False
0088
0089      Also: hasT==True is only allowed in SkFileC, SkAnonC, and SkShmC
0090            (viz, not allowed to make translations from non-client areas)
0091 */
0092 typedef
0093    struct {
0094       SegKind kind;
0095       /* Extent */
0096       Addr    start;    // lowest address in range
0097       Addr    end;      // highest address in range
0098       /* Shrinkable? (SkResvn only) */
0099       ShrinkMode smode;
0100       /* Associated file (SkFile{C,V} only) */
0101       ULong   dev;
0102       ULong   ino;
0103       Off64T  offset;
0104       UInt    mode;
0105       Int     fnIdx;    // file name table index, if name is known
0106       /* Permissions (SkAnon{C,V}, SkFile{C,V} only) */
0107       Bool    hasR;
0108       Bool    hasW;
0109       Bool    hasX;
0110       Bool    hasT;     // True --> translations have (or MAY have)
0111                         // been taken from this segment
0112       Bool    isCH;     // True --> is client heap (SkAnonC ONLY)
0113 #if defined(VGO_freebsd)
0114       Bool    isFF;     // True --> is a fixed file mapping
0115       Bool    ignore_offset; // True --> we can't work out segment offset
0116 #endif
0117    }
0118    NSegment;
0119
0120
0121 /* Collect up the start addresses of segments whose kind matches one of
0122    the kinds specified in kind_mask.
0123    The interface is a bit strange in order to avoid potential
0124    segment-creation races caused by dynamic allocation of the result
0125    buffer *starts.
0126
0127    The function first computes how many entries in the result
0128    buffer *starts will be needed.  If this number <= nStarts,
0129    they are placed in starts[0..], and the number is returned.
0130    If nStarts is not large enough, nothing is written to
0131    starts[0..], and the negation of the size is returned.
0132
0133    Correct use of this function may mean calling it multiple times in
0134    order to establish a suitably-sized buffer. */
0135 extern Int VG_(am_get_segment_starts)( UInt kind_mask, Addr* starts,
0136                                        Int nStarts );
0137
0138 /* Finds the segment containing 'a'.  Only returns file/anon/resvn
0139    segments.  This returns a 'NSegment const *' - a pointer to
0140    readonly data. */
0141 extern NSegment const * VG_(am_find_nsegment) ( Addr a );
0142
0143 /* Get the filename corresponding to this segment, if known and if it
0144    has one. The function may return NULL if the file name is not known. */
0145 extern const HChar* VG_(am_get_filename)( NSegment const * );
0146
0147 /* Is the area [start .. start+len-1] validly accessible by the
0148    client with at least the permissions 'prot' ?  To find out
0149    simply if said area merely belongs to the client, pass
0150    VKI_PROT_NONE as 'prot'.  Will return False if any part of the
0151    area does not belong to the client or does not have at least
0152    the stated permissions. */
0153 extern Bool VG_(am_is_valid_for_client) ( Addr start, SizeT len,
0154                                           UInt prot );
0155
0156 /* Really just a wrapper around VG_(am_mmap_anon_float_valgrind). */
0157 extern SysRes VG_(am_shadow_alloc)(SizeT size);
0158
0159 /* Unmap the given address range and update the segment array
0160    accordingly.  This fails if the range isn't valid for valgrind. */
0161 extern SysRes VG_(am_munmap_valgrind)( Addr start, SizeT length );
0162
0163 #endif   // __PUB_TOOL_ASPACEMGR_H
0164
0165 /*--------------------------------------------------------------------*/
0166 /*--- end                                                          ---*/
0167 /*--------------------------------------------------------------------*/