Mon May 1 21:36:01 2017 UTC ()
Update mutex(9) for mutex_ownable()


(pgoyette)
diff -r1.410 -r1.411 src/share/man/man9/Makefile
diff -r1.26 -r1.27 src/share/man/man9/mutex.9
cvs diff -r1.410 -r1.411 src/share/man/man9/Makefile (expand / switch to unified diff)

--- src/share/man/man9/Makefile 2017/04/30 12:30:00 1.410
+++ src/share/man/man9/Makefile 2017/05/01 21:36:01 1.411
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1# $NetBSD: Makefile,v 1.410 2017/04/30 12:30:00 pgoyette Exp $ 1# $NetBSD: Makefile,v 1.411 2017/05/01 21:36:01 pgoyette Exp $
2 2
3# Makefile for section 9 (kernel function and variable) manual pages. 3# Makefile for section 9 (kernel function and variable) manual pages.
4 4
5MAN= accept_filter.9 accf_data.9 accf_http.9 \ 5MAN= accept_filter.9 accf_data.9 accf_http.9 \
6 altq.9 arp.9 audio.9 autoconf.9 \ 6 altq.9 arp.9 audio.9 autoconf.9 \
7 bcdtobin.9 bcmp.9 bcopy.9 bintime_add.9 bluetooth.9 boothowto.9 bpf.9 \ 7 bcdtobin.9 bcmp.9 bcopy.9 bintime_add.9 bluetooth.9 boothowto.9 bpf.9 \
8 buffercache.9 bufferio.9 bufq.9 bus_dma.9 bus_space.9 byteorder.9 \ 8 buffercache.9 bufferio.9 bufq.9 bus_dma.9 bus_space.9 byteorder.9 \
9 bzero.9 \ 9 bzero.9 \
10 callback.9 callout.9 cardbus.9 clock.9 cnmagic.9 condvar.9 config.9 \ 10 callback.9 callout.9 cardbus.9 clock.9 cnmagic.9 condvar.9 config.9 \
11 cons.9 copy.9 coredump_write.9 \ 11 cons.9 copy.9 coredump_write.9 \
12 cpu_configure.9 cpu_coredump.9 cpu_dumpconf.9 \ 12 cpu_configure.9 cpu_coredump.9 cpu_dumpconf.9 \
13 cpu_lwp_fork.9 \ 13 cpu_lwp_fork.9 \
14 cpu_idle.9 cpu_initclocks.9 cpu_need_resched.9 \ 14 cpu_idle.9 cpu_initclocks.9 cpu_need_resched.9 \
@@ -22,27 +22,27 @@ MAN= accept_filter.9 accf_data.9 accf_ht @@ -22,27 +22,27 @@ MAN= accept_filter.9 accf_data.9 accf_ht
22 fetch.9 file.9 fileassoc.9 filedesc.9 firmload.9 flash.9 \ 22 fetch.9 file.9 fileassoc.9 filedesc.9 firmload.9 flash.9 \
23 fork1.9 fsetown.9 fstrans.9 \ 23 fork1.9 fsetown.9 fstrans.9 \
24 genfs.9 genfs_rename.9 \ 24 genfs.9 genfs_rename.9 \
25 hash.9 hashinit.9 hardclock.9 humanize_number.9 hz.9 \ 25 hash.9 hashinit.9 hardclock.9 humanize_number.9 hz.9 \
26 ieee80211.9 ieee80211_crypto.9 ieee80211_input.9 ieee80211_ioctl.9 \ 26 ieee80211.9 ieee80211_crypto.9 ieee80211_input.9 ieee80211_ioctl.9 \
27 ieee80211_node.9 ieee80211_output.9 ieee80211_proto.9 \ 27 ieee80211_node.9 ieee80211_output.9 ieee80211_proto.9 \
28 ieee80211_radiotap.9 iic.9 imax.9 \ 28 ieee80211_radiotap.9 iic.9 imax.9 \
29 in_getifa.9 \ 29 in_getifa.9 \
30 in4_cksum.9 inittodr.9 interrupt_distribute.9 intro.9 ioasic.9 \ 30 in4_cksum.9 inittodr.9 interrupt_distribute.9 intro.9 ioasic.9 \
31 ioctl.9 ipkdb.9 ipi.9 isa.9 isapnp.9 itimerfix.9 kauth.9 kcopy.9 \ 31 ioctl.9 ipkdb.9 ipi.9 isa.9 isapnp.9 itimerfix.9 kauth.9 kcopy.9 \
32 kcpuset.9 kernhist.9 klua_lock.9 klua_mod_register.9 kmem.9 kpause.9 \ 32 kcpuset.9 kernhist.9 klua_lock.9 klua_mod_register.9 kmem.9 kpause.9 \
33 kfilter_register.9 knote.9 \ 33 kfilter_register.9 knote.9 \
34 kprintf.9 kthread.9 linedisc.9 lock.9 locking.9 log.9 ltsleep.9 \ 34 kprintf.9 kthread.9 linedisc.9 lock.9 locking.9 log.9 ltsleep.9 \
35 LWP_CACHE_CREDS.9 \ 35 localcount.9 LWP_CACHE_CREDS.9 \
36 makeiplcookie.9 \ 36 makeiplcookie.9 \
37 malloc.9 mb.9 mbuf.9 mca.9 memcmp.9 memcpy.9 memoryallocators.9 \ 37 malloc.9 mb.9 mbuf.9 mca.9 memcmp.9 memcpy.9 memoryallocators.9 \
38 memmove.9 memset.9 \ 38 memmove.9 memset.9 \
39 microseq.9 microtime.9 microuptime.9 mi_switch.9 module.9 \ 39 microseq.9 microtime.9 microuptime.9 mi_switch.9 module.9 \
40 mstohz.9 mutex.9 m_tag.9 namecache.9 \ 40 mstohz.9 mutex.9 m_tag.9 namecache.9 \
41 namei.9 nullop.9 opencrypto.9 optstr.9 \ 41 namei.9 nullop.9 opencrypto.9 optstr.9 \
42 panic.9 pathbuf.9 pci.9 pci_configure_bus.9 pci_intr.9 \ 42 panic.9 pathbuf.9 pci.9 pci_configure_bus.9 pci_intr.9 \
43 pci_msi.9 pckbport.9 pcmcia.9 pcq.9 pcu.9 \ 43 pci_msi.9 pckbport.9 pcmcia.9 pcq.9 pcu.9 \
44 percpu.9 pfil.9 physio.9 pmap.9 pmatch.9 pmc.9 pmf.9 pool.9 \ 44 percpu.9 pfil.9 physio.9 pmap.9 pmatch.9 pmc.9 pmf.9 pool.9 \
45 pool_cache.9 powerhook_establish.9 ppi.9 ppsratecheck.9 preempt.9 \ 45 pool_cache.9 powerhook_establish.9 ppi.9 ppsratecheck.9 preempt.9 \
46 proc_find.9 pserialize.9 pslist.9 psref.9 putter.9 \ 46 proc_find.9 pserialize.9 pslist.9 psref.9 putter.9 \
47 radio.9 ras.9 rasops.9 ratecheck.9 resettodr.9 rnd.9 rndsink.9 \ 47 radio.9 ras.9 rasops.9 ratecheck.9 resettodr.9 rnd.9 rndsink.9 \
48 roundup.9 rssadapt.9 rt_timer.9 rwlock.9 RUN_ONCE.9 STACK.9 \ 48 roundup.9 rssadapt.9 rt_timer.9 rwlock.9 RUN_ONCE.9 STACK.9 \
@@ -109,26 +109,27 @@ MLINKS+=accept_filter.9 accept_filt_get. @@ -109,26 +109,27 @@ MLINKS+=accept_filter.9 accept_filt_get.
109 109
110MLINKS+=arp.9 arp_ifinit.9 arp.9 arpresolve.9 arp.9 arpintr.9 110MLINKS+=arp.9 arp_ifinit.9 arp.9 arpresolve.9 arp.9 arpintr.9
111MLINKS+=autoconf.9 config_search_loc.9 \ 111MLINKS+=autoconf.9 config_search_loc.9 \
112 autoconf.9 config_search_ia.9 \ 112 autoconf.9 config_search_ia.9 \
113 autoconf.9 config_found_sm_loc.9 \ 113 autoconf.9 config_found_sm_loc.9 \
114 autoconf.9 config_found_ia.9 \ 114 autoconf.9 config_found_ia.9 \
115 autoconf.9 config_found.9 \ 115 autoconf.9 config_found.9 \
116 autoconf.9 config_match.9 \ 116 autoconf.9 config_match.9 \
117 autoconf.9 config_attach_loc.9 \ 117 autoconf.9 config_attach_loc.9 \
118 autoconf.9 config_attach.9 \ 118 autoconf.9 config_attach.9 \
119 autoconf.9 config_attach_pseudo.9 \ 119 autoconf.9 config_attach_pseudo.9 \
120 autoconf.9 config_detach.9 \ 120 autoconf.9 config_detach.9 \
121 autoconf.9 config_detach_children.9 \ 121 autoconf.9 config_detach_children.9 \
 122 autoconf.9 config_detach_release.9 \
122 autoconf.9 config_deactivate.9 \ 123 autoconf.9 config_deactivate.9 \
123 autoconf.9 config_defer.9 \ 124 autoconf.9 config_defer.9 \
124 autoconf.9 config_interrupts.9 \ 125 autoconf.9 config_interrupts.9 \
125 autoconf.9 config_mountroot.9 \ 126 autoconf.9 config_mountroot.9 \
126 autoconf.9 config_pending_incr.9 \ 127 autoconf.9 config_pending_incr.9 \
127 autoconf.9 config_pending_decr.9 \ 128 autoconf.9 config_pending_decr.9 \
128 autoconf.9 config_finalize_register.9 129 autoconf.9 config_finalize_register.9
129MLINKS+=bcdtobin.9 bintobcd.9 130MLINKS+=bcdtobin.9 bintobcd.9
130MLINKS+=bintime_add.9 bintime_addx.9 \ 131MLINKS+=bintime_add.9 bintime_addx.9 \
131 bintime_add.9 bintime_sub.9 \ 132 bintime_add.9 bintime_sub.9 \
132 bintime_add.9 bintime2timespec.9 \ 133 bintime_add.9 bintime2timespec.9 \
133 bintime_add.9 timespec2bintime.9 \ 134 bintime_add.9 timespec2bintime.9 \
134 bintime_add.9 bintime2timeval.9 \ 135 bintime_add.9 bintime2timeval.9 \
@@ -506,26 +507,27 @@ MLINKS+=module.9 module_autoload.9 \ @@ -506,26 +507,27 @@ MLINKS+=module.9 module_autoload.9 \
506 module.9 module_builtin_require_force.9 \ 507 module.9 module_builtin_require_force.9 \
507 module.9 module_find_section.9 \ 508 module.9 module_find_section.9 \
508 module.9 module_hold.9 \ 509 module.9 module_hold.9 \
509 module.9 module_init.9 \ 510 module.9 module_init.9 \
510 module.9 module_init_class.9 \ 511 module.9 module_init_class.9 \
511 module.9 module_load.9 \ 512 module.9 module_load.9 \
512 module.9 module_load_vfs_init.9 \ 513 module.9 module_load_vfs_init.9 \
513 module.9 module_rele.9 \ 514 module.9 module_rele.9 \
514 module.9 module_start_unload_thread.9 \ 515 module.9 module_start_unload_thread.9 \
515 module.9 module_unload.9 516 module.9 module_unload.9
516MLINKS+=mstohz.9 hztoms.9 517MLINKS+=mstohz.9 hztoms.9
517MLINKS+=mutex.9 mutex_init.9 mutex.9 mutex_destroy.9 mutex.9 mutex_enter.9 \ 518MLINKS+=mutex.9 mutex_init.9 mutex.9 mutex_destroy.9 mutex.9 mutex_enter.9 \
518 mutex.9 mutex_exit.9 mutex.9 mutex_tryenter.9 mutex.9 mutex_owned.9 \ 519 mutex.9 mutex_exit.9 mutex.9 mutex_tryenter.9 mutex.9 mutex_owned.9 \
 520 mutex.9 mutex_ownable.9 \
519 mutex.9 mutex_spin_enter.9 mutex.9 mutex_spin_exit.9 521 mutex.9 mutex_spin_enter.9 mutex.9 mutex_spin_exit.9
520MLINKS+=m_tag.9 m_tag_copy.9 \ 522MLINKS+=m_tag.9 m_tag_copy.9 \
521 m_tag.9 m_tag_copy_chain.9 \ 523 m_tag.9 m_tag_copy_chain.9 \
522 m_tag.9 m_tag_delete.9 \ 524 m_tag.9 m_tag_delete.9 \
523 m_tag.9 m_tag_delete_chain.9 \ 525 m_tag.9 m_tag_delete_chain.9 \
524 m_tag.9 m_tag_delete_nonpersistent.9 \ 526 m_tag.9 m_tag_delete_nonpersistent.9 \
525 m_tag.9 m_tag_find.9 \ 527 m_tag.9 m_tag_find.9 \
526 m_tag.9 m_tag_first.9 \ 528 m_tag.9 m_tag_first.9 \
527 m_tag.9 m_tag_free.9 \ 529 m_tag.9 m_tag_free.9 \
528 m_tag.9 m_tag_get.9 \ 530 m_tag.9 m_tag_get.9 \
529 m_tag.9 m_tag_init.9 \ 531 m_tag.9 m_tag_init.9 \
530 m_tag.9 m_tag_next.9 \ 532 m_tag.9 m_tag_next.9 \
531 m_tag.9 m_tag_prepend.9 \ 533 m_tag.9 m_tag_prepend.9 \
cvs diff -r1.26 -r1.27 src/share/man/man9/mutex.9 (expand / switch to unified diff)

--- src/share/man/man9/mutex.9 2013/09/04 10:17:58 1.26
+++ src/share/man/man9/mutex.9 2017/05/01 21:36:01 1.27
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1.\" $NetBSD: mutex.9,v 1.26 2013/09/04 10:17:58 skrll Exp $ 1.\" $NetBSD: mutex.9,v 1.27 2017/05/01 21:36:01 pgoyette Exp $
2.\" 2.\"
3.\" Copyright (c) 2007, 2009 The NetBSD Foundation, Inc. 3.\" Copyright (c) 2007, 2009 The NetBSD Foundation, Inc.
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation 6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Andrew Doran. 7.\" by Andrew Doran.
8.\" 8.\"
9.\" Redistribution and use in source and binary forms, with or without 9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions 10.\" modification, are permitted provided that the following conditions
11.\" are met: 11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright 12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer. 13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" 2. Redistributions in binary form must reproduce the above copyright
@@ -26,42 +26,45 @@ @@ -26,42 +26,45 @@
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE. 28.\" POSSIBILITY OF SUCH DAMAGE.
29.\" 29.\"
30.Dd September 4, 2013 30.Dd September 4, 2013
31.Dt MUTEX 9 31.Dt MUTEX 9
32.Os 32.Os
33.Sh NAME 33.Sh NAME
34.Nm mutex , 34.Nm mutex ,
35.Nm mutex_init , 35.Nm mutex_init ,
36.Nm mutex_destroy , 36.Nm mutex_destroy ,
37.Nm mutex_enter , 37.Nm mutex_enter ,
38.Nm mutex_exit , 38.Nm mutex_exit ,
 39.Nm mutex_ownable ,
39.Nm mutex_owned , 40.Nm mutex_owned ,
40.Nm mutex_spin_enter , 41.Nm mutex_spin_enter ,
41.Nm mutex_spin_exit , 42.Nm mutex_spin_exit ,
42.Nm mutex_tryenter 43.Nm mutex_tryenter
43.Nd mutual exclusion primitives 44.Nd mutual exclusion primitives
44.Sh SYNOPSIS 45.Sh SYNOPSIS
45.In sys/mutex.h 46.In sys/mutex.h
46.Ft void 47.Ft void
47.Fn mutex_init "kmutex_t *mtx" "kmutex_type_t type" "int ipl" 48.Fn mutex_init "kmutex_t *mtx" "kmutex_type_t type" "int ipl"
48.Ft void 49.Ft void
49.Fn mutex_destroy "kmutex_t *mtx" 50.Fn mutex_destroy "kmutex_t *mtx"
50.Ft void 51.Ft void
51.Fn mutex_enter "kmutex_t *mtx" 52.Fn mutex_enter "kmutex_t *mtx"
52.Ft void 53.Ft void
53.Fn mutex_exit "kmutex_t *mtx" 54.Fn mutex_exit "kmutex_t *mtx"
54.Ft int 55.Ft int
 56.Fn mutex_ownable "kmutex_t *mtx"
 57.Ft int
55.Fn mutex_owned "kmutex_t *mtx" 58.Fn mutex_owned "kmutex_t *mtx"
56.Ft void 59.Ft void
57.Fn mutex_spin_enter "kmutex_t *mtx" 60.Fn mutex_spin_enter "kmutex_t *mtx"
58.Ft void 61.Ft void
59.Fn mutex_spin_exit "kmutex_t *mtx" 62.Fn mutex_spin_exit "kmutex_t *mtx"
60.Ft int 63.Ft int
61.Fn mutex_tryenter "kmutex_t *mtx" 64.Fn mutex_tryenter "kmutex_t *mtx"
62.Pp 65.Pp
63.Cd "options DIAGNOSTIC" 66.Cd "options DIAGNOSTIC"
64.Cd "options LOCKDEBUG" 67.Cd "options LOCKDEBUG"
65.Sh DESCRIPTION 68.Sh DESCRIPTION
66Mutexes are used in the kernel to implement mutual exclusion among LWPs 69Mutexes are used in the kernel to implement mutual exclusion among LWPs
67(lightweight processes) and interrupt handlers. 70(lightweight processes) and interrupt handlers.
@@ -162,26 +165,41 @@ Otherwise, the potential for system dead @@ -162,26 +165,41 @@ Otherwise, the potential for system dead
162.Pp 165.Pp
163Adaptive mutexes and other types of lock that can sleep may 166Adaptive mutexes and other types of lock that can sleep may
164not be acquired while a spin mutex is held by the caller. 167not be acquired while a spin mutex is held by the caller.
165.Pp 168.Pp
166When acquiring a spin mutex, the IPL of the current CPU will be raised to 169When acquiring a spin mutex, the IPL of the current CPU will be raised to
167the level set in 170the level set in
168.Fn mutex_init 171.Fn mutex_init
169if it is not already equal or higher. 172if it is not already equal or higher.
170.It Fn mutex_exit "mtx" 173.It Fn mutex_exit "mtx"
171.Pp 174.Pp
172Release a mutex. 175Release a mutex.
173The mutex must have been previously acquired by the caller. 176The mutex must have been previously acquired by the caller.
174Mutexes may be released out of order as needed. 177Mutexes may be released out of order as needed.
 178.It Fn mutex_ownable "mtx"
 179.Pp
 180When compiled with LOCKDEBUG (see
 181.Xr options 4 ) ,
 182ensure that the current process can successfully acquire mtx.
 183If mtx is already owned by the current process, the system will panic
 184with a "locking against myself" error.
 185.Pp
 186This function is needed because
 187.Fn mutex_owned
 188does not differentiate if a spin mutex is owned by the current process
 189vs owned by another process.
 190.Fn mutex_ownable
 191is reasonably heavy-weight, and should only be used with
 192.Xr KDASSERT 9 .
175.It Fn mutex_owned "mtx" 193.It Fn mutex_owned "mtx"
176.Pp 194.Pp
177For adaptive mutexes, return non-zero if the current LWP holds the mutex. 195For adaptive mutexes, return non-zero if the current LWP holds the mutex.
178For spin mutexes, return non-zero if the mutex is held, potentially by the 196For spin mutexes, return non-zero if the mutex is held, potentially by the
179current processor. 197current processor.
180Otherwise, return zero. 198Otherwise, return zero.
181.Pp 199.Pp
182.Fn mutex_owned 200.Fn mutex_owned
183is provided for making diagnostic checks to verify that a lock is held. 201is provided for making diagnostic checks to verify that a lock is held.
184For example: 202For example:
185.Bd -literal 203.Bd -literal
186 KASSERT(mutex_owned(\*[Am]driver_lock)); 204 KASSERT(mutex_owned(\*[Am]driver_lock));
187.Ed 205.Ed