.\"	$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 .