1.\" $OpenBSD: km_alloc.9,v 1.9 2019/12/06 19:15:16 jmc Exp $ 2.\" Copyright (c) 2011 Artur Grabowski <art@openbsd.org> 3.\" All rights reserved. 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: December 6 2019 $ 18.Dt KM_ALLOC 9 19.Os 20.Sh NAME 21.Nm km_alloc , 22.Nm km_free 23.Nd kernel memory allocator 24.Sh SYNOPSIS 25.In sys/types.h 26.In uvm/uvm_extern.h 27.Ft void * 28.Fn km_alloc "size_t sz" "const struct kmem_va_mode *kv" "const struct kmem_pa_mode *kp" "const struct kmem_dyn_mode *kd" 29.Ft void 30.Fn km_free "void *v" "size_t sz" "const struct kmem_va_mode *kv" "const struct kmem_pa_mode *kp" 31.Sh DESCRIPTION 32The 33.Fn km_alloc 34function allocates kernel virtual space optionally backed by physical pages. 35The 36.Fn km_free 37function frees the space that was previously allocated by 38.Fn km_alloc . 39.Pp 40The 41.Fa sz 42argument specifies the size of the allocation and must be a multiple 43of 44.Dv PAGE_SIZE . 45The 46.Fa kv 47and 48.Fa kp 49arguments specify the type of virtual and physical memory to be allocated. 50The 51.Fa kd 52argument specifies additional options for the allocation. 53The arguments passed to 54.Fn km_free 55must match those that were used to obtain the space in 56.Fn km_alloc . 57.Pp 58Typically a user will use certain predefined modes for memory allocation. 59For virtual space the predefined modes are: 60.Pp 61.Bl -tag -width kv_intrsafe -offset 3n -compact 62.It kv_any 63Allocates the virtual space anywhere. 64.It kv_intrsafe 65Allocates the virtual space in the interrupt safe map. 66.It kv_page 67Allocates single pages. 68.El 69.Pp 70For physical pages the predefined modes are: 71.Pp 72.Bl -tag -width kp_pageable -offset 3n -compact 73.It kp_dirty 74Maps dirty pages into the allocation. 75.It kp_zero 76Maps zeroed pages into the allocation. 77.It kp_dma 78Maps dma-accessible pages into the allocation. 79.It kp_dma_zero 80Maps zeroed dma-accessible pages into the allocation. 81.It kp_pageable 82Pages will be demand paged. 83.It kp_none 84Leaves the allocation unmapped. 85.El 86.Pp 87The other parameters for allocation are: 88.Pp 89.Bl -tag -width kd_trylock -offset 3n -compact 90.It kd_waitok 91Sleeping for physical pages is allowed. 92.It kd_nowait 93Sleeping is not allowed. 94.It kd_trylock 95Fail if the allocator cannot obtain locks without waiting. 96.El 97.Pp 98In case the predefined allocation modes are not sufficient, a custom allocation 99mode can be created. 100The structure controlling the virtual space allocation is: 101.Bd -literal 102struct kmem_va_mode { 103 struct vm_map **kv_map; 104 vsize_t kv_align; 105 int kv_wait; 106 int kv_singlepage; 107}; 108.Ed 109.Bl -tag -width kv_singlepage 110.It kv_map 111A pointer to the pointer to the uvm_map the space will be allocated from. 112.It kv_align 113Alignment constraint of the allocated space. 114.It kv_wait 115A flag indicating whether the allocator should wait for space to be freed if 116the allocation cannot be satisfied. 117.It kv_singlepage 118A flag indicating if the allocations will always be for single pages. 119.El 120.Bd -literal 121struct kmem_pa_mode { 122 struct uvm_constraint_range *kp_constraint; 123 struct uvm_object **kp_object; 124 paddr_t kp_align; 125 paddr_t kp_boundary; 126 int kp_nomem; 127 int kp_maxseg; 128 int kp_zero; 129 int kp_pageable; 130}; 131.Ed 132.Bl -tag -width kp_constraint 133.It kp_constraint 134A pointer to physical allocation constraints. 135.It kp_object 136A pointer to a pointer to a uvm_object if the pages should be backed by a 137kernel object. 138.It kp_align 139Physical alignment of the first page in the allocation. 140.It kp_boundary 141Boundary that the physical addresses can't cross if the allocation is 142contiguous. 143.It kp_nomem 144A flag that specifies that the allocation should not be backed by physical 145pages. 146.It kp_maxseg 147Maximal amount of contiguous physical segments in the allocation. 148.It kp_zero 149A flag that specifies if the returned memory should be zeroed. 150.It kp_pageable 151A flag that specifies if the returned memory should be demand paged from the 152backing object instead of being allocated up front. 153.El 154.Bd -literal 155struct kmem_dyn_mode { 156 int kd_waitok; 157 int kd_trylock; 158 voff_t kd_prefer; 159 int *kd_slowdown; 160}; 161.Ed 162.Bl -tag -width kd_slowdown 163.It kd_waitok 164A flag that specifies if the allocator may sleep waiting for memory. 165.It kd_trylock 166A flag that specifies if the allocator should fail if it can't immediately 167obtain a lock. 168.It kd_prefer 169An offset given to PMAP_PREFER to virtually align the allocated space. 170.It kd_slowdown 171A pointer to an integer that will be set to 1 if the internal single page 172allocator needs the caller to back off to allow the allocator to catch up. 173.El 174.Sh RETURN VALUES 175.Fn km_alloc 176returns a kernel virtual address or 177.Dv NULL 178if the allocation cannot be satisfied. 179.Sh SEE ALSO 180.Xr malloc 9 , 181.Xr uvm_init 9 182