1.\" 2.\" Copyright (c) 2003 Bruce M Simpson <bms@spc.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 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. 13.\" 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 24.\" SUCH DAMAGE. 25.\" 26.Dd September 12, 2013 27.Dt VM_MAP_FIND 9 28.Os 29.Sh NAME 30.Nm vm_map_find 31.Nd find a free region within a map, and optionally map a vm_object 32.Sh SYNOPSIS 33.In sys/param.h 34.In vm/vm.h 35.In vm/vm_map.h 36.Ft int 37.Fo vm_map_find 38.Fa "vm_map_t map" "vm_object_t object" "vm_ooffset_t offset" 39.Fa "vm_offset_t *addr" "vm_size_t length" "vm_offset_t max_addr" 40.Fa "int find_space" "vm_prot_t prot" "vm_prot_t max" "int cow" 41.Fc 42.Sh DESCRIPTION 43The 44.Fn vm_map_find 45function attempts to find a free region in the target 46.Fa map , 47with the given 48.Fa length. 49If a free region is found, 50.Fn vm_map_find 51creates a mapping of 52.Fa object 53via a call to 54.Xr vm_map_insert 9 . 55.Pp 56The arguments 57.Fa offset , 58.Fa prot , 59.Fa max , 60and 61.Fa cow 62are passed unchanged to 63.Xr vm_map_insert 9 64when creating the mapping, if and only if a free region is found. 65.Pp 66If 67.Fa object 68is 69.Pf non- Dv NULL , 70the reference count on the object must be incremented 71by the caller before calling this function to account for the new entry. 72.Pp 73If 74.Fa max_addr 75is non-zero, 76it specifies an upper bound on the mapping. 77The mapping will only succeed if a free region can be found that resides 78entirely below 79.Fa max_addr . 80.Pp 81The 82.Fa find_space 83argument specifies the strategy to use when searching for a free region of 84the requested length. 85For all values other than 86.Dv VMFS_NO_SPACE , 87.Xr vm_map_findspace 9 88is called to locate a free region of the requested length with a starting 89address at or above 90.Fa *addr . 91The following strategies are supported: 92.Bl -tag -width "Dv VMFS_ALIGNED_SPACE Ns" 93.It Dv VMFS_NO_SPACE 94The mapping will only succeed if there is a free region of the requested 95length at the given address 96.Fa *addr . 97.It Dv VMFS_ANY_SPACE 98The mapping will succeed as long as there is a free region. 99.It Dv VMFS_SUPER_SPACE 100The mapping will succeed as long as there is a free region that begins on 101a superpage boundary. 102If 103.Fa object 104is 105.Pf non- Dv NULL 106and is already backed by superpages, 107then the mapping will require a free region that aligns relative to the 108existing superpages rather than one beginning on a superpage boundary. 109.It Dv VMFS_OPTIMAL_SPACE 110The mapping will succeed as long as there is a free region. 111However, if 112.Fa object 113is 114.Pf non- Dv NULL 115and is already backed by superpages, 116this strategy will attempt to find a free region aligned relative to 117the existing superpages. 118.It Dv VMFS_ALIGNED_SPACE Ns Pq Fa n 119The mapping will succeed as long as there is a free region that aligns on 120a 121.Pf 2^ Fa n 122boundary. 123.El 124.Sh IMPLEMENTATION NOTES 125This function acquires a lock on 126.Fa map 127by calling 128.Xr vm_map_lock 9 , 129and holds it until the function returns. 130.Pp 131The search for a free region is defined to be first-fit, from the address 132.Fa addr 133onwards. 134.Sh RETURN VALUES 135The 136.Fn vm_map_find 137function returns 138.Dv KERN_SUCCESS 139if the mapping was successfully created. 140If space could not be found or 141.Fa find_space 142was 143.Dv VMFS_NO_SPACE 144and the given address, 145.Fa addr , 146was already mapped, 147.Dv KERN_NO_SPACE 148will be returned. 149If the discovered range turned out to be bogus, 150.Dv KERN_INVALID_ADDRESS 151will be returned. 152.Sh SEE ALSO 153.Xr vm_map 9 , 154.Xr vm_map_findspace 9 , 155.Xr vm_map_insert 9 , 156.Xr vm_map_lock 9 157.Sh AUTHORS 158This manual page was written by 159.An Bruce M Simpson Aq Mt bms@spc.org . 160