1.\" $OpenBSD: uvm_map.9,v 1.3 2022/12/09 21:19:53 jmc Exp $ 2.\" $NetBSD: uvm.9,v 1.14 2000/06/29 06:08:44 mrg Exp $ 3.\" 4.\" Copyright (c) 1998 Matthew R. Green 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 21.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 22.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 23.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 24.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd $Mdocdate: December 9 2022 $ 29.Dt UVM_MAP 9 30.Os 31.Sh NAME 32.Nm uvm_map , 33.Nm uvm_map_pageable , 34.Nm uvm_map_pageable_all , 35.Nm uvm_map_checkprot , 36.Nm uvm_map_protect , 37.Nm uvmspace_alloc , 38.Nm uvmspace_exec , 39.Nm uvmspace_fork , 40.Nm uvmspace_free , 41.Nm uvmspace_share , 42.Nm uvm_uarea_alloc , 43.Nm uvm_uarea_free , 44.Nm UVM_MAPFLAG 45.Nd virtual address space management interface 46.Sh SYNOPSIS 47.In sys/param.h 48.In uvm/uvm.h 49.Ft int 50.Fn uvm_map "vm_map_t map" "vaddr_t *startp" "vsize_t size" "struct uvm_object *uobj" "voff_t uoffset" "vsize_t alignment" "unsigned int flags" 51.Ft int 52.Fn uvm_map_pageable "vm_map_t map" "vaddr_t start" "vaddr_t end" "boolean_t new_pageable" "int lockflags" 53.Ft int 54.Fn uvm_map_pageable_all "vm_map_t map" "int flags" "vsize_t limit" 55.Ft boolean_t 56.Fn uvm_map_checkprot "vm_map_t map" "vaddr_t start" "vaddr_t end" "vm_prot_t protection" 57.Ft int 58.Fn uvm_map_protect "vm_map_t map" "vaddr_t start" "vaddr_t end" "vm_prot_t new_prot" "int et" "boolean_t set_max" "boolean_t checkimmutable" 59.Ft struct vmspace * 60.Fn uvmspace_alloc "vaddr_t min" "vaddr_t max" "boolean_t pageable" "boolean_t remove_holes" 61.Ft void 62.Fn uvmspace_exec "struct proc *p" "vaddr_t start" "vaddr_t end" 63.Ft struct vmspace * 64.Fn uvmspace_fork "struct process *pr" 65.Ft void 66.Fn uvmspace_free "struct vmspace *vm" 67.Ft struct vmspace * 68.Fn uvmspace_share "struct process *pr" 69.Ft vaddr_t 70.Fn uvm_uarea_alloc "void" 71.Ft void 72.Fn uvm_uarea_free "struct proc *p" 73.Ft unsigned int 74.Fn UVM_MAPFLAG "vm_prot_t prot" "vm_prot_t maxprot" "vm_inherit_t inh" "int advice" "int flags" 75.Sh DESCRIPTION 76The 77.Fn uvm_map 78function establishes a valid mapping in map 79.Fa map , 80which must be unlocked. 81The new mapping has size 82.Fa size , 83which must be in 84.Dv PAGE_SIZE 85units. 86If 87.Fa alignment 88is non-zero, it describes the required alignment of the list, in 89power-of-two notation. 90The 91.Fa uobj 92and 93.Fa uoffset 94arguments can have four meanings. 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. 107If 108.Fa uoffset 109is any other value, it is used as the hint to 110.Dv PMAP_PREFER . 111When 112.Fa uobj 113is not 114.Dv NULL 115and 116.Fa uoffset 117is 118.Dv UVM_UNKNOWN_OFFSET , 119.Fn uvm_map 120finds the offset based upon the virtual address, passed as 121.Fa startp . 122If 123.Fa uoffset 124is any other value, we are doing a normal mapping at this offset. 125The start address of the map will be returned in 126.Fa startp . 127.Pp 128.Fa flags 129passed to 130.Fn uvm_map 131are typically created using the 132.Fn UVM_MAPFLAG 133macro, which uses the following values. 134The 135.Fa prot 136and 137.Fa maxprot 138can take a mix of the following values: 139.Bd -literal 140#define PROT_MASK 0x07 /* protection mask */ 141#define PROT_NONE 0x00 /* protection none */ 142#define PROT_READ 0x01 /* read */ 143#define PROT_WRITE 0x02 /* write */ 144#define PROT_EXEC 0x04 /* exec */ 145.Ed 146.Pp 147The values that 148.Fa inh 149can take are: 150.Bd -literal 151#define MAP_INHERIT_MASK 0x30 /* inherit mask */ 152#define MAP_INHERIT_SHARE 0x00 /* "share" */ 153#define MAP_INHERIT_COPY 0x10 /* "copy" */ 154#define MAP_INHERIT_NONE 0x20 /* "none" */ 155#define MAP_INHERIT_ZERO 0x30 /* "zero" */ 156.Ed 157.Pp 158The values that 159.Fa advice 160can take are: 161.Bd -literal 162#define MADV_NORMAL 0x0 /* 'normal' */ 163#define MADV_RANDOM 0x1 /* 'random' */ 164#define MADV_SEQUENTIAL 0x2 /* 'sequential' */ 165#define MADV_MASK 0x7 /* mask */ 166.Ed 167.Pp 168The values that 169.Fa flags 170can take are: 171.Bd -literal 172#define UVM_FLAG_FIXED 0x0010000 /* find space */ 173#define UVM_FLAG_OVERLAY 0x0020000 /* establish overlay */ 174#define UVM_FLAG_NOMERGE 0x0040000 /* don't merge map entries */ 175#define UVM_FLAG_COPYONW 0x0080000 /* set copy_on_write flag */ 176#define UVM_FLAG_TRYLOCK 0x0100000 /* fail if we can not lock map */ 177#define UVM_FLAG_HOLE 0x0200000 /* no backend */ 178#define UVM_FLAG_QUERY 0x0400000 /* do everything, 179 except actual execution */ 180#define UVM_FLAG_NOFAULT 0x0800000 /* don't fault */ 181#define UVM_FLAG_UNMAP 0x1000000 /* unmap to make space */ 182#define UVM_FLAG_STACK 0x2000000 /* page may contain a stack */ 183.Ed 184.Pp 185The 186.Dv UVM_MAPFLAG 187macro arguments can be combined with an or operator. 188There are also some additional macros to extract bits from the flags. 189The 190.Dv UVM_PROTECTION , 191.Dv UVM_INHERIT , 192.Dv UVM_MAXPROTECTION 193and 194.Dv UVM_ADVICE 195macros return the protection, inheritance, maximum protection and advice, 196respectively. 197.Fn uvm_map 198returns a standard errno. 199.Pp 200The 201.Fn uvm_map_pageable 202function changes the pageability of the pages in the range from 203.Fa start 204to 205.Fa end 206in map 207.Fa map 208to 209.Fa new_pageable . 210The 211.Fn uvm_map_pageable_all 212function changes the pageability of all mapped regions. 213If 214.Fa limit 215is non-zero and 216.Fn pmap_wired_count 217is implemented, 218.Dv ENOMEM 219is returned if the amount of wired pages exceed 220.Fa limit . 221The map is locked on entry if 222.Fa lockflags 223contain 224.Dv UVM_LK_ENTER , 225and locked on exit if 226.Fa lockflags 227contain 228.Dv UVM_LK_EXIT . 229.Fn uvm_map_pageable 230and 231.Fn uvm_map_pageable_all 232return a standard errno. 233.Pp 234The 235.Fn uvm_map_checkprot 236function checks the protection of the range from 237.Fa start 238to 239.Fa end 240in map 241.Fa map 242against 243.Fa protection . 244This returns either 245.Dv TRUE 246or 247.Dv FALSE . 248.Pp 249The 250.Fn uvm_map_protect 251function changes the protection 252.Fa start 253to 254.Fa end 255in map 256.Fa map 257to 258.Fa new_prot , 259also setting the maximum protection to the region to 260.Fa new_prot 261if 262.Fa set_max 263is non-zero. 264The 265.Fa et 266parameter should be 0, unless a 267.Dv PROT_READ | PROT_WRITE 268mapping is being changed to extend the stack limit, then it may be 269.Dv UVM_ET_STACK . 270This function returns a standard errno. 271.Pp 272The 273.Fn uvmspace_alloc 274function allocates and returns a new address space, with ranges from 275.Fa min 276to 277.Fa max , 278setting the pageability of the address space to 279.Fa pageable . 280If 281.Fa remove_holes 282is non-zero, hardware 283.Sq holes 284in the virtual address space will be removed from the newly allocated 285address space. 286.Pp 287The 288.Fn uvmspace_exec 289function either reuses the address space of process 290.Fa p 291if there are no other references to it, or creates 292a new one with 293.Fn uvmspace_alloc . 294The range of valid addresses in the address space is reset to 295.Fa start 296through 297.Fa end . 298.Pp 299The 300.Fn uvmspace_fork 301function creates and returns a new address space based upon the 302address space of process 303.Fa pr 304and is typically used when allocating an address space for a 305child process. 306.Pp 307The 308.Fn uvmspace_free 309function lowers the reference count on the address space 310.Fa vm , 311freeing the data structures if there are no other references. 312.Pp 313The 314.Fn uvmspace_share 315function returns a reference to the address space of process 316.Fa pr , 317increasing its reference count. 318.Pp 319The 320.Fn uvm_uarea_alloc 321function allocates a thread's 322.Sq uarea , 323the memory where its kernel stack and PCB are stored. 324The 325.Fn uvm_uarea_free 326function frees the uarea for 327thread 328.Fa p , 329which must no longer be running. 330.Sh SEE ALSO 331.Xr pmap 9 332