407 lines
9.0 KiB
Groff
407 lines
9.0 KiB
Groff
.\" $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 .
|