[src/trunk]: src/share/man/man9 Update mutex(9) for mutex_ownable()

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

details:   https://anonhg.NetBSD.org/src/rev/e257372cbe44
branches:  trunk
changeset: 823666:e257372cbe44
user:      pgoyette <pgoyette%NetBSD.org@localhost>
date:      Mon May 01 21:36:01 2017 +0000

description:
Update mutex(9) for mutex_ownable()

diffstat:

 share/man/man9/Makefile |   6 ++++--
 share/man/man9/mutex.9  |  20 +++++++++++++++++++-
 2 files changed, 23 insertions(+), 3 deletions(-)

diffs (82 lines):

diff -r 7135df19e3d8 -r e257372cbe44 share/man/man9/Makefile
--- a/share/man/man9/Makefile   Mon May 01 21:35:25 2017 +0000
+++ b/share/man/man9/Makefile   Mon May 01 21:36:01 2017 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.410 2017/04/30 12:30:00 pgoyette Exp $
+#       $NetBSD: Makefile,v 1.411 2017/05/01 21:36:01 pgoyette Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -32,7 +32,7 @@
        kcpuset.9 kernhist.9 klua_lock.9 klua_mod_register.9 kmem.9 kpause.9 \
        kfilter_register.9 knote.9 \
        kprintf.9 kthread.9 linedisc.9 lock.9 locking.9 log.9 ltsleep.9 \
-       LWP_CACHE_CREDS.9 \
+       localcount.9 LWP_CACHE_CREDS.9 \
        makeiplcookie.9 \
        malloc.9 mb.9 mbuf.9 mca.9 memcmp.9 memcpy.9 memoryallocators.9 \
        memmove.9 memset.9 \
@@ -119,6 +119,7 @@
        autoconf.9 config_attach_pseudo.9 \
        autoconf.9 config_detach.9 \
        autoconf.9 config_detach_children.9 \
+       autoconf.9 config_detach_release.9 \
        autoconf.9 config_deactivate.9 \
        autoconf.9 config_defer.9 \
        autoconf.9 config_interrupts.9 \
@@ -516,6 +517,7 @@
 MLINKS+=mstohz.9 hztoms.9
 MLINKS+=mutex.9 mutex_init.9 mutex.9 mutex_destroy.9 mutex.9 mutex_enter.9 \
        mutex.9 mutex_exit.9 mutex.9 mutex_tryenter.9 mutex.9 mutex_owned.9 \
+       mutex.9 mutex_ownable.9 \
        mutex.9 mutex_spin_enter.9 mutex.9 mutex_spin_exit.9
 MLINKS+=m_tag.9 m_tag_copy.9 \
        m_tag.9 m_tag_copy_chain.9 \
diff -r 7135df19e3d8 -r e257372cbe44 share/man/man9/mutex.9
--- a/share/man/man9/mutex.9    Mon May 01 21:35:25 2017 +0000
+++ b/share/man/man9/mutex.9    Mon May 01 21:36:01 2017 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: mutex.9,v 1.26 2013/09/04 10:17:58 skrll Exp $
+.\"    $NetBSD: mutex.9,v 1.27 2017/05/01 21:36:01 pgoyette Exp $
 .\"
 .\" Copyright (c) 2007, 2009 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -36,6 +36,7 @@
 .Nm mutex_destroy ,
 .Nm mutex_enter ,
 .Nm mutex_exit ,
+.Nm mutex_ownable ,
 .Nm mutex_owned ,
 .Nm mutex_spin_enter ,
 .Nm mutex_spin_exit ,
@@ -52,6 +53,8 @@
 .Ft void
 .Fn mutex_exit "kmutex_t *mtx"
 .Ft int
+.Fn mutex_ownable "kmutex_t *mtx"
+.Ft int
 .Fn mutex_owned "kmutex_t *mtx"
 .Ft void
 .Fn mutex_spin_enter "kmutex_t *mtx"
@@ -172,6 +175,21 @@
 Release a mutex.
 The mutex must have been previously acquired by the caller.
 Mutexes may be released out of order as needed.
+.It Fn mutex_ownable "mtx"
+.Pp
+When compiled with LOCKDEBUG (see
+.Xr options 4 ) ,
+ensure that the current process can successfully acquire mtx.
+If mtx is already owned by the current process, the system will panic
+with a "locking against myself" error.
+.Pp
+This function is needed because
+.Fn mutex_owned
+does not differentiate if a spin mutex is owned by the current process
+vs owned by another process.
+.Fn mutex_ownable
+is reasonably heavy-weight, and should only be used with
+.Xr KDASSERT 9 .
 .It Fn mutex_owned "mtx"
 .Pp
 For adaptive mutexes, return non-zero if the current LWP holds the mutex.