1.\" $NetBSD: uvm_km.9,v 1.3 2014/05/14 16:16:55 riastradh 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 June 3, 2011 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 54.Fa size 55bytes of kernel memory in map 56.Fa map . 57The first address of the allocated memory range will be aligned according to the 58.Fa align 59argument 60.Pq specify 0 if no alignment is necessary . 61The alignment must be a multiple of page size. 62The 63.Fa flags 64is a bitwise inclusive OR of the allocation type and operation flags. 65.Pp 66The allocation type should be one of: 67.Bl -tag -width UVM_KMF_PAGEABLE 68.It UVM_KMF_WIRED 69Wired memory. 70.It UVM_KMF_PAGEABLE 71Demand-paged zero-filled memory. 72.It UVM_KMF_VAONLY 73Virtual address only. 74No physical pages are mapped in the allocated region. 75If necessary, it is the caller's responsibility to enter page mappings. 76It is also the caller's responsibility to clean up the mappings before freeing 77the address range. 78.El 79.Pp 80The following operation flags are available: 81.Bl -tag -width UVM_KMF_PAGEABLE 82.It UVM_KMF_CANFAIL 83Can fail even if 84.Dv UVM_KMF_NOWAIT 85is not specified and 86.Dv UVM_KMF_WAITVA 87is specified. 88.It UVM_KMF_ZERO 89Request zero-filled memory. 90Only supported for 91.Dv UVM_KMF_WIRED . 92Should not be used with other types. 93.It UVM_KMF_TRYLOCK 94Fail if cannot lock the map without sleeping. 95.It UVM_KMF_NOWAIT 96Fail immediately if no memory is available. 97.It UVM_KMF_WAITVA 98Sleep to wait for the virtual address resources if needed. 99.El 100.Pp 101If neither 102.Dv UVM_KMF_NOWAIT 103nor 104.Dv UVM_KMF_CANFAIL 105are specified and 106.Dv UVM_KMF_WAITVA 107is specified, 108.Fn uvm_km_alloc 109will never fail, but rather sleep indefinitely until the allocation succeeds. 110.Pp 111Pageability of the pages allocated with 112.Dv UVM_KMF_PAGEABLE 113can be changed by 114.Fn uvm_map_pageable . 115In that case, the entire range must be changed atomically. 116Changing a part of the range is not supported. 117.Pp 118.Fn uvm_km_free 119frees the memory range allocated by 120.Fn uvm_km_alloc . 121.Fa addr 122must be an address returned by 123.Fn uvm_km_alloc . 124.Fa map 125and 126.Fa size 127must be the same as the ones used for the corresponding 128.Fn uvm_km_alloc . 129.Fa flags 130must be the allocation type used for the corresponding 131.Fn uvm_km_alloc . 132Note that 133.Fn uvm_km_free 134is the only way to free memory ranges allocated by 135.Fn uvm_km_alloc . 136.Fn uvm_unmap 137must not be used. 138.Pp 139.Fn uvm_km_suballoc 140allocates submap from 141.Fa map , 142creating a new map if 143.Fa submap 144is 145.Dv NULL . 146The addresses of the submap can be specified explicitly by setting the 147.Fa fixed 148argument to true, which causes the 149.Fa min 150argument to specify the beginning of the address in the submap. 151If 152.Fa fixed 153is false, any address of size 154.Fa size 155will be allocated from 156.Fa map 157and the start and end addresses returned in 158.Fa min 159and 160.Fa max . 161The 162.Fa flags 163are used to initialize the created submap. 164The following flags can be set: 165.Bl -tag -width VM_MAP_PAGEABLE 166.It VM_MAP_PAGEABLE 167Entries in the map may be paged out. 168.It VM_MAP_INTRSAFE 169Map should be interrupt-safe. 170.It VM_MAP_TOPDOWN 171A top-down mapping should be arranged. 172.El 173.Sh SEE ALSO 174.Xr kmem 9 , 175.Xr pmap 9 , 176.Xr pool_cache 9 , 177.Xr uvm 9 , 178.Xr uvm_map 9 , 179.Xr vmem 9 180.Sh HISTORY 181UVM and 182.Nm 183first appeared in 184.Nx 1.4 . 185