1.\" $NetBSD: uvm_map.9,v 1.5 2014/05/21 12:15:25 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, 2014 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_deallocate "struct vm_map *map" "vaddr_t start" "vsize_t size" 53.Ft struct vmspace * 54.Fn uvmspace_alloc "vaddr_t min" "vaddr_t max" 55.Ft void 56.Fn uvmspace_exec "struct lwp *l" "vaddr_t start" "vaddr_t end" 57.Ft struct vmspace * 58.Fn uvmspace_fork "struct vmspace *vm" 59.Ft void 60.Fn uvmspace_free "struct vmspace *vm" 61.Ft void 62.Fn uvmspace_share "struct proc *p1" "struct proc *p2" 63.\" .Ft void 64.\" .Fn uvmspace_unshare "struct lwp *l" 65.Ft vaddr_t 66.Fn uvm_uarea_alloc "void" 67.Ft void 68.Fn uvm_uarea_free "vaddr_t uaddr" 69.Ft vaddr_t 70.Fn uvm_uarea_system_alloc "void" 71.Ft void 72.Fn uvm_uarea_system_free "vaddr_t uaddr" 73.Sh DESCRIPTION 74The UVM facility for virtual address space management. 75.Sh FUNCTIONS 76.Fn uvm_map 77establishes a valid mapping in map 78.Fa map , 79which must be unlocked. 80The new mapping has size 81.Fa size , 82which must be a multiple of 83.Dv PAGE_SIZE . 84.Pp 85The 86.Fa uobj 87and 88.Fa uoffset 89arguments can have four meanings: 90.Bl -bullet -offset abcd -compact 91.It 92When 93.Fa uobj 94is 95.Dv NULL 96and 97.Fa uoffset 98is 99.Dv UVM_UNKNOWN_OFFSET , 100.Fn uvm_map 101does not use the machine-dependent 102.Dv PMAP_PREFER 103function. 104.It 105When 106.Fa uobj 107is 108.Dv NULL 109and 110.Fa uoffset 111is any other value, it is used as the hint to 112.Dv PMAP_PREFER . 113.It 114When 115.Fa uobj 116is not 117.Dv NULL 118and 119.Fa uoffset 120is 121.Dv UVM_UNKNOWN_OFFSET , 122.Fn uvm_map 123finds the offset based upon the virtual address, passed as 124.Fa startp . 125.It 126When 127.Fa uobj 128is not 129.Dv NULL 130and 131.Fa uoffset 132is any other value, then a regular mapping is performed at this offset. 133The start address of the map will be returned in 134.Fa startp . 135.El 136Note that 137.Fn uvm_map 138does not add a reference to 139.Fa uobj ; 140it is the caller's responsibility to do so. 141.Pp 142.Fa align 143specifies alignment of mapping unless 144.Dv UVM_FLAG_FIXED 145is specified in 146.Fa flags . 147.Fa align 148must be a power of 2. 149.Pp 150.Fa flags 151passed to 152.Fn uvm_map 153are typically created using the 154.Fn UVM_MAPFLAG "vm_prot_t prot" "vm_prot_t maxprot" "vm_inherit_t inh" \ 155"int advice" "int flags" 156macro, which uses the following values. 157.Pp 158The values that 159.Fa prot 160and 161.Fa maxprot 162can take are: 163.Bl -tag -offset abcd -compact -width UVM_ADV_SEQUENTIAL 164.It UVM_PROT_NONE 165No protection bits. 166.It UVM_PROT_R 167Read. 168.It UVM_PROT_W 169Write. 170.It UVM_PROT_X 171Exec. 172.It UVM_PROT_MASK 173Mask to extraction the protection bits. 174.El 175Additionally, the following constants for ORed values are available: 176.Dv UVM_PROT_RW , 177.Dv UVM_PROT_RX , 178.Dv UVM_PROT_WX 179and 180.Dv UVM_PROT_RWX . 181.Pp 182The values that 183.Fa inh 184can take are: 185.Bl -tag -offset abcd -compact -width UVM_ADV_SEQUENTIAL 186.It UVM_INH_SHARE 187Share the map. 188.It UVM_INH_COPY 189Copy the map. 190.It UVM_INH_NONE 191No inheritance. 192.It UVM_INH_MASK 193Mark to extract inherit flags. 194.El 195.Pp 196The values that 197.Fa advice 198can take are: 199.Bl -tag -offset abcd -compact -width UVM_ADV_SEQUENTIAL 200.It UVM_ADV_NORMAL 201"Normal" use. 202.It UVM_ADV_RANDOM 203"Random" access likelihood. 204.It UVM_ADV_SEQUENTIAL 205"Sequential" access likelihood. 206.It UVM_ADV_MASK 207Mask to extract the advice flags. 208.El 209.Pp 210The values that 211.Fa flags 212can take are: 213.Bl -tag -offset abcd -compact -width UVM_ADV_SEQUENTIAL 214.It UVM_FLAG_FIXED 215Attempt to map on the address specified by 216.Fa startp . 217Otherwise, it is used just as a hint. 218.It UVM_FLAG_OVERLAY 219Establish overlay. 220.It UVM_FLAG_NOMERGE 221Do not merge map entries, if such merge is possible. 222.It UVM_FLAG_COPYONW 223Use copy-on-write i.e. do not fault in the pages immediately. 224.It UVM_FLAG_AMAPPAD 225Used for BSS: allocate larger amap, if extending is likely. 226.It UVM_FLAG_TRYLOCK 227Fail if cannot acquire the lock immediately. 228.It UVM_FLAG_NOWAIT 229Not allowed to sleep. 230Fail, in such case. 231.It UVM_FLAG_QUANTUM 232Indicates that map entry cannot be split once mapped. 233.It UVM_FLAG_WAITVA 234Sleep until VA space is available, if it is not. 235.It UVM_FLAG_VAONLY 236Unmap only VA space. 237Used by 238.Fn uvm_unmap . 239.El 240.Pp 241The 242.Dv UVM_MAPFLAG 243macro arguments can be combined with an or operator. 244There are several special purpose macros for checking protection 245combinations, e.g., the 246.Dv UVM_PROT_WX . 247There are also some additional macros to extract bits from the flags. 248The 249.Dv UVM_PROTECTION , 250.Dv UVM_INHERIT , 251.Dv UVM_MAXPROTECTION 252and 253.Dv UVM_ADVICE 254macros return the protection, inheritance, maximum protection, and 255advice, respectively. 256.Fn uvm_map 257returns zero on success or error number otherwise. 258.Pp 259.Fn uvm_unmap 260removes a valid mapping, 261from 262.Fa start 263to 264.Fa end , 265in map 266.Fa map , 267which must be unlocked. 268.Pp 269.Fn uvm_map_pageable 270changes the pageability of the pages in the range from 271.Fa start 272to 273.Fa end 274in map 275.Fa map 276to 277.Fa new_pageable . 278.Fn uvm_map_pageable 279returns zero on success or error number otherwise. 280.Pp 281.Fn uvm_map_checkprot 282checks the protection of the range from 283.Fa start 284to 285.Fa end 286in map 287.Fa map 288against 289.Fa protection . 290This returns either 291.Dv true 292or 293.Dv false . 294.Pp 295.Fn uvm_map_protect 296changes the protection 297.Fa start 298to 299.Fa end 300in map 301.Fa map 302to 303.Fa new_prot , 304also setting the maximum protection to the region to 305.Fa new_prot 306if 307.Fa set_max 308is true. 309This function returns a standard UVM return value. 310.Pp 311.Fn uvm_deallocate 312deallocates kernel memory in map 313.Fa map 314from address 315.Fa start 316to 317.Fa start + size . 318.Pp 319.Fn uvmspace_alloc 320allocates and returns a new address space, with ranges from 321.Fa min 322to 323.Fa max . 324.Pp 325.Fn uvmspace_exec 326either reuses the address space of thread 327.Fa l 328(its process) if there are no other references to it, or creates 329a new one with 330.Fn uvmspace_alloc . 331The range of valid addresses in the address space is reset to 332.Fa start 333through 334.Fa end . 335.Pp 336.Fn uvmspace_fork 337creates and returns a new address space based upon the 338.Fa vm 339address space, typically used when allocating an address space for a 340child process. 341.Pp 342.Fn uvmspace_free 343lowers the reference count on the address space 344.Fa vm , 345freeing the data structures if there are no other references. 346.Pp 347.Fn uvmspace_share 348causes process 349.Pa p2 350to share the address space of 351.Fa p1 . 352.\" .Pp 353.\" .Fn uvmspace_unshare 354.\" ensures that thread 355.\" .Fa l 356.\" has its own, unshared address space, by creating a new one if 357.\" necessary by calling 358.\" .Fn uvmspace_fork . 359.Pp 360.Fn uvm_uarea_alloc 361allocates memory for a u-area (i.e. kernel stack, PCB, etc) and returns 362the address. 363.Pp 364.Fn uvm_uarea_free 365frees a u-area allocated with 366.Fn uvm_uarea_alloc . 367.Pp 368.Fn uvm_uarea_system_alloc 369and 370.Fn uvm_uarea_system_free 371are optimized routines, which are used for kernel threads. 372.Sh SEE ALSO 373.Xr pmap 9 , 374.Xr uvm 9 , 375.Xr uvm_km 9 , 376.Xr vmem 9 377.Sh HISTORY 378UVM and 379.Nm 380first appeared in 381.Nx 1.4 . 382