1.\" $NetBSD: uvm_km.9,v 1.5 2015/08/15 10:31:41 maxv Exp $ 2.\" 3.\" Copyright (c) 1998 Matthew R. Green 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 20.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 21.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 22.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 23.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd August 15, 2015 28.Dt UVM_KM 9 29.Os 30.Sh NAME 31.Nm uvm_km 32.Nd raw kernel memory or address space allocator 33.Sh SYNOPSIS 34.In sys/param.h 35.In uvm/uvm.h 36.Ft vaddr_t 37.Fn uvm_km_alloc "struct vm_map *map" "vsize_t size" "vsize_t align" "uvm_flag_t flags" 38.Ft void 39.Fn uvm_km_free "struct vm_map *map" "vaddr_t addr" "vsize_t size" "uvm_flag_t flags" 40.Ft struct vm_map * 41.Fn uvm_km_suballoc "struct vm_map *map" "vaddr_t *min" "vaddr_t *max" \ 42"vsize_t size" "int flags" "bool fixed" "struct vm_map *submap" 43.Sh DESCRIPTION 44The UVM facility for allocation of kernel memory or address space in pages. 45Both wired and pageable memory can be allocated by this facility, as well 46as kernel address space. 47Note that this is a raw allocator. 48For general purpose memory allocation, 49.Xr kmem 9 50interface should be used. 51.Sh FUNCTIONS 52.Fn uvm_km_alloc 53allocates a contiguous range of 54.Fa size 55bytes of kernel memory in map 56.Fa map 57and returns the virtual address of the range, or returns zero on failure. 58The first address of the allocated memory range will be aligned according to the 59.Fa align 60argument 61.Pq specify 0 if no alignment is necessary . 62The alignment must be a multiple of page size. 63The 64.Fa flags 65is a bitwise inclusive OR of the allocation type and operation flags. 66.Pp 67The allocation type should be one of: 68.Bl -tag -width UVM_KMF_PAGEABLE 69.It UVM_KMF_WIRED 70Wired memory. 71.It UVM_KMF_PAGEABLE 72Demand-paged zero-filled memory. 73.It UVM_KMF_VAONLY 74Virtual address only. 75No physical pages are mapped in the allocated region. 76If necessary, it is the caller's responsibility to enter page mappings. 77It is also the caller's responsibility to clean up the mappings before freeing 78the address range. 79.El 80.Pp 81The following operation flags are available: 82.Bl -tag -width UVM_KMF_PAGEABLE 83.It UVM_KMF_CANFAIL 84Can fail even if 85.Dv UVM_KMF_NOWAIT 86is not specified and 87.Dv UVM_KMF_WAITVA 88is specified. 89.It UVM_KMF_ZERO 90Request zero-filled memory. 91Only supported for 92.Dv UVM_KMF_WIRED . 93Should not be used with other types. 94.It UVM_KMF_EXEC 95Request memory with executable rights. 96.It UVM_KMF_TRYLOCK 97Fail if cannot lock the map without sleeping. 98.It UVM_KMF_NOWAIT 99Fail immediately if no memory is available. 100.It UVM_KMF_WAITVA 101Sleep to wait for the virtual address resources if needed. 102.El 103.Pp 104If neither 105.Dv UVM_KMF_NOWAIT 106nor 107.Dv UVM_KMF_CANFAIL 108are specified and 109.Dv UVM_KMF_WAITVA 110is specified, 111.Fn uvm_km_alloc 112will never fail, but rather sleep indefinitely until the allocation succeeds. 113.Pp 114Pageability of the pages allocated with 115.Dv UVM_KMF_PAGEABLE 116can be changed by 117.Fn uvm_map_pageable . 118In that case, the entire range must be changed atomically. 119Changing a part of the range is not supported. 120.Pp 121.Fn uvm_km_free 122frees the memory range allocated by 123.Fn uvm_km_alloc . 124.Fa addr 125must be an address returned by 126.Fn uvm_km_alloc . 127.Fa map 128and 129.Fa size 130must be the same as the ones used for the corresponding 131.Fn uvm_km_alloc . 132.Fa flags 133must be the allocation type used for the corresponding 134.Fn uvm_km_alloc . 135Note that 136.Fn uvm_km_free 137is the only way to free memory ranges allocated by 138.Fn uvm_km_alloc . 139.Fn uvm_unmap 140must not be used. 141.Pp 142.Fn uvm_km_suballoc 143allocates submap from 144.Fa map , 145creating a new map if 146.Fa submap 147is 148.Dv NULL . 149The addresses of the submap can be specified explicitly by setting the 150.Fa fixed 151argument to true, which causes the 152.Fa min 153argument to specify the beginning of the address in the submap. 154If 155.Fa fixed 156is false, any address of size 157.Fa size 158will be allocated from 159.Fa map 160and the start and end addresses returned in 161.Fa min 162and 163.Fa max . 164The 165.Fa flags 166are used to initialize the created submap. 167The following flags can be set: 168.Bl -tag -width VM_MAP_PAGEABLE 169.It VM_MAP_PAGEABLE 170Entries in the map may be paged out. 171.It VM_MAP_INTRSAFE 172Map should be interrupt-safe. 173.It VM_MAP_TOPDOWN 174A top-down mapping should be arranged. 175.El 176.Sh SEE ALSO 177.Xr kmem 9 , 178.Xr pmap 9 , 179.Xr pool_cache 9 , 180.Xr uvm 9 , 181.Xr uvm_map 9 , 182.Xr vmem 9 183.Sh HISTORY 184UVM and 185.Nm 186first appeared in 187.Nx 1.4 . 188