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