share/doc/papers/newvm/a.t

   1 .\" Copyright (c) 1986 The Regents of the University of California.
   2 .\" 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 .\"     @(#)a.t 5.1 (Berkeley) 4/16/91
  33 .\" $FreeBSD: src/share/doc/papers/newvm/a.t,v 1.6 1999/08/28 00:18:14 peter Exp $
  34 .\"
  35 .sp 2
  36 .ne 2i
  37 .NH
  38 Appendix A \- Virtual Memory Interface
  39 .NH 2
  40 Mapping pages
  41 .PP
  42 The system supports sharing of data between processes
  43 by allowing pages to be mapped into memory.  These mapped
  44 pages may be \fIshared\fP with other processes or \fIprivate\fP
  45 to the process.
  46 Protection and sharing options are defined in \fI<sys/mman.h>\fP as:
  47 .DS
  48 .ta \w'#define\ \ 'u +\w'MAP_HASSEMAPHORE\ \ 'u +\w'0x0080\ \ 'u
  49 /* protections are chosen from these bits, or-ed together */
  50 #define PROT_READ       0x04    /* pages can be read */
  51 #define PROT_WRITE      0x02    /* pages can be written */
  52 #define PROT_EXEC       0x01    /* pages can be executed */
  53 .DE
  54 .DS
  55 .ta \w'#define\ \ 'u +\w'MAP_HASSEMAPHORE\ \ 'u +\w'0x0080\ \ 'u
  56 /* flags contain mapping type, sharing type and options */
  57 /* mapping type; choose one */
  58 #define MAP_FILE        0x0001  /* mapped from a file or device */
  59 #define MAP_ANON        0x0002  /* allocated from memory, swap space */
  60 #define MAP_TYPE        0x000f  /* mask for type field */
  61 .DE
  62 .DS
  63 .ta \w'#define\ \ 'u +\w'MAP_HASSEMAPHORE\ \ 'u +\w'0x0080\ \ 'u
  64 /* sharing types; choose one */
  65 #define MAP_SHARED      0x0010  /* share changes */
  66 #define MAP_PRIVATE     0x0000  /* changes are private */
  67 .DE
  68 .DS
  69 .ta \w'#define\ \ 'u +\w'MAP_HASSEMAPHORE\ \ 'u +\w'0x0080\ \ 'u
  70 /* other flags */
  71 #define MAP_FIXED       0x0020  /* map addr must be exactly as requested */
  72 #define MAP_INHERIT     0x0040  /* region is retained after exec */
  73 #define MAP_HASSEMAPHORE        0x0080  /* region may contain semaphores */
  74 .DE
  75 The cpu-dependent size of a page is returned by the
  76 \fIgetpagesize\fP system call:
  77 .DS
  78 pagesize = getpagesize();
  79 result int pagesize;
  80 .DE
  81 .LP
  82 The call:
  83 .DS
  84 maddr = mmap(addr, len, prot, flags, fd, pos);
  85 result caddr_t maddr; caddr_t addr; int *len, prot, flags, fd; off_t pos;
  86 .DE
  87 causes the pages starting at \fIaddr\fP and continuing
  88 for at most \fIlen\fP bytes to be mapped from the object represented by
  89 descriptor \fIfd\fP, starting at byte offset \fIpos\fP.
  90 The starting address of the region is returned;
  91 for the convenience of the system,
  92 it may differ from that supplied
  93 unless the MAP_FIXED flag is given,
  94 in which case the exact address will be used or the call will fail.
  95 The actual amount mapped is returned in \fIlen\fP.
  96 The \fIaddr\fP, \fIlen\fP, and \fIpos\fP parameters
  97 must all be multiples of the pagesize.
  98 A successful \fImmap\fP will delete any previous mapping
  99 in the allocated address range.
 100 The parameter \fIprot\fP specifies the accessibility
 101 of the mapped pages.
 102 The parameter \fIflags\fP specifies
 103 the type of object to be mapped,
 104 mapping options, and
 105 whether modifications made to
 106 this mapped copy of the page
 107 are to be kept \fIprivate\fP, or are to be \fIshared\fP with
 108 other references.
 109 Possible types include MAP_FILE,
 110 mapping a regular file or character-special device memory,
 111 and MAP_ANON, which maps memory not associated with any specific file.
 112 The file descriptor used for creating MAP_ANON regions is used only
 113 for naming, and may be given as \-1 if no name
 114 is associated with the region.\(dg
 115 .FS
 116 \(dg The current design does not allow a process
 117 to specify the location of swap space.
 118 In the future we may define an additional mapping type, MAP_SWAP,
 119 in which the file descriptor argument specifies a file
 120 or device to which swapping should be done.
 121 .FE
 122 The MAP_INHERIT flag allows a region to be inherited after an \fIexec\fP.
 123 The MAP_HASSEMAPHORE flag allows special handling for
 124 regions that may contain semaphores.
 125 .PP
 126 A facility is provided to synchronize a mapped region with the file
 127 it maps; the call
 128 .DS
 129 msync(addr, len);
 130 caddr_t addr; int len;
 131 .DE
 132 writes any modified pages back to the filesystem and updates
 133 the file modification time.
 134 If \fIlen\fP is 0, all modified pages within the region containing \fIaddr\fP
 135 will be flushed;
 136 if \fIlen\fP is non-zero, only the pages containing \fIaddr\fP and \fIlen\fP
 137 succeeding locations will be examined.
 138 Any required synchronization of memory caches
 139 will also take place at this time.
 140 Filesystem operations on a file that is mapped for shared modifications
 141 are unpredictable except after an \fImsync\fP.
 142 .PP
 143 A mapping can be removed by the call
 144 .DS
 145 munmap(addr, len);
 146 caddr_t addr; int len;
 147 .DE
 148 This call deletes the mappings for the specified address range,
 149 and causes further references to addresses within the range
 150 to generate invalid memory references.
 151 .NH 2
 152 Page protection control
 153 .PP
 154 A process can control the protection of pages using the call
 155 .DS
 156 mprotect(addr, len, prot);
 157 caddr_t addr; int len, prot;
 158 .DE
 159 This call changes the specified pages to have protection \fIprot\fP\|.
 160 Not all implementations will guarantee protection on a page basis;
 161 the granularity of protection changes may be as large as an entire region.
 162 .NH 2
 163 Giving and getting advice
 164 .PP
 165 A process that has knowledge of its memory behavior may
 166 use the \fImadvise\fP call:
 167 .DS
 168 madvise(addr, len, behav);
 169 caddr_t addr; int len, behav;
 170 .DE
 171 \fIBehav\fP describes expected behavior, as given
 172 in \fI<sys/mman.h>\fP:
 173 .DS
 174 .ta \w'#define\ \ 'u +\w'MADV_SEQUENTIAL\ \ 'u +\w'00\ \ \ \ 'u
 175 #define MADV_NORMAL     0       /* no further special treatment */
 176 #define MADV_RANDOM     1       /* expect random page references */
 177 #define MADV_SEQUENTIAL 2       /* expect sequential references */
 178 #define MADV_WILLNEED   3       /* will need these pages */
 179 #define MADV_DONTNEED   4       /* don't need these pages */
 180 #define MADV_SPACEAVAIL 5       /* insure that resources are reserved */
 181 .DE
 182 Finally, a process may obtain information about whether pages are
 183 core resident by using the call
 184 .DS
 185 mincore(addr, len, vec)
 186 caddr_t addr; int len; result char *vec;
 187 .DE
 188 Here the current core residency of the pages is returned
 189 in the character array \fIvec\fP, with a value of 1 meaning
 190 that the page is in-core.
 191 .NH 2
 192 Synchronization primitives
 193 .PP
 194 Primitives are provided for synchronization using semaphores in shared memory.
 195 Semaphores must lie within a MAP_SHARED region with at least modes
 196 PROT_READ and PROT_WRITE.
 197 The MAP_HASSEMAPHORE flag must have been specified when the region was created.
 198 To acquire a lock a process calls:
 199 .DS
 200 value = mset(sem, wait)
 201 result int value; semaphore *sem; int wait;
 202 .DE
 203 \fIMset\fP indivisibly tests and sets the semaphore \fIsem\fP.
 204 If the previous value is zero, the process has acquired the lock
 205 and \fImset\fP returns true immediately.
 206 Otherwise, if the \fIwait\fP flag is zero,
 207 failure is returned.
 208 If \fIwait\fP is true and the previous value is non-zero,
 209 \fImset\fP relinquishes the processor until notified that it should retry.
 210 .LP
 211 To release a lock a process calls:
 212 .DS
 213 mclear(sem)
 214 semaphore *sem;
 215 .DE
 216 \fIMclear\fP indivisibly tests and clears the semaphore \fIsem\fP.
 217 If the ``WANT'' flag is zero in the previous value,
 218 \fImclear\fP returns immediately.
 219 If the ``WANT'' flag is non-zero in the previous value,
 220 \fImclear\fP arranges for waiting processes to retry before returning.
 221 .PP
 222 Two routines provide services analogous to the kernel
 223 \fIsleep\fP and \fIwakeup\fP functions interpreted in the domain of
 224 shared memory.
 225 A process may relinquish the processor by calling \fImsleep\fP
 226 with a set semaphore:
 227 .DS
 228 msleep(sem)
 229 semaphore *sem;
 230 .DE
 231 If the semaphore is still set when it is checked by the kernel,
 232 the process will be put in a sleeping state
 233 until some other process issues an \fImwakeup\fP for the same semaphore
 234 within the region using the call:
 235 .DS
 236 mwakeup(sem)
 237 semaphore *sem;
 238 .DE
 239 An \fImwakeup\fP may awaken all sleepers on the semaphore,
 240 or may awaken only the next sleeper on a queue.