.\"	$NetBSD: uvm_km.9,v 1.5 2015/08/15 10:31:41 maxv 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 August 15, 2015
.Dt UVM_KM 9
.Os
.Sh NAME
.Nm uvm_km
.Nd raw kernel memory or address space allocator
.Sh SYNOPSIS
.In sys/param.h
.In uvm/uvm.h
.Ft vaddr_t
.Fn uvm_km_alloc "struct vm_map *map" "vsize_t size" "vsize_t align" "uvm_flag_t flags"
.Ft void
.Fn uvm_km_free "struct vm_map *map" "vaddr_t addr" "vsize_t size" "uvm_flag_t flags"
.Ft struct vm_map *
.Fn uvm_km_suballoc "struct vm_map *map" "vaddr_t *min" "vaddr_t *max" \
"vsize_t size" "int flags" "bool fixed" "struct vm_map *submap"
.Sh DESCRIPTION
The UVM facility for allocation of kernel memory or address space in pages.
Both wired and pageable memory can be allocated by this facility, as well
as kernel address space.
Note that this is a raw allocator.
For general purpose memory allocation,
.Xr kmem 9
interface should be used.
.Sh FUNCTIONS
.Fn uvm_km_alloc
allocates a contiguous range of
.Fa size
bytes of kernel memory in map
.Fa map
and returns the virtual address of the range, or returns zero on failure.
The first address of the allocated memory range will be aligned according to the
.Fa align
argument
.Pq specify 0 if no alignment is necessary .
The alignment must be a multiple of page size.
The
.Fa flags
is a bitwise inclusive OR of the allocation type and operation flags.
.Pp
The allocation type should be one of:
.Bl -tag -width UVM_KMF_PAGEABLE
.It UVM_KMF_WIRED
Wired memory.
.It UVM_KMF_PAGEABLE
Demand-paged zero-filled memory.
.It UVM_KMF_VAONLY
Virtual address only.
No physical pages are mapped in the allocated region.
If necessary, it is the caller's responsibility to enter page mappings.
It is also the caller's responsibility to clean up the mappings before freeing
the address range.
.El
.Pp
The following operation flags are available:
.Bl -tag -width UVM_KMF_PAGEABLE
.It UVM_KMF_CANFAIL
Can fail even if
.Dv UVM_KMF_NOWAIT
is not specified and
.Dv UVM_KMF_WAITVA
is specified.
.It UVM_KMF_ZERO
Request zero-filled memory.
Only supported for
.Dv UVM_KMF_WIRED .
Should not be used with other types.
.It UVM_KMF_EXEC
Request memory with executable rights.
.It UVM_KMF_TRYLOCK
Fail if cannot lock the map without sleeping.
.It UVM_KMF_NOWAIT
Fail immediately if no memory is available.
.It UVM_KMF_WAITVA
Sleep to wait for the virtual address resources if needed.
.El
.Pp
If neither
.Dv UVM_KMF_NOWAIT
nor
.Dv UVM_KMF_CANFAIL
are specified and
.Dv UVM_KMF_WAITVA
is specified,
.Fn uvm_km_alloc
will never fail, but rather sleep indefinitely until the allocation succeeds.
.Pp
Pageability of the pages allocated with
.Dv UVM_KMF_PAGEABLE
can be changed by
.Fn uvm_map_pageable .
In that case, the entire range must be changed atomically.
Changing a part of the range is not supported.
.Pp
.Fn uvm_km_free
frees the memory range allocated by
.Fn uvm_km_alloc .
.Fa addr
must be an address returned by
.Fn uvm_km_alloc .
.Fa map
and
.Fa size
must be the same as the ones used for the corresponding
.Fn uvm_km_alloc .
.Fa flags
must be the allocation type used for the corresponding
.Fn uvm_km_alloc .
Note that
.Fn uvm_km_free
is the only way to free memory ranges allocated by
.Fn uvm_km_alloc .
.Fn uvm_unmap
must not be used.
.Pp
.Fn uvm_km_suballoc
allocates submap from
.Fa map ,
creating a new map if
.Fa submap
is
.Dv NULL .
The addresses of the submap can be specified explicitly by setting the
.Fa fixed
argument to true, which causes the
.Fa min
argument to specify the beginning of the address in the submap.
If
.Fa fixed
is false, any address of size
.Fa size
will be allocated from
.Fa map
and the start and end addresses returned in
.Fa min
and
.Fa max .
The
.Fa flags
are used to initialize the created submap.
The following flags can be set:
.Bl -tag -width VM_MAP_PAGEABLE
.It VM_MAP_PAGEABLE
Entries in the map may be paged out.
.It VM_MAP_INTRSAFE
Map should be interrupt-safe.
.It VM_MAP_TOPDOWN
A top-down mapping should be arranged.
.El
.Sh SEE ALSO
.Xr kmem 9 ,
.Xr pmap 9 ,
.Xr pool_cache 9 ,
.Xr uvm 9 ,
.Xr uvm_map 9 ,
.Xr vmem 9
.Sh HISTORY
UVM and
.Nm
first appeared in
.Nx 1.4 .