xref: /netbsd-src/share/man/man9/uvm_map.9 (revision bdc22b2e01993381dcefeff2bc9b56ca75a4235c)
1.\"	$NetBSD: uvm_map.9,v 1.10 2017/05/20 08:00:47 wiz Exp $
2.\"
3.\" Copyright (c) 1998 Matthew R. Green
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
20.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
21.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
22.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
23.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25.\" SUCH DAMAGE.
26.\"
27.Dd May 20, 2017
28.Dt UVM_MAP 9
29.Os
30.Sh NAME
31.Nm uvm_map
32.Nd
33virtual address space management interface
34.Sh SYNOPSIS
35.In sys/param.h
36.In uvm/uvm.h
37.Ft int
38.Fn uvm_map "struct vm_map *map" "vaddr_t *startp" "vsize_t size" \
39"struct uvm_object *uobj" "voff_t uoffset" "vsize_t align" "uvm_flag_t flags"
40.Ft void
41.Fn uvm_unmap "struct vm_map *map" "vaddr_t start" "vaddr_t end"
42.Ft int
43.Fn uvm_map_pageable "struct vm_map *map" "vaddr_t start" "vaddr_t end" \
44"bool new_pageable" "int lockflags"
45.Ft bool
46.Fn uvm_map_checkprot "struct vm_map *map" "vaddr_t start" "vaddr_t end" \
47"vm_prot_t protection"
48.Ft int
49.Fn uvm_map_protect "struct vm_map *map" "vaddr_t start" "vaddr_t end" \
50"vm_prot_t new_prot" "bool set_max"
51.Ft int
52.Fn uvm_map_protect_user "struct lwp *l" "vaddr_t start" "vaddr_t end" \
53"vm_prot_t new_prot"
54.Ft int
55.Fn uvm_deallocate "struct vm_map *map" "vaddr_t start" "vsize_t size"
56.Ft struct vmspace *
57.Fn uvmspace_alloc "vaddr_t min" "vaddr_t max"
58.Ft void
59.Fn uvmspace_exec "struct lwp *l" "vaddr_t start" "vaddr_t end"
60.Ft struct vmspace *
61.Fn uvmspace_fork "struct vmspace *vm"
62.Ft void
63.Fn uvmspace_free "struct vmspace *vm"
64.Ft void
65.Fn uvmspace_share "struct proc *p1" "struct proc *p2"
66.\" .Ft void
67.\" .Fn uvmspace_unshare "struct lwp *l"
68.Ft vaddr_t
69.Fn uvm_uarea_alloc "void"
70.Ft void
71.Fn uvm_uarea_free "vaddr_t uaddr"
72.Ft vaddr_t
73.Fn uvm_uarea_system_alloc "void"
74.Ft void
75.Fn uvm_uarea_system_free "vaddr_t uaddr"
76.Sh DESCRIPTION
77The UVM facility for virtual address space management.
78.Sh FUNCTIONS
79.Fn uvm_map
80establishes a valid mapping in map
81.Fa map ,
82which must be unlocked.
83The new mapping has size
84.Fa size ,
85which must be a multiple of
86.Dv PAGE_SIZE .
87.Pp
88The
89.Fa uobj
90and
91.Fa uoffset
92arguments can have four meanings:
93.Bl -bullet -offset abcd -compact
94.It
95When
96.Fa uobj
97is
98.Dv NULL
99and
100.Fa uoffset
101is
102.Dv UVM_UNKNOWN_OFFSET ,
103.Fn uvm_map
104does not use the machine-dependent
105.Dv PMAP_PREFER
106function.
107.It
108When
109.Fa uobj
110is
111.Dv NULL
112and
113.Fa uoffset
114is any other value, it is used as the hint to
115.Dv PMAP_PREFER .
116.It
117When
118.Fa uobj
119is not
120.Dv NULL
121and
122.Fa uoffset
123is
124.Dv UVM_UNKNOWN_OFFSET ,
125.Fn uvm_map
126finds the offset based upon the virtual address, passed as
127.Fa startp .
128.It
129When
130.Fa uobj
131is not
132.Dv NULL
133and
134.Fa uoffset
135is any other value, then a regular mapping is performed at this offset.
136The start address of the map will be returned in
137.Fa startp .
138.El
139Note that
140.Fn uvm_map
141does not add a reference to
142.Fa uobj ;
143it is the caller's responsibility to do so.
144.Pp
145.Fa align
146specifies alignment of mapping unless
147.Dv UVM_FLAG_FIXED
148is specified in
149.Fa flags .
150.Fa align
151must be a power of 2.
152.Pp
153.Fa flags
154passed to
155.Fn uvm_map
156are typically created using the
157.Fn UVM_MAPFLAG "vm_prot_t prot" "vm_prot_t maxprot" "vm_inherit_t inh" \
158"int advice" "int flags"
159macro, which uses the following values.
160.Pp
161The values that
162.Fa prot
163and
164.Fa maxprot
165can take are:
166.Bl -tag -offset abcd -compact -width UVM_ADV_SEQUENTIAL
167.It UVM_PROT_NONE
168No protection bits.
169.It UVM_PROT_R
170Read.
171.It UVM_PROT_W
172Write.
173.It UVM_PROT_X
174Exec.
175.It UVM_PROT_MASK
176Mask to extraction the protection bits.
177.El
178Additionally, the following constants for ORed values are available:
179.Dv UVM_PROT_RW ,
180.Dv UVM_PROT_RX ,
181.Dv UVM_PROT_WX
182and
183.Dv UVM_PROT_RWX .
184.Pp
185The values that
186.Fa inh
187can take are:
188.Bl -tag -offset abcd -compact -width UVM_ADV_SEQUENTIAL
189.It UVM_INH_SHARE
190Share the map.
191.It UVM_INH_COPY
192Copy the map.
193.It UVM_INH_NONE
194No inheritance.
195.It UVM_INH_MASK
196Mask to extract inherit flags.
197.El
198.Pp
199The values that
200.Fa advice
201can take are:
202.Bl -tag -offset abcd -compact -width UVM_ADV_SEQUENTIAL
203.It UVM_ADV_NORMAL
204"Normal" use.
205.It UVM_ADV_RANDOM
206"Random" access likelihood.
207.It UVM_ADV_SEQUENTIAL
208"Sequential" access likelihood.
209.It UVM_ADV_MASK
210Mask to extract the advice flags.
211.El
212.Pp
213The values that
214.Fa flags
215can take are:
216.Bl -tag -offset abcd -compact -width UVM_ADV_SEQUENTIAL
217.It UVM_FLAG_FIXED
218Attempt to map on the address specified by
219.Fa startp .
220Otherwise, it is used just as a hint.
221.It UVM_FLAG_OVERLAY
222Establish overlay.
223.It UVM_FLAG_NOMERGE
224Do not merge map entries, if such merge is possible.
225.It UVM_FLAG_COPYONW
226Use copy-on-write i.e. do not fault in the pages immediately.
227.It UVM_FLAG_AMAPPAD
228Used for BSS: allocate larger amap, if extending is likely.
229.It UVM_FLAG_TRYLOCK
230Fail if cannot acquire the lock immediately.
231.It UVM_FLAG_NOWAIT
232Not allowed to sleep.
233Fail, in such case.
234.It UVM_FLAG_QUANTUM
235Indicates that map entry cannot be split once mapped.
236.It UVM_FLAG_WAITVA
237Sleep until VA space is available, if it is not.
238.It UVM_FLAG_VAONLY
239Unmap only VA space.
240Used by
241.Fn uvm_unmap .
242.It UVM_FLAG_UNMAP
243Any existing entires in the range for this mapping should be
244unmapped as part of creating the new mapping.
245Use of this flag without also specifying
246.Dv UVM_FLAG_FIXED
247is a bug.
248.El
249.Pp
250The
251.Dv UVM_MAPFLAG
252macro arguments can be combined with an or operator.
253There are several special purpose macros for checking protection
254combinations, e.g., the
255.Dv UVM_PROT_WX .
256There are also some additional macros to extract bits from the flags.
257The
258.Dv UVM_PROTECTION ,
259.Dv UVM_INHERIT ,
260.Dv UVM_MAXPROTECTION
261and
262.Dv UVM_ADVICE
263macros return the protection, inheritance, maximum protection, and
264advice, respectively.
265.Fn uvm_map
266returns zero on success or error number otherwise.
267.Pp
268.Fn uvm_unmap
269removes a valid mapping,
270from
271.Fa start
272to
273.Fa end ,
274in map
275.Fa map ,
276which must be unlocked.
277.Pp
278.Fn uvm_map_pageable
279changes the pageability of the pages in the range from
280.Fa start
281to
282.Fa end
283in map
284.Fa map
285to
286.Fa new_pageable .
287.Fn uvm_map_pageable
288returns zero on success or error number otherwise.
289.Pp
290.Fn uvm_map_checkprot
291checks the protection of the range from
292.Fa start
293to
294.Fa end
295in map
296.Fa map
297against
298.Fa protection .
299This returns either
300.Dv true
301or
302.Dv false .
303.Pp
304.Fn uvm_map_protect
305changes the protection
306.Fa start
307to
308.Fa end
309in map
310.Fa map
311to
312.Fa new_prot ,
313also setting the maximum protection to the region to
314.Fa new_prot
315if
316.Fa set_max
317is true.
318This function returns a standard UVM return value.
319.Pp
320.Fn uvm_map_protect_user
321verifies that the new permissions honor PAX restrictions if applicable
322and forwards to
323.Fn uvm_map_protect
324on passing.
325.Pp
326.Fn uvm_deallocate
327deallocates kernel memory in map
328.Fa map
329from address
330.Fa start
331to
332.Fa start + size .
333.Pp
334.Fn uvmspace_alloc
335allocates and returns a new address space, with ranges from
336.Fa min
337to
338.Fa max .
339.Pp
340.Fn uvmspace_exec
341either reuses the address space of thread
342.Fa l
343(its process) if there are no other references to it, or creates
344a new one with
345.Fn uvmspace_alloc .
346The range of valid addresses in the address space is reset to
347.Fa start
348through
349.Fa end .
350.Pp
351.Fn uvmspace_fork
352creates and returns a new address space based upon the
353.Fa vm
354address space, typically used when allocating an address space for a
355child process.
356.Pp
357.Fn uvmspace_free
358lowers the reference count on the address space
359.Fa vm ,
360freeing the data structures if there are no other references.
361.Pp
362.Fn uvmspace_share
363causes process
364.Pa p2
365to share the address space of
366.Fa p1 .
367.\" .Pp
368.\" .Fn uvmspace_unshare
369.\" ensures that thread
370.\" .Fa l
371.\" has its own, unshared address space, by creating a new one if
372.\" necessary by calling
373.\" .Fn uvmspace_fork .
374.Pp
375.Fn uvm_uarea_alloc
376allocates memory for a u-area (i.e. kernel stack, PCB, etc) and returns
377the address.
378.Pp
379.Fn uvm_uarea_free
380frees a u-area allocated with
381.Fn uvm_uarea_alloc .
382.Pp
383.Fn uvm_uarea_system_alloc
384and
385.Fn uvm_uarea_system_free
386are optimized routines, which are used for kernel threads.
387.Sh SEE ALSO
388.Xr pmap 9 ,
389.Xr uvm 9 ,
390.Xr uvm_km 9 ,
391.Xr vmem 9
392.Sh HISTORY
393UVM and
394.Nm
395first appeared in
396.Nx 1.4 .
397