[src/trunk]: src/share/man/man9 mutex(9): Note counterintuitive IPL change re...

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

details:   https://anonhg.NetBSD.org/src/rev/300ab8943b7a
branches:  trunk
changeset: 369509:300ab8943b7a
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Sat Aug 20 14:17:36 2022 +0000

description:
mutex(9): Note counterintuitive IPL change releasing spin locks.

No functional change -- documentation only.

Details:

https://mail-index.netbsd.org/tech-kern/2010/11/12/msg009203.html

diffstat:

 share/man/man9/mutex.9 |  15 ++++++++++++++-
 1 files changed, 14 insertions(+), 1 deletions(-)

diffs (29 lines):

diff -r 2c29ea03b3b2 -r 300ab8943b7a share/man/man9/mutex.9
--- a/share/man/man9/mutex.9    Sat Aug 20 14:09:20 2022 +0000
+++ b/share/man/man9/mutex.9    Sat Aug 20 14:17:36 2022 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: mutex.9,v 1.31 2017/12/09 16:00:19 wiz Exp $
+.\"    $NetBSD: mutex.9,v 1.32 2022/08/20 14:17:36 riastradh Exp $
 .\"
 .\" Copyright (c) 2007, 2009 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -141,6 +141,19 @@
 .Pp
 A processor will always busy-wait when attempting to acquire
 a spin mutex that is already held.
+.Pp
+.Sy Note :
+Releasing a spin mutex may not lower the IPL to what it was when
+entered.
+If other spin mutexes are held, the IPL will not be lowered until the
+last one is released.
+.Pp
+This is usually not a problem because spin mutexes should held only for
+very short durations anyway, so blocking higher-priority interrupts a
+little longer doesn't hurt much.
+But it interferes with writing assertions that the IPL is
+.Em no higher than
+a specified level.
 .El
 .Pp
 See