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