1 .\" Copyright (c) 1986 The Regents of the University of California.
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
32 .\" @(#)a.t 5.1 (Berkeley) 4/16/91
38 Appendix A \- Virtual Memory Interface
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
46 Protection and sharing options are defined in \fI<sys/mman.h>\fP as:
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 */
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 */
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 */
69 .ta \w'#define\ \ 'u +\w'MAP_HASSEMAPHORE\ \ 'u +\w'0x0080\ \ 'u
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 */
75 The cpu-dependent size of a page is returned by the
76 \fIgetpagesize\fP system call:
78 pagesize = getpagesize();
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;
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
102 The parameter \fIflags\fP specifies
103 the type of object to be mapped,
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
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
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.
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.
126 A facility is provided to synchronize a mapped region with the file
130 caddr_t addr; int len;
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
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.
143 A mapping can be removed by the call
146 caddr_t addr; int len;
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.
152 Page protection control
154 A process can control the protection of pages using the call
156 mprotect(addr, len, prot);
157 caddr_t addr; int len, prot;
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.
163 Giving and getting advice
165 A process that has knowledge of its memory behavior may
166 use the \fImadvise\fP call:
168 madvise(addr, len, behav);
169 caddr_t addr; int len, behav;
171 \fIBehav\fP describes expected behavior, as given
172 in \fI<sys/mman.h>\fP:
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 */
182 Finally, a process may obtain information about whether pages are
183 core resident by using the call
185 mincore(addr, len, vec)
186 caddr_t addr; int len; result char *vec;
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.
192 Synchronization primitives
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:
200 value = mset(sem, wait)
201 result int value; semaphore *sem; int wait;
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,
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.
211 To release a lock a process calls:
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.
222 Two routines provide services analogous to the kernel
223 \fIsleep\fP and \fIwakeup\fP functions interpreted in the domain of
225 A process may relinquish the processor by calling \fImsleep\fP
226 with a set semaphore:
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:
239 An \fImwakeup\fP may awaken all sleepers on the semaphore,
240 or may awaken only the next sleeper on a queue.