1.\" $NetBSD: uvm_map.9,v 1.12 2020/08/27 14:14:00 fcambus 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 139If 140.Fa uobj 141is supplied, then 142.Fn uvm_map 143.Em consumes 144the caller's reference to 145.Fa uobj 146on success; 147.Fn uvm_unmap 148will release it when removing this mapping. 149On failure, 150.Fn uvm_map 151leaves the reference count of 152.Fa uobj 153unmodified. 154.Pp 155.Fa align 156specifies alignment of mapping unless 157.Dv UVM_FLAG_FIXED 158is specified in 159.Fa flags . 160.Fa align 161must be a power of 2. 162.Pp 163.Fa flags 164passed to 165.Fn uvm_map 166are typically created using the 167.Fn UVM_MAPFLAG "vm_prot_t prot" "vm_prot_t maxprot" "vm_inherit_t inh" \ 168"int advice" "int flags" 169macro, which uses the following values. 170.Pp 171The values that 172.Fa prot 173and 174.Fa maxprot 175can take are: 176.Bl -tag -offset abcd -compact -width UVM_ADV_SEQUENTIAL 177.It UVM_PROT_NONE 178No protection bits. 179.It UVM_PROT_R 180Read. 181.It UVM_PROT_W 182Write. 183.It UVM_PROT_X 184Exec. 185.It UVM_PROT_MASK 186Mask to extraction the protection bits. 187.El 188Additionally, the following constants for ORed values are available: 189.Dv UVM_PROT_RW , 190.Dv UVM_PROT_RX , 191.Dv UVM_PROT_WX 192and 193.Dv UVM_PROT_RWX . 194.Pp 195The values that 196.Fa inh 197can take are: 198.Bl -tag -offset abcd -compact -width UVM_ADV_SEQUENTIAL 199.It UVM_INH_SHARE 200Share the map. 201.It UVM_INH_COPY 202Copy the map. 203.It UVM_INH_NONE 204No inheritance. 205.It UVM_INH_MASK 206Mask to extract inherit flags. 207.El 208.Pp 209The values that 210.Fa advice 211can take are: 212.Bl -tag -offset abcd -compact -width UVM_ADV_SEQUENTIAL 213.It UVM_ADV_NORMAL 214"Normal" use. 215.It UVM_ADV_RANDOM 216"Random" access likelihood. 217.It UVM_ADV_SEQUENTIAL 218"Sequential" access likelihood. 219.It UVM_ADV_MASK 220Mask to extract the advice flags. 221.El 222.Pp 223The values that 224.Fa flags 225can take are: 226.Bl -tag -offset abcd -compact -width UVM_ADV_SEQUENTIAL 227.It UVM_FLAG_FIXED 228Attempt to map on the address specified by 229.Fa startp . 230Otherwise, it is used just as a hint. 231.It UVM_FLAG_OVERLAY 232Establish overlay. 233.It UVM_FLAG_NOMERGE 234Do not merge map entries, if such merge is possible. 235.It UVM_FLAG_COPYONW 236Use copy-on-write i.e. do not fault in the pages immediately. 237.It UVM_FLAG_AMAPPAD 238Used for BSS: allocate larger amap, if extending is likely. 239.It UVM_FLAG_TRYLOCK 240Fail if cannot acquire the lock immediately. 241.It UVM_FLAG_NOWAIT 242Not allowed to sleep. 243Fail, in such case. 244.It UVM_FLAG_QUANTUM 245Indicates that map entry cannot be split once mapped. 246.It UVM_FLAG_WAITVA 247Sleep until VA space is available, if it is not. 248.It UVM_FLAG_VAONLY 249Unmap only VA space. 250Used by 251.Fn uvm_unmap . 252.It UVM_FLAG_UNMAP 253Any existing entries in the range for this mapping should be 254unmapped as part of creating the new mapping. 255Use of this flag without also specifying 256.Dv UVM_FLAG_FIXED 257is a bug. 258.El 259.Pp 260The 261.Dv UVM_MAPFLAG 262macro arguments can be combined with an or operator. 263There are several special purpose macros for checking protection 264combinations, e.g., the 265.Dv UVM_PROT_WX . 266There are also some additional macros to extract bits from the flags. 267The 268.Dv UVM_PROTECTION , 269.Dv UVM_INHERIT , 270.Dv UVM_MAXPROTECTION 271and 272.Dv UVM_ADVICE 273macros return the protection, inheritance, maximum protection, and 274advice, respectively. 275.Fn uvm_map 276returns zero on success or error number otherwise. 277.Pp 278.Fn uvm_unmap 279removes a valid mapping, 280from 281.Fa start 282to 283.Fa end , 284in map 285.Fa map , 286which must be unlocked. 287.Pp 288.Fn uvm_map_pageable 289changes the pageability of the pages in the range from 290.Fa start 291to 292.Fa end 293in map 294.Fa map 295to 296.Fa new_pageable . 297.Fn uvm_map_pageable 298returns zero on success or error number otherwise. 299.Pp 300.Fn uvm_map_checkprot 301checks the protection of the range from 302.Fa start 303to 304.Fa end 305in map 306.Fa map 307against 308.Fa protection . 309This returns either 310.Dv true 311or 312.Dv false . 313.Pp 314.Fn uvm_map_protect 315changes the protection 316.Fa start 317to 318.Fa end 319in map 320.Fa map 321to 322.Fa new_prot , 323also setting the maximum protection to the region to 324.Fa new_prot 325if 326.Fa set_max 327is true. 328This function returns a standard UVM return value. 329.Pp 330.Fn uvm_map_protect_user 331verifies that the new permissions honor PAX restrictions if applicable 332and forwards to 333.Fn uvm_map_protect 334on passing. 335.Pp 336.Fn uvm_deallocate 337deallocates kernel memory in map 338.Fa map 339from address 340.Fa start 341to 342.Fa start + size . 343.Pp 344.Fn uvmspace_alloc 345allocates and returns a new address space, with ranges from 346.Fa min 347to 348.Fa max . 349.Pp 350.Fn uvmspace_exec 351either reuses the address space of thread 352.Fa l 353(its process) if there are no other references to it, or creates 354a new one with 355.Fn uvmspace_alloc . 356The range of valid addresses in the address space is reset to 357.Fa start 358through 359.Fa end . 360.Pp 361.Fn uvmspace_fork 362creates and returns a new address space based upon the 363.Fa vm 364address space, typically used when allocating an address space for a 365child process. 366.Pp 367.Fn uvmspace_free 368lowers the reference count on the address space 369.Fa vm , 370freeing the data structures if there are no other references. 371.Pp 372.Fn uvmspace_share 373causes process 374.Pa p2 375to share the address space of 376.Fa p1 . 377.\" .Pp 378.\" .Fn uvmspace_unshare 379.\" ensures that thread 380.\" .Fa l 381.\" has its own, unshared address space, by creating a new one if 382.\" necessary by calling 383.\" .Fn uvmspace_fork . 384.Pp 385.Fn uvm_uarea_alloc 386allocates memory for a u-area (i.e. kernel stack, PCB, etc) and returns 387the address. 388.Pp 389.Fn uvm_uarea_free 390frees a u-area allocated with 391.Fn uvm_uarea_alloc . 392.Pp 393.Fn uvm_uarea_system_alloc 394and 395.Fn uvm_uarea_system_free 396are optimized routines, which are used for kernel threads. 397.Sh SEE ALSO 398.Xr pmap 9 , 399.Xr uvm 9 , 400.Xr uvm_km 9 , 401.Xr vmem 9 402.Sh HISTORY 403UVM and 404.Nm 405first appeared in 406.Nx 1.4 . 407