Module Name: src
Committed By: christos
Date: Fri Dec 11 04:11:23 UTC 2015
Modified Files:
src/share/man/man9: kmem.9
Log Message:
Spell out that KM_SLEEP allocations can fail.
To generate a diff of this commit:
cvs rdiff -u -r1.17 -r1.18 src/share/man/man9/kmem.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man9/kmem.9
diff -u src/share/man/man9/kmem.9:1.17 src/share/man/man9/kmem.9:1.18
--- src/share/man/man9/kmem.9:1.17 Tue Jul 28 05:52:43 2015
+++ src/share/man/man9/kmem.9 Thu Dec 10 23:11:23 2015
@@ -1,4 +1,4 @@
-.\" $NetBSD: kmem.9,v 1.17 2015/07/28 09:52:43 wiz Exp $
+.\" $NetBSD: kmem.9,v 1.18 2015/12/11 04:11:23 christos Exp $
.\"
.\" Copyright (c)2006 YAMAMOTO Takashi,
.\" All rights reserved.
@@ -25,7 +25,7 @@
.\" SUCH DAMAGE.
.\"
.\" ------------------------------------------------------------
-.Dd July 28, 2015
+.Dd December 10, 2015
.Dt KMEM 9
.Os
.\" ------------------------------------------------------------
@@ -77,6 +77,15 @@ Either of the following:
.It Dv KM_SLEEP
If the allocation cannot be satisfied immediately, sleep until enough
memory is available.
+Note that this does not mean that if
+.Dv KM_SLEEP
+is specified, then the allocation cannot fail.
+Under resource stress conditions, the allocation can fail and the
+function will return
+.Dv NULL .
+One such scenario is when the allocation size is larger than it can ever
+be allocated; another is when the system memory resources are exhausted
+to even allocate pools of pages.
.It Dv KM_NOSLEEP
Don't sleep.
Immediately return
@@ -134,6 +143,9 @@ It must be the one returned by
.Fn kmem_alloc
or
.Fn kmem_zalloc .
+One such scenario is when the allocation size is larger than it can ever
+be allocated; another is when the system memory resources are exhausted
+to even allocate pools of pages.
.It Fa size
The size of the memory being freed, in bytes.
It must be the same as the
@@ -173,6 +185,10 @@ It should be noted that
.Fn kmem_free
may also block.
.Pp
+Always check the return value of the allocators, even when
+.Dv KM_SLEEP
+is specified to avoid kernel crashes during resource stress conditions.
+.Pp
For some locks this is permissible or even unavoidable.
For others, particularly locks that may be taken from soft interrupt context,
it is a serious problem.
