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 #endif
0116    }
0117    NSegment;
0118
0119
0120 /* Collect up the start addresses of segments whose kind matches one of
0121    the kinds specified in kind_mask.
0122    The interface is a bit strange in order to avoid potential
0123    segment-creation races caused by dynamic allocation of the result
0124    buffer *starts.
0125
0126    The function first computes how many entries in the result
0127    buffer *starts will be needed.  If this number <= nStarts,
0128    they are placed in starts[0..], and the number is returned.
0129    If nStarts is not large enough, nothing is written to
0130    starts[0..], and the negation of the size is returned.
0131
0132    Correct use of this function may mean calling it multiple times in
0133    order to establish a suitably-sized buffer. */
0134 extern Int VG_(am_get_segment_starts)( UInt kind_mask, Addr* starts,
0135                                        Int nStarts );
0136
0137 /* Finds the segment containing 'a'.  Only returns file/anon/resvn
0138    segments.  This returns a 'NSegment const *' - a pointer to
0139    readonly data. */
0140 extern NSegment const * VG_(am_find_nsegment) ( Addr a );
0141
0142 /* Get the filename corresponding to this segment, if known and if it
0143    has one. The function may return NULL if the file name is not known. */
0144 extern const HChar* VG_(am_get_filename)( NSegment const * );
0145
0146 /* Is the area [start .. start+len-1] validly accessible by the
0147    client with at least the permissions 'prot' ?  To find out
0148    simply if said area merely belongs to the client, pass
0149    VKI_PROT_NONE as 'prot'.  Will return False if any part of the
0150    area does not belong to the client or does not have at least
0151    the stated permissions. */
0152 extern Bool VG_(am_is_valid_for_client) ( Addr start, SizeT len,
0153                                           UInt prot );
0154
0155 /* Really just a wrapper around VG_(am_mmap_anon_float_valgrind). */
0156 extern void* VG_(am_shadow_alloc)(SizeT size);
0157
0158 /* Unmap the given address range and update the segment array
0159    accordingly.  This fails if the range isn't valid for valgrind. */
0160 extern SysRes VG_(am_munmap_valgrind)( Addr start, SizeT length );
0161
0162 #endif   // __PUB_TOOL_ASPACEMGR_H
0163
0164 /*--------------------------------------------------------------------*/
0165 /*--- end                                                          ---*/
0166 /*--------------------------------------------------------------------*/