coregrind/pub_core_aspacemgr.h

   1
   2 /*--------------------------------------------------------------------*/
   3 /*--- The address space manager.              pub_core_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_CORE_ASPACEMGR_H
  30 #define __PUB_CORE_ASPACEMGR_H
  31
  32 //--------------------------------------------------------------------
  33 // PURPOSE: This module deals with management of the entire process
  34 // address space.  Almost everything depends upon it, including dynamic
  35 // memory management.  Hence this module is almost completely
  36 // standalone; the only module it uses is m_debuglog.  DO NOT CHANGE
  37 // THIS.
  38 //--------------------------------------------------------------------
  39
  40 #include "pub_tool_aspacemgr.h"
  41
  42 //--------------------------------------------------------------
  43 // Definition of address-space segments
  44
  45 /* types SegKind, ShrinkMode and NSegment are described in
  46    the tool-visible header file, not here. */
  47
  48
  49 //--------------------------------------------------------------
  50 // Initialisation
  51
  52 /* Initialise the address space manager, setting up the initial
  53    segment list, and reading /proc/self/maps into it.  This must
  54    be called before any other function.
  55
  56    Takes a pointer to the SP at the time V gained control.  This is
  57    taken to be the highest usable address (more or less).  Based on
  58    that (and general consultation of tea leaves, etc) return a
  59    suggested end address (highest addressable byte) for the client's stack. */
  60 extern Addr VG_(am_startup) ( Addr sp_at_startup );
  61
  62 /* Check whether ADDR is OK to be used as aspacem_minAddr. If not, *ERRMSG
  63    will be set to identify what's wrong. ERRMSG may be NULL. */
  64 extern Bool VG_(am_is_valid_for_aspacem_minAddr)( Addr addr,
  65                                                   const HChar **errmsg );
  66
  67 //--------------------------------------------------------------
  68 // Querying current status
  69
  70
  71 /* Finds an anonymous segment containing 'a'. Returned pointer is read only. */
  72 extern NSegment const *VG_(am_find_anon_segment) ( Addr a );
  73
  74 /* Find the next segment along from 'here', if it is a file/anon/resvn
  75    segment. */
  76 extern NSegment const* VG_(am_next_nsegment) ( const NSegment* here,
  77                                                Bool fwds );
  78
  79 /* Is the area [start .. start+len-1] validly accessible by
  80    valgrind with at least the permissions 'prot' ?  To find out
  81    simply if said area merely belongs to valgrind, pass
  82    VKI_PROT_NONE as 'prot'.  Will return False if any part of the
  83    area does not belong to valgrind or does not have at least
  84    the stated permissions. */
  85 extern Bool VG_(am_is_valid_for_valgrind)
  86    ( Addr start, SizeT len, UInt prot );
  87
  88 /* Variant of VG_(am_is_valid_for_client) which allows free areas to
  89    be consider part of the client's addressable space.  It also
  90    considers reservations to be allowable, since from the client's
  91    point of view they don't exist. */
  92 extern Bool VG_(am_is_valid_for_client_or_free_or_resvn)
  93    ( Addr start, SizeT len, UInt prot );
  94
  95 /* Checks if a piece of memory consists of either free or reservation
  96    segments. */
  97 extern Bool VG_(am_is_free_or_resvn)( Addr start, SizeT len );
  98
  99 /* Check whether ADDR looks like an address or address-to-be located in an
 100    extensible client stack segment. */
 101 extern Bool VG_(am_addr_is_in_extensible_client_stack)( Addr addr );
 102
 103 /* Trivial fn: return the total amount of space in anonymous mappings,
 104    both for V and the client.  Is used for printing stats in
 105    out-of-memory messages. */
 106 extern ULong VG_(am_get_anonsize_total)( void );
 107
 108 /* Show the segment array on the debug log, at given loglevel. */
 109 extern void VG_(am_show_nsegments) ( Int logLevel, const HChar* who );
 110
 111 /* VG_(am_get_segment_starts) is also part of this section, but its
 112    prototype is tool-visible, hence not in this header file. */
 113
 114 /* Sanity check: check that Valgrind and the kernel agree on the
 115    address space layout.  Prints offending segments and call point if
 116    a discrepancy is detected, but does not abort the system.  Returned
 117    Bool is False if a discrepancy was found. */
 118
 119 extern Bool VG_(am_do_sync_check) ( const HChar* fn,
 120                                     const HChar* file, Int line );
 121
 122 //--------------------------------------------------------------
 123 // Functions pertaining to the central query-notify mechanism
 124 // used to handle mmap/munmap/mprotect resulting from client
 125 // syscalls.
 126
 127 /* Describes a request for VG_(am_get_advisory). */
 128 typedef
 129    struct {
 130       /* Note: if rkind == MAlign then start specifies alignment. This is
 131          Solaris specific. */
 132       enum { MFixed, MHint, MAny, MAlign } rkind;
 133       Addr start;
 134       Addr len;
 135    }
 136    MapRequest;
 137
 138 /* Query aspacem to ask where a mapping should go.  On success, the
 139    advised placement is returned, and *ok is set to True.  On failure,
 140    zero is returned and *ok is set to False.  Note that *ok must be
 141    consulted by the caller to establish success or failure; that
 142    cannot be established reliably from the returned value.  If *ok is
 143    set to False, it means aspacem has vetoed the mapping, and so the
 144    caller should not proceed with it. */
 145 extern Addr VG_(am_get_advisory)
 146    ( const MapRequest* req, Bool forClient, /*OUT*/Bool* ok );
 147
 148 /* Convenience wrapper for VG_(am_get_advisory) for client floating or
 149    fixed requests.  If start is zero, a floating request is issued; if
 150    nonzero, a fixed request at that address is issued.  Same comments
 151    about return values apply. */
 152 extern Addr VG_(am_get_advisory_client_simple)
 153    ( Addr start, SizeT len, /*OUT*/Bool* ok );
 154
 155 /* Returns True if [start, start + len - 1] is covered by a single
 156    free segment, otherwise returns False.
 157    This allows to check the following case:
 158    VG_(am_get_advisory_client_simple) (first arg == 0, meaning
 159    this-or-nothing) is too lenient, and may allow us to trash
 160    the next segment along.  So make very sure that the proposed
 161    new area really is free.  This is perhaps overly
 162    conservative, but it fixes #129866. */
 163 extern Bool VG_(am_covered_by_single_free_segment)
 164    ( Addr start, SizeT len);
 165
 166 /* Notifies aspacem that the client completed an mmap successfully.
 167    The segment array is updated accordingly.  If the returned Bool is
 168    True, the caller should immediately discard translations from the
 169    specified address range. */
 170 extern Bool VG_(am_notify_client_mmap)
 171    ( Addr a, SizeT len, UInt prot, UInt flags, Int fd, Off64T offset );
 172
 173 /* Notifies aspacem that the client completed a shmat successfully.
 174    The segment array is updated accordingly.  If the returned Bool is
 175    True, the caller should immediately discard translations from the
 176    specified address range. */
 177 extern Bool VG_(am_notify_client_shmat)( Addr a, SizeT len, UInt prot );
 178
 179 /* Notifies aspacem that an mprotect was completed successfully.  The
 180    segment array is updated accordingly.  Note, as with
 181    VG_(am_notify_munmap), it is not the job of this function to reject
 182    stupid mprotects, for example the client doing mprotect of
 183    non-client areas.  Such requests should be intercepted earlier, by
 184    the syscall wrapper for mprotect.  This function merely records
 185    whatever it is told.  If the returned Bool is True, the caller
 186    should immediately discard translations from the specified address
 187    range. */
 188 extern Bool VG_(am_notify_mprotect)( Addr start, SizeT len, UInt prot );
 189
 190 /* Notifies aspacem that an munmap completed successfully.  The
 191    segment array is updated accordingly.  As with
 192    VG_(am_notify_mprotect), we merely record the given info, and don't
 193    check it for sensibleness.  If the returned Bool is True, the
 194    caller should immediately discard translations from the specified
 195    address range. */
 196 extern Bool VG_(am_notify_munmap)( Addr start, SizeT len );
 197
 198 /* Hand a raw mmap to the kernel, without aspacem updating the segment
 199    array.  THIS FUNCTION IS DANGEROUS -- it will cause aspacem's view
 200    of the address space to diverge from that of the kernel.  DO NOT
 201    USE IT UNLESS YOU UNDERSTAND the request-notify model used by
 202    aspacem.  In short, DO NOT USE THIS FUNCTION. */
 203 extern SysRes VG_(am_do_mmap_NO_NOTIFY)
 204    ( Addr start, SizeT length, UInt prot, UInt flags, Int fd, Off64T offset);
 205
 206
 207 //--------------------------------------------------------------
 208 // Dealing with mappings which do not arise directly from the
 209 // simulation of the client.  These are typically used for
 210 // loading the client and building its stack/data segment, before
 211 // execution begins.  Also for V's own administrative use.
 212
 213 /* --- --- --- map, unmap, protect  --- --- --- */
 214
 215 /* Map a file at a fixed address for the client, and update the
 216    segment array accordingly. */
 217 extern SysRes VG_(am_mmap_file_fixed_client)
 218    ( Addr start, SizeT length, UInt prot, Int fd, Off64T offset );
 219 extern SysRes VG_(am_mmap_file_fixed_client_flags)
 220    ( Addr start, SizeT length, UInt prot, UInt flags, Int fd, Off64T offset );
 221 extern SysRes VG_(am_mmap_named_file_fixed_client)
 222    ( Addr start, SizeT length, UInt prot, Int fd,
 223      Off64T offset, const HChar *name );
 224 extern SysRes VG_(am_mmap_named_file_fixed_client_flags)
 225    ( Addr start, SizeT length, UInt prot, UInt flags, Int fd,
 226      Off64T offset, const HChar *name );
 227
 228 /* Map anonymously at a fixed address for the client, and update
 229    the segment array accordingly. */
 230 extern SysRes VG_(am_mmap_anon_fixed_client)
 231    ( Addr start, SizeT length, UInt prot );
 232
 233
 234 /* Map anonymously at an unconstrained address for the client, and
 235    update the segment array accordingly.  */
 236 extern SysRes VG_(am_mmap_anon_float_client) ( SizeT length, Int prot );
 237
 238 /* Map anonymously at an unconstrained address for V, and update the
 239    segment array accordingly.  This is fundamentally how V allocates
 240    itself more address space when needed. */
 241 extern SysRes VG_(am_mmap_anon_float_valgrind)( SizeT cszB );
 242
 243 /* Map privately a file at an unconstrained address for V, and update the
 244    segment array accordingly.  This is used by V for transiently
 245    mapping in object files to read their debug info.  */
 246 extern SysRes VG_(am_mmap_file_float_valgrind)
 247    ( SizeT length, UInt prot, Int fd, Off64T offset );
 248
 249 /* Map shared a file at an unconstrained address for V, and update the
 250    segment array accordingly.  This is used by V for communicating
 251    with vgdb.  */
 252 extern SysRes VG_(am_shared_mmap_file_float_valgrind)
 253    ( SizeT length, UInt prot, Int fd, Off64T offset );
 254
 255 /* Similar to VG_(am_mmap_anon_float_client) but also
 256    marks the segment as containing the client heap. */
 257 extern SysRes VG_(am_mmap_client_heap) ( SizeT length, Int prot );
 258
 259 /* Unmap the given address range and update the segment array
 260    accordingly.  This fails if the range isn't valid for the client.
 261    If *need_discard is True after a successful return, the caller
 262    should immediately discard translations from the specified address
 263    range. */
 264 extern SysRes VG_(am_munmap_client)( /*OUT*/Bool* need_discard,
 265                                      Addr start, SizeT length );
 266
 267 /* Let (start,len) denote an area within a single Valgrind-owned
 268   segment (anon or file).  Change the ownership of [start, start+len)
 269   to the client instead.  Fails if (start,len) does not denote a
 270   suitable segment. */
 271 extern Bool VG_(am_change_ownership_v_to_c)( Addr start, SizeT len );
 272
 273 /* Set the 'hasT' bit on the segment containing ADDR indicating that
 274    translations have or may have been taken from this segment. ADDR is
 275    expected to belong to a client segment. */
 276 extern void VG_(am_set_segment_hasT)( Addr addr );
 277
 278 /* --- --- --- reservations --- --- --- */
 279
 280 /* Create a reservation from START .. START+LENGTH-1, with the given
 281    ShrinkMode.  When checking whether the reservation can be created,
 282    also ensure that at least abs(EXTRA) extra free bytes will remain
 283    above (> 0) or below (< 0) the reservation.
 284
 285    The reservation will only be created if it, plus the extra-zone,
 286    falls entirely within a single free segment.  The returned Bool
 287    indicates whether the creation succeeded. */
 288 extern Bool VG_(am_create_reservation)
 289    ( Addr start, SizeT length, ShrinkMode smode, SSizeT extra );
 290
 291 /* ADDR is the start address of an anonymous client mapping.  This fn extends
 292    the mapping by DELTA bytes, taking the space from a reservation section
 293    which must be adjacent.  If DELTA is positive, the segment is
 294    extended forwards in the address space, and the reservation must be
 295    the next one along.  If DELTA is negative, the segment is extended
 296    backwards in the address space and the reservation must be the
 297    previous one.  DELTA must be page aligned.  abs(DELTA) must not
 298    exceed the size of the reservation segment minus one page, that is,
 299    the reservation segment after the operation must be at least one
 300    page long. The function returns a pointer to the resized segment. */
 301 extern const NSegment *VG_(am_extend_into_adjacent_reservation_client)
 302    ( Addr addr, SSizeT delta, /*OUT*/Bool *overflow );
 303
 304 /* --- --- --- resizing/move a mapping --- --- --- */
 305
 306 /* This function grows a client mapping in place into an adjacent free segment.
 307    ADDR is the client mapping's start address and DELTA, which must be page
 308    aligned, is the growth amount. The function returns a pointer to the
 309    resized segment. The function is used in support of mremap. */
 310 extern const NSegment *VG_(am_extend_map_client)( Addr addr, SizeT delta );
 311
 312 /* Remap the old address range to the new address range.  Fails if any
 313    parameter is not page aligned, if the either size is zero, if any
 314    wraparound is implied, if the old address range does not fall
 315    entirely within a single segment, if the new address range overlaps
 316    with the old one, or if the old address range is not a valid client
 317    mapping.  If *need_discard is True after a successful return, the
 318    caller should immediately discard translations from both specified
 319    address ranges.  */
 320 extern Bool VG_(am_relocate_nooverlap_client)( /*OUT*/Bool* need_discard,
 321                                                Addr old_addr, SizeT old_len,
 322                                                Addr new_addr, SizeT new_len );
 323
 324 //--------------------------------------------------------------
 325 // Valgrind (non-client) thread stacks.  V itself runs on such
 326 // stacks.  The address space manager provides and suitably
 327 // protects such stacks.
 328
 329 // VG_DEFAULT_STACK_ACTIVE_SZB is the default size of a Valgrind stack.
 330 // The effectively used size is controlled by the command line options
 331 // --valgrind-stack-size=xxxx (which must be page aligned).
 332 // Note that m_main.c needs an interim stack (just to startup), before
 333 // any command line option can be processed. This interim stack
 334 // (declared in m_main.c) will use the size VG_DEFAULT_STACK_ACTIVE_SZB.
 335 #if defined(VGP_ppc32_linux) \
 336     || defined(VGP_ppc64be_linux) || defined(VGP_ppc64le_linux) \
 337     || defined(VGP_mips32_linux) || defined(VGP_mips64_linux) \
 338     || defined(VGP_arm64_linux) || defined(VGP_nanomips_linux)
 339 # define VG_STACK_GUARD_SZB  65536  // 1 or 16 pages
 340 #else
 341 # define VG_STACK_GUARD_SZB  8192   // 2 pages
 342 #endif
 343 # define VG_DEFAULT_STACK_ACTIVE_SZB 1048576 // (4096 * 256) = 1Mb
 344
 345 typedef struct _VgStack VgStack;
 346
 347
 348 /* Allocate and initialise a VgStack (anonymous valgrind space).
 349    Protect the stack active area and the guard areas appropriately.
 350    Returns NULL on failure, else the address of the bottom of the
 351    stack.  On success, also sets *initial_sp to what the stack pointer
 352    should be set to. */
 353
 354 extern VgStack* VG_(am_alloc_VgStack)( /*OUT*/Addr* initial_sp );
 355
 356 /* Figure out how many bytes of the stack's active area have not been
 357    used.  Used for estimating if we are close to overflowing it.  If
 358    the free area is larger than 'limit', just return 'limit'. */
 359 extern SizeT VG_(am_get_VgStack_unused_szB)( const VgStack* stack,
 360                                              SizeT limit );
 361
 362 /* Returns the Addr of the lowest usable byte of stack. */
 363 extern Addr VG_(am_valgrind_stack_low_addr)( const VgStack* stack);
 364
 365 // DDD: this is ugly
 366 #if defined(VGO_darwin)
 367 typedef
 368    struct {
 369       Bool   is_added;  // Added or removed seg?
 370       Addr   start;
 371       SizeT  end;
 372       UInt   prot;      // Not used for removed segs.
 373       Off64T offset;    // Not used for removed segs.
 374    }
 375    ChangedSeg;
 376
 377 extern Bool VG_(get_changed_segments)(
 378       const HChar* when, const HChar* where, /*OUT*/ChangedSeg* css,
 379       Int css_size, /*OUT*/Int* css_used);
 380 #endif
 381
 382 #if defined(VGO_solaris)
 383 extern Bool VG_(am_search_for_new_segment)(Addr *start, SizeT *size,
 384                                            UInt *prot);
 385 #endif
 386
 387 #if defined(VGO_freebsd)
 388 /* For kern.usrstack syscall on FreeBSD */
 389 extern Word VG_(get_usrstack)(void);
 390 #endif
 391
 392 #endif   // __PUB_CORE_ASPACEMGR_H
 393
 394 /*--------------------------------------------------------------------*/
 395 /*--- end                                                          ---*/
 396 /*--------------------------------------------------------------------*/