diff options
Diffstat (limited to 'static/openbsd/man9/km_alloc.9')
| -rw-r--r-- | static/openbsd/man9/km_alloc.9 | 181 |
1 files changed, 181 insertions, 0 deletions
diff --git a/static/openbsd/man9/km_alloc.9 b/static/openbsd/man9/km_alloc.9 new file mode 100644 index 00000000..2feb82cd --- /dev/null +++ b/static/openbsd/man9/km_alloc.9 @@ -0,0 +1,181 @@ +.\" $OpenBSD: km_alloc.9,v 1.9 2019/12/06 19:15:16 jmc Exp $ +.\" Copyright (c) 2011 Artur Grabowski <art@openbsd.org> +.\" All rights reserved. +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: December 6 2019 $ +.Dt KM_ALLOC 9 +.Os +.Sh NAME +.Nm km_alloc , +.Nm km_free +.Nd kernel memory allocator +.Sh SYNOPSIS +.In sys/types.h +.In uvm/uvm_extern.h +.Ft void * +.Fn km_alloc "size_t sz" "const struct kmem_va_mode *kv" "const struct kmem_pa_mode *kp" "const struct kmem_dyn_mode *kd" +.Ft void +.Fn km_free "void *v" "size_t sz" "const struct kmem_va_mode *kv" "const struct kmem_pa_mode *kp" +.Sh DESCRIPTION +The +.Fn km_alloc +function allocates kernel virtual space optionally backed by physical pages. +The +.Fn km_free +function frees the space that was previously allocated by +.Fn km_alloc . +.Pp +The +.Fa sz +argument specifies the size of the allocation and must be a multiple +of +.Dv PAGE_SIZE . +The +.Fa kv +and +.Fa kp +arguments specify the type of virtual and physical memory to be allocated. +The +.Fa kd +argument specifies additional options for the allocation. +The arguments passed to +.Fn km_free +must match those that were used to obtain the space in +.Fn km_alloc . +.Pp +Typically a user will use certain predefined modes for memory allocation. +For virtual space the predefined modes are: +.Pp +.Bl -tag -width kv_intrsafe -offset 3n -compact +.It kv_any +Allocates the virtual space anywhere. +.It kv_intrsafe +Allocates the virtual space in the interrupt safe map. +.It kv_page +Allocates single pages. +.El +.Pp +For physical pages the predefined modes are: +.Pp +.Bl -tag -width kp_pageable -offset 3n -compact +.It kp_dirty +Maps dirty pages into the allocation. +.It kp_zero +Maps zeroed pages into the allocation. +.It kp_dma +Maps dma-accessible pages into the allocation. +.It kp_dma_zero +Maps zeroed dma-accessible pages into the allocation. +.It kp_pageable +Pages will be demand paged. +.It kp_none +Leaves the allocation unmapped. +.El +.Pp +The other parameters for allocation are: +.Pp +.Bl -tag -width kd_trylock -offset 3n -compact +.It kd_waitok +Sleeping for physical pages is allowed. +.It kd_nowait +Sleeping is not allowed. +.It kd_trylock +Fail if the allocator cannot obtain locks without waiting. +.El +.Pp +In case the predefined allocation modes are not sufficient, a custom allocation +mode can be created. +The structure controlling the virtual space allocation is: +.Bd -literal +struct kmem_va_mode { + struct vm_map **kv_map; + vsize_t kv_align; + int kv_wait; + int kv_singlepage; +}; +.Ed +.Bl -tag -width kv_singlepage +.It kv_map +A pointer to the pointer to the uvm_map the space will be allocated from. +.It kv_align +Alignment constraint of the allocated space. +.It kv_wait +A flag indicating whether the allocator should wait for space to be freed if +the allocation cannot be satisfied. +.It kv_singlepage +A flag indicating if the allocations will always be for single pages. +.El +.Bd -literal +struct kmem_pa_mode { + struct uvm_constraint_range *kp_constraint; + struct uvm_object **kp_object; + paddr_t kp_align; + paddr_t kp_boundary; + int kp_nomem; + int kp_maxseg; + int kp_zero; + int kp_pageable; +}; +.Ed +.Bl -tag -width kp_constraint +.It kp_constraint +A pointer to physical allocation constraints. +.It kp_object +A pointer to a pointer to a uvm_object if the pages should be backed by a +kernel object. +.It kp_align +Physical alignment of the first page in the allocation. +.It kp_boundary +Boundary that the physical addresses can't cross if the allocation is +contiguous. +.It kp_nomem +A flag that specifies that the allocation should not be backed by physical +pages. +.It kp_maxseg +Maximal amount of contiguous physical segments in the allocation. +.It kp_zero +A flag that specifies if the returned memory should be zeroed. +.It kp_pageable +A flag that specifies if the returned memory should be demand paged from the +backing object instead of being allocated up front. +.El +.Bd -literal +struct kmem_dyn_mode { + int kd_waitok; + int kd_trylock; + voff_t kd_prefer; + int *kd_slowdown; +}; +.Ed +.Bl -tag -width kd_slowdown +.It kd_waitok +A flag that specifies if the allocator may sleep waiting for memory. +.It kd_trylock +A flag that specifies if the allocator should fail if it can't immediately +obtain a lock. +.It kd_prefer +An offset given to PMAP_PREFER to virtually align the allocated space. +.It kd_slowdown +A pointer to an integer that will be set to 1 if the internal single page +allocator needs the caller to back off to allow the allocator to catch up. +.El +.Sh RETURN VALUES +.Fn km_alloc +returns a kernel virtual address or +.Dv NULL +if the allocation cannot be satisfied. +.Sh SEE ALSO +.Xr malloc 9 , +.Xr uvm_init 9 |