1.\" $OpenBSD: uvm_km_alloc.9,v 1.2 2019/12/05 15:58:27 jmc Exp $ 2.\" $NetBSD: uvm.9,v 1.14 2000/06/29 06:08:44 mrg Exp $ 3.\" 4.\" Copyright (c) 1998 Matthew R. Green 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 21.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 22.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 23.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 24.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd $Mdocdate: December 5 2019 $ 29.Dt UVM_KM_ALLOC 9 30.Os 31.Sh NAME 32.Nm uvm_km_alloc , 33.Nm uvm_km_zalloc , 34.Nm uvm_km_alloc1 , 35.Nm uvm_km_kmemalloc , 36.Nm uvm_km_valloc , 37.Nm uvm_km_valloc_wait , 38.Nm uvm_km_suballoc , 39.Nm uvm_km_free , 40.Nm uvm_km_free_wakeup 41.Nd raw kernel memory or address space allocator 42.Sh SYNOPSIS 43.In sys/param.h 44.In uvm/uvm.h 45.Ft vaddr_t 46.Fn uvm_km_alloc "vm_map_t map" "vsize_t size" 47.Ft vaddr_t 48.Fn uvm_km_zalloc "vm_map_t map" "vsize_t size" 49.Ft vaddr_t 50.Fn uvm_km_alloc1 "vm_map_t map" "vsize_t size" "vsize_t align" "boolean_t zeroit" 51.Ft vaddr_t 52.Fn uvm_km_kmemalloc "vm_map_t map" "struct uvm_object *obj" "vsize_t size" "int flags" 53.Ft vaddr_t 54.Fn uvm_km_valloc "vm_map_t map" "vsize_t size" 55.Ft vaddr_t 56.Fn uvm_km_valloc_wait "vm_map_t map" "vsize_t size" 57.Ft struct vm_map * 58.Fn uvm_km_suballoc "vm_map_t map" "vaddr_t *min" "vaddr_t *max " "vsize_t size" "int flags" "boolean_t fixed" "vm_map_t submap" 59.Ft void 60.Fn uvm_km_free "vm_map_t map" "vaddr_t addr" "vsize_t size" 61.Ft void 62.Fn uvm_km_free_wakeup "vm_map_t map" "vaddr_t addr" "vsize_t size" 63.Sh DESCRIPTION 64The 65.Fn uvm_km_alloc 66and 67.Fn uvm_km_zalloc 68functions allocate 69.Fa size 70bytes of wired kernel memory in map 71.Fa map . 72In addition to allocation, 73.Fn uvm_km_zalloc 74zeros the memory. 75Both of these functions are defined as macros in terms of 76.Fn uvm_km_alloc1 , 77and should almost always be used in preference to 78.Fn uvm_km_alloc1 . 79.Pp 80The 81.Fn uvm_km_alloc1 82function allocates and returns 83.Fa size 84bytes of wired memory in the kernel map aligned to the 85.Fa align 86boundary, zeroing the memory if the 87.Fa zeroit 88argument is non-zero. 89.Pp 90The 91.Fn uvm_km_kmemalloc 92function allocates and returns 93.Fa size 94bytes of wired kernel memory into 95.Fa obj . 96The flags can be any of: 97.Bd -literal 98#define UVM_KMF_NOWAIT 0x1 /* matches M_NOWAIT */ 99#define UVM_KMF_VALLOC 0x2 /* allocate VA only */ 100#define UVM_KMF_TRYLOCK UVM_FLAG_TRYLOCK /* try locking only */ 101.Ed 102.Pp 103The 104.Dv UVM_KMF_NOWAIT 105flag causes 106.Fn uvm_km_kmemalloc 107to return immediately if no memory is available. 108.Dv UVM_KMF_VALLOC 109causes no pages to be allocated, only a virtual address. 110.Dv UVM_KMF_TRYLOCK 111causes 112.Fn uvm_km_kmemalloc 113to only try and not sleep when locking maps. 114.Pp 115The 116.Fn uvm_km_valloc 117and 118.Fn uvm_km_valloc_wait 119functions return a newly allocated zero-filled address in the kernel map of size 120.Fa size . 121.Fn uvm_km_valloc_wait 122will also wait for kernel memory to become available, if there is a 123memory shortage. 124.Pp 125The 126.Fn uvm_km_suballoc 127function allocates submap (with the specified 128.Fa flags , 129as described above) from 130.Fa map , 131creating a new map if 132.Fa submap 133is 134.Dv NULL . 135The addresses of the submap can be specified exactly by setting the 136.Fa fixed 137argument to non-zero, which causes the 138.Fa min 139argument to specify the beginning of the address in the submap. 140If 141.Fa fixed 142is zero, any address of size 143.Fa size 144will be allocated from 145.Fa map 146and the start and end addresses returned in 147.Fa min 148and 149.Fa max . 150.Pp 151The 152.Fn uvm_km_free 153and 154.Fn uvm_km_free_wakeup 155functions free 156.Fa size 157bytes of memory in the kernel map, starting at address 158.Fa addr . 159.Fn uvm_km_free_wakeup 160calls 161.Fn wakeup 162on the map before unlocking the map. 163.Sh SEE ALSO 164.Xr km_alloc 9 165