[src/trunk]: src/share/man/man9 vmem(9): Clarify possible failure modes.

[riastradh <riastradh%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/c87a0522a349
branches:  trunk
changeset: 371867:c87a0522a349
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Sat Oct 15 14:54:21 2022 +0000

description:
vmem(9): Clarify possible failure modes.

Note that vmem_alloc and vmem_xalloc have failure modes -- failing
with ENOMEM despite VM_SLEEP, or importing or sleeping forever --
that appear to be bugs when align/phase/nocross/minaddr/maxaddr are
specified.

diffstat:

 share/man/man9/vmem.9 |  75 +++++++++++++++++++++++++++++++++++++++++++-------
 1 files changed, 64 insertions(+), 11 deletions(-)

diffs (95 lines):

diff -r 986a4d2a81af -r c87a0522a349 share/man/man9/vmem.9
--- a/share/man/man9/vmem.9     Sat Oct 15 14:03:16 2022 +0000
+++ b/share/man/man9/vmem.9     Sat Oct 15 14:54:21 2022 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: vmem.9,v 1.20 2020/06/16 01:29:00 thorpej Exp $
+.\"    $NetBSD: vmem.9,v 1.21 2022/10/15 14:54:21 riastradh Exp $
 .\"
 .\" Copyright (c)2006 YAMAMOTO Takashi,
 .\" All rights reserved.
@@ -500,18 +500,45 @@
 .\" ------------------------------------------------------------
 .Sh RETURN VALUES
 .Fn vmem_create
-return a pointer to the newly allocated vmem_t.
-Otherwise, it returns
-.Dv NULL .
+and
+.Fn vmem_xcreate
+return a pointer to the newly allocated vmem_t on success, or
+.Dv NULL
+if
+.Dv VM_NOSLEEP
+was specified and memory could not be allocated immediately.
 .Pp
-On success,
+.Fn vmem_add
+returns 0 on success, or
+.Er ENOMEM
+if
+.Dv VM_NOSLEEP
+was specified and memory could not be allocated immediately to record
+the region.
+.Pp
+.Fn vmem_alloc
+and
 .Fn vmem_xalloc
-and
-.Fn vmem_alloc
-return 0.
-Otherwise,
-.Dv ENOMEM
-is returned.
+return 0 on success, or
+.Er ENOMEM
+if either:
+.Bl -dash
+.It
+.Dv VM_NOSLEEP
+was specified and a matching region could not be allocated immediately;
+or
+.It
+non-default
+.Fa align ,
+.Fa phase ,
+or
+.Fa nocross
+parameters were specified, and a matching region could not be allocated
+without calling the backing
+.Fa allocfn
+passed to
+.Fn vmem_create .
+.El
 .\" ------------------------------------------------------------
 .Sh CODE REFERENCES
 The
@@ -546,3 +573,29 @@
 .Xr RUN_ONCE 9 ,
 so it cannot be used as early during system bootstrap as
 .Xr extent 9 .
+.Pp
+.Nm
+has no way to pass
+.Fa align ,
+.Fa phase ,
+.Fa nocross ,
+.Fa minaddr ,
+or
+.Fa maxaddr
+constraints into the backing allocator
+.Fa allocfn ,
+so even if
+.Dv VM_SLEEP
+is specified,
+.Fn vmem_alloc
+and
+.Fn vmem_xalloc
+may spuriously fail immediately with
+.Fa align ,
+.Fa phase ,
+or
+.Fa nocross ,
+or sleep forever with
+.Fa minaddr
+or
+.Fa maxaddr .