share/doc/psd/05.sysman/1.2.t

   1 .\" Copyright (c) 1983, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)1.2.t       8.1 (Berkeley) 6/8/93
  33 .\" $FreeBSD: src/share/doc/psd/05.sysman/1.2.t,v 1.5 1999/08/28 00:18:18 peter Exp $
  34 .\" $DragonFly: src/share/doc/psd/05.sysman/1.2.t,v 1.2 2003/06/17 04:36:56 dillon Exp $
  35 .\"
  36 .sh "Memory management\(dg
  37 .NH 3
  38 Text, data and stack
  39 .PP
  40 .FS
  41 \(dg This section represents the interface planned for later
  42 releases of the system.  Of the calls described in this section,
  43 only \fIsbrk\fP and \fIgetpagesize\fP are included in 4.3BSD.
  44 .FE
  45 Each process begins execution with three logical areas of memory
  46 called text, data and stack.
  47 The text area is read-only and shared, while the data and stack
  48 areas are private to the process.  Both the data and stack areas may
  49 be extended and contracted on program request.  The call
  50 .DS
  51 addr = sbrk(incr);
  52 result caddr_t addr; int incr;
  53 .DE
  54 changes the size of the data area by \fIincr\fP bytes and
  55 returns the new end of the data area, while
  56 .DS
  57 addr = sstk(incr);
  58 result caddr_t addr; int incr;
  59 .DE
  60 changes the size of the stack area.
  61 The stack area is also automatically extended as needed.
  62 On the VAX the text and data areas are adjacent in the P0 region,
  63 while the stack section is in the P1 region, and grows downward.
  64 .NH 3
  65 Mapping pages
  66 .PP
  67 The system supports sharing of data between processes
  68 by allowing pages to be mapped into memory.  These mapped
  69 pages may be \fIshared\fP with other processes or \fIprivate\fP
  70 to the process.
  71 Protection and sharing options are defined in \fI<sys/mman.h>\fP as:
  72 .DS
  73 .ta \w'#define\ \ 'u +\w'MAP_HASSEMAPHORE\ \ 'u +\w'0x0080\ \ 'u
  74 /* protections are chosen from these bits, or-ed together */
  75 #define PROT_READ       0x04    /* pages can be read */
  76 #define PROT_WRITE      0x02    /* pages can be written */
  77 #define PROT_EXEC       0x01    /* pages can be executed */
  78 .DE
  79 .DS
  80 .ta \w'#define\ \ 'u +\w'MAP_HASSEMAPHORE\ \ 'u +\w'0x0080\ \ 'u
  81 /* flags contain mapping type, sharing type and options */
  82 /* mapping type; choose one */
  83 #define MAP_FILE        0x0001  /* mapped from a file or device */
  84 #define MAP_ANON        0x0002  /* allocated from memory, swap space */
  85 #define MAP_TYPE        0x000f  /* mask for type field */
  86 .DE
  87 .DS
  88 .ta \w'#define\ \ 'u +\w'MAP_HASSEMAPHORE\ \ 'u +\w'0x0080\ \ 'u
  89 /* sharing types; choose one */
  90 #define MAP_SHARED      0x0010  /* share changes */
  91 #define MAP_PRIVATE     0x0000  /* changes are private */
  92 .DE
  93 .DS
  94 .ta \w'#define\ \ 'u +\w'MAP_HASSEMAPHORE\ \ 'u +\w'0x0080\ \ 'u
  95 /* other flags */
  96 #define MAP_FIXED       0x0020  /* map addr must be exactly as requested */
  97 #define MAP_INHERIT     0x0040  /* region is retained after exec */
  98 #define MAP_HASSEMAPHORE        0x0080  /* region may contain semaphores */
  99 #define MAP_NOPREALLOC  0x0100  /* do not preallocate space */
 100 .DE
 101 The cpu-dependent size of a page is returned by the
 102 \fIgetpagesize\fP system call:
 103 .DS
 104 pagesize = getpagesize();
 105 result int pagesize;
 106 .DE
 107 .LP
 108 The call:
 109 .DS
 110 maddr = mmap(addr, len, prot, flags, fd, pos);
 111 result caddr_t maddr; caddr_t addr; int *len, prot, flags, fd; off_t pos;
 112 .DE
 113 causes the pages starting at \fIaddr\fP and continuing
 114 for at most \fIlen\fP bytes to be mapped from the object represented by
 115 descriptor \fIfd\fP, starting at byte offset \fIpos\fP.
 116 The starting address of the region is returned;
 117 for the convenience of the system,
 118 it may differ from that supplied
 119 unless the MAP_FIXED flag is given,
 120 in which case the exact address will be used or the call will fail.
 121 The actual amount mapped is returned in \fIlen\fP.
 122 The \fIaddr\fP, \fIlen\fP, and \fIpos\fP parameters
 123 must all be multiples of the pagesize.
 124 A successful \fImmap\fP will delete any previous mapping
 125 in the allocated address range.
 126 The parameter \fIprot\fP specifies the accessibility
 127 of the mapped pages.
 128 The parameter \fIflags\fP specifies
 129 the type of object to be mapped,
 130 mapping options, and
 131 whether modifications made to
 132 this mapped copy of the page
 133 are to be kept \fIprivate\fP, or are to be \fIshared\fP with
 134 other references.
 135 Possible types include MAP_FILE,
 136 mapping a regular file or character-special device memory,
 137 and MAP_ANON, which maps memory not associated with any specific file.
 138 The file descriptor used for creating MAP_ANON regions is used only
 139 for naming, and may be given as \-1 if no name
 140 is associated with the region.\(dd
 141 .FS
 142 \(dd The current design does not allow a process
 143 to specify the location of swap space.
 144 In the future we may define an additional mapping type, MAP_SWAP,
 145 in which the file descriptor argument specifies a file
 146 or device to which swapping should be done.
 147 .FE
 148 The MAP_INHERIT flag allows a region to be inherited after an \fIexec\fP.
 149 The MAP_HASSEMAPHORE flag allows special handling for
 150 regions that may contain semaphores.
 151 The MAP_NOPREALLOC flag allows processes to allocate regions whose
 152 virtual address space, if fully allocated,
 153 would exceed the available memory plus swap resources.
 154 Such regions may get a SIGSEGV signal if they page fault and resources
 155 are not available to service their request;
 156 typically they would free up some resources via \fIunmap\fP so that
 157 when they return from the signal the page
 158 fault could be successfully completed.
 159 .PP
 160 A facility is provided to synchronize a mapped region with the file
 161 it maps; the call
 162 .DS
 163 msync(addr, len);
 164 caddr_t addr; int len;
 165 .DE
 166 writes any modified pages back to the filesystem and updates
 167 the file modification time.
 168 If \fIlen\fP is 0, all modified pages within the region containing \fIaddr\fP
 169 will be flushed;
 170 if \fIlen\fP is non-zero, only the pages containing \fIaddr\fP and \fIlen\fP
 171 succeeding locations will be examined.
 172 Any required synchronization of memory caches
 173 will also take place at this time.
 174 Filesystem operations on a file that is mapped for shared modifications
 175 are unpredictable except after an \fImsync\fP.
 176 .PP
 177 A mapping can be removed by the call
 178 .DS
 179 munmap(addr, len);
 180 caddr_t addr; int len;
 181 .DE
 182 This call deletes the mappings for the specified address range,
 183 and causes further references to addresses within the range
 184 to generate invalid memory references.
 185 .NH 3
 186 Page protection control
 187 .PP
 188 A process can control the protection of pages using the call
 189 .DS
 190 mprotect(addr, len, prot);
 191 caddr_t addr; int len, prot;
 192 .DE
 193 This call changes the specified pages to have protection \fIprot\fP\|.
 194 Not all implementations will guarantee protection on a page basis;
 195 the granularity of protection changes may be as large as an entire region.
 196 .NH 3
 197 Giving and getting advice
 198 .PP
 199 A process that has knowledge of its memory behavior may
 200 use the \fImadvise\fP call:
 201 .DS
 202 madvise(addr, len, behav);
 203 caddr_t addr; int len, behav;
 204 .DE
 205 \fIBehav\fP describes expected behavior, as given
 206 in \fI<sys/mman.h>\fP:
 207 .DS
 208 .ta \w'#define\ \ 'u +\w'MADV_SEQUENTIAL\ \ 'u +\w'00\ \ \ \ 'u
 209 #define MADV_NORMAL     0       /* no further special treatment */
 210 #define MADV_RANDOM     1       /* expect random page references */
 211 #define MADV_SEQUENTIAL 2       /* expect sequential references */
 212 #define MADV_WILLNEED   3       /* will need these pages */
 213 #define MADV_DONTNEED   4       /* don't need these pages */
 214 #define MADV_SPACEAVAIL 5       /* insure that resources are reserved */
 215 .DE
 216 Finally, a process may obtain information about whether pages are
 217 core resident by using the call
 218 .DS
 219 mincore(addr, len, vec)
 220 caddr_t addr; int len; result char *vec;
 221 .DE
 222 Here the current core residency of the pages is returned
 223 in the character array \fIvec\fP, with a value of 1 meaning
 224 that the page is in-core.
 225 .NH 3
 226 Synchronization primitives
 227 .PP
 228 Primitives are provided for synchronization using semaphores in shared memory.
 229 Semaphores must lie within a MAP_SHARED region with at least modes
 230 PROT_READ and PROT_WRITE.
 231 The MAP_HASSEMAPHORE flag must have been specified when the region was created.
 232 To acquire a lock a process calls:
 233 .DS
 234 value = mset(sem, wait)
 235 result int value; semaphore *sem; int wait;
 236 .DE
 237 \fIMset\fP indivisibly tests and sets the semaphore \fIsem\fP.
 238 If the previous value is zero, the process has acquired the lock
 239 and \fImset\fP returns true immediately.
 240 Otherwise, if the \fIwait\fP flag is zero,
 241 failure is returned.
 242 If \fIwait\fP is true and the previous value is non-zero,
 243 \fImset\fP relinquishes the processor until notified that it should retry.
 244 .LP
 245 To release a lock a process calls:
 246 .DS
 247 mclear(sem)
 248 semaphore *sem;
 249 .DE
 250 \fIMclear\fP indivisibly tests and clears the semaphore \fIsem\fP.
 251 If the ``WANT'' flag is zero in the previous value,
 252 \fImclear\fP returns immediately.
 253 If the ``WANT'' flag is non-zero in the previous value,
 254 \fImclear\fP arranges for waiting processes to retry before returning.
 255 .PP
 256 Two routines provide services analogous to the kernel
 257 \fIsleep\fP and \fIwakeup\fP functions interpreted in the domain of
 258 shared memory.
 259 A process may relinquish the processor by calling \fImsleep\fP
 260 with a set semaphore:
 261 .DS
 262 msleep(sem)
 263 semaphore *sem;
 264 .DE
 265 If the semaphore is still set when it is checked by the kernel,
 266 the process will be put in a sleeping state
 267 until some other process issues an \fImwakeup\fP for the same semaphore
 268 within the region using the call:
 269 .DS
 270 mwakeup(sem)
 271 semaphore *sem;
 272 .DE
 273 An \fImwakeup\fP may awaken all sleepers on the semaphore,
 274 or may awaken only the next sleeper on a queue.