CVS commit: src/share/man/man9
Module Name:src
Committed By: uwe
Date: Wed Jul 24 12:48:17 UTC 2024
Modified Files:
src/share/man/man9: crashme.9
Log Message:
crashme(9): brush up markup, reword cn_fn slightly for clarity
To generate a diff of this commit:
cvs rdiff -u -r1.5 -r1.6 src/share/man/man9/crashme.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/crashme.9
diff -u src/share/man/man9/crashme.9:1.5 src/share/man/man9/crashme.9:1.6
--- src/share/man/man9/crashme.9:1.5 Sat Dec 11 23:47:53 2021
+++ src/share/man/man9/crashme.9 Wed Jul 24 12:48:17 2024
@@ -1,4 +1,4 @@
-.\" $NetBSD: crashme.9,v 1.5 2021/12/11 23:47:53 riastradh Exp $
+.\" $NetBSD: crashme.9,v 1.6 2024/07/24 12:48:17 uwe Exp $
.\"
.\" Copyright (c) 2019 Matthew R. Green
.\" All rights reserved.
@@ -46,20 +46,21 @@ These nodes are simply named callbacks t
system to crash.
.Pp
The crashme functionality is only available in kernels with the
-.Xr options 4
-.Dv DEBUG
-option set.
+.Ic options DEBUG
+set in the kernel
+.Xr config 5
+file.
.Pp
Each crashme node is maintained in a
.Vt crashme_node
structure which has the following public members:
-.Bd -literal
-typedef int (*crashme_fn)(int);
+.Bd -literal -offset indent
+typedef int (*crashme_fn)(int /* flags */);
typedef struct crashme_node {
- const char *cn_name;
- const char *cn_longname;
- crashme_fn cn_fn;
+const char *cn_name;
+const char *cn_longname;
+crashme_fn cn_fn;
} crashme_node;
.Ed
.Pp
@@ -72,17 +73,19 @@ and
members.
.Pp
The
+.Fa cn_fn
+function is passed
.Ar flags
-parameter is passed from sysctl.
-The return value is 0 upon success or non zero for failure.
+parameter from sysctl.
+It shall return 0 upon success or non zero on failure.
.Sh SYSCTL SUPPORT
The following
.Xr sysctl 8
variables are provided by the
.Nm
subsystem:
-.Bl -tag -width Li
-.It Li debug.crashme_enable
+.Bl -tag -offset indent -width Va
+.It Va debug.crashme_enable
Must be set to 1 for any
.Nm
node to be executed.
@@ -90,28 +93,29 @@ node to be executed.
.Pp
The following
.Xr sysctl 8
-nodes trigger crashes in different ways when written:
-.Bl -tag -width ".Li debug.crashme.null_deref"
-.It Li debug.crashme.panic
+variables trigger crashes in different ways when written to:
+.Bl -tag -offset indent -width Va
+.It Va debug.crashme.panic
Call
.Xr panic 9 .
-.It Li debug.crashme.null_deref
+.It Va debug.crashme.null_deref
Dereference a null pointer.
-.It Li debug.crashme.null_jump
+.It Va debug.crashme.null_jump
Call a null function pointer, i.e., jump to the instruction address
zero.
-.It Li debug.crashme.ddb
+.It Va debug.crashme.ddb
Enter
-.Xr ddb 9
+.Xr ddb 4
directly by calling
-.Xr Debugger 9 .
+.Fn Debugger .
Requires
-.Xr options 4
-.Dv DDB .
+.Ic options DDB .
.El
.Sh SEE ALSO
+.Xr ddb 4 ,
.Xr options 4 ,
-.Xr panic 9
+.Xr sysctl 8 ,
+.Xr panic 9 .
.Sh HISTORY
The
.Nm
CVS commit: src/share/man/man9
Module Name:src Committed By: uwe Date: Wed Jul 24 12:48:17 UTC 2024 Modified Files: src/share/man/man9: crashme.9 Log Message: crashme(9): brush up markup, reword cn_fn slightly for clarity To generate a diff of this commit: cvs rdiff -u -r1.5 -r1.6 src/share/man/man9/crashme.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src
Committed By: rin
Date: Wed Jul 10 07:20:01 UTC 2024
Modified Files:
src/share/man/man9: Makefile
Log Message:
man9: Provide all combinations of {,u}{i,l}{max,min}(9)
To generate a diff of this commit:
cvs rdiff -u -r1.470 -r1.471 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.470 src/share/man/man9/Makefile:1.471
--- src/share/man/man9/Makefile:1.470 Fri Jun 14 13:19:35 2024
+++ src/share/man/man9/Makefile Wed Jul 10 07:20:01 2024
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.470 2024/06/14 13:19:35 riastradh Exp $
+# $NetBSD: Makefile,v 1.471 2024/07/10 07:20:01 rin Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
@@ -413,7 +413,13 @@ MLINKS+=iic.9 iic_acquire_bus.9 \
iic.9 iic_smbus_write_byte.9 \
iic.9 iic_smbus_read_byte.9 \
iic.9 iic_smbus_receive_byte.9
-MLINKS+=imax.9 imin.9
+MLINKS+=imax.9 imin.9 \
+ imax.9 lmax.9 \
+ imax.9 lmin.9 \
+ imax.9 uimax.9 \
+ imax.9 uimin.9 \
+ imax.9 ulmax.9 \
+ imax.9 ulmin.9
MLINKS+=in4_cksum.9 in_cksum.9 \
in4_cksum.9 in6_cksum.9
MLINKS+=ioasic.9 ioasic_intr_establish.9 \
CVS commit: src/share/man/man9
Module Name:src
Committed By: rin
Date: Wed Jul 10 07:20:01 UTC 2024
Modified Files:
src/share/man/man9: Makefile
Log Message:
man9: Provide all combinations of {,u}{i,l}{max,min}(9)
To generate a diff of this commit:
cvs rdiff -u -r1.470 -r1.471 src/share/man/man9/Makefile
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: rin Date: Wed Jul 10 07:08:37 UTC 2024 Modified Files: src/share/man/man9: imax.9 Log Message: imax.9: Additional fixes for previous... To generate a diff of this commit: cvs rdiff -u -r1.7 -r1.8 src/share/man/man9/imax.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: rin Date: Wed Jul 10 07:08:37 UTC 2024 Modified Files: src/share/man/man9: imax.9 Log Message: imax.9: Additional fixes for previous... To generate a diff of this commit: cvs rdiff -u -r1.7 -r1.8 src/share/man/man9/imax.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/imax.9 diff -u src/share/man/man9/imax.9:1.7 src/share/man/man9/imax.9:1.8 --- src/share/man/man9/imax.9:1.7 Wed Jul 10 07:03:47 2024 +++ src/share/man/man9/imax.9 Wed Jul 10 07:08:37 2024 @@ -1,4 +1,4 @@ -.\" $NetBSD: imax.9,v 1.7 2024/07/10 07:03:47 rin Exp $ +.\" $NetBSD: imax.9,v 1.8 2024/07/10 07:08:37 rin Exp $ .\" .\" Copyright (c) 2006 Igor Sobrado .\" All rights reserved. @@ -32,8 +32,8 @@ .Nm imin , .Nm lmax , .Nm lmin , -.Nm max , -.Nm min , +.Nm uimax , +.Nm uimin , .Nm ulmax , .Nm ulmin .Nd compare integers @@ -58,7 +58,7 @@ The .Fn imin , .Fn lmin , -.Fn min , +.Fn uimin , and .Fn ulmin functions return whichever argument is algebraically smaller, differing only @@ -68,7 +68,7 @@ natural size, long, unsigned and unsigne The .Fn imax , .Fn lmax , -.Fn max , +.Fn uimax , and .Fn ulmax functions are identical except that they return the algebraically larger
CVS commit: src/share/man/man9
Module Name:src Committed By: rin Date: Wed Jul 10 07:03:47 UTC 2024 Modified Files: src/share/man/man9: imax.9 Log Message: imax(9): Belatedly catch up with min/max --> uimin/uimax renaming done almost 6 years ago: http://cvsweb.netbsd.org/bsdweb.cgi/src/sys/lib/libkern/libkern.h#rev1.130 Thanks asahi at iij for pointing this out :) To generate a diff of this commit: cvs rdiff -u -r1.6 -r1.7 src/share/man/man9/imax.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/imax.9 diff -u src/share/man/man9/imax.9:1.6 src/share/man/man9/imax.9:1.7 --- src/share/man/man9/imax.9:1.6 Tue Jun 8 08:55:46 2010 +++ src/share/man/man9/imax.9 Wed Jul 10 07:03:47 2024 @@ -1,4 +1,4 @@ -.\" $NetBSD: imax.9,v 1.6 2010/06/08 08:55:46 jruoho Exp $ +.\" $NetBSD: imax.9,v 1.7 2024/07/10 07:03:47 rin Exp $ .\" .\" Copyright (c) 2006 Igor Sobrado .\" All rights reserved. @@ -24,7 +24,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd June 8, 2010 +.Dd July 10, 2024 .Dt IMAX 9 .Os .Sh NAME @@ -47,9 +47,9 @@ .Ft long .Fn lmin "long a" "long b" .Ft u_int -.Fn max "u_int a" "u_int b" +.Fn uimax "u_int a" "u_int b" .Ft u_int -.Fn min "u_int a" "u_int b" +.Fn uimin "u_int a" "u_int b" .Ft u_long .Fn ulmax "u_long a" "u_long b" .Ft u_long
CVS commit: src/share/man/man9
Module Name:src Committed By: rin Date: Wed Jul 10 07:03:47 UTC 2024 Modified Files: src/share/man/man9: imax.9 Log Message: imax(9): Belatedly catch up with min/max --> uimin/uimax renaming done almost 6 years ago: http://cvsweb.netbsd.org/bsdweb.cgi/src/sys/lib/libkern/libkern.h#rev1.130 Thanks asahi at iij for pointing this out :) To generate a diff of this commit: cvs rdiff -u -r1.6 -r1.7 src/share/man/man9/imax.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Tue Jun 18 19:10:50 UTC 2024 Modified Files: src/share/man/man9: atomic_loadstore.9 Log Message: atomic_loadstore(9): Clarify relation to __HAVE_ATOMIC64_OPS. PR kern/58340 To generate a diff of this commit: cvs rdiff -u -r1.7 -r1.8 src/share/man/man9/atomic_loadstore.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Tue Jun 18 19:10:50 UTC 2024 Modified Files: src/share/man/man9: atomic_loadstore.9 Log Message: atomic_loadstore(9): Clarify relation to __HAVE_ATOMIC64_OPS. PR kern/58340 To generate a diff of this commit: cvs rdiff -u -r1.7 -r1.8 src/share/man/man9/atomic_loadstore.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/atomic_loadstore.9 diff -u src/share/man/man9/atomic_loadstore.9:1.7 src/share/man/man9/atomic_loadstore.9:1.8 --- src/share/man/man9/atomic_loadstore.9:1.7 Sat Apr 9 23:32:53 2022 +++ src/share/man/man9/atomic_loadstore.9 Tue Jun 18 19:10:50 2024 @@ -1,4 +1,4 @@ -.\" $NetBSD: atomic_loadstore.9,v 1.7 2022/04/09 23:32:53 riastradh Exp $ +.\" $NetBSD: atomic_loadstore.9,v 1.8 2024/06/18 19:10:50 riastradh Exp $ .\" .\" Copyright (c) 2019 The NetBSD Foundation .\" All rights reserved. @@ -544,9 +544,10 @@ must be zero. .Pp All .Nx -ports support atomic loads and stores on units of data up to 32 bits. -Some ports additionally support atomic loads and stores on larger -quantities, like 64-bit quantities, if +ports support cheap atomic loads and stores on units of data up to 32 +bits. +Some ports additionally support cheap atomic loads and stores on +64-bit quantities if .Dv __HAVE_ATOMIC64_LOADSTORE is defined. The macros are not allowed on larger quantities of data than the port @@ -587,6 +588,24 @@ must be conditional on ... mutex_exit(>f_lock); .Ed +.Pp +Some ports support expensive 64-bit atomic read/modify/write +operations, but not cheap 64-bit atomic loads and stores. +For example, the armv7 instruction set includes 64-bit +.Li ldrexd +and +.Li strexd +loops (load-exclusive, store-conditional) which are atomic on 64-bit +quantities. +But the cheap 64-bit +.Li ldrd / strd +instructions are only atomic on 32-bit accesses at a time. +These ports define +.Dv __HAVE_ATOMIC64_OPS +but not +.Dv __HAVE_ATOMIC64_LOADSTORE , +since they do not have cheaper 64-bit atomic load/store operations than +the full atomic read/modify/write operations. .Sh C11 COMPATIBILITY These macros are meant to follow .Tn C11
CVS commit: src/share/man/man9
Module Name:src Committed By: uwe Date: Fri Jun 14 14:36:32 UTC 2024 Modified Files: src/share/man/man9: uvm_obj_wirepages.9 Log Message: uvm_obj_wirepages(9): fix a couple of markup glitches To generate a diff of this commit: cvs rdiff -u -r1.1 -r1.2 src/share/man/man9/uvm_obj_wirepages.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/uvm_obj_wirepages.9 diff -u src/share/man/man9/uvm_obj_wirepages.9:1.1 src/share/man/man9/uvm_obj_wirepages.9:1.2 --- src/share/man/man9/uvm_obj_wirepages.9:1.1 Fri Jun 14 13:19:35 2024 +++ src/share/man/man9/uvm_obj_wirepages.9 Fri Jun 14 14:36:32 2024 @@ -1,4 +1,4 @@ -.\" $NetBSD: uvm_obj_wirepages.9,v 1.1 2024/06/14 13:19:35 riastradh Exp $ +.\" $NetBSD: uvm_obj_wirepages.9,v 1.2 2024/06/14 14:36:32 uwe Exp $ .\" .\" Copyright (c) 2024 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -53,9 +53,9 @@ the pages in the range will not be paged If .Fa list is nonnull, it is initialized to a tailq of pages linked through the -.Dv pageq.queue +.Fa pageq.queue member of -.Dt struct vm_page , +.Vt struct vm_page , for the convenience of the caller. The caller is not transferred ownership of any part of .Fa list
CVS commit: src/share/man/man9
Module Name:src Committed By: uwe Date: Fri Jun 14 14:36:32 UTC 2024 Modified Files: src/share/man/man9: uvm_obj_wirepages.9 Log Message: uvm_obj_wirepages(9): fix a couple of markup glitches To generate a diff of this commit: cvs rdiff -u -r1.1 -r1.2 src/share/man/man9/uvm_obj_wirepages.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Tue Jun 4 21:43:13 UTC 2024 Modified Files: src/share/man/man9: bus_dma.9 Log Message: bus_dma(9): Document BUS_DMA_PREFETCHABLE. Like BUS_DMA_NOCACHE. Doesn't absolve you of the need for bus_dmamap_sync, but if you later pass the vaddr to bus_dmamap_load, the DMA map might notice the mapping is write-combining and use this to make bus_dmamap_sync cheaper. PR kern/58309 To generate a diff of this commit: cvs rdiff -u -r1.68 -r1.69 src/share/man/man9/bus_dma.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Tue Jun 4 21:43:13 UTC 2024 Modified Files: src/share/man/man9: bus_dma.9 Log Message: bus_dma(9): Document BUS_DMA_PREFETCHABLE. Like BUS_DMA_NOCACHE. Doesn't absolve you of the need for bus_dmamap_sync, but if you later pass the vaddr to bus_dmamap_load, the DMA map might notice the mapping is write-combining and use this to make bus_dmamap_sync cheaper. PR kern/58309 To generate a diff of this commit: cvs rdiff -u -r1.68 -r1.69 src/share/man/man9/bus_dma.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/bus_dma.9 diff -u src/share/man/man9/bus_dma.9:1.68 src/share/man/man9/bus_dma.9:1.69 --- src/share/man/man9/bus_dma.9:1.68 Sat Feb 17 08:27:46 2024 +++ src/share/man/man9/bus_dma.9 Tue Jun 4 21:43:13 2024 @@ -1,4 +1,4 @@ -.\" $NetBSD: bus_dma.9,v 1.68 2024/02/17 08:27:46 skrll Exp $ +.\" $NetBSD: bus_dma.9,v 1.69 2024/06/04 21:43:13 riastradh Exp $ .\" .\" Copyright (c) 1996, 1997, 1998, 2001, 2005, 2006 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -717,9 +717,20 @@ function. This flag is a .Em hint to machine-dependent code. -If possible, map the uncached memory. +If possible, map the memory uncached. This flag may be useful in the case that the memory cache causes unexpected behavior of the device. +.Pp +Exclusive with +.Dv BUS_DMA_PREFETCHABLE . +.It Dv BUS_DMA_PREFETCHABLE +This flag is a +.Em hint +to machine-dependent code. +If possible, map the memory prefetchable/write-combining. +.Pp +Exclusive with +.Dv BUS_DMA_NOCACHE . .El .El .Pp
CVS commit: src/share/man/man9
Module Name:src Committed By: pgoyette Date: Thu May 23 06:35:45 UTC 2024 Modified Files: src/share/man/man9: versioningsyscalls.9 Log Message: s/and/an/ To generate a diff of this commit: cvs rdiff -u -r1.6 -r1.7 src/share/man/man9/versioningsyscalls.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/versioningsyscalls.9 diff -u src/share/man/man9/versioningsyscalls.9:1.6 src/share/man/man9/versioningsyscalls.9:1.7 --- src/share/man/man9/versioningsyscalls.9:1.6 Mon May 20 17:12:41 2024 +++ src/share/man/man9/versioningsyscalls.9 Thu May 23 06:35:45 2024 @@ -1,4 +1,4 @@ -.\" $NetBSD: versioningsyscalls.9,v 1.6 2024/05/20 17:12:41 christos Exp $ +.\" $NetBSD: versioningsyscalls.9,v 1.7 2024/05/23 06:35:45 pgoyette Exp $ .\" .\" Copyright (c) 2023 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -224,7 +224,7 @@ variable. .Ss Regenerating the system calls If versioning structs, then modify .Pa sys/kern/makesyscalls.sh -by adding and entry for +by adding an entry for .Ft struct my_structCNUM type to .Va uncompattypes .
CVS commit: src/share/man/man9
Module Name:src Committed By: pgoyette Date: Thu May 23 06:35:45 UTC 2024 Modified Files: src/share/man/man9: versioningsyscalls.9 Log Message: s/and/an/ To generate a diff of this commit: cvs rdiff -u -r1.6 -r1.7 src/share/man/man9/versioningsyscalls.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src
Committed By: christos
Date: Mon May 20 17:12:41 UTC 2024
Modified Files:
src/share/man/man9: versioningsyscalls.9
Log Message:
explain what the current and new numbering practice are.
To generate a diff of this commit:
cvs rdiff -u -r1.5 -r1.6 src/share/man/man9/versioningsyscalls.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/versioningsyscalls.9
diff -u src/share/man/man9/versioningsyscalls.9:1.5 src/share/man/man9/versioningsyscalls.9:1.6
--- src/share/man/man9/versioningsyscalls.9:1.5 Fri Jul 14 05:03:37 2023
+++ src/share/man/man9/versioningsyscalls.9 Mon May 20 13:12:41 2024
@@ -1,4 +1,4 @@
-.\" $NetBSD: versioningsyscalls.9,v 1.5 2023/07/14 09:03:37 rillig Exp $
+.\" $NetBSD: versioningsyscalls.9,v 1.6 2024/05/20 17:12:41 christos Exp $
.\"
.\" Copyright (c) 2023 The NetBSD Foundation, Inc.
.\" 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 June 23, 2023
+.Dd May 20, 2024
.Dt VERSIONINGSYSCALLS 9
.Os
.
@@ -89,7 +89,7 @@ The version of the syscall that will bec
.El
.Pp
Additionally,
-.Ar XYZ
+.Ar CNUM
always represents the last
.Nx
release where the current
@@ -115,6 +115,42 @@ will be versioned.
If not versioning a struct, passages that mention
.Ft my_struct
can be ignored.
+.Pp
+The syscall version suffix
+.Dv VNUM
+indicates the first release of
+.Nx
+the system call will appear in.
+The compat version
+.Dv CNUM
+is the last version of
+.Nx the old system call was used.
+Typically VNUM = CNUM + 1 .
+.Pp
+For example if you are versioning
+.Xr getcontext 2
+just after
+.Nx 11
+was released, and the original system call was called
+.Fn getcontext ,
+the system call will become
+.Fn __getcontext12
+and the compat entry point will become
+.Fn compat_11_getcontext .
+.Pp
+Next time
+.Xr getcontext 2
+needs versioning, for example just after
+.Nx 15
+was released, it will become
+.Fn __getcontext16
+and the compat entry will become
+.Fn compat_15___getcontext12 .
+.Pp
+Please note that the historical practice up to
+.Nx 11
+has been that the syscall suffix matched the version when the syscall
+was last used.
.
.Ss Versioning structs
To version
@@ -122,7 +158,7 @@ To version
first make a copy of
.Ft my_struct
renamed to
-.Ft my_structXYZ
+.Ft my_structCNUM
in an equivalent header in
.Pa sys/compat/sys .
After that, you can freely modify
@@ -131,14 +167,14 @@ as desired.
.
.Ss Versioning the entry point
The stub for the next version of the syscall will be
-.Fn __my_syscallXYZ ,
+.Fn __my_syscallVNUM ,
and will have entry point
-.Fn sys___my_syscallXYZ .
+.Fn sys___my_syscallVNUM .
.
.Ss Modifying syscalls.conf
.Pa sys/kern/syscalls.conf
may need to be modified to contain
-.Li compat_XYZ
+.Li compat_CNUM
in the
.Va compatopts
variable.
@@ -149,20 +185,20 @@ First, add the next syscall to
keeping
.Fn my_syscall
as the name, and set the (optional) compat field of the declaration to
-.Ar XYZ .
+.Ar CNUM .
.Pp
Next, modify the current version of the syscall, and replace the type
field
.Pq usually just Li STD
with
-.Dv COMPAT_XYZ MODULAR compat_XYZ .
+.Dv COMPAT_CNUM MODULAR compat_CNUM .
.Pp
The keyword
.Dv MODULAR
indicates that the system call can be part of a kernel module.
Even if the system call was not part of a module before, now it will be part
of the
-.Dv COMPAT_XYZ
+.Dv COMPAT_CNUM
module.
.Pp
Finally, if applicable, replace the types of the current and old versions of the
@@ -171,16 +207,16 @@ syscall with the compat type.
Overall, the final diff should look like
.Bd -literal
- 123 STD { int|sys||my_syscall(struct my_struct *ms); }
-+ 123 COMPAT_XYZ MODULAR compat_XYZ { int|sys||my_syscall(struct my_structXYZ *ms); }
++ 123 COMPAT_CNUM MODULAR compat_CNUM { int|sys||my_syscall(struct my_structCNUM *ms); }
\&...
-+ 456 STD { int|sys|XYZ|my_syscall(struct my_struct *ms); }
++ 456 STD { int|sys|VNUM|my_syscall(struct my_struct *ms); }
.Ed
.
.Ss Modifying Makefile.rump
If the current syscall is rump,
.Pa sys/rump/Makefile.rump
must contain
-.Ar XYZ
+.Ar CNUM
in the
.Dv RUMP_NBCOMPAT
variable.
@@ -189,7 +225,7 @@ variable.
If versioning structs, then modify
.Pa sys/kern/makesyscalls.sh
by adding and entry for
-.Ft struct my_structXYZ
+.Ft struct my_structCNUM
type to
.Va uncompattypes .
.Pp
@@ -223,26 +259,26 @@ and lives inside
.
.Ss Creating the compat current syscall
The compat version of the current syscall has entry point
-.Fn compat_XYZ_sys_my_syscall ,
+.Fn compat_CNUM_sys_my_syscall ,
and should be implemented in
-.Pa sys/compat/common/my_file_XYZ.c
+.Pa sys/compat/common/my_file_CNUM.c
with the same semantics as the current syscall.
Often this involves translating the arguments to the
CVS commit: src/share/man/man9
Module Name:src Committed By: christos Date: Mon May 20 17:12:41 UTC 2024 Modified Files: src/share/man/man9: versioningsyscalls.9 Log Message: explain what the current and new numbering practice are. To generate a diff of this commit: cvs rdiff -u -r1.5 -r1.6 src/share/man/man9/versioningsyscalls.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: christos Date: Tue May 7 15:40:15 UTC 2024 Modified Files: src/share/man/man9: ltsleep.9 Log Message: also mention kpause(9) here. To generate a diff of this commit: cvs rdiff -u -r1.19 -r1.20 src/share/man/man9/ltsleep.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: christos Date: Tue May 7 15:40:15 UTC 2024 Modified Files: src/share/man/man9: ltsleep.9 Log Message: also mention kpause(9) here. To generate a diff of this commit: cvs rdiff -u -r1.19 -r1.20 src/share/man/man9/ltsleep.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/ltsleep.9 diff -u src/share/man/man9/ltsleep.9:1.19 src/share/man/man9/ltsleep.9:1.20 --- src/share/man/man9/ltsleep.9:1.19 Thu Aug 27 10:14:00 2020 +++ src/share/man/man9/ltsleep.9 Tue May 7 11:40:15 2024 @@ -1,4 +1,4 @@ -.\" $NetBSD: ltsleep.9,v 1.19 2020/08/27 14:14:00 fcambus Exp $ +.\" $NetBSD: ltsleep.9,v 1.20 2024/05/07 15:40:15 christos Exp $ .\" .\" Copyright (c) 1996, 2002, 2007 The NetBSD Foundation, Inc. .\" 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 March 22, 2014 +.Dd May 7, 2024 .Dt LTSLEEP 9 .Os .Sh NAME @@ -270,6 +270,7 @@ require amending to remove .Xr sigaction 2 , .Xr condvar 9 , .Xr hz 9 , +.Xr kpause 9 , .Xr mutex 9 , .Xr rwlock 9 .Sh HISTORY
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Sat Mar 9 05:22:05 UTC 2024 Modified Files: src/share/man/man9: pmf.9 Log Message: pmf(9): Document the bug in pmf_device_register return type. PR kern/57575 To generate a diff of this commit: cvs rdiff -u -r1.22 -r1.23 src/share/man/man9/pmf.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/pmf.9 diff -u src/share/man/man9/pmf.9:1.22 src/share/man/man9/pmf.9:1.23 --- src/share/man/man9/pmf.9:1.22 Tue Mar 18 18:20:40 2014 +++ src/share/man/man9/pmf.9 Sat Mar 9 05:22:05 2024 @@ -1,4 +1,4 @@ -.\" $NetBSD: pmf.9,v 1.22 2014/03/18 18:20:40 riastradh Exp $ +.\" $NetBSD: pmf.9,v 1.23 2024/03/09 05:22:05 riastradh Exp $ .\" .\" Copyright (c) 2007 Jared D. McNeill .\" All rights reserved. @@ -24,7 +24,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd April 2, 2012 +.Dd March 9, 2024 .Dt PMF 9 .Os .Sh NAME @@ -161,9 +161,10 @@ is then it is assumed that device state does not need to be captured and resumed on a power transition. Bus and class-level power management will still be performed. -Returns -.Dv false -if there was an error. +.Pp +.Fn pmf_device_register +always returns true. +Callers should ignore the return value. .It Fn pmf_device_register1 "dev" "suspend" "resume" "shutdown" Like .Fn pmf_device_register , @@ -184,6 +185,10 @@ should return on success and .Dv false on failure. +.Pp +.Fn pmf_device_register1 +always returns true. +Callers should ignore the return value. .It Fn pmf_device_deregister "dev" Deregister a device with the power management framework. .It Fn pmf_device_suspend "dev" "qual" @@ -296,3 +301,10 @@ framework appeared in .Sh AUTHORS .An Jared D. McNeill Aq Mt jmcne...@netbsd.org .An Joerg Sonnenberger Aq Mt jo...@netbsd.org +.Sh BUGS +.Fn pmf_device_register +and +.Fn pmf_device_register1 +never fail and should return void, but until all callers are updated to +ignore the return value, they must continue to return bool: +.Lk "https://gnats.NetBSD.org/57575; "PR kern/57575"
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Sat Mar 9 05:22:05 UTC 2024 Modified Files: src/share/man/man9: pmf.9 Log Message: pmf(9): Document the bug in pmf_device_register return type. PR kern/57575 To generate a diff of this commit: cvs rdiff -u -r1.22 -r1.23 src/share/man/man9/pmf.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: skrll Date: Sat Feb 17 08:27:46 UTC 2024 Modified Files: src/share/man/man9: bus_dma.9 Log Message: Steal the sync operation descriptions from FreeBSD and improve other wording in this area. Inspired by jmcneill@ To generate a diff of this commit: cvs rdiff -u -r1.67 -r1.68 src/share/man/man9/bus_dma.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: skrll Date: Sat Feb 17 08:27:46 UTC 2024 Modified Files: src/share/man/man9: bus_dma.9 Log Message: Steal the sync operation descriptions from FreeBSD and improve other wording in this area. Inspired by jmcneill@ To generate a diff of this commit: cvs rdiff -u -r1.67 -r1.68 src/share/man/man9/bus_dma.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/bus_dma.9 diff -u src/share/man/man9/bus_dma.9:1.67 src/share/man/man9/bus_dma.9:1.68 --- src/share/man/man9/bus_dma.9:1.67 Sat Jan 22 15:16:37 2022 +++ src/share/man/man9/bus_dma.9 Sat Feb 17 08:27:46 2024 @@ -1,4 +1,4 @@ -.\" $NetBSD: bus_dma.9,v 1.67 2022/01/22 15:16:37 skrll Exp $ +.\" $NetBSD: bus_dma.9,v 1.68 2024/02/17 08:27:46 skrll Exp $ .\" .\" Copyright (c) 1996, 1997, 1998, 2001, 2005, 2006 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -28,7 +28,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd January 22, 2022 +.Dd February 17, 2024 .Dt BUS_DMA 9 .Os .Sh NAME @@ -436,14 +436,19 @@ One or more synchronization operation to The following DMA synchronization operations are defined: .Bl -tag -width BUS_DMASYNC_POSTWRITE -compact .It Dv BUS_DMASYNC_PREREAD -Perform any pre-read DMA cache and/or bounce operations. +Perform any synchronization required prior to an update of host memory by the +device. .It Dv BUS_DMASYNC_POSTREAD -Perform any post-read DMA cache and/or bounce operations. +Perform any synchronization required after an update of host memory by the +device and prior to CPU access to host memory. .It Dv BUS_DMASYNC_PREWRITE -Perform any pre-write DMA cache and/or bounce operations. +Perform any synchronization required after an update of host memory by the CPU +and prior to device access to host memory. .It Dv BUS_DMASYNC_POSTWRITE -Perform any post-write DMA cache and/or bounce operations. +Perform any synchronization required after device access to host memory. .El +where each operation may involve cache flush/invalidation, bounce buffer +copying, and/or memory barriers. .Pp More than one operation may performed in a given synchronization call. Mixing of
CVS commit: src/share/man/man9
Module Name:src Committed By: mrg Date: Tue Oct 17 03:12:35 UTC 2023 Modified Files: src/share/man/man9: usbnet.9 Log Message: fix a typo: s/usbent_set_link/usbnet_set_link/. To generate a diff of this commit: cvs rdiff -u -r1.20 -r1.21 src/share/man/man9/usbnet.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/usbnet.9 diff -u src/share/man/man9/usbnet.9:1.20 src/share/man/man9/usbnet.9:1.21 --- src/share/man/man9/usbnet.9:1.20 Sat Aug 20 23:50:41 2022 +++ src/share/man/man9/usbnet.9 Tue Oct 17 03:12:35 2023 @@ -1,4 +1,4 @@ -.\" $NetBSD: usbnet.9,v 1.20 2022/08/20 23:50:41 riastradh Exp $ +.\" $NetBSD: usbnet.9,v 1.21 2023/10/17 03:12:35 mrg Exp $ .\" .\" Copyright (c) 2019 Matthew R. Green .\" All rights reserved. @@ -795,7 +795,7 @@ only code that inspects the result of th .It Common errors It's common to forget to set link active on devices with MII. Be sure to call -.Fn usbent_set_link +.Fn usbnet_set_link during any status change event. .Pp Many locking issues are hidden without
CVS commit: src/share/man/man9
Module Name:src Committed By: mrg Date: Tue Oct 17 03:12:35 UTC 2023 Modified Files: src/share/man/man9: usbnet.9 Log Message: fix a typo: s/usbent_set_link/usbnet_set_link/. To generate a diff of this commit: cvs rdiff -u -r1.20 -r1.21 src/share/man/man9/usbnet.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: ad Date: Thu Sep 7 20:01:43 UTC 2023 Modified Files: src/share/man/man9: condvar.9 Log Message: Permit calling cv_signal()/cv_broadcast() after mutex release. To generate a diff of this commit: cvs rdiff -u -r1.30 -r1.31 src/share/man/man9/condvar.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: ad Date: Thu Sep 7 20:01:43 UTC 2023 Modified Files: src/share/man/man9: condvar.9 Log Message: Permit calling cv_signal()/cv_broadcast() after mutex release. To generate a diff of this commit: cvs rdiff -u -r1.30 -r1.31 src/share/man/man9/condvar.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/condvar.9 diff -u src/share/man/man9/condvar.9:1.30 src/share/man/man9/condvar.9:1.31 --- src/share/man/man9/condvar.9:1.30 Thu Aug 27 14:14:00 2020 +++ src/share/man/man9/condvar.9 Thu Sep 7 20:01:43 2023 @@ -1,6 +1,6 @@ -.\" $NetBSD: condvar.9,v 1.30 2020/08/27 14:14:00 fcambus Exp $ +.\" $NetBSD: condvar.9,v 1.31 2023/09/07 20:01:43 ad Exp $ .\" -.\" Copyright (c) 2006, 2007, 2008, 2020 The NetBSD Foundation, Inc. +.\" Copyright (c) 2006, 2007, 2008, 2020, 2023 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation @@ -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 May 2, 2020 +.Dd September 7, 2023 .Dt CONDVAR 9 .Os .Sh NAME @@ -265,10 +265,12 @@ LWP may be awoken. This can be used to avoid a "thundering herd" problem, where a large number of LWPs are awoken following an event, but only one LWP can process the event. +.Pp The mutex passed to the wait function .Po Fa mtx Pc -must also be held when calling -.Fn cv_signal . +should be held or have been released immediately before +.Fn cv_signal +is called. .Pp (Note that .Fn cv_signal @@ -277,10 +279,14 @@ sense to LWPs waiting on a CV.) .It Fn cv_broadcast "cv" .Pp Awaken all LWPs waiting on the specified condition variable. -The mutex passed to the wait function +.Pp +As with +.Fn cv_signal , +the mutex passed to the wait function .Po Fa mtx Pc -must also be held when calling -.Fn cv_broadcast . +should be held or have been released immediately before +.Fn cv_broadcast +is called. .It Fn cv_has_waiters "cv" .Pp Return
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Wed Aug 2 06:24:46 UTC 2023 Modified Files: src/share/man/man9: percpu.9 Log Message: percpu(9): percpu_create ctor may be called later, not synchronously. To generate a diff of this commit: cvs rdiff -u -r1.15 -r1.16 src/share/man/man9/percpu.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/percpu.9 diff -u src/share/man/man9/percpu.9:1.15 src/share/man/man9/percpu.9:1.16 --- src/share/man/man9/percpu.9:1.15 Fri Feb 7 15:11:46 2020 +++ src/share/man/man9/percpu.9 Wed Aug 2 06:24:46 2023 @@ -1,4 +1,4 @@ -.\" $NetBSD: percpu.9,v 1.15 2020/02/07 15:11:46 wiz Exp $ +.\" $NetBSD: percpu.9,v 1.16 2023/08/02 06:24:46 riastradh Exp $ .\" .\" Copyright (c) 2010 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -94,15 +94,18 @@ returns a handle for the per-CPU storage .It Fn percpu_create "size" "ctor" "dtor" "arg" Like .Fn percpu_alloc , -but before returning, for each CPU, call -.Fn "(*ctor)" p arg ci -in the current thread, where +but before any access to the storage on any CPU, arrange to call +.Fn "(*ctor)" p arg ci , +where .Fa p is the pointer to that CPU's storage and .Fa ci is the .Vt "struct cpu_info *" for that CPU. +This may happen synchronously in +.Fn percpu_create +or when a CPU is attached later. Further, arrange that .Fn percpu_free will do the same with
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Wed Aug 2 06:24:46 UTC 2023 Modified Files: src/share/man/man9: percpu.9 Log Message: percpu(9): percpu_create ctor may be called later, not synchronously. To generate a diff of this commit: cvs rdiff -u -r1.15 -r1.16 src/share/man/man9/percpu.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: rillig Date: Fri Jul 14 09:03:37 UTC 2023 Modified Files: src/share/man/man9: versioningsyscalls.9 Log Message: versioningsyscalls.9: fix typo To generate a diff of this commit: cvs rdiff -u -r1.4 -r1.5 src/share/man/man9/versioningsyscalls.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/versioningsyscalls.9 diff -u src/share/man/man9/versioningsyscalls.9:1.4 src/share/man/man9/versioningsyscalls.9:1.5 --- src/share/man/man9/versioningsyscalls.9:1.4 Mon Jul 10 23:55:13 2023 +++ src/share/man/man9/versioningsyscalls.9 Fri Jul 14 09:03:37 2023 @@ -1,4 +1,4 @@ -.\" $NetBSD: versioningsyscalls.9,v 1.4 2023/07/10 23:55:13 uwe Exp $ +.\" $NetBSD: versioningsyscalls.9,v 1.5 2023/07/14 09:03:37 rillig Exp $ .\" .\" Copyright (c) 2023 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -277,7 +277,7 @@ my_file_XYZ_fini(void) .Pp Finally, .Pa sys/compat/common/compat_XYZ_mod.c -needs to be be modified to have its +needs to be modified to have its .Fn compat_XYZ_init and .Fn compat_XYZ_fini
CVS commit: src/share/man/man9
Module Name:src Committed By: rillig Date: Fri Jul 14 09:03:37 UTC 2023 Modified Files: src/share/man/man9: versioningsyscalls.9 Log Message: versioningsyscalls.9: fix typo To generate a diff of this commit: cvs rdiff -u -r1.4 -r1.5 src/share/man/man9/versioningsyscalls.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: uwe Date: Mon Jul 10 23:55:14 UTC 2023 Modified Files: src/share/man/man9: versioningsyscalls.9 Log Message: versioningsyscalls(9): wrap long line in the example To generate a diff of this commit: cvs rdiff -u -r1.3 -r1.4 src/share/man/man9/versioningsyscalls.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: uwe Date: Mon Jul 10 23:55:14 UTC 2023 Modified Files: src/share/man/man9: versioningsyscalls.9 Log Message: versioningsyscalls(9): wrap long line in the example To generate a diff of this commit: cvs rdiff -u -r1.3 -r1.4 src/share/man/man9/versioningsyscalls.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/versioningsyscalls.9 diff -u src/share/man/man9/versioningsyscalls.9:1.3 src/share/man/man9/versioningsyscalls.9:1.4 --- src/share/man/man9/versioningsyscalls.9:1.3 Mon Jul 10 15:54:18 2023 +++ src/share/man/man9/versioningsyscalls.9 Mon Jul 10 23:55:13 2023 @@ -1,4 +1,4 @@ -.\" $NetBSD: versioningsyscalls.9,v 1.3 2023/07/10 15:54:18 christos Exp $ +.\" $NetBSD: versioningsyscalls.9,v 1.4 2023/07/10 23:55:13 uwe Exp $ .\" .\" Copyright (c) 2023 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -325,11 +325,12 @@ syscall will be Overall, .Pa lib/libc/compat/sys/compat_my_syscall.c must at the minimum include -.Bd -literal +.Bd -literal -offset indent #include __warn_references(my_syscall, -"warning: reference to compatibility my_syscall(); message on how to use the next my_syscall()"); +"warning: reference to compatibility my_syscall();" +" message on how to use the next my_syscall()"); int my_syscall()
CVS commit: src/share/man/man9
Module Name:src Committed By: christos Date: Mon Jul 10 15:54:18 UTC 2023 Modified Files: src/share/man/man9: versioningsyscalls.9 Log Message: Forgot to commit the expanded userland portion To generate a diff of this commit: cvs rdiff -u -r1.2 -r1.3 src/share/man/man9/versioningsyscalls.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src
Committed By: christos
Date: Mon Jul 10 15:54:18 UTC 2023
Modified Files:
src/share/man/man9: versioningsyscalls.9
Log Message:
Forgot to commit the expanded userland portion
To generate a diff of this commit:
cvs rdiff -u -r1.2 -r1.3 src/share/man/man9/versioningsyscalls.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/versioningsyscalls.9
diff -u src/share/man/man9/versioningsyscalls.9:1.2 src/share/man/man9/versioningsyscalls.9:1.3
--- src/share/man/man9/versioningsyscalls.9:1.2 Sat Jul 8 20:29:49 2023
+++ src/share/man/man9/versioningsyscalls.9 Mon Jul 10 11:54:18 2023
@@ -1,4 +1,4 @@
-.\" $NetBSD: versioningsyscalls.9,v 1.2 2023/07/09 00:29:49 uwe Exp $
+.\" $NetBSD: versioningsyscalls.9,v 1.3 2023/07/10 15:54:18 christos Exp $
.\"
.\" Copyright (c) 2023 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -301,9 +301,37 @@ constant or a
.Li #define .
.
.Ss libc
-A userland version of any old and current versions of the syscall should be
-implemented in terms of the next syscall in
-.Pa lib/libc/compat/sys
-and should contain an appropriate call to
+A userland version of any old and current versions of the syscall must be
+implemented.
+For the current syscall with stub
+.Fn my_syscall struct\ my_struct\ *ms
+in
+.Pa sys/sys/my_header.h ,
+an implementation of
+.Fn my_syscall
+must be written in
+.Pa lib/libc/compat/sys/compat_my_syscall.c .
+.Pp
+Additionally, a call to
.Fn __warn_references
-for old and current versions of the syscall.
+must be added in
+.Pa lib/libc/compat/sys/compat_my_syscall.c
+to warn of any uses of the compat syscall and mention how to use the next
+version of the syscall.
+In almost all cases the instructions on how to use the next version of the
+syscall will be
+.Dq include to generate correct reference .
+.Pp
+Overall,
+.Pa lib/libc/compat/sys/compat_my_syscall.c
+must at the minimum include
+.Bd -literal
+#include
+
+__warn_references(my_syscall,
+"warning: reference to compatibility my_syscall(); message on how to use the next my_syscall()");
+
+int
+my_syscall()
+{ /* Compat implementation goes here. */ }
+.Ed
CVS commit: src/share/man/man9
Module Name:src Committed By: uwe Date: Sun Jul 9 00:29:49 UTC 2023 Modified Files: src/share/man/man9: versioningsyscalls.9 Log Message: versioningsyscalls(9): markup fixes While here, fix the pasto for the new ino_t and time_t size. To generate a diff of this commit: cvs rdiff -u -r1.1 -r1.2 src/share/man/man9/versioningsyscalls.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src
Committed By: uwe
Date: Sun Jul 9 00:29:49 UTC 2023
Modified Files:
src/share/man/man9: versioningsyscalls.9
Log Message:
versioningsyscalls(9): markup fixes
While here, fix the pasto for the new ino_t and time_t size.
To generate a diff of this commit:
cvs rdiff -u -r1.1 -r1.2 src/share/man/man9/versioningsyscalls.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/versioningsyscalls.9
diff -u src/share/man/man9/versioningsyscalls.9:1.1 src/share/man/man9/versioningsyscalls.9:1.2
--- src/share/man/man9/versioningsyscalls.9:1.1 Sat Jul 8 16:14:11 2023
+++ src/share/man/man9/versioningsyscalls.9 Sun Jul 9 00:29:49 2023
@@ -1,4 +1,4 @@
-.\" $NetBSD: versioningsyscalls.9,v 1.1 2023/07/08 16:14:11 christos Exp $
+.\" $NetBSD: versioningsyscalls.9,v 1.2 2023/07/09 00:29:49 uwe Exp $
.\"
.\" Copyright (c) 2023 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -28,11 +28,13 @@
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd June 23, 2023
-.Dt versioningsyscalls 9
+.Dt VERSIONINGSYSCALLS 9
.Os
+.
.Sh NAME
.Nm versioningsyscalls
.Nd guide on versioning syscalls
+.
.Sh DESCRIPTION
.Nx
has the ability to change the ABI of a syscall whilst retaining backwards
@@ -45,18 +47,18 @@ to move from 16 bits to 32 bits,
.Ft ino_t
and
.Ft time_t
-to move from 16 bits to 32 bits and
-adding fields to
+to move from 32 bits to 64 bits,
+and adding fields to
.Ft struct kevent
without disturbing existing binaries.
To achieve this both kernel and userland changes are required.
.Pp
In the kernel, a new syscall is added with a new ABI, and the old syscall
is retained and moved to a new location that holds the compatibility syscalls
-.Pa ( src/sys/compat ) .
+.Pq Pa src/sys/compat .
Kernels can be compiled with or without backwards compatibility syscalls.
See the
-.Li COMPAT_XX
+.Dv COMPAT_ Ns Ar XX
options in
.Xr options 4 .
.Pp
@@ -76,18 +78,18 @@ emulated because of the cost and safety
.Pp
To avoid confusion, the following words are used to disambiguate which version
of the system call is being described.
-.Bl -tag -offset indent -width "current"
-.It old
+.Bl -tag -offset indent -width Em
+.It Em old
Any previous versions of the syscall, which have already been versioned and
superseded by the current version of the syscall.
-.It current
+.It Em current
The version of the syscall currently in use.
-.It next
+.It Em next
The version of the syscall that will become standard in the next release.
.El
.Pp
Additionally,
-.Em XYZ
+.Ar XYZ
always represents the last
.Nx
release where the current
@@ -96,63 +98,71 @@ leading zero.
For example
.Nx 0.9
has
-.Li COMPAT_09
+.Dv COMPAT_09
whereas
.Nx 10.0
has
-.Li COMPAT_100 .
+.Dv COMPAT_100 .
+.
.Sh VERSIONING THE SYSCALL
This section describes what needs to be modified to add the new version of the
syscall.
It assumes the current version of the syscall is
-.Fn my_syscall struct\ my_struct\ *ms
+.Fn my_syscall "struct my_struct *ms"
and that
-.Li my_struct
+.Ft my_struct
will be versioned.
If not versioning a struct, passages that mention
-.Li my_struct
+.Ft my_struct
can be ignored.
+.
.Ss Versioning structs
To version
-.Li struct my_struct ,
+.Ft struct my_struct ,
first make a copy of
-.Li my_struct
+.Ft my_struct
renamed to
-.Li my_structXYZ
+.Ft my_structXYZ
in an equivalent header in
.Pa sys/compat/sys .
After that, you can freely modify
-.Li my_struct
+.Ft my_struct
as desired.
+.
.Ss Versioning the entry point
The stub for the next version of the syscall will be
.Fn __my_syscallXYZ ,
and will have entry point
.Fn sys___my_syscallXYZ .
+.
.Ss Modifying syscalls.conf
.Pa sys/kern/syscalls.conf
may need to be modified to contain
.Li compat_XYZ
in the
-.Li compatopts
-field.
+.Va compatopts
+variable.
+.
.Ss Modifying syscalls.master
First, add the next syscall to
.Pa sys/kern/syscalls.master
keeping
-.Li my_syscall
-as the name, and set the (optional) compat field of the declaration to XYZ.
+.Fn my_syscall
+as the name, and set the (optional) compat field of the declaration to
+.Ar XYZ .
.Pp
Next, modify the current version of the syscall, and replace the type
-field (usually just STD) with
-.Li COMPAT_XYZ MODULAR compat_XYZ .
+field
+.Pq usually just Li STD
+with
+.Dv COMPAT_XYZ MODULAR compat_XYZ .
.Pp
The keyword
-.Li MODULAR
+.Dv MODULAR
indicates that the system call can be part of a kernel module.
Even if the system call was not part of a module before, now it will be part
of the
-.Li COMPAT_XYZ
+.Dv COMPAT_XYZ
module.
.Pp
Finally, if applicable, replace the types of the current and old versions of the
@@ -162,27 +172,29 @@ Overall, the final diff should look like
.Bd -literal
- 123 STD { int|sys||my_syscall(struct my_struct *ms); }
+ 123 COMPAT_XYZ MODULAR compat_XYZ { int|sys||my_syscall(struct my_structXYZ *ms); }
CVS commit: src/share/man/man9
Module Name:src Committed By: uwe Date: Fri Jul 7 15:56:31 UTC 2023 Modified Files: src/share/man/man9: heartbeat.9 Log Message: heartbeat(9): markup fixes Use .Cd for options. Don't use the usual , which is superfluous in the man page. Paragraph break after the config section of synopsis, before the C API section. To generate a diff of this commit: cvs rdiff -u -r1.4 -r1.5 src/share/man/man9/heartbeat.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/heartbeat.9 diff -u src/share/man/man9/heartbeat.9:1.4 src/share/man/man9/heartbeat.9:1.5 --- src/share/man/man9/heartbeat.9:1.4 Fri Jul 7 13:19:30 2023 +++ src/share/man/man9/heartbeat.9 Fri Jul 7 15:56:31 2023 @@ -1,4 +1,4 @@ -.\" $NetBSD: heartbeat.9,v 1.4 2023/07/07 13:19:30 riastradh Exp $ +.\" $NetBSD: heartbeat.9,v 1.5 2023/07/07 15:56:31 uwe Exp $ .\" .\" Copyright (c) 2023 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -33,8 +33,9 @@ .Nd periodic checks to ensure CPUs are making progress .\" .Sh SYNOPSIS -.Fd "options HEARTBEAT" -.Fd "options HEARTBEAT_MAX_PERIOD_DEFAULT=15" +.Cd "options HEARTBEAT" +.Cd "options HEARTBEAT_MAX_PERIOD_DEFAULT=15" +.Pp .\" .In sys/heartbeat.h .\"
CVS commit: src/share/man/man9
Module Name:src Committed By: uwe Date: Fri Jul 7 15:56:31 UTC 2023 Modified Files: src/share/man/man9: heartbeat.9 Log Message: heartbeat(9): markup fixes Use .Cd for options. Don't use the usual , which is superfluous in the man page. Paragraph break after the config section of synopsis, before the C API section. To generate a diff of this commit: cvs rdiff -u -r1.4 -r1.5 src/share/man/man9/heartbeat.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Fri Jul 7 13:19:30 UTC 2023 Modified Files: src/share/man/man9: heartbeat.9 Log Message: heartbeat(9): Fix grammaro in man page. To generate a diff of this commit: cvs rdiff -u -r1.3 -r1.4 src/share/man/man9/heartbeat.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/heartbeat.9 diff -u src/share/man/man9/heartbeat.9:1.3 src/share/man/man9/heartbeat.9:1.4 --- src/share/man/man9/heartbeat.9:1.3 Fri Jul 7 13:15:00 2023 +++ src/share/man/man9/heartbeat.9 Fri Jul 7 13:19:30 2023 @@ -1,4 +1,4 @@ -.\" $NetBSD: heartbeat.9,v 1.3 2023/07/07 13:15:00 wiz Exp $ +.\" $NetBSD: heartbeat.9,v 1.4 2023/07/07 13:19:30 riastradh Exp $ .\" .\" Copyright (c) 2023 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -127,7 +127,7 @@ Called by .Xr hardclock 9 periodically. .It Fn heartbeat_dump -Print all the heartbeat counter, uptime cache, and uptime cache +Print each CPU's heartbeat counter, uptime cache, and uptime cache timestamp (in units of heartbeats) to the console. .Pp Can be invoked from
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Fri Jul 7 13:19:30 UTC 2023 Modified Files: src/share/man/man9: heartbeat.9 Log Message: heartbeat(9): Fix grammaro in man page. To generate a diff of this commit: cvs rdiff -u -r1.3 -r1.4 src/share/man/man9/heartbeat.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: wiz Date: Fri Jul 7 13:15:00 UTC 2023 Modified Files: src/share/man/man9: heartbeat.9 Log Message: Replace main(9) reference with code location To generate a diff of this commit: cvs rdiff -u -r1.2 -r1.3 src/share/man/man9/heartbeat.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: wiz Date: Fri Jul 7 13:15:00 UTC 2023 Modified Files: src/share/man/man9: heartbeat.9 Log Message: Replace main(9) reference with code location To generate a diff of this commit: cvs rdiff -u -r1.2 -r1.3 src/share/man/man9/heartbeat.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/heartbeat.9 diff -u src/share/man/man9/heartbeat.9:1.2 src/share/man/man9/heartbeat.9:1.3 --- src/share/man/man9/heartbeat.9:1.2 Fri Jul 7 12:59:45 2023 +++ src/share/man/man9/heartbeat.9 Fri Jul 7 13:15:00 2023 @@ -1,4 +1,4 @@ -.\" $NetBSD: heartbeat.9,v 1.2 2023/07/07 12:59:45 wiz Exp $ +.\" $NetBSD: heartbeat.9,v 1.3 2023/07/07 13:15:00 wiz Exp $ .\" .\" Copyright (c) 2023 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -143,7 +143,9 @@ marked online. Start monitoring heartbeats systemwide. .Pp Called by -.Xr main 9 +.Fn main +in +.Pa sys/kern/init_main.c as soon as soft interrupts can be established. .It Fn heartbeat_suspend Suspend heartbeat monitoring of the current CPU.
CVS commit: src/share/man/man9
Module Name:src Committed By: wiz Date: Fri Jul 7 12:59:45 UTC 2023 Modified Files: src/share/man/man9: heartbeat.9 Log Message: Sort SEE ALSO To generate a diff of this commit: cvs rdiff -u -r1.1 -r1.2 src/share/man/man9/heartbeat.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/heartbeat.9 diff -u src/share/man/man9/heartbeat.9:1.1 src/share/man/man9/heartbeat.9:1.2 --- src/share/man/man9/heartbeat.9:1.1 Fri Jul 7 12:34:49 2023 +++ src/share/man/man9/heartbeat.9 Fri Jul 7 12:59:45 2023 @@ -1,4 +1,4 @@ -.\" $NetBSD: heartbeat.9,v 1.1 2023/07/07 12:34:49 riastradh Exp $ +.\" $NetBSD: heartbeat.9,v 1.2 2023/07/07 12:59:45 wiz Exp $ .\" .\" Copyright (c) 2023 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -159,8 +159,8 @@ subsystem is implemented in .Pa sys/kern/kern_heartbeat.c . .\" .Sh SEE ALSO -.Xr wdogctl 8 , -.Xr swwdog 4 +.Xr swwdog 4 , +.Xr wdogctl 8 .\" .Sh HISTORY The
CVS commit: src/share/man/man9
Module Name:src Committed By: wiz Date: Fri Jul 7 12:59:45 UTC 2023 Modified Files: src/share/man/man9: heartbeat.9 Log Message: Sort SEE ALSO To generate a diff of this commit: cvs rdiff -u -r1.1 -r1.2 src/share/man/man9/heartbeat.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: uwe Date: Thu Apr 20 10:43:17 UTC 2023 Modified Files: src/share/man/man9: optstr.9 Log Message: optstr(9): markup fixes While here, wrap long .Fn lines for readability and make the optstr_get_item list compact. To generate a diff of this commit: cvs rdiff -u -r1.5 -r1.6 src/share/man/man9/optstr.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/optstr.9 diff -u src/share/man/man9/optstr.9:1.5 src/share/man/man9/optstr.9:1.6 --- src/share/man/man9/optstr.9:1.5 Thu Apr 20 09:06:02 2023 +++ src/share/man/man9/optstr.9 Thu Apr 20 10:43:17 2023 @@ -1,4 +1,4 @@ -.\" $NetBSD: optstr.9,v 1.5 2023/04/20 09:06:02 skrll Exp $ +.\" $NetBSD: optstr.9,v 1.6 2023/04/20 10:43:17 uwe Exp $ .\" .\" Copyright (c) 2006 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -30,6 +30,7 @@ .Dd May 20, 2023 .Dt OPTSTR 9 .Os +. .Sh NAME .Nm optstr_get , .Nm optstr_get_string , @@ -38,79 +39,110 @@ .Nm optstr_get_number_hex , .Nm optstr_get_macaddr .Nd Options string management +. .Sh SYNOPSIS .In sys/optstr.h +. .Ft bool -.Fn optstr_get "const char *optstr" "const char *key" "char *buf" "size_t bufsize" -.Ft bool -.Fn optstr_get_string "const char *optstr" "const char *key" "char **result" -.Ft bool -.Fn optstr_get_number "const char *optstr" "const char *key" "unsigned long *result" -.Ft bool -.Fn optstr_get_number_binary "const char *optstr" "const char *key" "unsigned long *result" -.Ft bool -.Fn optstr_get_number_hex "const char *optstr" "const char *key" "unsigned long *result" -.Ft bool -.Fn optstr_get_macaddr "const char *optstr" "const char *key" "uint8_t result[ETHER_ADDR_LEN]" +.Fo optstr_get +.Fa "const char *optstr" +.Fa "const char *key" +.Fa "char *buf" +.Fa "size_t bufsize" +.Fc +. +.Ft bool +.Fo optstr_get_string +.Fa "const char *optstr" +.Fa "const char *key" +.Fa "char **result" +.Fc +. +.Ft bool +.Fo optstr_get_number +.Fa "const char *optstr" +.Fa "const char *key" +.Fa "unsigned long *result" +.Fc +. +.Ft bool +.Fo optstr_get_number_binary +.Fa "const char *optstr" +.Fa "const char *key" +.Fa "unsigned long *result" +.Fc +. +.Ft bool +.Fo optstr_get_number_hex +.Fa "const char *optstr" +.Fa "const char *key" +.Fa "unsigned long *result" +.Fc +. +.Ft bool +.Fo optstr_get_macaddr +.Fa "const char *optstr" +.Fa "const char *key" +.Fa "uint8_t result[ETHER_ADDR_LEN]" +.Fc +. .Sh DESCRIPTION An options string is a list of key/value pairs represented in textual form. Each pair is expressed as -.Sq 'key=value' +.Ar key\^ Ns Li = Ns Ar value and is separated from other pairs by one or more spaces. For example: -.Bd -literal -key1=value1 key2=value2 key3=value3 -.Ed +.Pp +.Dl key1=value1 key2=value2 key3=value3 .Pp Options strings are used to pass information between userland programs and the kernel in a binary-agnostic way. This makes them endianness and ABI independent. .Sh FUNCTIONS The following functions are provided to manage options strings: -.Bl -tag -width compact +.Bl -tag -width Fn .It Fn optstr_get "optstr" "key" "buf" "bufsize" Scans the -.Va optstr +.Fa optstr options string looking for the key -.Va key +.Fa key and stores its value in the buffer pointed to by -.Va buf +.Fa buf copying a maximum of -.Va bufsize +.Fa bufsize bytes. Returns -.Sq true +.Ql true if the key was found or -.Sq false +.Ql false otherwise, in which case -.Va buf +.Fa buf is left unmodified. .El .Pp The -.Fn optstr_get_ITEM +.Li optstr_get_ Ns Ar item family of functions provide the ability to scan for the key, and return the value converted to an appropriate type. .Pp -.Bl -tag -width compact +.Bl -tag -width Fn -compact .It Fn optstr_get_string "optstr" "key" "result" .It Fn optstr_get_number "optstr" "key" "result" .It Fn optstr_get_number_binary "optstr" "key" "result" .It Fn optstr_get_number_hex "optstr" "key" "result" .It Fn optstr_get_macaddr "optstr" "key" "result" -.Pp These functions scan the -.Va optstr +.Fa optstr options string looking for the key -.Va key +.Fa key and returns the key value converted as per the function name in -.Va result . +.Fa result . All functions return -.Sq true +.Ql true if the key was found or -.Sq false +.Ql false otherwise, in which case -.Va result +.Fa result is left unmodified. .El .Sh CODE REFERENCES
CVS commit: src/share/man/man9
Module Name:src Committed By: uwe Date: Thu Apr 20 10:43:17 UTC 2023 Modified Files: src/share/man/man9: optstr.9 Log Message: optstr(9): markup fixes While here, wrap long .Fn lines for readability and make the optstr_get_item list compact. To generate a diff of this commit: cvs rdiff -u -r1.5 -r1.6 src/share/man/man9/optstr.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: skrll Date: Thu Apr 20 09:06:02 UTC 2023 Modified Files: src/share/man/man9: optstr.9 Log Message: Update to include value conversion routines. To generate a diff of this commit: cvs rdiff -u -r1.4 -r1.5 src/share/man/man9/optstr.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: skrll Date: Thu Apr 20 09:06:02 UTC 2023 Modified Files: src/share/man/man9: optstr.9 Log Message: Update to include value conversion routines. To generate a diff of this commit: cvs rdiff -u -r1.4 -r1.5 src/share/man/man9/optstr.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/optstr.9 diff -u src/share/man/man9/optstr.9:1.4 src/share/man/man9/optstr.9:1.5 --- src/share/man/man9/optstr.9:1.4 Wed Apr 30 13:10:58 2008 +++ src/share/man/man9/optstr.9 Thu Apr 20 09:06:02 2023 @@ -1,4 +1,4 @@ -.\" $NetBSD: optstr.9,v 1.4 2008/04/30 13:10:58 martin Exp $ +.\" $NetBSD: optstr.9,v 1.5 2023/04/20 09:06:02 skrll Exp $ .\" .\" Copyright (c) 2006 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -27,16 +27,31 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd August 11, 2007 +.Dd May 20, 2023 .Dt OPTSTR 9 .Os .Sh NAME -.Nm optstr_get +.Nm optstr_get , +.Nm optstr_get_string , +.Nm optstr_get_number , +.Nm optstr_get_number_binary , +.Nm optstr_get_number_hex , +.Nm optstr_get_macaddr .Nd Options string management .Sh SYNOPSIS .In sys/optstr.h .Ft bool .Fn optstr_get "const char *optstr" "const char *key" "char *buf" "size_t bufsize" +.Ft bool +.Fn optstr_get_string "const char *optstr" "const char *key" "char **result" +.Ft bool +.Fn optstr_get_number "const char *optstr" "const char *key" "unsigned long *result" +.Ft bool +.Fn optstr_get_number_binary "const char *optstr" "const char *key" "unsigned long *result" +.Ft bool +.Fn optstr_get_number_hex "const char *optstr" "const char *key" "unsigned long *result" +.Ft bool +.Fn optstr_get_macaddr "const char *optstr" "const char *key" "uint8_t result[ETHER_ADDR_LEN]" .Sh DESCRIPTION An options string is a list of key/value pairs represented in textual form. Each pair is expressed as @@ -71,6 +86,33 @@ otherwise, in which case .Va buf is left unmodified. .El +.Pp +The +.Fn optstr_get_ITEM +family of functions provide the ability to scan for the key, and +return the value converted to an appropriate type. +.Pp +.Bl -tag -width compact +.It Fn optstr_get_string "optstr" "key" "result" +.It Fn optstr_get_number "optstr" "key" "result" +.It Fn optstr_get_number_binary "optstr" "key" "result" +.It Fn optstr_get_number_hex "optstr" "key" "result" +.It Fn optstr_get_macaddr "optstr" "key" "result" +.Pp +These functions scan the +.Va optstr +options string looking for the key +.Va key +and returns the key value converted as per the function name in +.Va result . +All functions return +.Sq true +if the key was found or +.Sq false +otherwise, in which case +.Va result +is left unmodified. +.El .Sh CODE REFERENCES The options string management functions are implemented within the files .Pa sys/kern/subr_optstr.c
CVS commit: src/share/man/man9
Module Name:src Committed By: thorpej Date: Mon Mar 6 12:25:06 UTC 2023 Modified Files: src/share/man/man9: portfeatures.9 Log Message: Document __HAVE_UCAS_FULL and __HAVE_UCAS_MP. To generate a diff of this commit: cvs rdiff -u -r1.2 -r1.3 src/share/man/man9/portfeatures.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/portfeatures.9 diff -u src/share/man/man9/portfeatures.9:1.2 src/share/man/man9/portfeatures.9:1.3 --- src/share/man/man9/portfeatures.9:1.2 Mon Mar 6 01:03:45 2023 +++ src/share/man/man9/portfeatures.9 Mon Mar 6 12:25:06 2023 @@ -1,4 +1,4 @@ -.\" $NetBSD: portfeatures.9,v 1.2 2023/03/06 01:03:45 wiz Exp $ +.\" $NetBSD: portfeatures.9,v 1.3 2023/03/06 12:25:06 thorpej Exp $ .\" .\" Copyright (c) The NetBSD Foundation, Inc. .\" All rights reserved. @@ -75,4 +75,18 @@ interlock. .\" - .It Dv __HAVE_SPIN_MUTEX_STUBS Pq Xr mutex 9 The port provides fast path enter and exit stubs for spin mutexes. +. +.\" - +.It Dv __HAVE_UCAS_FULL Pq Xr ucas 9 +The port provides a full implementation of the low-level primitives +required for atomic compare-and-swap operations to user-space addresses. +. +.\" - +.It Dv __HAVE_UCAS_MP Pq Xr ucas 9 +The port does not provide a full implementation of the low-level +primitives required for atomic compare-and-swap operations to user-space +addresses, but does provide an implementation of those primitives that +can be used if +.Pq and only if +the system has more than one processor. .El
CVS commit: src/share/man/man9
Module Name:src Committed By: thorpej Date: Mon Mar 6 12:25:06 UTC 2023 Modified Files: src/share/man/man9: portfeatures.9 Log Message: Document __HAVE_UCAS_FULL and __HAVE_UCAS_MP. To generate a diff of this commit: cvs rdiff -u -r1.2 -r1.3 src/share/man/man9/portfeatures.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: wiz Date: Mon Mar 6 01:03:45 UTC 2023 Modified Files: src/share/man/man9: portfeatures.9 Log Message: fix typos To generate a diff of this commit: cvs rdiff -u -r1.1 -r1.2 src/share/man/man9/portfeatures.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/portfeatures.9 diff -u src/share/man/man9/portfeatures.9:1.1 src/share/man/man9/portfeatures.9:1.2 --- src/share/man/man9/portfeatures.9:1.1 Mon Mar 6 00:49:31 2023 +++ src/share/man/man9/portfeatures.9 Mon Mar 6 01:03:45 2023 @@ -1,4 +1,4 @@ -.\" $NetBSD: portfeatures.9,v 1.1 2023/03/06 00:49:31 uwe Exp $ +.\" $NetBSD: portfeatures.9,v 1.2 2023/03/06 01:03:45 wiz Exp $ .\" .\" Copyright (c) The NetBSD Foundation, Inc. .\" All rights reserved. @@ -32,9 +32,9 @@ .Nd the __HAVEs (\|and the have nots\|) . .Sh DESCRIPTION -Machine-independent kernel code adapts to differeces in hardware +Machine-independent kernel code adapts to differences in hardware capabilities provided by the machine-dependent parts of the kernel. -A port declares its capabilities by definining various +A port declares its capabilities by defining various .Li __HAVE_ Ns Ar feature macros. This manual page provides an index of such macros with pointers to
CVS commit: src/share/man/man9
Module Name:src Committed By: wiz Date: Mon Mar 6 01:03:45 UTC 2023 Modified Files: src/share/man/man9: portfeatures.9 Log Message: fix typos To generate a diff of this commit: cvs rdiff -u -r1.1 -r1.2 src/share/man/man9/portfeatures.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Thu Feb 23 03:03:23 UTC 2023 Modified Files: src/share/man/man9: pcq.9 Log Message: pcq(9): Document memory ordering guarantees. To generate a diff of this commit: cvs rdiff -u -r1.8 -r1.9 src/share/man/man9/pcq.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/pcq.9 diff -u src/share/man/man9/pcq.9:1.8 src/share/man/man9/pcq.9:1.9 --- src/share/man/man9/pcq.9:1.8 Thu Feb 8 09:03:23 2018 +++ src/share/man/man9/pcq.9 Thu Feb 23 03:03:23 2023 @@ -1,4 +1,4 @@ -.\" $NetBSD: pcq.9,v 1.8 2018/02/08 09:03:23 dholland Exp $ +.\" $NetBSD: pcq.9,v 1.9 2023/02/23 03:03:23 riastradh Exp $ .\" .\" Copyright (c) 2010 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -118,6 +118,63 @@ otherwise, return The item must not have the value of .Dv NULL . .El +.Ss Memory ordering +Any memory operations sequenced before +.Fn pcq_put +of an item in one thread happen before all memory operations with data +dependencies on the item returned by +.Fn pcq_get +or +.Fn pcq_peek +in another thread. +For example: +.Bd -literal -offset indent +int mumble; + +/* producer */ +mumble = 42; // A +foo->x = 123; // B +refcnt = foo->refcnt; // C +pcq_put(pcq, foo); +KASSERT(refcnt == 0); + +/* consumer */ +foo = pcq_get(pcq); +if (foo == NULL) + return; +atomic_inc_uint(>refcnt); // D +x = foo->x; // E +if (x == 123) + KASSERT(mumble == 42); // F +.Ed +.Pp +In this example, memory operations B and C happen-before D and E. +However, no ordering is guaranteed for A or F relative to any other +memory operations, because the memory location of +.Fa mumble +is independent of the pointer +.Fa foo +returned by +.Fn pcq_get . +.Pp +If you must guarantee A happens before F, then on the consumer side, +after +.Fn pcq_get +or +.Fn pcq_peek , +you can call +.Fn membar_acquire +to turn it into an acquire operation instead of a consume operation; +.Fn pcq_put +serves as the matching release operation. +.Po +This is a little dicey. +Perhaps there should be separate +.Fn pcq_peek_acq +and +.Fn pcq_get_acq +operations if this semantics is necessary. +.Pc .Sh CODE REFERENCES The .Nm
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Thu Feb 23 03:03:23 UTC 2023 Modified Files: src/share/man/man9: pcq.9 Log Message: pcq(9): Document memory ordering guarantees. To generate a diff of this commit: cvs rdiff -u -r1.8 -r1.9 src/share/man/man9/pcq.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: pgoyette Date: Thu Feb 16 04:58:21 UTC 2023 Modified Files: src/share/man/man9: vnfileops.9 Log Message: Add a period at the end of a sentence. To generate a diff of this commit: cvs rdiff -u -r1.16 -r1.17 src/share/man/man9/vnfileops.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/vnfileops.9 diff -u src/share/man/man9/vnfileops.9:1.16 src/share/man/man9/vnfileops.9:1.17 --- src/share/man/man9/vnfileops.9:1.16 Thu Dec 2 12:54:13 2010 +++ src/share/man/man9/vnfileops.9 Thu Feb 16 04:58:21 2023 @@ -1,4 +1,4 @@ -.\" $NetBSD: vnfileops.9,v 1.16 2010/12/02 12:54:13 wiz Exp $ +.\" $NetBSD: vnfileops.9,v 1.17 2023/02/16 04:58:21 pgoyette Exp $ .\" .\" Copyright (c) 2001, 2005, 2006 The NetBSD Foundation, Inc. .\" 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 April 9, 2008 +.Dd February 16, 2023 .Dt VNFILEOPS 9 .Os .Sh NAME @@ -103,7 +103,7 @@ The file is specified by .Fa fp . The argument .Fa l -is the calling lwp +is the calling lwp. .Fn vn_ioctl simply locks the vnode and invokes the vnode operation .Xr VOP_IOCTL 9
CVS commit: src/share/man/man9
Module Name:src Committed By: pgoyette Date: Thu Feb 16 04:58:21 UTC 2023 Modified Files: src/share/man/man9: vnfileops.9 Log Message: Add a period at the end of a sentence. To generate a diff of this commit: cvs rdiff -u -r1.16 -r1.17 src/share/man/man9/vnfileops.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: uwe Date: Thu Feb 2 14:09:52 UTC 2023 Modified Files: src/share/man/man9: devsw_attach.9 Log Message: devsw_attach(9): Use semantic markup instead of .Em To generate a diff of this commit: cvs rdiff -u -r1.5 -r1.6 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.5 src/share/man/man9/devsw_attach.9:1.6 --- src/share/man/man9/devsw_attach.9:1.5 Thu Feb 2 13:25:41 2023 +++ src/share/man/man9/devsw_attach.9 Thu Feb 2 14:09:52 2023 @@ -1,4 +1,4 @@ -.\" $NetBSD: devsw_attach.9,v 1.5 2023/02/02 13:25:41 pgoyette Exp $ +.\" $NetBSD: devsw_attach.9,v 1.6 2023/02/02 14:09:52 uwe Exp $ .\" .\" Copyright (c) 2015 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -73,11 +73,11 @@ .Sh DESCRIPTION If a device driver has character device interfaces accessed from userland, the driver must define a -.Em cdevsw +.Vt cdevsw structure. If the driver also has block device interfaces, the driver must additionally define a -.Em bdevsw +.Vt bdevsw structure. These structures are constant, and are defined within the .Xr driver 9 . @@ -85,54 +85,57 @@ These structures are constant, and are d For drivers which are included in the kernel via .Xr config 1 , the -.Em cdevsw +.Vt cdevsw and -.Em bdevsw +.Vt bdevsw structures are automatically linked into the configuration database. For drivers which are separately loaded, the .Fn devsw_attach function creates the necessary linkage and associates the -.Em cdev +.Fa cdev and optional -.Em bdev +.Fa bdev with the .Xr driver 9 . If there is no block device interface needed, -.Em bdev +.Fa bdev should be set to .Dv NULL and -.Em bmajor +.Fa bmajor to -.Dv \-1 . +.Dv NODEVMAJOR . The -.Em devname , +.Fa devname , major number, and device type (character or block) must correspond to the device file which will be opened by user programs. By passing -.Dv \-1 +.Dv NODEVMAJOR to the function for the -.Em cmajor +.Fa cmajor or -.Em bmajor , +.Fa bmajor , the major number can be automatically generated. -It can then be returned to userspace (for example, using -.Xr sysctl 8 ) +It can then be returned to userspace +.Po +for example, using +.Xr sysctl 8 +.Pc for creation of the device node. .Pp The .Fn devsw_detach function is used to detach the -.Em bdev +.Fa bdev and -.Em cdev +.Fa cdev structures. .Fn devsw_detach should be called before a loaded device driver is unloaded. The caller must ensure that there are no open instances of the device, and that the device's -.Fn d_open +.Fa d_open function will fail, before calling .Fn devsw_detach . .Pp @@ -141,22 +144,22 @@ The and .Fn cdevsw_lookup functions return -.Em "const struct bdevsw *" +.Vt "const struct bdevsw *" and -.Em "const struct cdevsw *" +.Vt "const struct cdevsw *" for the given -.Em dev . +.Fa dev . .Pp The .Fn bdevsw_lookup_major and .Fn cdevsw_lookup_major functions return -.Em "devmajor_t" +.Vt "devmajor_t" for the given -.Em "const struct bdevsw *" +.Vt "const struct bdevsw *" or -.Em "const struct cdevsw *" . +.Vt "const struct cdevsw *" . .Sh RETURN VALUES Upon successful completion, .Fn devsw_attach
CVS commit: src/share/man/man9
Module Name:src Committed By: uwe Date: Thu Feb 2 14:09:52 UTC 2023 Modified Files: src/share/man/man9: devsw_attach.9 Log Message: devsw_attach(9): Use semantic markup instead of .Em To generate a diff of this commit: cvs rdiff -u -r1.5 -r1.6 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.
CVS commit: src/share/man/man9
Module Name:src Committed By: pgoyette Date: Thu Feb 2 13:25:41 UTC 2023 Modified Files: src/share/man/man9: devsw_attach.9 Log Message: Fix markup. To generate a diff of this commit: cvs rdiff -u -r1.4 -r1.5 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.4 src/share/man/man9/devsw_attach.9:1.5 --- src/share/man/man9/devsw_attach.9:1.4 Mon Mar 28 12:33:20 2022 +++ src/share/man/man9/devsw_attach.9 Thu Feb 2 13:25:41 2023 @@ -1,4 +1,4 @@ -.\" $NetBSD: devsw_attach.9,v 1.4 2022/03/28 12:33:20 riastradh Exp $ +.\" $NetBSD: devsw_attach.9,v 1.5 2023/02/02 13:25:41 pgoyette Exp $ .\" .\" Copyright (c) 2015 The NetBSD Foundation, Inc. .\" 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 January 11, 2022 +.Dd February 2, 2023 .Dt DEVSW 9 .Os .Sh NAME @@ -133,8 +133,8 @@ should be called before a loaded device The caller must ensure that there are no open instances of the device, and that the device's .Fn d_open -function will fail, before calling. -Fn devsw_detach . +function will fail, before calling +.Fn devsw_detach . .Pp The .Fn bdevsw_lookup
CVS commit: src/share/man/man9
Module Name:src Committed By: pgoyette Date: Thu Feb 2 13:25:41 UTC 2023 Modified Files: src/share/man/man9: devsw_attach.9 Log Message: Fix markup. To generate a diff of this commit: cvs rdiff -u -r1.4 -r1.5 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.
CVS commit: src/share/man/man9
Module Name:src Committed By: gutteridge Date: Wed Feb 1 03:27:46 UTC 2023 Modified Files: src/share/man/man9: mutex.9 Log Message: mutex.9: add a small detail to the history section To generate a diff of this commit: cvs rdiff -u -r1.34 -r1.35 src/share/man/man9/mutex.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/mutex.9 diff -u src/share/man/man9/mutex.9:1.34 src/share/man/man9/mutex.9:1.35 --- src/share/man/man9/mutex.9:1.34 Mon Dec 19 00:41:45 2022 +++ src/share/man/man9/mutex.9 Wed Feb 1 03:27:45 2023 @@ -1,4 +1,4 @@ -.\" $NetBSD: mutex.9,v 1.34 2022/12/19 00:41:45 uwe Exp $ +.\" $NetBSD: mutex.9,v 1.35 2023/02/01 03:27:45 gutteridge Exp $ .\" .\" Copyright (c) 2007, 2009 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -314,3 +314,6 @@ code must provide to support mutexes. .Sh HISTORY The mutex primitives first appeared in .Nx 5.0 . +.Fn mutex_ownable +first appeared in +.Nx 8.0 .
CVS commit: src/share/man/man9
Module Name:src Committed By: gutteridge Date: Wed Feb 1 03:27:46 UTC 2023 Modified Files: src/share/man/man9: mutex.9 Log Message: mutex.9: add a small detail to the history section To generate a diff of this commit: cvs rdiff -u -r1.34 -r1.35 src/share/man/man9/mutex.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: uwe Date: Mon Dec 19 00:41:45 UTC 2022 Modified Files: src/share/man/man9: mutex.9 Log Message: mutex(9): Minor formatting fixes While here, move the reference to options(4) to the OPTIONS section. To generate a diff of this commit: cvs rdiff -u -r1.33 -r1.34 src/share/man/man9/mutex.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/mutex.9 diff -u src/share/man/man9/mutex.9:1.33 src/share/man/man9/mutex.9:1.34 --- src/share/man/man9/mutex.9:1.33 Sun Dec 18 23:38:42 2022 +++ src/share/man/man9/mutex.9 Mon Dec 19 00:41:45 2022 @@ -1,4 +1,4 @@ -.\" $NetBSD: mutex.9,v 1.33 2022/12/18 23:38:42 gutteridge Exp $ +.\" $NetBSD: mutex.9,v 1.34 2022/12/19 00:41:45 uwe Exp $ .\" .\" Copyright (c) 2007, 2009 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -67,7 +67,8 @@ .Cd "options LOCKDEBUG" .Sh DESCRIPTION Mutexes are used in the kernel to implement mutual exclusion among LWPs -(lightweight processes) and interrupt handlers. +.Pq lightweight processes +and interrupt handlers. .Pp The .Vt kmutex_t @@ -80,23 +81,21 @@ Mutexes replace the system traditionally used to provide synchronization between interrupt handlers and LWPs. .Sh OPTIONS -.Bl -tag -width abcd +The following kernel options have effect on mutex operations: +.Bl -tag -width Cd .It Cd "options DIAGNOSTIC" -.Pp Kernels compiled with the .Dv DIAGNOSTIC option perform basic sanity checks on mutex operations. .It Cd "options LOCKDEBUG" -.Pp Kernels compiled with the .Dv LOCKDEBUG option perform potentially CPU intensive sanity checks on mutex operations. .El .Sh FUNCTIONS -.Bl -tag -width abcd +.Bl -tag -width Ds .It Fn mutex_init "mtx" "type" "ipl" -.Pp Dynamically initialize a mutex for use. .Pp No other operations can be performed on a mutex until it has been initialized. @@ -115,9 +114,8 @@ an endorsed, stable part of the interfac The type of mutex returned depends on the .Fa ipl argument: -.Bl -tag -width abcd -.It IPL_NONE, or one of the IPL_SOFT* constants -.Pp +.Bl -tag -width Dv +.It Dv IPL_NONE , No or one of the Dv IPL_SOFT* No constants An adaptive mutex will be returned. Adaptive mutexes provide mutual exclusion between LWPs, and between LWPs and soft interrupt handlers. @@ -125,8 +123,7 @@ and between LWPs and soft interrupt hand Adaptive mutexes cannot be acquired from a hardware interrupt handler. An LWP may either sleep or busy-wait when attempting to acquire an adaptive mutex that is already held. -.It IPL_VM, IPL_SCHED, IPL_HIGH -.Pp +.It Dv IPL_VM , IPL_SCHED , IPL_HIGH A spin mutex will be returned. Spin mutexes provide mutual exclusion between LWPs, and between LWPs and interrupt handlers. @@ -160,13 +157,11 @@ See .Xr spl 9 for further information on interrupt priority levels (IPLs). .It Fn mutex_destroy "mtx" -.Pp Release resources used by a mutex. The mutex may not be used after it has been destroyed. .Fn mutex_destroy may block in order to free memory. .It Fn mutex_enter "mtx" -.Pp Acquire a mutex. If the mutex is already held, the caller will block and not return until the mutex is acquired. @@ -194,7 +189,6 @@ the level set in .Fn mutex_init if it is not already equal or higher. .It Fn mutex_exit "mtx" -.Pp Release a mutex. The mutex must have been previously acquired by the caller. Mutexes may be released out of order as needed. @@ -210,17 +204,16 @@ to acquire the mutex even on another CPU Thus, there is a global total ordering on all loads and stores under the same mutex. .It Fn mutex_ownable "mtx" -.Pp When compiled with .Dv LOCKDEBUG -(see -.Xr options 4 ) , ensure that the current process can successfully acquire .Ar mtx . If .Ar mtx is already owned by the current process, the system will panic -with a "locking against myself" error. +with a +.Dq locking against myself\^ +error. .Pp This function is needed because .Fn mutex_owned @@ -230,7 +223,6 @@ vs owned by another process. 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. For spin mutexes, return non-zero if the mutex is held, potentially by the current processor. @@ -239,14 +231,11 @@ Otherwise, return zero. .Fn mutex_owned is provided for making diagnostic checks to verify that a lock is held. For example: -.Bd -literal - KASSERT(mutex_owned(_lock)); -.Ed +.Dl KASSERT(mutex_owned(_lock)); .Pp It should not be used to make locking decisions at run time. For spin mutexes, it must not be used to verify that a lock is not held. .It Fn mutex_spin_enter "mtx" -.Pp Equivalent to .Fn mutex_enter , but may only be used when it is known that @@ -257,7 +246,6 @@ Implies the same memory ordering as On some architectures, this can substantially reduce the cost of acquiring a spin mutex. .It Fn
CVS commit: src/share/man/man9
Module Name:src Committed By: uwe Date: Mon Dec 19 00:41:45 UTC 2022 Modified Files: src/share/man/man9: mutex.9 Log Message: mutex(9): Minor formatting fixes While here, move the reference to options(4) to the OPTIONS section. To generate a diff of this commit: cvs rdiff -u -r1.33 -r1.34 src/share/man/man9/mutex.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: gutteridge Date: Sun Dec 18 23:38:42 UTC 2022 Modified Files: src/share/man/man9: mutex.9 Log Message: mutex.9: fix markup (.Em not .Fn) To generate a diff of this commit: cvs rdiff -u -r1.32 -r1.33 src/share/man/man9/mutex.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/mutex.9 diff -u src/share/man/man9/mutex.9:1.32 src/share/man/man9/mutex.9:1.33 --- src/share/man/man9/mutex.9:1.32 Sat Aug 20 14:17:36 2022 +++ src/share/man/man9/mutex.9 Sun Dec 18 23:38:42 2022 @@ -1,4 +1,4 @@ -.\" $NetBSD: mutex.9,v 1.32 2022/08/20 14:17:36 riastradh Exp $ +.\" $NetBSD: mutex.9,v 1.33 2022/12/18 23:38:42 gutteridge Exp $ .\" .\" Copyright (c) 2007, 2009 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -203,7 +203,7 @@ All loads and stores before .Fn mutex_exit will not be reordered after it or delayed in a write buffer, and hence will -.Fn happen before +.Em happen before any subsequent .Fn mutex_enter to acquire the mutex even on another CPU or in an interrupt.
CVS commit: src/share/man/man9
Module Name:src Committed By: gutteridge Date: Sun Dec 18 23:38:42 UTC 2022 Modified Files: src/share/man/man9: mutex.9 Log Message: mutex.9: fix markup (.Em not .Fn) To generate a diff of this commit: cvs rdiff -u -r1.32 -r1.33 src/share/man/man9/mutex.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: msaitoh Date: Tue Oct 25 00:20:36 UTC 2022 Modified Files: src/share/man/man9: altq.9 Log Message: ifq_drops was changed to use uint64_t. To generate a diff of this commit: cvs rdiff -u -r1.18 -r1.19 src/share/man/man9/altq.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/altq.9 diff -u src/share/man/man9/altq.9:1.18 src/share/man/man9/altq.9:1.19 --- src/share/man/man9/altq.9:1.18 Thu May 26 14:39:30 2022 +++ src/share/man/man9/altq.9 Tue Oct 25 00:20:36 2022 @@ -1,4 +1,4 @@ -.\" $NetBSD: altq.9,v 1.18 2022/05/26 14:39:30 rillig Exp $ +.\" $NetBSD: altq.9,v 1.19 2022/10/25 00:20:36 msaitoh Exp $ .\" $OpenBSD: altq.9,v 1.4 2001/07/12 12:41:42 itojun Exp $ .\" .\" Copyright (C) 2001 @@ -25,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd May 26, 2022 +.Dd October 24, 2022 .Dt ALTQ 9 .Os .\" @@ -169,7 +169,7 @@ these fields.) struct mbuf *ifq_tail; |struct mbuf *ifq_tail; int ifq_len; |int ifq_len; int ifq_maxlen; |int ifq_maxlen; -int ifq_drops;|int ifq_drops; +uint64_t ifq_drops;|uint64_t ifq_drops; };|/* altq related fields */ |.. | };
CVS commit: src/share/man/man9
Module Name:src Committed By: msaitoh Date: Tue Oct 25 00:20:36 UTC 2022 Modified Files: src/share/man/man9: altq.9 Log Message: ifq_drops was changed to use uint64_t. To generate a diff of this commit: cvs rdiff -u -r1.18 -r1.19 src/share/man/man9/altq.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Sat Oct 15 14:54:21 UTC 2022 Modified Files: src/share/man/man9: vmem.9 Log Message: 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. To generate a diff of this commit: cvs rdiff -u -r1.20 -r1.21 src/share/man/man9/vmem.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/vmem.9 diff -u src/share/man/man9/vmem.9:1.20 src/share/man/man9/vmem.9:1.21 --- src/share/man/man9/vmem.9:1.20 Tue Jun 16 01:29:00 2020 +++ src/share/man/man9/vmem.9 Sat Oct 15 14:54:21 2022 @@ -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 @@ The caller must ensure that no one will .\" .Sh RETURN VALUES .Fn vmem_create -return a pointer to the newly allocated vmem_t. -Otherwise, it returns -.Dv NULL . -.Pp -On success, -.Fn vmem_xalloc 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 +.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 -return 0. -Otherwise, -.Dv ENOMEM -is returned. +and +.Fn vmem_xalloc +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 @@ and .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 .
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Sat Oct 15 14:54:21 UTC 2022 Modified Files: src/share/man/man9: vmem.9 Log Message: 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. To generate a diff of this commit: cvs rdiff -u -r1.20 -r1.21 src/share/man/man9/vmem.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Thu Sep 22 14:02:24 UTC 2022 Modified Files: src/share/man/man9: curproc.9 Log Message: curproc(9): Rework man page. To generate a diff of this commit: cvs rdiff -u -r1.5 -r1.6 src/share/man/man9/curproc.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/curproc.9 diff -u src/share/man/man9/curproc.9:1.5 src/share/man/man9/curproc.9:1.6 --- src/share/man/man9/curproc.9:1.5 Thu Jul 1 15:12:31 2010 +++ src/share/man/man9/curproc.9 Thu Sep 22 14:02:24 2022 @@ -1,4 +1,4 @@ -.\" $NetBSD: curproc.9,v 1.5 2010/07/01 15:12:31 wiz Exp $ +.\" $NetBSD: curproc.9,v 1.6 2022/09/22 14:02:24 riastradh Exp $ .\" .\" Copyright (c) 2002 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -40,41 +40,68 @@ .In sys/proc.h .Ft struct cpu_info * .Fn curcpu "void" -.Ft struct proc * -.Fn curproc "void" -.Ft struct lwp * -.Fn curlwp "void" +.Vt struct proc *curproc ; +.Vt struct lwp *curlwp ; .Sh DESCRIPTION -The following macros can be used to retrieve -the current processor, process, and light-weight process -.Pq Tn LWP , +The following macros retrieve +the current CPU, process, and thread +.Pq lightweight process, or Tn LWP , respectively: -.Bl -enum -offset indent -.It -The machine-dependent +.Bl -tag -width Dv +.It Fn curcpu +Returns a pointer to the +.Vt "struct cpu_info" +structure representing the CPU that the code calling it is running on. +.Pp +The value of .Fn curcpu -macro returns a pointer to a -.Em cpu_info -structure containing information of the -.Tn CPU -that this thread is running on. -.It -The machine-independent -.Fn curproc -macro refers to a pointer to the process currently running on this -.Tn CPU . -.It -The -.Fn curlwp -macro expands to a pointer to -.Em lwp -structure, containing information about the current -.Tn LWP . -This macro is machine-independent, -but machine-dependent -.In machine/cpu.h -may redefine it. +is unstable and may be stale as soon as it is read unless the caller +prevents preemption by raising the IPL +.Pq Xr spl 9 , Xr mutex 9 , +by disabling preemption +.Pq Xr kpreempt_disable 9 , +or by binding the thread to its CPU +.Pq Xr curlwp_bind 9 . +.It Dv curproc +Yields a pointer to the +.Vt "struct proc" +structure representing the currently running process. +.Pp +The value of +.Dv curproc +is stable and does not change during execution except in +machine-dependent logic to perform context switches, so it works like a +global constant, not like a stateful procedure. +.It Dv curlwp +Yields a pointer to the +.Vt "struct lwp" +structure representing the currently running thread. +.Pp +The value of +.Dv curlwp +is stable and does not change during execution except in +machine-dependent logic to perform context switches, so it works like a +global constant, not like a stateful procedure. .El +.Sh SOURCE REFERENCES +The +.Fn curcpu +macro is defined in the machine-independent +.Pa machine/cpu.h . +.Pp +The +.Dv curproc +macro is defined in +.Pa sys/lwp.h . +.Pp +The +.Dv curlwp +macro has a machine-independent definition in +.Pa sys/lwp.h , +but it may be overridden by +.Pa machine/cpu.h , +and must be overridden on architectures supporting multiprocessing and +kernel preemption. .Sh SEE ALSO .Xr cpu_number 9 , .Xr proc_find 9
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Thu Sep 22 14:02:24 UTC 2022 Modified Files: src/share/man/man9: curproc.9 Log Message: curproc(9): Rework man page. To generate a diff of this commit: cvs rdiff -u -r1.5 -r1.6 src/share/man/man9/curproc.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: pgoyette Date: Wed Sep 7 01:18:33 UTC 2022 Modified Files: src/share/man/man9: sysctl.9 Log Message: Update to match recent changes in implementation. To generate a diff of this commit: cvs rdiff -u -r1.23 -r1.24 src/share/man/man9/sysctl.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/sysctl.9 diff -u src/share/man/man9/sysctl.9:1.23 src/share/man/man9/sysctl.9:1.24 --- src/share/man/man9/sysctl.9:1.23 Wed Aug 7 19:58:50 2019 +++ src/share/man/man9/sysctl.9 Wed Sep 7 01:18:32 2022 @@ -1,4 +1,4 @@ -.\" $NetBSD: sysctl.9,v 1.23 2019/08/07 19:58:50 wiz Exp $ +.\" $NetBSD: sysctl.9,v 1.24 2022/09/07 01:18:32 pgoyette Exp $ .\" .\" Copyright (c) 2004 The NetBSD Foundation, Inc. .\" 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 7, 2019 +.Dd September 6, 2022 .Dt SYSCTL 9 .Os .Sh NAME @@ -546,7 +546,8 @@ specifically ignores any arguments given to zero, and returns success. .Sh SETUP FUNCTIONS Although nodes can be added to the SYSCTL tree at any time, in order to -add nodes during the kernel bootstrap phase, a proper +add nodes during the kernel bootstrap phase (and during loadable module +initialization), a proper .Dq setup function must be used. Setup functions are declared using the @@ -565,11 +566,11 @@ The address of the function is added to traverses during initialization. For loadable kernel modules (see .Xr module 9 ) , -the list of functions is called from the module loader after the module's +the list of functions is called from the module loader before the module's initialization routine. Any sysctl nodes created for the loadable module are removed using .Fn sysctl_teardown -before calling the module's termination code. +after calling the module's termination code. .Pp Setup functions do not have to add nodes to the main tree, but can set up their own trees for emulation or other purposes.
CVS commit: src/share/man/man9
Module Name:src Committed By: pgoyette Date: Wed Sep 7 01:18:33 UTC 2022 Modified Files: src/share/man/man9: sysctl.9 Log Message: Update to match recent changes in implementation. To generate a diff of this commit: cvs rdiff -u -r1.23 -r1.24 src/share/man/man9/sysctl.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: wiz Date: Mon Sep 5 16:42:59 UTC 2022 Modified Files: src/share/man/man9: pktqueue.9 Log Message: Fix logic error in pktq_set_maxlen() description. Ok thorpej@ To generate a diff of this commit: cvs rdiff -u -r1.2 -r1.3 src/share/man/man9/pktqueue.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/pktqueue.9 diff -u src/share/man/man9/pktqueue.9:1.2 src/share/man/man9/pktqueue.9:1.3 --- src/share/man/man9/pktqueue.9:1.2 Mon Sep 5 09:18:39 2022 +++ src/share/man/man9/pktqueue.9 Mon Sep 5 16:42:59 2022 @@ -1,4 +1,4 @@ -.\" $NetBSD: pktqueue.9,v 1.2 2022/09/05 09:18:39 wiz Exp $ +.\" $NetBSD: pktqueue.9,v 1.3 2022/09/05 16:42:59 wiz Exp $ .\" .\" Copyright (c) 2022 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -138,7 +138,7 @@ Sets the maximum queue length to the val .Fa maxlen . If the new value of .Fa maxlen -is greater than the previous value, then this routine may block until +is smaller than the previous value, then this routine may block until all packets that were previously in the packet queue can be re-enqueued. .It Fn pktq_rps_hash "funcp" "m" Calculates the RPS hash for the packet
CVS commit: src/share/man/man9
Module Name:src Committed By: wiz Date: Mon Sep 5 16:42:59 UTC 2022 Modified Files: src/share/man/man9: pktqueue.9 Log Message: Fix logic error in pktq_set_maxlen() description. Ok thorpej@ To generate a diff of this commit: cvs rdiff -u -r1.2 -r1.3 src/share/man/man9/pktqueue.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: wiz Date: Mon Sep 5 09:18:39 UTC 2022 Modified Files: src/share/man/man9: pktqueue.9 Log Message: pkgqueue(9): fix some nits, remove trailing whitespace To generate a diff of this commit: cvs rdiff -u -r1.1 -r1.2 src/share/man/man9/pktqueue.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/pktqueue.9 diff -u src/share/man/man9/pktqueue.9:1.1 src/share/man/man9/pktqueue.9:1.2 --- src/share/man/man9/pktqueue.9:1.1 Sun Sep 4 21:37:50 2022 +++ src/share/man/man9/pktqueue.9 Mon Sep 5 09:18:39 2022 @@ -1,4 +1,4 @@ -.\" $NetBSD: pktqueue.9,v 1.1 2022/09/04 21:37:50 thorpej Exp $ +.\" $NetBSD: pktqueue.9,v 1.2 2022/09/05 09:18:39 wiz Exp $ .\" .\" Copyright (c) 2022 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -28,7 +28,7 @@ .\" POSSIBILITY OF SUCH DAMAGE. .\" .Dd September 3, 2022 -.Dt pktqueue 9 +.Dt PKTQUEUE 9 .Os .Sh NAME .Nm pktqueue , @@ -42,7 +42,7 @@ .Nm pktq_set_maxlen , .Nm pktq_rps_hash , .Nm pktq_sysctl_setup , -.Nm sysctl_pktq_rps_hash_handler , +.Nm sysctl_pktq_rps_hash_handler .Nd Lockless network protocol input queues with integrated ISR scheduling .Sh SYNOPSIS .In net/pktqueue.h @@ -96,7 +96,7 @@ will be established at .Dv SOFTINT_NET . .It Fn pktq_destroy "pq" Destroy the specified packet queue. -The caller is reponsible for ensuring that no packets remain in the queue +The caller is responsible for ensuring that no packets remain in the queue prior to calling this function. .It Fn pktq_enqueue "pq" "m" "hash" Enqueue the packet @@ -127,7 +127,7 @@ It performs a operation on all packet queues. .It Fn pktq_flush "pq" This function removes and frees all packets in the specified queue. -The caller is reponsible for ensuring that no calls to +The caller is responsible for ensuring that no calls to .Fn pktq_enqueue or .Fn pktq_dequeue @@ -204,8 +204,8 @@ cast to .Pc . .El .Sh CODE REFERENCES -The -.Nm +The +.Nm interface is implemented within the file .Pa net/pktqueue.c . .Pp @@ -247,13 +247,13 @@ may result in re-ordering the delivery o the queue. .\" .Sh EXAMPLES .Sh SEE ALSO +.Xr sysctl 8 , .Xr kpreempt 9 , .Xr pcq 9 , .Xr softintr 9 , -.Xr sysctl 8 , .Xr sysctl 9 .Sh HISTORY -The -.Nm +The +.Nm interface first appeared in .Nx 7.0 .
CVS commit: src/share/man/man9
Module Name:src Committed By: wiz Date: Mon Sep 5 09:18:39 UTC 2022 Modified Files: src/share/man/man9: pktqueue.9 Log Message: pkgqueue(9): fix some nits, remove trailing whitespace To generate a diff of this commit: cvs rdiff -u -r1.1 -r1.2 src/share/man/man9/pktqueue.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Sat Aug 20 23:50:41 UTC 2022 Modified Files: src/share/man/man9: usbnet.9 Log Message: usbnet(9): Clarify how mii functions are used. To generate a diff of this commit: cvs rdiff -u -r1.19 -r1.20 src/share/man/man9/usbnet.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/usbnet.9 diff -u src/share/man/man9/usbnet.9:1.19 src/share/man/man9/usbnet.9:1.20 --- src/share/man/man9/usbnet.9:1.19 Sat Aug 20 14:08:59 2022 +++ src/share/man/man9/usbnet.9 Sat Aug 20 23:50:41 2022 @@ -1,4 +1,4 @@ -.\" $NetBSD: usbnet.9,v 1.19 2022/08/20 14:08:59 riastradh Exp $ +.\" $NetBSD: usbnet.9,v 1.20 2022/08/20 23:50:41 riastradh Exp $ .\" .\" Copyright (c) 2019 Matthew R. Green .\" All rights reserved. @@ -403,29 +403,29 @@ when bringing the interface up. .It Ft int Fn (*uno_read_reg) "struct usbnet *un" "int phy" "int reg" "uint16_t *val" Read MII register. Required with MII. -Serialized with other MII functions, and with +Serialized with other MII functions, and only called after .Dq uno_init -and +and before .Dq uno_stop . .It Ft int Fn (*uno_write_reg) "struct usbnet *un" "int phy" "int reg" "uint16_t val" Write MII register. Required with MII. -Serialized with other MII functions, and with +Serialized with other MII functions, and only called after .Dq uno_init -and +and before .Dq uno_stop . .It Ft usbd_status Fn (*uno_statchg) "struct ifnet *ifp" Handle MII status change. Required with MII. -Serialized with other MII functions, and with +Serialized with other MII functions, and only called after .Dq uno_init -and +and before .Dq uno_stop . .It Ft unsigned Fn (*uno_tx_prepare) "struct usbnet *un" "struct mbuf *m" "struct usbnet_chain *c" Prepare an mbuf for transmit. Required. Called sequentially between, and not during, -.Dq uno_init . +.Dq uno_init and .Dq uno_stop . .It Ft void Fn (*uno_rx_loop) "struct usbnet *un" "struct usbnet_chain *c" "uint32_t total_len"
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Sat Aug 20 23:50:41 UTC 2022 Modified Files: src/share/man/man9: usbnet.9 Log Message: usbnet(9): Clarify how mii functions are used. To generate a diff of this commit: cvs rdiff -u -r1.19 -r1.20 src/share/man/man9/usbnet.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Sat Aug 20 14:17:36 UTC 2022 Modified Files: src/share/man/man9: mutex.9 Log Message: 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 To generate a diff of this commit: cvs rdiff -u -r1.31 -r1.32 src/share/man/man9/mutex.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/mutex.9 diff -u src/share/man/man9/mutex.9:1.31 src/share/man/man9/mutex.9:1.32 --- src/share/man/man9/mutex.9:1.31 Sat Dec 9 16:00:19 2017 +++ src/share/man/man9/mutex.9 Sat Aug 20 14:17:36 2022 @@ -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 @@ try to acquire adaptive mutexes or other .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
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Sat Aug 20 14:17:36 UTC 2022 Modified Files: src/share/man/man9: mutex.9 Log Message: 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 To generate a diff of this commit: cvs rdiff -u -r1.31 -r1.32 src/share/man/man9/mutex.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: skrll Date: Sun Aug 14 19:12:23 UTC 2022 Modified Files: src/share/man/man9: usbdi.9 Log Message: usbd_do_request_async got deleted back in 2013 so remove the commented out reference to it here. To generate a diff of this commit: cvs rdiff -u -r1.36 -r1.37 src/share/man/man9/usbdi.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/usbdi.9 diff -u src/share/man/man9/usbdi.9:1.36 src/share/man/man9/usbdi.9:1.37 --- src/share/man/man9/usbdi.9:1.36 Sat Dec 11 19:24:19 2021 +++ src/share/man/man9/usbdi.9 Sun Aug 14 19:12:23 2022 @@ -1,4 +1,4 @@ -.\" $NetBSD: usbdi.9,v 1.36 2021/12/11 19:24:19 mrg Exp $ +.\" $NetBSD: usbdi.9,v 1.37 2022/08/14 19:12:23 skrll Exp $ .\" .\" Copyright (c) 2012 Matthew R. Green .\" All rights reserved. @@ -133,7 +133,6 @@ .Fn usbd_do_request_flags "struct usbd_device *dev" \ "usb_device_request_t *req" "void *data" "uint16_t flags" "int *actlen" \ "uint32_t timo" -.\" usbd_do_request_async() not used outside of usbdi* .Ft usb_interface_descriptor_t * .Fn usbd_get_interface_descriptor "struct usbd_interface *iface" .Ft usb_config_descriptor_t *
CVS commit: src/share/man/man9
Module Name:src Committed By: skrll Date: Sun Aug 14 19:12:23 UTC 2022 Modified Files: src/share/man/man9: usbdi.9 Log Message: usbd_do_request_async got deleted back in 2013 so remove the commented out reference to it here. To generate a diff of this commit: cvs rdiff -u -r1.36 -r1.37 src/share/man/man9/usbdi.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: wiz Date: Sat Aug 13 17:06:55 UTC 2022 Modified Files: src/share/man/man9: bus_space.9 Log Message: Remove Li without effect. To generate a diff of this commit: cvs rdiff -u -r1.54 -r1.55 src/share/man/man9/bus_space.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/bus_space.9 diff -u src/share/man/man9/bus_space.9:1.54 src/share/man/man9/bus_space.9:1.55 --- src/share/man/man9/bus_space.9:1.54 Fri Aug 12 13:24:37 2022 +++ src/share/man/man9/bus_space.9 Sat Aug 13 17:06:55 2022 @@ -1,4 +1,4 @@ -.\" $NetBSD: bus_space.9,v 1.54 2022/08/12 13:24:37 riastradh Exp $ +.\" $NetBSD: bus_space.9,v 1.55 2022/08/13 17:06:55 wiz Exp $ .\" .\" Copyright (c) 1997 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -1369,7 +1369,7 @@ This functions similarly to but additionally orders bus space I/O which .Xr membar_ops 3 may not. -.It Dv "BUS_SPACE_BARRIER_READ" Li "|" Dv "BUS_SPACE_BARRIER_WRITE" +.It Dv "BUS_SPACE_BARRIER_READ" | Dv "BUS_SPACE_BARRIER_WRITE" Guarantee that any program-prior bus space read, bus space write, or memory access via .Fn bus_space_vaddr
CVS commit: src/share/man/man9
Module Name:src Committed By: wiz Date: Sat Aug 13 17:06:55 UTC 2022 Modified Files: src/share/man/man9: bus_space.9 Log Message: Remove Li without effect. To generate a diff of this commit: cvs rdiff -u -r1.54 -r1.55 src/share/man/man9/bus_space.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Fri Aug 12 15:30:41 UTC 2022 Modified Files: src/share/man/man9: usbnet.9 Log Message: usbnet(9): Tidy up language about init/rx/tx/stop in man page. To generate a diff of this commit: cvs rdiff -u -r1.17 -r1.18 src/share/man/man9/usbnet.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/usbnet.9 diff -u src/share/man/man9/usbnet.9:1.17 src/share/man/man9/usbnet.9:1.18 --- src/share/man/man9/usbnet.9:1.17 Sat Mar 5 06:55:58 2022 +++ src/share/man/man9/usbnet.9 Fri Aug 12 15:30:41 2022 @@ -1,4 +1,4 @@ -.\" $NetBSD: usbnet.9,v 1.17 2022/03/05 06:55:58 riastradh Exp $ +.\" $NetBSD: usbnet.9,v 1.18 2022/08/12 15:30:41 riastradh Exp $ .\" .\" Copyright (c) 2019 Matthew R. Green .\" All rights reserved. @@ -503,7 +503,7 @@ and must be set before calling .Fn usbnet_attach_ifp . .Sh RECEIVE AND SEND -Receive and send routines are structured around a the +Receive and send routines are structured around the .Va usbnet_cdata and .Va usbnet_chain @@ -513,11 +513,11 @@ structures, the and .Dv un_tx_xfer_flags members, and the -.Fn uno_stop , .Fn uno_init , .Fn uno_tx_prepare , +.Fn uno_rx_loop , and -.Fn uno_rx_loop +.Fn uno_stop callbacks of .Va usbnet_ops . .Pp @@ -535,19 +535,12 @@ array entries filled in, and optionally .Dv USBNET_ENDPT_INTR entry filled in if applicable. .Pp -The optional -.Fn uno_stop -callback performs device-specific operations to shutdown the -transmit or receive handling. -.Pp The .Fn uno_init -callback both performs device-specific enablement and then calls -.Fn usbnet_rx_tx_init , -which sets up the receive, transmit, and, optionally, the interrupt -pipes, as well as starting the receive pipes. -All USB transfer setup is handled internally to the framework, and -the driver callbacks merely copy data in or out of a chain entry using +callback enables the hardware, and if necessary reprograms the hardware +multicast filter, before the framework initiates USB Tx/Rx transfers. +All USB transfer setup is handled by the framework. +The driver callbacks merely copy data in or out of a chain entry using what is typically a device-specific method. .Pp The @@ -560,8 +553,7 @@ enqueued with the higher layers using ei (for most devices) or .Fn usbnet_input for devices that use -.Fn if_input -. +.Fn if_input . (This currently relies upon the .Va struct ifnet having the @@ -593,6 +585,11 @@ It also contains pointers back to the ow and the .Va struct usbd_xfer associated with this transfer. +.Pp +After aborting all USB Tx/Rx transfers when bringing an interface down, +the framework calls the optional +.Fn uno_stop +callback to disable the hardware. .Sh MII For devices that have MII support these callbacks in .Fa struct usbnet_ops
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Fri Aug 12 15:30:41 UTC 2022 Modified Files: src/share/man/man9: usbnet.9 Log Message: usbnet(9): Tidy up language about init/rx/tx/stop in man page. To generate a diff of this commit: cvs rdiff -u -r1.17 -r1.18 src/share/man/man9/usbnet.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Fri Aug 12 13:24:37 UTC 2022 Modified Files: src/share/man/man9: bus_space.9 Log Message: bus_space(9): Update barrier semantics to match reality and sense. As proposed on tech-kern: https://mail-index.netbsd.org/tech-kern/2022/07/16/msg028249.html tl;dr: - bus_space_barrier is needed only with prefetchable/cacheable. - BUS_SPACE_BARRIER_READ is like membar_acquire. - BUS_SPACE_BARRIER_WRITE is like membar_release. - READ|WRITE is like membar_sync. To generate a diff of this commit: cvs rdiff -u -r1.53 -r1.54 src/share/man/man9/bus_space.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/bus_space.9 diff -u src/share/man/man9/bus_space.9:1.53 src/share/man/man9/bus_space.9:1.54 --- src/share/man/man9/bus_space.9:1.53 Mon Nov 13 09:10:37 2017 +++ src/share/man/man9/bus_space.9 Fri Aug 12 13:24:37 2022 @@ -1,4 +1,4 @@ -.\" $NetBSD: bus_space.9,v 1.53 2017/11/13 09:10:37 wiz Exp $ +.\" $NetBSD: bus_space.9,v 1.54 2022/08/12 13:24:37 riastradh Exp $ .\" .\" Copyright (c) 1997 The NetBSD Foundation, Inc. .\" 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 September 15, 2016 +.Dd August 12, 2022 .Dt BUS_SPACE 9 .Os .Sh NAME @@ -466,49 +466,30 @@ that all of the data being accessed is i handle describes. Trying to access data outside that region is an error. .Pp -Because some architectures' memory systems use buffering to improve -memory and device access performance, there is a mechanism which can be -used to create -.Dq barriers -in the bus space read and write stream. -.Pp -There are two types of barriers: ordering barriers and completion -barriers. -.Pp -Ordering barriers prevent some operations from bypassing other -operations. -They are relatively light weight and described in terms of the -operations they are intended to order. -The important thing to note is that they create specific ordering -constraint surrounding bus accesses but do not necessarily force any -synchronization themselves. -So, if there is enough distance between the memory operations being -ordered, the preceding ones could complete by themselves resulting -in no performance penalty. -.Pp -For instance, a write before read barrier will force any writes -issued before the barrier instruction to complete before any reads -after the barrier are issued. -This forces processors with write buffers to read data from memory rather -than from the pending write in the write buffer. -.Pp -Ordering barriers are usually sufficient for most circumstances, -and can be combined together. -For instance a read before write barrier can be combined with a write -before write barrier to force all memory operations to complete before -the next write is started. -.Pp -Completion barriers force all memory operations and any pending -exceptions to be completed before any instructions after the -barrier may be issued. -Completion barriers are extremely expensive and almost never required -in device driver code. -A single completion barrier can force the processor to stall on memory -for hundreds of cycles on some machines. -.Pp -Correctly-written drivers will include all appropriate barriers, -and assume only the read/write ordering imposed by the barrier -operations. +Bus space I/O operations on mappings made with +.Dv BUS_SPACE_MAP_PREFETCHABLE +or +.Dv BUS_SPACE_MAP_CACHEABLE +may be reordered or combined for performance on devices that support +it, such as write-combining +.Pq "a.k.a." Sq prefetchable +graphics framebuffers or cacheable ROM images. +The +.Fn bus_space_barrier +function orders reads and writes in prefetchable or cacheable mappings +relative to other reads and writes in bus spaces. +Barriers are needed +.Em only +when prefetchable or cacheable mappings are involved: +.Bl -bullet +.It +Bus space reads and writes on non-prefetchable, non-cacheable mappings +at a single device are totally ordered with one another. +.It +Ordering of memory operations on normal memory with bus space I/O +for triggering DMA or being notified of DMA completion requires +.Xr bus_dmamap_sync 9 . +.El .Pp People trying to write portable drivers with the .Nm @@ -1185,9 +1166,9 @@ be read, on others it may cause a system .Pp Read operations done by the .Fn bus_space_read_N -functions may be executed out -of order with respect to other pending read and write operations unless -order is enforced by use of the +functions may be executed out of order with respect to other read and +write operations if either are on prefetchable or cacheable mappings +unless order is enforced by use of the .Fn bus_space_barrier function. .Pp @@ -1223,8 +1204,8 @@ to be written, on others it may cause a .Pp Write operations done by the .Fn bus_space_write_N -functions may be
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Fri Aug 12 13:24:37 UTC 2022 Modified Files: src/share/man/man9: bus_space.9 Log Message: bus_space(9): Update barrier semantics to match reality and sense. As proposed on tech-kern: https://mail-index.netbsd.org/tech-kern/2022/07/16/msg028249.html tl;dr: - bus_space_barrier is needed only with prefetchable/cacheable. - BUS_SPACE_BARRIER_READ is like membar_acquire. - BUS_SPACE_BARRIER_WRITE is like membar_release. - READ|WRITE is like membar_sync. To generate a diff of this commit: cvs rdiff -u -r1.53 -r1.54 src/share/man/man9/bus_space.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: andvar Date: Thu Jul 7 20:22:03 UTC 2022 Modified Files: src/share/man/man9: ioctl.9 Log Message: fix reference to magma(4) by pointing to sparc/magma 4 and update the date. To generate a diff of this commit: cvs rdiff -u -r1.35 -r1.36 src/share/man/man9/ioctl.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/ioctl.9 diff -u src/share/man/man9/ioctl.9:1.35 src/share/man/man9/ioctl.9:1.36 --- src/share/man/man9/ioctl.9:1.35 Thu Jul 7 20:07:47 2022 +++ src/share/man/man9/ioctl.9 Thu Jul 7 20:22:03 2022 @@ -1,4 +1,4 @@ -.\" $NetBSD: ioctl.9,v 1.35 2022/07/07 20:07:47 andvar Exp $ +.\" $NetBSD: ioctl.9,v 1.36 2022/07/07 20:22:03 andvar Exp $ .\" .\" Copyright (c) 1999 The NetBSD Foundation, Inc. .\" 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 January 27, 2019 +.Dd July 7, 2022 .Dt IOCTL 9 .Os .Sh NAME @@ -164,7 +164,7 @@ pci(4) .It 'P' compat/ossaudio and soundcard.h .It 'P' -.Xr magma 4 +.Xr sparc/magma 4 bpp (sparc) .It 'q' .Xr altq 9
CVS commit: src/share/man/man9
Module Name:src Committed By: andvar Date: Thu Jul 7 20:22:03 UTC 2022 Modified Files: src/share/man/man9: ioctl.9 Log Message: fix reference to magma(4) by pointing to sparc/magma 4 and update the date. To generate a diff of this commit: cvs rdiff -u -r1.35 -r1.36 src/share/man/man9/ioctl.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: andvar Date: Thu Jul 7 20:07:47 UTC 2022 Modified Files: src/share/man/man9: ioctl.9 Log Message: remove reference to tb(4), which was removed back in 2005. To generate a diff of this commit: cvs rdiff -u -r1.34 -r1.35 src/share/man/man9/ioctl.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/ioctl.9 diff -u src/share/man/man9/ioctl.9:1.34 src/share/man/man9/ioctl.9:1.35 --- src/share/man/man9/ioctl.9:1.34 Sun Jan 27 08:53:29 2019 +++ src/share/man/man9/ioctl.9 Thu Jul 7 20:07:47 2022 @@ -1,4 +1,4 @@ -.\" $NetBSD: ioctl.9,v 1.34 2019/01/27 08:53:29 maxv Exp $ +.\" $NetBSD: ioctl.9,v 1.35 2022/07/07 20:07:47 andvar Exp $ .\" .\" Copyright (c) 1999 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -86,8 +86,6 @@ ADB devices (mac68k, macppc) .It 'A' .Xr audio 4 .It 'b' -.Xr \ 4 -.It 'b' Bluetooth HCI sockets, see .Xr bluetooth 4 .It 'b'
CVS commit: src/share/man/man9
Module Name:src Committed By: andvar Date: Thu Jul 7 20:07:47 UTC 2022 Modified Files: src/share/man/man9: ioctl.9 Log Message: remove reference to tb(4), which was removed back in 2005. To generate a diff of this commit: cvs rdiff -u -r1.34 -r1.35 src/share/man/man9/ioctl.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src Committed By: rillig Date: Thu May 26 14:39:30 UTC 2022 Modified Files: src/share/man/man9: altq.9 Log Message: altq.9: remove CONSTCOND comment from example code Since 2021-01-31, lint no longer needs CONSTCOND in a do-while loop. To generate a diff of this commit: cvs rdiff -u -r1.17 -r1.18 src/share/man/man9/altq.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
CVS commit: src/share/man/man9
Module Name:src
Committed By: rillig
Date: Thu May 26 14:39:30 UTC 2022
Modified Files:
src/share/man/man9: altq.9
Log Message:
altq.9: remove CONSTCOND comment from example code
Since 2021-01-31, lint no longer needs CONSTCOND in a do-while loop.
To generate a diff of this commit:
cvs rdiff -u -r1.17 -r1.18 src/share/man/man9/altq.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/altq.9
diff -u src/share/man/man9/altq.9:1.17 src/share/man/man9/altq.9:1.18
--- src/share/man/man9/altq.9:1.17 Wed Mar 21 10:21:17 2018
+++ src/share/man/man9/altq.9 Thu May 26 14:39:30 2022
@@ -1,4 +1,4 @@
-.\" $NetBSD: altq.9,v 1.17 2018/03/21 10:21:17 wiz Exp $
+.\" $NetBSD: altq.9,v 1.18 2022/05/26 14:39:30 rillig Exp $
.\" $OpenBSD: altq.9,v 1.4 2001/07/12 12:41:42 itojun Exp $
.\"
.\" Copyright (C) 2001
@@ -25,7 +25,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd March 20, 2018
+.Dd May 26, 2022
.Dt ALTQ 9
.Os
.\"
@@ -228,7 +228,7 @@ do {
} \e
if ((err))\e
(ifq)->ifq_drops++; \e
-} while (/*CONSTCOND*/ 0)
+} while (false)
.Ed
.Pp
.Fn IFQ_ENQUEUE
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Sun May 22 11:40:46 UTC 2022 Modified Files: src/share/man/man9: opencrypto.9 Log Message: opencrypto: Touch up man page a little. To generate a diff of this commit: cvs rdiff -u -r1.22 -r1.23 src/share/man/man9/opencrypto.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/opencrypto.9 diff -u src/share/man/man9/opencrypto.9:1.22 src/share/man/man9/opencrypto.9:1.23 --- src/share/man/man9/opencrypto.9:1.22 Sun May 22 11:40:29 2022 +++ src/share/man/man9/opencrypto.9 Sun May 22 11:40:46 2022 @@ -1,5 +1,5 @@ .\" $OpenBSD: crypto.9,v 1.25 2003/07/11 13:47:41 jmc Exp $ -.\" $NetBSD: opencrypto.9,v 1.22 2022/05/22 11:40:29 riastradh Exp $ +.\" $NetBSD: opencrypto.9,v 1.23 2022/05/22 11:40:46 riastradh Exp $ .\" .\" The author of this man page is Angelos D. Keromytis (ange...@cis.upenn.edu) .\" @@ -276,15 +276,12 @@ buffer for the result (or for re-formatt .It Fa crp_callback This routine is invoked upon completion of the request, whether successful or not. -It is invoked through the +It is invoked by the driver through the .Fn crypto_done routine. If the request was not successful, an error code is set in the .Fa crp_etype field. -It is the responsibility of the callback routine to set the appropriate -.Xr spl 9 -level. .It Fa crp_etype Contains the error type, if any errors were encountered, or zero if the request was successfully processed. @@ -710,13 +707,3 @@ supported. Note that 3DES is considered one algorithm (and not three instances of DES). Thus, 3DES and DES could be mixed in the same request. -.Pp -A queue for completed operations should be implemented and processed -at some software -.Xr spl 9 -level, to avoid overall system latency issues, and potential kernel -stack exhaustion while processing a callback. -.Pp -When SMP time comes, we will support use of a second processor (or -more) as a crypto device (this is actually AMP, but we need the same -basic support).
CVS commit: src/share/man/man9
Module Name:src Committed By: riastradh Date: Sun May 22 11:40:46 UTC 2022 Modified Files: src/share/man/man9: opencrypto.9 Log Message: opencrypto: Touch up man page a little. To generate a diff of this commit: cvs rdiff -u -r1.22 -r1.23 src/share/man/man9/opencrypto.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
