2 .\" Copyright (c) 2003 Bruce M Simpson <bms@spc.org>
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .Dd September 12, 2013
33 .Nd find a free region within a map, and optionally map a vm_object
40 .Fa "vm_map_t map" "vm_object_t object" "vm_ooffset_t offset"
41 .Fa "vm_offset_t *addr" "vm_size_t length" "vm_offset_t max_addr"
42 .Fa "int find_space" "vm_prot_t prot" "vm_prot_t max" "int cow"
47 function attempts to find a free region in the target
51 If a free region is found,
64 are passed unchanged to
66 when creating the mapping, if and only if a free region is found.
72 the reference count on the object must be incremented
73 by the caller before calling this function to account for the new entry.
78 it specifies an upper bound on the mapping.
79 The mapping will only succeed if a free region can be found that resides
85 argument specifies the strategy to use when searching for a free region of
87 For all values other than
89 .Xr vm_map_findspace 9
90 is called to locate a free region of the requested length with a starting
93 The following strategies are supported:
94 .Bl -tag -width "Dv VMFS_ALIGNED_SPACE Ns"
96 The mapping will only succeed if there is a free region of the requested
97 length at the given address
100 The mapping will succeed as long as there is a free region.
101 .It Dv VMFS_SUPER_SPACE
102 The mapping will succeed as long as there is a free region that begins on
103 a superpage boundary.
108 and is already backed by superpages,
109 then the mapping will require a free region that aligns relative to the
110 existing superpages rather than one beginning on a superpage boundary.
111 .It Dv VMFS_OPTIMAL_SPACE
112 The mapping will succeed as long as there is a free region.
117 and is already backed by superpages,
118 this strategy will attempt to find a free region aligned relative to
119 the existing superpages.
120 .It Dv VMFS_ALIGNED_SPACE Ns Pq Fa n
121 The mapping will succeed as long as there is a free region that aligns on
126 .Sh IMPLEMENTATION NOTES
127 This function acquires a lock on
131 and holds it until the function returns.
133 The search for a free region is defined to be first-fit, from the address
141 if the mapping was successfully created.
142 If space could not be found or
146 and the given address,
151 If the discovered range turned out to be bogus,
152 .Dv KERN_INVALID_ADDRESS
156 .Xr vm_map_findspace 9 ,
157 .Xr vm_map_insert 9 ,
160 This manual page was written by
161 .An Bruce M Simpson Aq bms@spc.org .