diff options
Diffstat (limited to 'static/netbsd/man9/uvm_map.9')
| -rw-r--r-- | static/netbsd/man9/uvm_map.9 | 406 |
1 files changed, 406 insertions, 0 deletions
diff --git a/static/netbsd/man9/uvm_map.9 b/static/netbsd/man9/uvm_map.9 new file mode 100644 index 00000000..11126a1e --- /dev/null +++ b/static/netbsd/man9/uvm_map.9 @@ -0,0 +1,406 @@ +.\" $NetBSD: uvm_map.9,v 1.12 2020/08/27 14:14:00 fcambus Exp $ +.\" +.\" 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 May 20, 2017 +.Dt UVM_MAP 9 +.Os +.Sh NAME +.Nm uvm_map +.Nd +virtual address space management interface +.Sh SYNOPSIS +.In sys/param.h +.In 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_map_protect_user "struct lwp *l" "vaddr_t start" "vaddr_t end" \ +"vm_prot_t new_prot" +.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" +.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 *vm" +.Ft void +.Fn uvmspace_share "struct proc *p1" "struct proc *p2" +.\" .Ft void +.\" .Fn uvmspace_unshare "struct lwp *l" +.Ft vaddr_t +.Fn uvm_uarea_alloc "void" +.Ft void +.Fn uvm_uarea_free "vaddr_t uaddr" +.Ft vaddr_t +.Fn uvm_uarea_system_alloc "void" +.Ft void +.Fn uvm_uarea_system_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 . +.Pp +The +.Fa uobj +and +.Fa uoffset +arguments can have four meanings: +.Bl -bullet -offset abcd -compact +.It +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. +.It +When +.Fa uobj +is +.Dv NULL +and +.Fa uoffset +is any other value, it is used as the hint to +.Dv PMAP_PREFER . +.It +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 . +.It +When +.Fa uobj +is not +.Dv NULL +and +.Fa uoffset +is any other value, then a regular mapping is performed at this offset. +The start address of the map will be returned in +.Fa startp . +.El +If +.Fa uobj +is supplied, then +.Fn uvm_map +.Em consumes +the caller's reference to +.Fa uobj +on success; +.Fn uvm_unmap +will release it when removing this mapping. +On failure, +.Fn uvm_map +leaves the reference count of +.Fa uobj +unmodified. +.Pp +.Fa align +specifies alignment of mapping unless +.Dv UVM_FLAG_FIXED +is specified in +.Fa flags . +.Fa align +must be a power of 2. +.Pp +.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. +.Pp +The values that +.Fa prot +and +.Fa maxprot +can take are: +.Bl -tag -offset abcd -compact -width UVM_ADV_SEQUENTIAL +.It UVM_PROT_NONE +No protection bits. +.It UVM_PROT_R +Read. +.It UVM_PROT_W +Write. +.It UVM_PROT_X +Exec. +.It UVM_PROT_MASK +Mask to extraction the protection bits. +.El +Additionally, the following constants for ORed values are available: +.Dv UVM_PROT_RW , +.Dv UVM_PROT_RX , +.Dv UVM_PROT_WX +and +.Dv UVM_PROT_RWX . +.Pp +The values that +.Fa inh +can take are: +.Bl -tag -offset abcd -compact -width UVM_ADV_SEQUENTIAL +.It UVM_INH_SHARE +Share the map. +.It UVM_INH_COPY +Copy the map. +.It UVM_INH_NONE +No inheritance. +.It UVM_INH_MASK +Mask to extract inherit flags. +.El +.Pp +The values that +.Fa advice +can take are: +.Bl -tag -offset abcd -compact -width UVM_ADV_SEQUENTIAL +.It UVM_ADV_NORMAL +"Normal" use. +.It UVM_ADV_RANDOM +"Random" access likelihood. +.It UVM_ADV_SEQUENTIAL +"Sequential" access likelihood. +.It UVM_ADV_MASK +Mask to extract the advice flags. +.El +.Pp +The values that +.Fa flags +can take are: +.Bl -tag -offset abcd -compact -width UVM_ADV_SEQUENTIAL +.It UVM_FLAG_FIXED +Attempt to map on the address specified by +.Fa startp . +Otherwise, it is used just as a hint. +.It UVM_FLAG_OVERLAY +Establish overlay. +.It UVM_FLAG_NOMERGE +Do not merge map entries, if such merge is possible. +.It UVM_FLAG_COPYONW +Use copy-on-write i.e. do not fault in the pages immediately. +.It UVM_FLAG_AMAPPAD +Used for BSS: allocate larger amap, if extending is likely. +.It UVM_FLAG_TRYLOCK +Fail if cannot acquire the lock immediately. +.It UVM_FLAG_NOWAIT +Not allowed to sleep. +Fail, in such case. +.It UVM_FLAG_QUANTUM +Indicates that map entry cannot be split once mapped. +.It UVM_FLAG_WAITVA +Sleep until VA space is available, if it is not. +.It UVM_FLAG_VAONLY +Unmap only VA space. +Used by +.Fn uvm_unmap . +.It UVM_FLAG_UNMAP +Any existing entries in the range for this mapping should be +unmapped as part of creating the new mapping. +Use of this flag without also specifying +.Dv UVM_FLAG_FIXED +is a bug. +.El +.Pp +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 . +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 zero on success or error number otherwise. +.Pp +.Fn uvm_unmap +removes a valid mapping, +from +.Fa start +to +.Fa end , +in map +.Fa map , +which must be unlocked. +.Pp +.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 zero on success or error number otherwise. +.Pp +.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 . +.Pp +.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. +.Pp +.Fn uvm_map_protect_user +verifies that the new permissions honor PAX restrictions if applicable +and forwards to +.Fn uvm_map_protect +on passing. +.Pp +.Fn uvm_deallocate +deallocates kernel memory in map +.Fa map +from address +.Fa start +to +.Fa start + size . +.Pp +.Fn uvmspace_alloc +allocates and returns a new address space, with ranges from +.Fa min +to +.Fa max . +.Pp +.Fn uvmspace_exec +either reuses the address space of thread +.Fa l +(its process) 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 . +.Pp +.Fn uvmspace_fork +creates and returns a new address space based upon the +.Fa vm +address space, typically used when allocating an address space for a +child process. +.Pp +.Fn uvmspace_free +lowers the reference count on the address space +.Fa vm , +freeing the data structures if there are no other references. +.Pp +.Fn uvmspace_share +causes process +.Pa p2 +to share the address space of +.Fa p1 . +.\" .Pp +.\" .Fn uvmspace_unshare +.\" ensures that thread +.\" .Fa l +.\" has its own, unshared address space, by creating a new one if +.\" necessary by calling +.\" .Fn uvmspace_fork . +.Pp +.Fn uvm_uarea_alloc +allocates memory for a u-area (i.e. kernel stack, PCB, etc) and returns +the address. +.Pp +.Fn uvm_uarea_free +frees a u-area allocated with +.Fn uvm_uarea_alloc . +.Pp +.Fn uvm_uarea_system_alloc +and +.Fn uvm_uarea_system_free +are optimized routines, which are used for kernel threads. +.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 . |