CVS commit: [pgoyette-localcount] src/share/man/man9
Module Name:src Committed By: pgoyette Date: Thu Dec 8 06:56:21 UTC 2016 Modified Files: src/share/man/man9 [pgoyette-localcount]: localcount.9 Log Message: Minor tweaks. To generate a diff of this commit: cvs rdiff -u -r1.1.2.6 -r1.1.2.7 src/share/man/man9/localcount.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/localcount.9 diff -u src/share/man/man9/localcount.9:1.1.2.6 src/share/man/man9/localcount.9:1.1.2.7 --- src/share/man/man9/localcount.9:1.1.2.6 Wed Aug 3 13:11:36 2016 +++ src/share/man/man9/localcount.9 Thu Dec 8 06:56:21 2016 @@ -1,4 +1,4 @@ -.\" $NetBSD: localcount.9,v 1.1.2.6 2016/08/03 13:11:36 pgoyette Exp $ +.\" $NetBSD: localcount.9,v 1.1.2.7 2016/12/08 06:56:21 pgoyette Exp $ .\" .\" Copyright (c) 2016 .\" All rights reserved. @@ -27,7 +27,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd August 2, 2016 +.Dd December 8, 2016 .Dt LOCALCOUNT 9 .Os .Sh NAME @@ -77,11 +77,13 @@ and almost always more than .Pp As a rough heuristic, .Nm -should be used for classes of objects of which there are maybe a few dozen -instances but not a few thousand instances (e.g. autoconf devices, but not +should be used for classes of objects of which there are perhaps a few dozen +instances (such as +.Xr autoconf 9 +devices) but not thousands of instances (such as network flows) and on which there may be a mixture of long-term I/O waits, such as xyzread for a device xyz(4), and short-term fast operations, such as -xyzioctl(IOC_READ_A_CPU_REG). +.Dv xyzioctl(IOC_READ_A_CPU_REG) . .Sh FUNCTIONS .Bl -tag -width abcd .It Fn localcount_init "lc"
CVS commit: [pgoyette-localcount] src/share/man/man9
Module Name:src Committed By: pgoyette Date: Wed Aug 3 13:11:37 UTC 2016 Modified Files: src/share/man/man9 [pgoyette-localcount]: localcount.9 Log Message: As suggested in private Email, rename BUGS section to CAVEATS. To generate a diff of this commit: cvs rdiff -u -r1.1.2.5 -r1.1.2.6 src/share/man/man9/localcount.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/localcount.9 diff -u src/share/man/man9/localcount.9:1.1.2.5 src/share/man/man9/localcount.9:1.1.2.6 --- src/share/man/man9/localcount.9:1.1.2.5 Mon Aug 1 12:02:00 2016 +++ src/share/man/man9/localcount.9 Wed Aug 3 13:11:36 2016 @@ -1,4 +1,4 @@ -.\" $NetBSD: localcount.9,v 1.1.2.5 2016/08/01 12:02:00 pgoyette Exp $ +.\" $NetBSD: localcount.9,v 1.1.2.6 2016/08/03 13:11:36 pgoyette Exp $ .\" .\" Copyright (c) 2016 .\" All rights reserved. @@ -173,7 +173,7 @@ was written by .An Taylor R. Campbell . This manual page was compiled by .An Paul Goyette . -.Sh BUGS +.Sh CAVEATS The .Nm facility does not provide any way to examine the reference count without
CVS commit: [pgoyette-localcount] src/share/man/man9
Module Name:src Committed By: pgoyette Date: Mon Aug 1 12:02:00 UTC 2016 Modified Files: src/share/man/man9 [pgoyette-localcount]: localcount.9 Log Message: Add a BUGS section, which is really a RESTRICTIONS section (but mdoclint doesn't like RESTRICTIONS!) To generate a diff of this commit: cvs rdiff -u -r1.1.2.4 -r1.1.2.5 src/share/man/man9/localcount.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/localcount.9 diff -u src/share/man/man9/localcount.9:1.1.2.4 src/share/man/man9/localcount.9:1.1.2.5 --- src/share/man/man9/localcount.9:1.1.2.4 Sat Jul 16 23:42:35 2016 +++ src/share/man/man9/localcount.9 Mon Aug 1 12:02:00 2016 @@ -1,4 +1,4 @@ -.\" $NetBSD: localcount.9,v 1.1.2.4 2016/07/16 23:42:35 pgoyette Exp $ +.\" $NetBSD: localcount.9,v 1.1.2.5 2016/08/01 12:02:00 pgoyette Exp $ .\" .\" Copyright (c) 2016 .\" All rights reserved. @@ -27,7 +27,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd July xx, 2016 +.Dd August 2, 2016 .Dt LOCALCOUNT 9 .Os .Sh NAME @@ -173,3 +173,17 @@ was written by .An Taylor R. Campbell . This manual page was compiled by .An Paul Goyette . +.Sh BUGS +The +.Nm +facility does not provide any way to examine the reference count without +actually waiting for the count to reach zero. +.Pp +Waiting for a +.Nm +reference count to reach zero is a one-shot operation. +Once the +.Nm +has been waited for, no further operations are allowed until the +.Nm +has been re-initialized.
CVS commit: [pgoyette-localcount] src/share/man/man9
Module Name:src Committed By: pgoyette Date: Mon Jul 18 03:38:09 UTC 2016 Modified Files: src/share/man/man9 [pgoyette-localcount]: Makefile Log Message: Additional MLINKS for devsw_attach To generate a diff of this commit: cvs rdiff -u -r1.396.2.2 -r1.396.2.3 src/share/man/man9/Makefile 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/Makefile diff -u src/share/man/man9/Makefile:1.396.2.2 src/share/man/man9/Makefile:1.396.2.3 --- src/share/man/man9/Makefile:1.396.2.2 Sat Jul 16 09:49:24 2016 +++ src/share/man/man9/Makefile Mon Jul 18 03:38:09 2016 @@ -1,4 +1,4 @@ -# $NetBSD: Makefile,v 1.396.2.2 2016/07/16 09:49:24 pgoyette Exp $ +# $NetBSD: Makefile,v 1.396.2.3 2016/07/18 03:38:09 pgoyette Exp $ # Makefile for section 9 (kernel function and variable) manual pages. @@ -281,8 +281,12 @@ MLINKS+=delay.9 DELAY.9 MLINKS+=devsw_attach.9 devsw_detach.9 \ devsw_attach.9 bdevsw_lookup.9 \ devsw_attach.9 cdevsw_lookup.9 \ + devsw_attach.9 bdevsw_lookup_acquire.9 \ + devsw_attach.9 cdevsw_lookup_acquire.9 \ devsw_attach.9 bdevsw_lookup_major.9 \ - devsw_attach.9 cdevsw_lookup_major.9 + devsw_attach.9 cdevsw_lookup_major.9 \ + devsw_attach.9 bdevsw_release.9 \ + devsw_attach.9 cdevsw_release.9 MLINKS+=disk.9 disk_attach.9 disk.9 disk_detach.9 \ disk.9 disk_busy.9 disk.9 disk_unbusy.9 disk.9 disk_find.9 \ disk.9 disk_init.9 disk.9 disk_destroy.9 disk.9 disk_begindetach.9
CVS commit: [pgoyette-localcount] src/share/man/man9
Module Name:src
Committed By: pgoyette
Date: Sun Jul 17 05:48:28 UTC 2016
Modified Files:
src/share/man/man9 [pgoyette-localcount]: devsw_attach.9
Log Message:
Update for new functions {b,c}devsw_{acquire,release}
To generate a diff of this commit:
cvs rdiff -u -r1.2 -r1.2.2.1 src/share/man/man9/devsw_attach.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/devsw_attach.9
diff -u src/share/man/man9/devsw_attach.9:1.2 src/share/man/man9/devsw_attach.9:1.2.2.1
--- src/share/man/man9/devsw_attach.9:1.2 Thu May 14 13:59:15 2015
+++ src/share/man/man9/devsw_attach.9 Sun Jul 17 05:48:28 2016
@@ -1,4 +1,4 @@
-.\" $NetBSD: devsw_attach.9,v 1.2 2015/05/14 13:59:15 wiz Exp $
+.\" $NetBSD: devsw_attach.9,v 1.2.2.1 2016/07/17 05:48:28 pgoyette Exp $
.\"
.\" Copyright (c) 2015 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -27,16 +27,20 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd May 13, 2015
+.Dd July 17, 2016
.Dt DEVSW_ATTACH 9
.Os
.Sh NAME
.Nm devsw_attach ,
.Nm devsw_detach ,
.Nm bdevsw_lookup ,
+.Nm bdevsw_lookup_acquire ,
.Nm cdevsw_lookup ,
+.Nm cdevsw_lookup_acquire ,
.Nm bdevsw_lookup_major ,
-.Nm cdevsw_lookup_major
+.Nm cdevsw_lookup_major,
+.Nm bdevsw_release ,
+.Nm cdevsw_release
.Nd character and block device switch functions
.Sh SYNOPSIS
.In sys/conf.h
@@ -57,10 +61,26 @@
.Fo bdevsw_lookup
.Fa "dev_t dev"
.Fc
+.Ft "const struct bdevsw *"
+.Fo bdevsw_lookup_acquire
+.Fa "dev_t dev"
+.Fc
+.Ft "void"
+.Fo bdevsw_release
+.Fa "const struct bdevsw *bdev"
+.Fc
.Ft "const struct cdevsw *"
.Fo cdevsw_lookup
.Fa "dev_t dev"
.Fc
+.Ft "const struct cdevsw *"
+.Fo cdevsw_lookup_acquire
+.Fa "dev_t dev"
+.Fc
+.Ft "void"
+.Fo cdevsw_release
+.Fa "const struct cdevsw *cdev"
+.Fc
.Ft devmajor_t
.Fo bdevsw_lookup_major
.Fa "const struct bdevsw *bdev"
@@ -129,17 +149,38 @@ and
structures.
.Fn devsw_detach
should be called before a loaded device driver is unloaded.
+For loadable drivers,
+.Fn devsw_detach
+will wait until the device's reference count is zero (see
+.Fn bdevsw_release
+and
+.Fn cdevsw_release
+below) before returning.
.Pp
The
-.Fn bdevsw_lookup
+.Fn bdevsw_lookup ,
+.Fn bdevsw_lookup_acquire ,
+.Fn cdevsw_lookup ,
and
-.Fn cdevsw_lookup
+.Fn cdevsw_lookup_acquire
functions return
.Em "const struct bdevsw *"
and
.Em "const struct cdevsw *"
for the given
.Em dev .
+The
+.Fn bdevsw_lookup_acquire
+and
+.Fn cdevsw_lookup_acquire
+functions will additionally increment a reference count for loadable
+drivers.
+Callers must invoke
+.Fn bdevsw_release
+or
+.Fn cdevsw_release
+to decrement the reference counter when access to the device is no longer
+needed.
.Pp
The
.Fn bdevsw_lookup_major
@@ -160,9 +201,11 @@ return 0.
Otherwise they return an error value.
.Pp
In case of failure,
-.Fn bdevsw_lookup
+.Fn bdevsw_lookup ,
+.Fn bdevsw_lookup_acquire ,
+.Fn cdevsw_lookup ,
and
-.Fn cdevsw_lookup
+.Fn cdevsw_lookup_acquire
return the
.Dv NULL
value.
CVS commit: [pgoyette-localcount] src/share/man/man9
Module Name:src Committed By: pgoyette Date: Sat Jul 16 23:42:35 UTC 2016 Modified Files: src/share/man/man9 [pgoyette-localcount]: localcount.9 Log Message: Add myself as author/compiler of the man page. To generate a diff of this commit: cvs rdiff -u -r1.1.2.3 -r1.1.2.4 src/share/man/man9/localcount.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/localcount.9 diff -u src/share/man/man9/localcount.9:1.1.2.3 src/share/man/man9/localcount.9:1.1.2.4 --- src/share/man/man9/localcount.9:1.1.2.3 Sat Jul 16 23:28:37 2016 +++ src/share/man/man9/localcount.9 Sat Jul 16 23:42:35 2016 @@ -1,4 +1,4 @@ -.\" $NetBSD: localcount.9,v 1.1.2.3 2016/07/16 23:28:37 pgoyette Exp $ +.\" $NetBSD: localcount.9,v 1.1.2.4 2016/07/16 23:42:35 pgoyette Exp $ .\" .\" Copyright (c) 2016 .\" All rights reserved. @@ -169,4 +169,7 @@ The localcount primitives first appeared This implementation of .Nm was written by +.An -nosplit .An Taylor R. Campbell . +This manual page was compiled by +.An Paul Goyette .
CVS commit: [pgoyette-localcount] src/share/man/man9
Module Name:src Committed By: pgoyette Date: Sat Jul 16 23:28:37 UTC 2016 Modified Files: src/share/man/man9 [pgoyette-localcount]: localcount.9 Log Message: Improve description of localcount_release To generate a diff of this commit: cvs rdiff -u -r1.1.2.2 -r1.1.2.3 src/share/man/man9/localcount.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/localcount.9 diff -u src/share/man/man9/localcount.9:1.1.2.2 src/share/man/man9/localcount.9:1.1.2.3 --- src/share/man/man9/localcount.9:1.1.2.2 Sat Jul 16 23:13:59 2016 +++ src/share/man/man9/localcount.9 Sat Jul 16 23:28:37 2016 @@ -1,4 +1,4 @@ -.\" $NetBSD: localcount.9,v 1.1.2.2 2016/07/16 23:13:59 pgoyette Exp $ +.\" $NetBSD: localcount.9,v 1.1.2.3 2016/07/16 23:28:37 pgoyette Exp $ .\" .\" Copyright (c) 2016 .\" All rights reserved. @@ -86,36 +86,42 @@ xyzioctl(IOC_READ_A_CPU_REG). .Bl -tag -width abcd .It Fn localcount_init "lc" .Pp -Dynamically initialize a localcount for use. +Dynamically initialize localcount +.Ar lc +for use. .Pp No other operations can be performed on a localcount until it has been initialized. .It Fn localcount_fini "lc" .Pp -Release resources used by a localcount. +Release resources used by localcount +.Ar lc . The caller must have already called -.fn localcount_drain . +.Fn localcount_drain . The localcount may not be used after .Fn localcount_fini has been called until it has been re-initialized by .Fn localcount_init . .It Fn localcount_acquire "lc" .Pp -Acquire a reference to the localcount. +Acquire a reference to the localcount +.Ar lc . .It Fn localcount_release "lc" "cv" "mtx" .Pp -Release a reference to the localcount. -Must be called with the mutex +Release a reference to the localcount +.Ar lc . +If the localcount is currently being drained, the mutex .Ar mtx -locked. -If the localcount is being drained, and the reference count goes to zero, -.Fn localcout_release +will be used to synchronize updates to the global reference count (i.e. +the total across all CPUs). +If the reference count goes to zero, +.Fn localcount_release will broadcast availability of the condvar .Ar cv . .It Fn localcount_drain "lc" "cv" "mtx" .Pp -Wait for all references to the -.Nm +Wait for all references to the localcount +.Ar lc to be released. The caller must hold the mutex .Ar mtx ;
CVS commit: [pgoyette-localcount] src/share/man/man9
Module Name:src Committed By: pgoyette Date: Sat Jul 16 23:13:59 UTC 2016 Modified Files: src/share/man/man9 [pgoyette-localcount]: localcount.9 Log Message: Add a bit more about appropriate use-cases. To generate a diff of this commit: cvs rdiff -u -r1.1.2.1 -r1.1.2.2 src/share/man/man9/localcount.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/localcount.9 diff -u src/share/man/man9/localcount.9:1.1.2.1 src/share/man/man9/localcount.9:1.1.2.2 --- src/share/man/man9/localcount.9:1.1.2.1 Sat Jul 16 09:36:57 2016 +++ src/share/man/man9/localcount.9 Sat Jul 16 23:13:59 2016 @@ -1,4 +1,4 @@ -.\" $NetBSD: localcount.9,v 1.1.2.1 2016/07/16 09:36:57 pgoyette Exp $ +.\" $NetBSD: localcount.9,v 1.1.2.2 2016/07/16 23:13:59 pgoyette Exp $ .\" .\" Copyright (c) 2016 .\" All rights reserved. @@ -74,6 +74,14 @@ more than .Xr atomic_ops 3 and almost always more than .Xr psref 9 . +.Pp +As a rough heuristic, +.Nm +should be used for classes of objects of which there are maybe a few dozen +instances but not a few thousand instances (e.g. autoconf devices, but not +network flows) and on which there may be a mixture of long-term I/O waits, +such as xyzread for a device xyz(4), and short-term fast operations, such as +xyzioctl(IOC_READ_A_CPU_REG). .Sh FUNCTIONS .Bl -tag -width abcd .It Fn localcount_init "lc"
CVS commit: [pgoyette-localcount] src/share/man/man9
Module Name:src Committed By: pgoyette Date: Sat Jul 16 09:36:57 UTC 2016 Modified Files: src/share/man/man9 [pgoyette-localcount]: Makefile Added Files: src/share/man/man9 [pgoyette-localcount]: localcount.9 Log Message: Initial man page for localcount(9). To generate a diff of this commit: cvs rdiff -u -r1.396 -r1.396.2.1 src/share/man/man9/Makefile cvs rdiff -u -r0 -r1.1.2.1 src/share/man/man9/localcount.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/Makefile diff -u src/share/man/man9/Makefile:1.396 src/share/man/man9/Makefile:1.396.2.1 --- src/share/man/man9/Makefile:1.396 Tue Jul 12 03:39:55 2016 +++ src/share/man/man9/Makefile Sat Jul 16 09:36:57 2016 @@ -1,4 +1,4 @@ -# $NetBSD: Makefile,v 1.396 2016/07/12 03:39:55 knakahara Exp $ +# $NetBSD: Makefile,v 1.396.2.1 2016/07/16 09:36:57 pgoyette Exp $ # Makefile for section 9 (kernel function and variable) manual pages. @@ -31,7 +31,7 @@ MAN= accept_filter.9 accf_data.9 accf_ht ioctl.9 ipkdb.9 ipi.9 isa.9 isapnp.9 itimerfix.9 kauth.9 kcopy.9 \ kcpuset.9 kernhist.9 kmem.9 kpause.9 \ kfilter_register.9 knote.9 \ - kprintf.9 kthread.9 linedisc.9 lock.9 log.9 ltsleep.9 \ + kprintf.9 kthread.9 linedisc.9 localcount.9 lock.9 log.9 ltsleep.9 \ LWP_CACHE_CREDS.9 \ makeiplcookie.9 \ malloc.9 mb.9 mbuf.9 mca.9 memcmp.9 memcpy.9 memoryallocators.9 \ Added files: Index: src/share/man/man9/localcount.9 diff -u /dev/null src/share/man/man9/localcount.9:1.1.2.1 --- /dev/null Sat Jul 16 09:36:57 2016 +++ src/share/man/man9/localcount.9 Sat Jul 16 09:36:57 2016 @@ -0,0 +1,158 @@ +.\" $NetBSD: localcount.9,v 1.1.2.1 2016/07/16 09:36:57 pgoyette Exp $ +.\" +.\" Copyright (c) 2016 +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Taylor R. Campbell. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\"notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\"notice, this list of conditions and the following disclaimer in the +.\"documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July xx, 2016 +.Dt LOCALCOUNT 9 +.Os +.Sh NAME +.Nm localcount , +.Nm localcount_init , +.Nm localcount_fini , +.Nm localcount_acquire , +.Nm localcount_release , +.Nm localcount_drain , +.Sh SYNOPSIS +.In sys/localcount.h +.Ft int +.Fn localcount_init "struct localcount *lc" +.Ft void +.Fn localcount_fini "struct localcount *lc" +.Ft void +.Fn localcount_acquire "struct localcount *lc" +.Ft void +.Fn localcount_release "struct localcount *lc" "struct kcondvar *cv" \ +"struct kmutex *mtx" +.Ft void +.Fn localcount_drain "struct localcount *lc" "struct kcondvar *cv" \ +"struct kmutex *mtx" +.Sh DESCRIPTION +Localcounts are used in the kernel to implement a medium-weight reference +counting mechanism. +During normal operations, localcounts do not need the interprocessor +synchronization associated with +.Xr atomic_ops 3 +atomic memory operations, and (unlike +.Xr psref 9 ) +.Nm +references can be held across sleeps and can migrate between CPUs. +Draining a +.Nm localcount +requires more expensive interprocessor synchronization than +.Xr atomic_ops 3 +(similar to +.Xr psref 9 ) . +And +.Nm +references require eight bytes of memory per object per-CPU, significantly +more than +.Xr atomic_ops 3 +and almost always more than +.Xr psref 9 . +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn localcount_init "lc" +.Pp +Dynamically initialize a localcount for use. +.Pp +No other operations can be performed on a localcount until it has been +initialized. +.It Fn localcount_fini "lc" +.Pp +Release resources used by a localcount. +The caller must have already called +.fn localcount_drain . +The localcount may not be used after +.Fn localcount_fini +has been called until it
