1.\" $OpenBSD: km_alloc.9,v 1.5 2013/06/04 19:27:08 schwarze 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: June 4 2013 $ 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 size" "struct kmem_va_mode *kv" "struct kmem_pa_mode *kp" "struct kmem_dyn_mode *kd" 29.Ft void 30.Fn km_free "void *v" "size_t size" "struct kmem_va_mode *kv" "struct kmem_pa_mode *pa" 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 size 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 alloction 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 int kv_executable; 108}; 109.Ed 110.Bl -tag -width kv_singlepage 111.It kv_map 112A pointer to the pointer to the uvm_map the space will be allocated from. 113.It kv_align 114Alignment constraint of the allocated space. 115.It kv_wait 116A flag indicating whether the allocator should wait for space to be freed if 117the allocation cannot be satisfied. 118.It kv_singlepage 119A flag indicating if the allocations will always be for single pages. 120.It kv_executable 121A flag indicating if the memory mapped should be mapped permitting execution. 122.El 123.Bd -literal 124struct kmem_pa_mode { 125 struct uvm_constraint_range *kp_constraint; 126 struct uvm_object **kp_object; 127 paddr_t kp_align; 128 paddr_t kp_boundary; 129 int kp_nomem; 130 int kp_maxseg; 131 int kp_zero; 132 int kp_pageable; 133}; 134.Ed 135.Bl -tag -width kp_constraint 136.It kp_constraint 137A pointer to physical allocation constraints. 138.It kp_object 139A pointer to a pointer to a uvm_object if the pages should be backed by a 140kernel object. 141.It kp_align 142Physical alignment of the first page in the allocation. 143.It kp_boundary 144Boundary that the physical addresses can't cross if the allocation is 145contiguous. 146.It kp_nomem 147A flag that specifies that the allocation should not be backed by physical 148pages. 149.It kp_maxseg 150Maximal amount of contiguous physical segments in the allocation. 151.It kp_zero 152A flag that specifies if the returned memory should be zeroed. 153.It kp_pageable 154A flag that specifies if the returned memory should be demand paged from the 155backing object instead of being allocated up front. 156.El 157.Bd -literal 158struct kmem_dyn_mode { 159 int kd_waitok; 160 int kd_trylock; 161 voff_t kd_prefer; 162 int *kd_slowdown; 163}; 164.Ed 165.Bl -tag -width kd_slowdown 166.It kd_waitok 167A flag that specifies if the allocator may sleep waiting for memory. 168.It kd_trylock 169A flag that specifies if the allocator should fail if it can't immediately 170obtain a lock. 171.It kd_prefer 172An offset given to PMAP_PREFER to virtually align the allocated space. 173.It kd_slowdown 174A pointer to an integer that will be set to 1 if the internal single page 175allocator needs the caller to back off to allow the allocator to catch up. 176.El 177.Sh RETURN VALUES 178.Fn km_alloc 179returns a kernel virtual address or 180.Dv NULL 181if the allocation cannot be satisifed. 182.Sh SEE ALSO 183.Xr malloc 9 , 184.Xr uvm 9 185