Copyright (c) 1998 Matthew R. Green
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
.Dd June 1, 2011 .Dt UVM_MAP 9 .Os .Sh NAME .Nm uvm_map .Nd virtual address space management interface .Sh SYNOPSIS n sys/param.h n uvm/uvm.h .Ft int .Fn uvm_map "struct vm_map *map" "vaddr_t *startp" "vsize_t size" \ "struct uvm_object *uobj" "voff_t uoffset" "vsize_t align" "uvm_flag_t flags" .Ft void .Fn uvm_unmap "struct vm_map *map" "vaddr_t start" "vaddr_t end" .Ft int .Fn uvm_map_pageable "struct vm_map *map" "vaddr_t start" "vaddr_t end" \ "bool new_pageable" "int lockflags" .Ft bool .Fn uvm_map_checkprot "struct vm_map *map" "vaddr_t start" "vaddr_t end" \ "vm_prot_t protection" .Ft int .Fn uvm_map_protect "struct vm_map *map" "vaddr_t start" "vaddr_t end" \ "vm_prot_t new_prot" "bool set_max" .Ft int .Fn uvm_deallocate "struct vm_map *map" "vaddr_t start" "vsize_t size" .Ft struct vmspace * .Fn uvmspace_alloc "vaddr_t min" "vaddr_t max" "int pageable" .Ft void .Fn uvmspace_exec "struct lwp *l" "vaddr_t start" "vaddr_t end" .Ft struct vmspace * .Fn uvmspace_fork "struct vmspace *vm" .Ft void .Fn uvmspace_free "struct vmspace *vm1" .Ft void .Fn uvmspace_share "struct proc *p1" "struct proc *p2" .Ft void .Fn uvmspace_unshare "struct lwp *l" .Ft bool .Fn uvm_uarea_alloc "vaddr_t *uaddrp" .Ft void .Fn uvm_uarea_free "vaddr_t uaddr" .Sh DESCRIPTION The UVM facility for virtual address space management. .Sh FUNCTIONS .Fn uvm_map establishes a valid mapping in map .Fa map , which must be unlocked. The new mapping has size .Fa size , which must be a multiple of .Dv PAGE_SIZE . The .Fa uobj and .Fa uoffset arguments can have four meanings. When .Fa uobj is .Dv NULL and .Fa uoffset is .Dv UVM_UNKNOWN_OFFSET , .Fn uvm_map does not use the machine-dependent .Dv PMAP_PREFER function. If .Fa uoffset is any other value, it is used as the hint to .Dv PMAP_PREFER . When .Fa uobj is not .Dv NULL and .Fa uoffset is .Dv UVM_UNKNOWN_OFFSET , .Fn uvm_map finds the offset based upon the virtual address, passed as .Fa startp . If .Fa uoffset is any other value, we are doing a normal mapping at this offset. The start address of the map will be returned in .Fa startp .
p .Fa align specifies alignment of mapping unless .Dv UVM_FLAG_FIXED is specified in .Fa flags . .Fa align must be a power of 2.
p .Fa flags passed to .Fn uvm_map are typically created using the .Fn UVM_MAPFLAG "vm_prot_t prot" "vm_prot_t maxprot" "vm_inherit_t inh" "int advice" "int flags" macro, which uses the following values. The .Fa prot and .Fa maxprot can take are: d -literal #define UVM_PROT_MASK 0x07 /* protection mask */ #define UVM_PROT_NONE 0x00 /* protection none */ #define UVM_PROT_ALL 0x07 /* everything */ #define UVM_PROT_READ 0x01 /* read */ #define UVM_PROT_WRITE 0x02 /* write */ #define UVM_PROT_EXEC 0x04 /* exec */ #define UVM_PROT_R 0x01 /* read */ #define UVM_PROT_W 0x02 /* write */ #define UVM_PROT_RW 0x03 /* read-write */ #define UVM_PROT_X 0x04 /* exec */ #define UVM_PROT_RX 0x05 /* read-exec */ #define UVM_PROT_WX 0x06 /* write-exec */ #define UVM_PROT_RWX 0x07 /* read-write-exec */ .Ed
p The values that .Fa inh can take are: d -literal #define UVM_INH_MASK 0x30 /* inherit mask */ #define UVM_INH_SHARE 0x00 /* "share" */ #define UVM_INH_COPY 0x10 /* "copy" */ #define UVM_INH_NONE 0x20 /* "none" */ #define UVM_INH_DONATE 0x30 /* "donate" \*[Lt]\*[Lt] not used */ .Ed
p The values that .Fa advice can take are: d -literal #define UVM_ADV_NORMAL 0x0 /* 'normal' */ #define UVM_ADV_RANDOM 0x1 /* 'random' */ #define UVM_ADV_SEQUENTIAL 0x2 /* 'sequential' */ #define UVM_ADV_MASK 0x7 /* mask */ .Ed
p The values that .Fa flags can take are: d -literal #define UVM_FLAG_FIXED 0x010000 /* find space */ #define UVM_FLAG_OVERLAY 0x020000 /* establish overlay */ #define UVM_FLAG_NOMERGE 0x040000 /* don't merge map entries */ #define UVM_FLAG_COPYONW 0x080000 /* set copy_on_write flag */ #define UVM_FLAG_AMAPPAD 0x100000 /* for bss: pad amap to reduce malloc() */ #define UVM_FLAG_TRYLOCK 0x200000 /* fail if we can not lock map */ .Ed
p The .Dv UVM_MAPFLAG macro arguments can be combined with an or operator. There are several special purpose macros for checking protection combinations, e.g., the .Dv UVM_PROT_WX macro. There are also some additional macros to extract bits from the flags. The .Dv UVM_PROTECTION , .Dv UVM_INHERIT , .Dv UVM_MAXPROTECTION and .Dv UVM_ADVICE macros return the protection, inheritance, maximum protection and advice, respectively. .Fn uvm_map returns a standard UVM return value.
p .Fn uvm_unmap removes a valid mapping, from .Fa start to .Fa end , in map .Fa map , which must be unlocked.
p .Fn uvm_map_pageable changes the pageability of the pages in the range from .Fa start to .Fa end in map .Fa map to .Fa new_pageable . .Fn uvm_map_pageable returns a standard UVM return value.
p .Fn uvm_map_checkprot checks the protection of the range from .Fa start to .Fa end in map .Fa map against .Fa protection . This returns either .Dv true or .Dv false .
p .Fn uvm_map_protect changes the protection .Fa start to .Fa end in map .Fa map to .Fa new_prot , also setting the maximum protection to the region to .Fa new_prot if .Fa set_max is true. This function returns a standard UVM return value.
p .Fn uvm_deallocate deallocates kernel memory in map .Fa map from address .Fa start to .Fa start + size .
p .Fn uvmspace_alloc allocates and returns a new address space, with ranges from .Fa min to .Fa max , setting the pageability of the address space to .Fa pageable .
p .Fn uvmspace_exec either reuses the address space of lwp .Fa l if there are no other references to it, or creates a new one with .Fn uvmspace_alloc . The range of valid addresses in the address space is reset to .Fa start through .Fa end .
p .Fn uvmspace_fork creates and returns a new address space based upon the .Fa vm1 address space, typically used when allocating an address space for a child process.
p .Fn uvmspace_free lowers the reference count on the address space .Fa vm , freeing the data structures if there are no other references.
p .Fn uvmspace_share causes process
a p2 to share the address space of .Fa p1 .
p .Fn uvmspace_unshare ensures that lwp .Fa l has its own, unshared address space, by creating a new one if necessary by calling .Fn uvmspace_fork .
p .Fn uvm_uarea_alloc allocates virtual space for a u-area (i.e., a kernel stack) and stores its virtual address in .Fa *uaddrp . The return value is .Dv true if the u-area is already backed by wired physical memory, otherwise .Dv false .
p .Fn uvm_uarea_free frees a u-area allocated with .Fn uvm_uarea_alloc , freeing both the virtual space and any physical pages which may have been allocated to back that virtual space later. .Sh SEE ALSO .Xr pmap 9 , .Xr uvm 9 , .Xr uvm_km 9 , .Xr vmem 9 .Sh HISTORY UVM and .Nm first appeared in .Nx 1.4 .