Documentation for km_alloc and km_free

2 files changed, 185 insertions, 2 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index de771d0b6ff..10a8c1ad7ca 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.163 2011/03/08 00:13:41 bluhm Exp $
+#	$OpenBSD: Makefile,v 1.164 2011/04/04 11:26:51 art Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -15,7 +15,8 @@ MAN=	altq.9 aml_evalnode.9 atomic.9 audio.9 autoconf.9 bio_register.9 \
 	ieee80211_node.9 ieee80211_output.9 ieee80211_proto.9 \
 	ieee80211_radiotap.9 \
 	iic.9 intro.9 inittodr.9 \
-	kern.9 knote.9 kthread.9 ktrace.9 loadfirmware.9 lock.9 log.9 \
+	kern.9 km_alloc.9 knote.9 kthread.9 ktrace.9 \
+	loadfirmware.9 lock.9 log.9 \
 	malloc.9 mbuf.9 mbuf_tags.9 md5.9 mi_switch.9 microtime.9 \
 	mountroothook_establish.9 mutex.9 namei.9 \
 	panic.9 pci_conf_read.9 pci_intr_map.9 pfind.9 physio.9 pmap.9 \
@@ -184,6 +185,7 @@ MLINKS+=kern.9 imax.9 kern.9 imin.9 kern.9 lmax.9 kern.9 lmin.9 \
 	kern.9 strlen.9 kern.9 strncpy.9 kern.9 strlcpy.9 kern.9 strlcat.9 \
 	kern.9 strcmp.9 kern.9 strncmp.9 kern.9 strncasecmp.9 \
 	kern.9 timingsafe_bcmp.9 kern.9 getsn.9
+MLINKS+=km_alloc.9 km_free.9
 MLINKS+=knote.9 KNOTE.9
 MLINKS+=kthread.9 kthread_create.9 kthread.9 kthread_exit.9 \
 	kthread.9 kthread_create_deferred.9
diff --git a/share/man/man9/km_alloc.9 b/share/man/man9/km_alloc.9
new file mode 100644
index 00000000000..f43824825c8
--- /dev/null
+++ b/share/man/man9/km_alloc.9
@@ -0,0 +1,181 @@
+.\"	$OpenBSD: km_alloc.9,v 1.1 2011/04/04 11:26:51 art 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: April 4 2011 $
+.Dt KM_ALLOC 9
+.Os
+.Sh NAME
+.Nm km_alloc ,
+.Nm km_free
+.Nd kernel memory allocator
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/uvm_extern.h>
+.Ft void *
+.Fn km_alloc "size_t size" "struct kmem_va_mode *kv" "struct kmem_pa_mode *kp" "struct kmem_dyn_mode *kd"
+.Ft void
+.Fn km_free "void *v" "size_t size" "struct kmem_va_mode *kv" "struct kmem_pa_mode *pa"
+.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 size
+argument specifies the size of the allocation and must be a multiple
+of
+.Dv PAGE_SIZE .
+The
+.Fa kv
+and
+.Fa kp
+arguments specifies 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:
+.Bl -tag -width kv_intrsafe
+.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:
+.Bl -tag -width kp_pageable
+.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:
+.Bl -tag -width kd_trylock
+.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 alloction is:
+.Bd -literal
+struct kmem_va_mode {
+	struct vm_map **kv_map;
+	vsize_t kv_align;
+	int kv_wait;
+	int kv_singlepage;
+	int kv_executable;
+};
+.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.
+.It kv_executable
+A falg indicating if the memory mapped should be mapped permitting execution.
+.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 satisifed.
+.Sh SEE ALSO
+.Xr malloc 9 ,
+.Xr uvm 9