diff options
Diffstat (limited to 'static/netbsd/man9')
294 files changed, 70344 insertions, 0 deletions
diff --git a/static/netbsd/man9/CTASSERT.9 b/static/netbsd/man9/CTASSERT.9 new file mode 100644 index 00000000..d81d641f --- /dev/null +++ b/static/netbsd/man9/CTASSERT.9 @@ -0,0 +1,70 @@ +.\" $NetBSD: CTASSERT.9,v 1.2 2010/04/05 19:18:45 joerg Exp $ +.\" Copyright (c) 2003 Hiten M. Pandya +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man9/CTASSERT.9,v 1.3 2008/09/05 15:24:54 emaste Exp $ +.\" +.Dd January 24, 2010 +.Dt CTASSERT 9 +.Os +.Sh NAME +.Nm CTASSERT +.Nd compile time assertion macro +.Sh SYNOPSIS +.Ft void +.Fn CTASSERT expression +.Sh DESCRIPTION +The +.Fn CTASSERT +macro evaluates +.Fa expression +at compile time and causes a compiler error if it is false. +.Pp +The +.Fn CTASSERT +macro is useful for asserting the size or alignment of important +data structures and variables during compilation, which would +otherwise cause the code to fail at run time. +.Sh IMPLEMENTATION NOTES +The +.Fn CTASSERT +macro should not be used in a header file. +It is implemented using a dummy typedef, with a name (based on line number) +that may conflict with a +.Fn CTASSERT +in a source file including that header. +.Sh EXAMPLES +Assert that the size of the +.Vt uuid +structure is 16 bytes. +.Pp +.Dl "CTASSERT(sizeof(struct uuid) == 16);" +.Sh SEE ALSO +.Xr KASSERT 9 +.Sh AUTHORS +This manual page was written by +.An Hiten M. Pandya +.Aq hmp@FreeBSD.org . diff --git a/static/netbsd/man9/KASSERT.9 b/static/netbsd/man9/KASSERT.9 new file mode 100644 index 00000000..b5c0fa85 --- /dev/null +++ b/static/netbsd/man9/KASSERT.9 @@ -0,0 +1,118 @@ +.\" $NetBSD: KASSERT.9,v 1.13 2011/09/27 00:36:51 jym Exp $ +.\" +.\" Copyright (c) 2006 Igor Sobrado +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 27, 2011 +.Dt KASSERT 9 +.Os +.Sh NAME +.Nm KASSERT , +.Nm KASSERTMSG , +.Nm KDASSERT , +.Nm KDASSERTMSG +.Nd kernel expression verification macros +.Sh SYNOPSIS +.Ft void +.Fn KASSERT expression +.Ft void +.Fn KASSERTMSG expression format ... +.Ft void +.Fn KDASSERT expression +.Ft void +.Fn KDASSERTMSG expression format ... +.Sh DESCRIPTION +These machine independent assertion-checking macros cause a kernel +.Xr panic 9 +if the given +.Ar expression +evaluates to false. +Two compile-time +.Xr options 4 +define the behavior of the checks. +.Bl -enum -offset 2n +.It +The +.Fn KASSERT +and +.Fn KASSERTMSG +tests are included only in kernels compiled with the +.Dv DIAGNOSTIC +configuration option. +In a kernel that does not have this configuration option, +the macros are defined to be no-ops. +.It +The +.Fn KDASSERT +and +.Fn KDASSERTMSG +tests are included only in kernels compiled with the +.Dv DEBUG +configuration option. +The +.Fn KDASSERT +and +.Fn KASSERT +macros are identical except for the controlling option +.Pf ( Dv DEBUG +vs +.Dv DIAGNOSTIC ) . +Basically, +.Fn KASSERT +should be used for light-weight checks and +.Fn KDASSERT +should be used for heavier ones. +.El +.Pp +Callers should not rely on the side effects of +.Ar expression +because, depending on the kernel compile options mentioned above, +.Ar expression +might not be evaluated at all. +.Pp +The panic message will display the style of assertion (debugging +vs. diagnostic), the expression that failed and the filename, and line +number the failure happened on. +The +.Fn KASSERTMSG +and +.Fn KDASSERTMSG +macros append +to the +.Xr panic 9 +format string the message specified by +.Fa format +and its subsequent arguments, similar to +.Xr printf 9 +functions. +.Sh SEE ALSO +.Xr config 1 , +.Xr options 4 , +.Xr CTASSERT 9 , +.Xr panic 9 , +.Xr printf 9 +.Sh AUTHORS +These macros were written by +.An Chris G. Demetriou +.Aq cgd@netbsd.org . diff --git a/static/netbsd/man9/KERNEL_LOCK.9 b/static/netbsd/man9/KERNEL_LOCK.9 new file mode 100644 index 00000000..fca083ff --- /dev/null +++ b/static/netbsd/man9/KERNEL_LOCK.9 @@ -0,0 +1,312 @@ +.\" $NetBSD: KERNEL_LOCK.9,v 1.2 2022/02/15 22:58:25 wiz Exp $ +.\" +.\" Copyright (c) 2022 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 13, 2022 +.Dt KERNEL_LOCK 9 +.Os +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh NAME +.Nm KERNEL_LOCK +.Nd compatibility with legacy uniprocessor code +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SYNOPSIS +.In sys/systm.h +.\" +.Ft void +.Fn KERNEL_LOCK "int nlocks" "struct lwp *l" +.Ft void +.Fn KERNEL_UNLOCK_ONE "struct lwp *l" +.Ft void +.Fn KERNEL_UNLOCK_ALL "struct lwp *l" "int *nlocksp" +.Ft void +.Fn KERNEL_UNLOCK_LAST "struct lwp *l" +.Ft bool +.Fn KERNEL_LOCKED_P +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh DESCRIPTION +The +.Nm +facility serves to gradually transition software from the kernel's +legacy uniprocessor execution model, where the kernel runs on only a +single CPU and never in parallel on multiple CPUs, to a multiprocessor +system. +.Pp +.Sy New code should not use Nm . +.Nm +is meant only for gradual transition of +.Nx +to natively MP-safe code, which uses +.Xr mutex 9 +or other +.Xr locking 9 +facilities to synchronize between threads and interrupt handlers. +Use of +.Nm +hurts system performance and responsiveness. +This man page exists only to document the legacy API in order to make +it easier to transition away from. +.Pp +The kernel lock, sometimes also known as +.Sq giant lock +or +.Sq big lock , +is a recursive exclusive spin-lock that can be held by a CPU at any +interrupt priority level and is dropped while sleeping. +This means: +.Bl -tag -width "held by a CPU" +.It recursive +If a CPU already holds the kernel lock, it can be acquired again and +again, as long as it is released an equal number of times. +.It exclusive +Only one CPU at a time can hold the kernel lock. +.It spin-lock +When one CPU holds the kernel lock and another CPU wants to hold it, +the second CPU +.Sq spins , +i.e., repeatedly executes instructions to see if the kernel lock is +available yet, until the first CPU releases it. +During this time, no other threads can run on the spinning CPU. +.Pp +This means holding the kernel lock for long periods of time, such as +nontrivial computation, must be avoided. +Under +.Dv LOCKDEBUG +kernels, holding the kernel lock for too long can lead to +.Sq spinout +crashes. +.It held by a CPU +The kernel lock is held by a CPU, not by a process, kthread, LWP, or +interrupt handler. +It may be shared by a kthread LWP and several softint LWPs at the same +time, for example, if the softints interrupted the thread on a CPU. +.It any interrupt priority level +The kernel lock +.Em does not +block interrupts; subsystems running with the kernel lock use +.Xr spl 9 +to synchronize with interrupt handlers. +.Pp +Interrupt handlers that are not marked MP-safe are always run with the +kernel lock. +If the interrupt arrives on a CPU where the kernel lock is already +held, it is simply taken again recursively on interrupt entry and +released to its original recursion depth on interrupt exit. +.It dropped while sleeping +Any time the kernel sleeps to let other threads run, for any reason +including +.Xr tsleep 9 +or +.Xr condvar 9 +or even adaptive +.Xr mutex 9 +locks, it releases the kernel lock before going to sleep and then +reacquires it afterward. +.Pp +This means, for instance, that although data structures accessed only +under the kernel lock won't be changed before the sleep, they may be +changed by another thread during the sleep. +For example, the following program may crash on an assertion failure +because the sleep in +.Xr mutex_enter 9 +can allow another CPU to run and change the global variable +.Dv x : +.Bd -literal + KERNEL_LOCK(1, NULL); + x = 42; + mutex_enter(...); + ... + mutex_exit(...); + KASSERT(x == 42); + KERNEL_UNLOCK_ONE(NULL); +.Ed +.Pp +This means simply introducing calls to +.Xr mutex_enter 9 +and +.Xr mutex_exit 9 +can break kernel-locked assumptions. +Subsystems need to be consistently converted from +.Nm +and +.Xr spl 9 +to +.Xr mutex 9 , +.Xr condvar 9 , +etc.; mixing +.Xr mutex 9 +and +.Nm +usually doesn't work. +.El +.Pp +Holding the kernel lock +.Em does not +prevent other code from running on other CPUs at the same time. +It only prevents other +.Em kernel-locked +code from running on other CPUs at the same time. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn KERNEL_LOCK nlocks l +Acquire +.Fa nlocks +recursive levels of kernel lock. +.Pp +If the kernel lock is already held by another CPU, spins until it can +be acquired by this one. +If the kernel lock is already held by this CPU, records the kernel +lock recursion depth and returns immediately. +.Pp +Most of the time +.Fa nlocks +is 1, but code that deliberately releases all of the kernel locks held +by the current CPU in order to sleep and later reacquire the same +number of kernel locks will pass a value of +.Fa nlocks +obtained from +.Fn KERNEL_UNLOCK_ALL . +.It Fn KERNEL_UNLOCK_ONE l +Release one level of the kernel lock. +Equivalent to +.Fo KERNEL_UNLOCK +.Li 1 , +.Fa l , +.Dv NULL +.Fc . +.It Fn KERNEL_UNLOCK_ALL l nlocksp +Store the kernel lock recursion depth at +.Fa nlocksp +and release all recursive levels of the kernel lock. +.Pp +This is often used inside logic implementing sleep, around a call to +.Xr mi_switch 9 , +so that the same number of recursive kernel locks can be reacquired +afterward once the thread is reawoken: +.Bd -literal + int nlocks; + + KERNEL_UNLOCK_ALL(l, &nlocks); + ... mi_switch(l) ... + KERNEL_LOCK(nlocks, l); +.Ed +.It Fn KERNEL_UNLOCK_LAST l +Release the kernel lock, which must be held at exactly one level. +.Pp +This is normally used at the end of a non-MP-safe thread, which was +known to have started with exactly one level of the kernel lock, and is +now about to exit. +.It Fn KERNEL_LOCKED_P +True if the kernel lock is held. +.Pp +To be used only in diagnostic assertions with +.Xr KASSERT 9 . +.El +.Pp +The legacy argument +.Fa l +must be +.Dv NULL +or +.Dv curlwp , +which mean the same thing. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh NOTES +Some +.Nx +kernel abstractions execute caller-specified functions with the kernel +lock held by default, for compatibility with legacy code, but can be +explicitly instructed +.Em not +to hold the kernel lock by passing an MP-safe flag: +.Bl -bullet +.It +.Xr callout 9 , +.Dv CALLOUT_MPSAFE +.It +.Xr kfilter_register 9 +and +.Xr knote 9 , +.Dv FILTEROPS_MPSAFE +.It +.Xr kthread 9 , +.Dv KTHREAD_MPSAFE +.It +.Xr pci_intr 9 , +.Dv PCI_INTR_MPSAFE +.It +.Xr scsipi 9 , +.Dv SCSIPI_ADAPT_MPSAFE +.It +.Xr softint 9 , +.Dv SOFTINT_MPSAFE +.It +.Xr usbdi 9 +pipes, +.Dv USBD_MPSAFE +.It +.Xr usbdi 9 +tasks, +.Dv USB_TASKQ_MPSAFE +.It +.Xr vnode 9 , +.Dv VV_MPSAFE +.It +.Xr workqueue 9 , +.Dv WQ_MPSAFE +.El +.Pp +The following +.Nx +subsystems are still kernel-locked and need re-engineering to take +advantage of parallelism on multiprocessor systems: +.Bl -bullet +.It +.Xr ata 4 , +.Xr atapi 4 , +.Xr wd 4 +.It +.Xr video 4 +.It +.Xr autoconf 9 +.It +most of the network stack by default, unless the option +.Dv NET_MPSAFE +is enabled +.It +.No ... +.El +.Pp +All interrupt handlers at +.Dv IPL_VM , +or lower +.Pq Xr spl 9 +run with the kernel lock on most ports. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SEE ALSO +.Xr locking 9 , +.Xr mutex 9 , +.Xr spl 9 diff --git a/static/netbsd/man9/LWP_CACHE_CREDS.9 b/static/netbsd/man9/LWP_CACHE_CREDS.9 new file mode 100644 index 00000000..33c74a0c --- /dev/null +++ b/static/netbsd/man9/LWP_CACHE_CREDS.9 @@ -0,0 +1,75 @@ +.\" $NetBSD: LWP_CACHE_CREDS.9,v 1.3 2022/05/31 08:43:14 andvar Exp $ +.\" +.\" Copyright (c)2007 YAMAMOTO Takashi, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ------------------------------------------------------------ +.Dd December 9, 2007 +.Dt LWP_CACHE_CREDS 9 +.Os +.\" ------------------------------------------------------------ +.Sh NAME +.Nm LWP_CACHE_CREDS +.Nd synchronize LWP credential with process credential +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In sys/lwp.h +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn LWP_CACHE_CREDS \ +"lwp_t *l" "struct proc *p" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +.Fn LWP_CACHE_CREDS +updates the LWP's cached credential to match with the process' credential +if the latter has been changed after the last synchronization. +.Pp +Each LWPs have its cached credential so that it can be used without +worrying about potential of other LWP changing the process' credential. +.Fn kauth_cred_get +returns the cached credential. +.Pp +.Fn LWP_CACHE_CREDS +is called by MD entry code for system call and various traps. +LWPs which can live in kernel for long period should call +.Fn LWP_CACHE_CREDS +by itself to refresh its credential. +.Pp +.Fn LWP_CACHE_CREDS +takes the following arguments. +.Bl -tag -width l +.It Fa l +The calling lwp. +.It Fa p +The process which the lwp +.Fa l +belongs to. +.El +.Pp +.Fn LWP_CACHE_CREDS +might be implemented as a macro. +.\" ------------------------------------------------------------ +.Sh SEE ALSO +.Xr intro 9 , +.Xr kauth 9 diff --git a/static/netbsd/man9/Makefile b/static/netbsd/man9/Makefile new file mode 100644 index 00000000..bd003b70 --- /dev/null +++ b/static/netbsd/man9/Makefile @@ -0,0 +1,7 @@ +MAN = $(wildcard *.9) +SUBDIRS = man9.i386 \ + man9.sun3 \ + man9.x86 + +include ../../mandoc.mk + diff --git a/static/netbsd/man9/RUN_ONCE.9 b/static/netbsd/man9/RUN_ONCE.9 new file mode 100644 index 00000000..f860fc39 --- /dev/null +++ b/static/netbsd/man9/RUN_ONCE.9 @@ -0,0 +1,136 @@ +.\" $NetBSD: RUN_ONCE.9,v 1.11 2019/03/19 10:17:35 wiz Exp $ +.\" +.\" Copyright (c)2005 YAMAMOTO Takashi, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ------------------------------------------------------------ +.Dd March 19, 2019 +.Dt RUN_ONCE 9 +.Os +.\" ------------------------------------------------------------ +.Sh NAME +.Nm RUN_ONCE , +.Nm INIT_ONCE , +.Nm FINI_ONCE +.Nd run a function exactly once +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In sys/once.h +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Vt ONCE_DECL(control); +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn RUN_ONCE \ +"once_t *control" "int (*init_func)(void)" +.Ft int +.Fn INIT_ONCE \ +"once_t *control" "int (*init_func)(void)" +.Ft void +.Fn FINI_ONCE \ +"once_t *control" "void (*fini_func)(void)" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +.Fn RUN_ONCE +provides a functionality similar to +.Xr pthread_once 3 . +It ensures that, for a given +.Fa control , +.Fn init_func +is executed (successfully) exactly once. +It is considered as a successful execution if and only if +.Fn init_func +returned 0. +As long as there was no successful execution, +.Fn RUN_ONCE +will try again each time it is called. +.Pp +.Fn RUN_ONCE +can sleep if it's called concurrently. +.Pp +.Fn INIT_ONCE +is used in pair with +.Fn FINI_ONCE . +.Fn INIT_ONCE +will only be run once similar to +.Fn RUN_ONCE . +.Fn FINI_ONCE +will only be run at last time if it is called as many times as calling +.Fn INIT_ONCE . +When +.Fn FINI_ONCE +is executed, the next call to +.Fn INIT_ONCE +will be executed again. +That is, +.Fn INIT_ONCE +and +.Fn FINI_ONCE +can be nested. +.\" ------------------------------------------------------------ +.Sh RETURN VALUES +On failure, +.Fn RUN_ONCE +returns what +.Fn init_func +returned. +Otherwise, it returns 0. +.\" ------------------------------------------------------------ +.Sh EXAMPLES +The following example shows how +.Fn RUN_ONCE +is used. +Regardless of how many times +.Fn some_func +is executed, +.Fn init_func +will be executed exactly once. +.Bd -literal +static int +init_func(void) +{ + + /* + * do some initialization. + */ + + return 0; /* success */ +} + +int +some_func(void) +{ + static ONCE_DECL(control); + + RUN_ONCE(&control, init_func); + + /* + * we are sure that init_func has already been completed here. + */ +} +.Ed +.\" ------------------------------------------------------------ +.Sh SEE ALSO +.Xr pthread_once 3 , +.Xr condvar 9 , +.Xr intro 9 diff --git a/static/netbsd/man9/SET.9 b/static/netbsd/man9/SET.9 new file mode 100644 index 00000000..6507c091 --- /dev/null +++ b/static/netbsd/man9/SET.9 @@ -0,0 +1,71 @@ +.\" $NetBSD: SET.9,v 1.5 2015/12/13 23:32:52 wiz Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 13, 2015 +.Dt SET 9 +.Os +.Sh NAME +.Nm SET +.Nd primitive bit macros +.Sh SYNOPSIS +.In sys/types.h +.Ft void +.Fn SET "val" "x" +.Ft int +.Fn ISSET "val" "x" +.Ft void +.Fn CLR "val" "x" +.Sh DESCRIPTION +These macros define three standard bit operations: +.Bl -enum -offset indent +.It +.Fn SET +sets the set bits from +.Fa x +in +.Fa val ; +.It +.Fn CLR +clears the set bits from +.Fa x +in +.Fa val ; +and +.It +.Fn ISSET +returns true if any of the set bits from +.Fa x +are set in +.Fa val . +.El +.Sh SEE ALSO +.Xr bits 3 +.Sh BUGS +The rationale is to provide clarity in the source code, +but arguably these operations are clear enough without the use of the macros. diff --git a/static/netbsd/man9/STACK.9 b/static/netbsd/man9/STACK.9 new file mode 100644 index 00000000..f459d5cb --- /dev/null +++ b/static/netbsd/man9/STACK.9 @@ -0,0 +1,97 @@ +.\" $NetBSD: STACK.9,v 1.2 2011/04/08 07:55:04 jruoho Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 8, 2011 +.Dt STACK 9 +.Os +.Sh NAME +.Nm STACK +.Nd stack macros +.Sh SYNOPSIS +.In sys/param.h +.Ft type +.Fn STACK_ALLOC "sp" "size" +.Ft type +.Fn STACK_MAX "sp" "size" +.Ft type +.Fn STACK_ALIGN "sp" "bytes" +.Ft type +.Fn STACK_GROW "sp" "size" +.Ft type +.Fn STACK_SHRINK "sp" "size" +.Sh DESCRIPTION +A stack is an area of memory with a fixed origin but with a variable size. +A stack pointer points to the most recently referenced location on the stack. +Initially, when the stack has a size of zero, +the stack pointer points to the origin of the stack. +When data items are added to the stack, +the stack pointer moves away from the origin. +.Pp +The +.Fn STACK_ALLOC +macro returns a pointer to allocated stack space of some +.Fa size . +Given the returned pointer +.Fa sp +and +.Fa size , +.Fn STACK_MAX +returns the maximum stack address of the allocated stack space. +The +.Fn STACK_ALIGN +macro can be used to align the stack pointer +.Fa sp +by the specified amount of +.Fa bytes . +.Pp +Two basic operations are common to all stacks: +a data item is added +.Pq Dq push +to the location pointed by +.Fa sp +or a data item is removed +.Pq Dq pop +from the stack. +The stack pointer must be subsequently adjusted by the size of the data item. +The +.Fn STACK_GROW +and +.Fn STACK_SHRINK +macros adjust the stack pointer +.Fa sp +by given +.Fa size . +.Pp +A stack may grow either up or down. +The described macros take this into account by using the +.Dv __MACHINE_STACK_GROWS_UP +preprocessor define. +.Sh SEE ALSO +.Xr param 3 , +.Xr queue 3 diff --git a/static/netbsd/man9/VOP_ACLCHECK.9 b/static/netbsd/man9/VOP_ACLCHECK.9 new file mode 100644 index 00000000..b6e0c5ed --- /dev/null +++ b/static/netbsd/man9/VOP_ACLCHECK.9 @@ -0,0 +1,103 @@ +.\" $NetBSD: VOP_ACLCHECK.9,v 1.2 2022/01/17 23:12:41 wiz Exp $ +.\"- +.\" Copyright (c) 1999 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/share/man/man9/VOP_ACLCHECK.9 206622 2010-04-14 19:08:06Z uqs $ +.\" +.Dd January 17, 2022 +.Dt VOP_ACLCHECK 9 +.Os +.Sh NAME +.Nm VOP_ACLCHECK +.Nd check an access control list for a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/acl.h +.Ft int +.Fn VOP_ACLCHECK "struct vnode *vp" "acl_type_t type" "struct acl *aclp" "kauth_cred_t cred" +.Sh DESCRIPTION +This vnode call may be used to determine the validity of a particular access +control list (ACL) for a particular file or directory. +.Pp +Its arguments are: +.Bl -tag -width type +.It Fa vp +The vnode of the file or directory. +.It Fa type +The type of ACL to check. +.It Fa aclp +A pointer to an ACL structure from which to retrieve the ACL data. +.It Fa cred +The user credentials to use in authorizing the request. +.El +.Pp +The +.Fa cred +pointer may be +.Dv NULL +to indicate that access control checks are not to be +performed, if possible. +This cred setting might be used to allow the +kernel to authorize ACL verification that the active process might not be +permitted to do. +.Pp +The vnode ACL interface defines the syntax, and not semantics, of file and +directory ACL interfaces. +More information about ACL management in kernel +may be found in +.Xr acl 9 . +.Sh LOCKS +No locks are required to call this vnode method, and any locks held on +entry will be held on exit. +.Sh RETURN VALUES +If the +.Fa aclp +pointer points to a valid ACL of type +.Fa type +for the object +.Fa vp , +then zero is returned. +Otherwise, an appropriate error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACCES +The file or directory ACL does not permit access. +.It Bq Er EINVAL +The ACL type passed is invalid for this vnode, or the ACL data is invalid. +.It Bq Er ENOMEM +Sufficient memory is not available to fulfill the request. +.It Bq Er EOPNOTSUPP +The file system does not support +.Fn VOP_ACLCHECK . +.El +.Sh SEE ALSO +.Xr acl 9 , +.Xr vnode 9 , +.Xr VOP_GETACL 9 , +.Xr VOP_SETACL 9 +.Sh AUTHORS +This manual page was written by +.An Robert Watson . diff --git a/static/netbsd/man9/VOP_GETACL.9 b/static/netbsd/man9/VOP_GETACL.9 new file mode 100644 index 00000000..4d3e23ad --- /dev/null +++ b/static/netbsd/man9/VOP_GETACL.9 @@ -0,0 +1,95 @@ +.\" $NetBSD: VOP_GETACL.9,v 1.2 2022/01/17 23:12:41 wiz Exp $ +.\"- +.\" Copyright (c) 1999, 2000, 2001 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/share/man/man9/VOP_GETACL.9 235319 2012-05-12 03:46:43Z gjb $ +.\" +.Dd January 17, 2022 +.Dt VOP_GETACL 9 +.Os +.Sh NAME +.Nm VOP_GETACL +.Nd retrieve access control list for a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/acl.h +.Ft int +.Fn VOP_GETACL "struct vnode *vp" "acl_type_t type" "struct acl *aclp" "kauth_cred_t cred" +.Sh DESCRIPTION +This vnode call may be used to retrieve the access control list (ACL) from a +file or directory. +.Pp +Its arguments are: +.Bl -tag -width type +.It Fa vp +The vnode of the file or directory. +.It Fa type +The type of ACL to retrieve. +.It Fa aclp +A pointer to an ACL structure to receive the ACL data. +.It Fa cred +The user credentials to use in authorizing the request. +.El +.Pp +The +.Fa cred +pointer may be +.Dv NULL +to indicate that access control checks are not to be performed, if possible. +This cred setting might be used to allow the kernel to authorize ACL +retrieval that the active process might not be permitted to do. +.Pp +The vnode ACL interface defines the syntax, and not semantics, of file and +directory ACL interfaces. +More information about ACL management in kernel may be found in +.Xr acl 9 . +.Sh LOCKS +The vnode will be locked on entry and should remain locked on return. +.Sh RETURN VALUES +If the +.Fa aclp +pointer will point to a valid ACL, then zero is returned. +Otherwise, an appropriate error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACCES +The caller does not have the appropriate privilege. +.It Bq Er EINVAL +The ACL type passed is invalid for this vnode. +.It Bq Er ENOMEM +Sufficient memory is not available to fulfill the request. +.It Bq Er EOPNOTSUPP +The file system does not support +.Fn VOP_GETACL . +.El +.Sh SEE ALSO +.Xr acl 9 , +.Xr vnode 9 , +.Xr VOP_ACLCHECK 9 , +.Xr VOP_SETACL 9 +.Sh AUTHORS +This manual page was written by +.An Robert Watson . diff --git a/static/netbsd/man9/VOP_SETACL.9 b/static/netbsd/man9/VOP_SETACL.9 new file mode 100644 index 00000000..f8706939 --- /dev/null +++ b/static/netbsd/man9/VOP_SETACL.9 @@ -0,0 +1,104 @@ +.\" $NetBSD: VOP_SETACL.9,v 1.2 2022/01/17 23:12:41 wiz Exp $ +.\"- +.\" Copyright (c) 1999, 2000, 2001 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/share/man/man9/VOP_SETACL.9 235319 2012-05-12 03:46:43Z gjb $ +.\" +.Dd January 17, 2022 +.Dt VOP_SETACL 9 +.Os +.Sh NAME +.Nm VOP_SETACL +.Nd set the access control list for a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/acl.h +.Ft int +.Fn VOP_SETACL "struct vnode *vp" "acl_type_t type" "struct acl *aclp" "kauth_cred_t cred" +.Sh DESCRIPTION +This vnode call may be used to set the access control list (ACL) for a file +or directory. +.Pp +Its arguments are: +.Bl -tag -width type +.It Fa vp +The vnode of the file or directory. +.It Fa type +The type of ACL to set. +.It Fa aclp +A pointer to an ACL structure from which to retrieve the ACL data. +.It Fa cred +The user credentials to use in authorizing the request. +.El +.Pp +The +.Fa aclp +pointer may be +.Dv NULL +to indicate that the specified ACL should be deleted. +.Pp +The +.Fa cred +pointer may be +.Dv NULL +to indicate that access control checks are not to be performed, if possible. +This cred setting might be used to allow the kernel to authorize ACL +changes that the active process might not be permitted to make. +.Pp +The vnode ACL interface defines the syntax, and not semantics, of file and +directory ACL interfaces. +More information about ACL management in kernel +may be found in +.Xr acl 9 . +.Sh LOCKS +The vnode will be locked on entry and should remain locked on return. +.Sh RETURN VALUES +If the ACL is successfully set, then zero is returned. +Otherwise, an appropriate error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACCES +The caller does not have the appropriate privilege. +.It Bq Er EINVAL +The ACL type passed is invalid for this vnode, or the ACL data is invalid. +.It Bq Er ENOMEM +Sufficient memory is not available to fulfill the request. +.It Bq Er ENOSPC +The file system is out of space. +.It Bq Er EOPNOTSUPP +The file system does not support +.Fn VOP_SETACL . +.It Bq Er EROFS +The file system is read-only. +.El +.Sh SEE ALSO +.Xr acl 9 , +.Xr vnode 9 , +.Xr VOP_ACLCHECK 9 , +.Xr VOP_GETACL 9 +.Sh AUTHORS +This manual page was written by +.An Robert Watson . diff --git a/static/netbsd/man9/__cpu_simple_lock.9 b/static/netbsd/man9/__cpu_simple_lock.9 new file mode 100644 index 00000000..a847517c --- /dev/null +++ b/static/netbsd/man9/__cpu_simple_lock.9 @@ -0,0 +1,235 @@ +.\" $NetBSD: __cpu_simple_lock.9,v 1.2 2024/10/26 03:05:06 riastradh Exp $ +.\" +.\" Copyright (c) 2022 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 25, 2024 +.Dt __CPU_SIMPLE_LOCK 9 +.Os +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh NAME +.Nm __cpu_simple_lock +.Nd simple spin locks +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SYNOPSIS +.In sys/lock.h +.\" +.Ft void +.Fn __cpu_simple_lock_init "__cpu_simple_lock_t *lock" +.\" +.Vt #define __SIMPLELOCK_UNLOCKED ... +.\" +.Ft void +.Fn __cpu_simple_lock "__cpu_simple_lock_t *lock" +.Ft int +.Fn __cpu_simple_lock_try "__cpu_simple_lock *lock" +.Ft void +.Fn __cpu_simple_unlock "__cpu_simple_lock_t *lock" +.\" +.Ft int +.Fn __SIMPLELOCK_LOCKED_P "__cpu_simple_lock *lock" +.\" +.Fd "/* obsolete and for ABI compat only -- do not use */" +.Ft void +.Fn __cpu_simple_lock_set "__cpu_simple_Lock *lock" +.Ft void +.Fn __cpu_simple_lock_clear "__cpu_simple_lock *lock" +.Ft int +.Fn __SIMPLELOCK_UNLOCKED_P "__cpu_simple_lock *lock" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh DESCRIPTION +The +.Nm +functions provide a simple spin-lock facility for limited purposes that +cannot be served by +.Xr mutex 9 , +such as inside the implementation of +.Xr mutex 9 +itself on platforms with limited atomic read/modify/write operations. +.Pp +.Nm +is very limited: +.Bl -bullet +.It +.Nm +provides no debugging or diagnostic support through the +.Dv LOCKDEBUG +option. +.It +.Nm +does not synchronize between code on a CPU and interrupt handlers +running on that CPU \(em you must use it with +.Xr spl 9 +for any locks that may be taken in interrupt context; failing to do so +will likely lead to hard-to-debug deadlock. +.It +.Nm +does not block preemption, so a thread holding a lock may be preempted, +potentially requiring other callers to spin for long durations until +the scheduler runs the holder again. +.It +.Nm +does no exponential backoff to reduce memory traffic during +contention. +.El +.Pp +Unless you know what you are doing, you should use +.Xr mutex 9 +instead. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh INITIALIZATION +The macro +.Dv __SIMPLELOCK_UNLOCKED +expands to an initializer for the type +.Vt __cpu_simple_lock_t : +.Dl "__cpu_simple_lock_t lock = __SIMPLELOCK_UNLOCKED;" +.Pp +A +.Vt __cpu_simple_lock_t +object can also be initialized with +.Fn __cpu_simple_lock_init . +.Pp +No actions are needed to destroy a +.Vt __cpu_simple_lock_t +object. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn __cpu_simple_lock_init lock +Initialize +.Fa lock +for use with the other +.Nm +functions. +.Pp +The caller is responsible for ensuring +.Fn __cpu_simple_lock_init +happens before any use of the other functions. +.Fn __cpu_simple_lock_init +implies no particular memory ordering on its own. +.\"""""""""""""""" +.It Fn __cpu_simple_lock lock +Acquire +.Fa lock , +waiting until it is released if currently held. +.Pp +Any memory operations preceding the previous +.Fn __cpu_simple_unlock +call that released the lock happen before any memory operations after +the next +.Fn __cpu_simple_lock +call that acquires it. +.\"""""""""""""""" +.It Fn __cpu_simple_lock_try lock +Try to acquire +.Fa lock , +without waiting if it is currently held. +Return 1 if successful, 0 if not. +.Pp +Any memory operations preceding the previous +.Fn __cpu_simple_unlock +call that released the lock happen before any memory operations after +the next +.Em successful +.Fn __cpu_simple_lock_try +call that acquires it. +.\"""""""""""""""" +.It Fn __cpu_simple_unlock lock +Release +.Fa lock . +.Pp +Any memory operations preceding +.Fn __cpu_simple_unlock +happen before the next call to +.Fn __cpu_simple_lock , +or the next successful call to +.Fn __cpu_simple_lock_try , +that acquires +.Fa lock . +.\"""""""""""""""" +.It Fn __SIMPLELOCK_LOCKED_P lock +True if +.Fa lock +is currently locked, by anyone. +.Pp +This is normally only used for diagnostic assertions, or for loops +around +.Fn __cpu_simple_lock_try +that also have higher-level functions like blocking interrupts and +performing exponential backoff. +.Pp +No memory ordering is implied. +.El +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh OBSOLETE FUNCTIONS +The following functions abuse the +.Vt __cpu_simple_lock_t +type to store a boolean. +They are used inside the +.Xr pthread 3 +library, and were included in the library ABI, so they can't be removed +without breaking the +.Xr pthread 3 +ABI. +Do not use these in new code +.Po +except +.Fn __SIMPLELOCK_LOCKED_P +.Pc . +.Bl -tag -width ".Fn __SIMPLELOCK_UNLOCKED_P lock" +.It Fn __cpu_simple_lock_set lock +Set +.Fa lock +to true. +.It Fn __cpu_simple_lock_clear lock +Set +.Fa lock +to false. +.It Fn __SIMPLELOCK_LOCKED_P lock +True iff +.Fa lock +is true. +.It Fn __SIMPLELOCK_UNLOCKED_P lock +True iff +.Fa lock +is false. +.El +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh CODE REFERENCES +The +.Nm +functions are implemented in +.Pa sys/arch/$ARCH/include/lock.h . +.Pp +A machine-independent implementation, using compiler support for +atomic and memory barrier builtins, is available in +.Pa sys/sys/common_lock.h . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SEE ALSO +.Xr locking 9 , +.Xr mutex 9 +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh HISTORY +.Nm +appeared a long time ago. diff --git a/static/netbsd/man9/accept_filter.9 b/static/netbsd/man9/accept_filter.9 new file mode 100644 index 00000000..741731f4 --- /dev/null +++ b/static/netbsd/man9/accept_filter.9 @@ -0,0 +1,163 @@ +.\" $NetBSD: accept_filter.9,v 1.5 2009/04/10 18:15:26 wiz Exp $ +.\" +.\" Copyright (c) 2000 Alfred Perlstein +.\" +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man9/accept_filter.9,v 1.13 2004/06/16 08:33:57 ru Exp $ +.\" " +.Dd November 12, 2008 +.Dt ACCEPT_FILTER 9 +.Os +.Sh NAME +.Nm accept_filter , +.Nm accept_filt_add , +.Nm accept_filt_del , +.Nm accept_filt_generic_mod_event , +.Nm accept_filt_get +.Nd filter incoming connections +.Sh SYNOPSIS +.Fd #define ACCEPT_FILTER_MOD +.In sys/param.h +.In sys/kernel.h +.In sys/sysctl.h +.In sys/signalvar.h +.In sys/socketvar.h +.In netinet/accept_filter.h +.Ft int +.Fn accept_filt_add "struct accept_filter *filt" +.Ft int +.Fn accept_filt_del "char *name" +.Ft int +.Fn accept_filt_generic_mod_event "module_t mod" "int event" "void *data" +.Ft struct accept_filter * +.Fn accept_filt_get "char *name" +.Sh DESCRIPTION +Accept filters allow an application to request +that the kernel pre-process incoming connections. +This manual page describes the kernel interface for accept filters. +User applications request accept filters via the +.Xr setsockopt 2 +system call, passing in an +.Fa optname +of +.Dv SO_ACCEPTFILTER . +.Sh IMPLEMENTATION NOTES +A module that wants to be an accept filter +must provide a +.Vt "struct accept_filter" +to the system: +.Bd -literal +struct accept_filter { + char accf_name[16]; + void (*accf_callback)(struct socket *so, void *arg, int waitflag); + void * (*accf_create)(struct socket *so, char *arg); + void (*accf_destroy)(struct socket *so); + SLIST_ENTRY(accept_filter) accf_next; /* next on the list */ +}; +.Ed +.Pp +The module should register it with the function +.Fn accept_filt_add , +passing a pointer to a +.Vt "struct accept_filter" , +allocated with +.Xr malloc 9 . +.Pp +The accept filters currently provided with +.Nx +.Xr ( accf_data 9 +and +.Xr accf_http 9 ) +are implemented as pseudo-devices, but an accept filter may use any +supported means of initializing and registering itself at system startup +or later, including the module framework if supported +by the running kernel. +.Pp +The fields of +.Vt "struct accept_filter" +are as follows: +.Bl -tag -width ".Va accf_callback" +.It Va accf_name +Name of the filter; +this is how it will be accessed from userland. +.It Va accf_callback +The callback that the kernel will do +once the connection is established. +It is the same as a socket upcall +and will be called when the connection is established +and whenever new data arrives on the socket, +unless the callback modifies the socket's flags. +.It Va accf_create +Called whenever a +.Xr setsockopt 2 +installs the filter onto +a listening socket. +.It Va accf_destroy +Called whenever the user removes the accept filter on the socket. +.El +.Pp +The +.Fn accept_filt_del +function +passed the same string used in +.Va accept_filter.accf_name +during registration with +.Fn accept_filt_add , +the kernel will then disallow and further userland use of the filter. +.Pp +The +.Fn accept_filt_get +function is used internally to locate which accept filter to use via the +.Xr setsockopt 2 +system call. +.Pp +The +.Fn accept_filt_generic_mod_event +function can be used by accept filters which are loadable kernel modules +to add and delete themselves. +.Sh SEE ALSO +.Xr setsockopt 2 , +.Xr accf_data 9 , +.Xr accf_http 9 , +.Xr malloc 9 +.Sh HISTORY +The accept filter mechanism was introduced in +.Fx 4.0 . +It was ported to +.Nx +by Coyote Point Systems, Inc. and appeared in +.Nx 5.0 . +.Sh AUTHORS +This manual page was written by +.An -nosplit +.An Alfred Perlstein , +.An Sheldon Hearn , +and +.An Jeroen Ruigrok van der Werven . +.Pp +The accept filter concept was pioneered by +.An David Filo +at Yahoo!\& +and refined to be a loadable module system by +.An Alfred Perlstein . diff --git a/static/netbsd/man9/accf_data.9 b/static/netbsd/man9/accf_data.9 new file mode 100644 index 00000000..a1e20948 --- /dev/null +++ b/static/netbsd/man9/accf_data.9 @@ -0,0 +1,75 @@ +.\" $NetBSD: accf_data.9,v 1.6 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright (c) 2000 Alfred Perlstein +.\" +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man9/accf_data.9,v 1.8 2005/01/18 20:52:51 ru Exp $ +.\" " +.Dd August 10, 2008 +.Dt ACCF_DATA 9 +.Os +.Sh NAME +.Nm accf_data +.Nd buffer incoming connections until data arrives +.Sh SYNOPSIS +.Cd "options INET" +.Cd "pseudo-device accf_data" +.Sh DESCRIPTION +This is a filter to be placed on a socket that will be using +.Fn accept +to receive incoming connections. +.Pp +It prevents the application from receiving the connected descriptor via +.Fn accept +until data arrives on the connection. +.Sh EXAMPLES +If the +.Nm +accept filter is present in the kernel configuration, +this will enable the data accept filter +on the socket +.Fa sok . +.Bd -literal -offset 0i + struct accept_filter_arg afa; + + bzero(&afa, sizeof(afa)); + strcpy(afa.af_name, "dataready"); + setsockopt(sok, SOL_SOCKET, SO_ACCEPTFILTER, &afa, sizeof(afa)); +.Ed +.Sh SEE ALSO +.Xr setsockopt 2 , +.Xr accept_filter 9 , +.Xr accf_http 9 +.Sh HISTORY +The accept filter mechanism and the +.Nm +filter were introduced in +.Fx 4.0 . +They were ported to +.Nx +by Coyote Point Systems and appeared in +.Nx 5.0 . +.Sh AUTHORS +This manual page and the filter were written by +.An Alfred Perlstein . diff --git a/static/netbsd/man9/accf_http.9 b/static/netbsd/man9/accf_http.9 new file mode 100644 index 00000000..327bb910 --- /dev/null +++ b/static/netbsd/man9/accf_http.9 @@ -0,0 +1,102 @@ +.\" $NetBSD: accf_http.9,v 1.8 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright (c) 2000 Alfred Perlstein +.\" +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man9/accf_http.9,v 1.11 2005/01/18 20:52:51 ru Exp $ +.\" " +.Dd September 4, 2008 +.Dt ACCF_HTTP 9 +.Os +.Sh NAME +.Nm accf_http +.Nd "buffer incoming connections until a certain complete HTTP requests arrive" +.Sh SYNOPSIS +.Cd "options INET" +.Cd "pseudo-device accf_http" +.Sh DESCRIPTION +This is a filter to be placed on a socket that will be using +.Fn accept +to receive incoming HTTP connections. +.Pp +Once installed on a listening socket, this filter is activated when a +connection becomes ready to receive data (at which point +.Xr accept 2 +would usually return the connected descriptor to the application). +The filter prevents the descriptor from being returned immediately +to the application via +.Xr accept 2 . +The descriptor is made available to the application via +.Xr accept 2 +only when one of the following conditions is met: +.Bl -enum +.It +A complete, syntactically valid HTTP/1.0 or HTTP/1.1 HEAD or GET request has +been buffered by the kernel. +.It +The data buffered by the kernel cannot be part of a complete, syntactically +valid HTTP 1.0 or HTTP/1.1 HEAD or GET request. +.El +.Pp +The utility of +.Nm +is that a server will not have to context switch several times +before performing the initial parsing of the request. +This effectively reduces the amount of required CPU utilization +to handle incoming requests by keeping active +processes in preforking servers such as Apache low +and reducing the size of the file descriptor set that needs +to be managed by interfaces such as +.Fn select , +.Fn poll +or +.Fn kevent +based servers. +.Sh EXAMPLES +If the accf_data accept filter is present in the kernel configuration, +this will enable the http accept filter +on the socket +.Fa sok . +.Bd -literal -offset 0i + struct accept_filter_arg afa; + + bzero(&afa, sizeof(afa)); + strcpy(afa.af_name, "httpready"); + setsockopt(sok, SOL_SOCKET, SO_ACCEPTFILTER, &afa, sizeof(afa)); +.Ed +.Sh SEE ALSO +.Xr setsockopt 2 , +.Xr accept_filter 9 +.Sh HISTORY +The accept filter mechanism and the +.Nm +filter were introduced in +.Fx 4.0 . +They were ported to +.Nx +by Coyote Point Systems and appeared in +.Nx 5.0 . +.Sh AUTHORS +This manual page and the filter were written by +.An Alfred Perlstein . diff --git a/static/netbsd/man9/acct_process.9 b/static/netbsd/man9/acct_process.9 new file mode 100644 index 00000000..dc23ff09 --- /dev/null +++ b/static/netbsd/man9/acct_process.9 @@ -0,0 +1,61 @@ +.\" $NetBSD: acct_process.9,v 1.2 2024/08/05 13:40:51 uwe Exp $ +.\" +.\" Copyright (c) 2024 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 5, 2024 +.Dt ACCT_PROCESS 9 +.Os +.Sh NAME +.Nm acct_process +.Nd populate and write the process accounting record +.Sh SYNOPSIS +.In sys/acct.h +.Ft int +.Fn acct_process "struct lwp *l" +.Sh DESCRIPTION +The +.Nm +function is called when the process exits. +If accounting is turned off, it returns immediately. +If accounting is turned on via +.Xr acct 2 , +then the +.Nm +populates the accounting structure described in +.Xr acct 5 , +then writes the accounting record to the file specified by +.Xr acct 2 . +.Sh RETURN VALUES +.Nm +returns 0 on success and the same error codes as +.Xr vn_rdwr 9 +on failure. +.Sh SEE ALSO +.Xr acct 2 , +.Xr acct 5 , +.Xr vn_rdwr 9 . diff --git a/static/netbsd/man9/acl.9 b/static/netbsd/man9/acl.9 new file mode 100644 index 00000000..92edf374 --- /dev/null +++ b/static/netbsd/man9/acl.9 @@ -0,0 +1,226 @@ +.\" $NetBSD: acl.9,v 1.4 2022/01/18 20:38:28 christos Exp $ +.\"- +.\" Copyright (c) 1999-2001 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/share/man/man9/acl.9 287445 2015-09-04 00:14:20Z delphij $ +.\" +.Dd January 18, 2022 +.Dt ACL 9 +.Os +.Sh NAME +.Nm acl +.Nd virtual file system access control lists +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/acl.h +.Pp +In the kernel configuration file: +.Cd "options UFS_ACL" +.Sh DESCRIPTION +Access control lists, or ACLs, +allow fine-grained specification of rights +for vnodes representing files and directories. +However, as there are a plethora of file systems with differing ACL semantics, +the vnode interface is aware only of the syntax of ACLs, +relying on the underlying file system to implement the details. +Depending on the underlying file system, each file or directory +may have zero or more ACLs associated with it, named using the +.Fa type +field of the appropriate vnode ACL calls: +.Xr VOP_ACLCHECK 9 , +.Xr VOP_GETACL 9 , +and +.Xr VOP_SETACL 9 . +.Pp +Currently, each ACL is represented in-kernel by a fixed-size +.Vt acl +structure, defined as follows: +.Bd -literal -offset indent +struct acl { + unsigned int acl_maxcnt; + unsigned int acl_cnt; + int acl_spare[4]; + struct acl_entry acl_entry[ACL_MAX_ENTRIES]; +}; +.Ed +.Pp +An ACL is constructed from a fixed size array of ACL entries, +each of which consists of a set of permissions, principal namespace, +and principal identifier. +In this implementation, the +.Vt acl_maxcnt +field is always set to +.Dv ACL_MAX_ENTRIES . +.Pp +Each individual ACL entry is of the type +.Vt acl_entry_t , +which is a structure with the following members: +.Bl -tag -width 2n +.It Vt acl_tag_t Va ae_tag +The following is a list of definitions of ACL types +to be set in +.Va ae_tag : +.Pp +.Bl -tag -width ".Dv ACL_UNDEFINED_FIELD" -offset indent -compact +.It Dv ACL_UNDEFINED_FIELD +Undefined ACL type. +.It Dv ACL_USER_OBJ +Discretionary access rights for processes whose effective user ID +matches the user ID of the file's owner. +.It Dv ACL_USER +Discretionary access rights for processes whose effective user ID +matches the ACL entry qualifier. +.It Dv ACL_GROUP_OBJ +Discretionary access rights for processes whose effective group ID +or any supplemental groups +match the group ID of the file's owner. +.It Dv ACL_GROUP +Discretionary access rights for processes whose effective group ID +or any supplemental groups +match the ACL entry qualifier. +.It Dv ACL_MASK +The maximum discretionary access rights that can be granted +to a process in the file group class. +This is only valid for POSIX.1e ACLs. +.It Dv ACL_OTHER +Discretionary access rights for processes not covered by any other ACL +entry. +This is only valid for POSIX.1e ACLs. +.It Dv ACL_OTHER_OBJ +Same as +.Dv ACL_OTHER . +.It Dv ACL_EVERYONE +Discretionary access rights for all users. +This is only valid for NFSv4 ACLs. +.El +.Pp +Each POSIX.1e ACL must contain exactly one +.Dv ACL_USER_OBJ , +one +.Dv ACL_GROUP_OBJ , +and one +.Dv ACL_OTHER . +If any of +.Dv ACL_USER , +.Dv ACL_GROUP , +or +.Dv ACL_OTHER +are present, then exactly one +.Dv ACL_MASK +entry should be present. +.It Vt uid_t Va ae_id +The ID of user for whom this ACL describes access permissions. +For entries other than +.Dv ACL_USER +and +.Dv ACL_GROUP , +this field should be set to +.Dv ACL_UNDEFINED_ID . +.It Vt acl_perm_t Va ae_perm +This field defines what kind of access the process matching this ACL has +for accessing the associated file. +For POSIX.1e ACLs, the following are valid: +.Bl -tag -width ".Dv ACL_WRITE_NAMED_ATTRS" +.It Dv ACL_EXECUTE +The process may execute the associated file. +.It Dv ACL_WRITE +The process may write to the associated file. +.It Dv ACL_READ +The process may read from the associated file. +.It Dv ACL_PERM_NONE +The process has no read, write or execute permissions +to the associated file. +.El +.Pp +For NFSv4 ACLs, the following are valid: +.Bl -tag -width ".Dv ACL_WRITE_NAMED_ATTRS" +.It Dv ACL_READ_DATA +The process may read from the associated file. +.It Dv ACL_LIST_DIRECTORY +Same as +.Dv ACL_READ_DATA . +.It Dv ACL_WRITE_DATA +The process may write to the associated file. +.It Dv ACL_ADD_FILE +Same as +.Dv ACL_ACL_WRITE_DATA . +.It Dv ACL_APPEND_DATA +.It Dv ACL_ADD_SUBDIRECTORY +Same as +.Dv ACL_APPEND_DATA . +.It Dv ACL_READ_NAMED_ATTRS +Ignored. +.It Dv ACL_WRITE_NAMED_ATTRS +Ignored. +.It Dv ACL_EXECUTE +The process may execute the associated file. +.It Dv ACL_DELETE_CHILD +.It Dv ACL_READ_ATTRIBUTES +.It Dv ACL_WRITE_ATTRIBUTES +.It Dv ACL_DELETE +.It Dv ACL_READ_ACL +.It Dv ACL_WRITE_ACL +.It Dv ACL_WRITE_OWNER +.It Dv ACL_SYNCHRONIZE +Ignored. +.El +.It Vt acl_entry_type_t Va ae_entry_type +This field defines the type of NFSv4 ACL entry. +It is not used with POSIX.1e ACLs. +The following values are valid: +.Bl -tag -width ".Dv ACL_WRITE_NAMED_ATTRS" +.It Dv ACL_ENTRY_TYPE_ALLOW +.It Dv ACL_ENTRY_TYPE_DENY +.El +.It Vt acl_flag_t Va ae_flags +This field defines the inheritance flags of NFSv4 ACL entry. +It is not used with POSIX.1e ACLs. +The following values are valid: +.Bl -tag -width ".Dv ACL_ENTRY_DIRECTORY_INHERIT" +.It Dv ACL_ENTRY_FILE_INHERIT +.It Dv ACL_ENTRY_DIRECTORY_INHERIT +.It Dv ACL_ENTRY_NO_PROPAGATE_INHERIT +.It Dv ACL_ENTRY_INHERIT_ONLY +.It Dv ACL_ENTRY_INHERITED +.El +The +.Dv ACL_ENTRY_INHERITED +flag is set on an ACE that has been inherited from its parent. +It may also be set programmatically, and is valid on both files +and directories. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr genfs 9 , +.Xr genfs_can_access 9 , +.Xr genfs_can_access_acl_nfs4 9 , +.Xr genfs_can_access_acl_posix1e 9 , +.Xr VOP_ACLCHECK 9 , +.Xr VOP_GETACL 9 , +.Xr VOP_SETACL 9 +.Sh AUTHORS +This manual page was written by +.An Robert Watson . diff --git a/static/netbsd/man9/altq.9 b/static/netbsd/man9/altq.9 new file mode 100644 index 00000000..c5ef81ea --- /dev/null +++ b/static/netbsd/man9/altq.9 @@ -0,0 +1,601 @@ +.\" $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 +.\" Sony Computer Science Laboratories Inc. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY SONY CSL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL SONY CSL OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd October 24, 2022 +.Dt ALTQ 9 +.Os +.\" +.Sh NAME +.Nm ALTQ +.Nd kernel interfaces for manipulating output queues on network interfaces +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In net/if.h +.Ft void \"macro +.Fn IFQ_ENQUEUE "struct ifaltq *ifq" "struct mbuf *m" "struct altq_pktattr *pattr" "int err" +.Ft void \"macro +.Fn IFQ_DEQUEUE "struct ifaltq *ifq" "struct mbuf *m" +.Ft void \"macro +.Fn IFQ_POLL "struct ifaltq *ifq" "struct mbuf *m" +.Ft void \"macro +.Fn IFQ_PURGE "struct ifaltq *ifq" +.Ft void \"macro +.Fn IFQ_CLASSIFY "struct ifaltq *ifq" "struct mbuf *m" "int af" "struct altq_pktattr *pattr" +.Ft void \"macro +.Fn IFQ_IS_EMPTY "struct ifaltq *ifq" +.Ft void \"macro +.Fn IFQ_SET_MAXLEN "struct ifaltq *ifq" "int len" +.Ft void \"macro +.Fn IFQ_INC_LEN "struct ifaltq *ifq" +.Ft void \"macro +.Fn IFQ_DEC_LEN "struct ifaltq *ifq" +.Ft void \"macro +.Fn IFQ_INC_DROPS "struct ifaltq *ifq" +.Ft void \"macro +.Fn IFQ_SET_READY "struct ifaltq *ifq" +.Sh DESCRIPTION +The +.Nm +system is a framework to manage queueing disciplines on network +interfaces. +.Nm +introduces new macros to manipulate output queues. +The output queue macros are used to abstract queue operations and not to +touch the internal fields of the output queue structure. +The macros are independent from the +.Nm +implementation, and compatible with the traditional +.Dv ifqueue +macros for ease of transition. +.Pp +.Fn IFQ_ENQUEUE +enqueues a packet +.Fa m +to the queue +.Fa ifq . +The underlying queueing discipline may discard the packet. +.Fa err +is set to 0 on success, or +.Dv ENOBUFS +if the packet is discarded. +.Fa m +will be freed by the device driver on success or by the queueing discipline on +failure, so that the caller should not touch +.Fa m +after calling +.Fn IFQ_ENQUEUE . +.Pp +.Fn IFQ_DEQUEUE +dequeues a packet from the queue. +The dequeued packet is returned in +.Fa m , +or +.Fa m +is set to +.Dv NULL +if no packet is dequeued. +The caller must always check +.Fa m +since a non-empty queue could return +.Dv NULL +under rate-limiting. +.Pp +.Fn IFQ_POLL +returns the next packet without removing it from the queue. +It is guaranteed by the underlying queueing discipline that +.Fn IFQ_DEQUEUE +immediately after +.Fn IFQ_POLL +returns the same packet. +.Pp +.Fn IFQ_PURGE +discards all the packets in the queue. +The purge operation is needed since a non-work conserving queue cannot be +emptied by a dequeue loop. +.Pp +.Fn IFQ_CLASSIFY +classifies a packet to a scheduling class, and returns the result in +.Fa pattr . +.Pp +.Fn IFQ_IS_EMPTY +can be used to check if the queue is empty. +Note that +.Fn IFQ_DEQUEUE +could still return +.Dv NULL +if the queueing discipline is non-work conserving. +.Pp +.Fn IFQ_SET_MAXLEN +sets the queue length limit to the default FIFO queue. +.Pp +.Fn IFQ_INC_LEN +and +.Fn IFQ_DEC_LEN +increment or decrement the current queue length in packets. +.Pp +.Fn IFQ_INC_DROPS +increments the drop counter and is equal to +.Fn IF_DROP . +It is defined for naming consistency. +.Pp +.Fn IFQ_SET_READY +sets a flag to indicate this driver is converted to use the new macros. +.Nm +can be enabled only on interfaces with this flag. +.Sh COMPATIBILITY +.Ss ifaltq structure +In order to keep compatibility with the existing code, the new +output queue structure +.Dv ifaltq +has the same fields. +The traditional +.Fn IF_XXX +macros and the code directly referencing the fields within +.Dv if_snd +still work with +.Dv ifaltq . +(Once we finish conversions of all the drivers, we no longer need +these fields.) +.Bd -literal + ##old-style## ##new-style## + | + struct ifqueue { | struct ifaltq { + struct mbuf *ifq_head; | struct mbuf *ifq_head; + struct mbuf *ifq_tail; | struct mbuf *ifq_tail; + int ifq_len; | int ifq_len; + int ifq_maxlen; | int ifq_maxlen; + uint64_t ifq_drops; | uint64_t ifq_drops; + }; | /* altq related fields */ + | ...... + | }; + | +.Ed +The new structure replaces +.Dv struct ifqueue +in +.Dv struct ifnet . +.Bd -literal + ##old-style## ##new-style## + | + struct ifnet { | struct ifnet { + .... | .... + | + struct ifqueue if_snd; | struct ifaltq if_snd; + | + .... | .... + }; | }; + | +.Ed +The (simplified) new +.Fn IFQ_XXX +macros looks like: +.Bd -literal + #ifdef ALTQ + #define IFQ_DEQUEUE(ifq, m) \e + if (ALTQ_IS_ENABLED((ifq)) \e + ALTQ_DEQUEUE((ifq), (m)); \e + else \e + IF_DEQUEUE((ifq), (m)); + #else + #define IFQ_DEQUEUE(ifq, m) IF_DEQUEUE((ifq), (m)); + #endif +.Ed +.Ss Enqueue operation +The semantics of the enqueue operation are changed. +In the new style, +enqueue and packet drop are combined since they cannot be easily +separated in many queueing disciplines. +The new enqueue operation corresponds to the following macro that is +written with the old macros. +.Bd -literal +#define IFQ_ENQUEUE(ifq, m, pattr, err) \e +do { \e + if (ALTQ_IS_ENABLED((ifq))) \e + ALTQ_ENQUEUE((ifq), (m), (pattr), (err)); \e + else { \e + if (IF_QFULL((ifq))) { \e + m_freem((m)); \e + (err) = ENOBUFS; \e + } else { \e + IF_ENQUEUE((ifq), (m)); \e + (err) = 0; \e + } \e + } \e + if ((err)) \e + (ifq)->ifq_drops++; \e +} while (false) +.Ed +.Pp +.Fn IFQ_ENQUEUE +does the following: +.Bl -hyphen -compact +.It +queue a packet +.It +drop (and free) a packet if the enqueue operation fails +.El +If the enqueue operation fails, +.Fa err +is set to +.Dv ENOBUFS . +.Fa m +is freed by the queueing discipline. +The caller should not touch mbuf after calling +.Fn IFQ_ENQUEUE +so that the caller may need to copy +.Fa m_pkthdr.len +or +.Fa m_flags +field beforehand for statistics. +The caller should not use +.Fn senderr +since mbuf was already freed. +.Pp +The new style +.Fn if_output +looks as follows: +.Bd -literal + ##old-style## ##new-style## + | + int | int + ether_output(ifp, m0, dst, rt0) | ether_output(ifp, m0, dst, rt0) + { | { + ...... | ...... + | + | mflags = m->m_flags; + | len = m->m_pkthdr.len; + s = splimp(); | s = splimp(); + if (IF_QFULL(&ifp->if_snd)) { | IFQ_ENQUEUE(&ifp->if_snd, m, + | NULL, error); + IF_DROP(&ifp->if_snd); | if (error != 0) { + splx(s); | splx(s); + senderr(ENOBUFS); | return (error); + } | } + IF_ENQUEUE(&ifp->if_snd, m); | + ifp->if_obytes += | ifp->if_obytes += len; + m->m_pkthdr.len; | + if (m->m_flags & M_MCAST) | if (mflags & M_MCAST) + ifp->if_omcasts++; | ifp->if_omcasts++; + | + if ((ifp->if_flags & IFF_OACTIVE) | if ((ifp->if_flags & IFF_OACTIVE) + == 0) | == 0) + (*ifp->if_start)(ifp); | (*ifp->if_start)(ifp); + splx(s); | splx(s); + return (error); | return (error); + | + bad: | bad: + if (m) | if (m) + m_freem(m); | m_freem(m); + return (error); | return (error); + } | } + | +.Ed +.Ss Classifier +The classifier mechanism is currently implemented in +.Fn if_output . +.Dv struct altq_pktattr +is used to store the classifier result, and it is passed to the enqueue +function. +(We will change the method to tag the classifier result to mbuf in the future.) +.Bd -literal +int +ether_output(ifp, m0, dst, rt0) +{ + ...... + struct altq_pktattr pktattr; + + ...... + + /* classify the packet before prepending link-headers */ + IFQ_CLASSIFY(&ifp->if_snd, m, dst->sa_family, &pktattr); + + /* prepend link-level headers */ + ...... + + IFQ_ENQUEUE(&ifp->if_snd, m, &pktattr, error); + + ...... +} +.Ed +.Sh HOW TO CONVERT THE EXISTING DRIVERS +First, make sure the corresponding +.Fn if_output +is already converted to the new style. +.Pp +Look for +.Fa if_snd +in the driver. +You will probably need to make changes to the lines that include +.Fa if_snd . +.Ss Empty check operation +If the code checks +.Fa ifq_head +to see whether the queue is empty or not, use +.Fn IFQ_IS_EMPTY . +.Bd -literal + ##old-style## ##new-style## + | + if (ifp->if_snd.ifq_head != NULL) | if (IFQ_IS_EMPTY(&ifp->if_snd) == 0) + | +.Ed +Note that +.Fn IFQ_POLL +can be used for the same purpose, but +.Fn IFQ_POLL +could be costly for a complex scheduling algorithm since +.Fn IFQ_POLL +needs to run the scheduling algorithm to select the next packet. +On the other hand, +.Fn IFQ_IS_EMPTY +checks only if there is any packet stored in the queue. +Another difference is that even when +.Fn IFQ_IS_EMPTY +is +.Dv false , +.Fn IFQ_DEQUEUE +could still return +.Dv NULL +if the queue is under rate-limiting. +.Ss Dequeue operation +Replace +.Fn IF_DEQUEUE +by +.Fn IFQ_DEQUEUE . +Always check whether the dequeued mbuf is +.Dv NULL +or not. +Note that even when +.Fn IFQ_IS_EMPTY +is +.Dv false , +.Fn IFQ_DEQUEUE +could return +.Dv NULL +due to rate-limiting. +.Bd -literal + ##old-style## ##new-style## + | + IF_DEQUEUE(&ifp->if_snd, m); | IFQ_DEQUEUE(&ifp->if_snd, m); + | if (m == NULL) + | return; + | +.Ed +A driver is supposed to call +.Fn if_start +from transmission complete interrupts in order to trigger the next dequeue. +.Ss Poll-and-dequeue operation +If the code polls the packet at the head of the queue and actually uses +the packet before dequeueing it, use +.Fn IFQ_POLL +and +.Fn IFQ_DEQUEUE . +.Bd -literal + ##old-style## ##new-style## + | + m = ifp->if_snd.ifq_head; | IFQ_POLL(&ifp->if_snd, m); + if (m != NULL) { | if (m != NULL) { + | + /* use m to get resources */ | /* use m to get resources */ + if (something goes wrong) | if (something goes wrong) + return; | return; + | + IF_DEQUEUE(&ifp->if_snd, m); | IFQ_DEQUEUE(&ifp->if_snd, m); + | + /* kick the hardware */ | /* kick the hardware */ + } | } + | +.Ed +It is guaranteed that +.Fn IFQ_DEQUEUE +immediately after +.Fn IFQ_POLL +returns the same packet. +Note that they need to be guarded by +.Fn splimp +if called from outside of +.Fn if_start . +.Ss Eliminating IF_PREPEND +If the code uses +.Fn IF_PREPEND , +you have to eliminate it since the prepend operation is not possible for many +queueing disciplines. +A common use of +.Fn IF_PREPEND +is to cancel the previous dequeue operation. +You have to convert the logic into poll-and-dequeue. +.Bd -literal + ##old-style## ##new-style## + | + IF_DEQUEUE(&ifp->if_snd, m); | IFQ_POLL(&ifp->if_snd, m); + if (m != NULL) { | if (m != NULL) { + | + if (something_goes_wrong) { | if (something_goes_wrong) { + IF_PREPEND(&ifp->if_snd, m); | + return; | return; + } | } + | + | /* at this point, the driver + | * is committed to send this + | * packet. + | */ + | IFQ_DEQUEUE(&ifp->if_snd, m); + | + /* kick the hardware */ | /* kick the hardware */ + } | } + | +.Ed +.Ss Purge operation +Use +.Fn IFQ_PURGE +to empty the queue. +Note that a non-work conserving queue cannot be emptied by a dequeue loop. +.Bd -literal + ##old-style## ##new-style## + | + while (ifp->if_snd.ifq_head != NULL) {| IFQ_PURGE(&ifp->if_snd); + IF_DEQUEUE(&ifp->if_snd, m); | + m_freem(m); | + } | + | +.Ed +.Ss Attach routine +Use +.Fn IFQ_SET_MAXLEN +to set +.Fa ifq_maxlen +to +.Fa len . +Add +.Fn IFQ_SET_READY +to show this driver is converted to the new style. +(This is used to distinguish new-style drivers.) +.Bd -literal + ##old-style## ##new-style## + | + ifp->if_snd.ifq_maxlen = qsize; | IFQ_SET_MAXLEN(&ifp->if_snd, qsize); + | IFQ_SET_READY(&ifp->if_snd); + if_attach(ifp); | if_attach(ifp); + | +.Ed +.Ss Other issues +The new macros for statistics: +.Bd -literal + ##old-style## ##new-style## + | + IF_DROP(&ifp->if_snd); | IFQ_INC_DROPS(&ifp->if_snd); + | + ifp->if_snd.ifq_len++; | IFQ_INC_LEN(&ifp->if_snd); + | + ifp->if_snd.ifq_len--; | IFQ_DEC_LEN(&ifp->if_snd); + | +.Ed +Some drivers instruct the hardware to invoke transmission complete +interrupts only when it thinks necessary. +Rate-limiting breaks its assumption. +.Ss How to convert drivers using multiple ifqueues +Some (pseudo) devices (such as slip) have another +.Dv ifqueue +to prioritize packets. +It is possible to eliminate the second queue +since +.Nm +provides more flexible mechanisms but the following shows +how to keep the original behavior. +.Bd -literal +struct sl_softc { + struct ifnet sc_if; /* network-visible interface */ + ... + struct ifqueue sc_fastq; /* interactive output queue */ + ... +}; +.Ed +The driver doesn't compile in the new model since it has the following +line +.Po +.Fa if_snd +is no longer a type of +.Dv struct ifqueue +.Pc . +.Bd -literal + struct ifqueue *ifq = &ifp->if_snd; +.Ed +A simple way is to use the original +.Fn IF_XXX +macros for +.Fa sc_fastq +and use the new +.Fn IFQ_XXX +macros for +.Fa if_snd . +The enqueue operation looks like: +.Bd -literal + ##old-style## ##new-style## + | + struct ifqueue *ifq = &ifp->if_snd; | struct ifqueue *ifq = NULL; + | + if (ip->ip_tos & IPTOS_LOWDELAY) | if ((ip->ip_tos & IPTOS_LOWDELAY) && + ifq = &sc->sc_fastq; | !ALTQ_IS_ENABLED(&sc->sc_if.if_snd)) { + | ifq = &sc->sc_fastq; + if (IF_QFULL(ifq)) { | if (IF_QFULL(ifq)) { + IF_DROP(ifq); | IF_DROP(ifq); + m_freem(m); | m_freem(m); + splx(s); | error = ENOBUFS; + sc->sc_if.if_oerrors++; | } else { + return (ENOBUFS); | IF_ENQUEUE(ifq, m); + } | error = 0; + IF_ENQUEUE(ifq, m); | } + | } else + | IFQ_ENQUEUE(&sc->sc_if.if_snd, + | m, NULL, error); + | + | if (error) { + | splx(s); + | sc->sc_if.if_oerrors++; + | return (error); + | } + if ((sc->sc_oqlen = | if ((sc->sc_oqlen = + sc->sc_ttyp->t_outq.c_cc) == 0) | sc->sc_ttyp->t_outq.c_cc) == 0) + slstart(sc->sc_ttyp); | slstart(sc->sc_ttyp); + splx(s); | splx(s); + | +.Ed +The dequeue operations looks like: +.Bd -literal + ##old-style## ##new-style## + | + s = splimp(); | s = splimp(); + IF_DEQUEUE(&sc->sc_fastq, m); | IF_DEQUEUE(&sc->sc_fastq, m); + if (m == NULL) | if (m == NULL) + IF_DEQUEUE(&sc->sc_if.if_snd, m); | IFQ_DEQUEUE(&sc->sc_if.if_snd, m); + splx(s); | splx(s); + | +.Ed +.Sh QUEUEING DISCIPLINES +Queueing disciplines need to maintain +.Fa ifq_len +.Po +used by +.Fn IFQ_IS_EMPTY +.Pc . +Queueing disciplines also need to guarantee the same mbuf is returned if +.Fn IFQ_DEQUEUE +is called immediately after +.Fn IFQ_POLL . +.Sh SEE ALSO +.Xr pf 4 , +.Xr altq.conf 5 , +.Xr pf.conf 5 , +.Xr altqd 8 , +.Xr tbrconfig 8 +.Sh HISTORY +The +.Nm +system first appeared in March 1997 and found its home in the KAME project +.Lk ( http://www.kame.net ) . +It was imported into +.Nx 1.6 . diff --git a/static/netbsd/man9/arp.9 b/static/netbsd/man9/arp.9 new file mode 100644 index 00000000..fb332235 --- /dev/null +++ b/static/netbsd/man9/arp.9 @@ -0,0 +1,138 @@ +.\" $NetBSD: arp.9,v 1.27 2019/09/01 14:49:11 sevan Exp $ +.\" +.\" Copyright (c) 1997 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Ignatios Souvatzis. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.Dd September 1, 2019 +.Dt ARP 9 +.Os +.Sh NAME +.Nm arp , +.Nm arp_ifinit , +.Nm arpresolve , +.Nm arpintr +.Nd externally visible ARP functions +.Sh SYNOPSIS +.In netinet/if_inarp.h +.Ft void +.Fn arp_ifinit "struct ifnet *ifp" "struct ifaddr *ifa" +.Ft int +.Fn arpresolve "struct ifnet *ifp" "const struct rtentry *rt" "struct mbuf *m" "const struct sockaddr *dst" "void *desten" "size_t destlen" +.Ft void +.Fn arpintr +.Sh DESCRIPTION +The +.Nm +functions provide the interface between the +.Nm +module and the network drivers which need +.Nm +functionality. +Such drivers must request the +.Ar arp +attribute in their "files" declaration. +.Bl -tag -width "arp_ifinit()" +.It Fn arp_ifinit +Sets up the +.Nm +specific fields in +.Fa ifa . +Additionally, it sends out a gratuitous +.Nm +request on +.Fa ifp , +so that other machines are warned that we have a (new) address and +duplicate addresses can be detected. +.Pp +You must call this in your drivers' ioctl function when you get a +SIOCSIFADDR request with an AF_INET address family. +.It Fn arpresolve +is called by network output functions to resolve an IPv4 address. +If no +.Fa rt +is given, a new one is looked up or created. +If the passed or found +.Fa rt +does not contain a valid gateway link level address, a pointer to the packet +in +.Fa m +is stored in the route entry, possibly replacing older stored packets, and an +.Nm +request is sent instead. +When an +.Nm +reply is received, the last held packet is send. +Otherwise, the looked up address is returned and written into the storage +.Fa desten +points to. +.Fn arpresolve +returns 1, if a valid address was stored to +.Fa desten , +and the packet can be sent immediately. +Else a 0 is returned. +.It Fn arpintr +When an +.Nm +packet is received, the network driver (class) input interrupt handler queues +the packet on the arpintrq queue, and requests an +.Fn arpintr +soft interrupt callback. +.Fn arpintr +dequeues the packets, performs sanity checks and calls (for IPv4 +.Nm +packets, which are the only ones supported currently) the +.Fn in_arpinput +function. +.Fn in_arpinput +either generates a reply to request packets, and adds the sender address +translation to the routing table, if a matching route entry is found. +If the route entry contained a pointer to a held packet, that packet is +sent. +.El +.Sh CODE REFERENCES +The ARP code is implemented in +.Pa sys/net/if_arp.h , +.Pa sys/netinet/if_inarp.h +and +.Pa sys/netinet/if_arp.c . +.Sh SEE ALSO +.Xr ether_ifattach 9 +.\" .Xr fddi_ifattach 9 , +.\" .Xr arc_ifattach 9 +.Pp +Plummer, D., "RFC826", An Ethernet Address Resolution Protocol. +.Sh STANDARDS +RFC 826 +.Sh HISTORY +Rewritten to support other than Ethernet link level addresses in +.Nx 1.3 . +.Sh AUTHORS +.An UCB CSRG +(original implementation) +.An Ignatios Souvatzis +(support for non-Ethernet) diff --git a/static/netbsd/man9/atomic_loadstore.9 b/static/netbsd/man9/atomic_loadstore.9 new file mode 100644 index 00000000..af50d9ce --- /dev/null +++ b/static/netbsd/man9/atomic_loadstore.9 @@ -0,0 +1,827 @@ +.\" $NetBSD: atomic_loadstore.9,v 1.8 2024/06/18 19:10:50 riastradh Exp $ +.\" +.\" Copyright (c) 2019 The NetBSD Foundation +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Taylor R. Campbell. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 11, 2022 +.Dt ATOMIC_LOADSTORE 9 +.Os +.Sh NAME +.Nm atomic_load_relaxed , +.Nm atomic_load_acquire , +.Nm atomic_load_consume , +.Nm atomic_store_relaxed , +.Nm atomic_store_release +.Nd atomic and ordered memory operations +.Sh SYNOPSIS +.In sys/atomic.h +.Ft T +.Fn atomic_load_relaxed "const volatile T *p" +.Ft T +.Fn atomic_load_acquire "const volatile T *p" +.Ft T +.Fn atomic_load_consume "const volatile T *p" +.Ft void +.Fn atomic_store_relaxed "volatile T *p" "T v" +.Ft void +.Fn atomic_store_release "volatile T *p" "T v" +.Sh DESCRIPTION +These type-generic macros implement memory operations that are +.Em atomic +and that have +.Em memory ordering constraints . +Aside from atomicity and ordering, the load operations are equivalent +to +.Li * Ns Fa p +and the store operations are equivalent to +.Li * Ns Fa p Li "=" Fa v . +The pointer +.Fa p +must be aligned, even on architectures like x86 which generally lack +strict alignment requirements; see +.Sx SIZE AND ALIGNMENT +for details. +.Pp +.Em Atomic +means that the memory operations cannot be +.Em fused +or +.Em torn : +.Bl -bullet +.It +.Em Fusing +is combining multiple memory operations on a single object into one +memory operation, such as replacing +.Bd -literal -compact + *p = v; + x = *p; +.Ed +by +.Bd -literal -compact + *p = v; + x = v; +.Ed +since the compiler can prove that +.Li \&*p +will yield +.Li v +after +.Li \&*p\ =\ v . +For +.Em atomic +memory operations, the implementation +.Em will not +assume that +.Bl -dash -compact +.It +consecutive loads of the same object will return the same value, or +.It +a store followed by a load of the same object will return the value +stored, or +.It +consecutive stores of the same object are redundant. +.El +Thus, the implementation will not replace two consecutive atomic loads +by one, will not elide an atomic load following a store, and will not +combine two consecutive atomic stores into one. +.Pp +For example, +.Bd -literal + atomic_store_relaxed(&flag, 1); + while (atomic_load_relaxed(&flag)) + continue; +.Ed +.Pp +may be used to set a flag and then busy-wait until another thread +clears it, whereas +.Bd -literal + flag = 1; + while (flag) + continue; +.Ed +.Pp +may be transformed into the infinite loop +.Bd -literal + flag = 1; + while (1) + continue; +.Ed +.It +.Em Tearing +is implementing a memory operation on a large data unit such as a +32-bit word by issuing multiple memory operations on smaller data units +such as 8-bit bytes. +The implementation will not tear +.Em atomic +loads or stores into smaller ones. +Thus, as far as any interrupt, other thread, or other CPU can tell, an +atomic memory operation is issued either all at once or not at all. +.Pp +For example, if a 32-bit word +.Va w +is written with +.Pp +.Dl atomic_store_relaxed(&w,\ 0x00010002); +.Pp +then an interrupt, other thread, or other CPU reading it with +.Li atomic_load_relaxed(&w) +will never witness it partially written, whereas +.Pp +.Dl w\ =\ 0x00010002; +.Pp +might be compiled into a pair of separate 16-bit store instructions +instead of one single word-sized store instruction, in which case other +threads may see the intermediate state with only one of the halves +written. +.El +.Pp +Atomic operations on any single object occur in a total order shared by +all interrupts, threads, and CPUs, which is consistent with the program +order in every interrupt, thread, and CPU. +A single program without interruption or other threads or CPUs will +always observe its own loads and stores in program order, but another +program in an interrupt handler, in another thread, or on another CPU +may issue loads that return values as if the first program's stores +occurred out of program order, and vice versa. +Two different threads might each observe a third thread's memory +operations in different orders. +.Pp +The +.Em memory ordering constraints +make limited guarantees of ordering relative to memory operations on +.Em other +objects as witnessed by interrupts, other threads, or other CPUs, and +have the following meanings: +.Bl -tag -width relaxed +.It relaxed +No ordering relative to memory operations on any other objects is +guaranteed. +Relaxed ordering is the default for ordinary non-atomic memory +operations like +.Li "*p" +and +.Li "*p = v" . +.Pp +Atomic operations with relaxed ordering are cheap: they are not +read/modify/write atomic operations, and they do not involve any kind +of inter-CPU ordering barriers. +.It acquire +This memory operation happens before all subsequent memory operations +in program order. +However, prior memory operations in program order may be reordered to +happen after this one. +For example, assuming no aliasing between the pointers, the +implementation is allowed to treat +.Bd -literal + int x = *p; + if (atomic_load_acquire(q)) { + int y = *r; + *s = x + y; + return 1; + } +.Ed +.Pp +as if it were +.Bd -literal + if (atomic_load_acquire(q)) { + int x = *p; + int y = *r; + *s = x + y; + return 1; + } +.Ed +.Pp +but +.Em not +as if it were +.Bd -literal + int x = *p; + int y = *r; + *s = x + y; + if (atomic_load_acquire(q)) { + return 1; + } +.Ed +.It consume +This memory operation happens before all memory operations on objects +at addresses that are computed from the value returned by this one. +Otherwise, no ordering relative to memory operations on other objects +is implied. +.Pp +For example, the implementation is allowed to treat +.Bd -literal + struct foo *foo0, *foo1; + + struct foo *f0 = atomic_load_consume(&foo0); + struct foo *f1 = atomic_load_consume(&foo1); + int x = f0->x; + int y = f1->y; +.Ed +.Pp +as if it were +.Bd -literal + struct foo *foo0, *foo1; + + struct foo *f1 = atomic_load_consume(&foo1); + struct foo *f0 = atomic_load_consume(&foo0); + int y = f1->y; + int x = f0->x; +.Ed +.Pp +but loading +.Li f0->x +is guaranteed to happen after loading +.Li foo0 +even if the CPU had a cached value for the address that +.Li f0->x +happened to be at, and likewise for +.Li f1->y +and +.Li foo1 . +.Pp +.Fn atomic_load_consume +functions like +.Fn atomic_load_acquire +as long as the memory operations that must happen after it are limited +to addresses that depend on the value returned by it, but it is almost +always as cheap as +.Fn atomic_load_relaxed . +See +.Sx ACQUIRE OR CONSUME? +below for more details. +.It release +All prior memory operations in program order happen before this one. +However, subsequent memory operations in program order may be reordered +to happen before this one too. +For example, assuming no aliasing between the pointers, the +implementation is allowed to treat +.Bd -literal + int x = *p; + *q = x; + atomic_store_release(r, 0); + int y = *s; + return x + y; +.Ed +.Pp +as if it were +.Bd -literal + int y = *s; + int x = *p; + *q = x; + atomic_store_release(r, 0); + return x + y; +.Ed +.Pp +but +.Em not +as if it were +.Bd -literal + atomic_store_release(r, 0); + int x = *p; + int y = *s; + *q = x; + return x + y; +.Ed +.El +.Ss PAIRING ORDERED MEMORY OPERATIONS +In general, each +.Fn atomic_store_release +.Em must +be paired with either +.Fn atomic_load_acquire +or +.Fn atomic_load_consume +in order to have an effect \(em it is only when a release operation +synchronizes with an acquire or consume operation that any ordering +guaranteed between memory operations +.Em before +the release operation and memory operations +.Em after +the acquire/consume operation. +.Pp +For example, to set up an entry in a table and then mark the entry +ready, you should: +.Bl -enum +.It +Perform memory operations to initialize the data. +.Bd -literal + tab[i].x = ...; + tab[i].y = ...; +.Ed +.It +Issue +.Fn atomic_store_release +to mark it ready. +.Bd -literal + atomic_store_release(&tab[i].ready, 1); +.Ed +.It +Possibly in another thread, issue +.Fn atomic_load_acquire +to ascertain whether it is ready. +.Bd -literal + if (atomic_load_acquire(&tab[i].ready) == 0) + return EWOULDBLOCK; +.Ed +.It +Perform memory operations to use the data. +.Bd -literal + do_stuff(tab[i].x, tab[i].y); +.Ed +.El +.Pp +Similarly, if you want to create an object, initialize it, and then +publish it to be used by another thread, then you should: +.Bl -enum +.It +Perform memory operations to initialize the object. +.Bd -literal + struct mumble *m = kmem_alloc(sizeof(*m), KM_SLEEP); + m->x = x; + m->y = y; + m->z = m->x + m->y; +.Ed +.It +Issue +.Fn atomic_store_release +to publish it. +.Bd -literal + atomic_store_release(&the_mumble, m); +.Ed +.It +Possibly in another thread, issue +.Fn atomic_load_consume +to get it. +.Bd -literal + struct mumble *m = atomic_load_consume(&the_mumble); +.Ed +.It +Perform memory operations to use the object's members. +.Bd -literal + m->y &= m->x; + do_things(m->x, m->y, m->z); +.Ed +.El +.Pp +In both examples, assuming that the value written by +.Fn atomic_store_release +in step\~2 +is read by +.Fn atomic_load_acquire +or +.Fn atomic_load_consume +in step\~3, this guarantees that all of the memory operations in +step\~1 complete before any of the memory operations in step\~4 \(em +even if they happen on different CPUs. +.Pp +Without +.Em both +the release operation in step\~2 +.Em and +the acquire or consume operation in step\~3, no ordering is guaranteed +between the memory operations in steps\~1 and\~4. +In fact, without +.Em both +release and acquire/consume, even the assignment +.Li m->z\ =\ m->x\ +\ m->y +in step\~1 might read values of +.Li m->x +and +.Li m->y +that were written in step\~4. +.Ss ACQUIRE OR CONSUME? +You must use +.Fn atomic_load_acquire +when subsequent memory operations in program order that must happen +after the load are on objects at +.Em addresses that might not depend arithmetically on the resulting value . +This applies particularly when the choice of whether to do the +subsequent memory operation depends on a +.Em control-flow decision based on the resulting value : +.Bd -literal + struct gadget { + int ready, x; + } the_gadget; + + /* Producer */ + the_gadget.x = 42; + atomic_store_release(&the_gadget.ready, 1); + + /* Consumer */ + if (atomic_load_acquire(&the_gadget.ready) == 0) + return EWOULDBLOCK; + int x = the_gadget.x; +.Ed +.Pp +Here the +.Em decision of whether to load +.Li the_gadget.x +depends on a control-flow decision depending on value loaded from +.Li the_gadget.ready , +and loading +.Li the_gadget.x +must happen after loading +.Li the_gadget.ready . +Using +.Fn atomic_load_acquire +guarantees that the compiler and CPU do not conspire to load +.Li the_gadget.x +before we have ascertained that it is ready. +.Pp +You may use +.Fn atomic_load_consume +if all subsequent memory operations in program order that must happen +after the load are performed on objects at +.Em addresses computed arithmetically from the resulting value , +such as loading a pointer to a structure object and then dereferencing +it: +.Bd -literal + struct gizmo { + int x, y, z; + }; + struct gizmo null_gizmo; + struct gizmo *the_gizmo = &null_gizmo; + + /* Producer */ + struct gizmo *g = kmem_alloc(sizeof(*g), KM_SLEEP); + g->x = 12; + g->y = 34; + g->z = 56; + atomic_store_release(&the_gizmo, g); + + /* Consumer */ + struct gizmo *g = atomic_load_consume(&the_gizmo); + int y = g->y; +.Ed +.Pp +Here the +.Em address +of +.Li g->y +depends on the value of the pointer loaded from +.Li the_gizmo . +Using +.Fn atomic_load_consume +guarantees that we do not witness a stale cache for that address. +.Pp +In some cases it may be unclear. +For example: +.Bd -literal + int x[2]; + bool b; + + /* Producer */ + x[0] = 42; + atomic_store_release(&b, 0); + + /* Consumer 1 */ + int y = atomic_load_???(&b) ? x[0] : x[1]; + + /* Consumer 2 */ + int y = x[atomic_load_???(&b) ? 0 : 1]; + + /* Consumer 3 */ + int y = x[atomic_load_???(&b) ^ 1]; +.Ed +.Pp +Although the three consumers seem to be equivalent, by the letter of +C11 consumers\~1 and\~2 require +.Fn atomic_load_acquire +because the value determines the address of a subsequent load only via +control-flow decisions in the +.Li ?: +operator, whereas consumer\~3 can use +.Fn atomic_load_consume . +However, if you're not sure, you should err on the side of +.Fn atomic_load_acquire +until C11 implementations have ironed out the kinks in the semantics. +.Pp +On all CPUs other than DEC Alpha, +.Fn atomic_load_consume +is cheap \(em it is identical to +.Fn atomic_load_relaxed . +In contrast, +.Fn atomic_load_acquire +usually implies an expensive memory barrier. +.Ss SIZE AND ALIGNMENT +The pointer +.Fa p +must be aligned \(em that is, if the object it points to is +.\" +2\c +.ie t \s-2\v'-0.4m'n\v'+0.4m'\s+2 +.el ^n +.\" +bytes long, then the low-order +.Ar n +bits of +.Fa p +must be zero. +.Pp +All +.Nx +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 +supports atomically; attempts to use them for such quantities should +result in a compile-time assertion failure. +.Pp +For example, as long as you use +.Fn atomic_store_* +to write a 32-bit quantity, you can safely use +.Fn atomic_load_relaxed +to optimistically read it outside a lock, but for a 64-bit quantity it +must be conditional on +.Dv __HAVE_ATOMIC64_LOADSTORE +\(em otherwise it will lead to compile-time errors on platforms without +64-bit atomic loads and stores: +.Bd -literal + struct foo { + kmutex_t f_lock; + uint32_t f_refcnt; + uint64_t f_ticket; + }; + + if (atomic_load_relaxed(&foo->f_refcnt) == 0) + return 123; +#ifdef __HAVE_ATOMIC64_LOADSTORE + if (atomic_load_relaxed(&foo->f_ticket) == ticket) + return 123; +#endif + mutex_enter(&foo->f_lock); + if (foo->f_refcnt == 0 || foo->f_ticket == ticket) + ret = 123; + ... +#ifdef __HAVE_ATOMIC64_LOADSTORE + atomic_store_relaxed(&foo->f_ticket, foo->f_ticket + 1); +#else + foo->f_ticket++; +#endif + ... + mutex_exit(&foo->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 +semantics, in terms of +.Li atomic_load_explicit() +and +.Li atomic_store_explicit() +with the appropriate memory order specifiers, and are meant to make +future adoption of the +.Tn C11 +atomic API easier. +Eventually it may be mandatory to use the +.Tn C11 +.Vt _Atomic +type qualifier or equivalent for the operands. +.Sh LINUX ANALOGUES +The Linux kernel provides two macros +.Li READ_ONCE(x) +and +.Li WRITE_ONCE(x,\ v) +which are similar to +.Li atomic_load_consume(&x) +and +.Li atomic_store_relaxed(&x,\ v) , +respectively. +However, while Linux's +.Li READ_ONCE +and +.Li WRITE_ONCE +prevent fusing, they may in some cases be torn \(em and therefore fail +to guarantee atomicity \(em because: +.Bl -bullet +.It +They do not require the address +.Li "&x" +to be aligned. +.It +They do not require +.Li sizeof(x) +to be at most the largest size of available atomic loads and stores on +the host architecture. +.El +.Sh MEMORY BARRIERS AND ATOMIC READ/MODIFY/WRITE +The atomic read/modify/write operations in +.Xr atomic_ops 3 +have relaxed ordering by default, but can be combined with the memory +barriers in +.Xr membar_ops 3 +for the same effect as an acquire operation and a release operation for +the purposes of pairing with +.Fn atomic_store_release +and +.Fn atomic_load_acquire +or +.Fn atomic_load_consume . +If +.Li atomic_r/m/w() +is an atomic read/modify/write operation in +.Xr atomic_ops 3 , +then +.Bd -literal + membar_release(); + atomic_r/m/w(obj, ...); +.Ed +.Pp +functions like a release operation on +.Va obj , +and +.Bd -literal + atomic_r/m/w(obj, ...); + membar_acquire(); +.Ed +.Pp +functions like a acquire operation on +.Va obj . +.Pp +On architectures where +.Dv __HAVE_ATOMIC_AS_MEMBAR +is defined, all the +.Xr atomic_ops 3 +imply release and acquire operations, so the +.Xr membar_acquire 3 +and +.Xr membar_release 3 +are redundant. +.Pp +The combination of +.Fn atomic_load_relaxed +and +.Xr membar_acquire 3 +in that order is equivalent to +.Fn atomic_load_acquire , +and the combination of +.Xr membar_release 3 +and +.Fn atomic_store_relaxed +in that order is equivalent to +.Fn atomic_store_release . +.Sh EXAMPLES +Maintaining lossy counters. +These may lose some counts, because the read/modify/write cycle as a +whole is not atomic. +But this guarantees that the count will increase by at most one each +time. +In contrast, without atomic operations, in principle a write to a +32-bit counter might be torn into multiple smaller stores, which could +appear to happen out of order from another CPU's perspective, leading +to nonsensical counter readouts. +(For frequent events, consider using per-CPU counters instead in +practice.) +.Bd -literal + unsigned count; + + void + record_event(void) + { + atomic_store_relaxed(&count, + 1 + atomic_load_relaxed(&count)); + } + + unsigned + read_event_count(void) + { + return atomic_load_relaxed(&count); + } +.Ed +.Pp +Initialization barrier. +.Bd -literal + int ready; + struct data d; + + void + setup_and_notify(void) + { + setup_data(&d.things); + atomic_store_release(&ready, 1); + } + + void + try_if_ready(void) + { + if (atomic_load_acquire(&ready)) + do_stuff(d.things); + } +.Ed +.Pp +Publishing a pointer to the current snapshot of data. +(Caller must arrange that only one call to +.Li take_snapshot() +happens at any +given time; generally this should be done in coordination with +.Xr pserialize 9 +or similar to enable resource reclamation.) +.Bd -literal + struct data *current_d; + + void + take_snapshot(void) + { + struct data *d = kmem_alloc(sizeof(*d)); + + d->things = ...; + + atomic_store_release(¤t_d, d); + } + + struct data * + get_snapshot(void) + { + return atomic_load_consume(¤t_d); + } +.Ed +.Sh CODE REFERENCES +.Pa sys/sys/atomic.h +.Sh SEE ALSO +.Xr atomic_ops 3 , +.Xr membar_ops 3 , +.Xr pserialize 9 +.Sh HISTORY +These atomic operations first appeared in +.Nx 9.0 . +.Sh CAVEATS +C11 formally specifies that all subexpressions, except the left +operands of the +.Ql && , +.Ql || , +.Ql ?: , +and +.Ql \&, +operators and the +.Li kill_dependency() +macro, carry dependencies for which +.Dv memory_order_consume +guarantees ordering, but most or all implementations to date simply +treat +.Dv memory_order_consume +as +.Dv memory_order_acquire +and do not take advantage of data dependencies to elide costly memory +barriers or load-acquire CPU instructions. +.Pp +Instead, we implement +.Fn atomic_load_consume +as +.Fn atomic_load_relaxed +followed by +.Xr membar_datadep_consumer 3 , +which is equivalent to +.Xr membar_consumer 3 +on DEC Alpha and +.Xr __insn_barrier 3 +elsewhere. +.Sh BUGS +Some idiot decided to call it +.Em tearing , +depriving us of the opportunity to say that atomic operations prevent +fusion and +.Em fission . diff --git a/static/netbsd/man9/audio.9 b/static/netbsd/man9/audio.9 new file mode 100644 index 00000000..9bec5ed4 --- /dev/null +++ b/static/netbsd/man9/audio.9 @@ -0,0 +1,676 @@ +.\" $NetBSD: audio.9,v 1.61 2021/03/28 07:42:06 isaki Exp $ +.\" +.\" Copyright (c) 1999, 2000 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 2, 2021 +.Dt AUDIO 9 +.Os +.Sh NAME +.Nm audio +.Nd interface between low and high level audio drivers +.Sh DESCRIPTION +The audio device driver is divided into a high level, +hardware independent layer, and a low level hardware +dependent layer. +The interface between these is the +.Va audio_hw_if +structure. +.Bd -literal +struct audio_hw_if { + int (*open)(void *, int); + void (*close)(void *); + + int (*query_format)(void *, audio_format_query_t *); + int (*set_format)(void *, int, + const audio_params_t *, const audio_params_t *, + audio_filter_reg_t *, audio_filter_reg_t *); + int (*round_blocksize)(void *, int, int, const audio_params_t *); + + int (*commit_settings)(void *); + + int (*init_output)(void *, void *, int); + int (*init_input)(void *, void *, int); + int (*start_output)(void *, void *, int, void (*)(void *), + void *); + int (*start_input)(void *, void *, int, void (*)(void *), + void *); + int (*halt_output)(void *); + int (*halt_input)(void *); + + int (*speaker_ctl)(void *, int); +#define SPKR_ON 1 +#define SPKR_OFF 0 + + int (*getdev)(void *, struct audio_device *); + + int (*set_port)(void *, mixer_ctrl_t *); + int (*get_port)(void *, mixer_ctrl_t *); + + int (*query_devinfo)(void *, mixer_devinfo_t *); + + void *(*allocm)(void *, int, size_t); + void (*freem)(void *, void *, size_t); + size_t (*round_buffersize)(void *, int, size_t); + + int (*get_props)(void *); + + int (*trigger_output)(void *, void *, void *, int, + void (*)(void *), void *, const audio_params_t *); + int (*trigger_input)(void *, void *, void *, int, + void (*)(void *), void *, const audio_params_t *); + int (*dev_ioctl)(void *, u_long, void *, int, struct lwp *); + void (*get_locks)(void *, kmutex_t **, kmutex_t **); +}; + +typedef struct audio_params { + u_int sample_rate; /* sample rate */ + u_int encoding; /* e.g. mu-law, linear, etc */ + u_int precision; /* bits/subframe */ + u_int validbits; /* valid bits in a subframe */ + u_int channels; /* mono(1), stereo(2) */ +} audio_params_t; +.Ed +.Pp +The high level audio driver attaches to the low level driver +when the latter calls +.Va audio_attach_mi . +This call should be +.Bd -literal + device_t + audio_attach_mi(const struct audio_hw_if *ahwp, void *hdl, device_t dev); +.Ed +.Pp +The +.Va audio_hw_if +struct is as shown above. +The +.Va hdl +argument is a handle to some low level data structure. +It is sent as the first argument to all the functions +in +.Va audio_hw_if +when the high level driver calls them. +.Va dev +is the device struct for the hardware device. +.Pp +The upper layer of the audio driver allocates one buffer for playing +and one for recording. +It handles the buffering of data from the user processes in these. +The data is presented to the lower level in smaller chunks, called blocks. +If, during playback, there is no data available from the user process when +the hardware request another block a block of silence will be used instead. +Furthermore, if the user process does not read data quickly enough during +recording data will be thrown away. +.Pp +The phase that these functions are called is classified into three. +Attach phase, Closed phase and Opened phase. +Attach phase is during device attach and +it transits to the Closed phase when the attach succeeded. +Closed phase is when no sampling device is opened and +it transits to the Opened phase when open succeeded. +Opened phase is when any sampling device is opened and +it transits to the Closed phase when close succeeded. +.Pp +The fields of +.Va audio_hw_if +are described in some more detail below. +Some fields are optional and can be set to +.Dv NULL +if not needed. +.Bl -tag -width indent +.It Dv int open(void *hdl, int flags) +optional, is called when the first device combining playback and recording +is opened. +On a full duplex hardware, +.Dv ( FREAD | FWRITE ) +is passed to flags. +On a half duplex hardware, +.Dv FWRITE +is passed for playback, or +.Dv FREAD +for recording. +Every successful call to +.Va open +is matched by a call to +.Va close . +Return 0 on success, otherwise an error code. +It is called in the Closed phase. +.It Dv void close(void *hdl) +optional, is called when the last audio device combining +playback and recording is closed. +Before call to this, +.Va halt_input +and +.Va halt_output +are called if necessary. +It is called in the Opened phase. +.It Dv int query_format(void *hdl, audio_format_query_t *afp) +is called to enumerate formats supported by the hardware. +It should fill the +.Vt audio_format_t +structure according to given number +.Va afp->index . +If there is no format with the given number, return +.Er EINVAL . +It can be called at any time. +.Bd -literal +typedef struct audio_format_query { + u_int index; + struct audio_format fmt; +} audio_format_query_t; +.Ed +.Pp +It is also used by the upper layer to determine the default format, as follows: +.Bl -enum +.It +Higher priority is preferred (normally 0, the highest is 3, the lowest is 0). +.It +.Dv AUDIO_ENCODING_SLINEAR_NE:16 +is preferred if exists. +.It +.Dv AUDIO_ENCODING_SLINEAR_OE:16 +is preferred if exists. +.It +The format with more channels is preferred. +.El +.Pp +If the driver supports +.Dv SLINEAR_NE:16 +and the upper layer chooses it, +the driver does not need to provide a conversion function in +.Va set_format . +Similarly, if the driver supports +.Dv SLINEAR_OE:16 +and the upper layer chooses it, +the driver does not need to provide a conversion function, +because the upper layer supports conversion between +.Dv SLINEAR_NE:16 +and +.Dv SLINEAR_OE:16 +for convenience. +If the upper layer chooses another format, +the driver needs to provide a conversion function in +.Va set_format . +See also +.Va set_format . +If the driver can not provide the conversion from/to +.Dv SLINEAR_NE:16 , +set priority to \-1. +It means that the hardware supports this format but the driver does not +(e.g. AC3), and it will never be chosen. +.It Dv int set_format(void *hdl, int setmode, +.Dv "const audio_params_t *play, const audio_params_t *rec," +.Dv "audio_filter_reg_t *pfil, audio_filter_reg_t *rfil)" +.Pp +is called to set specified format to the hardware, +when the device is attached or the hardware format is changed. +.Va setmode +is a combination of the +.Dv AUMODE_RECORD +and +.Dv AUMODE_PLAY +flags to indicate which modes are to be set. +.Pp +The +.Va play +and +.Va rec +structures contain the encoding parameters that should be set to the hardware. +All of these parameters are chosen from formats returned by +.Va query_format . +Therefore +.Va play +and/or +.Va rec +are always settable. +If the hardware does not support +.Dv AUDIO_ENCODING_SLINEAR_{NE,OE}:16 , +conversion information should be filled the +.Va pfil +for playing or +.Va rfil +for recording. +The definition of +.Vt audio_filter_reg_t +and a related structure follow: +.Bd -literal +typedef struct { + const void *src; + const audio_format2_t *srcfmt; + void *dst; + const audio_format2_t *dstfmt; + int count; + void *context; +} audio_filter_arg_t; + +typedef void(*audio_filter_t)(audio_filter_arg_t *arg); + +typedef struct { + audio_filter_t codec; + void *context; +} audio_filter_reg_t; +.Ed +.Pp +.Va codec +is a conversion function and +.Va context +is an optional opaque pointer passed to +.Va codec . +.Pp +When +.Va codec +is called, all parameters required by +.Va codec +are contained in +.Va arg . +.Va src +points to the input buffer block, +.Va srcfmt +contains the input encoding parameters, +.Va dst +points to the output buffer block and +.Va dstfmt +contains the output encoding parameters. +.Va count +represents the number of frames to process on this call. +.Va src +and +.Va dst +are guaranteed to be able to consecutively access number of frames +specified by +.Va count. +.Va codec +must fill the entirety of +.Va dst . +For example, let count = 100, srcfmt is { precision = 16, channels = 3 }, +dstfmt is { precision = 8, channels = 4 }, +in this case, +src block length = 2(bytes) * 3(channels) * 100(frames) = 600 bytes, +The length to be written to +.Va dst +block is 1(byte) * 4(channels) * 100(frames) = 400 bytes. +.Va codec +cannot abort the conversion halfway and there is no error reporting mechanism. +.Va context +is a opaque pointer that can be used by +.Va codec +if necessary. +.Pp +If the device does not have the +.Dv AUDIO_PROP_INDEPENDENT +property the same value is passed in both +.Va play +and +.Va rec . +Returns 0 on success, otherwise an error code. +It is called in the Attach or Closed phases. +.It Dv int round_blocksize(void *hdl, int bs, int mode, +.Dv "const audio_params_t *param)" +.Pp +optional, is called with the block size, +.Va bs , +that has been computed by the upper layer, +.Va mode , +.Dv AUMODE_PLAY +or +.Dv AUMODE_RECORD , +and +.Va param , +encoding parameters for the hardware. +.Va bs +passed is always non-zero and a multiple of the frame size represented by +param->channels * param->precision / 8. +It should return a block size, possibly changed according to the needs +of the hardware driver. +The return value also must be non-zero and a multiple of the frame size. +It is called in the Attach or Closed phases. +.It Dv int commit_settings(void *hdl) +optional, is called after all calls to +.Va set_format , +and +.Va set_port , +are done. +A hardware driver that needs to get the hardware in and out of command +mode for each change can save all the changes during previous calls and +do them all here. +Returns 0 on success, otherwise an error code. +It is called in the Attach or Closed phases. +.It Dv int init_output(void *hdl, void *buffer, int size) +optional, is called before any output starts, but when the total +.Va size +of the output +.Va buffer +has been determined. +It can be used to initialize looping DMA for hardware that needs that. +Return 0 on success, otherwise an error code. +It is called in the Attach or Closed phases. +.It Dv int init_input(void *hdl, void *buffer, int size) +optional, is called before any input starts, but when the total +.Va size +of the input +.Va buffer +has been determined. +It can be used to initialize looping DMA for hardware that needs that. +Returns 0 on success, otherwise an error code. +It is called in the Attach or Closed phases. +.It Dv int start_output(void *hdl, void *block, int blksize, +.Dv "void (*intr)(void*), void *intrarg)" +.Pp +is called to start the transfer of +.Va blksize +bytes from +.Va block +to the audio hardware. +The call should return when the data transfer has been initiated +(normally with DMA). +When the hardware is ready to accept more samples the function +.Va intr +should be called with the argument +.Va intrarg . +Calling +.Va intr +will normally initiate another call to +.Va start_output . +Returns 0 on success, otherwise an error code. +This field is optional only if the driver doesn't support playback. +It is called in the Opened phase. +.It Dv int start_input(void *hdl, void *block, int blksize, +.Dv "void (*intr)(void*), void *intrarg)" +.Pp +is called to start the transfer of +.Va blksize +bytes to +.Va block +from the audio hardware. +The call should return when the data transfer has been initiated +(normally with DMA). +When the hardware is ready to deliver more samples the function +.Va intr +should be called with the argument +.Va intrarg . +Calling +.Va intr +will normally initiate another call to +.Va start_input . +Returns 0 on success, otherwise an error code. +This field is optional only if the driver doesn't support recording. +It is called in the Opened phase. +.It Dv int halt_output(void *hdl) +is called to abort the output transfer (started by +.Va start_output ) +in progress. +Returns 0 on success, otherwise an error code. +This field is optional only if the driver doesn't support playback. +It is called in the Opened phase. +.It Dv int halt_input(void *hdl) +is called to abort the input transfer (started by +.Va start_input ) +in progress. +Returns 0 on success, otherwise an error code. +This field is optional only if the driver doesn't support recording, +It is called in the Opened phase. +.It Dv int speaker_ctl(void *hdl, int on) +optional, is called when a half duplex device changes between +playing and recording. +It can, e.g., be used to turn on +and off the speaker. +Returns 0 on success, otherwise an error code. +It is called in the Opened phase. +.It Dv int getdev(void *hdl, struct audio_device *ret) +Should fill the +.Va audio_device +struct with relevant information about the driver. +Returns 0 on success, otherwise an error code. +It is called in the Opened phase. +.It Dv int set_port(void *hdl, mixer_ctrl_t *mc) +is called in when +.Dv AUDIO_MIXER_WRITE +is used. +It should take data from the +.Va mixer_ctrl_t +struct and set the corresponding mixer values. +Returns 0 on success, otherwise an error code. +It is called in the Opened or Closed phases. +.It Dv int get_port(void *hdl, mixer_ctrl_t *mc) +is called in when +.Dv AUDIO_MIXER_READ +is used. +It should fill the +.Va mixer_ctrl_t +struct. +Returns 0 on success, otherwise an error code. +It is called in the Opened or Closed phases. +.It Dv int query_devinfo(void *hdl, mixer_devinfo_t *di) +is called in when +.Dv AUDIO_MIXER_DEVINFO +is used. +It should fill the +.Va mixer_devinfo_t +struct. +Return 0 on success, otherwise an error code. +It is called at any time. +.It Dv "void *allocm(void *hdl, int direction, size_t size)" +optional, is called to allocate the device buffers. +If not present +.Xr malloc 9 +is used instead (with the same arguments but the first two). +The reason for using a device dependent routine instead of +.Xr malloc 9 +is that some buses need special allocation to do DMA. +Returns the address of the buffer, or +.Dv NULL +on failure. +It is called in the Attached or Closed phases. +.It Dv void freem(void *hdl, void *addr, size_t size) +optional, is called to free memory allocated by +.Va allocm . +If not supplied +.Xr free 9 +is used. +It is called in the Attached or Closed phases. +.It Dv size_t round_buffersize(void *hdl, int direction, size_t bufsize) +optional, is called at startup to determine the audio +buffer size. +The upper layer supplies the suggested size in +.Va bufsize , +which the hardware driver can then change if needed. +E.g., DMA on the ISA bus cannot exceed 65536 bytes. +It is called in the Attached or Closed phases. +.It Dv int get_props(void *hdl) +Should return the device properties in a combination of following flags: +.Pp +.Bl -tag -width AUDIO_PROP_INDEPENDENT -compact +.It Dv AUDIO_PROP_PLAYBACK +the device is capable of audio playback. +.It Dv AUDIO_PROP_CAPTURE +the device is capable of audio capture. +.It Dv AUDIO_PROP_FULLDUPLEX +the device admits full duplex operation. +Don't set it if the device is unidirectional. +.It Dv AUDIO_PROP_INDEPENDENT +the device can set the playing and recording encoding parameters +independently. +Don't set it if the device is unidirectional. +.It Dv AUDIO_PROP_MMAP +is handled in the upper layer, so new drivers should not return this property. +.El +It is called in the Attach phase. +.It Dv int trigger_output(void *hdl, void *start, void *end, +.Dv "int blksize, void (*intr)(void*), void *intrarg," +.Pp +.Dv "const audio_params_t *param)" +.Pp +optional, is called to start the transfer of data from the circular buffer +delimited by +.Va start +and +.Va end +to the audio hardware, parameterized as in +.Va param . +The call should return when the data transfer has been initiated +(normally with DMA). +When the hardware is finished transferring each +.Va blksize +sized block, the function +.Va intr +should be called with the argument +.Va intrarg +(typically from the audio hardware interrupt service routine). +Once started the transfer may be stopped using +.Va halt_output . +Return 0 on success, otherwise an error code. +It is called in the Opened phase. +.It Dv int trigger_input(void *hdl, void *start, void *end, +.Dv "int blksize, void (*intr)(void*), void *intrarg," +.Pp +.Dv "const audio_params_t *param)" +.Pp +optional, is called to start the transfer of data from the audio hardware, +parameterized as in +.Va param , +to the circular buffer delimited by +.Va start +and +.Va end . +The call should return when the data transfer has been initiated +(normally with DMA). +When the hardware is finished transferring each +.Va blksize +sized block, the function +.Va intr +should be called with the argument +.Va intrarg +(typically from the audio hardware interrupt service routine). +Once started the transfer may be stopped using +.Va halt_input . +Return 0 on success, otherwise an error code. +It is called in the Opened phase. +.It Dv int dev_ioctl(void *hdl, u_long cmd, void *addr, +.Pp +.Dv "int flag, struct lwp *l)" +.Pp +optional, is called when an +.Xr ioctl 2 +is not recognized by the generic audio driver. +Return 0 on success, otherwise an error code. +It is called in the Opened phase. +.It Dv void get_locks(void *hdl, kmutex_t **intr, kmutex_t **thread) +Returns the interrupt and thread locks to the common audio layer. +It is called in the Attach phase. +.El +.Pp +The +.Va query_devinfo +method should define certain mixer controls for +.Dv AUDIO_SETINFO +to be able to change the port and gain, +and +.Dv AUDIO_GETINFO +to read them, as follows. +.Pp +If the record mixer is capable of input from more than one source, +it should define +.Dv AudioNsource +in class +.Dv AudioCrecord . +This mixer control should be of type +.Dv AUDIO_MIXER_ENUM +or +.Dv AUDIO_MIXER_SET +and enumerate the possible input sources. +Each of the named sources for which the recording level can be set +should have a control in the +.Dv AudioCrecord +class of type +.Dv AUDIO_MIXER_VALUE , +except the +.Qq mixerout +source is special, +and will never have its own control. +Its selection signifies, +rather, +that various sources in class +.Dv AudioCrecord +will be combined and presented to the single recording output +in the same fashion that the sources of class +.Dv AudioCinputs +are combined and presented to the playback output(s). +If the overall recording level can be changed, +regardless of the input source, +then this control should be named +.Dv AudioNmaster +and be of class +.Dv AudioCrecord . +.Pp +Controls for various sources that affect only the playback output, +as opposed to recording, +should be in the +.Dv AudioCinputs +class, +as of course should any controls that affect both playback and recording. +.Pp +If the play +mixer is capable of output to more than one destination, +it should define +.Dv AudioNselect +in class +.Dv AudioCoutputs . +This mixer control should be of type +.Dv AUDIO_MIXER_ENUM +or +.Dv AUDIO_MIXER_SET +and enumerate the possible destinations. +For each of the named destinations for which the output level can be set, +there should be +a control in the +.Dv AudioCoutputs +class of type +.Dv AUDIO_MIXER_VALUE . +If the overall output level can be changed, +which is invariably the case, +then this control should be named +.Dv AudioNmaster +and be of class +.Dv AudioCoutputs . +.Pp +There's one additional source recognized specially by +.Dv AUDIO_SETINFO +and +.Dv AUDIO_GETINFO , +to be presented as monitor_gain, +and that is a control named +.Dv AudioNmonitor , +of class +.Dv AudioCmonitor . +.Sh SEE ALSO +.Xr audio 4 +.Sh HISTORY +This +.Nm +interface first appeared in +.Nx 1.3 . diff --git a/static/netbsd/man9/autoconf.9 b/static/netbsd/man9/autoconf.9 new file mode 100644 index 00000000..735c5711 --- /dev/null +++ b/static/netbsd/man9/autoconf.9 @@ -0,0 +1,507 @@ +.\" $NetBSD: autoconf.9,v 1.35 2021/08/08 16:12:10 andvar Exp $ +.\" +.\" Copyright (c) 2001, 2002, 2021 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 7, 2021 +.Dt AUTOCONF 9 +.Os +.Sh NAME +.Nm autoconf , +.Nm config_search , +.Nm config_found , +.Nm config_match , +.Nm config_attach , +.Nm config_attach_pseudo , +.Nm config_detach , +.Nm config_detach_children , +.Nm config_deactivate , +.Nm config_defer , +.Nm config_interrupts , +.Nm config_mountroot , +.Nm config_pending_incr , +.Nm config_pending_decr , +.Nm config_finalize_register +.Nd autoconfiguration framework +.Sh SYNOPSIS +.In sys/param.h +.In sys/device.h +.In sys/errno.h +.Ft cfdata_t +.Fn config_search "device_t parent" "void *aux" "const struct cfargs *" +.Ft device_t +.Fn config_found "device_t parent" "void *aux" "cfprint_t print" \ +"const struct cfargs *" +.Ft int +.Fn config_match "device_t parent" "cfdata_t cf" "void *aux" +.Ft int +.Fn config_probe "device_t parent" "cfdata_t cf" "void *aux" +.Ft device_t +.Fn config_attach "device_t parent" "cfdata_t cf" "void *aux" \ +"cfprint_t print" "const struct cfargs *" +.Ft device_t +.Fn config_attach_pseudo "cfdata_t cf" +.Ft int +.Fn config_detach "device_t dev" "int flags" +.Ft int +.Fn config_detach_children "device_t dev" "int flags" +.Ft int +.Fn config_deactivate "device_t dev" +.Ft int +.Fn config_defer "device_t dev" "void (*func)(device_t)" +.Ft void +.Fn config_interrupts "device_t dev" "void (*func)(device_t)" +.Ft void +.Fn config_mountroot "device_t dev" "void (*func)(device_t)" +.Ft void +.Fn config_pending_incr +.Ft void +.Fn config_pending_decr +.Ft int +.Fn config_finalize_register "device_t dev" "int (*func)(device_t)" +.Sh DESCRIPTION +Autoconfiguration is the process of matching hardware devices with an +appropriate device driver. +In its most basic form, autoconfiguration consists of the recursive process +of finding and attaching all devices on a bus, including other busses. +.Pp +The autoconfiguration framework supports +.Em direct configuration +where the bus driver can determine the devices present. +The autoconfiguration framework also supports +.Em indirect configuration +where the drivers must probe the bus looking for the presence of a device. +Direct configuration is preferred since it can find hardware +regardless of the presence of proper drivers. +.Pp +The autoconfiguration process occurs at system bootstrap and is driven +by a table generated from a +.Do +machine description +.Dc +file by +.Xr config 1 . +For a description of the +.Xr config 1 +.Do +device definition +.Dc +language, see +.Xr config 9 . +.Pp +Each device must have a name consisting of an alphanumeric string that +ends with a unit number. +The unit number identifies an instance of the driver. +Device data structures are allocated dynamically during +autoconfiguration, giving a unique address for each instance. +.Pp +Several of the autoconfiguration functions take a strongly-typed variadic +list of arguments to pass information from driver autoconfiguration +functions to the kernel's autoconfiguration system. +This list is constructed using the +.Fn CFARGS +macro, like this example: +.Bd -literal -offset indent +config_search(self, NULL, + CFARGS(.search = mainbus_search, + .iattr = "mainbus")); +.Ed +.Pp +Each tag is followed by a tag-specific value. +.Bl -tag -offset indent -width ".Fa devhandle" +.It Fa submatch +A pointer to a +.Sq submatch +function used in +.Em direct +configuration. +.\" +.It Fa search +A pointer to a +.Sq search +function used in +.Em indirect +configuration. +.\" +.It Fa iattr +A pointer to a constant +.Tn C +string +.Pq Vt "const char *" +specifying an interface attribute. +If a parent device carries only a single interface attribute, then this +argument may be omitted. +If an interface attribute is specified that the parent device does not +carry, or no interface attribute is specified and the parent device carries +more than one, behavior is undefined. +On kernels built with the +.Dv DIAGNOSTIC +option, this may result in an assertion panic. +.\" +.It Fa locators +A pointer to a constant array of integers +.Pq Vt "const int *" +containing interface attribute-specific locators. +.\" +.It Fa devhandle +A +.Vt devhandle_t +(passed by value) corresponding to the device being attached. +.El +.Pp +If no arguments are to be passed, the special value +.Dv CFARGS_NONE +may be used in place of the +.Fn CFARGS +macro. +.Sh FUNCTIONS +.Bl -tag -width ".Fn config" +.\" +.\" +.It Fn config_search "parent" "aux" "cfargs" +Cfargs consumed: +.Fa search , +.Fa iattr , +.Fa locators . +.\" +.Pp +Performs indirect configuration of physical devices. +.Fn config_search +iterates over all potential children, calling the given +search function +If no search function is specified, +.fn config_search +applies the potential child's match function instead. +The argument +.Fa parent +is the pointer to the parent's device structure. +If an interface attribute is specified, only potential children eligible to +attach to that interface attribute will be consulted. +If specified, +the locators argument lists the locator values for the device and are passed +to the search function. +The given +.Fa aux +argument describes the device that has been found and is simply passed +on through the search function to the child. +.Fn config_search +returns a pointer to the configuration data that indicates the best-matched +child or +.Dv NULL +otherwise. +.Pp +The role of the search function is to call +.Fn config_probe +for each potential child and call +.Fn config_attach +for any positive matches. +If no search function is specified, +then the parent should record the return value from +.Fn config_search +and call +.Fn config_attach +itself. +.Pp +Note that this function is designed so that it can be used to apply an +arbitrary function to all potential children. +In this case callers may choose to ignore the return value. +.\" +.\" +.It Fn config_found "parent" "aux" "print" "cfargs" +Cfargs consumed: +.Fa submatch , +.Fa iattr , +.Fa locators , +.Fa devhandle . +.\" +.Pp +Performs direct configuration on a physical device. +.Fn config_found +is called by the parent and in turn calls the specified submatch function +as determined by the configuration table. +The submatch function compares user-specified locators from the +machine description file against those specifying a found device, +calling +.Fn config_match +if they match +.Pq including wildcard matching . +If a submatch function is not specified, then driver match functions are +called directly. +The argument +.Fa parent +is the pointer to the parent's device structure. +If an interface attribute is specified, only potential children eligible to +attach to that interface attribute will be consulted. +If specified, the locators argument lists the locator values for the found +device and may be used by the submatch function and will be recorded in the +device structure of the child device. +The given +.Fa aux +argument describes the device that has been found. +.Fn config_found +internally uses +.Fn config_search . +The +.Vt softc +structure for the matched device will be allocated, and the +appropriate driver attach function will be called. +If the device is matched, the system prints the name of the child and +parent devices, and then calls the +.Fa print +function to produce additional information if desired. +If no driver takes a match, the same +.Fa print +function is called to complain. +The print function is called with the +.Fa aux +argument and, if the matches failed, the full name (including unit +number) of the parent device, otherwise +.Dv NULL . +The +.Fa print +function must return an integer value. +.Pp +Two special strings, +.Do +not configured +.Dc +and +.Do +unsupported +.Dc +will be appended automatically to non-driver reports if the return +value is +.Dv UNCONF +or +.Dv UNSUPP +respectively; otherwise the function should +return the value +.Dv QUIET . +If a device handle is specified, that handle will be associated with +the resulting child device structure if a driver matches. +.Pp +.Fn config_found +returns a pointer to the attached device's +.Vt device +structure if the device is attached, +.Dv NULL +otherwise. +Most callers can ignore this value, since the system will already have +printed a diagnostic. +.\" +.\" +.It Fn config_match "parent" "cf" "aux" +.\" +Match a device +.Pq direct configuration . +Invokes the driver's match function according to the configuration table. +The +.Fn config_match +function returns a nonzero integer indicating the confidence of +supporting this device and a value of 0 if the driver doesn't support +the device. +.\" +.\" +.It Fn config_probe "parent" "cf" "aux" +.\" +Probe for a device +.Pq indirect configuration . +Invokes the driver's match function according to the configuration table. +The +.Fn config_probe +function returns a nonzero integer to indicate a successful probe +and a value of 0 otherwise. +Unlike +.Fn config_match , +the return value of +.Fn config_probe +is not intended to reflect a confidence value. +.\" +.\" +.It Fn config_attach "parent" "cf" "aux" "print" "cfargs" +Cfargs consumed: +.Fa locators , +.Fa devhandle . +.\" +.Pp +Attach a found device. +Allocates the memory for the +.Vt softc +structure and calls the drivers attach function according to the +configuration table. +If successful, +.Fn config_attach +returns a pointer to the +.Vt device +structure. +If unsuccessful, it returns +.Dv NULL . +.\" +.\" +.It Fn config_attach_pseudo "cf" +.\" +Create an instance of a pseudo-device driver. +.Xr config 5 +syntax allows the creation of pseudo-devices from which regular +.Ft device_t +instances can be created. +Such objects are similar to the devices that attach at the root of the device +tree. +.Pp +The caller is expected to allocate and fill the +.Ft cfdata_t +object and pass it to +.Fn config_attach_pseudo . +The content of that object is similar to what is returned by +.Fn config_search +for regular devices. +.\" +.\" +.It Fn config_detach "dev" "flags" +.\" +Called by the parent to detach the child device. +The second argument +.Fa flags +contains detachment flags. +Valid values are +.Dv DETACH_FORCE +(force detachment, e.g., because of hardware removal) +and +.Dv DETACH_QUIET +(do not print a notice). +.Fn config_detach +returns zero if successful and an error code otherwise. +.Fn config_detach +is always called from a thread context, allowing condition variables +to be used while the device detaches itself. +.\" +.\" +.It Fn config_detach_children "dev" "flags" +.\" +Iterate through all attached devices, calling +.Fn config_detach +for each child of +.Fa dev , +passing +.Fa flags . +If detaching any child results in an error, the iteration will halt +and any remaining devices will not be detached. +.Fn config_detach_children +returns zero if successful and an error code otherwise. +.\" +.\" +.It Fn config_deactivate "dev" +.\" +Called by the parent to deactivate the child device +.Fa dev . +.Fn config_deactivate +is called from interrupt context to immediately relinquish resources +and notify dependent kernel subsystems that the device is about to be +detached. +At some later point +.Fn config_detach +will be called to finalise the removal of the device. +.\" +.\" +.It Fn config_defer "dev" "func" +.\" +Called by the child to defer the remainder of its configuration until +all its parent's devices have been attached. +At this point, the function +.Fa func +is called with the argument +.Fa dev . +.\" +.\" +.It Fn config_interrupts "dev" "func" +.\" +Called by the child to defer the remainder of its configuration until +interrupts are enabled. +At this point, the function +.Fa func +is called with the argument +.Fa dev . +.\" +.\" +.It Fn config_mountroot "dev" "func" +.\" +Called by the child to defer the remainder of its configuration until +the root file system is mounted. +At this point, the function +.Fa func +is called with the argument +.Fa dev . +This is used for devices that need to load firmware image from +a mounted file system. +.\" +.\" +.It Fn config_pending_incr +.\" +Increment the +.Va config_pending +semaphore. +It is used to account for deferred configurations before +mounting the root file system. +.\" +.\" +.It Fn config_pending_decr +.\" +Decrement the +.Va config_pending +semaphore. +It is used to account for deferred configurations before +mounting the root file system. +.\" +.\" +.It Fn config_finalize_register "dev" "func" +.\" +.\" +Register a function to be called after all real devices have been found. +.Pp +Registered functions are all executed until all of them return 0. +The callbacks should return 0 to indicate they do not require to be called +another time, but they should be aware that they still might be in case one of +them returns 1. +.El +.Sh CODE REFERENCES +The autoconfiguration framework itself is implemented within the file +.Pa sys/kern/subr_autoconf.c . +Data structures and function prototypes for the framework are located in +.Pa sys/sys/device.h . +.Sh SEE ALSO +.Xr config 1 , +.Xr config 5 , +.Xr condvar 9 , +.Xr config 9 , +.Xr driver 9 +.Sh HISTORY +Autoconfiguration first appeared in +.Bx 4.1 . +The autoconfiguration framework was completely revised in +.Bx 4.4 . +The detach and deactivate interfaces appeared in +.Nx 1.5 . diff --git a/static/netbsd/man9/bcdtobin.9 b/static/netbsd/man9/bcdtobin.9 new file mode 100644 index 00000000..ab832f78 --- /dev/null +++ b/static/netbsd/man9/bcdtobin.9 @@ -0,0 +1,62 @@ +.\" $NetBSD: bcdtobin.9,v 1.2 2008/04/30 13:10:58 martin Exp $ +.\" +.\" Copyright (c) 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 11, 2006 +.Dt BCDTOBIN 9 +.Os +.Sh NAME +.Nm bcdtobin , +.Nm bintobcd +.Nd convert a single byte between (unsigned) packed bcd and binary +.Sh SYNOPSIS +.In sys/systm.h +.Ft unsigned int +.Fn bcdtobin "unsigned int bcd" +.Ft unsigned int +.Fn bintobcd "unsigned int bin" +.Sh DESCRIPTION +The +.Fn bcdtobin +and +.Fn bintobcd +functions +convert a single byte between (unsigned) packed bcd and binary +encodings. +.Sh RETURN VALUES +The +.Fn bcdtobin +function +returns the binary value of its BCD-encoded argument, +.Fa bcd . +The +.Fn bintobcd +function returns the BCD encoding of its binary argument, +.Fa bin . +.\" .Sh SEE ALSO +.\" .Sh STANDARDS diff --git a/static/netbsd/man9/bcmp.9 b/static/netbsd/man9/bcmp.9 new file mode 100644 index 00000000..b7ff08b9 --- /dev/null +++ b/static/netbsd/man9/bcmp.9 @@ -0,0 +1,74 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)bcmp.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: bcmp.9,v 1.6 2003/08/07 10:31:29 agc Exp $ +.\" +.Dd July 7, 2001 +.Dt BCMP 9 +.Os +.Sh NAME +.Nm bcmp +.Nd compare byte string +.Sh SYNOPSIS +.In sys/systm.h +.Ft int +.Fn bcmp "const void *b1" "const void *b2" "size_t len" +.Sh DESCRIPTION +.Bf -symbolic +The +.Fn bcmp +interface is obsolete. +Do not add new code using it. +It will soon be purged. +Use +.Xr memcmp 9 +instead. +(The +.Fn bcmp +function is now a macro for +.Xr memcmp 9 . ) +.Ef +.Pp +The +.Fn bcmp +function +compares byte string +.Fa b1 +against byte string +.Fa b2 , +returning zero if they are identical, non-zero otherwise. +Both strings are assumed to be +.Fa len +bytes long. +Zero-length strings are always identical. +.Pp +The strings may overlap. +.Sh SEE ALSO +.Xr memcmp 9 diff --git a/static/netbsd/man9/bcopy.9 b/static/netbsd/man9/bcopy.9 new file mode 100644 index 00000000..603db900 --- /dev/null +++ b/static/netbsd/man9/bcopy.9 @@ -0,0 +1,89 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)bcopy.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: bcopy.9,v 1.9 2003/08/07 10:31:30 agc Exp $ +.\" +.Dd July 7, 2001 +.Dt BCOPY 9 +.Os +.Sh NAME +.Nm bcopy +.Nd copy byte string +.Sh SYNOPSIS +.In sys/systm.h +.Ft void +.Fn bcopy "const void *src" "void *dst" "size_t len" +.Sh DESCRIPTION +.Bf -symbolic +The +.Fn bcopy +interface is obsolete. +Do not add new code using it. +It will soon be purged. +Use +.Xr memcpy 9 +instead. +(The +.Fn bcopy +function is now a macro for +.Xr memcpy 9 . ) +.Ef +.Pp +The +.Fn bcopy +function +copies +.Fa len +bytes from string +.Fa src +to string +.Fa dst . +.Pp +.Bf -symbolic +Unlike +.Xr bcopy 3 +the two strings must not overlap! +.Ef +In the traditional +.Bx +kernel, overlapping copies were handled by the now-purged +.Fn ovbcopy +function. +If you need to copy overlapping data, see +.Xr memmove 9 . +.Pp +If +.Fa len +is zero, no bytes are copied. +.Sh SEE ALSO +.Xr bcopy 3 , +.Xr memcpy 9 , +.Xr memmove 9 diff --git a/static/netbsd/man9/bintime_add.9 b/static/netbsd/man9/bintime_add.9 new file mode 100644 index 00000000..cf74f804 --- /dev/null +++ b/static/netbsd/man9/bintime_add.9 @@ -0,0 +1,101 @@ +.\" $NetBSD: bintime_add.9,v 1.2 2010/06/08 07:20:20 wiz Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 8, 2010 +.Dt BINTIME_ADD 9 +.Os +.Sh NAME +.Nm bintime_add +.Nd operations on +.Dq bintime +.Sh SYNOPSIS +.In sys/time.h +.Ft vid +.Fn bintime_add "struct bintime *bt" "const struct bintime *bt2" +.Ft void +.Fn bintime_addx "struct bintime *bt" "uint64_t x" +.Ft void +.Fn bintime_sub "struct bintime *bt" "const struct bintime *bt2" +.Ft void +.Fn bintime2timespec "const struct bintime *bt" "struct timespec *ts" +.Ft void +.Fn timespec2bintime "const struct timespec *ts" "struct bintime *bt" +.Ft void +.Fn bintime2timeval "const struct bintime *bt" "struct timeval *tv" +.Ft void +.Fn timeval2bintime "const struct timeval *tv" "struct bintime *bt" +.Sh DESCRIPTION +These functions are provided for convenience as part of the machine-independent +.Xr timecounter 9 +framework. +All of them operate with the +.Em bintime +structure. +.Pp +The function +.Fn bintime_add +adds the time information stored in +.Fa bt2 +to +.Fa bt . +Conversely, +.Fn bintime_sub +subtracts +.Fa bt2 +from +.Fa bt . +The +.Fn bintime_addx +function stores the fraction of a second +.Fa x +to +.Fa bt . +.Pp +Like the function names bespeak, +.Fn bintime2timespec +converts the +.Em bintime +structure to +.Em struct timespec +and +.Fn timespec2bintime +does the opposite. +The functions +.Fn bintime2timeval +and +.Fn timeval2bintime +operate with +.Em struct timeval +instead. +The result is stored to the right-hand side. +.Sh SEE ALSO +.Xr timeradd 3 , +.Xr timeval 3 , +.Xr bintime 9 , +.Xr timecounter 9 diff --git a/static/netbsd/man9/bluetooth.9 b/static/netbsd/man9/bluetooth.9 new file mode 100644 index 00000000..d58d1576 --- /dev/null +++ b/static/netbsd/man9/bluetooth.9 @@ -0,0 +1,384 @@ +.\" $NetBSD: bluetooth.9,v 1.6 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright (c) 2006 Itronix Inc. +.\" All rights reserved. +.\" +.\" Written by Iain Hibbert for Itronix Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of Itronix Inc. may not be used to endorse +.\" or promote products derived from this software without specific +.\" prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY ITRONIX INC. ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ITRONIX INC. BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +.\" ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.Dd November 20, 2007 +.Dt BLUETOOTH 9 +.Os +.Sh NAME +.Nm BLUETOOTH +.Nd Bluetooth Device/Protocol API +.Sh SYNOPSIS +.In netbt/bluetooth.h +.In netbt/hci.h +.In netbt/l2cap.h +.In netbt/rfcomm.h +.Ft struct hci_unit * +.Fn hci_attach "const struct hci_if *hci_if" "device_t dev" "uint16_t flags" +.Ft void +.Fn hci_detach "struct hci_unit *unit" +.Ft void +.Fn hci_input_event "struct hci_unit *unit" "struct mbuf *m" +.Ft void +.Fn hci_input_acl "struct hci_unit *unit" "struct mbuf *m" +.Ft void +.Fn hci_input_sco "struct hci_unit *unit" "struct mbuf *m" +.Ft int +.Fn btproto_attach "btproto_handle *" "const struct btproto *proto" "void *ref" +.Ft int +.Fn btproto_bind "btproto_handle" "struct sockaddr_bt *addr" +.Ft int +.Fn btproto_sockaddr "btproto_handle" "struct sockaddr_bt *addr" +.Ft int +.Fn btproto_connect "btproto_handle" "struct sockaddr_bt *addr" +.Ft int +.Fn btproto_peeraddr "btproto_handle" "struct sockaddr_bt *addr" +.Ft int +.Fn btproto_disconnect "btproto_handle" "int linger" +.Ft int +.Fn btproto_detach "btproto_handle *" +.Ft int +.Fn btproto_listen "btproto_handle" +.Ft int +.Fn btproto_send "btproto_handle" "struct mbuf *mbuf" +.Ft int +.Fn btproto_rcvd "btproto_handle" "size_t space" +.Ft int +.Fn btproto_setopt "btproto_handle" "int optarg" "void *arg" +.Ft int +.Fn btproto_getopt "btproto_handle" "int optarg" "void *arg" +.Sh DESCRIPTION +The Bluetooth Protocol Stack provides socket based access to Bluetooth +Devices. +This document describes device driver access to the stack from +below, and also the general Bluetooth Protocol/Service API for layering +above existing Bluetooth Protocols. +.Sh DATA TYPES +Device drivers attaching to the Bluetooth Protocol Stack should pass a +pointer to a +.Fa struct hci_if +defined in +.In netbt/hci.h +containing the driver information as follows: +.Bd -literal +struct hci_if { + int (*enable)(device_t); + void (*disable)(device_t); + void (*output_cmd)(device_t, struct mbuf *); + void (*output_acl)(device_t, struct mbuf *); + void (*output_sco)(device_t, struct mbuf *); + void (*get_stats)(device_t, struct bt_stats *, int); + int ipl; +}; +.Ed +.Pp +Statistics counters should be updated by the device after packets have +been transmitted or received, or when errors occur. +.Bd -literal +struct bt_stats { + uint32_t err_tx; + uint32_t err_rx; + uint32_t cmd_tx; + uint32_t evt_rx; + uint32_t acl_tx; + uint32_t acl_rx; + uint32_t sco_tx; + uint32_t sco_rx; + uint32_t byte_tx; + uint32_t byte_rx; +}; +.Ed +.Pp +Bluetooth Protocol layers attaching above the Bluetooth Protocol Stack +will make use of the +.Fa struct btproto +data type, which is defined in +.In netbt/bluetooth.h +and contains the following function callbacks which +should be initialized by the protocol layer before attaching to the +protocol which it uses: +.Bd -literal +struct btproto { + void (*connecting)(void *); + void (*connected)(void *); + void (*disconnected)(void *, int); + void *(*newconn)(void *, struct sockaddr_bt *, struct sockaddr_bt *); + void (*complete)(void *, int); + void (*linkmode)(void *, int); + void (*input)(void *, struct mbuf *); +}; +.Ed +.Sh FUNCTIONS +The following functions are related to the Bluetooth Device API. +.Bl -tag -width XXXX +.It Fn hci_attach "hci_if" "dev" +Attach Bluetooth HCI device +.Ar dev +to the protocol stack in the manner described by +.Ar hci_if . +Driver quirks may be registered by passing the corresponding +.Dv BTF_xxxx +flag in the +.Ar flags +argument. +.Pp +.Fn hci_attach +will return a +.Fa struct hci_unit +handle to be passed to the protocol stack in other calls. +.It Fn hci_detach "unit" +Detach Bluetooth HCI +.Ar unit +from the device. +.It Fn hci_input_event "unit" "mbuf" +This function should be called by the device when it has an event +packet to present to the protocol stack. +It may be called from an interrupt routine at the +.Fa ipl +value given in the +.Ar hci_if +descriptor. +.It Fn hci_input_acl "unit" "mbuf" +This function should be called by the device when it has an ACL data +packet to present to the protocol stack. +It may be called from an interrupt routine at the +.Fa ipl +value given in the +.Ar hci_if +descriptor. +.It Fn hci_input_sco "unit" "mbuf" +This function should be called by the device when it has an SCO data +packet to present to the protocol stack. +It may be called from an interrupt routine at the +.Fa ipl +value given in the +.Ar hci_if +descriptor. +.It Fn "(*enable)" "dev" +This will be called when the protocol stack wishes to enable the device. +.It Fn "(*disable)" "dev" +This will be called when the protocol stack wishes to disable the device. +.It Fn "(*output_cmd)" "dev" "mbuf" +Will be called to output command packets on the device. +The device is responsible for arbitrating access to the output queue, and +output commands should be sent asynchronously. +The device owns the +.Ar mbuf +and should release it when sent. +.It Fn "(*output_acl)" "dev" "mbuf" +Will be called to output ACL data packets on the device. +The device is responsible for arbitrating access to the output queue, and +ACL data packets should be sent asynchronously. +The device owns the +.Ar mbuf +and should release it when sent. +.It Fn "(*output_sco)" "dev" "mbuf" +Will be called to output SCO data packets on the device. +The device is responsible for arbitrating access to the output queue, and +SCO data packets should be sent asynchronously. +When the SCO data packet has been placed on the device and the +.Ar mbuf +is no longer required, it should be returned to the Bluetooth protocol +stack via the +.Fn hci_complete_sco +call. +.It Fn "(*get_stats)" "dev" "dest" "flush" +Will be called when IO statistics are requested. +The +.Fa bt_stats +structure +.Ar dest +should be filled in, and if the +.Ar flush +argument is true, statistics should be reset. +.El +.Pp +The following function definitions are related to the Bluetooth Protocol API. +Note that the "btproto" prefix is representative only, the protocol being +used will have a more specific prefix with prototypes being declared in +the appropriate +.In netbt/btproto.h +file. +.Bl -tag -width XXXX +.It Fn btproto_attach "handle_ptr" "proto" "ref" +Allocate and initialize a new protocol object at the +.Ar handle_ptr +address that should subsequently be passed into the other functions. +.Ar proto +is a pointer to the +.Fa btproto +structure as described above containing relevant callbacks, and +.Ar ref +is the argument that will be supplied to those calls. +.It Fn btproto_bind "handle" "addr" +Set the local address of the protocol object described by +.Ar handle +to +.Ar addr . +.It Fn btproto_sockaddr "handle" "addr" +Copy the local address of the protocol object described by +.Ar handle +into +.Ar addr +.It Fn btproto_connect "handle" "addr" +Initiate a connection by the protocol object described by +.Ar handle +to the remote device described by +.Ar addr . +This will result in a call to either +.Fn proto->connected +or +.Fn proto->disconnected , +and optionally +.Fn proto->connecting +with the appropriate reference as given to +.Fn btproto_attach . +.It Fn btproto_peeraddr "handle" "addr" +Copy the remote address of the protocol object described by +.Ar handle +into +.Ar addr . +.It Fn btproto_disconnect "handle" "linger" +Schedule a disconnection by the protocol object described by +.Ar handle . +This will result in a call to +.Fn proto->disconnected +with the appropriate reference when the connection is torn +down. +If linger is zero, the disconnection will be initiated +immediately and any outstanding data may be lost. +.It Fn btproto_detach "handle_ptr" +Detach the protocol object described by the value in the location of +.Ar handle_ptr , +and free any related memory. +The pointer in the location is cleared. +.It Fn btproto_listen "handle" +Use the protocol object described by +.Ar handle +as a listening post. +This will result in calls to the +.Fn proto->newconn +function when incoming connections are detected. +.It Fn btproto_send "handle" "mbuf" +Send data on the connection described by the protocol object. +.It Fn btproto_rcvd "handle" "space" +Indicate to the protocol that +.Ar space +is now available in the input buffers so that flow control may be +deasserted. +This should also be called to indicate initial buffer space. +Note that +.Ar space +is an absolute value. +.It Fn btproto_setopt "handle" "optarg" "arg" +Set options on the protocol object described by +.Ar handle . +.It Fn btproto_getopt "handle" "optarg" "arg" +Get options for the protocol object described by +.Ar handle . +.It Fn "(*connecting)" "ref" +This function will be called when the protocol receives information +that the connection described by +.Ar ref +is pending. +.It Fn "(*connected)" "ref" +This function will be called when the connection described by +.Ar ref +is successful and indicates that data may now be sent. +.It Fn "(*disconnected)" "ref" "error" +This function will be called when the connection described by +.Ar ref +is disconnected. +.It Fn "*(*newconn)" "ref" "laddr" "raddr" +This function will be called when the protocol receives a new incoming +connection on the local device described by +.Ar laddr +from the remote device described by +.Ar raddr . +The protocol should decide if it wishes to accept the connection and +should attach and return a new instance of the relevant protocol handle +or NULL. +.It Fn "(*complete)" "ref" "count" +This function will be called when the protocol has completed sending +data. +Complete will usually mean that the data has successfully left +the device though for guaranteed protocols it can mean that the data +has arrived at the other end and been acknowledged, and that +.Ar count +amount of data can be removed from the socket buffer. +The units of the +.Ar count +value will be dependent on the protocol being used (e.g. RFCOMM is bytes, +but L2CAP is packets) +.It Fn "(*linkmode)" "ref" "mode" +This function will be called for established connections, when the link mode +of the baseband link has changed. +.Ar mode +is the new mode. +.It Fn "(*input)" "ref" "mbuf" +This function is called to supply new data on the connection described by +.Ar ref . +.El +.Sh CODE REFERENCES +The Bluetooth Protocol Stack is contained in the +.Pa sys/netbt +directory. +.Pp +The Bluetooth Device API as described above is contained +in the +.Pa sys/netbt/hci_unit.c +file. +.Pp +For examples of the Bluetooth Protocol API see the interaction between +the L2CAP upper layer in +.Pa sys/netbt/l2cap_upper.c +and either the L2CAP socket layer in +.Pa sys/netbt/l2cap_socket.c +or the +.Xr bthidev 4 +pseudo-device in +.Pa sys/dev/bluetooth/bthidev.c . +.Pp +Also, the RFCOMM upper layer in +.Pa sys/netbt/rfcomm_upper.c +and the RFCOMM socket layer in +.Pa sys/netbt/rfcomm_socket.c . +.Sh SEE ALSO +.Xr bluetooth 4 , +.Xr bt3c 4 , +.Xr bthidev 4 , +.Xr ubt 4 +.Sh HISTORY +This Bluetooth Protocol Stack was written for +.Nx 4.0 +by +.An Iain Hibbert , +under the sponsorship of Itronix, Inc. diff --git a/static/netbsd/man9/boothowto.9 b/static/netbsd/man9/boothowto.9 new file mode 100644 index 00000000..b423925d --- /dev/null +++ b/static/netbsd/man9/boothowto.9 @@ -0,0 +1,289 @@ +.\" $NetBSD: boothowto.9,v 1.8 2018/07/19 11:09:38 wiz Exp $ +.\" +.\" Copyright (c) 2009 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 14, 2018 +.Dt BOOTHOWTO 9 +.Os +.Sh NAME +.Nm boothowto , +.Nm BOOT_FLAG +.Nd flags passed to kernel during boot or shutdown +.Sh SYNOPSIS +.In sys/reboot.h +.In sys/systm.h +.Vt extern int boothowto; +.In sys/boot_flag.h +.Vt #define BOOT_FLAG(arg, retval) ... +.Sh DESCRIPTION +The +.Va boothowto +variable contains flags passed to the kernel by the boot loader (see +.Xr boot 8 ) , +or the +.Xr reboot 2 +system call. +The value is interpreted as a bit mask, with bits defined by the +.Dq Sy RB_ Ns No * +and +.Dq Sy AB_ Ns No * +symbols in +.In sys/reboot.h . +The value is made available via the +.Xr sysctl 7 +variable +.Va kern.boothowto . +.Pp +The +.Dv BOOT_FLAG +macro defined in +.In sys/boot_flag.h +is used by many boot loaders to convert command line options into +.Va boothowto +flags. +Note that not all boot loaders use this macro, and some boot loaders +may have incompatible options. +.Pp +Where possible, flags set by the +.Xr reboot 2 +system call will be passed to the new kernel after a reboot; +the extent to which this is possible is machine dependent. +.Pp +In the following tables, +each flag is listed with +its symbolic name, +the corresponding numeric value defined in +.In sys/reboot.h , +and the option letter (if any) understood by the +.Dv BOOT_FLAG +macro. +. +.Ss Flags that affect booting or shutting down +The following flags affect actions taken during system boot +or shutdown. +.Bl -column RB_INITNAMEA 0x00000000 \&-x +.It Dv RB_AUTOBOOT Ta Li 0 Ta Ta +The default if no other flags are set. +Causes the system to boot in the normal way. +.It Dv RB_ASKNAME Ta Li 0x00000001 Ta Fl a Ta +This flag causes various parts of the system to prompt: +.Bl -bullet -compact +.It +The boot loader may prompt for the name or location of the +kernel to be booted. +.It +The kernel will prompt for the root file system device. +.It +The kernel will prompt for the root file system type. +.It +The kernel will prompt for the location of the dump device. +.It +The kernel will prompt for the path to the +.Xr init 8 +program. +.El +Some subsystems set this flag when they are unable to automatically +make a decision. +.It Dv RB_SINGLE Ta Li 0x00000002 Ta Fl s Ta +Boot in single-user mode. +If this flag is set, the kernel passes the +.Fl s +option to +.Xr init 8 . +.It Dv RB_NOSYNC Ta Li 0x00000004 Ta Ta +If this flag is set, then some parts of the shutdown process will +be less graceful than usual: +.Bl -bullet -compact +.It +Disks will not be synced +(see +.Xr sync 2 +and +.Xr cpu_reboot 9 ) . +.It +Devices will not be detached (see +.Xr autoconf 9 ) . +.\" actually, see config_detach_all, but that is undocumented +.It +File systems will not be unmounted (see +.Xr cpu_reboot 9 , +and +.Xr vfs_shutdown 9 ) . +.It +The time of day clock will not be set (see +.Xr resettodr 9 ) . +.El +.It Dv RB_HALT Ta Li 0x00000008 Ta Fl b Ta +If this flag is set, then +.Xr reboot 2 +will cause the system to halt instead of rebooting. +This flag may be set at boot time, and cannot be cleared by +.Xr reboot 2 . +.It Dv RB_INITNAME Ta Li 0x00000010 Ta Ta +This flag is obsolete. +It was previously used to cause the kernel to prompt for the name of the +.Xr init 8 +program, but that function is now controlled by the +.Dv RB_ASKNAME +flag. +.It Dv RB_KDB Ta Li 0x00000040 Ta Fl d Ta +Gives control to a kernel debugger early in the boot sequence. +See +.Xr ddb 4 +and +.Dq "options KGDB" +in +.Xr options 4 . +.It Dv RB_RDONLY Ta Li 0x00000080 Ta Ta +This flag is deprecated. +It previously caused the kernel to mount the root file system +in read-only mode, but now that is the default, and this flag +has no effect. +.It Dv RB_DUMP Ta Li 0x00000100 Ta Ta +Causes the kernel to dump memory to the dump device during shutdown. +See +.Xr savecore 8 , +.Xr cpu_reboot 9 , +and +.Xr dumpsys 9 . +.It Dv RB_MINIROOT Ta Li 0x00000200 Ta Fl m Ta +This flag informs the kernel that a mini-root file system is present +in memory. +See +.Xr md 4 , +and +.Xr mdsetimage 8 . +.It Dv RB_STRING Ta Li 0x00000400 Ta Ta +This flag indicates that a boot string is present. +The string may be provided by +.Xr reboot 2 +and will be passed to the boot loader if possible. +.It Dv RB_POWERDOWN Ta Li (RB_HALT|0x800) Ta Ta +This flag is used in conjunction with +.Dv RB_HALT . +If this flag is set, then then system will be powered down if possible. +If powerdown is not supported, then the system will halt. +.It Dv RB_USERCONF Ta Li 0x00001000 Ta Fl c Ta +This flag causes the kernel to invoke the +.Xr userconf 4 +device configuration manager early in the boot sequence. +.El +. +.Ss Flags that affect verbosity +The following flags affect the verbosity of messages printed by the kernel. +These flags are used by several functions described in +.Xr kprintf 9 +to control whether output is sent to the console, the system log, +.\" the /dev/log device driver is undocumented +both, or neither. +The use of flags that increase verbosity simultaneously with +the use of flags that decrease verbosity, +is not well defined. +.Bl -column RB_INITNAMEA 0x00000000 \&-x +.It Dv AB_NORMAL Ta Li 0 Ta Ta +The default, if none of the other +.Dv AB_* +flags is set, is that ordinary kernel messages are sent +both to the console and to the system log. +.It Dv AB_QUIET Ta Li 0x00010000 Ta Fl q Ta +Boot quietly. +Ordinary kernel messages are sent to the system log, +but not to the console. +Messages printed with +.Xr aprint_naive 9 +are sent to the console, but not to the system log. +.It Dv AB_VERBOSE Ta Li 0x00020000 Ta Fl v Ta +Boot verbosely. +Some messages will be printed that would otherwise not be printed. +Both ordinary kernel messages, and messages printed with +.Xr aprint_verbose 9 , +will be sent both to the console and to the system log. +If this flag is not set, then messages printed with +.Xr aprint_verbose 9 +will be sent only to the system log. +.It Dv AB_SILENT Ta Li 0x00040000 Ta Fl z Ta +Boot silently. +Most kernel messages will be sent only to the system log, not to the console. +The +.Fn aprint_* +functions display a spinning symbol on the console. +.It Dv AB_DEBUG Ta Li 0x00080000 Ta Fl x Ta +Boot with debug messages. +.El +. +.Ss Machine-dependent flags +The following flags have machine-dependent meanings. +.Bl -column RB_INITNAMEA 0x00000000 \&-x +.It Dv RB_MD1 Ta Li 0x10000000 Ta Fl 1 Ta +Some ports use this flag to disable multiprocessor mode, +making them use only a single CPU. +The zaurus port uses this flag to enable the serial console. +.It Dv RB_MD2 Ta Li 0x20000000 Ta Fl 2 Ta +The i386 and amd64 ports use this flag to disable +.Xr acpi 4 . +.It Dv RB_MD3 Ta Li 0x40000000 Ta Fl 3 Ta +This flag is currently not used by any ports. +.It Dv RB_MD4 Ta Li 0x80000000 Ta Fl 4 Ta +This flag is currently not used by any ports. +.El +. +.Sh SEE ALSO +.\" sets boothowto +.Xr reboot 2 , +.\" RB_KDB +.Xr ddb 4 , +.\" RB_USERCONF +.Xr userconf 4 , +.\" sysctl kern.boothowto +.Xr sysctl 7 , +.\" sets boothowto +.Xr boot 8 , +.Xr crash 8 , +.\" RB_SINGLE, RB_INITNAME +.Xr init 8 , +.\" reboot/poweroff/halt calls reboot(2) +.Xr reboot 8 , +.\" useful after RB_DUMP +.Xr savecore 8 , +.\" RB_NOSYNC +.Xr sync 8 , +.\" RB_NOSYNC, RB_HALT, RB_DUMP +.Xr cpu_reboot 9 , +.\" aprint_*() functions use AB_* flags +.Xr kprintf 9 +.Sh HISTORY +The +.Va boothowto +variable appeared in +.Bx 4.0 . +The +.Sy BOOT_FLAG +macro appeared in +.Nx 1.6 . +.Pp +The +.Dv RB_DFLTROOT +option is now +.Em obsolete . diff --git a/static/netbsd/man9/bpf.9 b/static/netbsd/man9/bpf.9 new file mode 100644 index 00000000..38331855 --- /dev/null +++ b/static/netbsd/man9/bpf.9 @@ -0,0 +1,71 @@ +.\" $NetBSD: bpf.9,v 1.5 2018/06/25 10:53:47 wiz Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 25, 2018 +.Dt BPF 9 +.Os +.Sh NAME +.Nm bpf +.Nd Berkeley Packet Filter kernel interface +.Sh SYNOPSIS +.In sys/mbuf.h +.In net/bpf.h +.Sh DESCRIPTION +.Nm +is called via an operations vector described by the following struct: +.Bd -literal +struct bpf_ops { + void (*bpf_attach)(struct ifnet *, u_int, u_int, struct bpf_if **); + void (*bpf_detach)(struct ifnet *); + void (*bpf_change_type)(struct ifnet *, u_int, u_int); + + void (*bpf_mtap)(struct bpf_if *, struct mbuf *); + void (*bpf_mtap2)(struct bpf_if *, void *, u_int, struct mbuf *); + void (*bpf_mtap_af)(struct bpf_if *, uint32_t, struct mbuf *); + void (*bpf_mtap_et)(struct bpf_if *, uint16_t, struct mbuf *); + void (*bpf_mtap_sl_in)(struct bpf_if *, u_char *, struct mbuf **); + void (*bpf_mtap_sl_out)(struct bpf_if *, u_char *, struct mbuf *); +}; +.Ed +.Pp +This vector is found from +.Vt struct bpf_ops * +.Va bpf_ops . +It is either a +.Dq stub +implementation or a real implementation, depending on whether +.Nm +is absent or present in the kernel, respectively. +.Sh CODE REFERENCES +The +.Nm +implementation is located in +.Pa sys/net/bpf.c , +the stub implementation is in +.Pa sys/net/bpf_stub.c , +and +.Pa sys/net/bpf.h +describes the interface. diff --git a/static/netbsd/man9/buffercache.9 b/static/netbsd/man9/buffercache.9 new file mode 100644 index 00000000..bf503d72 --- /dev/null +++ b/static/netbsd/man9/buffercache.9 @@ -0,0 +1,332 @@ +.\" $NetBSD: buffercache.9,v 1.33 2025/07/09 07:44:56 bad Exp $ +.\" +.\" Copyright (c)2003 YAMAMOTO Takashi, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.\" following copyright notices are from sys/kern/vfs_bio.c. +.\" they are here because i took some comments from it. yamt@NetBSD.org +.\" +.\" +.\"/*- +.\" * Copyright (c) 1982, 1986, 1989, 1993 +.\" * The Regents of the University of California. All rights reserved. +.\" * (c) UNIX System Laboratories, Inc. +.\" * All or some portions of this file are derived from material licensed +.\" * to the University of California by American Telephone and Telegraph +.\" * Co. or Unix System Laboratories, Inc. and are reproduced herein with +.\" * the permission of UNIX System Laboratories, Inc. +.\" * +.\" * Redistribution and use in source and binary forms, with or without +.\" * modification, are permitted provided that the following conditions +.\" * are met: +.\" * 1. Redistributions of source code must retain the above copyright +.\" * notice, this list of conditions and the following disclaimer. +.\" * 2. Redistributions in binary form must reproduce the above copyright +.\" * notice, this list of conditions and the following disclaimer in the +.\" * documentation and/or other materials provided with the distribution. +.\" * 3. Neither the name of the University nor the names of its contributors +.\" * may be used to endorse or promote products derived from this software +.\" * without specific prior written permission. +.\" * +.\" * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" * ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" * SUCH DAMAGE. +.\" * +.\" * @(#)vfs_bio.c 8.6 (Berkeley) 1/11/94 +.\" */ +.\" +.\"/*- +.\" * Copyright (c) 1994 Christopher G. Demetriou +.\" * +.\" * Redistribution and use in source and binary forms, with or without +.\" * modification, are permitted provided that the following conditions +.\" * are met: +.\" * 1. Redistributions of source code must retain the above copyright +.\" * notice, this list of conditions and the following disclaimer. +.\" * 2. Redistributions in binary form must reproduce the above copyright +.\" * notice, this list of conditions and the following disclaimer in the +.\" * documentation and/or other materials provided with the distribution. +.\" * 3. All advertising materials mentioning features or use of this software +.\" * must display the following acknowledgement: +.\" * This product includes software developed by the University of +.\" * California, Berkeley and its contributors. +.\" * 4. Neither the name of the University nor the names of its contributors +.\" * may be used to endorse or promote products derived from this software +.\" * without specific prior written permission. +.\" * +.\" * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" * ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" * SUCH DAMAGE. +.\" * +.\" * @(#)vfs_bio.c 8.6 (Berkeley) 1/11/94 +.\" */ +.\" +.\" +.\" ------------------------------------------------------------ +.Dd April 11, 2017 +.Dt BUFFERCACHE 9 +.Os +.Sh NAME +.Nm buffercache , +.Nm bread , +.Nm breadn , +.Nm bwrite , +.Nm bawrite , +.Nm bdwrite , +.Nm getblk , +.Nm geteblk , +.Nm incore , +.Nm allocbuf , +.Nm brelse +.Nd buffer cache interfaces +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In sys/buf.h +.Ft int +.Fn bread "struct vnode *vp" "daddr_t blkno" "int size" \ +"int flags" "buf_t **bpp" +.Ft int +.Fn breadn "struct vnode *vp" "daddr_t blkno" "int size" \ +"daddr_t rablks[]" "int rasizes[]" "int nrablks" \ +"int flags" "buf_t **bpp" +.Ft int +.Fn bwrite "buf_t *bp" +.Ft void +.Fn bawrite "buf_t *bp" +.Ft void +.Fn bdwrite "buf_t *bp" +.Ft buf_t * +.Fn getblk "struct vnode *vp" "daddr_t blkno" "int size" \ +"int slpflag" "int slptimeo" +.Ft buf_t * +.Fn geteblk "int size" +.Ft buf_t * +.Fn incore "struct vnode *vp" "daddr_t blkno" +.Ft void +.Fn allocbuf "buf_t *bp" "int size" "int preserve" +.Ft void +.Fn brelse "buf_t *bp" "int set" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +The +.Nm +interface is used by each filesystems to improve I/O performance using +in-core caches of filesystem blocks. +.Pp +The kernel memory used to cache a block is called a buffer and +described by a +.Em buf +structure. +In addition to describing a cached block, a +.Em buf +structure is also used to describe an I/O request as a part of +the disk driver interface. +.\" XXX buf_t, B_ flags, MP locks, etc +.\" ------------------------------------------------------------ +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn bread "vp" "blkno" "size" "flags" "bpp" +Read a block corresponding to +.Fa vp +and +.Fa blkno . +The buffer is returned via +.Fa bpp . +The units of +.Fa blkno +are specifically the units used by the +.Fn VOP_STRATEGY +routine for the +.Fa vp +vnode. +For device special files, +.Fa blkno +is in units of +.Dv DEV_BSIZE +and both +.Fa blkno +and +.Fa size +must be multiples of the underlying device's block size. +For other files, +.Fa blkno +is in units chosen by the file system containing +.Fa vp . +.Pp +If the buffer is not found (i.e. the block is not cached in memory), +.Fn bread +allocates a buffer with enough pages for +.Fa size +and reads the specified disk block into it. +.Pp +The buffer returned by +.Fn bread +is marked as busy. +(The +.Dv B_BUSY +flag is set.) +After manipulation of the buffer returned from +.Fn bread , +the caller should unbusy it so that another thread can get it. +If the buffer contents are modified and should be written back to disk, +it should be unbusied using one of variants of +.Fn bwrite . +Otherwise, it should be unbusied using +.Fn brelse . +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn breadn "vp" "blkno" "size" "rablks" "rasizes" "nrablks" "flags" \ +"bpp" +Get a buffer as +.Fn bread . +In addition, +.Fn breadn +will start read-ahead of blocks specified by +.Fa rablks , +.Fa rasizes , +.Fa nrablks . +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn bwrite "bp" +Write a block. +Start I/O for write using +.Fn VOP_STRATEGY . +Then, unless the +.Dv B_ASYNC +flag is set in +.Fa bp , +.Fn bwrite +waits for the I/O to complete. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn bawrite "bp" +Write a block asynchronously. +Set the +.Dv B_ASYNC +flag in +.Fa bp +and simply call +.Fn VOP_BWRITE , +which results in +.Fn bwrite +for most filesystems. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn bdwrite "bp" +Delayed write. +Unlike +.Fn bawrite , +.Fn bdwrite +won't start any I/O. +It only marks the buffer as dirty +.Pq Dv BO_DELWRI +and unbusy it. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn getblk "vp" "blkno" "size" "slpflag" "slptimeo" +Get a block of requested size +.Fa size +that is associated with a given vnode and block +offset, specified by +.Fa vp +and +.Fa blkno . +If it is found in the block cache, make it busy and return it. +Otherwise, return an empty block of the correct size. +It is up to the caller to ensure that the cached blocks +are of the correct size. +.Pp +If +.Fn getblk +needs to sleep, +.Fa slpflag +and +.Fa slptimeo +are used as arguments for +.Fn cv_timedwait . +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn geteblk "size" +Allocate an empty, disassociated block of a given size +.Fa size . +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn incore "vp" "blkno" +Determine if a block associated to a given vnode and block offset +is in the cache. +If it is there, return a pointer to it. +Note that +.Fn incore +doesn't busy the buffer unlike +.Fn getblk . +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn allocbuf "bp" "size" "preserve" +Expand or contract the actual memory allocated to a buffer. +If +.Fa preserve +is zero, the entire data in the buffer will be lost. +Otherwise, if the buffer shrinks, the truncated part of the data +is lost, so it is up to the caller to have written +it out +.Em first +if needed; this routine will not start a write. +If the buffer grows, it is the callers responsibility to fill out +the buffer's additional contents. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn brelse "bp" "set" +Unbusy a buffer and release it to the free lists. +.El +.\" ------------------------------------------------------------ +.Sh CODE REFERENCES +The buffer cache subsystem is implemented within the file +.Pa sys/kern/vfs_bio.c . +.Sh SEE ALSO +.Xr intro 9 , +.Xr bufferio 9 , +Xr vnode 9 +.Rs +.%A Maurice J. Bach +.%B "The Design of the UNIX Operating System" +.%I "Prentice Hall" +.%D 1986 +.Re +.Rs +.%A Marshall Kirk McKusick +.%A Keith Bostic +.%A Michael J. Karels +.%A John S. Quarterman +.%B "The Design and Implementation of the 4.4BSD Operating System" +.%I "Addison Wesley" +.%D 1996 +.Re diff --git a/static/netbsd/man9/bufferio.9 b/static/netbsd/man9/bufferio.9 new file mode 100644 index 00000000..67591629 --- /dev/null +++ b/static/netbsd/man9/bufferio.9 @@ -0,0 +1,442 @@ +.\" $NetBSD: bufferio.9,v 1.18 2019/09/12 21:08:35 sevan Exp $ +.\" +.\" Copyright (c) 2015 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Taylor R. Campbell. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 12, 2019 +.Dt BUFFERIO 9 +.Os +.Sh NAME +.Nm BUFFERIO , +.Nm biodone , +.Nm biowait , +.Nm getiobuf , +.Nm putiobuf , +.Nm nestiobuf_setup , +.Nm nestiobuf_done +.Nd block I/O buffer transfers +.Sh SYNOPSIS +.In sys/buf.h +.Ft void +.Fn biodone "buf_t *bp" +.Ft int +.Fn biowait "buf_t *bp" +.Ft buf_t * +.Fn getiobuf "struct vnode *vp" "bool waitok" +.Ft void +.Fn putiobuf "buf_t *bp" +.Ft void +.Fn nestiobuf_setup "buf_t *mbp" "buf_t *bp" "int offset" \ + "size_t size" +.Ft void +.Fn nestiobuf_done "buf_t *mbp" "int donebytes" "int error" +.Sh DESCRIPTION +The +.Nm +subsystem manages block I/O buffer transfers, described by the +.Vt "struct buf" +structure, which serves multiple purposes between users in +.Nm , +users in +.Xr buffercache 9 , +and users in block device drivers to execute transfers to physical +disks. +.Sh BLOCK DEVICE USERS +Users of +.Nm +wishing to submit a buffer for block I/O transfer must obtain a +.Vt "struct buf" , +e.g. via +.Fn getiobuf , +fill its parameters, and submit it to a block device with +.Xr bdev_strategy 9 , +usually via +.Xr VOP_STRATEGY 9 . +.Pp +The parameters to an I/O transfer described by +.Fa bp +are specified by the following +.Vt "struct buf" +fields: +.Bl -tag -width 6n -offset abcd +.It Fa bp Ns Li "->b_flags" +Flags specifying the type of transfer. +.Bl -tag -width 6n -compact +.It Dv B_READ +Transfer is read from device. +If not set, transfer is write to device. +.It Dv B_ASYNC +Asynchronous I/O. +Caller must not provide +.Fa bp Ns Li "->b_iodone" +and must not call +.Fn biowait bp . +.El +For legibility, callers should indicate writes by passing the +pseudo-flag +.Dv B_WRITE , +which is zero. +.It Fa bp Ns Li "->b_data" +Pointer to kernel virtual address of source/target for transfer. +.It Fa bp Ns Li "->b_bcount" +Nonnegative number of bytes requested for transfer. +.It Fa bp Ns Li "->b_blkno" +Block number at which to do transfer. +.It Fa bp Ns Li "->b_iodone" +I/O completion callback. +.Dv B_ASYNC +must not be set in +.Fa bp Ns Li "->b_flags" . +.El +.Pp +Additionally, if the I/O transfer is a write associated with a +.Xr vnode 9 +.Fa vp , +then before the user submits it to a block device, the user must +increment +.Fa vp Ns Li "->v_numoutput" . +The user must not acquire +.Fa vp Ns Ap s +vnode lock between incrementing +.Fa vp Ns Li "->v_numoutput" +and submitting +.Fa bp +to a block device \(em doing so will likely cause deadlock with the +syncer. +.Pp +Block I/O transfer completion may be notified by the +.Fa bp Ns Li "->b_iodone" +callback, by signalling +.Fn biowait +waiters, or not at all in the +.Dv B_ASYNC +case. +.Bl -dash +.It +If the user sets the +.Fa bp Ns Li "->b_iodone" +callback to a +.Pf non- Dv NULL +function pointer, it will be called in soft interrupt context when the +I/O transfer is complete. +The user +.Em may not +call +.Fn biowait bp +in this case. +.It +If +.Dv B_ASYNC +is set, then the I/O transfer is asynchronous and the user will not be +notified when it is completed. +The user +.Em may not +call +.Fn biowait bp +in this case. +.It +Otherwise, if +.Fa bp Ns Li "->b_iodone" +is +.Dv NULL +and +.Dv B_ASYNC +is not specified, the user may wait for the I/O transfer to complete +with +.Fn biowait bp . +.El +.Pp +Once an I/O transfer has completed, its +.Vt "struct buf" +may be reused, but the user must first clear the +.Dv BO_DONE +flag of +.Fa bp Ns Li "->b_oflags" +before reusing it. +.Sh NESTED I/O TRANSFERS +Sometimes an I/O transfer from a single buffer in memory cannot go to a +single location on a block device: it must be split up into smaller +transfers for each segment of the memory buffer. +.Pp +After initializing the +.Li b_flags , +.Li b_data , +and +.Li b_bcount +parameters of an I/O transfer for the buffer, called the +.Em master +buffer, the user can issue smaller transfers for segments of the buffer +using +.Fn nestiobuf_setup . +When nested I/O transfers complete, in any order, they debit from the +amount of work left to be done in the master buffer. +If any segments of the buffer were skipped, the user can report this +with +.Fn nestiobuf_done +to debit the skipped part of the work. +.Pp +The master buffer's I/O transfer is completed when all nested buffers' +I/O transfers are completed, and if +.Fn nestiobuf_done +is called in the case of skipped segments. +.Pp +For writes associated with a vnode +.Fa vp , +.Fn nestiobuf_setup +accounts for +.Fa vp Ns Li "->v_numoutput" , +so the caller is not allowed to acquire +.Fa vp Ns Ap s +vnode lock before submitting the nested I/O transfer to a block +device. +However, the caller is responsible for accounting the master buffer in +.Fa vp Ns Li "->v_numoutput" . +This must be done very carefully because after incrementing +.Fa vp Ns Li "->v_numoutput" , +the caller is not allowed to acquire +.Fa vp Ns Ap s +vnode lock before either calling +.Fn nestiobuf_done +or submitting the last nested I/O transfer to a block device. +.Pp +For example: +.Bd -literal -offset abcd +struct buf *mbp, *bp; +size_t skipped = 0; +unsigned i; +int error = 0; + +mbp = getiobuf(vp, true); +mbp->b_data = data; +mbp->b_resid = mbp->b_bcount = datalen; +mbp->b_flags = B_WRITE; + +KASSERT(0 < nsegs); +KASSERT(datalen == nsegs*segsz); +for (i = 0; i < nsegs; i++) { + struct vnode *devvp; + daddr_t blkno; + + vn_lock(vp, LK_EXCLUSIVE | LK_RETRY); + error = VOP_BMAP(vp, i*segsz, &devvp, &blkno, NULL); + VOP_UNLOCK(vp); + if (error == 0 && blkno == -1) + error = EIO; + if (error) { + /* Give up early, don't try to handle holes. */ + skipped += datalen - i*segsz; + break; + } + + bp = getiobuf(vp, true); + nestiobuf_setup(bp, mbp, i*segsz, segsz); + bp->b_blkno = blkno; + if (i == nsegs - 1) /* Last segment. */ + break; + VOP_STRATEGY(devvp, bp); +} + +/* + * Account v_numoutput for master write. + * (Must not vn_lock before last VOP_STRATEGY!) + */ +mutex_enter(&vp->v_interlock); +vp->v_numoutput++; +mutex_exit(&vp->v_interlock); + +if (skipped) + nestiobuf_done(mbp, skipped, error); +else + VOP_STRATEGY(devvp, bp); +.Ed +.Sh BLOCK DEVICE DRIVERS +Block device drivers implement a +.Sq strategy +method, in the +.Li d_strategy +member of +.Li struct bdevsw +.Pq Xr driver 9 , +to queue a buffer for disk I/O. +The inputs to the strategy method are: +.Bl -tag -width 6n -offset abcd +.It Fa bp Ns Li "->b_flags" +Flags specifying the type of transfer. +.Bl -tag -width 6n -compact +.It Dv B_READ +Transfer is read from device. +If not set, transfer is write to device. +.El +.It Fa bp Ns Li "->b_data" +Pointer to kernel virtual address of source/target for transfer. +.It Fa bp Ns Li "->b_bcount" +Nonnegative number of bytes requested for transfer. +.It Fa bp Ns Li "->b_blkno" +Block number at which to do transfer, relative to partition start. +.El +.Pp +If the strategy method uses +.Xr bufq 9 , +it must additionally initialize the following fields before queueing +.Fa bp +with +.Xr bufq_put 9 : +.Bl -tag -width 6n -offset abcd +.It Fa bp Ns Li "->b_rawblkno" +Block number relative to volume start. +.El +.Pp +When the I/O transfer is complete, whether it succeeded or failed, the +strategy method must: +.Bl -dash +.It +Set +.Fa bp Ns Li "->b_error" +to zero on success, or to an +.Xr errno 2 +error code on failure. +.It +Set +.Fa bp Ns Li "->b_resid" +to the number of bytes remaining to transfer, whether on success or +on failure. +If no bytes were transferred, this must be set to +.Fa bp Ns Li "->b_bcount" . +.It +Call +.Fn biodone bp . +.El +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn biodone bp +Notify that the I/O transfer described by +.Fa bp +has completed. +.Pp +To be called by a block device driver. +Caller must first set +.Fa bp Ns Li "->b_error" +to an error code and +.Fa bp Ns Li "->b_resid" +to the number of bytes remaining to transfer. +.It Fn biowait bp +Wait for the synchronous I/O transfer described by +.Fa bp +to complete. +Returns the value of +.Fa bp Ns Li "->b_error" . +.Pp +To be called by a user requesting the I/O transfer. +.Pp +May not be called if +.Fa bp +has a callback or is asynchronous \(em that is, if +.Fa bp Ns Li "->b_iodone" +is set, or if +.Dv B_ASYNC +is set in +.Fa bp Ns Li "->b_flags" . +.It Fn getiobuf vp waitok +Allocate a +.Vt "struct buf" +for an I/O transfer. +If +.Fa vp +is +.Pf non- Dv NULL , +the transfer is associated with it. +If +.Fa waitok +is false, +returns +.Dv NULL +if none can be allocated immediately. +.Pp +The resulting +.Vt "struct buf" +pointer must eventually be passed to +.Fn putiobuf +to release it. +Do +.Em not +use +.Xr brelse 9 . +.Pp +The buffer may not be used for an asynchronous I/O transfer, because +there is no way to know when it is completed and may be safely passed +to +.Fn putiobuf . +Asynchronous I/O transfers are allowed only for buffers in the +.Xr buffercache 9 . +.Pp +May sleep if +.Fa waitok +is true. +.It Fn putiobuf bp +Free +.Fa bp , +which must have been allocated by +.Fn getiobuf . +Either +.Fa bp +must never have been submitted to a block device, or the I/O transfer +must have completed. +.El +.Sh CODE REFERENCES +The +.Nm +subsystem is implemented in +.Pa sys/kern/vfs_bio.c . +.Sh SEE ALSO +.Xr buffercache 9 , +.Xr bufq 9 +.Sh BUGS +The +.Nm +abstraction provides no way to cancel an I/O transfer once it has been +submitted to a block device. +.Pp +The +.Nm +abstraction provides no way to do I/O transfers with non-kernel pages, +e.g. directly to buffers in userland without copying into the kernel +first. +.Pp +The +.Vt "struct buf" +type is all mixed up with the +.Xr buffercache 9 . +.Pp +The +.Nm +abstraction is a totally idiotic API design. +.Pp +The +.Li v_numoutput +accounting required of +.Nm +callers is asinine. diff --git a/static/netbsd/man9/bufq.9 b/static/netbsd/man9/bufq.9 new file mode 100644 index 00000000..80f62e7f --- /dev/null +++ b/static/netbsd/man9/bufq.9 @@ -0,0 +1,238 @@ +.\" $NetBSD: bufq.9,v 1.22 2016/11/18 08:29:43 wiz Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Juergen Hannken-Illjes. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 17, 2016 +.Dt BUFQ 9 +.Os +.Sh NAME +.Nm bufq , +.Nm bufq_init , +.Nm bufq_register , +.Nm bufq_unregister , +.Nm bufq_state , +.Nm bufq_alloc , +.Nm bufq_drain , +.Nm bufq_free , +.Nm bufq_getstrategyname , +.Nm bufq_move , +.Nm bufq_put , +.Nm bufq_get , +.Nm bufq_peek , +.Nm bufq_cancel +.Nd device buffer queues +.Sh SYNOPSIS +.In sys/bufq.h +.Ft void +.Fn bufq_init "void" +.Ft int +.Fn bufq_register "struct bufq_strat *" +.Ft int +.Fn bufq_unregister "struct bufq_strat *" +.Ft int +.Fn bufq_alloc "struct bufq_state **bufq" "const char *strategy" "int flags" +.Ft void +.Fn bufq_drain "struct bufq_state *bufq" +.Ft void +.Fn bufq_free "struct bufq_state *bufq" +.Ft "const char *" +.Fn bufq_getstrategyname "struct bufq_state *bufq" +.Ft void +.Fn bufq_move "struct bufq_state *dst" "struct bufq_state *src" +.Ft void +.Fn bufq_put "struct bufq_state *bufq" "struct buf *bp" +.Ft "struct buf *" +.Fn bufq_get "struct bufq_state *bufq" +.Ft "struct buf *" +.Fn bufq_peek "struct bufq_state *bufq" +.Ft "struct buf *" +.Fn bufq_cancel "struct bufq_state *bufq" "struct buf *bp" +.Sh DESCRIPTION +The +.Nm +subsystem is a set of operations for the management of device buffer queues. +Various strategies for ordering of entries in the buffer queues can be +provided by loadable kernel modules (see +.Xr module 9 ) . +By default, the +.Dv BUFQ_FCFS +and +.Dv BUFQ_DISKSORT +strategies are included in +the kernel; see +.Xr options 4 +for more details. +.Pp +The primary data type for using the operations is the +.Em bufq_state +structure, which is opaque for users. +Each buffer queue strategy module is defined by the +.Em bufq_strat +structure, which is also opaque for users. +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn bufq_init "void" +Initialize the +.Nm +subsystem. +This routine must be called before any other +.Nm +routines. +.It Fn bufq_register "bs" +Registers the specified buffer queue strategy module so it can be used +in subsequent operations. +.It Fn bufq_unregister "bs" +Unregisters the specified buffer queue strategy module. +The routine will fail if any buffer queues for the specified strategy +are in use (see +.Fn bufq_alloc +below). +.It Fn bufq_alloc "bufq" "strategy" "flags" +Allocate and initialize a +.Em bufq_state +descriptor. +.Pp +The argument +.Fa strategy +specifies a buffer queue strategy to be used for this buffer queue. +The following special values can be used: +.Pp +.Bl -tag -offset indent -width BUFQ_DISK_DEFAULT_STRAT -compact +.It Dv BUFQ_STRAT_ANY +Let +.Fn bufq_alloc +select a strategy. +.It Dv BUFQ_DISK_DEFAULT_STRAT +Let +.Fn bufq_alloc +select a strategy, assuming it will be used for a normal disk device. +.El +.Pp +Valid bits for the +.Fa flags +are: +.Pp +.Bl -tag -offset indent -width BUFQ_SORT_RAWBLOCK -compact +.It Dv BUFQ_SORT_RAWBLOCK +sort by +.Em b_rawblkno +.It Dv BUFQ_SORT_CYLINDER +sort by +.Em b_cylinder +and then by +.Em b_rawblkno +.It Dv BUFQ_EXACT +Fail if a strategy specified by +.Fa strategy +is not available. +In that case, +.Fa bufq_alloc +returns +.Dv ENOENT . +If this flag is not specified, +.Fn bufq_alloc +will silently use one of available strategies. +.El +.Pp +If a specific strategy is specified but not currently available, the +.Nm bufq +subsystem will attempt to auto-load the corresponding kernel module using +.Xr module_autoload 9 . +.It Fn bufq_drain "bufq" +Drain a +.Em bufq_state +descriptor. +.It Fn bufq_free "bufq" +Destroy a +.Em bufq_state +descriptor. +.It Fn bufq_getstrategyname "bufq" +Get a strategy identifier of a buffer queue, the +string returned will be NUL-terminated and it always +will be a valid strategy name. +.It Fn bufq_move "dst" "src" +Move all requests from the buffer queue +.Fa src +to the buffer queue +.Fa dst . +.It Fn bufq_put "bufq" "bp" +Put the buf +.Fa bp +in the queue. +.It Fn bufq_get "bufq" +Get the next buf from the queue and remove it from the queue. +Returns +.Dv NULL +if the queue is empty. +.It Fn bufq_peek "bufq" +Get the next buf from the queue without removal. +The next buf will remain the same until +.Fn bufq_get , +.Fn bufq_put , +or +.Fn bufq_drain +is called. +Returns +.Dv NULL +if the queue is empty. +.It Fn bufq_cancel "bufq" "bp" +Cancel the buf +.Fa bp +issued earlier on the queue. +Returns +.Dv NULL +if the element can not be found on the queue or +.Fa bp +if it has been found and removed. +This operation can be computationally expensive if there are +a lot of buffers queued. +.El +.Sh CODE REFERENCES +The actual code implementing the device buffer queues can be found +in the file +.Pa sys/kern/subr_bufq.c . +The code implementing specific buffer queue strategies can be found in +the files +.Pa sys/kern/bufq_*.c . +.Sh NOTES +A list of currently available buffer queue strategies is available via +the +.Dq kern.bufq.strategies +.Xr sysctl 7 +variables. +.Sh HISTORY +The +.Nm +subsystem appeared in +.Nx 2.0 . +.Sh AUTHORS +The +.Nm +subsystem was written by +.An J\(:urgen Hannken-Illjes +.Aq hannken@NetBSD.org . diff --git a/static/netbsd/man9/bus_dma.9 b/static/netbsd/man9/bus_dma.9 new file mode 100644 index 00000000..e0b963d5 --- /dev/null +++ b/static/netbsd/man9/bus_dma.9 @@ -0,0 +1,995 @@ +.\" $NetBSD: bus_dma.9,v 1.82 2025/01/04 17:18:08 riastradh Exp $ +.\" +.\" Copyright (c) 1996, 1997, 1998, 2001, 2005, 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility, +.\" NASA Ames Research Center. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 29, 2024 +.Dt BUS_DMA 9 +.Os +.Sh NAME +.Nm bus_dma , +.Nm bus_dmamap_create , +.Nm bus_dmamap_destroy , +.Nm bus_dmamap_load , +.Nm bus_dmamap_load_mbuf , +.Nm bus_dmamap_load_uio , +.Nm bus_dmamap_load_raw , +.Nm bus_dmamap_unload , +.Nm bus_dmamap_sync , +.Nm bus_dmamem_alloc , +.Nm bus_dmamem_free , +.Nm bus_dmamem_map , +.Nm bus_dmamem_unmap , +.Nm bus_dmamem_mmap , +.Nm bus_dmatag_subregion , +.Nm bus_dmatag_destroy +.Nd Bus and Machine Independent DMA Mapping Interface +. +.Sh SYNOPSIS +. +.In sys/bus.h +. +.Ft int +.Fo bus_dmamap_create +.Fa "bus_dma_tag_t tag" +.Fa "bus_size_t size" +.Fa "int nsegments" +.Fa "bus_size_t maxsegsz" +.Fa "bus_size_t boundary" +.Fa "int flags" +.Fa "bus_dmamap_t *dmamp" +.Fc +. +.Ft void +.Fo bus_dmamap_destroy +.Fa "bus_dma_tag_t tag" +.Fa "bus_dmamap_t dmam" +.Fc +. +.Ft int +.Fo bus_dmamap_load +.Fa "bus_dma_tag_t tag" +.Fa "bus_dmamap_t dmam" +.Fa "void *buf" +.Fa "bus_size_t buflen" +.Fa "struct proc *p" +.Fa "int flags" +.Fc +. +.Ft int +.Fo bus_dmamap_load_mbuf +.Fa "bus_dma_tag_t tag" +.Fa "bus_dmamap_t dmam" +.Fa "struct mbuf *chain" +.Fa "int flags" +.Fc +. +.Ft int +.Fo bus_dmamap_load_uio +.Fa "bus_dma_tag_t tag" +.Fa "bus_dmamap_t dmam" +.Fa "struct uio *uio" +.Fa "int flags" +.Fc +. +.Ft int +.Fo bus_dmamap_load_raw +.Fa "bus_dma_tag_t tag" +.Fa "bus_dmamap_t dmam" +.Fa "bus_dma_segment_t *segs" +.Fa "int nsegs" +.Fa "bus_size_t size" +.Fa "int flags" +.Fc +. +.Ft void +.Fo bus_dmamap_unload +.Fa "bus_dma_tag_t tag" +.Fa "bus_dmamap_t dmam" +.Fc +. +.Ft void +.Fo bus_dmamap_sync +.Fa "bus_dma_tag_t tag" +.Fa "bus_dmamap_t dmam" +.Fa "bus_addr_t offset" +.Fa "bus_size_t len" +.Fa "int ops" +.Fc +. +.Ft int +.Fo bus_dmamem_alloc +.Fa "bus_dma_tag_t tag" +.Fa "bus_size_t size" +.Fa "bus_size_t alignment" +.Fa "bus_size_t boundary" +.Fa "bus_dma_segment_t *segs" +.Fa "int nsegs" +.Fa "int *rsegs" +.Fa "int flags" +.Fc +. +.Ft void +.Fo bus_dmamem_free +.Fa "bus_dma_tag_t tag" +.Fa "bus_dma_segment_t *segs" +.Fa "int nsegs" +.Fc +. +.Ft int +.Fo bus_dmamem_map +.Fa "bus_dma_tag_t tag" +.Fa "bus_dma_segment_t *segs" +.Fa "int nsegs" +.Fa "size_t size" +.Fa "void **kvap" +.Fa "int flags" +.Fc +. +.Ft void +.Fo bus_dmamem_unmap +.Fa "bus_dma_tag_t tag" +.Fa "void *kva" +.Fa "size_t size" +.Fc +. +.Ft paddr_t +.Fo bus_dmamem_mmap +.Fa "bus_dma_tag_t tag" +.Fa "bus_dma_segment_t *segs" +.Fa "int nsegs" +.Fa "off_t off" +.Fa "int prot" +.Fa "int flags" +.Fc +. +.Ft int +.Fo bus_dmatag_subregion +.Fa "bus_dma_tag_t tag" +.Fa "bus_addr_t min_addr" +.Fa "bus_addr_t max_addr" +.Fa "bus_dma_tag_t *newtag" +.Fa "int flags" +.Fc +. +.Ft void +.Fo bus_dmatag_destroy +.Fa "bus_dma_tag_t tag" +.Fc +. +.Sh DESCRIPTION +Provide a bus- and machine-independent +.Dq Tn DMA No mapping interface . +. +.Ss Implementation Notes +All data types and constants will be defined +by the port-specific header +.In machine/bus_defs.h . +All functions will be defined +by the port-specific header +.In machine/bus_funcs.h . +Note that this document +assumes the existence of types already defined by the current +.Xr bus_space 9 +interface. +.Pp +Unless otherwise noted, all function calls in this interface may be +defined as +.Xr cpp 1 +macros. +.Ss Data Types +Individual implementations may name these structures whatever they +wish, providing that the external representations are: +.Bl -tag -width Vt +.It Vt bus_dma_tag_t +A machine-dependent opaque type describing the implementation of +DMA for a given bus. +.It Vt bus_dma_segment_t +A structure with at least the following members: +.Bd -literal -offset indent +bus_addr_t ds_addr; +bus_size_t ds_len; +.Ed +.Pp +The structure may have machine-dependent members and arbitrary layout. +The values in +.Fa ds_addr +and +.Fa ds_len +are suitable for programming into +DMA controller address and length registers. +.It Vt bus_dmamap_t +A pointer to a structure with at least the following members: +.Bd -literal -offset indent +bus_size_t dm_maxsegsz; +bus_size_t dm_mapsize; +int dm_nsegs; +bus_dma_segment_t *dm_segs; +.Ed +.Pp +The structure may have machine-dependent members and arbitrary layout. +The +.Fa dm_maxsegsz +member indicates the maximum number of bytes that may be transferred by +any given DMA segment. +The +.Fa dm_mapsize +member indicates the size of the mapping. +A value of 0 indicates the mapping is invalid. +The +.Fa dm_segs +member may be an array of segments or a pointer to an +array of segments. +The +.Fa dm_nsegs +member indicates the number of segments in +.Fa dm_segs . +.El +. +.Ss Functions +.Bl -tag -width Ds \" Fn +.It Fn bus_dmamap_create "tag" "size" "nsegments" "maxsegsz" "boundary" "flags" "dmamp" +Allocates a DMA handle and initializes it according to the parameters +provided. +.Bl -tag -width Ds \" Fa +.It Fa tag +This is the +.Vt bus_dma_tag_t +passed down from the parent driver via +.Fa <bus>_attach_args . +.It Fa size +This is the maximum DMA transfer that can be mapped by the handle. +.It Fa nsegments +Number of segments the device can support in a single DMA transaction. +This may be the number of scatter-gather descriptors supported by the +device. +.It Fa maxsegsz +The maximum number of bytes that may be transferred by any given DMA +segment and will be assigned to the +.Fa dm_maxsegsz +member. +.It Fa boundary +Some DMA controllers are not able to transfer data that crosses a +particular boundary. +This argument allows this boundary to be specified. +The boundary lines begin at 0, and occur every +.Fa boundary +bytes. +Mappings may begin on a boundary line but may not end on or +cross a boundary line. +If no boundary condition needs to be observed, a +.Fa boundary +argument of 0 should be used. +.It Fa flags +.Bl -tag -width Ds \" Dv +.It Dv BUS_DMA_WAITOK +It is safe to wait (sleep) for resources during this call. +.It Dv BUS_DMA_NOWAIT +It is not safe to wait (sleep) for resources during this call. +.It Dv BUS_DMA_ALLOCNOW +Perform any resource allocation this handle may need now. +If this is not specified, the allocation may be deferred to +.Fn bus_dmamap_load . +If this flag is specified, +.Fn bus_dmamap_load +will not block on resource +allocation. +.It Dv BUS_DMA_BUS[1-4] +These flags are placeholders, and may be used by busses to provide +bus-dependent functionality. +.El +.It Fa dmamp +This is a pointer to a +.Vt bus_dmamap_t . +A DMA map will be allocated and pointed to by +.Fa dmamp +upon successful completion of this routine. +.Fa dmamp +is undefined if this routine fails. +.El +.Pp +Behavior is not defined if invalid arguments are passed to +.Fn bus_dmamap_create . +.Pp +Returns 0 on success, or an error code to indicate mode of failure. +.It Fn bus_dmamap_destroy "tag" "dmam" +Frees all resources associated with a given DMA handle. +.Bl -tag -width Ds \" Fa +.It Fa tag +This is the +.Vt bus_dma_tag_t +passed down from the parent driver via +.Fa <bus>_attach_args . +.It Fa dmam +The DMA handle to destroy. +.El +.Pp +In the event that the DMA handle contains a valid mapping, +the mapping will be unloaded via the same mechanism used by +.Fn bus_dmamap_unload . +.Pp +Behavior is not defined if invalid arguments are passed to +.Fn bus_dmamap_destroy . +.Pp +If given valid arguments, +.Fn bus_dmamap_destroy +always succeeds. +.It Fn bus_dmamap_load "tag" "dmam" "buf" "buflen" "p" "flags" +Loads a DMA handle with mappings for a DMA transfer. +It assumes that all pages involved in a DMA transfer are wired. +.Bl -tag -width Ds \" Fa +.It Fa tag +This is the +.Vt bus_dma_tag_t +passed down from the parent driver via +.Fa <bus>_attach_args . +.It Fa dmam +The DMA handle with which to map the transfer. +.It Fa buf +The buffer to be used for the DMA transfer. +.It Fa buflen +The size of the buffer. +.It Fa p +Used to indicate the address space in which the buffer is located. +If +.Dv NULL , +the buffer is assumed to be in kernel space. +Otherwise, the buffer is assumed to be in proc +.Fa p Ap s +address space. +.It Fa flags +.Bl -tag -width Ds \" Dv +.It Dv BUS_DMA_WAITOK +It is safe to wait (sleep) for resources during this call. +.It Dv BUS_DMA_NOWAIT +It is not safe to wait (sleep) for resources during this call. +.It Dv BUS_DMA_STREAMING +By default, the +.Nm +API assumes that there is coherency between memory and the device +performing the DMA transaction. +Some platforms, however, have special hardware, such as an +.Dq I/O cache , +which may improve performance +of some types of DMA transactions, but which break the assumption +that there is coherency between memory and the device performing +the DMA transaction. +This flag allows the use of this special hardware, provided that +the device is doing sequential, unidirectional transfers which +conform to certain alignment and size constraints defined by the +platform. +If the platform does not support the feature, or if the buffer being +loaded into the DMA map does not conform to the constraints required +for use of the feature, then this flag will be silently ignored. +Also refer to the use of this flag with the +.Fn bus_dmamem_alloc +function. +.It Dv BUS_DMA_READ +This is a hint to the machine-dependent back-end that indicates the +mapping will be used only for a +.Em device No \(-> Em memory +transaction. +The back-end may perform optimizations based on this information. +.It Dv BUS_DMA_WRITE +This is a hint to the machine-dependent back-end that indicates the +mapping will be used only for a +.Em memory No \(-> Em device +transaction. +The back-end may perform optimizations based on this information. +.It Dv BUS_DMA_BUS[1-4] +These flags are placeholders, and may be used by busses to +provide bus-dependent functionality. +.El +.El +.Pp +As noted above, if a DMA handle is created with +.Dv BUS_DMA_ALLOCNOW , +.Fn bus_dmamap_load +will never block. +.Pp +If a call to +.Fn bus_dmamap_load +fails, the mapping in +the DMA handle will be invalid. +It is the responsibility of the caller to clean up any inconsistent +device state resulting from incomplete iteration through the uio. +.Pp +Behavior is not defined if invalid arguments are passed to +.Fn bus_dmamap_load . +.Pp +Returns 0 on success, or an error code to indicate mode of failure. +Possible error codes include the following: +.Pp +.Bl -tag -width Er +.It Er EFBIG +Too many segments. +.It Er EINVAL +.Fa buflen +is too large for the DMA map. +.It Er ENOMEM +Could not allocate memory for, e.g., a bounce buffer. +.El +.It Fn bus_dmamap_load_mbuf "tag" "dmam" "chain" "flags" +This is a variation of +.Fn bus_dmamap_load +which maps mbuf chains +for DMA transfers. +Mbuf chains are assumed to be in kernel virtual address space. +.It Fn bus_dmamap_load_uio "tag" "dmam" "uio" "flags" +This is a variation of +.Fn bus_dmamap_load +which maps buffers pointed to by +.Fa uio +for DMA transfers. +Determination if the buffers are in user or kernel virtual address space +is done internally, according to +.Fa uio\^ Ns Li -> Ns Fa uio_vmspace . +See +.Xr uiomove 9 +for details of the +.Dv uio +structure. +.It Fn bus_dmamap_load_raw "tag" "dmam" "segs" "nsegs" "size" "flags" +This is a variation of +.Fn bus_dmamap_load +which maps buffers +allocated by +.Fn bus_dmamem_alloc +(see below). +The +.Fa segs +argument is an array of bus_dma_segment_t's filled in +by +.Fn bus_dmamem_alloc . +The +.Fa nsegs +argument is the number of segments in the array. +The +.Fa size +argument is the size of the DMA transfer. +.It Fn bus_dmamap_unload "tag" "dmam" +Deletes the mappings for a given DMA handle. +.Bl -tag -width Ds \" Fa +.It Fa tag +This is the +.Vt bus_dma_tag_t +passed down from the parent driver via +.Fa <bus>_attach_args . +.It Fa dmam +The DMA handle containing the mappings which are to be deleted. +.El +.Pp +If the DMA handle was created with +.Dv BUS_DMA_ALLOCNOW , +.Fn bus_dmamap_unload +will not free the corresponding +resources which were allocated by +.Fn bus_dmamap_create . +This is to ensure that +.Fn bus_dmamap_load +will never block +on resources if the handle was created with +.Dv BUS_DMA_ALLOCNOW . +.Pp +.Fn bus_dmamap_unload +will not perform any implicit synchronization of DMA buffers. +This must be done explicitly by +.Fn bus_dmamap_sync . +.Pp +.Fn bus_dmamap_unload +will restore the +.Fa dm_maxsegsz +member to its initial value assigned by +.Fn bus_dmamap_create . +.Pp +Behavior is not defined if invalid arguments are passed to +.Fn bus_dmamap_unload . +.Pp +If given valid arguments, +.Fn bus_dmamap_unload +always succeeds. +.It Fn bus_dmamap_sync "tag" "dmam" "offset" "len" "ops" +Performs pre- and post-DMA operation cache and/or buffer synchronization. +.Bl -tag -width Ds \" Fa +.It Fa tag +This is the +.Vt bus_dma_tag_t +passed down from the parent driver via +.Fa <bus>_attach_args . +.It Fa dmam +The DMA mapping to be synchronized. +.It Fa offset +The offset into the DMA mapping to synchronize. +.It Fa len +The length of the mapping from +.Fa offset +to synchronize. +.It Fa ops +One or more synchronization operations to perform. +The following DMA synchronization operations are defined: +.Bl -tag -width Ds \" Dv +.It Dv BUS_DMASYNC_PREREAD +Perform any synchronization required prior to an update of host memory by the +device. +.It Dv BUS_DMASYNC_POSTREAD +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 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 synchronization required after device access to host memory. +.El +.Pp +where each operation may involve cache flush/invalidation, bounce buffer +copying, and/or memory barriers. +.Pp +More than one operation may be performed in a given synchronization call. +Mixing of +.Dv PRE +and +.Dv POST +operations is not allowed, and behavior is undefined if this is attempted. +.Pp +Synchronization operations are expressed from the perspective of +the host RAM, i.e., a +.Em device No \(-> Em memory +operation is a +.Dv READ , +and a +.Em memory No \(-> Em device +operation is a +.Dv WRITE . +.El +.Pp +.Fn bus_dmamap_sync +may consult state kept within the DMA map to determine if the memory +is mapped in a DMA coherent fashion. +If so, +.Fn bus_dmamap_sync +may elect to skip certain expensive operations, such as flushing +of the data cache. +See +.Fn bus_dmamem_map +for more information on this subject. +.Pp +On platforms which implement a weak memory access ordering model, +.Fn bus_dmamap_sync +will always cause the appropriate memory barriers to be issued. +.Pp +This function exists to ensure that the host and the device have +a consistent view of a range of DMA memory, before and after +a DMA operation. +.Pp +An example of using +.Fn bus_dmamap_sync , +involving multiple read-write use of a single mapping +might look like this: +.Bd -literal +bus_dmamap_load(...); + +while (not done) { + /* invalidate soon-to-be-stale cache blocks */ + bus_dmamap_sync(..., BUS_DMASYNC_PREREAD); + + [ do read DMA ] + + /* copy from bounce */ + bus_dmamap_sync(..., BUS_DMASYNC_POSTREAD); + + /* read data now in driver-provided buffer */ + + [ computation ] + + /* data to be written now in driver-provided buffer */ + + /* flush write buffers and writeback, copy to bounce */ + bus_dmamap_sync(..., BUS_DMASYNC_PREWRITE); + + [ do write DMA ] + + /* probably a no-op, but provided for consistency */ + bus_dmamap_sync(..., BUS_DMASYNC_POSTWRITE); +} + +bus_dmamap_unload(...); +.Ed +.Pp +This function +.Em must +be called to synchronize DMA buffers before and after a DMA operation. +Other +.Nm +functions can +.Em not +be relied on to do this synchronization implicitly. +If DMA read and write operations are not preceded and followed by the +appropriate synchronization operations, behavior is undefined. +.Pp +Behavior is not defined if invalid arguments are passed to +.Fn bus_dmamap_sync . +.Pp +If given valid arguments, +.Fn bus_dmamap_sync +always succeeds. +.It Fn bus_dmamem_alloc "tag" "size" "alignment" "boundary" "segs" "nsegs" "rsegs" "flags" +Allocates memory that is +.Dq DMA safe +for the bus corresponding to the +given tag. +.Pp +The mapping of this memory is machine-dependent +.Pq or Dq opaque ; +machine-independent code must not assume that the +addresses returned are valid in kernel virtual address space, or that +the addresses returned are system physical addresses. +The address value returned as part of +.Fa segs +can thus not be used to program DMA controller address registers. +Only the values in the +.Fa dm_segs +array of a successfully loaded DMA map +.Pq using Fn bus_dmamap_load +can be used for this purpose. +.Pp +Allocations will always be rounded to the hardware page size. +Callers may wish to take advantage of this, and cluster allocation of small +data structures. +.Bl -tag -width Ds \" Fa +.It Fa tag +This is the +.Vt bus_dma_tag_t +passed down from the parent driver via +.Fa <bus>_attach_args . +.It Fa size +The amount of memory to allocate. +.It Fa alignment +Each segment in the allocated memory will be aligned to this value. +If the alignment is less than a hardware page size, it will be rounded up +to the hardware page size. +This value must be a power of two. +.It Fa boundary +Each segment in the allocated memory must not cross this boundary +(relative to zero). +This value must be a power of two. +A boundary value less than the size of the allocation is invalid. +If no boundary condition needs to be observed, a +.Fa boundary +argument of 0 should be used. +.It Fa segs +An array of bus_dma_segment_t's, filled in as memory is allocated, +representing the opaque addresses of the memory chunks. +.It Fa nsegs +Specifies the number of segments in +.Fa segs , +and this is the maximum number +of segments that the allocated memory may contain. +.It Fa rsegs +Used to return the actual number of segments the memory contains. +.It Fa flags +.Bl -tag -width Ds \" Dv +.It Dv BUS_DMA_WAITOK +It is safe to wait (sleep) for resources during this call. +.It Dv BUS_DMA_NOWAIT +It is not safe to wait (sleep) for resources during this call. +.It Dv BUS_DMA_STREAMING +Adjusts, if necessary, the size, alignment, and boundary constraints +to conform to the platform-dependent requirements for the use of the +.Dv BUS_DMA_STREAMING +flag with the +.Fn bus_dmamap_load +function. +If the platform does not support the +.Dv BUS_DMA_STREAMING +feature, or if the size, alignment, and boundary constraints +would already satisfy the platform's requirements, this flag +is silently ignored. +The +.Dv BUS_DMA_STREAMING +flag will never relax the constraints specified in the call. +.It Dv BUS_DMA_BUS[1-4] +These flags are placeholders, and may be used by busses to provide +bus-dependent functionality. +.El +.El +.Pp +All pages allocated by +.Fn bus_dmamem_alloc +will be wired down +until they are freed by +.Fn bus_dmamem_free . +.Pp +Behavior is undefined if invalid arguments are passed to +.Fn bus_dmamem_alloc . +.Pp +Returns 0 on success, or an error code indicating mode of failure. +.It Fn bus_dmamem_free "tag" "segs" "nsegs" +Frees memory previously allocated by +.Fn bus_dmamem_alloc . +Any mappings +will be invalidated. +.Bl -tag -width Ds \" Fa +.It Fa tag +This is the +.Vt bus_dma_tag_t +passed down from the parent driver via +.Fa <bus>_attach_args . +.It Fa segs +The array of bus_dma_segment_t's filled in by +.Fn bus_dmamem_alloc . +.It Fa nsegs +The number of segments in +.Fa segs . +.El +.Pp +Behavior is undefined if invalid arguments are passed to +.Fn bus_dmamem_free . +.Pp +If given valid arguments, +.Fn bus_dmamem_free +always succeeds. +.It Fn bus_dmamem_map "tag" "segs" "nsegs" "size" "kvap" "flags" +Maps memory allocated with +.Fn bus_dmamem_alloc +into kernel virtual address space. +.Bl -tag -width Ds \" Fa +.It Fa tag +This is the +.Vt bus_dma_tag_t +passed down from the parent driver via +.Fa <bus>_attach_args . +.It Fa segs +The array of bus_dma_segment_t's filled in by +.Fn bus_dmamem_alloc , +representing the memory regions to map. +.It Fa nsegs +The number of segments in +.Fa segs . +.It Fa size +The size of the mapping. +.It Fa kvap +Filled in to specify the kernel virtual address where the memory is mapped. +.It Fa flags +.Bl -tag -width Ds \" Dv +.It Dv BUS_DMA_WAITOK +It is safe to wait (sleep) for resources during this call. +.It Dv BUS_DMA_NOWAIT +It is not safe to wait (sleep) for resources during this call. +.It Dv BUS_DMA_BUS[1-4] +These flags are placeholders, and may be used by busses to provide +bus-dependent functionality. +.It Dv BUS_DMA_COHERENT +This flag is a +.Em hint +to machine-dependent code. +If possible, map the memory in such a way as it will be DMA coherent. +This may include mapping the pages into uncached address space or +setting the cache-inhibit bits in page table entries. +If DMA coherent mappings are impossible, this flag is silently ignored. +.Pp +Later, when this memory is loaded into a DMA map, machine-dependent code +will take whatever steps are necessary to determine if the memory was +mapped in a DMA coherent fashion. +This may include checking if the kernel virtual address lies within +uncached address space or if the cache-inhibit bits are set in page +table entries. +If it is determined that the mapping is DMA coherent, state may be +placed into the DMA map for use by later calls to +.Fn bus_dmamap_sync . +.Pp +Note that a device driver must not rely on +.Dv BUS_DMA_COHERENT +for correct operation. +All calls to +.Fn bus_dmamap_sync +must still be made. +This flag is provided only as an optimization hint to machine-dependent code. +.Pp +Also note that this flag only applies to coherency between the CPU +and memory. +Coherency between memory and the device is controlled with a different flag. +See the description of the +.Fn bus_dmamap_load +function. +.It Dv BUS_DMA_NOCACHE +This flag is a +.Em hint +to machine-dependent code. +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 +Behavior is undefined if invalid arguments are passed to +.Fn bus_dmamem_map . +.Pp +Returns 0 on success, or an error code indicating mode of failure. +.It Fn bus_dmamem_unmap "tag" "kva" "size" +Unmaps memory previously mapped with +.Fn bus_dmamem_map , +freeing the +kernel virtual address space used by the mapping. +.Bl -tag -width Ds \" Fa +.It Fa tag +This is the +.Vt bus_dma_tag_t +passed down from the parent driver via +.Fa <bus>_attach_args . +.It Fa kva +The kernel virtual address of the mapped memory. +.It Fa size +The size of the mapping. +.El +.Pp +Behavior is undefined if invalid arguments are passed to +.Fn bus_dmamem_unmap . +.Pp +If given valid arguments, +.Fn bus_dmamem_unmap +always succeeds. +.It Fn bus_dmamem_mmap "tag" "segs" "nsegs" "off" "prot" "flags" +Provides support for user +.Xr mmap 2 Ap ing +of DMA-safe memory. +This function is to be called by a device driver's +.Li (* Ns Fa d_mmap Ns Li )() +entry +point, which is called by the device pager for each page to be mapped. +.Bl -tag -width Ds \" Fa +.It Fa tag +This is the +.Vt bus_dma_tag_t +passed down from the parent driver via +.Fa <bus>_attach_args . +.It Fa segs +The array of bus_dma_segment_t's filled in by +.Fn bus_dmamem_alloc , +representing the memory to be +.Xr mmap 2 Ap ed . +.It Fa nsegs +The number of elements in the +.Fa segs +array. +.It Fa off +The offset of the page in DMA memory which is to be mapped. +.It Fa prot +The protection codes for the mapping. +.It Fa flags +.Bl -tag -width Ds \" Dv +.It Dv BUS_DMA_WAITOK +It is safe to wait (sleep) for resources during this call. +.It Dv BUS_DMA_NOWAIT +It is not safe to wait (sleep) for resources during this call. +.It Dv BUS_DMA_BUS[1-4] +These flags are placeholders, and may be used by busses to provide +bus-dependent functionality. +.It Dv BUS_DMA_COHERENT +See +.Fn bus_dmamem_map +above for a description of this flag. +.It Dv BUS_DMA_NOCACHE +See +.Fn bus_dmamem_map +above for a description of this flag. +.El +.El +.Pp +Behavior is undefined if invalid arguments are passed +to +.Fn bus_dmamem_mmap . +.Pp +Returns \-1 to indicate failure. +Otherwise, returns an opaque value to be interpreted by the device pager. +.It Fn bus_dmatag_subregion "tag" "min_addr" "max_addr" "newtag" "flags" +Given a +.Vt bus_dma_tag_t +create a new +.Vt bus_dma_tag_t +with a limited bus address space. +This function should not normally be used, but is useful for devices +that do not support the full address space of the parent bus. +Not all ports implement this method; on ports where it is unavailable, +.Er EOPNOTSUPP +is returned. +.Bl -tag -width Ds \" Fa +.It Fa tag +This is the +.Vt bus_dma_tag_t +to subregion. +.It Fa min_addr +The smallest address this new tag can address. +.It Fa max_addr +The largest address this new tag can address. +.It Fa newtag +Pointer filled in with the address of the new +.Vt bus_dma_tag_t . +.It Fa flags +.Bl -tag -width Ds \" Dv +.It Dv BUS_DMA_WAITOK +It is safe to wait (sleep) for resources during this call. +.It Dv BUS_DMA_NOWAIT +It is not safe to wait (sleep) for resources during this call. +.El +.El +.Pp +The address range +.Fa min_addr +to +.Fa max_addr +is inclusive of both addresses. +.It Fn bus_dmatag_destroy "tag" +Free a tag created by +.Fn bus_dmatag_subregion . +.El +.Sh SEE ALSO +.Xr membar_ops 3 , +.Xr bus_space 9 +.Rs +.%A Jason Thorpe +.%T "A Machine-Independent DMA Framework for NetBSD" +.%I USENIX Association +.%B Proceedings of the FREENIX Track: 1998 USENIX Annual Technical Conference +.%P 1-12 +.%D June 15-19, 1998 +.%U http://www.usenix.org/publications/library/proceedings/usenix98/freenix/thorpe_dma.pdf +.Re +.Sh HISTORY +The +.Nm +interface appeared in +.Nx 1.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm +interface was designed and implemented by +.An Jason R. Thorpe +of the +Numerical Aerospace Simulation Facility, NASA Ames Research Center. +Additional input on the +.Nm +design was provided by +.An Chris Demetriou , +.An Charles Hannum , +.An Ross Harvey , +.An Matthew Jacob , +.An Jonathan Stone , +and +.An Matt Thomas . diff --git a/static/netbsd/man9/bus_space.9 b/static/netbsd/man9/bus_space.9 new file mode 100644 index 00000000..8ee4bbce --- /dev/null +++ b/static/netbsd/man9/bus_space.9 @@ -0,0 +1,1985 @@ +.\" $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. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christopher G. Demetriou. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 12, 2022 +.Dt BUS_SPACE 9 +.Os +.Sh NAME +.Nm bus_space , +.Nm bus_space_barrier , +.Nm bus_space_copy_region_1 , +.Nm bus_space_copy_region_2 , +.Nm bus_space_copy_region_4 , +.Nm bus_space_copy_region_8 , +.Nm bus_space_free , +.Nm bus_space_handle_is_equal , +.Nm bus_space_is_equal , +.Nm bus_space_map , +.Nm bus_space_mmap , +.Nm bus_space_peek_1 , +.Nm bus_space_peek_2 , +.Nm bus_space_peek_4 , +.Nm bus_space_peek_8 , +.Nm bus_space_poke_1 , +.Nm bus_space_poke_2 , +.Nm bus_space_poke_4 , +.Nm bus_space_poke_8 , +.Nm bus_space_read_1 , +.Nm bus_space_read_2 , +.Nm bus_space_read_4 , +.Nm bus_space_read_8 , +.Nm bus_space_read_multi_1 , +.Nm bus_space_read_multi_2 , +.Nm bus_space_read_multi_4 , +.Nm bus_space_read_multi_8 , +.Nm bus_space_read_multi_stream_1 , +.Nm bus_space_read_multi_stream_2 , +.Nm bus_space_read_multi_stream_4 , +.Nm bus_space_read_multi_stream_8 , +.Nm bus_space_read_region_1 , +.Nm bus_space_read_region_2 , +.Nm bus_space_read_region_4 , +.Nm bus_space_read_region_8 , +.Nm bus_space_read_region_stream_1 , +.Nm bus_space_read_region_stream_2 , +.Nm bus_space_read_region_stream_4 , +.Nm bus_space_read_region_stream_8 , +.Nm bus_space_read_stream_1 , +.Nm bus_space_read_stream_2 , +.Nm bus_space_read_stream_4 , +.Nm bus_space_read_stream_8 , +.Nm bus_space_release , +.Nm bus_space_reservation_addr , +.Nm bus_space_reservation_init , +.Nm bus_space_reservation_size , +.Nm bus_space_reservation_map , +.Nm bus_space_reservation_unmap , +.Nm bus_space_reserve , +.Nm bus_space_reserve_subregion , +.Nm bus_space_set_region_1 , +.Nm bus_space_set_region_2 , +.Nm bus_space_set_region_4 , +.Nm bus_space_set_region_8 , +.Nm bus_space_subregion , +.Nm bus_space_tag_create , +.Nm bus_space_tag_destroy , +.Nm bus_space_unmap , +.Nm bus_space_vaddr , +.Nm bus_space_write_1 , +.Nm bus_space_write_2 , +.Nm bus_space_write_4 , +.Nm bus_space_write_8 , +.Nm bus_space_write_multi_1 , +.Nm bus_space_write_multi_2 , +.Nm bus_space_write_multi_4 , +.Nm bus_space_write_multi_8 , +.Nm bus_space_write_multi_stream_1 , +.Nm bus_space_write_multi_stream_2 , +.Nm bus_space_write_multi_stream_4 , +.Nm bus_space_write_multi_stream_8 , +.Nm bus_space_write_region_1 , +.Nm bus_space_write_region_2 , +.Nm bus_space_write_region_4 , +.Nm bus_space_write_region_8 , +.Nm bus_space_write_region_stream_1 , +.Nm bus_space_write_region_stream_2 , +.Nm bus_space_write_region_stream_4 , +.Nm bus_space_write_region_stream_8 , +.Nm bus_space_write_stream_1 , +.Nm bus_space_write_stream_2 , +.Nm bus_space_write_stream_4 , +.Nm bus_space_write_stream_8 +.Nd bus space manipulation functions +.Sh SYNOPSIS +.In sys/bus.h +.Ft bool +.Fn bus_space_handle_is_equal "bus_space_tag_t space" \ + "bus_space_handle_t handle1" "bus_space_handle_t handle2" +.Ft bool +.Fn bus_space_is_equal "bus_space_tag_t space1" "bus_space_tag_t space2" +.Ft void +.Fn bus_space_release "bus_space_tag_t t" "bus_space_reservation_t *bsr" +.Ft int +.Fn bus_space_reserve "bus_space_tag_t t" "bus_addr_t bpa" "bus_size_t size" \ + "int flags" "bus_space_reservation_t *bsrp" +.Ft int +.Fn bus_space_reserve_subregion "bus_space_tag_t t" \ + "bus_addr_t reg_start" "bus_addr_t reg_end" \ + "bus_size_t size" "bus_size_t alignment" "bus_size_t boundary" \ + "int flags" "bus_space_reservation_t *bsrp" +.Ft void +.Fn bus_space_reservation_init "bus_space_reservation_t *bsr" \ + "bus_addr_t addr" "bus_size_t size" +.Ft bus_size_t +.Fn bus_space_reservation_size "bus_space_reservation_t *bsr" +.Ft int +.Fn bus_space_reservation_map "bus_space_tag_t t" \ + "bus_space_reservation_t *bsr" "int flags" "bus_space_handle_t *bshp" +.Ft void +.Fn bus_space_reservation_unmap "bus_space_tag_t t" "bus_space_handle_t bsh" \ + "bus_size_t size" +.Ft int +.Fn bus_space_map "bus_space_tag_t space" "bus_addr_t address" \ +"bus_size_t size" "int flags" "bus_space_handle_t *handlep" +.Ft void +.Fn bus_space_unmap "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t size" +.Ft int +.Fn bus_space_subregion "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "bus_size_t size" "bus_space_handle_t *nhandlep" +.Ft int +.Fo bus_space_alloc +.Fa "bus_space_tag_t space" "bus_addr_t reg_start" "bus_addr_t reg_end" +.Fa "bus_size_t size" "bus_size_t alignment" "bus_size_t boundary" +.Fa "int flags" "bus_addr_t *addrp" "bus_space_handle_t *handlep" +.Fc +.Ft void +.Fn bus_space_free "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t size" +.Ft void * +.Fn bus_space_vaddr "bus_space_tag_t space" "bus_space_handle_t handle" +.Ft paddr_t +.Fn bus_space_mmap "bus_space_tag_t space" "bus_addr_t addr" "off_t off" \ +"int prot" "int flags" +.Ft int +.Fn bus_space_tag_create "bus_space_tag_t obst" "uint64_t present" \ + "uint64_t extpresent" "const struct bus_space_overrides *ov" "void *ctx" \ + "bus_space_tag_t *bstp" +.Ft void +.Fn bus_space_tag_destroy "bus_space_tag_t bst" +.Ft int +.Fn bus_space_peek_1 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "uint8_t *datap" +.Ft int +.Fn bus_space_peek_2 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "uint16_t *datap" +.Ft int +.Fn bus_space_peek_4 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "uint32_t *datap" +.Ft int +.Fn bus_space_peek_8 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "uint64_t *datap" +.Ft int +.Fn bus_space_poke_1 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "uint8_t data" +.Ft int +.Fn bus_space_poke_2 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "uint16_t data" +.Ft int +.Fn bus_space_poke_4 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "uint32_t data" +.Ft int +.Fn bus_space_poke_8 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "uint64_t data" +.Ft uint8_t +.Fn bus_space_read_1 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" +.Ft uint16_t +.Fn bus_space_read_2 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" +.Ft uint32_t +.Fn bus_space_read_4 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" +.Ft uint64_t +.Fn bus_space_read_8 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" +.Ft void +.Fn bus_space_write_1 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "uint8_t value" +.Ft void +.Fn bus_space_write_2 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "uint16_t value" +.Ft void +.Fn bus_space_write_4 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "uint32_t value" +.Ft void +.Fn bus_space_write_8 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "uint64_t value" +.Ft void +.Fn bus_space_barrier "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "bus_size_t length" "int flags" +.Ft void +.Fn bus_space_read_region_1 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_region_2 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_region_4 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_region_8 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_region_stream_1 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_region_stream_2 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_region_stream_4 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_region_stream_8 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_write_region_1 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const uint8_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_write_region_2 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const uint16_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_write_region_4 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const uint32_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_write_region_8 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const uint64_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_write_region_stream_1 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const uint8_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_write_region_stream_2 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const uint16_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_write_region_stream_4 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const uint32_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_write_region_stream_8 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const uint64_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_copy_region_1 "bus_space_tag_t space" \ +"bus_space_handle_t srchandle" "bus_size_t srcoffset" \ +"bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Ft void +.Fn bus_space_copy_region_2 "bus_space_tag_t space" \ +"bus_space_handle_t srchandle" "bus_size_t srcoffset" \ +"bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Ft void +.Fn bus_space_copy_region_4 "bus_space_tag_t space" \ +"bus_space_handle_t srchandle" "bus_size_t srcoffset" \ +"bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Ft void +.Fn bus_space_copy_region_8 "bus_space_tag_t space" \ +"bus_space_handle_t srchandle" "bus_size_t srcoffset" \ +"bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Ft void +.Fn bus_space_set_region_1 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "uint8_t value" \ +"bus_size_t count" +.Ft void +.Fn bus_space_set_region_2 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "uint16_t value" \ +"bus_size_t count" +.Ft void +.Fn bus_space_set_region_4 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "uint32_t value" \ +"bus_size_t count" +.Ft void +.Fn bus_space_set_region_8 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "uint64_t value" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_multi_1 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_multi_2 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_multi_4 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_multi_8 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_multi_stream_1 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_multi_stream_2 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_multi_stream_4 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_multi_stream_8 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_write_multi_1 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const uint8_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_write_multi_2 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const uint16_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_write_multi_4 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const uint32_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_write_multi_8 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const uint64_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_write_multi_stream_1 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const uint8_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_write_multi_stream_2 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const uint16_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_write_multi_stream_4 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const uint32_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_write_multi_stream_8 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const uint64_t *datap" \ +"bus_size_t count" +.Sh DESCRIPTION +The +.Nm +functions exist to allow device drivers +machine-independent access to bus memory and register areas. +All of the functions and types described in this document can be used +by including the +.In sys/bus.h +header file. +.Pp +Many common devices are used on multiple architectures, but are accessed +differently on each because of architectural constraints. +For instance, a device which is mapped in one system's I/O space may be +mapped in memory space on a second system. +On a third system, architectural limitations might change the way +registers need to be accessed (e.g., creating a non-linear register space). +In some cases, a single +driver may need to access the same type of device in multiple ways in a +single system or architecture. +The goal of the +.Nm +functions is to allow a single driver source file to manipulate a set +of devices on different system architectures, and to allow a single driver +object file to manipulate a set of devices on multiple bus types on a +single architecture. +.Pp +Not all busses have to implement all functions described in this +document, though that is encouraged if the operations are logically +supported by the bus. +Unimplemented functions should cause compile-time errors if possible. +.Pp +All of the interface definitions described in this document are shown as +function prototypes and discussed as if they were required to be +functions. +Implementations are encouraged to implement prototyped (type-checked) +versions of these interfaces, but may implement them as macros if appropriate. +Machine-dependent types, variables, and functions should be marked clearly in +.In machine/bus_defs.h +and in +.In machine/bus_funcs.h +to avoid confusion with the +machine-independent types and functions, and, if possible, should be +given names which make the machine-dependence clear. +.Sh CONCEPTS AND GUIDELINES +Bus spaces are described by bus space tags, which can be created only by +machine-dependent code. +A given machine may have several different types of bus space +(e.g., memory space and I/O space), and thus may provide multiple different +bus space tags. +Individual busses or devices on a machine may use more than one bus space +tag. +For instance, ISA devices are given an ISA memory space tag and an +ISA I/O space tag. +Architectures may have several different tags which represent the same +type of space, for instance because of multiple different host bus +interface chipsets. +.Pp +A range in bus space is described by a bus address and a bus size. +The bus address describes the start of the range in bus space. +The bus size describes the size of the range in bytes. +Busses which are not byte addressable may require use of bus space ranges +with appropriately aligned addresses and properly rounded sizes. +.Pp +Access to regions of bus space is facilitated by use of bus space handles, +which are usually created by mapping a specific range of a bus space. +Handles may also be created by allocating +and mapping a range of bus space, the actual location of which is picked +by the implementation within bounds specified by the caller of the +allocation function. +.Pp +All of the bus space access functions require one bus space tag +argument, at least one handle argument, and at least one offset argument +(a bus size). +The bus space tag specifies the space, each handle specifies a region in +the space, and each offset specifies the offset into the region of the +actual location(s) to be accessed. +Offsets are given in bytes, though busses may impose alignment constraints. +The offset used to access data relative to a given handle must be such +that all of the data being accessed is in the mapped region that the +handle describes. +Trying to access data outside that region is an error. +.Pp +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 +functions should +try to make minimal assumptions about what the system allows. +In particular, they should expect that the system requires bus space +addresses being accessed to be naturally aligned (i.e., base address of +handle added to offset is a multiple of the access size), and that the +system does alignment checking on pointers (i.e., pointer to objects being +read and written must point to properly-aligned data). +.Pp +The descriptions of the +.Nm +functions given below all assume that +they are called with proper arguments. +If called with invalid arguments or arguments that are out of range +(e.g., trying to access data outside of the region mapped when a given +handle was created), undefined behaviour results. +In that case, they may cause the system to halt, either intentionally +(via panic) or unintentionally (by causing a fatal trap or by some other +means) or may cause improper operation which is not immediately fatal. +Functions which return void or which return data read from bus space +(i.e., functions which don't obviously return an error code) do not fail. +They could only fail if given invalid arguments, and in that case their +behaviour is undefined. +Functions which take a count of bytes have undefined results if the specified +.Fa count +is zero. +.Sh TYPES +Several types are defined in +.In machine/bus_defs.h +to facilitate use of the +.Nm +functions by drivers. +.Pp +.Bl -ohang -compact +.It Fa bus_addr_t +.Pp +The +.Fa bus_addr_t +type is used to describe bus addresses. +It must be an unsigned integral type capable of holding the largest bus +address usable by the architecture. +This type is primarily used when mapping and unmapping bus space. +.Pp +.It Fa bus_size_t +.Pp +The +.Fa bus_size_t +type is used to describe sizes of ranges in bus space. +It must be an unsigned integral type capable of holding the size of the +largest bus address range usable on the architecture. +This type is used by virtually all of the +.Nm +functions, describing sizes when mapping regions and +offsets into regions when performing space access operations. +.Pp +.It Fa bus_space_tag_t +.Pp +The +.Fa bus_space_tag_t +type is used to describe a particular bus space on a machine. +Its contents are machine-dependent and should be considered opaque by +machine-independent code. +This type is used by all +.Nm +functions to name the space on which they're operating. +.Pp +.It Fa bus_space_handle_t +.Pp +The +.Fa bus_space_handle_t +type is used to describe a mapping of a range of bus space. +Its contents are machine-dependent and should be considered opaque by +machine-independent code. +This type is used when performing bus space access operations. +.Pp +.It Fa bus_space_reservation_t +.Pp +The +.Fa bus_space_reservation_t +type is used to describe a range of bus space. +It logically consists of a +.Fa bus_addr_t , +the first address in the range, +and a +.Fa bus_size_t , +the length in bytes of the range. +Machine-independent code creates and interrogates a +.Fa bus_space_reservation_t +using a constructor, +.Fn bus_space_reservation_init , +and accessor functions, +.Fn bus_space_reservation_addr +and +.Fn bus_space_reservation_size . +.El +.Sh COMPARING BUS SPACE TAGS +To check whether or not one +.Fa bus_space_tag_t +refers to the same space as another in machine-independent code, +do not use either +.Xr memcmp 9 +or the C equals +.Po +== +.Pc +operator. +Use +.Fn bus_space_is_equal , +instead. +.Sh MAPPING AND UNMAPPING BUS SPACE +Bus space must be mapped before it can be used, and should be +unmapped when it is no longer needed. +The +.Fn bus_space_map , +.Fn bus_space_reservation_map , +.Fn bus_space_reservation_unmap , +and +.Fn bus_space_unmap +functions provide these capabilities. +.Pp +Some drivers need to be able to pass a subregion of already-mapped bus +space to another driver or module within a driver. +The +.Fn bus_space_subregion +function allows such subregions to be created. +.Pp +.Bl -ohang -compact +.It Fn bus_space_map "space" "address" "size" "flags" "handlep" +.Pp +The +.Fn bus_space_map +function exclusively reserves and maps the region of bus space named by the +.Fa space , +.Fa address , +and +.Fa size +arguments. +If successful, it returns zero and fills in the bus space handle pointed +to by +.Fa handlep +with the handle +that can be used to access the mapped region. +If unsuccessful, it will return non-zero and leave the bus space handle +pointed to by +.Fa handlep +in an undefined state. +.Pp +The +.Fa flags +argument controls how the space is to be mapped. +Supported flags include: +.Bl -tag -width BUS_SPACE_MAP_CACHEABLE -offset indent +.It Dv BUS_SPACE_MAP_CACHEABLE +Try to map the space so that accesses can be cached +by the system cache. +If this flag is not specified, the implementation should map the space so +that it will not be cached. +This mapping method will only be useful in very rare occasions. +.Pp +This flag must have a value of 1 on all implementations for backward +compatibility. +.It Dv BUS_SPACE_MAP_PREFETCHABLE +Try to map the space so that accesses can be prefetched by the system, +and writes can be buffered. +This means, accesses should be side effect free (idempotent). +The +.Fn bus_space_barrier +methods will flush the write buffer or force actual read accesses. +If this flag is not specified, the +implementation should map the space so that it will not be prefetched +or delayed. +.It Dv BUS_SPACE_MAP_LINEAR +Try to map the space so that its contents can be accessed linearly via +normal memory access methods (e.g., pointer dereferencing and structure +accesses). +The +.Fn bus_space_vaddr +method can be used to obtain the kernel virtual address of the mapped range. +This is useful when software wants to do direct access to a memory +device, e.g., a frame buffer. +If this flag is specified and linear mapping is not possible, the +.Fn bus_space_map +call should fail. +If this flag is not specified, the system may map the space in whatever +way is most convenient. +Use of this mapping method is not encouraged for normal device access; +where linear access is not essential, use of the +.Fn bus_space_read/write +methods is strongly recommended. +.El +.Pp +Not all combinations of flags make sense or are supported with all +spaces. +For instance, +.Dv BUS_SPACE_MAP_CACHEABLE +may be meaningless when +used on many systems' I/O port spaces, and on some systems +.Dv BUS_SPACE_MAP_LINEAR +without +.Dv BUS_SPACE_MAP_PREFETCHABLE +may never work. +When the system hardware or firmware provides hints as to how spaces should be +mapped (e.g., the PCI memory mapping registers' "prefetchable" bit), those +hints should be followed for maximum compatibility. +On some systems, requesting a mapping that cannot be satisfied (e.g., +requesting a non-prefetchable mapping when the system can only provide +a prefetchable one) will cause the request to fail. +.Pp +Some implementations may keep track of use of bus space for some or all +bus spaces and refuse to allow duplicate allocations. +This is encouraged for bus spaces which have no notion of slot-specific +space addressing, such as ISA and VME, and for spaces which coexist with +those spaces (e.g., EISA and PCI memory and I/O spaces co-existing with +ISA memory and I/O spaces). +.Pp +Mapped regions may contain areas for which there is no device on the bus. +If space in those areas is accessed, the results are bus-dependent. +.Pp +.It Fn bus_space_reservation_map "space" "bsr" "flags" "handlep" +.Pp +The +.Fn bus_space_reservation_map +function is similar to +.Fn bus_space_map +but it maps a region of bus space +that was previously reserved by a call to +.Fn bus_space_reserve +or +.Fn bus_space_reserve_subregion . +The region is given by the +.Fa space +and +.Fa bsr +arguments. +If successful, it returns zero and fills in the bus space handle pointed +to by +.Fa handlep +with the handle that can be used to access the mapped region. +If unsuccessful, it will return non-zero and leave the bus space handle +pointed to by +.Fa handlep +in an undefined state. +.Pp +A region mapped by +.Fn bus_space_reservation_map +may only be unmapped by a call to +.Fn bus_space_reservation_unmap . +.Pp +For more details, see the description of +.Fn bus_space_map . +.Pp +.It Fn bus_space_unmap "space" "handle" "size" +.Pp +The +.Fn bus_space_unmap +function unmaps and relinquishes a region of bus space reserved and +mapped with +.Fn bus_space_map . +When unmapping a region, the +.Fa size +specified should be +the same as the size given to +.Fn bus_space_map +when mapping that region. +.Pp +After +.Fn bus_space_unmap +is called on a handle, that handle is no longer valid. +(If copies were made of the handle they are no longer valid, either.) +.Pp +This function will never fail. +If it would fail (e.g., because of an argument error), that indicates +a software bug which should cause a panic. +In that case, +.Fn bus_space_unmap +will never return. +.Pp +.It Fn bus_space_reservation_unmap "space" "handle" "size" +.Pp +The +.Fn bus_space_reservation_unmap +function is similar to +.Fn bus_space_unmap +but it should be called on handles +mapped by +.Fn bus_space_reservation_map +and only on such handles. +Unlike +.Fn bus_space_unmap , +.Fn bus_space_reservation_unmap +does not relinquish exclusive use of the bus space named by +.Fa handle +and +.Fa size ; +that is the job of +.Fn bus_space_release . +.Pp +.It Fn bus_space_subregion "space" "handle" "offset" "size" "nhandlep" +.Pp +The +.Fn bus_space_subregion +function is a convenience function which makes a +new handle to some subregion of an already-mapped region of bus space. +The subregion described by the new handle starts at byte offset +.Fa offset +into the region described by +.Fa handle , +with the size given by +.Fa size , +and must be wholly contained within the original region. +.Pp +If successful, +.Fn bus_space_subregion +returns zero and fills in the bus +space handle pointed to by +.Fa nhandlep . +If unsuccessful, it returns non-zero and leaves the bus space handle +pointed to by +.Fa nhandlep +in an +undefined state. +In either case, the handle described by +.Fa handle +remains valid and is unmodified. +.Pp +When done with a handle created by +.Fn bus_space_subregion , +the handle should +be thrown away. +Under no circumstances should +.Fn bus_space_unmap +be used on the handle. +Doing so may confuse any resource management being done on the space, +and will result in undefined behaviour. +When +.Fn bus_space_unmap +or +.Fn bus_space_free +is called on a handle, all subregions of that handle become invalid. +.Pp +.It Fn bus_space_vaddr "tag" "handle" +.Pp +This method returns the kernel virtual address of a mapped bus space if and +only if it was mapped with the +.Dv BUS_SPACE_MAP_LINEAR +flag. +The range can be accessed by normal (volatile) pointer dereferences. +If mapped with the +.Dv BUS_SPACE_MAP_PREFETCHABLE +flag, the +.Fn bus_space_barrier +method must be used to force a particular access order. +.Pp +.It Fn bus_space_mmap "tag" "addr" "off" "prot" "flags" +.Pp +This method is used to provide support for memory mapping bus space +into user applications. +If an address space is addressable via volatile pointer dereferences, +.Fn bus_space_mmap +will return the physical address (possibly encoded as a machine-dependent +cookie) of the bus space indicated by +.Fa addr +and +.Fa off . +.Fa addr +is the base address of the device or device region, and +.Fa off +is the offset into that region that is being requested. +If the request is made with +.Dv BUS_SPACE_MAP_LINEAR +as a flag, then a linear region must be returned to the caller. +If the region cannot be mapped (either the address does not exist, +or the constraints can not be met), +.Fn bus_space_mmap +returns +.Dv -1 +to indicate failure. +.Pp +Note that it is not necessary that the region being requested by a +.Fn bus_space_mmap +call be mapped into a +.Fa bus_space_handle_t . +.Pp +.Fn bus_space_mmap +is called once per +.Dv PAGE_SIZE +page in the range. +The +.Fa prot +argument indicates the memory protection requested by the user application +for the range. +.Pp +.It Fn bus_space_handle_is_equal "space" "handle1" "handle2" +Use +.Fn bus_space_handle_is_equal +to check whether or not +.Fa handle1 +and +.Fa handle2 +refer to regions starting at the same address in the bus space +.Fa space . +.El +.Sh ALLOCATING AND FREEING BUS SPACE +Some devices require or allow bus space to be allocated by the operating +system for device use. +When the devices no longer need the space, the +operating system should free it for use by other devices. +The +.Fn bus_space_alloc , +.Fn bus_space_free , +.Fn bus_space_reserve , +.Fn bus_space_reserve_subregion , +and +.Fn bus_space_release +functions provide these capabilities. +The functions +.Fn bus_space_reserve , +.Fn bus_space_reserve_subregion , +and +.Fn bus_space_release +are not yet available on all architectures. +.Pp +.Bl -ohang -compact +.It Fn bus_space_alloc "space" "reg_start" "reg_end" "size" "alignment" \ +"boundary" "flags" "addrp" "handlep" +.Pp +The +.Fn bus_space_alloc +function allocates and maps a region of bus space with the size given by +.Fa size , +corresponding to the given constraints. +If successful, it returns zero, fills in the bus address pointed to by +.Fa addrp +with the bus space address of the allocated region, and fills in +the bus space handle pointed to by +.Fa handlep +with the handle that can be used to access that region. +If unsuccessful, it returns non-zero and leaves the bus address pointed to by +.Fa addrp +and the bus space handle pointed to by +.Fa handlep +in an undefined state. +.Pp +Constraints on the allocation are given by the +.Fa reg_start , +.Fa reg_end , +.Fa alignment , +and +.Fa boundary +parameters. +The allocated region will start at or after +.Fa reg_start +and end before or at +.Fa reg_end . +The +.Fa alignment +constraint must be a power of two, and the allocated region will start at +an address that is an even multiple of that power of two. +The +.Fa boundary +constraint, if non-zero, ensures that the region is allocated so that +.Fa "first address in region" +/ +.Fa boundary +has the same value as +.Fa "last address in region" +/ +.Fa boundary . +If the constraints cannot be met, +.Fn bus_space_alloc +will fail. +It is an error to specify a set of constraints that can never be met +.Po +for example, +.Fa size +greater than +.Fa boundary +.Pc . +.Pp +The +.Fa flags +parameter is the same as the like-named parameter to +.Fa bus_space_map , +the same flag values should be used, and they have the +same meanings. +.Pp +Handles created by +.Fn bus_space_alloc +should only be freed with +.Fn bus_space_free . +Trying to use +.Fn bus_space_unmap +on them causes undefined behaviour. +The +.Fn bus_space_subregion +function can be used on handles created by +.Fn bus_space_alloc . +.Pp +.It Fn bus_space_reserve "t" "bpa" "size" "flags" "bsrp" +.Pp +The +.Fn bus_space_reserve +function reserves, for the caller's exclusive use, +.Fa size +bytes starting at the address +.Fa bpa +in the space referenced by +.Fa t . +.Pp +.Fn bus_space_reserve +does +.Em not +map the space. +The caller should use +.Fn bus_space_reservation_map +to map the reservation. +.Fa flags +contains a hint how the caller may map the reservation, later. +Whenever possible, callers should pass the same flags to +.Fn bus_space_reserve +as they will pass to +.Fn bus_space_reservation_map +to map the reservation. +.Pp +On success, +.Fn bus_space_reserve +records the reservation at +.Fa bsrp +and returns 0. +On failure, +.Fa bsrp +is undefined, and +.Fn bus_space_reserve +returns a non-zero error code. +Possible error codes include +.Bl -tag -width EOPNOTSUPP -offset indent +.It Er ENOMEM +There was not sufficient bus space at +.Fa bpa +to satisfy the request. +.It Er EOPNOTSUPP +.Fn bus_space_reserve +is not supported on this architecture, or +.Fa flags +was incompatible with the bus space represented by +.Fa t . +.El +.Pp +.It Fn bus_space_reserve_subregion "t" "reg_start" "reg_end" \ + "size" "alignment" "boundary" "flags" "bsrp" +.Pp +The +.Fn bus_space_reserve_subregion +function reserves, for the caller's exclusive use, +.Fa size +bytes in the space referenced by +.Fa t . +The parameters +.Fa reg_start , +.Fa reg_end , +.Fa alignment , +.Fa boundary , +and +.Fa flags +each work alike to the +.Fn bus_space_alloc +parameters of the same names. +.Pp +On success, +.Fn bus_space_reserve_subregion +records the reservation at +.Fa bsrp +and returns 0. +On failure, +.Fa bsrp +is undefined, and +.Fn bus_space_reserve_subregion +returns a non-zero error code. +Possible error codes include +.Bl -tag -width EOPNOTSUPP -offset indent +.It Er ENOMEM +There was not sufficient bus space at +.Fa bpa +to satisfy the request. +.It Er EOPNOTSUPP +.Fn bus_space_reserve +is not supported on this architecture, or +.Fa flags +was incompatible with the bus space represented by +.Fa t . +.El +.Pp +.It Fn bus_space_release "t" "bsr" +.Pp +The +.Fn bus_space_release +function releases the bus space +.Fa bsr +in +.Fa t +that was previously reserved by +.Fn bus_space_reserve +or +.Fn bus_space_reserve_subregion . +.Pp +If +.Fn bus_space_release +is called on a reservation that has been mapped by +.Fn bus_space_reservation_map +without subsequently being unmapped, the behavior of the system is +undefined. +.Pp +.It Fn bus_space_free "space" "handle" "size" +.Pp +The +.Fn bus_space_free +function unmaps and frees a region of bus space mapped +and allocated with +.Fn bus_space_alloc . +When unmapping a region, the +.Fa size +specified should be the same as the size given to +.Fn bus_space_alloc +when allocating the region. +.Pp +After +.Fn bus_space_free +is called on a handle, that handle is no longer valid. +(If copies were made of the handle, they are no longer valid, either.) +.Pp +This function will never fail. +If it would fail (e.g., because of an argument error), that indicates +a software bug which should cause a panic. +In that case, +.Fn bus_space_free +will never return. +.El +.Sh READING AND WRITING SINGLE DATA ITEMS +The simplest way to access bus space is to read or write a single data +item. +The +.Fn bus_space_read_N +and +.Fn bus_space_write_N +families of functions provide +the ability to read and write 1, 2, 4, and 8 byte data items on busses +which support those access sizes. +.Pp +.Bl -ohang -compact +.It Fn bus_space_read_1 "space" "handle" "offset" +.It Fn bus_space_read_2 "space" "handle" "offset" +.It Fn bus_space_read_4 "space" "handle" "offset" +.It Fn bus_space_read_8 "space" "handle" "offset" +.Pp +The +.Fn bus_space_read_N +family of functions reads a 1, 2, 4, or 8 byte data item from +the offset specified by +.Fa offset +into the region specified by +.Fa handle +of the bus space specified by +.Fa space . +The location being read must lie within the bus space region specified by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data item being read. +On some systems, not obeying this requirement may cause incorrect data to +be read, on others it may cause a system crash. +.Pp +Read operations done by the +.Fn bus_space_read_N +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 +These functions will never fail. +If they would fail (e.g., because of an argument error), that indicates +a software bug which should cause a panic. +In that case, they will never return. +.Pp +.It Fn bus_space_write_1 "space" "handle" "offset" "value" +.It Fn bus_space_write_2 "space" "handle" "offset" "value" +.It Fn bus_space_write_4 "space" "handle" "offset" "value" +.It Fn bus_space_write_8 "space" "handle" "offset" "value" +.Pp +The +.Fn bus_space_write_N +family of functions writes a 1, 2, 4, or 8 byte data item to the offset +specified by +.Fa offset +into the region specified by +.Fa handle +of the bus space specified by +.Fa space . +The location being written must lie within +the bus space region specified by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data item being +written. +On some systems, not obeying this requirement may cause incorrect data +to be written, on others it may cause a system crash. +.Pp +Write operations done by the +.Fn bus_space_write_N +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 +These functions will never fail. +If they would fail (e.g., because of an argument error), that indicates +a software bug which should cause a panic. +In that case, they will never return. +.El +.Sh PROBING BUS SPACE FOR HARDWARE WHICH MAY NOT RESPOND +One problem with the +.Fn bus_space_read_N +and +.Fn bus_space_write_N +family of functions is that they provide no protection against +exceptions which can occur when no physical hardware or +device responds to the read or write cycles. +In such a situation, the system typically would panic due to a kernel-mode +bus error. +The +.Fn bus_space_peek_N +and +.Fn bus_space_poke_N +family of functions provide a mechanism to handle these exceptions +gracefully without the risk of crashing the system. +.Pp +As with +.Fn bus_space_read_N +and +.Fn bus_space_write_N , +the peek and poke functions provide the ability to read and +write 1, 2, 4, and 8 byte data items on busses which support those +access sizes. +All of the constraints specified in the descriptions of the +.Fn bus_space_read_N +and +.Fn bus_space_write_N +functions also apply to +.Fn bus_space_peek_N +and +.Fn bus_space_poke_N . +.Pp +The return value indicates the outcome of the peek or poke operation. +A return value of zero implies that a hardware device is +responding to the operation at the specified offset in the bus space. +A non-zero return value indicates that the kernel intercepted a +hardware exception (e.g., bus error) when the peek or poke operation +was attempted. +Note that some busses are incapable of generating exceptions when +non-existent hardware is accessed. +In such cases, these functions will always return zero and the value of +the data read by +.Fn bus_space_peek_N +will be unspecified. +.Pp +Finally, it should be noted that at this time the +.Fn bus_space_peek_N +and +.Fn bus_space_poke_N +functions are not re-entrant and should not, therefore, be used +from within an interrupt service routine. +This constraint may be removed at some point in the future. +.Pp +.Bl -ohang -compact +.It Fn bus_space_peek_1 "space" "handle" "offset" "datap" +.It Fn bus_space_peek_2 "space" "handle" "offset" "datap" +.It Fn bus_space_peek_4 "space" "handle" "offset" "datap" +.It Fn bus_space_peek_8 "space" "handle" "offset" "datap" +.Pp +The +.Fn bus_space_peek_N +family of functions cautiously read a 1, 2, 4, or 8 byte data item from +the offset specified by +.Fa offset +in the region specified by +.Fa handle +of the bus space specified by +.Fa space . +The data item read is stored in the location pointed to by +.Fa datap . +It is permissible for +.Fa datap +to be NULL, in which case the data item will be discarded after being read. +.Pp +.It Fn bus_space_poke_1 "space" "handle" "offset" "value" +.It Fn bus_space_poke_2 "space" "handle" "offset" "value" +.It Fn bus_space_poke_4 "space" "handle" "offset" "value" +.It Fn bus_space_poke_8 "space" "handle" "offset" "value" +.Pp +The +.Fn bus_space_poke_N +family of functions cautiously write a 1, 2, 4, or 8 byte data item +specified by +.Fa value +to the offset specified by +.Fa offset +in the region specified by +.Fa handle +of the bus space specified by +.Fa space . +.El +.Sh BARRIERS +Devices that support prefetchable (also known as +.Sq write-combining ) +or cacheable I/O may be mapped with +.Dv BUS_SPACE_MAP_PREFETCHABLE +or +.Dv BUS_SPACE_MAP_CACHEABLE +for higher performance by allowing bus space read and write operations +to be reordered, fused, torn, and/or cached by the system. +.Pp +When a driver requires ordering, e.g. to write to a command ring in bus +space and then update the command ring pointer, the +.Fn bus_space_barrier +function enforces it. +.Pp +.Bl -ohang -compact +.It Fn bus_space_barrier "space" "handle" "offset" "length" "flags" +.Pp +The +.Fn bus_space_barrier +function enforces ordering of bus space read and write operations +for the specified subregion (described by the +.Fa offset +and +.Fa length +parameters) of the region named by +.Fa handle +in the space named by +.Fa space . +.Pp +The +.Fa flags +argument controls what types of operations are to be ordered. +Supported flags are: +.Bl -tag -width BUS_SPACE_BARRIER_WRITE -offset indent +.It Dv BUS_SPACE_BARRIER_READ +Guarantee that any program-prior bus space read on +.Em any +bus space has returned data from the device or memory before any +program-later bus space read, bus space write, or memory access via +.Fn bus_space_vaddr , +on the specified range in the given bus space. +.Pp +This functions similarly to +.Xr membar_acquire 3 , +but additionally orders bus space I/O which +.Xr membar_ops 3 +may not. +.It Dv BUS_SPACE_BARRIER_WRITE +Guarantee that any program-prior bus space read, bus space write, or +memory access via +.Fn bus_space_vaddr , +on the specified range in the given bus space, has completed before any +program-later bus space write on +.Em any +bus space. +.Pp +This functions similarly to +.Xr membar_release 3 , +but additionally orders bus space I/O which +.Xr membar_ops 3 +may not. +.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 +on +.Em any +bus space has completed before any program-later bus space read, bus +space write, or memory access via +.Fn bus_space_vaddr +on +.Em any +bus space. +.Pp +Note that this is independent of the specified bus space and range. +.Pp +This functions similarly to +.Xr membar_sync 3 , +but additionally orders bus space I/O which +.Xr membar_ops 3 +may not. +This combination is very unusual, and often much more expensive; most +drivers do not need it. +.El +.Pp +Example: Consider a command ring in bus space with a command ring +pointer register, and a response ring in bus space with a response ring +pointer register. +.Bd -literal +error = bus_space_map(sc->sc_regt, ..., 0, &sc->sc_regh); +if (error) + \&... +error = bus_space_map(sc->sc_memt, ..., BUS_SPACE_MAP_PREFETCHABLE, + &sc->sc_memh); +if (error) + \&... +.Ed +.Pp +To submit a command (assuming there is space in the ring), first write +it out and then update the pointer: +.Bd -literal +i = sc->sc_nextcmdslot; +bus_space_write_4(sc->sc_memt, sc->sc_memh, CMDSLOT(i), cmd); +bus_space_write_4(sc->sc_memt, sc->sc_memh, CMDSLOT(i) + 4, arg1); +bus_space_write_4(sc->sc_memt, sc->sc_memh, CMDSLOT(i) + 8, arg2); +\&... +bus_space_write_4(sc->sc_memt, sc->sc_memh, CMDSLOT(i) + 4*n, argn); +bus_space_barrier(sc->sc_memt, sc->sc_memh, CMDSLOT(i), 4*n, + BUS_SPACE_BARRIER_WRITE); +bus_space_write_4(sc->sc_regt, sc->sc_regh, CMDPTR, i); +sc->sc_nextcmdslot = (i + n + 1) % sc->sc_ncmdslots; +.Ed +.Pp +To obtain a response, read the pointer first and then the ring data: +.Bd -literal +ptr = bus_space_read_4(sc->sc_regt, sc->sc_regh, RESPPTR); +while ((i = sc->sc_nextrespslot) != ptr) { + bus_space_barrier(sc->sc_memt, sc->sc_memh, RESPSLOT(i), 4, + BUS_SPACE_BARRIER_READ); + status = bus_space_read_4(sc->sc_memt, sc->sc_memh, RESPSLOT(i)); + handle_response(status); + sc->sc_nextrespslot = (i + 1) % sc->sc_nrespslots; +} +.Ed +.El +.Sh REGION OPERATIONS +Some devices use buffers which are mapped as regions in bus space. +Often, drivers want to copy the contents of those buffers to or from +memory, e.g., into mbufs which can be passed to higher levels of the +system or from mbufs to be output to a network. +In order to allow drivers to do this as efficiently as possible, the +.Fn bus_space_read_region_N +and +.Fn bus_space_write_region_N +families of functions are provided. +.Pp +Drivers occasionally need to copy one region of a bus space to another, +or to set all locations in a region of bus space to contain a single +value. +The +.Fn bus_space_copy_region_N +family of functions and the +.Fn bus_space_set_region_N +family of functions allow drivers to perform these operations. +.Pp +.Bl -ohang -compact +.It Fn bus_space_read_region_1 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_read_region_2 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_read_region_4 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_read_region_8 "space" "handle" "offset" "datap" "count" +.Pp +The +.Fn bus_space_read_region_N +family of functions reads +.Fa count +1, 2, 4, or 8 byte data items from bus space +starting at byte offset +.Fa offset +in the region specified by +.Fa handle +of the bus space specified by +.Fa space +and writes them into the array specified by +.Fa datap . +Each successive data item is read from an offset +1, 2, 4, or 8 bytes after the previous data item (depending on which +function is used). +All locations being read must lie within the bus space region specified by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data items being +read and the data array pointer should be properly aligned. +On some systems, not obeying these requirements may cause incorrect data +to be read, on others it may cause a system crash. +.Pp +Read operations done by the +.Fn bus_space_read_region_N +functions may be executed in any order. +They may also 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. +There is no way to insert barriers between reads of individual bus +space locations executed by the +.Fn bus_space_read_region_N +functions. +.Pp +These functions will never fail. +If they would fail (e.g., because of an argument error), that indicates a +software bug which should cause a panic. +In that case, they will never return. +.Pp +.It Fn bus_space_write_region_1 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_write_region_2 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_write_region_4 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_write_region_8 "space" "handle" "offset" "datap" "count" +.Pp +The +.Fn bus_space_write_region_N +family of functions reads +.Fa count +1, 2, 4, or 8 byte data items from the array +specified by +.Fa datap +and writes them to bus space starting at byte offset +.Fa offset +in the region specified by +.Fa handle +of the bus space specified +by +.Fa space . +Each successive data item is written to an offset 1, 2, 4, +or 8 bytes after the previous data item (depending on which function is +used). +All locations being written must lie within the bus space region specified by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data items being +written and the data array pointer should be properly aligned. +On some systems, not obeying these requirements may cause incorrect data +to be written, on others it may cause a system crash. +.Pp +Write operations done by the +.Fn bus_space_write_region_N +functions may be +executed in any order. +They may also 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. +There is no way to insert barriers between writes of individual bus +space locations executed by the +.Fn bus_space_write_region_N +functions. +.Pp +These functions will never fail. +If they would fail (e.g., because of an argument error), that indicates +a software bug which should cause a panic. +In that case, they will never return. +.Pp +.It Fn bus_space_copy_region_1 "space" "srchandle" "srcoffset" "dsthandle" \ +"dstoffset" "count" +.It Fn bus_space_copy_region_2 "space" "srchandle" "srcoffset" "dsthandle" \ +"dstoffset" "count" +.It Fn bus_space_copy_region_4 "space" "srchandle" "srcoffset" "dsthandle" \ +"dstoffset" "count" +.It Fn bus_space_copy_region_8 "space" "srchandle" "srcoffset" "dsthandle" \ +"dstoffset" "count" +.Pp +The +.Fn bus_space_copy_region_N +family of functions copies +.Fa count +1, 2, 4, or 8 byte data items in bus space +from the area starting at byte offset +.Fa srcoffset +in the region specified by +.Fa srchandle +of the bus space specified by +.Fa space +to the area starting at byte offset +.Fa dstoffset +in the region specified by +.Fa dsthandle +in the same bus space. +Each successive data item read or written has an offset 1, 2, 4, or 8 +bytes after the previous data item (depending on which function is used). +All locations being read and written must lie within the bus space +region specified by their respective handles. +.Pp +For portability, the starting addresses of the regions specified by +each handle plus its respective offset should be a multiple of the size +of data items being copied. +On some systems, not obeying this requirement may cause incorrect data +to be copied, on others it may cause a system crash. +.Pp +Read and write operations done by the +.Fn bus_space_copy_region_N +functions may be executed in any order. +They may also 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. +There is no way to insert barriers between reads or writes of +individual bus space locations executed by the +.Fn bus_space_copy_region_N +functions. +.Pp +Overlapping copies between different subregions of a single region +of bus space are handled correctly by the +.Fn bus_space_copy_region_N +functions. +.Pp +These functions will never fail. +If they would fail (e.g., because of an argument error), that indicates +a software bug which should cause a panic. +In that case, they will never return. +.Pp +.It Fn bus_space_set_region_1 "space" "handle" "offset" "value" "count" +.It Fn bus_space_set_region_2 "space" "handle" "offset" "value" "count" +.It Fn bus_space_set_region_4 "space" "handle" "offset" "value" "count" +.It Fn bus_space_set_region_8 "space" "handle" "offset" "value" "count" +.Pp +The +.Fn bus_space_set_region_N +family of functions writes the given +.Fa value +to +.Fa count +1, 2, 4, or 8 byte +data items in bus space starting at byte offset +.Fa offset +in the region specified by +.Fa handle +of the bus space specified by +.Fa space . +Each successive data item has an offset 1, 2, 4, or 8 bytes after the +previous data item (depending on which function is used). +All locations being written must lie within the bus space region +specified by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data items being +written. +On some systems, not obeying this requirement may cause incorrect data +to be written, on others it may cause a system crash. +.Pp +Write operations done by the +.Fn bus_space_set_region_N +functions may be +executed in any order. +They may also 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. +There is no way to insert barriers between writes of +individual bus space locations executed by the +.Fn bus_space_set_region_N +functions. +.Pp +These functions will never fail. +If they would fail (e.g., because of an argument error), that indicates +a software bug which should cause a panic. +In that case, they will never return. +.El +.Sh READING AND WRITING A SINGLE LOCATION MULTIPLE TIMES +Some devices implement single locations in bus space which are to be read +or written multiple times to communicate data, e.g., some ethernet +devices' packet buffer FIFOs. +In order to allow drivers to manipulate these types of devices as +efficiently as possible, the +.Fn bus_space_read_multi_N +and +.Fn bus_space_write_multi_N +families of functions are provided. +.Pp +.Bl -ohang -compact +.It Fn bus_space_read_multi_1 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_read_multi_2 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_read_multi_4 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_read_multi_8 "space" "handle" "offset" "datap" "count" +.Pp +The +.Fn bus_space_read_multi_N +family of functions reads +.Fa count +1, 2, 4, or 8 byte data items from bus space +at byte offset +.Fa offset +in the region specified by +.Fa handle +of the bus space specified by +.Fa space +and writes them into the array specified by +.Fa datap . +Each successive data item is read from the same location in bus +space. +The location being read must lie within the bus space region specified by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data items being +read and the data array pointer should be properly aligned. +On some systems, not obeying these requirements may cause incorrect data +to be read, on others it may cause a system crash. +.Pp +Read operations done by the +.Fn bus_space_read_multi_N +functions may be executed out of order with respect to other read and +write operations if the latter are on prefetchable or cacheable +mappings unless order is enforced by use of the +.Fn bus_space_barrier +function. +.Fn bus_space_read_multi_N +makes no sense itself on prefetchable or cacheable mappings. +.Pp +These functions will never fail. +If they would fail (e.g., because of an argument error), that indicates +a software bug which should cause a panic. +In that case, they will never return. +.Pp +.It Fn bus_space_write_multi_1 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_write_multi_2 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_write_multi_4 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_write_multi_8 "space" "handle" "offset" "datap" "count" +.Pp +The +.Fn bus_space_write_multi_N +family of functions reads +.Fa count +1, 2, 4, or 8 byte data items from the array +specified by +.Fa datap +and writes them into bus space at byte offset +.Fa offset +in the region specified by +.Fa handle +of the bus space specified by +.Fa space . +Each successive data item is written to the same location in +bus space. +The location being written must lie within the bus space region specified by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data items being +written and the data array pointer should be properly aligned. +On some systems, not obeying these requirements may cause incorrect data +to be written, on others it may cause a system crash. +.Pp +Write operations done by the +.Fn bus_space_write_multi_N +functions may be executed out of order with respect to other read and +write operations if the latter are on prefetchable or cacheable +mappings unless order is enforced by use of the +.Fn bus_space_barrier +function. +.Fn bus_space_write_multi_N +makes no sense itself on prefetchable or cacheable mappings. +.Pp +These functions will never fail. +If they would fail (e.g., because of an argument error), that indicates +a software bug which should cause a panic. +In that case, they will never return. +.El +.Sh STREAM FUNCTIONS +Most of the +.Nm +functions imply a host byte-order and a bus byte-order and take care of +any translation for the caller. +In some cases, however, hardware may map a FIFO or some other memory region +for which the caller may want to use multi-word, yet untranslated access. +Access to these types of memory regions should be with the +.Fn bus_space_*_stream_N +functions. +.Pp +.Bl -ohang -compact +.It Fn bus_space_read_stream_1 "space" "handle" "offset" +.It Fn bus_space_read_stream_2 "space" "handle" "offset" +.It Fn bus_space_read_stream_4 "space" "handle" "offset" +.It Fn bus_space_read_stream_8 "space" "handle" "offset" +.It Fn bus_space_read_multi_stream_1 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_read_multi_stream_2 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_read_multi_stream_4 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_read_multi_stream_8 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_read_region_stream_1 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_read_region_stream_2 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_read_region_stream_4 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_read_region_stream_8 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_write_stream_1 "space" "handle" "offset" "value" +.It Fn bus_space_write_stream_2 "space" "handle" "offset" "value" +.It Fn bus_space_write_stream_4 "space" "handle" "offset" "value" +.It Fn bus_space_write_stream_8 "space" "handle" "offset" "value" +.It Fn bus_space_write_multi_stream_1 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_write_multi_stream_2 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_write_multi_stream_4 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_write_multi_stream_8 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_write_region_stream_1 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_write_region_stream_2 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_write_region_stream_4 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_write_region_stream_8 "space" "handle" "offset" "datap" "count" +.El +.Pp +These functions are defined just as their non-stream counterparts, +except that they provide no byte-order translation. +.Sh IMPLEMENTING BUS SPACES IN MACHINE-INDEPENDENT CODE +.Bl -ohang -compact +.It Fn bus_space_tag_create "obst" "present" "extpresent" "ov" "ctx" "bstp" +Create a copy of the tag +.Fa obst +at +.Fa *bstp . +Except for the behavior +overridden by +.Fa ov , +.Fa *bstp +inherits the behavior of +.Fa obst +under +.Nm +calls. +.Pp +.Fa ov +contains function pointers corresponding to +.Nm +routines. +Each function pointer has a corresponding bit in +.Fa present +or +.Fa extpresent , +and if that bit is 1, the function pointer overrides the corresponding +.Nm +call for the new tag. +Any combination of these bits may be set in +.Fa present : +.Pp +.Bl -tag -width BUS_SPACE_OVERRIDE_RESERVE_SUBREGION -compact +.It Dv BUS_SPACE_OVERRIDE_MAP +.It Dv BUS_SPACE_OVERRIDE_UNMAP +.It Dv BUS_SPACE_OVERRIDE_ALLOC +.It Dv BUS_SPACE_OVERRIDE_FREE +.It Dv BUS_SPACE_OVERRIDE_RESERVE +.It Dv BUS_SPACE_OVERRIDE_RELEASE +.It Dv BUS_SPACE_OVERRIDE_RESERVATION_MAP +.It Dv BUS_SPACE_OVERRIDE_RESERVATION_UNMAP +.It Dv BUS_SPACE_OVERRIDE_RESERVE_SUBREGION +.El +.Pp +.Fn bus_space_tag_create +does not copy +.Fa ov . +After a new tag is created by +.Fn bus_space_tag_create , +.Fa ov +must not be destroyed until after the +tag is destroyed by +.Fn bus_space_tag_destroy . +.Pp +The first argument of every override-function is a +.Vt "void *" , +and +.Fa ctx +is passed in that argument. +.Pp +Return 0 if the call succeeds. +Return +.Er EOPNOTSUPP +if the architecture does not support overrides. +Return +.Er EINVAL +if +.Fa present +is 0, if +.Fa ov +is +.Dv NULL , +or if +.Fa present +indicates that an override is present, but the corresponding override +in +.Fa ov +is +.Dv NULL . +.Pp +If the call does not succeed, +.Fa *bstp +is undefined. +.It Fn bus_space_tag_destroy "bst" +Destroy a tag, +.Fa bst , +created by a prior call to +.Fn bus_space_tag_create . +If +.Fa bst +was not created by +.Fn bus_space_tag_create , +results are undefined. +If +.Fa bst +was already destroyed, results are undefined. +.El +.Sh EXPECTED CHANGES TO THE BUS_SPACE FUNCTIONS +The definition of the +.Nm +functions should not yet be considered finalized. +There are several changes and improvements which should be explored, +including: +.Bl -bullet +.It +Exporting the +.Nm +functions to userland so that applications +(such as X servers) have easier, more portable access to device space. +.It +Redefining bus space tags and handles so that machine-independent bus +interface drivers (for example PCI to VME bridges) could define and +implement bus spaces without requiring machine-dependent code. +If this is done, it should be done in such a way that machine-dependent +optimizations should remain possible. +.It +Converting bus spaces (such as PCI configuration space) which currently +use space-specific access methods to use the +.Nm +functions where that is appropriate. +.It +Redefining the way bus space is mapped and allocated, so that mapping +and allocation are done with bus specific functions which return bus +space tags. +This would allow further optimization than is currently possible, and +would also ease translation of the +.Nm +functions into user space (since mapping in user space would look like +it just used a different bus-specific mapping function). +.El +.Sh COMPATIBILITY +The current version of the +.Nm +interface specification differs slightly from the original +specification that came into wide use. +A few of the function names and arguments have changed +for consistency and increased functionality. +Drivers that were written to the +old, deprecated specification can be compiled by defining the +.Dv __BUS_SPACE_COMPAT_OLDDEFS +preprocessor symbol before including +.In sys/bus.h . +.Sh SEE ALSO +.Xr membar_ops 3 , +.Xr bus_dma 9 +.Sh HISTORY +The +.Nm +functions were introduced in a different form (memory and I/O spaces +were accessed via different sets of functions) in +.Nx 1.2 . +The functions were merged to work on generic +.Dq spaces +early in the +.Nx 1.3 +development cycle, and many drivers were converted to use them. +This document was written later during the +.Nx 1.3 +development cycle and the specification was updated to fix some +consistency problems and to add some missing functionality. +.Sh AUTHORS +.An -nosplit +The +.Nm +interfaces were designed and implemented by the +.Nx +developer +community. +Primary contributors and implementors were +.An Chris Demetriou , +.An Jason Thorpe , +and +.An Charles Hannum , +but the rest of the +.Nx +developers and the user community played a significant role in development. +.Pp +.An Chris Demetriou +wrote this manual page. diff --git a/static/netbsd/man9/byteorder.9 b/static/netbsd/man9/byteorder.9 new file mode 100644 index 00000000..53cd8325 --- /dev/null +++ b/static/netbsd/man9/byteorder.9 @@ -0,0 +1,201 @@ +.\" $NetBSD: byteorder.9,v 1.11 2017/10/16 15:48:14 christos Exp $ +.\" +.\" Copyright (c) 2002 Mike Barcroft <mike@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man9/byteorder.9,v 1.6 2003/05/21 17:32:55 ru Exp $ +.\" +.Dd October 16, 2017 +.Dt BYTEORDER 9 +.Os +.Sh NAME +.Nm bswap16 , +.Nm bswap32 , +.Nm bswap64 , +.Nm be16toh , +.Nm be32toh , +.Nm be64toh , +.Nm htobe16 , +.Nm htobe32 , +.Nm htobe64 , +.Nm htole16 , +.Nm htole32 , +.Nm htole64 , +.Nm le16toh , +.Nm le32toh , +.Nm le64toh , +.Nm be16enc , +.Nm be16dec , +.Nm be32enc , +.Nm be32dec , +.Nm be64enc , +.Nm be64dec , +.Nm le16enc , +.Nm le16dec , +.Nm le32enc , +.Nm le32dec , +.Nm le64enc , +.Nm le64dec +.Nd byte order operations +.Sh SYNOPSIS +.In sys/endian.h +.Ft uint16_t +.Fn bswap16 "uint16_t int16" +.Ft uint32_t +.Fn bswap32 "uint32_t int32" +.Ft uint64_t +.Fn bswap64 "uint64_t int64" +.Ft uint16_t +.Fn be16toh "uint16_t big16" +.Ft uint32_t +.Fn be32toh "uint32_t big32" +.Ft uint64_t +.Fn be64toh "uint64_t big64" +.Ft uint16_t +.Fn htobe16 "uint16_t host16" +.Ft uint32_t +.Fn htobe32 "uint32_t host32" +.Ft uint64_t +.Fn htobe64 "uint64_t host64" +.Ft uint16_t +.Fn htole16 "uint16_t host16" +.Ft uint32_t +.Fn htole32 "uint32_t host32" +.Ft uint64_t +.Fn htole64 "uint64_t host64" +.Ft uint16_t +.Fn le16toh "uint16_t little16" +.Ft uint32_t +.Fn le32toh "uint32_t little32" +.Ft uint64_t +.Fn le64toh "uint64_t little64" +.Ft uint16_t +.Fn be16dec "const void *stream" +.Ft uint32_t +.Fn be32dec "const void *stream" +.Ft uint64_t +.Fn be64dec "const void *stream" +.Ft uint16_t +.Fn le16dec "const void *stream" +.Ft uint32_t +.Fn le32dec "const void *stream" +.Ft uint64_t +.Fn le64dec "const void *stream" +.Ft void +.Fn be16enc "void *stream" "uint16_t host16" +.Ft void +.Fn be32enc "void *stream" "uint32_t host32" +.Ft void +.Fn be64enc "void *stream" "uint64_t host64" +.Ft void +.Fn le16enc "void *stream" "uint16_t host16" +.Ft void +.Fn le32enc "void *stream" "uint32_t host32" +.Ft void +.Fn le64enc "void *stream" "uint64_t host64" +.Sh DESCRIPTION +The +.Fn bswap16 , +.Fn bswap32 , +and +.Fn bswap64 +functions return a byte order swapped integer. +On big endian systems, the number is converted to little endian byte order. +On little endian systems, the number is converted to big endian byte order. +.Pp +The +.Fn be16toh , +.Fn be32toh , +and +.Fn be64toh +functions return a big endian byte ordered integer +converted to the system's native byte order. +The return value will be the same as the argument on big endian systems. +.Pp +The +.Fn le16toh , +.Fn le32toh , +and +.Fn le64toh +functions return a little endian byte ordered integer +converted to the system's native byte order. +The return value will be the same as the argument on little endian systems. +.Pp +The +.Fn htobe16 , +.Fn htobe32 , +and +.Fn htobe64 +functions return an integer in the system's native +byte order converted to big endian byte order. +The return value will be the same as the argument on big endian systems. +.Pp +The +.Fn htole16 , +.Fn htole32 , +and +.Fn htole64 +functions return an integer in the system's native +byte order converted to little endian byte order. +The return value will be the same as the argument on little endian systems. +.Pp +The +.Fn be16enc , +.Fn be16dec , +.Fn be32enc , +.Fn be32dec , +.Fn be64enc , +.Fn be64dec , +.Fn le16enc , +.Fn le16dec , +.Fn le32enc , +.Fn le32dec , +.Fn le64enc , +and +.Fn le64dec +functions encode and decode integers to/from octet stream +on any alignment in big/little endian format. +.Sh SEE ALSO +.Xr bswap 3 , +.Xr byteorder 3 +.Sh HISTORY +The +.Fn hto* +and +.Fn *toh +functions first appeared in +.Nx 1.5 . +These were later ported to +.Fx 5.0 . +These functions were originally introduced to handle PCI bus master +devices that (via DMA) transfer little endian data even on big +endian systems. +.Pp +The encode/decode functions first appeared in +.Fx 5.1 . +These were later ported to +.Nx 3.0 +as a part of the +.Xr uuidgen 2 +support. diff --git a/static/netbsd/man9/bzero.9 b/static/netbsd/man9/bzero.9 new file mode 100644 index 00000000..ad323e13 --- /dev/null +++ b/static/netbsd/man9/bzero.9 @@ -0,0 +1,73 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)bzero.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: bzero.9,v 1.7 2003/08/07 10:31:30 agc Exp $ +.\" +.Dd July 7, 2001 +.Dt BZERO 9 +.Os +.Sh NAME +.Nm bzero +.Nd write zeroes to a byte string +.Sh SYNOPSIS +.In sys/systm.h +.Ft void +.Fn bzero "void *b" "size_t len" +.Sh DESCRIPTION +.Bf -symbolic +The +.Fn bzero +interface is obsolete. +Do not add new code using it. +It will soon be purged. +Use +.Xr memset 9 +instead. +(The +.Fn bzero +function is now a macro for +.Xr memset 9 . ) +.Ef +.Pp +The +.Fn bzero +function +writes +.Fa len +zero bytes to the string +.Fa b . +If +.Fa len +is zero, +.Fn bzero +does nothing. +.Sh SEE ALSO +.Xr memset 9 diff --git a/static/netbsd/man9/callback.9 b/static/netbsd/man9/callback.9 new file mode 100644 index 00000000..39b89c45 --- /dev/null +++ b/static/netbsd/man9/callback.9 @@ -0,0 +1,112 @@ +.\" $NetBSD: callback.9,v 1.5 2010/12/02 12:54:13 wiz Exp $ +.\" +.\" Copyright (c) 2009 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 28, 2009 +.Dt CALLBACK 9 +.Os +.Sh NAME +.Nm callback +.Nd generic callback interface +.Sh SYNOPSIS +.In sys/callback.h +.Ft void +.Fn callback_head_init "struct callback_head *ch" "int ipl" +.Ft void +.Fn callback_head_destroy "struct callback_head *ch" +.Ft void +.Fn callback_register \ +"struct callback_head *ch" "struct callback_entry *ce" "void *obj" \ +"int (*fn)(struct callback_entry *, void *, void *)" +.Ft void +.Fn callback_unregister "struct callback_head *ch" "struct callback_entry *ce" +.Ft int +.Fn callback_run_roundrobin "struct callback_head *ch" "void *arg" +.Sh DESCRIPTION +The generic +.Nm callback +interface allows lower-level layer code to execute a registered function, +or set of functions, from the higher-level layer. +.Pp +Registered functions must return one of these constants: +.Bl -tag -width Dv +.It Dv CALLBACK_CHAIN_CONTINUE +Indicates that the function call was successful. +The following functions in the chain will be called. +.It Dv CALLBACK_CHAIN_ABORT +Indicates a failure case in the function call. +Any following functions in the chain will not be executed. +.El +.Sh FUNCTIONS +The callback structure +.Vt callback_head +should be initialized and destroyed using the functions described below. +This structure contains the list of callback entries and other internal data. +.Pp +The +.Vt callback_entry +structure is an entry, normally associated with the higher-level object. +It contains the internal data of the callback interface. +.Bl -tag -width compact +.It Fn callback_head_init "ch" "ipl" +Initialize the callback structure specified by +.Fa ch . +The highest IPL at which this callback can be used is specified by +.Fa ipl . +.It Fn callback_head_destroy "ch" +Destroy the callback structure specified by +.Fa ch . +The caller must unregister all functions before destroying the callback structure. +.It Fn callback_register "ch" "ce" "obj" "fn" +Register the callback function in the callback structure specified by +.Fa ch . +.Fa ce +should point to the entry structure of the callback object. +The callback object itself is specified by +.Fa obj . +The function pointer is specified by +.Fa fn . +.It Fn callback_unregister "ch" "ce" +Unregister the callback function from the structure specified by +.Fa ch . +The entry should be passed as +.Fa ce . +This function may block. +.It Fn callback_run_roundrobin "ch" "arg" +Executes all functions registered in the callback +structure, specified by +.Fa ch . +The functions are executed in round-robin fashion. +The value of +.Fa arg +will be passed to the callback functions. +.El +.Sh CODE REFERENCES +The +.Nm +interface is implemented within the file +.Pa sys/kern/subr_callback.c . +.Sh SEE ALSO +.Xr intro 9 diff --git a/static/netbsd/man9/callout.9 b/static/netbsd/man9/callout.9 new file mode 100644 index 00000000..55e9b3c2 --- /dev/null +++ b/static/netbsd/man9/callout.9 @@ -0,0 +1,322 @@ +.\" $NetBSD: callout.9,v 1.29 2020/01/12 20:49:21 sevan Exp $ +.\" +.\" Copyright (c) 2000, 2003, 2009 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 12, 2020 +.Dt CALLOUT 9 +.Os +.Sh NAME +.Nm callout_init , +.Nm callout_destroy , +.Nm callout_halt , +.Nm callout_reset , +.Nm callout_schedule , +.Nm callout_setfunc , +.Nm callout_stop , +.Nm callout_pending , +.Nm callout_expired , +.Nm callout_invoking , +.Nm callout_ack +.Nd execute a function after a specified length of time +.Sh SYNOPSIS +.In sys/callout.h +.Ft void +.Fn "callout_init" "callout_t *c" "u_int flags" +.Ft void +.Fn "callout_destroy" "callout_t *c" +.Ft void +.Fn "callout_reset" "callout_t *c" "int ticks" \ + "void (*func)(void *)" "void *arg" +.Ft void +.Fn "callout_schedule" "callout_t *c" "int ticks" +.Ft void +.Fn "callout_setfunc" "callout_t *c" "void (*func)(void *)" "void *arg" +.Ft bool +.Fn "callout_stop" "callout_t *c" +.Ft bool +.Fn "callout_halt" "callout_t *c" "void *interlock" +.Ft bool +.Fn "callout_pending" "callout_t *c" +.Ft bool +.Fn "callout_expired" "callout_t *c" +.Ft bool +.Fn "callout_active" "callout_t *c" +.Ft bool +.Fn "callout_invoking" "callout_t *c" +.Ft void +.Fn "callout_ack" "callout_t *c" +.Sh DESCRIPTION +The +.Nm callout +facility provides a mechanism to execute a function at a given time. +The timer is based on the hardclock timer which ticks +.Dv hz +times per second. +The function is called at softclock interrupt level. +.Pp +Clients of the +.Nm callout +facility are responsible for providing pre-allocated +callout structures, or +.Dq handles . +The +.Nm callout +facility replaces the historic +.Ux +functions +.Fn timeout +and +.Fn untimeout . +.Sh FUNCTIONS +The +.Fn callout_init +function initializes the callout handle +.Fa c +for use. +No operations can be performed on the callout before it is initialized. +If the +.Fa flags +argument is +.Dv CALLOUT_MPSAFE , +the handler will be called without getting the global kernel lock. +In this case it should only use functions that are multiprocessor +safe. +.Pp +.Fn callout_destroy +destroys the callout, preventing further use. +It is provided as a diagnostic facility intended to catch bugs. +To ensure future compatibility, +.Fn callout_destroy +should always be called when the callout is no longer required (for instance, +when a device is being detached). +The callout should be stopped before +.Fn callout_destroy +is called by calling +.Fn callout_halt . +Note that +.Fn callout_stop +shouldn't be used for this purpose. +.Pp +The +.Fn callout_reset +function resets and starts the timer associated with the callout handle +.Fa c . +When the timer expires after +.Fa ticks Ns No /hz +seconds, the function specified by +.Fa func +will be called with the argument +.Fa arg . +If the timer associated with the callout handle is already running, +the callout will simply be rescheduled to execute at the newly specified +time. +Once the timer is started, the callout handle is marked as +.Em PENDING . +Once the timer expires, +the handle is marked as +.Em EXPIRED +and +.Em INVOKING , +and the +.Em PENDING +status is cleared. +.Pp +The +.Fn callout_setfunc +function sets the function and argument of the callout handle +.Fa c +to +.Fa func +and +.Fa arg +respectively. +The callout handle must already be initialized. +If a callout will always be used with the same function and argument, +then +.Fn callout_setfunc +used in conjunction with +.Fn callout_schedule +is slightly more efficient than using +.Fn callout_reset . +.Pp +The +.Fn callout_stop +function requests that the timer associated with the callout handle +.Fa c +be stopped. +The +.Em PENDING +and +.Em EXPIRED +status for the callout handle is cleared. +It is safe to call +.Fn callout_stop +on a callout handle that is not pending, so long as it is initialized. +.Fn callout_stop +will return a non-zero value if the callout was +.Em EXPIRED . +Note that +.Fn callout_stop +can return while the callout is running on a different CPU or at a +different interrupt priority level on the current CPU. +It can only be said to prevent the callout from firing in the future, +unless explicitly re-scheduled. +To stop a callout and wait for completion, use +.Fn callout_halt . +.Pp +.Fn callout_halt +acts much like +.Fn callout_stop , +but waits for the callout to complete if it is currently in-flight. +.Fn callout_halt +may not be called from a hard interrupt handler as it will sleep if the +callout is currently executing. +If the callout can take locks (such as mutexes or RW locks), the caller of +.Fn callout_halt +must not hold any of those locks, otherwise the two could deadlock. +To facilitate this, +.Fn callout_halt +can optionally release a single mutex specified by the +.Fa interlock +parameter. +If +.Fa interlock +is not +.Dv NULL +and the calling thread must wait for the callout to complete, +.Fa interlock +will be released before waiting and re-acquired before returning. +If no wait is required, +.Fa interlock +will not be released. +However, to avoid race conditions the caller should always assume that +.Fa interlock +has been released and reacquired, and act accordingly. +.Pp +The +.Fn callout_pending +function tests the +.Em PENDING +status of the callout handle +.Fa c . +A +.Em PENDING +callout is one that has been started and whose function has not yet +been called. +Note that it is possible for a callout's timer to have expired without +its function being called if interrupt level has not dropped low enough +to let softclock interrupts through. +Note that it is only safe to test +.Em PENDING +status when at softclock interrupt level or higher. +.Pp +The +.Fn callout_expired +function tests to see if the callout's timer has expired and its +function called. +.Pp +The +.Fn callout_active +function returns true if a timer has been started but not explicitly stopped, +even if it has already fired. +.Fn callout_active foo +is logically the same as +.Fn callout_pending foo +|| +.Fn callout_expired foo ; +it is implemented as a separate function for compatibility with +.Fx +and for the special case of +.Fn TCP_TIMER_ISARMED . +Its use is not recommended. +.Pp +The +.Fn callout_invoking +function tests the +.Em INVOKING +status of the callout handle +.Fa c . +This flag is set just before a callout's function is being called. +Since the priority level is lowered prior to invocation of the +callout function, other pending higher-priority code may run before +the callout function is allowed to run. +This may create a race condition if this higher-priority code +deallocates storage containing one or more callout structures whose +callout functions are about to be run. +In such cases, one technique to prevent references to deallocated +storage would be to test whether any callout functions are in the +.Em INVOKING +state using +.Fn callout_invoking , +and if so, to mark the data structure and defer storage +deallocation until the callout function is allowed to run. +For this handshake protocol to work, the callout function will +have to use the +.Fn callout_ack +function to clear this flag. +.Pp +The +.Fn callout_ack +function clears the +.Em INVOKING +state in the callout handle +.Fa c . +This is used in situations where it is necessary to protect against +the race condition described under +.Fn callout_invoking . +.Sh CONCURRENCY +The callout facility performs locking internally in order to guarantee the +atomicity of individual operations performed on callouts. +It does not provide life cycle management of user-provided callout data +structures, nor does it ensure that groups of operations (multiple function +calls) are performed atomically. +These aspects of callout management are the responsibility of the user of +the callout facility. +.Pp +Scheduled callouts may be active concurrently in a context different to the +user of the callout facility: on another CPU, or at a different interrupt +priority level or thread on the current CPU. +The callout facility provides only one guarantee in this regard: any given +callout will never have multiple concurrent invocations. +.Sh SEE ALSO +.Xr condvar 9 , +.Xr hz 9 , +.Xr softint 9 , +.Xr workqueue 9 +.Sh HISTORY +The +.Nm callout +facility was implemented by Artur Grabowski and Thomas Nordin, based +on the work of G. Varghese and A. Lauck, described in the paper +Hashed and Hierarchical Timing Wheels: Data Structures for the +Efficient Implementation of a Timer Facility +in the Proceedings of the 11th ACM Annual Symposium on Operating System +Principles, Austin, Texas, November 1987. +It was adapted to the +.Nx +kernel by Jason R. Thorpe. diff --git a/static/netbsd/man9/cardbus.9 b/static/netbsd/man9/cardbus.9 new file mode 100644 index 00000000..bda79d1f --- /dev/null +++ b/static/netbsd/man9/cardbus.9 @@ -0,0 +1,328 @@ +.\" $NetBSD: cardbus.9,v 1.20 2016/02/15 22:37:54 riastradh Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 13, 2014 +.Dt CARDBUS 9 +.Os +.Sh NAME +.Nm Cardbus , +.Nm cardbus_attach_card , +.Nm cardbus_detach_card , +.Nm cardbus_function_enable , +.Nm cardbus_function_disable , +.Nm cardbus_mapreg_map , +.Nm cardbus_mapreg_unmap , +.Nm cardbus_get_capability , +.Nm cardbus_make_tag , +.Nm cardbus_conf_read , +.Nm cardbus_conf_write , +.Nm cardbus_intr_establish , +.Nm cardbus_intr_disestablish , +.Nm CARDBUS_VENDOR , +.Nm CARDBUS_PRODUCT , +.Nm Cardbus_function_enable , +.Nm Cardbus_function_disable , +.Nm Cardbus_mapreg_map , +.Nm Cardbus_mapreg_unmap , +.Nm Cardbus_make_tag , +.Nm Cardbus_conf_read , +.Nm Cardbus_conf_write +.Nd support for CardBus PC-Card devices +.Sh SYNOPSIS +.In sys/bus.h +.In dev/cardbus/cardbusvar.h +.In dev/cardbus/cardbusreg.h +.In dev/cardbus/cardbusdevs.h +.Ft int +.Fn cardbus_attach_card "struct cardbus_softc *csc" +.Ft void +.Fn cardbus_detach_card "struct cardbus_softc *csc" +.Ft int +.Fn cardbus_function_enable "struct cardbus_softc *csc" "int function" +.Ft int +.Fn cardbus_function_disable "struct cardbus_softc *csc" "int function" +.Ft int +.Fo cardbus_mapreg_map +.Fa "struct cardbus_softc *csc" "int cf" "int reg" +.Fa "pcireg_t type" "int busflags" "bus_space_tag_t *tagp" +.Fa "bus_space_handle_t *handlep" "bus_addr_t *basep" "bus_size_t *sizep" +.Fc +.Ft int +.Fn cardbus_mapreg_unmap "struct cardbus_softc *csc" "int cf" \ +"int reg" "bus_space_tag_t tag" "bus_space_handle_t handle" \ +"bus_size_t size" +.Ft int +.Fn cardbus_get_capability "cardbus_chipset_tag_t cc" \ +"cardbus_function_tag_t cf" "pcitag_t tag" "int capid" \ +"int *offsetp" "pcireg_t *valuep" +.Ft pcitag_t +.Fn cardbus_make_tag "cardbus_chipset_tag_t cc" "int cf" "int bus" \ +"int device" "int function" +.Ft pcireg_t +.Fn cardbus_conf_read "cardbus_chipset_tag_t cc" "int cf" \ +"pcitag_t tag" "int offs" +.Ft void +.Fn cardbus_conf_write "cardbus_chipset_tag_t cc" "int cf" \ +"pcitag_t tag" "int offs" "busreg_t val" +.Ft void * +.Fn cardbus_intr_establish "cardbus_chipset_tag_t cc" \ +"cardbus_function_tag_t cf" "cardbus_intr_handle_t irq" "int level" \ +"int (*handler)(void *)" "void *arg" +.Ft void +.Fn cardbus_intr_disestablish "cardbus_chipset_tag_t cc" \ +"cardbus_function_tag_t cf" "void *ih" +.Ft int +.Fn CARDBUS_VENDOR "pcireg_t id" +.Ft int +.Fn CARDBUS_PRODUCT "pcireg_t id" +.Ft int +.Fn Cardbus_function_enable "cardbus_devfunc_t ct" +.Ft int +.Fn Cardbus_function_disable "cardbus_devfunc_t ct" +.Ft int +.Fn Cardbus_mapreg_map "cardbus_devfunc_t ct" "int reg" \ +"pcireg_t type" "int busflags" "bus_space_tag_t *tagp" \ +"bus_space_handle_t *handlep" "bus_addr_t *basep" "bus_size_t *sizep" +.Ft int +.Fn Cardbus_mapreg_unmap "cardbus_devfunc_t ct" \ +"int reg" "bus_space_tag_t tag" "bus_space_handle_t handle" \ +"bus_size_t size" +.Ft pcitag_t +.Fn Cardbus_make_tag "cardbus_devfunc_t ct" +.Ft pcireg_t +.Fn Cardbus_conf_read "cardbus_devfunc_t ct" "pcitag_t tag" \ +"int offs" +.Ft void +.Fn Cardbus_conf_write "cardbus_devfunc_t ct" "pcitag_t tag" \ +"int offs" "busreg_t val" +.Sh DESCRIPTION +The machine-independent +.Nm +subsystem provides support for CardBus devices. +.Pp +The CardBus interface is an improvement to the PC-Card interface +supported by +.Xr pcmcia 9 . +It introduces several new capabilities such as 32-bit addressing, +33MHz operation, busmaster operation and 3.3 volt low-voltage power. +It remains compatible with all features of the PC-Card standard. +.Pp +The CardBus interface signaling protocol is derived from the PCI +signaling protocol. +There are some differences between PCI and CardBus, however operations +are identical for most functions implemented. +Since a 32-bit CardBus interface is also defined for 16-bit PC-Cards, +the same Card Services client to be used to manage both CardBus and +PCMCIA PC-Cards. +By interrogating the card upon detection of an insertion event, +.Nx +determines whether the card requires +.Nm +support or not, and then applies the appropriate power and signaling +protocol requirements. +.Sh DATA TYPES +Drivers attached to the CardBus will make use of the following +data types: +.Bl -tag -width compact +.It struct cardbus_attach_args +Devices have their identity recorded in this structure. +It contains the following members: +.Bd -literal + cardbus_devfunc_t ca_ct; + bus_space_tag_t ca_iot; /* CardBus I/O space tag */ + bus_space_tag_t ca_memt; /* CardBus MEM space tag */ + bus_dma_tag_t ca_dmat; /* DMA tag */ + u_int ca_device; + pcitag_t ca_tag; + pcireg_t ca_id; + pcireg_t ca_class; + cardbus_intr_line_t ca_intrline; /* interrupt info */ + struct cardbus_cis_info ca_cis; +.Ed +.El +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn cardbus_attach_card "csc" +Attaches the card on the slot by turning on the power, read and +analyse the tuple and sets configuration index. +This function returns the number of recognised device functions. +If no device functions are recognised it returns zero. +.It Fn cardbus_detach_card "csc" +Detaches the card on the slot by release resources and turning off the +power. +This function must not be called under interrupt context. +.It Fn cardbus_function_enable "csc" "function" +Enables device function +.Fa function +on the card. +Power will be applied if it hasn't already. +.It Fn cardbus_function_disable "csc" "function" +Disables device function +.Fa function +on the card. +When no device functions are enabled, the turn is turned off. +.It Fn cardbus_mapreg_map "csc" "cf" "reg" "type" "busflags" "tagp" "handlep" "basep" "sizep" +Maps bus-space on the value of Base Address Register (BAR) indexed by +.Fa reg +for device function +.Fa cf . +The bus-space configuration is returned in +.Fa tagp , +.Fa handlep , +.Fa basep , +and +.Fa sizep . +.It Fn cardbus_mapreg_unmap "csc" "cf" "reg" "tag" "handle" "bus_size_t size" +Releases bus-space region for device function +.Fa cf +specified by +.Fa tag , +.Fa handle +and +.Fa size . +.Fa reg +is the offset of the BAR register. +.It Fn cardbus_get_capability "cc" "cf" "tag" "capid" "offsetp" "valuep" +Find the PCI capability for the device function +.Fa cf +specified by +.Fa capid . +Returns the capability in +.Fa offsetp +and +.Fa valuep . +.It Fn cardbus_make_tag "cc" "cf" "bus" "device" "function" +Make a tag to access config space of a CardBus card. +It works the same as +.Fn pci_make_tag . +.It Fn cardbus_conf_read "cc" "cf" "tag" "offs" +Read the config space of a CardBus card. +It works the same as +.Fn pci_conf_read . +.It Fn cardbus_conf_write "cc" "cf" "tag" "offs" "val" +Write to the config space of a CardBus card. +It works same as +.Fn pci_conf_write . +.It Fn cardbus_intr_establish "cc" "cf" "irq" "level" "handler" "arg" +Establish an interrupt handler for device function +.Fa cf . +The priority of the interrupt is specified by +.Fa level . +When the interrupt occurs the function +.Fa handler +is called with argument +.Fa arg . +The return value is a handle for the interrupt handler. +.Fn cardbus_intr_establish +returns an opaque handle to an event descriptor if it succeeds, and +returns NULL on failure. +.It Fn cardbus_intr_disestablish "cc" "cf" "ih" +Dis-establish the interrupt handler for device function +.Fa cf +with handle +.Fa ih . +The handle was returned from +.Fn cardbus_intr_establish . +.It Fn CARDBUS_VENDOR "id" +Return the CardBus vendor ID for device +.Fa id . +.It Fn CARDBUS_PRODUCT "id" +Return the CardBus product ID for device +.Fa id . +.El +.Pp +The +.Fn Cardbus_* +functions are convenience functions taking a +.Fa cardbus_devfunc_t +argument and perform the same operation as their namesake described +above. +.Sh AUTOCONFIGURATION +During autoconfiguration, a +.Nm +driver will receive a pointer to +.Fa struct cardbus_attach_args +describing the device attaches to the CardBus. +Drivers match the device using the +.Fa ca_id +member using +.Fn CARDBUS_VENDOR +and +.Fn CARDBUS_PRODUCT . +.Pp +During the driver attach step, drivers should initially map the device +I/O and memory resources using +.Fn cardbus_mapreg_map +or +.Fn Cardbus_mapreg_map . +Upon successful allocation of resources, power can be +applied to the device with +.Fn cardbus_function_enable +or +.Fn Cardbus_function_enable . +so that device-specific interrogation can be performed. +Finally, power should be removed from the device using +.Fn cardbus_function_disable +or +.Fn Cardbus_function_disable . +.Pp +Since CardBus devices support dynamic configuration, drivers should +make use of +.Fn pmf 9 +framework. +Power can be applied and the interrupt handler should be established +through this interface. +.Sh DMA SUPPORT +No additional support is provided for CardBus DMA beyond the +facilities provided by the +.Xr bus_dma 9 +interface. +.Sh CODE REFERENCES +The CardBus subsystem itself is implemented within the files +.Pa sys/dev/cardbus/cardbus.c , +.Pa sys/dev/cardbus/cardbus_map.c +and +.Pa sys/dev/cardbus/cardslot.c . +The database for PCI devices is also used for known CardBus devices. +For more details see +.Xr pci 9 . +.Sh SEE ALSO +.Xr cardbus 4 , +.Xr pcmcia 4 , +.Xr autoconf 9 , +.Xr bus_dma 9 , +.Xr bus_space 9 , +.Xr driver 9 , +.Xr pci 9 , +.Xr pcmcia 9 +.Sh HISTORY +The machine-independent +.Nm +subsystem appeared in +.Nx 1.5 . diff --git a/static/netbsd/man9/clock.9 b/static/netbsd/man9/clock.9 new file mode 100644 index 00000000..fbbc490f --- /dev/null +++ b/static/netbsd/man9/clock.9 @@ -0,0 +1,103 @@ +.\" $NetBSD: clock.9,v 1.2 2014/12/26 14:15:18 wiz Exp $ +.\" +.\" Copyright (c) 2014 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is contributed to The NetBSD Foundation by Kamil Rytarowski +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 26, 2014 +.Dt CLOCK 9 +.Os +.Sh NAME +.Nm days_in_month , +.Nm is_leap_year , +.Nm days_per_year +.Nd handy time utilities +.Sh SYNOPSIS +.In sys/clock.h +.Vt #define SECS_PER_MINUTE 60 +.Vt #define SECS_PER_HOUR 3600 +.Vt #define SECS_PER_DAY 86400 +.Vt #define DAYS_PER_COMMON_YEAR 365 +.Vt #define DAYS_PER_LEAP_YEAR 366 +.Vt #define SECS_PER_COMMON_YEAR (SECS_PER_DAY * DAYS_PER_COMMON_YEAR) +.Vt #define SECS_PER_LEAP_YEAR (SECS_PER_DAY * DAYS_PER_LEAP_YEAR) +.Ft static inline int +.Fn days_in_month "int m" +.Ft static inline int +.Fn is_leap_year "uint64_t year" +.Ft static inline int +.Fn days_per_year "uint64_t year" +.Sh DESCRIPTION +The +.In sys/clock.h +file provides handy time constants and +.Ft static inline +functions. +.Sh FUNCTIONS +The +.Fn days_in_month +function returns the number of days in the given month. +.Fn days_in_month +assumes 28 days for February. +If the input value is out of the valid range (1-12) then the function returns +\-1. +.Pp +The +.Fn is_leap_year +and +.Fn days_per_year +functions take as the input parameter a value in the Gregorian year format. +.Sh SEE ALSO +.Xr bintime 9 , +.Xr boottime 9 , +.Xr time_second 9 , +.Xr time_uptime 9 , +.Xr todr_gettime 9 +.Sh HISTORY +The +.In sys/clock.h +header with handy utilities originated from +.In dev/clock_subr.h , +which originated from +.In arch/hp300/hp300/clock.c . +.Pp +The +.In arch/hp300/hp300/clock.c +file first appeared in +.Nx 0.8 +as a set of hp300 time-converting functions. +.In dev/clock_subr.h +first appeared in +.Nx 1.3 +as a shared list of functions to convert between +.Dq year/month/day/hour/minute/second +and seconds since 1970 +.Pq Dq POSIX time . +The +.In sys/clock.h +file first appeared in +.Nx 8 . +.Sh AUTHORS +.An Kamil Rytarowski diff --git a/static/netbsd/man9/cnmagic.9 b/static/netbsd/man9/cnmagic.9 new file mode 100644 index 00000000..2ab75c28 --- /dev/null +++ b/static/netbsd/man9/cnmagic.9 @@ -0,0 +1,198 @@ +.\" $NetBSD: cnmagic.9,v 1.17 2024/09/07 19:13:29 rillig Exp $ +.\" +.\" Copyright (c) 2000 Eduardo Horvath +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the +.\" NetBSD Project. See https://www.NetBSD.org/ for +.\" information about NetBSD. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" --(license Id: LICENSE.proto,v 1.1 2000/06/13 21:40:26 cgd Exp )-- +.\" +.Dd July 7, 2019 +.Dt CNMAGIC 9 +.Os +.Sh NAME +.Nm cn_init_magic , +.Nm cn_trap , +.Nm cn_isconsole , +.Nm cn_check_magic , +.Nm cn_destroy_magic , +.Nm cn_set_magic , +.Nm cn_get_magic +.Nd console magic key sequence management +.Sh SYNOPSIS +.In sys/systm.h +.Ft void +.Fn cn_init_magic "cnm_state_t *cnms" +.Ft void +.Fn cn_trap +.Ft int +.Fn cn_isconsole "dev_t dev" +.Ft void +.Fn cn_check_magic "dev_t dev" "int k" "cnm_state_t *cnms" +.Ft void +.Fn cn_destroy_magic "cnm_state_t *cnms" +.Ft int +.Fn cn_set_magic "char *magic" +.Ft int +.Fn cn_get_magic "char *magic" "int len" +.Sh DESCRIPTION +The +.Nx +console magic key sequence management framework is designed to provide +flexible methods to set, change, and detect magic key sequences on console +devices and break into the debugger or ROM monitor with a minimum of interrupt +latency. +.Pp +Drivers that generate console input should make use of these routines. +A different +.Va cnm_state_t +should be used for each separate input stream. +Multiple devices that share the same input stream, such as USB +keyboards, can share the same +.Va cnm_state_t . +Once a +.Va cnm_state_t +is allocated, it should be initialized with +.Fn cn_init_magic +so it can be used by +.Fn cn_check_magic . +If a driver thinks it might be the console input device it can set the +magic sequence with +.Fn cn_set_magic +to any arbitrary string. +Whenever the driver receives input, it should call +.Fn cn_check_magic +to process the data and determine whether the magic sequence has +been hit. +.Pp +The magic key sequence can be accessed through the +.Va hw.cnmagic +.Ic sysctl +variable. +This is the raw data and may be keycodes rather than +processed characters, depending on the console device. +.Sh FUNCTIONS +The following functions describe the console magic interface. +.Bl -tag -width indent +.It Fn cn_init_magic "cnm" +Initialize the console magic state pointed to by +.Fa cnm +to a usable state. +.It Fn cn_trap +Trap into the kernel debugger or ROM monitor. +By default this routine is defined to be +.Fn console_debugger +but can be overridden in MI header files. +.It Fn cn_isconsole "dev" +Determine whether a given +.Fa dev +is the system console. +This macro tests to see if +.Fa dev +is the same as +.Va cn_tab->cn_dev +but can be overridden in MI header files. +.It Fn cn_check_magic "dev" "k" "cnms" +All input should be passed through +.Fn cn_check_magic +so the state machine remains in a consistent state. +.Fn cn_check_magic +calls +.Fn cn_isconsole +with +.Fa dev +to determine if this is the console. +If that returns true then it runs the input value +.Fa k +through the state machine. +If the state machine completes a match of the current console magic sequence +.Fn cn_trap +is called. +Some input may need to be translated to state machine +values such as the serial line +.Li BREAK +sequence. +.It Fn cn_destroy_magic "cnms" +This should be called once what +.Fa cnms +points to is no longer needed. +.It Fn cn_set_magic "magic" +.Fn cn_set_magic +encodes a +.Li nul +terminated arbitrary string into values that can be used by +the state machine and installs it as the global magic sequence. +The escape sequence is character value +.Li 0x27 +and can be used to encode special values: +.Pp +.Bl -tag -width "0x001" -compact -offset indent +.It 0x27 +The literal value +.Li 0x27 . +.It 0x01 +Serial +.Li BREAK +sequence. +.It 0x02 +.Li Nul +character. +.El +.Pp +Returns +.Li 0 +on success or a non-zero error value. +.It Fn cn_get_magic "magic" "len" +Extract the current magic sequence from the state machine and return +up to +.Fa len +bytes of it in the buffer pointed to by +.Fa magic . +It uses the same encoding accepted by +.Fn cn_set_magic . +Returns +.Li 0 +on success or a non-zero error value. +.El +.Sh SEE ALSO +.Xr ddb 4 , +.Xr sysctl 8 , +.Xr cons 9 +.Sh HISTORY +The +.Nx +console magic key sequence management framework +first appeared in +.Nx 1.6 . +.Sh AUTHORS +The +.Nx +console magic key sequence management framework was designed and +implemented by +.An Eduardo Horvath +.Aq eeh@NetBSD.org . diff --git a/static/netbsd/man9/condvar.9 b/static/netbsd/man9/condvar.9 new file mode 100644 index 00000000..535b63e6 --- /dev/null +++ b/static/netbsd/man9/condvar.9 @@ -0,0 +1,379 @@ +.\" $NetBSD: condvar.9,v 1.31 2023/09/07 20:01:43 ad Exp $ +.\" +.\" 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 +.\" by Andrew Doran. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 7, 2023 +.Dt CONDVAR 9 +.Os +.Sh NAME +.Nm cv , +.Nm condvar , +.Nm cv_init , +.Nm cv_destroy , +.Nm cv_wait , +.Nm cv_wait_sig , +.Nm cv_timedwait , +.Nm cv_timedwait_sig , +.Nm cv_timedwaitbt , +.Nm cv_timedwaitbt_sig , +.Nm cv_signal , +.Nm cv_broadcast , +.Nm cv_has_waiters +.Nd condition variables +.Sh SYNOPSIS +.In sys/condvar.h +.Ft void +.Fn cv_init "kcondvar_t *cv" "const char *wmesg" +.Ft void +.Fn cv_destroy "kcondvar_t *cv" +.Ft void +.Fn cv_wait "kcondvar_t *cv" "kmutex_t *mtx" +.Ft int +.Fn cv_wait_sig "kcondvar_t *cv" "kmutex_t *mtx" +.Ft int +.Fn cv_timedwait "kcondvar_t *cv" "kmutex_t *mtx" "int ticks" +.Ft int +.Fn cv_timedwait_sig "kcondvar_t *cv" "kmutex_t *mtx" "int ticks" +.Ft int +.Fn cv_timedwaitbt "kcondvar_t *cv" "kmutex_t *mtx" "struct bintime *bt" \ +"const struct bintime *epsilon" +.Ft int +.Fn cv_timedwaitbt_sig "kcondvar_t *cv" "kmutex_t *mtx" "struct bintime *bt" \ +"const struct bintime *epsilon" +.Ft void +.Fn cv_signal "kcondvar_t *cv" +.Ft void +.Fn cv_broadcast "kcondvar_t *cv" +.Ft bool +.Fn cv_has_waiters "kcondvar_t *cv" +.Pp +.Cd "options DIAGNOSTIC" +.Cd "options LOCKDEBUG" +.Sh DESCRIPTION +Condition variables (CVs) are used in the kernel to synchronize access +to resources that are limited (for example, memory) and to wait for +pending I/O operations to complete. +.Pp +The +.Vt kcondvar_t +type provides storage for the CV object. +This should be treated as an opaque object and not examined directly by +consumers. +.Sh OPTIONS +.Bl -tag -width abcd +.It Cd "options DIAGNOSTIC" +.Pp +Kernels compiled with the +.Dv DIAGNOSTIC +option perform basic sanity checks on CV operations. +.It Cd "options LOCKDEBUG" +.Pp +Kernels compiled with the +.Dv LOCKDEBUG +option perform potentially CPU intensive sanity checks +on CV operations. +.El +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn cv_init "cv" "wmesg" +.Pp +Initialize a CV for use. +No other operations can be performed on the CV until it has been initialized. +.Pp +The +.Fa wmesg +argument specifies a string of no more than 8 characters that describes +the resource or condition associated with the CV. +The kernel does not use this argument directly but makes it available for +utilities such as +.Xr ps 1 +to display. +.It Fn cv_destroy "cv" +.Pp +Release resources used by a CV. +If there could be waiters, they should be awoken first with +.Fn cv_broadcast . +The CV must not be used afterwards. +.It Fn cv_wait "cv" "mtx" +.Pp +Cause the current LWP to wait non-interruptably for access to a resource, +or for an I/O operation to complete. +The LWP will resume execution when awoken by another thread using +.Fn cv_signal +or +.Fn cv_broadcast . +.Pp +.Fa mtx +specifies a kernel mutex to be used as an interlock, and must be held by the +calling LWP on entry to +.Fn cv_wait . +It will be released once the LWP has prepared to sleep, and will be reacquired +before +.Fn cv_wait +returns. +.Pp +A small window exists between testing for availability of a resource and +waiting for the resource with +.Fn cv_wait , +in which the resource may become available again. +The interlock is used to guarantee that the resource will not be signalled +as available until the calling LWP has begun to wait for it. +.Pp +Non-interruptable waits have the potential to deadlock the system, and so must +be kept short (typically, under one second). +.Pp +.Fn cv_wait +is typically used within a loop or restartable code sequence, because it +may awaken spuriously. +The calling LWP should re-check the condition that caused the wait. +If necessary, the calling LWP may call +.Fn cv_wait +again to continue waiting. +.It Fn cv_wait_sig "cv" "mtx" +.Pp +As per +.Fn cv_wait , +but causes the current LWP to wait interruptably. +If the LWP receives a signal, or is interrupted by another condition such +as its containing process exiting, the wait is ended early and an error +code returned. +.Pp +If +.Fn cv_wait_sig +returns as a result of a signal, the return value is +.Er ERESTART +if the signal +has the +.Dv SA_RESTART +property. +If awoken normally, the value is zero, and +.Er EINTR +under all other conditions. +.It Fn cv_timedwait "cv" "mtx" "ticks" +.Pp +As per +.Fn cv_wait , +but will return early if a timeout specified by the +.Fa ticks +argument expires. +.Pp +.Fa ticks +is an architecture and system dependent value related to the number of +clock interrupts per second. +See +.Xr hz 9 +for details. +The +.Xr mstohz 9 +macro can be used to convert a timeout expressed in milliseconds to +one suitable for +.Fn cv_timedwait . +If the +.Fa ticks +argument is zero, +.Fn cv_timedwait +behaves exactly like +.Fn cv_wait . +.Pp +If the timeout expires before the LWP is awoken, the return value is +.Er EWOULDBLOCK . +If awoken normally, the return value is zero. +.It Fn cv_timedwait_sig "cv" "mtx" "ticks" +.Pp +As per +.Fn cv_wait_sig , +but also accepts a timeout value and will return +.Er EWOULDBLOCK +if the timeout expires. +.It Fn cv_timedwaitbt "cv" "mtx" "bt" "epsilon" +.It Fn cv_timedwaitbt_sig "cv" "mtx" "bt" "epsilon" +.Pp +As per +.Fn cv_wait +and +.Fn cv_wait_sig , +but will return early if the duration +.Fa bt +has elapsed, immediately if +.Fa bt +is zero. +On return, +.Fn cv_timedwaitbt +and +.Fn cv_timedwaitbt_sig +subtract the time elapsed from +.Fa bt +in place, or set it to zero if there is no time remaining. +.Pp +Note that +.Fn cv_timedwaitbt +and +.Fn cv_timedwaitbt_sig +may return zero indicating success, rather than +.Er EWOULDBLOCK , +even if they set the timeout to zero; this means that the caller must +re-check the condition in order to avoid potentially losing a +.Fn cv_signal , +but the +.Em next +wait will time out immediately. +.Pp +The hint +.Fa epsilon , +which can be +.Dv DEFAULT_TIMEOUT_EPSILON +if in doubt, requests that the wakeup not be delayed more than +.Fa bt Li "+" Fa epsilon , +so that the system can coalesce multiple wakeups within their +respective epsilons into a single high-resolution clock interrupt or +choose to use cheaper low-resolution clock interrupts instead. +.Pp +However, the system is still limited by its best clock interrupt +resolution and by scheduling competition, which may delay the wakeup by +more than +.Fa bt Li "+" Fa epsilon . +.It Fn cv_signal "cv" +.Pp +Awaken one LWP waiting on the specified condition variable. +Where there are waiters sleeping non-interruptaby, more than one +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 +should be held or have been released immediately before +.Fn cv_signal +is called. +.Pp +(Note that +.Fn cv_signal +is erroneously named in that it does not send a signal in the traditional +sense to LWPs waiting on a CV.) +.It Fn cv_broadcast "cv" +.Pp +Awaken all LWPs waiting on the specified condition variable. +.Pp +As with +.Fn cv_signal , +the mutex passed to the wait function +.Po Fa mtx Pc +should be held or have been released immediately before +.Fn cv_broadcast +is called. +.It Fn cv_has_waiters "cv" +.Pp +Return +.Dv true +if one or more LWPs are waiting on the specified condition variable. +.Pp +.Fn cv_has_waiters +cannot test reliably for interruptable waits. +It should only be used to test for non-interruptable waits +made using +.Fn cv_wait . +.Pp +.Fn cv_has_waiters +should only be used when making diagnostic assertions, and must +be called while holding the interlocking mutex passed to +.Fn cv_wait . +.El +.Sh EXAMPLES +Consuming a resource: +.Bd -literal + /* + * Lock the resource. Its mutex will also serve as the + * interlock. + */ + mutex_enter(&res->mutex); + + /* + * Wait for the resource to become available. Timeout after + * five seconds. If the resource is not available within the + * allotted time, return an error. + */ + struct bintime timeout = { .sec = 5, .frac = 0 }; + while (res->state == BUSY) { + error = cv_timedwaitbt(&res->condvar, + &res->mutex, &timeout, DEFAULT_TIMEOUT_EPSILON); + if (error) { + KASSERT(error == EWOULDBLOCK); + mutex_exit(&res->mutex); + return ETIMEDOUT; + } + } + + /* + * It's now available to us. Take ownership of the + * resource, and consume it. + */ + res->state = BUSY; + mutex_exit(&res->mutex); + consume(res); +.Ed +.Pp +Releasing a resource for the next consumer to use: +.Bd -literal + mutex_enter(&res->mutex); + res->state = IDLE; + cv_signal(&res->condvar); + mutex_exit(&res->mutex); +.Ed +.Sh CODE REFERENCES +The core of the CV implementation is in +.Pa sys/kern/kern_condvar.c . +.Pp +The header file +.Pa sys/sys/condvar.h +describes the public interface. +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr membar_ops 3 , +.Xr errno 9 , +.Xr mstohz 9 , +.Xr mutex 9 , +.Xr rwlock 9 +.Pp +.Rs +.%A Jim Mauro +.%A Richard McDougall +.%T Solaris Internals: Core Kernel Architecture +.%I Prentice Hall +.%D 2001 +.%O ISBN 0-13-022496-0 +.Re +.Sh HISTORY +The CV primitives first appeared in +.Nx 5.0 . +The +.Fn cv_timedwaitbt +and +.Fn cv_timedwaitbt_sig +primitives first appeared in +.Nx 9.0 . diff --git a/static/netbsd/man9/config.9 b/static/netbsd/man9/config.9 new file mode 100644 index 00000000..51a925df --- /dev/null +++ b/static/netbsd/man9/config.9 @@ -0,0 +1,352 @@ +.\" $NetBSD: config.9,v 1.30 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 3, 2010 +.Dt CONFIG 9 +.Os +.Sh NAME +.Nm config +.Nd the autoconfiguration framework +.Do +device definition +.Dc +language +.Sh DESCRIPTION +In +.Nx , +the +.Xr config 1 +program reads and verifies a machine description file (documented in +.Xr config 5 ) +that specifies the devices to include in the kernel. +A table is produced by +.Xr config 1 +which is used by the kernel during autoconfiguration (see +.Xr autoconf 9 ) +giving needed hints and details on matching hardware devices with +device drivers. +.Pp +Each device in the machine description file has: +.Bl -tag -width xxxxxx +.It A Name +The name is simply an alphanumeric string that ends in a unit number +(e.g., "sd0", "sd1", and so forth). +These unit numbers identify particular instances of a base device name; +the base name in turn maps directly to a device driver. +Device unit numbers are independent of hardware features. +.It A Parent +Every device must have a parent. +The pairing is denoted by "child at parent". +These pairings form the links in a directed graph. +The root device is the only exception, as it does not have a parent. +.It Locators +Locators are used to augment the parent/child pairings that locate +specific devices. +Each locator value is simply an integer that represents some sort of +device address on the parent bus or controller. +This can be a memory address, an I/O port, a driver number, or any +other value. +Locators can sometimes be wildcarded on devices that support direct +connection. +.It Attributes +An attribute describes the device's relationship with the code; it +then serves to constrain the device graph. +A +.Em plain attribute +describes some attribute of a device. +An +.Em interface attribute +describes a kind of +.Do +software interface +.Dc +and declares the device's ability to support other devices that use +that interface. +In addition, an interface attribute usually identifies additional locators. +.El +.Pp +During autoconfiguration, the directed graph is turned into a tree by +nominating one device as the root node and matching drivers with +devices by doing a depth-first traversal through the graph starting at +this root node. +.Pp +However, there must be constraints on the parent/child pairings that +are possible. +These constraints are embedded in the +.Do +device definition +.Dc +files. +The remainder of this page describes the +.Do +device definition +.Dc +language and how to use this language to add new functionality to the +.Nx +kernel. +.Sh DEVICE DEFINITION FILES +The device definition files are separated into machine-dependent and +machine-independent files. +The machine-dependent file is located in +.Pa sys/arch/<arch>/conf/files.<arch> , +where <arch> is the name of +.Nx +architecture. +The machine-independent file is located in +.Pa sys/conf/files . +It in turn includes files for the machine-independent drivers located +in +.Pa sys/dev/<bus>/files.<bus> , +where <bus> is the name of the machine-independent bus. +.Pp +These files define all legal devices and pseudo-devices. +They also define all attributes and interfaces, establishing the rules that +determine allowable machine descriptions, and list the source files +that make up the kernel. +.Pp +Each device definition file consists of a list of statements, +typically one per line. +Comments may be inserted anywhere using the +.Do +# +.Dc +character, and any line that begins with white space continues the +previous line. +Valid statements are: +.Bl -tag -width xxxxxx +.It cinclude filename +Conditionally include contents of file +.Ar filename +to currently processed configuration. +If the specified +.Ar filename +doesn't exist, a warning is printed, but the error +ignored. +.It defflag [filename] {options} +The space-separated list of pre-processor macros +.Em options +are defined in file +.Em filename . +This statement permits ``options FOO'' for FOO (i.e, without a value) +in the machine description file. +.Xr config 1 +will generate an error if a value is given. +If the filename field is not specified, it will be constructed based upon +the lower-case of the option name, ``opt_foo.h'' for example. +The +.Em option +is case-sensitive. +.It defparam [filename] {options} +The space-separated list of pre-processor macros +.Em options +are defined in file +.Em filename . +This statement permits ``options FOO=bar'' or ``option FOO="\e"com\e""'' +in the machine description file. +.Xr config 1 +will generate an error if a value is not given. +If the filename field is not specified, it will be constructed based upon +the lower-case of the option name, ``opt_foo.h'' for example. +The +.Em option +is case-sensitive. +.It defopt [filename] {options} +The space-separated list of pre-processor macros +.Em options +are defined in file +.Em filename . +This statement permits the syntax of either the defflag and defparam +statements and +.Xr config 1 +does not perform any checking of whether ``options FOO'' takes a +value. +Therefore, the use of the defopt statement is deprecated in +favour of the defflag and defparam statements. +If the filename field is not specified, it will be constructed based upon +the lower-case of the option name, ``opt_foo.h'' for example. +The +.Em option +is case-sensitive. +.It deffs name [[name] ...] +Define a filesystem +.Em name . +.It devclass name +Define a device class +.Em name . +A device class is similar to an attribute. +.It define name [{locators}] +The attribute +.Em name +is defined and device definitions can then refer to it. +If the attribute is an interface attribute and defines optional +.Em locators , +device attributes that refer to +.Em name +are assumed to share the interface and require the same locators. +.It device name [{locators}]: [attributes] +The device +.Em name +is defined and requires the optional comma-separated list of locators +.Em locators . +The optional +.Em attributes +define attribute dependencies. +.It attach name at interface [with ifname]: [attributes] +The device +.Em name +is defined and supports the interface +.Em interface . +If +.Em ifname +is specified, it is used to specify the interface to the driver for +device +.Em name +(see +.Xr driver 9 +for details). +The optional +.Em attributes +define attribute dependencies. +.It defpseudo name: [{locators}] +The pseudo-device +.Em name +is defined. +The optional +.Em locators +may be defined, but are largely pointless since no device can attach +to a pseudo-device. +.It file pathname [attributes [flags]] [rule] +The file +.Em pathname +is added to the list of files used to build the kernel. +If no attributes are specified, the file is always added to the kernel +compilation. +If any of the attributes are specified by other devices in the machine +description file, then the file is included in compilation, otherwise it +is omitted. +Valid values for the optional flags are: +.Bl -tag -width xxxxxx +.It needs-count +Specify that config should generate a file for each of the attributes +notifying the driver how many of some particular device or set of +devices are configured in the kernel. +This flag allows drivers to make calculations of driver used at compile time. +This option prevents autoconfiguration cloning. +.It needs-flag +This flag performs the same operation as +.Em needs-count +but only records if the number is nonzero. +Since the count is not exact, +.Em needs-flag +does not prevent autoconfiguration cloning. +.El +.It device-major name char [block] [attributes] +The character device switch +.Em name +associated with a character major device number is added to the list of +device switches used to build the kernel. +If +.Em block +is specified, the block device switch associated with a block major device +number is also added. +If all of attributes are specified by devices in the machine description +files, then device switches are added into the device switches' table of +the kernel in compilation, otherwise they are omitted. +.It include Ar filename +Include contents of file +.Ar filename +to currently processed configuration. +If the specified +.Ar filename +doesn't exist, +.Xr config 1 +exits with error. +.It package Ar filename +Changes prefix to directory of +.Ar filename , +processes contents of +.Ar filename , +and switches back to previous prefix. +This is syntactic sugar for: +.Bd -literal -compact -offset indent +.Li prefix Ar dirname(filename) +.Li include Ar basename(filename) +.Li prefix +.Ed +.It prefix Op Ar dirname +If +.Ar dirname +is specified, it is pushed on top of prefix stack. +Any further files specified via option +.Ar file +would have the prefix implicitly prepended before its +.Ar filename . +If +.Ar dirname +is not specified, pops (removes) a prefix from prefix stack. +.El +.Pp +To allow locators to be wildcarded in the machine description file, +their default value must be defined in the attribute definition. +To allow locators to be omitted entirely in the machine description file, +enclose the locator in square brackets. +This can be used when some locators do not make sense for some devices, +but the software interface requires them. +.Sh CODE REFERENCES +The device definition files are in +.Pa sys/conf/files , +.Pa sys/arch/<arch>/conf/files.<arch> , +and +.Pa sys/dev/<bus>/files.<bus> . +.Pp +The grammar for machine description files can be found in +.Xr config 1 , +in +.Pa usr.bin/config/gram.y . +.Sh SEE ALSO +.Xr config 1 , +.Xr config 5 , +.Xr autoconf 9 , +.Xr driver 9 +.Rs +.%T "Building 4.4 BSD Systems with Config" +.Re +.Rs +.%A Chris Torek +.%T "Device Configuration in 4.4BSD" +.%D 1992 +.Re +.Sh HISTORY +Autoconfiguration first appeared in +.Bx 4.1 . +The autoconfiguration framework was completely revised in +.Bx 4.4 . +It has been modified within +.Nx +to support bus-independent drivers and bus-dependent attachments. diff --git a/static/netbsd/man9/cons.9 b/static/netbsd/man9/cons.9 new file mode 100644 index 00000000..42db38b2 --- /dev/null +++ b/static/netbsd/man9/cons.9 @@ -0,0 +1,161 @@ +.\" $NetBSD: cons.9,v 1.19 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 8, 2010 +.Dt CONS 9 +.Os +.Sh NAME +.Nm cnbell , +.Nm cnflush , +.Nm cngetc , +.Nm cngetsn , +.Nm cnhalt , +.Nm cnpollc , +.Nm cnputc +.Nd console access interface +.Sh SYNOPSIS +.In dev/cons.h +.Ft void +.Fn cnbell "u_int pitch" "u_int period" "u_int volume" +.Ft void +.Fn cnflush "void" +.Ft int +.Fn cngetc "void" +.Ft int +.Fn cngetsn "char *cp" "int size" +.Ft void +.Fn cnhalt "void" +.Ft void +.Fn cnpollc "int on" +.Ft void +.Fn cnputc "int c" +.Sh DESCRIPTION +These functions operate over the current console device. +The console must be initialized before these functions can be used. +.Pp +Console input polling functions +.Fn cngetc , +.Fn cngetsn +and +.Fn cnpollc +are only to be used during initial system +boot, e.g., when asking for root and dump device or to get +necessary user input within mountroothooks. +Once the system boots, user input is read via standard +.Xr tty 4 +facilities. +.Pp +The following is a brief description of each function: +.Bl -tag -width "cngetsn()" +.It Fn cnbell +Ring a bell at appropriate +.Fa pitch , +for duration of +.Fa period +milliseconds at given +.Fa volume . +Note that the +.Fa volume +value is ignored commonly. +.It Fn cnflush +Waits for all pending output to finish. +.It Fn cngetc +Poll (busy wait) for an input and return the input key. +Returns 0 if there is no console input device. +.Fn cnpollc +.Em must +be called before +.Fn cngetc +could be used. +.Fn cngetc +should be used during kernel startup only. +.It Fn cngetsn +Read one line of user input, stop reading once the newline +key is input. +Input is echoed back. +This uses +.Fn cnpollc +and +.Fn cngetc . +Number of read characters is +.Fa size +at maximum, user is notified by console bell when the end +of input buffer is reached. +<Backspace> key works as expected. +<@> or <CTRL>-u make +.Fn cngetsn +discard input read so far, print newline and +wait for next input. +.Fn cngetsn +returns number of characters actually read, excluding +the final newline. +.Fa cp +is +.Em not +zero-ended before return. +.Fn cngetsn +should be used during kernel startup only. +.It Fn cnhalt +Terminates the console device (i.e. cleanly shuts down the console hardware.) +.It Fn cnpollc +Switch the console driver to polling mode if +.Fa on +is nonzero, or back to interrupt driven mode if +.Fa on +is zero. +.Fn cnpollc +should be used during kernel startup only. +.It Fn cnputc +Console kernel output character routine. +Commonly, kernel code uses +.Xr printf 9 +rather than using this low-level interface. +.El +.Sh EXAMPLES +This waits until a <Enter> key is pressed: +.Pp +.Bd -literal -offset indent +int c; + +cnpollc(1); +for(;;) { + c = cngetc(); + if ((c == '\er' || (c == '\en')) { + printf("\en"); + break; + } +} +cnpollc(0); +.Ed +.Sh SEE ALSO +.Xr pckbd 4 , +.Xr pcppi 4 , +.Xr tty 4 , +.Xr wscons 4 , +.Xr wskbd 4 , +.Xr printf 9 , +.Xr spl 9 , +.Xr wscons 9 diff --git a/static/netbsd/man9/copy.9 b/static/netbsd/man9/copy.9 new file mode 100644 index 00000000..1e1f4d37 --- /dev/null +++ b/static/netbsd/man9/copy.9 @@ -0,0 +1,180 @@ +.\" $NetBSD: copy.9,v 1.22 2019/09/01 19:08:22 wiz Exp $ +.\" +.\" Copyright (c) 1996, 2002 Jason R. Thorpe. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed by Kenneth Stailey. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Jason R. Thorpe. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 28, 2005 +.Dt COPY 9 +.Os +.Sh NAME +.Nm copy , +.Nm copyin , +.Nm copyout , +.Nm copystr , +.Nm copyinstr , +.Nm copyoutstr +.Nd kernel space to/from user space copy functions +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft int +.Fn copyin "const void *uaddr" "void *kaddr" "size_t len" +.Ft int +.Fn copyout "const void *kaddr" "void *uaddr" "size_t len" +.Ft int +.Fn copystr "const void *kfaddr" "void *kdaddr" "size_t len" "size_t *done" +.Ft int +.Fn copyinstr "const void *uaddr" "void *kaddr" "size_t len" "size_t *done" +.Ft int +.Fn copyoutstr "const void *kaddr" "void *uaddr" "size_t len" "size_t *done" +.Ft int +.Fn copyin_proc "struct proc *p" "const void *uaddr" "void *kaddr" "size_t len" +.Ft int +.Fn copyout_proc "struct proc *p" "const void *kaddr" "void *uaddr" "size_t len" +.Ft int +.Fn ioctl_copyin "int ioctlflags" "const void *src" "void *dst" "size_t len" +.Ft int +.Fn ioctl_copyout "int ioctlflags" "const void *src" "void *dst" "size_t len" +.Sh DESCRIPTION +The +.Nm +functions are designed to copy contiguous data from one address +to another. +All but +.Fn copystr +copy data from user-space to kernel-space or vice-versa. +.Pp +The +.Nm +routines provide the following functionality: +.Bl -tag -width "copyout_proc()" +.It Fn copyin +Copies +.Fa len +bytes of data from the user-space address +.Fa uaddr +in the current process to the kernel-space address +.Fa kaddr . +.It Fn copyout +Copies +.Fa len +bytes of data from the kernel-space address +.Fa kaddr +to the user-space address +.Fa uaddr +in the current process. +.It Fn copystr +Copies a NUL-terminated string, at most +.Fa len +bytes long, from kernel-space address +.Fa kfaddr +to kernel-space address +.Fa kdaddr . +If the +.Fa done +argument is non-NULL, +the number of bytes actually copied, including the terminating +NUL, is returned in +.Fa *done . +.It Fn copyinstr +Copies a NUL-terminated string, at most +.Fa len +bytes long, from user-space address +.Fa uaddr +in the current process to kernel-space address +.Fa kaddr . +If the +.Fa done +argument is non-NULL, +the number of bytes actually copied, including the terminating +NUL, is returned in +.Fa *done . +.It Fn copyoutstr +Copies a NUL-terminated string, at most +.Fa len +bytes long, from kernel-space address +.Fa kaddr +to user-space address +.Fa uaddr +in the current process. +If the +.Fa done +argument is non-NULL, +the number of bytes actually copied, including the terminating +NUL, is returned in +.Fa *done . +.It Fn copyin_proc +Like +.Fn copyin , +except it operates on the address space of the process +.Fa p . +.It Fn copyout_proc +Like +.Fn copyout , +except it operates on the address space of the process +.Fa p . +.It Fn ioctl_copyin +Like +.Fn copyin , +except it operates on kernel addresses when the +.Dv FKIOCTL +flag is passed in +.Fa ioctlflags +from the ioctl call. +.It Fn ioctl_copyout +Like +.Fn copyout , +except it operates on kernel addresses when the +.Dv FKIOCTL +flag is passed in +.Fa ioctlflags +from the ioctl call. +.El +.Sh RETURN VALUES +The +.Nm +functions return 0 on success or +.Er EFAULT +if a bad address is encountered. +In addition, the +.Fn copystr , +.Fn copyinstr , +and +.Fn copyoutstr +functions return +.Er ENAMETOOLONG +if the string is longer than +.Fa len +bytes. +.Sh SEE ALSO +.Xr ufetch 9 , +.Xr ustore 9 diff --git a/static/netbsd/man9/coredump_write.9 b/static/netbsd/man9/coredump_write.9 new file mode 100644 index 00000000..7639c179 --- /dev/null +++ b/static/netbsd/man9/coredump_write.9 @@ -0,0 +1,73 @@ +.\" $NetBSD: coredump_write.9,v 1.5 2010/12/02 12:54:13 wiz Exp $ +.\" +.\" Copyright (c) 2005 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Matt Thomas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 24, 2005 +.Dt COREDUMP_WRITE 9 +.Os +.Sh NAME +.Nm coredump_write +.Nd common coredump write routine +.Sh SYNOPSIS +.In sys/signalvar.h +.Ft int +.Fn coredump_write "void *iocookie" "enum uio_seg segflg" \ +"const void *data" "size_t len" +.Sh DESCRIPTION +.Fn coredump_write +is used by both machine-dependent and machine-independent components +to write information to a coredump. +.Fa iocookie +is an opaque pointer that was supplied to the caller of +.Fn coredump_write . +.Fa segflg +indicates where the +.Fa data +is located, system space or user space. +.Fa data +points to the information to be written to the coredump. +.Fa len +is the amount of data to be written. +.Pp +.Fn coredump_write +returns 0 on success and an appropriate error code on failure. +.Sh CODE REFERENCES +Process core dumps are initiated within the file +.Pa sys/kern/kern_sig.c . +Process core dumps for ELF +.Nx +binaries are performed within the files +.Pa sys/kern/core_elf32.c +or +.Pa sys/kern/core_elf64.c . +Process core dumps for other +.Nx +binaries are performed within the file +.Pa sys/kern/core_netbsd.c . +.Sh SEE ALSO +.Xr cpu_coredump 9 diff --git a/static/netbsd/man9/cprng.9 b/static/netbsd/man9/cprng.9 new file mode 100644 index 00000000..b7decf41 --- /dev/null +++ b/static/netbsd/man9/cprng.9 @@ -0,0 +1,264 @@ +.\" $NetBSD: cprng.9,v 1.16 2022/05/17 15:00:05 riastradh Exp $ +.\" +.\" Copyright (c) 2011-2015 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Thor Lancelot Simon and Taylor R. Campbell. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 16, 2020 +.Dt CPRNG 9 +.Os +.Sh NAME +.Nm cprng , +.Nm cprng_strong_create , +.Nm cprng_strong_destroy , +.Nm cprng_strong , +.Nm cprng_strong32 , +.Nm cprng_strong64 , +.Nm cprng_fast , +.Nm cprng_fast32 , +.Nm cprng_fast64 +.Nd cryptographic pseudorandom number generators +.Sh SYNOPSIS +.In sys/cprng.h +.Ft cprng_strong_t * +.Fn cprng_strong_create "const char *name" "int ipl" "int flags" +.Ft void +.Fn cprng_strong_destroy "cprng_strong_t *cprng" +.Ft size_t +.Fn cprng_strong "cprng_strong_t *cprng" "void *buf" "size_t len" "int flags" +.Ft uint32_t +.Fn cprng_strong32 "void" +.Ft uint64_t +.Fn cprng_strong64 "void" +.Ft size_t +.Fn cprng_fast "void *buf" "size_t len" +.Ft uint32_t +.Fn cprng_fast32 "void" +.Ft uint64_t +.Fn cprng_fast64 "void" +.Bd -literal +#define CPRNG_MAX_LEN 524288 +.Ed +.Sh DESCRIPTION +The +.Nm +family of functions provide cryptographic pseudorandom number +generators automatically seeded from the kernel entropy pool. +All applications in the kernel requiring random data or random choices +should use the +.Nm cprng_strong +family of functions, unless performance constraints demand otherwise. +.Pp +The +.Nm cprng_fast +family of functions may be used in applications that can tolerate +exposure of past random data, such as initialization vectors or +transaction ids that are sent over the internet anyway, if the +applications require higher throughput or lower per-request latency +than the +.Nm cprng_strong +family of functions provide. +If in doubt, choose +.Nm cprng_strong . +.Pp +A single instance of the fast generator serves the entire kernel. +A well-known instance of the strong generator, +.Dv kern_cprng , +may be used by any in-kernel caller, but separately seeded instances of +the strong generator can also be created by calling +.Fn cprng_strong_create . +.Pp +The +.Nm +functions may be used in soft interrupt context, +except for +.Fn cprng_strong_create +and +.Fn cprng_strong_destroy +which are allowed only at +.Dv IPL_NONE +in thread context; see +.Xr spl 9 . +.Pp +The +.Nm +functions replace the legacy +.Xr arc4random 9 +and +.Xr rnd_extract_data 9 +functions. +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn cprng_strong_create "name" "ipl" "flags" +Create an instance of the cprng_strong generator. +This generator currently implements the NIST SP 800-90A Hash_DRBG with +SHA-256 as the hash function. +.Pp +The +.Fa name +argument is used to +.Dq personalize +the Hash_DRBG according to the standard, so that its initial state will +depend both on seed material from the entropy pool and also on the +personalization string (name). +.Pp +The +.Fa ipl +argument specifies the interrupt priority level for the mutex which +will serialize access to the new instance of the generator (see +.Xr spl 9 ) , +and must be no higher than +.Dv IPL_SOFTSERIAL . +.Pp +The +.Fa flags +argument must be zero. +.Pp +Creation will succeed even if full entropy for the generator is not +available. +In this case, the first request to read from the generator may cause +reseeding. +.Pp +.Fn cprng_strong_create +may sleep to allocate memory. +.It Fn cprng_strong_destroy "cprng" +Destroy +.Fa cprng . +.Pp +.Fn cprng_strong_destroy +may sleep. +.It Fn cprng_strong "cprng" "buf" "len" "flags" +Fill memory location +.Fa buf +with up to +.Fa len +bytes from the generator +.Fa cprng , +and return the number of bytes. +.Fa len +must be at most +.Dv CPRNG_MAX_LEN . +.Fa flags +must be zero. +.It Fn cprng_strong32 +Generate 32 bits using the +.Dv kern_cprng +strong generator. +.Pp +.Fn cprng_strong32 +does not sleep. +.It Fn cprng_strong64 +Generate 64 bits using the +.Dv kern_cprng +strong generator. +.Pp +.Fn cprng_strong64 +does not sleep. +.It Fn cprng_fast "buf" "len" +Fill memory location +.Fa buf +with +.Fa len +bytes from the fast generator. +.Pp +.Fn cprng_fast +does not sleep. +.It Fn cprng_fast32 +Generate 32 bits using the fast generator. +.Pp +.Fn cprng_fast32 +does not sleep. +.It Fn cprng_fast64 +Generate 64 bits using the fast generator. +.Pp +.Fn cprng_fast64 +does not sleep. +.El +.Sh SECURITY MODEL +The +.Nm +family of functions provide the following security properties: +.Bl -bullet -offset abcd +.It +An attacker who has seen some outputs of any of the +.Nm +functions cannot predict past or future unseen outputs. +.It +An attacker who has compromised kernel memory cannot predict past +outputs of the +.Nm cprng_strong +functions. +However, such an attacker may be able to predict past outputs of the +.Nm cprng_fast +functions. +.El +.Pp +The second property is sometimes called +.Dq backtracking resistance , +.Dq forward secrecy , +or +.Dq key erasure +in the cryptography literature. +The +.Nm cprng_strong +functions provide backtracking resistance; +the +.Nm cprng_fast +functions do not. +.Sh CODE REFERENCES +The +.Nm cprng_strong +functions are implemented in +.Pa sys/kern/subr_cprng.c , +and use the NIST SP 800-90A Hash_DRBG implementation in +.Pa sys/crypto/nist_hash_drbg . +The +.Nm cprng_fast +functions are implemented in +.Pa sys/crypto/cprng_fast/cprng_fast.c , +and use the ChaCha8 stream cipher. +.Sh SEE ALSO +.Xr condvar 9 , +.Xr rnd 9 , +.Xr spl 9 +.Rs +.%A Elaine Barker +.%A John Kelsey +.%T Recommendation for Random Number Generation Using Deterministic Random Bit Generators (Revised) +.%I National Institute of Standards and Technology +.%D 2011 +.%O NIST Special Publication 800-90A, Rev 1 +.Re +.Rs +.%A Daniel J. Bernstein +.%T ChaCha, a variant of Salsa20 +.%D 2008-01-28 +.%O Document ID: 4027b5256e17b9796842e6d0f68b0b5e +.%U http://cr.yp.to/papers.html#chacha +.Re +.Sh HISTORY +The cprng family of functions first appeared in +.Nx 6.0 . diff --git a/static/netbsd/man9/cpu_configure.9 b/static/netbsd/man9/cpu_configure.9 new file mode 100644 index 00000000..665c38f0 --- /dev/null +++ b/static/netbsd/man9/cpu_configure.9 @@ -0,0 +1,74 @@ +.\" $NetBSD: cpu_configure.9,v 1.7 2015/03/23 13:40:34 riastradh Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 13, 2010 +.Dt CPU_CONFIGURE 9 +.Os +.Sh NAME +.Nm cpu_configure +.Nd machine-dependent device autoconfiguration +.Sh SYNOPSIS +.In sys/systm.h +.Ft void +.Fn cpu_configure "void" +.Sh DESCRIPTION +The machine-dependent +.Fn cpu_configure +is called during system bootstrap to perform the machine-dependent +portion of device autoconfiguration. +It sets the configuration machinery in motion by finding the root bus +.Pq Dq mainbus . +When this function returns, interrupts must be enabled. +.Pp +The following tasks are performed by +.Fn cpu_configure : +.Bl -bullet -offset indent +.It +initialize soft interrupts (see +.Xr softint 9 ) ; +.It +initialize +.Tn CPU +interrupts and +.Tn SPLs +(see +.Xr spl 9 ) ; +.It +call +.Fn config_rootfound +for +.Dq mainbus ; +and +.It +complete any initialization deferred from +.Xr cpu_startup 9 . +.El +.Sh SEE ALSO +.Xr autoconf 9 , +.Xr cpu_startup 9 diff --git a/static/netbsd/man9/cpu_coredump.9 b/static/netbsd/man9/cpu_coredump.9 new file mode 100644 index 00000000..fb65c01f --- /dev/null +++ b/static/netbsd/man9/cpu_coredump.9 @@ -0,0 +1,73 @@ +.\" $NetBSD: cpu_coredump.9,v 1.10 2010/12/02 12:54:13 wiz Exp $ +.\" +.\" Copyright (c) 2002, 2005 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 24, 2005 +.Dt CPU_COREDUMP 9 +.Os +.Sh NAME +.Nm cpu_coredump +.Nd machine-dependent process core dump interface +.Sh SYNOPSIS +.In sys/signalvar.h +.Ft int +.Fn cpu_coredump "struct lwp *l" "void *iocookie" "struct core *chdr" +.Ft int +.Fn cpu_coredump32 "struct lwp *l" "void *iocookie" "struct core32 *chdr" +.Sh DESCRIPTION +.Fn cpu_coredump +is the machine-dependent interface invoked by machine-independent code +to dump the machine-dependent header information at the start of a +process core dump. +The header information primarily consists of the +CPU and floating-point registers. +.Fa l +is the lwp structure of the thread being dumped. +.Fa iocookie +is an opaque pointer to be passed to +.Fn coredump_write . +Information about the machine-dependent header sections are returned in +.Fa chdr . +.Pp +.Fn cpu_coredump +returns 0 on success and an appropriate error code on failure. +.Sh CODE REFERENCES +Process core dumps are initiated within the file +.Pa sys/kern/kern_sig.c . +Process core dumps for ELF +.Nx +binaries are performed within the files +.Pa sys/kern/core_elf32.c +or +.Pa sys/kern/core_elf64.c . +Process core dumps for other +.Nx +binaries are performed within the file +.Pa sys/kern/core_netbsd.c . +.Sh SEE ALSO +.Xr coredump_write 9 diff --git a/static/netbsd/man9/cpu_dumpconf.9 b/static/netbsd/man9/cpu_dumpconf.9 new file mode 100644 index 00000000..e2124d3d --- /dev/null +++ b/static/netbsd/man9/cpu_dumpconf.9 @@ -0,0 +1,81 @@ +.\" $NetBSD: cpu_dumpconf.9,v 1.6 2008/04/30 13:10:58 martin Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 24, 2002 +.Dt CPU_DUMPCONF 9 +.Os +.Sh NAME +.Nm cpu_dumpconf , +.Nm cpu_dump , +.Nm cpu_dumpsize , +.Nm dumpsys +.Nd machine-dependent kernel core dumps +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft void +.Fn cpu_dumpconf "void" +.Ft int +.Fn cpu_dump "int (*dump)(dev_t, daddr_t, void *, size_t)" "daddr_t *blknop" +.Ft int +.Fn cpu_dumpsize "void" +.Ft void +.Fn dumpsys "void" +.Sh DESCRIPTION +.Fn cpu_dumpconf +is the machine-dependent interface invoked during system bootstrap to +determine the dump device and initialize machine-dependent kernel core +dump state. +Internally, +.Fn cpu_dumpconf +will invoke +.Fn cpu_dumpsize +to calculate the size of machine-dependent kernel core dump headers. +.Pp +.Fn dumpsys +is invoked by +.Fn cpu_reboot +to dump kernel physical memory onto the dump device. +.Fn dumpsys +invokes +.Fn cpu_dump +to write the machine-dependent header to the dump device at block number +.Fa *blknop +using the dump device's PIO dump routine specified by the +.Fa dump +argument. +.Pp +.Fn cpu_dumpsize , +.Fn cpu_dump , +and +.Fn dumpsys +are parts of the machine-dependent interface, however they are not +exported to machine-independent code. +.Sh SEE ALSO +.Xr cpu_reboot 9 diff --git a/static/netbsd/man9/cpu_idle.9 b/static/netbsd/man9/cpu_idle.9 new file mode 100644 index 00000000..f74bc2f2 --- /dev/null +++ b/static/netbsd/man9/cpu_idle.9 @@ -0,0 +1,85 @@ +.\" $NetBSD: cpu_idle.9,v 1.9 2007/04/20 13:45:43 yamt Exp $ +.\" +.\" Copyright (c)2007 YAMAMOTO Takashi, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ------------------------------------------------------------ +.Dd April 20, 2007 +.Dt CPU_IDLE 9 +.Os +.\" ------------------------------------------------------------ +.Sh NAME +.Nm cpu_idle +.Nd machine-dependent processor idling interface +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In sys/cpu.h +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn cpu_idle \ +"void" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +.Fn cpu_idle +is called by machine-independent code when the processor has +nothing to do. +It can be used to conserve the processor power, for example. +.Pp +.Fn cpu_idle +returns immediately if +.Fn cpu_need_resched +has been called for the processor after +the last call of +.Fn cpu_idle +or +.Fn cpu_did_resched +on the processor. +.Fn cpu_idle +returns as soon as possible when +.Fn cpu_need_resched +is called for the processor. +Otherwise, it returns whenever it likes. +.Pp +.Fn cpu_idle +is called at +.Dv IPL_NONE , +without any locks held. +.\" ------------------------------------------------------------ +.Sh EXAMPLES +The simplest (and, in some cases, the best) implementation of +.Fn cpu_idle +is the following. +.Bd -literal + void + cpu_idle(void) + { + /* nothing */ + } +.Ed +.\" ------------------------------------------------------------ +.Sh SEE ALSO +.Xr cpu_need_resched 9 , +.Xr cpu_switchto 9 , +.Xr intro 9 , +.Xr spl 9 diff --git a/static/netbsd/man9/cpu_initclocks.9 b/static/netbsd/man9/cpu_initclocks.9 new file mode 100644 index 00000000..9ce13e03 --- /dev/null +++ b/static/netbsd/man9/cpu_initclocks.9 @@ -0,0 +1,52 @@ +.\" $NetBSD: cpu_initclocks.9,v 1.8 2010/12/02 12:54:13 wiz Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 24, 2002 +.Dt CPU_INITCLOCKS 9 +.Os +.Sh NAME +.Nm cpu_initclocks +.Nd machine-dependent clock setup interface +.Sh SYNOPSIS +.In sys/systm.h +.Ft void +.Fn cpu_initclocks "void" +.Sh DESCRIPTION +.Fn cpu_initclocks +is invoked by +.Fn initclocks +during system bootstrap, immediately after autoconfiguration, to +perform the machine-dependent initialization of clock frequencies and +start the real-time and statistic clocks running. +.Sh CODE REFERENCES +Machine-independent clock interface operations are performed within +the file +.Pa sys/kern/kern_clock.c . +.Sh SEE ALSO +.Xr autoconf 9 diff --git a/static/netbsd/man9/cpu_lwp_fork.9 b/static/netbsd/man9/cpu_lwp_fork.9 new file mode 100644 index 00000000..b60e1d10 --- /dev/null +++ b/static/netbsd/man9/cpu_lwp_fork.9 @@ -0,0 +1,102 @@ +.\" $NetBSD: cpu_lwp_fork.9,v 1.7 2018/04/26 14:59:11 scole Exp $ +.\" +.\" Copyright (c) 2002, 2005, 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry; and Rui Paulo. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 26, 2018 +.Dt CPU_LWP_FORK 9 +.Os +.Sh NAME +.Nm cpu_lwp_fork , +.Nm child_return , +.Nm lwp_trampoline +.Nd finish a fork operation +.Sh SYNOPSIS +.In sys/proc.h +.Ft void +.Fn cpu_lwp_fork "struct lwp *l1" "struct lwp *l2" "void *stack" \ +"size_t stacksize" "void (*func)(void *)" "void *arg" +.Ft void +.Fn child_return "void *arg" +.Sh DESCRIPTION +.Fn cpu_lwp_fork +is the machine-dependent portion of +.Fn fork1 +which finishes a fork operation, with child lwp +.Fa l2 +nearly set up. +It copies and updates the PCB and trap frame from the parent +.Fa l1 , +making the child ready to run. +.Pp +.Fn cpu_lwp_fork +rigs the child's kernel stack so that it will start in +.Fn lwp_trampoline . +.Fn lwp_trampoline +does not have a normal calling sequence and is entered by +.Fn cpu_switchto . +If an alternate user-level stack is requested (with non-zero values +in both the +.Fa stack +and +.Fa stacksize +arguments), the user stack pointer is set up accordingly. +.Pp +After being entered by +.Fn cpu_switchto +and while running in user context (within the kernel) +.Fn lwp_trampoline +will invoke the function +.Fa func +with the argument +.Fa arg . +If a kernel thread is being created, the return path and argument +are specified with +.Fa func +and +.Fa arg . +If a user process is being created, +.Fn fork1 +will pass +.Fn child_return +and +.Fa l2 +to +.Fn cpu_lwp_fork +as +.Fa func +and +.Fa arg +respectively. +This causes the newly-created child process to go directly to user +level with an apparent return value of 0 from +.Xr fork 2 , +while the parent process returns normally. +.Sh SEE ALSO +.Xr fork 2 , +.Xr cpu_switchto 9 , +.Xr fork1 9 diff --git a/static/netbsd/man9/cpu_need_resched.9 b/static/netbsd/man9/cpu_need_resched.9 new file mode 100644 index 00000000..b7478be9 --- /dev/null +++ b/static/netbsd/man9/cpu_need_resched.9 @@ -0,0 +1,116 @@ +.\" $NetBSD: cpu_need_resched.9,v 1.10 2019/11/23 19:46:38 ad Exp $ +.\" +.\" Copyright (c) 2002, 2019 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry, and Andrew Doran. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 17, 2019 +.Dt CPU_NEED_RESCHED 9 +.Os +.Sh NAME +.Nm cpu_need_resched +.Nd context switch notification +.Sh SYNOPSIS +.In sys/cpu.h +.Ft void +.Fn cpu_need_resched "struct cpu_info *ci" "struct lwp *l" "int flags" +.Sh DESCRIPTION +The +.Fn cpu_need_resched +function is the machine-independent interface for the scheduler to +notify machine-dependent code that a context switch from the current +LWP +.Fa l , +on the cpu +.Fa ci , +is required. +This event may occur if a higher priority LWP appears on the run +queue or if the current LWP has exceeded its time slice. +.Fa l +is the last LWP observed running on the CPU. +It may no longer be running, as +.Fn cpu_need_resched +can be called without holding scheduler locks. +.Pp +If the +.Dv RESCHED_KPREEMPT +flag is specified in +.Fa flags +and +.Dv __HAVE_PREEMPTION +C pre-processor macro is defined in +.In machine/intr.h , +machine-dependent code should make a context switch happen as soon as possible +even if the CPU is running in kernel mode. +If the +.Dv RESCHED_KPREEMPT +flag is not specified, then +.Dv RESCHED_UPREEMPT +is specified instead. +.Pp +If the +.Dv RESCHED_IDLE +flag is specified in +.Fa flags , +the last thread observed running on the CPU was the idle LWP. +.Pp +If +.Dv RESCHED_REMOTE +flag is specified in +.Fa flags , +the request is not for the current CPU. +The opposite also holds true. +If +.Fa ci +is not the current processor, +.Fn cpu_need_resched +typically issues an inter processor call to the processor to make it +notice the need of a context switch as soon as possible. +.Pp +.Fn cpu_need_resched +is always called with kernel preemption disabled. +.Pp +Typically, the +.Fn cpu_need_resched +function will perform the following operations: +.Bl -bullet -offset indent +.It +Set a per-processor flag which is checked by +.Xr userret 9 +when returning to user-mode execution. +.It +Post an asynchronous software trap +.Pq Tn AST . +.It +Send an inter processor interrupt to wake up +.Xr cpu_idle 9 +and/or force an user process across the user/kernel boundary, thus making a +trip through +.Fn userret . +.El +.Sh SEE ALSO +.Xr sched_4bsd 9 , +.Xr userret 9 diff --git a/static/netbsd/man9/cpu_number.9 b/static/netbsd/man9/cpu_number.9 new file mode 100644 index 00000000..7dad8c91 --- /dev/null +++ b/static/netbsd/man9/cpu_number.9 @@ -0,0 +1,53 @@ +.\" $NetBSD: cpu_number.9,v 1.4 2010/04/13 06:21:40 jruoho Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 13, 2010 +.Dt CPU_NUMBER 9 +.Os +.Sh NAME +.Nm cpu_number +.Nd unique +.Tn CPU +identification number +.Sh SYNOPSIS +.In sys/types.h +.In machine/cpu.h +.Ft cpuid_t +.Fn cpu_number "void" +.Sh DESCRIPTION +The +.Fn cpu_number +function returns an unique +.Tn CPU +identification number for the +.Tn CPU +that this thread is running on. +It may also be implemented as a macro. +.Sh SEE ALSO +.Xr curcpu 9 diff --git a/static/netbsd/man9/cpu_reboot.9 b/static/netbsd/man9/cpu_reboot.9 new file mode 100644 index 00000000..5dbbf736 --- /dev/null +++ b/static/netbsd/man9/cpu_reboot.9 @@ -0,0 +1,120 @@ +.\" $NetBSD: cpu_reboot.9,v 1.19 2024/09/07 19:13:29 rillig Exp $ +.\" +.\" Copyright (c) 1994 Christopher G. Demetriou +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the +.\" NetBSD Project. See https://www.NetBSD.org/ for +.\" information about NetBSD. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" <<Id: LICENSE,v 1.2 2000/06/14 15:57:33 cgd Exp>> +.\" +.Dd February 11, 2010 +.Dt CPU_REBOOT 9 +.Os +.Sh NAME +.Nm cpu_reboot +.Nd halt or reboot the system +.Sh SYNOPSIS +.In sys/reboot.h +.Ft void +.Fn cpu_reboot "int howto" "char *bootstr" +.Sh DESCRIPTION +The +.Fn cpu_reboot +function handles final system shutdown, and either halts or reboots +the system. +The exact action to be taken is determined by the flags passed in +.Fa howto +and by whether or not the system has finished autoconfiguration. +.Pp +If the system has finished autoconfiguration, +.Fn cpu_reboot +does the following: +.Bl -enum -offset indent +.It +Sets the +.Va boothowto +system variable (see +.Xr boothowto 9 ) +from the +.Fa howto +argument. +.It +If this is the first invocation of +.Fn cpu_reboot +and the +.Dv RB_NOSYNC +flag is not set in +.Fa howto , +syncs and unmounts the system disks by calling +.Xr vfs_shutdown 9 +and sets the time of day clock by calling +.Xr resettodr 9 . +.It +Disables interrupts. +.It +If rebooting after a crash (i.e., if +.Dv RB_DUMP +is set in +.Fa howto , +but +.Dv RB_HALT +is not), saves a system crash dump. +.It +Runs any shutdown hooks by calling +.Xr pmf_system_shutdown 9 . +.It +Prints a message indicating that the system is about to be halted +or rebooted. +.It +If +.Dv RB_HALT +is set in +.Fa howto , +halts the system. +Otherwise, reboots the system. +.El +.Pp +If the system has not finished autoconfiguration, +.Fn cpu_reboot +runs any shutdown hooks by calling +.Xr pmf_system_shutdown 9 , +prints a message, and halts the system. +.Pp +If +.Dv RB_STRING +is set in +.Pa howto , +then the parameter +.Fa bootstr +is passed to the system boot loader on some ports. +.Sh SEE ALSO +.Xr boothowto 9 , +.Xr dumpsys 9 , +.Xr pmf_system_shutdown 9 , +.Xr resettodr 9 , +.Xr vfs_shutdown 9 diff --git a/static/netbsd/man9/cpu_rootconf.9 b/static/netbsd/man9/cpu_rootconf.9 new file mode 100644 index 00000000..85364288 --- /dev/null +++ b/static/netbsd/man9/cpu_rootconf.9 @@ -0,0 +1,140 @@ +.\" $NetBSD: cpu_rootconf.9,v 1.10 2014/11/26 20:46:46 wiz Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 11, 2014 +.Dt CPU_ROOTCONF 9 +.Os +.Sh NAME +.Nm cpu_rootconf , +.Nm rootconf , +.Nm setroot +.Nd root file system setup +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft void +.Fn cpu_rootconf "void" +.Ft void +.Fn rootconf "void" +.Ft void +.Fn setroot "device_t bootdv" "int bootpartition" +.Sh DESCRIPTION +The +.Fn cpu_rootconf +is a machine-dependent interface invoked during system bootstrap to +determine the root file system device and initialize machine-dependent +file system state. +.Fn cpu_rootconf +provides the global variables +.Fa booted_device , +.Fa booted_partition , +.Fa booted_startblk , +.Fa booted_nblks , +and +.Fa bootspec . +.Fa cpu_rootconf +invokes the machine-independent function +.Fa rootconf +which calls the function +.Fa setroot +to record the root device and the root partition information +for use in machine-independent code. +.Pp +.Fa rootconf +may adjust the global variables and determines the parameters +for setroot. +This is for example used to translate a device +and partition number provided by the bootloader into a disk +wedge device covering the same partition. +.Pp +If the bootloader already identified a disk wedge, it passes +a non-zero value for +.Fa booted_nblks , +then +.Fa booted_startblk +and +.Fa booted_nblks +specify a disk wedge as the boot device. +.Pp +.Fa setroot +evaluates several sources to identify the root device in the +following order until a valid device is selected: +.Bl -enum +.It +The kernel configuration variable +.Fa rootspec +which is set by +.Xr config 1 . +The value is the name and unit of the root device, e.g., "sd0" (disk) +or "dk0" (wedge) or "le0" (network) or the prefix "wedge:" followed +by the name of the disk wedge. +For disk devices the partition passed as argument to +.Fa setroot +is used. +.It +The variable +.Fa bootspec +following the same syntax. +.It +The result of an interactive query of the root device if +.Fa boothowto +has set the flag +.Dv RB_ASKNAME . +The input uses the same syntax as the previous sources. +Here also the kernel dump device is queried. +.It +The boot device and partition passed as arguments. +.El +.Pp +If a root device cannot be selected, +.Fa setroot +sets the +.Dv RB_ASKNAME +flag and loops. +.Pp +Otherwise the kernel dump device is identified in a similar +manner from +.Bl -enum +.It +The result of a previous interactive query. +See above. +.It +The kernel configuration variable +.Fa dumpspec , +if set. +.It +The second partition of the root device, if it is a regular disk. +.It +The first disk wedge device of type DKW_PTYPE_SWAP. +.El +.Sh SEE ALSO +.Xr config 1 , +.Xr dk 4 , +.Xr boot 8 , +.Xr boothowto 9 diff --git a/static/netbsd/man9/cpu_startup.9 b/static/netbsd/man9/cpu_startup.9 new file mode 100644 index 00000000..7b989017 --- /dev/null +++ b/static/netbsd/man9/cpu_startup.9 @@ -0,0 +1,63 @@ +.\" $NetBSD: cpu_startup.9,v 1.7 2010/04/13 12:04:25 jruoho Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 13, 2010 +.Dt CPU_STARTUP 9 +.Os +.Sh NAME +.Nm cpu_startup +.Nd machine-dependent +.Tn CPU +startup +.Sh SYNOPSIS +.In sys/systm.h +.Ft void +.Fn cpu_startup "void" +.Sh DESCRIPTION +The machine-dependent +.Fn cpu_startup +is invoked early during system bootstrap, after the console +has been set up and immediately after +.Xr uvm 9 +has been initialized. +.Pp +The following tasks are performed by +.Fn cpu_startup : +.Bl -bullet -offset indent +.It +print the initial copyright message; +.It +allocate memory and buffers for kernel tables; and +.It +initialize the +.Tn CPU . +.El +.Sh SEE ALSO +.Xr autoconf 9 , +.Xr uvm 9 diff --git a/static/netbsd/man9/cpu_switchto.9 b/static/netbsd/man9/cpu_switchto.9 new file mode 100644 index 00000000..49f096be --- /dev/null +++ b/static/netbsd/man9/cpu_switchto.9 @@ -0,0 +1,149 @@ +.\" $NetBSD: cpu_switchto.9,v 1.14 2011/06/03 08:06:54 wiz Exp $ +.\" +.\" Copyright (c)2007 YAMAMOTO Takashi, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ------------------------------------------------------------ +.Dd June 2, 2011 +.Dt CPU_SWITCHTO 9 +.Os +.\" ------------------------------------------------------------ +.Sh NAME +.Nm cpu_switchto +.Nd machine-dependent +.Tn LWP +context switching interface +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In sys/cpu.h +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft lwp_t * +.Fn cpu_switchto \ +"lwp_t *oldlwp" "lwp_t *newlwp" "bool returning" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +The +.Fn cpu_switchto +function saves the context of the +.Tn LWP +which is currently running on the processor, +and restores the context of the +.Tn LWP +specified by +.Fa newlwp . +.Pp +Remarks: +.Bl -enum -offset indent +.It +.Fn cpu_switchto +does not switch address spaces. +.It +.Fn cpu_switchto +sets +.Xr curlwp 9 +to +.Fa newlwp . +If the architecture does non-interlocked adaptive mutex release, +.Fn cpu_switchto +does an equivalent of +.Xr membar_producer 3 , +before and after the modification of +.Xr curlwp 9 . +.It +.Fn cpu_switchto +should be called at +.Dv IPL_SCHED . +When the function returns, the caller should lower +the priority level as soon as possible. +.It +.Fn cpu_switchto +might be called with spin mutexes held. +.El +.Pp +The function takes the following arguments. +.Bl -tag -width "returning " -offset indent +.It Fa oldlwp +Specify the +.Tn LWP +from which the switch is going to be made, i.e., the calling +.Tn LWP . +If it was +.Dv NULL , +the context of the +.Tn LWP +currently running on this processor is not saved. +.It Fa newlwp +Specify the +.Tn LWP +to which to switch. +It must not be +.Dv NULL . +.It Fa returning +Only meaningful if the architecture implements fast software interrupts. +If true, it indicates that +.Fa oldlwp +is a soft interrupt +.Tn LWP +that is blocking. +It is a good indication that any kind of address space or user activity +can be completely ignored. +For example: +.Xr ras_lookup 9 , +cache flushes, TLB wirings, adjusting lazy +.Tn FPU +state. +All that is required is to restore the register state and stack, and +return to the interrupted +.Tn LWP . +.El +.\" ------------------------------------------------------------ +.Sh RETURN VALUES +The +.Fn cpu_switchto +function does not return until another +.Tn LWP +calls +.Fn cpu_switchto . +It returns the +.Vt oldlwp +argument of the +.Fn cpu_switchto +which is called to switch back to our +.Tn LWP . +It is either a +.Tn LWP +which called +.Fn cpu_switchto +to switch to us or +.Dv NULL +in case the +.Tn LWP +was exiting. +.\" ------------------------------------------------------------ +.Sh SEE ALSO +.Xr membar_producer 3 , +.Xr swapcontext 3 , +.Xr intro 9 , +.Xr mutex 9 , +.Xr spl 9 diff --git a/static/netbsd/man9/cpufreq.9 b/static/netbsd/man9/cpufreq.9 new file mode 100644 index 00000000..4935b242 --- /dev/null +++ b/static/netbsd/man9/cpufreq.9 @@ -0,0 +1,311 @@ +.\" $NetBSD: cpufreq.9,v 1.7 2015/12/01 12:07:41 jmcneill Exp $ */ +.\" +.\" Copyright (c) 2011 Jukka Ruohonen <jruohonen.iki.fi> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 1, 2015 +.Dt CPUFREQ 9 +.Os +.Sh NAME +.Nm cpufreq , +.Nm cpufreq_register , +.Nm cpufreq_deregister , +.Nm cpufreq_suspend , +.Nm cpufreq_resume , +.Nm cpufreq_get , +.Nm cpufreq_get_backend , +.Nm cpufreq_get_state , +.Nm cpufreq_get_state_index , +.Nm cpufreq_set , +.Nm cpufreq_set_all +.Nd interface for CPU frequency scaling +.Sh SYNOPSIS +.In sys/cpufreq.h +.Ft int +.Fn cpufreq_register "struct cpufreq *cf" +.Ft void +.Fn cpufreq_deregister "void" +.Ft void +.Fn cpufreq_suspend "struct cpu_info *ci" +.Ft void +.Fn cpufreq_resume "struct cpu_info *ci" +.Ft uint32_t +.Fn cpufreq_get "struct cpu_info *ci" +.Ft int +.Fn cpufreq_get_backend "struct cpufreq *cf" +.Ft int +.Fn cpufreq_get_state "uint32_t freq" "struct cpufreq_state *cfs" +.Ft int +.Fn cpufreq_get_state_index "uint32_t index" "struct cpufreq_state *cfs" +.Ft void +.Fn cpufreq_set "struct cpu_info *ci" "uint32_t freq" +.Ft void +.Fn cpufreq_set_all "uint32_t freq" +.\" .Ft void +.\" .Fn cpufreq_set_higher "struct cpu_info *ci" +.\" .Ft void +.\" .Fn cpufreq_set_lower "struct cpu_info *ci" +.Sh DESCRIPTION +The machine-independent +.Nm +interface provides a framework for +.Tn CPU +frequency scaling done by a machine-dependent backend implementation. +.Pp +The +.Nm +interface is a per-CPU framework. +It is implicitly assumed that the frequency can be set +independently for all processors in the system. +However, +.Nm +does not imply any restrictions upon whether this information +is utilized by the actual machine-dependent implementation. +It is possible to use +.Nm +with frequency scaling implemented via +.Xr pci 4 . +In addition, it assumed that the available frequency levels are +shared uniformly by all processors in the system, +even when it is possible to control the frequency of individual processors. +.Pp +It should be noted that the +.Nm +interface is generally stateless. +This implies for instance that possible caching should +be done in the machine-dependent backend. +The +.Fn cpufreq_suspend +and +.Fn cpufreq_resume +functions are exceptions. +These can be integrated with +.Xr pmf 9 . +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn cpufreq_register "cf" +The +.Fn cpufreq_register +function initializes the interface by associating +a machine-dependent backend with the framework. +Only one backend can be registered. +Upon successful completion, +.Fn cpufreq_register +returns 0 and sets the frequency of all processors +to the maximum available level. +Note that the registration can be done +only after interrupts have been enabled; cf. +.Xr config_interrupts 9 . +.Pp +The following elements in +.Vt struct cpufreq +should be filled prior to the call: +.Bd -literal -offset indent +char cf_name[CPUFREQ_NAME_MAX]; +struct cpufreq_state cf_state[CPUFREQ_STATE_MAX]; +uint32_t cf_state_count; +bool cf_mp; +void *cf_cookie; +xcfunc_t cf_get_freq; +xcfunc_t cf_set_freq; +.Ed +.Pp +.Bl -bullet +.It +The name of the backend should be given in +.Vt cf_name . +.It +The +.Vt cpufreq_state +structure conveys descriptive information about the frequency states. +The following fields can be used for the registration: +.Bd -literal -offset 2n +uint32_t cfs_freq; +uint32_t cfs_power; +.Ed +.Pp +From these +.Vt cfs_freq +(the clock frequency in MHz) is mandatory, whereas the optional +.Vt cfs_power +can be filled to describe the power consumption (in mW) of each state. +The +.Fa cf_state +array must be filled in descending order, that is, the highest +frequency should be at the zero index. +.Pp +If the backend operates with a simple boolean switch +without knowing the clock frequencies, the +.Fa cfs_freq +field should be set to +.Dv CPUFREQ_STATE_ENABLED +or +.Dv CPUFREQ_STATE_DISABLED . +The first constant should precede the latter one in +.Vt cf_state . +.It +The +.Vt cf_state_count +field defines the number of states that the backend has filled in the +.Vt cf_state +array. +.It +The +.Vt cf_mp +boolean should be set to false if it is known that the backend +can not handle per-CPU frequency states; +changes should always be propagated +to all processors in the system. +.It +The +.Vt cf_cookie +field is an opaque pointer passed to the backend when +.Fn cpufreq_get , +.Fn cpufreq_set , +or +.Fn cpufreq_set_all +is called. +.It +The +.Vt cf_get_freq +and +.Vt cf_set_freq +are function pointers that should be associated with the +machine-dependent functions to get and set a frequency, respectively. +The +.Vt xcfunc_t +type is part of +.Xr xcall 9 . +When the function pointers are invoked by +.Nm , +the first parameter is always the +.Vt cf_cookie +and the second parameter is the frequency, defined as +.Vt uint32_t * . +.El +.It Fn cpufreq_deregister +Deregisters any possible backend in use. +.It Fn cpufreq_suspend "ci" +The +.Fn cpufreq_suspend +can be called when the processor suspends. +The function saves the current frequency of +.Fa ci +and sets the minimum available frequency. +.It Fn cpufreq_resume "ci" +Resumes the frequency of +.Fa ci +that was used before suspend. +.It Fn cpufreq_get "ci" +Returns the current frequency of the processor +.Fa ci . +A value zero is returned upon failure. +.It Fn cpufreq_get_backend "cf" +Upon successful completion, +.Fn cpufreq_get_backend +returns 0 and fills +.Fa cf +with the data related to the currently used backend. +.It Fn cpufreq_get_state "freq" "cfs" +The +.Fn cpufreq_get_state +function looks for the given frequency +from the array of known frequency states. +If +.Fa freq +is not found, the closest match is returned. +Upon successful completion, +the function returns zero and stores the state information to +.Fa cfs . +.It Fn cpufreq_get_state_index "index" "cfs" +Stores the frequency state with the given +.Fa index +to +.Fa cfs , +returning zero upon successful completion. +.It Fn cpufreq_set "ci" "freq" +The +.Fn cpufreq_set +function sets the frequency of +.Fa ci +to +.Fa freq . +.It Fn cpufreq_set_all "freq" +Sets +.Fa freq +for all processors in the system. +.\" .It Fn cpufreq_set_higher "ci" +.\" Decrements the current frequency level of +.\" .Fa ci +.\" by one state. +.\" .It Fn cpufreq_set_lower "ci" +.\" Increases the current frequency state of +.\" .Fa ci +.\" by one state. +.El +.Pp +The three functions +.Fn cpufreq_get , +.Fn cpufreq_set , +and +.Fn cpufreq_set_all +guarantee that the call will be made in +.Xr curcpu 9 . +The interface holds a +.Xr mutex 9 +while calling the functions. +This, and the use of +.Xr xcall 9 , +implies that no memory can be allocated in the backend during the calls. +Nor should the functions be called from interrupt context. +.Sh CODE REFERENCES +The +.Nm +interface is implemented within +.Pa sys/kern/subr_cpufreq.c . +.Sh SEE ALSO +.Xr pmf 9 , +.Xr xcall 9 +.Rs +.%A Venkatesh Pallipadi +.%A Alexey Starikovskiy +.%T The Ondemand Governor. Past, Present, and Future +.%I Intel Open Source Technology Center +.%O Proceedings of the Linux Symposium +.%D July, 2006 +.%U http://www.kernel.org/doc/ols/2006/ols2006v2-pages-223-238.pdf +.Re +.Sh HISTORY +The +.Nm +interface first appeared in +.Nx 6.0 . +.Sh AUTHORS +.An Jukka Ruohonen +.Aq jruohonen@iki.fi +.Sh BUGS +The interface does not support different +.Dq governors +and policies. diff --git a/static/netbsd/man9/crashme.9 b/static/netbsd/man9/crashme.9 new file mode 100644 index 00000000..33864d55 --- /dev/null +++ b/static/netbsd/man9/crashme.9 @@ -0,0 +1,125 @@ +.\" $NetBSD: crashme.9,v 1.6 2024/07/24 12:48:17 uwe Exp $ +.\" +.\" Copyright (c) 2019 Matthew R. Green +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 7, 2019 +.Dt CRASHME 9 +.Os +.Sh NAME +.Nm crashme , +.Nm crashme_add , +.Nm crashme_remove +.Nd in-kernel testing of crash handling +.Sh SYNOPSIS +.In sys/crashme.h +.Ft int +.Fn crashme_add "crashme_node *cn" +.Ft int +.Fn crashme_remove "crashme_node *cn" +.Sh DESCRIPTION +The +.Nm +functions provide access to dynamically add and remove crashme nodes. +These nodes are simply named callbacks that are expected to cause the +system to crash. +.Pp +The crashme functionality is only available in kernels with the +.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 -offset indent +typedef int (*crashme_fn)(int /* flags */); + +typedef struct crashme_node { + const char *cn_name; + const char *cn_longname; + crashme_fn cn_fn; +} crashme_node; +.Ed +.Pp +The +caller must fill in the +.Fa cn_name , +.Fa cn_longname , +and +.Fa cn_fn +members. +.Pp +The +.Fa cn_fn +function is passed +.Ar flags +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 -offset indent -width Va +.It Va debug.crashme_enable +Must be set to 1 for any +.Nm +node to be executed. +.El +.Pp +The following +.Xr sysctl 8 +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 Va debug.crashme.null_deref +Dereference a null pointer. +.It Va debug.crashme.null_jump +Call a null function pointer, i.e., jump to the instruction address +zero. +.It Va debug.crashme.ddb +Enter +.Xr ddb 4 +directly by calling +.Fn Debugger . +Requires +.Ic options DDB . +.El +.Sh SEE ALSO +.Xr ddb 4 , +.Xr options 4 , +.Xr sysctl 8 , +.Xr panic 9 . +.Sh HISTORY +The +.Nm +driver appeared in +.Nx 9.0 . +.Sh AUTHORS +.An Matthew R. Green diff --git a/static/netbsd/man9/csf.9 b/static/netbsd/man9/csf.9 new file mode 100644 index 00000000..ab6418f0 --- /dev/null +++ b/static/netbsd/man9/csf.9 @@ -0,0 +1,216 @@ +.\" $NetBSD: csf.9,v 1.9 2015/05/25 21:02:37 prlw1 Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Daniel Sieger. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 27, 2014 +.Dt CSF 9 +.Os +.Sh NAME +.Nm CSF +.Nd The +.Nx +common scheduler framework +.Sh SYNOPSIS +.In sys/sched.h +.Ft void +.Fn sched_rqinit "void" +.Ft void +.Fn sched_setup "void" +.Ft void +.Fn sched_cpuattach "struct cpu_info *" +.Ft void +.Fn sched_tick "struct cpu_info *" +.Ft void +.Fn sched_schedclock "lwp_t *" +.Ft bool +.Fn sched_curcpu_runnable_p "void" +.Ft lwp_t * +.Fn sched_nextlwp "void" +.Ft void +.Fn sched_enqueue "lwp_t *" "bool" +.Ft void +.Fn sched_dequeue "lwp_t *" +.Ft void +.Fn sched_nice "struct proc *" "int" +.Ft void +.Fn sched_proc_fork "struct proc *" "struct proc *" +.Ft void +.Fn sched_proc_exit "struct proc *" "struct proc *" +.Ft void +.Fn sched_lwp_fork "lwp_t *" +.Ft void +.Fn sched_lwp_exit "lwp_t *" +.Ft void +.Fn sched_setrunnable "lwp_t *" +.Ft void +.Fn sched_print_runqueue "void (*pr)(const char *, ...)" +.Ft void +.Fn sched_pstats_hook "struct proc *" "int" +.Ft void +.Fn sched_pstats "void *arg" +.Ft pri_t +.Fn sched_kpri "lwp_t *" +.Ft void +.Fn resched_cpu "lwp_t *" +.Ft void +.Fn setrunnable +.Ft void +.Fn schedclock "lwp_t *" +.Ft void +.Fn sched_init "void" +.Sh DESCRIPTION +.Nm +provides a modular and self-contained interface for +implementing different thread scheduling algorithms. +The different schedulers can be selected at compile-time. +Currently, the schedulers available are +.Xr sched_4bsd 9 , +the traditional 4.4BSD thread scheduler, and +.Xr sched_m2 9 +which implements a SVR4/Solaris like approach. +.Pp +The interface is divided into two parts: A set of functions each +scheduler needs to implement and common functions used by all +schedulers. +.Sh Scheduler-specific functions +The following functions have to be implemented by the individual +scheduler. +.Ss Scheduler initialization +.Bl -tag -width compact +.It Ft void Fn sched_cpuattach "struct cpu_info *" +Per-CPU scheduler initialization routine. +.It Ft void Fn sched_rqinit "void" +Initialize the scheduler's runqueue data structures. +.It Ft void Fn sched_setup "void" +Setup initial scheduling parameters and kick off timeout driven +events. +.El +.Ss Runqueue handling +Runqueue handling is completely internal to the scheduler. +Other parts of the kernel should access runqueues only through the +following functions: +.Bl -tag -width compact +.It Ft void Fn sched_enqueue "lwp_t *" "bool" +Place an LWP within the scheduler's runqueue structures. +.It Ft void Fn sched_dequeue "lwp_t *" +Remove an LWP from the scheduler's runqueue structures. +.It Ft lwp_t * Fn sched_nextlwp "void" +Return the LWP that should run the CPU next. +.It Ft bool Fn sched_curcpu_runnable_p "void" +Indicate if there is a runnable LWP for the current CPU. +.It Ft void Fn sched_print_runqueue "void (*pr)(const char *, ...)" +Print runqueues in DDB. +.El +.Ss Core scheduler functions +.Bl -tag -width compact +.It Ft void Fn sched_tick "struct cpu_info *" +Periodically called from +.Xr hardclock 9 . +Determines if a reschedule is necessary, if the running LWP has +used up its quantum. +.It Ft void Fn sched_schedclock "lwp_t *" +Periodically called from +.Fn schedclock +in order to handle priority adjustment. +.El +.Ss Priority adjustment +.Bl -tag -width compact +.It Ft void Fn sched_nice "struct proc *" "int" +Recalculate the process priority according to its nice value. +.El +.Ss General helper functions +.Bl -tag -width compact +.It Ft void Fn sched_proc_fork "struct proc *" "struct proc *" +Inherit the scheduling history of the parent process after +.Fn fork . +.It Ft void Fn sched_proc_exit "struct proc *" "struct proc *" +Charge back a processes parent for its resource usage. +.It Ft void Fn sched_lwp_fork "lwp_t *" +LWP-specific version of the above +.It Ft void Fn sched_lwp_exit "lwp_t *" +LWP-specific version of the above +.It Ft void Fn sched_setrunnable "lwp_t *" +Scheduler-specific actions for +.Fn setrunnable . +.It Ft void Fn sched_pstats_hook "struct proc *" "int" +Scheduler-specific actions for +.Fn sched_pstats . +.El +.Sh Common scheduler functions +.Bl -tag -width compact +.It Ft pri_t Fn sched_kpri "lwp_t *" +Scale a priority level to a kernel priority level, usually for an LWP +that is about to sleep. +.It Ft void Fn sched_pstats "void *" +Update process statistics and check CPU resource allocation. +.It Ft inline void Fn resched_cpu "lwp_t *" +Arrange for a reschedule. +.It Ft void Fn setrunnable "lwp_t *" +Change process state to be runnable, placing it on a runqueue if it +is in memory, awakening the swapper otherwise. +.It Ft void Fn schedclock "lwp_t *" +Scheduler clock. +Periodically called from +.Fn statclock . +.It Ft void Fn sched_init "void" +Initialize callout for +.Fn sched_pstats +and call +.Fn sched_setup +to initialize any other scheduler-specific data. +.El +.Sh CODE REFERENCES +The +.Nm +programming interface is defined within the file +.Pa sys/sys/sched.h . +.Pp +Functions common to all scheduler implementations are in +.Pa sys/kern/kern_synch.c . +.Pp +The traditional 4.4BSD scheduler is implemented in +.Pa sys/kern/sched_4bsd.c . +.Pp +The M2 scheduler is implemented in +.Pa sys/kern/sched_m2.c . +.Sh SEE ALSO +.Xr mi_switch 9 , +.Xr preempt 9 , +.Xr sched_4bsd 9 , +.Xr sched_m2 9 +.Sh HISTORY +The +.Nm +appeared in +.Nx 5.0 . +.Sh AUTHORS +The +.Nm +was written by +.An Daniel Sieger +.Aq dsieger@NetBSD.org . diff --git a/static/netbsd/man9/ctod.9 b/static/netbsd/man9/ctod.9 new file mode 100644 index 00000000..7cee342e --- /dev/null +++ b/static/netbsd/man9/ctod.9 @@ -0,0 +1,84 @@ +.\" $NetBSD: ctod.9,v 1.4 2011/04/08 07:55:04 jruoho Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 8, 2011 +.Dt CTOD 9 +.Os +.Sh NAME +.Nm ctod +.Nd macros related to bytes, pages, and disk blocks +.Sh SYNOPSIS +.In sys/param.h +.Ft size +.Fn ctod "size x" +.Ft size +.Fn dtoc "size x" +.Ft size +.Fn ctob "size x" +.Ft size +.Fn btoc "size x" +.Ft size +.Fn dbtob "size x" +.Ft size +.Fn btodb "size x" +.Sh DESCRIPTION +The +.Nm +family of macros can be used to convert between bytes, pages +.Pq Dq clicks , +and disk blocks. +.Pp +The following table lists the possible conversions: +.Bl -column -offset indent "disk blocks " "disk blocks " "disk blocks " +.It Sy Macro Ta Sy From Ta Sy To +.It Fn ctod Ta pages Ta disk blocks +.It Fn dtoc Ta disk blocks Ta pages +.It Fn ctob Ta pages Ta bytes +.It Fn btoc Ta bytes Ta pages +.It Fn dbtob Ta disk blocks Ta bytes +.It Fn btodb Ta bytes Ta disk blocks +.El +.Pp +These are typical macros that may appear +with different names in other operating systems. +Examples include +.Fn btop +and +.Fn btopr +in Solaris. +.Sh SEE ALSO +.Xr param 3 +.Sh HISTORY +Some of these macros appeared in +.At v7 . +.Sh CAVEATS +The described macros make no assumptions +about the type of the input parameter. +A caller should ensure that neither +integer overflow nor integer underflow are possible. diff --git a/static/netbsd/man9/curlwp_bind.9 b/static/netbsd/man9/curlwp_bind.9 new file mode 100644 index 00000000..7715be92 --- /dev/null +++ b/static/netbsd/man9/curlwp_bind.9 @@ -0,0 +1,98 @@ +.\" $NetBSD: curlwp_bind.9,v 1.3 2026/01/01 01:12:52 uwe Exp $ +.\" +.\" Copyright (c) 2025 The NetBSD Foundation +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 31, 2025 +.Dt CURLWP_BIND 9 +.Os +.Sh NAME +.Nm curlwp_bind , +.Nm curlwp_bindx +.Nd temporarily bind the current thread to the running CPU +.Sh SYNOPSIS +.In sys/lwp.h +.Ft int +.Fn curlwp_bind "void" +.Ft void +.Fn curlwp_bindx "int bound" +.Sh DESCRIPTION +.Fn curlwp_bind +temporarily binds the current thread to the running CPU and returns a +cookie +.Fa bound +which must be passed to +.Fn curlwp_bindx +when done. +.Pp +During this time, the thread may sleep and may be preempted, but it +will never migrate to another CPU until +.Fn curlwp_bindx . +If the CPU is offlined, the thread will not run again until the CPU is +onlined again. +.Pp +Calls to +.Fn curlwp_bind +and +.Fn curlwp_bindx +may be nested as long as the matching cookie is passed. +.Sh EXAMPLES +For temporary access to resources protected by +.Xr psref 9 +from an arbitrary thread: +.Bd -literal -offset indent +struct psref psref; +int bound, s; + +bound = curlwp_bind(); +s = pserialize_read_enter(); +IFADDR_READER_FOREACH(ifa, ifp) { + ifa_acquire(ifa, &psref); + pserialize_read_exit(s); + + /* + * ifa is now stable, even if caller is preempted + * or sleeps + */ + + s = pserialize_read_enter(); + ifa_release(ifa, &psref); +} +pserialize_read_exit(s); +curlwp_bindx(bound); +.Ed +.Sh CODE REFERENCES +.Pa sys/sys/lwp.h +.Sh SEE ALSO +.Xr localcount 9 , +.Xr pserialize 9 , +.Xr psref 9 , +.Xr spl 9 +.Sh HISTORY +The +.Nm +function first appeared in +.Nx 8.0 +to support +.Xr psref 9 . diff --git a/static/netbsd/man9/curproc.9 b/static/netbsd/man9/curproc.9 new file mode 100644 index 00000000..282af8d1 --- /dev/null +++ b/static/netbsd/man9/curproc.9 @@ -0,0 +1,124 @@ +.\" $NetBSD: curproc.9,v 1.7 2023/07/08 13:59:05 riastradh Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 8, 2023 +.Dt CURPROC 9 +.Os +.Sh NAME +.Nm curcpu , +.Nm curlwp , +.Nm curproc +.Nd current processor, thread, and process +.Sh SYNOPSIS +.In sys/proc.h +.Ft struct cpu_info * +.Fn curcpu "void" +.Vt struct proc *curproc ; +.Vt struct lwp *curlwp ; +.In sys/cpu.h +.Ft bool +.Fn curcpu_stable "void" +.Sh DESCRIPTION +The following retrieve the current CPU, process, and thread +.Pq lightweight process, or Tn LWP , +respectively: +.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 +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 . +.Pp +The function +.Fn curcpu_stable +can be used in assertions +.Pq Xr KASSERT 9 +to verify that +.Fn curcpu +is stable in the current context. +.Fn curcpu_stable +MUST NOT be used to make dynamic decisions about whether to query +.Fn curcpu . +.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. +.Pp +The +.Fn curcpu_stable +function is defined in +.Pa kern/subr_cpu.c . +.Sh SEE ALSO +.Xr cpu_number 9 , +.Xr proc_find 9 diff --git a/static/netbsd/man9/ddb.9 b/static/netbsd/man9/ddb.9 new file mode 100644 index 00000000..41501891 --- /dev/null +++ b/static/netbsd/man9/ddb.9 @@ -0,0 +1,162 @@ +.\" $NetBSD: ddb.9,v 1.3 2020/10/31 10:48:17 wiz Exp $ +.\" +.\" Copyright (c) 2020 Valery Ushakov +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd October 30, 2020 +.Dt DDB 9 +.Os +.\" +.\" +.Sh NAME +.Nm ddb +.Nd in-kernel debugger +.\" +.\" +.Sh SYNOPSIS +.\" +.In ddb/ddb.h +.\" +.Ft int +.Fn db_register_tbl "uint8_t type" "const struct db_command *commands" +.\" +.Ft int +.Fn db_unregister_tbl "uint8_t type" "const struct db_command *commands" +.\" +.\" XXX: there's no typedef defined for this +.Ft void +.Fo "(*pf)" \" it seems there's no way to format this differently +.Fa "db_expr_t addr" +.Fa "bool have_addr" +.Fa "db_expr_t count" +.Fa "const char *modif" +.Fc +.\" +.\" - a macro, but document the types here +.Fo DDB_ADD_CMD +.Fa "const char *name" +.Fa "void (*pf)(db_expr_t, bool, db_expr_t, const char *)" +.Fa "uint16_t flags" +.Fa "const char *cmd_descr" +.Fa "const char *cmd_arg" +.Fa "const char *arg_desc" +.Fc +.\" +.Sh DESCRIPTION +Devices and kernel modules can add new commands to the +.Xr ddb 4 +in-kernel debugger with +.Fn db_register_tbl +and remove previously added commands with +.Fn db_unregister_tbl +respectively. +.Pp +The +.Fa type +argument is one of: +.Bl -tag -offset indent -width Dv +.\" +.It Dv DDB_BASE_CMD +top-level commands; +.\" +.It Dv DDB_MACH_CMD +sub-commands of the top-level +.Ic mach +command; +.\" +.It Dv DDB_SHOW_CMD +sub-commands of the top-level +.Ic show +command. +.\" +.El +.\" +.Pp +The +.Fa commands +argument is an array of +.Vt struct db_command\| +entries. +The initializer list for the array should use the +.Fn DDB_ADD_CMD +macro for its entries. +The +.Fa name +argument is the name of the debugger command. +An entry with +.Dv NULL +.Fa name +terminates the array. +.Pp +The +.Fa pf +argument is the function that implements the command. +The debugger's +.Tn REPL +parses the usual command format documented in +.Xr ddb 4 +and invokes the implementation with the values obtained. +.Pp +The +.Fa flags +argument is a bitwise +.Tn OR +of the following values: +.Bl -tag -offset indent -width Dv +.\" +.It Dv CS_MORE +The command takes the usual arguments but may additionally parse the +remainder of its command line. +.\" +.It Dv CS_NOREPEAT +The command should not be automatically repeated by the +.Tn REPL +when the user enters an empty command after it. +.\" +.It Dv CS_OWN +The command doesn't follow the normal +.Xr ddb 4 +conventions and parses its command line itself. +The +.Tn REPL +doesn't try to parse the command line. +The values passed to its implementation are dummies. +.\" +.It Dv CS_SET_DOT +The command sets the +.Va dot . +.\" +.El +.\" +.Pp +The remaining parameters are strings that provide documentation for +the command and its arguments. +That documentation is available to the user via the +.Ic help +command if the kernel was compiled with the +.Dv DDB_VERBOSE_HELP +option. +.\" +.Sh SEE ALSO +.Xr ddb 4 diff --git a/static/netbsd/man9/ddc.9 b/static/netbsd/man9/ddc.9 new file mode 100644 index 00000000..f1c02071 --- /dev/null +++ b/static/netbsd/man9/ddc.9 @@ -0,0 +1,110 @@ +.\" $NetBSD: ddc.9,v 1.8 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright 2006 Itronix Inc. +.\" All rights reserved. +.\" +.\" Written by Garrett D'Amore for Itronix Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of Intronix Inc. may not be used to endorse +.\" or promote products derived from this software without specific prior +.\" written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY INTRONIX INC. ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ITRONIX INC. BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 11, 2006 +.Dt DDC 9 +.Os +.Sh NAME +.Nm ddc +.Nd VESA Display Data Channel V2 +.Sh SYNOPSIS +.In dev/i2c/ddcvar.h +.Ft int +.Fo ddc_read_edid +.Fa "i2c_tag_t tag" +.Fa "uint8_t *dest" +.Fa "size_t len" +.Fc +.Sh DESCRIPTION +The +.Fn ddc_read_edid +reads a VESA Extended Display Identification Data block (EDID) via +VESA Display Data Channel (DDCv2). +DDCv2 is a protocol for data exchange between display devices (such +as monitors and flat panels) and host machines using an I2C bus. +.Pp +The +.Fa tag +argument is a machine-dependent tag used to specify the I2C +bus on which the DDCv2 device is located. +The +.Fa dest +argument is a pointer to a buffer where the EDID data will be stored. +The +.Fa len +argument is the amount of data to read into the buffer. +(The buffer must be large enough.) +Typically, this value will be 128, which is the size of a normal +EDID data block. +.Pp +Normally the EDID data block will be post-processed with the +.Fn edid_parse +function. +.Sh RETURN VALUES +The +.Fn ddc_read_edid +function returns zero on success, and non-zero otherwise. +.Sh ENVIRONMENT +The +.Fn ddc_read_edid +function is part of the +.Xr ddc 4 +driver, and is only included in the kernel if that driver is also included. +.Sh EXAMPLES +The following code uses +.Fn ddc_read_edid +to retrieve and print information about a monitor: +.Pp +.Bd -literal -compact + struct edid_info info; + i2c_tag_t tag; + char buffer[128]; + + ... + /* initialize i2c tag... */ + ... + if ((ddc_read_edid(tag, buffer, 128) == 0) && + (edid_parse(buffer, &info) == 0)) + edid_print(info); + ... +.Ed +.Pp +Note that this must be called before the PCI bus is attached during +autoconfiguration. +.Sh SEE ALSO +.Xr ddc 4 , +.Xr edid 9 , +.Xr iic 9 +.Sh HISTORY +DDCv2 support was added in +.Nx 4.0 . +.Sh AUTHORS +.An Garrett D'Amore Aq Mt gdamore@NetBSD.org diff --git a/static/netbsd/man9/delay.9 b/static/netbsd/man9/delay.9 new file mode 100644 index 00000000..70f60737 --- /dev/null +++ b/static/netbsd/man9/delay.9 @@ -0,0 +1,60 @@ +.\" $NetBSD: delay.9,v 1.8 2021/05/31 12:24:15 simonb Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 20, 2011 +.Dt DELAY 9 +.Os +.Sh NAME +.Nm delay , +.Nm DELAY +.Nd microsecond delay +.Sh SYNOPSIS +.In sys/param.h +.Ft void +.Fn delay "unsigned int us" +.Ft void +.Fn DELAY "unsigned int us" +.Sh DESCRIPTION +Wait approximately +.Fa us +microseconds. +.Pp +The delay is implemented as a machine loop, preventing events other than +interrupt handlers for unmasked interrupts to run. +.Fn DELAY +is reentrant (doesn't modify any global kernel or machine state) and is +safe to use in interrupt or process context. +.Pp +For long delays, condition variables +should be considered, however they can only be used from process context +and their resolution is limited by the system clock frequency. +.Sh SEE ALSO +.Xr condvar 9 , +.Xr hz 9 , +.Xr kpause 9 diff --git a/static/netbsd/man9/deviter.9 b/static/netbsd/man9/deviter.9 new file mode 100644 index 00000000..3c5f4ac9 --- /dev/null +++ b/static/netbsd/man9/deviter.9 @@ -0,0 +1,198 @@ +.\" $NetBSD: deviter.9,v 1.5 2014/03/18 18:20:40 riastradh Exp $ +.\" +.\" Copyright (c) 2009 David Young <dyoung@NetBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY David Young ``AS IS'' AND ANY EXPRESS +.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL David Young BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE +.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER +.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR +.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" NetBSD: pmf.9,v 1.12 2009/10/21 16:06:59 snj Exp +.\" +.\" Copyright (c) 2007 Jared D. McNeill <jmcneill@invisible.ca> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 4, 2009 +.Dt DEVITER 9 +.Os +.Sh NAME +.Nm deviter , +.Nm deviter_first , +.Nm deviter_init , +.Nm deviter_next , +.Nm deviter_release +.Nd machine-independent device iteration API +.Sh SYNOPSIS +.In sys/device.h +.Ft void +.Fn deviter_init "deviter_t *di" "deviter_flags_t flags" +.Ft device_t +.Fn deviter_first "deviter_t *di" "deviter_flags_t flags" +.Ft device_t +.Fn deviter_next "deviter_t *di" +.Ft void +.Fn deviter_release "deviter_t *di" +.Sh DESCRIPTION +The machine-independent +.Nm +API lets interrupt handlers running at any priority level and kernel +threads iterate over the devices attached to the kernel. +Using +.Nm , +it is safe for an interrupt handler or a thread to iterate over +devices attached to the kernel while another thread attaches or +detaches the devices. +.Sh DATA TYPES +Kernel subsystems using +.Nm +may make use of the following data types: +.Bl -tag -width compact +.It Fa deviter_flags_t +The kernel can iterate over devices for different purposes and in +different orders. +The following flags affect device iteration: +.Bl -item -compact -offset indent +.It +.Dv DEVITER_F_RW +.It +.Dv DEVITER_F_SHUTDOWN +.It +.Dv DEVITER_F_LEAVES_FIRST +.It +.Dv DEVITER_F_ROOT_FIRST +.El +.It Fa deviter_t +This is a device iteration +.Dq cursor +or +.Dq iterator . +It holds iteration state such as the next device to visit. +.El +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn deviter_init "di" "flags" +Initialize the device iterator, +.Fa di . +Set bits in +.Fa flags +to affect the order of iteration. +Set +.Dv DEVITER_F_LEAVES_FIRST +to visit each device only after visiting its children (visit the +leaves of the device tree, first). +Set +.Dv DEVITER_F_ROOT_FIRST +to visit each device before visiting its children (visit the root +of the device tree, first). +If you set neither +.Dv DEVITER_F_LEAVES_FIRST +nor +.Dv DEVITER_F_ROOT_FIRST , +.Nm +returns devices in an arbitrary order. +.Pp +Set +.Dv DEVITER_F_RW +if your purpose for iterating over devices is to modify the device +tree by attaching or detaching devices. +Set +.Dv DEVITER_F_SHUTDOWN +if your purpose for iterating over devices is to detach all of +the devices during system shutdown. +.Dv DEVITER_F_SHUTDOWN +implies +.Dv DEVITER_F_RW . +.It Fn deviter_next "di" +Advance the iterator +.Fa di +to the next device. +.Fn deviter_next +returns the current device or +.Dv NULL +if there are no more devices. +.Fn deviter_next +is undefined if +.Fa di +has not been initialized using +.Fn deviter_init +or +.Fn deviter_first . +.It Fn deviter_first "di" "flags" +Initialize the iterator +.Fa di +with +.Fa flags . +Return the first device according to the ordering +indicated by +.Fa flags +and advance +.Fa di +to the second device, or +return +.Dv NULL +if there are no devices. +This is equivalent to calling +.Fn deviter_init "di" "flags" +and then +.Fn deviter_next "di" . +.It Fn deviter_release "di" +Release all resources held by the iterator +.Fa di . +Every iterator that is initialized with +.Fn deviter_first +or +.Fn deviter_init +MUST be released. +.El +.Sh CODE REFERENCES +Device iteration is implemented within the files +.Pa sys/sys/device.h +and +.Pa sys/kern/subr_autoconf.c . +.Sh SEE ALSO +.Xr autoconf 9 , +.Xr driver 9 +.Sh HISTORY +.Nm +appeared in +.Nx 5.0 . +.Sh AUTHORS +.An David Young Aq Mt dyoung@NetBSD.org diff --git a/static/netbsd/man9/devsw_attach.9 b/static/netbsd/man9/devsw_attach.9 new file mode 100644 index 00000000..48ccbbce --- /dev/null +++ b/static/netbsd/man9/devsw_attach.9 @@ -0,0 +1,185 @@ +.\" $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. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Kamil Rytarowski. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 2, 2023 +.Dt DEVSW 9 +.Os +.Sh NAME +.Nm devsw , +.Nm devsw_attach , +.Nm devsw_detach , +.Nm bdevsw_lookup , +.Nm cdevsw_lookup , +.Nm bdevsw_lookup_major , +.Nm cdevsw_lookup_major +.Nd character and block device switch functions +.Sh SYNOPSIS +.In sys/conf.h +.Ft int +.Fo devsw_attach +.Fa "const char *devname" +.Fa "const struct bdevsw *bev" +.Fa "devmajor_t *bmajor" +.Fa "const struct cdevsw *cdev" +.Fa "devmajor_t *cmajor" +.Fc +.Ft void +.Fo devsw_detach +.Fa "const struct bdevsw *bdev" +.Fa "const struct cdevsw *cdev" +.Fc +.Ft "const struct bdevsw *" +.Fo bdevsw_lookup +.Fa "dev_t dev" +.Fc +.Ft "const struct cdevsw *" +.Fo cdevsw_lookup +.Fa "dev_t dev" +.Fc +.Ft devmajor_t +.Fo bdevsw_lookup_major +.Fa "const struct bdevsw *bdev" +.Fc +.Ft devmajor_t +.Fo cdevsw_lookup_major +.Fa "const struct cdevsw *cdev" +.Fc +.Sh DESCRIPTION +If a device driver has character device interfaces accessed from +userland, the driver must define a +.Vt cdevsw +structure. +If the driver also has block device interfaces, the driver must +additionally define a +.Vt bdevsw +structure. +These structures are constant, and are defined within the +.Xr driver 9 . +.Pp +For drivers which are included in the kernel via +.Xr config 1 , +the +.Vt cdevsw +and +.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 +.Fa cdev +and optional +.Fa bdev +with the +.Xr driver 9 . +If there is no block device interface needed, +.Fa bdev +should be set to +.Dv NULL +and +.Fa bmajor +to +.Dv NODEVMAJOR . +The +.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 NODEVMAJOR +to the function for the +.Fa cmajor +or +.Fa bmajor , +the major number can be automatically generated. +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 +.Fa bdev +and +.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 +.Fa d_open +function will fail, before calling +.Fn devsw_detach . +.Pp +The +.Fn bdevsw_lookup +and +.Fn cdevsw_lookup +functions return +.Vt "const struct bdevsw *" +and +.Vt "const struct cdevsw *" +for the given +.Fa dev . +.Pp +The +.Fn bdevsw_lookup_major +and +.Fn cdevsw_lookup_major +functions return +.Vt "devmajor_t" +for the given +.Vt "const struct bdevsw *" +or +.Vt "const struct cdevsw *" . +.Sh RETURN VALUES +Upon successful completion, +.Fn devsw_attach +returns 0. +Otherwise it returns an error value. +.Pp +In case of failure, +.Fn bdevsw_lookup +and +.Fn cdevsw_lookup +return the +.Dv NULL +value. +.Pp +The +.Fn bdevsw_lookup_major +and +.Fn cdevsw_lookup_major +functions return +.Dv NODEVMAJOR +for an unsuccessful completion. +.Sh SEE ALSO +.Xr driver 9 diff --git a/static/netbsd/man9/disk.9 b/static/netbsd/man9/disk.9 new file mode 100644 index 00000000..1bd4d195 --- /dev/null +++ b/static/netbsd/man9/disk.9 @@ -0,0 +1,574 @@ +.\" $NetBSD: disk.9,v 1.46 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright (c) 1995, 1996 Jason R. Thorpe. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Jason R. Thorpe. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 5, 2017 +.Dt DISK 9 +.Os +.Sh NAME +.Nm disk , +.Nm disk_init , +.Nm disk_attach , +.Nm disk_begindetach , +.Nm disk_detach , +.Nm disk_destroy , +.Nm disk_wait , +.Nm disk_busy , +.Nm disk_unbusy , +.Nm disk_isbusy , +.Nm disk_find , +.Nm disk_set_info +.Nd generic disk framework +.Sh SYNOPSIS +.In sys/types.h +.In sys/disklabel.h +.In sys/disk.h +.Ft void +.Fn disk_init "struct disk *" "const char *name" "const struct dkdriver *driver" +.Ft void +.Fn disk_attach "struct disk *" +.Ft void +.Fn disk_begindetach "struct disk *" "int (*lastclose)(device_t)" "device_t self" "int flags" +.Ft void +.Fn disk_detach "struct disk *" +.Ft void +.Fn disk_destroy "struct disk *" +.Ft void +.Fn disk_wait "struct disk *" +.Ft void +.Fn disk_busy "struct disk *" +.Ft void +.Fn disk_unbusy "struct disk *" "long bcount" "int read" +.Ft bool +.Fn disk_isbusy "struct disk *" +.Ft struct disk * +.Fn disk_find "const char *" +.Ft void +.Fn disk_set_info "device_t" "struct disk *" "const char *type" +.Sh DESCRIPTION +The +.Nx +generic disk framework is designed to provide flexible, +scalable, and consistent handling of disk state and metrics information. +The fundamental component of this framework is the +.Nm disk +structure, which is defined as follows: +.Bd -literal +struct disk { + TAILQ_ENTRY(disk) dk_link; /* link in global disklist */ + const char *dk_name; /* disk name */ + prop_dictionary_t dk_info; /* reference to disk-info dictionary */ + int dk_bopenmask; /* block devices open */ + int dk_copenmask; /* character devices open */ + int dk_openmask; /* composite (bopen|copen) */ + int dk_state; /* label state ### */ + int dk_blkshift; /* shift to convert DEV_BSIZE to blks */ + int dk_byteshift; /* shift to convert bytes to blks */ + + /* + * Metrics data; note that some metrics may have no meaning + * on certain types of disks. + */ + struct io_stats *dk_stats; + + const struct dkdriver *dk_driver; /* pointer to driver */ + + /* + * Information required to be the parent of a disk wedge. + */ + kmutex_t dk_rawlock; /* lock on these fields */ + u_int dk_rawopens; /* # of opens of rawvp */ + struct vnode *dk_rawvp; /* vnode for the RAW_PART bdev */ + + kmutex_t dk_openlock; /* lock on these and openmask */ + u_int dk_nwedges; /* # of configured wedges */ + /* all wedges on this disk */ + LIST_HEAD(, dkwedge_softc) dk_wedges; + + /* + * Disk label information. Storage for the in-core disk label + * must be dynamically allocated, otherwise the size of this + * structure becomes machine-dependent. + */ + daddr_t dk_labelsector; /* sector containing label */ + struct disklabel *dk_label; /* label */ + struct cpu_disklabel *dk_cpulabel; +}; +.Ed +.Pp +The system maintains a global linked-list of all disks attached to the +system. +This list, called +.Nm disklist , +may grow or shrink over time as disks are dynamically added and removed +from the system. +Drivers which currently make use of the detachment +capability of the framework are the +.Nm ccd , +.Nm dm , +and +.Nm vnd +pseudo-device drivers. +.Pp +The following is a brief description of each function in the framework: +.Bl -tag -width ".Fn disk_set_info" +.It Fn disk_init +Initialize the disk structure. +.It Fn disk_attach +Attach a disk; allocate storage for the disklabel, set the +.Dq attached time +timestamp, insert the disk into the disklist, and increment the +system disk count. +.It Fn disk_begindetach +Check whether the disk is open, and if not, return 0. +If the disk is open, and +.Dv DETACH_FORCE +is not set in +.Fa flags , +return +.Dv EBUSY . +Otherwise, call the provided +.Fa lastclose +routine +.Po +if not +.Dv NULL +.Pc +and return its exit code. +.It Fn disk_detach +Detach a disk; free storage for the disklabel, remove the disk +from the disklist, and decrement the system disk count. +If the count drops below zero, panic. +.It Fn disk_destroy +Release resources used by the disk structure when it is no longer +required. +.It Fn disk_wait +Disk timings are measured by counting the number of queued +requests (wait counter) and requests issued to the hardware (busy counter) +and keeping timestamp when the counters change. +The time interval between +two changes of a counter is accumulated into a total and also multiplied +by the counter value and the accumulated into a sum. +Both values can be +used to determine how much time is spent in the driver queue or in-flight +to the hardware as well as the average number of requests in either state. +.Fn disk_wait +increment the disk's wait counter and handles the accumulation. +.It Fn disk_busy +Decrements the disk's wait counter and increments the disk's +.Dq busy counter , +and handles either accumulation. +If the wait counter is still zero, it +is assumed that the driver hasn't been updated to call +.Fn disk_wait , +then only the values from the busy counter are available. +.It Fn disk_unbusy +Decrement the disk's busy counter and handles the accumulation. +The third argument +.Ar read +specifies the direction of I/O; +if non-zero it means reading from the disk, +otherwise it means writing to the disk. +.It Fn disk_isbusy +Returns +.Ar true +if disk is marked as busy and false if it is not. +.It Fn disk_find +Return a pointer to the disk structure corresponding to the name provided, +or +.Dv NULL +if the disk does not exist. +.It Fn disk_set_info +Setup disk-info dictionary and other dependent values of the disk structure, +the driver must have initialized the dk_geom member of +.Fa struct disk +with suitable values. +If +.Fa type +is not +.Dv NULL , +it will be added to the dictionary. +.El +.Pp +The functions typically called by device drivers are +.Fn disk_init +.Fn disk_attach , +.Fn disk_begindetach , +.Fn disk_detach , +.Fn disk_destroy , +.Fn disk_wait , +.Fn disk_busy , +.Fn disk_unbusy , +and +.Fn disk_set_info . +The function +.Fn disk_find +is provided as a utility function. +.Sh DISK IOCTLS +The following ioctls should be implemented by disk drivers: +.Bl -tag -width "xxxxxx" +.It Dv DIOCGDINFO "struct disklabel" +Get disklabel. +.It Dv DIOCSDINFO "struct disklabel" +Set in-memory disklabel. +.It Dv DIOCWDINFO "struct disklabel" +Set in-memory disklabel and write on-disk disklabel. +.It Dv DIOCGPART "struct partinfo" +Get partition information. +This is used internally. +.It Dv DIOCRFORMAT "struct format_op" +Read format. +.It Dv DIOCWFORMAT "struct format_op" +Write format. +.It Dv DIOCSSTEP "int" +Set step rate. +.It Dv DIOCSRETRIES "int" +Set number of retries. +.It Dv DIOCKLABEL "int" +Specify whether to keep or drop the in-memory disklabel +when the device is closed. +.It Dv DIOCWLABEL "int" +Enable or disable writing to the part of the disk that contains the label. +.It Dv DIOCSBAD "struct dkbad" +Set kernel dkbad. +.It Dv DIOCEJECT "int" +Eject removable disk. +.It Dv DIOCLOCK "int" +Lock or unlock disk pack. +For devices with removable media, locking is intended to prevent +the operator from removing the media. +.It Dv DIOCGDEFLABEL "struct disklabel" +Get default label. +.It Dv DIOCCLRLABEL +Clear disk label. +.It Dv DIOCGCACHE "int" +Get status of disk read and write caches. +The result is a bitmask containing the following values: +.Bl -tag -width DKCACHE_RCHANGE +.It Dv DKCACHE_READ +Read cache enabled. +.It Dv DKCACHE_WRITE +Write(back) cache enabled. +.It Dv DKCACHE_RCHANGE +Read cache enable is changeable. +.It Dv DKCACHE_WCHANGE +Write cache enable is changeable. +.It Dv DKCACHE_SAVE +Cache parameters may be saved, so that they persist across reboots +or device detach/attach cycles. +.El +.It Dv DIOCSCACHE "int" +Set status of disk read and write caches. +The input is a bitmask in the same format as used for +.Dv DIOCGCACHE . +.It Dv DIOCCACHESYNC "int" +Synchronise the disk cache. +This causes information in the disk's write cache (if any) +to be flushed to stable storage. +The argument specifies whether or not to force a flush even if +the kernel believes that there is no outstanding data. +.It Dv DIOCBSLIST "struct disk_badsecinfo" +Get bad sector list. +.It Dv DIOCBSFLUSH +Flush bad sector list. +.It Dv DIOCAWEDGE "struct dkwedge_info" +Add wedge. +.It Dv DIOCGWEDGEINFO "struct dkwedge_info" +Get wedge information. +.It Dv DIOCDWEDGE "struct dkwedge_info" +Delete wedge. +.It Dv DIOCLWEDGES "struct dkwedge_list" +List wedges. +.It Dv DIOCGSTRATEGY "struct disk_strategy" +Get disk buffer queue strategy. +.It Dv DIOCSSTRATEGY "struct disk_strategy" +Set disk buffer queue strategy. +.It Dv DIOCGDISKINFO "struct plistref" +Get disk-info dictionary. +.It Dv DIOCGMEDIASIZE "off_t" +Get disk size in bytes. +.It Dv DIOCGSECTORSIZE "u_int" +Get sector size in bytes. +.El +.Sh USING THE FRAMEWORK +This section includes a description on basic use of the framework +and example usage of its functions. +Actual implementation of a device driver which uses the framework +may vary. +.Pp +Each device in the system uses a +.Dq softc +structure which contains autoconfiguration and state information for that +device. +In the case of disks, the softc should also contain one instance +of the disk structure, e.g.: +.Bd -literal +struct foo_softc { + device_t sc_dev; /* generic device information */ + struct disk sc_dk; /* generic disk information */ + [ . . . more . . . ] +}; +.Ed +.Pp +In order for the system to gather metrics data about a disk, the disk must +be registered with the system. +The +.Fn disk_attach +routine performs all of the functions currently required to register a disk +with the system including allocation of disklabel storage space, +recording of the time since boot that the disk was attached, and insertion +into the disklist. +Note that since this function allocates storage space for the disklabel, +it must be called before the disklabel is read from the media or used in +any other way. +Before +.Fn disk_attach +is called, a portions of the disk structure must be initialized with +data specific to that disk. +For example, in the +.Dq foo +disk driver, the following would be performed in the autoconfiguration +.Dq attach +routine: +.Bd -literal +void +fooattach(device_t parent, device_t self, void *aux) +{ + struct foo_softc *sc = device_private(self); + [ . . . ] + + /* Initialize and attach the disk structure. */ + disk_init(&sc->sc_dk, device_xname(self), &foodkdriver); + disk_attach(&sc->sc_dk); + + /* Read geometry and fill in pertinent parts of disklabel. */ + /* Initialize geometry values of the disk structure */ + [ . . . ] + disk_set_info(&self>, &sc->sc_dk, type); +} +.Ed +.Pp +The +.Nm foodkdriver +above is the disk's +.Dq driver +switch. +This switch currently includes pointers to several driver entry points, +where only the +.Nm d_strategy +entry point is used by the disk framework. +This switch needs to have global scope and should be initialized as follows: +.Bd -literal +void (foostrategy)(struct buf *); +void (foominphys)(struct buf *); +int (fooopen)(dev_t, int, int, struct lwp *); +int (fooclose)(dev_t, int, int, struct lwp *); +int (foo_discard)(device_t, off_t, off_t); +int (foo_diskstart)(device_t, struct buf *); +void (foo_iosize)(device_t, int *); +int (foo_dumpblocks)(device_t, void *, daddr_t, int); +int (foo_lastclose)(device_t); +int (foo_firstopen)(device_t, dev_t, int, int); +int (foo_label)(device_t, struct disklabel *); + +const struct dkdriver foodkdriver = { + .d_open = fooopen, + .d_close = fooclose, + .d_strategy = foostrategy, + .d_minphys = foominphys, + .d_discard = foo_discard, + .d_diskstart = foo_diskstart, /* optional */ + .d_dumpblocks = foo_dumpblocks, /* optional */ + .d_iosize = foo_iosize, /* optional */ + .d_firstopen = foo_firstopen, /* optional */ + .d_lastclose = foo_lastclose, /* optional */ + .d_label = foo_label, /* optional */ +}; +.Ed +.Pp +Once the disk is attached, metrics may be gathered on that disk. +In order to gather metrics data, the driver must tell the framework when +the disk queues, starts and stops operations. +This functionality is provided by the +.Fn disk_wait , +.Fn disk_busy +and +.Fn disk_unbusy +routines. +Because +.Nm struct disk +is part of device driver private data it needs to be guarded. +Mutual exclusion must be done by driver +.Fn disk_wait , +.Fn disk_busy +and +.Fn disk_unbusy +are not thread safe. +The +.Fn disk_busy +routine should be called immediately before a command to the disk is +sent, e.g.: +.Bd -literal +void +foostrategy(struct buf *bp) +{ + [ . . . ] + + mutex_enter(&sc->sc_dk_mtx); + disk_wait(&sc->sc_dk); + + /* Put buffer onto drive's transfer queue */ + + mutex_exit(&sc->sc_dk_mtx); + + foostart(sc); +} + +void +foostart(struct foo_softc *sc) +{ + [ . . . ] + + /* Get buffer from drive's transfer queue. */ + [ . . . ] + + /* Build command to send to drive. */ + [ . . . ] + + /* Tell the disk framework we're going busy. */ + mutex_enter(&sc->sc_dk_mtx); + disk_busy(&sc->sc_dk); + mutex_exit(&sc->sc_dk_mtx); + + /* Send command to the drive. */ + [ . . . ] +} +.Ed +.Pp +The routine +.Fn disk_unbusy +performs some consistency checks, such as ensuring that the calls to +.Fn disk_busy +and +.Fn disk_unbusy +are balanced. +It also performs the final steps of the metrics calcuation. +A byte count is added to the disk's running total, and if greater than +zero, the number of transfers the disk has performed is incremented. +The third argument +.Ar read +specifies the direction of I/O; +if non-zero it means reading from the disk, +otherwise it means writing to the disk. +.Bd -literal +void +foodone(xfer) + struct foo_xfer *xfer; +{ + struct foo_softc = (struct foo_softc *)xfer->xf_softc; + struct buf *bp = xfer->xf_buf; + long nbytes; + [ . . . ] + + /* + * Get number of bytes transferred. If there is no buf + * associated with the xfer, we are being called at the + * end of a non-I/O command. + */ + if (bp == NULL) + nbytes = 0; + else + nbytes = bp->b_bcount - bp->b_resid; + + [ . . . ] + + mutex_enter(&sc->sc_dk_mtx); + /* Notify the disk framework that we've completed the transfer. */ + disk_unbusy(&sc->sc_dk, nbytes, + bp != NULL ? bp->b_flags & B_READ : 0); + mutex_exit(&sc->sc_dk_mtx); + + [ . . . ] +} +.Ed +.Pp +.Fn disk_isbusy +is used to get status of disk device it returns true if device is +currently busy and false if it is not. +Like +.Fn disk_wait , +.Fn disk_busy +and +.Fn disk_unbusy +it requires explicit locking from user side. +.Sh CODE REFERENCES +The disk framework itself is implemented within the file +.Pa sys/kern/subr_disk.c . +Data structures and function prototypes for the framework are located in +.Pa sys/sys/disk.h . +.Pp +The +.Nx +machine-independent SCSI disk and CD-ROM drivers use the +disk framework. +They are located in +.Pa sys/scsi/sd.c +and +.Pa sys/scsi/cd.c . +.Pp +The +.Nx +.Nm ccd , +.Nm dm , +and +.Nm vnd +drivers use the detachment capability of the framework. +They are located in +.Pa sys/dev/ccd.c , +.Pa sys/dev/vnd.c , +and +.Pa sys/dev/dm/device-mapper.c . +.Sh SEE ALSO +.Xr ccd 4 , +.Xr dm 4 , +.Xr vnd 4 , +.Xr dksubr 9 +.Sh HISTORY +The +.Nx +generic disk framework appeared in +.Nx 1.2 . +.Sh AUTHORS +The +.Nx +generic disk framework was architected and implemented by +.An Jason R. Thorpe +.Aq Mt thorpej@NetBSD.org . diff --git a/static/netbsd/man9/disklabel.9 b/static/netbsd/man9/disklabel.9 new file mode 100644 index 00000000..7f4b19f5 --- /dev/null +++ b/static/netbsd/man9/disklabel.9 @@ -0,0 +1,182 @@ +.\" $NetBSD: disklabel.9,v 1.13 2008/04/30 13:10:58 martin Exp $ +.\" +.\" Copyright (c) 1996 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Paul Kranenburg. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 26, 1996 +.Dt DISKLABEL 9 +.Os +.Sh NAME +.Nm disklabel , +.Nm readdisklabel , +.Nm writedisklabel , +.Nm setdisklabel , +.Nm bounds_check_with_label +.Nd disk label management routines +.Sh SYNOPSIS +.Ft char * +.Fn readdisklabel "dev_t dev" "void (*strat)(struct buf *)" "struct disklabel *lp" "struct cpu_disklabel *clp" +.Ft int +.Fn writedisklabel "dev_t dev" "void (*strat)(struct buf *)" "struct disklabel *lp" "struct cpu_disklabel *clp" +.Ft int +.Fn setdisklabel "struct disklabel *olp" "struct disklabel *nlp" "u_long openmask" "struct cpu_disklabel *clp" +.Ft int +.Fn bounds_check_with_label "struct buf *bp" "struct disklabel *lp" "int wlabel" +.Sh DESCRIPTION +This collection of routines provides a disklabel management interface to +kernel device drivers. +These routines are classified as machine- or architecture-dependent because +of restrictions imposed by the machine architecture and boot-strapping code +on the location of the label, or because cooperation with other operating +systems requires specialized conversion code. +.Pp +.Fn readdisklabel +attempts to read a disklabel from the device identified by +.Fa dev , +using the device strategy routine passed in +.Fa strat . +Note that a buffer structure is required to pass to the strategy routine; +it needs to be acquired and parameterized for the intended I/O operation, +and disposed of when the operation has completed. +Some fields in the disklabel passed in +.Fa lp +may be pre-initialized by the caller in order to meet device driver +requirements for the I/O operation initiated to get to the disklabel data +on the medium. +In particular, the field +.Dq d_secsize , +if non-zero, is used by +.Fn readdisklabel +to get an appropriately sized buffer to pass to the device strategy routine. +Unspecified fields in +.Fa lp +should be set to zero. +If the medium does not contain a native disklabel that can be read in directly, +.Fn readdisklabel +may resort to constructing a label from other machine-dependent information +using the provided buffer passed in the +.Fa clp +argument. +If a disk label can not be found or constructed, a string containing +an approximated description of the failure mode is returned. +Otherwise the +.Dv NULL +string is returned. +.Pp +.Fn writedisklabel +stores disk label information contained in the disk label structure given by +.Fa lp +on the device identified by +.Fa dev . +Like +.Fn readdisklabel , +it acquires and sets up an I/O buffer to pass to the strategy routine +.Fa strat . +.Fn writedisklabel +may elect to do a machine-dependent conversion of the native disk label +structure +.Po +using the buffer pointed at by +.Fa clp +.Pc , +to store the disk label onto the medium in a format complying with +architectural constraints. +.Fn writedisklabel +returns 0 on success and +.Dv EINVAL +if the disk label specifies invalid or inconvertible values. +Otherwise, any error condition reported by the device strategy routine +in the buffer's +.Dq Va b_error +field is returned. +.Pp +.Fn setdisklabel +checks a proposed new disk label passed in +.Fa nlp +for some amount of basic sanity. +This includes a check on attempts to +change the location, or reduce the size, of an existing disk partition +that is currently in use by the system. +The current disposition of the disk partitions is made available through +.Fa olp +and +.Fa openmask , +which provide, respectively, the existing disk label and a bit mask +identifying the partitions that are currently in use. +Failure to pass on +.Dq basic sanity , +results in a +.Dv EINVAL +return value, while a vetoed update of the partition layout is signaled by a +.Dv EBUSY +return value. +Otherwise, 0 is returned. +.Pp +.Fn bounds_check_with_label +is used to check whether a device transfer described by +.Fa bp +to the device identified by +.Fa dev , +is properly contained within a disk partition of the disk with label +.Fa lp . +If this check fails, +.Fn bounds_check_with_label +sets the buffer's +.Dq Va b_error +field to +.Dv EINVAL , +sets the +.Dv B_ERROR +flag in +.Dq Va b_flags , +and returns -1. +If the argument +.Fa wlabel +is zero, and the transfer is a write operation, a check is done if the transfer +would overwrite +.Pq a portion of +the disklabel area on the medium. +If that is the case, +.Dv EROFS +is set in +.Dq Va b_error , +the +.Dv B_ERROR +flag is set in +.Dq Va b_flags , +and -1 is returned. +Note that +.Fa wlabel +should be set to a non-zero value if the intended operation is expected to +install or update the disk label. +Programs that intend to do so using the raw device interface should notify +the driver by using a +.Dv DIOCWLABEL +ioctl function. +.Sh SEE ALSO +.Xr disklabel 5 , +.Xr disklabel 8 diff --git a/static/netbsd/man9/dksubr.9 b/static/netbsd/man9/dksubr.9 new file mode 100644 index 00000000..83a72123 --- /dev/null +++ b/static/netbsd/man9/dksubr.9 @@ -0,0 +1,309 @@ +.\" $NetBSD: dksubr.9,v 1.7 2019/12/08 12:23:00 mlelstv Exp $ +.\" +.\" Copyright (c) 2016 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd November 28, 2016 +.Dt DKSUBR 9 +.Os +.Sh NAME +.Nm dk_softc , +.Nm dk_init , +.Nm dk_attach , +.Nm dk_detach , +.Nm dk_open , +.Nm dk_close , +.Nm dk_size , +.Nm dk_dump , +.Nm dk_ioctl , +.Nm dk_strategy , +.Nm dk_strategy_defer , +.Nm dk_strategy_pending , +.Nm dk_start , +.Nm dk_done , +.Nm dk_drain , +.Nm dk_discard , +.Nm dk_getdefaultlabel , +.Nm dk_getdisklabel +.Nd disk driver subroutines +.Sh SYNOPSIS +.In sys/bufq.h +.In sys/disk.h +.In dev/dkvar.h +.Ft void +.Fn dk_init "struct dk_softc *" "device_t" "int dtype" +.Ft void +.Fn dk_attach "struct dk_softc *" +.Ft void +.Fn dk_detach "struct dk_softc *" +.Ft int +.Fn dk_open "struct dk_softc *" "dev_t" "int flags" "int fmt" "struct lwp *" +.Ft int +.Fn dk_close "struct dk_softc *" "dev_t" "int flags" "int fmt" "struct lwp *" +.Ft int +.Fn dk_discard "struct dk_softc *" "dev_t" "off_t pos" "off_t len" +.Ft int +.Fn dk_size "struct dk_softc *" "dev_t" +.Ft int +.Fn dk_dump "struct dk_softc *" "dev_t" "daddr_t blkno" "void *vav" "size_t size" +.Ft int +.Fn dk_ioctl "struct dk_softc *" "dev_t" "u_long cmd" "void *data" "int flag" "struct lwp *" +.Ft void +.Fn dk_strategy "struct dk_softc *" "struct buf *" +.Ft int +.Fn dk_strategy_defer "struct dk_softc *" "struct buf *" +.Ft int +.Fn dk_strategy_pending "struct dk_softc *" +.Ft void +.Fn dk_start "struct dk_softc *" "struct buf *" +.Ft void +.Fn dk_done "struct dk_softc *" "struct buf *" +.Ft int +.Fn dk_drain "struct dk_softc *" +.Ft void +.Fn dk_getdefaultlabel "struct dk_softc *" "struct disklabel *" +.Ft void +.Fn dk_getdisklabel "struct dk_softc *" "dev_t" +.Sh DESCRIPTION +The disk driver subroutines provide common functionality for all disk drivers +to reduce the amount of replicated code. +For many disk drivers, their +corresponding entry points can be made mostly stubs. +.Pp +The subroutines encapsulate data structures found in a driver's softc +into +.Bd -literal +struct dk_softc { + device_t sc_dev; + struct disk sc_dkdev; + struct bufq_state sc_bufq; + krndsource_t sc_rnd_source; +\&... +} +.Ed +The +.Nm dk_softc +structure therefore replaces the +.Nm device_t +member of the driver's softc struct. +.Pp +The following is a brief description of each function in the framework: +.Bl -tag -width ".Fn dk_strategy_pending" +.It Fn dk_init +Initialize the dk_softc structure. +.It Fn dk_attach +Attach framework after driver has attached the +.Xr disk 9 +subsystem, created a +.Xr bufq 9 +and is ready to handle I/O. +.It Fn dk_detach +Undo dk_attach. +.It Fn dk_open +Handles open steps for the +.Xr disk 9 +framework, acquires the disklabel and validates open parameters. +The driver may provide the +.Nm d_firstopen +callback to handle initialization steps. +.It Fn dk_close +Handles close steps for the +.Xr disk 9 +framework. +The driver may provide the +.Nm d_lastclose +callback to handle finalization steps. +.Nm dk_open +and +.Nm dk_close +are serialized by the openlock mutex. +.It Fn dk_discard +Validates parameters, computes raw block numbers and passes +these to the +.Nm d_discard +callback. +.It Fn dk_size +Returns dump size information from the +.Xr disklabel 9 +and opens and closes the driver when necessary. +.It Fn dk_dump +Validates parameters, computes raw block numbers and iterates +over the +.Nm d_dumpblocks +callback in appropriate chunks determined by the +.Nm d_iosize +callback. +.It Fn dk_ioctl +Handles the ioctls +.Dv DIOCKLABEL , +.Dv DIOCWLABEL , +.Dv DIOCGDEFLABEL , +.Dv DIOCGSTRATEGY , +and +.Dv DIOCSSTRATEGY +and passes other disk ioctls through the +.Xr disk 9 +framework. +Returns +.Nm ENOTTY +when an ioctl isn't implemented. +This routine is run as a fallback to +handle commands that are not specific to the driver. +.It Fn dk_strategy +Validates parameters, computes raw block numbers, queues a buffer for I/O +and triggers queue processing by calling +.Nm dk_start . +.It Fn dk_strategy_defer +Alternative to +.Nm dk_strategy +that only queues the buffer. +Drivers that implement a separate I/O thread +can use +.Nm dk_strategy_defer +within their own strategy routine and signal the thread through a private +interface. +.It Fn dk_strategy_pending +This function is called by an I/O thread to determine if work has been +queued by +.Nm dk_strategy_defer . +The driver must then call +.Nm dk_start +to trigger queue processing. +.It Fn dk_start +If +.Ar bp != Dv NULL +put it into the queue. +Run the +.Nm d_diskstart +callback for every buffer until the queue is empty or the callback returns +.Nm EAGAIN . +In the latter case, the buffer is saved and issued on the +next queue run. +This also calls +.Nm disk_busy +accordingly to handle I/O metrics. +.It Fn dk_done +Called by the driver when an I/O operation completed. +.Nm dk_done +logs errors, calls +.Nm disk_unbusy +to handle I/O metrics and collects entropy for the +.Xr cprng 9 . +.It Fn dk_drain +Aborts all queued I/O. +This function must be called instead of +.Fn bufq_drain +to cooperate with +.Nm dk_start . +.It Fn dk_getdefaultlabel +Compute a common default disklabel for all disk drivers. +Some drivers provide device specific information or assign specific +disk formats to partitions. +Such drivers may implement the +.Nm d_label +callback that is called by +.Nm dk_getdefaultlabel +after initializing the label with common values. +.It Fn dk_getdisklabel +Read disklabel with machine dependent low-level function +.Nm readdisklabel +and do sanity checks. +.El +.Sh DRIVER INTERFACE +The driver needs to provide a common set of entry points that are +used by the disk driver subroutines and the +.Xr disk 9 +framework. +.Bd -literal +struct dkdriver { + void (*d_strategy)(struct buf *); + void (*d_minphys)(struct buf *); + int (*d_open)(dev_t, int, int, struct lwp *); + int (*d_close)(dev_t, int, int, struct lwp *); + int (*d_diskstart)(device_t, struct buf *); + void (*d_iosize)(device_t, int *); + int (*d_dumpblocks)(device_t, void *, daddr_t, int); + int (*d_lastclose)(device_t); + int (*d_discard)(device_t, off_t, off_t); + int (*d_firstopen)(device_t, dev_t, int, int); + void (*d_label)(device_t, struct disklabel *); +}; +.Ed +.Bl -tag -width ".Fn dk_firstopen" +.It Fn d_strategy +The driver strategy routine queues a single buffer for I/O +and starts queue processing as appropriate. +.It Fn d_minphys +The driver minphys routine limits the buffer +.Nm b_bcount +to the maximum size for an I/O transfer supported by the driver +and hardware. +It also calls +.Nm minphys +to apply the platform limit. +.It Fn d_open +The driver open routine. +.It Fn d_close +The driver close routine. +.It Fn d_diskstart +Issues a single I/O request, called by +.Nm dk_start . +.It Fn d_iosize +Truncate I/O size to the driver limit. +This is similar to +.Nm minphys +but operates on an integer value instead of a buffer. +.It Fn d_dumpblocks +Issue a single I/O requests, called by +.Nm dk_dump . +.It Fn d_lastclose +Private cleanup after last user is finished. +Often used to flush write caches. +.It Fn d_discard +Issue a single I/O request to invalidate a disk region. +.It Fn d_firstopen +Private initialization when first user opens the driver. +.El +.Sh SEE ALSO +.Xr cgd 4 , +.Xr ld 4 , +.Xr cprng 9 , +.Xr disk 9 , +.Xr driver 9 +.Sh HISTORY +The +.Nx +common disk driver subroutines appeared in +.Nx 2.0 +as a base for the cryptographic disk driver and was extended +to handle disk wedges in +.Nx 4.0 . +Most functionality provided by +.Xr ld 4 +was included and extended in +.Nx 8.0 +to support other disk drivers. +The callback interface used by the +.Xr disk 9 +framework has been merged as well. diff --git a/static/netbsd/man9/dmover.9 b/static/netbsd/man9/dmover.9 new file mode 100644 index 00000000..f6d8e413 --- /dev/null +++ b/static/netbsd/man9/dmover.9 @@ -0,0 +1,622 @@ +.\" $NetBSD: dmover.9,v 1.15 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright (c) 2002 Wasabi Systems, Inc. +.\" All rights reserved. +.\" +.\" Written by Jason R. Thorpe for Wasabi Systems, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project by +.\" Wasabi Systems, Inc. +.\" 4. The name of Wasabi Systems, Inc. may not be used to endorse +.\" or promote products derived from this software without specific prior +.\" written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL WASABI SYSTEMS, INC +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 4, 2007 +.Dt DMOVER 9 +.Os +.Sh NAME +.Nm dmover_backend_register , +.Nm dmover_backend_unregister , +.Nm dmover_session_create , +.Nm dmover_session_destroy , +.Nm dmover_request_alloc , +.Nm dmover_request_free , +.Nm dmover_process , +.Nm dmover_done +.Nd hardware-assisted data mover interface +.Sh SYNOPSIS +.In dev/dmover/dmovervar.h +.Pp +Client interface routines: +.Pp +.Ft int +.Fn "dmover_session_create" "const char *" "struct dmover_session **" +.Ft void +.Fn "dmover_session_destroy" "struct dmover_session *" +.Ft "struct dmover_request *" +.Fn "dmover_request_alloc" "struct dmover_session *" "dmover_buffer *" +.Ft void +.Fn "dmover_request_free" "struct dmover_request *" +.Ft void +.Fn "dmover_process" "struct dmover_request *" +.Pp +Back-end interface routines: +.Pp +.Ft void +.Fn "dmover_backend_register" "struct dmover_backend *" +.Ft void +.Fn "dmover_backend_unregister" "struct dmover_backend *" +.Ft void +.Fn "dmover_done" "struct dmover_request *" +.Sh DESCRIPTION +The +.Nm dmover +facility provides an interface to hardware-assisted data movers. +This can be used to copy data from one location in memory to another, clear +a region of memory, fill a region of memory with a pattern, and perform +simple operations on multiple regions of memory, such as an XOR, without +intervention by the CPU. +.Pp +The drivers for hardware-assisted data movers present themselves to +.Nm dmover +by registering their capabilities. +When a client wishes to use a +.Nm dmover +function, it creates a session for that function, which identifies back-ends +capable of performing that function. +The client then enqueues requests on that session, which the back-ends +process asynchronously. +The client may choose to block until the request is completed, or may +have a call-back invoked once the request has been completed. +.Pp +When a client creates a session, the +.Nm dmover +facility identifies back-ends which are capable of handling the requested +function. +When a request is scheduled for processing, the +.Nm dmover +scheduler will identify the best back-end to process the request from +the list of candidate back-ends, in an effort to provide load balancing, +while considering the relative performance of each back-end. +.Pp +A +.Nm dmover +function always has one output region. +A function may have zero or more input regions, or may use an immediate +value as an input. +For functions which use input regions, the lengths of each input region +and the output region must be the same. +All +.Nm dmover +functions with the same name will have the same number of and type inputs. +If a back-end attempts to register a function which violates this invariant, +behavior is undefined. +.Pp +The +.Nm dmover +facility supports several types of buffer descriptors. +For functions which use input regions, each input buffer descriptor and +the output buffer descriptor must be of the same type. +This restriction may be removed in a future revision of the interface. +.Pp +The +.Nm dmover +facility may need to interrupt request processing and restart it. +Clients of the +.Nm dmover +facility should take care to avoid unwanted side-effects should this occur. +In particular, for functions which use input regions, no input region may +overlap with the output region. +.Ss DATA STRUCTURES +The +.Nm dmover +facility shares several data structures between the client and +back-end in order to describe sessions and requests. +.Bd -literal -offset indent +typedef enum { + DMOVER_BUF_LINEAR, + DMOVER_BUF_UIO +} dmover_buffer_type; + +typedef struct { + void *l_addr; + size_t l_len; +} dmover_buf_linear; + +typedef union { + dmover_buf_linear dmbuf_linear; + struct uio *dmbuf_uio; +} dmover_buffer; +.Ed +.Pp +Together, these data types are used to describe buffer data structures +which the +.Nm dmover +facility understands. +Additional buffer types may be added in future revisions of the +.Nm dmover +interface. +.Pp +The +.Fa dmover_assignment +structure contains the information about the back-end to which a +request is currently assigned. +It contains the following public members: +.Bl -tag -width "XXXX" +.It struct dmover_backend *das_backend +This is a pointer to the back-end. +.It const struct dmover_algdesc *das_algdesc +This is a pointer to the algorithm description provided by +the back-end for the request's function. +.El +.Pp +The +.Fa dmover_session +structure contains the following public members: +.Bl -tag -width "XXXX" +.It void *dses_cookie +This is a pointer to client private data. +.It int dses_ninputs +This is the number of inputs used by the selected function. +.El +.Pp +The +.Fa dmover_request +structure contains the following public members: +.Bl -tag -width "XXXX" +.It TAILQ_ENTRY(dmover_request) dreq_dmbq +Linkage on the back-end's queue of pending requests. +.It struct dmover_session *dreq_session +Pointer to the session with which this request is associated. +This is intended for use by the back-end. +.It struct dmover_assignment *dreq_assignment +Pointer to the +.Fa dmover_assignment +structure which describes the back-end to which the request is +currently assigned. +The back-end is assigned when the request is scheduled with +.Fn dmover_process . +.It void (*dreq_callback)(struct dmover_request *) +This is a pointer to an optional call-back function provided by the +client. +If provided, the call-back is invoked when the request is complete. +This field must be +.Dv NULL +if +.Em DMOVER_REQ_WAIT +is set in +.Em dreq_flags . +.It void *dreq_cookie +This is a pointer to client private data specific to the request. +.It void *dreq_dmbcookie +This is a pointer to back-end private data, for use while the back-end +is actively processing a request. +.It volatile int dreq_flags +The following flags are defined: +.Bl -tag -width "DMOVER_REQ_RUNNINGXX" +.It DMOVER_REQ_DONE +The request has been completed. +If not using a call-back, the client may poll this bit to determine +if a request has been processed. +.It DMOVER_REQ_ERROR +An error has occurred while processing the request. +.It DMOVER_REQ_RUNNING +The request is currently being executed by the back-end. +Once a command is running, it cannot be cancelled, and must run to completion. +.It DMOVER_REQ_WAIT +If set by the client, +.Fn dmover_process +will wait for the request to complete using +.Xr cv_wait 9 . +This flag may only be used if the caller has a valid thread context. +If this flag is set, a callback may not be used. +.El +.It int dreq_error +If the +.Em DMOVER_REQ_ERROR +bit is set, this contains the +.Xr errno 2 +value indicating the error that occurred during processing. +.It dmover_buffer_type dreq_outbuf_type +The type of the output buffer. +.It dmover_buffer dreq_outbuf +The output buffer. +.It uint8_t dreq_immediate[8] +This is the input for algorithms which use an immediate value. +Values smaller than 8 bytes should use the least-significant bytes first. +For example, a 32-bit integer would occupy bytes 0, 1, 2, and 3. +.It dmover_buffer_type dreq_inbuf_type +The type of the input buffer. +This is only used if the +.Nm dmover +function has one or more inputs. +.It dmover_buffer *dreq_inbuf +A pointer to an array of input buffers. +This is only used if the +.Nm dmover +function has one or more inputs. +The number of inputs, and thus the number of valid elements in the +array, is specified by the algorithm description for the session. +.El +.Ss CLIENT INTERFACE +The following functions are provided to the client: +.Bl -tag -width "XXXX" +.It Fn dmover_session_create "function" "sessionp" +.Pp +The +.Fn dmover_session_create +function creates a data mover session for the specified data movement +function +.Fa function . +A handle to the new session is returned in +.Fa sessionp . +.Pp +The following are valid data movement function names: +.Bl -tag -width "fill8xx" +.It Dq zero +Fill a memory region with zeros. +This algorithm has an input count of 0. +.It Dq fill8 +Fill a memory region with an 8-bit pattern. +This algorithm has an input count of 0. +The pattern is provided in the +.Em dreq_imm8 +member of the +.Fa dmover_request +structure. +.It Dq copy +Copy a memory region from one location to another. +This algorithm has an input count of 1. +.It Dq xor2 +Perform an XOR operation on 2 inputs. +This algorithm has an input count of 2. +.It Dq xor3 +Perform an XOR operation on 3 inputs. +This algorithm has an input count of 3. +.It Dq xor4 +Perform an XOR operation on 4 inputs. +This algorithm has an input count of 4. +.It Dq xor5 +Perform an XOR operation on 5 inputs. +This algorithm has an input count of 5. +.It Dq xor6 +Perform an XOR operation on 6 inputs. +This algorithm has an input count of 6. +.It Dq xor7 +Perform an XOR operation on 7 inputs. +This algorithm has an input count of 7. +.It Dq xor8 +Perform an XOR operation on 8 inputs. +This algorithm has an input count of 8. +.El +.Pp +Users of the +.Nm dmover +facility are encouraged to use the following aliases for the well-known +function names, as doing so saves space and reduces the chance of programming +errors: +.Bl -tag -width "DMOVER_FUNC_FILL32xx" +.It DMOVER_FUNC_ZERO +.Dq zero +.Pq Va dmover_funcname_zero +.It DMOVER_FUNC_FILL8 +.Dq fill8 +.Pq Va dmover_funcname_fill8 +.It DMOVER_FUNC_COPY +.Dq copy +.Pq Va dmover_funcname_copy +.It DMOVER_FUNC_XOR2 +.Dq xor2 +.Pq Va dmover_funcname_xor2 +.It DMOVER_FUNC_XOR3 +.Dq xor3 +.Pq Va dmover_funcname_xor3 +.It DMOVER_FUNC_XOR4 +.Dq xor4 +.Pq Va dmover_funcname_xor4 +.It DMOVER_FUNC_XOR5 +.Dq xor5 +.Pq Va dmover_funcname_xor5 +.It DMOVER_FUNC_XOR6 +.Dq xor6 +.Pq Va dmover_funcname_xor6 +.It DMOVER_FUNC_XOR7 +.Dq xor7 +.Pq Va dmover_funcname_xor7 +.It DMOVER_FUNC_XOR8 +.Dq xor8 +.Pq Va dmover_funcname_xor8 +.El +.It Fn dmover_session_destroy "session" +.Pp +The +.Fn dmover_session_destroy +function tears down a data mover session and releases all resources +associated with it. +.It Fn dmover_request_alloc "session" "inbuf" +.Pp +The +.Fn dmover_request_alloc +function allocates a +.Nm dmover +request structure and associates it with the specified session. +If the +.Fa inbuf +argument is not +.Dv NULL , +.Fa inbuf +is used as the array of input buffer descriptors in the request. +Otherwise, if +.Fa inbuf +is +.Dv NULL +and the +.Nm dmover +function requires input buffers, the input buffer descriptors will be +allocated automatically using +.Xr malloc 9 . +.Pp +If the request structure or input buffer descriptors cannot be allocated, +.Fn dmover_request_alloc +return +.Dv NULL +to indicate failure. +.It Fn dmover_request_free "req" +.Pp +The +.Fn dmover_request_free +function frees a +.Nm dmover +request structure. +If the +.Nm dmover +function requires input buffers, and the input buffer descriptors +associated with +.Fa req +were allocated by +.Fn dmover_request_alloc , +then the input buffer descriptors will also be freed. +.It Fn dmover_process "req" +.Pp +The +.Fn dmover_process +function submits the +.Nm dmover +request +.Fa req +for processing. +The call-back specified by the request is invoked when processing is +complete. +.El +.Pp +The +.Fn dmover_session_create +and +.Fn dmover_session_destroy +functions must not be called from interrupt context. +.Pp +The +.Fn dmover_request_alloc , +.Fn dmover_request_free , +and +.Fn dmover_process +functions may be called from interrupt handlers at levels +.Em IPL_VM , +.Em IPL_SOFTCLOCK , +and +.Em IPL_SOFTNET , +or in non-interrupt context. +.Pp +The request completion call-back is called from a software interrupt +handler at +.Em IPL_SOFTCLOCK . +.Ss BACK-END INTERFACE +A back-end describes the +.Nm dmover +functions it can perform using an array of +.Fa dmover_algdesc +structures: +.Bd -literal -offset indent +struct dmover_algdesc { + const char *dad_name; /* algorithm name */ + void *dad_data; /* opaque algorithm description */ + int dad_ninputs; /* number of inputs */ +}; +.Ed +.Pp +The +.Em dad_name +member points to a valid +.Nm dmover +function name which the client may specify. +The +.Em dad_data +member points to a back-end-specific description of the algorithm. +.Pp +A back-end presents itself to the +.Nm dmover +facility using the +.Fa dmover_backend +structure. +The back-end must initialize the following members of the structure: +.Bl -tag -width "XXXX" +.It const char *dmb_name +This is the name of the back-end. +.It u_int dmb_speed +This is an estimate of the number of kilobytes/second that the +back-end can process. +.It void *dmb_cookie +This is a pointer to back-end private data. +.It const struct dmover_algdesc *dmb_algdescs +This points to an array of +.Fa dmover_algdesc +structures which describe the functions the data mover can perform. +.It int dmb_nalgdescs +This is the number of elements in the +.Em dmb_algdescs +array. +.It void (*dmb_process)(struct dmover_backend *) +This is the entry point to the back-end used to process requests. +.El +.Pp +When invoked by the +.Nm dmover +facility, the back-end's +.Fn (*dmb_process) +function should examine the pending request queue in its +.Fa dmover_backend +structure: +.Bl -tag -width "XXXX" +.It TAILQ_HEAD(, dmover_request) dmb_pendreqs +This is the queue of pending requests. +.It int dmb_npendreqs +This is the number of requests in the +.Em dmb_pendreqs +queue. +.El +.Pp +If an error occurs when processing the request, the +.Em DMOVER_REQ_ERROR +bit must be set in the +.Em dreq_flags +member of the request, and the +.Em dreq_error +member set to an +.Xr errno 2 +value to indicate the error. +.Pp +When the back-end has finished processing the request, it must call +the +.Fn dmover_done +function. +This function eventually invokes the client's call-back routine. +.Pp +If a hardware-assisted data mover uses interrupts, the interrupt handlers +should be registered at IPL_VM. +.Pp +The following functions are provided to the back-ends: +.Bl -tag -width "XXXX" +.It Fn dmover_backend_register "backend" +.Pp +The +.Fn dmover_backend_register +function registers the back-end +.Fa backend +with the +.Nm dmover +facility. +.It Fn dmover_backend_unregister "backend" +.Pp +The +.Fn dmover_backend_unregister +function removes the back-end +.Fa backend +from the +.Nm dmover +facility. +The back-end must already be registered. +.It Fn dmover_done "req" +.Pp +The +.Fn dmover_done +function is called by the back-end when it has finished processing +a request, whether the request completed successfully or not. +.El +.Pp +The +.Fn dmover_backend_register +and +.Fn dmover_backend_unregister +functions must not be called from interrupt context. +.Pp +The +.Fn dmover_done +function may be called at +.Em IPL_VM , +.Em IPL_SOFTCLOCK , +.Em IPL_SOFTNET , +or in non-interrupt context. +.Sh EXAMPLES +The following is an example of a client using +.Nm dmover +to zero-fill a region of memory. +In this example, the CPU will be able to context switch to another +thread and perform work while the hardware-assisted data mover clears +the specified block of memory. +.Bd -literal +int +hw_bzero(void *buf, size_t len) +{ + struct dmover_session *dses; + struct dmover_request *dreq; + int error; + + error = dmover_session_create(DMOVER_FUNC_ZERO, &dses); + if (error) + return (error); + + dreq = dmover_request_alloc(dses, NULL); + if (dreq == NULL) { + dmover_session_destroy(dses); + return (ENOMEM); + } + + dreq->dreq_flags = DMOVER_REQ_WAIT; + dreq->dreq_callback = NULL; + dreq->dreq_outbuf.dreq_outbuf_type = DMOVER_BUF_LINEAR; + dreq->dreq_outbuf.dmbuf_linear.l_addr = buf; + dreq->dreq_outbuf.dmbuf_linear.l_len = len; + + dmover_process(dreq); + + error = (dreq->dreq_flags & DMOVER_REQ_ERROR) ? + dreq->dreq_error : 0; + + dmover_request_free(dreq); + dmover_session_destroy(dses); + + return (error); +} +.Ed +.Sh SEE ALSO +.Xr queue 3 , +.Xr dmoverio 4 +.Sh HISTORY +The +.Nm dmover +facility first appeared in +.Nx 2.0 . +.Sh AUTHORS +The +.Nm dmover +facility was designed and implemented by +.An Jason R. Thorpe +.Aq thorpej@wasabisystems.com +and contributed by Wasabi Systems, Inc. +.Sh BUGS +The mechanism by which a back-end should advertise its performance to +the request scheduler is not well-defined. +Therefore, the load-balancing mechanism within the request scheduler is +also not well-defined. diff --git a/static/netbsd/man9/do_setresuid.9 b/static/netbsd/man9/do_setresuid.9 new file mode 100644 index 00000000..4f3be0e7 --- /dev/null +++ b/static/netbsd/man9/do_setresuid.9 @@ -0,0 +1,92 @@ +.\" $NetBSD: do_setresuid.9,v 1.7 2017/10/17 21:11:36 pgoyette Exp $ +.\" +.\"- +.\" Copyright (c) 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by David Laight. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 28, 2003 +.Dt DO_SETRESUID 9 +.Os +.Sh NAME +.Nm do_setresuid , +.Nm do_setresgid +.Nd set process uid and gid +.Sh SYNOPSIS +.In sys/ucred.h +.Ft int +.Fn do_setresuid "struct lwp *lwp" "uid_t ruid" "uid_t euid" "uid_t svuid" "u_int flags" +.Ft int +.Fn do_setresgid "struct lwp *lwp" "uid_t ruid" "uid_t euid" "uid_t svuid" "u_int flags" +.Sh DESCRIPTION +The +.Nm do_setresuid +and +.Nm do_setresgid +functions are used to implement the various system calls that allow a +process to change its real, effective, and saved uid and gid values. +.Pp +The +.Nm do_setresuid +function sets the specified process's real user ID to +.Ar ruid , +its effective user ID to +.Ar euid , +and its saved user ID to +.Ar svuid . +If any of the uid arguments are \-1 then that assignment is skipped. +.Pp +If +.Fn suser +is true, then any values may be assigned, otherwise the new uid +values must match one of the existing values and the caller must have +set the relevant bit in +.Ar flags . +.Pp +The +.Ar flags +argument specifies which of the existing uid values the new value must match. +It should be set to a logical OR of ID_{R,E,S}_EQ_{R,E,S}, where ID_E_EQ_R +means that it is valid to set the effective ID to the current value of the +real ID. +.Pp +The +.Nm do_setresgid +function sets the group IDs but otherwise behaves in the same manner as +.Nm . +The processes group list is neither examined nor effected. +.Sh CODE REFERENCES +These functions are implemented in: +.Pa sys/kern/kern_prot.c . +.Sh SEE ALSO +.Xr setregid 2 , +.Xr setreuid 2 , +.Xr setuid 2 +.Sh HISTORY +Implemented for +.Nx 2.0 +to replace ad-hoc code in each system call routine and in the +various compat modules. diff --git a/static/netbsd/man9/dofileread.9 b/static/netbsd/man9/dofileread.9 new file mode 100644 index 00000000..2701c940 --- /dev/null +++ b/static/netbsd/man9/dofileread.9 @@ -0,0 +1,120 @@ +.\" $NetBSD: dofileread.9,v 1.9 2010/12/02 12:54:13 wiz Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 20, 2005 +.Dt DOFILEREAD 9 +.Os +.Sh NAME +.Nm dofileread , +.Nm dofilereadv , +.Nm dofilewrite , +.Nm dofilewritev +.Nd high-level file operations +.Sh SYNOPSIS +.In sys/file.h +.Ft int +.Fn dofileread "struct lwp *l" "int fd" "struct file *fp" "void *buf" \ +"size_t nbyte" "off_t *offset" "int flags" "register_t *retval" +.Ft int +.Fn dofilewrite "struct lwp *l" "int fd" "struct file *fp" \ +"const void *buf" "size_t nbyte" "off_t *offset" "int flags" \ +"register_t *retval" +.Ft int +.Fn dofilereadv "struct lwp *l" "int fd" "struct file *fp" \ +"const struct iovec *iovp" "int iovcnt" "off_t *offset" "int flags" \ +"register_t *retval" +.Ft int +.Fn dofilewritev "struct lwp *l" "int fd" "struct file *fp" \ +"const struct iovec *iovp" "int iovcnt" "off_t *offset" "int flags" \ +"register_t *retval" +.Sh DESCRIPTION +The functions implement the underlying functionality of the +.Xr read 2 , +.Xr write 2 , +.Xr readv 2 , +and +.Xr writev 2 +system calls. +They are also used throughout the kernel as high-level access routines +for file I/O. +.Pp +The +.Fn dofileread +function attempts to read +.Fa nbytes +of data from the object referenced by file entry +.Fa fp +into the buffer pointed to by +.Fa buf . +The +.Fn dofilewrite +function attempts to write +.Fa nbytes +of data to the object referenced by file entry +.Fa fp +from the buffer pointed to by +.Fa buf . +.Pp +The +.Fn dofilereadv +and +.Fn dofilewritev +functions perform the same operations, but scatter the data with the +.Fa iovcnt +buffers specified by the members of the +.Fa iov +array. +.Pp +The offset of the file operations is explicitly specified by +.Fa *offset . +The new file offset after the file operation is returned in +.Fa *offset . +If the FOF_UPDATE_OFFSET flag is specified in the +.Fa flags +argument, the file offset in the file entry +.Fa fp +is updated to reflect the new file offset, otherwise it remains +unchanged after the operation. +.Pp +The file descriptor +.Fa fd +is largely unused except for use by the ktrace framework for reporting +to userlevel the process's file descriptor. +.Pp +Upon successful completion the number of bytes which were transferred +is returned in +.Fa *retval . +.Sh RETURN VALUES +Upon successful completion zero is returned, otherwise an appropriate +error is returned. +.Sh CODE REFERENCES +The framework for these file operations is implemented within the file +.Pa sys/kern/sys_generic.c . +.Sh SEE ALSO +.Xr file 9 diff --git a/static/netbsd/man9/dopowerhooks.9 b/static/netbsd/man9/dopowerhooks.9 new file mode 100644 index 00000000..95c9ddb6 --- /dev/null +++ b/static/netbsd/man9/dopowerhooks.9 @@ -0,0 +1,60 @@ +.\" $NetBSD: dopowerhooks.9,v 1.6 2010/04/05 19:31:29 joerg Exp $ +.\" +.\" Copyright (c) 1999 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 11, 2010 +.Dt DOPOWERHOOKS 9 +.Os +.Sh NAME +.Nm dopowerhooks +.Nd run all power hooks +.Sh SYNOPSIS +.Ft void +.Fn dopowerhooks "int why" +.Sh DESCRIPTION +.Em The +.Nm +.Em routine is deprecated. +.Em Use +.Xr pmf_system_suspend 9 +.Em instead. +.Pp +The +.Fn dopowerhooks +function invokes all power hooks established using the +.Xr powerhook_establish 9 +function. +When power is disappearing the power hooks are called in +reverse order, i.e., the power hook established last will be called first. +When power is restored they are called normal order. +.Pp +This function is called from the +.Xr apm 4 +driver when a power change is detected. +.Sh SEE ALSO +.Xr powerhook_establish 9 diff --git a/static/netbsd/man9/doshutdownhooks.9 b/static/netbsd/man9/doshutdownhooks.9 new file mode 100644 index 00000000..15afe22b --- /dev/null +++ b/static/netbsd/man9/doshutdownhooks.9 @@ -0,0 +1,68 @@ +.\" $NetBSD: doshutdownhooks.9,v 1.13 2024/09/07 19:13:29 rillig Exp $ +.\" +.\" Copyright (c) 1994 Christopher G. Demetriou +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the +.\" NetBSD Project. See https://www.NetBSD.org/ for +.\" information about NetBSD. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" <<Id: LICENSE,v 1.2 2000/06/14 15:57:33 cgd Exp>> +.\" +.Dd February 11, 2010 +.Dt DOSHUTDOWNHOOKS 9 +.Os +.Sh NAME +.Nm doshutdownhooks +.Nd run all shutdown hooks +.Sh SYNOPSIS +.Ft void +.Fn doshutdownhooks "void" +.Sh DESCRIPTION +.Em The +.Nm +.Em routine is deprecated. +.Em Use +.Xr pmf_system_shutdown 9 +.Em instead. +.Pp +The +.Fn doshutdownhooks +function invokes all shutdown hooks established using the +.Xr shutdownhook_establish 9 +function. +Shutdown hooks are called in reverse order, i.e., +the shutdown hook established last will be called first. +.Pp +This function is called from +.Fn cpu_reboot +with interrupts turned off. +It is called immediately before the system is halted or rebooted, +after file systems have been unmounted, after the clock has been updated, +and after a system dump has been done (if necessary). +.Sh SEE ALSO +.Xr cpu_reboot 9 , +.Xr shutdownhook_establish 9 diff --git a/static/netbsd/man9/driver.9 b/static/netbsd/man9/driver.9 new file mode 100644 index 00000000..b9d62859 --- /dev/null +++ b/static/netbsd/man9/driver.9 @@ -0,0 +1,372 @@ +.\" $NetBSD: driver.9,v 1.38 2026/03/28 13:02:36 uwe Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 30, 2017 +.Dt DRIVER 9 +.Os +.Sh NAME +.Nm driver +.Nd description of a device driver +.Sh SYNOPSIS +.In sys/param.h +.In sys/device.h +.In sys/errno.h +.Ft static int +.Fn foo_match "device_t parent" "cfdata_t match" "void *aux" +.Ft static void +.Fn foo_attach "device_t parent" "device_t self" "void *aux" +.Ft static int +.Fn foo_detach "device_t self" "int flags" +.Ft static int +.Fn foo_activate "device_t self" "enum devact act" +.Sh DESCRIPTION +This page briefly describes the basic +.Nx +autoconfiguration interface used by device drivers. +For a detailed overview of the autoconfiguration framework see +.Xr autoconf 9 . +.Pp +Each device driver must present to the system a standard +autoconfiguration interface. +This interface is provided by the +.Vt cfattach +structure. +The interface to the driver is constant and is defined +statically inside the driver. +For example, the interface to driver +.Ql foo +is defined with: +.Bd -literal -offset indent +CFATTACH_DECL_NEW(foo, /* driver name */ + sizeof(struct foo_softc), /* size of instance data */ + foo_match, /* match/probe function */ + foo_attach, /* attach function */ + foo_detach, /* detach function */ + foo_activate); /* activate function */ +.Ed +.Pp +For each device instance controlled by the driver, the +autoconfiguration framework allocates a block of memory to record +device-instance-specific driver variables. +The size of this memory block is specified by the second argument in the +.Dv CFATTACH_DECL +family of macros. +The memory block is referred to as the driver's +.Vt softc +structure. +The +.Vt softc +structure is only accessed within the driver, so its definition is +local to the driver. +Nevertheless, the +.Vt softc +structure should adopt the standard +.Nx +configuration and naming conventions. +For example, the +.Vt softc +structure for driver +.Ql foo +is defined with: +.Bd -literal -offset indent +struct foo_softc { + device_t sc_dev; /* generic device info */ + /* device-specific state */ +}; +.Ed +.Pp +If a driver has character device interfaces accessed from userland, the driver +must define the +.Vt cdevsw +structure. +The structure is constant and is defined inside the driver. +For example, the +.Vt cdevsw +structure for driver +.Ql foo +can be defined with: +.Bd -literal -offset indent +const struct cdevsw foo_cdevsw { + .d_open = fooopen, + .d_close = nullclose, + .d_read = fooread, + .d_write = nowrite, + .d_ioctl = fooioctl, + .d_stop = nostop, + .d_tty = notty, + .d_poll = foopoll, + .d_mmap = nommap, + .d_kqfilter = nokqfilter, + .d_discard = nodiscard, + .d_flag = D_OTHER | D_MPSAFE, +}; +.Ed +.Pp +The structure variable must be named +.Va foo_cdevsw +by appending the letters +.Ql _cdevsw +to the driver's base name. +This convention is mandated by the autoconfiguration framework. +.Pp +If the driver +.Ql foo +has also block device interfaces, the driver must define the +.Vt bdevsw +structure. +The structure is constant and is defined inside the driver. +For example, the +.Vt bdevsw +structure for driver +.Ql foo +is defined with: +.Bd -literal -offset indent +const struct bdevsw foo_bdevsw { + .d_open = fooopen, + .d_close = fooclose, + .d_strategy = foostrategy, + .d_ioctl = fooioctl, + .d_dump = nodump, + .d_psize = nosize, + .d_flag = D_DISK | D_MPSAFE, +}; +.Ed +.Pp +The structure variable must be named +.Va foo_bdevsw +by appending the letters +.Ql _bdevsw +to the driver's base name. +This convention is mandated by the autoconfiguration framework. +.Pp +During system bootstrap, the autoconfiguration framework searches the +system for devices. +For each device driver, its match function is called +.Po +via its +.Vt cfattach +structure +.Pc +to match the driver with a device instance. +The match function is called with three arguments. +This first argument +.Fa parent +is a pointer to the driver's parent device structure. +The second argument +.Fa match +is a pointer to a data structure describing the autoconfiguration +framework's understanding of the driver. +Both the +.Fa parent +and +.Fa match +arguments are ignored by most drivers. +The third argument +.Fa aux +contains a pointer to a structure describing a potential +device-instance. +It is passed to the driver from the parent. +The match function would type-cast the +.Fa aux +argument to its appropriate attachment structure and use its contents +to determine whether it supports the device. +Depending on the device hardware, the contents of the attachment +structure may contain +.Dq locators +to locate the device instance so that the driver can probe it for its +identity. +If the probe process identifies additional device properties, it may +modify the members of the attachment structure. +For these devices, the +.Nx +convention is to +call the match routine +.Fn foo_probe +instead of +.Fn foo_match +to make this distinction clear. +Either way, the match function returns a nonzero integer indicating the +confidence of supporting this device and a value of 0 if the driver +doesn't support the device. +Generally, only a single driver exists for a device, so the match +function returns 1 for a positive match. +.Pp +The autoconfiguration framework will call the attach function +.Po +via its +.Vt cfattach +structure +.Pc +of the driver which returns the highest value from its match function. +The attach function is called with three arguments. +The attach function performs the necessary process to initialise the +device for operation. +The first argument +.Fa parent +is a pointer to the driver's parent device structure. +The second argument +.Fa self +is a pointer to the driver's device structure. +The device's +.Vt softc +structure can be obtained from it using the +.Fn device_private +function +.Po see +.Xr disk 9 +.Pc . +The third argument +.Fa aux +is a pointer to the attachment structure. +The +.Fa parent +and +.Fa aux +arguments are the same as passed to the match function. +.Pp +The driver's attach function is called before system interrupts are +enabled. +If interrupts are required during initialisation, then the attach +function should make use of +.Fn config_interrupts +.Po +see +.Xr autoconf 9 +.Pc . +.Pp +Some devices can be removed from the system without requiring a system +reboot. +The autoconfiguration framework calls the driver's detach function +.Po +via its +.Vt cfattach +structure +.Pc +during device detachment. +If the device does not support detachment, then the driver does not +have to provide a detach function. +The detach function is used to relinquish resources allocated to the +driver which are no longer needed. +The first argument +.Fa self +is a pointer to the driver's device structure. +It is the same structure as passed to the attach function. +The second argument +.Fa flags +contains detachment flags. +Valid values are +.Dv DETACH_FORCE +.Pq force detachment; hardware gone +and +.Dv DETACH_QUIET +.Pq do not print a notice . +.Pp +The activate function is used by some buses to notify drivers from +interrupt context when detachment is imminent, with +.Fa act +set to +.Dv DVACT_DEACTIVATE . +Currently only +.Xr pcmcia 9 +and +.Xr cardbus 9 +use this. +If the action is not supported the activate function should return +.Er EOPNOTSUPP . +.Pp +Most drivers will want to make use of interrupt facilities. +Interrupt locators provided through the attachment structure should be +used to establish interrupts within the system. +Generally, an interrupt interface is provided by the parent. +The interface will require a handler and a driver-specific argument +to be specified. +This argument is usually a pointer to the device-instance-specific +softc structure. +When a hardware interrupt for the device occurs the handler is called +with the argument. +Interrupt handlers should return 0 for +.Dq interrupt not for me , +1 for +.Dq I took care of it , +or \-1 for +.Do +I guess it was mine, but I wasn't expecting it +.Dc . +.Pp +For a driver to be compiled into the kernel, +.Xr config 1 +must be aware of its existence. +This is done by including an entry in files.<bus> in the +directory containing the driver. +For example, the driver +.Ar foo +attaching to bus +.Ar bar +with dependency on kernel module +.Ar baz +has the entry: +.Bd -literal -offset indent +.Cd device Ar foo Ns Cd \&: Ar baz +.Cd attach Ar foo Cm at Ar bar +.Cd file Pa dev/ Ns Ar bar Ns Pa / Ns Ar foo Ns Pa \&.c Ar foo +.Ed +.Pp +An entry can now be added to the machine description file: +.Bd -ragged -offset indent +.Ar foo\^ Ns Cm \&* Cm at Ar bar\^ Ns Cm \&? +.Ed +.Pp +For device interfaces of a driver to be compiled into the kernel, +.Xr config 1 +must be aware of its existence. +This is done by including an entry in +.Pa majors. Ns Aq Ar arch . +For example, the driver +.Ar foo +with character device interfaces, a character major device number +.Ar cmaj , +block device interfaces, a block device major number +.Ar bmaj +and dependency on kernel module +.Ar baz +has the entry: +.Bd -ragged -offset indent +.Cd device-major Ar foo Cm char Ar cmaj Cm block Ar bmaj Ar baz +.Ed +.Pp +For a detailed description of the machine description file and the +.Dq device definition +language see +.Xr config 9 . +.Sh SEE ALSO +.Xr config 1 , +.Xr autoconf 9 , +.Xr config 9 , +.Xr devsw 9 , +.Xr pmf 9 diff --git a/static/netbsd/man9/edid.9 b/static/netbsd/man9/edid.9 new file mode 100644 index 00000000..3d0c43ff --- /dev/null +++ b/static/netbsd/man9/edid.9 @@ -0,0 +1,131 @@ +.\" $NetBSD: edid.9,v 1.9 2014/01/04 15:40:55 wiz Exp $ +.\" +.\" Copyright 2006 Itronix Inc. +.\" All rights reserved. +.\" +.\" Written by Garrett D'Amore for Itronix Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of Intronix Inc. may not be used to endorse +.\" or promote products derived from this software without specific prior +.\" written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY INTRONIX INC. ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ITRONIX INC. BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 24, 2013 +.Dt EDID 9 +.Os +.Sh NAME +.Nm edid +.Nd VESA Extended Display Identification Data +.Sh SYNOPSIS +.In dev/videomode/videomode.h +.In dev/videomode/edidvar.h +.In dev/videomode/edidreg.h +.Ft int +.Fo edid_is_valid +.Fa "uint8_t *data" +.Fc +.Ft int +.Fo edid_parse +.Fa "uint8_t *data" +.Fa "struct edid_info *info" +.Fc +.Ft void +.Fo edid_print +.Fa "struct edid_info *info" +.Fc +.Sh DESCRIPTION +These +functions provide support parsing the Extended Display Identification Data +which describes a display device such as a monitor or flat panel display. +.Pp +The +.Fn edid_is_valid +function simply tests if the EDID block in +.Fa data +contains valid data. +This test includes a verification of the checksum, +and that valid vendor and product idenfication data is present. +The data block contain at least 128 bytes. +.Pp +The +.Fn edid_parse +function parses the supplied +.Fa data +block (which again, must be at least 128 bytes), writing the relevant +data into the structure pointed to by +.Fa info . +.Pp +The +.Fn edid_print +function prints the data in the given +.Fa info +structure to the console device. +.\" XXX +.\" XXX It sure would be nice to have documentation about the details of the +.\" XXX edid_info structure itself. This takes more time, though, and +.\" XXX hopefully someone else will write it up. In the meantime, the code +.\" XXX references should be useful. +.\" XXX +.Sh RETURN VALUES +The +.Fn edid_is_valid +function returns 0 if the data block is valid, and +.Er EINVAL +otherwise. +The +.Fn edid_parse +function returns zero if the data was successfully parsed, and +non-zero otherwise. +.Sh EXAMPLES +The following code uses these functions +to retrieve and print information about a monitor: +.Pp +.Bd -literal -compact + struct edid_info info; + i2c_tag_t tag; + char buffer[128]; + + ... + /* initialize i2c tag... */ + ... + if ((ddc_read_edid(tag, buffer, 128) == 0) && + (edid_parse(buffer, &info) == 0)) + edid_print(&info); + ... +.Ed +.Sh CODE REFERENCES +The EDID subsystem is implemented within the file +.Pa sys/dev/videomode/edid.c . +.Pp +The EDID subsystem also makes use of VESA Generalized Timing Formula located +located in +.Pa sys/dev/videomode/vesagtf.c +and the generic videomode database located in +.Pa sys/dev/videomode/videomode.c . +.Sh SEE ALSO +.Xr ddc 9 , +.Xr iic 9 +.Sh HISTORY +These routines were added in +.Nx 4.0 . +.Sh AUTHORS +.An Garrett D'Amore Aq Mt gdamore@NetBSD.org diff --git a/static/netbsd/man9/errno.9 b/static/netbsd/man9/errno.9 new file mode 100644 index 00000000..430213f1 --- /dev/null +++ b/static/netbsd/man9/errno.9 @@ -0,0 +1,120 @@ +.\" $NetBSD: errno.9,v 1.6 2021/06/29 22:40:53 dholland Exp $ +.\" +.\" Copyright (c) 2004 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Andrew Brown. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd December 3, 2004 +.Dt ERRNO 9 +.Os +.Sh NAME +.Nm errno +.Nd kernel internal error numbers +.Sh SYNOPSIS +.In sys/errno.h +.Sh DESCRIPTION +This section provides an overview of the error numbers used internally +by the kernel and indicate neither success nor failure. +These error numbers are not returned to userland code. +.Sh DIAGNOSTICS +Kernel functions that indicate success or failure by means of either 0 +or an +.Xr errno 2 +value sometimes have a need to indicate that +.Dq special +handling is required at an upper layer or, in the case of +.Xr ioctl 2 +processing, that +.Dq nothing was wrong but the request was not handled . +To handle these cases, some negative +.Xr errno 2 +values are defined which are handled by the kernel before returning a +different +.Xr errno 2 +value to userland or simply zero. +.Pp +The following is a list of the defined names and their meanings as +given in +.In errno.h . +It is important to note that the value \-1 is +.Em not +used, since it is commonly used to indicate generic failure and leaves +it up to the caller to determine the action to take. +.Bl -hang -width Ds +.It Er \-2 EJUSTRETURN Em "Modify regs, just return" . +No more work is required and the function should just return. +.It Er \-3 ERESTART Em "Restart syscall" . +The system call should be restarted. +This typically means that the machine dependent system call trap code +will reposition the process's instruction pointer or program counter +to re-execute the current system call with no other work required. +.It Er \-4 EPASSTHROUGH Em "Operation not handled by this layer" . +The operation was not handled and should be passed through to another +layer. +This often occurs when processing +.Xr ioctl 2 +requests since lower layer processing may not handle something that +subsequent code at a higher level will. +.It Er \-5 EDUPFD Em "Duplicate file descriptor." +This error is returned from the device open routine indicating that +the +.Ar l_dupfd +field contains the file descriptor information to be returned to the caller, +instead of the file descriptor that has been opened already. +This error is used by cloning device multiplexors. +Cloning device multiplexors open a new file descriptor and associate that +file descriptor with the appropriate cloned device. +They set +.Ar l_dupfd +to that new file descriptor and return +.Er EDUPFD . +.Xr vn_open 9 +takes the file descriptor pointed to by +.Ar l_dupfd +and arranges for it to be copied to the file descriptor that the open +call will return. +.It Er \-6 EMOVEFD Em "Move file descriptor." +This error is similar to +.Er EDUPFD +except that the file descriptor in +.Ar l_dupfd +is closed after it has been copied. +.El +.Sh SEE ALSO +.Xr errno 2 , +.Xr ioctl 9 +.Sh HISTORY +An +.Nm +manual page appeared in +.At v6 . +This +.Nm +manual page appeared in +.Nx 3.0 . diff --git a/static/netbsd/man9/ethersubr.9 b/static/netbsd/man9/ethersubr.9 new file mode 100644 index 00000000..7442859a --- /dev/null +++ b/static/netbsd/man9/ethersubr.9 @@ -0,0 +1,174 @@ +.\" $NetBSD: ethersubr.9,v 1.28 2020/01/20 18:38:18 thorpej Exp $ +.\" +.\" Copyright (c) 1997 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Ignatios Souvatzis. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 19, 2020 +.Dt ETHERSUBR 9 +.Os +.Sh NAME +.Nm ethersubr , +.Nm ether_ifattach , +.Nm ether_addmulti , +.Nm ether_delmulti , +.Nm ETHER_FIRST_MULTI , +.Nm ETHER_NEXT_MULTI , +.Nm ETHER_IS_MULTICAST +.Nd Ethernet driver support functions and macros +.Sh SYNOPSIS +.In net/if_ether.h +.Ft void +.Fn ether_ifattach "struct ifnet *ifp" "uint8_t *lla" +.Ft int +.Fn ether_addmulti "const struct sockaddr *sa" "struct ethercom *ec" +.Ft int +.Fn ether_delmulti "const struct sockaddr *sa" "struct ethercom *ec" +.Ft void +.Fn ETHER_FIRST_MULTI "struct ether_multistep step" "struct ethercom *ec" "struct ether_multi *enm" +.Ft void +.Fn ETHER_NEXT_MULTI "struct ether_multistep step" "struct ether_multi *enm" +.Ft int +.Fn ETHER_IS_MULTICAST "uint8_t *addr" +.Sh DESCRIPTION +The +.Nm +functions provide the interface between the +.Nm +module and the network drivers which need Ethernet support. +Such drivers must request the +.Ar ether +attribute in their +.Ar files +declaration and call the appropriate functions as specified below. +.Pp +Note that you also need the +.Xr arp 9 +stuff to support IPv4 on your hardware. +.Bl -tag -width compact +.It Fn ether_ifattach "ifp" "lla" +Perform the device-independent, but Ethernet-specific initialization of +the interface pointed to by +.Fa ifp . +.Pp +Among other duties, this function creates a record for the link level +address in the interface's address list and records the link level address +pointed to by +.Fa lla +there. +Drivers can initialize the link level address by themselves by calling +the function with +.Fa lla +as +.Dv NULL +and calling +.Fn if_set_sadl . +.Pp +This function must be called from the driver's attach function. +.It Fn ether_addmulti "sa" "ec" +.It Fn ether_delmulti "sa" "ec" +Add +.Pq Fn ether_addmulti +or delete +.Pq Fn ether_delmulti +the address described by the +.Fa sa +pointer to the Ethernet multicast list belonging to +.Fa ec . +.Pp +These functions must be called from the driver's ioctl function to +handle +.Dv SIOCADDMULTI +and +.Dv SIOCDELMULTI +requests. +If these return +.Er ENETRESET , +the hardware multicast filter must be reinitialized. +.Pp +These functions accept +.Dv AF_UNSPEC +addresses, which are interpreted as Ethernet addresses, or +.Dv AF_INET +addresses. +In the latter case, +.Dv INADDR_ANY +is mapped to a range describing all the Ethernet address +space reserved for IPv4 multicast addresses. +.Pp +The +.Fn ether_addmulti +returns +.Er EAFNOSUPPORT +if an unsupported address family is specified, +.Er EINVAL +if a non-multicast address is specified, or +.Er ENETRESET +if +the multicast list really changed and the driver should synchronize +its hardware filter with it. +.Pp +The +.Fn ether_delmulti +returns, in addition to the above errors, +.Er ENXIO +if the specified address +can't be found in the list of multicast addresses. +.It Fn ETHER_NEXT_MULTI "step" "enm" +A macro to step through all of the +.Em ether_multi +records, one at a time. +The current position is remembered in +.Fa step , +which the caller must provide. +.It Fn ETHER_FIRST_MULTI "step" "ec" "enm" +A macro that must be called to initialize +.Fa step +and get the first record. +Both macros return a +.Dv NULL +.Fa enm +when there are no remaining records. +.It Fn ETHER_IS_MULTICAST "addr" +A macro that returns 1, if +.Fa addr +points to an Ethernet/FDDI multicast (or broadcast) address. +.El +.Sh CODE REFERENCES +Ethernet support functions are declared in +.In net/if_ether.h +and defined (if not implemented as macro) in +.Pa sys/net/if_ethersubr.c . +.Sh SEE ALSO +.Xr arp 9 +.Sh HISTORY +Rewritten to attach to the new ARP system in +.Nx 1.3 . +.Sh AUTHORS +UCB CSRG (original implementation) +.Pp +.An Ignatios Souvatzis +(support for new ARP system) diff --git a/static/netbsd/man9/evcnt.9 b/static/netbsd/man9/evcnt.9 new file mode 100644 index 00000000..a9c2d0e1 --- /dev/null +++ b/static/netbsd/man9/evcnt.9 @@ -0,0 +1,315 @@ +.\" $NetBSD: evcnt.9,v 1.23 2024/09/07 19:13:29 rillig Exp $ +.\" +.\" Copyright (c) 2000 Christopher G. Demetriou +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the +.\" NetBSD Project. See https://www.NetBSD.org/ for +.\" information about NetBSD. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" --(license Id: LICENSE.proto,v 1.1 2000/06/13 21:40:26 cgd Exp )-- +.\" +.Dd January 14, 2011 +.Dt EVCNT 9 +.Os +.Sh NAME +.Nm evcnt , +.Nm evcnt_attach_dynamic , +.Nm evcnt_attach_static , +.Nm evcnt_detach +.Nd generic event counter framework +.Sh SYNOPSIS +.In sys/evcnt.h +.Ft void +.Fn evcnt_attach_dynamic "struct evcnt *ev" \ +"int type" "const struct evcnt *parent" "const char *group" "const char *name" +.Ft void +.Fn evcnt_attach_static "struct evcnt *ev" +.Ft void +.Fn evcnt_detach "struct evcnt *ev" +.Sh DESCRIPTION +The +.Nx +generic event counter framework is designed to provide a flexible and +hierarchical event counting facility, which is useful for tracking +system events (including device interrupts). +.Pp +The fundamental component of this framework is the +.Em evcnt +structure. +Its user-accessible fields are: +.Bd -literal +struct evcnt { + uint64_t ev_count; /* how many have occurred */ + TAILQ_ENTRY(evcnt) ev_list; /* entry on list of all counters */ + unsigned char ev_type; /* counter type; see below */ + unsigned char ev_grouplen; /* 'group' len, excluding NUL */ + unsigned char ev_namelen; /* 'name' len, excluding NUL */ + const struct evcnt *ev_parent; /* parent, for hierarchical ctrs */ + const char *ev_group; /* name of group */ + const char *ev_name; /* name of specific event */ +}; +.Ed +.Pp +The system maintains a global linked list of all active event counters. +This list, called +.Nm allevents , +may grow or shrink over time as event counters are dynamically +added to and removed from the system. +.Pp +Each event counter is marked (in the +.Fa ev_type +field) with the type of event being counted. +The following types are currently defined: +.Bl -tag -offset indent -width EVCNT_TYPE_MISC +.It Ev EVCNT_TYPE_MISC +Miscellaneous; doesn't fit into one of the other types. +.It Ev EVCNT_TYPE_INTR +Interrupt counter, reported by +.Ic vmstat -i . +.It Ev EVCNT_TYPE_TRAP +Processor trap style events. +.El +.Pp +Each event counter also has a group name +.Pq Fa ev_group +and +an event name +.Pq Fa ev_name +which are used to identify the counter. +The group name may be shared by a set of counters. +For example, device interrupt counters would use the name of the +device whose interrupts are being counted as the group name. +The counter +name is meant to distinguish the counter from others in its group +(and need not be unique across groups). +Both names should be understandable by users, since they are printed +by commands like +.Xr vmstat 1 . +The constant +.Dv EVCNT_STRING_MAX +is defined to be the maximum group or event name length in +bytes (including the trailing +.Dv NUL ) . +In the current implementation it is 256. +.Pp +To support hierarchical tracking of events, each event counter can +name a +.Dq parent +event counter. +For instance, interrupt dispatch code could have an event counter per +interrupt line, and devices could each have counters for the number +of interrupts that they were responsible for causing. +In that case, the counter for a device on a given interrupt line +would have the line's counter as its parent. +The value +.Dv NULL +is used to indicate that a counter has no parent. +A counter's parent must be attached before the counter is attached, +and detached after the counter is detached. +.Pp +The +.Fn EVCNT_INITIALIZER +macro can be used to provide a static initializer for an event +counter structure. +It is invoked as +.Fn EVCNT_INITIALIZER "type" "parent" "group" "name" , +and its arguments will be placed into the corresponding fields of +the event counter structure it is initializing. +The +.Fa group +and +.Fa name +arguments must be constant strings. +.Sh FUNCTIONS +The following is a brief description of each function in the framework: +.Bl -tag -width indent +.It Fn evcnt_attach_dynamic "ev" "type" "parent" "group" "name" +Attach the event counter structure pointed to by +.Fa ev +to the system event list. +The event counter is cleared and its fields initialized using the +arguments to the function call. +The contents of the remaining elements in the structure (e.g., the +name lengths) are calculated, and the counter is added to the +system event list. +.Pp +The strings specified as the group and +counter names must persist (with the same value) +throughout the life of the event counter; they are referenced by, +not copied into, the counter. +.It Fn evcnt_attach_static "ev" +Attach the statically-initialized event counter structure +pointed to by +.Fa ev +to the system event list. +The event counter is assumed to be statically initialized using the +.Fn EVCNT_INITIALIZER +macro. +This function simply calculates structure elements' values as appropriate +(e.g., the string lengths), and adds the counter to the system event list. +.It Fn evcnt_detach "ev" +Detach the event counter structure pointed to by +.Fa ev +from the system event list. +.El +.Pp +Note that no method is provided to increment the value of an +event counter. +Code incrementing an event counter should do so by directly accessing its +.Fa ev_count +field in a manner that is known to be safe. +For instance, additions to a device's event counters in the interrupt +handler for that device will often be safe without additional protection +(because interrupt handler entries for a given device have to be +serialized). +However, for other uses of event counters, additional locking +or use of machine-dependent atomic operation may be appropriate. +(The overhead of using a mechanism that is guaranteed to +be safe to increment every counter, regardless of actual need +for such a mechanism where the counter is being incremented, +would be too great. +On some systems, it might involve a global lock and several function calls.) +.Sh EXAMPLES +This section includes a description on basic use of the framework +and example usage of its functions. +.Pp +Device drivers can use the +.Fn evcnt_attach_dynamic +and +.Fn evcnt_detach +functions to manage device-specific event counters. +Statically configured system modules can use +.Fn evcnt_attach_static +to configure global event counters. +Similarly, loadable modules can use +.Fn evcnt_attach_static +to configure their global event counters, +.Fn evcnt_attach_dynamic +to attach device-specific event +counters, and +.Fn evcnt_detach +to detach all counters when being unloaded. +.Pp +Device drivers that wish to use the generic event counter +framework should place event counter structures in their +.Dq softc +structures. +For example, to keep track of the number of interrupts for a given +device (broken down further into +.Dq device readable +and +.Dq device writable +interrupts) a device driver might use: +.Bd -literal +struct foo_softc { + [ . . . ] + struct evcnt sc_ev_intr; /* interrupt count */ + struct evcnt sc_ev_intr_rd; /* 'readable' interrupt count */ + struct evcnt sc_ev_intr_wr; /* 'writable' interrupt count */ + [ . . . ] +}; +.Ed +.Pp +In the device attach function, those counters would be registered with +the system using the +.Fn evcnt_attach_dynamic +function, using code like: +.Bd -literal +void +fooattach(device_t parent, device_t self, void *aux) +{ + struct foo_softc *sc = device_private(self); + + [ . . . ] + + /* Initialize and attach event counters. */ + evcnt_attach_dynamic(&sc->sc_ev, EVCNT_TYPE_INTR, + NULL, device_xname(self), "intr"); + evcnt_attach_dynamic(&sc->sc_ev_rd, EVCNT_TYPE_INTR, + &sc->sc_ev, device_xname(self), "intr rd"); + evcnt_attach_dynamic(&sc->sc_ev_wr, EVCNT_TYPE_INTR, + &sc->sc_ev, device_xname(self), "intr wr"); + + [ . . . ] +} +.Ed +.Pp +If the device can be detached from the system, its detach +function should invoke +.Fn evcnt_detach +on each attached counter (making sure to detach any +.Dq parent +counters only after detaching all children). +.Pp +Code like the following might be used to initialize a static +event counter (in this example, one used to track CPU alignment traps): +.Bd -literal + struct evcnt aligntrap_ev = EVCNT_INITIALIZER(EVCNT_TYPE_MISC, + NULL, "cpu", "aligntrap") +.Ed +.Pp +To attach this event counter, code like the following could be used: +.Bd -literal + evcnt_attach_static(&aligntrap_ev); +.Ed +.Sh CODE REFERENCES +The event counter framework itself is implemented within the file +.Pa sys/kern/subr_evcnt.c . +Data structures and function prototypes for the framework are located in +.Pa sys/sys/device.h . +.Pp +Event counters are used throughout the system. +.Pp +The +.Xr vmstat 1 +source file +.Pa usr.bin/vmstat/vmstat.c +shows an example of how to access event counters from user programs. +.Sh SEE ALSO +.Xr vmstat 1 +.Sh HISTORY +A set of interrupt counter interfaces with similar names to the interfaces +in the +.Nx +generic event counter framework appeared as part +of the new autoconfiguration system in +.Bx 4.4 . +Those interfaces were never widely adopted in +.Nx +because of limitations in their applicability. +(Their use was limited to non-hierarchical, dynamically +attached device interrupt counters.) +The +.Nx +generic event counter framework first appeared in +.Nx 1.5 . +.Sh AUTHORS +The +.Nx +generic event counter framework was designed and implemented by +.An Chris Demetriou +.Aq cgd@NetBSD.org . diff --git a/static/netbsd/man9/extattr.9 b/static/netbsd/man9/extattr.9 new file mode 100644 index 00000000..be7317c3 --- /dev/null +++ b/static/netbsd/man9/extattr.9 @@ -0,0 +1,86 @@ +.\" $NetBSD: extattr.9,v 1.4 2009/03/09 19:24:32 joerg Exp $ +.\" +.\" Copyright (c) 1999, 2000, 2001, 2003 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" FreeBSD: src/share/man/man9/extattr.9,v 1.14 2003/10/23 02:33:03 hmp Exp +.\" +.Dd January 2, 2005 +.Dt EXTATTR 9 +.Os +.Sh NAME +.Nm extattr +.Nd file system extended attributes +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/extattr.h +.Sh DESCRIPTION +Extended attributes allow additional meta-data to be associated +with vnodes representing files and directories. +The semantics of this additional data is that of a +.Dq name=value +pair, where a name may be defined or undefined, and if defined, +associated with zero or more bytes of arbitrary binary data. +Extended attribute names exist within a set of namespaces; each operation +on an extended attribute is required to provide the namespace to which the +operation refers. +If the same name is present in multiple namespaces, the extended attributes +associated with the names are stored and manipulated independently. +The following two namespaces are defined universally, although individual +file systems may implement additional namespaces, or not implement +these namespaces: +.Dv EXTATTR_NAMESPACE_USER , +.Dv EXTATTR_NAMESPACE_SYSTEM . +The semantics of these attributes are intended to be as follows: user +attribute data is protected according the normal discretionary +and mandatory protections associated with the data in the file or +directory; system attribute data is protected such that appropriate +privilege is required to directly access or manipulate these attributes. +.Pp +Reads of extended attribute data may return specific contiguous regions of +the meta-data, in the style of +.Xr VOP_READ 9 , +but writes will replace the entire current +.Dq value +associated with a given name. +As there are a plethora of file systems with differing extended attributes, +availability and functionality of these functions may be limited, and they +should be used with awareness of the underlying semantics of the supporting +file system. +Authorization schemes for extended attribute data may also vary by file +system, as well as maximum attribute size, and whether or not any or +specific new attributes may be defined. +.Pp +Extended attributes are named using a nul-terminated character string. +Depending on underlying file system semantics, this name may or may not be +case-sensitive. +Appropriate vnode extended attribute calls are: +.Xr VOP_GETEXTATTR 9 , +.Xr VOP_LISTEXTATTR 9 , +and +.Xr VOP_SETEXTATTR 9 . +.Sh SEE ALSO +.Xr vfsops 9 , +.Xr vnodeops 9 diff --git a/static/netbsd/man9/extent.9 b/static/netbsd/man9/extent.9 new file mode 100644 index 00000000..10dafb64 --- /dev/null +++ b/static/netbsd/man9/extent.9 @@ -0,0 +1,393 @@ +.\" $NetBSD: extent.9,v 1.37 2017/08/28 06:18:40 skrll Exp $ +.\" +.\" Copyright (c) 1996, 1998 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe and Greg Hudson. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 28, 2017 +.Dt EXTENT 9 +.Os +.Sh NAME +.Nm extent , +.Nm extent_create , +.Nm extent_destroy , +.Nm extent_alloc , +.Nm extent_alloc_subregion , +.Nm extent_alloc1 , +.Nm extent_alloc_subregion1 , +.Nm extent_alloc_region , +.Nm extent_free , +.Nm extent_print +.Nd general purpose extent manager +.Sh SYNOPSIS +.In sys/malloc.h +.In sys/extent.h +.Ft struct extent * +.Fn extent_create "char *name" "u_long start" "u_long end" "void *storage" "size_t storagesize" "int flags" +.Ft void +.Fn extent_destroy "struct extent *ex" +.Ft int +.Fn extent_alloc "struct extent *ex" "u_long size" "u_long alignment" "u_long boundary" "int flags" "u_long *result" +.Ft int +.Fn extent_alloc_subregion "struct extent *ex" "u_long substart" "u_long subend" "u_long size" "u_long alignment" "u_long boundary" "u_long flags" "u_long *result" +.Ft int +.Fn extent_alloc1 "struct extent *ex" "u_long size" "u_long alignment" "u_long skew" "u_long boundary" "int flags" "u_long *result" +.Ft int +.\" too many arguments for a single .Fn +.Fo extent_alloc_subregion1 +.Fa "struct extent *ex" +.Fa "u_long substart" +.Fa "u_long subend" +.Fa "u_long size" +.Fa "u_long alignment" +.Fa "u_long skew" +.Fa "u_long boundary" +.Fa "u_long flags" +.Fa "u_long *result" +.Fc +.Ft int +.Fn extent_alloc_region "struct extent *ex" "u_long start" "u_long size" "int flags" +.Ft int +.Fn extent_free "struct extent *ex" "u_long start" "u_long size" "int flags" +.Ft void +.Fn extent_print "struct extent *ex" +.Sh DESCRIPTION +The +.Nx +extent manager provides management of areas of memory or +other number spaces (such as I/O ports). +An opaque structure called an +.Nm extent map +keeps track of allocated regions within the number space. +.Pp +.Fn extent_create +creates an extent map managing the space from +.Fa start +to +.Fa end +inclusive. +The extent map will have the name +.Fa name , +used for identification in case of an error. +If the flag +.Dv EX_NOCOALESCE +is specified, only entire regions may be freed within the extent map, +but internal coalescing of regions is disabled so that +.Fn extent_free +will never have to allocate a region descriptor and therefore will +never fail. +The caller must specify one of the flags +.Dv EX_NOWAIT +or +.Dv EX_WAITOK , +specifying whether it is okay to wait for memory allocated for +extent map overhead. +.Pp +There are some applications which may want to use an extent map but +can't use +.Fn malloc +and +.Fn free . +These applications may provide pre-allocated storage for +all descriptor overhead with the arguments +.Fa storage +and +.Fa storagesize . +An extent of this type is called a +.Nm fixed extent . +If the application can safely use +.Fn malloc +and +.Fn free , +.Fa storage +should be +.Dv NULL . +A fixed extent has a fixed number of region descriptors, so care +should be taken to provide enough storage for them; alternatively, the +flag +.Dv EX_MALLOCOK +may be passed to allocation requests to indicate that a fixed extent +map may be extended using a call to +.Fn malloc . +.Pp +If the flag +.Dv EX_EARLY +is specified, no +.Xr mutex 9 +calls are made in the expectation that +mutual exclusion is not available or required. +.Pp +.Fn extent_destroy +destroys the extent map +.Fa ex , +freeing all allocated regions. +If the extent is not a fixed extent, the region and internal extent +descriptors themselves are freed. +This function always succeeds. +.Pp +.Fn extent_alloc +allocates a region in extent +.Fa ex +of size +.Fa size +that fits the provided parameters. +There are two distinct allocation policies, which are selected by the +.Fa flags +argument: +.Bl -tag -offset indent -width "XXXXXXXXX" +.It Dv EX_FAST +Allocate the first region that fits the provided parameters, regardless +of resulting extent fragmentation. +.It default +Allocate the smallest region that is capable of holding the request, +thus minimizing fragmentation of the extent. +.El +.Pp +The caller must specify if waiting for space in the extent is allowed +using the flag +.Dv EX_WAITSPACE . +If +.Dv EX_WAITSPACE +is not specified, the allocation will fail if the request can not be +satisfied without sleeping. +The caller must also specify, using the +.Dv EX_NOWAIT +or +.Dv EX_WAITOK +flags, if waiting for overhead allocation is allowed. +The request will be aligned to +.Fa alignment +boundaries. +Alignment values must be a power of 2. +If no alignment is necessary, the value 1 should be specified. +If +.Fa boundary +is nonzero, the allocated region will not cross any of the numbers +which are a multiple of +.Fa boundary . +If the caller specifies the +.Dv EX_BOUNDZERO +flag, the boundary lines begin at zero. +Otherwise, the boundary lines begin at the beginning of the extent. +The allocated region may begin on a boundary address, but the end of +the region will not touch nor cross it. +A boundary argument smaller than the size of the request is invalid. +Upon successful completion, +.Fa *result +will contain the start of the allocated region. +.Pp +.Fn extent_alloc_subregion +is similar to +.Fn extent_alloc , +but it allows the caller to specify that the allocated region must +fall within the subregion from +.Fa substart +to +.Fa subend +inclusive. +The other arguments and the return values of +.Fn extent_alloc_subregion +are otherwise the same as those of +.Fn extent_alloc . +.Pp +.Fn extent_alloc_region +allocates the specific region in the extent map +.Fa ex +beginning at +.Fa start +with the size +.Fa size . +The caller must specify whether it is okay to wait for the indicated +region to be free using the flag +.Dv EX_WAITSPACE . +If +.Dv EX_WAITSPACE +is not specified, the allocation will fail if the request can not be +satisfied without sleeping. +The caller must also specify, using the +.Dv EX_NOWAIT +or +.Dv EX_WAITOK +flags, if waiting for overhead allocation is allowed. +.Pp +The +.Fn extent_alloc1 +and +.Fn extent_alloc_subregion1 +functions are extensions that take one additional argument, +.Fa skew , +that modifies the requested alignment result in the following way: +the value +.Pq Fa result No - Fa skew +is aligned to +.Fa alignment +boundaries. +.Fa skew +must be a smaller number than +.Fa alignment . +Also, a boundary argument smaller than the sum of the requested skew +and the size of the request is invalid. +.Pp +.Fn extent_free +frees a region of +.Fa size +bytes in extent +.Fa ex +starting at +.Fa start . +If the extent has the +.Dv EX_NOCOALESCE +property, only entire regions may be freed. +If the extent has the +.Dv EX_NOCOALESCE +property and the caller attempts to free a partial region, behavior is +undefined. +The caller must specify one of the flags +.Dv EX_NOWAIT +or +.Dv EX_WAITOK +to specify whether waiting for memory is okay; these flags have +meaning in the event that allocation of a region descriptor is +required during the freeing process. +This situation occurs only when a partial region that begins and ends +in the middle of another region is freed. +Behavior is undefined if invalid arguments are provided. +.Pp +.Fn extent_print +Print out information about extent +.Fa ex . +This function always succeeds. +Behavior is undefined if invalid arguments are provided. +.Sh LOCKING +The extent manager performs all necessary locking (unless +.Dv EX_EARLY +is specified) on the extent map +itself, and any other data structures internal to the extent manager. +The locks used by the extent manager are simplelocks, and will never sleep +.Po +see +.Xr lock 9 +.Pc . +This should be taken into account when designing the locking protocol +for users of the extent manager. +.Sh RETURN VALUES +The behavior of all extent manager functions is undefined if given +invalid arguments. +.Fn extent_create +returns the extent map on success, or +.Dv NULL +if it fails to allocate storage for the extent map. +It always succeeds when creating a fixed extent or when given the flag +.Dv EX_WAITOK . +.Fn extent_alloc , +.Fn extent_alloc_region , +.Fn extent_alloc_subregion , +and +.Fn extent_free +return one of the following values: +.Bl -tag -offset indent -width "XXXXXXXX" +.It Dv 0 +Operation was successful. +.It Dv ENOMEM +If +.Dv EX_NOWAIT +is specified, the extent manager was not able to allocate a region +descriptor for the new region or to split a region when freeing a +partial region. +.It Dv EAGAIN +Requested region is not available and +.Dv EX_WAITSPACE +was not specified. +.It Dv EINTR +Process received a signal while waiting for the requested region to +become available in the extent. +Does not apply to +.Fn extent_free . +.El +.Sh EXAMPLES +Here is an example of a (useless) function that uses several of the +extent manager routines. +.Bd -literal +void +func() +{ + struct extent *foo_ex; + u_long region_start; + int error; + + /* + * Extent "foo" manages a 256k region starting at 0x0 and + * only allows complete regions to be freed so that + * extent_free() never needs to allocate memory. + */ + foo_ex = extent_create("foo", 0x0, 0x3ffff, M_DEVBUF, + NULL, 0, EX_WAITOK | EX_NOCOALESCE); + + /* + * Allocate an 8k region, aligned to a 4k boundary, which + * does not cross any of the 3 64k boundaries (at 64k, + * 128k, and 192k) within the extent. + */ + error = extent_alloc(foo_ex, 0x2000, 0x1000, 0x10000, + EX_NOWAIT, ®ion_start); + if (error) + panic("you lose"); + + /* + * Give up the extent. + */ + extent_destroy(foo_ex); +} +.Ed +.Sh CODE REFERENCES +The extent manager itself is implemented within the file +.Pa sys/kern/subr_extent.c . +Function prototypes for the framework are located in +.Pa sys/sys/extent.h . +.Pp +The i386 bus management code uses the extent manager for managing I/O +ports and I/O memory. +This code is in the file +.Pa sys/arch/i386/i386/machdep.c . +.Sh SEE ALSO +.Xr malloc 9 +.Sh HISTORY +The +.Nx +extent manager appeared in +.Nx 1.3 . +.Sh AUTHORS +The +.Nx +extent manager was architected and implemented by +.An Jason R. Thorpe +.Aq thorpej@NetBSD.org . +.An Matthias Drochner +.Aq drochner@zelux6.zel.kfa-juelich.de +contributed to the initial testing and optimization of the implementation. +.An Chris Demetriou +.Aq cgd@NetBSD.org +contributed many architectural suggestions. diff --git a/static/netbsd/man9/file.9 b/static/netbsd/man9/file.9 new file mode 100644 index 00000000..a4e08ada --- /dev/null +++ b/static/netbsd/man9/file.9 @@ -0,0 +1,256 @@ +.\" $NetBSD: file.9,v 1.19 2017/04/23 11:37:29 wiz Exp $ +.\" +.\" Copyright (c) 2002, 2005, 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 17, 2009 +.Dt FILE 9 +.Os +.Sh NAME +.Nm file , +.Nm closef , +.Nm ffree , +.Nm FILE_IS_USABLE , +.Nm FILE_USE , +.Nm FILE_UNUSE , +.Nm FILE_SET_MATURE +.Nd operations on file entries +.Sh SYNOPSIS +.In sys/file.h +.Ft int +.Fn closef "struct file *fp" "struct lwp *l" +.Ft void +.Fn ffree "struct file *fp" +.Ft int +.Fn FILE_IS_USABLE "struct file *fp" +.Ft void +.Fn FILE_USE "struct file *fp" +.Ft void +.Fn FILE_UNUSE "struct file *fp" "struct lwp *l" +.Ft void +.Fn FILE_SET_MATURE "struct file *fp" +.Sh DESCRIPTION +The file descriptor table of a process references a file entry for +each file used by the kernel. +See +.Xr filedesc 9 +for details of the file descriptor table. +Each file entry is given by: +.Bd -literal +struct file { + LIST_ENTRY(file) f_list; /* list of active files */ + int f_flag; + int f_iflags; /* internal flags */ + int f_type; /* descriptor type */ + u_int f_count; /* reference count */ + u_int f_msgcount; /* message queue references */ + int f_usecount; /* number active users */ + kauth_cred_t f_cred; /* creds associated with descriptor */ + struct fileops { + int (*fo_read)(struct file *fp, off_t *offset, + struct uio *uio, kauth_cred_t cred, int flags); + int (*fo_write)(struct file *fp, off_t *offset, + struct uio *uio, kauth_cred_t cred, int flags); + int (*fo_ioctl)(struct file *fp, u_long com, void *data, + struct lwp *l); + int (*fo_fcntl)(struct file *fp, u_int com, void *data, + struct lwp *l); + int (*fo_poll)(struct file *fp, int events, + struct lwp *l); + int (*fo_stat)(struct file *fp, struct stat *sp, + struct lwp *l); + int (*fo_close)(struct file *fp, struct lwp *l); + } *f_ops; + off_t f_offset; + void *f_data; /* descriptor data */ +}; +.Ed +.Pp +.Nx +treats file entries in an object-oriented fashion after they are created. +Each entry specifies the object type, +.Em f_type , +which can have the values +.Dv DTYPE_VNODE , +.Dv DTYPE_SOCKET , +.Dv DTYPE_PIPE +and +.Dv DTYPE_MISC . +The file entry also has a pointer to a data structure, +.Em f_data , +that contains information specific to the instance of the underlying object. +The data structure is opaque to the routines that manipulate the file entry. +Each entry also contains an array of function pointers, +.Em f_ops , +that translate the generic operations on a file descriptor into the +specific action associated with its type. +A reference to the data structure is passed as the first parameter to a +function that implements a file operation. +The operations that must be implemented for each descriptor type are +read, write, ioctl, fcntl, poll, stat, and close. +See +.Xr vnfileops 9 +for an overview of the vnode file operations. +All state associated with an instance of an object must be stored in +that instance's data structure; the underlying objects are not permitted +to manipulate the file entry themselves. +.Pp +For data files, the file entry points to a +.Xr vnode 9 +structure. +Pipes and sockets do not have data blocks allocated on the disk and +are handled by the special-device filesystem that calls appropriate +drivers to handle I/O for them. +For pipes, the file entry points to a system block that is used during +data transfer. +For sockets, the file entry points to a system block that is used in +doing interprocess communications. +.Pp +The descriptor table of a process (and thus access to the objects to +which the descriptors refer) is inherited from its parent, so several +different processes may reference the same file entry. +Thus, each file entry has a reference count, +.Em f_count . +Each time a new reference is created, the reference count is incremented. +When a descriptor is closed, the reference count is decremented. +When the reference count drops to zero, the file entry is freed. +.Pp +Some file descriptor semantics can be altered through the +.Ar flags +argument to the +.Xr open 2 +system call. +These flags are recorded in +.Em f_flags +member of the file entry. +For example, the flags record whether the descriptor is open for +reading, writing, or both reading and writing. +The following flags and their corresponding +.Xr open 2 +flags are: +.Pp +.Bl -tag -offset indent -width FNONBLOCK -compact +.It FAPPEND +.Dv O_APPEND +.It FASYNC +.Dv O_ASYNC +.It O_FSYNC +.Dv O_SYNC +.It FNDELAY +.Dv O_NONBLOCK +.It O_NDELAY +.Dv O_NONBLOCK +.It FNONBLOCK +.Dv O_NONBLOCK +.It FFSYNC +.Dv O_SYNC +.It FDSYNC +.Dv O_DSYNC +.It FRSYNC +.Dv O_RSYNC +.It FALTIO +.Dv O_ALT_IO +.El +.Pp +Some additional state-specific flags are recorded in the +.Em f_iflags +member. +Valid values include: +.Pp +.Bl -tag -offset indent -width FIF_WANTCLOSE -compact +.It Dv FIF_WANTCLOSE +If set, then the reference count on the file is zero, but there were +multiple users of the file. +This can happen if a file descriptor table is shared by multiple processes. +This flag notifies potential users that the file is closing and will +prevent them from adding additional uses to the file. +.It Dv FIF_LARVAL +The file entry is not fully constructed (mature) and should not be used. +.El +.Pp +The +.Xr read 2 +and +.Xr write 2 +system calls do not take an offset in the file as an argument. +Instead, each read or write updates the current file offset, +.Em f_offset +in the file according to the number of bytes transferred. +Since more than one process may open the same file and each needs its +own offset in the file, the offset cannot be stored in the per-object +data structure. +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn closef "fp" "l" +The internal form of +.Xr close 2 +which decrements the reference count on file entry +.Fa fp . +The +.Fn closef +function release all locks on the file owned by lwp +.Fa l , +decrements the reference count on the file entry, and invokes +.Fn ffree +to free the file entry. +.It Fn ffree "struct file *fp" +Free file entry +.Fa fp . +The file entry was created in +.Xr falloc 9 . +.It Fn FILE_IS_USABLE "fp" +Ensure that the file entry is usable by ensuring that neither the +.Dv FIF_WANTCLOSE +flag nor the +.Dv FIF_LARVAL +flag is set in +.Em f_iflags . +.It Fn FILE_USE "fp" +Increment the reference count on file entry +.Fa fp . +.It Fn FILE_UNUSE "fp" "l" +Decrement the reference count on file entry +.Fa fp . +If the +.Dv FIF_WANTCLOSE +flag is set in +.Em f_iflags , +the file entry is freed. +.It Fn FILE_SET_MATURE "fp" +Mark the file entry as being fully constructed (mature) by clearing the +.Dv FIF_LARVAL +flag in +.Em f_iflags . +.El +.Sh CODE REFERENCES +The framework for file entry handling is implemented within the file +.Pa sys/kern/kern_descrip.c . +.Sh SEE ALSO +.Xr dofileread 9 , +.Xr filedesc 9 , +.Xr vnfileops 9 , +.Xr vnode 9 diff --git a/static/netbsd/man9/fileassoc.9 b/static/netbsd/man9/fileassoc.9 new file mode 100644 index 00000000..b9a88d45 --- /dev/null +++ b/static/netbsd/man9/fileassoc.9 @@ -0,0 +1,346 @@ +.\" $NetBSD: fileassoc.9,v 1.30 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright (c) 2006 Elad Efrat <elad@NetBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 1, 2016 +.Dt FILEASSOC 9 +.Os +.Sh NAME +.Nm fileassoc +.Nd in-kernel, file system independent, file meta-data association +.Sh SYNOPSIS +.In sys/fileassoc.h +.Ft int +.Fn fileassoc_register "const char *name" \ +"fileassoc_cleanup_cb_t cleanup_cb" "fileassoc_t *result" +.Ft int +.Fn fileassoc_deregister "fileassoc_t id" +.Ft void * +.Fn fileassoc_lookup "struct vnode *vp" "fileassoc_t id" +.Ft int +.Fn fileassoc_table_delete "struct mount *mp" +.Ft int +.Fn fileassoc_table_clear "struct mount *mp" "fileassoc_t id" +.Ft int +.Fn fileassoc_table_run "struct mount *mp" "fileassoc_t id" \ +"fileassoc_cb_t cb" "void *cookie" +.Ft int +.Fn fileassoc_file_delete "struct vnode *vp" +.Ft int +.Fn fileassoc_add "struct vnode *vp" "fileassoc_t id" "void *data" +.Ft int +.Fn fileassoc_clear "struct vnode *vp" "fileassoc_t id" +.Sh DESCRIPTION +The +.Nm +KPI allows association of meta-data with files independent of file system +support for such elaborate meta-data. +.Pp +When plugging a new fileassoc to the system, a developer can specify private +data to be associated with every file, as well as (potentially different) +private data to be associated with every file system mount. +.Pp +For example, a developer might choose to associate a custom ACL with every +file, and a count of total files with ACLs with the mount. +.Sh KERNEL PROGRAMMING INTERFACE +Designed with simplicity in mind, the +.Nm +KPI usually accepts four different types of parameters to the most commonly +used routines: +.Bl -tag -width "123456" +.It Ft struct mount * Ar mp +Describing a mount on which to take action. +.It Ft struct vnode * Ar vp +Describing a file on which to take action. +.It Ft fileassoc_t Ar id +Describing an id, as returned from a successful call to +.Fn fileassoc_register . +.It Ft void * Ar data +Describing a custom private data block, attached to either a file or a mount. +.El +.Pp +Before using the +.Nm +KPI it is important to keep in mind that the interface provides memory +management only for +.Nm +internal memory. +Any additional memory stored in the tables (such as private data structures +used by custom fileassocs) should be allocated and freed by the developer. +.Pp +.Nm +provides the ability to specify a +.Dq cleanup +routine to +.Fn fileassoc_register +(see below) +to be called whenever an entry for a file or a mount is deleted. +.Ss REGISTRATION AND DEREGISTRATION ROUTINES +These routines allow a developer to allocate a +.Nm +slot to be used for private data. +.Bl -tag -width "123456" +.It Fn fileassoc_register "name" "cleanup_cb" "result" +Registers a new fileassoc as +.Ar name , +and returns a +.Ft fileassoc_t +via +.Fa result +to be used as identifier in subsequent calls to the +.Nm +subsystem. +.Pp +.Fn fileassoc_register +returns zero on success. +Otherwise, an error number will be returned. +.Pp +If +.Ar cleanup_cb +is not +.Dv NULL , +it will be called during delete/clear operations (see routines below) with +indication whether the passed data is file- or mount-specific. +.Pp +.Ar cleanup_cb +should be a function receiving a +.Ft void * +and returning +.Ft void . +See the +.Sx EXAMPLES +section for illustration. +.Pp +.It Fn fileassoc_deregister "id" +Deregisters a +.Nm fileassoc +whose id is +.Ar id . +.Pp +Note that calling +.Fn fileassoc_deregister +only frees the associated slot in the +.Nm +subsystem. +It is up to the developer to take care of garbage collection. +.El +.Ss LOOKUP ROUTINES +These routines allow lookup of +.Nm +mounts, files, and private data attached to them. +.Bl -tag -width "123456" +.It Fn fileassoc_lookup "vp" "id" +Returns the private data for the file/id combination +or +.Dv NULL +if not found. +.El +.Ss MOUNT-WIDE ROUTINES +.Bl -tag -width "123456" +.It Fn fileassoc_table_delete "mp" +Deletes a fileassoc table for +.Ar mp . +.Pp +.It Fn fileassoc_table_clear "mp" "id" +Clear all table entries for +.Ar fileassoc +from +.Ar mp . +.Pp +If specified, the fileassoc's +.Dq cleanup routine +will be called with a pointer to the private data structure. +.Pp +.It Fn fileassoc_table_run "mp" "id" "cb" "cookie" +For each entry for +.Ar id , +call +.Ar cb +with the entry being the first argument, and +.Ar cookie +being the second argument. +.Pp +.Ar cb +is a function returning +.Ft void +and receiving two +.Ft "void *" +parameters. +.El +.Ss FILE-SPECIFIC ROUTINES +.Bl -tag -width "123456" +.It Fn fileassoc_file_delete "vp" +Delete the fileassoc entries for +.Ar vp . +.Pp +If specified, the +.Dq cleanup routines +of all fileassoc types added will be called with a pointer to the corresponding +private data structure and indication of +.Dv FILEASSOC_CLEANUP_FILE . +.El +.Ss FILEASSOC-SPECIFIC ROUTINES +.Bl -tag -width "123456" +.It Fn fileassoc_add "vp" "id" "data" +Add private data in +.Ar data +for +.Ar vp , +for the fileassoc specified by +.Ar id . +.Pp +If a table for the mount-point +.Ar vp +is on doesn't exist, one will be created automatically. +.Nm +manages internally the optimal table sizes as tables are modified. +.It Fn fileassoc_clear "vp" "id" +Clear the private data for +.Ar vp , +for the fileassoc specified by +.Ar id . +.Pp +If specified, the fileassoc's +.Dq cleanup routine +will be called with a pointer to the private data structure and indication of +.Dv FILEASSOC_CLEANUP_FILE . +.El +.Sh EXAMPLES +The following code examples should give you a clue on using +.Nm +for your purposes. +.Pp +First, we'll begin with registering a new id. +We need to do that to save a slot for private data storage with each mount +and/or file: +.Bd -literal -offset indent +fileassoc_t myhook_id; +int error; + +error = fileassoc_register("my_hook", myhook_cleanup, &myhook_id); +if (error != 0) + ...handle error... +.Ed +.Pp +In the above example we pass a +.Fn myhook_cleanup +routine. +It could look something like this: +.Bd -literal -offset indent +void +myhook_cleanup(void *data) +{ + + printf("Myhook: Removing entry for file.\en"); + ...handle file entry removal... + free(data, M_TEMP); +} +.Ed +.Pp +Another useful thing would be to add our private data to a file. +For example, let's assume we keep a custom ACL with each file: +.Bd -literal -offset indent +int +myhook_acl_add(struct vnode *vp, struct myhook_acl *acl) +{ + int error; + + error = fileassoc_add(vp, myhook_id, acl); + if (error) { + printf("Myhook: Could not add ACL.\en"); + ...handle error... + } + + printf("Myhook: Added ACL.\en"); + + return (0); +} +.Ed +.Pp +Adding an entry will override any entry that previously exists. +.Pp +Whatever your plug is, eventually you'll want to access the private data you +store with each file. +To do that you can use the following: +.Bd -literal -offset indent +int +myhook_acl_access(struct vnode *vp, int access_flags) +{ + struct myhook_acl *acl; + + acl = fileassoc_lookup(vp, myhook_id); + if (acl == NULL) + return (0); + + error = myhook_acl_eval(acl, access_flags); + if (error) { + printf("Myhook: Denying access based on ACL decision.\en"); + return (error); + } + + return (0); +} +.Ed +.Pp +And, in some cases, it may be desired to remove private data associated with +an file: +.Bd -literal -offset indent +int error; + +error = fileassoc_clear(vp, myhook_id); +if (error) { + printf("Myhook: Error occurred during fileassoc removal.\en"); + ...handle error... +} +.Ed +.Pp +As mentioned previously, the call to +.Fn fileassoc_clear +will result in a call to the +.Dq cleanup routine +specified in the initial call to +.Fn fileassoc_register . +.Pp +The above should be enough to get you started. +.Pp +For example usage of +.Nm , +see the Veriexec code. +.Sh CODE REFERENCES +The +.Nm +is implemented within +.Pa src/sys/kern/kern_fileassoc.c . +.Sh SEE ALSO +.Xr veriexec 9 +.Sh HISTORY +The +.Nm +KPI first appeared in +.Nx 4.0 . +.Sh AUTHORS +.An Elad Efrat Aq Mt elad@NetBSD.org +.An Brett Lymn Aq Mt blymn@NetBSD.org diff --git a/static/netbsd/man9/filedesc.9 b/static/netbsd/man9/filedesc.9 new file mode 100644 index 00000000..26a02e02 --- /dev/null +++ b/static/netbsd/man9/filedesc.9 @@ -0,0 +1,250 @@ +.\" $NetBSD: filedesc.9,v 1.18 2019/04/08 13:30:46 wiz Exp $ +.\" +.\" Copyright (c) 2002, 2005, 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 8, 2019 +.Dt FILEDESC 9 +.Os +.Sh NAME +.Nm filedesc , +.Nm fd_alloc , +.Nm fd_checkstd , +.Nm fd_clone , +.Nm fd_closeexec , +.Nm fd_copy , +.Nm fd_dup , +.Nm fd_dup2 , +.Nm fd_dupopen , +.Nm fd_free , +.Nm fd_init , +.Nm fd_getfile , +.Nm fd_share , +.Nm fd_tryexpand +.Nd file descriptor tables and operations +.Sh SYNOPSIS +.In sys/file.h +.In sys/filedesc.h +.Ft int +.Fn fd_alloc "proc_t *p" "int want" "int *result" +.Ft int +.Fn fd_checkstd "void" +.Ft int +.Fn fd_clone "file_t *fp" "int fd" "int flag" "const struct fileops *fops" "void *data" +.Ft filedesc_t * +.Fn fd_copy "void" +.Ft void +.Fn fd_closeexec "void" +.Ft int +.Fn fd_dup "file_t *fp" "int minfd" "int *newp" "bool exclose" +.Ft int +.Fn fd_dup2 "file_t *fp" "unsigned newfd" "int flags" +.Ft int +.Fn fd_dupopen "int old" "int *newp" "int error" +.Ft void +.Fn fd_free "void" +.Ft filedesc_t * +.Fn fd_init "filedesc_t *fdp" +.Ft file_t * +.Fn fd_getfile "unsigned fd" +.Ft void +.Fn fd_share "proc_t *p" +.Ft void +.Fn fd_tryexpand "proc_t *p" +.Sh DESCRIPTION +For user processes, all I/O is done through file descriptors. +These file descriptors represent underlying objects supported by the kernel +and are created by system calls specific to the type of object. +In +.Nx , +six types of objects can be represented by file descriptors: data +files, pipes, sockets, event queues, crypto, and miscellaneous. +.Pp +The kernel maintains a descriptor table for each process which is used +to translate the external representation of a file descriptor into an +internal representation. +The file descriptor is merely an index into this table. +The table maintains the following information: +.Pp +.Bl -bullet -compact +.It +the number of descriptors allocated in the file descriptor table; +.It +approximate next free descriptor; +.It +a reference count on the file descriptor table; and +.It +an array of open file entries. +.El +.Pp +On creation of the file descriptor table, a fixed number of file +entries are created. +It is the responsibility of the file descriptor operations to expand the +available number of entries if more are required. +Each file entry in the descriptor table contains the information needed +to access the underlying object and to maintain common information. +See +.Xr file 9 +for details of operations on the file entries. +.Pp +New file descriptors are generally allocated by +.Fn fd_alloc +and freed by +.Fn fd_free . +File entries are extracted from the file descriptor table by +.Fn fd_getfile . +Most of the remaining functions in the interface are purpose-specific +and perform lower-level file descriptor operations. +.Sh FUNCTIONS +The following functions are high-level interface routines to access +the file descriptor table for a process and its file entries. +.Bl -tag -width compact +.It Fn fd_alloc "p" "want" "*result" +Create a new open file entry in the file descriptor table and +allocate a file descriptor for the process +.Fa p . +The credential on the file entry are inherited from process +.Fa p . +Calling the +.Fn fd_alloc +function expands the file descriptor table when necessary. +.Pp +The index of the file entry is returned in +.Fa *result . +The +.Fn fd_alloc +function returns zero on success, or an appropriate error value +otherwise. +.It Fn fd_getfile "fd" +Get the file entry for file descriptor . +.Fa fd +The file entry is returned if it is valid and usable, otherwise +.Dv NULL +is returned. +.It Fn fd_dup "fp" "minfd" "*newp" "exclose" +Duplicate file descriptor +.Fa fp +for the current process. +The fd picked will be at least +.Fa minfd . +The resulting descriptor is given in +.Fa newp . +.It Fn fd_dup2 "fp" "newfd" "flags" +Duplicate file descriptor +.Fa fp +in fd number +.Fa newfd . +If newfd is already in use by an open file, close it (See +.Xr dup2 2 ) . +.It Fn fd_dupopen "old" "*newp" "error" +Duplicate file descriptor specified in +.Fa old +for the current lwp. +.El +.Pp +The following functions operate on the file descriptor table for a +process. +.Bl -tag -width compact +.It Fn fd_alloc "p" "want" "*result" +Allocate a file descriptor +.Fa want +for process +.Fa p . +The resultant file descriptor is returned in +.Fa *result . +The +.Fn fd_alloc +function returns zero on success, otherwise an appropriate error is +returned. +.It Fn fd_clone "fp" "fd" "flag" "fops" "data" +This function is meant to be used by devices which allocate a file +entry upon open. +.Fn fd_clone +fills +.Fa fp +with the given parameters. +It always returns the in-kernel errno +.Er EMOVEFD . +This special return value is interpreted by the caller of the device +open routine. +.It Fn fd_closeexec "void" +Close any files for the current process +that are marked +.Dq close on exec . +This operation is performed by invoking +.Fn fd_close +on the appropriate file descriptor. +.It Fn fd_copy "void" +Copy the file descriptor table from the current process +and return a pointer to the copy. +The returned file descriptor is guaranteed to have a reference count of one. +All file descriptor state is maintained. +The reference counts on each file entry referenced by the file +descriptor table is incremented accordingly. +.It Fn fd_tryexpand "p" +Expand the file descriptor table for process +.Fa p +by allocating memory for additional file descriptors. +.It Fn fd_free "void" +Decrement the reference count on the file descriptor table for the current lwp +and release the file descriptor table if the reference count drops to +zero. +.It Fn fd_share "p" +Make process +.Fa p +share the current process's filedesc structure. +.It Fn fd_checkstd "l" +Check the standard file descriptors 0, 1, and 2 and ensure they are +referencing valid file descriptors. +If they are not, create references to +.Pa /dev/null . +This is done to setuid/setgid executables, as file descriptors 0, 1, 2 +are implicitly used by the Standard C Library. +.It Fn fd_init "fdp" +Create a file descriptor table using the same current and root +directories of the current process. +The returned file descriptor table is guaranteed to have a reference +count of one. +.El +.Sh RETURN VALUES +Successful operations return zero. +A failed operation will return a non-zero value. +Possible values include: +.Bl -tag -width Er +.It Bq Er EBADF +Bad file descriptor specified. +.It Bq Er EMFILE +Cannot exceed file descriptor limit. +.It Bq Er ENOSPC +No space left in file descriptor table. +.El +.Sh CODE REFERENCES +The framework for file descriptor handling is implemented within the +file +.Pa sys/kern/kern_descrip.c . +.Sh SEE ALSO +.Xr file 9 diff --git a/static/netbsd/man9/firmload.9 b/static/netbsd/man9/firmload.9 new file mode 100644 index 00000000..6c4832d2 --- /dev/null +++ b/static/netbsd/man9/firmload.9 @@ -0,0 +1,135 @@ +.\" $NetBSD: firmload.9,v 1.10 2018/03/16 02:35:56 sevan Exp $ +.\" +.\" Copyright (c) 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 16, 2018 +.Dt FIRMLOAD 9 +.Os +.Sh NAME +.Nm firmload +.Nd Firmware loader API for device drivers +.Sh SYNOPSIS +.In dev/firmload.h +.\" +.Ft int +.Fn "firmware_open" "const char *drvname" "const char *imgname" \ +"firmware_handle_t *fhp" +.\" +.Ft int +.Fn "firmware_close" "firmware_handle_t fh" +.\" +.Ft off_t +.Fn "firmware_get_size" "firmware_handle_t fh" +.\" +.Ft int +.Fn "firmware_read" "firmware_handle_t fh" "off_t offset" "void *buf" \ +"size_t size" +.\" +.Ft void * +.Fn "firmware_malloc" "size_t size" +.\" +.Ft void +.Fn "firmware_free" "void *buf" "size_t size" +.Sh DESCRIPTION +.Nm +provides a simple and convenient API for device drivers to load firmware +images from files residing in the file system that are necessary for the +devices that they control. +Firmware images reside in sub-directories, one for each driver, of a series +of colon-separated path prefixes specified by the sysctl variable +.Dv hw.firmware.path . +.Sh FUNCTIONS +The following functions are provided by the +.Nm +API: +.Bl -tag -width indent +.It Fn "firmware_open" "drvname" "imgname" "fhp" +.Pp +Open the firmware image +.Fa imgname +for the driver +.Fa drvname . +The path to the firmware image file is constructed by appending the string +.Dq "/drvname/imgname" +to each configured path prefix until opening the firmware image file succeeds. +Upon success, +.Fn firmware_open +returns 0 and stores a firmware image handle in the location pointed to by +.Fa fhp . +Otherwise, an error code is returned to indicate the reason for failure. +.It Fn "firmware_close" "fh" +.Pp +Close the firmware image file associated with the firmware handle +.Fa fh . +Returns 0 upon success or an error code to indicate the reason for failure. +.It Fn "firmware_get_size" "fh" +.Pp +Returns the size of the image file associated with the firmware handle +.Fa fh . +.It Fn "firmware_read" "fh" "offset" "buf" "size" +.Pp +Reads from the image file associated with the firmware handle +.Fa fh +beginning at offset +.Fa offset +for length +.Fa size . +The firmware image data is placed into the buffer specified by +.Fa buf . +Returns 0 upon success or an error code to indicate the reason for failure. +.It Fn "firmware_malloc" "size" +.Pp +Allocates a region of wired kernel memory of size +.Fa size . +Note: +.Fn firmware_malloc +may block. +.It Fn "firmware_free" "buf" "size" +.Pp +Frees a region of memory previously allocated by +.Fn firmware_malloc . +.El +.Sh FILES +Default search path for firmware +.Bl -tag -width /libdata/firmware -compact +.It Pa /libdata/firmware +.It Pa /usr/libdata/firmware +.It Pa /usr/pkg/libdata/firmware +.It Pa /usr/pkg/libdata +.El +.Sh SEE ALSO +.Xr autoconf 9 , +.Xr malloc 9 , +.Xr vnsubr 9 +.Sh HISTORY +The +.Nm +framework first appeared in +.Nx 4.0 . +.Sh AUTHORS +.An Jason Thorpe Aq Mt thorpej@NetBSD.org diff --git a/static/netbsd/man9/flash.9 b/static/netbsd/man9/flash.9 new file mode 100644 index 00000000..a6e060ca --- /dev/null +++ b/static/netbsd/man9/flash.9 @@ -0,0 +1,86 @@ +.\" $NetBSD: flash.9,v 1.5 2014/03/18 18:20:40 riastradh Exp $ +.\" +.\" Copyright (c) 2010 Department of Software Engineering, +.\" University of Szeged, Hungary +.\" Copyright (c) 2010 Adam Hoka <ahoka@NetBSD.org> +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by the Department of Software Engineering, University of Szeged, Hungary +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 31, 2011 +.Dt FLASH 9 +.Os +.Sh NAME +.Nm flash +.Nd subsystem for flash-like memory devices +.Sh SYNOPSIS +.In dev/flash/flash.h +.Ft device_t +.Fn flash_attach_mi "const struct flash_interface *fl" "device_t dev" +.Sh DESCRIPTION +Flash-like devices can register themselves to the +.Nm +layer with the +.Fa flash_hw_if +structure. +This structure has function pointers and other fields. +.Pp +The attachment can be done by calling +.Fn flash_attach_mi +with this structure and the device's +.Vt device_t +as an argument. +Return value is the flash layer device. +The +.Fa flash_interface +structure is shown below. +.Bd -literal +struct flash_interface { + int (*erase) (device_t, struct flash_erase_instruction *); + int (*read) (device_t, off_t, size_t, size_t *, uint8_t *); + int (*write) (device_t, off_t, size_t, size_t *, const uint8_t *); + int (*block_markbad)(device_t, uint64_t); + int (*block_isbad)(device_t, uint64_t); + int (*sync) (device_t); + + int (*submit)(device_t, struct buf *); + + /* storage for partition info */ + struct flash_partition partition; + + /* total size of mtd */ + flash_addr_t size; + uint32_t page_size; + uint32_t erasesize; + uint32_t writesize; + uint32_t minor; + uint8_t type; +}; +.Ed +.Sh SEE ALSO +.Xr flash 4 , +.Xr nand 9 +.Sh AUTHORS +.An Adam Hoka Aq Mt ahoka@NetBSD.org diff --git a/static/netbsd/man9/fork1.9 b/static/netbsd/man9/fork1.9 new file mode 100644 index 00000000..7844f622 --- /dev/null +++ b/static/netbsd/man9/fork1.9 @@ -0,0 +1,151 @@ +.\" $NetBSD: fork1.9,v 1.16 2018/04/16 15:02:37 wiz Exp $ +.\" +.\" Copyright (c) 1998 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility, +.\" NASA Ames Research Center. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 16, 2018 +.Dt FORK1 9 +.Os +.Sh NAME +.Nm fork1 +.Nd create a new process +.Sh SYNOPSIS +.In sys/types.h +.In sys/proc.h +.Ft int +.Fn "fork1" "struct lwp *l1" "int flags" "int exitsig" "void *stack" "size_t stacksize" "void (*func)(void *)" "void *arg" "register_t *retval" +.Sh DESCRIPTION +.Fn fork1 +creates a new process out of the process behind +.Ar l1 , +which is assumed to be the current lwp. +This function is used primarily to implement the +.Xr fork 2 +and +.Xr vfork 2 +system calls, but is versatile enough to be used as a backend for +e.g. the +.Xr __clone 2 +call. +.Pp +The +.Ar flags +argument controls the semantics of the fork operation, and is made up of +the bitwise-OR of the following values: +.Bl -tag -width FORK_SHAREFILES +.It FORK_PPWAIT +The parent process will sleep until the child process successfully calls +.Xr execve 2 +or exits (either by a call to +.Xr _exit 2 +or abnormally). +.It FORK_SHAREVM +The child process will share the parent's virtual address space. +If this flag is not specified, the child will get a copy-on-write +snapshot of the parent's address space. +.It FORK_SHARECWD +The child process will share the parent's current directory, root directory, +and file creation mask. +.It FORK_SHAREFILES +The child process will share the parent's file descriptors. +.It FORK_SHARESIGS +The child process will share the parent's signal actions. +.It FORK_NOWAIT +The child process will at creation time be inherited by the init process. +.It FORK_CLEANFILES +The child process will not copy or share the parent's descriptors, but +rather will start out with a clean set. +.El +.Pp +A +.Ar flags +value of 0 indicates a standard fork operation. +.Pp +The +.Ar exitsig +argument controls the signal sent to the parent on child death. +If normal operation desired, SIGCHLD should be supplied. +.Pp +It is possible to specify the child userspace stack location and size +by using the +.Ar stack +and +.Ar stacksize +arguments, respectively. +Values +.Dv NULL +and 0, respectively, will give the child the default values +for the machine architecture in question. +.Pp +The arguments +.Ar func +and +.Ar arg +can be used to specify a kernel function to be called when the child process +returns instead of +.Fn child_return . +These are used for example in starting the init process and creating kernel +threads. +.Pp +The +.Ar retval +argument is provided for the use of system call stubs. +If +.Ar retval +is not NULL, it will hold the following values after successful completion +of the fork operation: +.Bl -tag -width retval[0] +.It Ar retval[0] +This will contain the pid of the child process. +.It Ar retval[1] +In the parent process, this will contain the value 0. +In the child process, this will contain 1. +.El +.Pp +User level system call stubs typically subtract 1 from +.Ar retval[1] +and bitwise-AND it with +.Ar retval[0] , +thus returning the pid to the parent process and 0 to the child. +.Sh RETURN VALUES +Upon successful completion of the fork operation, +.Fn fork1 +returns 0. +Otherwise, the following error values are returned: +.Bl -tag -width [EAGAIN] +.It Bq Er EAGAIN +The limit on the total number of system processes would be exceeded; +or the limit +.Dv RLIMIT_NPROC +on the total number of processes under execution by this +user id would be exceeded. +.El +.Sh SEE ALSO +.Xr execve 2 , +.Xr fork 2 , +.Xr vfork 2 diff --git a/static/netbsd/man9/fsetown.9 b/static/netbsd/man9/fsetown.9 new file mode 100644 index 00000000..4b895c00 --- /dev/null +++ b/static/netbsd/man9/fsetown.9 @@ -0,0 +1,152 @@ +.\" $NetBSD: fsetown.9,v 1.9 2009/03/12 12:44:08 joerg Exp $ +.\" +.\" Copyright (c) 2003, 2005 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jaromir Dolecek. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 20, 2005 +.Dt FSETOWN 9 +.Os +.Sh NAME +.Nm fsetown , +.Nm fgetown , +.Nm fownsignal +.Nd file descriptor owner handling functions +.Sh SYNOPSIS +.In sys/file.h +.Ft int +.Fn fsetown "struct lwp *l" "pid_t *pgid" "int cmd" "const void *data" +.Ft int +.Fn fgetown "struct lwp *l" "pid_t pgid" "int cmd" "void *data" +.Ft void +.Fn fownsignal "pid_t pgid" "int signo" "int code" "int band" "void *fdescdata" +.Sh DESCRIPTION +These functions handle file descriptor owner related ioctls and +related signal delivery. +Device drivers and other parts of the kernel call these functions from +ioctl entry functions or I/O notification functions. +.Pp +.Fn fsetown +sets the owner of file. +.Fa cmd +is an ioctl command, one of +.Dv SIOCSPGRP , +.Dv FIOSETOWN , +and +.Dv TIOCSPGRP . +.Fa data +is interpreted as a pointer to a signed integer, the integer being +the ID of the owner. +The +.Fa cmd +determines how exactly +.Fa data +should be interpreted. +If +.Fa cmd +is +.Dv TIOCSPGRP , +the ID needs to be positive and is interpreted as process group ID. +For +.Dv SIOCSPGRP +and +.Dv FIOSETOWN , +the passed ID is the process ID if positive, or the process group ID +if negative. +.Pp +.Fn fgetown +returns the current owner of the file. +.Fa cmd +is an ioctl command, one of +.Dv SIOCGPGRP , +.Dv FIOGETOWN , +and +.Dv TIOCGPGRP . +.Fa data +is interpreted as a pointer to a signed integer, +and the value is set according to the passed +.Fa cmd . +For +.Dv TIOCGPGRP , +the returned +.Fa data +value is positive process group ID if the owner is the process group, +or negative process ID if the owner is a process. +For other ioctls, +the returned value is the positive process ID if the owner is a process, +or the negative process group ID if the owner is a process group. +.Pp +.Fn fownsignal +schedules the +.Fa signo +signal to be sent to the current file descriptor owner. +The signals typically used with this function are +.Dv SIGIO +and +.Dv SIGURG . +The +.Fa code +and +.Fa band +arguments are sent along with the signal as additional signal specific +information if +.Dv SA_SIGINFO +is activated. +If the information is not available from the context of the +.Fn fownsignal +call, these should be passed as zero. +.Fa fdescdata +is used to lookup the file descriptor for +.Dv SA_SIGINFO +signals. +If it is specified, the file descriptor number is sent along with +the signal as additional signal specific information. +If file descriptor data pointer is not available in the context of the +.Fn fownsignal +call, +.Dv NULL +should be used instead. +.Pp +Note that a +.Xr fcntl 2 +.Dv F_SETOWN request +is translated by the kernel to a +.Dv FIOSETOWN +ioctl, and +.Dv F_GETOWN +is translated to +.Dv FIOGETOWN . +This is done transparently by generic code, before the device- or +subsystem-specific ioctl entry function is called. +.Sh SEE ALSO +.Xr fcntl 2 , +.Xr siginfo 2 , +.Xr signal 7 , +.Xr ioctl 9 , +.Xr signal 9 +.Sh HISTORY +These kernel functions appeared in +.Nx 2.0 . diff --git a/static/netbsd/man9/fstrans.9 b/static/netbsd/man9/fstrans.9 new file mode 100644 index 00000000..bf8e94a6 --- /dev/null +++ b/static/netbsd/man9/fstrans.9 @@ -0,0 +1,331 @@ +.\" $NetBSD: fstrans.9,v 1.29 2018/10/05 16:21:22 uwe Exp $ +.\" +.\" Copyright (c) 2007 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Juergen Hannken-Illjes. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 4, 2018 +.Dt FSTRANS 9 +.Os +.Sh NAME +.Nm fstrans , +.Nm fstrans_setstate , +.Nm fstrans_getstate , +.Nm fstrans_start , +.Nm fstrans_start_nowait , +.Nm fstrans_start_lazy , +.Nm fstrans_done , +.Nm fstrans_is_owner , +.Nm fscow_establish , +.Nm fscow_disestablish , +.Nm fscow_run +.Nd file system suspension helper subsystem +.Sh SYNOPSIS +.In sys/mount.h +.In sys/fstrans.h +.Ft void +.Fn fstrans_start "struct mount *mp" +.Ft int +.Fn fstrans_start_nowait "struct mount *mp" +.Ft void +.Fn fstrans_start_lazy "struct mount *mp" +.Ft void +.Fn fstrans_done "struct mount *mp" +.Ft int +.Fn fstrans_setstate "struct mount *mp" "enum fstrans_state new_state" +.Ft "enum fstrans_state" +.Fn fstrans_getstate "struct mount *mp" +.Ft int +.Fn fstrans_is_owner "struct mount *mp" +.Ft int +.Fn fscow_establish "struct mount *mp" \ +"int (*func)(void *, struct buf *, bool)" "void *cookie" +.Ft int +.Fn fscow_disestablish "struct mount *mp" \ +"int (*func)(void *, struct buf *, bool)" "void *cookie" +.Ft int +.Fn fscow_run "struct buf *bp" "bool data_valid" +.Sh DESCRIPTION +The +.Nm +subsystem assists file system suspension and copy-on-write snapshots. +.Pp +The file system's normal operations, such as its +.Xr vnodeops 9 , +must be bracketed by +.Fn fstrans_start +and +.Fn fstrans_done +in a +.Em shared +transaction, which is blocked by suspending the file system and while +it is suspended. +.Pp +Operations needed while suspending the file system must be bracketed by +.Fn fstrans_start_lazy +and +.Fn fstrans_done +in a +.Em lazy +transaction, which is allowed while suspending the file system, but +blocked while the file system is suspended. +.Pp +Transactions are per-thread and nestable: if a thread is already in a +transaction, it can enter another transaction without blocking. +Each +.Fn fstrans_start +must be paired with +.Fn fstrans_done . +Transactions for multiple distinct mount points may not be nested. +.Pp +The file system's +.Xr VFS_SUSPENDCTL 9 +method can use +.Fn fstrans_setstate +to: +.Bl -dash +.It +enter the +.Dv FSTRANS_SUSPENDING +state to suspend all normal operations but allow lazy transactions, +.It +enter the +.Dv FSTRANS_SUSPENDED +state to suspend all operations, and +.It +restore to the +.Dv FSTRANS_NORMAL +state to resume all operations. +.El +.Pp +A file system supporting +.Nm +may establish a copy-on-write callback with +.Fn fscow_establish . +The copy-on-write callback will be called every time a buffer is +written to a block device with +.Fn VOP_STRATEGY +and every time a buffer is read into the +.Xr buffercache 9 +with +.Dv B_MODIFY +set indicating the caller's intent to modify it. +Anyone modifying a buffer may additionally use +.Fn fscow_run +to explicitly invoke the established callback. +The copy-on-write callback must be disestablished with +.Fn fscow_disestablish +when the file system is done with it. +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn fstrans_start "mp" +Enter a transaction on the file system +.Fa mp +in the current thread. +If the file system is in a state that blocks such transactions, wait +until it changes state to one that does not. +.Pp +If the file system is suspended, wait until it is resumed. +.Pp +However, if the current thread is already in a transaction on +.Fa mp , +.Fn fstrans_start +will enter a nested transaction and return immediately without +waiting. +.Pp +May sleep. +.It Fn fstrans_start_nowait "mp" +Like +.Fn fstrans_start , +but return +.Er EBUSY +immediately if transactions are blocked in its current state. +.Pp +May sleep nevertheless on internal locks. +.It Fn fstrans_start_lazy "mp" +Like +.Fn fstrans_start , +but will not block while suspending. +.Pp +May sleep. +.It Fn fstrans_done "mp" +End the current transaction on +.Fa mp . +.It Fn fstrans_getstate "mp" +Return the current state of the file system +.Fa mp . +.Pp +Must be called within a transaction for the answer to be stable. +.It Fn fstrans_setstate "mp" "new_state" +Change the state of the file system +.Fa mp +to +.Fa new_state , +and wait for all transactions not allowed in +.Fa new_state +to complete. +.Bl -tag -width "Dv FSTRANS_SUSPENDING" +.It Dv FSTRANS_NORMAL +Allow all transactions. +.It Dv FSTRANS_SUSPENDING +Block +.Dv FSTRANS_SHARED +transactions but allow +.Dv FSTRANS_LAZY +transactions. +.It Dv FSTRANS_SUSPENDED +Block all transactions. +.El +.Pp +A thread that changes a file system to a state other than +.Dv FSTRANS_NORMAL +enters a transaction for the purposes of +.Fn fstrans_getstate +until it changes state back to +.Dv FSTRANS_NORMAL . +.Pp +Additionally, a thread that changes a file system to a state other than +.Dv FSTRANS_NORMAL +acquires an exclusive lock on the file system state, so that +.Fn fstrans_is_owner +will return true in that thread, and no other thread can change the +file system's state until the owner restores it to +.Dv FSTRANS_NORMAL . +.Pp +May sleep, and may be interrupted by a signal. +On success, return zero. +On failure, restore the file system to the +.Dv FSTRANS_NORMAL +state and return an error code. +.Fn fstrans_setstate +never fails if +.Fa new_state +is +.Dv FSTRANS_NORMAL . +.It Fn fstrans_is_owner "mp" +Return +.Dv true +if the current thread is currently suspending the file system +.Fa mp . +.It Fn fscow_establish "mp" "func" "cookie" +Establish a copy-on-write callback for the file system +.Fa mp . +The function +.Fa func +will be called for every buffer +.Fa bp +written through this file system as +.Dl Fa func Ns ( Fa cookie , Fa bp , Fa data_valid ) +where +.Fa data_valid +is true if and only if the buffer +.Fa bp +has not yet been modified. +.Pp +May sleep. +.It Fn fscow_disestablish "mp" "func" "cookie" +Disestablish a copy-on-write callback established with +.Fn fscow_establish . +.Pp +May sleep. +.It Fn fscow_run "bp" "data_valid" +Run all copy-on-write callbacks established for the file system this buffer +belongs to, if they have not already been run for this buffer. +If +.Fa data_valid +is +.Dv true +the buffer data has not yet been modified. +.Pp +May sleep. +.El +.Sh EXAMPLES +The following is an example of a file system suspend operation. +.Bd -literal +int +xxx_suspendctl(struct mount *mp, int cmd) +{ + int error; + + switch (cmd) { + case SUSPEND_SUSPEND: + error = fstrans_setstate(mp, FSTRANS_SUSPENDING); + if (error) + return error; + return fstrans_setstate(mp, FSTRANS_SUSPENDED); + + case SUSPEND_RESUME: + return fstrans_setstate(mp, FSTRANS_NORMAL); + + default: + return EINVAL; + } +} +.Ed +.Pp +This is an example of a file system operation. +.Bd -literal +int +xxx_create(void *v) +{ + struct vop_create_args *ap = v; + struct mount *mp = ap->a_dvp->v_mount; + int error; + + fstrans_start(mp); + + /* Actually create the node. */ + + fstrans_done(mp); + + return 0; +} +.Ed +.Sh CODE REFERENCES +The +.Nm +subsystem is implemented in the file +.Pa sys/kern/vfs_trans.c . +.Sh SEE ALSO +.Xr vfs_resume 9 , +.Xr vfs_suspend 9 +.Sh HISTORY +The +.Nm +subsystem appeared in +.Nx 5.0 . +.Sh AUTHORS +The +.Nm +subsystem was written by +.An J\(:urgen Hannken-Illjes +.Aq hannken@NetBSD.org . +.Sh BUGS +.Nm +is useful only for temporary suspension \(em it does not help to +permanently block file system operations for unmounting, because +.Fn fstrans_start +cannot fail. diff --git a/static/netbsd/man9/genfs.9 b/static/netbsd/man9/genfs.9 new file mode 100644 index 00000000..3de54d45 --- /dev/null +++ b/static/netbsd/man9/genfs.9 @@ -0,0 +1,114 @@ +.\" $NetBSD: genfs.9,v 1.8 2022/01/17 22:27:20 wiz Exp $ +.\" +.\" Copyright 2012 Elad Efrat <elad@NetBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 17, 2022 +.Dt GENFS 9 +.Os +.Sh NAME +.Nm genfs +.Nd genfs routines +.Sh SYNOPSIS +.In miscfs/genfs/genfs.h +.Ft int +.Fn genfs_can_chflags "vnode_t *vp" kauth_cred_t cred" "uid_t owner_uid" \ +"bool changing_sysflags" +.Ft int +.Fn genfs_can_chmod "vnode_t *vp" "kauth_cred_t cred" "uid_t cur_uid" \ +"gid_t cur_gid" "mode_t new_mode" +.Ft int +.Fn genfs_can_chown "vnode_t *vp" "kauth_cred_t cred" "uid_t cur_uid" \ + "gid_t cur_gid" "uid_t new_uid" "gid_t new_gid" +.Ft int +.Fn genfs_can_chtimes "vnode_t *vp" "kauth_cred_t cred" "uid_t owner_uid" \ +"u_int vaflags" +.Ft int +.Fn genfs_can_extattr "vnode_t *vp" "kauth_cred_t cred" "accmode_t accmode" \ +"int attrnamespace" +.Ft int +.Fn genfs_can_sticky "vnode_t *vp" "kauth_cred_t cred" "uid_t dir_uid" \ + "uid_t file_uid" +.Sh DESCRIPTION +The functions documented here are general routines for internal use in +file systems to implement common policies for performing various operations. +The developer must understand that these routines implement no system-wide +policies and only take into account the object being accessed and the +nominal values of the credentials accessing it. +.Pp +In other words, these functions are not meant to be called directly. +They are intended to be used in +.Xr kauth 9 +vnode scope authorization calls, for providing the fall-back file system +decision. +.Pp +As a rule of thumb, code that looks like this is wrong: +.Bd -literal -offset indent +error = genfs_can_foo(...); /* WRONG */ +.Ed +.Pp +While code that looks like this is right: +.Bd -literal -offset indent +error = kauth_authorize_vnode(..., genfs_can_foo(...)); +.Ed +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn genfs_can_chflags "vnode_t *vp" "kauth_cred_t cred" +"uid_t owner_uid" "bool changing_sysflags" +Implements +.Xr chflags 2 +policy. +.It Fn genfs_can_chmod "vnode_t *vp" "kauth_cred_t cred" "uid_t cur_uid" \ +"gid_t cur_gid" "mode_t new_mode" +Implements +.Xr chmod 2 +policy. +.It Fn genfs_can_chown "vnode_t *vp" "kauth_cred_t cred" "uid_t cur_uid" \ +"gid_t cur_gid" "uid_t new_uid" "gid_t new_gid" +Implements +.Xr chown 2 +policy. +.It Fn genfs_can_chtimes "vnode_t *vp" "kauth_cred_t cred" "uid_t owner_uid" \ +"u_int vaflags" +Implements +.Xr utimes 2 +policy. +.It Fn genfs_can_extattr "vnode_t *vp" "kauth_cred_t cred" "accmode_t accmode" \ +"int attrnamespace" +Implements extended attributes access policy. +.It Fn genfs_can_sticky "vnode_t *vp" "kauth_cred_t cred" "uid_t dir_uid" \ +"uid_t file_uid" +Implements rename and delete policy from sticky directories. +.El +.Sh SEE ALSO +.Xr genfs_can_access 9 , +.Xr genfs_can_access_acl_nfs4 9 , +.Xr genfs_can_access_acl_posix1e 9 , +.Xr genfs_rename 9 , +.Xr kauth 9 +.Sh AUTHORS +.An Elad Efrat Aq Mt elad@NetBSD.org +wrote this manual page. diff --git a/static/netbsd/man9/genfs_can_access.9 b/static/netbsd/man9/genfs_can_access.9 new file mode 100644 index 00000000..31e8d9d3 --- /dev/null +++ b/static/netbsd/man9/genfs_can_access.9 @@ -0,0 +1,122 @@ +.\" $NetBSD: genfs_can_access.9,v 1.2 2022/01/17 22:27:20 wiz Exp $ +.\"- +.\" Copyright (c) 2001 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/share/man/man9/vaccess.9 206622 2010-04-14 19:08:06Z uqs $ +.\" +.Dd January 17, 2022 +.Dt GENFS_CAN_ACCESS 9 +.Os +.Sh NAME +.Nm genfs_can_access +.Nd generate an access control decision using vnode parameters +.Sh SYNOPSIS +.In miscfs/genfs/genfs.h +.Ft int +.Fo genfs_can_access +.Fa "vnode_t *vp" +.Fa "kauth_cred_t cred" +.Fa "uid_t file_uid" +.Fa "gid_t file_gid" +.Fa "mode_t file_mode" +.Fa "struct acl *acl" +.Fa "accmode_t accmode" +.Fc +.Sh DESCRIPTION +This call implements the logic for the +.Ux +discretionary file security model +common to many file systems in +.Fx . +It accepts the vnode +.Fa vp , +requesting credential +.Fa cred , +permissions via +owning UID +.Fa file_uid , +owning GID +.Fa file_gid , +file permissions +.Fa file_mode , +access ACL for the file +.Fa acl , +desired access mode +.Fa accmode , +.Pp +This call is intended to support implementations of +.Xr VOP_ACCESS 9 , +which will use their own access methods to retrieve the vnode properties, +and then invoke +.Fn vaccess +in order to perform the actual check. +Implementations of +.Xr VOP_ACCESS 9 +may choose to implement additional security mechanisms whose results will +be composed with the return value. +.Pp +The algorithm used by +.Fn genfs_can_access +selects a component of the file permission bits based on comparing the +passed credential, file owner, and file group. +If the credential's effective UID matches the file owner, then the +owner component of the permission bits is selected. +If the UID does not match, then the credential's effective GID, followed +by additional groups, are compared with the file group\[em]if there is +a match, then the group component of the permission bits is selected. +If neither the credential UID or GIDs match the passed file owner and +group, then the other component of the permission bits is selected. +.Pp +Once appropriate protections are selected for the current credential, +the requested access mode, in combination with the vnode type, will be +compared with the discretionary rights available for the credential. +If the rights granted by discretionary protections are insufficient, +then super-user privilege, if available for the credential, will also be +considered. +.Sh RETURN VALUES +.Fn genfs_can_access +will return 0 on success, or a non-zero error value on failure. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACCES +Permission denied. +An attempt was made to access a file in a way forbidden by its file access +permissions. +.It Bq Er EPERM +Operation not permitted. +An attempt was made to perform an operation limited to processes with +appropriate privileges or to the owner of a file or other resource. +.El +.Sh SEE ALSO +.Xr genfs 9 , +.Xr genfs_can_access_acl_nfs4 9 , +.Xr genfs_can_access_acl_posix1e 9 , +.Xr vnode 9 , +.Xr VOP_ACCESS 9 +.Sh AUTHORS +This manual page and the current implementation of +.Fn vaccess +were written by +.An Robert Watson . diff --git a/static/netbsd/man9/genfs_can_access_acl_nfs4.9 b/static/netbsd/man9/genfs_can_access_acl_nfs4.9 new file mode 100644 index 00000000..2ae7a6f5 --- /dev/null +++ b/static/netbsd/man9/genfs_can_access_acl_nfs4.9 @@ -0,0 +1,122 @@ +.\" $NetBSD: genfs_can_access_acl_nfs4.9,v 1.1 2022/01/17 19:08:06 christos Exp $ +.\"- +.\" Copyright (c) 2001 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/share/man/man9/genfs_can_access_acl_nfs4.9 267936 2014-06-26 21:44:30Z bapt $ +.\" +.Dd September 18, 2009 +.Dt GENFS_CAN_ACCESS_ACL_NFS4 9 +.Os +.Sh NAME +.Nm genfs_can_access_acl_nfs4 +.Nd generate a NFSv4 ACL access control decision using vnode parameters +.Sh SYNOPSIS +.In miscfs/genfs/genfs.h +.Ft int +.Fo genfs_can_access_acl_nfs4 + genfs_can_access_acl_nfs4(struct vnode *, kauth_cred_t, uid_t, gid_t, + mode_t, struct acl *, accmode_t) +.Fa "struct vnode *vp" +.Fa "kath_cred_t cred" +.Fa "uid_t file_uid" +.Fa "gid_t file_gid" +.Fa "mode_t file_mode" +.Fa "struct acl *acl" +.Fa "accmode_t accmode" +.Fc +.Sh DESCRIPTION +This call implements the logic for the +.Ux +discretionary file security model +with NFSv4 ACL extensions. +It accepts the vnode +.Fa vp , +requesting credential +.Fa cred , +owning UID +.Fa file_uid , +owning GID +.Fa file_gid , +file permissions +.Fa file_mode , +access ACL for the file +.Fa acl , +desired access mode +.Fa accmode , +.Pp +This call is intended to support implementations of +.Xr VOP_ACCESS 9 , +which will use their own access methods to retrieve the vnode properties, +and then invoke +.Fn genfs_can_access_acl_nfs4 +in order to perform the actual check. +Implementations of +.Xr VOP_ACCESS 9 +may choose to implement additional security mechanisms whose results will +be composed with the return value. +.Pp +The algorithm used by +.Fn genfs_can_access_acl_nfs4 +is based on the NFSv4 ACL evaluation algorithm, as described in +NFSv4 Minor Version 1, draft-ietf-nfsv4-minorversion1-21.txt. +The algorithm selects a +.Em matching +entry from the access ACL, which may +then be composed with an available ACL mask entry, providing +.Ux +security compatibility. +.Pp +Once appropriate protections are selected for the current credential, +the requested access mode, in combination with the vnode type, will be +compared with the discretionary rights available for the credential. +If the rights granted by discretionary protections are insufficient, +then super-user privilege, if available for the credential, will also be +considered. +.Sh RETURN VALUES +.Fn genfs_can_access_acl_nfs4 +will return 0 on success, or a non-zero error value on failure. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACCES +Permission denied. +An attempt was made to access a file in a way forbidden by its file access +permissions. +.It Bq Er EPERM +Operation not permitted. +An attempt was made to perform an operation limited to processes with +appropriate privileges or to the owner of a file or other resource. +.El +.Sh SEE ALSO +.Xr genfs_can_access 9 , +.Xr vnode 9 , +.Xr VOP_ACCESS 9 +.Sh AUTHORS +Current implementation of +.Fn genfs_can_access_acl_nfs4 +was written by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org . +.Sh BUGS +This manual page should include a full description of the NFSv4 ACL +evaluation algorithm, or cross reference another page that does. diff --git a/static/netbsd/man9/genfs_can_access_acl_posix1e.9 b/static/netbsd/man9/genfs_can_access_acl_posix1e.9 new file mode 100644 index 00000000..780e84cb --- /dev/null +++ b/static/netbsd/man9/genfs_can_access_acl_posix1e.9 @@ -0,0 +1,120 @@ +.\" $NetBSD: genfs_can_access_acl_posix1e.9,v 1.1 2022/01/17 19:08:06 christos Exp $ +.\"- +.\" Copyright (c) 2001 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/share/man/man9/genfs_can_access_acl_posix1e.9 206622 2010-04-14 19:08:06Z uqs $ +.\" +.Dd January 17, 2022 +.Dt GENFS_CAN_ACCESS_ACL_POSIX1E 9 +.Os +.Sh NAME +.Nm genfs_can_access_acl_posix1e +.Nd generate a POSIX.1e ACL access control decision using vnode parameters +.Sh SYNOPSIS +.In miscfs/genfs/genfs.h +.Ft int +.Fo genfs_can_access_acl_posix1e +.Fa "struct vnode *vp" +.Fa "kauth_cred_t cred" +.Fa "uid_t file_uid" +.Fa "gid_t file_gid" +.Fa "mode_t file_mode" +.Fa "struct acl *acl" +.Fa "accmode_t accmode" +.Fc +.Sh DESCRIPTION +This call implements the logic for the +.Ux +discretionary file security model +with POSIX.1e ACL extensions. +It accepts the vnode +.Fa vp , +requesting credential +.Fa cred , +owning UID +.Fa file_uid , +owning GID +.Fa file_gid , +file permissions +.Fa file_mode , +access ACL for the file +.Fa acl , +and +desired access mode +.Fa accmode . +.Pp +This call is intended to support implementations of +.Xr VOP_ACCESS 9 , +which will use their own access methods to retrieve the vnode properties, +and then invoke +.Fn genfs_can_access_acl_posix1e +in order to perform the actual check. +Implementations of +.Xr VOP_ACCESS 9 +may choose to implement additional security mechanisms whose results will +be composed with the return value. +.Pp +The algorithm used by +.Fn genfs_can_access_acl_posix1e +is based on the POSIX.1e ACL evaluation algorithm. +The algorithm selects a +.Em matching +entry from the access ACL, which may +then be composed with an available ACL mask entry, providing +.Ux +security compatibility. +.Pp +Once appropriate protections are selected for the current credential, +the requested access mode, in combination with the vnode type, will be +compared with the discretionary rights available for the credential. +If the rights granted by discretionary protections are insufficient, +then super-user privilege, if available for the credential, will also be +considered. +.Sh RETURN VALUES +.Fn genfs_can_access_acl_posix1e +will return 0 on success, or a non-zero error value on failure. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACCES +Permission denied. +An attempt was made to access a file in a way forbidden by its file access +permissions. +.It Bq Er EPERM +Operation not permitted. +An attempt was made to perform an operation limited to processes with +appropriate privileges or to the owner of a file or other resource. +.El +.Sh SEE ALSO +.Xr genfs_can_access 9 , +.Xr vnode 9 , +.Xr VOP_ACCESS 9 +.Sh AUTHORS +This manual page and the current implementation of +.Fn genfs_can_access_acl_posix1e +were written by +.An Robert Watson . +.Sh BUGS +This manual page should include a full description of the POSIX.1e ACL +evaluation algorithm, or cross reference another page that does. diff --git a/static/netbsd/man9/genfs_rename.9 b/static/netbsd/man9/genfs_rename.9 new file mode 100644 index 00000000..115be04c --- /dev/null +++ b/static/netbsd/man9/genfs_rename.9 @@ -0,0 +1,621 @@ +.\" $NetBSD: genfs_rename.9,v 1.5 2022/01/17 22:27:10 wiz Exp $ +.\" +.\" Copyright (c) 2013 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation is derived from text contributed to The NetBSD +.\" Foundation by Taylor R. Campbell. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 1, 2013 +.Dt GENFS_RENAME 9 +.Os +.Sh NAME +.Nm genfs_rename , +.Nm genfs_insane_rename , +.Nm genfs_sane_rename +.Nd generic framework for implementing +.Xr VOP_RENAME 9 +.Sh SYNOPSIS +.Ft int +.Fo genfs_insane_rename +.Fa "struct vop_rename_args *v" +.Fa "int (*sane_rename)(struct vnode *fdvp, struct componentname *fcnp, struct vnode *tdvp, struct componentname *tcnp, kauth_cred_t, bool)" +.Fc +.Ft int +.Fo genfs_sane_rename +.Fa "const struct genfs_rename_ops *gro" +.Fa "struct vnode *fdvp" +.Fa "struct componentname *fcnp" +.Fa "void *fde" +.Fa "struct vnode *tdvp" +.Fa "struct componentname *tcnp" +.Fa "void *tde" +.Fa "kauth_cred_t cred" +.Fa "bool posixly_correct" +.Fc +.Ft int +.Fo genfs_rename_knote +.Fa "struct vnode *fdvp" +.Fa "struct vnode *fvp" +.Fa "struct vnode *tdvp" +.Fa "struct vnode *tvp" +.Fc +.Ft void +.Fo genfs_rename_cache_purge +.Fa "struct vnode *fdvp" +.Fa "struct vnode *fvp" +.Fa "struct vnode *tdvp" +.Fa "struct vnode *tvp" +.Fc +.Ft int +.Fo genfs_ufslike_rename_check_possible +.Fa "unsigned long fdflags" +.Fa "unsigned long fflags" +.Fa "unsigned long tdflags" +.Fa "unsigned long tflags" +.Fa "bool clobber" +.Fa "unsigned long immutable" +.Fa "unsigned long append" +.Fc +.Ft int +.Fo genfs_ufslike_rename_check_permitted +.Fa "kauth_cred_t cred" +.Fa "struct vnode *fdvp" +.Fa "mode_t fdmode" +.Fa "uid_t fduid" +.Fa "struct vnode *fvp" +.Fa "uid_t fuid" +.Fa "struct vnode *tdvp" +.Fa "mode_t tdmode" +.Fa "uid_t tduid" +.Fa "struct vnode *tvp" +.Fa "uid_t tuid" +.Fc +.Ft int +.Fo genfs_ufslike_remove_check_possible +.Fa "unsigned long dflags" +.Fa "unsigned long flags" +.Fa "unsigned long immutable" +.Fa "unsigned long append" +.Fc +.Ft int +.Fo genfs_ufslike_remove_check_permitted +.Fa "kauth_cred_t cred" +.Fa "struct vnode *dvp" +.Fa "mode_t dmode" +.Fa "uid_t duid" +.Fa "struct vnode *vp" +.Fa "uid_t uid" +.Fc +.Sh DESCRIPTION +The +.Nm +functions provide a file-system-independent framework for implementing +.Xr VOP_RENAME 9 +with correct locking and error-checking. +.Pp +Implementing rename is nontrivial. +If you are doing it for a new file system, you should consider starting +from +.Fn tmpfs_rename +as implemented in +.Pa sys/fs/tmpfs/tmpfs_rename.c +and adapting it to your file system's physical operations. +.Pp +Because there are so many moving parts to a rename operation, +.Nm +uses the following naming conventions: +.Bl -tag -width indent +.It Fa mp Pq "mount point" +mount point of the file system in question +.It Fa fdvp Pq "from directory vnode pointer" +directory from which we are removing an entry +.It Fa fcnp Pq "from componentname pointer" +name of entry to remove from +.Fa fdvp +.It Fa fde Pq "from directory entry" +fs-specific data about the entry in +.Fa fdvp +.It Fa fvp Pq "from vnode pointer" +file at the entry named +.Fa fcnp +in +.Fa fdvp +.It Fa tdvp Pq "to directory vnode pointer" +directory to which we are adding an entry +.It Fa tcnp Pq "to componentname pointer" +name of entry to add to +.Fa tdvp +.It Fa tde Pq "to directory entry" +fs-specific data about the entry in +.Fa tdvp +.It Fa tvp Pq "to vnode pointer" +file previously at the entry named +.Fa tcnp +in +.Fa tdvp , +to be replaced, if any, or +.Dv NULL +if there was no entry before +.It Fa vp Pq "vnode pointer" +any file +.It Fa dvp Pq "directory vnode pointer" +any directory with an entry for +.Fa vp +.El +.Pp +A file system mumblefs should implement various file-system-dependent +parts of the rename operation in a +.Vt struct genfs_rename_ops , +and use +.Nm +to implement +.Fn mumblefs_rename +for +.Xr VOP_RENAME 9 +as follows: +.Bd -literal -offset indent +static const struct genfs_rename_ops mumblefs_genfs_rename_ops; + +static int +mumblefs_sane_rename( + struct vnode *fdvp, struct componentname *fcnp, + struct vnode *tdvp, struct componentname *tcnp, + kauth_cred_t cred, bool posixly_correct) +{ + struct mumblefs_lookup_results fulr, tulr; + + return genfs_sane_rename(&mumblefs_genfs_rename_ops, + fdvp, fcnp, &fulr, tdvp, tcnp, &tulr, + cred, posixly_correct); +} + +int +mumblefs_rename(void *v) +{ + + return genfs_insane_rename(v, &mumblefs_sane_rename); +} +.Ed +.Pp +The split between +.Fn mumblefs_rename +and +.Fn mumblefs_sane_rename +is designed to enable us to easily change the +.Xr VOP_RENAME 9 +interface, which is currently designed for a broken (hence +.Sq insane ) +locking scheme, to a more sensible locking scheme once all the file +systems have their rename operations split up thus. +.Pp +The +.Vt struct mumblefs_lookup_results +structure is storage for information about directory entries which +needs to pass from the lookups of the children (see the +.Fa gro_lookup +member of +.Vt "struct genfs_rename_ops" ) +to the physical on-disk rename or remove operations (see the +.Fa gro_rename +and +.Fa gro_remove +members of +.Vt "struct genfs_rename_ops" ) . +.Pp +Callers must implement the following operations as members in a +.Vt struct genfs_rename_ops +structure passed to +.Nm : +.Bl -tag -width indent +.It Ft int Fn "(*gro_genealogy)" "struct mount *mp" "kauth_cred_t cred" "struct vnode *fdvp" "struct vnode *tdvp" "struct vnode **intermediate_node_ret" +Walk up the directory tree from the directory vnode +.Fa tdvp +until hitting either +.Fa fdvp +or the root. +If +.Fa fdvp +is hit, store the child of +.Fa fdvp +through which the path from +.Fa tdvp +passed in +.Fa *intermediate_node_ret , +referenced but unlocked. +If +.Fa fdvp +is not hit, store +.Dv NULL +in +.Fa *intermediate_node_ret . +Return zero on success or error on failure. +(Failure means file-system-specific failures, not hitting or missing +.Fa fdvp . ) +.Pp +.Fa fdvp +and +.Fa tdvp +are guaranteed to be distinct, non-null, referenced, and unlocked. +Since no locks are held on entry except for the file-system-wide rename +lock, +.Fa gro_genealogy +may take any locks it pleases. +.It Ft int Fn "(*gro_lock_directory)" "struct mount *mp" "struct vnode *vp" +Lock the directory vnode +.Fa vp , +but fail if it has been rmdired already. +Return zero on success or error on failure. +.It Ft int Fn "(*gro_lookup)" "struct mount *mp" "struct vnode *dvp" "struct componentname *cnp" "void *de" "struct vnode **vpp" +Look up the entry in +.Fa dvp +for +.Fa cnp , +storing the vnode in +.Fa "*vpp" +and using +.Fa de , +one of the pointers passed to +.Nm genfs_sane_rename , +to store information about the directory entry as needed by the file +system's +.Fa gro_rename +operation, and return zero. +If there is no such entry, return error. +.Pp +.Fa dvp +is guaranteed to be locked, and the vnode returned in +.Fa "*vpp" +must be unlocked. +However, +.Fa gro_lookup +may temporarily lock the vnode without causing deadlock. +.It Ft bool Fn "(*gro_directory_empty_p)" "struct mount *mp" "kauth_cred_t cred" "struct vnode *vp" "struct vnode *dvp" +Return true if the directory vnode +.Fa vp +is empty. +The argument +.Fa dvp +is the parent of +.Fa vp , +as required for this check by some file systems. +.Pp +.Fa dvp +and +.Fa vp +are guaranteed to be distinct, non-null, referenced, and locked. +.It Ft int Fn "(*gro_rename_check_possible)" "struct mount *mp" "struct vnode *fdvp" "struct vnode *fvp" "struct vnode *tdvp" "struct vnode *tvp" +Return zero if the file system might allow the rename independent of +credentials, or error if not. +This should check, for example, any immutability flags in the vnodes in +question, and should use +.Fn genfs_ufslike_rename_check_possible +for file systems similar to UFS/FFS. +.Pp +.Fa fdvp +and +.Fa tdvp +may be the same; every other pair of vnodes is guaranteed to be +distinct. +.Fa tvp +may be +.Dv NULL ; +every other vnode is guaranteed to be non-null. +All three or four vnodes are guaranteed to be referenced and locked. +.It Ft int Fn "(*gro_rename_check_permitted)" "struct mount *mp" "kauth_cred_t cred" "struct vnode *fdvp" "struct vnode *fvp" "struct vnode *tdvp" "struct vnode *tvp" +Return zero if the file system allows the rename given the credentials +.Fa cred , +or error if not. +This should check, for example, the ownership and permissions bits of +the vnodes in question, and should use +.Fn genfs_ufslike_rename_check_permitted +for file systems similar to UFS/FFS. +.Pp +.Fa fdvp +and +.Fa tdvp +may be the same; every other pair of vnodes is guaranteed to be +distinct. +.Fa tvp +may be +.Dv NULL ; +every other vnode is guaranteed to be non-null. +All three or four vnodes are guaranteed to be referenced and locked. +.It Ft int Fn "(*gro_rename)" "struct mount *mp" "kauth_cred_t cred" "struct vnode *fdvp" "struct componentname *fcnp" "void *fde" "struct vnode *fvp" "struct vnode *tdvp" "struct componentname *tcnp" "void *tde" "struct vnode *tvp" +Perform the physical file system rename operation, report any knotes, +and purge the namecache entries. +Return zero on success or error on failure. +All file-system-independent error cases have been handled already. +.Pp +File systems using +.Xr fstrans 9 +should use +.Xr fstrans_start 9 +and +.Xr fstrans_done 9 +here. +.Fa fde +and +.Fa tde +are the pointers that were supplied to +.Fn genfs_sane_rename +and got passed to the +.Fa gro_lookup +operation to find information about directory entries. +.Pp +This may use +.Fn genfs_rename_knote +to report any knotes, if the various file-system-dependent routines it +uses to edit links don't do that already. +This should use +.Fn genfs_rename_cache_purge +to purge the namecache. +.Pp +.Fa fdvp +and +.Fa tdvp +may be the same; every other pair of vnodes is guaranteed to be +distinct. +.Fa tvp +may be null; every other vnode is guaranteed to be non-null. +All three or four vnodes are guaranteed to be referenced and locked. +.It Ft int Fn "(*gro_remove_check_possible)" "struct mount *mp" "struct vnode *dvp" "struct vnode *vp" +Return zero if the file system might allow removing an entry in +.Fa dvp +for +.Fa vp +independent of credentials, or error if not. +This should use +.Fn genfs_ufslike_remove_check_possible +for file systems similar to UFS/FFS. +.Pp +.Fa dvp +and +.Fa vp +are guaranteed to be distinct, non-null, referenced, and locked. +.Pp +This, and +.Fa gro_remove_check_permitted +below, are for renames that reduce to a remove; that is, renaming one +entry to another when both entries refer to the same file. +For reasons of locking insanity, +.Nm +cannot simply call +.Xr VOP_REMOVE 9 +instead. +.It Ft int Fn "(*gro_remove_check_permitted)" "struct mount *mp" "kauth_cred_t cred" "struct vnode *dvp" "struct vnode *vp" +Return zero if the file system allows removing an entry in +.Fa dvp +for +.Fa vp +given the credentials +.Fa cred , +or error if not. +This should use +.Fn genfs_ufslike_remove_check_permitted +for file systems similar to UFS/FFS. +.Pp +.Fa dvp +and +.Fa vp +are guaranteed to be distinct, non-null, referenced, and locked. +.It Ft int Fn "(*gro_remove)" "struct mount *mp" "kauth_cred_t cred" "struct vnode *dvp" "struct componentname *cnp" "void *de" "struct vnode *vp" +For a rename that is effectively a remove, perform the physical file +system remove operation, report any knotes, and purge the namecache +entries. +Return zero on success or error on failure. +All file-system-independent error cases have been handled already. +.Pp +File systems using +.Xr fstrans 9 +should use +.Xr fstrans_start 9 +and +.Xr fstrans_done 9 +here. +.Fa de +is one of the pointers that were supplied to +.Fn genfs_sane_rename +and got passed to the +.Fa gro_lookup +operation to find information about directory entries. +.Pp +This should signal a +.Dv NOTE_WRITE +knote for +.Fa dvp , +and either a +.Dv NOTE_DELETE +or a +.Dv NOTE_LINK +knote for +.Fa vp , +depending on whether this removed the last link to it or not. +.Pp +.Fa dvp +and +.Fa vp +are guaranteed to be distinct, non-null, referenced, and locked. +.El +.Pp +The following utilities are provided for implementing the +.Vt struct genfs_rename_ops +operations: +.Bl -tag -width indent +.It Fn genfs_rename_knote fdvp fvp tdvp tvp +Signal all the knotes relevant for the rename operation. +.It Fn genfs_rename_cache_purge fdvp fvp tdvp tvp +Purge any namecache entries that the rename operation invalidates. +.It Fn genfs_ufslike_rename_check_possible fdflags fflags tdflags tflags clobber immutable append +Check whether the UFS/FFS-like flags of the files involved a rename +allow it. +Return zero if allowed or error if not. +.Pp +.Bl -tag -width immutable -compact +.It Fa fdflags +flags of source directory +.It Fa fflags +flags of source file +.It Fa tdflags +flags of target directory +.It Fa tflags +flags of target file, if there is one and +.Fa clobber +is true, or ignored otherwise +.It Fa clobber +true if there is a target file whose entry will be clobbered or false +if not +.It Fa immutable +bit mask for the file system's immutable bit, like the UFS/FFS +.Dv IMMUTABLE +.It Fa append +bit mask for the file system's append-only bit, like the UFS/FFS +.Dv APPEND +.El +.It Fn genfs_ufslike_rename_check_permitted cred fdvp fdmode fduid fvp fuid tdvp tdmode tduid tvp tuid +Check whether the credentials +.Fa cred +are permitted by the file ownership and permissions bits to perform a +rename. +Return zero if permitted or error if not. +.Pp +.Bl -tag -width fdmode -compact +.It Fa cred +caller's credentials +.It Fa fdvp +source directory +.It Fa fdmode +file permissions bits of +.Fa fdvp +.It Fa fduid +uid of the owner of +.Fa fdvp +.It Fa fvp +source file +.It Fa fuid +uid of owner of +.Fa fvp +.It Fa tdvp +target directory +.It Fa tdmode +file permissions bits of +.Fa tdvp +.It Fa tduid +uid of owner of +.Fa tdvp +.It Fa tvp +target file, if there is one, or +.Dv NULL +if not +.It Fa tuid +uid of owner of +.Fa tvp , +if there is a target file, or ignored otherwise +.El +.It Fn genfs_ufslike_remove_check_possible dflags flags immutable append +Check whether the UFS/FFS-like flags of the files involved a remove +allow it. +Return zero if allowed or error if not. +.Pp +.Bl -tag -width immutable -compact +.It Fa dflags +flags of the directory +.It Fa flags +flags of the file in the directory +.It Fa immutable +bit mask for the file system's immutable bit, like the UFS/FFS +.Dv IMMUTABLE +.It Fa append +bit mask for the file system's append-only bit, like the UFS/FFS +.Dv APPEND +.El +.It Fn genfs_ufslike_remove_check_permitted cred dvp dmode duid vp uid +Check whether the credentials +.Fa cred +are permitted by the file ownership and permissions bits to perform a +remove. +Return zero if permitted or error if not. +.Pp +.Bl -tag -width fdmode -compact +.It Fa cred +caller's credentials +.It Fa dvp +directory +.It Fa dmode +file permissions bits of +.Fa dvp +.It Fa duid +uid of owner of +.Fa dvp +.It Fa vp +file in +.Fa dvp +.It Fa uid +uid of owner of +.Fa vp +.El +.El +.Sh NOTES +Because there are so many cases of rename, it cannot be assumed a +priori that any pairs of +.Fa fdvp , +.Fa fvp , +.Fa tdvp , +or +.Fa fvp +are distinct: +.Bl -column -offset indent \ +"fdvp = tdvp" "rename(\*qa/b\*q, \*qa/c\*q)" +.It Li "fdvp = fvp" Ta Li "rename(\*qa/.\*q, \*qb\*q)" +.It Li "fdvp = tdvp" Ta Li "rename(\*qa/b\*q, \*qa/c\*q)" +.It Li "fdvp = tvp" Ta Li "rename(\*qa/b\*q, \*qa\*q)" +.It Li "fvp = tdvp" Ta Li "rename(\*qa\*q, \*qa/b\*q)" +.It Li "fvp = tvp" Ta Li "rename(\*qa\*q, \*qa\*q)" +.It Li "tdvp = tvp" Ta Li "rename(\*qa\*q, \*qb/.\*q)" +.El +.Pp +Handling all these cases correctly, and getting the locking correct and +deadlock-free, is very tricky, which is why +.Nm +exists. +The interface to +.Nm +is very complicated because it must fit the insane +.Xr VOP_RENAME 9 +and +.Xr VOP_LOOKUP 9 +protocols until we can fix them, and because it must accommodate a +variety of crufty file systems. +.Sh SEE ALSO +.Xr genfs 9 , +.Xr vfs 9 , +.Xr vnodeops 9 +.Sh HISTORY +.Nm +was designed and implemented by +.An Taylor R. Campbell Aq Mt riastradh@NetBSD.org +after many discussions with +.An David Holland Aq Mt dholland@NetBSD.org , +and first appeared in +.Nx 6.0 . diff --git a/static/netbsd/man9/hardclock.9 b/static/netbsd/man9/hardclock.9 new file mode 100644 index 00000000..5eadb5d9 --- /dev/null +++ b/static/netbsd/man9/hardclock.9 @@ -0,0 +1,81 @@ +.\" $NetBSD: hardclock.9,v 1.3 2010/03/25 15:17:38 jruoho Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Thomas Klausner. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 25, 2010 +.Dt HARDCLOCK 9 +.Os +.Sh NAME +.Nm hardclock +.Nd real-time timer +.Sh SYNOPSIS +.Ft void +.Fn hardclock "struct clockframe *frame" +.Sh DESCRIPTION +The +.Fn hardclock +function is called +.Xr hz 9 +times per second. +It implements the real-time system clock. +The argument +.Va frame +is an opaque, +machine-dependent structure that encapsulates the previous machine state. +.Pp +The +.Fn hardclock +performs different tasks such as: +.Bl -bullet -offset indent +.It +Run the current process's virtual and profile time (decrease the +corresponding timers, if they are activated, and generate +.Li SIGVTALRM +or +.Li SIGPROF , +respectively). +.It +Increment the time-of-day, taking care of any +.Xr ntpd 8 +or +.Xr adjtime 2 +induced changes and leap seconds, as well as any necessary +compensations to keep in sync with PPS signals or external clocks, if +support for this is in the kernel (see +.Xr options 4 ) . +.It +Schedule softclock interrupts if any callouts should be triggered (see +.Xr callout 9 ) . +.El +.Sh SEE ALSO +.Xr adjtime 2 , +.Xr ntp_adjtime 2 , +.Xr signal 7 , +.Xr ntpd 8 , +.Xr callout 9 , +.Xr hz 9 diff --git a/static/netbsd/man9/hash.9 b/static/netbsd/man9/hash.9 new file mode 100644 index 00000000..c024bd89 --- /dev/null +++ b/static/netbsd/man9/hash.9 @@ -0,0 +1,118 @@ +.\" $NetBSD: hash.9,v 1.4 2008/04/30 13:10:58 martin Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Luke Mewburn of Wasabi Systems, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 5, 2001 +.Dt HASH 9 +.Os +.Sh NAME +.Nm hash , +.Nm hash32_buf , +.Nm hash32_str , +.Nm hash32_strn +.Nd kernel hash functions +.Sh SYNOPSIS +.In sys/types.h +.In sys/hash.h +.Ft uint32_t +.Fn hash32_buf "const void *buf" "size_t len" "uint32_t ihash" +.Ft uint32_t +.Fn hash32_str "const void *buf" "uint32_t ihash" +.Ft uint32_t +.Fn hash32_strn "const void *buf" "size_t len" "uint32_t ihash" +.Sh DESCRIPTION +The +.Nm +functions returns a hash of the given buffer. +.Pp +The +.Fn hash32_buf +function returns a 32 bit hash of +.Fa buf , +which is +.Fa len +bytes long, +seeded with an initial hash of +.Fa ihash +(which is usually +.Dv HASH32_BUF_INIT ) . +This function may use a different algorithm to +.Fn hash32_str +and +.Fn hash32_strn . +.Pp +The +.Fn hash32_str +function returns a 32 bit hash of +.Fa buf , +which is +a +.Dv NUL +terminated +.Tn ASCII +string, +seeded with an initial hash of +.Fa ihash +(which is usually +.Dv HASH32_STR_INIT ) . +This function must use the same algorithm as +.Fn hash32_strn , +so that the same data returns the same hash. +.Pp +The +.Fn hash32_strn +function returns a 32 bit hash of +.Fa buf , +which is +a +.Dv NUL +terminated +.Tn ASCII +string, +up to a maximum of +.Fa len +bytes, +seeded with an initial hash of +.Fa ihash +(which is usually +.Dv HASH32_STR_INIT ) . +This function must use the same algorithm as +.Fn hash32_str , +so that the same data returns the same hash. +.Pp +The +.Fa ihash +parameter is provided to allow for incremental hashing by allowing +successive calls to use a previous hash value. +.Sh RETURN VALUES +The +.Fa hash32_* +functions return a 32 bit hash of the provided buffer. +.Sh HISTORY +The kernel hashing API first appeared in +.Nx 1.6 . diff --git a/static/netbsd/man9/hashinit.9 b/static/netbsd/man9/hashinit.9 new file mode 100644 index 00000000..3df9f596 --- /dev/null +++ b/static/netbsd/man9/hashinit.9 @@ -0,0 +1,205 @@ +.\" $NetBSD: hashinit.9,v 1.9 2013/09/17 19:58:03 wiz Exp $ +.\" +.\" Copyright (c) 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Chapman Flack. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 1, 2008 +.Dt HASHINIT 9 +.Os +.Sh NAME +.Nm hashinit , +.Nm hashdone +.Nd kernel hash table construction and destruction +.Sh SYNOPSIS +.In sys/systm.h +.Ft "void *" +.Fo hashinit +.Fa "u_int chains" +.Fa "enum hashtype htype" +.Fa "bool waitok" +.Fa "u_long *hashmask" +.Fc +.Ft void +.Fn hashdone "void *hashtbl" "enum hashtype htype" "u_long hashmask" +.Sh DESCRIPTION +The +.Fn hashinit +function allocates and initializes space for a simple chaining hash table. +The number of slots will be the least power of two not smaller than +.Fa chains . +The customary choice for +.Fa chains +is the maximum number of elements you intend to store divided by +your intended load factor. +The +.Dv LIST... +or +.Dv TAILQ... +macros of +.Xr queue 3 +can be used to manipulate the chains; pass +.Dv HASH_LIST +or +.Dv HASH_TAILQ +as +.Fa htype +to indicate which. +Each slot will be initialized as the head of an empty chain of the +proper type. +Because different data structures from +.Xr queue 3 +can define head structures of different sizes, the total size of the +allocated table can vary with the choice of +.Fa htype . +.Pp +If +.Fa waitok +is true, +.Fa hashinit +can wait until enough memory is available. +Otherwise, it immediately fails if there is not enough memory is available. +.Pp +A value will be stored into +.Fa *hashmask +suitable for masking any computed hash, to obtain the index of a chain +head in the allocated table. +.Pp +The +.Fn hashdone +function deallocates the storage allocated by +.Fn hashinit +and pointed to by +.Fa hashtbl , +given the same +.Fa htype +and +.Fa hashmask +that were passed to and returned from +.Fn hashinit . +If the table contains any nonempty chain when +.Fn hashdone +is called, the result is undefined. +.Sh RETURN VALUES +The value returned by +.Fn hashinit +should be cast as pointer to an array of +.Dv LIST_HEAD +or +.Dv TAILQ_HEAD +as appropriate. +.Fn hashinit +returns +.Dv NULL +on failure. +.Sh CODE REFERENCES +These functions are implemented in +.Pa sys/kern/subr_hash.c . +.Sh SEE ALSO +.Xr queue 3 , +.Xr hash 9 , +.Xr malloc 9 +.Sh HISTORY +A +.Fn hashinit +function was present, without the +.Fa htype +or +.Fa mflags +arguments, in +.Bx 4.4 alpha . +It was independent of +.Xr queue 3 +and simply allocated and nulled a table of pointer-sized slots. +It sized the table to the +.Em largest +power of two +.Em not greater than +.Fa chains ; +that is, it built in a load factor between 1 and 2. +.Pp +.Nx 1.0 +was the first +.Nx +release to have a +.Fn hashinit +function. +It resembled that from +.Bx 4.4 +but made each slot a +.Dv LIST_HEAD +from +.Xr queue 3 . +For +.Nx 1.3.3 +it had been changed to size the table to the least power of two +not less than +.Em or equal to +.Fa chains . +By +.Nx 1.4 +it had the +.Fa mflags +argument and the current sizing rule. +.Pp +.Nx 1.5 +had the +.Fn hashdone +function. +By +.Nx 1.6 +.Fn hashinit +supported +.Dv LIST +or +.Dv TAILQ +chains selected with +.Fa htype . +.Pp +.Fx +has a +.Fn hashinit +with behavior equivalent (as of +.Fx 6.1 ) +to that in +.Nx 1.0 , +and a +.Fn hashdestroy +that behaves as +.Fn hashdone +but checks that all chains are empty first. +.Ox +has a +.Fn hashinit +comparable (as of +.Ox 3.9 ) +to that of +.Nx 1.4 . +This manual page was added for +.Nx 4.0 . +.Sh BUGS +The only part of the work of implementing a hash table that these functions +relieve is the part that isn't much work. diff --git a/static/netbsd/man9/heartbeat.9 b/static/netbsd/man9/heartbeat.9 new file mode 100644 index 00000000..3e2deff4 --- /dev/null +++ b/static/netbsd/man9/heartbeat.9 @@ -0,0 +1,172 @@ +.\" $NetBSD: heartbeat.9,v 1.6 2024/06/02 13:28:45 andvar Exp $ +.\" +.\" Copyright (c) 2023 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 6, 2023 +.Dt HEARTBEAT 9 +.Os +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh NAME +.Nm heartbeat +.Nd periodic checks to ensure CPUs are making progress +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SYNOPSIS +.Cd "options HEARTBEAT" +.Cd "options HEARTBEAT_MAX_PERIOD_DEFAULT=15" +.Pp +.\" +.In sys/heartbeat.h +.\" +.Ft void +.Fn heartbeat_start void +.Ft void +.Fn heartbeat void +.Ft void +.Fn heartbeat_suspend void +.Ft void +.Fn heartbeat_resume void +.Fd "#ifdef DDB" +.Ft void +.Fn heartbeat_dump void +.Fd "#endif" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh DESCRIPTION +The +.Nm +subsystem verifies that soft interrupts +.Pq Xr softint 9 +and the system +.Xr timecounter 9 +are making progress over time, and panics if they appear stuck. +.Pp +The number of seconds before +.Nm +panics without progress is controlled by the sysctl knob +.Li kern.heartbeat.max_period , +which defaults to 15. +If set to zero, heartbeat checks are disabled. +.Pp +The periodic hardware timer interrupt handler calls +.Fn heartbeat +every tick on each CPU. +Once per second +.Po +i.e., every +.Xr hz 9 +ticks +.Pc , +.Fn heartbeat +schedules a soft interrupt at priority +.Dv SOFTINT_CLOCK +to advance the current CPU's view of +.Xr time_uptime 9 . +.Pp +.Fn heartbeat +checks whether +.Xr time_uptime 9 +has changed, to see if either the +.Xr timecounter 9 +or soft interrupts on the current CPU are stuck. +If it hasn't advanced within +.Li kern.heartbeat.max_period +seconds worth of ticks, or if it has updated and the current CPU's view +of it hasn't been updated by more than +.Li kern.heartbeat.max_period +seconds, then +.Fn heartbeat +panics. +.Pp +.Fn heartbeat +also checks whether the next online CPU has advanced its view of +.Xr time_uptime 9 , +to see if soft interrupts +.Pq including Xr callout 9 +on that CPU are stuck. +If it hasn't updated within +.Li kern.heartbeat.max_period +seconds, +.Fn heartbeat +sends an +.Xr ipi 9 +to panic on that CPU. +If that CPU has not acknowledged the +.Xr ipi 9 +within one second, +.Fn heartbeat +panics on the current CPU instead. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh FUNCTIONS +.Bl -tag -width Fn +.It Fn heartbeat +Check for timecounter and soft interrupt progress on this CPU and on +another CPU, and schedule a soft interrupt to advance this CPU's view +of timecounter progress. +.Pp +Called by +.Xr hardclock 9 +periodically. +.It Fn heartbeat_dump +Print each CPU's heartbeat counter, uptime cache, and uptime cache +timestamp (in units of heartbeats) to the console. +.Pp +Can be invoked from +.Xr ddb 9 +by +.Ql call heartbeat_dump . +.It Fn heartbeat_resume +Resume heartbeat monitoring of the current CPU. +.Pp +Called after a CPU has started running but before it has been +marked online. +.It Fn heartbeat_start +Start monitoring heartbeats systemwide. +.Pp +Called by +.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. +.Pp +Called after the current CPU has been marked offline but before it has +stopped running. +.El +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh CODE REFERENCES +The +.Nm +subsystem is implemented in +.Pa sys/kern/kern_heartbeat.c . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SEE ALSO +.Xr swwdog 4 , +.Xr wdogctl 8 +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh HISTORY +The +.Nm +subsystem first appeared in +.Nx 11.0 . diff --git a/static/netbsd/man9/humanize_number.9 b/static/netbsd/man9/humanize_number.9 new file mode 100644 index 00000000..9bfa1c58 --- /dev/null +++ b/static/netbsd/man9/humanize_number.9 @@ -0,0 +1,119 @@ +.\" $NetBSD: humanize_number.9,v 1.9 2010/08/07 16:41:34 jruoho Exp $ +.\" +.\" Copyright (c) 1999 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Luke Mewburn. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 7, 2010 +.Dt HUMANIZE_NUMBER 9 +.Os +.Sh NAME +.Nm humanize_number , +.Nm format_bytes +.Nd human readable numbers +.Sh SYNOPSIS +.Ft int +.Fn humanize_number \ +"char *buf" "size_t len" "uint64_t number" "const char *suffix" "int divisor" +.Ft int +.Fn format_bytes "char *buf" "size_t len" "uint64_t number" +.Sh DESCRIPTION +The +.Fn humanize_number +function formats the unsigned 64-bit quantity given in +.Fa number +into +.Fa buf . +A space and then +.Fa suffix +is appended to the end. +The supplied +.Fa buf +must be at least +.Fa len +bytes long. +.Pp +If the formatted number (including +.Fa suffix ) +is too long to fit into +.Fa buf , +.Fn humanize_number +divides +.Fa number +by +.Fa divisor +until it will fit. +In this case, +.Fa suffix +is prefixed with the appropriate SI designator. +Suitable values of +.Fa divisor +are 1024 or 1000 to remain consistent with the common meanings of the +SI designator prefixes. +.Pp +The prefixes are: +.Bl -column "Prefix" "Description" "Multiplier" -offset indent +.It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier" +.It k kilo 1024 +.It M mega 1048576 +.It G giga 1073741824 +.It T tera 1099511627776 +.It P peta 1125899906842624 +.It E exa 1152921504606846976 +.El +.Pp +The +.Fa len +argument must be at least 4 plus the length of +.Fa suffix , +in order to ensure a useful result in +.Fa buf . +.Pp +The +.Fn format_bytes +function +is a front-end to +.Fn humanize_number . +It calls the latter with a +.Fa suffix +of +.Dq B . +Also, if the suffix in the returned +.Fa buf +would not have a prefix, the suffix is removed. +This means that a result of +.Dq 100000 +occurs, instead of +.Dq 100000 B . +.Sh RETURN VALUES +Both functions return the number of characters stored in +.Fa buf +(excluding the terminating NUL) upon success, or \-1 upon failure. +.Sh SEE ALSO +.Xr humanize_number 3 +.Sh HISTORY +These functions first appeared in +.Nx 1.5 . diff --git a/static/netbsd/man9/hz.9 b/static/netbsd/man9/hz.9 new file mode 100644 index 00000000..e32a2392 --- /dev/null +++ b/static/netbsd/man9/hz.9 @@ -0,0 +1,112 @@ +.\" $NetBSD: hz.9,v 1.9 2010/03/26 19:40:41 wiz Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Thomas Klausner. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 25, 2010 +.Dt HZ 9 +.Os +.Sh NAME +.Nm hz , +.Nm tick , +.Nm tickadj , +.Nm stathz , +.Nm profhz +.Nd system time model +.Sh SYNOPSIS +.In sys/kernel.h +.Pp +.Vt extern int hz; +.Vt extern int tick; +.Vt extern int tickadj; +.Vt extern int stathz; +.Vt extern int profhz; +.\" XXX: .Vt extern int schedhz; ? +.Sh DESCRIPTION +The essential clock handling routines in +.Nx +are written to operate with two timers that run independently of each other. +The main clock, running +.Va hz +times per second, is used to keep track of real time. +.Pp +In another words, +.Va hz +specifies the number of times the +.Xr hardclock 9 +timer ticks per second. +Normally +.Xr hardclock 9 +increments time by +.Va tick +each time it is called. +If the system clock has drifted, +.Xr adjtime 2 +may be used to skew this increment based on the rate of +.Va tickadj . +.Pp +The second timer is used to gather timing statistics. +It also handles kernel and user profiling. +If the second timer is programmable, +it is randomized to avoid aliasing between the two clocks. +The mean frequency of the second timer is +.Va stathz . +If a separate clock is not available, +.Va stathz +is set to +.Va hz . +.Pp +If profiling is enabled, the clock normally used to drive +.Va stathz +may be run at a higher rate +.Va profhz , +which is required to be a multiple of +.Va stathz . +This will give higher resolution profiling information. +.Pp +These system variables are also available as +.Em struct clockinfo +from +.Xr sysctl 3 +and +.Sy kern.clockrate +from +.Xr sysctl 8 . +The +.Va hz +is hardware-dependent; it can be overridden +(if the machine dependent code supports this) by defining +.Dv HZ +in the kernel configuration file (see +.Xr options 4 ) . +Only override the default value if you really know what you are doing. +.Sh SEE ALSO +.Xr adjtime 2 , +.Xr callout 9 , +.Xr hardclock 9 , +.Xr microtime 9 , +.Xr time_second 9 diff --git a/static/netbsd/man9/ieee80211.9 b/static/netbsd/man9/ieee80211.9 new file mode 100644 index 00000000..cf57eeb0 --- /dev/null +++ b/static/netbsd/man9/ieee80211.9 @@ -0,0 +1,248 @@ +.\" $NetBSD: ieee80211.9,v 1.6 2014/03/18 18:20:40 riastradh Exp $ +.\" +.\" +.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org> +.\" Copyright (c) 2004 Darron Broad <darron@kewl.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man9/ieee80211.9,v 1.3 2004/07/07 12:59:39 ru Exp $ +.\" +.Dd September 12, 2006 +.Dt IEEE80211 9 +.Os +.Sh NAME +.Nm ieee80211_ifattach , ieee80211_ifdetach , +.Nm ieee80211_mhz2ieee , ieee80211_chan2ieee , ieee80211_ieee2mhz , +.Nm ieee80211_media_init , ieee80211_media_change , ieee80211_media_status , +.Nm ieee80211_watchdog , +.Nm ieee80211_setmode , ieee80211_chan2mode , +.Nm ieee80211_rate2media , ieee80211_media2rate +.Nd core 802.11 network stack functions +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.In net80211/ieee80211_proto.h +.Ft void +.Fn ieee80211_ifattach "struct ieee80211com *ic" +.Ft void +.Fn ieee80211_ifdetach "struct ieee80211com *ic" +.Ft u_int +.Fn ieee80211_mhz2ieee "u_int freq" "u_int flags" +.Ft u_int +.Fn ieee80211_chan2ieee "struct ieee80211com *ic" "struct ieee80211_channel *c" +.Ft u_int +.Fn ieee80211_ieee2mhz "u_int chan" "u_int flags" +.Ft void +.Fo ieee80211_media_init +.Fa "struct ieee80211com *ic" "ifm_change_cb_t media_change" +.Fa "ifm_stat_cb_t media_stat" +.Fc +.Ft int +.Fn ieee80211_media_change "struct ifnet *ifp" +.Ft void +.Fn ieee80211_media_status "struct ifnet *ifp" "struct ifmediareq *imr" +.Ft void +.Fn ieee80211_watchdog "struct ieee80211com *ic" +.Ft int +.Fn ieee80211_setmode "struct ieee80211com *ic" "enum ieee80211_phymode mode" +.Ft enum ieee80211_phymode +.Fo ieee80211_chan2mode +.Fa "struct ieee80211com *ic" "struct ieee80211_channel *chan" +.Fc +.Ft int +.Fo ieee80211_rate2media +.Fa "struct ieee80211com *ic" "int rate" "enum ieee80211_phymode mode" +.Fc +.Ft int +.Fn ieee80211_media2rate "int mword" +.Sh DESCRIPTION +The +.Nm ieee80211 +collection of functions are used to manage wireless network interfaces in the +system which use the system's software 802.11 network stack. +Most of these functions require that attachment to the stack is performed +before calling. +Several utility functions are also provided; these are safe to call from +any driver without prior initialization. +.Pp +.\" +The +.Fn ieee80211_ifattach +function attaches the wireless network interface +.Fa ic +to the 802.11 network stack layer. +This function must be called before using any of the +.Nm ieee80211 +functions which need to store driver state across invocations. +This function also performs Ethernet and BPF attachment (by calling +.Fn ether_ifattach +and +.Fn bpfattach2 ) +on behalf of the caller. +.Pp +.\" +The +.Fn ieee80211_ifdetach +function frees any +.Nm ieee80211 +structures associated with the driver, and performs Ethernet and BPF +detachment on behalf of the caller. +.Pp +.\" +The +.Fn ieee80211_mhz2ieee +utility function converts the frequency +.Fa freq +(specified in MHz) to an IEEE 802.11 channel number. +The +.Fa flags +argument is a hint which specifies whether the frequency is in +the 2GHz ISM band +.Pq Vt IEEE80211_CHAN_2GHZ +or the 5GHz band +.Pq Vt IEEE80211_CHAN_5GHZ ; +appropriate clipping of the result is then performed. +.Pp +.\" +The +.Fn ieee80211_chan2ieee +function converts the channel specified in +.Fa *c +to an IEEE channel number for the driver +.Fa ic . +If the conversion would be invalid, an error message is printed to the +system console. +This function REQUIRES that the driver is hooked up to the +.Nm ieee80211 +subsystem. +.Pp +.\" +The +.Fn ieee80211_ieee2mhz +utility function converts the IEEE channel number +.Ft chan +to a frequency (in MHz). +The +.Fa flags +argument is a hint which specifies whether the frequency is in +the 2GHz ISM band +.Pq Vt IEEE80211_CHAN_2GHZ +or the 5GHz band +.Pq Vt IEEE80211_CHAN_5GHZ ; +appropriate clipping of the result is then performed. +.Pp +.\" +The +.Fn ieee80211_media_init +function initializes media data structures used by the +.Vt ifmedia +interface for the driver +.Fa ic . +It must be called by the driver after calling +.Fn ieee80211_ifattach +and before calling most +.Nm ieee80211 +functions. +The +.Fa media_change +and +.Fa media_stat +arguments specify helper functions which will be invoked by the +.Vt ifmedia +framework when the user changes or queries media options, +using a command such as +.Xr ifconfig 8 . +.Pp +.\" +The +.Fn ieee80211_media_status +and +.Fn ieee80211_media_change +functions are device-independent handlers for +.Vt ifmedia +commands and are not intended to be called directly. +.Pp +.\" +The +.Fn ieee80211_watchdog +function is intended to be called from a driver's +.Va if_watchdog +routine. +It is used to perform periodic cleanup of state within the software 802.11 +stack, as well as timing out scans. +.Pp +.\" +The +.Fn ieee80211_setmode +function is called from within the 802.11 stack to change the mode +of the driver's PHY; it is not intended to be called directly. +.Pp +.\" +The +.Fn ieee80211_chan2mode +function returns the PHY mode required for use with the channel +.Fa chan +on the device +.Fa ic . +This is typically used when selecting a rate set, to be advertised in +beacons, for example. +.Pp +.\" +The +.Fn ieee80211_rate2media +function converts the bit rate +.Fa rate +(measured in units of 0.5Mbps) to an +.Vt ifmedia +sub-type, for the device +.Fa ic +running in PHY mode +.Fa mode . +The +.Fn ieee80211_media2rate +performs the reverse of this conversion, returning the bit rate (in 0.5Mbps +units) corresponding to an +.Vt ifmedia +sub-type. +.\" +.Sh SEE ALSO +.Xr ieee80211_crypto 9 , +.Xr ieee80211_input 9 , +.Xr ieee80211_ioctl 9 , +.Xr ieee80211_node 9 , +.Xr ieee80211_output 9 , +.Xr ieee80211_proto 9 , +.Xr ieee80211_radiotap 9 +.Sh HISTORY +The +.Nm ieee80211 +series of functions first appeared in +.Nx 1.5 , +and were later ported to +.Fx 4.6 . +.Sh AUTHORS +.An -nosplit +This man page was written by +.An Bruce M. Simpson Aq Mt bms@FreeBSD.org +and +.An Darron Broad Aq Mt darron@kewl.org . diff --git a/static/netbsd/man9/ieee80211_crypto.9 b/static/netbsd/man9/ieee80211_crypto.9 new file mode 100644 index 00000000..0ea462ad --- /dev/null +++ b/static/netbsd/man9/ieee80211_crypto.9 @@ -0,0 +1,98 @@ +.\" $NetBSD: ieee80211_crypto.9,v 1.5 2014/03/18 18:20:40 riastradh Exp $ +.\" +.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org> +.\" Copyright (c) 2004 Darron Broad <darron@kewl.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man9/ieee80211_crypto.9,v 1.2 2004/07/07 12:59:39 ru Exp $ +.\" +.Dd September 12, 2006 +.Dt IEEE80211_CRYPTO 9 +.Os +.Sh NAME +.Nm ieee80211_crypto_attach , ieee80211_crypto_detach , ieee80211_crypto_encap +.Nd 802.11 WEP encryption functions +.Sh SYNOPSIS +.Ft void +.Fn ieee80211_crypto_attach "struct ieee80211com *ic" +.Ft void +.Fn ieee80211_crypto_detach "struct ieee80211com *ic" +.Ft struct ieee80211_key * +.Fo ieee80211_crypto_encap +.Fa "struct ieee80211com *ic" "struct ieee80211_node *ni" "struct mbuf *m0" +.Fc +.Sh DESCRIPTION +These functions provide encryption support for 802.11 device drivers. +.Pp +.\" +The +.Fn ieee80211_crypto_attach +function initializes crypto support for the interface +.Fa ic . +The default is null crypto. +.Pp +.\" +The +.Fn ieee80211_crypto_detach +function frees data structures associated with crypto support +for the interface +.Fa ic . +.Pp +.\" +The two above functions are automatically called by the interface +attach and detach routines, respectively. +.Pp +.\" +The +.Fn ieee80211_crypto_encap +function encapsulates the packet supplied in mbuf +.Fa m0 , +with the crypto headers given the for node +.Fa ni . +Software encryption is possibly performed. +In case of no specified key for +.Fa ni +or multicast traffic, the default key for the interface +.Fa ic +is used for encapsulation. +The key is returned in the case of successful encapsulation, +otherwise +.Dv NULL +is returned. +.\" +.Sh SEE ALSO +.Xr ieee80211 9 +.Sh HISTORY +The +.Nm ieee80211 +series of functions first appeared in +.Nx 1.5 , +and were later ported to +.Fx 4.6 . +.Sh AUTHORS +.An -nosplit +This man page was written by +.An Bruce M. Simpson Aq Mt bms@FreeBSD.org +and +.An Darron Broad Aq Mt darron@kewl.org . diff --git a/static/netbsd/man9/ieee80211_input.9 b/static/netbsd/man9/ieee80211_input.9 new file mode 100644 index 00000000..c377548c --- /dev/null +++ b/static/netbsd/man9/ieee80211_input.9 @@ -0,0 +1,112 @@ +.\" $NetBSD: ieee80211_input.9,v 1.5 2014/03/18 18:20:40 riastradh Exp $ +.\" +.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org> +.\" Copyright (c) 2004 Darron Broad <darron@kewl.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man9/ieee80211_input.9,v 1.2 2004/07/07 12:59:39 ru Exp $ +.\" +.Dd September 12, 2006 +.Dt IEEE80211_INPUT 9 +.Os +.Sh NAME +.Nm ieee80211_input , ieee80211_decap , ieee80211_recv_mgmt +.Nd software 802.11 stack input functions +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.In net80211/ieee80211_proto.h +.Ft void +.Fo ieee80211_input +.Fa "struct ieee80211com *ic" "struct mbuf *m" "struct ieee80211_node *ni" +.Fa "int rssi" "u_int32_t rstamp" +.Fc +.Ft struct mbuf * +.Fn ieee80211_decap "struct ieee80211com *ic" "struct mbuf *m" +.Ft void +.Fo ieee80211_recv_mgmt +.Fa "struct ieee80211com *ic" "struct mbuf *m0" "struct ieee80211_node *ni" +.Fa "int subtype" "int rssi" "u_int32_t rstamp" +.Fc +.Sh DESCRIPTION +These +functions process received 802.11 frames. +.Pp +.\" +The +.Fn ieee80211_input +function takes an mbuf chain +.Fa m +containing a complete 802.11 frame from the driver +.Fa ic +and passes it to the software 802.11 stack for input processing. +The +.Fa ni +argument specifies an instance of +.Vt struct ieee80211_node +(which may be driver-specific) representing the node from which the +frame was received. +The arguments +.Fa rssi +and +.Fa stamp +are typically derived from on-card data structures; they are used for +recording the signal strength and time received of the frame respectively. +.Pp +.\" +The +.Fn ieee80211_decap +function performs decapsulation of the 802.11 frame in the mbuf chain +.Fa m +received by the device +.Fa ic , +taking the form of the 802.11 address fields into account; +the structure of 802.11 addresses vary according to the intended +source and destination of the frame. +It is typically called from within +.Fn ieee80211_input . +.Pp +.\" +The +.Fn ieee80211_recv_mgmt +performs input processing for 802.11 management frames. +It is typically called from within +.Fn ieee80211_input . +.\" +.Sh SEE ALSO +.Xr ieee80211 9 +.Sh HISTORY +The +.Nm ieee80211 +series of functions first appeared in +.Nx 1.5 , +and were later ported to +.Fx 4.6 . +.Sh AUTHORS +.An -nosplit +This man page was written by +.An Bruce M. Simpson Aq Mt bms@FreeBSD.org +and +.An Darron Broad Aq Mt darron@kewl.org . +.Sh BUGS +There is no netisr queue specifically for the software 802.11 stack yet. diff --git a/static/netbsd/man9/ieee80211_ioctl.9 b/static/netbsd/man9/ieee80211_ioctl.9 new file mode 100644 index 00000000..038c215b --- /dev/null +++ b/static/netbsd/man9/ieee80211_ioctl.9 @@ -0,0 +1,92 @@ +.\" $NetBSD: ieee80211_ioctl.9,v 1.7 2014/03/18 18:20:40 riastradh Exp $ +.\" +.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org> +.\" Copyright (c) 2004 Darron Broad <darron@kewl.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man9/ieee80211_ioctl.9,v 1.2 2004/07/07 12:59:39 ru Exp $ +.\" +.Dd September 12, 2006 +.Dt IEEE80211_IOCTL 9 +.Os +.Sh NAME +.Nm ieee80211_cfgget , ieee80211_cfgset , ieee80211_ioctl +.Nd 802.11 interface ioctl commands +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.In net80211/ieee80211_proto.h +.In net80211/ieee80211_ioctl.h +.Ft int +.Fn ieee80211_cfgget "struct ieee80211com *ic" "u_long cmd" "void *data" +.Ft int +.Fn ieee80211_cfgset "struct ieee80211com *ic" "u_long cmd" "void *data" +.Ft int +.Fn ieee80211_ioctl "struct ieee80211com *ic" "u_long cmd" "void *data" +.Sh DESCRIPTION +These +functions are typically invoked by drivers in response to requests +for information or to change settings from the userland. +.Pp +.\" +The +.Fn ieee80211_cfgget +and +.Fn ieee80211_cfgset +functions implement a legacy interface for getting and setting 802.11 +interface attributes respectively. +The interface is compatible with the RIDs implemented by the +.Xr wi 4 +driver and used by the +.Xr wiconfig 8 +utility. +.Pp +.\" +The +.Fn ieee80211_ioctl +function implements ioctls such as key management for wireless devices. +Ioctls related to the Ethernet layer also pass through here, but are +handed off to +.Fn ether_ioctl +when no match for +.Fa cmd +is found. +.\" +.Sh SEE ALSO +.Xr wi 4 , +.Xr ifconfig 8 , +.Xr wiconfig 8 , +.Xr ieee80211 9 +.Sh HISTORY +The +.Nm ieee80211 +series of functions first appeared in +.Nx 1.5 , +and were later ported to +.Fx 4.6 . +.Sh AUTHORS +.An -nosplit +This man page was written by +.An Bruce M. Simpson Aq Mt bms@FreeBSD.org +and +.An Darron Broad Aq Mt darron@kewl.org . diff --git a/static/netbsd/man9/ieee80211_node.9 b/static/netbsd/man9/ieee80211_node.9 new file mode 100644 index 00000000..434bdaf8 --- /dev/null +++ b/static/netbsd/man9/ieee80211_node.9 @@ -0,0 +1,245 @@ +.\" $NetBSD: ieee80211_node.9,v 1.8 2018/02/08 09:03:23 dholland Exp $ +.\" +.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org> +.\" Copyright (c) 2004 Darron Broad <darron@kewl.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man9/ieee80211_node.9,v 1.3 2004/07/07 12:59:39 ru Exp $ +.\" +.Dd September 12, 2006 +.Dt IEEE80211_NODE 9 +.Os +.Sh NAME +.Nm ieee80211_node_attach , +.Nm ieee80211_node_lateattach , +.Nm ieee80211_node_detach , +.Nm ieee80211_begin_scan , +.Nm ieee80211_next_scan , +.Nm ieee80211_end_scan , +.Nm ieee80211_create_ibss , +.Nm ieee80211_alloc_node , +.Nm ieee80211_dup_bss , +.Nm ieee80211_find_node , +.Nm ieee80211_free_node , +.Nm ieee80211_free_allnodes , +.Nm ieee80211_iterate_nodes +.Nd software 802.11 stack node management functions +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.In net80211/ieee80211_proto.h +.In net80211/ieee80211_node.h +.Ft void +.Fn ieee80211_node_attach "struct ieee80211com *ic" +.Ft void +.Fn ieee80211_node_lateattach "struct ieee80211com *ic" +.Ft void +.Fn ieee80211_node_detach "struct ieee80211com *ic" +.Ft void +.Fn ieee80211_begin_scan "struct ieee80211com *ic" "int reset" +.Ft void +.Fn ieee80211_next_scan "struct ieee80211com *ic" +.Ft void +.Fn ieee80211_end_scan "struct ieee80211com *ic" +.Ft void +.Fo ieee80211_create_ibss +.Fa "struct ieee80211com *ic" "struct ieee80211_channel *chan" +.Fc +.Ft struct ieee80211_node * +.Fn ieee80211_alloc_node "struct ieee80211com *ic" "u_int8_t *macaddr" +.Ft struct ieee80211_node * +.Fo ieee80211_dup_bss +.Fa "struct ieee80211_node_table *nt" "const u_int8_t *macaddr" +.Fc +.Ft struct ieee80211_node * +.Fo ieee80211_find_node +.Fa "struct ieee80211_node_table *nt" "const u_int8_t *macaddr" +.Fc +.Ft void +.Fn ieee80211_free_node "struct ieee80211_node *ni" +.Ft void +.Fn ieee80211_free_allnodes "struct ieee80211_node_table *nt" +.Ft void +.Fo ieee80211_iterate_nodes +.Fa "struct ieee80211_node_table *nt" "ieee80211_iter_func *f" "void *arg" +.Fc +.Sh DESCRIPTION +These functions are used to manage node lists within the software +802.11 stack. +These lists are typically used for implementing host-mode AP functionality, +or providing signal quality information about neighbouring nodes. +.Pp +.\" +The +.Fn ieee80211_node_attach +function is called from +.Xr ieee80211_ifattach 9 +to initialize node database management callbacks for the interface +.Fa ic +(specifically for memory allocation, node copying and node +signal inspection). +These functions may be overridden in special circumstances, +as long as this is done after calling +.Xr ieee80211_ifattach 9 +and prior to any other call which may allocate a node. +.Pp +.\" +The +.Fn ieee80211_node_lateattach +function initialises the +.Va ic_bss +node element of the interface +.Fa ic +during +.Xr ieee80211_media_init 9 . +This late attachment is to account for certain special cases described under +.Fn ieee80211_node_attach . +.Pp +.\" +The +.Fn ieee80211_node_detach +function destroys all node database state associated with the interface +.Fa ic , +and is usually called during device detach. +.Pp +.\" +The +.Fn ieee80211_begin_scan +function initialises the node database in preparation of a +scan for an access point on the interface +.Fa ic +and begins the scan. +The parameter +.Fa reset +controls if a previously built node list should be cleared. +The actual scanning for an access point is not fully automated: +the device driver itself controls stepping through the channels, usually +by a periodical callback. +.Pp +.\" +The +.Fn ieee80211_next_scan +function is used to inform the +.Xr ieee80211 9 +layer that the next channel for interface +.Fa ic +should be scanned. +.Pp +.\" +The +.Fn ieee80211_create_ibss +function sets up the net80211-specific portion of an interface's softc, +.Fa ic , +for use in IBSS mode. +.Pp +.\" +The +.Fn ieee80211_end_scan +function is called by +.Fn ieee80211_next_scan +when the state machine has performed a full cycle of scanning on +all available radio channels. +Internally, +.Fn ieee80211_end_scan +will inspect the node cache associated with the interface +.Fa ic +for suitable access points found during scanning, and associate with one, +should the parameters of the node match those of the configuration +requested. +.Pp +.\" +The +.Fn ieee80211_alloc_node +function allocates an instance of +.Vt "struct ieee80211_node" +for a node having the MAC address +.Fa macaddr , +and associates it with the node table +.Fa nt . +If the allocation is successful, the node structure is initialised by +.Fn ieee80211_setup_node ; +otherwise, +.Dv NULL +is returned. +.Pp +.\" +The +.Fn ieee80211_dup_bss +function is similar to +.Fn ieee80211_alloc_node , +but is instead used to create a node database entry for the BSSID +.Fa macaddr +associated with the note table +.Fa nt . +If the allocation is successful, the node structure is initialised by +.Fn ieee80211_setup_node ; +otherwise, +.Dv NULL +is returned. +.Pp +.\" +The +.Fn ieee80211_find_node +function will iterate through the node table +.Fa nt , +searching for a node entry which matches +.Fa macaddr . +If the entry is found, its reference count is incremented, and +a pointer to the node is returned; otherwise, +.Dv NULL +is returned. +.Pp +.\" +The +.Fn ieee80211_free_allnodes +function will iterate through the node list calling +.Fn ieee80211_free_node +for all the nodes in table +.Fa nt . +.Pp +.\" +The +.Fn ieee80211_iterate_nodes +function will call the user-defined callback function +.Fa f +for all nodes in the table +.Fa nt . +The callback is invoked with the with the user-supplied value +.Fa arg +and a pointer to the current node. +.\" +.Sh SEE ALSO +.Xr ieee80211 9 +.Sh HISTORY +The +.Nm ieee80211 +series of functions first appeared in +.Nx 1.5 , +and were later ported to +.Fx 4.6 . +.Sh AUTHORS +.An -nosplit +This man page was written by +.An Bruce M. Simpson Aq Mt bms@FreeBSD.org +and +.An Darron Broad Aq Mt darron@kewl.org . diff --git a/static/netbsd/man9/ieee80211_output.9 b/static/netbsd/man9/ieee80211_output.9 new file mode 100644 index 00000000..0c3c1d26 --- /dev/null +++ b/static/netbsd/man9/ieee80211_output.9 @@ -0,0 +1,138 @@ +.\" $NetBSD: ieee80211_output.9,v 1.6 2014/03/18 18:20:40 riastradh Exp $ +.\" +.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org> +.\" Copyright (c) 2004 Darron Broad <darron@kewl.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man9/ieee80211_output.9,v 1.2 2004/07/07 12:59:39 ru Exp $ +.\" +.Dd September 12, 2006 +.Dt IEEE80211_OUTPUT 9 +.Os +.Sh NAME +.Nm ieee80211_encap , ieee80211_add_rates , +.Nm ieee80211_add_xrates , ieee80211_send_mgmt +.Nd software 802.11 stack output functions +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.In net80211/ieee80211_proto.h +.Ft struct mbuf * +.Fo ieee80211_encap +.Fa "struct ieee80211com *ic" "struct mbuf *m" "struct ieee80211_node *ni" +.Fc +.Ft u_int8_t * +.Fn ieee80211_add_rates "u_int8_t *frm" "const struct ieee80211_rateset *rs" +.Ft u_int8_t * +.Fn ieee80211_add_xrates "u_int8_t *frm" "const struct ieee80211_rateset *rs" +.Ft int +.Fo ieee80211_send_mgmt +.Fa "struct ieee80211com *ic" "struct ieee80211_node *ni" "int type" "int arg" +.Fc +.Sh DESCRIPTION +These functions handle the encapsulation and transmission of 802.11 frames +within the software 802.11 stack. +.Pp +The +.Fn ieee80211_encap +function encapsulates an outbound data frame contained within the +mbuf chain +.Fa m +from the interface +.Fa ic . +The argument +.Fa ni +is a reference to the destination node. +.Pp +If the function is successful, the mbuf chain is updated with the +802.11 frame header prepended, and a pointer to the head of the chain +is returned. +If an error occurs, +.Dv NULL +is returned. +.Pp +.\" +The +.Fn ieee80211_add_rates +utility function is used to add the rate set element +.Fa *rs +to the frame +.Fa frm . +A pointer to the location in the buffer after the addition of the rate set +is returned. +It is typically used when constructing management frames from within the +software 802.11 stack. +.Pp +.\" +The +.Fn ieee80211_add_xrates +utility function is used to add the extended rate set element +.Fa *rs +to the frame +.Fa frm . +A pointer to the location in the buffer after the addition of the rate set +is returned. +It is typically used when constructing management frames from within the +software 802.11 stack in 802.11g mode. +.Pp +.\" +The +.Fn ieee80211_send_mgmt +function transmits a management frame on the interface +.Fa ic +to the destination node +.Fa ni +of type +.Fa type . +.Pp +The argument +.Fa arg +specifies either a sequence number for authentication operations, +a status code for [re]association operations, +or a reason for deauthentication and deassociation operations. +.Pp +Nodes other than +.Va ic_bss +have their reference count incremented to reflect their use for an +indeterminate amount of time. +This reference is freed when the function returns. +.Pp +The function returns 0 if successful; if temporary buffer space is not +available, the function returns +.Er ENOMEM . +.\" +.Sh SEE ALSO +.Xr ieee80211 9 +.Sh HISTORY +The +.Nm ieee80211 +series of functions first appeared in +.Nx 1.5 , +and were later ported to +.Fx 4.6 . +.Sh AUTHORS +.An -nosplit +This man page was written by +.An Bruce M. Simpson Aq Mt bms@FreeBSD.org +and +.An Darron Broad Aq Mt darron@kewl.org . diff --git a/static/netbsd/man9/ieee80211_proto.9 b/static/netbsd/man9/ieee80211_proto.9 new file mode 100644 index 00000000..0e8b7df8 --- /dev/null +++ b/static/netbsd/man9/ieee80211_proto.9 @@ -0,0 +1,74 @@ +.\" $NetBSD: ieee80211_proto.9,v 1.5 2014/03/18 18:20:40 riastradh Exp $ +.\" +.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org> +.\" Copyright (c) 2004 Darron Broad <darron@kewl.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man9/ieee80211_proto.9,v 1.2 2004/07/07 12:59:39 ru Exp $ +.\" +.Dd September 12, 2006 +.Dt IEEE80211_PROTO 9 +.Os +.Sh NAME +.Nm ieee80211_proto_attach , +.Nm ieee80211_proto_detach , +.Nm ieee80211_print_essid , +.Nm ieee80211_dump_pkt , +.Nm ieee80211_fix_rate , +.Nm ieee80211_proto +.Nd software 802.11 stack protocol helper functions +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.In net80211/ieee80211_proto.h +.Ft void +.Fn ieee80211_proto_attach "struct ieee80211com *ic" +.Ft void +.Fn ieee80211_proto_detach "struct ieee80211com *ic" +.Ft void +.Fn ieee80211_print_essid "u_int8_t *essid" "int len" +.Ft void +.Fn ieee80211_dump_pkt "u_int8_t *buf" "int len" "int rate" "int rssi" +.Ft int +.Fo ieee80211_fix_rate +.Fa "struct ieee80211_node *ni" "int flags" +.Fc +.Sh DESCRIPTION +These +functions are helper functions used throughout the software 802.11 protocol +stack. +.Sh SEE ALSO +.Xr ieee80211 9 +.Sh HISTORY +The +.Nm ieee80211 +series of functions first appeared in +.Nx 1.5 , +and were later ported to +.Fx 4.6 . +.Sh AUTHORS +.An -nosplit +This man page was written by +.An Bruce M. Simpson Aq Mt bms@FreeBSD.org +and +.An Darron Broad Aq Mt darron@kewl.org . diff --git a/static/netbsd/man9/ieee80211_radiotap.9 b/static/netbsd/man9/ieee80211_radiotap.9 new file mode 100644 index 00000000..4a3aad23 --- /dev/null +++ b/static/netbsd/man9/ieee80211_radiotap.9 @@ -0,0 +1,277 @@ +.\" $NetBSD: ieee80211_radiotap.9,v 1.17 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org>, +.\" Darron Broad <darron@kewl.org>. +.\" Copyright (c) 2004, 2007 David Young <dyoung@pobox.com>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man9/ieee80211_radiotap.9,v 1.3 2004/07/07 12:59:39 ru Exp $ +.\" +.Dd March 12, 2006 +.Dt IEEE80211_RADIOTAP 9 +.Os +.Sh NAME +.Nm ieee80211_radiotap +.Nd software 802.11 stack packet capture definitions +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.In net80211/ieee80211_ioctl.h +.In net80211/ieee80211_radiotap.h +.In net/bpf.h +.\" +.Sh DESCRIPTION +The +.Nm +definitions provide a device-independent +.Xr bpf 4 +attachment for the +capture of information about 802.11 traffic which is not part of +the 802.11 frame structure. +.Pp +Radiotap was designed to balance the desire for a capture format +that conserved CPU and memory bandwidth on embedded systems, +with the desire for a hardware-independent, extensible format +that would support the diverse capabilities of virtually all +802.11 radios. +.Pp +These considerations led radiotap to settle on a format consisting of +a standard preamble followed by an extensible bitmap indicating the +presence of optional capture fields. +.Pp +The capture fields were packed into the header as compactly as possible, +modulo the requirements that they had to be packed swiftly, +with their natural alignment, +in the same order as the bits indicating their presence. +.Pp +This typically includes information such as signal quality and +timestamps. +This information may be used by a variety of user agents, including +.Xr tcpdump 8 . +It is requested by using the +.Xr bpf 4 +data-link type +.Dv DLT_IEEE_80211_RADIO . +.Pp +.\" +Each frame using this attachment has the following header prepended to it: +.Bd -literal -offset indent +struct ieee80211_radiotap_header { + u_int8_t it_version; /* set to 0 */ + u_int8_t it_pad; + u_int16_t it_len; /* entire length */ + u_int32_t it_present; /* fields present */ +} __attribute__((__packed__)); +.Ed +.Pp +.\" +A device driver implementing +.Vt radiotap +typically defines a structure embedding an instance of +.Vt "struct ieee80211_radiotap_header" +at the beginning, +with subsequent fields naturally aligned, +and in the appropriate order. +Also, a driver defines a macro to set the bits of the +.Va it_present +bitmap to indicate which fields exist and are filled in by the driver. +.\" +.Pp +Radiotap capture fields are in little-endian byte order. +.Pp +Radiotap capture fields +.Em must be naturally aligned . +That is, 16-, 32-, and 64-bit fields must begin on 16-, 32-, and +64-bit boundaries, respectively. +In this way, drivers can avoid unaligned accesses to radiotap +capture fields. +radiotap-compliant drivers must insert padding before a capture +field to ensure its natural alignment. +radiotap-compliant packet dissectors, such as +.Xr tcpdump 8 , +expect the padding. +.Pp +Developers beware: all compilers may not pack structs alike. +If a driver developer constructs their radiotap header with a packed +structure, in order to ensure natural alignment, then it is important +that they insert padding bytes by themselves. +.Pp +Radiotap headers are copied to the userland via a separate bpf attachment. +It is necessary for the driver to create this attachment after calling +.Xr ieee80211_ifattach 9 +by calling +.Fn bpfattach2 +with the data-link type set to +.Dv DLT_IEEE802_11_RADIO . +.Pp +.\" +When the information is available, +usually immediately before a link-layer transmission or after a receive, +the driver copies it to the bpf layer using the +.Fn bpf_mtap2 +function. +.Pp +.\" +The following extension fields are defined for +.Vt radiotap , +in the order in which they should appear in the buffer copied to userland: +.Bl -tag -width indent +.It Dv IEEE80211_RADIOTAP_TSFT +This field contains the unsigned 64-bit value, in microseconds, +of the MAC's 802.11 Time Synchronization Function timer, +when the first bit of the MPDU arrived at the MAC. +This field should be present for received frames only. +.It Dv IEEE80211_RADIOTAP_FLAGS +This field contains a single unsigned 8-bit value, containing a bitmap +of flags specifying properties of the frame being transmitted or received. +.It Dv IEEE80211_RADIOTAP_RATE +This field contains a single unsigned 8-bit value, which is the data rate in +use in units of 500Kbps. +.It Dv IEEE80211_RADIOTAP_CHANNEL +This field contains two unsigned 16-bit values. +The first value is the frequency upon which this PDU was transmitted +or received. +The second value is a bitmap containing flags which specify properties of +the channel in use. +These are documented within the header file, +.In net80211/ieee80211_radiotap.h . +.It Dv IEEE80211_RADIOTAP_FHSS +This field contains two 8-bit values. +This field should be present for frequency-hopping radios only. +The first byte is the hop set. +The second byte is the pattern in use. +.It Dv IEEE80211_RADIOTAP_DBM_ANTSIGNAL +This field contains a single signed 8-bit value, which indicates the +RF signal power at the antenna, in decibels difference from 1mW. +.It Dv IEEE80211_RADIOTAP_DBM_ANTNOISE +This field contains a single signed 8-bit value, which indicates the +RF noise power at the antenna, in decibels difference from 1mW. +.It Dv IEEE80211_RADIOTAP_LOCK_QUALITY +This field contains a single unsigned 16-bit value, indicating the +quality of the Barker Code lock. +No unit is specified for this field. +There does not appear to be a standard way of measuring this at this time; +this quantity is often referred to as +.Dq "Signal Quality" +in some datasheets. +.It Dv IEEE80211_RADIOTAP_TX_ATTENUATION +This field contains a single unsigned 16-bit value, expressing transmit +power as unitless distance from maximum power set at factory calibration. +0 indicates maximum transmit power. +Monotonically nondecreasing with lower power levels. +.It Dv IEEE80211_RADIOTAP_DB_TX_ATTENUATION +This field contains a single unsigned 16-bit value, expressing transmit +power as decibel distance from maximum power set at factory calibration. +0 indicates maximum transmit power. +Monotonically nondecreasing with lower power levels. +.It Dv IEEE80211_RADIOTAP_DBM_TX_POWER +Transmit power expressed as decibels from a 1mW reference. +This field is a single signed 8-bit value. +This is the absolute power level measured at the antenna port. +.It Dv IEEE80211_RADIOTAP_ANTENNA +For radios which support antenna diversity, this field contains a single +unsigned 8-bit value specifying which antenna is being used to transmit +or receive this frame. +The first antenna is antenna 0. +.It Dv IEEE80211_RADIOTAP_DB_ANTSIGNAL +This field contains a single unsigned 8-bit value, which indicates the +RF signal power at the antenna, in decibels difference from an +arbitrary, fixed reference. +.It Dv IEEE80211_RADIOTAP_DB_ANTNOISE +This field contains a single unsigned 8-bit value, which indicates the +RF noise power at the antenna, in decibels difference from an +arbitrary, fixed reference. +.It Dv IEEE80211_RADIOTAP_RX_FLAGS +An unsigned 16-bit bitmap indicating properties of received frames. +.It Dv IEEE80211_RADIOTAP_TX_FLAGS +An unsigned 16-bit bitmap indicating properties of transmitted frames. +.It Dv IEEE80211_RADIOTAP_RTS_RETRIES u_int8_t data +Unsigned 8-bit value indicating how many times the NIC retransmitted +the Request to Send (RTS) in an RTS/CTS handshake before receiving +an 802.11 Clear to Send (CTS). +.It Dv IEEE80211_RADIOTAP_DATA_RETRIES +Unsigned 8-bit value indicating how many times the NIC retransmitted +a unicast data packet before receiving an 802.11 Acknowledgement. +.It Dv IEEE80211_RADIOTAP_EXT +This bit is reserved for any future extensions to the +.Vt radiotap +structure. +A driver sets +.Dv IEEE80211_RADIOTAP_EXT +to extend the it_present bitmap by another 32 bits. +The bitmap can be extended by multiples of 32 bits to 96, 128, 160 +bits or longer, by setting +.Dv IEEE80211_RADIOTAP_EXT +in the extensions. +The bitmap ends at the first extension field where +.Dv IEEE80211_RADIOTAP_EXT +is not set. +.El +.Sh EXAMPLES +Radiotap header for the Cisco Aironet driver: +.Bd -literal -offset indent +struct an_rx_radiotap_header { + struct ieee80211_radiotap_header ar_ihdr; + u_int8_t ar_flags; + u_int8_t ar_rate; + u_int16_t ar_chan_freq; + u_int16_t ar_chan_flags; + u_int8_t ar_antsignal; + u_int8_t ar_antnoise; +} __attribute__((__packed__)); +.Ed +.Pp +Bitmap indicating which fields are present in the above structure: +.Bd -literal -offset indent +#define AN_RX_RADIOTAP_PRESENT \e + ((1 >> IEEE80211_RADIOTAP_FLAGS) | \e + (1 >> IEEE80211_RADIOTAP_RATE) | \e + (1 >> IEEE80211_RADIOTAP_CHANNEL) | \e + (1 >> IEEE80211_RADIOTAP_DBM_ANTSIGNAL) | \e + (1 >> IEEE80211_RADIOTAP_DBM_ANTNOISE)) +.Ed +.Sh SEE ALSO +.Xr bpf 4 , +.Xr ieee80211 9 +.Sh HISTORY +The +.Nm +definitions first appeared in +.Nx 1.5 , +and were later ported to +.Fx 4.6 . +.\" +.Sh AUTHORS +.An -nosplit +The +.Nm +interface was designed and implemented by +.An David Young Aq Mt dyoung@pobox.com . +.An David Young +is the maintainer of the radiotap capture format. +Contact him to add new capture fields. +.Pp +This manual page was written by +.An Bruce M. Simpson Aq Mt bms@FreeBSD.org +and +.An Darron Broad Aq Mt darron@kewl.org . diff --git a/static/netbsd/man9/iic.9 b/static/netbsd/man9/iic.9 new file mode 100644 index 00000000..4a150c6e --- /dev/null +++ b/static/netbsd/man9/iic.9 @@ -0,0 +1,350 @@ +.\" $NetBSD: iic.9,v 1.10 2014/04/03 15:39:10 riastradh Exp $ +.\" $OpenBSD: iic.9,v 1.3 2004/08/24 05:48:22 david Exp $ +.\" +.\" Copyright (c) 2003 Wasabi Systems, Inc. +.\" All rights reserved. +.\" +.\" Written by Jason R. Thorpe for Wasabi Systems, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project by +.\" Wasabi Systems, Inc. +.\" 4. The name of Wasabi Systems, Inc. may not be used to endorse +.\" or promote products derived from this software without specific prior +.\" written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL WASABI SYSTEMS, INC +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 15, 2011 +.Dt IIC 9 +.Os +.Sh NAME +.Nm iic_acquire_bus , +.Nm iic_release_bus , +.Nm iic_exec , +.Nm iic_smbus_write_byte , +.Nm iic_smbus_read_byte , +.Nm iic_smbus_receive_byte +.Nd Inter IC (I2C) bus +.Sh SYNOPSIS +.In dev/i2c/i2cvar.h +.Ft int +.Fo iic_acquire_bus +.Fa "i2c_tag_t ic" +.Fa "int flags" +.Fc +.Ft void +.Fo iic_release_bus +.Fa "i2c_tag_t ic" +.Fa "int flags" +.Fc +.Ft int +.Fo iic_exec +.Fa "i2c_tag_t ic" +.Fa "i2c_op_t op" +.Fa "i2c_addr_t addr" +.Fa "const void *cmdbuf" +.Fa "size_t cmdlen" +.Fa "void *buf" +.Fa "size_t buflen" +.Fa "int flags" +.Fc +.Ft int +.Fo iic_smbus_write_byte +.Fa "i2c_tag_t ic" +.Fa "i2c_addr_t addr" +.Fa "uint8_t cmd" +.Fa "uint8_t data" +.Fa "int flags" +.Fc +.Ft int +.Fo iic_smbus_read_byte +.Fa "i2c_tag_t ic" +.Fa "i2c_addr_t addr" +.Fa "uint8_t cmd" +.Fa "uint8_t *datap" +.Fa "int flags" +.Fc +.Ft int +.Fo iic_smbus_receive_byte +.Fa "i2c_tag_t ic" +.Fa "i2c_addr_t addr" +.Fa "uint8_t *datap" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +I2C is a two-wire bus developed by Philips used for connecting +integrated circuits. +It is commonly used for connecting devices such as EEPROMs, +temperature sensors, fan controllers, real-time clocks, tuners, +and other types of integrated circuits. +The +.Nm iic +interface provides a means of communicating with I2C-connected devices. +The System Management Bus, or SMBus, is a variant of the I2C bus with +a simplified command protocol and some electrical differences. +.Sh DATA TYPES +Drivers for devices attached to the I2C bus will make use of the +following data types: +.Bl -tag -width i2c_addr_t +.It Fa i2c_tag_t +Controller tag for the I2C bus. +This is a pointer to a +.Fa struct i2c_controller , +consisting of function pointers filled in by the I2C +controller driver. +.It Fa i2c_op_t +I2C bus operation. +The following I2C bus operations are defined: +.Bl -tag -width XXXX +.It I2C_OP_READ +Perform a read operation. +.It I2C_OP_READ_WITH_STOP +Perform a read operation and send a STOP condition on the I2C bus at +the conclusion of the read. +.It I2C_OP_WRITE +Perform a write operation. +.It I2C_OP_WRITE_WITH_STOP +Perform a write operation and send a STOP condition on the I2C bus at +the conclusion of the write. +.El +.It Fa i2c_addr_t +I2C device address. +.It Fa struct i2c_attach_args +Devices are attached to an I2C bus using this structure. +The structure is defined as follows: +.Bd -literal +struct i2c_attach_args { + i2c_tag_t ia_tag; /* controller */ + i2c_addr_t ia_addr; /* address of device */ + int ia_size; /* size (for EEPROMs) */ +}; +.Ed +.El +.Sh FUNCTIONS +The following functions comprise the API provided to drivers of +I2C-connected devices: +.Bl -tag -width iic_exec +.It Fn iic_acquire_bus "ic" "flags" +Acquire an exclusive lock on the I2C bus. +This is required since only one device may communicate on the +I2C bus at a time. +Drivers should acquire the bus lock, perform the I2C bus operations +necessary, and then release the bus lock. +Passing the +.Dv I2C_F_POLL +flag indicates to +.Fn iic_acquire_bus +that sleeping is not permitted. +.It Fn iic_release_bus "ic" "flags" +Release an exclusive lock on the I2C bus. +If the +.Dv I2C_F_POLL +flag was passed to +.Fn iic_acquire_bus , +it must also be passed to +.Fn iic_release_bus . +.It Fn iic_exec "ic" "op" "addr" "cmdbuf" "cmdlen" "buf" "buflen" "flags" +Perform a series of I2C transactions on the bus. +.Fn iic_exec +initiates the operation by sending a START condition on the I2C +bus and then transmitting the address of the target device along +with the transaction type. +If +.Fa cmdlen +is non-zero, the command pointed to by +.Fa cmdbuf +is then sent to the device. +If +.Fa buflen +is non-zero, +.Fn iic_exec +will then transmit or receive the data, as indicated by +.Fa op . +If +.Fa op +indicates a read operation, +.Fn iic_exec +will send a REPEATED START before transferring the data. +If +.Fa op +so indicates, a STOP condition will be sent on the I2C +bus at the conclusion of the operation. +Passing the +.Dv I2C_F_POLL +flag indicates to +.Fn iic_exec +that sleeping is not permitted. +.It Fn iic_smbus_write_byte "ic" "addr" "cmd" "data" "flags" +Perform an SMBus WRITE BYTE operation. +This is equivalent to +I2C_OP_WRITE_WITH_STOP with +.Fa cmdlen +of 1 and +.Fa buflen +of 1. +.It Fn iic_smbus_read_byte "ic" "addr" "cmd" "datap" "flags" +Perform an SMBus READ BYTE operation. +This is equivalent to +I2C_OP_READ_WITH_STOP with +.Fa cmdlen +of 1 and +.Fa buflen +of 1. +.It Fn iic_smbus_receive_byte "ic" "addr" "datap" "flags" +Perform an SMBus RECEIVE BYTE operation. +This is equivalent to +I2C_OP_READ_WITH_STOP with +.Fa cmdlen +of 0 and +.Fa buflen +of 1. +.El +.Sh CONTROLLER INTERFACE +The I2C controller driver must fill in the function pointers of +an +.Fa i2c_controller +structure, which is defined as follows: +.Bd -literal +struct i2c_controller { + void *ic_cookie; /* controller private */ + + int (*ic_acquire_bus)(void *, int); + void (*ic_release_bus)(void *, int); + + int (*ic_exec)(void *, i2c_op_t, i2c_addr_t, + const void *, size_t, void *, size_t, int); + + int (*ic_send_start)(void *, int); + int (*ic_send_stop)(void *, int); + int (*ic_initiate_xfer)(void *, i2c_addr_t, int); + int (*ic_read_byte)(void *, uint8_t *, int); + int (*ic_write_byte)(void *, uint8_t, int); +}; +.Ed +.Pp +The +.Fn (*ic_acquire_bus) +and +.Fn (*ic_release_bus) +functions must always be provided. +.Pp +The controller driver may elect to provide an +.Fn (*ic_exec) +function. +This function is intended for use by automated controllers +that do not provide manual control over I2C bus conditions +such as START and STOP. +.Pp +If the +.Fn (*ic_exec) +function is not provided, the following 5 functions will be +used by +.Fn iic_exec +in order to execute the I2C bus operation: +.Bl -tag -width XXXX +.It Fn (*ic_send_start) "cookie" "flags" +Send a START condition on the I2C bus. +The +.Dv I2C_F_POLL +flag indicates that sleeping is not permitted. +.It Fn (*ic_send_stop) "cookie" "flags" +Send a STOP condition on the I2C bus. +The +.Dv I2C_F_POLL +flag indicates that sleeping is not permitted. +.It Fn (*ic_initiate_xfer) "cookie" "addr" "flags" +Initiate a transfer on the I2C bus by sending a START condition and +then transmitting the I2C device address and transfer type. +The +.Dv I2C_F_READ +flag indicates a read transfer; the lack of this flag indicates a +write transfer. +The +.Dv I2C_F_POLL +flag indicates that sleeping is not permitted. +The error code +.Dv ETIMEDOUT +should be returned if a timeout that would indicate that the +device is not present occurs. +.It Fn (*ic_read_byte) "cookie" "datap" "flags" +Read a byte from the I2C bus into the memory location referenced by +.Fa datap . +The +.Dv I2C_F_LAST +flag indicates that this is the final byte of the transfer, and that +a NACK condition should be sent on the I2C bus following the transfer +of the byte. +The +.Dv I2C_F_STOP +flag indicates that a STOP condition should be sent on the I2C bus following +the transfer of the byte. +The +.Dv I2C_F_POLL +flag indicates that sleeping is not permitted. +.It Fn (*ic_write_byte) "cookie" "data" "flags" +Write the byte contained in +.Fa data +to the I2C bus. +The +.Dv I2C_F_STOP +flag indicates that a STOP condition should be sent on the I2C bus following +the transfer of the byte. +The +.Dv I2C_F_POLL +flag indicates that sleeping is not permitted. +.El +.Sh SEE ALSO +.Xr iic 4 , +.Xr i2cscan 8 +.Rs +.%A NXP Semiconductors +.%T I2C-bus Specification and User Manual +.%N Revision 03 +.%D June 19, 2007 +.%U http://www.ics.nxp.com/support/documents/i2c/pdf/i2c.bus.specification.pdf +.Re +.Rs +.%A Duracell Inc. et. al. +.%T System Management Bus (SMBus) Specification +.%N Version 2.0 +.%D August 3, 2000 +.%U http://smbus.org/specs/smbus20.pdf +.Re +.Sh HISTORY +The +.Nm iic +API first appeared in +.Nx 2.0 . +.Ox +support was added in +.Ox 3.6 . +.Sh AUTHORS +The +.Nm iic +API was written by +Steve C. Woodford and Jason R. Thorpe for +.Nx +and then ported to +.Ox +by +.An Alexander Yurchenko Aq Mt grange@openbsd.org . diff --git a/static/netbsd/man9/imax.9 b/static/netbsd/man9/imax.9 new file mode 100644 index 00000000..9d6a1440 --- /dev/null +++ b/static/netbsd/man9/imax.9 @@ -0,0 +1,80 @@ +.\" $NetBSD: imax.9,v 1.8 2024/07/10 07:08:37 rin Exp $ +.\" +.\" Copyright (c) 2006 Igor Sobrado +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 10, 2024 +.Dt IMAX 9 +.Os +.Sh NAME +.Nm imax , +.Nm imin , +.Nm lmax , +.Nm lmin , +.Nm uimax , +.Nm uimin , +.Nm ulmax , +.Nm ulmin +.Nd compare integers +.Sh SYNOPSIS +.Ft int +.Fn imax "int a" "int b" +.Ft int +.Fn imin "int a" "int b" +.Ft long +.Fn lmax "long a" "long b" +.Ft long +.Fn lmin "long a" "long b" +.Ft u_int +.Fn uimax "u_int a" "u_int b" +.Ft u_int +.Fn uimin "u_int a" "u_int b" +.Ft u_long +.Fn ulmax "u_long a" "u_long b" +.Ft u_long +.Fn ulmin "u_long a" "u_long b" +.Sh DESCRIPTION +The +.Fn imin , +.Fn lmin , +.Fn uimin , +and +.Fn ulmin +functions return whichever argument is algebraically smaller, differing only +in their argument and return types: these functions operate on, respectively, +natural size, long, unsigned and unsigned long integers. +.Pp +The +.Fn imax , +.Fn lmax , +.Fn uimax , +and +.Fn ulmax +functions are identical except that they return the algebraically larger +argument between +.Ar a +and +.Ar b . +.Sh SEE ALSO +.Xr ilog2 3 diff --git a/static/netbsd/man9/in4_cksum.9 b/static/netbsd/man9/in4_cksum.9 new file mode 100644 index 00000000..46b5d489 --- /dev/null +++ b/static/netbsd/man9/in4_cksum.9 @@ -0,0 +1,111 @@ +.\" $NetBSD: in4_cksum.9,v 1.6 2008/04/30 13:10:58 martin Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Bill Sommerfeld. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 22, 2001 +.Dt IN_CKSUM 9 +.Os +.Sh NAME +.Nm in_cksum , +.Nm in4_cksum , +.Nm in6_cksum +.Nd compute Internet checksum +.Sh SYNOPSIS +.Ft uint16_t +.Fn in_cksum "struct mbuf *m" "int len" +.Ft uint16_t +.Fn in4_cksum "struct mbuf *m" "uint8_t nxt" "int off" "int len" +.Ft uint16_t +.Fn in6_cksum "struct mbuf *m" "uint8_t nxt" "int off" "int len" +.Sh DESCRIPTION +These functions are used to compute the ones-complement checksum +required by IP and IPv6. +The +.Fn in4_cksum +function is used to compute the transport-layer checksum required by +.Xr tcp 4 +and +.Xr udp 4 +over a range of bytes starting at +.Fa off +and continuing on for +.Fa len +bytes within the mbuf +.Fa m . +.Pp +If the +.Fa nxt +parameter is non-zero, it is assumed to be an IP protocol number. +It is also assumed that the data within +.Fa m +starts with an IP header, and the transport-layer header starts at +.Fa off ; +a pseudo-header is constructed as specified +in RFC768 and RFC793, and the pseudo-header is prepended to the data +covered by the checksum. +.Pp +The +.Fn in6_cksum +function is similar; if +.Fa nxt +is non-zero, it is assumed that +.Fa m +starts with an IPv6 header, and that the transport-layer header starts +after +.Fa off +bytes. +.Pp +The +.Fn in_cksum +function is equivalent to +.Fn in4_cksum "m" "0" "0" "len" . +.Pp +These functions are always performance critical and should be +reimplemented in assembler or optimized C for each platform; when +available, use of repeated full-width add-with-carry followed by +reduction of the sum to a 16 bit width usually leads to best results. +See RFC's 1071, 1141, 1624, and 1936 for more information about +efficient computation of the internet checksum. +.Sh RETURN VALUES +All three functions return the computed checksum value. +.Sh SEE ALSO +.Xr inet 4 , +.Xr inet6 4 , +.Xr tcp 4 , +.Xr udp 4 , +.Xr protocols 5 , +.Xr mbuf 9 +.Sh STANDARDS +These functions implement the Internet transport-layer checksum as specified +in RFC768, RFC793, and RFC2460. +.Sh BUGS +The +.Fn in6_cksum +function currently requires special handling of link-local addresses +in the pseudo-header due to the use of embedded scope-id's within +link-local addresses. diff --git a/static/netbsd/man9/in_getifa.9 b/static/netbsd/man9/in_getifa.9 new file mode 100644 index 00000000..477e4b02 --- /dev/null +++ b/static/netbsd/man9/in_getifa.9 @@ -0,0 +1,244 @@ +.\" $NetBSD: in_getifa.9,v 1.11 2020/01/21 07:53:51 wiz Exp $ +.\" +.\" Copyright (c) 2006 David Young. All rights reserved. +.\" +.\" This code was written by David Young. +.\" +.\" Redistribution and use in source and binary forms, with or +.\" without modification, are permitted provided that the following +.\" conditions are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer in the documentation and/or other materials provided +.\" with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY DAVID YOUNG ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, +.\" THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A +.\" PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL DAVID +.\" YOUNG BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, +.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED +.\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.Dd February 22, 2007 +.Dt IN_GETIFA 9 +.Os +.Sh NAME +.Nm in_getifa +.Nd Look up the IPv4 source address best matching an IPv4 destination +.Sh SYNOPSIS +.Cd options IPSELSRC +.In netinet/in_selsrc.h +.Ft struct ifaddr * +.Fn in_getifa "struct ifaddr *ifa" "const struct sockaddr *dst0" +.Sh DESCRIPTION +.Nm +enforces the IPv4 source-address selection policy. +Add the source-address selection policy mechanism to your kernel with +.Cd options IPSELSRC . +.Cd options IPSELSRC +lets the operator set the policy for choosing the source address +of any socket bound to the +.Dq wildcard +address, +.Dv INADDR_ANY . +Note that the policy is applied +.Em after +the kernel makes its forwarding decision, thereby choosing the +output interface; +in other words, this mechanism does not affect whether or not +.Nx +is a +.Dq strong ES . +.Pp +An operator affects the source-address selection using +.Xr sysctl 8 +and +.Xr ifconfig 8 . +Operators set policies with +.Xr sysctl 8 . +Some policies consider the +.Dq preference number +of an address. +An operator may set preference numbers for each address with +.Xr ifconfig 8 . +.Pp +A source-address policy is a priority-ordered list of source-address +ranking functions. +A ranking function maps its arguments, +.Po +.Em source address , +.Em source index , +.Em source preference , +.Em destination address +.Pc , +to integers. +The +.Em source index +is the position of +.Em source address +in the interface address list; the index of the first address is 0. +The +.Em source preference +is the preference number the operator assigned +to +.Em source address . +The +.Em destination address +is the socket peer / packet destination. +.Pp +Presently, there are four ranking functions to choose from: +.Bl -tag -width "common-prefix-len" +.It index +ranks by +.Em source index ; +lower indices are ranked more highly. +.It preference +ranks by +.Em source preference ; +higher preference numbers are ranked more highly. +.It common-prefix-len +ranks each +.Em source address +by the length of the longest prefix it has in common with +.Em destination address ; +longer common prefixes rank more highly. +.It same-category +determines the "categories" of +.Em source +and +.Em destination address . +A category is one of +.Em private , +.Em link-local , +or +.Em other . +If the categories exactly match, same-category assigns a rank of 2. +Some sources are ranked 1 by category: +a +.Em link-local +source with a +.Em private +destination, a +.Em private +source with a +.Em link-local +destination, and a +.Em private +source with an +.Em other +destination rank 1. +All other sources rank 0. +.Pp +Categories are defined as follows. +.Bl -tag -width "link-local" +.It private +RFC1918 networks, 192.168/16, 172.16/12, and 10/8 +.It link-local +169.254/16, 224/24 +.It other +all other networks---i.e., not private, not link-local +.El +.El +.Pp +To apply a policy, the kernel applies all ranking functions in the policy +to every source address, producing a vector of ranks for each source. +The kernel sorts the sources in descending, lexicographical order by their +rank-vector, and chooses the highest-ranking (first) source. +The kernel breaks ties by choosing the source with the least +.Em source index . +.Pp +The operator may set a policy on individual interfaces. +The operator may also set a global policy that applies to all +interfaces whose policy they do not set individually. +.Pp +Here is the sysctl tree for the policy at system startup: +.Bd -literal -offset indent +net.inet.ip.selectsrc.default = index +net.inet.ip.interfaces.ath0.selectsrc = +net.inet.ip.interfaces.sip0.selectsrc = +net.inet.ip.interfaces.sip1.selectsrc = +net.inet.ip.interfaces.lo0.selectsrc = +net.inet.ip.interfaces.pflog0.selectsrc = +.Ed +.Pp +The policy on every interface is the +.Dq empty +policy, so the default policy applies. +The default policy, +.Em index , +is the +.Dq historical +policy in +.Nx . +.Pp +The operator may override the default policy on ath0, +.Bd -literal -offset indent + # sysctl -w net.inet.ip.interfaces.ath0.selectsrc=same-category,common-prefix-len,preference +.Ed +.Pp +yielding this policy: +.Bd -literal -offset indent +net.inet.ip.selectsrc.default = index +net.inet.ip.interfaces.ath0.selectsrc = same-category,common-prefix-len,preference +.Ed +.Pp +The operator may set a new default, +.Bd -literal -offset indent +# sysctl -w net.inet.ip.selectsrc.debug=\ +> same-category,common-prefix-len,preference +# sysctl -w net.inet.ip.interfaces.ath0.selectsrc= +.Ed +.Pp +yielding this policy: +.Bd -literal -offset indent +net.inet.ip.selectsrc.default = same-category,common-prefix-len,preference +net.inet.ip.interfaces.ath0.selectsrc = +.Ed +.Pp +In a number of applications, the policy above will usually pick +suitable source addresses if ath0 is configured in this way: +.Bd -literal -offset indent +# ifconfig ath0 inet 64.198.255.1/24 +# ifconfig ath0 inet 10.0.0.1/24 +# ifconfig ath0 inet 169.254.1.1/24 +# ifconfig ath0 inet 192.168.49.1/24 preference 5 +# ifconfig ath0 inet 192.168.37.1/24 preference 9 +.Ed +A sysctl, net.inet.ip.selectsrc.debug, turns on and off debug messages +concerned with source selection. +You may set it to 0 (no messages) or 1. +.Sh SEE ALSO +.Xr ifconfig 8 , +.Xr sysctl 8 +.Sh STANDARDS +The family of IPv6 source-address selection policies defined by +.Li RFC3484 +resembles the family of IPv4 policies that +.Nm +enforces. +.Sh AUTHORS +.An David Young Aq Mt dyoung@NetBSD.org +.Sh BUGS +With +.Cd options IPSELSRC , +a new interface +.Xr ioctl 2 , +.Dv SIOCSIFADDRPREF , +was introduced. +It ought to be documented in +.Xr inet 4 . +Also, +.Xr options 4 +ought to cross-reference this manual page. +.Pp +This work should be used to set IPv6 source-address selection +policies, especially the family of policies defined by +.Li RFC3484 . diff --git a/static/netbsd/man9/inittodr.9 b/static/netbsd/man9/inittodr.9 new file mode 100644 index 00000000..93686ebe --- /dev/null +++ b/static/netbsd/man9/inittodr.9 @@ -0,0 +1,105 @@ +.\" $NetBSD: inittodr.9,v 1.14 2024/09/07 19:13:29 rillig Exp $ +.\" +.\" Copyright (c) 1994 Christopher G. Demetriou +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the +.\" NetBSD Project. See https://www.NetBSD.org/ for +.\" information about NetBSD. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" <<Id: LICENSE,v 1.2 2000/06/14 15:57:33 cgd Exp>> +.\" +.Dd September 6, 2006 +.Dt INITTODR 9 +.Os +.Sh NAME +.Nm inittodr +.Nd initialize system time +.Sh SYNOPSIS +.Ft void +.Fn inittodr "time_t base" +.Sh DESCRIPTION +The +.Fn inittodr +function determines the time and sets the system clock. +It tries to pick the correct time using a set of heuristics that examine +the system's battery-backed clock and the time reported by the file +system, as given in +.Fa base . +Those heuristics include: +.Bl -bullet +.It +If the battery-backed clock has a valid time, and is not significantly +behind the time provided by +.Fa base , +it is used. +.It +If the battery-backed clock does not have a valid time, or is significantly +behind the time provided in +.Fa base , +and the time provided in +.Fa base +is within reason, +.Fa base +is used as the current time. +.It +If the battery-backed clock appears invalid, and +.Fa base +appears non-sensical or was not provided (was given as zero), +an arbitrary base (typically some time within the same year that +the kernel was last updated) will be used. +.El +.Pp +Once a system time has been determined, it is stored in the +.Va time +variable. +.Sh DIAGNOSTICS +The +.Fn inittodr +function prints diagnostic messages if it has trouble figuring +out the system time. +Conditions that can cause diagnostic messages to be printed include: +.Bl -bullet +.It +There is no battery-backed clock present on the system. +.It +The battery-backed clock's time appears nonsensical. +.It +The +.Fa base +time appears nonsensical. +.It +The +.Fa base +time and the battery-backed clock's time differ by a large amount. +.El +.Sh SEE ALSO +.Xr clock_ymdhms_to_secs 9 , +.Xr resettodr 9 , +.Xr time_second 9 +.Sh BUGS +Some systems use heuristics for picking the correct time that are slightly +different. diff --git a/static/netbsd/man9/interrupt_distribute.9 b/static/netbsd/man9/interrupt_distribute.9 new file mode 100644 index 00000000..9472b3a5 --- /dev/null +++ b/static/netbsd/man9/interrupt_distribute.9 @@ -0,0 +1,55 @@ +.\" $NetBSD: interrupt_distribute.9,v 1.2 2016/07/06 09:20:42 abhinav Exp $ +.\" +.\" Copyright (c) 2015 Internet Initiative Japan Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 17, 2015 +.Dt INTERRUPT_DISTRIBUTE 9 +.Os +.Sh NAME +.Nm interrupt_distribute +.Nd assign an interrupt to a CPU +.Sh SYNOPSIS +.In sys/interrupt.h +.Ft int +.Fn interrupt_distribute "void *ich" "const kcpuset_t *newset" \ +"kcpuset_t *oldset" +.Sh DESCRIPTION +The +.Nm +function exists to assign an interrupt to a CPU. +.Pp +If a driver (or the other kernel component) wishes to assign an +interrupt to a CPU, it should pass an interrupt handler such as +the return value of +.Fn pci_intr_establish +as +.Fa ich +argument, and it should pass the kcpuset to which it should be +assigned as +.Fa newset . +To get the previous value, pass a +.Pf non- Dv NULL +value to +.Ft oldset . diff --git a/static/netbsd/man9/intro.9 b/static/netbsd/man9/intro.9 new file mode 100644 index 00000000..6015aacc --- /dev/null +++ b/static/netbsd/man9/intro.9 @@ -0,0 +1,633 @@ +.\" $NetBSD: intro.9,v 1.26 2019/09/01 19:09:00 wiz Exp $ +.\" +.\" Copyright (c) 1997, 2007 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jeremy Cooper, and Mindaugas Rasiukevicius. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 14, 2018 +.Dt INTRO 9 +.Os +.Sh NAME +.Nm intro +.Nd introduction to kernel internals +.Sh DESCRIPTION +This section contains information related to the internal operation of the +system kernel. +It describes function interfaces and variables of use to the systems and device +driver programmer. +.Pp +In addition to the normal man page format, the kernel pages include an +additional section: +.Bl -tag -width "CODE REFERENCES" +.It "CODE REFERENCES" +Contains the pathname(s) of the source file(s) which contain the definition +and/or source code of the variables or functions being documented. +Any paths are relative to the top level of the source tree (traditionally +.Pa /usr/src ) . +.El +.Sh MEMORY MANAGEMENT +Introduction to kernel memory allocators. +See +.Xr memoryallocators 9 . +.Pp +Machine-dependent portion of the virtual memory system. +See +.Xr pmap 9 . +.Pp +Virtual memory system external interface. +See +.Xr uvm 9 . +.Sh I/O SUBSYSTEM +Buffer cache interfaces. +See +.Xr buffercache 9 . +.Pp +Device buffer queues. +See +.Xr bufq 9 . +.Pp +Initiate I/O on raw devices. +See +.Xr physio 9 . +.Pp +I/O descriptor allocation interface. +See +.Xr getiobuf 9 . +.Sh PROCESS CONTROL +Idle CPU while waiting for work. +See +.Xr cpu_idle 9 . +.Pp +Finish a fork operation. +See +.Xr cpu_lwp_fork 9 . +.Pp +Switch to another light weight process. +See +.Xr mi_switch 9 . +.Pp +Current process and processor. +See +.Xr curproc 9 . +.Pp +Set process uid and gid. +See +.Xr do_setresuid 9 . +.Pp +New processes and kernel threads. +See +.Xr fork1 9 , +.Xr kthread 9 . +.Pp +Context switch notification. +See +.Xr cpu_need_resched 9 . +.Pp +Common scheduler framework. +See +.Xr csf 9 . +.Pp +Software signal facilities. +See +.Xr signal 9 . +.Pp +Suspend the scheduler. +See +.Xr suspendsched 9 . +.Pp +Return path to user-mode execution. +See +.Xr userret 9 . +.Sh FILE SYSTEM +High-level file operations. +See +.Xr dofileread 9 . +.Pp +Convert an extended attribute namespace identifier to a string and +vice versa. +See +.Xr extattr 9 . +.Pp +Operations on file entries. +See +.Xr file 9 . +.Pp +In-kernel, file system independent, file-meta data association. +See +.Xr fileassoc 9 . +.Pp +File descriptor tables and operations. +See +.Xr filedesc 9 . +.Pp +File descriptor owner handling functions. +See +.Xr fsetown 9 . +.Pp +File system suspension helper subsystem. +See +.Xr fstrans 9 . +.Pp +Pathname lookup, cache and management. +See +.Xr namei 9 , +.Xr namecache 9 . +.Pp +Kernel interface to file systems. +See +.Xr vfs 9 . +.Pp +Kernel representation of a file or directory and vnode attributes. +See +.Xr vnode 9 , +.Xr vattr 9 . +.Sh NETWORKING +Kernel interfaces for manipulating output queues on network interfaces. +See +.Xr altq 9 . +.Pp +Externally visible ARP functions. +See +.Xr arp 9 . +.Pp +Ethernet and FDDI driver support functions and macros. +See +.Xr ethersubr 9 . +.Pp +Core 802.11 network stack functions and rate adaptation based on +received signal strength. +See +.Xr ieee80211 9 , +.Xr rssadapt 9 . +.Pp +Compute Internet checksum. +See +.Xr in_cksum 9 . +.Pp +Look up the IPv4 source address best matching an IPv4 destination. +See +.Xr in_getifa 9 . +.Pp +Functions and macros for managing memory used by networking code. +See +.Xr mbuf 9 . +.Pp +Packet filter interface. +See +.Xr pfil 9 . +.Pp +Route callout functions. +See +.Xr rt_timer 9 . +.Pp +TCP congestion control API. +See +.Xr tcp_congctl 9 . +.Sh LOCKING AND INTERRUPT CONTROL +See +.Xr locking 9 +for an overview. +.Pp +Condition variables. +See +.Xr condvar 9 . +.Pp +Kernel lock functions. +See +.Xr lock 9 . +.Pp +Memory barriers. +See +.Xr membar_ops 3 . +.Pp +Mutual exclusion primitives. +See +.Xr mutex 9 . +.Pp +Restartable atomic sequences. +See +.Xr ras 9 . +.Pp +Reader / writer lock primitives. +See +.Xr rwlock 9 . +.Pp +Machine-independent software interrupt framework. +See +.Xr softint 9 . +.Pp +Functions to modify system interrupt priority level. +See +.Xr spl 9 . +.Pp +Functions to raise the system priority level. +See +.Xr splraiseipl 9 . +.Sh SECURITY +Kernel authorization framework. +See +.Xr kauth 9 . +.Pp +API for cryptographic services in the kernel. +See +.Xr opencrypto 9 . +.Pp +Security model development guidelines. +See +.Xr secmodel 9 . +.Sh SYSTEM TIME CONTROL +Execute a function after a specified length of time. +See +.Xr callout 9 . +.Pp +Microsecond delay. +See +.Xr delay 9 . +.Pp +Real-time timer. +See +.Xr hardclock 9 . +.Pp +System clock frequency. +See +.Xr hz 9 . +.Pp +Initialization of system time and time-of-day clock support. +See +.Xr inittodr 9 , +.Xr todr 9 . +.Pp +Check that a timeval value is valid, and correct. +See +.Xr itimerfix 9 . +.Pp +System time variables. +See +.Xr timecounter 9 . +.Pp +Realtime system clock. +See +.Xr microtime 9 . +.Pp +Get the time elapsed since boot. +See +.Xr microuptime 9 . +.Pp +Convert milliseconds to system clock ticks. +See +.Xr mstohz 9 . +.Pp +Function to help implement rate-limited actions. +See +.Xr ppsratecheck 9 . +.Pp +Function to help implement rate-limited actions. +See +.Xr ratecheck 9 . +.Pp +Set battery-backed clock from system time. +See +.Xr resettodr 9 . +.Pp +System time variables. +See +.Xr time_second 9 . +.Sh KERNEL AND USER SPACE DATA COPY FUNCTIONS +Kernel space to/from user space copy functions. +See +.Xr copy 9 . +.Pp +Store data to user-space. +See +.Xr ustore 9 . +.Pp +Fetch data from user-space. +See +.Xr ufetch 9 . +.Pp +Move data described by a struct uio. +See +.Xr uiomove 9 . +.Sh MACHINE DEPENDENT KERNEL FUNCTIONS +Machine-dependent clock setup interface. +See +.Xr cpu_initclocks 9 . +.Pp +Machine-dependent process core dump interface. +See +.Xr cpu_coredump 9 . +.Pp +Machine-dependent kernel core dumps. +See +.Xr cpu_dumpconf 9 . +.Pp +Unique CPU identification number +See +.Xr cpu_number 9 . +.Pp +Halt or reboot the system +See +.Xr cpu_reboot 9 . +.Pp +Machine-dependent root file system setup +See +.Xr cpu_rootconf 9 . +.Pp +Machine-dependent CPU startup +See +.Xr cpu_startup 9 . +.Pp +Disk label management routines. +See +.Xr disklabel 9 . +.Sh DEVICE CONFIGURATION +Autoconfiguration frame-work. +See +.Xr autoconf 9 . +.Pp +Description of a device driver. +See +.Xr driver 9 . +.Pp +The autoconfiguration framework ``device definition'' language. +See +.Xr config 9 . +.Pp +Machine-dependent device autoconfiguration. +See +.Xr cpu_configure 9 . +.Sh MI DEVICE DRIVER API +Bus and Machine Independent DMA Mapping Interface. +See +.Xr bus_dma 9 . +.Pp +Bus space manipulation functions. +See +.Xr bus_space 9 . +.Pp +Generic disk framework. +See +.Xr disk 9 . +.Pp +Hardware-assisted data mover interface. +See +.Xr dmover 9 . +Generic event counter framework. +See +.Xr evcnt 9 . +.Pp +Firmware loader API for device drivers. +See +.Xr firmload 9 . +.Pp +How to implement a new ioctl call to access device drivers. +See +.Xr ioctl 9 . +.Pp +Extensible line discipline framework. +See +.Xr linedisc 9 . +.Sh CONSOLE DEVICES +Console magic key sequence management. +See +.Xr cnmagic 9 . +.Pp +Console access interface. +See +.Xr cons 9 . +.Pp +Raster display operations. +See +.Xr rasops 9 . +.Pp +Generic virtual console framework. +See +.Xr vcons 9 . +.Pp +Machine-independent console support. +See +.Xr wscons 9 . +.Sh DEVICE SPECIFIC IMPLEMENTATION +Interface between low and high level audio drivers. +See +.Xr audio 9 . +.Pp +Bluetooth Device/Protocol API. +See +.Xr bluetooth 9 . +.Pp +Support for CardBus PC-Card devices. +See +.Xr cardbus 9 . +.Pp +VESA Display Data Channel V2. +See +.Xr ddc 9 . +.Pp +VESA Extended Display Identification Data. +See +.Xr edid 9 . +.Pp +Inter IC (I2C) bus. +See +.Xr iic 9 . +.Pp +Baseboard I/O control ASIC for DEC TURBOchannel systems. +See +.Xr ioasic 9 . +.Pp +Industry-standard Architecture. +See +.Xr isa 9 . +.Pp +Introduction to ISA Plug-and-Play support. +See +.Xr isapnp 9 . +.Pp +MicroChannel Architecture bus. +See +.Xr mca 9 . +.Pp +PPBUS microseqencer developer's guide. +See +.Xr microseq 9 . +.Pp +Peripheral Component Interconnect. +See +.Xr pci 9 . +.Pp +Perform PCI bus configuration. +See +.Xr pci_configure_bus 9 . +.Pp +PCI bus interrupt manipulation functions. +See +.Xr pci_intr 9 . +.Pp +PC keyboard port interface. +See +.Xr pckbport 9 . +.Pp +Support for PCMCIA PC-Card devices. +See +.Xr pcmcia 9 . +.Pp +Interface between low and high level radio drivers. +See +.Xr radio 9 . +.Pp +Functions to make a device available for entropy collection. +See +.Xr rnd 9 . +.Pp +SCSI/ATAPI middle-layer interface. +See +.Xr scsipi 9 . +.Pp +TURBOchannel bus. +See +.Xr tc 9 . +.Pp +USB tty support. +See +.Xr ucom 9 . +.Pp +USB device drivers interface. +See +.Xr usbdi 9 . +.Pp +Versa Module Euroboard bus. +See +.Xr vme 9 . +.Pp +Machine-independent IDE/ATAPI driver. +See +.Xr wdc 9 . +.Sh KERNEL EVENT +Functions to add or remove kernel event filters. +See +.Xr kfilter_register 9 . +.Pp +Functions to raise kernel event. +See +.Xr knote 9 . +.Pp +Record and wakeup select requests. +See +.Xr selrecord 9 . +.Pp +Simple do-it-in-thread-context framework. +See +.Xr workqueue 9 . +.Sh KERNEL HELPER FUNCTIONS +Kernel expression verification macros. +See +.Xr KASSERT 9 . +.Pp +Convert a single byte between (unsigned) packed bcd and binary. +See +.Xr bcdtobin 9 . +.Pp +Bitmask output conversion. +See +.Xr snprintb 3 . +.Pp +General purpose extent manager. +See +.Xr extent 9 . +.Pp +Compare integers. +See +.Xr imax 9 . +.Pp +Kernel formatted output conversion. +See +.Xr kprintf 9 . +.Pp +Data comparing, moving, copying, setting and cleaning. +See +.Xr memcmp 9 , +.Xr memmove 9 , +.Xr memcpy 9 , +.Xr memset 9 , +.Xr bcmp 9 , +.Xr bcopy 9 , +.Xr bzero 9 , +.Xr kcopy 9 . +.Pp +Log a message from the kernel through the /dev/klog device. +See +.Xr log 9 . +.Pp +Bring down system on fatal error. +See +.Xr panic 9 . +.Sh MISC +Power management and inter-driver messaging. +See +.Xr pmf 9 . +.Pp +Run all shutdown hooks. +See +.Xr pmf_system_shutdown 9 . +.Pp +Kernel internal error numbers. +See +.Xr errno 9 . +.Pp +Kernel hash functions, hash table construction and destruction. +See +.Xr hash 9 , +.Xr hashinit 9 . +.Pp +Format a number into a human readable form. +See +.Xr humanize_number 9 . +.Pp +Options string management. +See +.Xr optstr 9 . +.Pp +Performs pattern matching on strings. +See +.Xr pmatch 9 . +.Pp +Add or remove a shutdown hook. +See +.Xr pmf 9 . +.Pp +Non-local jumps. +See +.Xr setjmp 9 . +.Pp +System variable control interfaces. +See +.Xr sysctl 9 . +.Sh HISTORY +The +.Nx +kernel internals section first appeared in +.Nx 1.2 . diff --git a/static/netbsd/man9/ioasic.9 b/static/netbsd/man9/ioasic.9 new file mode 100644 index 00000000..5386e1ce --- /dev/null +++ b/static/netbsd/man9/ioasic.9 @@ -0,0 +1,214 @@ +.\" $NetBSD: ioasic.9,v 1.13 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright (c) 2000 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 6, 2000 +.Dt IOASIC 9 +.Os +.Sh NAME +.Nm IOASIC , +.Nm ioasic_intr_establish , +.Nm ioasic_intr_disestablish , +.Nm ioasic_intr_evcnt , +.Nm ioasic_attach_devs , +.Nm ioasic_submatch +.Nd baseboard I/O control ASIC for DEC TURBOchannel systems +.Sh SYNOPSIS +.In sys/bus.h +.In dev/tc/tcvar.h +.In dev/tc/ioasicreg.h +.In dev/tc/ioasicvar.h +.Ft void +.Fn ioasic_intr_establish "struct device *dev" "void *cookie" "int level" \ +"int (*handler)(void *)" "void *arg" +.Ft void +.Fn ioasic_intr_disestablish "struct device *dev" "void *cookie" +.Ft const struct evcnt * +.Fn ioasic_intr_evcnt "struct device *dev" "void *cookie" +.Ft void +.Fn ioasic_attach_devs "struct ioasic_softc *sc" \ +"struct ioasic_dev *ioasic_devs" "int ioasic_ndevs" +.Ft int +.Fn ioasic_submatch "struct cfdata *match" "struct ioasicdev_attach_args *ia" +.Sh DESCRIPTION +The +.Nm +device provides support for the DEC proprietary IOCTL ASIC found on +all DEC TURBOchannel machines with MIPS (DECstation 5000 series, +excluding the 5000/200) and Alpha (3000-series) systems. +The +.Nm +is memory-mapped into the TURBOchannel system slot to interface up to +sixteen I/O devices. +It connects the TURBOchannel to a 16-bit wide I/O bus and supplies +various control signals to the devices that share this bus. +.Pp +The +.Nm +provides hardware DMA channels and interrupt support. +DMA transfers are between one and four 32-bit words (16 bytes) in +length, depending on the device. +The +.Nm +stores the data in internal data registers. +The data is transferred to and from the registers in 16-bit words +to the device. +Various interrupts are signalled on DMA pointer-related conditions. +.Sh DATA TYPES +Drivers for devices attached to the +.Nm +will make use of the following data types: +.Bl -tag -width compact +.It Fa struct ioasicdev_attach_args +A structure used to inform the driver of the +.Nm +device properties. +It contains the following members: +.Bd -literal + char iada_modname + tc_offset_t iada_offset + tc_addr_t iada_addr + void *iada_cookie; +.Ed +.It Fa struct ioasic_softc +The parent structure which contains at the following members which are +useful for drivers: +.Bd -literal + bus_space_tag_t sc_bst; + bus_space_handle_t sc_bsh; + bus_dma_tag_t sc_dmat; +.Ed +.It Fa struct ioasic_dev +A structure describing the machine-dependent devices attached to the +.Nm +containing the following members: +.Bd -literal + char *iad_modname; + tc_offset_t iad_offset; + void *iad_cookie; + uint32_t iad_intrbits; +.Ed +.El +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn ioasic_intr_establish "dev" "cookie" "level" "handler" "arg" +Establish an interrupt handler with device +.Fa dev +for the interrupt described completely by +.Fa cookie . +The priority of the interrupt is specified by +.Fa level . +When the interrupt occurs the function +.Fa handler +is called with argument +.Fa arg . +.It Fn ioasic_intr_disestablish "dev" "cookie" +Dis-establish the interrupt handler with device +.Fa dev +for the interrupt described complete ly +.Fa cookie . +.It Fn ioasic_intr_evcnt "dev" "cookie" +Do interrupt event counting with device +.Fa dev +for the event described completely by +.Fa cookie . +.It Fn ioasic_attach_devs "sc" "ioasic_devs" "ioasic_ndevs" +Configure each of the +.Fa ioasic_ndevs +devices in +.Fa ioasic_devs . +.It Fn ioasic_submatch "match" "ia" +Check that the device offset is not OASIC_OFFSET_UNKNOWN. +.El +.Pp +The +.Fn ioasic_intr_establish , +.Fn ioasic_intr_disestablish , +and +.Fn ioasic_intr_evcnt +functions are likely to used by all +.Nm +device drivers. +The +.Fn ioasic_attach_devs +function is used by ioasic driver internally and is of interest to +driver writers because it must be aware of your device for it to be +found during autoconfiguration. +.Sh AUTOCONFIGURATION +The IOASIC is a direct-connection bus. +During autoconfiguration, machine-dependent code will provide an array of +.Fa struct ioasic_devs +describing devices attached to the +.Nm +to be used by the ioasic driver. +The ioasic driver will pass this array to +.Fn ioasic_attach_devs +to attach the drivers with the devices. +.Pp +Drivers match the device using +.Fa iada_modname . +.Pp +During attach, all drivers should use the parent's bus_space and +bus_dma resources, and map the appropriate bus_space region using +.Fn bus_space_subregion +with +.Fa iada_offset . +.Sh DMA SUPPORT +No additional support is provided for +.Nm +DMA beyond the facilities provided by the +.Xr bus_dma 9 +interface. +.Pp +The +.Nm +provides two pairs of DMA address pointers (transmitting and +receiving) for each DMA-capable device. +The pair of address pointers point to consecutive (but not necessarily +contiguous) DMA blocks of size IOASIC_DMA_BLOCKSIZE. +Upon successful transfer of the first block, DMA continues to the next +block and an interrupt is posted to signal an address pointer update. +DMA transfers are enabled and disabled by bits inside the +.Nm +status (CSR) register. +.Pp +The interrupt handler must update the address pointers to point to the +next block in the DMA transfer. +The address pointer update must be completed before the completion of +the second DMA block, otherwise a DMA overrun error condition will occur. +.Sh CODE REFERENCES +The IOASIC subsystem itself is implemented within the file +.Pa sys/dev/tc/ioasic_subr.c . +Machine-dependent portions can be found in +.Pa sys/arch/<arch>/tc/ioasic.c . +.Sh SEE ALSO +.Xr ioasic 4 , +.Xr autoconf 9 , +.Xr bus_dma 9 , +.Xr bus_space 9 , +.Xr driver 9 diff --git a/static/netbsd/man9/ioctl.9 b/static/netbsd/man9/ioctl.9 new file mode 100644 index 00000000..bd0977af --- /dev/null +++ b/static/netbsd/man9/ioctl.9 @@ -0,0 +1,317 @@ +.\" $NetBSD: ioctl.9,v 1.37 2025/12/10 19:25:24 andvar Exp $ +.\" +.\" Copyright (c) 1999 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Heiko W.Rupp <hwr@pilhuhn.de> +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 7, 2022 +.Dt IOCTL 9 +.Os +.Sh NAME +.Nm ioctl +.Nd "how to implement a new ioctl call to access device drivers" +.Sh SYNOPSIS +.In sys/ioctl.h +.In sys/ioccom.h +.Ft int +.Fn ioctl "int" "unsigned long" "..." +.Sh DESCRIPTION +.Nm +are internally defined as +.Bl -tag -width define +.It #define FOOIOCTL fun(t,n,pt) +.El +.Pp +where the different variables and functions are: +.Bl -tag -width FOOIOCTL +.It Cm FOOIOCTL +the name which will later be given in the +.Xr ioctl 2 +system call as second argument, e.g., +.Dl ioctl(s, FOOIOCTL, ...) . +.It Fn fun +a macro which can be one of +.Bl -tag -width _IOWR +.It _IO +the call is a simple message to the kernel by itself. +It does not copy anything into the kernel, nor does it want anything back. +.It _IOR +the call only reads parameters from the kernel and does not +pass any to it +.It _IOW +the call only writes parameters to the kernel, but does not want anything +back +.It _IOWR +the call writes data to the kernel and wants information back. +.El +.It Ar t +This integer describes to which subsystem the ioctl applies. +.Ar t +can be one of +.Bl -tag -width xxxxx -compact +.It '1' +pulse-per-second interface +.It 'a' +ISO networking +.It 'A' +ac devices (hp300) +.It 'A' +Advanced Power Management (hpcmips, i386, sparc), see +.Xr apm 4 +.It 'A' +ADB devices (mac68k, macppc) +.It 'A' +.Xr audio 4 +.It 'b' +Bluetooth HCI sockets, see +.Xr bluetooth 4 +.It 'b' +Bluetooth Hub Control, see +.Xr bthub 4 +.It 'b' +Bluetooth SCO audio driver, see +.Xr btsco 4 +.It 'B' +bell device (x68k) +.It 'B' +.Xr bpf 4 +.It 'c' +coda +.It 'c' +.Xr \&cd 4 +.It 'c' +.Xr \&ch 4 +.It 'C' +clock devices (amiga, atari, hp300, x68k) +.It 'd' +the disk subsystem +.It 'E' +.Xr envsys 4 +.It 'f' +files +.It 'F' +Sun-compatible framebuffers +.It 'F' +.Xr ccd 4 +and +.Xr vnd 4 +.It 'g' +qdss framebuffers +.It 'G' +grf devices (amiga, atari, hp300, mac68k, x68k) +.It 'h' +HIL devices (hp300) +.It 'H' +HIL devices (hp300) +.It 'H' +HPc framebuffers +.It 'i' +a (pseudo) interface +.It 'I' +.Xr ite 4 +(mac68k) +.It 'J' +ISA joystick interface +.It 'k' +Sun-compatible (and other) keyboards +.It 'l' +leo devices (atari) +.It 'm' +.Xr mtio 4 +.It 'M' +mouse devices (atari) +.It 'M' +.Xr mlx 4 +.It 'n' +virtual console device (arm32) +.It 'n' +SMB networking +.It 'O' +OpenPROM and OpenFirmware +.It 'p' +power control (x68k) +.It 'P' +parallel port (amiga, x68k) +.It 'P' +profiling (arm32) +.It 'P' +printer/plotter interface (hp300) +.It 'P' +pci(4) +.It 'P' +compat/ossaudio and soundcard.h +.It 'P' +.Xr sparc/magma 4 +bpp (sparc) +.It 'q' +.Xr altq 9 +.It 'q' +pmax graphics devices +.It 'Q' +.Xr altq 9 +.It 'Q' +raw SCSI commands +.It 'r' +the routing subsystem +.It 'r' +.Xr \&md 4 +.It 'R' +.Xr rnd 4 +.It 's' +the socket layer +.It 'S' +SCSI disks (arc, hp300, pmax) +.It 'S' +watchdog devices (sh3) +.It 'S' +ISA speaker devices +.It 'S' +stic devices +.It 'S' +scanners +.It 't' +the tty layer +.It 'u' +user defined ??? +.It 'U' +scsibus (see +.Xr scsi 4 ) +.It 'v' +Sun-compatible +.Dq firm events +.It 'V' +view device (amiga, atari) +.It 'V' +sram device (x68k) +.It 'w' +watchdog devices +.It 'W' +wt devices +.It 'W' +wscons devices +.It 'x' +bt8xx devices +.It 'Z' +ite devices (amiga, atari, x68k) +.It 'Z' +passthrough ioctls +.El +.It Ar n +This numbers the ioctl within the group. +There may be only one +.Ar n +for a given +.Ar t . +This is an unsigned 8 bit number. +.It Ar pt +This specifies the type of the passed parameter. +This one gets internally transformed to the size of the parameter, so +for example, if you want to pass a structure, then you have to specify that +structure and not a pointer to it or sizeof(struct foo) +.El +.Pp +In order for the new ioctl to be known to the system it is installed +in either +.Aq Pa sys/ioctl.h +or one of the files that are reached from +.Aq Pa sys/ioctl.h . +.Sh RETURN VALUES +All +.Fn ioctl +routines should return either 0 or a defined error code. +The use of magic numbers such as \-1, to indicate that a given ioctl +code was not handled is strongly discouraged. +The value \-1 coincides with the historic value for +.Cm ERESTART +which was shown to produce user space code that never returned from +a call to +.Xr ioctl 2 . +.Pp +For ioctl codes that +are not handled by a given routine, the pseudo error value +.Cm EPASSTHROUGH +is provided. +.Cm EPASSTHROUGH +indicates that no error occurred during processing (it did not fail), +but neither was anything processed (it did not succeed). +This supersedes the use of either +.Cm ENOTTY +(which is an explicit failure) or \-1 (which has no contextual meaning) +as a return value. +.Cm ENOTTY +will get passed directly back to user space and bypass any further +processing by other ioctl layers. +Only code that wishes to suppress possible further processing of an +ioctl code (e.g., the tty line discipline code) should return +.Cm ENOTTY . +All other code should return +.Cm EPASSTHROUGH , +even if it knows that no other layers will be called upon. +.Pp +If the value +.Cm EPASSTHROUGH +is returned to +.Fn sys_ioctl , +then it will there be changed to +.Cm ENOTTY +to be returned to user space, thereby providing the proper error +notification to the application. +.Sh EXAMPLES +.Bd -literal -offset indent +#define FOOIOCTL _IOWR('i', 23, int) + +int a = 3; +error = ioctl(s, FOOIOCTL, &a); +.Ed +.Pp +Within the +.Fn ioctl Ns No -routine +of the driver, it can be then accessed like +.Bd -literal -offset indent +driver_ioctl(..., u_long cmd, void *data) +{ + ... + switch (cmd) { + + case FOOIOCTL: + int *a = (int *)data; + printf(" Value passed: %d\en", *a); + break; + } +} +.Ed +.Sh NOTES +Note that if you for example try to read information from an ethernet +driver where the name of the card is included in the third argument +(e.g., ioctl(s, READFROMETH, struct ifreq *)), then you have to use +the +.Fn _IOWR +form not the +.Fn _IOR , +as passing the name of the card to the +kernel already consists of writing data. +.Sh SEE ALSO +.Xr ioctl 2 diff --git a/static/netbsd/man9/ipi.9 b/static/netbsd/man9/ipi.9 new file mode 100644 index 00000000..9410db4a --- /dev/null +++ b/static/netbsd/man9/ipi.9 @@ -0,0 +1,217 @@ +.\" $NetBSD: ipi.9,v 1.6 2022/02/12 01:21:11 riastradh Exp $ +.\" +.\" Copyright (c) 2014, 2019 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Mindaugas Rasiukevicius. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 31, 2019 +.Dt IPI 9 +.Os +.Sh NAME +.Nm ipi +.Nd machine-independent interprocessor interrupts +.Sh SYNOPSIS +.In sys/ipi.h +.Vt typedef void (*ipi_func_t)(void *); +.\" ----- +.Ft u_int +.Fn ipi_register "ipi_func_t func" "void *arg" +.Ft void +.Fn ipi_unregister "u_int ipi_id" +.Ft void +.Fn ipi_trigger "u_int ipi_id" "struct cpu_info *ci" +.Ft void +.Fn ipi_trigger_multi "u_int ipi_id" "const kcpuset_t *target" +.Ft void +.Fn ipi_trigger_broadcast "u_int ipi_id" "bool skip_self" +.\" ----- +.Ft void +.Fn ipi_unicast "ipi_msg_t *msg" "struct cpu_info *ci" +.Ft void +.Fn ipi_multicast "ipi_msg_t *msg" "const kcpuset_t *target" +.Ft void +.Fn ipi_broadcast "ipi_msg_t *msg" "bool skip_self" +.Ft void +.Fn ipi_wait "ipi_msg_t *msg" +.\" ----- +.Sh DESCRIPTION +The machine-independent +.Nm +interface provides capability to send inter-processor interrupts (IPIs) +amongst CPUs. +The interface has two mechanisms: asynchronous IPI to invoke functions +with a constant argument and synchronous IPIs with the cross-call support. +.Pp +Other synchronization interfaces are built using the MI IPI interface. +For a general purpose inter-processor cross-calls or remote +interrupts, use the +.Xr xcall 9 +or +.Xr softint 9 +interfaces. +.Pp +The primary use cases of the MI IPIs include the following: +.Bl -hyphen -compact +.It +provide a facility for the +.Xr softint 9 +subsystem to schedule software interrupts on remote CPUs +.It +provide a facility for the +.Xr xcall 9 +subsystem +.It +abstract IPI handling and facilitate machine-dependent code +.El +.\" ----- +.Ss Asynchronous IPI interface +This interface allows dynamic registration of IPI handlers with a constant +argument and asynchronous triggering of interrupts. +.Bl -tag -width compact +.It Fn ipi_register "func" "arg" +Register an IPI handler +.Fa func +with an arbitrary argument +.Fa arg . +Returns a non-zero IPI identifier on success and zero on failure. +.It Fn ipi_unregister "ipi_id" +Unregister the IPI handler identified by the +.Fa ipi_id . +.It Fn ipi_trigger "ipi_id" "ci" +Trigger an IPI identified by +.Fa ipi_id +on a remote CPU specified by +.Fa ci . +This function must be called with kernel preemption disabled and +the target CPU must be remote. +.It Fn ipi_trigger_multi "ipi_id" "target" +Trigger an IPI identified by +.Fa ipi_id +on all of the CPUs in the set specified by +.Fa target . +This function must be called with kernel preemption disabled. +The sending CPU may be included in the CPU set; when this is the case, +the IPI on the sending CPU is processes synchronously. +.It Fn ipi_trigger_broadcast "ipi_id" "skip_self" +Trigger an IPI identified by +.Fa ipi_id +on all of the attached CPUs. +This function must be called with kernel preemption disabled. +Optionally, the sending CPU may be skipped by passing +.Dv true +for +.Fa skip_self . +.El +.\" ----- +.Ss Synchronous IPI interface +This interface provides capability to perform cross-calls, i.e. invoke +an arbitrary function on a remote CPU. +The invocations are performed synchronously and the caller must wait +for completion. +The cross-call is described by an IPI "message". +The caller has to fill in an +.Vt ipi_msg_t +structure which has the following public members: +.Bd -literal + ipi_func_t func; + void arg; +.Ed +.Pp +The +.Ar func +member specifies a function to invoke and +.Ar arg +is the argument to be passed to the function. +.Bl -tag -width compact +.It Fn ipi_unicast "msg" "ci" +Send an IPI to a remote CPU specified by +.Fa ci . +.It Fn ipi_multicast "msg" "target" +Send IPIs to a CPU set specified by +.Fa target . +.It Fn ipi_broadcast "msg" "skip_self" +Send IPIs to all CPUs. +Optionally, the sending CPU may be skipped by passing +.Dv true +for +.Fa skip_self . +.It Fn ipi_wait "msg" +Wait until all IPIs complete. +.El +.Pp +All described functions, except +.Fn ipi_wait , +must be called with the kernel preemption disabled. +All synchronous IPI invocations must be completed (wait for them with the +.Fn ipi_wait +function) before the IPI message structure can be destroyed or new +cross-call requests can be performed. +.\" ----- +.Sh MEMORY ORDER +All memory operations that happen before triggering an IPI, via +.Fn ipi_trigger , +.Fn ipi_trigger_multi , +.Fn ipi_trigger_broadcast , +.Fn ipi_unicast , +.Fn ipi_multicast , +or +.Fn ipi_broadcast , +also happen before any memory operations in the IPI handler function on +the remote CPU. +.Pp +For synchronous IPIs, all memory operations that happen before the IPI +handler function has returned on the remote CPU also happen before +.Fn ipi_wait +returns on the waiting CPU. +.\" ----- +.Sh NOTES +Functions being called must be lightweight. +They run at +.Dv IPL_HIGH +and should generally not use any other synchronization interfaces +such as +.Xr mutex 9 . +If spin-locks are used, they must be used carefully and have no contention. +.\" ----- +.Sh CODE REFERENCES +The +.Nm +interface is implemented within the file +.Pa sys/kern/subr_ipi.c . +.\" ----- +.Sh SEE ALSO +.Xr kcpuset 9 , +.Xr kpreempt 9 , +.Xr softint 9 , +.Xr spl 9 , +.Xr xcall 9 +.Sh HISTORY +The +.Nm +interface first appeared in +.Nx 7.0 . +.Sh AUTHORS +.An Mindaugas Rasiukevicius Aq Mt rmind@NetBSD.org diff --git a/static/netbsd/man9/isa.9 b/static/netbsd/man9/isa.9 new file mode 100644 index 00000000..caf2b5ca --- /dev/null +++ b/static/netbsd/man9/isa.9 @@ -0,0 +1,501 @@ +.\" $NetBSD: isa.9,v 1.20 2011/05/30 01:48:40 dyoung Exp $ +.\" +.\" Copyright (c) 2001, 2005, 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 29, 2006 +.Dt ISA 9 +.Os +.Sh NAME +.Nm ISA , +.Nm isa_intr_alloc , +.Nm isa_intr_establish , +.Nm isa_intr_disestablish , +.Nm isa_intr_evcnt , +.Nm isa_dmamap_create , +.Nm isa_dmamap_destroy , +.Nm isa_dmamem_alloc , +.Nm isa_dmamem_free , +.Nm isa_dmamem_map , +.Nm isa_dmamem_unmap , +.Nm isa_malloc , +.Nm isa_free , +.Nm isa_dmastart , +.Nm isa_dmaabort , +.Nm isa_dmacount , +.Nm isa_dmadone , +.Nm isa_dmamaxsize , +.Nm isa_drq_alloc , +.Nm isa_drq_free , +.Nm isa_drq_isfree , +.Nm isa_dmacascade , +.Nm isa_mappage +.Nd Industry-standard Architecture +.Sh SYNOPSIS +.In sys/bus.h +.In dev/isa/isareg.h +.In dev/isa/isavar.h +.Ft int +.Fn isa_intr_alloc "isa_chipset_tag_t ic" "int mask" "int type" \ +"int *irq" +.Ft const struct evcnt * +.Fn isa_intr_evcnt "isa_chipset_tag_t ic" "int irq" +.Ft void * +.Fn isa_intr_establish "isa_chipset_tag_t ic" "int irq" "int type" \ +"int level" "int (*handler)(void *)" "void *arg" +.Ft void +.Fn isa_intr_disestablish "isa_chipset_tag_t ic" "void *ih" +.In dev/isa/isadmareg.h +.In dev/isa/isadmavar.h +.Ft int +.Fn isa_dmamap_create "isa_chipset_tag_t ic" "int chan" "bus_size_t size" \ +"int flags" +.Ft void +.Fn isa_dmamap_destroy "isa_chipset_tag_t ic" "int chan" +.Ft int +.Fn isa_dmamem_alloc "isa_chipset_tag_t ic" "int chan" "bus_size_t size" \ +"bus_addr_t *addrp" "int flags" +.Ft void +.Fn isa_dmamem_free "isa_chipset_tag_t ic" "int chan" "bus_addr_t addr" \ +"bus_size_t size" +.Ft int +.Fn isa_dmamem_map "isa_chipset_tag_t ic" "int chan" "bus_addr_t addr" \ +"bus_size_t size" "void **kvap" "int flags" +.Ft void +.Fn isa_dmamem_unmap "isa_chipset_tag_t ic" "int chan" "void *kva" \ +"size_t size" +.Ft void * +.Fn isa_malloc "isa_chipset_tag_t ic" "int chan" "size_t size" \ +"int pool" "int flags" +.Ft void +.Fn isa_free "void *addrp" "int pool" +.Ft int +.Fn isa_dmastart "isa_chipset_tag_t ic" "int chan" "bus_addr_t addr" \ +"bus_size_t size" "struct lwp *lwp" "int flags" "int bf" +.Ft void +.Fn isa_dmaabort "isa_chipset_tag_t ic" "int chan" +.Ft bus_size_t +.Fn isa_dmacount "isa_chipset_tag_t ic" "int chan" +.Ft void +.Fn isa_dmadone "isa_chipset_tag_t ic" "int chan" +.Ft bus_size_t +.Fn isa_dmamaxsize "isa_chipset_tag_t ic" "int chan" +.Ft int +.Fn isa_drq_alloc "isa_chipset_tag_t ic" "int chan" +.Ft int +.Fn isa_drq_free "isa_chipset_tag_t ic" "int chan" +.Ft int +.Fn isa_drq_isfree "isa_chipset_tag_t ic" "int chan" +.Ft int +.Fn isa_dmacascade "isa_chipset_tag_t ic" "int chan" +.Ft paddr_t +.Fn isa_mappage "void *mem" "off_t offset" "int prot" +.Sh DESCRIPTION +The machine-independent +.Nm +subsystem provides support for the ISA bus. +.Pp +The ISA bus was introduced on the IBM PC/AT. +It is an extension to the original bus found on the original IBM PC. +The ISA bus is essentially the host bus of the Intel 80286 processor, +however the widespread acceptance of the bus as a de facto standard has +seen it appear on systems without Intel processors. +.Pp +The ISA bus has a 16-bit data bus, a 24-bit memory address bus, a +16-bit I/O address bus, and operates at 8MHz. +It provides 15 interrupt lines and 8 DMA channels supporting DMA transfers +of 64KB or 128KB transfers depending on the width of the channel being used. +Historically, some devices only decoded the 10 lowest bits of +the I/O address bus, preventing use of the full 16-bit address space. +.Pp +On newer machines, the ISA bus is no longer connected directly to the +host bus, and is usually connected via a PCI-ISA bridge. +Either way, the bus looks the same to the device driver. +.Sh DATA TYPES +Drivers for devices attached to the +.Nm +bus will make use of the following data types: +.Bl -tag -width compact +.It Fa isa_chipset_tag_t +Chipset tag for the ISA bus. +.It Fa struct isa_attach_args +Location hints for devices are recorded in this structure. +It contains the following members: +.Bd -literal + bus_space_tag_t ia_iot; /* isa i/o space tag */ + bus_space_tag_t ia_memt; /* isa mem space tag */ + bus_dma_tag_t ia_dmat; /* DMA tag */ + isa_chipset_tag_t ia_ic; + int ia_iobase; /* base i/o address */ + int ia_iosize; /* span of ports used */ + int ia_maddr; /* physical mem addr */ + u_int ia_msize; /* size of memory */ + int ia_irq; /* interrupt request */ + int ia_drq; /* DMA request */ + int ia_drq2; /* second DMA request */ + void *ia_aux; /* driver specific */ +.Ed +.El +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn isa_intr_alloc "ic" "mask" "type" "irq" +This function is generally not required by device drivers. +It is used by bridges attaching other busses to the ISA bus. +.It Fn isa_intr_evcnt "ic" "irq" +Returns the event counter associated with interrupt line +.Fa irq . +.It Fn isa_intr_establish "ic" "irq" "type" "level" "handler" "arg" +To establish an ISA interrupt handler, a driver calls +.Fn isa_intr_establish +with the interrupt number +.Fa irq , +type +.Fa type , +and level +.Fa level . +When the interrupt occurs the function +.Fa handler +is called with argument +.Fa arg . +Valid values for +.Fa type +are: +.Bl -tag -width compact +.It IST_NONE +Reserve interrupt, but don't actually establish. +.It IST_EDGE +Edge-triggered interrupt. +.It IST_LEVEL +Level-triggered interrupt. +.It IST_PULSE +Pulse-triggered interrupt. +.El +.Pp +.Fn isa_intr_establish +returns an opaque handle to an event descriptor if it succeeds, and +returns NULL on failure. +.Pp +.It Fn isa_intr_disestablish "ic" "ih" +Dis-establish the interrupt handler with handle +.Fa ih . +The handle was returned from +.Fn isa_intr_establish . +.It Fn isa_drq_alloc "ic" "chan" +Reserves the DMA channel +.Fa chan +for future use. +Normally, this call precedes an +.Fn isa_dmamap_create +call. +It is an error to start DMA on a channel that has not been reserved with +.Fn isa_drq_alloc . +.It Fn isa_drq_free "ic" "chan" +Marks the DMA channel +.Fa chan +as available again. +.It Fn isa_dmamap_create "ic" "chan" "size" "flags" +Creates a DMA map for channel +.Fa chan . +It is initialised to accept maximum DMA transfers of size +.Fa size . +Valid values for the +.Fa flags +argument are the same as for +.Fn bus_dmamap_create +(see +.Xr bus_dma 9 ) . +This function returns zero on success or an error value on failure. +.It Fn isa_dmamap_destroy "ic" "chan" +Destroy the DMA map for DMA channel +.Fa chan . +.It Fn isa_dmamem_alloc "ic" "chan" "size" "addrp" "flags" +Allocate DMA-safe memory of size +.Fa size +for channel +.Fa chan . +Valid values for the +.Fa flags +argument are the same as for +.Fn bus_dmamem_alloc +(see +.Xr bus_dma 9 ) . +The bus-address of the memory is returned in +.Fa addrp . +This function returns zero on success or an error value on failure. +.It Fn isa_dmamem_free "ic" "chan" "addr" "size" +Frees memory previously allocated by +.Fn isa_dmamem_alloc +for channel +.Fa chan . +The bus-address and size of the memory are specified by +.Fa addr +and +.Fa size +respectively. +.It Fn isa_dmamem_map "ic" "chan" "addr" "size" "kvap" "flags" +Maps DMA-safe memory (allocated with +.Fn isa_dmamem_alloc ) +specified by bus-address +.Fa addr +and of size +.Fa size +into kernel virtual address space for DMA channel +.Fa chan . +Valid values for the +.Fa flags +argument are the same as for +.Fn bus_dmamem_map +(see +.Xr bus_dma 9 ) . +The kernel virtual address is returned in +.Fa kvap . +This function returns zero on success or an error value on failure. +.It Fn isa_dmamem_unmap "ic" "chan" "kva" "size" +Unmaps memory (previously mapped with +.Fn isa_dmamem_map ) +of size +.Fa size +for channel +.Fa chan . +The kernel virtual address space used by the mapping is freed. +.It Fn isa_malloc "ic" "chan" "size" "pool" "flags" +This function is a shortcut for allocating and mapping DMA-safe memory +in a single step. +The arguments correspond with the arguments to +.Fn isa_dmamem_alloc +and +.Fn isa_dmamem_map . +The argument +.Fa pool +is a pool to record the memory allocation. +This function returns a pointer to the DMA-safe memory. +.It Fn isa_free "addrp" "pool" +This function is a shortcut for unmapping and deallocating DMA-safe +memory in a single step. +It replaces +.Fn isa_dmamem_unmap +and +.Fn isa_dmamem_free . +The argument +.Fa addrp +is the pointer to the DMA-safe memory returned by +.Fn isa_malloc . +The argument +.Fa pool +is the same as the value passed to +.Fn isa_malloc . +.It Fn isa_dmastart "ic" "chan" "addr" "size" "lwp" "flags" "bf" +Load DMA memory specified by address +.Fa addr +of size +.Fa size +into the DMA controller at channel +.Fa chan +and set it in motion. +The argument +.Fa lwp +is used to indicate the address space in which the buffer is located. +If NULL, the buffer is assumed to be in kernel space. +Otherwise, the buffer is assumed to be in lwp +.Fa lwp 's +address space. +The argument +.Fa flags +describes the type of ISA DMA. +Valid values are: +.Bl -tag -width compact +.It DMAMODE_WRITE +DMA transfer from host to device. +.It DMAMODE_READ +DMA transfer to host from device. +.It DMAMODE_SINGLE +Transfer buffer once and stop. +.It DMAMODE_DEMAND +Demand mode. +.It DMAMODE_LOOP +Transfer buffer continuously in loop until notified to stop. +.It DMAMODE_LOOPDEMAND +Transfer buffer continuously in loop and demand mode. +.El +.Pp +The argument +.Fa bf +is the bus-space flags. +Valid values are the same as for +.Fn bus_dmamap_load +(see +.Xr bus_dma 9 ) . +.It Fn isa_dmaabort "ic" "chan" +Abort a DMA transfer on channel +.Fa chan . +.It Fn isa_dmacount "ic" "chan" +Returns the offset in the DMA memory of the current DMA transfer on +channel +.Fa chan . +.It Fn isa_dmadone "ic" "chan" +Unloads the DMA memory +on channel +.Fa chan +after a DMA transfer has completed. +.It Fn isa_dmamaxsize "ic" "chan" +Returns the maximum allowable DMA transfer size for channel +.Fa chan . +.It Fn isa_drq_isfree "ic" "chan" +If the +.Fa ia_drq +or +.Fa ia_drq2 +members of +.Fa struct isa_attach_args +are wildcarded, then the driver is expected to probe the hardware for +valid DMA channels. +In this case, the driver can check to see if the hardware-supported +DMA channel +.Fa chan +is available for use. +.It Fn isa_dmacascade "ic" "chan" +Programs the 8237 DMA controller channel +.Fa chan +to accept external DMA control by the device hardware. +.It Fn isa_mappage "mem" "offset" "prot" +Provides support for user +.Xr mmap 2 Ns 'ing +of DMA-safe memory. +.El +.Sh AUTOCONFIGURATION +The ISA bus is an indirect-connection bus. +During autoconfiguration each driver is required to probe the bus +for the presence of a device. +An ISA driver will receive a pointer to +.Fa struct isa_attach_args +hinting at "locations" on the ISA bus where the device may be located. +They should use the +.Em ia_iobase , +.Em ia_iosize , +.Em ia_maddr , +and +.Em ia_msize +members. +Not all of these hints will be necessary; locators may be wildcarded +with IOBASEUNK and MADDRUNK for +.Em ia_iobase +and +.Em ia_maddr +respectively. +If a driver can probe the device for configuration information at default +locations, it may update the members of +.Fa struct isa_attach_args . +The IRQ and DMA locators can also be wildcarded with IRQUNK and DRQUNK +respectively. +.Pp +During the driver attach step, the I/O and memory address spaces +should be mapped (see +.Xr bus_space 9 ) . +.Sh DMA SUPPORT +Extensive DMA facilities are provided for the ISA bus. +A driver can use up to two DMA channels simultaneously. +The DMA channels allocated during autoconfiguration are passed to the +driver during the driver attach using the +.Fa ia_drq +and +.Fa ia_drq2 +members of +.Fa struct isa_attach_args . +.Pp +Before allocating resources for DMA transfers on the ISA bus, a driver +should check the maximum allowable DMA transfer size for the DMA +channel using +.Fn isa_dmamaxsize . +.Pp +A DMA map should be created first using +.Fn isa_dmamap_create . +A DMA map describes how DMA memory is loaded into the DMA controllers. +Only DMA-safe memory can be used for DMA transfers. +DMA-safe memory is allocated using +.Fn isa_dmamem_alloc . +The memory allocated by +.Fn isa_dmamem_alloc +must now be mapped into kernel virtual address space by +.Fn isa_dmamem_map +so that it can be accessed by the driver. +.Pp +For a DMA transfer from the host to the device, the driver will fill +the DMA memory with the data to be transferred. +The DMA-transfer of the memory is started using +.Fn isa_dmastart +with +.Fa flags +containing DMAMODE_WRITE. +When the DMA transfer is completed, a call to +.Fn isa_dmadone +cleans up the DMA transfer by unloading the memory from the +controller. +.Pp +For a DMA transfer from the device to the host, the DMA-transfer is +started using +.Fn isa_dmastart +with +.Fa flags +containing DMAMODE_READ. +When the DMA transfer is completed, a call to +.Fn isa_dmadone +cleans up the DMA transfer by unloading the memory from the +controller. +The memory can now be access by the driver. +.Pp +When the DMA resources are no longer required they should be released +using +.Fn isa_dmamem_unmap , +.Fn isa_dmamem_free +and +.Fn isa_dmamap_destroy . +.Sh CODE REFERENCES +The ISA subsystem itself is implemented within the files +.Pa sys/dev/isa/isa.c +and +.Pa sys/dev/isa/isadma.c . +.Sh SEE ALSO +.Xr isa 4 , +.Xr autoconf 9 , +.Xr bus_dma 9 , +.Xr bus_space 9 , +.Xr driver 9 , +.Xr isapnp 9 +.Sh HISTORY +The machine-independent +.Nm +subsystem appeared in +.Nx 1.2 . +.Sh BUGS +The previous behaviour of +.Fn isa_intr_establish +was to invoke +.Fn panic +on failure. +.Fn isa_intr_establish +now returns NULL on failure. +Some old drivers written for the former behaviour discard the return value. diff --git a/static/netbsd/man9/isapnp.9 b/static/netbsd/man9/isapnp.9 new file mode 100644 index 00000000..8d6d6f30 --- /dev/null +++ b/static/netbsd/man9/isapnp.9 @@ -0,0 +1,239 @@ +.\" $NetBSD: isapnp.9,v 1.12 2011/05/30 01:50:07 dyoung Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 19, 2001 +.Dt ISAPNP 9 +.Os +.Sh NAME +.Nm ISAPNP , +.Nm isapnp_devmatch , +.Nm isapnp_config , +.Nm isapnp_unconfig +.Nd Plug 'n' Play ISA bus +.Sh SYNOPSIS +.In sys/bus.h +.In dev/isa/isareg.h +.In dev/isa/isavar.h +.In dev/isapnp/isapnpreg.h +.In dev/isapnp/isapnpvar.h +.In dev/isapnp/isapnpdevs.h +.Ft int +.Fn isapnp_devmatch "const struct isapnp_attach_args *ipa" \ +"const struct isapnp_devinfo *dinfo" "int *variant" +.Ft int +.Fn isapnp_config "bus_space_tag_t iot" "bus_space_tag_t memt" \ +"struct isapnp_attach_args *ipa" +.Ft void +.Fn isapnp_unconfig "bus_space_tag_t iot" "bus_space_tag_t memt" \ +"struct isapnp_attach_args *ipa" +.Sh DESCRIPTION +The machine-independent +.Nm +subsystem provides support for ISAPNP devices. +ISAPNP devices were developed to support "plug and play" connection +on the ISA bus. +In all other aspects, the ISAPNP bus is same as the ISA bus (see +.Xr isa 9 ) . +.Pp +Devices on the ISAPNP bus are uniquely identified by a 7-character +string. +Resources, such as I/O address space and interrupts, should +be allocated to the devices by the machine firmware. +On some machine the firmware seems doesn't work correctly and +.Nx +will attempt to allocate resources as necessary. +.Sh DATA TYPES +Drivers attached to the ISAPNP bus will make use of the following data +types: +.Bl -tag -width compact +.It Fa struct isapnp_matchinfo +.Nx +kernel contains a database of known ISAPNP devices. +Each entry in the database has a +.Em struct isapnp_matchinfo . +It contains the following members: +.Bd -literal + const char *name; /* device id string */ + int variant; /* variant flag */ +.Ed +.It Fa struct isapnp_devinfo +Defines the devices supported by a driver. +It contains pointer to an array of supported +.Em struct isapnp_matchinfo +structures and a pointer to another array of compatibility devices. +It contains the following members: +.Bd -literal + struct isapnp_matchinfo *devlogic; + int nlogic; + struct isapnp_matchinfo *devcompat; + int ncompat; +.Ed +.It Fa struct isapnp_region +Describes ISAPNP bus-space regions. +It contains the following members: +.Bd -literal + bus_space_handle_t h; + uint32_t base; + uint32_t length; +.Ed +.It Fa struct isapnp_pin +Describes the wiring of interrupts and DMA pins from the ISAPNP bus +onto the host processor. +It contains the following members: +.Bd -literal + uint8_t num; + uint8_t flags:4; + uint8_t type:4; + uint16_t bits; +.Ed +.It Fa struct isapnp_attach_args +A structure used to inform the driver of the device properties. +It contains the following members: +.Bd -literal + bus_space_tag_t ipa_iot; /* isa i/o space tag */ + bus_space_tag_t ipa_memt; /* isa mem space tag */ + bus_dma_tag_t ipa_dmat; /* isa dma tag */ + isa_chipset_tag_t ipa_ic; + struct isapnp_region ipa_io[ISAPNP_NUM_IO]; + struct isapnp_region ipa_mem[ISAPNP_NUM_MEM]; + struct isapnp_region ipa_mem32[ISAPNP_NUM_MEM32]; + struct isapnp_pin ipa_irq[ISAPNP_NUM_IRQ]; + struct isapnp_pin ipa_drq[ISAPNP_NUM_DRQ]; +.Ed +.El +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn isapnp_devmatch "ipa" "dinfo" "variant" +Matches the device described by the attachment +.Fa ipa +with the device-match information in +.Fa dinfo . +If the device is matched, +.Fn isapnp_devmatch +returns a non-zero value and variant is the flag describing the device +variant. +.Fn isapnp_devmatch +returns zero if the device is not found. +.It Fn isapnp_config "iot" "memt" "ipa" +Allocate device resources specified by +.Fa ipa . +The device is mapped into the I/O and memory bus spaces specified by +bus-space tags +.Fa iot +and +.Fa memt +respectively. +The +.Fa ipa_io , +.Fa ipa_mem , +.Fa ipa_mem32 , +.Fa ipa_irq , +and +.Fa ipa_drq +members of +.Fa ipa +are updated to reflect the allocated and mapped resources. +.Fn isapnp_config +returns zero on success and non-zero on error. +.It Fn isapnp_unconfig "iot" "memt" "ipa" +Free the resources allocated by +.Fn isapnp_config . +.El +.Sh AUTOCONFIGURATION +During autoconfiguration, an ISAPNP driver will receive a pointer to +.Fa struct isapnp_attach_args +describing the device attached to the ISAPNP bus. +Drivers match the device using +.Fn ispnp_devmatch . +.Pp +During the driver attach step, driver should initially allocate and +map resources using +.Fn isapnp_config . +The I/O (memory) bus-space resources can be accessed using the +bus-space tag +.Fa ipa_iot +.Po +.Fa ipa_memt +.Pc +and the bus-space handle +.Fa ipa_io[0].h +.Po +.Fa ipa_mem[0].h +.Pc +members of +.Fa ipa . +.Pp +Interrupts should be established using +.Fn isa_intr_establish +.Po +see +.Xr isa 9 +.Pc +with the IRQ specified by the +.Fa ipa_irq[0].num +member of +.Fa ipa . +Similarly, the standard +.Xr isa 9 +DMA interface should be used with the +.Fa ipa_drq[0].num +member of +.Fa ipa . +.Sh DMA SUPPORT +Extensive DMA facilities are provided through the +.Xr isa 9 +DMA facilities. +.Sh CODE REFERENCES +The +.Nm +subsystem itself is implemented within the file +.Pa sys/dev/isapnp/isapnp.c . +The database of the known devices exists within the file +.Pa sys/dev/isapnp/isapnpdevs.c +and is generated automatically from the file +.Pa sys/dev/isapnp/isapnpdevs . +New devices should be added to this file. +The database can be regenerated using the Makefile +.Pa sys/dev/isapnp/Makefile.isapnpdevs . +.Sh SEE ALSO +.Xr isa 4 , +.Xr isapnp 4 , +.Xr pnpbios 4 , +.Xr autoconf 9 , +.Xr bus_dma 9 , +.Xr bus_space 9 , +.Xr driver 9 , +.Xr isa 9 +.Rs +.%T "Plug and Play ISA Specification V1.0a" +.%D May 5 1994 +.Re +.Sh HISTORY +The machine-independent ISAPNP subsystem appear in +.Nx 1.3 . diff --git a/static/netbsd/man9/itimerfix.9 b/static/netbsd/man9/itimerfix.9 new file mode 100644 index 00000000..27cc8534 --- /dev/null +++ b/static/netbsd/man9/itimerfix.9 @@ -0,0 +1,63 @@ +.\" $NetBSD: itimerfix.9,v 1.8 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 23, 2001 +.Dt ITIMERFIX 9 +.Os +.Sh NAME +.Nm itimerfix +.Nd check that a timeval value is valid, and correct +.Sh SYNOPSIS +.In sys/time.h +.Ft int +.Fn itimerfix "struct timeval *tv" +.Sh DESCRIPTION +The +.Nm +function checks that the value in +.Fa tv +is valid (0 \*[Le] tv->tv_sec && 0 \*[Le] tv->tv_usec < 1000000), and that the +total time represented is at least one +.Em tick , +or zero. +.Pp +If the total represented time is nonzero and smaller than tick, +it is adjusted to exactly one tick. +.Sh RETURN VALUES +.Nm +returns 0 on success or +.Er EINVAL +if +.Fa tv +is invalid. +.Sh SEE ALSO +.Xr nanosleep 2 , +.Xr poll 2 , +.Xr select 2 , +.Xr setitimer 2 diff --git a/static/netbsd/man9/kauth.9 b/static/netbsd/man9/kauth.9 new file mode 100644 index 00000000..575b1dca --- /dev/null +++ b/static/netbsd/man9/kauth.9 @@ -0,0 +1,2048 @@ +.\" $NetBSD: kauth.9,v 1.115 2025/07/01 11:46:42 bad Exp $ +.\" +.\" Copyright (c) 2005, 2006 Elad Efrat <elad@NetBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd Jul 1, 2025 +.Dt KAUTH 9 +.Os +.Sh NAME +.Nm kauth +.Nd kernel authorization framework +.Sh SYNOPSIS +.In sys/kauth.h +.Sh DESCRIPTION +.Nm , +or kernel authorization, is the subsystem managing all authorization requests +inside the kernel. +It manages user credentials and rights, and can be used +to implement a system-wide security policy. +It allows external modules to plug-in the authorization process. +.Pp +.Nm +introduces some new concepts, namely +.Dq scopes +and +.Dq listeners , +which will be detailed together with other useful information for kernel +developers in this document. +.Ss Types +Some +.Nm +types include the following: +.Bl -tag -width kauth_listener_t +.It kauth_cred_t +Representing credentials that can be associated with an object. +Includes user- and group-ids (real, effective, and save) as well as group +membership information. +.It kauth_scope_t +Describes a scope. +.It kauth_listener_t +Describes a listener. +.El +.Ss Terminology +.Nm +operates in various +.Dq scopes , +each scope holding a group of +.Dq listeners . +.Pp +Each listener works as a callback for when an authorization request within the +scope is made. +When such a request is made, all listeners on the scope are passed common +information such as the credentials of the request context, an identifier for +the requested operation, and possibly other information as well. +.Pp +Every listener examines the passed information and returns its decision +regarding the requested operation. +It can either return: +.Pp +.Bl -tag -width KAUTH_RESULT_ALLOW -compact +.It Dv KAUTH_RESULT_ALLOW +The listener allows the operation. +.It Dv KAUTH_RESULT_DENY +The listener denies the operation. +.It Dv KAUTH_RESULT_DEFER +The listener defers the decision to other listeners. +.El +.Pp +For an operation to be allowed, at least one listener has to return +.Dv KAUTH_RESULT_ALLOW +while no other listener returned +.Dv KAUTH_RESULT_DENY . +.Pp +Scopes manage listeners that operate in the same aspect of the system. +.Ss Kernel Programming Interface +.Nm +exports a KPI that allows developers both of +.Nx +and third-party products to authorize requests, access and modify credentials, +create and remove scopes and listeners, and perform other miscellaneous operations on +credentials. +.Ss Authorization Requests +.Nm +provides a single authorization request routine, which all authorization +requests go through. +This routine dispatches the request to the listeners of the appropriate scope, +together with four optional user-data variables, and returns the augmented +result. +.Pp +It is declared as +.Pp +.Ft int Fn kauth_authorize_action "kauth_scope_t scope" "kauth_cred_t cred" \ +"kauth_action_t op" "void *arg0" "void *arg1" "void *arg2" "void *arg3" +.Pp +An authorization request can return one of two possible values: +.Bl -tag -width ".It Dv 0 Po zero Pc" -compact +.It Dv 0 Po zero Pc +indicates success; operation is allowed. +.It Dv EPERM +indicates failure; operation is denied. +See +.Xr errno 2 . +.El +.Pp +Each scope has its own authorization wrapper, to make it easy to call from various +places by eliminating the need to specify the scope and/or cast values. +The authorization wrappers are detailed in each scope's section. +.Pp +.Fn kauth_authorize_action +has several special cases, when it will always allow the request. +These are for when the request is issued by the kernel itself (indicated by the +credentials being either +.Dv NOCRED +or +.Dv FSCRED ) , +or when there was no definitive decision from any of the listeners (i.e., it +was not explicitly allowed or denied) and no security model was loaded. +.Ss Generic Scope +The generic scope, +.Dq org.netbsd.kauth.generic , +manages generic authorization requests in the kernel. +.Pp +The authorization wrapper for this scope is declared as +.Pp +.Ft int Fn kauth_authorize_generic "kauth_cred_t cred" "kauth_action_t op" \ +"void *arg0" +.Pp +The following operations are available for this scope: +.Bl -tag -width compact +.It Dv KAUTH_GENERIC_ISSUSER +Checks whether the credentials belong to the super-user. +.Pp +Using this request is strongly discouraged and should only be done as a +temporary place-holder, as it is breaking the separation between the +interface for authorization requests from the back-end implementation. +.El +.Ss System Scope +The system scope, +.Dq org.netbsd.kauth.system , +manages authorization requests affecting the entire system. +.Pp +The authorization wrapper for this scope is declared as +.Pp +.Ft int Fn kauth_authorize_system "kauth_cred_t cred" \ +"kauth_action_t op" "enum kauth_system_req req" "void *arg1" "void *arg2" \ +"void *arg3" +.Pp +The following requests are available for this scope: +.Bl -tag -width compact +.It Dv KAUTH_SYSTEM_ACCOUNTING +Check if enabling/disabling accounting allowed. +.It Dv KAUTH_SYSTEM_CHROOT +.Ar req +can be any of the following: +.Bl -tag -width compact +.It Dv KAUTH_REQ_SYSTEM_CHROOT_CHROOT +Check if calling +.Xr chroot 2 +is allowed. +.It Dv KAUTH_REQ_SYSTEM_CHROOT_FCHROOT +Check if calling +.Xr fchroot 2 +is allowed. +.El +.It Dv KAUTH_SYSTEM_CPU +Check CPU-manipulation access. +.Pp +.Ar req +can be any of the following: +.Bl -tag -width compact +.It Dv KAUTH_REQ_SYSTEM_CPU_SETSTATE +Set CPU state, including setting it online or offline. +.El +.It Dv KAUTH_SYSTEM_DEBUG +This request concentrates several debugging-related operations. +.It Dv KAUTH_SYSTEM_DEVMAPPER +Check if operations on the device mapper +.Xr dm 4 +device are allowed. +.It Dv KAUTH_SYSTEM_FILEHANDLE +Check if file handle operations allowed. +.It Dv KAUTH_SYSTEM_FS_EXTATTR +Check if starting, stopping, enabling, or disabling extended attributes +is allowed. +.Ar arg1 +is a +.Ft struct mount * +of the mount-point on which the operation is performed. +.It Dv KAUTH_SYSTEM_FS_SNAPSHOT +Check if setting up a file system snapshot is allowed. +.Ar arg1 +is a +.Ft struct mount * +of the mount-point of which the snapshot is taken, and +.Ar arg2 +is a +.Ft struct vnode * +of the vnode where the snapshot is expected to be. +.It Dv KAUTH_SYSTEM_FS_QUOTA +Check if file system quota operations are allowed. +.Pp +.Ar arg1 +is a +.Ft struct mount * +describing the file system mount in question. +.Ar req +can be one of the following: +.Bl -tag -width compact +.It Dv KAUTH_REQ_SYSTEM_FS_QUOTA_GET +Check if retrieving quota information is allowed. +.Pp +.Ar arg2 +is a +.Ft uid_t +with the user-id of the user whose quota information is to be retrieved. +.It Dv KAUTH_REQ_SYSTEM_FS_QUOTA_ONOFF +Check if turning quota on/off is allowed. +.It Dv KAUTH_REQ_SYSTEM_FS_QUOTA_MANAGE +Check if managing the quota by setting the quota/quota use is allowed. +.Pp +.Ar arg2 +is a +.Ft uid_t +with the user-id of the user whose quota/quota use is to be set. +.It Dv KAUTH_REQ_SYSTEM_FS_QUOTA_NOLIMIT +Check if bypassing the quota (not enforcing it) is allowed. +.El +.It Dv KAUTH_SYSTEM_FS_RESERVEDSPACE +Check if using the file system reserved space is allowed. +.It Dv KAUTH_SYSTEM_LFS +Check if LFS-related operations are allowed. +.Ar req +can be one of the following: +.Bl -tag -width compact +.It Dv KAUTH_REQ_SYSTEM_LFS_MARKV +Check if calling +.Xr lfs_markv 2 +is allowed. +.It Dv KAUTH_REQ_SYSTEM_LFS_BMAPV +Check if calling +.Xr lfs_bmapv 2 +is allowed. +.It Dv KAUTH_REQ_SYSTEM_LFS_SEGCLEAN +Check if calling +.Xr lfs_segclean 2 +is allowed. +.It Dv KAUTH_REQ_SYSTEM_LFS_SEGWAIT +Check if calling +.Xr lfs_segwait 2 +is allowed. +.It Dv KAUTH_REQ_SYSTEM_LFS_FCNTL +Check if operations on LFS through +.Xr fcntl 2 +are allowed. +.El +.It Dv KAUTH_SYSTEM_MAP_VA_ZERO +Check if changing the status of memory mapping of virtual address zero +is allowed. +.It Dv KAUTH_SYSTEM_MODULE +Check if a module request is allowed. +.Pp +.Ar arg1 +is the command. +.It Dv KAUTH_SYSTEM_MKNOD +Check if creating devices is allowed. +.It Dv KAUTH_SYSTEM_MOUNT +Check if mount-related operations are allowed. +.Pp +.Ar req +can be any of the following: +.Bl -tag -width compact +.It Dv KAUTH_REQ_SYSTEM_MOUNT_DEVICE +Check if mounting a device is allowed. +.Ar arg1 +is a +.Ft vnode_t * +of the device, +.Ar arg2 +is a +.Ft struct mount * +with the mount-point, and +.Ar arg3 +is a +.Ft mode_t +with the desired access mode. +.It Dv KAUTH_REQ_SYSTEM_MOUNT_GET +Check if retrieving information about a mount is allowed. +.Ar arg1 +is a +.Ft struct mount * +with the mount structure in question, +.Ar arg2 +is a +.Ft void * +with file system specific data, if any. +.It Dv KAUTH_REQ_SYSTEM_MOUNT_NEW +Check if mounting a new file system is allowed. +.Pp +.Ar arg1 +is the +.Ft struct vnode * +on which the file system is to be mounted, +.Ar arg2 +is an +.Ft int +with the mount flags, and +.Ar arg3 +is a +.Ft void * +with file system specific data, if any. +.It Dv KAUTH_REQ_SYSTEM_MOUNT_UNMOUNT +Checks if unmounting a file system is allowed. +.Pp +.Ar arg1 +is a +.Ft struct mount * +with the mount in question. +.It Dv KAUTH_REQ_SYSTEM_MOUNT_UPDATE +Checks if updating an existing mount is allowed. +.Pp +.Ar arg1 +is the +.Ft struct mount * +of the existing mount, +.Ar arg2 +is an +.Ft int +with the new mount flags, and +.Ar arg3 +is a +.Ft void * +with file system specific data, if any. +.It Dv KAUTH_REQ_SYSTEM_MOUNT_UMAP +Check if mounting the user and group id remapping file system. +See +.Xr mount_umap 8 . +.El +.It Dv KAUTH_SYSTEM_MQUEUE +Check if bypassing permissions on a message queue object are allowed. +.Ar arg1 +is a +.Ft mqueue_t * +describing the message queue. +.It Dv KAUTH_SYSTEM_PSET +Check processor-set manipulation. +.Pp +.Ar req +can be any of the following: +.Bl -tag -width compact +.It Dv KAUTH_REQ_SYSTEM_PSET_ASSIGN +Change processor-set processor assignment. +.It Dv KAUTH_REQ_SYSTEM_PSET_BIND +Bind an LWP to a processor-set. +.It Dv KAUTH_REQ_SYSTEM_PSET_CREATE +Create a processor-set. +.It Dv KAUTH_REQ_SYSTEM_PSET_DESTROY +Destroy a processor-set. +.El +.It Dv KAUTH_SYSTEM_REBOOT +Check if rebooting is allowed. +.It Dv KAUTH_SYSTEM_SETIDCORE +Check if changing coredump settings for set-id processes is allowed. +.It Dv KAUTH_SYSTEM_SEMAPHORE +Check if access to a kernel semaphore is allowed. +.Ar arg1 +is a +.Ft ksem_t * +describing the semaphore. +.It Dv KAUTH_SYSTEM_SWAPCTL +Check if privileged +.Xr swapctl 2 +requests are allowed. +.It Dv KAUTH_SYSTEM_SYSCTL +This requests operations related to +.Xr sysctl 9 . +.Ar req +indicates the specific request and can be one of the following: +.Bl -tag -width compact +.It Dv KAUTH_REQ_SYSTEM_SYSCTL_ADD +Check if adding a +.Xr sysctl 9 +node is allowed. +.It Dv KAUTH_REQ_SYSTEM_SYSCTL_DELETE +Check if deleting a +.Xr sysctl 9 +node is allowed. +.It Dv KAUTH_REQ_SYSTEM_SYSCTL_DESC +Check if adding description to a +.Xr sysctl 9 +node is allowed. +.It Dv KAUTH_REQ_SYSTEM_SYSCTL_MODIFY +Check if modifying a +.Xr sysctl 9 +node variable that doesn't have a custom sysctl helper function is allowed. +.Pp +This request might be deprecated in the future. +.It Dv KAUTH_REQ_SYSTEM_SYSCTL_PRVT +Check if accessing private +.Xr sysctl 9 +nodes is allowed. +.El +.It Dv KAUTH_SYSTEM_SYSVIPC +Check SysV IPC related operations. +.Ar req +indicates the specific request and can be one of the following: +.Bl -tag -width compact +.It Dv KAUTH_REQ_SYSTEM_SYSVIPC_BYPASS +Check if bypassing a SysV IPC object's permissions is allowed. +.Ar arg1 +is a +.Ft struct ipc_perm * +with the object's permissions and +.Ar arg2 +is a +.Ft mode_t +indicating the requested access mode. +.It Dv KAUTH_REQ_SYSTEM_SYSVIPC_SHM_LOCK +Check if shared memory locking is allowed. +.It Dv KAUTH_REQ_SYSTEM_SYSVIPC_SHM_UNLOCK +Check if shared memory unlocking is allowed. +.It Dv KAUTH_REQ_SYSTEM_SYSVIPC_MSGQ_OVERSIZE +Check if oversizing a message queue is allowed. +.Ar arg1 +is a +.Ft msglen_t +indicating the size of the message buffer, and +.Ar arg2 +is a +.Ft msglen_t +indicating the size of the message queue. +.El +.It Dv KAUTH_SYSTEM_TIME +This request groups time-related operations. +.Ar req +can be any of the following: +.Bl -tag -width compact +.It Dv KAUTH_REQ_SYSTEM_TIME_ADJTIME +Check if changing the time using +.Xr adjtime 2 +is allowed. +.It Dv KAUTH_REQ_SYSTEM_TIME_NTPADJTIME +Check if setting the time using +.Xr ntp_adjtime 2 +is allowed. +.It Dv KAUTH_REQ_SYSTEM_TIME_SYSTEM +Check if changing the time (usually via +.Xr settimeofday 2 ) +is allowed. +.Pp +.Ar arg1 +is a +.Ft struct timespec * +with the new time, +.Ar arg2 +is a +.Ft struct timeval * +with the delta from the current time, +.Ar arg3 +is a +.Ft bool +indicating whether the caller is a device context (e.g. +.Pa /dev/clockctl ) +or not. +.It Dv KAUTH_REQ_SYSTEM_TIME_RTCOFFSET +Check if changing the RTC offset is allowed. +.It Dv KAUTH_REQ_SYSTEM_TIME_TIMECOUNTERS +Check if manipulating timecounters is allowed. +.El +.It Dv KAUTH_SYSTEM_VERIEXEC +Check if operations on the +.Xr veriexec 8 +subsystem are allowed. +.Ar req +can be one of the following: +.Bl -tag -width compact +.It Dv KAUTH_REQ_SYSTEM_VERIEXEC_ACCESS +Check if access to the +.Xr veriexec 8 +subsystem is allowed. +.It Dv KAUTH_REQ_SYSTEM_VERIEXEC_MODIFY +Check if modifications to the state of +.Xr veriexec 8 +are allowed. +.El +.El +.Ss Process Scope +The process scope, +.Dq org.netbsd.kauth.process , +manages authorization requests related to processes in the system. +.Pp +The authorization wrapper for this scope is declared as +.Pp +.Ft int Fn kauth_authorize_process "kauth_cred_t cred" \ +"kauth_action_t op" "struct proc *p" "void *arg1" "void *arg2" \ +"void *arg3" +.Pp +The following operations are available for this scope: +.Bl -tag -width compact +.It Dv KAUTH_PROCESS_KTRACE +Checks whether an object with one set of credentials can +.Xr ktrace 1 +another process +.Ar p , +possibly with a different set of credentials. +.Pp +If +.Ar arg1 +is +.Dv KAUTH_REQ_PROCESS_KTRACE_PERSISTENT , +this checks if persistent tracing can be done. +Persistent tracing maintains the trace across a set-user-id/set-group-id +.Xr exec 3 , +and normally requires privileged credentials. +.It Dv KAUTH_PROCESS_PROCFS +Checks whether object with passed credentials can use +.Em procfs +to access process +.Ar p . +.Pp +.Ar arg1 +is the +.Ft struct pfsnode * +for the target element in the target process, and +.Ar arg2 +is the access type, which can be either +.Dv KAUTH_REQ_PROCESS_PROCFS_READ , +.Dv KAUTH_REQ_PROCESS_PROCFS_RW , +or +.Dv KAUTH_REQ_PROCESS_PROCFS_WRITE , +indicating +.Em control , +.Em read , +.Em read-write , +or +.Em write +access respectively. +.It Dv KAUTH_PROCESS_PTRACE +Checks whether object with passed credentials can use +.Xr ptrace 2 +to access process +.Ar p . +.Pp +.Ar arg1 +is the +.Xr ptrace 2 +command. +.It Dv KAUTH_PROCESS_CANSEE +Checks whether an object with one set of credentials can access +information about another process, possibly with a different set of +credentials. +.Pp +.Ar arg1 +indicates the class of information being viewed, and can be either of +.Dv KAUTH_REQ_PROCESS_CANSEE_ARGS , +.Dv KAUTH_REQ_PROCESS_CANSEE_ENTRY , +.Dv KAUTH_REQ_PROCESS_CANSEE_ENV , +or +.Dv KAUTH_REQ_PROCESS_CANSEE_OPENFILES . +.It Dv KAUTH_PROCESS_SCHEDULER_GETAFFINITY +Checks whether viewing the scheduler affinity is allowed. +.It Dv KAUTH_PROCESS_SCHEDULER_SETAFFINITY +Checks whether setting the scheduler affinity is allowed. +.It Dv KAUTH_PROCESS_SCHEDULER_GETPARAM +Checks whether viewing the scheduler policy and parameters is allowed. +.It Dv KAUTH_PROCESS_SCHEDULER_SETPARAM +Checks whether modifying the scheduler policy and parameters is allowed. +.It Dv KAUTH_PROCESS_SIGNAL +Checks whether an object with one set of credentials can post signals +to another process. +.Pp +.Ar p +is the process the signal is being posted to, and +.Ar arg1 +is the signal number. +.It Dv KAUTH_PROCESS_CORENAME +Controls access to process corename. +.Pp +.Ar arg1 +can be +.Dv KAUTH_REQ_PROCESS_CORENAME_GET +or +.Dv KAUTH_REQ_PROCESS_CORENAME_SET , +indicating access to read or write the process' corename, respectively. +.Pp +When modifying the corename, +.Ar arg2 +holds the new corename to be used. +.It Dv KAUTH_PROCESS_FORK +Checks if the process can fork. +.Ar arg1 +is an +.Ft int +indicating how many processes exist on the system at the time of the check. +.It Dv KAUTH_PROCESS_KEVENT_FILTER +Checks whether setting a process +.Xr kevent 2 +filter is allowed. +.It Dv KAUTH_PROCESS_NICE +Checks whether the +.Em nice +value of +.Ar p +can be changed to +.Ar arg1 . +.It Dv KAUTH_PROCESS_RLIMIT +Controls access to process resource limits. +.Pp +.Ar arg1 +can be +.Dv KAUTH_REQ_PROCESS_RLIMIT_GET +or +.Dv KAUTH_REQ_PROCESS_RLIMIT_SET , +indicating access to read or write the process' resource limits, respectively, or +.Dv KAUTH_REQ_PROCESS_RLIMIT_BYPASS +to check if the limit enforcement can be bypassed. +.Pp +When modifying resource limits, +.Ar arg2 +is the new value to be used and +.Ar arg3 +indicates which resource limit is to be modified. +.It Dv KAUTH_PROCESS_SETID +Check if changing the user- or group-ids, groups, or login-name for +.Ar p +is allowed. +.It Dv KAUTH_PROCESS_STOPFLAG +Check if setting the stop flags for +.Xr exec 3 , +.Xr exit 3 , +and +.Xr fork 2 +is allowed. +.Pp +.Ar arg1 +indicates the flag, and can be either +.Dv P_STOPEXEC , +.Dv P_STOPEXIT , +or +.Dv P_STOPFORK +respectively. +.El +.Ss Network Scope +The network scope, +.Dq org.netbsd.kauth.network , +manages networking-related authorization requests in the kernel. +.Pp +The authorization wrapper for this scope is declared as +.Pp +.Ft int Fn kauth_authorize_network "kauth_cred_t cred" "kauth_action_t op" \ +"enum kauth_network_req req" "void *arg1" "void *arg2" "void *arg3" +.Pp +The following operations are available for this scope: +.Bl -tag -width compact +.It Dv KAUTH_NETWORK_ALTQ +Checks if an ALTQ operation is allowed. +.Pp +.Ar req +indicates the ALTQ subsystem in question, and can be one of the following: +.Pp +.Bl -tag -compact -width compact +.It Dv KAUTH_REQ_NETWORK_ALTQ_AFMAP +.It Dv KAUTH_REQ_NETWORK_ALTQ_BLUE +.It Dv KAUTH_REQ_NETWORK_ALTQ_CBQ +.It Dv KAUTH_REQ_NETWORK_ALTQ_CDNR +.It Dv KAUTH_REQ_NETWORK_ALTQ_CONF +.It Dv KAUTH_REQ_NETWORK_ALTQ_FIFOQ +.It Dv KAUTH_REQ_NETWORK_ALTQ_HFSC +.It Dv KAUTH_REQ_NETWORK_ALTQ_JOBS +.It Dv KAUTH_REQ_NETWORK_ALTQ_PRIQ +.It Dv KAUTH_REQ_NETWORK_ALTQ_RED +.It Dv KAUTH_REQ_NETWORK_ALTQ_RIO +.It Dv KAUTH_REQ_NETWORK_ALTQ_WFQ +.El +.It Dv KAUTH_NETWORK_BIND +Checks if a +.Xr bind 2 +request is allowed. +.Pp +.Ar req +allows to indicate the type of the request to structure listeners and callers +easier. +Supported request types: +.Bl -tag -width compact +.It Dv KAUTH_REQ_NETWORK_BIND_PORT +Checks if binding to a non-privileged/reserved port is allowed. +.It Dv KAUTH_REQ_NETWORK_BIND_PRIVPORT +Checks if binding to a privileged/reserved port is allowed. +.El +.It Dv KAUTH_NETWORK_FIREWALL +Checks if firewall-related operations are allowed. +.Pp +.Ar req +indicates the sub-action, and can be one of the following: +.Bl -tag -width compact +.It Dv KAUTH_REQ_NETWORK_FIREWALL_FW +Modification of packet filtering rules. +.It Dv KAUTH_REQ_NETWORK_FIREWALL_NAT +Modification of NAT rules. +.El +.It Dv KAUTH_NETWORK_INTERFACE +Checks if network interface-related operations are allowed. +.Pp +.Ar arg1 +is (optionally) the +.Ft struct ifnet * +associated with the interface. +.Ar arg2 +is (optionally) an +.Ft int +describing the interface-specific operation. +.Ar arg3 +is (optionally) a pointer to the interface-specific request structure. +.Ar req +indicates the sub-action, and can be one of the following: +.Bl -tag -width compact +.It Dv KAUTH_REQ_NETWORK_INTERFACE_GET +Check if retrieving information from the device is allowed. +.It Dv KAUTH_REQ_NETWORK_INTERFACE_GETPRIV +Check if retrieving privileged information from the device is allowed. +.It Dv KAUTH_REQ_NETWORK_INTERFACE_SET +Check if setting parameters on the device is allowed. +.It Dv KAUTH_REQ_NETWORK_INTERFACE_SETPRIV +Check if setting privileged parameters on the device is allowed. +.It Dv KAUTH_REQ_NETWORK_INTERFACE_FIRMWARE +Check if manipulating the firmware on a network interface device is allowed. +.El +.Pp +Note that unless the +.Ft struct ifnet * +for the interface was passed in +.Ar arg1 , +there's no way to tell what structure +.Ar arg3 +is. +.It Dv KAUTH_NETWORK_INTERFACE_BRIDGE +Check if operations performed on the +.Xr bridge 4 +network interface are allowed. +.Pp +.Ar req +can be one of the following: +.Bl -tag -width compact +.It Dv KAUTH_REQ_NETWORK_INTERFACE_BRIDGE_GETPRIV +Check if getting privileges parameters is allowed. +.It Dv KAUTH_REQ_NETWORK_INTERFACE_BRIDGE_SETPRIV +Check if setting privileges parameters is allowed. +.El +.It Dv KAUTH_NETWORK_INTERFACE_PPP +Checks if operations performed on the +.Xr ppp 4 +network interface are allowed. +.Pp +.Ar req +can be one of the following: +.Bl -tag -width compact +.It Dv KAUTH_REQ_NETWORK_INTERFACE_PPP_ADD +Checks if adding and enabling a +.Xr ppp 4 +interface to the system is allowed. +.El +.It Dv KAUTH_NETWORK_INTERFACE_PVC +Check if operations performed on a PVC device (e.g. +.Xr en 4 ) +are allowed. +.Ar req +can be one of the following: +.Bl -tag -width compact +.It Dv KAUTH_REQ_NETWORK_INTERFACE_PVC_ADD +Check if adding a PVC device is allowed. +.El +.It Dv KAUTH_NETWORK_INTERFACE_SLIP +Checks if operations performed on the +.Xr sl 4 +network interface are allowed. +.Pp +.Ar req +can be one of the following: +.Bl -tag -width compact +.It Dv KAUTH_REQ_NETWORK_INTERFACE_SLIP_ADD +Checks if adding and enabling a +.Xr sl 4 +interface to the system is allowed. +.El +.It Dv KAUTH_NETWORK_INTERFACE_STRIP +Checks if operations performed on the +.Xr strip 4 +network interface are allowed. +.Pp +.Ar req +can be one of the following: +.Bl -tag -width compact +.It Dv KAUTH_REQ_NETWORK_INTERFACE_STRIP_ADD +Check if adding and enabling a +.Xr strip 4 +interface to the system is allowed. +.El +.It Dv KAUTH_NETWORK_INTERFACE_TUN +Checks if operations performed on the +.Xr tun 4 +network interface are allowed. +.Pp +.Ar req +can be one of the following: +.Bl -tag -width compact +.It Dv KAUTH_REQ_NETWORK_INTERFACE_TUN_ADD +Checks if adding and enabling a +.Xr tun 4 +interface to the system is allowed. +.El +.It Dv KAUTH_NETWORK_IPSEC +Check if operations related to +.Xr ipsec 4 +connections are allowed. +.Ar req +can be one of the following: +.Bl -tag -width compact +.It Dv KAUTH_REQ_NETWORK_IPSEC_BYPASS +Check if bypassing +.Xr ipsec 4 +policy is allowed. +.El +.It Dv KAUTH_NETWORK_IPV6 +Check if IPv6-specific operations are allowed. +.Ar req +can be one of the following: +.Bl -tag -width compact +.It Dv KAUTH_REQ_NETWORK_IPV6_HOPBYHOP +Check if setting hop-by-hop packet options is allowed. +.It Dv KAUTH_REQ_NETWORK_IPV6_JOIN_MULTICAST +Check if joining a multicast network is allowed. +.El +.It Dv KAUTH_NETWORK_FORWSRCRT +Checks whether status of forwarding of source-routed packets can be modified +or not. +.It Dv KAUTH_NETWORK_NFS +Check if an NFS related operation is allowed. +.Pp +.Ar req +can be any of the following: +.Bl -tag -width compact +.It Dv KAUTH_REQ_NETWORK_NFS_EXPORT +Check if modifying the NFS export table is allowed. +.It Dv KAUTH_REQ_NETWORK_NFS_SVC +Check if access to the NFS +.Xr nfssvc 2 +syscall is allowed. +.El +.It Dv KAUTH_NETWORK_ROUTE +Checks if a routing-related request is allowed. +.Pp +.Ar arg1 +is the +.Ft struct rt_msghdr * +for the request. +.It Dv KAUTH_NETWORK_SMB +Check if operations related to SMB are allowed. +.Pp +.Ar req +can be one of the following: +.Bl -tag -width compact +.It Dv KAUTH_REQ_NETWORK_SMB_SHARE_ACCESS +Check if accessing an SMB share is allowed. +.Pp +.Ar arg1 +is a +.Ft struct smb_share * +describing the SMB share, and +.Ar arg2 +is a +.Ft mode_t +with the desired access mode. +.It Dv KAUTH_REQ_NETWORK_SMB_SHARE_CREATE +Check if creating an SMB share is allowed. +.Pp +.Ar arg1 +is a +.Ft struct smb_sharespec * +describing the share to be created. +.It Dv KAUTH_REQ_NETWORK_SMB_VC_ACCESS +Check if accessing an SMB VC is allowed. +.Pp +.Ar arg1 +is a +.Ft struct smb_vc * +describing the SMB VC, and +.Ar arg2 +is a +.Ft mode_t +with the desired access mode. +.It Dv KAUTH_REQ_NETWORK_SMB_VC_CREATE +Check if creating an SMB VC is allowed. +.Pp +.Ar arg1 +is a +.Ft struct smb_vcspec * +describing the VC to be created. +.El +.It Dv KAUTH_NETWORK_SOCKET +Checks if a socket related operation is allowed. +.Pp +.Ar req +allows to indicate the type of the request to structure listeners and callers +easier. +Supported request types: +.Bl -tag -width compact +.It Dv KAUTH_REQ_NETWORK_SOCKET_RAWSOCK +Checks if opening a raw socket is allowed. +.It Dv KAUTH_REQ_NETWORK_SOCKET_OPEN +Checks if opening a socket is allowed. +.Ar arg1 , arg2 , +and +.Ar arg3 +are all +.Ft int +parameters describing the domain, socket type, and protocol, +respectively. +.It Dv KAUTH_REQ_NETWORK_SOCKET_CANSEE +Checks if looking at the socket passed is allowed. +.Pp +.Ar arg1 +is a +.Ft struct socket * +describing the socket. +.It Dv KAUTH_REQ_NETWORK_SOCKET_DROP +Checks if a connection can be dropped. +.Pp +.Ar arg1 +is a +.Ft struct socket * +describing the socket. +.It Dv KAUTH_REQ_NETWORK_SOCKET_SETPRIV +Checks if setting privileged socket options is allowed. +.Pp +.Ar arg1 +is a +.Ft struct socket * +describing the socket, +.Ar arg2 +is a +.Ft u_long +describing the socket option. +.El +.El +.Ss Machine-dependent Scope +The machine-dependent (machdep) scope, +.Dq org.netbsd.kauth.machdep , +manages machine-dependent authorization requests in the kernel. +.Pp +The authorization wrapper for this scope is declared as +.Pp +.Ft int Fn kauth_authorize_machdep "kauth_cred_t cred" "kauth_action_t op" \ +"void *arg0" "void *arg1" "void *arg2" "void *arg3" +.Pp +The actions on this scope provide a set that may or may not affect all +platforms. +Below is a list of available actions, along with which platforms are affected +by each. +.Bl -tag -width compact +.It Dv KAUTH_MACHDEP_CACHEFLUSH +Request to flush the whole CPU cache. +Affects +.Em m68k +Linux emulation. +.It Dv KAUTH_MACHDEP_CPU_UCODE_APPLY +Request to apply a CPU microcode to a CPU. +This is related to +.Em CPU_UCODE , +see +.Xr options 4 . +Affects +.Em i386 +and +.Em xen . +.It Dv KAUTH_MACHDEP_IOPERM_GET +Request to get the I/O permission level. +Affects +.Em amd64 , +.Em i386 , +.Em xen . +.It Dv KAUTH_MACHDEP_IOPERM_SET +Request to set the I/O permission level. +Affects +.Em amd64 , +.Em i386 , +.Em xen . +.It Dv KAUTH_MACHDEP_IOPL +Request to set the I/O privilege level. +Affects +.Em amd64 , +.Em i386 , +.Em xen . +.It Dv KAUTH_MACHDEP_LDT_GET +Request to get the LDT (local descriptor table). +Affects +.Em amd64 , +.Em i386 , +.Em xen . +.It Dv KAUTH_MACHDEP_LDT_SET +Request to set the LDT (local descriptor table). +Affects +.Em amd64 , +.Em i386 , +.Em xen . +.It Dv KAUTH_MACHDEP_MTRR_GET +Request to get the MTRR (memory type range registers). +Affects +.Em amd64 , +.Em i386 , +.Em xen . +.It Dv KAUTH_MACHDEP_MTRR_SET +Request to set the MTRR (memory type range registers). +Affects +.Em amd64 , +.Em i386 , +.Em xen . +.It Dv KAUTH_MACHDEP_NVRAM +Request to access (read/write) the NVRAM. +Affects +.Em i386 . +.It Dv KAUTH_MACHDEP_PXG +Request to start or stop the +.Xr pxg 4 +CPU. +.Ar arg0 +is +.Ft true +or +.Ft false , +respectively. +Affects +.Em pmax . +.It Dv KAUTH_MACHDEP_UNMANAGEDMEM +Request to access unmanaged memory. +Affects +.Em alpha , +.Em amd64 , +.Em arm , +.Em i386 , +.Em powerpc , +.Em sh3 , +.Em vax , +.Em x68k , +.Em xen . +.El +.Ss Device Scope +The device scope, +.Dq org.netbsd.kauth.device , +manages authorization requests related to devices on the system. +Devices can be, for example, terminals, tape drives, Bluetooth accessories, and +any other hardware. +Network devices specifically are handled by the +.Em network +scope. +.Pp +In addition to the standard authorization wrapper: +.Pp +.Ft int Fn kauth_authorize_device "kauth_cred_t cred" "kauth_action_t op" \ +"void *arg0" "void *arg1" "void *arg2" "void *arg3" +.Pp +this scope provides authorization wrappers for various device types. +.Pp +.Ft int Fn kauth_authorize_device_tty "kauth_cred_t cred" "kauth_action_t op" \ +"struct tty *tty" +.Pp +Authorizes requests for +.Em terminal devices +on the system. +The third argument, +.Ar tty , +is the terminal device in question. +It is passed to the listener as +.Ar arg0 . +The second argument, +.Ar op , +is the action and can be one of the following: +.Bl -tag -width compact +.It Dv KAUTH_DEVICE_TTY_OPEN +Open the terminal device pointed to by +.Ar tty . +.It Dv KAUTH_DEVICE_TTY_PRIVSET +Set privileged settings on the terminal device pointed to by +.Ar tty . +.It Dv KAUTH_DEVICE_TTY_STI +Use the +.Dq TIOCSTI +device +.Xr ioctl 2 , +allowing to inject characters into the terminal buffer, simulating terminal +input. +.It Dv KAUTH_DEVICE_TTY_VIRTUAL +Control the virtual console. +.Ar tty +is the current console +.Xr tty 4 . +.El +.Pp +.Ft int Fn kauth_authorize_device_spec "kauth_cred_t cred" \ +"enum kauth_device_req req" "struct vnode *vp" +.Pp +Authorizes requests for +.Em special files , +usually disk devices, but also direct memory access, on the system. +.Pp +It passes +.Dv KAUTH_DEVICE_RAWIO_SPEC +as the action to the listener, and accepts two arguments. +.Ar req , +passed to the listener as +.Ar arg0 , +is access requested, and can be one of +.Dv KAUTH_REQ_DEVICE_RAWIO_SPEC_READ , +.Dv KAUTH_REQ_DEVICE_RAWIO_SPEC_WRITE , +or +.Dv KAUTH_REQ_DEVICE_RAWIO_SPEC_RW , +representing read, write, or both read/write access respectively. +.Ar vp +is the vnode of the special file in question, and is passed to the listener as +.Ar arg1 . +.Pp +Keep in mind that it is the responsibility of the security model developer to +check whether the underlying device is a disk or the system memory, using +.Fn iskmemdev : +.Bd -literal -offset indent +if ((vp->v_type == VCHR) && + iskmemdev(vp->v_un.vu_specinfo->si_rdev)) + /* system memory access */ +.Ed +.Pp +.Ft int Fn kauth_authorize_device_passthru "kauth_cred_t cred" "dev_t dev" \ +"u_long mode" "void *data" +.Pp +Authorizes hardware +.Em passthru +requests, or user commands passed directly to the hardware. +These have the potential of resulting in direct disk and/or memory access. +.Pp +It passes +.Dv KAUTH_DEVICE_RAWIO_PASSTHRU +as the action to the listener, and accepts three arguments. +.Ar dev , +passed as +.Ar arg1 +to the listener, is the device for which the request is made. +.Ar mode , +passed as +.Ar arg0 +to the listener, is a generic representation of the access mode requested. +It can be one or more (binary-OR'd) of the following: +.Pp +.Bl -tag -width compact -offset indent -compact +.It KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_READ +.It KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_READCONF +.It KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_WRITE +.It KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_WRITECONF +.El +.Pp +.Ar data , +passed as +.Ar arg2 +to the listener, is device-specific data that may be associated with the +request. +.Ss Bluetooth Devices +Authorizing actions relevant to Bluetooth devices is done using the standard +authorization wrapper, with the following actions: +.Bl -tag -width compact +.It KAUTH_DEVICE_BLUETOOTH_BCSP +Check if operations on a +.Xr bcsp 4 +device are allowed. +.Pp +.Ar arg0 +is an +.Ft enum kauth_device_req +with one of the following values: +.Bl -tag -width compact +.It Dv KAUTH_REQ_DEVICE_BLUETOOTH_BCSP_ADD +Check if adding and enabling a +.Xr bcsp 4 +device is allowed. +.El +.It KAUTH_DEVICE_BLUETOOTH_BTUART +Check if operations on a +.Xr btuart 4 +device are allowed. +.Pp +.Ar arg0 +is an +.Ft enum kauth_device_req +with one of the following values: +.Bl -tag -width compact +.It Dv KAUTH_REQ_DEVICE_BLUETOOTH_BTUART_ADD +Check if adding and enabling a +.Xr btuart 4 +device is allowed. +.El +.It KAUTH_DEVICE_BLUETOOTH_RECV +Check if a packet can be received from the device. +.Pp +.Ar arg0 +is the packet type. +For +.Dv HCI_CMD_PKT +packets, +.Ar arg1 +is the opcode, for +.Dv HCI_EVENT_PKT +packets, +.Ar arg1 +is the event ID, and for +.Dv HCI_ACLDATA_PKT +or +.Dv HCI_SCODATA_PKT +packets, +.Ar arg1 +is the connection handle. +.It KAUTH_DEVICE_BLUETOOTH_SEND +Check if a packet can be sent to the device. +.Pp +.Ar arg0 +is a +.Ft struct hci_unit * +describing the HCI unit, +.Ar arg1 +is a +.Ft hci_cmd_hdr_t * +describing the packet header. +.It KAUTH_DEVICE_BLUETOOTH_SETPRIV +Check if privileged settings can be changed. +.Pp +.Ar arg0 +is a +.Ft struct hci_unit * +describing the HCI unit, +.Ar arg1 +is a +.Ft struct btreq * +describing the request, and +.Ar arg2 +is a +.Ft u_long +describing the command. +.El +.Ss Kernel random device +Authorization actions relevant to the kernel random device, +.Xr rnd 4 , +is done using the standard authorization wrapper, with the following actions: +.Bl -tag -width compact +.It KAUTH_DEVICE_RND_ADDDATA +Check if adding data to the entropy pool is allowed. +.It KAUTH_DEVICE_RND_GETPRIV +Check if privileged settings and information can be retrieved. +.It KAUTH_DEVICE_RND_SETPRIV +Check if privileged settings can be changed. +.El +.Ss Wscons devices +Authorization actions relevant to +.Xr wscons 4 +are done using the standard authorization wrapper, with the following actions: +.Bl -tag -width compact +.It KAUTH_DEVICE_WSCONS_KEYBOARD_BELL +Check if setting the default bell is allowed. +.It KAUTH_DEVICE_WSCONS_KEYBOARD_KEYREPEAT +Check if setting the default key-repeat is allowed. +.El +.Ss Vnode Scope +The vnode scope, +.Dq org.netbsd.kauth.vnode , +authorizes operations made on vnodes representing file system objects. +.Pp +The authorization wrapper for this scope is declared as +.Pp +.Ft int Fn kauth_authorize_vnode "kauth_cred_t cred" "kauth_action_t action" \ +"vnode_t *vp" "vnode_t *dvp" "int fs_decision" +.Pp +This scope is heavily used in file system code and can potentially affect +system-wide performance. +Therefore, there are several things developers should know when using it. +.Pp +First, the +.Ar action +parameter is a bit-mask and multiple actions can be binary-OR'd and authorized +in a single call. +Two helper functions help generate the +.Ar action +value for a couple of common cases: translating file system access to a +.Nm +action and checking access to a vnode. +.Pp +The first, +.Fn kauth_mode_to_action "mode_t access_mode" , +and returns a +.Ft kauth_action_t +representing the desired access modes. +Another function, +.Fn kauth_access_action "mode_t access_mode" "enum vtype v_type" \ +"mode_t file_mode" , +returns a +.Ft kauth_action_t +suitable for use in many file system +.Xr access 2 +implementations. +It calls the aforementioned +.Fn kauth_mode_to_action , +but before returning also adds the +.Dv KAUTH_VNODE_IS_EXEC +flag if needed. +See below for the meaning of this flag and how its necessity is +determined. +.Pp +Second, it is recommended to be very careful with adding listeners on this +scope. +A special parameter, +.Ar fs_decision , +allows different file systems to instrument different policies without adding +their own listener. +This parameter is special because it also serves as a fall-back decision when +no +.Xr secmodel 9 +is present to prevent a fail-open scenario. +It can take either an +.Xr errno 2 +value or +.Dq KAUTH_VNODE_REMOTEFS , +indicating that the file system on which the authorization is made is remote +and cannot provide us with a fall-back decision. +In this case, +.Nm +can only short-circuit the request but the file system will have the last +word if there is no definitive allow or deny decision. +.Pp +The value of +.Ar fs_decision +can be hard-coded or determined by calling an internal function implementing a +policy. +For the latter case, +.Xr genfs 9 +provides a set of helper functions that implement common policies that +file systems can use. +The calling convention is as follows: +.Bd -literal -offset indent +int error; + +error = kauth_authorize_vnode(..., genfs_can_foo(...)); +.Ed +.Pp +Actions on the vnode scope are of two types: operations and flags. +An operation is similar in concept to actions on other scopes in the sense +that it represents an operation desired by the caller. +A flag is an indicator of additional information about the vnode that +a file system can set in order to allow the listener to make a more +informed decision. +.Pp +Actions include the following: +.Bl -tag -width compact -offset indent +.It KAUTH_VNODE_READ_DATA +Read file data. +.It KAUTH_VNODE_LIST_DIRECTORY +Read directory listing. +Identical to the above. +.It KAUTH_VNODE_WRITE_DATA +Write file data. +.It KAUTH_VNODE_ADD_FILE +Add a file to a directory. +Identical to the above. +.It KAUTH_VNODE_EXECUTE +Execute a file. +.It KAUTH_VNODE_SEARCH +Search (enter) a directory. +Identical to the above. +.It KAUTH_VNODE_DELETE +Delete a file. +.It KAUTH_VNODE_APPEND_DATA +Append data to a file. +.It KAUTH_VNODE_ADD_SUBDIRECTORY +Add a subdirectory to a directory. +Identical to the above. +.It KAUTH_VNODE_READ_TIMES +Read the created, last accessed, and last modified times of a file. +.It KAUTH_VNODE_WRITE_TIMES +Modify the created, last accessed, or last modified times of a file. +.It KAUTH_VNODE_READ_FLAGS +Read file flags. +.It KAUTH_VNODE_WRITE_FLAGS +Modify file flags. +.It KAUTH_VNODE_READ_SYSFLAGS +Read file system flags. +.It KAUTH_VNODE_WRITE_SYSFLAGS +Modify file system flags. +.It KAUTH_VNODE_RENAME +Rename a file. +.It KAUTH_VNODE_CHANGE_OWNERSHIP +Change ownership of a file. +.It KAUTH_VNODE_READ_SECURITY +Read the permissions of a file. +.It KAUTH_VNODE_WRITE_SECURITY +Change the permissions of a file, for example by using +.Xr chmod 2 . +.It KAUTH_VNODE_READ_ATTRIBUTES +Read attributes of a file. +.It KAUTH_VNODE_WRITE_ATTRIBUTES +Modify attributes of a file. +.It KAUTH_VNODE_READ_EXTATTRIBUTES +Read extended attributes of a file. +.It KAUTH_VNODE_WRITE_EXTATTRIBUTES +Modify extended attributes of a file. +.It KAUTH_VNODE_RETAIN_SUID +Check if retaining the set-user-id bit on files after +.Xr chown 2 +is allowed. +.It KAUTH_VNODE_RETAIN_SGID +Check if retaining the set-group-id bit on files after +.Xr chown 2 +is allowed. +.It KAUTH_VNODE_REVOKE +Revoke a file. +.El +.Pp +Flags include the following: +.Bl -tag -width compact -offset indent +.It KAUTH_VNODE_IS_EXEC +The vnode is executable. +.Pp +The macro +.Fn FS_OBJECT_CAN_EXEC +can be used to help determine if this flag should be set. +This macro determines a file system object to be executable if it is a +directory (in which case we say it is searchable) or if it has at least one +executable bit set in its mode. +.Pp +Setting this flag helps a listener know that a vnode is executable and is used +in implementing privileged access to files and directories while maintaining +semantics that prevent execution until a file is marked as an executable. +An example for using this in listener code is: +.Bd -literal -offset indent +if (privileged) { + /* Always allow read/write; execute only if executable. */ + if ((action & KAUTH_VNODE_EXECUTE) == 0 || + (action & KAUTH_VNODE_IS_EXEC)) + result = KAUTH_RESULT_ALLOW; +} +.Ed +.Pp +Finally, the vnode scope authorization wrapper returns +.Er EACCES +in case of an error, to maintain file system semantics. +File systems can override this value if needed. +.It KAUTH_VNODE_HAS_SYSFLAGS +The file system object represented by the vnode has system flags set. +.It KAUTH_VNODE_ACCESS +The authorization is advisory only and no actual operation is to be +performed. +This is not implemented. +.El +.Ss Credentials Scope +The credentials scope, +.Dq org.netbsd.kauth.cred , +is a special scope used internally by the +.Nm +framework to provide hooking to credential-related operations. +.Pp +It is a +.Dq notify-only +scope, allowing hooking operations such as initialization of new credentials, +credential inheritance during a fork, and copying and freeing of credentials. +The main purpose for this scope is to give a security model a way to control +the aforementioned operations, especially in cases where the credentials +hold security model-private data. +.Pp +Notifications are made using the following function, which is internal to +.Nm : +.Pp +.Ft int Fn kauth_cred_hook "kauth_cred_t cred" "kauth_action_t action" \ +"void *arg0" "void *arg1" +.Pp +With the following actions: +.Bl -tag -width compact +.It Dv KAUTH_CRED_COPY +.Ar cred +are the credentials that are being copied. +.Ar arg0 +is a +.Ft kauth_cred_t +representing the destination +credentials. +That is the credentials are copied from +.Ar cred +to +.Ar arg0 . +.It Dv KAUTH_CRED_FORK +The credentials are being inherited from a parent to a child process during a +fork. +.Pp +.Ar cred +are the credentials of the lwp context doing the fork, and +.Ar arg0 +and +.Ar arg1 +are both +.Ft struct proc * +of the parent and child processes, respectively. +.It Dv KAUTH_CRED_CHROOT +The credentials in cred belong to a process whose root directory is +changed through +.Fn change_root +(see +.Xr vfs 9 ). +.Pp +.Ar Arg0 +is the new +.Ft struct cwdinfo * +of the process. +.It Dv KAUTH_CRED_FREE +The credentials in +.Ar cred +are being freed. +.It Dv KAUTH_CRED_INIT +The credentials in +.Ar cred +are being initialized. +.El +.Pp +Since this is a notify-only scope, all listeners are required to return +.Dv KAUTH_RESULT_ALLOW . +.Ss Credentials Accessors and Mutators +.Nm +has a variety of accessor and mutator routines to handle +.Ft kauth_cred_t +objects. +.Pp +The following routines can be used to access and modify the user- and +group-ids in a +.Ft kauth_cred_t : +.Bl -tag -width compact +.It Ft uid_t Fn kauth_cred_getuid "kauth_cred_t cred" +Returns the real user-id from +.Ar cred . +.It Ft uid_t Fn kauth_cred_geteuid "kauth_cred_t cred" +Returns the effective user-id from +.Ar cred . +.It Ft uid_t Fn kauth_cred_getsvuid "kauth_cred_t cred" +Returns the saved user-id from +.Ar cred . +.It Ft void Fn kauth_cred_setuid "kauth_cred_t cred" "uid_t uid" +Sets the real user-id in +.Ar cred +to +.Ar uid . +.It Ft void Fn kauth_cred_seteuid "kauth_cred_t cred" "uid_t uid" +Sets the effective user-id in +.Ar cred +to +.Ar uid . +.It Ft void Fn kauth_cred_setsvuid "kauth_cred_t cred" "uid_t uid" +Sets the saved user-id in +.Ar cred +to +.Ar uid . +.It Ft gid_t Fn kauth_cred_getgid "kauth_cred_t cred" +Returns the real group-id from +.Ar cred . +.It Ft gid_t Fn kauth_cred_getegid "kauth_cred_t cred" +Returns the effective group-id from +.Ar cred . +.It Ft gid_t Fn kauth_cred_getsvgid "kauth_cred_t cred" +Returns the saved group-id from +.Ar cred . +.It Ft void Fn kauth_cred_setgid "kauth_cred_t cred" "gid_t gid" +Sets the real group-id in +.Ar cred +to +.Ar gid . +.It Ft void Fn kauth_cred_setegid "kauth_cred_t cred" "gid_t gid" +Sets the effective group-id in +.Ar cred +to +.Ar gid . +.It Ft void Fn kauth_cred_setsvgid "kauth_cred_t cred" "gid_t gid" +Sets the saved group-id in +.Ar cred +to +.Ar gid . +.It Ft u_int Fn kauth_cred_getrefcnt "kauth_cred_t cred" +Return the reference count for +.Ar cred . +.El +.Pp +The following routines can be used to access and modify the group +list in a +.Ft kauth_cred_t : +.Bl -tag -width compact +.It Ft int Fn kauth_cred_ismember_gid "kauth_cred_t cred" "gid_t gid" \ +"int *resultp" +Checks if the group-id +.Ar gid +is a member in the group list of +.Ar cred . +.Pp +If it is, +.Ar resultp +will be set to one, otherwise, to zero. +.Pp +The return value is an error code, or zero for success. +.It Ft u_int Fn kauth_cred_ngroups "kauth_cred_t cred" +Return the number of groups in the group list of +.Ar cred . +.It Ft gid_t Fn kauth_cred_group "kauth_cred_t cred" "u_int idx" +Return the group-id of the group at index +.Ar idx +in the group list of +.Ar cred . +.It Ft int Fn kauth_cred_setgroups "kauth_cred_t cred" "const gid_t *groups" \ +"size_t ngroups" "uid_t gmuid" "enum uio_seg seg" +Copy +.Ar ngroups +groups from array pointed to by +.Ar groups +to the group list in +.Ar cred , +adjusting the number of groups in +.Ar cred +appropriately. +.Ar seg +should be either +.Dv UIO_USERSPACE +or +.Dv UIO_SYSSPACE +indicating whether +.Ar groups +is a user or kernel space address. +.Pp +Any groups remaining will be set to an invalid value. +.Pp +.Ar gmuid +is unused for now, and to maintain interface compatibility with the Darwin +KPI. +.Pp +The return value is an error code, or zero for success. +.It Ft int Fn kauth_cred_getgroups "kauth_cred_t cred" "gid_t *groups" \ +"size_t ngroups" "enum uio_seg seg" +Copy +.Ar ngroups +groups from the group list in +.Ar cred +to the buffer pointed to by +.Ar groups . +.Ar seg +should be either +.Dv UIO_USERSPACE +or +.Dv UIO_SYSSPACE +indicating whether +.Ar groups +is a user or kernel space address. +.Pp +The return value is an error code, or zero for success. +.El +.Ss Credential Private Data +.Nm +provides an interface to allow attaching security-model private data to +credentials. +.Pp +The use of this interface has two parts that can be divided to direct and +indirect control of the private-data. +Directly controlling the private data is done by using the below routines, +while the indirect control is often dictated by events such as process +fork, and is handled by listening on the credentials scope (see above). +.Pp +Attaching private data to credentials works by registering a key to serve +as a unique identifier, distinguishing various sets of private data that +may be associated with the credentials. +Registering, and deregistering, a key is done by using these routines: +.Bl -tag -width compact +.It Ft int Fn kauth_register_key "secmodel_t sm" "kauth_key_t *keyp" +Register new key for private data for security model +.Ar sm . +.Ar keyp +will be used to return the key to be used in further calls. +.Pp +The function returns 0 on success and an error code (see +.Xr errno 2 ) +on failure. +.It Ft int Fn kauth_deregister_key "kauth_key_t key" +Deregister private data key +.Ar key . +.El +.Pp +Once registered, private data may be manipulated by the following routines: +.Bl -tag -width compact +.It Ft void Fn kauth_cred_setdata "kauth_cred_t cred" "kauth_key_t key" \ +"void *data" +Set private data for +.Ar key +in +.Ar cred +to be +.Ar data . +.It Ft void * Fn kauth_cred_getdata "kauth_cred_t cred" "kauth_key_t key" +Retrieve private data for +.Ar key +in +.Ar cred . +.El +.Pp +Note that it is required to use the above routines every time the private +data is changed, i.e., using +.Fn kauth_cred_getdata +and later modifying the private data should be accompanied by a call to +.Fn kauth_cred_setdata +with the +.Dq new +private data. +.Ss Credential Inheritance and Reference Counting +.Nm +provides an interface for handling shared credentials. +.Pp +When a +.Ft kauth_cred_t +is first allocated, its reference count is set to 1. +However, with time, its reference count can grow as more objects (processes, +LWPs, files, etc.) reference it. +.Pp +The following routines are available for managing credentials reference +counting: +.Bl -tag -width compact +.It Ft kauth_cred_t Fn kauth_cred_hold "kauth_cred_t cred" +Increases reference count to +.Ar cred +by one and returns +.Ar cred +verbatim. +.It Ft void Fn kauth_cred_free "kauth_cred_t cred" +Decreases the reference count to +.Ar cred +by one. +.Pp +If the reference count dropped to zero, the memory used by +.Ar cred +will be freed. +.El +.Pp +Credential inheritance happens during a +.Xr fork 2 , +and is handled by the following function: +.Pp +.Ft void Fn kauth_proc_fork "struct proc *parent" "struct proc *child" +.Pp +When called, it references the parent's credentials from the child, +and calls the credentials scope's hook with the +.Dv KAUTH_CRED_FORK +action to allow security model-specific handling of the inheritance +to take place. +.Ss Credentials Memory Management +Data-structures for credentials, listeners, and scopes are allocated from +memory pools managed by the +.Xr pool 9 +subsystem. +.Pp +The +.Ft kauth_cred_t +objects have their own memory management routines: +.Bl -tag -width compact +.It Ft kauth_cred_t Fn kauth_cred_alloc "void" +Allocates a new +.Ft kauth_cred_t , +initializes its lock, and sets its reference count to one. +.El +.Ss Conversion Routines +Sometimes it might be necessary to convert a +.Ft kauth_cred_t +to userland's view of credentials, a +.Ft struct uucred , +or vice versa. +.Pp +The following routines are available for these cases: +.Bl -tag -width compact +.It Ft void Fn kauth_uucred_to_cred "kauth_cred_t cred" "const struct uucred *uucred" +Convert userland's view of credentials to a +.Ft kauth_cred_t . +.Pp +This includes effective user- and group-ids, a number of groups, and a group +list. +The reference count is set to one. +.Pp +Note that +.Nm +will try to copy as many groups as can be held inside a +.Ft kauth_cred_t . +.It Ft void Fn kauth_cred_to_uucred "struct uucred *uucred" "const kauth_cred_t cred" +Convert +.Ft kauth_cred_t +to userland's view of credentials. +.Pp +This includes effective user- and group-ids, a number of groups, and a group +list. +.Pp +Note that +.Nm +will try to copy as many groups as can be held inside a +.Ft struct uucred . +.It Ft int Fn kauth_cred_uucmp "kauth_cred_t cred" "struct uucred *uucred" +Compares +.Ar cred +with the userland credentials in +.Ar uucred . +.Pp +Common values that will be compared are effective user- and group-ids, and +the group list. +.El +.Ss Miscellaneous Routines +Other routines provided by +.Nm +are: +.Bl -tag -width compact +.It Ft void Fn kauth_cred_clone "kauth_cred_t cred1" "kauth_cred_t cred2" +Clone credentials from +.Ar cred1 +to +.Ar cred2 , +except for the lock and reference count. +.It Ft kauth_cred_t Fn kauth_cred_dup "kauth_cred_t cred" +Duplicate +.Ar cred . +.Pp +What this routine does is call +.Fn kauth_cred_alloc +followed by a call to +.Fn kauth_cred_clone . +.It Ft kauth_cred_t Fn kauth_cred_copy "kauth_cred_t cred" +Works like +.Fn kauth_cred_dup , +except for a few differences. +.Pp +If +.Ar cred +already has a reference count of one, it will be returned. +Otherwise, a new +.Ft kauth_cred_t +will be allocated and the credentials from +.Ar cred +will be cloned to it. +Last, a call to +.Fn kauth_cred_free +for +.Ar cred +will be done. +.It Ft kauth_cred_t Fn kauth_cred_get "void" +Return the credentials associated with the current LWP. +This does not change the reference count of the resulting +.Ft kauth_cred_t +object. +.El +.Ss Scope Management +.Nm +provides routines to manage the creation and deletion of scopes on the +system. +.Pp +Note that the built-in scopes, the +.Dq generic +scope and the +.Dq process +scope, can't be deleted. +.Bl -tag -width compact +.It Ft kauth_scope_t Fn kauth_register_scope "const char *id" \ +"kauth_scope_callback_t cb" "void *cookie" +Register a new scope on the system. +.Ar id +is the name of the scope, usually in reverse DNS-like notation. +For example, +.Dq org.netbsd.kauth.myscope . +.Ar cb +is the default listener, to which authorization requests for this scope +will be dispatched to. +.Ar cookie +is optional user-data that will be passed to all listeners +during authorization on the scope. +.It Ft void Fn kauth_deregister_scope "kauth_scope_t scope" +Deregister +.Ar scope +from the scopes available on the system, and free the +.Ft kauth_scope_t +object +.Ar scope . +.El +.Ss Listener Management +Listeners in +.Nm +are authorization callbacks that are called during an authorization +request in the scope which they belong to. +.Pp +When an authorization request is made, all listeners associated with +a scope are called to allow, deny, or defer the request. +.Pp +It is enough for one listener to deny the request in order for the +request to be denied; but all listeners are called during an authorization +process none-the-less. +All listeners are required to allow the request for it to be granted, +and in a case where all listeners defer the request \(em leaving the +decision for other listeners \(em the request is denied. +.Pp +The following KPI is provided for the management of listeners: +.Bl -tag -width compact +.It Ft kauth_listener_t Fn kauth_listen_scope "const char *id" \ +"kauth_scope_callback_t cb" "void *cookie" +Create a new listener on the scope with the id +.Ar id , +setting the default listener to +.Ar cb . +.Ar cookie +is optional user-data that will be passed to the listener when called +during an authorization request. +.It Ft void Fn kauth_unlisten_scope "kauth_listener_t listener" +Removes +.Ar listener +from the scope which it belongs to, ensuring it won't be called again, +and frees the +.Ft kauth_listener_t +object +.Ar listener . +.El +.Pp +.Nm +provides no means for synchronization within listeners. +It is the programmer's responsibility to make sure data used by the +listener is properly locked during its use, as it can be accessed +simultaneously from the same listener called multiple times. +It is also the programmer's responsibility to do garbage collection after +the listener, possibly freeing any allocated data it used. +.Pp +The common method to do the above is by having a reference count to +each listener. +On entry to the listener, this reference count should be raised; on +exit, lowered. +.Pp +During the removal of a listener, first +.Fn kauth_scope_unlisten +should be called to make sure the listener code will not be entered in +the future. +Then, the code should wait (possibly sleeping) until the reference count +drops to zero. +When that happens, it is safe to do the final cleanup. +.Pp +Listeners might sleep, so no locks can be held when calling an authorization +wrapper. +.Sh EXAMPLES +Older code had no abstraction of the security model, so most privilege +checks looked like this: +.Bd -literal -offset indent +if (suser(cred, &acflag) == 0) + /* allow privileged operation */ +.Ed +.Pp +Using the new interface, you must ask for a specific privilege explicitly. +For example, checking whether it is possible to open a socket would look +something like this: +.Bd -literal -offset indent +if (kauth_authorize_network(cred, KAUTH_NETWORK_SOCKET, + KAUTH_REQ_NETWORK_SOCKET_OPEN, PF_INET, SOCK_STREAM, + IPPROTO_TCP) == 0) + /* allow opening the socket */ +.Ed +.Pp +Note that the +.Em securelevel +implications were also integrated into the +.Nm +framework so you don't have to note anything special in the call to the +authorization wrapper, but rather just have to make sure the security +model handles the request as you expect it to. +.Pp +To do that you can just +.Xr grep 1 +in the relevant security model directory and have a look at the code. +.Sh EXTENDING KAUTH +Although +.Nm +provides a large set of both detailed and more or less generic requests, +it might be needed eventually to introduce more scopes, actions, or +requests. +.Pp +Adding a new scope should happen only when an entire subsystem is +introduced and it is assumed other parts of the kernel may want to +interfere with its inner-workings. +When a subsystem that has the potential of impacting the security +of the system is introduced, existing security modules must be updated +to also handle actions on the newly added scope. +.Pp +New actions should be added when sets of operations not covered at all +belong in an already existing scope. +.Pp +Requests (or sub-actions) can be added as subsets of existing actions +when an operation that belongs in an already covered area is introduced. +.Pp +Note that all additions should include updates to this manual, the +security models shipped with +.Nx , +and the example skeleton security model. +.Sh SEE ALSO +.Xr secmodel 9 +.Sh HISTORY +The kernel authorization framework first appeared in Mac OS X 10.4. +.Pp +The kernel authorization framework in +.Nx +first appeared in +.Nx 4.0 , +and is a clean-room implementation based on Apple TN2127, available at +.Lk http://developer.apple.com/technotes/tn2005/tn2127.html +.Sh NOTES +As +.Nm +in +.Nx +is still under active development, it is likely that the ABI, and possibly the +API, will differ between +.Nx +versions. +Developers are to take notice of this fact in order to avoid building code +that expects one version of the ABI and running it in a system with a different +one. +.Sh AUTHORS +.An Elad Efrat Aq Mt elad@NetBSD.org +implemented the kernel authorization framework in +.Nx . +.Pp +.An Jason R. Thorpe Aq Mt thorpej@NetBSD.org +provided guidance and answered questions about the Darwin implementation. diff --git a/static/netbsd/man9/kcopy.9 b/static/netbsd/man9/kcopy.9 new file mode 100644 index 00000000..e43f4e75 --- /dev/null +++ b/static/netbsd/man9/kcopy.9 @@ -0,0 +1,60 @@ +.\" $NetBSD: kcopy.9,v 1.7 2017/04/06 15:57:23 dholland Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 6, 2017 +.Dt KCOPY 9 +.Os +.Sh NAME +.Nm kcopy +.Nd copy data with abort on page fault +.Sh SYNOPSIS +.In sys/systm.h +.Ft int +.Fn kcopy "const void *src" "void *dst" "size_t len" +.Sh DESCRIPTION +.Fn kcopy +copies +.Fa len +bytes from +.Fa src +to +.Fa dst , +aborting if a fatal page fault is encountered. +.Pp +.Fn kcopy +must save and restore the old fault handler since it is called by +.Xr uiomove 9 , +which may be in the path of servicing a non-fatal page fault. +.Sh RETURN VALUES +.Fn kcopy +returns 0 on success and an error number on failure. +.Sh SEE ALSO +.Xr errno 2 , +.Xr memcpy 9 , +.Xr uiomove 9 diff --git a/static/netbsd/man9/kcpuset.9 b/static/netbsd/man9/kcpuset.9 new file mode 100644 index 00000000..0fcca7a2 --- /dev/null +++ b/static/netbsd/man9/kcpuset.9 @@ -0,0 +1,354 @@ +.\" $NetBSD: kcpuset.9,v 1.9 2014/03/18 18:20:40 riastradh Exp $ */ +.\" +.\" Copyright (c) 2011 Jukka Ruohonen <jruohonen.iki.fi> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 17, 2013 +.Dt KCPUSET 9 +.Os +.Sh NAME +.Nm kcpuset , +.Nm kcpuset_create , +.Nm kcpuset_destroy , +.Nm kcpuset_clone , +.Nm kcpuset_copy , +.Nm kcpuset_use , +.Nm kcpuset_unuse , +.Nm kcpuset_copyin , +.Nm kcpuset_copyout , +.Nm kcpuset_zero , +.Nm kcpuset_fill , +.Nm kcpuset_set , +.Nm kcpuset_clear , +.Nm kcpuset_isset , +.Nm kcpuset_isotherset , +.Nm kcpuset_iszero , +.Nm kcpuset_match , +.Nm kcpuset_intersect , +.Nm kcpuset_merge , +.Nm kcpuset_remove , +.Nm kcpuset_ffs , +.Nm kcpuset_ffs_intersecting , +.Nm kcpuset_countset , +.Nm kcpuset_atomic_set , +.Nm kcpuset_atomic_clear , +.Nm kcpuset_atomicly_intersect , +.Nm kcpuset_atomicly_merge , +.Nm kcpuset_atomicly_remove , +.Nm kcpuset_export_32 +.Nd dynamic kernel CPU sets +.Sh SYNOPSIS +.In sys/kcpuset.h +.Ft void +.Fn kcpuset_create "kcpuset_t **retkcp" "bool zero" +.Ft void +.Fn kcpuset_destroy "kcpuset_t *kcp" +.Ft void +.Fn kcpuset_clone "kcpuset_t **retkcp" "const kcpuset_t *skcp" +.Ft void +.Fn kcpuset_copy "kcpuset_t *dkcp" "const kcpuset_t *skcp" +.Ft void +.Fn kcpuset_use "kcpuset_t *kcp" +.Ft void +.Fn kcpuset_unuse "kcpuset_t *kcp" "kcpuset_t **lst" +.Ft int +.Fn kcpuset_copyin "const cpuset_t *ucp" "kcpuset_t *kcp" "size_t len" +.Ft int +.Fn kcpuset_copyout "kcpuset_t *kcp" "cpuset_t *ucp" "size_t len" +.Ft void +.Fn kcpuset_zero "kcpuset_t *kcp" +.Ft void +.Fn kcpuset_fill "kcpuset_t *kcp" +.Ft void +.Fn kcpuset_set "kcpuset_t *kcp" "cpuid_t cpu" +.Ft void +.Fn kcpuset_clear "kcpuset_t *kcp" "cpuid_t cpu" +.Ft bool +.Fn kcpuset_isset "const kcpuset_t * kcp" "cpuid_t cpu" +.Ft bool +.Fn kcpuset_isotherset "const kcpuset_t * kcp" "cpuid_t cpu" +.Ft bool +.Fn kcpuset_iszero "const kcpuset_t *kcp" +.Ft bool +.Fn kcpuset_intersecting_p "const kcpuset_t *kcp1" "const kcpuset_t *kcp2" +.Ft bool +.Fn kcpuset_match "const kcpuset_t *kcp1" "const kcpuset_t *kcp2" +.Ft void +.Fn kcpuset_intersect "kcpuset_t *kcp1" "const kcpuset_t *kcp2" +.Ft void +.Fn kcpuset_merge "kcpuset_t *kcp1" "const kcpuset_t *kcp2" +.Ft void +.Fn kcpuset_remove "kcpuset_t *kcp1" "const kcpuset_t *kcp2" +.Ft cpuid_t +.Fn kcpuset_ffs "const kcpuset_t *kcp" +.Ft cpuid_t +.Fn kcpuset_ffs_intersecting "const kcpuset_t *kcp1" "const kcpuset_t *kcp2" +.Ft int +.Fn kcpuset_countset "const kcpuset_t *kcp" +.Ft void +.Fn kcpuset_atomic_set "kcpuset_t *kcp" "cpuid_t cpu" +.Ft void +.Fn kcpuset_atomic_clear "kcpuset_t *kcp" "cpuid_t cpu" +.Ft void +.Fn kcpuset_atomicly_intersect "kcpuset_t *kcp1" "const kcpuset_t *kcp2" +.Ft void +.Fn kcpuset_atomicly_merge "kcpuset_t *kcp1" "const kcpuset_t *kcp2" +.Ft void +.Fn kcpuset_atomicly_remove "kcpuset_t *kcp1" "const kcpuset_t *kcp2" +.Ft void +.Fn kcpuset_export_u32 "const kcpuset_t *kcp" "uint32_t *bitfield" "size_t len" +.Sh DESCRIPTION +The machine-independent +.Nm +subsystem provides support for dynamic processor sets. +Conceptually +.Nm +can be understood to be the kernel equivalent of the user space +.Xr cpuset 3 +interface. +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn kcpuset_create "retkcp" "zero" +The +.Fn kcpuset_create +function creates a dynamic +.Tn CPU +set and stores the result to +.Fa retkcp . +If the boolean +.Fa zero +is not false, the allocated set is also initialized to zero. +.It Fn kcpuset_destroy "kcp" +Destroys the +.Tn CPU +set +.Fa kcp +and schedules any linked CPU sets for deferred destruction. +.It Fn kcpuset_copy "dkcp" "skcp" +Copies the +.Tn CPU +set pointed by +.Fa skcp +to +.Fa dkcp . +.It Fn kcpuset_clone "retkcp" "skcp" +Creates a dynamic +.Tn CPU +set and stores the result to +.Fa retkcp +and copies the +.Tn CPU +set pointed by +.Fa skcp +to the new +.Tn CPU +set. +.It Fn kcpuset_use "kcp" +Marks +.Fa kcp +as being in use by increasing the reference count of the object. +Note that initially +.Fn kcpuset_create +sets the reference count to 1. +.It Fn kcpuset_unuse "kcp" "lst" +Decreases the internal reference count of +.Fa kcp , +and on the last reference (when the count reaches zero), destroys +.Fa kcp . +If +.Fa lst +is not +.Dv NULL , +then instead of destroying, +.Fa kcp +will be added to the +.Fa lst +list for a deferred destruction. +.It Fn kcpuset_copyin "ucp" "kcp" "len" +Copies the +.Fa len +bytes long user-space +.Tn CPU +set +.Fa ucp +to the kernel +.Tn CPU +set +.Fa kcp . +.It Fn kcpuset_copyout "kcp" "ucp" "len" +Copies the kernel +.Tn CPU +set +.Fa kcp +to the user-space +.Tn CPU +set +.Fa ucp . +.It Fn kcpuset_zero "kcp" +Clears the set +.Fa kcp . +.It Fn kcpuset_fill "kcp" +Fills the whole set +.Fa kcp +with ones. +.It Fn kcpuset_set "kcp" "cpu" +Adds +.Fa cpu +to the set +.Fa kcp . +.It Fn kcpuset_clear "kcp" "cpu" +Removes +.Fa cpu +from the set +.Fa kcp . +.It Fn kcpuset_isset "kcp" "cpu" +Returns true if +.Fa cpu +is part of the +.Tn CPU +set +.Fa kcp . +.It Fn kcpuset_isotherset "kcp" "cpu" +Returns true if there any CPUs +other than +.Fa cpu +in the +.Tn CPU +set +.Fa kcp . +.It Fn kcpuset_iszero "kcp" +Returns true if the set +.Fa kcp +is empty. +.It Fn kcpuset_match "kcp1" "kcp2" +Compares the sets +.Fa kcp1 +and +.Fa kcp2 , +returning true if these are identical. +.It Fn kcpuset_intersect "kcp1" "kcp2" +Removes any +.Tn CPU +not set in +.Fa kcp2 +from the set +.Fa kcp1 . +.It Fn kcpuset_merge "kcp1" "kcp2" +Merges the set +.Fa kcp2 +to the set +.Fa kcp1 . +.It Fn kcpuset_remove "kcp1" "kcp2" +Removes any +.Tn CPU +present in +.Fa kcp2 +from the set +.Fa kcp1 . +.It Fn kcpuset_ffs "kcp" +Returns the lowest numbered +.Ft cpu +present in +.Fa kcp +plus 1. +If +.Fa kcp +is empty, a value of 0 is returned. +.Fa kcp +.It Fn kcpuset_ffs_intersecting "kcp1" "kcp2" +Returns the lowest numbered +.Ft cpu +present in the intersection of +.Fa kcp1 +and +.Fa kcp2 +plus 1. +If the intersection is empty, a value of 0 is returned. +.It Fn kcpuset_countset "kcp" +Counts how many CPUs are in the set +.Fa kcp . +.It Fn kcpuset_atomic_set "kcp" "cpu" +The +.Fn kcpuset_atomic_set +function operates as +.Fn kcpuset_set , +but the operation is atomic; see +.Xr atomic_ops 3 +for more details. +.It Fn kcpuset_atomic_clear "kcp" "cpu" +Removes +.Fa cpu +from the +.Tn CPU +set +.Fa kcp +atomically. +.It Fn kcpuset_atomicly_intersect "kcp1" "kcp2" +The +.Fn kcpuset_atomicly_intersect +function operates as +.Fn kcpuset_intersect , +but the operation is performed using atomic operations; see +.Xr atomic_ops 3 +for more details. +.It Fn kcpuset_atomicly_merge "kcp1" "kcp2" +The +.Fn kcpuset_atomicly_merge +function operates as +.Fn kcpuset_merge , +but the operation is performed using atomic operations; see +.Xr atomic_ops 3 +for more details. +.It Fn kcpuset_atomicly_remove "kcp1" "kcp2" +The +.Fn kcpuset_atomicly_remove +function operates as +.Fn kcpuset_remove , +but the operation is performed using atomic operations; see +.Xr atomic_ops 3 +for more details. +.It Fn kcpuset_export_u32 "kcp" "bitfield" "len" +Exports the CPU set +.Fa kcp +into a format of 32-bit integer array, +specified by +.Fa bitfield +and length in bytes by +.Fa len . +An integers is in the host byte-order and represents a bit field. +The first bit at index zero represents CPU number 0, and so on. +.El +.Sh CODE REFERENCES +The +.Nm +subsystem is implemented within +.Pa sys/kern/subr_kcpuset.c . +.Sh SEE ALSO +.Xr cpuset 3 +.Sh HISTORY +The +.Nm +subsystem first appeared in +.Nx 6.0 . diff --git a/static/netbsd/man9/kernhist.9 b/static/netbsd/man9/kernhist.9 new file mode 100644 index 00000000..6ee93408 --- /dev/null +++ b/static/netbsd/man9/kernhist.9 @@ -0,0 +1,286 @@ +.\" $NetBSD: kernhist.9,v 1.10 2021/12/11 19:24:19 mrg Exp $ +.\" +.\" Copyright (c) 2015 Matthew R. Green +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd October 25, 2017 +.Dt KERNHIST 9 +.Os +.Sh NAME +.Nm kernhist +.Nd basic low-level kernel history tracing mechanism +.Sh SYNOPSIS +.Cd options KERNHIST +.In sys/kernhist.h +.Pp +Below are the functions and macros provided by kernhist.h: +.Pp +.Fn KERNHIST_DECL "name" +.Fn KERNHIST_DEFINE "name" +.Fn KERNHIST_INIT "name" "unsigned num_entries" +.Fn KERNHIST_INITIALIZER "name" "void *buffer" +.Fn KERNHIST_INIT_STATIC "struct kern_history name" "void *buffer" +.Fn KERNHIST_LOG "struct kern_history name" "const char *fmt" "u_long arg0" \ + "u_long arg1" "u_long arg2" "u_long arg3" +.Fn KERNHIST_CALLARGS "struct kern_history name" "const char *fmt" \ + "u_long arg0" "u_long arg1" "u_long arg2" "u_long arg3" +.Fn KERNHIST_CALLED "struct kern_history name" +.Fn KERNHIST_FUNC "fname" +.Fn KERNHIST_DUMP "struct kern_history name" +.Ft void +.Fn kernhist_dump "struct kern_history *history" +.Ft void +.Fn kernhist_dumpmask "u_int32_t bitmask" +.Ft void +.Fn kernhist_print "void (*pr)(const char *, ...)" +.Sh DESCRIPTION +The +.Nm +facility provides a very low-level tracing facility that can be called +extremely early in the kernel initialisation. +It provides a simple restricted +.Xr printf 3 +format syntax with a maximum of 4 arguments, each of type +.Vt uintmax_t . +.Pp +.Cd options KERNHIST +must be present in the kernel configuration to enable these functions and +macros. +.Pp +A kernel history is a fixed-size buffer, either statically or dynamically +allocated, that is written and read on a circular basis. +Each entry includes the time the entry was made, the CPU from which the entry +was recorded, the +.Xr printf 3 +like format string and length, the function name and length, the unique call +count for this function, and the 4 arguments. +.Pp +The history event data can be viewed using the +.Fl U +and +.Fl u +.Ar histname +options to +.Xr vmstat 1 , +or by using the +.Ic show kernhist +command in +.Xr ddb 4 . +User-written programs can retrieve history data from the kernel using the +.Xr sysctl 9 +variable kern.hist.histname. +.Pp +The format string must be a literal string that can be referenced later as it +is not stored with the event (only a pointer to the format string is stored). +It should only contain conversion specifiers suitable for +.Vt uintmax_t +sized values, such as +.Dq %jx , +.Dq %ju , +and +.Dq %jo , +and address (pointer) arguments should be cast to +.Vt uintptr_t +to avoid compiler errors on architectures where pointers are smaller than +.Vt uintmax_t +integers. +Conversion specifiers without a length modifier, and specifiers with length +modifiers other than j, should not be used. +.Pp +Conversion specifiers that require additional dereferences of their +corresponding arguments, such as +.Dq %s , +will not work in +.Xr vmstat 1 , +but will work when called from +.Xr ddb 4 . +.Pp +These macros provide access to most kernel history functionality: +.Bl -tag -width 4n +.It Fn KERNHIST_DECL name +Declare an extern struct kern_history +.Fa name . +.It Fn KERNHIST_DEFINE name +Define a struct kern_history +.Fa name . +.It Fn KERNHIST_INIT name num_entries +Dynamically initialise a kernel history called name with +.Ar num_entries +entries. +.It Fn KERNHIST_INITIALIZER name buffer +Initialise a statically defined kernel history called +.Fa name +using +.Fa buffer +as a static allocation used for the buffer. +.It Fn KERNHIST_INIT_STATIC name buffer +Initialise a statically declared kernel history +.Fa name , +using the statically allocated +.Fa buffer +for history entries. +.It Fn KERNHIST_FUNC fname +Declare necessary variables for +.Nm +to be used this function. +Callable only once per function. +.It Fn KERNHIST_LOG name fmt arg0 arg1 arg2 arg3 +For the given kernel history +.Fa name , +log the format string and arguments in the history as a unique event. +.It Fn KERNHIST_CALLED name +Declare a function as being called. +Either this or +.Fn KERNHIST_CALLARGS +must be used once, near the function entry point, to maintain the number of +times the function has been called. +.It Fn KERNHIST_CALLARGS name fmt arg0 arg1 arg2 arg3 +A combination of +.Fn KERNHIST_CALLED +and +.Fn KERNHIST_LOG +that avoids having a +.Dq called! +log message in addition to a message containing normal arguments with a +format string. +.It Fn KERNHIST_DUMP name +Call +.Fn kernhist_dump +on the named kernel history. +.It Fn kernhist_dump history +Dump the entire contents of the specified kernel history. +.It Fn kernhist_dumpmask bitmask +Used to dump a well known list of kernel histories. +The following histories and their respective value (as seen in +.Pa kernhist.h ) +are available: +.Bl -tag -width KERNHIST_SCDEBUGHISTXXX +.It KERNHIST_UVMMAPHIST +Include events from +.Dq maphist . +.It KERNHIST_UVMPDHIST +Include events from +.Dq pdhist . +.It KERNHIST_UVMUBCHIST +Include events from +.Dq ubchist . +.It KERNHIST_UVMLOANHIST +Include events from +.Dq loanhist . +.It KERNHIST_USBHIST +Include events from +.Dq usbhist . +.It KERNHIST_SCDEBUGHIST +Include events from +.Dq scdebughist . +.It KERNHIST_BIOHIST +Include events from +.Dq biohist . +.El +.It Fn kernhist_print pr +Print all the kernel histories to the kernel message buffer. +The +.Fn pr +argument is currently ignored. +.El +.Sh CODE REFERENCES +The +.Nm +functionality is implemented within the files +.Pa sys/sys/kernhist.h +and +.Pa sys/kern/kern_history.c . +The former file contains the definitions of data structures used to export +the +.Nm data +via the +.Xr sysctl 9 +mechanism. +.Sh SEE ALSO +.Xr vmstat 1 , +.Xr usbdi 9 , +.Xr uvm 9 +.\" .Sh EXAMPLES +.\" +.\" add example here of code usage +.\" +.Sh HISTORY +A uvm-specific version of the +.Nm +facility first appeared in +.Nx 1.4 . +The generalized version of +.Nm +appeared in +.Nx 6.0 . +The +.Xr sysctl 9 +interface to +.Nm +was introduced in +.Nx 8.0 . +.Sh AUTHORS +.An -nosplit +.Nm +was originally written by +.An Charles D. Cranor +as part of the +.Xr uvm 9 +framework, under the name UVMHIST. +.An Matthew R. Green +generalized it into its current form to be available to non +.Xr uvm 9 +frameworks. +.An Paul Goyette Aq Mt pgoyette@NetBSD.org +provided the +.Xr sysctl 9 +interface. +.Sh BUGS +The restriction against using +.Dq %s +.Xr printf 3 +specifier in format strings could be reduced to literal strings (such as +the table of system call names) if +.Xr vmstat 1 +was extended to convert +.Dq %s +strings into user addresses after copying the strings out. +.Pp +.Fn KERNHIST_FUNC +could be converted to use __func__ always, as all the callers already do. +.Pp +The +.Fn kernhist_dumpmask +list of masks could be properly published and made available, and as such +this function may be removed in a future release. +.Pp +In addition to a statically-defined set of kernel histories, it would be +possible to allow modular code to register and unregister their own +histories dynamically, when a module is loaded or unloaded. +.Pp +The +.Fn kernhist_print +function currently ignores its +.Fa pr +argument. diff --git a/static/netbsd/man9/kfilter_register.9 b/static/netbsd/man9/kfilter_register.9 new file mode 100644 index 00000000..1369ef7d --- /dev/null +++ b/static/netbsd/man9/kfilter_register.9 @@ -0,0 +1,147 @@ +.\" $NetBSD: kfilter_register.9,v 1.11 2020/10/31 16:03:01 christos Exp $ +.\" +.\" Copyright (c) 2001, 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation is derived from text contributed by +.\" Luke Mewburn. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 31, 2020 +.Dt KFILTER_REGISTER 9 +.Os +.Sh NAME +.Nm kfilter_register , +.Nm kfilter_unregister +.Nd add or remove kernel event filters +.Sh SYNOPSIS +.In sys/event.h +.Ft int +.Fn kfilter_register "const char *name" "struct filterops *filtops" "int *retfilter" +.Ft int +.Fn kfilter_unregister "const char *name" +.Sh DESCRIPTION +The +.Fn kfilter_register +function adds a new kernel event filter (kfilter) to the system, +for use by callers of +.Xr kqueue 2 +and +.Xr kevent 2 . +.Fa name +is the name of the new filter (which must not already exist), and +.Fa filtops +is a pointer to a +.Va filterops +structure which describes the filter operations. +Both +.Fa name +and +.Fa filtops +will be copied to an internal data structure, and a new filter number +will be allocated. +If +.Fa retfilter +is not +.Dv NULL , +then the new filter number will be returned in the address pointed at by +.Fa retfilter . +.Pp +The +.Fn kfilter_unregister +function removes a kfilter named +.Fa name +that was previously registered with +.Fn kfilter_register . +If a filter with the same +.Fa name +is later reregistered with +.Fn kfilter_register , +it will get a different filter number +(i.e., filter numbers are not recycled). +It is not possible to unregister the system filters +(i.e., those that start with +.Dq EVFILT_ +and are documented in +.Xr kqueue 2 ) . +.Pp +The +.Va filterops +structure is defined as follows: +.Bd -literal -offset indent +struct filterops { + int f_isfd; /* true if ident == filedescriptor */ + int (*f_attach)(struct knote *kn); + /* called when knote is ADDed */ + void (*f_detach)(struct knote *kn); + /* called when knote is DELETEd */ + int (*f_event)(struct knote *kn, long hint); + /* called when event is triggered */ + void (*f_touch)(struct knote *kn, struct kevent *kev, long hint); + /* called during registration and event + * processing to provide custom handling + * of event fflags and data + */ +}; +.Ed +.Pp +If the filter operation is for a file descriptor, +.Va f_isfd +should be non-zero, otherwise it should be zero. +This controls where the +.Xr kqueue 2 +system stores the knotes for an object. +.Sh RETURN VALUES +.Fn kfilter_register +returns 0 on success, +.Er EINVAL +if there's an invalid argument, or +.Er EEXIST +if the filter already exists, +.Pp +.Fn kfilter_unregister +returns 0 on success, +.Er EINVAL +if there's an invalid argument, or +.Er ENOENT +if the filter doesn't exist. +.Sh SEE ALSO +.Xr kqueue 2 , +.Xr free 9 , +.Xr knote 9 , +.Xr malloc 9 +.Sh HISTORY +The +.Fn kfilter_register +and +.Fn kfilter_unregister +functions first appeared in +.Nx 2.0 . +.Sh AUTHORS +The +.Fn kfilter_register +and +.Fn kfilter_unregister +functions were implemented by +.An Luke Mewburn +.Aq lukem@NetBSD.org . diff --git a/static/netbsd/man9/klua_lock.9 b/static/netbsd/man9/klua_lock.9 new file mode 100644 index 00000000..4b3a391c --- /dev/null +++ b/static/netbsd/man9/klua_lock.9 @@ -0,0 +1,181 @@ +.\" $NetBSD: klua_lock.9,v 1.5 2017/04/16 06:36:03 wiz Exp $ +.\" +.\" Copyright (c) 2015 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Kamil Rytarowski. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 15, 2017 +.Dt KLUA_LOCK 9 +.Os +.Sh NAME +.Nm klua_lock , +.Nm klua_unlock , +.Nm klua_close , +.Nm klua_newstate , +.Nm kluaL_newstate +.Nd Lua kernel bindings +.Sh SYNOPSIS +.In sys/lua.h +.Ft void +.Fn klua_lock "klua_State *K" +.Ft void +.Fn klua_unlock "klua_State *K" +.Ft void +.Fn klua_close "klua_State *K" +.Ft "klua_State *" +.Fo klua_newstate +.Fa "lua_Alloc f" +.Fa "void *ud" +.Fa "const char *name" +.Fa "const char *desc" +.Fa "int ipl" +.Fc +.Ft "klua_State *" +.Fn kluaL_newstate "void *ud" "const char *name" "const char *desc" "int ipl" +.Sh DESCRIPTION +The Lua kernel bindings are designed to provide functionality to reuse Lua +scripts maintained by the +.Xr lua 9 +driver. +A +.Xr driver 9 +can be extended with dynamically managed Lua code with optional functionality +injected from userland with the +.Xr luactl 8 +utility. +.Pp +The kernel structure +.Ft klua_State +is defined as follows: +.Bd -literal +typedef struct _klua_State { + lua_State *L; + kmutex_t ks_lock; + bool ks_user; /* state created by user (ioctl) */ +} klua_State; +.Ed +.Pp +The first element +.Ft L +of the structure points to a standard Lua state structure. +The second element +.Ft ks_lock +is used to protect integrity during cross-thread access to the Lua state. +The third element +.Ft ks_user +indicates whether the structure was created from the kernel space or userland. +This parameter is used in the logic of +.Xr luactl 8 , +to prohibit the destruction of state from an opposing side. +Destroying kernel state from userland for example. +.Pp +The kernel Lua API is designed after the userland Lua API. +.Ss List of Functions +.Bl -column "kluaL_newstateX" "luaL_newstateX" "create a Lua state with custom allocatorX" +.It Sy kernel API Ta Sy userland API Ta Sy Description +.It Xr klua_lock 3 Ta lua_lock Ta lock a Lua state +.It Xr klua_unlock 3 Ta lua_unlock Ta unlock a Lua state +.It Xr klua_close 3 Ta lua_close Ta destroy a Lua state +.It Xr klua_newstate 3 Ta lua_newstate Ta create a Lua state with custom allocator +.It Xr kluaL_newstate 3 Ta luaL_newstate Ta create a Lua state +.El +.Pp +The +.Fn klua_lock +and +.Fn klua_unlock +functions must be used before and after the use of the +.Ft klua_State +structure. +The Lua state is not thread safe and this is the standard mechanism to overcome +this limitation. +These functions are also used by the +.Xr luactl 8 +utility when accessing +.Fa K . +.Pp +The +.Fn klua_close +function destroys the kernel Lua state. +.Pp +The +.Fn klua_newstate +and +.Fn kluaL_newstate +functions are used to create and register a new kernel Lua state. +.Fn klua_newstate +takes an additional standard parameter of type +.Fa f , +defined by the proper Lua release and an opaque pointer +.Fa ud +that Lua passes to the allocator in every call. +The +.Ft name +parameter identifies the kernel Lua state with a text literal. +It must not begin with the +.Dq _ +character and must be unique for the +.Xr lua 9 +device. +The +.Ft desc +parameter describes the Lua state in plain text. +The +.Ft ipl +argument is used to define the type of +.Xr mutex 9 +by the system interrupt priority level. +.Sh RETURN VALUES +The +.Fn klua_lock , +.Fn klua_unlock , +and +.Fn klua_close +functions do not return anything upon completion. +.Pp +The +.Fn klua_newstate +and +.Fn kluaL_newstate +functions return a pointer to newly created to the +.Ft klua_State +structure or otherwise in case of failure the +.Dv NULL +value. +.Sh EXAMPLES +A set of example modules is available in the +.Pa src/sys/modules/examples +directory hierarchy. +.Sh SEE ALSO +.Xr lua 1 , +.Xr luac 1 , +.Xr intro 3lua , +.Xr lua 4 , +.Xr klua_mod_register 9 , +.Xr klua_mod_unregister 9 , +.Xr intro 9lua +.Sh AUTHORS +.An Kamil Rytarowski Aq Mt kamil@NetBSD.org . diff --git a/static/netbsd/man9/klua_mod_register.9 b/static/netbsd/man9/klua_mod_register.9 new file mode 100644 index 00000000..4d126312 --- /dev/null +++ b/static/netbsd/man9/klua_mod_register.9 @@ -0,0 +1,112 @@ +.\" $NetBSD: klua_mod_register.9,v 1.5 2017/04/16 06:34:05 wiz Exp $ +.\" +.\" Copyright (c) 2015 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Kamil Rytarowski. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 15, 2017 +.Dt KLUA_MOD_REGISTER 9 +.Os +.Sh NAME +.Nm klua_mod_register , +.Nm klua_mod_unregister +.Nd Lua kernel bindings +.Sh SYNOPSIS +.In sys/lua.h +.Ft void +.Fn klua_mod_register "const char *name" "lua_CFunction open" +.Ft void +.Fn klua_mod_unregister "const char *name" +.Sh DESCRIPTION +The Lua kernel bindings are designed to provide functionality to Lua scripts +normally not available in the language itself, e.g. to access core kernel functionality. +This is achieved by utilizing the lua_modules functionality. +.Pp +The lua_module structure is declared as follows: +.Bd -literal +struct lua_module { + char mod_name[LUA_MAX_MODNAME]; + lua_CFunction open; + int refcount; + LIST_ENTRY(lua_module) mod_next; +}; +.Ed +.Pp +The +.Ft mod_name +defines the unique name of a module. +A C function must use the standard Lua protocol in order to communicate with +Lua, this part is maintained with the +.Ft open +element in the standard Lua way. +.Ft refcount +protects the module from being unloaded whilst still in use. +The last parameter, +.Ft mod_next , +is used for the standard container +.Xr LIST 3 . +.Pp +The +.Fn klua_mod_register +function registers a new function which is made available to the +.Xr lua 9 +device and Lua code using the +.Dv require +directive. +The +.Dv require +directive can be called from +.Xr luactl 8 +and the kernel Lua version. +The +.Fa name +parameter is a unique identifier of the kernel Lua module. +.Fa open +points to a function used in the C to Lua binding, +defined with the appropriate standard Lua API. +.Pp +Once registered, a C function can be unregistered with the +.Fn klua_mod_unregister +function. +This function takes as its parameter the unique literal identifier of the +extending module. +.Sh EXAMPLES +A set of example modules is available in the +.Pa src/sys/modules/examples +directory hierarchy. +.Sh SEE ALSO +.Xr lua 1 , +.Xr luac 1 , +.Xr intro 3lua , +.Xr lua 4 , +.Xr klua_close 9 , +.Xr klua_lock 9 , +.Xr klua_newstate 9 , +.Xr klua_unlock 9 , +.Xr kluaL_newstate 9 , +.Xr intro 9lua +.Sh AUTHORS +.An Kamil Rytarowski Aq Mt kamil@NetBSD.org . diff --git a/static/netbsd/man9/kmem.9 b/static/netbsd/man9/kmem.9 new file mode 100644 index 00000000..f7ac496e --- /dev/null +++ b/static/netbsd/man9/kmem.9 @@ -0,0 +1,355 @@ +.\" $NetBSD: kmem.9,v 1.28 2021/03/06 14:44:02 rin Exp $ +.\" +.\" Copyright (c)2006 YAMAMOTO Takashi, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ------------------------------------------------------------ +.Dd January 24, 2021 +.Dt KMEM 9 +.Os +.\" ------------------------------------------------------------ +.Sh NAME +.Nm kmem +.Nd kernel wired memory allocator +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In sys/kmem.h +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void * +.Fn kmem_alloc \ +"size_t size" "km_flag_t kmflags" +.Ft void * +.Fn kmem_zalloc \ +"size_t size" "km_flag_t kmflags" +.Ft void +.Fn kmem_free \ +"void *p" "size_t size" +.\" --- +.Ft void * +.Fn kmem_intr_alloc \ +"size_t size" "km_flag_t kmflags" +.Ft void * +.Fn kmem_intr_zalloc \ +"size_t size" "km_flag_t kmflags" +.Ft void +.Fn kmem_intr_free \ +"void *p" "size_t size" +.\" --- +.Ft char * +.Fn kmem_asprintf \ +"const char *fmt" "..." +.\" --- +.Ft char * +.Fn kmem_strdupsize \ +"const char *str" "size_t *size" "km_flag_t kmflags" +.Ft char * +.Fn kmem_strdup \ +"const char *str" "km_flag_t kmflags" +.Ft char * +.Fn kmem_strndup \ +"const char *str" "size_t manxlen" "km_flag_t kmflags" +.Ft void +.Fn kmem_strfree \ +"char *str" +.\" ------------------------------------------------------------ +.Ft void * +.Fn kmem_tmpbuf_alloc \ +"size_t size" "void *stackbuf" "size_t stackbufsize" "km_flag_t kmflags" +.Ft void +.Fn kmem_tmpbuf_free \ +"void *p" "size_t size" "void *stackbuf" +.\" ------------------------------------------------------------ +.Pp +.Cd "options KMEM_SIZE" +.Sh DESCRIPTION +.Fn kmem_alloc +allocates kernel wired memory. +It takes the following arguments. +.Bl -tag -width kmflags +.It Fa size +Specify the size of allocation in bytes. +.It Fa kmflags +Either of the following: +.Bl -tag -width KM_NOSLEEP +.It Dv KM_SLEEP +If the allocation cannot be satisfied immediately, sleep until enough +memory is available. +If +.Dv KM_SLEEP +is specified, then the allocation cannot fail. +.It Dv KM_NOSLEEP +Don't sleep. +Immediately return +.Dv NULL +if there is not enough memory available. +It should only be used when failure to allocate will not have harmful, +user-visible effects. +.Pp +.Bf -symbolic +Use of +.Dv KM_NOSLEEP +is strongly discouraged as it can create transient, hard to debug failures +that occur when the system is under memory pressure. +.Ef +.Pp +In situations where it is not possible to sleep, for example because locks +are held by the caller, the code path should be restructured to allow the +allocation to be made in another place. +.El +.El +.Pp +The contents of allocated memory are uninitialized. +.Pp +Unlike Solaris, kmem_alloc(0, flags) is illegal. +.Pp +.\" ------------------------------------------------------------ +.Fn kmem_zalloc +is the equivalent of +.Fn kmem_alloc , +except that it initializes the memory to zero. +.Pp +.\" ------------------------------------------------------------ +.Fn kmem_asprintf +functions as the well known +.Fn asprintf +function, but allocates memory using +.Fn kmem_alloc . +This routine can sleep during allocation. +The size of the allocated area is the length of the returned character string, plus one (for the NUL terminator). +This must be taken into consideration when freeing the returned area with +.Fn kmem_free . +.Pp +.\" ------------------------------------------------------------ +.Fn kmem_free +frees kernel wired memory allocated by +.Fn kmem_alloc +or +.Fn kmem_zalloc +so that it can be used for other purposes. +It takes the following arguments. +.Bl -tag -width kmflags +.It Fa p +The pointer to the memory being freed. +It must be the one returned by +.Fn kmem_alloc +or +.Fn kmem_zalloc . +.It Fa size +The size of the memory being freed, in bytes. +It must be the same as the +.Fa size +argument used for +.Fn kmem_alloc +or +.Fn kmem_zalloc +when the memory was allocated. +.El +.Pp +Freeing +.Dv NULL +is illegal. +.Pp +.\" ------------------------------------------------------------ +.Fn kmem_intr_alloc , +.Fn kmem_intr_zalloc +and +.Fn kmem_intr_free +are the equivalents of the above kmem routines which can be called +from the interrupt context. +These routines are for the special cases. +Normally, +.Xr pool_cache 9 +should be used for memory allocation from interrupt context. +.Pp +The +.Fn kmem_strdupsize +function is a utility function that can be used to copy the string in the +.Fa str +argument to a new buffer allocated using +.Fn kmem_alloc +and optionally return the size of the allocation (the length of the string +plus the trailing +.Dv NUL ) +in the +.Fa size +argument if that is not +.Dv NULL . +.Pp +The +.Fn kmem_strdup +function is a simplified version of +.Fn kmem_strdupsize +that does not return the size of the allocation. +.Pp +The +.Fn kmem_strndup +function is variation of +.Fn kmem_strdup +that copies at most +.Fa maxlen +characters from the string +.Fa str +always NUL terminating the copied string. +.Pp +The +.Fn kmem_strfree +function can be used to free a +.Dv NUL +terminated string computing the length of the string using +.Xr strlen 3 +and adding one for the +.Dv NUL +and then using +.Fn kmem_free . +.Pp +The +.Fn kmem_tmpbuf_alloc +function is a utility function for allocating memory for temporary +use, where allocation on the stack is desirable, but only up to a +certain size. +If the requested size fits within the specified stack buffer, the +stack buffer is returned. +Otherwise, memory is allocated with +.Fn kmem_alloc . +The +.Fn kmem_tmpbuf_free +function compares the result of a previous call to +.Fn kmem_tmpbuf_alloc +and frees the memory using +.Fn kmem_free +if it is not the specified stack buffer. +.\" ------------------------------------------------------------ +.Sh NOTES +Making +.Dv KM_SLEEP +allocations while holding mutexes or reader/writer locks is discouraged, as the +caller can sleep for an unbounded amount of time in order to satisfy the +allocation. +This can in turn block other threads that wish to acquire locks held by the +caller. +It should be noted that +.Fn kmem_free +may also block. +.Pp +For some locks this is permissible or even unavoidable. +For others, particularly locks that may be taken from soft interrupt context, +it is a serious problem. +As a general rule it is better not to allow this type of situation to develop. +One way to circumvent the problem is to make allocations speculative and part +of a retryable sequence. +For example: +.Bd -literal + retry: + /* speculative unlocked check */ + if (need to allocate) { + new_item = kmem_alloc(sizeof(*new_item), KM_SLEEP); + } else { + new_item = NULL; + } + mutex_enter(lock); + /* check while holding lock for true status */ + if (need to allocate) { + if (new_item == NULL) { + mutex_exit(lock); + goto retry; + } + consume(new_item); + new_item = NULL; + } + mutex_exit(lock); + if (new_item != NULL) { + /* did not use it after all */ + kmem_free(new_item, sizeof(*new_item)); + } +.Ed +.\" ------------------------------------------------------------ +.Sh OPTIONS +.Ss KMEM_SIZE +Kernels compiled with the +.Dv KMEM_SIZE +option ensure the size given in +.Fn kmem_free +matches the actual allocated size. +On +.Fn kmem_alloc , +the kernel will allocate an additional contiguous kmem page of eight +bytes in the buffer, will register the allocated size in the first kmem +page of that buffer, and will return a pointer to the second kmem page +in that same buffer. +When freeing, the kernel reads the first page, and compares the +size registered with the one given in +.Fn kmem_free . +Any mismatch triggers a panic. +.Pp +.Dv KMEM_SIZE +is enabled by default on +.Dv DIAGNOSTIC . +.Sh RETURN VALUES +On success, +.Fn kmem_alloc , +.Fn kmem_asprintf , +.Fn kmem_intr_alloc , +.Fn kmem_intr_zalloc , +.Fn kmem_strdupsize , +and +.Fn kmem_zalloc +return a pointer to allocated memory. +Otherwise, +.Dv NULL +is returned. +.\" ------------------------------------------------------------ +.Sh CODE REFERENCES +The +.Nm +subsystem is implemented within the file +.Pa sys/kern/subr_kmem.c . +.\" ------------------------------------------------------------ +.Sh SEE ALSO +.Xr intro 9 , +.Xr memoryallocators 9 , +.Xr percpu 9 , +.Xr pool_cache 9 , +.Xr uvm_km 9 +.\" ------------------------------------------------------------ +.Sh CAVEATS +The +.Fn kmem_alloc , +.Fn kmem_asprintf , +.Fn kmem_free , +.Fn kmem_strdupsize , +.Fn kmem_strfree , +and +.Fn kmem_zalloc +functions cannot be used from interrupt context, from a soft interrupt, +or from a callout. +Use +.Xr pool_cache 9 +in these situations. +.\" ------------------------------------------------------------ +.Sh SECURITY CONSIDERATIONS +As the memory allocated by +.Fn kmem_alloc +is uninitialized, it can contain security-sensitive data left by its +previous user. +It is the caller's responsibility not to expose it to the world. diff --git a/static/netbsd/man9/knote.9 b/static/netbsd/man9/knote.9 new file mode 100644 index 00000000..e8d29cec --- /dev/null +++ b/static/netbsd/man9/knote.9 @@ -0,0 +1,109 @@ +.\" $NetBSD: knote.9,v 1.17 2017/04/15 09:50:57 abhinav Exp $ +.\" +.\" Copyright (c) 2001, 2002, 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation is derived from text contributed by +.\" Luke Mewburn. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 18, 2004 +.Dt KNOTE 9 +.Os +.Sh NAME +.Nm knote , +.Nm KNOTE +.Nd raise kernel event +.Sh SYNOPSIS +.In sys/event.h +.Ft void +.Fn knote "struct klist *list" "long hint" +.Fn KNOTE "struct klist *list" "long hint" +.Sh DESCRIPTION +The +.Fn knote +function provides a hook into the kqueue kernel event notification +mechanism to allow sections of the kernel to raise a kernel event +in the form of a +.Sq knote , +which is a +.Fa struct knote +as defined in +.In sys/event.h . +.Pp +.Fn knote +takes a singly linked +.Fa list +of knotes, along with a +.Fa hint +(which is passed to the appropriate filter routine). +.Fn knote +then walks the +.Fa list +making calls to the filter routine for each knote. +As each knote contains a reference to the data structure that it is +attached to, the filter may choose to examine the data structure in +deciding whether an event should be reported. +The +.Fa hint +is used to pass in additional information, which may not be present in +the data structure that the filter examines. +.Pp +If the filter decides that the event should be returned, it returns a +non-zero value and +.Fn knote +links the knote onto the tail end of the active list in the +corresponding kqueue for the application to retrieve. +If the knote is already on the active list, no action is taken, but the +call to the filter occurs in order to provide an opportunity for the +filter to record the activity. +.Pp +.Fn knote +must not be called from interrupt contexts running at an interrupt +priority level higher than +.Xr splsched 9 . +.Pp +.Fn KNOTE +is a macro that calls +.Fn knote list hint +if +.Fa list +is not empty. +.\" .Sh ERRORS +.Sh SEE ALSO +.Xr kqueue 2 , +.Xr kfilter_register 9 +.Sh HISTORY +The +.Fn knote +and +.Fn KNOTE +functions first appeared in +.Fx 4.1 , +and then in +.Nx 2.0 . +.Sh AUTHORS +The +.Xr kqueue 2 +system was written by +.An Jonathan Lemon Aq Mt jlemon@FreeBSD.org . diff --git a/static/netbsd/man9/kpause.9 b/static/netbsd/man9/kpause.9 new file mode 100644 index 00000000..379802a8 --- /dev/null +++ b/static/netbsd/man9/kpause.9 @@ -0,0 +1,126 @@ +.\" $NetBSD: kpause.9,v 1.8 2013/10/17 13:17:50 gson Exp $ +.\" +.\" Copyright (c) 2006, 2007 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Andrew Doran. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" ------------------------------------------------------------ +.Dd July 20, 2011 +.Dt KPAUSE 9 +.Os +.\" ------------------------------------------------------------ +.Sh NAME +.Nm kpause +.Nd make the calling LWP sleep +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In sys/proc.h +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn kpause \ +"const char *wmesg" "bool intr" "int timeo" "kmutex_t *mtx" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +.Fn kpause +makes the calling LWP sleep. +It's similar to +.Xr cv_timedwait_sig 9 +without the corresponding +.Xr cv_signal 9 . +.Pp +.Fn kpause +can wake up spontaneously. +Callers should prepare to handle it. +.Pp +.Bl -tag -width wmesg +.It Fa wmesg +Specifies a string of no more than 8 characters that describes +the resource or condition associated with the call of +.Fn kpause . +The kernel does not use this argument directly but makes it available for +utilities such as +.Xr ps 1 +to display. +.It Fa intr +If true, sleep interruptably. +If the LWP receives a signal, or is interrupted by another condition such +as its containing process exiting, the wait is ended early and an error +code returned. +.It Fa timeo +Specify a timeout. +It is an architecture and system dependent value related to the number of +clock interrupts per second. +See +.Xr hz 9 +for details. +The +.Xr mstohz 9 +macro can be used to convert a timeout expressed in milliseconds to +one suitable for +.Fn kpause . +.Pp +Zero means no timeout. +.It Fa mtx +Convenience and symmetry with other synchronization operations. +If not +.Dv NULL , +.Fa mtx +will be released once the LWP has prepared to sleep, and will be reacquired +before +.Fn kpause +returns. +.El +.\" ------------------------------------------------------------ +.Sh RETURN VALUES +.Fn kpause +returns 0 when waking up spontaneously. +Otherwise, +it returns an error number. +.\" ------------------------------------------------------------ +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINTR +.Fn kpause +returned due to other reasons. +Typically as a result of a signal without +.Dv SA_RESTART +property. +.It Bq Er ERESTART +.Fn kpause +returned as a result of a signal with +.Dv SA_RESTART +property. +.It Bq Er EWOULDBLOCK +The timeout expired. +.El +.\" ------------------------------------------------------------ +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr condvar 9 , +.Xr delay 9 , +.Xr errno 9 , +.Xr hz 9 , +.Xr mstohz 9 diff --git a/static/netbsd/man9/kpreempt.9 b/static/netbsd/man9/kpreempt.9 new file mode 100644 index 00000000..57c48914 --- /dev/null +++ b/static/netbsd/man9/kpreempt.9 @@ -0,0 +1,87 @@ +.\" $NetBSD: kpreempt.9,v 1.3 2010/02/16 19:21:30 rmind Exp $ +.\" +.\" Copyright (c)2008 YAMAMOTO Takashi, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ------------------------------------------------------------ +.Dd February 16, 2010 +.Dt KPREEMPT 9 +.Os +.\" ------------------------------------------------------------ +.Sh NAME +.Nm kpreempt +.Nd control kernel preemption +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In sys/systm.h +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn kpreempt_disable \ +"void" +.Ft void +.Fn kpreempt_enable \ +"void" +.Ft bool +.Fn kpreempt_disabled \ +"void" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +These functions are used to control kernel preemption of the calling LWP. +.Pp +On architectures where kernel preemption is not supported natively, these +functions may still be used. +.Pp +It should be noted that kernel preemption is also disabled when holding +the interrupt priority level above IPL_NONE, e.g. using +.Xr spl 9 +or spinning +.Xr mutex 9 +calls or holding kernel_lock (indicating that the code is not MT safe). +.Pp +.Fn kpreempt_disable +disables kernel preemption of the calling LWP. +Note that disabling kernel preemption can prevent LWPs with higher priorities +from running. +.Pp +.Fn kpreempt_enable +enables kernel preemption of the calling LWP, which was previously disabled by +.Fn kpreempt_disable . +.Pp +.Fn kpreempt_disable +and +.Fn kpreempt_enable +can be nested. +.Pp +.Fn kpreempt_disabled +returns +.Dv true +if preemption of the calling LWP is disabled. +It is only for diagnostic purpose. +.\" ------------------------------------------------------------ +.\" .Sh RETURN VALUES +.\" ------------------------------------------------------------ +.Sh SEE ALSO +.Xr intro 9 , +.Xr mutex 9 , +.Xr spl 9 diff --git a/static/netbsd/man9/kprintf.9 b/static/netbsd/man9/kprintf.9 new file mode 100644 index 00000000..2113828f --- /dev/null +++ b/static/netbsd/man9/kprintf.9 @@ -0,0 +1,341 @@ +.\" $NetBSD: kprintf.9,v 1.41 2025/01/12 20:16:34 rillig Exp $ +.\" +.\" Copyright (c) 1998, 2002, 2007, 2011 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jeremy Cooper and by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 10, 2021 +.Dt KPRINTF 9 +.Os +.Sh NAME +.Nm device_printf , +.Nm printf , +.Nm printf_nolog , +.Nm printf_nostamp , +.Nm snprintf , +.Nm vasprintf , +.Nm vprintf , +.Nm vsnprintf , +.Nm uprintf , +.Nm ttyprintf , +.Nm tprintf_open , +.Nm tprintf , +.Nm tprintf_close , +.Nm aprint_normal , +.Nm aprint_naive , +.Nm aprint_verbose , +.Nm aprint_debug , +.Nm aprint_error , +.Nm aprint_normal_dev , +.Nm aprint_naive_dev , +.Nm aprint_verbose_dev , +.Nm aprint_debug_dev , +.Nm aprint_error_dev , +.Nm aprint_normal_ifnet , +.Nm aprint_naive_ifnet , +.Nm aprint_verbose_ifnet , +.Nm aprint_debug_ifnet , +.Nm aprint_error_ifnet , +.Nm aprint_get_error_count +.Nd kernel formatted output conversion +.Sh SYNOPSIS +.In sys/systm.h +.Ft void +.Fn device_printf "device_t" "const char *format" "..." +.Ft void +.Fn printf "const char *format" "..." +.Ft void +.Fn printf_nolog "const char *format" "..." +.Ft void +.Fn printf_nostamp "const char *format" "..." +.Ft int +.Fn snprintf "char *buf" "size_t size" "const char *format" "..." +.Ft int +.Fn vasprintf "char **buf" "const char *format" "va_list ap" +.Ft void +.Fn vprintf "const char *format" "va_list ap" +.Ft int +.Fn vsnprintf "char *buf" "size_t size" "const char *format" "va_list ap" +.Ft void +.Fn uprintf "const char *format" "..." +.Ft void +.Fn ttyprintf "struct tty *tty" "const char *format" "..." +.In sys/tprintf.h +.Ft tpr_t +.Fn tprintf_open "struct proc *p" +.Ft void +.Fn tprintf "tpr_t tpr" "const char *format" "..." +.Ft void +.Fn tprintf_close "tpr_t tpr" +.Ft void +.Fn aprint_normal "const char *format" "..." +.Ft void +.Fn aprint_naive "const char *format" "..." +.Ft void +.Fn aprint_verbose "const char *format" "..." +.Ft void +.Fn aprint_debug "const char *format" "..." +.Ft void +.Fn aprint_error "const char *format" "..." +.Ft void +.Fn aprint_normal_dev "device_t" "const char *format" "..." +.Ft void +.Fn aprint_naive_dev "device_t" "const char *format" "..." +.Ft void +.Fn aprint_verbose_dev "device_t" "const char *format" "..." +.Ft void +.Fn aprint_debug_dev "device_t" "const char *format" "..." +.Ft void +.Fn aprint_error_dev "device_t" "const char *format" "..." +.Ft void +.Fn aprint_normal_ifnet "struct ifnet *" "const char *format" "..." +.Ft void +.Fn aprint_naive_ifnet "struct ifnet *" "const char *format" "..." +.Ft void +.Fn aprint_verbose_ifnet "struct ifnet *" "const char *format" "..." +.Ft void +.Fn aprint_debug_ifnet "struct ifnet *" "const char *format" "..." +.Ft void +.Fn aprint_error_ifnet "struct ifnet *" "const char *format" "..." +.Ft int +.Fn aprint_get_error_count "void" +.Sh DESCRIPTION +The +.Fn printf +family of functions allows the kernel to send formatted messages to various +output devices. +The functions +.Fn printf +and +.Fn vprintf +send formatted strings to the system console. +The +.Fn device_printf +function is identical to +.Fn printf , +except that it prefixes the log message with the corresponding +device name. +The +.Fn printf_nolog +function is identical to +.Fn printf , +except it does not send the data to the system log. +The +.Fn printf_nostamp +function is identical to +.Fn printf , +except it does not prefix the output with a timestamp. +The functions +.Fn snprintf , +.Fn vasprintf , +and +.Fn vsnprintf +write output to a string buffer. +These five functions work similarly to their user space counterparts, +and are not described in detail here. +The +.Fn vasprintf +function allocates memory with +.Xr kmem_alloc 9 +and it is the caller's responsibility to free the returned string with +.Xr kmem_free 9 . +.Pp +The functions +.Fn uprintf +and +.Fn ttyprintf +send formatted strings to the current process's controlling tty and a specific +tty, respectively. +.Pp +The +.Fn tprintf +function sends formatted strings to a process's controlling tty, +via a handle of type tpr_t. +This allows multiple write operations to the tty with a guarantee that the +tty will be valid across calls. +A handle is acquired by calling +.Fn tprintf_open +with the target process as an argument. +This handle must be closed with a matching call to +.Fn tprintf_close . +.Pp +The functions +.Fn aprint_normal , +.Fn aprint_naive , +.Fn aprint_verbose , +.Fn aprint_debug , +and +.Fn aprint_error +are intended to be used to print +.Xr autoconf 9 +messages. +Their verbosity depends on flags set in the +.Va boothowto +variable, through options passed during bootstrap; see +.Xr boothowto 9 +and +.Sx Interactive mode +in +.Xr boot 8 : +.Bl -tag -width AB_VERBOSE +.It Dv AB_SILENT +silent mode, enabled by +.Ic boot +.Fl z . +.It Dv AB_QUIET +quiet mode, enabled by +.Ic boot +.Fl q . +.It Dv AB_VERBOSE +verbose mode, enabled by +.Ic boot +.Fl v . +.It Dv AB_DEBUG +debug mode, enabled by +.Ic boot +.Fl x . +.El +.Pp +The +.Fn aprint_* +functions have the following behaviour, based on the above +mentioned flags: +.Bl -tag -width Xaprint_verboseXXX +.It Fn aprint_normal +Sends to the console unless +.Dv AB_QUIET +is set. +Always sends to the log. +.It Fn aprint_naive +Sends to the console only if +.Dv AB_QUIET +is set. +Never sends to the log. +.It Fn aprint_verbose +Sends to the console only if +.Dv AB_VERBOSE +is set. +Always sends to the log. +.It Fn aprint_debug +Sends to the console and the log only if +.Dv AB_DEBUG +is set. +.It Fn aprint_error +Like +.Fn aprint_normal , +but also keeps track of the number of times called. +This allows a subsystem to report the number of errors that occurred +during a quiet or silent initialization phase. +.El +.Pp +For the +.Fn aprint_* +functions there are two additional families of functions with the +suffixes +.Dv _dev +and +.Dv _ifnet +which work like their counterparts without the suffixes, except that +they take a +.Ft device_t +and +.Ft struct ifnet * , +respectively, as first argument, +and prefix the log message with the +corresponding device or interface name. +.Pp +The +.Fn aprint_get_error_count +function reports the number of errors and resets the counter to 0. +.Pp +If +.Dv AB_SILENT +is set, none of the autoconfiguration message printing routines send output +to the console. +The +.Dv AB_VERBOSE +and +.Dv AB_DEBUG +flags override +.Dv AB_SILENT . +.Sh RETURN VALUES +The +.Fn snprintf +and +.Fn vsnprintf +functions return the number of characters that would have been placed +in the buffer +.Fa buf , +if there was enough space in the buffer, not including the trailing +.Dv NUL +character used to terminate output strings like the user-space functions +of the same name. +.Pp +The +.Fn tprintf_open +function returns +.Dv NULL +if no terminal handle could be acquired. +.Sh CODE REFERENCES +.Pa sys/kern/subr_prf.c +.Sh SEE ALSO +.Xr printf 1 , +.Xr printf 3 , +.Xr snprintb 3 , +.Xr boot 8 , +.Xr autoconf 9 , +.Xr boothowto 9 +.Sh HISTORY +In +.Nx 1.5 +and earlier, +.Fn printf +supported more format strings than the user space +.Fn printf . +These nonstandard format strings are no longer supported. +For the functionality provided by the former +.Li %b +format string, see +.Xr snprintb 3 . +.Pp +The +.Fn aprint_normal , +.Fn aprint_naive , +.Fn aprint_verbose , +and +.Fn aprint_debug +functions first appeared in +.Bsx . +.Sh BUGS +The +.Fn uprintf +and +.Fn ttyprintf +functions should be used sparingly, if at all. +Where multiple lines of output are required to reach a process's +controlling terminal, +.Fn tprintf +is preferred. diff --git a/static/netbsd/man9/kthread.9 b/static/netbsd/man9/kthread.9 new file mode 100644 index 00000000..342c2a8e --- /dev/null +++ b/static/netbsd/man9/kthread.9 @@ -0,0 +1,222 @@ +.\" $NetBSD: kthread.9,v 1.30 2020/08/01 09:50:42 wiz Exp $ +.\" +.\" Copyright (c) 2000, 2007, 2008 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry, and by Andrew Doran. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 21, 2015 +.Dt KTHREAD 9 +.Os +.Sh NAME +.Nm kthread_create , +.Nm kthread_exit , +.Nm kthread_join , +.Nm kthread_fpu_enter , +.Nm kthread_fpu_exit +.Nd kernel threads +.Sh SYNOPSIS +.In sys/kthread.h +.Ft int +.Fn kthread_create "pri_t pri" "int flags" "struct cpu_info *ci" \ +"void (*func)(void *)" "void *arg" "lwp_t **newlp" "const char *fmt" "..." +.Ft void +.Fn kthread_exit "int ecode" +.Ft int +.Fn kthread_join "lwp_t *l" +.Ft int +.Fn kthread_fpu_enter +.Ft void +.Fn kthread_fpu_exit "int s" +.Sh DESCRIPTION +Kernel threads are light-weight processes which execute entirely +within the kernel. +.Pp +Any process can request the creation of a new kernel thread. +Kernel threads are not swapped out during memory congestion. +The VM space and limits are shared with proc0 (usually swapper). +.Pp +If the machine has any per-CPU floating-point units or SIMD vector +units that are normally available to user threads, they can be used by +kthreads between +.Fn kthread_fpu_enter +and +.Fn kthread_fpu_exit . +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn kthread_create "pri" "flags" "ci" "func" "arg" "newlp" "fmt" "..." +Create a kernel thread. +The arguments are as follows. +.Bl -tag -width compact +.It Fa pri +Priority level for the thread. +If no priority level is desired specify +.Dv PRI_NONE , +causing +.Fn kthread_create +to select the default priority level. +.It Fa flags +Flags that can be logically ORed together to alter the thread's behaviour. +.It Fa ci +If +.No non- Ns Dv NULL , +the thread will be created bound to the CPU specified by +.Fa ci , +meaning that it will only ever execute on that CPU. +By default, the threads are free to execute on any CPU in the system. +.It Fa func +A function to be called when the thread begins executing. +This function must not return. +If the thread runs to completion, it must call +.Fn kthread_exit +to properly terminate itself. +.It Fa arg +An argument to be passed to +.Fn func . +May be +.Dv NULL +if not required. +.It Fa newlp +A pointer to receive the new LWP structure for the kernel thread. +May be +.Dv NULL , +unless +.Dv KTHREAD_MUSTJOIN +is specified in +.Fa flags . +.It Fa fmt +A string containing format information used to display the kernel +thread name. +Must not be +.Dv NULL . +.El +.Pp +The following +.Va flags +are defined. +.Bl -tag -width KTHREAD_MUSTJOIN +.It Dv KTHREAD_IDLE +Causes the thread to be created in the +.Dv LSIDL +(idle) state. +By default, the threads are created in the +.Dv LSRUN +(runnable) state, meaning they will begin execution shortly after creation. +.It Dv KTHREAD_MPSAFE +Specifies that the thread does its own locking and so is multiprocessor safe. +If not specified, the global kernel lock will be held whenever the thread is +running (unless explicitly dropped by the thread). +.It Dv KTHREAD_INTR +Specifies that the thread services device interrupts. +This flag is intended for kernel internal use and should not normally be +specified. +.It Dv KTHREAD_TS +Causes the kthread to be created in the +.Dv SCHED_OTHER +class (timeshared). +The thread's priority will be dynamically adjusted by the scheduler. +Increased activity by the kthread will cause its priority to fall; +decreased activity will cause its priority to rise. +By default, kthreads are created in the +.Dv SCHED_RR +class, with a fixed +priority specified by +.Ar pri . +Threads in the +.Dv SCHED_RR +class do not have their priority dynamically +adjusted by the scheduler. +.It Dv KTHREAD_MUSTJOIN +Indicates that created kthread must be joined. +In such case +.Fn kthread_exit +will wait until +.Fn kthread_join +will be called. +.El +.It Fn kthread_exit "ecode" +Exit from a kernel thread. +Must only be called by a kernel thread. +.It Fn kthread_join "l" +Suspend execution of calling thread until the target kthread terminates. +Conceptually the function can be compared to the user space +.Xr pthread_join 3 , +however it must be called only once for kernel thread which was +created using the +.Dv KTHREAD_MUSTJOIN +flag and would wait on +.Fa kthread_exit . +.It Fn kthread_fpu_enter +Allow the current kthread to use any machine-dependent per-CPU +floating-point units or SIMD vector units normally available to user +threads. +Returns a cookie that must be passed to +.Fn kthread_fpu_exit +when done. +.Pp +Matching pairs of +.Fn kthread_fpu_enter +and +.Fn kthread_fpu_exit +may be nested. +.It Fn kthread_fpu_exit "s" +Restore the current kthread's access to machine-dependent per-CPU +floating-point units or SIMD vector units to what it was before the +call to +.Fn kthread_fpu_enter +that returned +.Fa s . +.Pp +On the last +.Fn kthread_fpu_exit , +zero all the units' registers to avoid leaking secrets \(em such units +are often used for cryptography. +.El +.Sh RETURN VALUES +Upon successful completion, +.Fn kthread_create +returns 0. +Otherwise, the following error values are returned: +.Bl -tag -width [EAGAIN] +.It Bq Er EAGAIN +The limit on the total number of system processes would be exceeded; +or the limit +.Dv RLIMIT_NPROC +on the total number of processes under execution by this +user id would be exceeded. +.El +.Sh CODE REFERENCES +The kthread framework itself is implemented within the file +.Pa sys/kern/kern_kthread.c . +Data structures and function prototypes for the framework are located in +.Pa sys/sys/kthread.h . +.Sh SEE ALSO +.Xr condvar 9 , +.Xr driver 9 , +.Xr softint 9 , +.Xr workqueue 9 +.Sh HISTORY +The kthread framework appeared in +.Nx 1.4 . diff --git a/static/netbsd/man9/linedisc.9 b/static/netbsd/man9/linedisc.9 new file mode 100644 index 00000000..e5381836 --- /dev/null +++ b/static/netbsd/man9/linedisc.9 @@ -0,0 +1,107 @@ +.\" $NetBSD: linedisc.9,v 1.12 2024/09/07 19:13:29 rillig Exp $ +.\" +.\" Copyright (c) 2000 Christopher G. Demetriou. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the +.\" NetBSD Project. See https://www.NetBSD.org/ for +.\" information about NetBSD. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" --(license Id: LICENSE.proto,v 1.1 2000/06/13 21:40:26 cgd Exp )-- +.\" +.Dd November 1, 2000 +.Dt LINEDISC 9 +.Os +.Sh NAME +.Nm linedisc , +.Nm ttyldisc_add , +.Nm ttyldisc_lookup , +.Nm ttyldisc_remove +.Nd extensible line discipline framework +.Sh SYNOPSIS +.In sys/conf.h +.Ft int +.Fn ttyldisc_add "struct linesw *disc" "int no" +.Ft struct linesw * +.Fn ttyldisc_remove "const char *name" +.Ft struct linesw * +.Fn ttyldisc_lookup "const char *name" +.Sh DESCRIPTION +The +.Nx +TTY line discipline framework allows extensibility. +Modules that need special line disciplines can add +them as convenient and do not need to modify tty_conf.c. +Line disciplines are now managed by a string, rather than +number. +.Pp +Once the framework has been initialized, a new line +discipline can be added by creating and initializing a +.Fa struct linesw +and calling +.Fn ttyldisc_add . +.Pp +The following is a brief description of each function in the framework: +.Bl -tag -width "ttyldisc_remove()" +.It Fn ttyldisc_add +Register a line discipline. +The +.Fa l_name +field of the +.Fa struct linesw +should point to a string which is to be the symbolic +name of that line discipline. +For compatibility purposes, a line discipline number can be passed in +.Fa no , +but for new disciplines this should be set to +.Dv -1 . +.It Fn ttyldisc_lookup +Look up a line discipline by +.Fa name . +.Dv NULL +is returned if it can not be found. +.It Fn ttyldisc_remove +Remove a line discipline called +.Fa name +and return a pointer to it. +If the discipline cannot be found or removed +.Fn ttyldisc_remove +will return +.Dv NULL . +.El +.Sh SEE ALSO +.Xr tty 4 +.Sh HISTORY +The +.Nm +functions were added in +.Nx 1.6 . +.Sh AUTHORS +The +.Nx +extensible line discipline framework was created by +.An Eduardo Horvath +.Aq eeh@NetBSD.org . diff --git a/static/netbsd/man9/localcount.9 b/static/netbsd/man9/localcount.9 new file mode 100644 index 00000000..7b06ef1d --- /dev/null +++ b/static/netbsd/man9/localcount.9 @@ -0,0 +1,202 @@ +.\" $NetBSD: localcount.9,v 1.7 2019/02/25 21:43:00 pgoyette Exp $ +.\" +.\" Copyright (c) 2016 The NetBSD Foundation +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Taylor R. Campbell. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 25, 2019 +.Dt LOCALCOUNT 9 +.Os +.Sh NAME +.Nm localcount , +.Nm localcount_init , +.Nm localcount_fini , +.Nm localcount_acquire , +.Nm localcount_release , +.Nm localcount_drain +.Nd reference-count primitives +.Sh SYNOPSIS +.In sys/localcount.h +.Ft void +.Fn localcount_init "struct localcount *lc" +.Ft void +.Fn localcount_fini "struct localcount *lc" +.Ft void +.Fn localcount_acquire "struct localcount *lc" +.Ft void +.Fn localcount_release "struct localcount *lc" "struct kcondvar *cv" \ +"struct kmutex *mtx" +.Ft void +.Fn localcount_drain "struct localcount *lc" "struct kcondvar *cv" \ +"struct kmutex *mtx" +.Sh DESCRIPTION +Localcounts are used in the kernel to implement a medium-weight reference +counting mechanism. +During normal operations, localcounts do not need the interprocessor +synchronization associated with +.Xr atomic_ops 3 +atomic memory operations, and (unlike +.Xr psref 9 ) +.Nm +references can be held across sleeps and can migrate between CPUs. +Draining a +.Nm +requires more expensive interprocessor synchronization than +.Xr atomic_ops 3 +(similar to +.Xr psref 9 ) . +And +.Nm +references require eight bytes of memory per object per-CPU, significantly +more than +.Xr atomic_ops 3 +and almost always more than +.Xr psref 9 . +.Pp +As a rough heuristic, +.Nm +should be used for classes of objects of which there are perhaps a few dozen +instances (such as +.Xr autoconf 9 +devices) but not thousands of instances (such as +network flows) and on which there may be a mixture of long-term I/O waits, +such as xyzread for a device xyz(4), and short-term fast operations, such as +.Dv xyzioctl(IOC_READ_A_CPU_REG) . +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn localcount_init "lc" +Dynamically initialize localcount +.Ar lc +for use. +.Pp +No other operations can be performed on a localcount until it has been +initialized. +.It Fn localcount_fini "lc" +Release resources used by localcount +.Ar lc . +The caller must have already called +.Fn localcount_drain . +The localcount may not be used after +.Fn localcount_fini +has been called until it has been re-initialized by +.Fn localcount_init . +.It Fn localcount_acquire "lc" +Acquire a reference to the localcount +.Ar lc . +.Pp +The caller must ensure by some other mechanism that the localcount will +not be destroyed before the call to +.Fn localcount_acquire ; +typically this will be via a +.Xr pserialize 9 +read section. +.It Fn localcount_release "lc" "cv" "mtx" +Release a reference to the localcount +.Ar lc . +If the localcount is currently being drained, the mutex +.Ar mtx +will be used to synchronize updates to the global reference count (i.e., +the total across all CPUs). +If the reference count goes to zero, +.Fn localcount_release +will broadcast availability of the condvar +.Ar cv . +.It Fn localcount_drain "lc" "cv" "mtx" +Wait for all references to the localcount +.Ar lc +to be released. +The caller must hold the mutex +.Ar mtx ; +the mutex will be released during inter-CPU cross-calls (see +.Xr xcall 9 ) +and while waiting on the condvar +.Ar cv . +The same +.Ar cv +and +.Ar mtx +must be used with +.Fn localcount_release . +.Pp +The caller must guarantee that no new references can be acquired with +.Fn localcount_acquire +before calling +.Fn localcount_drain . +For example, any object that may be found in a list and acquired must be +removed from the list before calling +.Fn localcount_drain ; +removal from the list would typically be protected by calling +.Xr pserialize_perform 9 +to wait for any +.Xr pserialize 9 +readers to complete. +.Pp +Once the localcount object +.Ar lc +is passed to +.Fn localcount_drain , +it must be passed to +.Fn localcount_fini +before any other re-use. +.El +.Sh CODE REFERENCES +The core of the localcount implementation is located in +.Pa sys/kern/subr_localcount.c . +.Pp +The header file +.Pa sys/sys/localcount.h +describes the public interface, and interfaces that machine-dependent +code must provide to support localcounts. +.Sh SEE ALSO +.Xr atomic_ops 3 , +.Xr condvar 9 , +.Xr mutex 9 , +.Xr psref 9 +.Sh HISTORY +The localcount primitives first appeared in +.Nx 8.0 . +.Sh AUTHORS +.Nm +was designed by +.An -nosplit +.An Taylor R. Campbell , +who also provided a draft implementation. +The implementation was completed, tested, and integrated by +.An Paul Goyette . +.Sh CAVEATS +The +.Nm +facility does not provide any way to examine the reference count without +actually waiting for the count to reach zero. +.Pp +Waiting for a +.Nm +reference count to drain (reach zero) is a one-shot operation. +Once the +.Nm +has been drained, no further operations are allowed until the +.Nm +has been re-initialized. diff --git a/static/netbsd/man9/lock.9 b/static/netbsd/man9/lock.9 new file mode 100644 index 00000000..337f3c79 --- /dev/null +++ b/static/netbsd/man9/lock.9 @@ -0,0 +1,62 @@ +.\" $NetBSD: lock.9,v 1.29 2008/04/30 13:10:58 martin Exp $ +.\" +.\" Copyright (c) 2000, 2007, 2008 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 30, 2008 +.Dt LOCK 9 +.Os +.Sh NAME +.Nm lock , +.Nm simple_lock_init , +.Nm simple_lock , +.Nm simple_lock_try , +.Nm simple_unlock , +.Nm simple_lock_freecheck , +.Nm simple_lock_dump , +.Nm lockinit , +.Nm lockmgr , +.Nm lockstatus , +.Nm lockmgr_printinfo , +.Nm spinlockinit , +.Nm spinlockmgr +.Nd kernel lock functions +.Sh DESCRIPTION +These interfaces have been obsoleted and removed from the system. +.Pp +Please see the +.Xr condvar 9 , +.Xr mutex 9 , +and +.Xr rwlock 9 +manual pages for information on kernel synchronisation primitives. +.Sh SEE ALSO +.Xr condvar 9 , +.Xr mutex 9 , +.Xr rwlock 9 +.Sh HISTORY +The kernel locking API first appeared in +.Bx 4.4 Ns -lite2 , +and was replaced in +.Nx 5.0 . diff --git a/static/netbsd/man9/locking.9 b/static/netbsd/man9/locking.9 new file mode 100644 index 00000000..32a1451e --- /dev/null +++ b/static/netbsd/man9/locking.9 @@ -0,0 +1,317 @@ +.\" $NetBSD: locking.9,v 1.8 2017/08/27 20:44:42 wiz Exp $ +.\" +.\" Copyright (c) 2015 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Kamil Rytarowski. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 23, 2017 +.Dt LOCKING 9 +.Os +.Sh NAME +.Nm locking +.Nd introduction to kernel synchronization and interrupt control +.Sh DESCRIPTION +The +.Nx +kernel provides several synchronization and interrupt control primitives. +This man page aims to give an overview of these interfaces and their proper +application. +Also included are basic kernel thread control primitives and a rough +overview of the +.Nx +kernel design. +.Sh KERNEL OVERVIEW +The aim of synchronization, threads and interrupt control in the kernel is: +.Bl -bullet -offset indent +.It +To control concurrent access to shared resources (critical sections). +.It +Spawn tasks from an interrupt in the thread context. +.It +Mask interrupts from threads. +.It +Scale on multiple CPU system. +.El +.Pp +There are three types of contexts in the +.Nx +kernel: +.Bl -bullet -offset indent +.It +.Em Thread context +- running processes (represented by +.Dv struct proc ) +and light-weight processes (represented by +.Dv struct lwp , +also known as kernel threads). +Code in this context can sleep, block resources and own address-space. +.It +.Em Software interrupt context +- limited by thread context. +Code in this context must be processed shortly. +These interrupts don't own any address space context. +Software interrupts are a way of deferring hardware interrupts to do more +expensive processing at a lower interrupt priority. +.It +.Em Hard interrupt context +- Code in this context must be processed as quickly as possible. +It is forbidden for a piece of code to sleep or access long-awaited resources here. +.El +.Pp +The main differences between processes and kernel threads are: +.Bl -bullet -offset indent +.It +A single process can own multiple kernel threads (LWPs). +.It +A process owns address space context to map userland address space. +.It +Processes are designed for userland executables and kernel threads for +in-kernel tasks. +The only process running in the kernel-space is +.Dv proc0 +(called swapper). +.El +.Sh INTERFACES +.Ss Atomic memory operations +The +.Nm atomic_ops +family of functions provide atomic memory operations. +There are 7 classes of atomic memory operations available: +addition, logical +.Dq and , +compare-and-swap, decrement, increment, logical +.Dq or , +swap. +.Pp +See +.Xr atomic_ops 3 . +.Ss Condition variables +Condition variables (CVs) are used in the kernel to synchronize access to +resources that are limited (for example, memory) and to wait for pending I/O +operations to complete. +.Pp +See +.Xr condvar 9 . +.Ss Memory access barrier operations +The +.Nm membar_ops +family of functions provide memory access barrier operations necessary for +synchronization in multiprocessor execution environments that have relaxed load +and store order. +.Pp +See +.Xr membar_ops 3 . +.Ss Memory barriers +The memory barriers can be used to control the order in which memory accesses +occur, and thus the order in which those accesses become visible to other +processors. +They can be used to implement +.Dq lockless +access to data structures where the necessary barrier conditions are well +understood. +.Ss Mutual exclusion primitives +Thread-base adaptive mutexes. +These are lightweight, +exclusive locks that use threads as the focus of synchronization activity. +Adaptive mutexes typically behave like spinlocks, +but under specific conditions an attempt to acquire an already held adaptive +mutex may cause the acquiring thread to sleep. +Sleep activity occurs rarely. +Busy-waiting is typically more efficient because mutex hold times are most +often short. +In contrast to pure spinlocks, +a thread holding an adaptive mutex may be pre-empted in the kernel, +which can allow for reduced latency where soft real-time application are in use +on the system. +.Pp +See +.Xr mutex 9 . +.Ss Restartable atomic sequences +Restartable atomic sequences are user code only sequences which are guaranteed +to execute without preemption. +This property is assured by checking the set of restartable atomic sequences +registered for a process during +.Xr cpu_switchto 9 . +If a process is found to have been preempted during a restartable sequence, +then its execution is rolled-back to the start of the sequence by resetting its +program counter which is saved in its process control block (PCB). +.Pp +See +.Xr ras 9 . +.Ss Reader / writer lock primitives +Reader / writer locks (RW locks) are used in the kernel to synchronize access +to an object among LWPs (lightweight processes) and soft interrupt handlers. +In addition to the capabilities provided by mutexes, +RW locks distinguish between read (shared) and write (exclusive) access. +.Pp +See +.Xr rwlock 9 . +.Ss Functions to modify system interrupt priority level +These functions raise and lower the interrupt priority level. +They are used by kernel code to block interrupts in critical sections, +in order to protect data structures. +.Pp +See +.Xr spl 9 . +.Ss Machine-independent software interrupt framework +The software interrupt framework is designed to provide a generic software +interrupt mechanism which can be used any time a low-priority callback is +required. +It allows dynamic registration of software interrupts for loadable drivers, +protocol stacks, software interrupt prioritization, software interrupt fair +queuing and allows machine-dependent optimizations to reduce cost. +.Pp +See +.Xr softint 9 . +.Ss Functions to raise the system priority level +The +.Nm splraiseipl +function raises the system priority level to the level specified by +.Dv icookie , +which should be a value returned by +.Xr makeiplcookie 9 . +In general, device drivers should not make use of this interface. +To ensure correct synchronization, +device drivers should use the +.Xr condvar 9 , +.Xr mutex 9 , +and +.Xr rwlock 9 +interfaces. +.Pp +See +.Xr splraiseipl 9 . +.Ss Passive serialization mechanism +Passive serialization is a reader / writer synchronization mechanism designed +for lock-less read operations. +The read operations may happen from software interrupt at +.Dv IPL_SOFTCLOCK . +.Pp +See +.Xr pserialize 9 . +.Ss Passive reference mechanism +Passive references allow CPUs to cheaply acquire and release passive +references to a resource, which guarantee the resource will not be +destroyed until the reference is released. +Acquiring and releasing passive references requires no interprocessor +synchronization, except when the resource is pending destruction. +.Pp +See +.Xr psref 9 . +.Ss Localcount mechanism +Localcounts are used in the kernel to implement a medium-weight reference +counting mechanism. +During normal operations, localcounts do not need +the interprocessor synchronization associated with +.Xr atomic_ops 3 +atomic memory operations, and (unlike +.Xr psref 9 ) +localcount references can be held across sleeps and can migrate between +CPUs. +Draining a localcount requires more expensive interprocessor +synchronization than +.Xr atomic_ops 3 +(similar to +.Xr psref 9 ) . +And localcount references require eight bytes of memory per object per-CPU, +significantly more than +.Xr atomic_ops 3 +and almost always more than +.Xr psref 9 . +.Pp +See +.Xr localcount 9 . +.Ss Simple do-it-in-thread-context framework +The workqueue utility routines are provided to defer work which is needed to be +processed in a thread context. +.Pp +See +.Xr workqueue 9 . +.Sh USAGE +The following table describes in which contexts the use of the +.Nx +kernel interfaces are valid. +Synchronization primitives which are available in more than one context +can be used to protect shared resources between the contexts they overlap. +.Bl -column -offset indent \ +"xxxxxxxxxxxx " "xxxxxxx " "xxxxxxx " "xxxxxxx " +.It Sy interface Ta Sy thread Ta Sy softirq Ta Sy hardirq +.It Xr atomic_ops 3 Ta yes Ta yes Ta yes +.It Xr condvar 9 Ta yes Ta partly Ta no +.It Xr membar_ops 3 Ta yes Ta yes Ta yes +.It Xr mutex 9 Ta yes Ta depends Ta depends +.It Xr rwlock 9 Ta yes Ta yes Ta no +.It Xr softint 9 Ta yes Ta yes Ta yes +.It Xr spl 9 Ta yes Ta no Ta no +.It Xr splraiseipl 9 Ta yes Ta no Ta no +.It Xr pserialize 9 Ta yes Ta yes Ta no +.It Xr psref 9 Ta yes Ta yes Ta no +.It Xr localcount 9 Ta yes Ta yes Ta no +.It Xr workqueue 9 Ta yes Ta yes Ta yes +.El +.Sh SEE ALSO +.Xr atomic_ops 3 , +.Xr membar_ops 3 , +.Xr condvar 9 , +.Xr mutex 9 , +.Xr ras 9 , +.Xr rwlock 9 , +.Xr softint 9 , +.Xr spl 9 , +.Xr splraiseipl 9 , +.Xr workqueue 9 +.Sh HISTORY +Initial SMP support was introduced in +.Nx 2.0 +and was designed with a giant kernel lock. +Through +.Nx 4.0 , +the kernel used spinlocks and a per-CPU interrupt priority level (the +.Xr spl 9 +system). +These mechanisms did not lend themselves well to a multiprocessor environment +supporting kernel preemption. +The use of thread based (lock) synchronization was limited and the available +synchronization primitive (lockmgr) was inefficient and slow to execute. +.Nx 5.0 +introduced massive performance improvements on multicore hardware +by Andrew Doran. +This work was sponsored by The +.Nx +Foundation. +.Pp +A +.Nm +manual first appeared in +.Nx 8.0 +and was inspired by the corresponding +.Nm +manuals in +.Fx +and +.Dx . +.Sh AUTHORS +.An Kamil Rytarowski Aq Mt kamil@NetBSD.org . diff --git a/static/netbsd/man9/log.9 b/static/netbsd/man9/log.9 new file mode 100644 index 00000000..758e05f6 --- /dev/null +++ b/static/netbsd/man9/log.9 @@ -0,0 +1,65 @@ +.\" $NetBSD: log.9,v 1.10 2008/04/30 13:10:58 martin Exp $ +.\" +.\" Copyright (c) 1997 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Michael Graff. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 12, 1997 +.Dt LOG 9 +.Os +.Sh NAME +.Nm log +.Nd log a message from the kernel through the +.Pa /dev/klog +device +.Sh SYNOPSIS +.In sys/syslog.h +.Ft void +.Fo "log" +.Fa "int level" +.Fa "const char *format" +.Fa "..." +.Fc +.Sh DESCRIPTION +The +.Fn log +function allows the kernel to send messages to user processes listening +on +.Pa /dev/klog . +Usually +.Xr syslogd 8 +monitors +.Pa /dev/klog +for these messages and writes them to a log file. +.Pp +All messages are logged using facility +.Dv LOG_KERN . +See +.Xr syslog 3 +for a listing of log levels. +.Sh SEE ALSO +.Xr syslog 3 , +.Xr syslogd 8 diff --git a/static/netbsd/man9/ltsleep.9 b/static/netbsd/man9/ltsleep.9 new file mode 100644 index 00000000..0c727004 --- /dev/null +++ b/static/netbsd/man9/ltsleep.9 @@ -0,0 +1,284 @@ +.\" $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. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Paul Kranenburg. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 7, 2024 +.Dt LTSLEEP 9 +.Os +.Sh NAME +.Nm ltsleep , +.Nm mtsleep , +.Nm tsleep , +.Nm wakeup +.Nd process context sleep and wakeup +.Sh SYNOPSIS +.In sys/proc.h +.Ft int +.Fn "mtsleep" "wchan_t ident" "pri_t priority" "const char *wmesg" "int timo" "kmutex_t *mtx" +.Ft int +.Fn "tsleep" "wchan_t ident" "pri_t priority" "const char *wmesg" "int timo" +.Ft void +.Fn "wakeup" "wchan_t ident" +.Sh DESCRIPTION +.Em The interfaces described in this manual page are obsolete +.Em and will be removed from a future version of the system. +.Pp +.Em The +.Em Fn ltsleep +.Em interface has been obsoleted and removed from the system. +.Pp +.Em Please see the +.Xr condvar 9 , +.Xr mutex 9 , +.Em and +.Xr rwlock 9 +.Em manual pages for information on kernel synchronisation primitives. +.Pp +These functions implement voluntary context switching. +.Fn tsleep +and +.Fn mtsleep +are used throughout the kernel whenever processing in the current context +can not continue for any of the following reasons: +.Bl -bullet -offset indent +.It +The current process needs to await the results of a pending I/O operation. +.It +The current process needs resources +.Pq e.g., memory +which are temporarily unavailable. +.El +.Pp +The function +.Fn wakeup +is used to notify sleeping processes of possible changes to the condition +that caused them to go to sleep. +Typically, an awakened process will \(em after it has acquired a +context again \(em retry the action that blocked its operation to see +if the +.Dq blocking +condition has cleared. +.Pp +The +.Fn tsleep +and +.Fn mtsleep +functions take the following arguments: +.Bl -tag -width priority +.It Fa ident +An identifier of the +.Dq wait channel +representing the resource for which the current process needs to wait. +This typically is the virtual address of some kernel data-structure related +to the resource for which the process is contending. +The same identifier must be used in a call to +.Fn wakeup +to get the process going again. +.Fa ident +should not be +.Dv NULL . +.It Fa priority +The process priority to be used when the process is awakened and put on +the queue of runnable processes. +This mechanism is used to optimize +.Dq throughput +of processes executing in kernel mode. +If the flag +.Dv PCATCH +is OR'ed into +.Fa priority +the process checks for posted signals before and after sleeping. +.It Fa wmesg +A pointer to a character string indicating the reason a process is sleeping. +The kernel does not use the string, but makes it available +.Pq through the process structure field Li p_wmesg +for user level utilities such as +.Xr ps 1 . +.It Fa timo +If non-zero, the process will sleep for at most +.Li timo/hz +seconds. +If this amount of time elapses and no +.Fn wakeup "ident" +has occurred, and no signal +.Pq if Dv PCATCH No was set +was posted, +.Fn tsleep +will return +.Er EWOULDBLOCK . +.El +.Pp +The +.Fn mtsleep +function takes an additional argument and flag: +.Bl -tag -width priority +.It Fa mtx +A +.Xr mutex 9 +representing the lock protecting the data-structures. +On entry +.Fn mtsleep +will release the lock and re-acquire the lock on return. +.It Fa priority +If the flag +.Dv PNORELOCK +is OR'ed into +.Fa priority +then +.Fn mtsleep +will not re-acquire the lock. +.El +.Pp +The +.Fn wakeup +function will mark all processes which are currently sleeping on the identifier +.Fa ident +as runnable. +Eventually, each of the processes will resume execution in the kernel +context, causing a return from +.Fn tsleep +or +.Fn mtsleep . +Note that processes returning from sleep should always re-evaluate the +conditions that blocked them, since a call to +.Fn wakeup +merely signals a +.Em possible +change to the blocking conditions. +.Sh RETURN VALUES +.Fn tsleep +and +.Fn mtsleep +return 0 if they return as a result of a +.Fn wakeup . +If a +.Fn tsleep +and +.Fn mtsleep +return as a result of a signal, the return value is +.Er ERESTART +if the signal has the +.Dv SA_RESTART +property +.Pq see Xr sigaction 2 , +and +.Er EINTR +otherwise. +If +.Fn tsleep +and +.Fn mtsleep +return because of a timeout, the return value is +.Er EWOULDBLOCK . +.Sh MIGRATING TO CONDVAR +Note the conversion from tsleep/wakeup into +.Xr condvar 9 +should not be done mechanically i.e. +.Dq blindly . +Code logic should be understood before changing, and it may also need to be +revisited for the change. +Please also read the +.Xr condvar 9 +man page. +.Pp +The +.Fn tsleep +and +.Fn mtsleep , +and +.Fn wakeup +pairs should generally be replaced by +.Xr cv_wait 9 / +.Xr cv_wait_sig 9 / +.Xr cv_timedwait 9 / +.Xr cv_timedwait_sig 9 +and +.Xr cv_signal 9 / +.Xr cv_broadcast 9 +pairs. +The +.Fn cv_wait* +variant to use can be determined from looking at the corresponding +.Fn tsleep +usage. +.Pp +There are two arguments of interest: +.Ar timo +and +.Ar priority . +The +.Ar priority +value may have OR'ed the flag +.Dv PCATCH . +.Pp +The +.Dv PCATCH +flag means that the blocking thread should be awoken on signal, and +the sleep call should be replaced with +.Xr cv_wait_sig 9 . +.Pp +The +.Ar timo +value, if it is not zero, indicates how long to sleep, and +the sleep call should be replaced with +.Xr cv_timedwait 9 . +.Pp +If both the +.Dv PCATCH +flag and a non-zero +.Ar timo +value are specified, then +.Xr cv_timedwait_sig 9 +should be used. +.Pp +A +.Xr mutex 9 +(interlock) must be held across +.Fn cv_wait +and +.Fn cv_broadcast +calls, in order to protect state. +Most old code will require the addition of locking, whereas some will +require amending to remove +.Dv PNORELOCK . +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr condvar 9 , +.Xr hz 9 , +.Xr kpause 9 , +.Xr mutex 9 , +.Xr rwlock 9 +.Sh HISTORY +The sleep/wakeup process synchronization mechanism is very old. +It appeared in a very early version of Unix. +.Fn tsleep +appeared in +.Bx 4.4 . +.Fn ltsleep +appeared in +.Nx 1.5 . diff --git a/static/netbsd/man9/m_tag.9 b/static/netbsd/man9/m_tag.9 new file mode 100644 index 00000000..1d61b379 --- /dev/null +++ b/static/netbsd/man9/m_tag.9 @@ -0,0 +1,167 @@ +.\" $NetBSD: m_tag.9,v 1.8 2018/11/15 10:23:55 maxv Exp $ +.\" +.\" Copyright (c)2004 YAMAMOTO Takashi, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ------------------------------------------------------------ +.Dd November 15, 2018 +.Dt M_TAG 9 +.Os +.Sh NAME +.Nm m_tag , +.Nm m_tag_get , +.Nm m_tag_free , +.Nm m_tag_prepend , +.Nm m_tag_unlink , +.Nm m_tag_delete , +.Nm m_tag_delete_chain , +.Nm m_tag_find , +.Nm m_tag_copy , +.Nm m_tag_copy_chain +.Nd mbuf tagging interfaces +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In sys/mbuf.h +.Ft struct m_tag * +.Fn m_tag_get "int type" "int len" "int wait" +.Ft void +.Fn m_tag_free "struct m_tag *t" +.Ft void +.Fn m_tag_prepend "struct mbuf *m" "struct m_tag *t" +.Ft void +.Fn m_tag_unlink "struct mbuf *m" "struct m_tag *t" +.Ft void +.Fn m_tag_delete "struct mbuf *m" "struct m_tag *t" +.Ft void +.Fn m_tag_delete_chain "struct mbuf *m" +.Ft struct m_tag * +.Fn m_tag_find "struct mbuf *m" "int type" +.Ft struct m_tag * +.Fn m_tag_copy "struct m_tag *m" +.Ft int +.Fn m_tag_copy_chain "struct mbuf *to" "struct mbuf *from" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +The +.Nm +interface is used to +.Dq tag +mbufs. +.\" XXX PACKET_TAG_* +.\" ------------------------------------------------------------ +.Sh FUNCTIONS +.Bl -tag -width compact +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn m_tag_get "type" "len" "wait" +Allocate an mbuf tag. +.Fa type +is one of the +.Dv PACKET_TAG_ +macros. +.Fa len +is the size of the data associated with the tag, in bytes. +.Fa wait +is either +.Dv M_WAITOK +or +.Dv M_NOWAIT . +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn m_tag_free "t" +Free the mbuf tag +.Fa t . +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn m_tag_prepend "m" "t" +Prepend the mbuf tag +.Fa t +to the mbuf +.Fa m . +.Fa t +will become the first tag of the mbuf +.Fa m . +When +.Fa m +is freed, +.Fa t +will also be freed. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn m_tag_unlink "m" "t" +Unlink the mbuf tag +.Fa t +from the mbuf +.Fa m . +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn m_tag_delete "m" "t" +The same as +.Fn m_tag_unlink +followed by +.Fn m_tag_free . +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn m_tag_delete_chain "m" +Unlink and free mbuf tags from the mbuf +.Fa m . +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn m_tag_find "m" "type" +Find an mbuf tag with type +.Fa type +in the tag chain associated with the mbuf +.Fa m . +If an mbuf tag is found, return a pointer to it. +Otherwise return +.Dv NULL . +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn m_tag_copy "t" +Copy an mbuf tag +.Fa t . +Return a new mbuf tag on success. +Otherwise return +.Dv NULL . +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn m_tag_copy_chain "to" "from" +Copy all mbuf tags associated with the mbuf +.Fa from +to the mbuf +.Fa to . +If +.Fa to +already has any mbuf tags, they will be unlinked and freed beforehand. +Return 1 on success. +Otherwise return 0. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.El +.\" ------------------------------------------------------------ +.Sh CODE REFERENCES +The mbuf tagging interfaces are implemented within the file +.Pa sys/kern/uipc_mbuf.c . +.Pp +The +.Dv PACKET_TAG_ +macros are defined in the file +.Pa sys/sys/mbuf.h . +.Sh SEE ALSO +.Xr intro 9 , +.Xr malloc 9 , +.Xr mbuf 9 +.\" ------------------------------------------------------------ +.Sh BUGS +The semantics of the term "persistent tag" are vague. diff --git a/static/netbsd/man9/makeiplcookie.9 b/static/netbsd/man9/makeiplcookie.9 new file mode 100644 index 00000000..5d3d6bd0 --- /dev/null +++ b/static/netbsd/man9/makeiplcookie.9 @@ -0,0 +1,58 @@ +.\" $NetBSD: makeiplcookie.9,v 1.3 2006/12/23 10:01:32 wiz Exp $ +.\" +.\" Copyright (c)2006 YAMAMOTO Takashi, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ------------------------------------------------------------ +.Dd December 22, 2006 +.Dt MAKEIPLCOOKIE 9 +.Os +.\" ------------------------------------------------------------ +.Sh NAME +.Nm makeiplcookie +.Nd compose an ipl cookie +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In sys/param.h +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft ipl_cookie_t +.Fn makeiplcookie \ +"ipl_t ipl" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +.Fn makeiplcookie +composes a cookie which can be fed into +.Fa splraiseipl . +.Fa ipl +should be one of +.Dv IPL_ +constants. +.\" ------------------------------------------------------------ +.Sh RETURN VALUES +.Fn makeiplcookie +returns a composed cookie. +.\" ------------------------------------------------------------ +.Sh SEE ALSO +.Xr spl 9 , +.Xr splraiseipl 9 diff --git a/static/netbsd/man9/malloc.9 b/static/netbsd/man9/malloc.9 new file mode 100644 index 00000000..f2905cd0 --- /dev/null +++ b/static/netbsd/man9/malloc.9 @@ -0,0 +1,254 @@ +.\" $NetBSD: malloc.9,v 1.59 2021/01/04 18:27:46 pgoyette Exp $ +.\" +.\" Copyright (c) 1996, 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Paul Kranenburg, and by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 4, 2021 +.Dt MALLOC 9 +.Os +.Sh NAME +.Nm malloc , +.Nm realloc , +.Nm free , +.Nm malloc_type_attach , +.Nm malloc_type_detach , +.Nm MALLOC_DEFINE , +.Nm MALLOC_DECLARE +.Nd general-purpose kernel memory allocator +.Sh SYNOPSIS +.In sys/malloc.h +.Ft void * +.Fn malloc "unsigned long size" "struct malloc_type *type" "int flags" +.Ft void * +.Fn realloc "void *addr" "unsigned long newsize" "struct malloc_type *type" \ + "int flags" +.Ft void +.Fn free "void *addr" "struct malloc_type *type" +.Ft void +.Fn malloc_type_attach "struct malloc_type *type" +.Ft void +.Fn malloc_type_detach "struct malloc_type *type" +.In sys/mallocvar.h +.Fn MALLOC_DEFINE "type" "shortdesc" "longdesc" +.Fn MALLOC_JUSTDEFINE "type" "shortdesc" "longdesc" +.Fn MALLOC_DECLARE "type" +.Sh DESCRIPTION +.Bf -symbolic +These interfaces are being obsoleted and their new use is discouraged. +For new code, use +.Xr kmem 9 +for variable-sized or one-time allocations and +.Xr pool_cache 9 +for frequent fixed-size allocations instead. +.Ef +.Pp +The +.Fn malloc +function allocates uninitialized memory in kernel address space for an +object whose size is specified by +.Fa size . +.Fn free +releases memory at address +.Fa addr +that was previously allocated by +.Fn malloc +for re-use. +Unlike +.Xr free 3 , +.Fn free +does not accept an +.Fa addr +argument that is +.Dv NULL . +.Pp +The +.Fn realloc +function changes the size of the previously allocated memory referenced +by +.Fa addr +to +.Fa size +and returns a pointer to the +.Pq possibly moved +object. +The memory contents are unchanged up to the lesser of the new +and old sizes. +If the new size is larger, the newly allocated memory is +uninitialized. +If the requested memory cannot be allocated, +.Dv NULL +is returned and the memory referenced by +.Fa addr +is unchanged. +If +.Fa addr +is +.Dv NULL , +then +.Fn realloc +behaves exactly as +.Fn malloc . +If the new size is 0, then +.Fn realloc +behaves exactly as +.Fn free . +.Pp +Unlike its standard C library counterpart +.Pq Xr malloc 3 , +the kernel version takes two more arguments. +.Pp +The +.Fa flags +argument further qualifies +.Fn malloc +operational characteristics as follows: +.Bl -tag -offset indent -width M_NOWAIT +.It Dv M_NOWAIT +Causes +.Fn malloc +to return +.Dv NULL +if the request cannot be immediately fulfilled due to resource shortage. +If this flag is not set +(see +.Dv M_WAITOK ) , +.Fn malloc +will never return +.Dv NULL . +.It Dv M_WAITOK +By default, +.Fn malloc +may call +.Xr cv_wait 9 +to wait for resources to be released by other processes, and this +flag represents this behaviour. +Note that +.Dv M_WAITOK +is conveniently defined to be 0, and hence may be or'ed into the +.Fa flags +argument to indicate that it's ok to wait for resources. +.It Dv M_ZERO +Causes the allocated memory to be set to all zeros. +.El +.Pp +The +.Fa type +argument describes the subsystem and/or use within a subsystem for which +the allocated memory was needed, and is commonly used to maintain statistics +about kernel memory usage and, optionally, enforce limits on this usage for +certain memory types. +.Pp +In addition to some built-in generic types defined by the kernel +memory allocator, subsystems may define their own types. +.Pp +The +.Fn MALLOC_DEFINE +macro defines a malloc type named +.Fa type +with the short description +.Fa shortdesc , +which must be a constant string; this description will be used for +kernel memory statistics reporting. +The +.Fa longdesc +argument, also a constant string, is intended as way to place a +comment in the actual type definition, and is not currently stored +in the type structure. +If kernel memory statistics are being +gathered, the system will choose a reasonable default limit for +the malloc type. +.Pp +The +.Fn MALLOC_DECLARE +macro is intended for use in header files which are included by +code which needs to use the malloc type, providing the necessary +extern declaration. +.Pp +Code which includes +<sys/malloc.h> +does not need to include +<sys/mallocvar.h> +to get these macro definitions. +The +<sys/mallocvar.h> +header file is intended for other header files which need to use the +.Fn MALLOC_DECLARE +macro. +.Pp +The +.Fn malloc_type_attach +function attaches the malloc type +.Fa type +to the kernel memory allocator. +.Pp +The +.Fn malloc_type_detach +function detaches the malloc type +.Fa type +previously attached with +.Fn malloc_type_attach . +.Pp +The following generic malloc types are currently defined: +.Pp +.Bl -tag -offset indent -width XXXXXXXXXXXXXX -compact +.It Dv M_DEVBUF +Device driver memory. +.It Dv M_DMAMAP +.Xr bus_dma 9 +structures. +.It Dv M_FREE +Should be on free list. +.It Dv M_TEMP +Misc temporary data buffers. +.El +.Pp +Other malloc types are defined by the corresponding subsystem; see the +documentation for that subsystem for information about its available malloc +types. +.Sh NOTES +The malloc type argument is actually unused on +.Nx , +the argument is only supported for easier source compatibility +with +.Fx +and +.Ox . +Likewise calls to +.Fn MALLOC_DECLARE , +.Fn MALLOC_DEFINE , +.Fn malloc_type_attach , +and +.Fn malloc_type_detach +are defined out and have no effect on +.Nx . +.Sh RETURN VALUES +.Fn malloc +returns a kernel virtual address that is suitably aligned for storage of +any type of object. +.Sh SEE ALSO +.Xr vmstat 1 , +.Xr memoryallocators 9 diff --git a/static/netbsd/man9/man9.i386/Makefile b/static/netbsd/man9/man9.i386/Makefile new file mode 100644 index 00000000..032e9892 --- /dev/null +++ b/static/netbsd/man9/man9.i386/Makefile @@ -0,0 +1,4 @@ +MAN = $(wildcard *.9) + +include ../../../mandoc.mk + diff --git a/static/netbsd/man9/man9.i386/bios32_service.9 b/static/netbsd/man9/man9.i386/bios32_service.9 new file mode 100644 index 00000000..1c7a2772 --- /dev/null +++ b/static/netbsd/man9/man9.i386/bios32_service.9 @@ -0,0 +1,51 @@ +.\" $NetBSD: bios32_service.9,v 1.8 2017/02/17 22:31:08 christos Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 17, 2017 +.Dt BIOS32_SERVICE 9 i386 +.Os +.Sh NAME +.Nm bios32_service +.Nd locate BIOS32 service +.Sh SYNOPSIS +.In i386/bios32.h +.Ft int +.Fn bios32_service "uint32_t service" "bios32_entry_t e" \ +"bios32_entry_info_t ei" +.Sh DESCRIPTION +The +.Fn bios32_service +function calls the BIOS32 to locate the specified BIOS32 service +.Fa service +and fills in the entry point information +.Fa e +and +.Fa ei . +.Sh SEE ALSO +.Xr i386/bioscall 9 diff --git a/static/netbsd/man9/man9.i386/bioscall.9 b/static/netbsd/man9/man9.i386/bioscall.9 new file mode 100644 index 00000000..28e1dfc4 --- /dev/null +++ b/static/netbsd/man9/man9.i386/bioscall.9 @@ -0,0 +1,131 @@ +.\" $NetBSD: bioscall.9,v 1.10 2017/07/03 21:31:01 wiz Exp $ +.\" +.\" Copyright (c) 1998 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by John Kohl. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 5, 2010 +.Dt BIOSCALL 9 i386 +.Os +.Sh NAME +.Nm bioscall +.Nd call system BIOS function from real mode +.Sh SYNOPSIS +.In i386/bioscall.h +.Ft void +.Fn bioscall "int function" "struct bioscallregs *regs" +.Sh DESCRIPTION +The +.Fn bioscall +function switches the processor into real mode, calls the +.Tn BIOS +interrupt numbered +.Fa function , +and returns to protected mode. +.Pp +This function is intended to be called during the initial system +bootstrap when necessary to probe devices or pseudo-devices. +.Pp +The register values specified by +.Fa *regs +(with one exception) are installed before the +.Tn BIOS +interrupt is called. +The processor flags are handled specially. +Only the following flags are passed to the +.Tn BIOS +from the registers in +.Fa regs +(the remainder come from the processor's flags register at the time +of the call): +.Ar PSL_C , +.Ar PSL_PF , +.Ar PSL_AF , +.Ar PSL_Z , +.Ar PSL_N , +.Ar PSL_D , +.Ar PSL_V . +.Pp +The +.Va bioscallregs +structure is defined to contain structures for each register, to allow +access to 32-, 16- or 8-bit wide sections of the registers. +Definitions are provided which simplify access to the union members. +.Sh RETURN VALUES +The +.Fn bioscall +function fills in +.Fa *regs +with the processor registers as returned from the +.Tn BIOS +call. +.Sh EXAMPLES +The Advanced Power Management driver calls +.Fn bioscall +by setting up a register structure with the +.Tn APM +installation check and device types in registers +.Fa ax +and +.Fa bx , +then calls the +.Tn BIOS +to fetch the details for calling the +.Tn APM +support through a protected-mode interface. +The +.Tn BIOS +returns these details in the registers: +.Pp +.Bd -literal -offset indent +#include <i386/bioscall.h> +#include <i386/apmvar.h> +struct bioscallregs regs; + +regs.AX = APM_BIOS_FN(APM_INSTALLATION_CHECK); +regs.BX = APM_DEV_APM_BIOS; +regs.CX = regs.DX = 0; +regs.ESI = regs.EDI = regs.EFLAGS = 0; +bioscall(APM_SYSTEM_BIOS, ®s); +.Ed +.Sh CODE REFERENCES +.Pa sys/arch/i386/i386/bioscall.s , +.Pa sys/arch/i386/bioscall/biostramp.S +.Sh REFERENCES +.Xr apm 4 +.Sh HISTORY +The +.Fn bioscall +function first appeared in +.Nx 1.3 . +.Sh BUGS +Not all +.Tn BIOS +functions are safe to call through the trampoline, as they +may depend on system state which has been disturbed or used for other +purposes once the +.Nx +kernel is running. diff --git a/static/netbsd/man9/man9.i386/return_address.9 b/static/netbsd/man9/man9.i386/return_address.9 new file mode 100644 index 00000000..36e4ccdb --- /dev/null +++ b/static/netbsd/man9/man9.i386/return_address.9 @@ -0,0 +1,91 @@ +.\" $NetBSD: return_address.9,v 1.7 2014/03/18 18:20:40 riastradh Exp $ +.\" +.\" Copyright (c) 2009 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by David Young. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 5, 2010 +.Dt RETURN_ADDRESS 9 i386 +.Os +.Sh NAME +.Nm return_address +.Nd return address from call stack +.Sh SYNOPSIS +.In i386/return.h +.Ft void * +.Fn return_address "unsigned int level" +.Sh DESCRIPTION +The +.Fn return_address +function evaluates to the first return address on the call stack +if +.Fa level +equals 0, or else +to the return address for the stack frame +.Fa level +frames down. +.Pp +This function is intended to be called by diagnostic code to record +the call stack. +.Pp +A special fault handler stops +.Fn return_address +from crashing the kernel by examining a non-existent or corrupt stack +frame. +.Pp +Kernel compilation options affect both the ability of +.Fn return_address +to locate return addresses on the stack, and the programmer's +ability to interpret the addresses. +The compiler may optimize away the stack frame pointers that +.Fn return_address +depends on. +.Pp +To use +.Fn return_address +effecively, try a kernel configuration option such as +.Bd -literal +makeoptions DEBUG="-g -fno-omit-frame-pointer \e + -fno-optimize-sibling-calls -O0" +.Ed +.Sh RETURN VALUES +The +.Fn return_address +function returns the requested return address, or +.Dv NULL +if it cannot dissect the call stack. +.Sh CODE REFERENCES +.Pa sys/arch/i386/i386/copy.S , +.Pa sys/arch/i386/include/return.h +.Sh REFERENCES +.Xr config 5 +.Sh HISTORY +The +.Fn return_address +function first appeared in +.Nx 6.0 . +.Sh AUTHORS +.An "David Young" Aq Mt dyoung@NetBSD.org diff --git a/static/netbsd/man9/man9.i386/splraise.9 b/static/netbsd/man9/man9.i386/splraise.9 new file mode 100644 index 00000000..800666ac --- /dev/null +++ b/static/netbsd/man9/man9.i386/splraise.9 @@ -0,0 +1,85 @@ +.\" $NetBSD: splraise.9,v 1.1 2010/02/06 22:32:08 dyoung Exp $ +.\" +.\" Copyright (c) 2010 David Young. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 5, 2010 +.Dt SPLRAISE 9 +.Os +.Sh NAME +.Nm spllower , +.Nm splraise +.Nd modify system interrupt priority level +.Sh SYNOPSIS +.In machine/intr.h +.Ft void +.Fn spllower "int s" +.Ft int +.Fn splraise "int s" +.Sh DESCRIPTION +These functions raise and lower the interrupt priority level +on i386. +They are used by machine-dependent kernel code to implement +the machine-independent +.Xr spl 9 +interface. +.Pp +In a multi-CPU system, these functions change the interrupt +priority level on the local CPU only. +In general, device drivers should not make use of these functions. +.Pp +The +.Fn spllower +function sets the system priority level to the one encoded in +.Fa s , +if +.Fa s +is lower than the current level. +Otherwise, it does not change the level. +Use +.Fn splx +instead +of +.Fn spllower , +except in extraordinary circumstances. +.Pp +The +.Fn splraise +function sets the system priority level to the one encoded in +.Fa s , +if +.Fa s +is greater than the current level, and returns the previous level. +Otherwise, it does not change the level, and it returns the current level. +Except in extraordinary circumstances, +do not use +.Fn splraise . +Use one of the priority-raising functions defined in +.Xr spl 9 , +instead. +.Sh SEE ALSO +.Xr condvar 9 , +.Xr mutex 9 , +.Xr rwlock 9 , +.Xr spl 9 diff --git a/static/netbsd/man9/man9.sun3/Makefile b/static/netbsd/man9/man9.sun3/Makefile new file mode 100644 index 00000000..032e9892 --- /dev/null +++ b/static/netbsd/man9/man9.sun3/Makefile @@ -0,0 +1,4 @@ +MAN = $(wildcard *.9) + +include ../../../mandoc.mk + diff --git a/static/netbsd/man9/man9.sun3/isr_add.9 b/static/netbsd/man9/man9.sun3/isr_add.9 new file mode 100644 index 00000000..d834441d --- /dev/null +++ b/static/netbsd/man9/man9.sun3/isr_add.9 @@ -0,0 +1,124 @@ +.\" $NetBSD: isr_add.9,v 1.10 2019/12/27 09:41:48 msaitoh Exp $ +.\" +.\" Copyright (c) 1997 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jeremy Cooper. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 21, 1997 +.Dt ISR_ADD 9 sun3 +.Os +.Sh NAME +.Nm isr_add , +.Nm isr_add_autovect , +.Nm isr_add_vectored , +.Nm isr_add_custom +.Nd establish interrupt handler +.Sh SYNOPSIS +.In sun3/autoconf.h +.Bd -literal +typedef int (*isr_func_t)(void *); +.Ed +.Ft void +.Fn isr_add_autovect "isr_func_t fun" "void *arg" "int level" +.Ft void +.Fn isr_add_vectored "isr_func_t fun" "void *arg" "int pri" "int vec" +.Ft void +.Fn isr_add_custom "int level" "void *fun" +.Sh DESCRIPTION +The +.Nm +functions establish interrupt handlers into the system interrupt dispatch table +and are typically called from device drivers during the autoconfiguration +process. +.Pp +There are two types of interrupts in the Motorola 68000 architecture, +which differ in the way that an interrupt request is mapped to a dispatch +function within the interrupt vector table. +.Pp +When the CPU detects an asserted signal on one of its interrupt request lines, +it suspends normal instruction execution and begins an interrupt acknowledge +cycle on the system bus. +During this cycle the interrupting device directs how the CPU is to dispatch +its interrupt request. +.Pp +If the interrupting device is integrated tightly with the system bus, +it provides an 8-bit interrupt vector number to the CPU and a +.Sy vectored +interrupt occurs. +This vector number points to a vector entry within the interrupt +vector table to which instruction execution is immediately transferred. +.Pp +If the interrupting device cannot provide a vector number, +it asserts a specialized bus line and an +.Sy autovectored +interrupt occurs. +The vector number to use is determined by adding the interrupt priority +.Pq 0\(en6 +to an autovector base +.Pq typically Li 18 hexadecimal . +.Pp +.Bl -tag -width isr_add_autovec +.It Fn isr_add_autovect +Adds the function +.Fa fun +to the list of interrupt handlers to be called during an autovectored interrupt +of priority +.Fa level . +The pointer +.Fa arg +is passed to the function as its first argument. +.It Fn isr_add_vectored +Adds the function +.Fa fun +to the list of interrupt handlers to be called during a vectored interrupts of +priority +.Fa pri +at dispatch vector number +.Fa vec . +The pointer +.Fa arg +is passed to the function as its first argument. +.It Fn isr_add_custom +Establish function +.Fa fun +as the interrupt handler for vector +.Fa level . +The autovector base number is automatically added to +.Fa level . +.Pp +.Fa fun +is called directly as the dispatch handler and must handle all of the specifics +of saving the processor state and returning from a processor exception. +These requirements generally dictate that +.Fa fun +be written in assembler. +.El +.Sh CODE REFERENCES +.Pa sys/arch/sun3/sun3/isr.c +.Sh REFERENCES +MC68030 User's Manual, Third edition, MC68030UM/AD Rev 2, Motorola Inc. +.Sh BUGS +There is no way to remove a handler once it has been added. diff --git a/static/netbsd/man9/man9.x86/Makefile b/static/netbsd/man9/man9.x86/Makefile new file mode 100644 index 00000000..032e9892 --- /dev/null +++ b/static/netbsd/man9/man9.x86/Makefile @@ -0,0 +1,4 @@ +MAN = $(wildcard *.9) + +include ../../../mandoc.mk + diff --git a/static/netbsd/man9/man9.x86/nmi.9 b/static/netbsd/man9/man9.x86/nmi.9 new file mode 100644 index 00000000..708dba39 --- /dev/null +++ b/static/netbsd/man9/man9.x86/nmi.9 @@ -0,0 +1,135 @@ +.\" $NetBSD: nmi.9,v 1.5 2014/03/18 18:20:40 riastradh Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by David Young. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 17, 2011 +.Dt NMI 9 x86 +.Os +.Sh NAME +.Nm nmi , +.Nm nmi_establish , +.Nm nmi_disestablish , +.Nd NMI +.Sh SYNOPSIS +.In x86/nmi.h +.Ft nmi_handler_t * +.Fn nmi_establish "int (*func)(const struct trapframe *, void *)" "void *arg" +.Ft void +.Fn nmi_disestablish "nmi_handler_t *handle" +.Sh DESCRIPTION +The +.Nm +interface lets the kernel establish handlers for x86 Non-Maskable +Interrupts (NMIs). +An NMI signals to the processor an exception on a processor, memory +controller, or I/O bus that is irrecoverable or else needs attention +at a high priority. +A +.Dq "debug switch" +or a performance/watchdog timer may also trigger an NMI. +.Pp +An NMI handler will run to completion on the same processor where +it began without being preempted by any thread or interrupt except +for another NMI. +An NMI handler must prepare for re-entry. +An NMI handler may run simultaneously on more than one CPU. +.Pp +Synchronizing access to a shared data structure from +an NMI handler is a different challenge than synchronizing access +from hardware/software interrupt routines or from kernel threads. +An NMI handler may not perform any operation that may sleep, acquire +a mutex, or schedule a software interrupt. +An NMI handler may use +.Xr atomic_ops 3 . +An NMI handler may reference per-CPU storage +.Po +.Xr percpu 9 +.Pc . +.Pp +An NMI handler may not write to the kernel message buffer. +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn nmi_establish "func" "arg" +Call this in thread context to establish a handler for non-maskable +interrupts. +Establish +.Fa func +as one of the handler functions to call when an NMI occurs. +Where +.Fa tf +is a +.Vt struct trapframe +representation of the processor context where the NMI was received, +and +.Fa arg +is the argument to +.Fn nmi_establish , +the kernel will call +.Fo (*func) +.Fa tf +.Fa arg +.Fc +every time an NMI occurs until the handler is removed with +.Fn nmi_disestablish . +.Fa func +should return non-zero if it handled a condition that causes +NMI, or zero if it did not. +If, for a given NMI, all handlers return zero, the system will +panic or enter the kernel debugger, +.Xr ddb 4 . +.Fn nmi_establish +returns +.Dv NULL +on failure, and a handle for the NMI handler on success. +.It Fn nmi_disestablish "handle" +Call this in thread context to stop the kernel from calling an NMI +handler. +Indicate the handler to disestablish with the +.Fa handle +returned by +.Fn nmi_establish . +.El +.Sh CODE REFERENCES +The +.Nm +interface is implemented within the file +.Pa sys/arch/x86/x86/nmi.c . +.\" .Sh EXAMPLES +.Sh SEE ALSO +.Xr atomic_ops 3 , +.Xr ddb 4 +.Sh HISTORY +The +.Nm +interface first appeared in +.Nx 6.0 . +.Sh AUTHORS +.An YAMAMOTO Takashi Aq Mt yamt@NetBSD.org +.\" .Sh CAVEATS +.\" .Sh BUGS +.\" .Sh SECURITY CONSIDERATIONS diff --git a/static/netbsd/man9/man9.x86/rdmsr.9 b/static/netbsd/man9/man9.x86/rdmsr.9 new file mode 100644 index 00000000..ab95e482 --- /dev/null +++ b/static/netbsd/man9/man9.x86/rdmsr.9 @@ -0,0 +1,119 @@ +.\" $NetBSD: rdmsr.9,v 1.4 2017/02/17 22:31:08 christos Exp $ +.\" +.\" Copyright (c) 2011 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 17, 2017 +.Dt RDMSR 9 x86 +.Os +.Sh NAME +.Nm msr , +.Nm rdmsr , +.Nm rdmsr_safe , +.Nm wrmsr +.Nd functions for x86 MSRs +.Sh SYNOPSIS +.In x86/cpufunc.h +.Ft uint64_t +.Fn rdmsr "u_int msr" +.\" .Ft uint64_t +.\" .Fn rdmsr_locked "u_int msr" +.Ft int +.Fn rdmsr_safe "u_int msr" "uint64_t *valp" +.Ft void +.Fn wrmsr "u_int msr" "uint64_t val" +.\" .Ft void +.\" .Fn wrmsr_locked "u_int msr" "u_int" "uint64_t val" +.Sh DESCRIPTION +The +.Dv RDMSR +instruction reads from a x86 model-specific register +.Pq Dv MSR . +Conversely, the +.Dv WRMSR +instruction is used to write to a +.Dv MSR . +In +.Nx +the +.Fn rdmsr , +.Fn rdmsr_safe , +and +.Fn wrmsr +functions are used to access +.Dv MSRs . +The header +.In x86/specialreg.h +includes definitions for some of the commonly used MSRs, +that is, control registers that are present +in some x86 processor models but unavailable in others. +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn rdmsr "msr" +Returns the value read from +.Fa msr . +.\" .It Fn rdmsr_locked "msr" +.It Fn rdmsr_safe "msr" "valp" +The +.Fn rdmsr_safe +function is a safer variant of +.Fn rdmsr . +Upon successful completion, +the function returns zero and the value read from the register +.Fa msr +is returned in +.Fa valp . +If a fault occurs while accessing +.Fa msr , +.Fn rdmsr_safe +returns +.Dv EFAULT . +.It Fn wrmsr "msr" "val" +The +.Fn wrmsr +function writes +.Fa val +to the register +.Fa msr . +.\" .It Fn wrmsr_locked "msr" "xxx" "val" +.El +.Pp +Note that even though +.Fn rdmsr_safe +provides support for reading +.Dv MSRs +in a safe manner, it is still a good practice +to always verify that the given model-specific register +is present by using the +.Dv CPUID +instruction, available in +.Nx +via +.Fn x86_cpuid . +.Sh SEE ALSO +.Xr rdtsc 9 , +.Xr x86/x86_msr_xcall 9 diff --git a/static/netbsd/man9/man9.x86/tsc.9 b/static/netbsd/man9/man9.x86/tsc.9 new file mode 100644 index 00000000..31d255dc --- /dev/null +++ b/static/netbsd/man9/man9.x86/tsc.9 @@ -0,0 +1,152 @@ +.\" $NetBSD: tsc.9,v 1.8 2017/02/19 11:54:59 wiz Exp $ +.\" +.\" Copyright (c) 2011 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 17, 2017 +.Dt TSC 9 x86 +.Os +.Sh NAME +.Nm tsc +.Nd Time Stamp Counter +.Sh SYNOPSIS +.In x86/x86/tsc.h +.Ft uint64_t +.Fn rdtsc "void" +.Ft void +.Fn tsc_tc_init "void" +.Ft void +.Fn tsc_sync_ap "struct cpu_info *ci" +.Ft void +.Fn tsc_sync_bp "struct cpu_info *ci" +.Ft void +.Fn tsc_sync_drift "int64_t drift" +.Sh DESCRIPTION +The time stamp counter +.Pq Tn TSC +is a hardware counter found in all contemporary x86 processors. +The counter is implemented as a 64-bit model-specific register +.Pq Tn MSR +that is incremented at every clock cycle. +The +.Tn RDTSC +.Pq Dq read time stamp counter +register has been present since the original Pentium. +.Pp +Already because of the access method, +.Tn TSC +provides a low-overhead and high-resolution +way to obtain +.Tn CPU +timing information. +This traditional premise was violated when such factors as +system sleep states, +.Tn CPU +.Dq hotplugging , +.Dq hibernation , +and +.Tn CPU +frequency scaling +were introduced to the x86 lineage. +This was however mainly a short abruption: +in many new x86 +.Tn CPUs +the time stamp counter is again invariant with +respect to the stability of the clock frequency. +Care should be however taken in implementations that rely on this assumption. +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn rdtsc "" +The +.Fn rdtsc +function returns the value read from +.Dv RDTSC . +.It Fn tsc_tc_init "" +The +.Fn tsc_tc_init +function initializes the +.Tn TSC +as a +.Xr timecounter 9 . +The function is called early in the boot process when the processors attach. +.It Fn tsc_sync_bp "ci" +The +.Fn tsc_sync_bp +function synchronizes the counter for the boot processor +.Pq Tn BP . +The supplied +.Fa ci +must refer to the +.Tn BP +itself. +The +.Nm +interface takes internally care of such issues as out-of-order execution, +where instructions are not necessarily performed in the order of execution, +possibly causing a misleading cycle count. +.It Fn tsc_sync_ap "ci" +The +.Fn tsc_sync_ap +function synchronize the counter for the application processor +.Fa ci . +Interrupts must be off at machine-level when the function is called. +.Pp +It is necessary to call both +.Fn tsc_sync_ap +and +.Fn tsc_sync_bp +during the boot, but additional synchronization +may be required also during runtime. +As an example, the +.Tn TSC +needs to be synchronized for all processors when the system resumes from an +.Xr acpi 4 +sleep state. +.It Fn tsc_sync_drift "drift" +Finally, the +.Fn tsc_sync_drift +function records +.Fa drift , +measured in clock cycles. +This is called when the +.Tn APs +attach. +.El +.\" +.\" Some references that are not worth adding to the actual page: +.\" +.\" http://lwn.net/Articles/209101/ +.\" http://lwn.net/Articles/388188/ +.\" http://lkml.org/lkml/2005/11/4/173 +.\" http://www.ccsl.carleton.ca/~jamuir/rdtscpm1.pdf +.\" +.Sh SEE ALSO +.Xr gettimeofday 2 , +.Xr hpet 4 , +.Xr hz 9 , +.Xr timecounter 9 , +.Xr x86/rdmsr 9 diff --git a/static/netbsd/man9/man9.x86/x86_msr_xcall.9 b/static/netbsd/man9/man9.x86/x86_msr_xcall.9 new file mode 100644 index 00000000..34b9c103 --- /dev/null +++ b/static/netbsd/man9/man9.x86/x86_msr_xcall.9 @@ -0,0 +1,98 @@ +.\" $NetBSD: x86_msr_xcall.9,v 1.5 2017/02/17 22:31:08 christos Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 17, 2017 +.Dt X86_MSR_XCALL 9 x86 +.Os +.Sh NAME +.Nm x86_msr_xcall +.Nd MSR specific cross-call +.Sh SYNOPSIS +.In x86/cpu_msr.h +.Ft void +.Fn x86_msr_xcall "void *arg1" "void *arg1" +.Sh DESCRIPTION +The +.Fn x86_msr_xcall +function provides a x86-specific IPI handler suitable for use with the +.Xr xcall 9 +interface. +It can be used to ensure that a given +.Tn MSR +call is executed on all processors. +The prototype follows the +.Ft xcfunc_t +function pointer type and the opaque +.Fa arg1 +pointer is casted to the following structure: +.Bd -literal -offset indent +struct msr_rw_info { + int msr_read; + int msr_type; + uint64_t msr_value; + uint64_t msr_mask; +}; +.Ed +.Pp +This structure must be filled prior to the call. +Two fields are compulsory: +.Fa msr_type +is used as the address of the +.Tn MSR +and +.Fa msr_value +is the value to be written. +If +.Fa msr_read +is not zero, +.Fn x86_msr_xcall +will first read from +.Fa msr_type +and then clear the mask specified in +.Fa msr_mask +before the write operation. +.Sh EXAMPLES +The following example writes a value zero to the +.Tn MSR_THERM_CONTROL +model-specific register on all processors in the system: +.Bd -literal -offset indent +struct msr_rw_info msr; +uint64_t xc; + +msr.msr_value = 0; +msr.msr_read = true; +msr.msr_type = MSR_THERM_CONTROL; +msr.msr_mask = 0x1e; + +xc = xc_broadcast(0, (xcfunc_t)x86_msr_xcall, &msr, NULL); +xc_wait(xc); +.Ed +.Sh SEE ALSO +.Xr x86/rdmsr 9 , +.Xr xcall 9 diff --git a/static/netbsd/man9/mbuf.9 b/static/netbsd/man9/mbuf.9 new file mode 100644 index 00000000..1e3948f6 --- /dev/null +++ b/static/netbsd/man9/mbuf.9 @@ -0,0 +1,721 @@ +.\" $NetBSD: mbuf.9,v 1.67 2022/06/28 20:12:52 rillig Exp $ +.\" +.\" Copyright (c) 1997 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation is derived from text contributed to The NetBSD Foundation +.\" by S.P.Zeidler (aka stargazer). +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 28, 2022 +.Dt MBUF 9 +.Os +.Sh NAME +.Nm mbuf , +.Nm m_get , +.Nm m_gethdr , +.Nm m_devget , +.Nm m_copym , +.Nm m_copypacket , +.Nm m_copydata , +.Nm m_copyback , +.Nm m_copyback_cow , +.Nm m_cat , +.Nm m_dup , +.Nm m_makewritable , +.Nm m_pulldown , +.Nm m_pullup , +.Nm m_copyup , +.Nm m_split , +.Nm m_adj , +.Nm m_apply , +.Nm m_free , +.Nm m_freem , +.Nm mtod , +.Nm MGET , +.Nm MGETHDR , +.Nm MEXTMALLOC , +.Nm MEXTADD , +.Nm MCLGET , +.Nm m_copy_pkthdr , +.Nm m_move_pkthdr , +.Nm m_remove_pkthdr , +.Nm m_align , +.Nm M_LEADINGSPACE , +.Nm M_TRAILINGSPACE , +.Nm M_PREPEND , +.Nm MCHTYPE +.Nd "functions and macros for managing memory used by networking code" +.Sh SYNOPSIS +.In sys/mbuf.h +.Ft struct mbuf * +.Fn m_get "int how" "int type" +.Ft struct mbuf * +.Fn m_gethdr "int how" "int type" +.Ft struct mbuf * +.Fn m_devget "char *buf" "int totlen" "int off" "struct ifnet *ifp" +.Ft struct mbuf * +.Fn m_copym "struct mbuf *m" "int off" "int len" "int wait" +.Ft struct mbuf * +.Fn m_copypacket "struct mbuf *m" "int how" +.Ft void +.Fn m_copydata "struct mbuf *m" "int off" "int len" "void *cp" +.Ft void +.Fn m_copyback "struct mbuf *m0" "int off" "int len" "void *cp" +.Ft struct mbuf * +.Fn m_copyback_cow "struct mbuf *m0" "int off" "int len" "void *cp" "int how" +.Ft int +.Fn m_makewritable "struct mbuf **mp" "int off" "int len" "int how" +.Ft void +.Fn m_cat "struct mbuf *m" "struct mbuf *n" +.Ft struct mbuf * +.Fn m_dup "struct mbuf *m" "int off" "int len" "int wait" +.Ft struct mbuf * +.Fn m_pulldown "struct mbuf *m" "int off" "int len" "int *offp" +.Ft struct mbuf * +.Fn m_pullup "struct mbuf *n" "int len" +.Ft struct mbuf * +.Fn m_copyup "struct mbuf *m" "int len" "int dstoff" +.Ft struct mbuf * +.Fn m_split "struct mbuf *m0" "int len" "int wait" +.Ft void +.Fn m_adj "struct mbuf *mp" "int req_len" +.Ft int +.Fn m_apply "struct mbuf *m" "int off" "int len" "int *f(void *, void *, unsigned int)" "void *arg" +.Ft struct mbuf * +.Fn m_free "struct mbuf *m" +.Ft void +.Fn m_freem "struct mbuf *m" +.Ft datatype +.Fn mtod "struct mbuf *m" "datatype" +.Ft void +.Fn MGET "struct mbuf *m" "int how" "int type" +.Ft void +.Fn MGETHDR "struct mbuf *m" "int how" "int type" +.Ft void +.Fn MEXTMALLOC "struct mbuf *m" "int len" "int how" +.Ft void +.Fn MEXTADD "struct mbuf *m" "void *buf" "int size" "int type" "void (*free)(struct mbuf *, void *, size_t, void *)" "void *arg" +.Ft void +.Fn MCLGET "struct mbuf *m" "int how" +.Ft void +.Fn m_copy_pkthdr "struct mbuf *to" "struct mbuf *from" +.Ft void +.Fn m_move_pkthdr "struct mbuf *to" "struct mbuf *from" +.Ft void +.Fn m_remove_pkthdr "struct mbuf *m" +.Ft void +.Fn m_align "struct mbuf *m" "int len" +.Ft int +.Fn M_LEADINGSPACE "struct mbuf *m" +.Ft int +.Fn M_TRAILINGSPACE "struct mbuf *m" +.Ft void +.Fn M_PREPEND "struct mbuf *m" "int plen" "int how" +.Ft void +.Fn MCHTYPE "struct mbuf *m" "int type" +.Sh DESCRIPTION +The +.Nm +functions and macros provide an easy and consistent way to handle +a networking stack's memory management needs. +An +.Nm +consists of a header and a data area. +It is of a fixed size, +.Dv MSIZE +.Pq defined in Aq Pa machine/param.h , +which includes the size of the header. +The header contains a pointer to the next +.Nm +in the +.Sq "mbuf chain" , +a pointer to the next +.Sq "mbuf chain" , +a pointer to the data area, the amount of data in this mbuf, its type +and a +.Dv flags +field. +.Pp +The +.Dv type +variable can signify: +.Bl -tag -compact -offset indent -width "XXXXXXXXXXX" +.It Dv MT_FREE +the mbuf should be on the ``free'' list +.It Dv MT_DATA +data was dynamically allocated +.It Dv MT_HEADER +data is a packet header +.It Dv MT_SONAME +data is a socket name +.It Dv MT_SOOPTS +data is socket options +.It Dv MT_FTABLE +data is the fragment reassembly header +.It Dv MT_CONTROL +mbuf contains ancillary \&(protocol control\&) data +.It Dv MT_OOBDATA +mbuf contains out-of-band data. +.El +.Pp +The +.Dv flags +variable contains information describing the +.Nm , +notably: +.Bl -tag -compact -offset indent -width "XXXXXXXXXXX" +.It Dv M_EXT +has external storage +.It Dv M_PKTHDR +is start of record +.It Dv M_EOR +is end of record +.El +.Pp +If an +.Nm +designates the start of a record +.Pq Dv M_PKTHDR , +its +.Dv flags +field may contain additional information describing the content of +the record: +.Bl -tag -compact -offset indent -width "XXXXXXXXXXX" +.It Dv M_BCAST +sent/received as link-level broadcast +.It Dv M_MCAST +sent/received as link-level multicast +.El +.Pp +An +.Nm +may add a single +.Sq "mbuf cluster" +of +.Dv MCLBYTES +bytes +.Pq defined in Aq Pa machine/param.h , +which has no additional overhead +and is used instead of the internal data area; this is done when at least +.Dv MINCLSIZE +bytes of data must be stored. +.Pp +When the +.Dv M_EXT +flag is set on an mbuf, +the external storage area could be shared among multiple mbufs. +Therefore, care must be taken when overwriting the data content of an +mbuf, because its external storage could be considered as read-only. +.Bl -tag -width compact +.It Fn m_get "int how" "int type" +Allocates an mbuf and initializes it to contain internal data. +The +.Fa how +parameter is a choice of +.Dv M_WAIT / M_DONTWAIT +from caller. +.Dv M_WAIT +means the call cannot fail, but may take forever. +The +.Fa type +parameter is an mbuf type. +.It Fn m_gethdr "int how" "int type" +Allocates an mbuf and initializes it to contain a packet header and internal +data. +The +.Fa how +parameter is a choice of +.Dv M_WAIT / M_DONTWAIT +from caller. +The +.Fa type +parameter is an mbuf type. +.It Fn m_devget "char *buf" "int totlen" "int off" "struct ifnet *ifp" +Copies +.Fa len +bytes from device local memory into mbufs. +If parameter +.Fa off +is non-zero, the packet is supposed to be trailer-encapsulated and +.Fa off +bytes plus the type and length fields will be skipped before copying. +Returns the top of the mbuf chain it created. +.It Fn m_copym "struct mbuf *m" "int off" "int len" "int wait" +Creates a copy of an mbuf chain starting +.Fa off +bytes from the beginning, continuing for +.Fa len +bytes. +If the +.Fa len +requested is +.Dv M_COPYALL , +the complete mbuf chain will be copied. +The +.Fa wait +parameter is a choice of +.Dv M_WAIT / M_DONTWAIT +from caller. +.It Fn m_copypacket "struct mbuf *m" "int how" +Copies an entire packet, including header. +This function is an optimization of the common case +.Li m_copym ( m , 0 , Dv M_COPYALL , Fa how ) . +However, contrary to +.Fn m_copym , +a header must be present. +It is incorrect to use +.Fn m_copypacket +with an mbuf that does not have a header. +.It Fn m_copydata "struct mbuf *m" "int off" "int len" "void *cp" +Copies +.Fa len +bytes data from mbuf chain +.Fa m +into the buffer +.Fa cp , +starting +.Fa off +bytes from the beginning. +.It Fn m_copyback "struct mbuf *m0" "int off" "int len" "void *cp" +Copies +.Fa len +bytes data from buffer +.Fa cp +back into the mbuf chain +.Fa m0 , +starting +.Fa off +bytes from the beginning of the chain, extending the mbuf chain if necessary. +.Fn m_copyback +can only fail when extending the chain. +The caller should check for this kind of failure +by checking the resulting length of the chain in that case. +It is an error to use +.Fn m_copyback +on read-only mbufs. +.It Fn m_copyback_cow "struct mbuf *m0" "int off" "int len" "void *cp" \ +"int how" +Copies +.Fa len +bytes data from buffer +.Fa cp +back into the mbuf chain +.Fa m0 +as +.Fn m_copyback +does. +Unlike +.Fn m_copyback , +it is safe to use +.Fn m_copyback_cow +on read-only mbufs. +If needed, +.Fn m_copyback_cow +automatically allocates new mbufs and adjusts the chain. +On success, it returns a pointer to the resulting mbuf chain, +and frees the original mbuf +.Fa m0 . +Otherwise, it returns +.Dv NULL . +The +.Fa how +parameter is a choice of +.Dv M_WAIT / M_DONTWAIT +from the caller. +Unlike +.Fn m_copyback , +extending the mbuf chain isn't supported. +It is an error to attempt to extend the mbuf chain using +.Fn m_copyback_cow . +.It Fn m_makewritable "struct mbuf **mp" "int off" "int len" "int how" +Rearranges an mbuf chain so that +.Fa len +bytes from offset +.Fa off +are writable. +When it meets read-only mbufs, it allocates new mbufs, adjusts the chain as +.Fn m_copyback_cow +does, and copies the original content into them. +.Fn m_makewritable +does +.Em not +guarantee that all +.Fa len +bytes at +.Fa off +are consecutive. +The +.Fa how +parameter is a choice of +.Dv M_WAIT / M_DONTWAIT +from the caller. +.Fn m_makewritable +preserves the contents of the mbuf chain even in the case of failure. +It updates a pointer to the mbuf chain pointed to by +.Fa mp . +It returns 0 on success. +Otherwise, it returns an error code, typically +.Er ENOBUFS . +.It Fn m_cat "struct mbuf *m" "struct mbuf *n" +Concatenates mbuf chain +.Fa n +to +.Fa m . +Both chains must be of the same type; packet headers will +.Em not +be updated if present. +.It Fn m_dup "struct mbuf *m" "int off" "int len" "int wait" +Similarly to +.Fn m_copym , +the function creates a copy of an mbuf chain starting +.Fa off +bytes from the beginning, continuing for +.Fa len +bytes. +While +.Fn m_copym +tries to share external storage for mbufs with +.Dv M_EXT +flag, +.Fn m_dup +will deep-copy the whole data content into new mbuf chain +and avoids shared external storage. +.It Fn m_pulldown "struct mbuf *m" "int off" "int len" "int *offp" +Rearranges an mbuf chain so that +.Fa len +bytes from offset +.Fa off +are contiguous and in the data area of an mbuf. +The return value points to an mbuf in the middle of the mbuf chain +.Fa m . +If we call the return value +.Fa n , +the contiguous data region is available at +.Li "mtod(n, void *) + *offp" , +or +.Li "mtod(n, void *)" +if +.Fa offp +is +.Dv NULL . +The top of the mbuf chain +.Fa m , +and mbufs up to +.Fa off , +will not be modified. +On successful return, it is guaranteed that the mbuf pointed to by +.Fa n +does not have a shared external storage, +therefore it is safe to update the contiguous region. +Returns +.Dv NULL +and frees the mbuf chain on failure. +.Fa len +must be smaller than or equal to +.Dv MCLBYTES . +.It Fn m_pullup "struct mbuf *m" "int len" +Rearranges an mbuf chain so that +.Fa len +bytes are contiguous +and in the data area of an mbuf (so that +.Fn mtod +will work for a structure of size +.Fa len ) . +Returns the resulting +mbuf chain on success, frees it and returns +.Dv NULL +on failure. +If there is room, it will add up to +.Dv max_protohdr +- +.Fa len +extra bytes to the +contiguous region to possibly avoid being called again. +.Fa len +must be smaller or equal than +.Dv MHLEN . +.It Fn m_copyup "struct mbuf *m" "int len" "int dstoff" +Similar to +.Fn m_pullup +but copies +.Fa len +bytes of data into a new mbuf at +.Fa dstoff +bytes into the mbuf. +The +.Fa dstoff +argument aligns the data and leaves room for a link layer header. +Returns the new +mbuf chain on success, and frees the mbuf chain and returns +.Dv NULL +on failure. +Note that +the function does not allocate mbuf clusters, so +.Fa len + dstoff +must be less than +.Dv MHLEN . +.It Fn m_split "struct mbuf *m0" "int len" "int wait" +Partitions an mbuf chain in two pieces, returning the tail, +which is all but the first +.Fa len +bytes. +In case of failure, it returns +.Dv NULL +and restores the chain to its original state. +.It Fn m_adj "struct mbuf *mp" "int req_len" +Shaves off +.Fa req_len +bytes from head or tail of the (valid) data area. +If +.Fa req_len +is greater than zero, front bytes are being shaved off, if it's smaller, +from the back (and if it is zero, the mbuf will stay bearded). +This function does not move data in any way, but is used to manipulate the +data area pointer and data length variable of the mbuf in a non-clobbering +way. +.It Fn m_apply "struct mbuf *m" "int off" "int len" "int (*f)(void *, void *, unsigned int)" "void *arg" +Apply function +.Fa f +to the data in an mbuf chain starting +.Fa off +bytes from the beginning, continuing for +.Fa len +bytes. +Neither +.Fa off +nor +.Fa len +may be negative. +.Fa arg +will be supplied as first argument for +.Fa f , +the second argument will be the pointer to the data buffer of a +packet (starting after +.Fa off +bytes in the stream), and the third argument is the amount +of data in bytes in this call. +If +.Fa f +returns something not equal to zero +.Fn m_apply +will bail out, returning the return code of +.Fa f . +Upon successful completion it will return zero. +.It Fn m_free "struct mbuf *m" +Frees mbuf +.Fa m . +.It Fn m_freem "struct mbuf *m" +Frees the mbuf chain beginning with +.Fa m . +This function contains the elementary sanity check for a +.Dv NULL +pointer. +.It Fn mtod "struct mbuf *m" "datatype" +Returns a pointer to the data contained in the specified mbuf +.Fa m , +type-casted to the specified data type +.Fa datatype . +.It Fn MGET "struct mbuf *m" "int how" "int type" +Allocates mbuf +.Fa m +and initializes it to contain internal data. +See +.Fn m_get . +.It Fn MGETHDR "struct mbuf *m" "int how" "int type" +Allocates mbuf +.Fa m +and initializes it to contain a packet header. +See +.Fn m_gethdr . +.It Fn MEXTMALLOC "struct mbuf *m" "int len" "int how" +Allocates external storage of size +.Fa len +for mbuf +.Fa m . +The +.Fa how +parameter is a choice of +.Dv M_WAIT / M_DONTWAIT +from caller. +The flag +.Dv M_EXT +is set upon success. +.It Fn MEXTADD "struct mbuf *m" "void *buf" "int size" "int type" "void (*free)(struct mbuf *, void *, size_t, void *)" "void *arg" +Adds pre-allocated external storage +.Fa buf +to a normal mbuf +.Fa m ; +the parameters +.Fa size , +.Fa type , +.Fa free +and +.Fa arg +describe the external storage. +.Fa size +is the size of the storage, +.Fa type +describes its +.Xr malloc 9 +type, +.Fa free +is a free routine (if not the usual one), and +.Fa arg +is a possible argument to the free routine. +The flag +.Dv M_EXT +is set upon success. +If a free routine is specified, it will be called when the mbuf is freed. +In the case of former, the first argument for a free routine is the mbuf +.Fa m +and the routine is expected to free it in addition to the external storage +pointed by second argument. +In the case of latter, the first argument for the routine is NULL. +.It Fn MCLGET "struct mbuf *m" "int how" +Allocates and adds an mbuf cluster to a normal mbuf +.Fa m . +The +.Fa how +parameter is a choice of +.Dv M_WAIT / M_DONTWAIT +from caller. +The flag +.Dv M_EXT +is set upon success. +.It Fn m_copy_pkthdr "struct mbuf *to" "struct mbuf *from" +Copies the mbuf pkthdr from mbuf +.Fa from +to mbuf +.Fa to . +.Fa from +must have the type flag +.Dv M_PKTHDR +set, and +.Fa to +must be empty. +.It Fn m_move_pkthdr "struct mbuf *to" "struct mbuf *from" +Moves the mbuf pkthdr from mbuf +.Fa from +to mbuf +.Fa to . +.Fa from +must have the type flag +.Dv M_PKTHDR +set, and +.Fa to +must be empty. +The flag +.Dv M_PKTHDR +in mbuf +.Fa from +will be cleared. +.It Fn m_remove_pkthdr "struct mbuf *m" +Removes the mbuf pkthdr from mbuf +.Fa m . +.Fa m +must have the flag +.Dv M_PKTHDR +set. +This flag will be cleared. +.It Fn m_align "struct mbuf *m" "int len" +Sets the data pointer of a newly allocated mbuf +.Fa m +to +.Fa len +bytes from the end of the mbuf data area, so that +.Fa len +bytes of data written to the mbuf +.Fa m , +starting at the data pointer, will be aligned to the end of the data area. +.It Fn M_LEADINGSPACE "struct mbuf *m" +Returns the amount of space available before the current start of valid +data in mbuf +.Fa m . +Returns 0 if the mbuf data part is shared across multiple mbufs +.Pq i.e. not writable . +.It Fn M_TRAILINGSPACE "struct mbuf *m" +Returns the amount of space available after the current end of valid +data in mbuf +.Fa m . +Returns 0 if the mbuf data part is shared across multiple mbufs +.Pq i.e. not writable . +.It Fn M_PREPEND "struct mbuf *m" "int plen" "int how" +Prepends space of size +.Fa plen +to mbuf +.Fa m . +If a new mbuf must be allocated, +.Fa how +specifies whether to wait. +If +.Fa how +is +.Dv M_DONTWAIT +and allocation fails, the original mbuf chain is freed and +.Fa m +is set to +.Dv NULL . +It is illegal for the +.Fa plen +parameter to be greater than +.Dv MHLEN . +.It Fn MCHTYPE "struct mbuf *m" "int type" +Change mbuf +.Fa m +to new type +.Fa type . +.El +.Sh CODE REFERENCES +The +.Nm +management functions are implemented within the file +.Pa sys/kern/uipc_mbuf.c . +Function prototypes, and the functions implemented as macros +are located in +.Pa sys/sys/mbuf.h . +.Sh SEE ALSO +.Pa /usr/share/doc/reference/ref9/net , +.Xr netstat 1 , +.Xr m_tag 9 , +.Xr malloc 9 +.Rs +.%A Jun-ichiro Hagino +.%T "Mbuf issues in 4.4BSD IPv6/IPsec support (experiences from KAME IPv6/IPsec implementation)" +.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" +.%D June 2000 +.Re +.Sh AUTHORS +.An -nosplit +The original mbuf data structures were designed by Rob Gurwitz +when he did the initial TCP/IP implementation at BBN. +.Pp +Further extensions and enhancements were made by Bill Joy, Sam Leffler, +and Mike Karels at CSRG. +.Pp +Current implementation of external storage by +.An Matt Thomas +.Aq matt@3am-software.com +and +.An Jason R. Thorpe +.Aq thorpej@NetBSD.org . diff --git a/static/netbsd/man9/mca.9 b/static/netbsd/man9/mca.9 new file mode 100644 index 00000000..5ac4da15 --- /dev/null +++ b/static/netbsd/man9/mca.9 @@ -0,0 +1,192 @@ +.\" $NetBSD: mca.9,v 1.12 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 7, 2001 +.Dt MCA 9 +.Os +.Sh NAME +.Nm MCA , +.Nm mca_intr_establish , +.Nm mca_intr_disestablish , +.Nm mca_intr_evcnt , +.Nm mca_conf_read , +.Nm mca_conf_write +.Nd MicroChannel Architecture bus +.Sh SYNOPSIS +.In sys/bus.h +.In dev/mca/mcavar.h +.In dev/mca/mcadevs.h +.Ft void * +.Fn mca_intr_establish "mca_chipset_tag_t mc" "mca_intr_handle_t hdl" \ +"int level" "int (*handler)(void *)" "void *arg" +.Ft void +.Fn mca_intr_disestablish "mca_chipset_tag_t mc" "mca_intr_handle_t hdl" +.Ft const struct evcnt * +.Fn mca_intr_evcnt "mca_chipset_tag_t mc" "mca_intr_handle_t hdl" +.Ft int +.Fn mca_conf_read "mca_chipset_tag_t mc" "int slot" "int reg" +.Ft void +.Fn mca_conf_write "mca_chipset_tag_t mc" "int slot" "int reg" \ +"int data" +.Sh DESCRIPTION +The +.Nm +device provides support for IBM's MicroChannel Architecture bus found +on IBM PS/2 systems and selected workstations. +It was designed as a replacement bus for the ISA bus found on IBM's +older machines. +However, the bus specifications were only available under license, so +MCA did not achieve widespread acceptance in the industry. +.Pp +Being a replacement for the ISA bus, the MCA bus does share some +similar aspects with the ISA bus. +Some MCA devices can be detected via the usual ISA-style probing. +However, most device detection is done through the Programmable Option +Select (POS) registers. +These registers provide a window into a device to determine device-specific +properties and configuration. +The configuration of devices and their POS registers is performed using +IBM's system configuration software. +.Pp +The MCA bus uses level-triggered interrupts while the ISA bus uses +edge-triggered interrupts. +Level triggered interrupts have the advantage that they can be shared +among multiple device. +Therefore, most MCA-specific devices should be coded with shared +interrupts in mind. +.Sh DATA TYPES +Drivers for devices attached to the MCA bus will make use of the +following data types: +.Bl -tag -width compact +.It Fa mca_chipset_tag_t +Chipset tag for the MCA bus. +.It Fa mca_intr_handle_t +The opaque handle describing an established interrupt handler. +.It Fa struct mca_attach_args +A structure use to inform the driver of MCA bus properties. +It contains the following members: +.Bd -literal + bus_space_tag_t ma_iot; /* MCA I/O space tag */ + bus_space_tag_t ma_memt; /* MCA mem space tag */ + bus_dma_tag_t ma_dmat; /* MCA DMA tag */ + int ma_slot; /* MCA slot number */ + int ma_pos[8]; /* MCA POS values */ + int ma_id; /* MCA device */ +.Ed +.El +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn mca_intr_establish "mc" "hdl" "level" "handler" "arg" +Establish a MCA interrupt handler on the MCA bus specified by +.Fa mc +for the interrupt described completely by +.Fa hdl . +The priority of the interrupt is specified by +.Fa level . +When the interrupt occurs the function +.Fa handler +is called with argument +.Fa arg . +.It Fn mca_intr_disestablish "mc" "hdl" +Dis-establish the interrupt handler on the MCA bus specified by +.Fa mc +for the interrupt described completely +.Fa hdl . +.It Fn mca_intr_evcnt "mc" "hdl" +Do interrupt event counting on the MCA bus specified by +.Fa mc +for the event described completely by +.Fa hdl . +.It Fn mca_conf_read "mc" "slot" "reg" +Read the POS register +.Fa reg +for the device in slot +.Fa slot +on the MCA bus specified by +.Fa mc . +.It Fn mca_conf_write "mc" "slot" "reg" "data" +Write data +.Fa data +to the POS register +.Fa reg +for the device in slot +.Fa slot +on the MCA bus specified by +.Fa mc . +.El +.Sh AUTOCONFIGURATION +The MCA bus is a direct-connection bus. +During autoconfiguration, the parent specifies the MCA device ID for the +found device in the +.Fa ma_id +member of the +.Em mca_attach_args +structure. +Drivers should match on the device ID. +Device capabilities and configuration information should be read from +device POS registers using +.Fn mca_conf_read . +Some important configuration information found in the POS registers +include the I/O base address, memory base address and interrupt +number. +The location of these configurable options with the POS registers are +device specific. +.Sh DMA SUPPORT +The MCA bus supports 32-bit, bidirectional DMA transfers. +Currently, no machine-independent support for MCA DMA is available. +.Sh CODE REFERENCES +The MCA subsystem itself is implemented within the file +.Pa sys/dev/mca/mca_subr.c . +Machine-dependent portions can be found in +.Pa sys/arch/<arch>/mca/mca_machdep.c . +The database of known devices exists within the file +.Pa sys/dev/mca/mcadevs_data.h +and is generated automatically from the file +.Pa sys/dev/mca/mcadevs . +New vendor and product identifiers should be added to this file. +The database can be regenerated using the Makefile +.Pa sys/dev/mca/Makefile.mcadevs . +.Pp +A good source of information about MCA devices is IBM's system +configuration disk. +The disk contains .adf files which describe the location of device +configuration options in the POS registers. +.Sh SEE ALSO +.Xr mca 4 , +.Xr autoconf 9 , +.Xr bus_dma 9 , +.Xr bus_space 9 , +.Xr driver 9 , +.Xr isa 9 +.Sh BUGS +The machine-independent +.Nm +driver does not currently support DMA. +MCA devices which require DMA operation currently access the DMA +capabilities directly. diff --git a/static/netbsd/man9/memcmp.9 b/static/netbsd/man9/memcmp.9 new file mode 100644 index 00000000..c0ab1c90 --- /dev/null +++ b/static/netbsd/man9/memcmp.9 @@ -0,0 +1,74 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)memcmp.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: memcmp.9,v 1.5 2003/08/07 10:31:30 agc Exp $ +.\" +.Dd July 7, 2001 +.Dt MEMCMP 9 +.Os +.Sh NAME +.Nm memcmp +.Nd compare byte string +.Sh SYNOPSIS +.In sys/systm.h +.Ft int +.Fn memcmp "const void *b1" "const void *b2" "size_t len" +.Sh DESCRIPTION +The +.Fn memcmp +function +compares byte string +.Fa b1 +against byte string +.Fa b2 . +Both strings are assumed to be +.Fa len +bytes long. +.Sh RETURN VALUES +The +.Fn memcmp +function +returns zero if the two strings are identical, +otherwise returns the difference between the first two differing bytes +(treated as unsigned char values, so that +.Sq Li \e200 +is greater than +.Sq Li \&\e0 , +for example). +Zero-length strings are always identical. +.\" .Sh SEE ALSO +.Sh STANDARDS +The +.Fn memcmp +function +conforms to +.St -ansiC . diff --git a/static/netbsd/man9/memcpy.9 b/static/netbsd/man9/memcpy.9 new file mode 100644 index 00000000..be3e454a --- /dev/null +++ b/static/netbsd/man9/memcpy.9 @@ -0,0 +1,73 @@ +.\" $NetBSD: memcpy.9,v 1.10 2017/03/18 19:01:01 riastradh Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)memcpy.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd January 2, 2012 +.Dt MEMCPY 9 +.Os +.Sh NAME +.Nm memcpy +.Nd copy byte string +.Sh SYNOPSIS +.In sys/systm.h +.Ft void * +.Fn memcpy "void * restrict dst" "const void * restrict src" "size_t len" +.Sh DESCRIPTION +The +.Fn memcpy +function +copies +.Fa len +bytes from string +.Fa src +to string +.Fa dst . +The arguments must not overlap \(em behavior if the arguments overlap +is undefined. +To copy byte strings that overlap, use +.Xr memmove 9 . +.Sh RETURN VALUES +The +.Fn memcpy +function +returns the original value of +.Fa dst . +.Sh SEE ALSO +.Xr memmove 9 +.Sh STANDARDS +The +.Fn memcpy +function +conforms to +.St -isoC-99 . diff --git a/static/netbsd/man9/memmove.9 b/static/netbsd/man9/memmove.9 new file mode 100644 index 00000000..54bda7c2 --- /dev/null +++ b/static/netbsd/man9/memmove.9 @@ -0,0 +1,69 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)memmove.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: memmove.9,v 1.6 2003/08/07 10:31:30 agc Exp $ +.\" +.Dd July 7, 2001 +.Dt MEMMOVE 9 +.Os +.Sh NAME +.Nm memmove +.Nd copy byte string +.Sh SYNOPSIS +.In sys/systm.h +.Ft void * +.Fn memmove "void *dst" "const void *src" "size_t len" +.Sh DESCRIPTION +The +.Fn memmove +function +copies +.Fa len +bytes from string +.Fa src +to string +.Fa dst . +The two strings may overlap; +the copy is always done in a non-destructive manner. +.Sh RETURN VALUES +The +.Fn memmove +function returns the original value of +.Fa dst . +.Sh SEE ALSO +.Xr memcpy 9 +.Sh STANDARDS +The +.Fn memmove +function +conforms to +.St -ansiC . diff --git a/static/netbsd/man9/memoryallocators.9 b/static/netbsd/man9/memoryallocators.9 new file mode 100644 index 00000000..4ab06679 --- /dev/null +++ b/static/netbsd/man9/memoryallocators.9 @@ -0,0 +1,164 @@ +.\" $NetBSD: memoryallocators.9,v 1.8 2017/10/29 03:48:17 riastradh Exp $ +.\" +.\" Copyright (c) 2006 Elad Efrat <elad@NetBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 28, 2017 +.Dt MEMORYALLOCATORS 9 +.Os +.Sh NAME +.Nm memoryallocators +.Nd introduction to kernel memory allocators +.Sh DESCRIPTION +The +.Nx +kernel provides several memory allocators, each with different characteristics +and purpose. +This document summarizes the main differences between them. +.Pp +You should use the +.Xr kmem 9 +allocator for all allocations unless you have special needs that it +does not provide, such as: +.Bl -bullet -compact +.It +use from interrupt handlers +.It +a minimum reserved number of allocations +.It +a maximum usable number of allocations +.It +costly object initialization that can be reused +.It +allocating resources other than pageable RAM-backed kernel virtual +address space +.El +.Ss The Kmem Allocator +The +.Xr kmem 9 +allocator is main general purpose allocator in the kernel. +It was modelled after an interface of the same name implemented +in Solaris. +.Pp +.Xr kmem 9 +is fast and requires no setup. +It cannot be used from interrupt context. +.Pp +Internally, +.Xr kmem 9 +is implemented using a collection of pool caches for common small +allocation sizes, so there is no performance benefit to using a pool +cache if you have no other needs. +.Ss The Pool Allocator +The +.Xr pool 9 +allocator is a fixed-size memory allocator which requires setup to +initialize a shared pool. +.Pp +A pool can be configured with a low-water mark to reserve a minimum +number of objects available, a high-water mark to bound the maximum number of +objects in reserve, and a hard limit to bound on the maximum number of +objects in use. +.Pp +.Xr pool_get 9 +can be used to allocate memory in interrupt context for objects that +have been reserved in advance, with the possibility of failure if there +are none. +.Pp +By default, +.Xr pool 9 +allocates pageable RAM-backed kernel virtual address space from the +same backing store as +.Xr kmem 9 , +but it can be configured to allocate any kind of resource with a custom +allocator. +.\".Pp +.\" On some architectures (foo, bar) the +.\" .Xr pool 9 +.\" allocator will use direct-mapped segments rather than normal page +.\" mappings, which can reduce TLB contentions. +.Ss The Pool Cache Allocator +The pool cache allocator is a per-CPU cache on top of +.Xr pool 9 +for fixed-size memory allocations that may occur in interrupt context +requiring setup beforehand. +.Pp +The per-CPU cache makes allocation much cheaper \(em no interprocessor +synchronization in the fast case \(em at the cost of potentially +caching some extra resources on one CPU that cannot be used by another. +.Pp +In addition to all the features of a pool like a custom backing +allocator, a pool cache also supports a constructor and destructor +routine for when objects are drawn from the shared pool in case the +per-CPU cache is empty, or returned to it when the cache is full. +This can reduce the cost of reusable initialization and finalization, +or associate objects with CPU-local resources. +.Ss The UVM Kernel Memory Allocator +The +.Xr uvm_km 9 +API is a low-level memory allocator for page-aligned kernel virtual +address space in multiples of +.Dv PAGE_SIZE , +with wired RAM backing, pageable RAM backing, or backing to be supplied +by the caller with +.Xr pmap 9 . +.Ss The VMEM Allocator API +The +.Xr vmem 9 +API is a general address space allocator. +It is used internally by +.Xr kmem 9 , +.Xr pool 9 , +.Xr uvm 9 , +and other kernel subsystems and device drivers to allocate regions of +various kinds of address spaces. +Internally, it allocates large chunks of the address space and uses a +.Xr pool_cache 9 +to draw small allocations out of them. +.Ss The Extent Manager +The +.Xr extent 9 +API manages and allocates constrained regions of an address space. +The extent manager is optimized for simplicity, not speed, and is +available early at boot. +.Nx +uses +.Xr extent 9 +to reserve regions of I/O port and memory spaces to prevent drivers +from using the same device registers or bus memory. +.Sh SEE ALSO +.Xr bus_space 9 , +.Xr extent 9 , +.Xr intro 9 , +.Xr kmem 9 , +.Xr pool 9 , +.Xr pool_cache 9 , +.Xr uvm 9 , +.Xr uvm_km 9 , +.Xr vmem 9 +.Sh AUTHORS +.An Elad Efrat Aq Mt elad@NetBSD.org +.An YAMAMOTO Takashi Aq Mt yamt@NetBSD.org +.An Taylor R Campbell Aq Mt riastradh@NetBSD.org diff --git a/static/netbsd/man9/memset.9 b/static/netbsd/man9/memset.9 new file mode 100644 index 00000000..026aee77 --- /dev/null +++ b/static/netbsd/man9/memset.9 @@ -0,0 +1,67 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)memset.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: memset.9,v 1.5 2003/08/07 10:31:30 agc Exp $ +.\" +.Dd July 7, 2001 +.Dt MEMSET 9 +.Os +.Sh NAME +.Nm memset +.Nd write a byte to byte string +.Sh SYNOPSIS +.In sys/systm.h +.Ft void * +.Fn memset "void *b" "int c" "size_t len" +.Sh DESCRIPTION +The +.Fn memset +function +writes +.Fa len +bytes of value +.Fa c +(converted to an unsigned char) to the string +.Fa b . +.Sh RETURN VALUES +The +.Fn memset +function +returns the original value of +.Fa b . +.\" .Sh SEE ALSO +.Sh STANDARDS +The +.Fn memset +function +conforms to +.St -ansiC . diff --git a/static/netbsd/man9/mi_switch.9 b/static/netbsd/man9/mi_switch.9 new file mode 100644 index 00000000..b7b38723 --- /dev/null +++ b/static/netbsd/man9/mi_switch.9 @@ -0,0 +1,113 @@ +.\" $NetBSD: mi_switch.9,v 1.4 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright (c) 1996, 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Paul Kranenburg. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 21, 2007 +.Dt MI_SWITCH 9 +.Os +.Sh NAME +.Nm mi_switch +.Nd machine independent context switch prelude +.Sh SYNOPSIS +.Ft int +.Fn mi_switch "struct lwp *l" +.Sh DESCRIPTION +The +.Fn mi_switch +function implements the machine-independent prelude to an LWP context +switch. +It is called from only a few distinguished places in the kernel +code as a result of the principle of non-preemptable kernel mode +execution. +The three major uses of +.Fn mi_switch +can be enumerated as follows: +.Bl -enum -offset indent +.It +From within +.Xr cv_wait 9 +and associated methods +when the current LWP voluntarily relinquishes the CPU to wait for +some resource to become available. +.It +From within +.Xr preempt 9 +when the current LWP voluntarily relinquishes the CPU or when the +kernel prepares a return to user-mode execution. +.It +In the signal handling code +if a signal is delivered that causes an LWP to stop +.Pq see Xr issignal 9 . +.El +.Pp +.Fn mi_switch +records the amount of time the current LWP has been running in the +LWP structure and checks this value against the CPU time limits +allocated to the LWP +.Pq see Xr getrlimit 2 . +Exceeding the soft limit results in a +.Dv SIGXCPU +signal to be posted to the LWP, while exceeding the hard limit will +cause a +.Dv SIGKILL . +.Pp +Unless +.Fa l->l_switchto +is not +.Dv NULL , +.Fn mi_switch +will call +.Fn sched_nextlwp +to select a new LWP from the scheduler's runqueue structures. +If no runnable LWP is found, the idle LWP is used. +If the new LWP is not equal to the current one, +.Fn mi_switch +will hand over control to the machine-dependent function +.Xr cpu_switchto 9 +to switch to the new LWP. +.Pp +.Fn mi_switch +has to be called with the LWP lock held +(through calling +.Fn lwp_lock +first) and at the +.Xr splsched 9 +interrupt protection level. +It returns with the LWP lock released. +.Sh RETURN VALUES +.Fn mi_switch +returns 1 if a context switch was performed to a +different LWP, 0 otherwise. +.Sh SEE ALSO +.Xr condvar 9 , +.Xr cpu_switchto 9 , +.Xr csf 9 , +.Xr pmap 9 , +.Xr ras 9 , +.Xr sched_4bsd 9 , +.Xr splsched 9 diff --git a/static/netbsd/man9/microseq.9 b/static/netbsd/man9/microseq.9 new file mode 100644 index 00000000..39bb3c04 --- /dev/null +++ b/static/netbsd/man9/microseq.9 @@ -0,0 +1,514 @@ +.\" $NetBSD: microseq.9,v 1.6 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright (c) 1998, 1999, Nicolas Souchu +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man9/microseq.9,v 1.9.2.5 2001/12/17 11:30:18 ru Exp $ +.\" +.Dd December 29, 2003 +.Dt MICROSEQ 9 +.Os +.Sh NAME +.Nm microseq +.Nd ppbus microseqencer developer's guide +.Sh SYNOPSIS +.In sys/types.h +.In dev/ppbus/ppbus_conf.h +.In dev/ppbus/ppbus_msq.h +.Sh DESCRIPTION +See +.Xr ppbus 4 +for +.Nm ppbus +description and general info about the microsequencer. +.Pp +The purpose of this document is to encourage developers to use the +microsequencer mechanism in order to have: +.Bl -enum -offset indent +.It +a uniform programming model +.It +efficient code +.El +.Pp +Before using microsequences, you are encouraged to look at the +.Xr atppc 4 +microsequencer implementation and an example of how using it in +.Xr vpo 4 . +.Ss PPBUS register model +.Ss Background +The parallel port model chosen for +.Xr ppbus 4 +is the PC parallel port model. +Thus, any register described later has the same semantic than its +counterpart in a PC parallel port. +For more info about ISA/ECP programming, get the +Microsoft standard referenced +.Dq Tn "Extended Capabilities Port Protocol and ISA interface Standard" . +Registers described later are standard parallel port registers. +.Pp +Mask macros are defined in the standard +.Xr ppbus 4 +include files for each valid bit of parallel port registers. +.Ss Data register +In compatible or nibble mode, writing to this register will drive +data to the parallel port data lines. +In any other mode, drivers may be tri-stated by setting the direction +bit (PCD) in the control register. +Reads to this register return the value on the data lines. +.Ss Device status register +This read-only register reflects the inputs on the parallel port +interface. +.Pp +.Bl -column "Bit" "Name" "Description" -compact +.It Em Bit Ta Em Name Ta Em Description +.It 7 Ta nBUSY Ta "inverted version of parallel port Busy signal" +.It 6 Ta nACK Ta "version of parallel port nAck signal" +.It 5 Ta PERROR Ta "version of parallel port PERROR signal" +.It 4 Ta SELECT Ta "version of parallel port Select signal" +.It 3 Ta nFAULT Ta "version of parallel port nFault signal" +.El +.Pp +Others are reserved and return undefined result when read. +.Ss Device control register +This register directly controls several output signals as well as +enabling some functions. +.Pp +.Bl -column "Bit" "Name " "Description" -compact +.It Em Bit Ta Em Name Ta Em Description +.It 5 Ta PCD Ta "direction bit in extended modes" +.It 4 Ta IRQENABLE Ta "1 enables an interrupt on the rising edge of nAck" +.It 3 Ta SELECTIN Ta "inverted and driven as parallel port nSelectin signal" +.It 2 Ta nINIT Ta "driven as parallel port nInit signal" +.It 1 Ta AUTOFEED Ta "inverted and driven as parallel port nAutoFd signal" +.It 0 Ta STROBE Ta "inverted and driven as parallel port nStrobe signal" +.El +.Sh MICROINSTRUCTIONS +.Ss Description +.Em Microinstructions +are either parallel port accesses, program iterations, submicrosequence +or C calls. +The parallel port must be considered as the logical model described in +.Xr ppbus 4 . +.Pp +Available microinstructions are: +.Bd -literal +#define MS_OP_GET 0 /* get <ptr>, <len> */ +#define MS_OP_PUT 1 /* put <ptr>, <len> */ +#define MS_OP_RFETCH 2 /* rfetch <reg>, <mask>, <ptr> */ +#define MS_OP_RSET 3 /* rset <reg>, <mask>, <mask> */ +#define MS_OP_RASSERT 4 /* rassert <reg>, <mask> */ +#define MS_OP_DELAY 5 /* delay <val> */ +#define MS_OP_SET 6 /* set <val> */ +#define MS_OP_DBRA 7 /* dbra <offset> */ +#define MS_OP_BRSET 8 /* brset <mask>, <offset> */ +#define MS_OP_BRCLEAR 9 /* brclear <mask>, <offset> */ +#define MS_OP_RET 10 /* ret <retcode> */ +#define MS_OP_C_CALL 11 /* c_call <function>, <parameter> */ +#define MS_OP_PTR 12 /* ptr <pointer> */ +#define MS_OP_ADELAY 13 /* adelay <val> */ +#define MS_OP_BRSTAT 14 /* brstat <mask>, <mask>, <offset> */ +#define MS_OP_SUBRET 15 /* subret <code> */ +#define MS_OP_CALL 16 /* call <microsequence> */ +#define MS_OP_RASSERT_P 17 /* rassert_p <iter>, <reg> */ +#define MS_OP_RFETCH_P 18 /* rfetch_p <iter>, <reg>, <mask> */ +#define MS_OP_TRIG 19 /* trigger <reg>, <len>, <array> */ +.Ed +.Ss Execution context +The +.Em execution context +of microinstructions is: +.Bl -bullet -offset indent +.It +the +.Em program counter +which points to the next microinstruction to execute either in the +main microsequence or in a subcall +.It +the current value of +.Em ptr +which points to the next char to send/receive +.It +the current value of the internal +.Em branch register +.El +.Pp +This data is modified by some of the microinstructions, not all. +.Ss MS_OP_GET and MS_OP_PUT +are microinstructions used to do either predefined standard +.Tn IEEE1284-1994 +transfers or programmed non-standard I/O. +.Ss MS_OP_RFETCH - Register FETCH +is used to retrieve the current value of a parallel port register, +apply a mask and save it in a buffer. +.Pp +Parameters: +.Bl -enum -offset indent +.It +register +.It +character mask +.It +pointer to the buffer +.El +.Pp +Predefined macro: MS_RFETCH(reg,mask,ptr) +.Ss MS_OP_RSET - Register SET +is used to assert/clear some bits of a particular parallel port +register, two masks are applied. +.Pp +Parameters: +.Bl -enum -offset indent +.It +register +.It +mask of bits to assert +.It +mask of bits to clear +.El +.Pp +Predefined macro: MS_RSET(reg,assert,clear) +.Ss MS_OP_RASSERT - Register ASSERT +is used to assert all bits of a particular parallel port register. +.Pp +Parameters: +.Bl -enum -offset indent +.It +register +.It +byte to assert +.El +.Pp +Predefined macro: MS_RASSERT(reg,byte) +.Ss MS_OP_DELAY - microsecond DELAY +is used to delay the execution of the microsequence. +.Pp +Parameter: +.Bl -enum -offset indent +.It +delay in microseconds +.El +.Pp +Predefined macro: MS_DELAY(delay) +.Ss MS_OP_SET - SET internal branch register +is used to set the value of the internal branch register. +.Pp +Parameter: +.Bl -enum -offset indent +.It +integer value +.El +.Pp +Predefined macro: MS_SET(accum) +.Ss MS_OP_DBRA - \&Do BRAnch +is used to branch if internal branch register decremented by one result value +is positive. +.Pp +Parameter: +.Bl -enum -offset indent +.It +integer offset in the current executed (sub)microsequence. +Offset is added to +the index of the next microinstruction to execute. +.El +.Pp +Predefined macro: MS_DBRA(offset) +.Ss MS_OP_BRSET - BRanch on SET +is used to branch if some of the status register bits of the parallel port +are set. +.Pp +Parameter: +.Bl -enum -offset indent +.It +bits of the status register +.It +integer offset in the current executed (sub)microsequence. +Offset is added to +the index of the next microinstruction to execute. +.El +.Pp +Predefined macro: MS_BRSET(mask,offset) +.Ss MS_OP_BRCLEAR - BRanch on CLEAR +is used to branch if some of the status register bits of the parallel port +are cleared. +.Pp +Parameter: +.Bl -enum -offset indent +.It +bits of the status register +.It +integer offset in the current executed (sub)microsequence. +Offset is added to the index of the next microinstruction to execute. +.El +.Pp +Predefined macro: MS_BRCLEAR(mask,offset) +.Ss MS_OP_RET - RETurn +is used to return from a microsequence. +This instruction is mandatory. +This is the only way for the microsequencer to detect the end of +the microsequence. +The return code is returned in the integer pointed by the (int *) +parameter of the ppb_MS_microseq(). +.Pp +Parameter: +.Bl -enum -offset indent +.It +integer return code +.El +.Pp +Predefined macro: MS_RET(code) +.Ss MS_OP_C_CALL - C function CALL +is used to call C functions from microsequence execution. +This may be useful when a non-standard I/O is performed to retrieve +a data character from the parallel port. +.Pp +Parameter: +.Bl -enum -offset indent +.It +the C function to call +.It +the parameter to pass to the function call +.El +.Pp +The C function shall be declared as a +.Ft int(*)(void *p, char *ptr) . +The ptr parameter is the current position in the buffer currently +scanned. +.Pp +Predefined macro: MS_C_CALL(func,param) +.Ss MS_OP_PTR - initialize internal PTR +is used to initialize the internal pointer to the currently scanned +buffer. +This pointer is passed to any C call (see above). +.Pp +Parameter: +.Bl -enum -offset indent +.It +pointer to the buffer that shall be accessed by +.Fn xxx_P +microsequence calls. +Note that this pointer is automatically incremented during +.Fn xxx_P +calls. +.El +.Pp +Predefined macro: MS_PTR(ptr) +.Ss MS_OP_ADELAY - do an Asynchronous DELAY +is used to make a +.Xr cv_timedwait 9 +during microsequence execution. +.Pp +Parameter: +.Bl -enum -offset indent +.It +delay in ms +.El +.Pp +Predefined macro: MS_ADELAY(delay) +.Ss MS_OP_BRSTAT - BRanch on STATe +is used to branch on status register state condition. +.Pp +Parameter: +.Bl -enum -offset indent +.It +mask of asserted bits. +Bits that shall be asserted in the status register +are set in the mask +.It +mask of cleared bits. +Bits that shall be cleared in the status register +are set in the mask +.It +integer offset in the current executed (sub)microsequence. +Offset is added +to the index of the next microinstruction to execute. +.El +.Pp +Predefined macro: MS_BRSTAT(asserted_bits,clear_bits,offset) +.Ss MS_OP_SUBRET - SUBmicrosequence RETurn +is used to return from the submicrosequence call. +This action is mandatory before a RET call. +Some microinstructions (PUT, GET) may not be callable +within a submicrosequence. +.Pp +No parameter. +.Pp +Predefined macro: MS_SUBRET() +.Ss MS_OP_CALL - submicrosequence CALL +is used to call a submicrosequence. +A submicrosequence is a microsequence with a SUBRET call. +Parameter: +.Bl -enum -offset indent +.It +the submicrosequence to execute +.El +.Pp +Predefined macro: MS_CALL(microseq) +.Ss MS_OP_RASSERT_P - Register ASSERT from internal PTR +is used to assert a register with data currently pointed by the +internal PTR pointer. +Parameter: +.Bl -enum -offset indent +.It +amount of data to write to the register +.It +register +.El +.Pp +Predefined macro: MS_RASSERT_P(iter,reg) +.Ss MS_OP_RFETCH_P - Register FETCH to internal PTR +is used to fetch data from a register. +Data is stored in the buffer currently pointed by the internal PTR +pointer. +Parameter: +.Bl -enum -offset indent +.It +amount of data to read from the register +.It +register +.It +mask applied to fetched data +.El +.Pp +Predefined macro: MS_RFETCH_P(iter,reg,mask) +.Ss MS_OP_TRIG - TRIG register +is used to trigger the parallel port. +This microinstruction is intended to provide a very efficient +control of the parallel port. +Triggering a register is writing data, wait a while, write data, +wait a while... +This allows to write magic sequences to the port. +Parameter: +.Bl -enum -offset indent +.It +amount of data to read from the register +.It +register +.It +size of the array +.It +array of unsigned chars. +Each couple of u_chars define the data to write to the register +and the delay in us to wait. +The delay is limited to 255 us to simplify and reduce the size of +the array. +.El +.Pp +Predefined macro: MS_TRIG(reg,len,array) +.Sh MICROSEQUENCES +.Ss C structures +.Bd -literal +union ppb_insarg { + int i; + char c; + void *p; + int (* f)(void *, char *); +}; + +struct ppb_microseq { + int opcode; /* microins. opcode */ + union ppb_insarg arg[PPB_MS_MAXARGS]; /* arguments */ +}; +.Ed +.Ss Using microsequences +To instantiate a microsequence, just declare an array of ppb_microseq +structures and initialize it as needed. +You may either use predefined macros +or code directly your microinstructions according to the ppb_microseq +definition. +For example, +.Bd -literal + struct ppb_microseq select_microseq[] = { + + /* parameter list + */ + #define SELECT_TARGET MS_PARAM(0, 1, MS_TYP_INT) + #define SELECT_INITIATOR MS_PARAM(3, 1, MS_TYP_INT) + + /* send the select command to the drive */ + MS_DASS(MS_UNKNOWN), + MS_CASS(H_nAUTO | H_nSELIN | H_INIT | H_STROBE), + MS_CASS( H_AUTO | H_nSELIN | H_INIT | H_STROBE), + MS_DASS(MS_UNKNOWN), + MS_CASS( H_AUTO | H_nSELIN | H_nINIT | H_STROBE), + + /* now, wait until the drive is ready */ + MS_SET(VP0_SELTMO), +/* loop: */ MS_BRSET(H_ACK, 2 /* ready */), + MS_DBRA(-2 /* loop */), +/* error: */ MS_RET(1), +/* ready: */ MS_RET(0) + }; +.Ed +.Pp +Here, some parameters are undefined and must be filled before +executing the microsequence. +In order to initialize each microsequence, one +should use the +.Fn ppb_MS_init_msq +function like this: +.Bd -literal -offset indent +ppb_MS_init_msq(select_microseq, 2, + SELECT_TARGET, 1 << target, + SELECT_INITIATOR, 1 << initiator); +.Ed +.Pp +and then execute the microsequence. +.Ss The microsequencer +The microsequencer is executed either at ppbus or adapter level +(see +.Xr ppbus 4 +for info about ppbus system layers). +Most of the microsequencer is executed at +.Xr atppc 4 +level to avoid +.Xr ppbus 4 +to adapter function call overhead. +But some actions like deciding whereas the transfer is +.Tn IEEE1284-1994 +compliant are executed at +.Xr ppbus 4 +layer. +.Sh SEE ALSO +.Xr atppc 4 , +.Xr ppbus 4 , +.Xr vpo 4 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 3.0 . +.Sh AUTHORS +This +manual page is based on the +.Fx +.Nm microseq +manual page and was update for the +.Nx +port by +.An Gary Thorpe . +.Sh BUGS +Only one level of submicrosequences is allowed. +.Pp +When triggering the port, maximum delay allowed is 255 us. diff --git a/static/netbsd/man9/microtime.9 b/static/netbsd/man9/microtime.9 new file mode 100644 index 00000000..dab1996d --- /dev/null +++ b/static/netbsd/man9/microtime.9 @@ -0,0 +1,184 @@ +.\" $NetBSD: microtime.9,v 1.21 2013/09/17 19:58:03 wiz Exp $ +.\" +.\" Copyright (c) 1998 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jeremy Cooper. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 2000 Kelly Yancey +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man9/microtime.9,v 1.11 2005/10/13 16:01:28 jhb Exp $ +.\" +.Dd May 13, 2013 +.Dt MICROTIME 9 +.Os +.Sh NAME +.Nm bintime , +.Nm getbintime , +.Nm microtime , +.Nm getmicrotime , +.Nm nanotime , +.Nm getnanotime +.Nd get the current time +.Sh SYNOPSIS +.In sys/time.h +.Ft void +.Fo bintime +.Fa "struct bintime *bt" +.Fc +.Ft void +.Fo getbintime +.Fa "struct bintime *bt" +.Fc +.Ft void +.Fo "microtime" +.Fa "struct timeval *tv" +.Fc +.Ft void +.Fo getmicrotime +.Fa "struct timeval *tv" +.Fc +.Ft void +.Fo nanotime +.Fa "struct timespec *tsp" +.Fc +.Ft void +.Fo getnanotime +.Fa "struct timespec *tsp" +.Fc +.Sh DESCRIPTION +The +.Fn bintime +and +.Fn getbintime +functions store the system time as a +.Vt "struct bintime" +at the addresses specified by +.Fa bt . +The +.Fn microtime +and +.Fn getmicrotime +functions perform the same utility, but record the time as a +.Vt "struct timeval" +instead. +Similarly the +.Fn nanotime +and +.Fn getnanotime +functions store the time as a +.Vt "struct timespec" . +The structures are described in +.Xr timeval 3 . +.Pp +The +.Fn bintime , +.Fn microtime , +and +.Fn nanotime +functions +always query the timecounter to return the current time as precisely as +possible. +Whereas +.Fn getbintime , +.Fn getmicrotime , +and +.Fn getnanotime +functions are abstractions which return a less precise, but +faster to obtain, time. +.Pp +The intent of the +.Fn getbintime , +.Fn getmicrotime , +and +.Fn getnanotime +functions is to enforce the user's preference for timer accuracy versus +execution time. +They should be used where a precision of +.Pf 1/ Em HZ +(e.g., 10 msec on a +.Pf 100 Em HZ +machine, see +.Xr hz 9 ) +is acceptable or where performance is priority. +.Pp +The system realtime clock is guaranteed to be monotonically increasing +at all times. +As such, all calls to these functions are guaranteed to return a system time +greater than or equal to the system time returned in any previous calls. +Comparable functions exist to retrieve the time elapsed since boot; see +.Xr microuptime 9 . +.Sh CODE REFERENCES +The implementation of the +.Fn microtime +family of functions is in +.Pa sys/kern/kern_tc.c +as a part of the +.Xr timecounter 9 +framework. +.Pp +The implementation of the time counter sources used by the +.Xr timecounter 9 +is machine dependent, +hence its location in the source code tree varies from architecture to +architecture. +.Sh SEE ALSO +.Xr settimeofday 2 , +.Xr bintime_add 9 , +.Xr inittodr 9 , +.Xr time_second 9 , +.Xr tvtohz 9 +.Sh AUTHORS +This manual page was written by +.An Jeremy Cooper +and +.An Kelly Yancey Aq Mt kbyanc@posi.net . +.Sh CAVEATS +Despite the guarantee that the system realtime clock will always be +monotonically increasing, +it is always possible for the system clock to be manually reset by the +system administrator to any date. diff --git a/static/netbsd/man9/microuptime.9 b/static/netbsd/man9/microuptime.9 new file mode 100644 index 00000000..f1942188 --- /dev/null +++ b/static/netbsd/man9/microuptime.9 @@ -0,0 +1,115 @@ +.\" $NetBSD: microuptime.9,v 1.12 2014/03/18 18:20:40 riastradh Exp $ +.\" +.\" Copyright (c) 2000 Kelly Yancey +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man9/microuptime.9,v 1.7 2005/01/12 21:48:25 ru Exp $ +.\" +.Dd June 8, 2010 +.Dt MICROUPTIME 9 +.Os +.Sh NAME +.Nm binuptime , +.Nm getbinuptime , +.Nm microuptime , +.Nm getmicrouptime , +.Nm nanouptime , +.Nm getnanouptime +.Nd get the time elapsed since boot +.Sh SYNOPSIS +.In sys/time.h +.Ft void +.Fn binuptime "struct bintime *bt" +.Ft void +.Fn getbinuptime "struct bintime *bt" +.Ft void +.Fn microuptime "struct timeval *tv" +.Ft void +.Fn getmicrouptime "struct timeval *tv" +.Ft void +.Fn nanouptime "struct timespec *ts" +.Ft void +.Fn getnanouptime "struct timespec *tsp" +.Sh DESCRIPTION +The +.Fn binuptime +and +.Fn getbinuptime +functions store the time elapsed since boot as a +.Vt "struct bintime" +at the address specified by +.Fa bt . +The +.Fn microuptime +and +.Fn getmicrouptime +functions perform the same utility, but record the elapsed time as a +.Vt "struct timeval" +instead. +Similarly the +.Fn nanouptime +and +.Fn getnanouptime +functions store the elapsed time as a +.Vt "struct timespec" . +The used structures are described in +.Xr timeval 3 . +.Pp +The +.Fn binuptime , +.Fn microuptime , +and +.Fn nanouptime +functions +always query the timecounter to return the current time as precisely as +possible. +Whereas +.Fn getbinuptime , +.Fn getmicrouptime , +and +.Fn getnanouptime +functions are abstractions which return a less precise, but +faster to obtain, time. +.Pp +The intent of the +.Fn getbinuptime , +.Fn getmicrouptime , +and +.Fn getnanouptime +functions is to enforce the user's preference for timer accuracy versus +execution time. +They should be used where a precision of +.Pf 1/ Em HZ +(e.g., 10 msec on a +.Pf 100 Em HZ +machine, see +.Xr hz 9 ) +is acceptable or where performance is priority. +.Sh SEE ALSO +.Xr microtime 9 , +.Xr timecounter 9 , +.Xr tvtohz 9 +.Sh AUTHORS +This manual page was written by +.An Kelly Yancey Aq Mt kbyanc@posi.net . diff --git a/static/netbsd/man9/module.9 b/static/netbsd/man9/module.9 new file mode 100644 index 00000000..3e44e6cc --- /dev/null +++ b/static/netbsd/man9/module.9 @@ -0,0 +1,617 @@ +.\" $NetBSD: module.9,v 1.55 2025/02/25 08:51:27 martin Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Andrew Doran. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 21, 2021 +.Dt MODULE 9 +.Os +.Sh NAME +.Nm module , +.Nm module_load , +.Nm module_autoload , +.Nm module_unload , +.Nm module_init_class , +.Nm module_hold , +.Nm module_rele , +.Nm module_find_section , +.Nm module_kernel , +.Nm module_name , +.Nm module_source , +.Nm module_register_callbacks , +.Nm module_unregister_callbacks , +.Nm module_specific_key_create , +.Nm module_specific_key_delete , +.Nm module_getspecific , +.Nm module_setspecific +.Nd kernel module loader +.Sh SYNOPSIS +.In sys/module.h +.Fn MODULE "class" "name" "required" +.Ft int +.Fn module_load "const char *name" "int flags" "prop_dictionary_t props" \ +"modclass_t class" +.Ft int +.Fn module_autoload "const char *name" "modclass_t class" +.Ft int +.Fn module_unload "const char *name" +.Ft void +.Fn module_init_class "modclass_t class" +.Ft void +.Fn module_hold "module_t *module" +.Ft void +.Fn module_rele "module_t *module" +.Ft int +.Fn module_find_section "const char *" "void **" "size_t *" +.Ft "module_t *" +.Fn module_kernel "void" +.Ft "const char *" +.Fn module_name "struct module *module" +.Ft modsrc_t +.Fn module_source "struct module *module" +.Ft void +.Fn module_init "void" +.Ft void +.Fn module_start_unload_thread "void" +.Ft void +.Fn module_builtin_require_force "void" +.Ft void +.Fn module_load_vfs_init "void" +.Ft "void *" +.Fn module_register_callbacks "void (*)(struct module *)" \ +"void (*unload)(struct module *)" +.Ft void +.Fn module_unregister_callbacks "void *" +.Ft specificdata_key_t +.Fn module_specific_key_create "specificdata_key_t *keyp" \ +"specificdata_dtor_t dtor" +.Ft void +.Fn module_specific_key_delete "specificdata_key_t key" +.Ft "void *" +.Fn module_getspecific "module_t *mod" "specificdata_key_t key" +.Ft "void *" +.Fn module_setspecific "module_t *mod" "specificdata_key_t key" "void *data" +.Sh DESCRIPTION +Modules are sections of code that can be independently linked and selectively +loaded into or unloaded from a running kernel. +This provides a mechanism to update the module without having to relink +the kernel and reboot. +Modules can be loaded from within the kernel image, provided by the boot +loader, or loaded from the file system. +.Pp +The +.Nm +subsystem includes two data types: +.Bl -enum -offset indent +.It +The +.Vt module_t +type provides storage to describe a module. +.It +The +.Vt modinfo_t +type resides within +.Vt module_t +and contains module header info. +.El +.Pp +The module subsystem is protected by the global +.Va kernconfig_mutex . +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn MODULE "class" "name" "required" +The +.Fn MODULE +macro creates and initializes a +.Vt modinfo_t +structure. +The +.Fa class +argument identifies the class of module, and must be one of the following +(note that +.Dv MODULE_CLASS_ANY +should not be used here): +.Bl -tag -width MODULE_CLASS_SECMODEL -offset indent +.It Dv MODULE_CLASS_VFS +The module provide a virtual file system - see +.Xr vfs 9 +.It Dv MODULE_CLASS_DRIVER +The module is a device driver - see +.Xr driver 9 +.It Dv MODULE_CLASS_EXEC +The module provides an alternate execution environment - see the various +.Dv COMPAT_xxx +options in +.Xr options 4 +.It Dv MODULE_CLASS_SECMODEL +The module provides a security model - see +.Xr secmodel 9 +.It Dv MODULE_CLASS_BUFQ +The module provides a buffer queue strategy - see +.Xr bufq 9 +.It Dv MODULE_CLASS_MISC +The module provides miscellaneous kernel services +.El +.Pp +The +.Fa name +argument provides the name of the module. +Loaded modules, including those that are built-in to the kernel, must all +have unique names. +.Pp +The +.Fa required +argument is a quoted string containing a comma-separated list of module +names that are required by this module. +The list must not contain any white-space. +When a module is loaded, all of its required modules are auto-loaded and +initialized before the module itself is loaded. +Loading of required modules is a recursive operation. +.Pp +If there are no required modules, this argument should be specified as +.Dv NULL . +.Pp +In addition to the explicit arguments, the +.Fn MODULE +macro creates a reference to the module's +.Fn modcmd +function. +This function is defined as: +.Bl -tag -width modcmd -offset indent +.It Ft int +.Fn xxx_modcmd "modcmd_t cmd" "void *data" +.El +.Pp +(where xxx is the name of the module, from the +.Dv MODULE +macro). +.Pp +The +.Fa cmd +argument requests one of the following operations: +.Bl -tag -width MODULE_CMD_AUTOUNLOAD -offset indent +.It Dv MODULE_CMD_INIT +Perform module-specific initialization when the module is loaded. +.It Dv MODULE_CMD_FINI +Perform module-specific clean-up before the module is unloaded. +.It Dv MODULE_CMD_AUTOUNLOAD +Notify the module that it is about to be unloaded. +.It Dv MODULE_CMD_STAT +Request the module to provide status information (not currently implemented). +.El +.Pp +All modules' +.Fn modcmd +functions must implement the +.Dv MODULE_CMD_INIT +and +.Dv MODULE_CMD_FINI +commands. +The other commands are optional, +and should return +.Er ENOTTY +if not implemented. +.Pp +For the +.Dv MODULE_CMD_INIT +command, the +.Fa data +argument is used to pass a pointer to the module's +.Xr prop_dictionary 3 . +For the +.Dv MODULE_CMD_STAT +command, the +.Fa data +argument points to a buffer where the status information should be placed. +.Pp +The __link_set mechanism is used to enable the +.Nm +subsystem to locate the +.Vt modinfo_t +structure. +.It Fn module_load "name" "flags" "props" "class" +Load a module, link it into the running kernel, and call the module's +.Fn modcmd +routine with a +.Fa cmd +argument of +.Dv MODULE_CMD_INIT . +If the specified module requires other modules, they are loaded first; if +any required module cannot be loaded or if any of their +.Fn modcmd +control routines returns a non-zero status, loading of this module and +the specific required module will fail. +The required modules are marked for automatic unloading. +Thus, if the loading of the module failed, the required modules will +be automatically unloaded after a short delay. +.Pp +The loader will look first for a built-in module with the specified +.Fa name +that has not been disabled (see +.Fn module_unload +below). +If a built-in module with that +.Fa name +is not found, the list of modules prepared by the boot loader is searched. +If the named module is still not found, an attempt is made to locate the +module within the file system, provided it has been mounted by the +initialization code. +.Pp +The +.Fa flags +argument can include: +.Bl -tag -width MODCTL_LOAD_FORCE -offset indent +.It Dv MODCTL_NO_PROP +When loading a module from the file system, do not attempt to locate a +corresponding prop_dictionary file. +.It Dv MODCTL_LOAD_FORCE +Force loading of disabled built-in modules and modules built for a +different version of the operating system. +.El +.Pp +The +.Fa props +argument points to an externalized property list which is passed to the +module's +.Fn modcmd +routine. +If a module is being loaded from the file system, and the +.Dv MODCTL_NO_PROP +flag is not set, the system searches for a file with the same name as the +module file, but with the suffix +.Dq Pa .plist . +If this file is found, the prop_dictionary it contains is loaded and +merged with the prop_dictionary from the +.Fa props +argument. +.Pp +The +.Fa class +argument can be any of: +.Pp +.Bl -tag -width MODULE_CLASS_SECMODEL -offset indent -compact +.It Dv MODULE_CLASS_ANY +.It Dv MODULE_CLASS_DRIVER +Device driver +.It Dv MODULE_CLASS_EXEC +Executable image handler +.It Dv MODULE_CLASS_MISC +Miscellaneous module +.It Dv MODULE_CLASS_SECMODEL +Security model (see +.Xr secmodel 9 +for more details) +.It Dv MODULE_CLASS_VFS +Virtual file system +.El +.Pp +If the class is not +.Dv MODULE_CLASS_ANY , +the class of the module being loaded +must match the requested +.Fa class . +Except when verifying a module's class when it is being loaded, module +classes other than +.Dv MODULE_CLASS_SECMODEL +are transparent to the module subsystem. +They are provided only for the benefit of the subsystem's clients. +Modules with class +.Dv MODULE_CLASS_SECMODEL +are automatically registered with +.Fn secmodel_register +after being successfully loaded, and automatically deregistered with +.Fn secmodel_deregister +when being unloaded. +.Pp +The +.Fn module_load +routine is primarily intended as the implementation of the +.Dv MODCTL_LOAD +option of the +.Xr modctl 2 +system call. +.It Fn module_autoload "name" "class" +Auto-load a module, making it available for automatic unloading. +The +.Fa name +and +.Fa class +arguments are the same as for the +.Fn module_load +routine. +.Pp +The module subsystem uses a kernel thread to attempt to automatically +unload modules a short time (currently, 10 seconds) after being loaded by +.Fn module_autoload . +Before the module is unloaded by this thread, its +.Fn modcmd +is called with the +.Fa cmd +argument specified as +.Dv MODULE_CMD_AUTOUNLOAD . +A module can prevent itself from being unloaded by returning a non-zero +value. +Exception: If +.Li kern.module.autounload_unsafe +is set, a module that returns +.Er ENOTTY , +meaning it does not understand the command, may still be autounloaded. +.Pp +The +.Fn module_autoload +function is intended for use by kernel components to locate and load optional +system components. +The function is also used to load modules that are required by other modules. +.Pp +The directory from which the module is loaded will be searched for a file +with the same name as the module file, but with the suffix +.Dq Pa .plist . +If this file is found, the prop_dictionary it contains will be loaded and +passed to the module's +.Fn modcmd +routine. +If this prop_dictionary contains a +.Dq Pa noautoload +property which is set to +.Dq Pa true +then the system will refuse to load the module. +.It Fn module_unload "name" +Unload a module. +If the module's reference count is non-zero, the function returns +.Er EBUSY . +Otherwise, the module's +.Fn modcmd +routine is called with a +.Fa cmd +argument of +.Dv MODULE_CMD_FINI . +If the +.Fn modcmd +routine returns with an error, then the error is returned to the caller +otherwise the module is unloaded. +.Pp +The reference counts of all modules that were required by this module are +decremented, but the required modules are not unloaded by the call to +.Fn module_unload . +Instead, the required modules may be unloaded by subsequent calls to +.Fn module_unload . +.Pp +Unloading a built-in module causes the module to be marked as disabled. +This prevents the module from being re-loaded, except by the +.Fn module_load +function with the +.Fa flags +argument set to +.Dv MODULE_FORCE_LOAD . +.Pp +The +.Fn module_unload +function may be called by the +.Xr modctl 2 +system call, by the module subsystem's internal auto-unload thread, or by +other kernel facilities. +Generally, other kernel facilities should not be calling this function. +.It Fn module_init_class "class" +Load and initialize all available modules of the specified +.Fa class . +Any built-in modules that have not been disabled, and any modules provided +by the boot loader are loaded. +.It Fn module_hold "module" +Increment the reference count of a module. +A module cannot be unloaded if its reference count is non-zero. +.It Fn module_rele "module" +Decrement the reference count of a module. +.It Fn module_find_section "name" "addr" "size" +Find the start address and size of linker section +.Ar name +within a module. +The miniroot module uses this routine to find the address and size of the +embedded file system image. +This routine can only examine the linker data for the module that is +currently being initialized; it cannot examine data for any other module. +.It Fn module_kernel "void" +Returns a pointer to a +.Ft module_t +structure describing the kernel module. +.It Fn module_name module +Returns a pointer to the module's name. +.It Fn module_source module +Returns the source of the module, one of +.Dv MODULE_SOURCE_KERNEL , +.Dv MODULE_SOURCE_BOOT , +or +.Dv MODULE_SOURCE_FILESYS . +.It Fn module_init "void" +Initialize the module subsystem. +Creates and initializes various data structures, locates all built-in +modules, and establishes the sub-system's +.Xr sysctl 8 +tree. +.Fn module_init +is called early in system initialization to facilitate use of security model +modules. +.It Fn module_start_unload_thread "void" +Create the thread that attempts to automatically unload modules that were +loaded via the +.Fn module_autoload +routine. +The function is called only once, +after the scheduler and timer functions are initialized. +.It Fn module_builtin_require_force "void" +Mark as "disabled" any built-in modules that have not been successfully +initialized. +Modules marked "disabled" can only be loaded if the +.Dv MODCTL_LOAD_FORCE +is specified. +.Fn module_builtin_require_force +is called near the end of system initialization, after the +.Xr init 8 +process is created. +.It Fn module_load_vfs_init "void" +The module subsystem is initialized early, long before any file systems +are available. +After the root file system is mounted, +.Fn module_load_vfs_init "void" +is used to enable loading modules from the file system. +Until this routine is called, modules can only be loaded if they were +built-in to the kernel image or provided by the boot loader. +.It Fn module_register_callbacks "void (*load)(struct module *)" \ +"void (*unload)(struct module *)" +Register a new set of callbacks. +The +.Fa load +callback is invoked after any module (including this module) is +successfully loaded; the +.Fa unload +callback is invoked before any module is unloaded. +Each load or unload event can result in multiple invocations of the +callback routines. +An opaque cookie is returned which can be passed to +.Fn module_unregister_callbacks . +.It Fn module_unregister_callbacks "void *opaque" +Unregister a set of callback routines previously registered with +.Fn module_register_callbacks . +The +.Fa opaque +argument should be the return value from the previous +.Fn module_register_callbacks +call. +.It Fn module_specific_key_create "specificdata_key_t *keyp" \ +"specificdata_dtor_t dtor" +Creates a new specificdata_key for use within the +.Nm +domain. +The key identifier is returned in +.Fa keyp . +.It Fn module_specific_key_delete "specificdata_key_t key" +Deletes the specified specificdata_key +.Fa key +from the +.Nm +domain. +.It Fn module_getspecific "module_t *mod" "specificdata_key_t key" +Retrieves the value associated with +.Fa key +from module +.Fa mod . +.It Fn module_setspecific "module_t *mod" "specificdata_key_t key" "void *data" +Stores +.Fa data +as the value associated with +.Fa key +for module +.Fa mod . +.El +.Sh PROGRAMMING CONSIDERATIONS +The module subsystem is designed to be called recursively, but only within +a single LWP. +This permits one module's +.Fn modcmd +routine to load or unload other modules. +.Pp +Additional considerations: +.Bl -bullet -offset indent +.It +A module is not permitted to load or unload itself. +Attempts to load or unload a module from within its own +.Fn modcmd +routine will fail with +.Er EEXIST +or +.Er EBUSY , +respectively. +.It +Although a module can be loaded by using either +.Fn module_load +or +.Fn module_autoload , +it is not possible for the module's +.Fn modcmd +routine to distinguish between the two methods. +Any module which needs to ensure that it does not get auto-unloaded must +either handle the +.Dv MODULE_CMD_AUTOUNLOAD +command in its +.Fn modcmd +routine, or use +.Fn module_hold +to increment its reference count. +Note however that modules loaded manually with +.Xr modload 8 +are never auto-unloaded. +.El +.Sh EXAMPLES +A set of example modules is available in the +.Pa src/sys/modules/examples +directory hierarchy. +.Sh CODE REFERENCES +The core of the kernel module implementation is in +.Pa sys/kern/kern_module.c +and +.Pa sys/kern/kern_module_vfs.c . +.Pp +The routines for linking the module are in +.Pa sys/kern/subr_kobj.c . +.Pp +The routines for reading a module from the file system are in +.Pa sys/kern/subr_kobj_vfs.c . +.Pp +The header file +.In sys/sys/module.h +describes the public interface. +.Pp +In addition, each architecture is expected to provide +.Fn kobj_machdep , +.Fn kobj_reloc , +and +.Fn module_init_md . +.Fn kobj_machdep +is for any machine dependent actions, such as flushing caches, that are +needed when a module is loaded or unloaded. +.Fn kobj_reloc +deals with resolution of relocatable symbols. +.Fn module_init_md +is for finding modules passed in by the boot loader. +.Sh SEE ALSO +.Xr modctl 2 , +.Xr module 7 , +.Xr specificdata 9 , +.Xr intro 9lua +.Sh HISTORY +The kernel module subsystem first appeared in +.Nx 5.0 . +It replaces the +.Dq LKM +subsystem from earlier releases. +.Sh AUTHORS +.An -nosplit +The +.Nm +system was written by +.An Andrew Doran Aq Mt ad@NetBSD.org . +This manual page was written by +.An Paul Goyette Aq Mt pgoyette@NetBSD.org . diff --git a/static/netbsd/man9/mstohz.9 b/static/netbsd/man9/mstohz.9 new file mode 100644 index 00000000..9c0665f5 --- /dev/null +++ b/static/netbsd/man9/mstohz.9 @@ -0,0 +1,75 @@ +.\" $NetBSD: mstohz.9,v 1.12 2019/09/28 15:11:19 christos Exp $ +.\" +.\" Copyright (c) 2002 Manuel Bouyer. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd September 28, 2019 +.Dt MSTOHZ 9 +.Os +.Sh NAME +.Nm mstohz , +.Nm hztoms +.Nd convert between milliseconds and system clock ticks +.Sh SYNOPSIS +.In sys/param.h +.Ft unsigned int +.Fn mstohz "unsigned int ms" +.Ft unsigned int +.Fn hztoms "unsigned int hz" +.Sh DESCRIPTION +The +.Fn mstohz +macro can be used to convert time +in milliseconds to system clock ticks, as used +by the +.Xr callout 9 +facility, in an integer-overflow safe way. +Conversely, +.Fn hztoms +converts system clock ticks to milliseconds. +.Pp +These macros are defined in the +.Aq Em sys/param.h +header. +Individual ports can have a processor-specific, more efficient +version implemented in their +.Aq Em machine/param.h +header as a define. +.Sh RETURN VALUES +The return value is either the number of clock ticks or milliseconds +for the specified value. +.Sh SEE ALSO +.Xr param 3 , +.Xr callout 9 , +.Xr tvtohz 9 +.Sh BUGS +Neither +.Fn mstohz +nor +.Fn hztoms +make use of expensive 64-bit integer arithmetic. +The result from +.Fn mstohz +will be rounded down to one second if the parameter is larger +than 131072 milliseconds. diff --git a/static/netbsd/man9/mutex.9 b/static/netbsd/man9/mutex.9 new file mode 100644 index 00000000..63c0cfde --- /dev/null +++ b/static/netbsd/man9/mutex.9 @@ -0,0 +1,319 @@ +.\" $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. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Andrew Doran. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 8, 2017 +.Dt MUTEX 9 +.Os +.Sh NAME +.Nm mutex , +.Nm mutex_init , +.Nm mutex_destroy , +.Nm mutex_enter , +.Nm mutex_exit , +.Nm mutex_ownable , +.Nm mutex_owned , +.Nm mutex_spin_enter , +.Nm mutex_spin_exit , +.Nm mutex_tryenter +.Nd mutual exclusion primitives +.Sh SYNOPSIS +.In sys/mutex.h +.Ft void +.Fn mutex_init "kmutex_t *mtx" "kmutex_type_t type" "int ipl" +.Ft void +.Fn mutex_destroy "kmutex_t *mtx" +.Ft void +.Fn mutex_enter "kmutex_t *mtx" +.Ft void +.Fn mutex_exit "kmutex_t *mtx" +.Ft int +.Fn mutex_ownable "kmutex_t *mtx" +.Ft int +.Fn mutex_owned "kmutex_t *mtx" +.Ft void +.Fn mutex_spin_enter "kmutex_t *mtx" +.Ft void +.Fn mutex_spin_exit "kmutex_t *mtx" +.Ft int +.Fn mutex_tryenter "kmutex_t *mtx" +.Pp +.Cd "options DIAGNOSTIC" +.Cd "options LOCKDEBUG" +.Sh DESCRIPTION +Mutexes are used in the kernel to implement mutual exclusion among LWPs +.Pq lightweight processes +and interrupt handlers. +.Pp +The +.Vt kmutex_t +type provides storage for the mutex object. +This should be treated as an opaque object and not examined directly by +consumers. +.Pp +Mutexes replace the +.Xr spl 9 +system traditionally used to provide synchronization between interrupt +handlers and LWPs. +.Sh OPTIONS +The following kernel options have effect on mutex operations: +.Bl -tag -width Cd +.It Cd "options DIAGNOSTIC" +Kernels compiled with the +.Dv DIAGNOSTIC +option perform basic sanity checks on mutex operations. +.It Cd "options LOCKDEBUG" +Kernels compiled with the +.Dv LOCKDEBUG +option perform potentially CPU intensive sanity checks +on mutex operations. +.El +.Sh FUNCTIONS +.Bl -tag -width Ds +.It Fn mutex_init "mtx" "type" "ipl" +Dynamically initialize a mutex for use. +.Pp +No other operations can be performed on a mutex until it has been initialized. +Once initialized, all types of mutex are manipulated using the same interface. +Note that +.Fn mutex_init +may block in order to allocate memory. +.Pp +The +.Fa type +argument must be given as +.Dv MUTEX_DEFAULT . +Other constants are defined but are for low-level system use and are not +an endorsed, stable part of the interface. +.Pp +The type of mutex returned depends on the +.Fa ipl +argument: +.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. +.Pp +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 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. +.Pp +The +.Fa ipl +argument is used to pass a system interrupt priority level (IPL) +that will block all interrupt handlers that may try to acquire the mutex. +.Pp +LWPs that own spin mutexes may not sleep, and therefore must not +try to acquire adaptive mutexes or other sleep locks. +.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 +.Xr spl 9 +for further information on interrupt priority levels (IPLs). +.It Fn mutex_destroy "mtx" +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" +Acquire a mutex. +If the mutex is already held, the caller will block and not return until the +mutex is acquired. +.Pp +All loads and stores after +.Fn mutex_enter +will not be reordered before it or served from a prior cache, and hence +will +.Em happen after +any prior +.Fn mutex_exit +to release the mutex even on another CPU or in an interrupt. +Thus, there is a global total ordering on all loads and stores under +the same mutex. +.Pp +Mutexes and other types of locks must always be acquired in a +consistent order with respect to each other. +Otherwise, the potential for system deadlock exists. +.Pp +Adaptive mutexes and other types of lock that can sleep may +not be acquired while a spin mutex is held by the caller. +.Pp +When acquiring a spin mutex, the IPL of the current CPU will be raised to +the level set in +.Fn mutex_init +if it is not already equal or higher. +.It Fn mutex_exit "mtx" +Release a mutex. +The mutex must have been previously acquired by the caller. +Mutexes may be released out of order as needed. +.Pp +All loads and stores before +.Fn mutex_exit +will not be reordered after it or delayed in a write buffer, and hence +will +.Em happen before +any subsequent +.Fn mutex_enter +to acquire the mutex even on another CPU or in an interrupt. +Thus, there is a global total ordering on all loads and stores under +the same mutex. +.It Fn mutex_ownable "mtx" +When compiled with +.Dv LOCKDEBUG +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 +.Dq locking against myself\^ +error. +.Pp +This function is needed because +.Fn mutex_owned +does not differentiate if a spin mutex is owned by the current process +vs owned by another process. +.Fn mutex_ownable +is reasonably heavy-weight, and should only be used with +.Xr KDASSERT 9 . +.It Fn mutex_owned "mtx" +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. +Otherwise, return zero. +.Pp +.Fn mutex_owned +is provided for making diagnostic checks to verify that a lock is held. +For example: +.Dl KASSERT(mutex_owned(&driver_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" +Equivalent to +.Fn mutex_enter , +but may only be used when it is known that +.Ar mtx +is a spin mutex. +Implies the same memory ordering as +.Fn mutex_enter . +On some architectures, this can substantially reduce the cost of acquiring +a spin mutex. +.It Fn mutex_spin_exit "mtx" +Equivalent to +.Fn mutex_exit , +but may only be used when it is known that +.Ar mtx +is a spin mutex. +Implies the same memory ordering as +.Fn mutex_exit . +On some architectures, this can substantially reduce the cost of releasing +a spin mutex. +.It Fn mutex_tryenter "mtx" +Try to acquire a mutex, but do not block if the mutex is already held. +Returns non-zero if the mutex was acquired, or zero if the mutex was +already held. +.Pp +.Fn mutex_tryenter +can be used as an optimization when acquiring locks in the wrong order. +For example, in a setting where the convention is that +.Va first_lock +must be acquired before +.Va second_lock , +the following can be used to optimistically lock in reverse order: +.Bd -literal -offset indent +/* We hold second_lock, but not first_lock. */ +KASSERT(mutex_owned(&second_lock)); + +if (!mutex_tryenter(&first_lock)) { + /* Failed to get it - lock in the correct order. */ + mutex_exit(&second_lock); + mutex_enter(&first_lock); + mutex_enter(&second_lock); + + /* + * We may need to recheck any conditions the code + * path depends on, as we released second_lock + * briefly. + */ +} +.Ed +.El +.Sh CODE REFERENCES +The core of the mutex implementation is in +.Pa sys/kern/kern_mutex.c . +.Pp +The header file +.Pa sys/sys/mutex.h +describes the public interface, and interfaces that machine-dependent +code must provide to support mutexes. +.Sh SEE ALSO +.Xr atomic_ops 3 , +.Xr membar_ops 3 , +.Xr options 4 , +.Xr lockstat 8 , +.Xr condvar 9 , +.Xr kpreempt 9 , +.Xr rwlock 9 , +.Xr spl 9 +.Pp +.Rs +.%A Jim Mauro +.%A Richard McDougall +.%T Solaris Internals: Core Kernel Architecture +.%I Prentice Hall +.%D 2001 +.%O ISBN 0-13-022496-0 +.Re +.Sh HISTORY +The mutex primitives first appeared in +.Nx 5.0 . +.Fn mutex_ownable +first appeared in +.Nx 8.0 . diff --git a/static/netbsd/man9/namecache.9 b/static/netbsd/man9/namecache.9 new file mode 100644 index 00000000..7abed5aa --- /dev/null +++ b/static/netbsd/man9/namecache.9 @@ -0,0 +1,262 @@ +.\" $NetBSD: namecache.9,v 1.21 2017/04/19 11:33:01 abhinav Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 7, 2014 +.Dt NAMECACHE 9 +.Os +.Sh NAME +.Nm namecache , +.Nm cache_lookup , +.Nm cache_revlookup , +.Nm cache_enter , +.Nm cache_purge , +.Nm cache_purgevfs , +.Nm namecache_print +.Nd name lookup cache +.Sh SYNOPSIS +.In sys/namei.h +.In sys/proc.h +.In sys/uio.h +.In sys/vnode.h +.Ft int +.Fn cache_lookup "struct vnode *dvp" "const char *name" "size_t namelen" \ +"uint32_t nameiop" "uint32_t nameiflags" "int *iswhiteout" "struct vnode **vpp" +.Ft int +.Fn cache_revlookup "struct vnode *vp" "struct vnode *dvp" \ +"char **bpp" "char *bufp" +.Ft void +.Fn cache_enter "struct vnode *dvp" "struct vnode *vp" \ +"const char *name" "size_t namelen" "uint32_t nameiflags" +.Ft void +.Fn cache_purge "struct vnode *vp" +.Ft void +.Fn cache_purgevfs "struct mount *mp" +.Ft void +.Fn namecache_print "struct vnode *vp" "void (*func)(const char *, ...)" +.Sh DESCRIPTION +The name lookup cache is the mechanism to allow the file system type +dependent algorithms to quickly resolve a file's vnode from its +pathname. +The name lookup cache is generally accessed through the higher-level +.Xr namei 9 +interface. +.Pp +The name of the file is used to look up an entry associated with the +file in the name lookup cache. +If no entry is found, one is created for it. +If an entry is found, the information obtained from the cache lookup +contains information about the file which is useful to the file system +type dependent functions. +.Pp +The name lookup cache is managed by a least recently used (LRU) +algorithm so frequently used names will hang around. +The cache itself is a hash table called +.Va nchashtbl , +containing +.Em namecache +entries that are allocated dynamically from a kernel memory pool. +Each entry has the following structure: +.Bd -literal +#define NCHNAMLEN 31 /* maximum name segment length */ +struct namecache { + LIST_ENTRY(namecache) nc_hash; /* hash chain */ + TAILQ_ENTRY(namecache) nc_lru; /* LRU chain */ + LIST_ENTRY(namecache) nc_vhash; /* directory hash chain */ + LIST_ENTRY(namecache) nc_dvlist; + struct vnode *nc_dvp; /* vnode of parent of name */ + LIST_ENTRY(namecache) nc_vlist; + struct vnode *nc_vp; /* vnode the name refers to */ + int nc_flags; /* copy of componentname's ISWHITEOUT */ + char nc_nlen; /* length of name */ + char nc_name[NCHNAMLEN]; /* segment name */ +}; +.Ed +.Pp +For simplicity (and economy of storage), names longer than a maximum +length of NCHNAMLEN are not cached; they occur infrequently in any +case, and are almost never of interest. +.Pp +Each +.Em namecache +entry can appear on two hash chains in addition to +.Va nchashtbl : +.Em ncvhashtbl +(the name cache directory hash chain), and +.Em nclruhead +(the name cache LRU chain). +The hash chains are indexed by a hash value obtained from the file's +name and the address of its parent directory vnode. +.Pp +Functions which access to the name cache pass arguments in the +partially initialised +.Em componentname +structure. +See +.Xr vnodeops 9 +for details on this structure. +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn cache_lookup "dvp" "name" "namelen" "nameiop" "nameiflags" \ +"iswhiteout" "vpp" +Look for a name in the cache. +.Fn cache_lookup +is called with +.Fa dvp +pointing to the vnode of the directory to search. +The +.Fa name +and +.Fa namelen +arguments specify the name to look for. +The +.Fa nameiop +and +.Fa nameiflags +should be taken from the +.Fa cn_nameiop +and +.Fa cn_flags +fields of struct componentname. +.Pp +The lookup can produce either a cache miss or a cache hit, and a cache +hit can either be a positive hit, where the name looked up refers to +some existing object, or a negative hit, where the name looked up is +known to refer to +.Em no +existing object. +(The lookup cannot fail, in the sense of generating an error condition +that requires aborting the operation in progress.) +.Pp +On a cache miss, +.Fn cache_lookup +returns zero +.Pq false . +On a positive hit, the unlocked vnode for the object found is stored in +.Fa vpp , +and a nonzero +.Pq true +value is returned. +On a negative hit, +.Fa vpp +is set to contain a null pointer and a nonzero value is returned. +Usually a negative hit will prompt the caller to fail with +.Er ENOENT . +.Pp +The +.Fa iswhiteout +argument is a pointer to an integer result that will be set to nonzero if +the entry represents a whiteout, and zero if it does not. +This pointer may be +.Dv NULL +if the caller does not support whiteouts. +According to the current scheme for handling whiteouts, if +.Fn cache_lookup +sets +.Fa iswhiteout +the caller should add +.Dv ISWHITEOUT +to the +.Fa cn_flags +field of its struct componentname. +.It Fn cache_revlookup "vp" "dvp" "bpp" "bufp" +Scan cache looking for name of directory entry pointing at +.Fa vp +and fill in +.Fa dvpp . +If +.Fa bufp +is +.Pf non- Dv NULL , +also place the name in the buffer which starts at +.Fa bufp , +immediately before +.Fa bpp , +and move bpp backwards to point at the start of it. +If the lookup succeeds, the vnode is referenced. +Returns 0 on success, -1 on cache miss, positive errno on failure. +.It Fn cache_enter "dvp" "vp" "name" "namelen" "nameiflags" +Add an entry to the cache. +The +.Fa name +and +.Fa namelen +arguments specify the name to add to the cache. +The +.Fa dvp +argument specifies the directory the name appears in. +The +.Fa vp +argument specifies the object to enter in the cache. +The +.Fa nameiflags +argument should come from the +.Fa cn_flags +member of struct componentname. +.Pp +If +.Fa vp +is +.Dv NULL , +a negative cache entry is created, specifying that the entry +does not exist in the file system. +.It Fn cache_purge "vp" +Flush the cache of a particular vnode +.Fa vp . +.Fn cache_purge +is called when a vnode is renamed to hide entries that would now be +invalid. +.It Fn cache_purgevfs "mp" +Flush cache of a whole file system +.Fa mp . +.Fn cache_purgevfs +is called when file system is unmounted to remove entries that would +now be invalid. +.It Fn namecache_print "vp" "func" +Print all entries of the name cache. +.Fa func +is the +.Xr printf 9 +format. +.Fn namecache_print +is only defined if the kernel option DDB is compiled into the kernel. +.El +.Sh CODE REFERENCES +The name lookup cache is implemented within the file +.Pa sys/kern/vfs_cache.c . +.Sh SEE ALSO +.Xr intro 9 , +.Xr namei 9 , +.Xr vfs 9 , +.Xr vnode 9 +.Sh HISTORY +The name lookup cache first appeared in +.Bx 4.2 . +.Sh AUTHORS +The original name lookup cache was written by +.An Robert Elz . diff --git a/static/netbsd/man9/namei.9 b/static/netbsd/man9/namei.9 new file mode 100644 index 00000000..c1a86853 --- /dev/null +++ b/static/netbsd/man9/namei.9 @@ -0,0 +1,966 @@ +.\" $NetBSD: namei.9,v 1.52 2021/12/26 16:41:09 andvar Exp $ +.\" +.\" Copyright (c) 2001, 2005, 2006, 2017 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 5, 2019 +.Dt NAMEI 9 +.Os +.Sh NAME +.Nm namei , +.Nm NDINIT , +.Nm NDAT , +.Nm namei_simple_kernel , +.Nm namei_simple_user , +.Nm relookup , +.Nm lookup_for_nfsd , +.Nm lookup_for_nfsd_index +.Nd pathname lookup +.Sh SYNOPSIS +.In sys/namei.h +.In sys/uio.h +.In sys/vnode.h +.Fn NDINIT "struct nameidata *ndp" "u_long op" "u_long flags" \ +"struct pathbuf *pathbuf" +.Fn NDAT "struct nameidata *ndp" "struct vnode *dvp" +.Ft int +.Fn namei "struct nameidata *ndp" +.Ft int +.Fn namei_simple_kernel "const char *path" "namei_simple_flags_t sflags" \ +"struct vnode **ret" +.Ft int +.Fn namei_simple_user "const char *path" "namei_simple_flags_t sflags" \ +"struct vnode **ret" +.Ft int +.Fn relookup "struct vnode *dvp" "struct vnode **vpp" \ +"struct componentname *cnp" "int dummy" +.Ft int +.Fn lookup_for_nfsd "struct nameidata *ndp" "struct vnode *startdir" \ +"int neverfollow" +.Ft int +.Fn lookup_for_nfsd_index "struct nameidata *ndp" "struct vnode *startdir" +.Sh DESCRIPTION +The +.Nm +interface is used to convert pathnames to file system vnodes. +The +name of the interface is actually a contraction of the words +.Em name +and +.Em inode +for name-to-inode conversion, in the days before the +.Xr vfs 9 +interface was implemented. +.Pp +All access to the +.Nm +interface must be in process context. +Pathname lookups cannot be done in interrupt context. +.Pp +In the general form of +.Nm , +a caller must: +.Bl -enum -compact +.It +Allocate storage for a +.Ft struct nameidata +object +.Fa nd . +.It +Initialize +.Fa nd +with +.Fn NDINIT +and optionally +.Fn NDAT +to specify the arguments to a lookup. +.It +Call +.Fn namei +and handle failure if it returns a nonzero error code. +.It +Read the resulting vnode out of +.Fa nd Ns Li .ni_vp . +If requested with +.Dv LOCKPARENT , +read the directory vnode out of +.Fa nd Ns Li .ni_dvp . +.It +For directory operations, use the +.Ft struct componentname +object stored at +.Fa nd Ns Li .ni_cnd . +.El +.Pp +The other fields of +.Ft struct nameidata +should not be examined or altered directly. +.Pp +Note that the +.Xr nfs 4 +code misuses +.Ft struct nameidata +and currently has an incestuous relationship with the +.Nm +code. +This is gradually being cleaned up. +.Pp +The +.Ft struct componentname +type has the following layout: +.Bd -literal +struct componentname { + /* + * Arguments to VOP_LOOKUP and directory VOP routines. + */ + uint32_t cn_nameiop; /* namei operation */ + uint32_t cn_flags; /* flags to namei */ + kauth_cred_t cn_cred; /* credentials */ + const char *cn_nameptr; /* pointer to looked up name */ + size_t cn_namelen; /* length of looked up comp */ + /* + * Side result from VOP_LOOKUP. + */ + size_t cn_consume; /* chars to consume in lookup */ +}; +.Ed +.Pp +This structure contains the information about a single directory +component name, along with certain other information required by vnode +operations. +See +.Xr vnodeops 9 +for more information about these vnode operations. +.Pp +The members: +.Bl -tag -offset indent -width cn_consumexx -compact +.It cn_nameiop +The type of operation in progress; indicates the basic operating mode +of namei. +May be one of +.Dv LOOKUP , +.Dv CREATE , +.Dv DELETE , +or +.Dv RENAME . +These modes are described below. +.It cn_flags +Additional flags affecting the operation of namei. +These are described below as well. +.It cn_cred +The credentials to use for the lookup or other operation the +.Em componentname +is passed to. +This may match the credentials of the current process or it may not, +depending on where the original operation request came from and how it +has been routed. +.It cn_nameptr +The name of this directory component, followed by the rest of the path +being looked up. +.It cn_namelen +The length of the name of this directory component. +The name is not in general null terminated, although the complete +string (the full remaining path) always is. +.It cn_consume +This field starts at zero; it may be set to a larger value by +implementations of +.Xr VOP_LOOKUP 9 +to indicate how many more characters beyond +.Em cn_namelen +are being consumed. +New uses of this feature are discouraged and should be discussed. +.El +.Ss Operating modes +Each lookup happens in one of the following modes, specified by +callers of +.Nm +with +.Fn NDINIT +and specified internally by +.Nm +to +.Xr VOP_LOOKUP 9 : +.Bl -bullet -compact +.It +Callers of +.Nm +specify the mode for the last component of a lookup. +.It +Internally, +.Nm +recursively calls +.Xr VOP_LOOKUP 9 +in +.Dv LOOKUP +mode for each directory component, and then finally calls +.Xr VOP_LOOKUP 9 +in the caller-specified mode for the last component. +.El +Each mode can fail in different ways \(em for example, +.Dv LOOKUP +mode fails with +.Er ENOENT +if no entry exists, but +.Dv CREATE +mode succeeds with a +.Dv NULL +vnode. +.Bl -tag -width LOOKUP +.It Dv LOOKUP +Yield the vnode for an existing entry. +Callers specify +.Dv LOOKUP +for operations on existing vnodes: +.Xr stat 2 , +.Xr open 2 +without +.Dv O_CREATE , +etc. +.Pp +File systems: +.Bl -dash -compact +.It +MUST refuse if user lacks lookup permission for directory. +.It +SHOULD use +.Xr namecache 9 +to cache lookup results. +.El +.Pp +.Bl -tag -compact -width ENAMETOOLONG +.It Bq Er ENOENT +No entry exists. +.El +.It Dv CREATE +Yield the vnode for an existing entry; or, if there is none, yield +.Dv NULL +and hint that it will soon be created. +Callers specify +.Dv CREATE +for operations that may create directory entries: +.Xr mkdir 2 , +.Xr open 2 +with +.Dv O_CREATE , +etc. +.Pp +File systems: +.Bl -dash -compact +.It +MUST refuse if user lacks lookup permission for directory. +.It +MUST refuse if no entry exists and user lacks write permission for +directory. +.It +MUST refuse if no entry exists and file system is read-only. +.It +SHOULD NOT use +.Xr namecache 9 +to cache negative lookup results. +.It +SHOULD save lookup hints internally in the directory for a subsequent +operation to create a directory entry. +.El +.Pp +.Bl -tag -compact -width ENAMETOOLONG +.It Bq Er EPERM +The user lacks lookup permission for the directory. +.It Bq Er EPERM +No entry exists and the user lacks write permission for the directory. +.It Bq Er EROFS +No entry exists and the file system is read-only. +.El +.It Dv DELETE +Yield the vnode of an existing entry, and hint that it will soon be +deleted. +Callers specify +.Dv DELETE +for operations that delete directory entries: +.Xr unlink 2 , +.Xr rmdir 2 , +etc. +.Pp +File systems: +.Bl -dash -compact +.It +MUST refuse if user lacks lookup permission for directory. +.It +MUST refuse if entry exists and user lacks write permission for +directory. +.It +MUST refuse if entry exists and file system is read-only. +.It +SHOULD NOT use +.Xr namecache 9 +to cache lookup results. +.It +SHOULD save lookup hints internally in the directory for a subsequent +operation to delete a directory entry. +.El +.Pp +.Bl -tag -compact -width ENAMETOOLONG +.It Bq Er ENOENT +No entry exists. +.It Bq Er EPERM +The user lacks lookup permission for the directory. +.It Bq Er EPERM +An entry exists and the user lacks write permission for the directory. +.It Bq Er EROFS +An entry exists and the file system is read-only. +.El +.It Dv RENAME +Yield the vnode of an existing entry, and hint that it will soon be +overwritten; or, if there is none, yield +.Dv NULL , +and hint that it will soon be created. +.Pp +Callers specify +.Dv RENAME +for an entry that is about to be created or overwritten, namely for the +target of +.Xr rename 2 . +.Pp +File systems: +.Bl -dash -compact +.It +MUST refuse if user lacks lookup permission for directory. +.It +MUST refuse if user lacks write permission for directory. +.It +MUST refuse if file system is read-only. +.It +SHOULD NOT use +.Xr namecache 9 +to cache lookup results. +.It +SHOULD save lookup hints internally in the directory for a subsequent +operation to create or overwrite a directory entry. +.El +.Pp +.Bl -tag -compact -width ENAMETOOLONG +.It Bq Er EPERM +The user lacks lookup permission for the directory. +.It Bq Er EPERM +The user lacks write permission for the directory. +.It Bq Er EROFS +The file system is read-only. +.El +.El +.Pp +If a caller decides not to perform an operation it hinted at by a +destructive operating mode +.Pq Dv CREATE , Dv DELETE , No or Dv RENAME , +it SHOULD call +.Xr VOP_ABORTOP 9 +to release the hints. +If a file system fails to perform such an operation, it SHOULD call +.Xr VOP_ABORTOP 9 +to release the hints. +However, the current code is inconsistent about this, and every +implementation of +.Xr VOP_ABORTOP 9 +does nothing. +.Ss Flags +The following flags may be specified by +.Em callers +of +.Nm , +and MUST NOT be used by file systems: +.Bl -tag -width NOCROSSMOUNT +.It Dv FOLLOW +Follow symbolic links in the last path component. +Used by operations that do not address symbolic links directly, such as +.Xr stat 2 . +(Does not affect symbolic links found in the middle of a path.) +.It Dv NOFOLLOW +Do not follow symbolic links in the last path component. +Used by operations that address symbolic links directly, such as +.Xr lstat 2 . +.Pp +Note: The value of +.Dv NOFOLLOW +is 0. +We define the constant to let callers say either +.Dv FOLLOW +or +.Dv NOFOLLOW +explicitly. +.It Dv LOCKLEAF +On successful lookup, lock the vnode, if any, in +.Fa ndp Ns Li ->ni_vp . +Without this flag, it would be unlocked. +.It Dv LOCKPARENT +On successful lookup, lock and return the directory vnode in +.Fa ndp Ns Li ->ni_dvp . +Without this flag, it is not returned at all. +.It Dv TRYEMULROOT +If set, the path is looked up in the emulation root of the current +process first. +If that fails, the system root is used. +.It Dv EMULROOTSET +Indicates that the caller has set +.Fa ndp Ns Li ->ni_erootdir +prior to calling +.Nm . +This is only useful or permitted when the emulation in the current +process is partway through being set up. +.It Dv NOCHROOT +Bypass normal +.Xr chroot 8 +handling for absolute paths. +.It Dv NOCROSSMOUNT +Do not cross mount points. +.It Dv RDONLY +Enforce read-only behavior. +.It Dv CREATEDIR +Accept slashes after a component name that does not exist. +This only makes sense in +.Dv CREATE +mode and when creating a directory. +.It Dv NOCACHE +Do not cache the lookup result for the last component name. +This is used only with the +.Dv RENAME +mode for the target; the cache entry would be invalidated immediately. +.El +.Pp +The following flag may be set by a caller of +.Nm +and tested by a file system in +.Xr VOP_LOOKUP 9 +or other subsequent directory operations: +.Bl -tag -width NOCROSSMOUNT +.It Dv DOWHITEOUT +Allow whiteouts to be seen as objects instead of functioning as +.Dq nothing there . +.El +.Pp +The following flags are set by namei for calling +.Xr VOP_LOOKUP 9 : +.Bl -tag -width NOCROSSMOUNT +.It Dv ISDOTDOT +The current pathname component is +.Dq Li .. . +May be tested by subsequent directory operations too. +.It Dv ISLASTCN +The current pathname component is the last component found in the +pathname. +Guaranteed to remain set in subsequent directory operations. +.It Dv REQUIREDIR +The current object to be looked up must be a directory. +May not be used by subsequent directory operations. +.It Dv MAKEENTRY +The lookup result for the current pathname component should be added to +the +.Xr namecache 9 . +May be used to make additional caching decisions, e.g. to store an +mtime for determining whether our cache for a remote vnode is stale. +May not be used by subsequent directory operations. +.El +.Pp +A file system may set the following flag on return from +.Xr VOP_LOOKUP 9 +for use by +.Nm , +.Xr namecache 9 , +and subsequent directory operations: +.Bl -tag -width NOCROSSMOUNT +.It Dv ISWHITEOUT +The object at the current pathname component is a whiteout. +.El +.Pp +The following additional historic flags have been removed from +.Nx +and should be handled as follows if porting code from elsewhere: +.Bl -tag -width NOCROSSMOUNT +.It Dv INRENAME +Part of a misbegotten and incorrect locking scheme. +Any file-system-level code using this is presumptively incorrect. +File systems should use the +.Xr genfs_rename 9 +interface to handle locking in +.Fn VOP_RENAME . +.It Dv INRELOOKUP +Used at one point for signaling to +.Xr puffs 3 +to work around a protocol deficiency that was later rectified. +.It Dv ISSYMLINK +Useless internal state. +.It Dv SAVESTART +Unclean setting affect vnode reference counting. +Now effectively never in effect. +Any code referring to this is suspect. +.It Dv SAVENAME +Unclean setting relating to responsibility for freeing pathname buffers +in the days before the +.Em pathbuf +structure. +Now effectively always in effect; the caller of +.Nm +owns the +.Em pathbuf +structure and is always responsible for destroying it. +.It Dv HASBUF +Related to SAVENAME. +Any uses can be replaced with +.Dq true . +.El +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn NDINIT "ndp" "op" "flags" "pathbuf" +Initialise a nameidata structure pointed to by +.Fa ndp +for use by the +.Nm +interface. +The operating mode and flags (as documented above) are specified by +.Fa op +and +.Fa flags +respectively. +The pathname is passed as a pathbuf structure, which should be +initialized using one of the +.Xr pathbuf 9 +operations. +Destroying the pathbuf is the responsibility of the caller; this must +not be done until the caller is finished with all of the +.Nm +results and all of the nameidata contents except for the result vnode. +.Pp +This routine stores the credentials of the calling thread +.Va ( curlwp ) +in +.Fa ndp . +.Fn NDINIT +sets the credentials using +.Xr kauth_cred_get 9 . +In the rare case that another set of credentials is required for the +namei operation, +.Em ndp->ni_cnd.cn_cred +must be set manually after +.Fn NDINIT . +.It Fn NDAT "ndp" "dvp" +This macro is used after +.Fn NDINIT +to set the starting directory. +This supersedes the current process's current working directory as the +initial point of departure for looking up relative paths. +This mechanism is used by +.Xr openat 2 +and related calls. +.It Fn namei "ndp" +Convert a pathname into a pointer to a vnode. +The nameidata structure pointed to by +.Fa ndp +should be initialized with the +.Fn NDINIT +macro, and perhaps also the +.Fn NDAT +macro. +Direct initialization of members of struct nameidata is +.Em not +supported and may (will) break silently in the future. +.Pp +The vnode for the pathname is returned in +.Em ndp->ni_vp . +The parent directory is returned locked in +.Em ndp->ni_dvp +iff +.Dv LOCKPARENT +is specified. +.Pp +Any or all of the flags documented above as set by the caller can be +enabled by passing them (OR'd together) as the +.Fa flags +argument of +.Fn NDINIT . +As discussed above every such call should explicitly contain either +.Dv FOLLOW +or +.Dv NOFOLLOW +to control the behavior regarding final symbolic links. +.It Fn namei_simple_kernel "path" "sflags" "ret" +Look up the path +.Fa path +and translate it to a vnode, returned in +.Fa ret . +The +.Fa path +argument must be a kernel +.Pq Dv UIO_SYSSPACE +pointer. +The +.Fa sflags +argument chooses the precise behavior. +It may be set to one of the following symbols: +.Bl -tag -offset indent -width NSM_NOFOLLOW_TRYEMULROOT -compact +.It Dv NSM_NOFOLLOW_NOEMULROOT +.It Dv NSM_NOFOLLOW_TRYEMULROOT +.It Dv NSM_FOLLOW_NOEMULROOT +.It Dv NSM_FOLLOW_TRYEMULROOT +.El +These select (or not) the +.Dv FOLLOW/NOFOLLOW +and +.Dv TRYEMULROOT +flags. +Other flags are not available through this interface, which is +nonetheless sufficient for more than half the +.Fn namei +usage in the kernel. +Note that the encoding of +.Fa sflags +has deliberately been arranged to be type-incompatible with anything +else. +This prevents various possible accidents while the +.Fn namei +interface is being rototilled. +.It Fn namei_simple_user "path" "sflags" "ret" +This function is the same as +.Fn namei_simple_kernel +except that the +.Fa path +argument shall be a user pointer +.Pq Dv UIO_USERSPACE +rather than a kernel pointer. +.It Fn relookup "dvp" "vpp" "cnp" "dummy" +Reacquire a path name component is a directory. +This is a quicker way to lookup a pathname component when the parent +directory is known. +The locked parent directory vnode is specified by +.Fa dvp +and the pathname component by +.Fa cnp . +The vnode of the pathname is returned in the address specified by +.Fa vpp . +The +.Fa dummy +argument is unused. +Note that one may only use +.Fn relookup +to repeat a lookup of a final path component previously done by +.Nm , +and one must use the same +.Em componentname +structure that call produced. +Otherwise the behavior is undefined and likely adverse. +.It Fn lookup_for_nfsd "ndp" "startdir" "neverfollow" +This is a private entry point into +.Nm +used by the NFS server code. +It looks up a path starting from +.Fa startdir . +If +.Fa neverfollow +is set, +.Em any +symbolic link (not just at the end of the path) will cause an error. +Otherwise, it follows symlinks normally. +It should not be used by new code. +.It Fn lookup_for_nfsd_index "ndp" "startdir" +This is a (second) private entry point into +.Nm +used by the NFS server code. +It looks up a single path component starting from +.Fa startdir . +It should not be used by new code. +.El +.Sh INTERNALS +The +.Em nameidata +structure has the following layout: +.Bd -literal +struct nameidata { + /* + * Arguments to namei. + */ + struct vnode *ni_atdir; /* startup dir, cwd if null */ + struct pathbuf *ni_pathbuf; /* pathname container */ + char *ni_pnbuf; /* extra pathname buffer ref (XXX) */ + /* + * Internal starting state. (But see notes.) + */ + struct vnode *ni_rootdir; /* logical root directory */ + struct vnode *ni_erootdir; /* emulation root directory */ + /* + * Results from namei. + */ + struct vnode *ni_vp; /* vnode of result */ + struct vnode *ni_dvp; /* vnode of intermediate directory */ + /* + * Internal current state. + */ + size_t ni_pathlen; /* remaining chars in path */ + const char *ni_next; /* next location in pathname */ + unsigned int ni_loopcnt; /* count of symlinks encountered */ + /* + * Lookup parameters: this structure describes the subset of + * information from the nameidata structure that is passed + * through the VOP interface. + */ + struct componentname ni_cnd; +}; +.Ed +.Pp +These fields are: +.Bl -tag -offset indent -width ni_erootdirx -compact +.It ni_atdir +The directory to use for the starting point of relative paths. +If null, the current process's current directory is used. +This is initialized to +.Dv NULL +by +.Fn NDINIT +and set by +.Fn NDAT . +.It ni_pathbuf +The abstract path buffer in use, passed as an argument to +.Fn NDINIT . +The name pointers that appear elsewhere, such as in the +.Em componentname +structure, point into this buffer. +It is owned by the caller and must not be destroyed until all +.Nm +operations are complete. +See +.Xr pathbuf 9 . +.It ni_pnbuf +This is the name pointer used during +.Nm . +It points into +.Fa ni_pathbuf . +It is not initialized until entry into +.Nm . +.It ni_rootdir +The root directory to use as the starting point for absolute paths. +This is retrieved from the current process's current root directory +when +.Nm +starts up. +It is not initialized by +.Fn NDINIT . +.It ni_erootdir +The root directory to use as the emulation root, for processes running +in emulation. +This is retrieved from the current process's emulation root directory +when +.Nm +starts up and not initialized by +.Fn NDINIT . +As described elsewhere, it may be set by the caller if the +.Dv EMULROOTSET +flag is used, but this should only be done when the current process's +emulation root directory is not yet initialized. +(And ideally in the future things would be tidied so that this is not +necessary.) +.It ni_vp +.It ni_dvp +Returned vnodes, as described above. +These only contain valid values if +.Nm +returns successfully. +.It ni_pathlen +The length of the full current remaining path string in +.Fa ni_pnbuf . +This is not initialized by +.Fn NDINIT +and is used only internally. +.It ni_next +The remaining part of the path, after the current component found in +the +.Em componentname +structure. +This is not initialized by +.Fn NDINIT +and is used only internally. +.It ni_loopcnt +The number of symbolic links encountered (and traversed) so far. +If this exceeds a limit, +.Nm +fails with +.Er ELOOP . +This is not initialized by +.Fn NDINIT +and is used only internally. +.It ni_cnd +The +.Em componentname +structure holding the current directory component, and also the +mode, flags, and credentials. +The mode, flags, and credentials are initialized by +.Fn NDINIT ; +the rest is not initialized until +.Nm +runs. +.El +.Pp +There is also a +.Em namei_state +structure that is hidden within +.Pa vfs_lookup.c . +This contains the following additional state: +.Bl -tag -offset indent -width attempt_retry -compact +.It docache +A flag indicating whether to cache the last pathname component. +.It rdonly +The read-only state, initialized from the +.Dv RDONLY +flag. +.It slashes +The number of trailing slashes found after the current pathname +component. +.It attempt_retry +Set on some error cases (and not others) to indicate that a failure in +the emulation root should be followed by a retry in the real system +root. +.El +.Pp +The state in +.Em namei_state +is genuinely private to +.Nm . +Note that much of the state in +.Em nameidata +should also be private, but is currently not because it is misused in +some fashion by outside code, usually +.Xr nfs 4 . +.Pp +The control flow within the +.Nm +portions of +.Pa vfs_lookup.c +is as follows. +.Bl -tag -width namei_tryemulrootXX +.It Fn namei +does a complete path lookup by calling +.Fn namei_init , +.Fn namei_tryemulroot , +and +.Fn namei_cleanup . +.It Fn namei_init +sets up the basic internal state and makes some (precondition-type) +assertions. +.It Fn namei_cleanup +makes some postcondition-type assertions; it currently does nothing +besides this. +.It Fn namei_tryemulroot +handles +.Dv TRYEMULROOT +by calling +.Fn namei_oneroot +once or twice as needed, and attends to making sure the original +pathname is preserved for the second try. +.It Fn namei_oneroot +does a complete path search from a single root directory. +It begins with +.Fn namei_start , +then calls +.Fn lookup_once +(and if necessary, +.Fn namei_follow ) +repeatedly until done. +It also handles returning the result vnode(s) in the requested state. +.It Fn namei_start +sets up the initial state and locking; it calls +.Fn namei_getstartdir . +.It Fn namei_getstartdir +initializes the root directory state (both +.Fa ni_rootdir +and +.Fa ni_erootdir ) +and picks the starting directory, consuming the leading slashes of an +absolute path and handling the magic +.Dq /../ +string for bypassing the emulation root. +A different version +.Fn namei_getstartdir_for_nfsd +is used for lookups coming from +.Xr nfsd 8 +as those are required to have different semantics. +.It Fn lookup_once +calls +.Fn VOP_LOOKUP +for one path component, also handling any needed crossing of mount +points (either up or down) and coping with locking requirements. +.It Fn lookup_parsepath +is called prior to each +.Fn lookup_once +call to examine the pathname and find where the next component +starts. +.It Fn namei_follow +reads the contents of a symbolic link and updates both the path buffer +and the search directory accordingly. +.El +.Pp +As a final note be advised that the magic return value associated with +.Dv CREATE +mode is different for +.Nm +than it is for +.Fn VOP_LOOKUP . +The latter +.Dq fails +with +.Er EJUSTRETURN . +.Nm +translates this into succeeding and returning a null vnode. +.Sh CODE REFERENCES +The name lookup subsystem is implemented within the file +.Pa sys/kern/vfs_lookup.c . +.Sh SEE ALSO +.Xr intro 9 , +.Xr namecache 9 , +.Xr vfs 9 , +.Xr vnode 9 , +.Xr vnodeops 9 +.Sh BUGS +There should be no such thing as operating modes. +Only +.Dv LOOKUP +is actually needed. +The behavior where removing an object looks it up within +.Nm +and then calls into the file system (which must look it up again +internally or cache state from +.Fn VOP_LOOKUP ) +is particularly contorted. +.Pp +Most of the flags are equally bogus. +.Pp +Most of the contents of the +.Em nameidata +structure should be private and hidden within +.Nm ; +currently it cannot be because of abuse elsewhere. +.Pp +The +.Dv EMULROOTSET +flag is messy. +.Pp +There is no good way to support file systems that want to use +a more elaborate pathname schema than the customary slash-delimited +components. diff --git a/static/netbsd/man9/nullop.9 b/static/netbsd/man9/nullop.9 new file mode 100644 index 00000000..4be5e2b9 --- /dev/null +++ b/static/netbsd/man9/nullop.9 @@ -0,0 +1,88 @@ +.\" $NetBSD: nullop.9,v 1.1 2010/07/25 21:05:13 jruoho Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 25, 2010 +.Dt NULLOP 9 +.Os +.Sh NAME +.Nm nullop +.Nd dummy functions +.Sh SYNOPSIS +.In sys/systm.h +.Ft int +.Fn nullop "void *v" +.Ft void +.Fn voidop "void" +.Ft int +.Fn enodev "void" +.Ft int +.Fn enxio "void" +.Ft int +.Fn enoioctl "void" +.Ft int +.Fn enosys "void" +.Ft int +.Fn eopnotsupp "void" +.Sh DESCRIPTION +The +.Fn nullop +function provides a generic +.Dq null operation . +It always returns the value 0. +The +.Fn voidop +function takes no arguments and does nothing. +.Pp +The +.Fn enodev , +.Fn enxio , +.Fn enoioctl , +.Fn enosys , +and +.Fn eopnotsupp +functions always fail, returning +.Er ENODEV , +.Er ENXIO , +.Er ENOTTY , +.Er ENOSYS , +and +.Er EOPNOTSUPP , +respectively. +.Sh EXAMPLES +The following example demonstrates a case where +.Fn nullop +may be useful: +.Bd -literal -offset indent +uint64_t xc; + +\&... + +xc = xc_broadcast(0, (xcfunc_t)nullop, NULL, NULL); +xc_wait(xc); +.Ed diff --git a/static/netbsd/man9/opencrypto.9 b/static/netbsd/man9/opencrypto.9 new file mode 100644 index 00000000..0824fec2 --- /dev/null +++ b/static/netbsd/man9/opencrypto.9 @@ -0,0 +1,709 @@ +.\" $OpenBSD: crypto.9,v 1.25 2003/07/11 13:47:41 jmc Exp $ +.\" $NetBSD: opencrypto.9,v 1.24 2024/09/08 09:36:48 rillig Exp $ +.\" +.\" The author of this man page is Angelos D. Keromytis (angelos@cis.upenn.edu) +.\" +.\" Copyright (c) 2000, 2001 Angelos D. Keromytis +.\" +.\" Permission to use, copy, and modify this software with or without fee +.\" is hereby granted, provided that this entire notice is included in +.\" all source code copies of any software which is or includes a copy or +.\" modification of this software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR +.\" IMPLIED WARRANTY. IN PARTICULAR, NONE OF THE AUTHORS MAKES ANY +.\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE +.\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR +.\" PURPOSE. +.\" +.Dd May 26, 2017 +.Dt OPENCRYPTO 9 +.Os +.Sh NAME +.Nm opencrypto , +.Nm crypto_get_driverid , +.Nm crypto_register , +.Nm crypto_kregister , +.Nm crypto_unregister , +.Nm crypto_unregister_all , +.Nm crypto_done , +.Nm crypto_kdone , +.Nm crypto_newsession , +.Nm crypto_freesession , +.Nm crypto_dispatch , +.Nm crypto_kdispatch , +.Nm crypto_getreq , +.Nm crypto_freereq +.Nm crypto_kgetreq , +.Nm crypto_kfreereq +.Nd API for cryptographic services in the kernel +.Sh SYNOPSIS +.In opencrypto/cryptodev.h +.Ft int32_t +.Fn crypto_get_driverid "u_int32_t" +.Ft int +.Fn crypto_register "u_int32_t" "int" "u_int16_t" "u_int32_t" "int (*)(void *, u_int32_t *, struct cryptoini *)" "int (*)(void *, u_int32_t *)" "int (*)(u_int64_t)" "int (*)(struct cryptop *)" "void *" +.Ft int +.Fn crypto_kregister "u_int32_t" "int" "u_int32_t" "int (*)(void *, struct cryptkop *, int)" "void *" +.Ft int +.Fn crypto_unregister "u_int32_t" "int" +.Ft int +.Fn crypto_unregister_all "u_int32_t" +.Ft void +.Fn crypto_done "struct cryptop *" +.Ft void +.Fn crypto_kdone "struct cryptkop *" +.Ft int +.Fn crypto_newsession "u_int64_t *" "struct cryptoini *" "int" +.Ft void +.Fn crypto_freesession "u_int64_t" +.Ft void +.Fn crypto_dispatch "struct cryptop *" +.Ft void +.Fn crypto_kdispatch "struct cryptkop *" +.Ft struct cryptop * +.Fn crypto_getreq "int" +.Ft void +.Fn crypto_freereq "struct cryptop *" +.Ft struct cryptop * +.Fn crypto_kgetreq "int" "int" +.Ft void +.Fn crypto_kfreereq "struct cryptop *" +.Bd -literal + +#define EALG_MAX_BLOCK_LEN 16 + +struct cryptoini { + int cri_alg; + int cri_klen; + int cri_rnd; + void *cri_key; + u_int8_t cri_iv[EALG_MAX_BLOCK_LEN]; + struct cryptoini *cri_next; +}; + +struct cryptodesc { + int crd_skip; + int crd_len; + int crd_inject; + int crd_flags; + struct cryptoini CRD_INI; + struct cryptodesc *crd_next; +}; + +struct cryptop { + TAILQ_ENTRY(cryptop) crp_next; + u_int64_t crp_sid; + int crp_ilen; + int crp_olen; + int crp_etype; + int crp_flags; + void *crp_buf; + void *crp_opaque; + struct cryptodesc *crp_desc; + int (*crp_callback)(struct cryptop *); + void *crp_mac; +}; + +struct crparam { + void *crp_p; + u_int crp_nbits; +}; + +#define CRK_MAXPARAM 8 + +struct cryptkop { + TAILQ_ENTRY(cryptkop) krp_next; + u_int krp_op; /* i.e. CRK_MOD_EXP or other */ + u_int krp_status; /* return status */ + u_short krp_iparams; /* # of input parameters */ + u_short krp_oparams; /* # of output parameters */ + u_int32_t krp_hid; + struct crparam krp_param[CRK_MAXPARAM]; /* kvm */ + int (*krp_callback)(struct cryptkop *); +}; +.Ed +.Sh DESCRIPTION +.Nm +is a framework for drivers of cryptographic hardware to register with +the kernel so +.Dq consumers +(other kernel subsystems, and eventually +users through an appropriate device) are able to make use of it. +Drivers register with the framework the algorithms they support, +and provide entry points (functions) the framework may call to +establish, use, and tear down sessions. +Sessions are used to cache cryptographic information in a particular driver +(or associated hardware), so initialization is not needed with every request. +Consumers of cryptographic services pass a set of +descriptors that instruct the framework (and the drivers registered +with it) of the operations that should be applied on the data (more +than one cryptographic operation can be requested). +.Pp +Keying operations are supported as well. +Unlike the symmetric operators described above, +these sessionless commands perform mathematical operations using +input and output parameters. +.Pp +Since the consumers may not be associated with a process, drivers may +not use condition variables: +.Xr condvar 9 . +The same holds for the framework. +Thus, a callback mechanism is used +to notify a consumer that a request has been completed (the +callback is specified by the consumer on a per-request basis). +The callback is invoked by the framework whether the request was +successfully completed or not. +An error indication is provided in the latter case. +A specific error code, +.Er EAGAIN , +is used to indicate that a session number has changed and that the +request may be re-submitted immediately with the new session number. +Errors are only returned to the invoking function if not +enough information to call the callback is available (meaning, there +was a fatal error in verifying the arguments). +No callback mechanism is used for session initialization and teardown. +.Pp +The +.Fn crypto_newsession +routine is called by consumers of cryptographic services (such as the +.Xr ipsec 4 +stack) that wish to establish a new session with the framework. +On success, the first argument will contain the Session Identifier (SID). +The second argument contains all the necessary information for +the driver to establish the session. +The third argument indicates whether a +hardware driver should be used (1) or not (0). +The various fields in the +.Fa cryptoini +structure are: +.Bl -tag -width foobarmoocow +.It Fa cri_alg +Contains an algorithm identifier. +Currently supported algorithms are: +.Bd -literal +CRYPTO_DES_CBC +CRYPTO_3DES_CBC +CRYPTO_BLF_CBC +CRYPTO_CAST_CBC +CRYPTO_CAMELLIA_CBC +CRYPTO_SKIPJACK_CBC +CRYPTO_ARC4 +CRYPTO_AES_CBC +CRYPTO_AES_CTR +CRYPTO_AES_GCM_16 +CRYPTO_AES_GMAC +CRYPTO_AES_128_GMAC +CRYPTO_AES_192_GMAC +CRYPTO_AES_256_GMAC +CRYPTO_AES_XCBC_MAC_96 +CRYPTO_MD5 +CRYPTO_MD5_HMAC +CRYPTO_MD5_HMAC_96 +CRYPTO_MD5_KPDK +CRYPTO_NULL_CBC +CRYPTO_NULL_HMAC +CRYPTO_SHA1 +CRYPTO_SHA1_HMAC +CRYPTO_SHA1_HMAC_96 +CRYPTO_SHA1_KPDK +CRYPTO_SHA2_256_HMAC +CRYPTO_SHA2_384_HMAC +CRYPTO_SHA2_512_HMAC +CRYPTO_RIPEMD160_HMAC +CRYPTO_RIPEMD160_HMAC_96 +CRYPTO_DEFLATE_COMP +CRYPTO_DEFLATE_COMP_NOGROW +CRYPTO_GZIP_COMP +.Ed +.Pp +.It Fa cri_klen +Specifies the length of the key in bits, for variable-size key +algorithms. +.It Fa cri_rnd +Specifies the number of rounds to be used with the algorithm, for +variable-round algorithms. +.It Fa cri_key +Contains the key to be used with the algorithm. +.It Fa cri_iv +Contains an explicit initialization vector (IV), if it does not prefix +the data. +This field is ignored during initialization. +If no IV is explicitly passed (see below on details), a random IV is used +by the device driver processing the request. +.It Fa cri_next +Contains a pointer to another +.Fa cryptoini +structure. +Multiple such structures may be linked to establish multi-algorithm sessions +.Pf ( Xr ipsec 4 +is an example consumer of such a feature). +.El +.Pp +The +.Fa cryptoini +structure and its contents will not be modified by the framework (or +the drivers used). +Subsequent requests for processing that use the +SID returned will avoid the cost of re-initializing the hardware (in +essence, SID acts as an index in the session cache of the driver). +.Pp +.Fn crypto_freesession +is called with the SID returned by +.Fn crypto_newsession +to disestablish the session. +.Pp +.Fn crypto_dispatch +is called to process a request. +The various fields in the +.Fa cryptop +structure are: +.Bl -tag -width crp_callback +.It Fa crp_sid +Contains the SID. +.It Fa crp_ilen +Indicates the total length in bytes of the buffer to be processed. +.It Fa crp_olen +On return, contains the length of the result, not including +.Fa crd_skip . +For symmetric crypto operations, this will be the same as the input length. +.It Fa crp_alloctype +Indicates the type of buffer, as used in the kernel +.Xr malloc 9 +routine. +This will be used if the framework needs to allocate a new +buffer for the result (or for re-formatting the input). +.It Fa crp_callback +This routine is invoked upon completion of the request, whether +successful or not. +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 Fa crp_etype +Contains the error type, if any errors were encountered, or zero if +the request was successfully processed. +.Pp +Note that this field only makes sense when examined by +the callback routine specified in +.Fa crp_callback . +Errors are returned to the invoker of +.Fn crypto_process +only when enough information is not present to call the callback +routine (i.e., if the pointer passed is +.Dv NULL +or if no callback routine was specified). +.It Fa crp_flags +Is a bitmask of flags associated with this request. +Currently defined flags are: +.Bl -tag -width CRYPTO_F_IMBUF +.It Dv CRYPTO_F_IMBUF +The buffer pointed to by +.Fa crp_buf +is an mbuf chain. +.El +.Pp +.It Fa crp_buf +Points to the input buffer. +On return (when the callback is invoked), +it contains the result of the request. +The input buffer may be an mbuf +chain or a contiguous buffer (of a type identified by +.Fa crp_alloctype ) , +depending on +.Fa crp_flags . +.It Fa crp_opaque +This is passed through the crypto framework untouched and is +intended for the invoking application's use. +.It Fa crp_desc +This is a linked list of descriptors. +Each descriptor provides +information about what type of cryptographic operation should be done +on the input buffer. +The various fields are: +.Bl -tag -width ".Fa crd_inject" +.It Fa crd_skip +The offset in the input buffer where processing should start. +.It Fa crd_len +How many bytes, after +.Fa crd_skip , +should be processed. +.It Fa crd_inject +Offset from the beginning of the buffer to insert any results. +For encryption algorithms, this is where the initialization vector +(IV) will be inserted when encrypting or where it can be found when +decrypting (subject to +.Fa crd_flags ) . +For MAC algorithms, this is where the result of the keyed hash will be +inserted. +.It Fa crd_flags +For adjusting general operation from userland, +the following flags are defined: +.Bl -tag -width CRD_F_IV_EXPLICIT +.It Dv CRD_F_ENCRYPT +For encryption algorithms, this bit is set when encryption is required +(when not set, decryption is performed). +.It Dv CRD_F_IV_PRESENT +For encryption algorithms, this bit is set when the IV already +precedes the data, so the +.Fa crd_inject +value will be ignored and no IV will be written in the buffer. +Otherwise, the IV used to encrypt the packet will be written +at the location pointed to by +.Fa crd_inject . +Some applications that do special +.Dq IV cooking , +such as the half-IV mode in +.Xr ipsec 4 , +can use this flag to indicate that the IV should not be written on the packet. +This flag is typically used in conjunction with the +.Dv CRD_F_IV_EXPLICIT +flag. +.It Dv CRD_F_IV_EXPLICIT +For encryption algorithms, this bit is set when the IV is explicitly +provided by the consumer in the +.Fa crd_iv +fields. +Otherwise, for encryption operations the IV is provided for by +the driver used to perform the operation, whereas for decryption +operations it is pointed to by the +.Fa crd_inject +field. +This flag is typically used when the IV is calculated +.Dq on the fly +by the consumer, and does not precede the data (some +.Xr ipsec 4 +configurations, and the encrypted swap are two such examples). +.It Dv CRD_F_COMP +For compression algorithms, this bit is set when compression is required (when +not set, decompression is performed). +.El +.It Fa CRD_INI +This +.Fa cryptoini +structure will not be modified by the framework or the device drivers. +Since this information accompanies every cryptographic +operation request, drivers may re-initialize state on-demand +(typically an expensive operation). +Furthermore, the cryptographic +framework may re-route requests as a result of full queues or hardware +failure, as described above. +.It Fa crd_next +Point to the next descriptor. +Linked operations are useful in protocols such as +.Xr ipsec 4 , +where multiple cryptographic transforms may be applied on the same +block of data. +.El +.El +.Pp +.Fn crypto_getreq +allocates a +.Fa cryptop +structure with a linked list of as many +.Fa cryptodesc +structures as were specified in the argument passed to it, which must +be at least 1. +.Pp +.Fn crypto_freereq +deallocates a structure +.Fa cryptop +and any +.Fa cryptodesc +structures linked to it. +Note that it is the responsibility of the +callback routine to do the necessary cleanups associated with the +opaque field in the +.Fa cryptop +structure. +.Pp +.Fn crypto_kdispatch +is called to perform a keying operation. +The various fields in the +.Fa crytokop +structure are: +.Bl -tag -width crp_alloctype +.It Fa krp_op +Operation code, such as CRK_MOD_EXP. +.It Fa krp_status +Return code. +This errno-style variable indicates whether there were lower level reasons +for operation failure. +.It Fa krp_iparams +Number of input parameters to the specified operation. +Note that each operation has a (typically hardwired) number of such parameters. +.It Fa krp_oparams +Number of output parameters from the specified operation. +Note that each operation has a (typically hardwired) number of such parameters. +.It Fa krp_kvp +An array of kernel memory blocks containing the parameters. +.It Fa krp_hid +Identifier specifying which low-level driver is being used. +.It Fa krp_callback +Callback called on completion of a keying operation. +.El +.Pp +.Fn crypto_kgetreq +allocates a +.Fa cryptkop +structure. +The first argument means the same as +.Fn crypto_getreq , +except it is currently limited to be exactly 1. +The second argument means flags passed to +.Fn pool_get . +.Pp +.Fn crypto_kfreereq +deallocates a structure +.Fa cryptkop +structure. +.Pp +The following sysctl entries exist to adjust +the behaviour of the system from userland: +.Bl -tag -width opencrypto.crypto_ret_kq.maxlen +.It kern.usercrypto +Allow (1) or forbid (0) userland access to +.Pa /dev/crypto . +.It kern.userasymcrypto +Allow (1) or forbid (0) userland access to +do asymmetric crypto requests. +.It kern.cryptodevallowsoft +Enable/disable access to hardware versus software operations: +.Bl -tag -width xxx +.It < 0 +Force userlevel requests to use software operations, always. +.It = 0 +Use hardware if present, grant userlevel requests for non-accelerated +operations (handling the latter in software). +.It > 0 +Allow user requests only for operations which are hardware-accelerated. +.El +.It opencrypto.crypto_ret_q.maxlen +Limit the length of queue(crypto_ret_q) which mediates between +crypto driver's completion and calling +.Fa cryptop +callback. +When the queue exceeds this limit, +.Fn crypto_getreq +fails. +.Bl -tag -width xxxx +.It <= 0 +means unlimited. +.El +.It opencrypto.crypto_ret_kq.maxlen +Limit the length of queue(crypto_ret_kq) which mediates between +crypto driver's completion and calling +.Fa cryptkop +callback. +When the queue exceeds this limit, +.Fn crypto_kgetreq +fails. +.Bl -tag -width xxxx +.It <= 0 +means unlimited. +.El +.El +.Pp +.Bl -tag -width opencrypto.crypto_ret_kq.drops +The following sysctl entries exist to get statistics. +.It opencrypto.crypto_ret_q.len +Current crypto_ret_q length. +.It opencrypto.crypto_ret_q.drops +The count of +.Fn crypto_getreq +failed as overflow +.Pa opencrypto.crypto_ret_q.maxlen . +.It opencrypto.crypto_ret_kq.len +Current crypto_ret_kq length. +.It opencrypto.crypto_ret_kq.drops +The count of +.Fn crypto_kgetreq +failed as overflow +.Pa opencrypto.crypto_ret_kq.maxlen . +.El +.Sh DRIVER-SIDE API +The +.Fn crypto_get_driverid , +.Fn crypto_register , +.Fn crypto_kregister , +.Fn crypto_unregister , +.Fn crypto_unregister_all , +and +.Fn crypto_done +routines are used by drivers that provide support for cryptographic +primitives to register and unregister with the kernel crypto services +framework. +Drivers must first use the +.Fn crypto_get_driverid +function to acquire a driver identifier, specifying the +.Fa flags +as an argument (normally 0, but software-only drivers should specify +.Dv CRYPTOCAP_F_SOFTWARE ) . +For each algorithm the driver supports, it must then call +.Fn crypto_register . +The first argument is the driver identifier. +The second argument is an array of +.Dv CRYPTO_ALGORITHM_MAX + 1 +elements, indicating which algorithms are supported. +The last three arguments are pointers to three +driver-provided functions that the framework may call to establish new +cryptographic context with the driver, free already established +context, and ask for a request to be processed (encrypt, decrypt, +etc.) +.Fn crypto_unregister +is called by drivers that wish to withdraw support for an algorithm. +The two arguments are the driver and algorithm identifiers, respectively. +algorithms supported by the card. +If all algorithms associated with a driver are unregistered, the +driver will be disabled (no new sessions will be allocated on that +driver, and any existing sessions will be migrated to other drivers). +.Fn crypto_unregister_all +will unregister all registered algorithms, disable the driver, +and migrate existing sessions to other drivers. +.Pp +The calling convention for the three driver-supplied routines is: +.Bd -literal +int (*newsession) (void *, u_int32_t *, struct cryptoini *); +void (*freesession) (void *, u_int64_t); +int (*process) (void *, struct cryptop *, int); +.Ed +.Pp +On invocation, the first argument to +.Fn newsession +contains the driver identifier obtained via +.Fn crypto_get_driverid . +On successfully returning, it should contain a driver-specific session +identifier. +The second argument is identical to that of +.Fn crypto_newsession . +.Pp +The +.Fn freesession +routine takes as argument the SID (which is the concatenation of the +driver identifier and the driver-specific session identifier returned +by +.Fn newsession ). +It should clear any context associated with the session (clear hardware +registers, memory, etc.). +.Pp +The +.Fn process +routine is invoked with a request to perform crypto processing. +This routine must not block, but should queue the request and return +immediately. +Upon processing the request, the callback routine should be invoked. +In case of error, the error indication must be placed in the +.Fa crp_etype +field of the +.Fa cryptop +structure. +The +.Fa hint +argument can be set to +.Dv CRYPTO_HINT_MORE +when there will be more request right after this request. +When the request is completed, or an error is detected, the +.Fn process +routine should invoke +.Fn crypto_done . +Session migration may be performed, as mentioned previously. +.Pp +The +.Fn kprocess +routine is invoked with a request to perform crypto key processing. +This routine must not block, but should queue the request and return +immediately. +Upon processing the request, the callback routine should be invoked. +In case of error, the error indication must be placed in the +.Fa krp_status +field of the +.Fa cryptkop +structure. +When the request is completed, or an error is detected, the +.Fn kprocess +routine should invoke +.Fn crypto_kdone . +.Sh RETURN VALUES +.Fn crypto_register , +.Fn crypto_kregister , +.Fn crypto_unregister , +and +.Fn crypto_newsession +return 0 on success, or an error code on failure. +.Fn crypto_get_driverid +returns a non-negative value on error, and \-1 on failure. +.Fn crypto_getreq +returns a pointer to a +.Fa cryptop +structure and +.Dv NULL +on failure. +.Fn crypto_kgetreq +returns a pointer to a +.Fa cryptkop +structure and +.Dv NULL +on failure. +.Fn crypto_dispatch +arranges to invoke the callback with an error code +in the +.Fa crp_etype +field, or zero on success. +.Sh FILES +.Bl -tag -width sys/opencrypto/crypto.c +.It Pa sys/opencrypto/crypto.c +most of the framework code +.It Pa sys/crypto +crypto algorithm implementations +.El +.Sh SEE ALSO +.Xr ipsec 4 , +.Xr pcmcia 4 , +.Xr condvar 9 , +.Xr malloc 9 , +.Xr pool 9 +.Rs +.%A "Angelos D. Keromytis" +.%A "Jason L. Wright" +.%A "Theo de Raadt" +.%T "The Design of the OpenBSD Cryptographic Framework" +.%I "Usenix" +.%N "2003" +.%D "June 2003" +.Re +.Sh HISTORY +The cryptographic framework first appeared in +.Ox 2.7 +and was written by +.An Angelos D. Keromytis Aq Mt angelos@openbsd.org . +.Pp +.An Sam Leffler +ported the crypto framework to +.Fx +and made performance improvements. +.Pp +.An Jonathan Stone Aq Mt jonathan@NetBSD.org +ported the cryptoframe from +.Fx +to +.Nx . +.Nm opencrypto +first appeared in +.Nx 2.0 . +.Sh BUGS +The framework currently assumes that all the algorithms in a +.Fn crypto_newsession +operation must be available by the same driver. +If that's not the case, session initialization will fail. +.Pp +The framework also needs a mechanism for determining which driver is +best for a specific set of algorithms associated with a session. +Some type of benchmarking is in order here. +.Pp +Multiple instances of the same algorithm in the same session are not +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. diff --git a/static/netbsd/man9/optstr.9 b/static/netbsd/man9/optstr.9 new file mode 100644 index 00000000..8ca3b79a --- /dev/null +++ b/static/netbsd/man9/optstr.9 @@ -0,0 +1,155 @@ +.\" $NetBSD: optstr.9,v 1.6 2023/04/20 10:43:17 uwe Exp $ +.\" +.\" Copyright (c) 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Julio M. Merino Vidal. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 20, 2023 +.Dt OPTSTR 9 +.Os +. +.Sh NAME +.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 +.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 +.Ar key\^ Ns Li = Ns Ar value +and is separated from other pairs by one or more spaces. +For example: +.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 Fn +.It Fn optstr_get "optstr" "key" "buf" "bufsize" +Scans the +.Fa optstr +options string looking for the key +.Fa key +and stores its value in the buffer pointed to by +.Fa buf +copying a maximum of +.Fa bufsize +bytes. +Returns +.Ql true +if the key was found or +.Ql false +otherwise, in which case +.Fa buf +is left unmodified. +.El +.Pp +The +.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 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" +These functions scan the +.Fa optstr +options string looking for the key +.Fa key +and returns the key value converted as per the function name in +.Fa result . +All functions return +.Ql true +if the key was found or +.Ql false +otherwise, in which case +.Fa result +is left unmodified. +.El +.Sh CODE REFERENCES +The options string management functions are implemented within the files +.Pa sys/kern/subr_optstr.c +and +.Pa sys/sys/optstr.h . +.Sh HISTORY +Options strings appeared in +.Nx 4.0 . diff --git a/static/netbsd/man9/panic.9 b/static/netbsd/man9/panic.9 new file mode 100644 index 00000000..9a06acab --- /dev/null +++ b/static/netbsd/man9/panic.9 @@ -0,0 +1,114 @@ +.\" $NetBSD: panic.9,v 1.23 2019/10/04 21:55:00 gutteridge Exp $ +.\" +.\" Copyright (c) 1996 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" Michael Graff. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 4, 2019 +.Dt PANIC 9 +.Os +.Sh NAME +.Nm panic +.Nd bring down system on fatal error +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft void +.Fn vpanic "const char *fmt" "va_list ap" +.Ft void +.Fn panic "const char *fmt" "..." +.Sh DESCRIPTION +The +.Fn panic +and +.Fn vpanic +functions terminate the +.Nx +system. +The message +.Fa fmt +is a +.Xr printf 3 +style format string which is printed to the console and saved in the +variable +.Va panicstr +for later retrieval via core dump inspection. +A newline character is added at the end automatically, and is thus +not needed in the format string. +.Pp +If a kernel debugger is installed, control is passed to it after the +message is printed. +If the kernel debugger is +.Xr ddb 4 , +control may be passed to it, depending on the value of +.Em ddb.onpanic . +See +.Xr options 4 +for more details on setting +.Em ddb.onpanic . +If control is not passed through to +.Xr ddb 4 , +a +.Xr ddb 4 Ns -specific +function is used to print the kernel stack trace, and then control returns +to +.Fn panic . +.Pp +If control remains in +.Fn panic , +an attempt is made to save an image of system memory on the +configured dump device. +.Pp +If during the process of handling the panic, +.Fn panic +is called again +.Pq from the filesystem synchronization routines, for example , +the system is rebooted immediately without synchronizing any filesystems. +.Pp +.Fn panic +is meant to be used in situations where something unexpected has happened +and it is difficult to recover the system to a stable state, or in +situations where proceeding might make things worse, leading to data +corruption and/or loss. +It is not meant to be used in scenarios where the system could easily +ignore and/or isolate the condition/subsystem and proceed. +.Pp +In general developers should try to reduce the number of +.Fn panic +calls in the kernel to improve stability. +.Sh RETURN VALUES +The +.Fn panic +function never returns. +.Sh SEE ALSO +.Xr printf 3 , +.Xr sysctl 3 , +.Xr ddb 4 , +.Xr options 4 , +.Xr savecore 8 , +.Xr swapctl 8 , +.Xr sysctl 8 , +.Xr printf 9 diff --git a/static/netbsd/man9/paravirt_membar_sync.9 b/static/netbsd/man9/paravirt_membar_sync.9 new file mode 100644 index 00000000..ad6183e6 --- /dev/null +++ b/static/netbsd/man9/paravirt_membar_sync.9 @@ -0,0 +1,148 @@ +.\" $NetBSD: paravirt_membar_sync.9,v 1.1 2025/09/06 02:53:22 riastradh Exp $ +.\" +.\" Copyright (c) 2025 The NetBSD Foundation +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 31, 2025 +.Dt PARAVIRT_MEMBAR_SYNC 9 +.Os +.Sh NAME +.Nm paravirt_membar_sync +.Nd memory barrier for paravirtualized device drivers +.Sh SYNOPSIS +.In sys/paravirt_membar.h +.Ft void +.Fn paravirt_membar_sync "void" +.Sh DESCRIPTION +The +.Nm +function issues a store-before-load barrier for coordination with a +paravirtualized device. +.Pp +This function has the same ordering semantics as +.Xr membar_sync 3 , +but +.Xr membar_sync 3 +can only coordinate with other CPUs that +.Nx +is running on. +In a virtual machine, +.Nx +may be running on a single +.Em virtual +CPU, and patch +.Xr membar_sync 3 +to be a no-op, while the host side of a paravirtualized device may be +running on a different +.Em physical +CPU requiring a barrier that +.Xr membar_sync 3 +does not issue. +.Sh EXAMPLES +Submit a request to the host device, and notify the host to process +it\(embut elide the notification, which is expensive, if the host is +already reading requests anyway: +.Bd -literal + /* + * Write the request into the ring buffer. + */ + memcpy(cputodev_ring->buffer[sc->sc_cputodev_idx], request, + sizeof(*request)); + + /* + * Publish the request to the host device side. + */ + cputodev_ring->header->producer_tail = ++sc->sc_cputodev_idx; + + /* + * Ensure we have published it _before_ we check whether the + * host needs notification. + */ + paravirt_membar_sync(); + + /* + * Notify the host, if needed. Notifying the host is usually + * expensive (trap to hypervisor), so we try to avoid it if not + * needed. + */ + if (cputodev_ring->header->needs_notification) + notify_host(); +.Ed +.Pp +Enable interrupts from the host and check whether any were pending +while interrupts were disabled: +.Bd -literal + /* + * Tell the host device to deliver interrupts after this + * point. + */ +restart: + devtocpu_ring->header->needs_notification = true; + + /* + * Ensure we have requested interrupts _before_ we check + * whether we missed any notifications. + */ + paravirt_membar_sync(); + + /* + * Check whether there were any pending notifications while + * interrupts were blocked. If not, stop here. + */ + idx = devtocpu_ring->header->producer_idx; + if (sc->sc_devtocpu_idx == idx) + return; + + /* + * Process the notifications. + */ + devtocpu_ring->header->needs_notification = false; + while (sc->sc_devtocpu_idx != idx) { + struct buffer *buf = + devtocpu_ring->buffer[sc->sc_devtocpu_idx]; + process_notification(buf); + sc->sc_devtocpu_idx++; + sc->sc_devtocpu_idx %= ringlen; + } + goto restart; +.Ed +.Pp +.Sy "N.B.:" +Other ordering or bouncing may be required with +.Xr bus_dmamap_sync 9 ; +this is independent of +.Nm , +which is needed +.Em in addition to +.Xr bus_dmamap_sync 9 +to guarantee store-before-load ordering when there is no intervening +I/O doorbell trigger for a DMA operation, nor interrupt delivery for a +DMA completion. +.Sh SEE ALSO +.Xr membar_ops 3 , +.Xr bus_dma 9 , +.Xr bus_space 9 +.Sh HISTORY +These atomic operations first appeared in +.Nx 12.0 . diff --git a/static/netbsd/man9/pathbuf.9 b/static/netbsd/man9/pathbuf.9 new file mode 100644 index 00000000..8314958f --- /dev/null +++ b/static/netbsd/man9/pathbuf.9 @@ -0,0 +1,130 @@ +.\" $NetBSD: pathbuf.9,v 1.2 2010/11/30 10:32:46 dholland Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by David A. Holland. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 30, 2010 +.Dt PATHBUF 9 +.Os +.Sh NAME +.Nm pathbuf , +.Nm pathbuf_create , +.Nm pathbuf_assimilate , +.Nm pathbuf_copyin , +.Nm pathbuf_destroy +.Nd path buffer abstraction +.Sh SYNOPSIS +.In sys/namei.h +.Ft struct pathbuf * +.Fn pathbuf_create "const char *path" +.Ft struct pathbuf * +.Fn pathbuf_assimilate "char *pnbuf" +.Ft int +.Fn pathbuf_copyin "const char *userpath" "struct pathbuf **ret" +.Ft void +.Fn pathbuf_destroy "struct pathbuf *path" +.Sh DESCRIPTION +The +.Nm +interface is used to carry around pathnames. +This helps simplify the +.Xr namei 9 +interface. +A pathbuf should be thought of as a path name string combined with +whatever flags and metadata are needed to interpret it correctly. +It is an abstract type; the internals are hidden within the +.Xr namei 9 +implementation. +.Pp +The +.Fn pathbuf_create +function allocates and initializes a new pathbuf containing a copy of +the path string +.Fa path , +which should be a kernel pointer. +The return value should be checked for being +.Dv NULL +in case the system is out of memory. +Passing a path name larger than +.Dv PATH_MAX +will cause an assertion failure. +.Pp +The +.Fn pathbuf_copyin +function allocates and initializes a new pathbuf containing a path +string copied from user space with +.Xr copyinstr 9 . +It returns an error code. +.Pp +The +.Fn pathbuf_assimilate +function creates a pathbuf using the string buffer provided as +.Fa pnbuf . +This buffer must be of size +.Dv PATH_MAX +and must have been allocated with +.Fn PNBUF_GET . +The buffer is +.Dq taken over +by the returned pathbuf and will be released when the pathbuf is +destroyed. +Note: to avoid confusion and pointer bugs, +.Fn pathbuf_assimilate +should only be used where absolutely necessary; e.g. the NFS server +code uses it to generate pathbufs from strings fetched from mbufs. +.Pp +The +.Fn pathbuf_destroy +function deallocates a pathbuf. +Caution: because calling +.Xr namei 9 +loads pointers to memory belonging to the pathbuf into the nameidata +structure, a pathbuf should only be destroyed by the +.Fn namei +caller once all manipulations of the nameidata are complete. +.Pp +Also note that calling +.Fn namei +destroys the contents of the pathbuf. +Do not reuse a pathbuf for a second call to +.Fn namei . +.Sh CODE REFERENCES +The +.Nm +code is part of the name lookup code in +.Pa sys/kern/vfs_lookup.c . +.Sh SEE ALSO +.Xr namei 9 +.Sh BUGS +There are cases where it is necessary to get the path string left +behind after +.Fn namei +has run. +This produces an effect similar to +.Xr realpath 3 . +The interface for doing this is, for the time being, intentionally +undocumented and subject to change. diff --git a/static/netbsd/man9/pci.9 b/static/netbsd/man9/pci.9 new file mode 100644 index 00000000..840f6ffc --- /dev/null +++ b/static/netbsd/man9/pci.9 @@ -0,0 +1,881 @@ +.\" $NetBSD: pci.9,v 1.49 2018/11/02 15:01:18 jmcneill Exp $ +.\" +.\" Copyright (c) 2001, 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 2, 2018 +.Dt PCI 9 +.Os +.Sh NAME +.Nm PCI , +.Nm pci_activate , +.Nm pci_bus_devorder , +.Nm pci_chipset_tag_create , +.Nm pci_chipset_tag_destroy , +.Nm pci_conf_read , +.Nm pci_conf_write , +.Nm pci_conf_print , +.Nm pci_conf_capture , +.Nm pci_conf_restore , +.Nm pci_find_device , +.Nm pci_get_capability , +.Nm pci_get_ht_capability , +.Nm pci_get_ext_capability , +.Nm pci_get_segment , +.Nm pci_mapreg_type , +.Nm pci_mapreg_map , +.Nm pci_mapreg_info , +.Nm pci_intr_map , +.Nm pci_intr_string , +.Nm pci_intr_evcnt , +.Nm pci_intr_establish , +.Nm pci_intr_establish_xname , +.Nm pci_intr_disestablish , +.Nm pci_intr_type , +.Nm pci_intr_setattr , +.Nm pci_get_powerstate , +.Nm pci_set_powerstate , +.Nm pci_vpd_read , +.Nm pci_vpd_write , +.Nm pci_make_tag , +.Nm pci_decompose_tag , +.Nm pci_findvendor , +.Nm pci_devinfo , +.Nm PCI_VENDOR , +.Nm PCI_PRODUCT , +.Nm PCI_REVISION +.Nd Peripheral Component Interconnect +.Sh SYNOPSIS +.In sys/bus.h +.In dev/pci/pcivar.h +.In dev/pci/pcireg.h +.In dev/pci/pcidevs.h +.Ft int +.Fn pci_bus_devorder "pci_chipset_tag_t pc" "int bus" "uint8_t *devs" \ +"int maxdevs" +.Ft int +.Fn pci_activate "pci_chipset_tag_t pc" "pcitag_t tag" "device_t dev" \ +"int (*wakeup)(pci_chipset_tag_t pc, pcitag_t tag, device_t dev, pcireg_t reg)" +.Ft int +.Fn pci_chipset_tag_create "pci_chipset_tag_t opc" "uint64_t present" \ +"const struct pci_overrides *ov" "void *ctx" "pci_chipset_tag_t *pcp" +.Ft void +.Fn pci_chipset_tag_destroy "pci_chipset_tag_t pc" +.Ft pcireg_t +.Fn pci_conf_read "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" +.Ft void +.Fn pci_conf_write "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" \ +"pcireg_t val" +.Ft void +.Fn pci_conf_print "pci_chipset_tag_t pc" "pcitag_t tag" \ +"void (*func)(pci_chipset_tag_t, pcitag_t, const pcireg_t *)" +.Ft void +.Fn pci_conf_capture "pci_chipset_tag_t pc" "pcitag_t tag" \ +"struct pci_conf_state *" +.Ft void +.Fn pci_conf_restore "pci_chipset_tag_t pc" "pcitag_t tag" \ +"struct pci_conf_state *" +.Ft int +.Fn pci_find_device "struct pci_attach_args *pa" \ +"int (*func)(const struct pci_attach_args *)" +.Ft int +.Fn pci_get_capability "pci_chipset_tag_t pc" "pcitag_t tag" \ +"int capid" "int *offsetp" "pcireg_t *valuep" +.Ft int +.Fn pci_get_ht_capability "pci_chipset_tag_t pc" "pcitag_t tag" \ +"int capid" "int *offsetp" "pcireg_t *valuep" +.Ft int +.Fn pci_get_ext_capability "pci_chipset_tag_t pc" "pcitag_t tag" \ +"int capid" "int *offsetp" "pcireg_t *valuep" +.Ft u_int +.Fn pci_get_segment "pci_chipset_tag_t pc" +.Ft pcireg_t +.Fn pci_mapreg_type "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" +.Ft int +.Fn pci_mapreg_map "const struct pci_attach_args *pa" "int reg" \ +"pcireg_t type" "int busflags" "bus_space_tag_t *tagp" \ +"bus_space_handle_t *handlep" "bus_addr_t *basep" "bus_size_t *sizep" +.Ft int +.Fn pci_mapreg_info "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" \ +"pcireg_t type" "bus_addr_t *basep" "bus_size_t *sizep" "int *flagsp" +.Ft int +.Fn pci_find_rom "const struct pci_attach_args *pa" \ +"bus_space_tag_t bst" "bus_space_handle_t bsh" "int code" \ +"bus_space_handle_t *handlep" "bus_space_size_t *sizep" +.Ft int +.Fn pci_intr_map "const struct pci_attach_args *pa" "pci_intr_handle_t *ih" +.Ft const char * +.Fn pci_intr_string "pci_chipset_tag_t pc" "pci_intr_handle_t ih" +.Ft const struct evcnt * +.Fn pci_intr_evcnt "pci_chipset_tag_t pc" "pci_intr_handle_t ih" +.Ft void * +.Fn pci_intr_establish "pci_chipset_tag_t pc" "pci_intr_handle_t ih" \ +"int level" "int (*handler)(void *)" "void *arg" +.Ft void * +.Fn pci_intr_establish_xname "pci_chipset_tag_t pc" "pci_intr_handle_t ih" \ +"int level" "int (*handler)(void *)" "void *arg" "const char *xname" +.Ft void +.Fn pci_intr_disestablish "pci_chipset_tag_t pc" "void *ih" +.Ft pci_intr_type_t +.Fn pci_intr_type "pci_chipset_tag_t pc" "pci_intr_handle_t ih" +.Ft int +.Fn pci_intr_setattr "pci_chipset_tag_t pc" "pci_intr_handle_t *ih" "int attr" "uint64_t data" +.Ft int +.Fn pci_set_powerstate "pci_chipset_tag_t pc" "pcitag_t tag" \ +"pcireg_t newstate" +.Ft int +.Fn pci_get_powerstate "pci_chipset_tag_t pc" "pcitag_t tag" "pcireg_t *state" +.Ft int +.Fn pci_vpd_read "pci_chipset_tag_t pc" "pcitag_t tag" "int offset" \ +"int count" "pcireg_t *data" +.Ft int +.Fn pci_vpd_write "pci_chipset_tag_t pc" "pcitag_t tag" "int offset" \ +"int count" "pcireg_t *data" +.Ft pcitag_t +.Fn pci_make_tag "pci_chipset_tag_t pc" "int bus" "int device" \ +"int function" +.Ft void +.Fn pci_decompose_tag "pci_chipset_tag_t pc" "pcitag_t tag" \ +"int *busp" "int *devicep" "int *functionp" +.Ft char * +.Fn pci_findvendor "pcireg_t id" +.Ft void +.Fn pci_devinfo "pcireg_t id" "pcireg_t class" "int show" "char *cp" "size_t len" +.Ft void +.Fn pci_aprint_devinfo "struct pci_attach_args *pa" "const char *naive" +.Ft int +.Fn PCI_VENDOR "pcireg_t id" +.Ft int +.Fn PCI_PRODUCT "pcireg_t id" +.Ft int +.Fn PCI_REVISION "pcireg_t id" +.Sh DESCRIPTION +The machine-independent +.Nm +subsystem provides support for PCI devices. +.Pp +The PCI bus was initially developed by Intel in the early 1990's to +replace the ISA bus for interfacing with their Pentium processor. +The PCI specification is widely regarded as well designed, and the +PCI bus has found widespread acceptance in machines ranging from +Apple's PowerPC-based systems to Sun's UltraSPARC-based machines. +.Pp +The PCI bus is a multiplexed bus, allowing addresses and data on the same +pins for a reduced number of pins. +Data transfers can be 8-bit, 16-bit or 32-bit. +A 64-bit extended PCI bus is also defined. +Multi-byte transfers are little-endian. +The PCI bus operates up to 33MHz and any device on the bus can be +the bus master. +.Pp +AGP is a version of PCI optimised for high-throughput data rates, +particularly for accelerated frame buffers. +.Pp +The PCI bus is a "plug and play" bus, in the sense that devices can be +configured dynamically by software. +The PCI interface chip on a PCI device bus presents a small window +of registers into the PCI configuration space. +These registers contain information about the device such as the vendor +and a product ID. +The configuration registers can also be written to by software to alter +how the device interfaces to the PCI bus. +An important register in the configuration space is the Base Address +Register (BAR). +The BAR is written to by software to map the device registers into a +window of processor address space. +Once this mapping is done, the device registers can be accessed relative +to the base address. +.Sh DATA TYPES +Drivers for devices attached to the +.Nm +will make use of the following data types: +.Bl -tag -width compact +.It Fa pcireg_t +Configuration space register. +.It Fa pci_chipset_tag_t +Chipset tag for the PCI bus. +.It Fa pcitag_t +Configuration tag describing the location and function of the PCI +device. +It contains the tuple +.Ao +bus, device, function +.Ac . +.It Fa pci_intr_handle_t +The opaque handle describing an established interrupt handler. +.It Fa struct pci_attach_args +Devices have their identity recorded in this structure. +It contains the following members: +.Bd -literal + bus_space_tag_t pa_iot; /* pci i/o space tag */ + bus_space_tag_t pa_memt; /* pci mem space tag */ + bus_dma_tag_t pa_dmat; /* DMA tag */ + pci_chipset_tag_t pa_pc; + int pa_flags; /* flags */ + pcitag_t pa_tag; + pcireg_t pa_id; + pcireg_t pa_class; +.Ed +.It Fa struct pci_conf_state +Stores the PCI configuration state of a device. +It contains the following member: +.Bd -literal + pcireg_t reg[16]; /* pci conf register */ +.Ed +.It Fa struct pci_overrides +Stores pointers to functions that override the architecture's +default +.Nm +and +.Xr pci_intr 9 +implementation. +It contains the following members: +.Bd -literal + pcireg_t (*ov_conf_read)(void *, + pci_chipset_tag_t, pcitag_t, int); + void (*ov_conf_write)(void *, + pci_chipset_tag_t, pcitag_t, int, pcireg_t); + int (*ov_intr_map)(void *, + const struct pci_attach_args *, pci_intr_handle_t *); + const char *(*ov_intr_string)(void *, + pci_chipset_tag_t, pci_intr_handle_t); + const struct evcnt *(*ov_intr_evcnt)(void *, + pci_chipset_tag_t, pci_intr_handle_t); + void *(*ov_intr_establish)(void *, + pci_chipset_tag_t, pci_intr_handle_t, + int, int (*)(void *), void *); + void (*ov_intr_disestablish)(void *, + pci_chipset_tag_t, void *); + pcitag_t (*ov_make_tag)(void *, + pci_chipset_tag_t, int, int, int); + void (*ov_decompose_tag)(void *, + pci_chipset_tag_t, pcitag_t, int *, int *, int *); +.Ed +.El +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn pci_bus_devorder "pc" "bus" "devs" "maxdevs" +Tell how many devices a PCI bus driver should probe +and in what order. +If +.Fa maxdevs +is less than or equal to zero, return 0 and +do not modify +.Fa devs . +Otherwise, return +.Fa maxdevs +or the number of devices on +.Fa bus +to probe, whichever is less, and copy to +.Fa devs +each of the PCI device numbers to probe in the order that they +should be probed. +.Fn pci_bus_devorder +will not copy more than +.Fa maxdevs +device numbers to +.Fa devs . +.It Fn pci_activate "pc" "tag" "dev" "fun" +Attempt to bring the device to state D0. +If the device is not in the D0 state call +.Fa fun +to restore its state. +If +.Fa fun +is +.Dv NULL +then restoring from state D3 is going to fail. +.It Fn pci_chipset_tag_create "opc" "present" "ov" "ctx" "pcp" +Create a copy of the tag +.Fa opc +at +.Fa *pcp . +Except for the behavior +overridden by +.Fa ov , +.Fa *pcp +inherits the behavior of +.Fa opc +under +.Nm +calls. +.Pp +.Fa ov +contains function pointers corresponding to +.Nm +routines. +Each function pointer has a corresponding bit in +.Fa present , +and if that bit is 1, the function pointer overrides the corresponding +.Nm +call for the new tag. +Any combination of these bits may be set in +.Fa present : +.Pp +.Bl -tag -width PCI_OVERRIDE_INTR_DISESTABLISH -compact +.It Dv PCI_OVERRIDE_CONF_READ +.It Dv PCI_OVERRIDE_CONF_WRITE +.It Dv PCI_OVERRIDE_INTR_MAP +.It Dv PCI_OVERRIDE_INTR_STRING +.It Dv PCI_OVERRIDE_INTR_EVCNT +.It Dv PCI_OVERRIDE_INTR_ESTABLISH +.It Dv PCI_OVERRIDE_INTR_DISESTABLISH +.It Dv PCI_OVERRIDE_MAKE_TAG +.It Dv PCI_OVERRIDE_DECOMPOSE_TAG +.El +.Pp +.Fn pci_chipset_tag_create +does not copy +.Fa ov . +After a new tag is created +by +.Fn pci_chipset_tag_create , +.Fa ov +must not be destroyed until after the +tag is destroyed by +.Fn pci_chipset_tag_destroy . +.Pp +The first argument of every override-function is a +.Vt "void *" , +and +.Fa ctx +is passed in that argument. +.Pp +Return 0 if the call succeeds. +Return +.Dv EOPNOTSUPP +if the architecture does not support overrides. +Return +.Dv EINVAL +if +.Fa present +is 0, if +.Fa ov +is +.Dv NULL , +or if +.Fa present +indicates that an override is present, but the corresponding override +in +.Fa ov +is +.Dv NULL . +.Pp +If the call does not succeed, +.Fa *pcp +is undefined. +.It Fn pci_chipset_tag_destroy "pc" +Destroy a tag, +.Fa pc , +created by a prior call to +.Fn pci_chipset_tag_create . +If +.Fa pc +was not created by +.Fn pci_chipset_tag_create , +results are undefined. +If +.Fa pc +was already destroyed, results are undefined. +.It Fn pci_conf_read "pc" "tag" "reg" +Read from register +.Fa reg +in PCI configuration space. +The argument +.Fa tag +is the PCI tag for the current device attached to PCI chipset +.Fa pc . +.It Fn pci_conf_write "pc" "tag" "reg" "val" +Write to register +.Fa reg +in PCI configuration space. +The argument +.Fa tag +is the PCI tag for the current device attached to PCI chipset +.Fa pc . +.It Fn pci_conf_print "pc" "tag" "func" +Print out most of the registers in the PCI configuration for the +device. +The argument +.Fa tag +is the PCI tag for the current device attached to PCI chipset +.Fa pc . +The argument +.Fa func +is a function called by +.Fn pci_conf_print +to print the device-dependent registers. +This function is only useful for driver development and is usually +wrapped in pre-processor declarations. +.It Fn pci_conf_capture "pc" "tag" "pcs" +Capture PCI configuration space into structure +.Fa pcs . +The argument +.Fa tag +is the PCI tag for the current device attached to the PCI +chipset +.Fa pc . +.It Fn pci_conf_restore "pc" "tag" "pcs" +Restores PCI configuration space from structure +.Fa pcs . +The argument +.Fa tag +is the PCI tag for the current device attached to the PCI +chipset +.Fa pc . +.It Fn pci_find_device "pa" "func" +Find a device using a match function on all probed busses. +The argument +.Fa func +is called by +.Fn pci_find_device +to match a device. +The argument +.Fa pa +is filled in if the device is matched. +.Fn pci_find_device +returns 1 if the device is matched, and zero otherwise. +This function is specifically for use by kernel modules +and its use otherwise is strongly discouraged. +.It Fn pci_get_capability "pc" "tag" "capid" "offsetp" "valuep" +Parse the device capability list in configuration space looking for +capability +.Fa capid . +If +.Fa offsetp +is not +.Dv NULL , +the register offset in configuration space is returned in +.Fa offsetp . +If +.Fa valuep +is not +.Dv NULL , +the value of the capability is returned in +.Fa valuep . +The argument +.Fa tag +is the PCI tag for the current device attached to PCI chipset +.Fa pc . +This function returns 1 if the capability was found. +If the capability was not found, it returns zero, and +.Fa offsetp +and +.Fa valuep +remain unchanged. +.It Fn pci_get_ht_capability "pc" "tag" "capid" "offsetp" "valuep" +Parse the device capability list in HyperTransport configuration +space looking for capability +.Fa capid . +If +.Fa offsetp +is not +.Dv NULL , +the register offset in configuration space is returned in +.Fa offsetp . +If +.Fa valuep +is not +.Dv NULL , +the value of the capability is returned in +.Fa valuep . +The argument +.Fa tag +is the PCI tag for the current device attached to PCI chipset +.Fa pc . +This function returns 1 if the capability was found. +If the capability was not found, it returns zero, and +.Fa offsetp +and +.Fa valuep +remain unchanged. +.It Fn pci_get_ext_capability "pc" "tag" "capid" "offsetp" "valuep" +Parse the device capability list in extended configuration space looking for +capability +.Fa capid . +If +.Fa offsetp +is not +.Dv NULL , +the register offset in extended configuration space is returned in +.Fa offsetp . +If +.Fa valuep +is not +.Dv NULL , +the value of the capability is returned in +.Fa valuep . +The argument +.Fa tag +is the PCI tag for the current device attached to PCI chipset +.Fa pc . +This function returns 1 if the capability was found. +If the capability was not found, it returns zero, and +.Fa offsetp +and +.Fa valuep +remain unchanged. +.It Fn pci_get_segment "pc" +Return the PCI segment number for PCI chipset +.Fa pc . +This machine-dependent function is only available if +.Dv __HAVE_PCI_GET_SEGMENT +is defined in the header +.In machine/pci_machdep.h . +.It Fn pci_mapreg_type "pc" "tag" "reg" +Interrogates the Base Address Register (BAR) in configuration space +specified by +.Fa reg +and returns the default (or current) mapping type. +Valid returns values are: +.Bl -tag -width compact +.It Dv PCI_MAPREG_TYPE_IO +The mapping is to I/O address space. +.It Dv PCI_MAPREG_TYPE_MEM +The mapping is to memory address space. +.It Dv PCI_MAPREG_TYPE_MEM | PCI_MAPREG_MEM_TYPE_64BIT +The mapping is to 64-bit memory address space. +.It Dv PCI_MAPREG_TYPE_ROM +The mapping is to ROM. +Note that in the current implementation, +.Dv PCI_MAPREG_TYPE_ROM +has the same numeric value as +.Dv PCI_MAPREG_TYPE_MEM . +.El +.Pp +The argument +.Fa tag +is the PCI tag for the current device attached to PCI chipset +.Fa pc . +.It Fn pci_mapreg_map "pa" "reg" "type" "busflags" "tagp" "handlep" "basep" "sizep" +Maps the register windows for the device into kernel virtual address +space. +This function is generally only called during the driver attach step +and takes a pointer to the +.Em struct pci_attach_args +in +.Fa pa . +The physical address of the mapping is in the Base Address Register +(BAR) in configuration space specified by +.Fa reg . +Valid values for the type of mapping +.Fa type , +which can be obtained from +.Fn pci_mapreg_type , +are: +.Bl -tag -width compact +.It Dv PCI_MAPREG_TYPE_IO +The mapping should be to I/O address space. +.It Dv PCI_MAPREG_TYPE_MEM +The mapping should be to memory address space. +.It Dv PCI_MAPREG_TYPE_MEM | PCI_MAPREG_MEM_TYPE_64BIT +The mapping should be to 64-bit memory address space. +.It Dv PCI_MAPREG_TYPE_ROM +The mapping is to access ROM. +This type of mapping is only permitted when the value for +.Fa reg +is +.Dv PCI_MAPREG_ROM . +.El +.Pp +The argument +.Fa busflags +are bus-space flags passed to +.Fn bus_space_map +to perform the mapping (see +.Xr bus_space 9 ) . +The bus-space tag and handle for the mapped register window are +returned in +.Fa tagp +and +.Fa handlep +respectively. +The bus-address and size of the mapping are returned in +.Fa basep +and +.Fa sizep +respectively. +If any of +.Fa tagp , +.Fa handlep , +.Fa basep , +or +.Fa sizep +are +.Dv NULL +then +.Fn pci_mapreg_map +does not define their return value. +This function returns zero on success and non-zero on error. +.It Fn pci_mapreg_info "pc" "tag" "reg" "type" "basep" "sizep" "flagsp" +Performs the same operations as +.Fn pci_mapreg_map +but doesn't actually map the register window into kernel virtual +address space. +Returns the bus-address, size and bus flags in +.Fa basep , +.Fa sizep +and +.Fa flagsp +respectively. +These return values can be used by +.Fn bus_space_map +to actually map the register window into kernel virtual address space. +This function is useful for setting up the registers in configuration +space and deferring the mapping to a later time, such as in a +bus-independent attachment routine. +.Fa pci_mapreg_info +returns zero on success and non-zero on failure. +.It Fn pci_find_rom "pa" "bst" "bsh" "code" "handlep" "sizep" +Locates a suitable ROM image within a PCI expansion ROM previously mapped with +.Fn pci_mapreg_map +and creates a subregion for it with +.Fn bus_space_subregion . +The +.Fa bst +and +.Fa bsh +arguments are the bus tag and handle obtained with the prior call to +.Fn pci_mapreg_map . +Valid values for the image type +.Fa code +are: +.Bl -tag -width compact +.It Dv PCI_ROM_CODE_TYPE_X86 +Find a ROM image containing i386 executable code for use by PC BIOS. +.It Dv PCI_ROM_CODE_TYPE_OFW +Find a ROM image containing Forth code for use by Open Firmware. +.It Dv PCI_ROM_CODE_TYPE_HPPA +Find a ROM image containing HP PA/RISC executable code. +.El +.Pp +The created subregion will cover the entire selected ROM image, including +header data. +The handle to this subregion is returned in +.Fa handlep . +The size of the image (and the corresponding subregion) is returned in +.Fa sizep . +This function can only be used with expansion ROMs located at the +.Dv PCI_MAPREG_ROM +base address register (BAR). +.It Fn pci_intr_map "pa" "ih" +See +.Xr pci_intr 9 . +.It Fn pci_intr_string "pc" "ih" +See +.Xr pci_intr 9 . +.It Fn pci_intr_evcnt "pc" "ih" +See +.Xr pci_intr 9 . +.It Fn pci_intr_establish "pc" "ih" "level" "handler" "arg" +See +.Xr pci_intr 9 . +.It Fn pci_intr_establish_xname "pc" "ih" "level" "handler" "arg" "xname" +See +.Xr pci_intr 9 . +.It Fn pci_intr_disestablish "pc" "ih" +See +.Xr pci_intr 9 . +.It Fn pci_intr_type "pc" "ih" +See +.Xr pci_msi 9 . +.It Fn pci_intr_setattr "pc" "ih" "attr" "data" +See +.Xr pci_intr 9 . +.It Fn pci_set_powerstate "pc" "tag" "newstate" +Set power state of the device to newstate. +Valid values for +.Fa newstate +are: +.Pp +.Bl -tag -width PCI_PMCSR_STATE_D0 -compact +.It Dv PCI_PMCSR_STATE_D0 +.It Dv PCI_PMCSR_STATE_D1 +.It Dv PCI_PMCSR_STATE_D2 +.It Dv PCI_PMCSR_STATE_D3 +.El +.It Fn pci_get_powerstate "pc" "tag" "state" +Get current power state of the device. +.It Fn pci_vpd_read "pc" "tag" "offset" "count" "data" +Read +.Fa count +32-bit words of Vital Product Data for the device starting at offset +.Fa offset +into the buffer pointed to by +.Fa data . +Returns 0 on success or non-zero if the device has no Vital Product Data +capability or if reading the Vital Product Data fails. +.It Fn pci_vpd_write "pc" "tag" "offset" "count" "data" +Write +.Fa count +32-bit words of Vital Product Data for the device starting at offset +.Fa offset +from the buffer pointed to by +.Fa data . +Returns 0 on success or non-zero if the device has no Vital Product Data +capability of if writing the Vital Product Data fails. +.It Fn pci_make_tag "pc" "bus" "device" "function" +Create a new PCI tag for the PCI device specified by the tuple +.Ao +bus, device, function +.Ac . +This function is not useful to the usual PCI device driver. +It is generally used by drivers of multi-function devices when +attaching other PCI device drivers to each function. +.It Fn pci_decompose_tag "pc" "tag" "busp" "devicep" "fnp" +Decompose the PCI tag +.Fa tag +generated by +.Fn pci_make_tag +into its +.Ao +bus, device, function +.Ac +tuple. +.It Fn pci_findvendor "id" +Return the string of the vendor name for the device specified by +.Fa id . +.It Fn pci_devinfo "id" "class" "show" "cp" "len" +Returns the description string from the in-kernel PCI database for the +device described by +.Fa id +and +.Fa class . +The description string is returned in +.Fa cp ; +the size of that storage is given in +.Fa len . +The argument +.Fa show +specifies whether the PCI subsystem should report the string to the +console. +.It Fn pci_aprint_devinfo "pa" "naive" +Print device information to the console and system log, using the +.Xr aprint_normal 9 +and +.Xr aprint_naive 9 +functions. +For the device information, the +.Dq pci_devinfo +function above is used, or the +.Ar naive +argument in the +.Dq AB_QUIET +case. +This function is intended to be used early in device attach. +.It Fn PCI_VENDOR "id" +Return the PCI vendor id for device +.Fa id . +.It Fn PCI_PRODUCT "id" +Return the PCI product id for device +.Fa id . +.It Fn PCI_REVISION "id" +Return the PCI product revision for device +.Fa id . +.El +.Sh AUTOCONFIGURATION +During autoconfiguration, a +.Nm +driver will receive a pointer to +.Fa struct pci_attach_args +describing the device attaches to the PCI bus. +Drivers match the device using the +.Fa pa_id +member using +.Fn PCI_VENDOR . +.Fn PCI_PRODUCT +and +.Fn PCI_REVISION . +.Pp +During the driver attach step, drivers can read the device +configuration space using +.Fn pci_conf_read . +The meaning attached to registers in the PCI configuration space are +device-dependent, but will usually contain physical addresses of the +device register windows. +Device options can also be stored into the PCI configuration space using +.Fn pci_conf_write . +For example, the driver can request support for bus-mastering DMA by +writing the option to the PCI configuration space. +.Pp +Device capabilities can be queried using +.Fn pci_get_capability , +and returns device-specific information which can be found in the PCI +configuration space to alter device operation. +.Pp +After reading the physical addresses of the device register windows +from configuration space, these windows must be mapped into kernel +virtual address space using +.Fn pci_mapreg_map . +Device registers can now be accessed using the standard bus-space API +(see +.Xr bus_space 9 ) . +.Pp +Details of using PCI interrupts is described in +.Xr pci_intr 9 . +.Sh DMA SUPPORT +The PCI bus supports bus-mastering operations from any device on the bus. +The DMA facilities are accessed through the standard +.Xr bus_dma 9 +interface. +To support DMA transfers from the device to the host, it is necessary +to enable bus-mastering in the PCI configuration space for the device. +.Pp +During system shutdown, it is necessary to abort any DMA transfers in +progress by registering a shutdown hook (see +.Xr pmf 9 ) . +.Sh CODE REFERENCES +The PCI subsystem itself is implemented within the files +.Pa sys/dev/pci/pci.c , +.Pa sys/dev/pci/pci_subr.c , +.Pa sys/dev/pci/pci_map.c , +.Pa sys/dev/pci/pci_quirks.c , +and +.Pa sys/dev/pci/pciconf.c . +Machine-dependent portions are implemented within the file +.Pa sys/arch/<arch>/pci/pci_machdep.c . +.Pp +The database of known devices exists within the file +.Pa sys/dev/pci/pcidevs_data.h +and is generated automatically from the file +.Pa sys/dev/pci/pcidevs . +New vendor and product identifiers should be added to this file. +The database can be regenerated using the Makefile +.Pa sys/dev/pci/Makefile.pcidevs . +.Sh SEE ALSO +.Xr pci 4 , +.Xr autoconf 9 , +.Xr bus_dma 9 , +.Xr bus_space 9 , +.Xr driver 9 , +.Xr pci_configure_bus 9 , +.Xr pci_intr 9 , +.Xr pci_msi 9 , +.Xr pmf 9 +.Sh HISTORY +The machine-independent PCI subsystem appeared in +.Nx 1.2 . diff --git a/static/netbsd/man9/pci_configure_bus.9 b/static/netbsd/man9/pci_configure_bus.9 new file mode 100644 index 00000000..56037e5a --- /dev/null +++ b/static/netbsd/man9/pci_configure_bus.9 @@ -0,0 +1,303 @@ +.\" $NetBSD: pci_configure_bus.9,v 1.20 2020/08/27 14:14:00 fcambus Exp $ +.\" +.\" Copyright 2001 Wasabi Systems, Inc. +.\" All rights reserved. +.\" +.\" Written by Allen Briggs for Wasabi Systems, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project by +.\" Wasabi Systems, Inc. +.\" 4. The name of Wasabi Systems, Inc. may not be used to endorse +.\" or promote products derived from this software without specific prior +.\" written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL WASABI SYSTEMS, INC +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 7, 2020 +.Dt PCI_CONFIGURE_BUS 9 +.Os +.Sh NAME +.Nm pci_configure_bus , +.Nm pci_conf_hook , +.Nm pci_conf_interrupt , +.Nm pciconf_resource_init , +.Nm pciconf_resource_add , +.Nm pciconf_resource_fini +.Nd perform PCI bus configuration +.Sh SYNOPSIS +.In dev/pci/pciconf.h +.Ft int +.Fn pci_configure_bus "pci_chipset_tag_t pc" "struct pciconf_resources *res" \ + "int firstbus" "int cacheline_size" +.Ft struct pciconf_resources * +.Fn pciconf_resource_init "void" +.Ft void +.Fn pciconf_resource_add "struct pciconf_resources *res" "int type" \ + "bus_addr_t addr" "bus_size_t size" +.Ft void +.Fn pciconf_resource_fini "struct pciconf_resources *res" +.Sh DESCRIPTION +The +.Fn pci_configure_bus +function configures a PCI bus for use. +This involves: +.Bl -bullet +.It +Defining bus numbers for all busses on the system, +.It +Setting the Base Address Registers for all devices, +.It +Setting up the interrupt line register for all devices, +.It +Configuring bus latency timers for all devices, and +.It +Configuring cacheline sizes for all devices. +.El +.Pp +In traditional PCs and Alpha systems, the BIOS or firmware takes care +of this task, but that is not the case for all systems. +.Fn pci_configure_bus +should be called prior to the autoconfiguration of the bus. +.Pp +The +.Fa pc +argument is a machine-dependent tag used to specify the PCI chipset to the +system. +This should be the same value used with +.Fn pci_make_tag . +The +.Fa res +argument is a container for PCI bus resources that will be used to +configure the bus. +The +.Fa firstbus +argument indicates the number of the first bus to be configured. +The +.Fa cacheline_size +argument is used to configure the PCI Cache Line Size Register; it +should be the size, in bytes, of the largest D-cache line on the system. +.Pp +An implementation may choose to not have full configuration performed +by +.Fn pci_configure_bus +on certain PCI devices, such as PCI host bridges or PCI bus analyzers +which are instantiated as devices on the bus. +In order for this to take place, the header +.In machine/pci_machdep.h +must define the +.Dv __HAVE_PCI_CONF_HOOK +symbol (without a value), and a machine-dependent function +.Fn pci_conf_hook +(declared in the same header) +must be defined. +The prototype for this function is: +.Pp +.Ft int +.Fn "pci_conf_hook" "pci_chipset_tag_t pc" "int bus" \ + "int device" "int function" "pcireg_t id" ; +.Pp +In this function, +.Fa bus , +.Fa device , +and +.Fa function +uniquely identify the item being configured; +in addition to this, the value of the device's PCI identification +register is passed in +.Fa id . +For each device +.Fn pci_conf_hook +can then decide upon the amount of configuration to be performed by +returning a bitwise inclusive-or of the following flags: +.Bl -tag -width PCI_CONF_ENABLE_MEM -offset indent +.It Dv PCI_CONF_MAP_IO +Configure Base Address Registers that map I/O space +.It Dv PCI_CONF_MAP_MEM +Configure Base Address Registers that map memory space +.It Dv PCI_CONF_MAP_ROM +Configure Expansion ROM Base Address register +.It Dv PCI_CONF_ENABLE_IO +Enable I/O space accesses +.It Dv PCI_CONF_ENABLE_MEM +Enable memory space accesses +.It Dv PCI_CONF_ENABLE_BM +Enable bus mastering +.El +.Pp +In addition, +.Dv PCI_CONF_ALL +specifies all of the above. +.Pp +One of the functions of +.Fn pci_configure_bus +is to configure interrupt +.Dq line +information. +This must be done on a machine-dependent basis, so a +machine-dependent function +.Fn pci_conf_interrupt +must be defined. +The prototype for this function is +.Pp +.Ft void +.Fn "pci_conf_interrupt" "pci_chipset_tag_t pc" "int bus" \ + "int device" "int pin" "int swiz" "int *iline" +.Pp +In this function, +.Fa bus , +.Fa device , +and +.Fa pin , +uniquely identify the item being configured. +The +.Fa swiz +argument is a +.Dq swizzle , +a sum of the device numbers of the primary interface of the bridges between +the host bridge and the current device. +The function is responsible for setting the value of +.Fa iline . +See chapter 9 of the +.Dq PCI-to-PCI Bridge Architecture Specification +for more information on swizzling (also known as interrupt routing). +.Pp +The resources used to configure the PCI bus are encapsulated into a +resource container. +The +.Fn pciconf_resource_init +function allocates and initializes one of these containers, and the +.Fn pciconf_resource_add +function adds resources to the container, specifying the type, start +address, and size of the resource being added. +The following resource types are supported: +.Bl -tag -width PCICONF_RESOURCE_PREFETCHABLE_MEM -offset indent +.It Dv PCICONF_RESOURCE_IO +An address region used for PCI I/O accesses. +.It Dv PCICONF_RESOURCE_MEM +An address region used for PCI memory accesses where reads may have side +effects. +.It Dv PCICONF_RESOURCE_PREFETCHABLE_MEM +An address region used for PCI memory accesses where reads do not have +side effects +.Po +e.g. ROMs, frame buffers, other memory-like regions that are marked as +prefetchable in their BAR +.Pc . +.El +.Pp +If an implementation does not distinguish between prefetchable and +non-prefetchable memory, then adding a +.Dv PCICONF_RESOURCE_PREFETCHABLE_MEM +resource is not required; +.Dv PCICONF_RESOURCE_MEM +resources will be used for ROMs and BARs that are marked as prefetchable. +.Pp +Once the bus has been successfully configured, the resource container should +be disposed of by calling +.Fn pciconf_resource_fini . +.Sh RETURN VALUES +If successful +.Fn pci_configure_bus +returns 0. +A non-zero return value means that the bus was not completely +configured for some reason. +A description of the failure will be displayed on the console. +.Sh ENVIRONMENT +The +.Fn pci_configure_bus +function is only included in the kernel if the kernel is compiled with +the +.Dv PCI_NETBSD_CONFIGURE +option enabled. +.Sh EXAMPLES +The +.Fn pci_conf_hook +function in evbppc's walnut implementation looks like: +.Pp +.Bd -literal -compact +int +pci_conf_hook(pci_chipset_tag_t pc, int bus, int dev, int func, + pcireg_t id) +{ + + if ((PCI_VENDOR(id) == PCI_VENDOR_IBM && + PCI_PRODUCT(id) == PCI_PRODUCT_IBM_405GP) || + (PCI_VENDOR(id) == PCI_VENDOR_INTEL && + PCI_PRODUCT(id) == PCI_PRODUCT_INTEL_80960_RP)) { + /* Don't configure the bridge and PCI probe. */ + return 0; + } + return (PCI_CONF_ALL & ~PCI_CONF_MAP_ROM); +} +.Ed +.Pp +The +.Fn pci_conf_interrupt +function in the sandpoint implementation looks like: +.Pp +.Bd -literal -compact +void +pci_conf_interrupt(pci_chipset_tag_t pc, int bus, int dev, int pin, + int swiz, int *iline) +{ + if (bus == 0) { + *iline = dev; + } else { + *iline = 13 + ((swiz + dev + 3) & 3); + } +} +.Ed +.Pp +This configuration example is taken from the bebox port. +.Pp +.Bd -literal -compact +#define PCI_IO_START 0x00008000 +#define PCI_IO_END 0x0000ffff +#define PCI_IO_SIZE ((PCI_IO_END - PCI_IO_START) + 1) + +#define PCI_MEM_START 0x00000000 +#define PCI_MEM_END 0x0fffffff +#define PCI_MEM_SIZE ((PCI_MEM_END - PCI_MEM_START) + 1) + ... + struct pciconf_resources *pcires; + ... + pcires = pciconf_resource_init(); + pciconf_resource_add(pcires, PCICONF_RESOURCE_IO, + PCI_IO_START, PCI_IO_SIZE); + pciconf_resource_add(pcires, PCICONF_RESOURCE_MEM, + PCI_MEM_START, PCI_MEM_SIZE); + ... + pci_configure_bus(pc, pcires, 0, CACHELINESIZE); + ... + pciconf_resource_fini(pcires); + ... +.Ed +.Pp +Note that this must be called before the PCI bus is attached during +autoconfiguration. +.Sh SEE ALSO +.Xr pci 4 +.Sh HISTORY +.Fn pci_configure_bus +was added in +.Nx 1.6 . diff --git a/static/netbsd/man9/pci_intr.9 b/static/netbsd/man9/pci_intr.9 new file mode 100644 index 00000000..9d48dd78 --- /dev/null +++ b/static/netbsd/man9/pci_intr.9 @@ -0,0 +1,208 @@ +.\" $NetBSD: pci_intr.9,v 1.27 2020/08/27 14:14:00 fcambus Exp $ +.\" +.\" Copyright (c) 2000 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Bill Sommerfeld +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 20, 2018 +.Dt PCI_INTR 9 +.Os +.Sh NAME +.Nm pci_intr , +.Nm pci_intr_map , +.Nm pci_intr_string , +.Nm pci_intr_evcnt , +.Nm pci_intr_establish , +.Nm pci_intr_establish_xname , +.Nm pci_intr_disestablish , +.Nm pci_intr_setattr +.Nd PCI bus interrupt manipulation functions +.Sh SYNOPSIS +.In dev/pci/pcivar.h +.Ft int +.Fn pci_intr_map "const struct pci_attach_args *pa" "pci_intr_handle_t *ih" +.Ft const char * +.Fn pci_intr_string "pci_chipset_tag_t pc" "pci_intr_handle_t ih" "char *buf" "size_t len" +.Ft const struct evcnt * +.Fn pci_intr_evcnt "pci_chipset_tag_t pc" "pci_intr_handle_t ih" +.Ft void * +.Fn pci_intr_establish "pci_chipset_tag_t pc" "pci_intr_handle_t ih" \ +"int ipl" "int (*intrhand)(void *)" "void *intrarg" +.Ft void * +.Fn pci_intr_establish_xname "pci_chipset_tag_t pc" "pci_intr_handle_t ih" \ +"int ipl" "int (*intrhand)(void *)" "void *intrarg" "const char *xname" +.Ft void +.Fn pci_intr_disestablish "pci_chipset_tag_t pc" "void *ih" +.Ft int +.Fn pci_intr_setattr "pci_chipset_tag_t pc" "pci_intr_handle_t *ih" "int attr" "uint64_t data" +.Sh DESCRIPTION +The +.Nm +functions exist to allow device drivers machine-independent access to +PCI bus interrupts. +The functions described in this page are typically declared in a port's +.In machine/pci_machdep.h +header file; however, drivers should generally include +.In dev/pci/pcivar.h +to get other PCI-specific declarations as well. +.Pp +Each driver has an +.Fn attach +function which has a bus-specific +.Ft attach_args +structure. +Each driver for a PCI device is passed a pointer to an object of type +.Ft struct pci_attach_args +which contains, among other things, information about the location +of the device in the PCI bus topology sufficient to allow interrupts +from the device to be handled. +.Pp +If a driver wishes to establish an interrupt handler for the device, +it should pass the +.Ft struct pci_attach_args * +to the +.Fn pci_intr_map +function, which returns zero on success, and nonzero on failure. +The function sets the +.Ft pci_intr_handle_t +pointed at by its second argument to a machine-dependent value which +identifies a particular interrupt source. +.Pp +If the driver wishes to refer to the interrupt source in an attach or +error message, it should use the value returned by +.Fn pci_intr_string . +The buffer passed to +.Fn pci_intr_string +should be at least +.Dv PCI_INTRSTR_LEN +bytes. +.Pp +Subsequently, when the driver is prepared to receive interrupts, it +should call +.Fn pci_intr_establish +to actually establish the handler; when the device interrupts, +.Fa intrhand +will be called with a single argument +.Fa intrarg , +and will run at the interrupt priority level +.Fa ipl . +.Pp +The return value of +.Fn pci_intr_establish +may be saved and passed to +.Fn pci_intr_disestablish +to disable the interrupt handler +when the driver is no longer interested in interrupts from the device. +.Pp +.Fn pci_intr_establish_xname +is almost the same as +.Fn pci_intr_establish . +The difference is only +.Fa xname +which is used by +.Xr intrctl 8 +to show the device name(s) of the interrupt id. +.Pp +The +.Fn pci_intr_setattr +function sets an attribute +.Fa attr +of the interrupt handler to +.Fa data . +Currently, only the following attribute is supported: +.Bl -tag -width PCI_INTR_MPSAFE +.It Dv PCI_INTR_MPSAFE +If this attribute is set to +.Dv true , +it specifies that the interrupt handler is multiprocessor safe and works its +own locking; otherwise the kernel lock will be held for the call to the +interrupt handler. +The default is +.Dv false . +.El +.Pp +The +.Fn pci_intr_setattr +function returns zero on success, and nonzero on failure. +.Pp +The +.Fn pci_intr_evcnt +function should return an evcnt structure pointer or +.Dv NULL +if there is no evcnt associated with this interrupt. +See +.Xr evcnt 9 +for more details. +.Ss PORTING +A port's implementation of +.Fn pci_intr_map +may use the following members of +.Ft struct pci_attach_args +to determine how the device's interrupts are routed. +.Bd -literal + pci_chipset_tag_t pa_pc; + pcitag_t pa_tag; + pcitag_t pa_intrtag; /* intr. appears to come from here */ + pci_intr_pin_t pa_intrpin; /* intr. appears on this pin */ + pci_intr_line_t pa_intrline; /* intr. routing information */ + pci_intr_pin_t pa_rawintrpin; /* unswizzled pin */ +.Ed +.Pp +PCI-PCI +bridges swizzle (permute) interrupt wiring. +Depending on implementation details, it may be more convenient to use +either original or the swizzled interrupt parameters. +The original device tag and interrupt pin can be found in +.Ft pa_tag +and +.Ft pa_rawintrpin +respectively, while the swizzled tag and pin can be found in +.Ft pa_intrtag +and +.Ft pa_intrpin . +.Pp +When a device is attached to a primary bus, both pairs of fields +contain the same values. +When a device is found behind one or more pci-pci bridges, +.Ft pa_intrpin +contains the +.Dq swizzled +interrupt pin number, while +.Ft pa_rawintrpin +contains the original interrupt pin; +.Ft pa_tag +contains the PCI tag of the device itself, and +.Ft pa_intrtag +contains the PCI tag of the uppermost bridge device. +.Sh SEE ALSO +.Xr evcnt 9 , +.Xr pci 9 , +.Xr pci_msi 9 +.Sh HISTORY +.Fn pci_intr_establish_xname +was added in +.Nx 8.0 +as part of MSI/MSI-X support. diff --git a/static/netbsd/man9/pci_msi.9 b/static/netbsd/man9/pci_msi.9 new file mode 100644 index 00000000..43988809 --- /dev/null +++ b/static/netbsd/man9/pci_msi.9 @@ -0,0 +1,341 @@ +.\" $NetBSD: pci_msi.9,v 1.18 2021/01/12 05:08:50 knakahara Exp $ +.\" +.\" Copyright (c) 2015 Internet Initiative Japan Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 12, 2021 +.Dt PCI_MSI 9 +.Os +.Sh NAME +.Nm pci_msi , +.Nm pci_msix , +.Nm pci_msi_count , +.Nm pci_msi_alloc , +.Nm pci_msi_alloc_exact , +.Nm pci_msix_count , +.Nm pci_msix_alloc , +.Nm pci_msix_alloc_exact , +.Nm pci_msix_alloc_map , +.Nm pci_intx_alloc , +.Nm pci_intr_alloc , +.Nm pci_intr_release , +.Nm pci_intr_type +.Nd PCI MSI{,-X} manipulation functions +.Sh SYNOPSIS +.Ft int +.Fn pci_msi_count "pci_chipset_tag_t pc" \ +"pcitag_t tag" +.Ft int +.Fn pci_msi_alloc "const struct pci_attach_args *pa" \ +"pci_intr_handle_t **ihps" "int *count" +.Ft int +.Fn pci_msi_alloc_exact "const struct pci_attach_args *pa" \ +"pci_intr_handle_t **ihps" "int count" +.Ft int +.Fn pci_msix_count "pci_chipset_tag_t pc" \ +"pcitag_t tag" +.Ft int +.Fn pci_msix_alloc "const struct pci_attach_args *pa" \ +"pci_intr_handle_t **ihps" "int *count" +.Ft int +.Fn pci_msix_alloc_exact "const struct pci_attach_args *pa" \ +"pci_intr_handle_t **ihps" "int count" +.Ft int +.Fn pci_msix_alloc_map "const struct pci_attach_args *pa" \ +"pci_intr_handle_t **ihps" "u_int *table_indexes" "int count" +.Ft int +.Fn pci_intx_alloc "const struct pci_attach_args *pa" \ +"pci_intr_handle_t **ihp" +.Ft int +.Fn pci_intr_alloc "const struct pci_attach_args *pa" \ +"pci_intr_handle_t **ihp" "int *counts" \ +"pci_intr_type_t max_type" +.Ft void +.Fn pci_intr_release "pci_chipset_tag_t pc" \ +"pci_intr_handle_t *pih" "int count" +.Ft pci_intr_type_t +.Fn pci_intr_type "pci_chipset_tag_t pc" \ +"pci_intr_handle_t ih" +.Sh DESCRIPTION +The +.Nm +functions exist to allow device drivers to use MSI/MSI-X. +When the system uses MSI/MSI-X, it must define the +.Dv __HAVE_PCI_MSI_MSIX +build option. +.Pp +Each driver has an +.Fn attach +function which has a bus-specific +.Ft attach_args +structure. +Each driver for a PCI device is passed a pointer to an object of type +.Ft struct pci_attach_args +which contains, among other things, information about the location +of the device in the PCI bus topology sufficient to allow interrupts +from the device to be handled. +.Pp +.Fn pci_msi_count +returns the max number of the device's MSI. +If the device can not use MSI, +.Fn pci_msi_count +returns zero. +.Fn pci_msix_count +works in the same manner for MSI-X. +.Pp +If a driver wishes to establish an MSI handler for the device, +it should pass the +.Ft struct pci_attach_args * +and +.Fa count +.Fn pci_msi_alloc +or +.Fn pci_msi_alloc_exact +functions, which return zero on success, and nonzero on failure. +When the functions are successful, they return the pointer to the +allocated handle array in +.Ft pihs +whose size is +.Ft count +or less. +The difference between +.Fn pci_msi_alloc +and +.Fn pci_msi_alloc_exact +is whether +.Fa count +can be decremented or not. +.Fn pci_msi_alloc +can decrement +.Fa count , +and which is similar to +.Fx Ap s +.Fn pci_alloc_msi . +In contrast, +.Fn pci_msi_alloc_exact +can not decrement +.Ft count . +.Pp +If the driver wishes to refer to the MSI source in an attach or +error message, it should use the value returned by +.Fn pci_intr_string +the same as INTx. +The buffer passed to +.Fn pci_intr_string +should be at least +.Dv PCI_INTRSTR_LEN +bytes long. +.Pp +Subsequently, when the driver is prepared to receive MSIs, it +should call +.Fn pci_intr_establish +the same as INTx to actually establish the handler; +when the device interrupts, +.Fa intrhand +will be called with a single argument +.Fa intrarg , +and will run at the interrupt priority level +.Fa ipl . +.Pp +The return value of +.Fn pci_intr_establish +may be saved and passed to +.Fn pci_intr_disestablish +to disable the interrupt handler the same as INTx +when the driver is no longer interested in MSIs from the device. +After that, the driver should also call +.Fn pci_intr_release +to free resources about MSI as well as INTx and MSI-X. +If +.Fa pih +is NULL, +.Fn pci_intr_release +does nothing. +.Pp +If a driver wishes to establish an MSI-X handler for the device, +it is almost the same as MSI. +The only differences is +.Fn pci_msix_alloc_map . +This function can assign separate handlers for each MSI-X table +entry. +I.e., if the driver wants to assign the handlers in the following way: +.Bd -literal + msix_handler0 => MSI-X table index: 4 + msix_handler1 => MSI-X table index: 5 + msix_handler2 => MSI-X table index: 0 +.Ed +the driver should set +.Fa table_indexes +this way: +.Bd -literal + table_indexes[0] = 4; + table_indexes[1] = 5; + table_indexes[2] = 0; +.Ed +.Pp +If the driver wants to fall back to INTx, the driver should use +.Fn pci_intx_alloc +and +.Fn pci_intr_release +instead of +.Fn pci_intr_map +to resolve contradiction of the interrupt handler ownership. +I.e., +.Fn pci_intr_map +does not have the ownership (the function just calculates value), +in contrast, +.Fn pci_msi_alloc +and +.Fn pci_msix_alloc +have (the functions allocate memory for interrupt handlers). +.Pp +.Fn pci_intr_alloc +is wrapper function which select and automatically fallback +allocation functions according to the argument +.Fa counts . +The elements of +.Fa counts +array means each required interrupt count for INTx, MSI, and MSI-X. +The index count of +.Fa counts +must be +.Dv PCI_INTR_TYPE_SIZE . +.Fa max_type +must be +.Dv PCI_INTR_TYPE_MSIX , +.Dv PCI_INTR_TYPE_MSI , +or +.Dv PCI_INTR_TYPE_INTX . +The parameter does not mean array index counts of +.Fa counts . +The parameter means the interrupt type which +.Fn pci_intr_alloc +tries to allocate first. +I.e., if the driver wants to allocate interrupts in the following way: +.Bd -literal + 5 MSI-X + 1 MSI (if MSI-X allocation failed) + INTx (if MSI allocation failed either) +.Ed +the driver should call +.Fn pci_intr_alloc +in the following way: +.Bd -literal + int counts[PCI_INTR_TYPE_SIZE]; + counts[PCI_INTR_TYPE_MSIX] = 5; + counts[PCI_INTR_TYPE_MSI] = 1; + counts[PCI_INTR_TYPE_INTX] = 1; + error = pci_intr_alloc(pa, ihps, counts, + PCI_INTR_TYPE_MSIX); +.Ed +If the driver wants to allocate interrupts in the following way: +.Bd -literal + hardware max number MSI-X + 1 MSI (if MSI-X allocation failed) +.Ed +that is, the driver does not use INTx, the driver should call +.Fn pci_intr_alloc +in the following way: +.Bd -literal + int counts[PCI_INTR_TYPE_SIZE]; + counts[PCI_INTR_TYPE_MSIX] = -1; /* -1 means max */ + counts[PCI_INTR_TYPE_MSI] = 1; + counts[PCI_INTR_TYPE_INTX] = 0; /* 0 means not use */ + error = pci_intr_alloc(pa, ihps, counts, + PCI_INTR_TYPE_MSIX); +.Ed +If the driver wants to allocate interrupts in the following way: +.Bd -literal + 3 MSI + INTx (if MSI allocation failed) +.Ed +that is, the driver does not use MSI-X, the driver should call +.Fn pci_intr_alloc +in the following way: +.Bd -literal + int counts[PCI_INTR_TYPE_SIZE]; + counts[PCI_INTR_TYPE_MSIX] = 0; /* 0 means not use */ + counts[PCI_INTR_TYPE_MSI] = 3; + counts[PCI_INTR_TYPE_INTX] = 1; + error = pci_intr_alloc(pa, ihps, counts, + PCI_INTR_TYPE_MSI); +.Ed +If the driver wants to allocate interrupts in the following way: +.Bd -literal + 1 MSI-X + 1 MSI + INTx (if MSI/MSI-X allocation failed) +.Ed +that is, general usage, the driver should call simply +.Fn pci_intr_alloc +in the following way: +.Bd -literal + error = pci_intr_alloc(pa, ihps, NULL, 0); +.Ed +.Fa max_type +is ignored in this case. +.Fn pci_intr_alloc +returns zero on any allocation function success, and non-zero on +all allocation function failures. +On success, +.Fa counts +is overwritten by a really allocated count. +I.e., if 5 MSI-X is allocated, +.Fa counts +is +.Bd -literal + counts[PCI_INTR_TYPE_MSIX] == 5 + counts[PCI_INTR_TYPE_MSI] == 0 + counts[PCI_INTR_TYPE_INTX] == 0 +.Ed +on return. +.Pp +.Fn pci_intr_type +returns the interrupt type of +.Fa ih . +The return value is +.Dv PCI_INTR_TYPE_MSIX +for MSI-X, +.Dv PCI_INTR_TYPE_MSI +for MSI, and +.Dv PCI_INTR_TYPE_INTX +for others. +.Sh SEE ALSO +.Xr pci_intr 9 +.Sh HISTORY +.Nm +support first appeared in +.Nx 8.0 . +Support is present on +.Em i386 , +.Em amd64 +and +.Em aarch64 +architectures. +.Sh AUTHORS +The +.Nm +interfaces were designed and implemented by +.An Kengo Nakahara +.Aq Mt knakahara@NetBSD.org . diff --git a/static/netbsd/man9/pckbport.9 b/static/netbsd/man9/pckbport.9 new file mode 100644 index 00000000..9a00360e --- /dev/null +++ b/static/netbsd/man9/pckbport.9 @@ -0,0 +1,330 @@ +.\" $NetBSD: pckbport.9,v 1.5 2009/03/09 19:24:32 joerg Exp $ +.\" +.\" Copyright (c) 2004 Ben Harris +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 5, 2004 +.Dt PCKBPORT 9 +.Os +.Sh NAME +.Nm pckbport , +.Nm pckbport_attach , +.Nm pckbport_attach_slot , +.Nm pckbport_cnattach , +.Nm pckbportintr , +.Nm pckbport_set_inputhandler , +.Nm pckbport_flush , +.Nm pckbport_poll_cmd , +.Nm pckbport_enqueue_cmd , +.Nm pckbport_poll_data , +.Nm pckbport_set_poll , +.Nm pckbport_xt_translation , +.Nm pckbport_slot_enable +.Nd PC keyboard port interface +.Sh SYNOPSIS +.In dev/pckbport/pckbportvar.h +.Ft pckbport_tag_t +.Fn pckbport_attach "void *" "struct pckbport_accessops const *" +.Ft "struct device *" +.Fn pckbport_attach_slot "struct device *" pckbport_tag_t pckbport_slot_t +.Ft int +.Fn pckbport_cnattach "void *" "struct pckbport_accessops const *" \ +pckbport_slot_t +.Ft void +.Fn pckbportintr pckbport_tag_t pckbport_slot_t int +.Ft void +.Fn pckbport_set_inputhandler pckbport_tag_t pckbport_slot_t \ +pckbport_inputfcn "void *" "char *" +.Ft void +.Fn pckbport_flush pckbport_tag_t pckbport_slot_t +.Ft int +.Fn pckbport_poll_cmd pckbport_tag_t pckbport_slot_t "u_char *" int int \ +"u_char *" int +.Ft int +.Fn pckbport_enqueue_cmd pckbport_tag_t pckbport_slot_t "u_char *" int int \ +int "u_char *" +.Ft int +.Fn pckbport_poll_data pckbport_tag_t pckbport_slot_t +.Ft void +.Fn pckbport_set_poll pckbport_tag_t pckbport_slot_t int +.Ft int +.Fn pckbport_xt_translation pckbport_tag_t pckbport_slot_t int +.Ft void +.Fn pckbport_slot_enable pckbport_tag_t pckbport_slot_t int +.Sh DESCRIPTION +The machine-independent +.Nm +subsystem provides an interface layer corresponding to the serial +keyboard and mouse interface used on the +.Tn IBM PS/2 +and many other machines. +It interfaces a controller driver such as +.Xr pckbc 4 +to device drivers such as +.Xr pckbd 4 +and +.Xr pms 4 . +.Pp +A single controller can have up to two ports (known as +.Dq slots ) , +and these are identified by values of type +.Fa pckbport_slot_t . +The values +.Dv PCKBPORT_KBD_SLOT +and +.Dv PCKBPORT_AUX_SLOT +should be used for keyboard and mouse ports respectively. +Each controller is identified by an opaque value of type +.Fa pckbport_tag_t . +.Ss Controller interface +A PC keyboard controller registers itself by calling +.Fn pckbport_attach cookie ops , +with +.Fa ops +being a pointer to a +.Fa struct pckbport_accessops +containing pointers to functions for driving the controller, which will +all be called with +.Fa cookie +as their first argument. +.Fn pckbport_attach +returns the +.Fa pckbport_tag_t +assigned to the controller. +The controller is then expected to call +.Fn pckbport_attach_slot +for each slot with which it is equipped, passing the +.Fa "struct device *" +corresponding to the controller. +This function returns a pointer to the child device attached to the slot, +or +.Dv NULL +if no such device was attached. +.Pp +The elements of +.Fa "struct pckbport_accessops" +each take as their first two arguments the +.Fa cookie +passed to +.Fn pckbport_attach +and the slot in question. +The elements are: +.Bl -tag -width Fn +.It Fa int Fn (*t_xt_translation) "void *cookie" "pckbport_slot_t slot" \ +"int on" +If +.Fa on +is non-zero, enable, otherwise disable, AT-to-XT keycode translation +on the slot specified. +Returns 1 on success, 0 on failure (or if the controller does not support such +translation). +.It Fa int Fn (*t_send_devcmd) "void *cookie" "pckbport_slot_t slot" \ +"u_char byte" +Send a single +.Fa byte +to the device without waiting for completion. +Returns 1 on success, 0 on failure. +.It Fa int Fn (*t_poll_data1) "void *cookie" "pckbport_slot_t slot" +Wait for and return one byte of data from the device, without using interrupts. +This function will only be called after +.Fn "(*t_set_poll)" +has been used to put the slot in polling mode. +If no data are forthcoming from the device after about 100ms, return \-1. +.It Fa void Fn (*t_slot_enable) "void *cookie" "pckbport_slot_t slot" "int on" +If +.Fa on +is non-zero, enable, otherwise disable, the slot. +If a slot is disabled, it can be powered down, and is not expected to +generate any interrupts. +When first attached, ports should be disabled. +.It Fa void Fn (*t_intr_establish) "void *cookie" "pckbport_slot_t slot" +Set up an interrupt handler for the slot. +Called when a device gets attached to it. +.It Fa void Fn (*t_set_poll) "void *cookie" "pckbport_slot_t slot" "int on" +If +.Fa on +is non-zero, enable, otherwise disable, polling mode on the slot. +In polling mode, data received from the device are provided to +.Fn (*t_poll_data1) +and not passed to +.Fn pckbportintr , +whether or not interrupts are enabled. +In non-polling mode, +data from the device are expected to cause interrupts. +The controller interrupt handler should call +.Fn pckbportintr tag slot byte +once for each +.Va byte +received from the device. +When first attached, a port should be in non-polling mode. +.El +.Ss Device interface +Devices that attach to +.Nm +controllers do so using the normal +.Xr autoconf 9 +mechanism. +Their +.Fn (*ca_match) +and +.Fn (*ca_attach) +functions get passed a +.Fa "struct pckbport_attach_args" +which contains the controller and slot number where the device was found. +Device drivers can use the following functions to communicate with the +controller. +Each takes +.Fa tag +and +.Fa slot +arguments to specify the slot to be acted on. +.Bl -tag -width Fn +.It Fn pckbport_set_inputhandler tag slot fn arg name +Arrange for +.Fa fn +to be called with argument +.Fa arg +whenever an unsolicited byte is received from the slot. +The function will be called at +.Fn spltty . +.It Fn pckbport_flush tag slot +Ensure that there is no pending input from the slot. +.It Fn pckbport_poll_cmd tag slot cmd len responselen respbuf slow +Issue a complete device command, +.Fa cmd , +.Fa len +bytes long, expecting a response +.Fa responselen +bytes long, which will be placed in +.Fa respbuf . +If +.Fa slow +is true, the command is expected to take over a second to execute. +.Fn pckbport_poll_cmd +handles getting an acknowledgement from the device and retrying the command +if necessary. +Returns 0 on success, and an error value on failure. +This function should only be called during autoconfiguration or when the +slot has been placed into polling mode by +.Fn pckbport_set_poll . +.It Fn pckbport_enqueue_cmd tag slot cmd len responselen sync respbuf +Issue a complete device command, +.Fa cmd , +.Fa len +bytes long, expecting a response +.Fa responselen +bytes long, which will be places in +.Fa respbuf . +If +.Fa sync +is true, +.Fn pckbport_enqueue_cmd +waits for the command to complete before returning, otherwise it returns +immediately. +It is not safe to set +.Fa sync +when calling from an interrupt context. +The +.Nm pckbport +layer handles getting an acknowledgement from the device and retrying +the command if necessary. +Returns 0 on success, and an error value on failure. +.It Fn pckbport_poll_data tag slot +Low-level command to poll for a single byte of data from the device, but +ignoring bytes that are part of the response to a command issued through +.Fn pckbport_enqueue_command . +.It Fn pckbport_set_poll tag slot on +If +.Fa on +is true, enable polling on the slot, otherwise disable it. +In polling mode, +.Fn pckbport_poll_cmd +can be used to issue commands and +.Fn pckbport_poll_data +to read unsolicited data, without enabling interrupts. +In non-polling mode, commands should be issued using +.Fn pckbport_enqueue_cmd , +unsolicited data are handled by the input function, and disabling interrupts +will suspend +.Nm +operation. +.It Fn pckbport_xt_translation tag slot on +Passthrough of +.Fn (*t_xt_translation) +(see above). +.It Fn pckbport_slot enable tag slot on +Passthrough of +.Fn (*t_slot_enable) +(see above). +.El +.Ss Console interface +On systems that can attach consoles through +.Nm , +the controller's console attachment function (called very early in +autoconfiguration) calls +.Fn pckbport_cnattach cookie ops slot . +The first two arguments are the same as for +.Fn pckbport_attach , +while the third indicates which slot the console keyboard is attached to. +.Fn pckbport_cnattach +either calls +.Fn pckbd_cnattach , +if it is available, or +.Fn pckbport_machdep_cnattach . +The latter allows machine-dependent keyboard drivers to attach themselves, +but it is only called if a device with the +.Ql pckbport_machdep_cnattach +attribute is configured into the system. +.Fn pckbport_cnattach +returns 0 on success and an error value on failure. +.Fn pckbport_machdep_cnattach +is expected to do the same. +.Sh CODE REFERENCES +The +.Nm +code, and the +.Xr pckbd 4 +and +.Xr pms 4 +device drivers are in +.Pa sys/dev/pckbport . +.Sh SEE ALSO +.Xr pckbc 4 , +.Xr pckbd 4 , +.Xr pms 4 , +.Xr autoconf 9 , +.Xr spl 9 +.Sh HISTORY +The +.Nm +system appeared in +.Nx 2.0 . +Before that, +.Xr pckbd 4 +and +.Xr pms 4 +attached directly to +.Xr pckbc 4 +without any sensible way of using a different controller. diff --git a/static/netbsd/man9/pcmcia.9 b/static/netbsd/man9/pcmcia.9 new file mode 100644 index 00000000..9eac0cfb --- /dev/null +++ b/static/netbsd/man9/pcmcia.9 @@ -0,0 +1,431 @@ +.\" $NetBSD: pcmcia.9,v 1.22 2018/02/11 14:17:24 wiz Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 15, 2010 +.Dt PCMCIA 9 +.Os +.Sh NAME +.Nm PCMCIA , +.Nm pcmcia_function_init , +.Nm pcmcia_function_enable , +.Nm pcmcia_function_disable , +.Nm pcmcia_io_alloc , +.Nm pcmcia_io_free , +.Nm pcmcia_io_map , +.Nm pcmcia_io_unmap , +.Nm pcmcia_mem_alloc , +.Nm pcmcia_mem_free , +.Nm pcmcia_mem_map , +.Nm pcmcia_mem_unmap , +.Nm pcmcia_intr_establish , +.Nm pcmcia_intr_disestablish , +.Nm pcmcia_cis_read_1 , +.Nm pcmcia_cis_read_2 , +.Nm pcmcia_cis_read_3 , +.Nm pcmcia_cis_read_4 , +.Nm pcmcia_cis_read_n , +.Nm pcmcia_scan_cis +.Nd support for PCMCIA PC-Card devices +.Sh SYNOPSIS +.In sys/bus.h +.In dev/pcmcia/pcmciareg.h +.In dev/pcmcia/pcmciavar.h +.In dev/pcmcia/pcmciadevs.h +.Ft void +.Fn pcmcia_function_init "struct pcmcia_function *pf" \ +"struct pcmcia_config_entry *cfe" +.Ft int +.Fn pcmcia_function_enable "struct pcmcia_function *pf" +.Ft void +.Fn pcmcia_function_disable "struct pcmcia_function *pf" +.Ft int +.Fn pcmcia_io_alloc "struct pcmcia_function *pf" "bus_addr_t start" \ +"bus_size_t size" "bus_size_t align" "struct pcmcia_io_handle *pciop" +.Ft void +.Fn pcmcia_io_free "struct pcmcia_function *pf" \ +"struct pcmcia_io_handle *pcihp" +.Ft int +.Fn pcmcia_io_map "struct pcmcia_function *pf" "int width" \ +"struct pcmcia_io_handle *pcihp" "int *windowp" +.Ft void +.Fn pcmcia_io_unmap "struct pcmcia_function *pf" "int window" +.Ft int +.Fn pcmcia_mem_alloc "struct pcmcia_function *pf" "bus_size_t size" \ +"struct pcmcia_mem_handle *pcmhp" +.Ft void +.Fn pcmcia_mem_free "struct pcmcia_function *pf" \ +"struct pcmcia_mem_handle *pcmhp" +.Ft int +.Fn pcmcia_mem_map "struct pcmcia_function *pf" "int width" \ +"bus_addr_t card_addr" "bus_size_t size" "struct pcmcia_mem_handle *pcmhp" \ +"bus_size_t *offsetp" "int *windowp" +.Ft void +.Fn pcmcia_mem_unmap "struct pcmcia_function *pf" "int window" +.Ft void * +.Fn pcmcia_intr_establish "struct pcmcia_function *pf" "int level" \ +"int (*handler)(void *)" "void *arg" +.Ft void +.Fn pcmcia_intr_disestablish "struct pcmcia_function *pf" "void *ih" +.Ft uint8_t +.Fn pcmcia_cis_read_1 "struct pcmcia_tuple *tuple" "int index" +.Ft uint16_t +.Fn pcmcia_cis_read_2 "struct pcmcia_tuple *tuple" "int index" +.Ft uint32_t +.Fn pcmcia_cis_read_3 "struct pcmcia_tuple *tuple" "int index" +.Ft uint32_t +.Fn pcmcia_cis_read_4 "struct pcmcia_tuple *tuple" "int index" +.Ft uint32_t +.Fn pcmcia_cis_read_n "struct pcmcia_tuple *tuple" "int number" "int index" +.Ft int +.Fn pcmcia_scan_cis "struct device *dev" \ +"int (*func)(struct pcmcia_tuple *, void *)" "void *arg" +.Sh DESCRIPTION +The machine-independent +.Nm +subsystem provides support for PC-Card devices defined by the Personal +Computer Memory Card International Association (PCMCIA). +The +.Nm +bus supports insertion and removal of cards while a system is +powered-on (ie, dynamic reconfiguration). +The socket must be powered-off when a card is not present. +To the user, this appears as though the socket is "hot" during +insertion and removal events. +.Pp +A PCMCIA controller interfaces the PCMCIA bus with the ISA or PCI +busses on the host system. +The controller is responsible for detecting and enabling devices and +for allocating and mapping resources such as memory and interrupts +to devices on the PCMCIA bus. +.Pp +Each device has a table called the Card Information Structure (CIS) +which contains configuration information. +The tuples in the CIS are used by the controller to uniquely identify +the device. +Additional information may be present in the CIS, such as the ethernet +MAC address, that can be accessed and used within a device driver. +.Pp +Devices on the PCMCIA bus are uniquely identified by a 32-bit +manufacturer ID and a 32-bit product ID. +Additionally, devices can perform multiple functions (such as ethernet +and modem) and these functions are identified by a function ID. +.Pp +PCMCIA devices do not support DMA, however memory on the device can be +mapped into the address space of the host. +.Sh DATA TYPES +Drivers attached to the +.Nm +bus will make use of the following data types: +.Bl -tag -width compact +.It Fa struct pcmcia_card +Devices (cards) have their identity recorded in this structure. +It contains the following members: +.Bd -literal + char *cis1_info[4]; + int32_t manufacturer; + int32_t product; + uint16_t error; + SIMPLEQ_HEAD(, pcmcia_function) pf_head; +.Ed +.It Fa struct pcmcia_function +Identifies the function of the devices. +A device can have multiple functions. +Consider it an opaque type for identifying a particular function +of a device. +.It struct pcmcia_config_entry +Contains information about the resources requested by the device. +It contains the following members: +.Bd -literal + int number; + uint32_t flags; + int iftype; + int num_iospace; + u_long iomask; + struct { + u_long length; + u_long start; + } iospace[4]; + uint16_t irqmask; + int num_memspace; + struct { + u_long length; + u_long cardaddr; + u_long hostaddr; + } memspace[2]; + int maxtwins; + SIMPLEQ_ENTRY(pcmcia_config_entry) cfe_list; +.Ed +.It Fa struct pcmcia_tuple +A handle for identifying an entry in the CIS. +.It Fa struct pcmcia_io_handle +A handle for mapping and allocating I/O address spaces. +It contains the tag and handle for accessing the bus-space. +.It Fa struct pcmcia_mem_handle +A handle for mapping and allocating memory address spaces. +It contains the tag and handle for accessing the bus-space. +.It Fa struct pcmcia_attach_args +A structure used to inform the driver of the +device properties. +It contains the following members: +.Bd -literal + int32_t manufacturer; + int32_t product; + struct pcmcia_card *card; + struct pcmcia_function *pf; +.Ed +.El +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn pcmcia_function_init "pf" "cfe" +Initialise the machine-independent +.Nm +state with the config entry +.Fa cfe . +.It Fn pcmcia_function_enable "pf" +Provide power to the socket containing the device specified by +device function +.Fa pf . +.It Fn pcmcia_function_disable "pf" +Remove power from the socket containing the device specified by +device function +.Fa pf . +.It Fn pcmcia_io_alloc "pf" "start" "size" "align" "pciop" +Request I/O space for device function +.Fa pf +at address +.Fa start +of size +.Fa size . +Alignment is specified by +.Fa align . +A handle for the I/O space is returned in +.Fa pciop . +.It Fn pcmcia_io_free "pf" "pcihp" +Release I/O space with handle +.Fa pcihp +for device function +.Fa pf . +.It Fn pcmcia_io_map "pf" "width" "pcihp" "windowp" +Map device I/O for device function +.Fa pf +to the I/O space with handle +.Fa pcihp . +The width of data access is specified by +.Fa width . +Valid values for the width are: +.Bl -tag -width PCMCIA_WIDTH_AUTO +.It PCMCIA_WIDTH_AUTO +Use the largest I/O width reported by the device. +.It PCMCIA_WIDTH_IO8 +Force 8-bit I/O width. +.It PCMCIA_WIDTH_IO16 +Force 16-bit I/O width. +.El +.Pp +A handle for the mapped I/O window is returned in +.Fa windowp . +.It Fn pcmcia_io_unmap "pf" "window" +Unmap the I/O window +.Fa window +for device function +.Fa pf . +.It Fn pcmcia_mem_alloc "pf" "size" "pcmhp" +Request memory space for device function +.Fa pf +of size +.Fa size . +A handle for the memory space is returned in +.Fa pcmhp . +.It Fn pcmcia_mem_free "pf" "pcmhp" +Release memory space with handle +.Fa pcmhp +for device function +.Fa pf . +.It Fn pcmcia_mem_map "pf" "width" "card_addr" "size" "pcmhp" "offsetp" \ +"windowp" +Map device memory for device function +.Fa pf +to the memory space with handle +.Fa pcmhp . +The address of the device memory starts at +.Fa card_addr +and is size +.Fa size . +The width of data access is specified by +.Fa width . +Valid values for the width are: +.Bl -tag -width PCMCIA_WIDTH_MEM16 +.It PCMCIA_WIDTH_MEM8 +Force 8-bit memory width. +.It PCMCIA_WIDTH_MEM16 +Force 16-bit memory width. +.El +.Pp +A handle for the mapped memory window is returned in +.Fa windowp +and a bus-space offset into the memory window is returned in +.Fa offsetp . +.It Fn pcmcia_mem_unmap "pf" "window" +Unmap the memory window +.Fa window +for device function +.Fa pf . +.It Fn pcmcia_intr_establish "pf" "level" "handler" "arg" +Establish an interrupt handler for device function +.Fa pf . +The priority of the interrupt is specified by +.Fa level . +When the interrupt occurs the function +.Fa handler +is called with argument +.Fa arg . +The return value is a handle for the interrupt handler. +.Fn pcmcia_intr_establish +returns an opaque handle to an event descriptor if it succeeds, and +returns NULL on failure. +.It Fn pcmcia_intr_disestablish "pf" "ih" +Dis-establish the interrupt handler for device function +.Fa pf +with handle +.Fa ih . +The handle was returned from +.Fn pcmcia_intr_establish . +.It Fn pcmcia_cis_read_1 "tuple" "index" +Read one byte from tuple +.Fa tuple +at index +.Fa index +in the CIS. +.It Fn pcmcia_cis_read_2 "tuple" "index" +Read two bytes from tuple +.Fa tuple +at index +.Fa index +in the CIS. +.It Fn pcmcia_cis_read_3 "tuple" "index" +Read three bytes from tuple +.Fa tuple +at index +.Fa index +in the CIS. +.It Fn pcmcia_cis_read_4 "tuple" "index" +Read four bytes from tuple +.Fa tuple +at index +.Fa index +in the CIS. +.It Fn pcmcia_cis_read_n "tuple" "number" "index" +Read +.Fa n +bytes from tuple +.Fa tuple +at index +.Fa index +in the CIS. +.It Fn pcmcia_scan_cis "dev" "func" "arg" +Scan the CIS for device +.Fa dev . +For each tuple in the CIS, function +.Fa func +is called with the tuple and the argument +.Fa arg . +.Fa func +should return 0 if the tuple it was called with is the one it was +looking for, or 1 otherwise. +.El +.Sh AUTOCONFIGURATION +During autoconfiguration, a +.Nm +driver will receive a pointer to +.Fa struct pcmcia_attach_args +describing the device attached to the PCMCIA bus. +Drivers match the device using the +.Em manufacturer +and +.Em product +members. +.Pp +During the driver attach step, drivers will use the pcmcia function +.Em pf . +The driver should traverse the list of config entries searching for a +useful configuration. +This config entry is passed to +.Fn pcmcia_function_init +to initialise the machine-independent interface. +I/O and memory resources should be initialised using +.Fn pcmcia_io_alloc +and +.Fn pcmcia_mem_alloc +using the specified resources in the config entry. +These resources can then be mapped into processor bus space using +.Fn pcmcia_io_map +and +.Fn pcmcia_mem_map +respectively. +Upon successful allocation of resources, power can be applied to the +device with +.Fn pcmcia_function_enable +so that device-specific interrogation can be performed. +Finally, power should be removed from the device using +.Fn pcmcia_function_disable . +.Pp +Since PCMCIA devices support dynamic configuration, drivers should +make use of +.Xr pmf 9 +framework. +Power can be applied and the interrupt handler should be established +through this interface. +.Sh DMA SUPPORT +PCMCIA devices do not support DMA. +.Sh CODE REFERENCES +The PCMCIA subsystem itself is implemented within the file +.Pa sys/dev/pcmcia/pcmcia.c . +The database of known devices exists within the file +.Pa sys/dev/pcmcia/pcmciadevs_data.h +and is generated automatically from the file +.Pa sys/dev/pcmcia/pcmciadevs . +New manufacturer and product identifiers should be added to this file. +The database can be regenerated using the Makefile +.Pa sys/dev/pcmcia/Makefile.pcmciadevs . +.Sh SEE ALSO +.Xr pcic 4 , +.Xr pcmcia 4 , +.Xr tcic 4 , +.Xr autoconf 9 , +.Xr bus_dma 9 , +.Xr bus_space 9 , +.Xr driver 9 +.Rs +.%A Personal Computer Memory Card International Association (PCMCIA) +.%T "PC Card 95 Standard" +.%D 1995 +.Re +.Sh HISTORY +The machine-independent PCMCIA subsystem appeared in +.Nx 1.3 . diff --git a/static/netbsd/man9/pcq.9 b/static/netbsd/man9/pcq.9 new file mode 100644 index 00000000..9d14cd6e --- /dev/null +++ b/static/netbsd/man9/pcq.9 @@ -0,0 +1,194 @@ +.\" $NetBSD: pcq.9,v 1.9 2023/02/23 03:03:23 riastradh Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Matt Thomas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 22, 2012 +.Dt PCQ 9 +.Os +.Sh NAME +.Nm pcq +.Nd producer/consumer queue +.Sh SYNOPSIS +.In sys/pcq.h +.Ft pcq_t * +.Fn pcq_create "size_t maxlen" "km_flags_t kmflags" +.Ft void +.Fn pcq_destroy "pcq_t *pcq" +.Ft void * +.Fn pcq_get "pcq_t *pcq" +.Ft size_t +.Fn pcq_maxitems "pcq_t *pcq" +.Ft void * +.Fn pcq_peek "pcq_t *pcq" +.Ft bool +.Fn pcq_put "pcq_t *pcq" "void *item" +.Sh DESCRIPTION +The machine-independent +.Nm +interface provides lockless producer/consumer queues. +A queue +.Po +.Vt pcq_t +.Pc +allows multiple writers +.Pq producers , +but only a single reader +.Pq consumer . +The consumer is expected to be protected by a lock that covers +the structure that the +.Vt pcq_t +is embedded into +.Po +e.g., socket lock, ifnet hwlock +.Pc . +These queues operate in a first-in, first-out +.Pq FIFO +manner. +The act of inserting or removing an item from a +.Vt pcq_t +does not modify the item in any way. +.Nm +does not prevent an item from being inserted multiple times into a single +.Vt pcq_t . +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn pcq_create "maxlen" "kmflags" +Create a queue that can store at most +.Fa maxlen +items at one time. +.Fa kmflags +should be either +.Dv KM_SLEEP , +if +.Fn pcq_create +is allowed to sleep until resources are available, or +.Dv KM_NOSLEEP +if it should return +.Dv NULL +immediately, if resources are unavailable. +.It Fn pcq_destroy "pcq" +Free the resources held by +.Fa pcq . +.It Fn pcq_get "pcq" +Remove the next item to be consumed from the queue and return it. +If the queue is empty, +return +.Dv NULL . +The caller must prevent concurrent gets from occurring. +.It Fn pcq_maxitems "pcq" +Return the maximum number of items that the queue can store at +any one time. +.It Fn pcq_peek "pcq" +Return the next item to be consumed from the queue but do not remove +it from the queue. +If the queue is empty, +return +.Dv NULL . +.It Fn pcq_put "pcq" "item" +Place an item at the end of the queue. +If there is no room in the queue for the item, return +.Dv false ; +otherwise, return +.Dv true . +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(&foo->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 +interface is implemented within the file +.Pa sys/kern/subr_pcq.c . +.\" .Sh EXAMPLES +.Sh SEE ALSO +.Xr atomic_ops 3 , +.Xr queue 3 +.Sh HISTORY +The +.Nm +interface first appeared in +.Nx 6.0 . +.\" .Sh CAVEATS +.\" .Sh BUGS +.\" .Sh SECURITY CONSIDERATIONS diff --git a/static/netbsd/man9/pcu.9 b/static/netbsd/man9/pcu.9 new file mode 100644 index 00000000..746fdcb1 --- /dev/null +++ b/static/netbsd/man9/pcu.9 @@ -0,0 +1,130 @@ +.\" $NetBSD: pcu.9,v 1.12 2017/03/17 10:09:24 wiz Exp $ +.\" +.\" Copyright (c) 2012-2014 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Mindaugas Rasiukevicius. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 16, 2017 +.Dt PCU 9 +.Os +.Sh NAME +.Nm pcu +.Nd per-CPU unit (PCU) +.Sh SYNOPSIS +.In sys/pcu.h +.Ft void +.Fn pcu_load "const pcu_ops_t *pcu" +.Ft void +.Fn pcu_save "const pcu_ops_t *pcu" "lwp_t *l" +.Ft void +.Fn pcu_save_all "lwp_t *l" +.Ft void +.Fn pcu_discard "const pcu_ops_t *pcu" "lwp_t *l" "bool valid" +.Ft void +.Fn pcu_discard_all "lwp_t *l" +.Ft bool +.Fn pcu_valid_p "const pcu_ops_t *pcu" +.\" ----- +.Sh DESCRIPTION +Per CPU Unit (PCU) is an interface to manage synchronization of any +per-CPU context (unit) tied to an LWP context. +Typical use of PCU is for "lazy-switch" synchronization of the FPU state. +Each PCU has its operations defined by a +.Vt pcu_ops_t +structure. +Members of +.Vt pcu_ops_t +are +.Bd -literal + u_int pcu_id; + void (*pcu_state_save)(lwp_t *l); + void (*pcu_state_load)(lwp_t *l, u_int flags); + void (*pcu_state_release)(lwp_t *l); +.Ed +.Pp +.Bl -tag +.It Fn pcu_state_save +Indicate to MD code that the PCU state on the current CPU should be +saved into the given LWP's MD storage. +.It Fn pcu_state_load +Load PCU state from the given LWP's MD storage to the current CPU. +The +.Ar flags +argument is a combination of one or more of the following: +.Bl -tag -width PCU_VALIDXXX +.It Dv PCU_VALID +Indicate that the PCU state is considered valid and need not be initialized. +This is the case if the PCU state was already used (and thus loaded) by the LWP +and has not been discarded since. +.It Dv PCU_REENABLE +Indicate that a fault reoccurred while the PCU state is loaded, +therefore PCU should be re-enabled. +This happens if LWP is context switched to another CPU and then switched +back to the original CPU while the state on that CPU has not been changed +by other LWPs. +It may also happen due to instruction "bouncing" on some architectures. +.El +.It Fn pcu_state_release +Indicate to MD code that the PCU ownership by the LWP was released, +therefore the next use of PCU on the LWP shall be detected and +.Fn pcu_load +be called to reacquire the ownership. +For example, this would normally be the changing of a bit for a CPU to +trap on the execution of one of the PCU's instructions. +.El +.\" ----- +.Sh FUNCTIONS +.Bl -tag -width pcu_save_allXXX +.It Fn pcu_load +Load or initialize the PCU state of the current LWP on the current CPU. +.It Fn pcu_save +Save the specified PCU state to the given LWP. +.It Fn pcu_discard +Discard the specified PCU state of the current LWP. +The PCU state will be considered invalid, +unless the "valid" parameter is set to true. +.It Fn pcu_valid_p +Return true if PCU state is considered valid. +Generally, it always becomes "valid" when +.Fn pcu_load +is called by the LWP. +Otherwise, return false. +.It Fn pcu_discard_all +Discard all PCU states of the given LWP; generally used by exec and exit. +.It Fn pcu_save_all +Save all PCU states of the given LWP; generally used during new LWP +creation so that the PCU state of the parent could be copied. +.El +.\" ----- +.Sh CODE REFERENCES +.Nm +is implemented within the file +.Pa sys/kern/subr_pcu.c . +.Sh HISTORY +PCU first appeared in +.Nx 6.0 . +.Sh AUTHORS +.An Mindaugas Rasiukevicius Aq Mt rmind@NetBSD.org diff --git a/static/netbsd/man9/percpu.9 b/static/netbsd/man9/percpu.9 new file mode 100644 index 00000000..eb59af41 --- /dev/null +++ b/static/netbsd/man9/percpu.9 @@ -0,0 +1,226 @@ +.\" $NetBSD: percpu.9,v 1.16 2023/08/02 06:24:46 riastradh Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by David Young. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 7, 2020 +.Dt PERCPU 9 +.Os +.Sh NAME +.Nm percpu , +.Nm percpu_alloc , +.Nm percpu_create , +.Nm percpu_free , +.Nm percpu_getref , +.Nm percpu_putref , +.Nm percpu_foreach , +.Nm percpu_foreach_xcall +.Nd per-CPU storage allocator +.Sh SYNOPSIS +.In sys/percpu.h +.Vt typedef void (*percpu_callback_t)(void *, void *, struct cpu_info *); +.Ft percpu_t * +.Fn percpu_alloc "size_t size" +.Ft percpu_t * +.Fn percpu_create "size_t size" "percpu_callback_t ctor" "percpu_callback_t dtor" "void *arg" +.Ft void +.Fn percpu_free "percpu_t *pc" "size_t size" +.Ft void * +.Fn percpu_getref "percpu_t *pc" +.Ft void +.Fn percpu_putref "percpu_t *pc" +.Ft void +.Fn percpu_foreach "percpu_t *pc" "percpu_callback_t cb" "void *arg" +.Ft void +.Fn percpu_foreach_xcall "percpu_t *pc" "u_int xcflags" "percpu_callback_t cb" "void *arg" +.Sh DESCRIPTION +The machine-independent +.Nm +interface provides per-CPU, CPU-local memory reservations to kernel +subsystems. +.Fo percpu_alloc +.Fa size +.Fc +reserves on each CPU an independent memory region of +.Fa size +bytes that is local to that CPU, returning a handle +.Po +.Vt percpu_t +.Pc +to those regions. +A thread may subsequently ask for a pointer, +.Fa p , +to the region held by the +.Vt percpu_t +on the thread's current CPU. +Until the thread relinquishes the pointer, or voluntarily sleeps, +the thread may read or write the region at +.Fa p +without causing interprocessor memory synchronization. +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn percpu_alloc "size" +Call this in thread context to allocate +.Fa size +bytes of local storage on each CPU. +The storage is initialized with zeroes. +Treat this as an expensive operation. +.Fn percpu_alloc +returns a handle for the per-CPU storage. +.It Fn percpu_create "size" "ctor" "dtor" "arg" +Like +.Fn percpu_alloc , +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 +.Fn "(*dtor)" p arg ci . +.Pp +.Fa ctor +and +.Fa dtor +.Em MAY +sleep, e.g. to allocate memory or to wait for users to drain before +deallocating memory. +Do not rely on any particular order of iteration over the CPUs. +.It Fn percpu_free "pc" "size" +Call this in thread context to +return to the system the per-CPU storage held by +.Fa pc . +.Fa size +should match the +.Fa size +passed to +.Fn percpu_alloc +or +.Fn percpu_create . +When +.Fn percpu_free +returns, +.Fa pc +is undefined. +Treat this as an expensive operation. +.It Fn percpu_getref "pc" +Disable preemption and return a pointer to the storage held by +.Fa pc +on the local CPU. +Use +.Fn percpu_getref +in either thread or interrupt context. +Follow each +.Fn percpu_getref +call with a matching call to +.Fn percpu_putref . +.Pp +Caller +.Em MUST NOT +sleep after +.Fn percpu_getref , +not even on an adaptive lock, before +.Fn percpu_putref . +.It Fn percpu_putref "pc" +Indicate that the thread is finished +with the pointer returned by the matching +call to +.Fn percpu_getref . +Re-enables preemption. +.It Fn percpu_foreach "pc" "cb" "arg" +For each CPU, with +.Fa ci +being the corresponding +.Vt "struct cpu_info *" +and +.Fa "p" +the CPU-local storage held by +.Fa pc , +run +.Fo "(*cb)" +.Fa "p" +.Fa "arg" +.Fa "ci" +.Fc . +The call to +.Fa cb +runs in the current thread; use +.Fn percpu_foreach_xcall +to execute the call to +.Fa cb +on the remote CPUs. +.Pp +Must be used in thread context. +.Fa cb +.Em MUST NOT +sleep except on adaptive locks, and should be fast. +Do not rely on any particular order of iteration over the CPUs. +.It Fn percpu_foreach_xcall "pc" "xcflags" "cb" "arg" +Like +.Fn percpu_foreach , +except the call to +.Fa cb +executes on the remote CPUs. +The +.Fa xcflags +argument specifies how the cross calls are invoked; see +.Xr xc_broadcast 9 . +The same caveats and restrictions that apply to +.Fn percpu_foreach +also apply to +.Fn percpu_foreach_xcall . +.El +.Sh CODE REFERENCES +The +.Nm +interface is implemented within the file +.Pa sys/kern/subr_percpu.c . +.\" .Sh EXAMPLES +.Sh SEE ALSO +.Xr atomic_ops 3 , +.Xr kmem 9 , +.Xr pcq 9 , +.Xr pool_cache 9 , +.Xr xcall 9 +.Sh HISTORY +The +.Nm +interface first appeared in +.Nx 6.0 . +.Sh AUTHORS +.An YAMAMOTO Takashi Aq Mt yamt@NetBSD.org +.\" .Sh CAVEATS +.\" .Sh BUGS +.\" .Sh SECURITY CONSIDERATIONS diff --git a/static/netbsd/man9/pfil.9 b/static/netbsd/man9/pfil.9 new file mode 100644 index 00000000..36a46e3f --- /dev/null +++ b/static/netbsd/man9/pfil.9 @@ -0,0 +1,267 @@ +.\" $NetBSD: pfil.9,v 1.40 2022/01/15 17:54:01 wiz Exp $ +.\" +.\" Copyright (c) 1996 Matthew R. Green +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 15, 2022 +.Dt PFIL 9 +.Os +.Sh NAME +.Nm pfil , +.Nm pfil_head_create , +.Nm pfil_head_destroy , +.Nm pfil_head_get , +.Nm pfil_hook_get , +.Nm pfil_add_hook , +.Nm pfil_remove_hook , +.Nm pfil_run_hooks , +.Nm pfil_add_ihook , +.Nm pfil_remove_ihook , +.Nm pfil_run_addrhooks , +.Nm pfil_run_ifhooks +.Nd packet filter interface +.Sh SYNOPSIS +.In sys/param.h +.In sys/mbuf.h +.In net/if.h +.In net/pfil.h +.Ft pfil_head_t * +.Fn pfil_head_create "int type" "void *key" +.Ft int +.Fn pfil_head_destroy "pfil_head_t *ph" +.Ft pfil_head_t * +.Fn pfil_head_get "int type" "void *key" +.Ft struct packet_filter_hook * +.Fn pfil_hook_get "int dir" "pfil_head_t *ph" +.Ft int +.Fn pfil_add_hook "pfil_func_t func" "void *arg" "int flags" "pfil_head_t *ph" +.Ft int +.Fn pfil_remove_hook "pfil_func_t func" "void *arg" "int flags" "pfil_head_t *ph" +.Ft int +.Fn (*func) "void *arg" "struct mbuf **mp" "struct ifnet *" "int dir" +.Ft int +.Fn pfil_run_hooks "pfil_head_t *ph" "struct mbuf **mp" "struct ifnet *ifp" "int dir" +.Ft int +.Fn pfil_add_ihook "pfil_ifunc_t ifunc" "void *arg" "int flags" "pfil_head_t *ph" +.Ft int +.Fn pfil_remove_ihook "pfil_ifunc_t ifunc" "void *arg" "int flags" "pfil_head_t *ph" +.Ft void +.Fn (*ifunc) "void *arg" "unsigned long cmd" "void *ptr" +.Ft void +.Fn pfil_run_addrhooks "pfil_head_t *ph" "unsigned long" "struct ifaddr *ifa" +.Ft void +.Fn pfil_run_ifhooks "pfil_head_t *ph" "unsigned long" "struct ifnet *ifp" +.Sh DESCRIPTION +The +.Nm +framework allows for a specified function to be invoked for every +incoming or outgoing packet for a particular network I/O stream. +These hooks may be used to implement a firewall or perform packet +transformations. +.Pp +Packet filtering points are created with +.Fn pfil_head_create . +Filtering points are identified by a +data link +.Vt ( int ) +.Fa type +and a +.Vt ( void * ) +.Fa key . +If a packet filtering point already exists for that data link +.Fa type +and +.Fa key +then the +.Fn pfil_head_create +function returns +.Dv NULL . +Packet filters use the +.Fn pfil_head_get +function specifying the data link +.Fa type +and the +.Fa key +to look up the filtering point with which they register themselves. +The +.Fa key +is unique to the filtering point. +The data link +.Fa type +is a +.Xr bpf 4 +.Dv DLT_ Ns Ar type +constant indicating what kind of header is present on the packet +at the filtering point. +Filtering points may be destroyed with the +.Fn pfil_head_destroy +function. +.Pp +Packet filters register/unregister themselves with a filtering point +with the +.Fn pfil_add_hook +and +.Fn pfil_remove_hook +functions, respectively. +The head is looked up using the +.Fn pfil_head_get +function, which takes the data link +.Fa type +and the +.Fa key +that the packet filter expects. +Filters may provide an argument to be passed to the filter when +invoked on a packet. +.Pp +When a filter is invoked, the packet appears just as if it +.Dq came off the wire . +That is, all protocol fields are in network byte order. +The filter is called with its specified argument, the pointer to the +pointer to the mbuf containing the packet, the pointer to the network +interface that the packet is traversing, and the direction (either +.Dv PFIL_IN +or +.Dv PFIL_OUT , +see also below) that the packet is traveling. +The filter may change which mbuf the +.Vt "mbuf **" +argument references. +The filter returns an errno if the packet processing is to stop, or 0 +if the processing is to continue. +If the packet processing is to stop, it is the responsibility of the +filter to free the packet. +.Pp +The +.Fa flags +parameter, used in the +.Fn pfil_add_hook +and +.Fn pfil_remove_hook +functions, indicates when the filter should be called. +The flags are: +.Pp +.Bl -tag -offset indent -width ".Dv PFIL_ALL" -compact +.It Dv PFIL_IN +call me on incoming packets +.It Dv PFIL_OUT +call me on outgoing packets +.It Dv PFIL_ALL +call me on all of the above +.El +.Pp +By the same token, event handlers register/unregister themselves +with the +.Fn pfil_add_ihook +and +.Fn pfil_remove_ihook +functions, respectively. +The event handler is called with its specified argument, the event id +(either +.Dv PFIL_IFNET_ATTACH +or +.Dv PFIL_IFNET_DETACH , +see also below) or ioctl number, and the pointer +to the network interface or the pointer to the ifaddr. +.Pp +The +.Fa flags +parameter, used in the +.Fn pfil_add_ihook +and +.Fn pfil_remove_ihook +functions, indicates when the filter should be called. +The flags are: +.Pp +.Bl -tag -offset indent -width ".Dv PFIL_IFADDR" -compact +.It Dv PFIL_IFADDR +call me on interface reconfig +.Fa ( cmd +is ioctl #) +.It Dv PFIL_IFNET +call me on interface attach/detach +.Fa ( cmd +is either +.Dv PFIL_IFNET_ATTACH +or +.Dv PFIL_IFNET_DETACH ) +.El +.Sh SEE ALSO +.Xr bpf 4 +.Sh HISTORY +The +.Nm +interface first appeared in +.Nx 1.3 . +The +.Nm +input and output lists were originally implemented as +.In sys/queue.h +.Dv LIST +structures; +however this was changed in +.Nx 1.4 +to +.Dv TAILQ +structures. +This change was to allow the input and output filters to be processed in +reverse order, to allow the same path to be taken, in or out of the kernel. +.Pp +The +.Nm +interface was changed in 1.4T to accept a 3rd parameter to both +.Fn pfil_add_hook +and +.Fn pfil_remove_hook , +introducing the capability of per-protocol filtering. +This was done primarily in order to support filtering of IPv6. +.Pp +In 1.5K, the +.Nm +framework was changed to work with an arbitrary number of filtering points, +as well as be less IP-centric. +.Pp +.Fn pfil_add_ihook +and +.Fn pfil_remove_ihook +were added in +.Nx 8.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +interface was designed and implemented by +.An Matthew R. Green , +with help from +.An Darren Reed , +.An Jason R. Thorpe , +and +.An Charles M. Hannum . +.An Darren Reed +added support for IPv6 in addition to IPv4. +.An Jason R. Thorpe +added support for multiple hooks and other clean up. +.Sh BUGS +The current +.Nm +implementation will need changes to suit a threaded kernel model. diff --git a/static/netbsd/man9/physio.9 b/static/netbsd/man9/physio.9 new file mode 100644 index 00000000..950fbf97 --- /dev/null +++ b/static/netbsd/man9/physio.9 @@ -0,0 +1,143 @@ +.\" $NetBSD: physio.9,v 1.12 2019/09/12 20:32:30 sevan Exp $ +.\" +.\" Copyright (c) 1996 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Paul Kranenburg. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 12, 2019 +.Dt PHYSIO 9 +.Os +.Sh NAME +.Nm physio +.Nd initiate I/O on raw devices +.Sh SYNOPSIS +.Ft int +.Fo "physio" +.Fa "void (*strategy)(buf_t *)" +.Fa "buf_t *bp" +.Fa "dev_t dev" +.Fa "int flags" +.Fa "void (*minphys)(buf_t *)" +.Fa "struct uio *uio" +.Fc +.Sh DESCRIPTION +The +.Fn physio +is a helper function typically called from character device read and write +routines to start +.Tn I/O +on a user process buffer. +It calls back on the provided +.Fa strategy +routine one or more times to complete the transfer described by +.Fa uio . +The maximum amount of data to transfer with each call to +.Fa strategy +is determined by the +.Fa minphys +routine. +.Pp +Since +.Fa uio +normally describes user space addresses, +.Fn physio +needs to lock the appropriate data area into memory before each transaction +with +.Fa strategy +(see +.Xr uvm_vslock 9 +and +.Xr uvm_vsunlock 9 ) . +The +.Fn physio +function always awaits the completion of the entire requested transfer before +returning, unless an error condition is detected earlier. +In all cases, the buffer passed in +.Fa bp +is locked (marked as +.Dq busy ) +for the duration of the entire transfer. +.Pp +A break-down of the arguments follows: +.Bl -tag -width "strategy " +.It Fa strategy +The device strategy routine to call for each chunk of data to initiate +device +.Tn I/O . +.It Fa bp +The buffer to use with the strategy routine. +The buffer flags will have +.Dv B_BUSY , +.Dv B_PHYS , +and +.Dv B_RAW +set when passed to the strategy routine. +If +.Dv NULL , +a buffer is allocated from a system pool. +.It Fa dev +The device number identifying the device to interact with. +.It Fa flags +Direction of transfer; the only valid settings are +.Dv B_READ +or +.Dv B_WRITE . +.It Fa minphys +A device specific routine called to determine the maximum transfer size +that the device's strategy routine can handle. +.It Fa uio +The description of the entire transfer as requested by the user process. +Currently, the results of passing a +.Fa uio +structure with the +.Sq uio_segflg +set to anything other than +.Dv UIO_USERSPACE , +are undefined. +.El +.Sh RETURN VALUES +If successful +.Fn physio +returns 0. +.Er EFAULT +is returned if the address range described by +.Fa uio +is not accessible by the requesting process. +.Fn physio +will return any error resulting from calls to the device strategy routine, +by examining the +.Dv B_ERROR +buffer flag and the +.Sq b_error +field. +Note that the actual transfer size may be less than requested by +.Fa uio +if the device signals an +.Dq end of file +condition. +.Sh SEE ALSO +.Xr read 2 , +.Xr write 2 diff --git a/static/netbsd/man9/pktqueue.9 b/static/netbsd/man9/pktqueue.9 new file mode 100644 index 00000000..d880a666 --- /dev/null +++ b/static/netbsd/man9/pktqueue.9 @@ -0,0 +1,259 @@ +.\" $NetBSD: pktqueue.9,v 1.3 2022/09/05 16:42:59 wiz Exp $ +.\" +.\" Copyright (c) 2022 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 3, 2022 +.Dt PKTQUEUE 9 +.Os +.Sh NAME +.Nm pktqueue , +.Nm pktq_create , +.Nm pktq_destroy , +.Nm pktq_enqueue , +.Nm pktq_dequeue , +.Nm pktq_barrier , +.Nm pktq_ifdetach , +.Nm pktq_flush , +.Nm pktq_set_maxlen , +.Nm pktq_rps_hash , +.Nm pktq_sysctl_setup , +.Nm sysctl_pktq_rps_hash_handler +.Nd Lockless network protocol input queues with integrated ISR scheduling +.Sh SYNOPSIS +.In net/pktqueue.h +.Ft pktqueue_t * +.Fn pktq_create "size_t maxlen" "void (*intrh)(void *)" "void *arg" +.Ft void +.Fn pktq_destroy "pktqueue_t *pq" +.Ft bool +.Fn pktq_enqueue "pktqueue_t *pq" "struct mbuf *m" "u_int hash" +.Ft struct mbuf * +.Fn pktq_dequeue "pktqueue_t *pq" +.Ft void +.Fn pktq_barrier "pktqueue_t *pq" +.Ft void +.Fn pktq_ifdetach "void" +.Ft void +.Fn pktq_flush "pktqueue_t *pq" +.Ft int +.Fn pktq_set_maxlen "pktqueue_t *pq" "size_t maxlen" +.Ft uint32_t +.Fn pktq_rps_hash "const pktq_rps_hash_func_t *funcp" "const struct mbuf *m" +.Ft int +.Fn pktq_sysctl_setup "pktqueue_t *pq" "struct sysctllog **clog" \ + "const struct sysctlnode *parent_node" "int qid" +.Ft int +.Fn sysctl_pktq_rps_hash_handler "SYSCTLFN_ARGS" +.Sh DESCRIPTION +The +.Nm +functions provide a lockless network protocol input queue interface +with integrated software interrupt scheduling and support for +receiver-side packet steering +.Pq RPS . +The implementation is based around per-CPU producer-consumer queues; +multiple CPUs may enqueue packets into a CPU's queue, but only the +owning CPU will dequeue packets from any given queue. +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn pktq_create "maxlen" "intrh" "arg" +Create a packet queue that can store at most +.Fa maxlen +packets at one time. +.Fa maxlen +must not exceed +.Dv PCQ_MAXLEN . +The software interrupt handler +.Fa intrh +with argument +.Fa arg +will be established at +.Dv SOFTINT_NET . +.It Fn pktq_destroy "pq" +Destroy the specified packet 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 +.Fa m +in the specified packet queue. +The modulus of +.Fa hash +and the number of CPUs will be computed and used to select the per-CPU +queue where the packet will be stored, and thus upon which CPU the packet +will be processed. +Once the CPU selection has been made and the packet placed in the queue, +the software interrupt associated with packet queue will be scheduled. +.It Fn pktq_dequeue "pq" +Dequeue a packet from the current CPU's queue. +If no packets remain, +.Dv NULL +is returned. +This function must be called with kernel preemption disabled, which is always +the case when running in a software interrupt handler. +.It Fn pktq_barrier "pq" +Wait for a grace period when all packets enqueued at the moment of +calling this function will have been dequeued. +.It Fn pktq_ifdetach +This function is called when a network interface is detached from the +system. +It performs a +.Fn pktq_barrier +operation on all packet queues. +.It Fn pktq_flush "pq" +This function removes and frees all packets in the specified queue. +The caller is responsible for ensuring that no calls to +.Fn pktq_enqueue +or +.Fn pktq_dequeue +run concurrently with +.Fn pktq_flush . +.It Fn pktq_set_maxlen "pq" "maxlen" +Sets the maximum queue length to the value +.Fa maxlen . +If the new value of +.Fa maxlen +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 +.Fa m +using the hash function referenced by +.Fa funcp . +The available hash functions are +.Dq zero +.Pq always returns 0 , +.Dq curcpu +.Pq returns the index of the current CPU , +.Dq toeplitz +.Pq Toeplitz hash of an IPv4 or IPv6 packet , +and +.Dq toeplitz-othercpus +.Po +same as +.Dq toeplitz +but always hashes to a CPU other than the current CPU +.Pc . +A default hash routine is provided by the global variable +.Dv pktq_rps_hash_default . +The default routine is guaranteed to be safe to use for any network protocol. +The behavior of +.Dq toeplitz +and +.Dq toeplitz-othercpus +is undefined if used with protocols other than IPv4 or IPv6. +.It Fn pktq_sysctl_setup "pq" "clog" "parent_node" "qid" +This function registers standard sysctl handlers for +.Fa pq +at the parent sysctl node +.Fa parent_node . +.Fa qid +allows the caller to specify the node ID at which to attach to +.Fa parent_node ; +use +.Dv CTL_CREATE +to dynamically assign a node ID. +The +.Fa clog +argument is passed directly to +.Fn sysctl_createv . +.It Fn sysctl_pktq_rps_hash_handler +This function provides a way for the user to select the preferred +RPS hash function to be used by a caller of +.Fn pktq_rps_hash +via +.Xr sysctl 8 . +When calling +.Fn sysctl_createv +to create the sysctl node, pass +.Fn sysctl_pktq_rps_hash_handler +as the +.Fa func +argument and the pointer to the RPS hash function reference variable +as the +.Fa newp +argument +.Po +cast to +.Sq void * +.Pc . +.El +.Sh CODE REFERENCES +The +.Nm +interface is implemented within the file +.Pa net/pktqueue.c . +.Pp +An example of how to use +.Fn pktq_rps_hash +can be found in the +.Fn ether_input +function. +An example of how to use +.Fn sysctl_pktq_rps_hash_handler +can be found in the +.Fn ether_sysctl_setup +function. +Both reside within the file +.Pa net/if_ethersubr.c . +.Pp +An example of how to use +.Fn pktq_sysctl_setup +can be found in the +.Fn sysctl_net_inet_ip_setup +function within the file +.Pa netinet/ip_input.c . +.Sh NOTES +The +.Fa maxlen +argument provided to +.Fn pktq_create +specifies the maximum number of packets that can be stored in each +per-CPU queue. +This means that, in theory, the maximum number of packets that can be +enqueued is +.Sq maxlen * ncpu . +However, as a practical matter, the number will be smaller because the +distribution of packets across the per-CPU queues is not perfectly uniform. +.Pp +Calls to +.Fn pktq_set_maxlen +may result in re-ordering the delivery of packets currently in +the queue. +.\" .Sh EXAMPLES +.Sh SEE ALSO +.Xr sysctl 8 , +.Xr kpreempt 9 , +.Xr pcq 9 , +.Xr softintr 9 , +.Xr sysctl 9 +.Sh HISTORY +The +.Nm +interface first appeared in +.Nx 7.0 . diff --git a/static/netbsd/man9/pmap.9 b/static/netbsd/man9/pmap.9 new file mode 100644 index 00000000..b8d87a43 --- /dev/null +++ b/static/netbsd/man9/pmap.9 @@ -0,0 +1,1243 @@ +.\" $NetBSD: pmap.9,v 1.48 2020/08/16 16:48:08 thorpej Exp $ +.\" +.\" Copyright (c) 2000, 2001, 2002, 2020 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 16, 2020 +.Dt PMAP 9 +.Os +.Sh NAME +.Nm pmap +.Nd machine-dependent portion of the virtual memory system +.Sh SYNOPSIS +.In sys/param.h +.In uvm/uvm_extern.h +.Ft void +.Fn "pmap_init" "void" +.Ft void +.Fn "pmap_virtual_space" "vaddr_t *vstartp" "vaddr_t *vendp" +.Ft vaddr_t +.Fn "pmap_steal_memory" "vsize_t size" "vaddr_t *vstartp" "vaddr_t *vendp" +.Ft pmap_t +.Fn "pmap_kernel" "void" +.Ft pmap_t +.Fn "pmap_create" "void" +.Ft void +.Fn "pmap_destroy" "pmap_t pmap" +.Ft void +.Fn "pmap_reference" "pmap_t pmap" +.Ft void +.Fn "pmap_fork" "pmap_t src_map" "pmap_t dst_map" +.Ft long +.Fn "pmap_resident_count" "pmap_t pmap" +.Ft long +.Fn "pmap_wired_count" "pmap_t pmap" +.Ft vaddr_t +.Fn "pmap_growkernel" "vaddr_t maxkvaddr" +.Ft int +.Fn "pmap_enter" "pmap_t pmap" "vaddr_t va" "paddr_t pa" "vm_prot_t prot" \ + "u_int flags" +.Ft void +.Fn "pmap_remove" "pmap_t pmap" "vaddr_t sva" "vaddr_t eva" +.Ft bool +.Fn "pmap_remove_all" "pmap_t pmap" +.Ft void +.Fn "pmap_protect" "pmap_t pmap" "vaddr_t sva" "vaddr_t eva" "vm_prot_t prot" +.Ft void +.Fn "pmap_unwire" "pmap_t pmap" "vaddr_t va" +.Ft bool +.Fn "pmap_extract" "pmap_t pmap" "vaddr_t va" "paddr_t *pap" +.Ft void +.Fn "pmap_kenter_pa" "vaddr_t va" "paddr_t pa" "vm_prot_t prot" "u_int flags" +.Ft void +.Fn "pmap_kremove" "vaddr_t va" "vsize_t size" +.Ft void +.Fn "pmap_copy" "pmap_t dst_map" "pmap_t src_map" "vaddr_t dst_addr" \ + "vsize_t len" "vaddr_t src_addr" +.Ft void +.Fn "pmap_update" "pmap_t pmap" +.Ft void +.Fn "pmap_activate" "struct lwp *l" +.Ft void +.Fn "pmap_deactivate" "struct lwp *l" +.Ft void +.Fn "pmap_zero_page" "paddr_t pa" +.Ft void +.Fn "pmap_copy_page" "paddr_t src" "paddr_t dst" +.Ft void +.Fn "pmap_page_protect" "struct vm_page *pg" "vm_prot_t prot" +.Ft bool +.Fn "pmap_clear_modify" "struct vm_page *pg" +.Ft bool +.Fn "pmap_clear_reference" "struct vm_page *pg" +.Ft bool +.Fn "pmap_is_modified" "struct vm_page *pg" +.Ft bool +.Fn "pmap_is_referenced" "struct vm_page *pg" +.Ft paddr_t +.Fn "pmap_phys_address" "paddr_t cookie" +.Ft vaddr_t +.Fn "PMAP_MAP_POOLPAGE" "paddr_t pa" +.Ft paddr_t +.Fn "PMAP_UNMAP_POOLPAGE" "vaddr_t va" +.Ft void +.Fn "PMAP_PREFER" "vaddr_t hint" "vaddr_t *vap" "vsize_t sz" "int td" +.Sh DESCRIPTION +The +.Nm +module is the machine-dependent portion of the +.Nx +virtual memory system +.Xr uvm 9 . +The purpose of the +.Nm +module is to manage physical address maps, to program the +memory management hardware on the system, and perform any +cache operations necessary to ensure correct operation of +the virtual memory system. +The +.Nm +module is also responsible for maintaining certain information +required by +.Xr uvm 9 . +.Pp +In order to cope with hardware architectures that make the +invalidation of virtual address mappings expensive (e.g., +TLB invalidations, TLB shootdown operations for multiple +processors), the +.Nm +module is allowed to delay mapping invalidation or protection +operations until such time as they are actually necessary. +The functions that are allowed to delay such actions are +.Fn pmap_enter , +.Fn pmap_remove , +.Fn pmap_protect , +.Fn pmap_kenter_pa , +and +.Fn pmap_kremove . +Callers of these functions must use the +.Fn pmap_update +function to notify the +.Nm +module that the mappings need to be made correct. +Since the +.Nm +module is provided with information as to which processors are +using a given physical map, the +.Nm +module may use whatever optimizations it has available to reduce +the expense of virtual-to-physical mapping synchronization. +.Ss HEADER FILES AND DATA STRUCTURES +Machine-dependent code must provide the header file +.In machine/pmap.h . +This file contains the definition of the +.Dv pmap +structure: +.Bd -literal -offset indent +struct pmap { + /* Contents defined by pmap implementation. */ +}; +typedef struct pmap *pmap_t; +.Ed +.Pp +This header file may also define other data structures that the +.Nm +implementation uses. +.Pp +Note that all prototypes for +.Nm +interface functions are provided by the header file +.In uvm/uvm_pmap.h . +It is possible to override this behavior by defining the +C pre-processor macro +.Dv PMAP_EXCLUDE_DECLS . +This may be used to add a layer of indirection to +.Nm +API calls, for handling different MMU types in a single +.Nm +module, for example. +If the +.Dv PMAP_EXCLUDE_DECLS +macro is defined, +.In machine/pmap.h +.Em must +provide function prototypes in a block like so: +.Bd -literal -offset indent +#ifdef _KERNEL /* not exposed to user namespace */ +__BEGIN_DECLS /* make safe for C++ */ +/* Prototypes go here. */ +__END_DECLS +#endif /* _KERNEL */ +.Ed +.Pp +The header file +.In uvm/uvm_pmap.h +defines a structure for tracking +.Nm +statistics (see below). +This structure is defined as: +.Bd -literal -offset indent +struct pmap_statistics { + long resident_count; /* number of mapped pages */ + long wired_count; /* number of wired pages */ +}; +.Ed +.Ss WIRED MAPPINGS +The +.Nm +module is based on the premise that all information contained +in the physical maps it manages is redundant. +That is, physical map information may be +.Dq forgotten +by the +.Nm +module in the event that it is necessary to do so; it can be rebuilt +by +.Xr uvm 9 +by taking a page fault. +There is one exception to this rule: so-called +.Dq wired +mappings may not be forgotten. +Wired mappings are those for which either no high-level information +exists with which to rebuild the mapping, or mappings which are needed +by critical sections of code where taking a page fault is unacceptable. +Information about which mappings are wired is provided to the +.Nm +module when a mapping is established. +.Ss MODIFIED/REFERENCED INFORMATION +The +.Nm +module is required to keep track of whether or not a page managed +by the virtual memory system has been referenced or modified. +This information is used by +.Xr uvm 9 +to determine what happens to the page when scanned by the +pagedaemon. +.Pp +Many CPUs provide hardware support for tracking +modified/referenced information. +However, many CPUs, particularly modern RISC CPUs, do not. +On CPUs which lack hardware support for modified/referenced tracking, the +.Nm +module must emulate it in software. +There are several strategies for doing this, and the best strategy +depends on the CPU. +.Pp +The +.Dq referenced +attribute is used by the pagedaemon to determine if a page is +.Dq active . +Active pages are not candidates for re-use in the page replacement algorithm. +Accurate referenced information is not required for correct operation; if +supplying referenced information for a page is not feasible, then the +.Nm +implementation should always consider the +.Dq referenced +attribute to be +.Dv false . +.Pp +The +.Dq modified +attribute is used by the pagedaemon to determine if a page needs +to be cleaned (written to backing store; swap space, a regular file, etc.). +Accurate modified information +.Em must +be provided by the +.Nm +module for correct operation of the virtual memory system. +.Pp +Note that modified/referenced information is only tracked for +pages managed by the virtual memory system (i.e., pages for +which a vm_page structure exists). +In addition, only +.Dq managed +mappings of those pages have modified/referenced tracking. +Mappings entered with the +.Fn pmap_enter +function are +.Dq managed +mappings. +It is possible for +.Dq unmanaged +mappings of a page to be created, using the +.Fn pmap_kenter_pa +function. +The use of +.Dq unmanaged +mappings should be limited to code which may execute in interrupt context +(for example, the kernel memory allocator), or to enter mappings for +physical addresses which are not managed by the virtual memory system. +.Dq Unmanaged +mappings may only be entered into the kernel's virtual address space. +This constraint is placed on the callers of the +.Fn pmap_kenter_pa +and +.Fn pmap_kremove +functions so that the +.Nm +implementation need not block interrupts when manipulating data +structures or holding locks. +.Pp +Also note that the modified/referenced information must be tracked +on a per-page basis; they are not attributes of a mapping, but attributes +of a page. +Therefore, even after all mappings for a given page have +been removed, the modified/referenced information for that page +.Em must +be preserved. +The only time the modified/referenced attributes may +be cleared is when the virtual memory system explicitly calls the +.Fn pmap_clear_modify +and +.Fn pmap_clear_reference +functions. +These functions must also change any internal state necessary to detect +the page being modified or referenced again after the modified or +referenced state is cleared. +(Prior to +.Nx 1.6 , +.Nm +implementations could get away without this because UVM (and Mach VM +before that) always called +.Fn pmap_page_protect +before clearing the modified or referenced state, but UVM has been changed +to not do this anymore, so all +.Nm +implementations must now handle this.) +.Ss STATISTICS +The +.Nm +is required to keep statistics as to the number of +.Dq resident +pages and the number of +.Dq wired +pages. +.Pp +A +.Dq resident +page is one for which a mapping exists. +This statistic is used to compute the resident size of a process and +enforce resource limits. +Only pages (whether managed by the virtual memory system or not) +which are mapped into a physical map should be counted in the resident +count. +.Pp +A +.Dq wired +page is one for which a wired mapping exists. +This statistic is used to enforce resource limits. +.Pp +Note that it is recommended (though not required) that the +.Nm +implementation use the +.Dv pmap_statistics +structure in the tracking of +.Nm +statistics by placing it inside the +.Dv pmap +structure and adjusting the counts when mappings are established, changed, +or removed. +This avoids potentially expensive data structure traversals when the +statistics are queried. +.Ss REQUIRED FUNCTIONS +This section describes functions that a +.Nm +module must provide to the virtual memory system. +.Bl -tag -width indent -offset indent +.It void Fn "pmap_init" "void" +This function initializes the +.Nm +module. +It is called by +.Fn uvm_init +to initialize any data structures that the module needs to +manage physical maps. +.It pmap_t Fn "pmap_kernel" "void" +A machine independent macro which expands to +.Va kernel_pmap_ptr . +This variable must be exported by the platform's pmap module and it +must point to the kernel pmap. +.It void Fn "pmap_virtual_space" "vaddr_t *vstartp" "vaddr_t *vendp" +The +.Fn pmap_virtual_space +function is called to determine the initial kernel virtual address +space beginning and end. +These values are used to create the kernel's virtual memory map. +The function must set +.Fa *vstartp +to the first kernel virtual address that will be managed by +.Xr uvm 9 , +and must set +.Fa *vendp +to the last kernel virtual address that will be managed by +.Xr uvm 9 . +.Pp +If the +.Fn pmap_growkernel +feature is used by a +.Nm +implementation, then +.Fa *vendp +should be set to the maximum kernel virtual address allowed by the +implementation. +If +.Fn pmap_growkernel +is not used, then +.Fa *vendp +.Em must +be set to the maximum kernel virtual address that can be mapped with +the resources currently allocated to map the kernel virtual address +space. +.It pmap_t Fn "pmap_create" "void" +Create a physical map and return it to the caller. +The reference count on the new map is 1. +.It void Fn "pmap_destroy" "pmap_t pmap" +Drop the reference count on the specified physical map. +If the reference count drops to 0, all resources associated with the +physical map are released and the physical map destroyed. +In the case of a drop-to-0, no mappings will exist in the map. +The +.Nm +implementation may assert this. +.It void Fn "pmap_reference" "pmap_t pmap" +Increment the reference count on the specified physical map. +.It long Fn "pmap_resident_count" "pmap_t pmap" +Query the +.Dq resident pages +statistic for +.Fa pmap . +.Pp +Note that this function may be provided as a C pre-processor macro. +.It long Fn "pmap_wired_count" "pmap_t pmap" +Query the +.Dq wired pages +statistic for +.Fa pmap . +.Pp +Note that this function may be provided as a C pre-processor macro. +.It int Fn "pmap_enter" "pmap_t pmap" "vaddr_t va" "paddr_t pa" \ + "vm_prot_t prot" "u_int flags" +Create a mapping in physical map +.Fa pmap +for the physical address +.Fa pa +at the virtual address +.Fa va +with protection specified by bits in +.Fa prot : +.Bl -tag -width "VM_PROT_EXECUTE " -offset indent +.It VM_PROT_READ +The mapping must allow reading. +.It VM_PROT_WRITE +The mapping must allow writing. +.It VM_PROT_EXECUTE +The page mapped contains instructions that will be executed by the +processor. +.El +.Pp +The +.Fa flags +argument contains protection bits (the same bits as used in the +.Fa prot +argument) indicating the type of access that caused the mapping to +be created. +This information may be used to seed modified/referenced +information for the page being mapped, possibly avoiding redundant faults +on platforms that track modified/referenced information in software. +Other information provided by +.Fa flags : +.Bl -tag -width "PMAP_CANFAIL " -offset indent +.It PMAP_WIRED +The mapping being created is a wired mapping. +.It PMAP_CANFAIL +The call to +.Fn pmap_enter +is allowed to fail. +If this flag is +.Em not +set, and the +.Fn pmap_enter +call is unable to create the mapping, perhaps due to insufficient +resources, the +.Nm +module must panic. +.It PMAP_NOCACHE +The mapping being created is +.Em not +cached. +Write accesses have a write-through policy. +No speculative memory accesses. +.It PMAP_WRITE_COMBINE +The mapping being created is +.Em not +cached. +Writes are combined and done in one burst. +Speculative read accesses may be allowed. +.It PMAP_WRITE_BACK +All accesses to the created mapping are cached. +On reads, cachelines become shared or exclusive if allocated on cache miss. +On writes, cachelines become modified on a cache miss. +.It PMAP_NOCACHE_OVR +Same as PMAP_NOCACHE but mapping is overrideable (e.g. on x86 by MTRRs). +.El +.Pp +The access type provided in the +.Fa flags +argument will never exceed the protection specified by +.Fa prot . +The +.Nm +implementation may assert this. +Note that on systems that do not provide hardware support for +tracking modified/referenced information, modified/referenced +information for the page +.Em must +be seeded with the access type provided in +.Fa flags +if the +.Dv PMAP_WIRED +flag is set. +This is to prevent a fault for the purpose of tracking +modified/referenced information from occurring while the system is in +a critical section where a fault would be unacceptable. +.Pp +Note that +.Fn pmap_enter +is sometimes called to enter a mapping at a virtual address +for which a mapping already exists. +In this situation, the implementation must take whatever action is +necessary to invalidate the previous mapping before entering the new one. +.Pp +Also note that +.Fn pmap_enter +is sometimes called to change the protection for a pre-existing +mapping, or to change the +.Dq wired +attribute for a pre-existing mapping. +.Pp +The +.Fn pmap_enter +function returns 0 on success or an error code indicating the mode +of failure. +.It void Fn "pmap_remove" "pmap_t pmap" "vaddr_t sva" "vaddr_t eva" +Remove mappings from the virtual address range +.Fa sva +to +.Fa eva +from the specified physical map. +.It bool Fn "pmap_remove_all" "pmap_t pmap" +This function is a hint to the +.Nm pmap +implementation that all entries in +.Fa pmap +will be removed before any more entries are entered. +Following this call, there will be +.Fn pmap_remove +calls resulting in every mapping being removed, followed by either +.Fn pmap_destroy +or +.Fn pmap_update . +No other +.Nm pmap +interfaces which take +.Fa pmap +as an argument will be called during this process. +Other interfaces which might need to access +.Fa pmap +(such as +.Fn pmap_page_protect ) +are permitted during this process. +.Pp +The +.Nm pmap +implementation is free to either remove all the +.Nm pmap Ns 's +mappings immediately in +.Fn pmap_remove_all , +or to use the knowledge of the upcoming +.Fn pmap_remove +calls to optimize the removals (or to just ignore this call). +.Pp +If all mappings in the address space have been removed, +.Fn pmap_remove_all +should return +.Dv true +to indicate that that the pmap is now empty. +In this case UVM will skip all subsequent calls to +.Fn pmap_remove +and +.Fn pmap_update +for the pmap, that would otherwise be required to clean it out. +If any mappings could possibly remain, +.Fn pmap_remove_all +must return +.Dv false . +.It void Fn "pmap_protect" "pmap_t pmap" "vaddr_t sva" "vaddr_t eva" \ + "vm_prot_t prot" +Set the protection of the mappings in the virtual address range +.Fa sva +to +.Fa eva +in the specified physical map. +.It void Fn "pmap_unwire" "pmap_t pmap" "vaddr_t va" +Clear the +.Dq wired +attribute on the mapping for virtual address +.Fa va . +.It bool Fn "pmap_extract" "pmap_t pmap" "vaddr_t va" "paddr_t *pap" +This function extracts a mapping from the specified physical map. +It serves two purposes: to determine if a mapping exists for the specified +virtual address, and to determine what physical address is mapped at the +specified virtual address. +The +.Fn pmap_extract +should return the physical address for any kernel-accessible address, +including KSEG-style direct-mapped kernel addresses. +.Pp +The +.Fn pmap_extract +function returns +.Dv false +if a mapping for +.Fa va +does not exist. +Otherwise, it returns +.Dv true +and places the physical address mapped at +.Fa va +into +.Fa *pap +if the +.Fa pap +argument is non-NULL. +.It void Fn "pmap_kenter_pa" "vaddr_t va" "paddr_t pa" "vm_prot_t prot" \ + "u_int flags" +Enter an +.Dq unmanaged +mapping for physical address +.Fa pa +at virtual address +.Fa va +with protection specified by bits in +.Fa prot : +.Bl -tag -width "VM_PROT_EXECUTE " -offset indent +.It VM_PROT_READ +The mapping must allow reading. +.It VM_PROT_WRITE +The mapping must allow writing. +.It VM_PROT_EXECUTE +The page mapped contains instructions that will be executed by the +processor. +.El +.Pp +Information provided by +.Fa flags : +.Bl -tag -width "PMAP_NOCACHE " -offset indent +.It PMAP_NOCACHE +The mapping being created is +.Em not +cached. +Write accesses have a write-through policy. +No speculative memory accesses. +.It PMAP_WRITE_COMBINE +The mapping being created is +.Em not +cached. +Writes are combined and done in one burst. +Speculative read accesses may be allowed. +.It PMAP_WRITE_BACK +All accesses to the created mapping are cached. +On reads, cachelines become shared or exclusive if allocated on cache miss. +On writes, cachelines become modified on a cache miss. +.It PMAP_NOCACHE_OVR +Same as PMAP_NOCACHE but mapping is overrideable (e.g. on x86 by MTRRs). +.El +.Pp +Mappings of this type are always +.Dq wired , +and are unaffected by routines that alter the protection of pages +(such as +.Fn pmap_page_protect ) . +Such mappings are also not included in the gathering of modified/referenced +information about a page. +Mappings entered with +.Fn pmap_kenter_pa +by machine-independent code +.Em must not +have execute permission, as the +data structures required to track execute permission of a page may not +be available to +.Fn pmap_kenter_pa . +Machine-independent code is not allowed to enter a mapping with +.Fn pmap_kenter_pa +at a virtual address for which a valid mapping already exists. +Mappings created with +.Fn pmap_kenter_pa +may be removed only with a call to +.Fn pmap_kremove . +.Pp +Note that +.Fn pmap_kenter_pa +must be safe for use in interrupt context. +.Fn splvm +blocks interrupts that might cause +.Fn pmap_kenter_pa +to be called. +.It void Fn "pmap_kremove" "vaddr_t va" "vsize_t size" +Remove all mappings starting at virtual address +.Fa va +for +.Fa size +bytes from the kernel physical map. +All mappings that are removed must be the +.Dq unmanaged +type created with +.Fn pmap_kenter_pa . +The implementation may assert this. +.It void Fn "pmap_copy" "pmap_t dst_map" "pmap_t src_map" "vaddr_t dst_addr" \ + "vsize_t len" "vaddr_t src_addr" +This function copies the mappings starting at +.Fa src_addr +in +.Fa src_map +for +.Fa len +bytes into +.Fa dst_map +starting at +.Fa dst_addr . +.Pp +Note that while this function is required to be provided by a +.Nm +implementation, it is not actually required to do anything. +.Fn pmap_copy +is merely advisory (it is used in the +.Xr fork 2 +path to +.Dq pre-fault +the child's address space). +.It void Fn "pmap_update" "pmap_t pmap" +This function is used to inform the +.Nm +module that all physical mappings, for the specified pmap, must now be +correct. +That is, all delayed virtual-to-physical mappings updates (such as TLB +invalidation or address space identifier updates) must be completed. +This routine must be used after calls to +.Fn pmap_enter , +.Fn pmap_remove , +.Fn pmap_protect , +.Fn pmap_kenter_pa , +and +.Fn pmap_kremove +in order to ensure correct operation of the virtual memory system. +.Pp +If a +.Nm +implementation does not delay virtual-to-physical mapping updates, +.Fn pmap_update +has no operation. +In this case, the call may be deleted using a C pre-processor macro in +.In machine/pmap.h . +.It void Fn "pmap_activate" "struct lwp *l" +Activate the physical map used by the process behind lwp +.Fa l . +on the current CPU. +This is called by the virtual memory system when the +virtual memory context for a process is changed, and is also +used by the context switch code to program the memory management hardware +with the process's page table base, etc. +All calls to +.Fn pmap_activate +from machine-independent code are made with preemption disabled and with +.Fa l +as the current lwp. +.Pp +The +.Fn pmap_activate +call, like +.Fn pmap_deactivate , +must never block, as it is used for context switching. +.It void Fn "pmap_deactivate" "struct lwp *l" +Deactivate the physical map used by the process behind lwp +.Fa l . +It is generally used in conjunction with +.Fn pmap_activate . +Like +.Fn pmap_activate , +.Fn pmap_deactivate +is called by machine-independent code with preemption disabled and with +.Fa l +as the current lwp. +.Pp +As above, +.Fn pmap_deactivate +must never block. +.It void Fn "pmap_zero_page" "paddr_t pa" +Zero the PAGE_SIZE sized region starting at physical address +.Fa pa . +The +.Nm +implementation must take whatever steps are necessary to map the +page to a kernel-accessible address and zero the page. +It is suggested that implementations use an optimized zeroing algorithm, +as the performance of this function directly impacts page fault performance. +The implementation may assume that the region is +PAGE_SIZE aligned and exactly PAGE_SIZE bytes in length. +.Pp +Note that the cache configuration of the platform should also be +considered in the implementation of +.Fn pmap_zero_page . +For example, on systems with a physically-addressed cache, the cache +load caused by zeroing the page will not be wasted, as the zeroing is +usually done on-demand. +However, on systems with a virtually-addressed cached, the cache load +caused by zeroing the page +.Em will +be wasted, as the page will be mapped at a virtual address which is +different from that used to zero the page. +In the virtually-addressed cache case, care should also be taken to +avoid cache alias problems. +.It void Fn "pmap_copy_page" "paddr_t src" "paddr_t dst" +Copy the PAGE_SIZE sized region starting at physical address +.Fa src +to the same sized region starting at physical address +.Fa dst . +The +.Nm +implementation must take whatever steps are necessary to map the +source and destination pages to a kernel-accessible address and +perform the copy. +It is suggested that implementations use an optimized copy algorithm, +as the performance of this function directly impacts page fault performance. +The implementation may assume that both regions are PAGE_SIZE aligned +and exactly PAGE_SIZE bytes in length. +.Pp +The same cache considerations that apply to +.Fn pmap_zero_page +apply to +.Fn pmap_copy_page . +.It void Fn "pmap_page_protect" "struct vm_page *pg" "vm_prot_t prot" +Lower the permissions for all mappings of the page +.Fa pg +to +.Fa prot . +This function is used by the virtual memory system to implement +copy-on-write (called with VM_PROT_READ set in +.Fa prot ) +and to revoke all mappings when cleaning a page (called with +no bits set in +.Fa prot ) . +Access permissions must never be added to a page as a result of +this call. +.It bool Fn "pmap_clear_modify" "struct vm_page *pg" +Clear the +.Dq modified +attribute on the page +.Fa pg . +.Pp +The +.Fn pmap_clear_modify +function returns +.Dv true +or +.Dv false +indicating whether or not the +.Dq modified +attribute was set on the page before it was cleared. +.Pp +Note that this function may be provided as a C pre-processor macro. +.It bool Fn "pmap_clear_reference" "struct vm_page *pg" +Clear the +.Dq referenced +attribute on the page +.Fa pg . +.Pp +The +.Fn pmap_clear_reference +function returns +.Dv true +or +.Dv false +indicating whether or not the +.Dq referenced +attribute was set on the page before it was cleared. +.Pp +Note that this function may be provided as a C pre-processor macro. +.It bool Fn "pmap_is_modified" "struct vm_page *pg" +Test whether or not the +.Dq modified +attribute is set on page +.Fa pg . +.Pp +Note that this function may be provided as a C pre-processor macro. +.It bool Fn "pmap_is_referenced" "struct vm_page *pg" +Test whether or not the +.Dq referenced +attribute is set on page +.Fa pg . +.Pp +Note that this function may be provided as a C pre-processor macro. +.It paddr_t Fn "pmap_phys_address" "paddr_t cookie" +Convert a cookie returned by a device +.Fn mmap +function into a physical address. +This function is provided to accommodate systems which have physical +address spaces larger than can be directly addressed by the platform's +.Fa paddr_t +type. +The existence of this function is highly dubious, and it is +expected that this function will be removed from the +.Nm pmap +API in a future release of +.Nx . +.Pp +Note that this function may be provided as a C pre-processor macro. +.El +.Ss OPTIONAL FUNCTIONS +This section describes several optional functions in the +.Nm +API. +.Bl -tag -width indent -offset indent +.It vaddr_t Fn "pmap_steal_memory" "vsize_t size" "vaddr_t *vstartp" \ + "vaddr_t *vendp" +This function is a bootstrap memory allocator, which may be provided +as an alternative to the bootstrap memory allocator used within +.Xr uvm 9 +itself. +It is particularly useful on systems which provide for example a direct-mapped +memory segment. +This function works by stealing pages from the (to be) managed memory +pool, which has already been provided to +.Xr uvm 9 +in the vm_physmem[] array. +The pages are then mapped, or otherwise made accessible to the kernel, +in a machine-dependent way. +The memory must be zeroed by +.Fn pmap_steal_memory . +Note that memory allocated with +.Fn pmap_steal_memory +will never be freed, and mappings made by +.Fn pmap_steal_memory +must never be +.Dq forgotten . +.Pp +Note that +.Fn pmap_steal_memory +should not be used as a general-purpose early-startup memory +allocation routine. +It is intended to be used only by the +.Fn uvm_pageboot_alloc +routine and its supporting routines. +If you need to allocate memory before the virtual memory system is +initialized, use +.Fn uvm_pageboot_alloc . +See +.Xr uvm 9 +for more information. +.Pp +The +.Fn pmap_steal_memory +function returns the kernel-accessible address of the allocated memory. +If no memory can be allocated, or if allocated memory cannot be mapped, +the function must panic. +.Pp +If the +.Fn pmap_steal_memory +function uses address space from the range provided to +.Xr uvm 9 +by the +.Fn pmap_virtual_space +call, then +.Fn pmap_steal_memory +must adjust +.Fa *vstartp +and +.Fa *vendp +upon return. +.Pp +The +.Fn pmap_steal_memory +function is enabled by defining the C pre-processor macro +.Dv PMAP_STEAL_MEMORY +in +.In machine/pmap.h . +.It vaddr_t Fn "pmap_growkernel" "vaddr_t maxkvaddr" +Management of the kernel virtual address space is complicated by the +fact that it is not always safe to wait for resources with which to +map a kernel virtual address. +However, it is not always desirable to pre-allocate all resources +necessary to map the entire kernel virtual address space. +.Pp +The +.Fn pmap_growkernel +interface is designed to help alleviate this problem. +The virtual memory startup code may choose to allocate an initial set +of mapping resources (e.g., page tables) and set an internal variable +indicating how much kernel virtual address space can be mapped using +those initial resources. +Then, when the virtual memory system wishes to map something +at an address beyond that initial limit, it calls +.Fn pmap_growkernel +to pre-allocate more sources with which to create the mapping. +Note that once additional kernel virtual address space mapping resources +have been allocated, they should not be freed; it is likely they will +be needed again. +.Pp +The +.Fn pmap_growkernel +function returns the new maximum kernel virtual address that can be mapped +with the resources it has available. +If new resources cannot be allocated, +.Fn pmap_growkernel +must panic. +.Pp +The +.Fn pmap_growkernel +function is enabled by defining the C pre-processor macro +.Dv PMAP_GROWKERNEL +in +.In machine/pmap.h . +.It void Fn "pmap_fork" "pmap_t src_map" "pmap_t dst_map" +Some +.Nm +implementations may need to keep track of other information not +directly related to the virtual address space. +For example, on the i386 port, the Local Descriptor Table state of a +process is associated with the pmap (this is due to the fact that +applications manipulate the Local Descriptor Table directly expect it +to be logically associated with the virtual memory state of the process). +.Pp +The +.Fn pmap_fork +function is provided as a way to associate information from +.Fa src_map +with +.Fa dst_map +when a +.Dv vmspace +is forked. +.Fn pmap_fork +is called from +.Fn uvmspace_fork . +.Pp +The +.Fn pmap_fork +function is enabled by defining the C pre-processor macro +.Dv PMAP_FORK +in +.In machine/pmap.h . +.It vaddr_t Fn "PMAP_MAP_POOLPAGE" "paddr_t pa" +This function is used by the +.Xr pool 9 +memory pool manager. +Pools allocate backing pages one at a time. +This is provided as a means to use hardware features such as a +direct-mapped memory segment to map the pages used by the +.Xr pool 9 +allocator. +This can lead to better performance by e.g. reducing TLB contention. +.Pp +.Fn PMAP_MAP_POOLPAGE +returns the kernel-accessible address of the page being mapped. +It must always succeed. +.Pp +The use of +.Fn PMAP_MAP_POOLPAGE +is enabled by defining it as a C pre-processor macro in +.In machine/pmap.h . +If +.Fn PMAP_MAP_POOLPAGE +is defined, +.Fn PMAP_UNMAP_POOLPAGE +must also be defined. +.Pp +The following is an example of how to define +.Fn PMAP_MAP_POOLPAGE : +.Bd -literal -offset indent +#define PMAP_MAP_POOLPAGE(pa) MIPS_PHYS_TO_KSEG0((pa)) +.Ed +.Pp +This takes the physical address of a page and returns the KSEG0 +address of that page on a MIPS processor. +.It paddr_t Fn "PMAP_UNMAP_POOLPAGE" "vaddr_t va" +This function is the inverse of +.Fn PMAP_MAP_POOLPAGE . +.Pp +.Fn PMAP_UNMAP_POOLPAGE +returns the physical address of the page corresponding to the +provided kernel-accessible address. +.Pp +The use of +.Fn PMAP_UNMAP_POOLPAGE +is enabled by defining it as a C pre-processor macro in +.In machine/pmap.h . +If +.Fn PMAP_UNMAP_POOLPAGE +is defined, +.Fn PMAP_MAP_POOLPAGE +must also be defined. +.Pp +The following is an example of how to define +.Fn PMAP_UNMAP_POOLPAGE : +.Bd -literal -offset indent +#define PMAP_UNMAP_POOLPAGE(pa) MIPS_KSEG0_TO_PHYS((va)) +.Ed +.Pp +This takes the KSEG0 address of a previously-mapped pool page +and returns the physical address of that page on a MIPS processor. +.It void Fn "PMAP_PREFER" "vaddr_t hint" "vaddr_t *vap" "vsize_t sz" "int td" +This function is used by +.Xr uvm_map 9 +to adjust a virtual address being allocated in order to avoid +cache alias problems. +If necessary, the virtual address pointed by +.Fa vap +will be advanced. +.Fa hint +is an object offset which will be mapped into the resulting virtual address, and +.Fa sz +is size of the region being mapped in bytes. +.Fa td +indicates if the machine dependent pmap uses the topdown VM. +.Pp +The use of +.Fn PMAP_PREFER +is enabled by defining it as a C pre-processor macro in +.In machine/pmap.h . +.It void Fn "pmap_procwr" "struct proc *p" "vaddr_t va" "vsize_t size" +Synchronize CPU instruction caches of the specified range. +The address space is designated by +.Fa p . +This function is typically used to flush instruction caches +after code modification. +.Pp +The use of +.Fn pmap_procwr +is enabled by defining a C pre-processor macro +.Dv PMAP_NEED_PROCWR +in +.In machine/pmap.h . +.El +.Sh SEE ALSO +.Xr uvm 9 +.Sh HISTORY +The +.Nm +module was originally part of the design of the virtual memory system +in the Mach Operating System. +The goal was to provide a clean separation between the machine-independent +and the machine-dependent portions of the virtual memory system, in +stark contrast to the original +.Bx 3 +virtual memory system, which was specific to the VAX. +.Pp +Between +.Bx 4.3 +and +.Bx 4.4 , +the Mach virtual memory system, including the +.Nm +API, was ported to +.Bx +and included in the +.Bx 4.4 +release. +.Pp +.Nx +inherited the +.Bx +version of the Mach virtual memory system. +.Nx 1.4 +was the first +.Nx +release with the new +.Xr uvm 9 +virtual memory system, which included several changes to the +.Nm +API. +Since the introduction of +.Xr uvm 9 , +the +.Nm +API has evolved further. +.Sh AUTHORS +The original Mach VAX +.Nm +module was written by +.An Avadis Tevanian, Jr. +and +.An Michael Wayne Young . +.Pp +.An Mike Hibler +did the integration of the Mach virtual memory system into +.Bx 4.4 +and implemented a +.Nm +module for the Motorola 68020+68851/68030/68040. +.Pp +The +.Nm +API as it exists in +.Nx +is derived from +.Bx 4.4 , +and has been modified by +.An Chuck Cranor , +.An Charles M. Hannum , +.An Chuck Silvers , +.An Wolfgang Solfrank , +.An Bill Sommerfeld , +and +.An Jason R. Thorpe . +.Pp +The author of this document is +.An Jason R. Thorpe +.Aq thorpej@NetBSD.org . +.Sh BUGS +The use and definition of +.Fn pmap_activate +and +.Fn pmap_deactivate +needs to be reexamined. +.Pp +The use of +.Fn pmap_copy +needs to be reexamined. +Empirical evidence suggests that performance of the system suffers when +.Fn pmap_copy +actually performs its defined function. +This is largely due to the fact that the copy of the virtual-to-physical +mappings is wasted if the process calls +.Xr execve 2 +after +.Xr fork 2 . +For this reason, it is recommended that +.Nm +implementations leave the body of the +.Fn pmap_copy +function empty for now. diff --git a/static/netbsd/man9/pmatch.9 b/static/netbsd/man9/pmatch.9 new file mode 100644 index 00000000..3eb8e0a4 --- /dev/null +++ b/static/netbsd/man9/pmatch.9 @@ -0,0 +1,68 @@ +.\" $NetBSD: pmatch.9,v 1.3 2009/10/19 18:41:09 bouyer Exp $ +.\" +.\" Copyright (c) 2003 Manuel Bouyer. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.Dd October 12, 2003 +.Dt PMATCH 9 +.Os +.Sh NAME +.Nm pmatch +.Nd performs pattern matching on strings +.Sh SYNOPSIS +.In sys/systm.h +.Ft int +.Fn pmatch "const char *string" "const char *pattern" "const char **estr" +.Sh DESCRIPTION +Extract substring matching +.Fa pattern +from +.Fa string . +If not +.Dv NULL , +.Fa estr +points to the end of the longest exact or substring match. +.Pp +.Fn pmatch +uses the following metacharacters: +.Bl -tag -width Ds +.It Li \&? +match any single character. +.It Li * +match any character 0 or more times. +.It Li \&[ +define a range of characters that will match. +The range is defined by 2 characters separated by a +.Sq Li \&- . +The range definition has to end with a +.Sq Li \&] . +A +.Sq Li ^ +following the +.Sq Li \&[ +will negate the range. +.El +.Sh RETURN VALUES +.Fn pmatch +will return 2 for an exact match, 1 for a substring match, 0 for no match and +\-1 if an error occurs. diff --git a/static/netbsd/man9/pmf.9 b/static/netbsd/man9/pmf.9 new file mode 100644 index 00000000..a20f5dc3 --- /dev/null +++ b/static/netbsd/man9/pmf.9 @@ -0,0 +1,310 @@ +.\" $NetBSD: pmf.9,v 1.23 2024/03/09 05:22:05 riastradh Exp $ +.\" +.\" Copyright (c) 2007 Jared D. McNeill <jmcneill@invisible.ca> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 9, 2024 +.Dt PMF 9 +.Os +.Sh NAME +.Nm PMF , +.Nm pmf_device_register , +.Nm pmf_device_register1 , +.Nm pmf_device_deregister , +.Nm pmf_device_suspend , +.Nm pmf_device_resume , +.Nm pmf_device_recursive_suspend , +.Nm pmf_device_recursive_resume , +.Nm pmf_device_resume_subtree , +.Nm pmf_class_network_register , +.Nm pmf_class_input_register , +.Nm pmf_class_display_register , +.Nm pmf_system_suspend , +.Nm pmf_system_resume , +.Nm pmf_system_shutdown , +.Nm pmf_event_register , +.Nm pmf_event_deregister , +.Nm pmf_event_inject , +.Nm pmf_set_platform , +.Nm pmf_get_platform +.Nd power management and inter-driver messaging framework +.Sh SYNOPSIS +.In sys/device.h +.Ft bool +.Fn pmf_device_register "device_t dev" "bool (*suspend)(device_t dev, const pmf_qual_t *qual)" "bool (*resume)(device_t dev, const pmf_qual_t *qual)" +.Ft bool +.Fn pmf_device_register1 "device_t dev" "bool (*suspend)(device_t dev, const pmf_qual_t *qual)" "bool (*resume)(device_t dev, const pmf_qual_t *qual)" "bool (*shutdown)(device_t dev, int how)" +.Ft void +.Fn pmf_device_deregister "device_t dev" +.Ft bool +.Fn pmf_device_suspend "device_t dev" "const pmf_qual_t *qual" +.Ft bool +.Fn pmf_device_resume "device_t dev" "const pmf_qual_t *qual" +.Ft bool +.Fn pmf_device_recursive_suspend "device_t dev" "const pmf_qual_t *qual" +.Ft bool +.Fn pmf_device_recursive_resume "device_t dev" "const pmf_qual_t *qual" +.Ft bool +.Fn pmf_device_subtree_resume "device_t dev" "const pmf_qual_t *qual" +.Ft void +.Fn pmf_class_network_register "device_t dev" "struct ifnet *ifp" +.Ft bool +.Fn pmf_class_input_register "device_t dev" +.Ft bool +.Fn pmf_class_display_register "device_t dev" +.Ft bool +.Fn pmf_system_suspend "const pmf_qual_t *qual" +.Ft bool +.Fn pmf_system_resume "const pmf_qual_t *qual" +.Ft void +.Fn pmf_system_shutdown "int" +.Ft bool +.Fn pmf_event_register "device_t dev" "pmf_generic_event_t ev" "void (*handler)(device_t dev)" "bool global" +.Ft void +.Fn pmf_event_deregister "device_t dev" "pmf_generic_event_t ev" "void (*handler)(device_t dev)" "bool global" +.Ft bool +.Fn pmf_event_inject "device_t dev" "pmf_generic_event_t ev" +.Ft bool +.Fn pmf_set_platform "const char *key" "const char *value" +.Ft const char * +.Fn pmf_get_platform "const char *key" +.Sh DESCRIPTION +The machine-independent +.Nm +framework provides power management and inter-driver messaging support +for device drivers. +.Sh DATA TYPES +Drivers for devices implementing +.Nm +may make use of the following data type: +.Bl -tag -width compact +.It Fa pmf_qual_t +An opaque aggregate of qualifications on a +.Nm +suspend or resume call. +.It Fa pmf_generic_event_t +A device driver can register as a listener for specific events, or inject +events into the message queue. +The following message types are defined: +.Bl -item -compact -offset indent +.It +.Dv PMFE_DISPLAY_ON +.It +.Dv PMFE_DISPLAY_REDUCED +.It +.Dv PMFE_DISPLAY_STANDBY +.It +.Dv PMFE_DISPLAY_SUSPEND +.It +.Dv PMFE_DISPLAY_OFF +.It +.Dv PMFE_DISPLAY_BRIGHTNESS_UP +.It +.Dv PMFE_DISPLAY_BRIGHTNESS_DOWN +.It +.Dv PMFE_AUDIO_VOLUME_UP +.It +.Dv PMFE_AUDIO_VOLUME_DOWN +.It +.Dv PMFE_AUDIO_VOLUME_TOGGLE +.It +.Dv PMFE_CHASSIS_LID_CLOSE +.It +.Dv PMFE_CHASSIS_LID_OPEN +.El +.El +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn pmf_device_register "dev" "suspend" "resume" +Register a device with the power management framework. +The +.Fa suspend +and +.Fa resume +functions are passed +.Fa dev +and a +.Fa pmf_qual_t , +and will be called when the system state changes; +they should return +.Dv true +on success and +.Dv false +on failure. +If either +.Fa suspend +or +.Fa resume +is +.Dv NULL +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. +.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 , +but additionally registers a shutdown handler. +During system shutdown, +.Fn pmf_system_shutdown +calls +.Fa shutdown +on +.Fa dev +with the +.Xr reboot 2 +.Dq howto +in the second argument. +.Fa shutdown +should return +.Dv true +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" +Suspend a device by first calling the class suspend handler, followed by +the driver suspend handler, and finally the bus suspend handler. +.It Fn pmf_device_resume "dev" "qual" +Resume a device by first calling the bus resume handler, followed by the +driver resume handler, and finally the class resume handler. +.It Fn pmf_device_recursive_suspend "dev" "qual" +As +.Fn pmf_device_suspend , +but ensures that all child devices of +.Fa dev +are suspended. +.It Fn pmf_device_recursive_resume "dev" "qual" +As +.Fn pmf_device_resume , +but ensures that all parent devices of +.Fa dev +are resumed. +.It Fn pmf_device_subtree_resume "dev" "qual" +As +.Fn pmf_device_resume , +but ensures that all child devices of +.Fa dev +are resumed. +.It Fn pmf_class_network_register "dev" "ifp" +Register a device with the power management framework as a network-class +device. +.It Fn pmf_class_input_register "dev" +Register a device with the power management framework as an input-class +device. +.It Fn pmf_class_display_register "dev" +Register a device with the power management framework as a display-class +device. +.It Fn pmf_system_suspend "qual" +Suspend all attached devices. +Devices are suspended by traversing the autoconfiguration tree +beginning with the leaf nodes. +This function will fail if any attached drivers do not support the power +management framework. +.It Fn pmf_system_resume "qual" +Resume all attached devices. +Devices are resumed by traversing the +autoconfiguration tree beginning with devices that do not have a parent. +This function will fail if any attached drivers do not support the power +management framework. +.It Fn pmf_system_shutdown "int" +Shutdown all attached devices. +Devices are shut down by traversing the +autoconfiguration tree beginning with the leaf nodes. +The integer argument is passed to the driver shutdown functions. +It should contain the +.Xr reboot 2 +.Dq howto +argument. +This function ignores the presence of attached drivers that do not support the +power management framework. +.It Fn pmf_event_register "dev" "ev" "handler" "global" +Register the callback +.Fa handler +to be called whenever an +.Fa ev +event is triggered. +If +.Fa global +is +.Dv true , +.Fa handler +accepts anonymous events from +.Fn pmf_event_inject . +.It Fn pmf_event_deregister "dev" "ev" "handler" "global" +Deregister the callback previously registered with +.Fn pmf_event_register . +.It Fn pmf_event_inject "dev" "ev" +Inject an inter-driver message into the message queue. +If +.Fa dev +is +.Dv NULL , +the event is considered to be anonymous and one or more drivers +may handle this event, otherwise the event is delivered directly to +the callback registered by +.Fa dev . +.It Fn pmf_set_platform "key" "value" +Insert a name-value pair into the platform information database. +.It Fn pmf_get_platform "key" +Retrieve the value for +.Fa key +from the platform information database. +Returns +.Dv NULL +if the key is not present. +.El +.Sh CODE REFERENCES +The power management framework is implemented within the files +.Pa sys/sys/pmf.h , +.Pa sys/sys/device.h , +.Pa sys/kern/kern_pmf.c , +and +.Pa sys/kern/subr_autoconf.c . +.Sh SEE ALSO +.Xr autoconf 9 , +.Xr driver 9 +.Sh HISTORY +The +.Nm +framework appeared in +.Nx 5.0 . +.Sh AUTHORS +.An Jared D. McNeill Aq Mt jmcneill@NetBSD.org +.An Joerg Sonnenberger Aq Mt joerg@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" diff --git a/static/netbsd/man9/pool.9 b/static/netbsd/man9/pool.9 new file mode 100644 index 00000000..7572c3e7 --- /dev/null +++ b/static/netbsd/man9/pool.9 @@ -0,0 +1,322 @@ +.\" $NetBSD: pool.9,v 1.50 2021/12/22 17:28:17 thorpej Exp $ +.\" +.\" Copyright (c) 1997, 1998, 2007 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Paul Kranenburg. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 12, 2020 +.Dt POOL 9 +.Os +.Sh NAME +.Nm pool_init , +.Nm pool_destroy , +.Nm pool_get , +.Nm pool_put , +.Nm pool_prime , +.Nm pool_sethiwat , +.Nm pool_setlowat , +.Nm pool_sethardlimit +.Nd resource-pool manager +.Sh SYNOPSIS +.In sys/pool.h +.Ft void +.Fo pool_init +.Fa "struct pool *pp" +.Fa "size_t size" +.Fa "u_int align" +.Fa "u_int align_offset" +.Fa "int flags" +.Fa "const char *wchan" +.Fa "struct pool_allocator *palloc" +.Fa "int ipl" +.Fc +.Ft void +.Fn pool_destroy "struct pool *pp" +.Ft void * +.Fn pool_get "struct pool *pp" "int flags" +.Ft void +.Fn pool_put "struct pool *pp" "void *item" +.Ft void +.Fn pool_prime "struct pool *pp" "int n" +.Ft void +.Fn pool_sethiwat "struct pool *pp" "int n" +.Ft void +.Fn pool_setlowat "struct pool *pp" "int n" +.Ft void +.Fn pool_sethardlimit "struct pool *pp" "int n" \ +"const char *warnmess" "int ratecap" +.Sh DESCRIPTION +These utility routines provide management of pools of fixed-sized +areas of memory. +Resource pools set aside an amount of memory for exclusive use by the resource +pool owner. +This can be used by applications to guarantee the availability of a minimum +amount of memory needed to continue operation independent of the memory +resources currently available from the system-wide memory allocator +.Pq Xr malloc 9 . +.Ss INITIALIZING A POOL +The function +.Fn pool_init +initializes a resource pool. +The arguments are: +.Bl -tag -offset indent -width "align_offset" +.It Fa pp +The handle identifying the pool resource instance. +.It Fa size +Specifies the size of the memory items managed by the pool. +.It Fa align +Specifies the memory address alignment of the items returned by +.Fn pool_get . +This argument must be a power of two. +If zero, +the alignment defaults to an architecture-specific natural alignment. +.It Fa align_offset +The offset within an item to which the +.Fa align +parameter applies. +.It Fa flags +Should be set to zero, +.Dv PR_NOTOUCH , +or +.Dv PR_PSERIALIZE . +If +.Dv PR_NOTOUCH +is given, free items are never used to keep internal state so that +the pool can be used for non memory backed objects. +If +.Dv PR_PSERIALIZE +is given, then the allocator guarantees that a passive serialization +barrier equivalent to +.Dq xc_barrier(0) +will be performed before the object's backing store is returned to +the system. +.Dv PR_PSERIALIZE +implies +.Dv PR_NOTOUCH . +Because of the guarantees provided by +.Dv PR_PSERIALIZE , +objects muste never be freed to a pool using this option from either +hard or soft interrupt context, as doing so may block. +.It Fa wchan +The +.Sq wait channel +passed on to +.Xr cv_wait 9 +if +.Fn pool_get +must wait for items to be returned to the pool. +.It Fa palloc +Can be set to +.Dv NULL +or +.Dv pool_allocator_kmem , +in which case the default kernel memory allocator will be used. +It can also be set to +.Dv pool_allocator_nointr +when the pool will never be accessed from interrupt context. +.It Fa ipl +Specifies an interrupt priority level that will block all interrupt +handlers that could potentially access the pool. +.El +.Ss DESTROYING A POOL +The function +.Fn pool_destroy +destroys a resource pool. +It takes a single argument +.Fa pp +identifying the pool resource instance. +.Ss ALLOCATING ITEMS FROM A POOL +.Fn pool_get +allocates an item from the pool and returns a pointer to it. +The arguments are: +.Bl -tag -offset indent -width "flags" +.It Fa pp +The handle identifying the pool resource instance. +.It Fa flags +The flags can be used to define behaviour in case the pooled resources +are depleted. +If no resources are available and +.Dv PR_NOWAIT +is given, +.Fn pool_get +returns +.Dv NULL . +If +.Dv PR_WAITOK +is given and allocation is attempted with no resources available, +the function will sleep until items are returned to the pool. +.\"Undefined behaviour results if +.\".Dv PR_MALLOCOK +.\"is specified on a pool handle that was created using client-provided +.\"storage. +.\" a bunch of other flags aren't documented. +If both +.Dv PR_LIMITFAIL +and +.Dv PR_WAITOK +are specified, and the pool has reached its hard limit, +.Fn pool_get +will return +.Dv NULL +without waiting, allowing the caller to do its own garbage collection; +however, it will still wait if the pool is not yet at its hard limit. +If the +.Dv PR_ZERO +flag is specified, then the memory returned will be zeroed first using +.Xr memset 3 . +.El +.Ss RETURNING ITEMS TO A POOL +.Fn pool_put +returns the pool item pointed at by +.Fa item +to the resource pool identified by the pool handle +.Fa pp . +If the number of available items in the pool exceeds the maximum pool +size set by +.Fn pool_sethiwat +and there are no outstanding requests for pool items, +the excess items will be returned to the system. +The arguments to +.Fn pool_put +are: +.Bl -tag -offset indent -width "item" +.It Fa pp +The handle identifying the pool resource instance. +.It Fa item +A pointer to a pool item previously obtained by +.Fn pool_get . +.El +.Ss SETTING POOL RESOURCE WATERMARKS AND LIMITS +A pool will attempt to increase its resource usage to keep up with the demand +for its items. +Conversely, +it will return unused memory to the system should the number of accumulated +unused items in the pool exceed a programmable limit. +.Pp +The targets for the minimum and maximum number of free items which a pool should +try to keep available are known as the high and low +.Sy watermarks . +The functions +.Fn pool_sethiwat +and +.Fn pool_setlowat +set a pool's high and low watermarks, respectively. +.Pp +The limits for the minimum and maximum number of total items (both free and +allocated) that the pool can have at any time are specified by the functions +.Fn pool_prime +and +.Fn pool_sethardlimit , +respectively. +The defaults for these limits are +.Dv 0 +and +.Dv UINT_MAX , +respectively. +Changing these limits will cause memory to be immediately allocated to the pool +or freed from the pool as needed. +.Pp +.Fn pool_sethiwat +.Bl -tag -offset indent -width "flags" +.It Fa pp +The handle identifying the pool resource instance. +.It Fa n +The maximum number of free items to keep in the pool. +As items are returned and the total number of free items in the pool is larger +than the maximum set by this function, +any completely unused pages are released immediately. +If this function is not used to specify a maximum number of items, +the pages will remain associated with the pool until the system runs low +on memory, +at which point the VM system will try to reclaim unused pages. +.El +.Pp +.Fn pool_setlowat +.Bl -tag -offset indent -width "flags" +.It Fa pp +The handle identifying the pool resource instance. +.It Fa n +The minimum number of free items to keep in the pool. +When the number of free items in the pool drops below this threshold, +a non-blocking attempt is made to allocate memory for more items. +The number of free items is not guaranteed to remain above this threshold. +.El +.Pp +.Fn pool_sethardlimit +.Bl -tag -offset indent -width "flags" +.It Fa pp +The handle identifying the pool resource instance. +.It Fa n +The maximum number of total items in the pool (i.e. the hard limit). +.It Fa warnmess +The warning message that will be logged when the hard limit is reached. +.It Fa ratecap +The minimal interval (in seconds) after which another warning message +is issued when the pool hits its hard limit again. +.El +.Pp +.Fn pool_prime +.Bl -tag -offset indent -width "storage" +.It Fa pp +The handle identifying the pool resource instance. +.It Fa n +The minimum number of total items for the pool. +If the current number of total items is less than the new minimum then new items +are allocated with blocking allocations. +.El +.Ss POTENTIAL PITFALLS +Note that undefined behaviour results when mixing the storage providing +methods supported by the pool resource routines. +.Pp +The pool resource code uses a per-pool lock to protect its internal state. +If any pool functions are called in an interrupt context, +the caller must block all interrupts that might cause the +code to be reentered. +Additionally, the functions +.Fn pool_init +and +.Fn pool_destroy +should never be called in interrupt context. +.Ss DIAGNOSTICS +Pool usage logs can be enabled by defining the compile-time option +.Dv POOL_DIAGNOSTIC . +.\" .Sh RETURN VALUES +.\" .Sh EXAMPLES +.Sh CODE REFERENCES +The pool manager is implemented in the file +.Pa sys/kern/subr_pool.c . +.\" .Sh AUTHOR +.Sh SEE ALSO +.Xr free 9 , +.Xr malloc 9 , +.Xr memoryallocators 9 , +.Xr pool_cache 9 , +.Xr uvm 9 +.Sh HISTORY +The +.Nx +pool manager appeared in +.Nx 1.4 . diff --git a/static/netbsd/man9/pool_cache.9 b/static/netbsd/man9/pool_cache.9 new file mode 100644 index 00000000..82115c3a --- /dev/null +++ b/static/netbsd/man9/pool_cache.9 @@ -0,0 +1,383 @@ +.\" $NetBSD: pool_cache.9,v 1.24 2021/12/22 17:28:17 thorpej Exp $ +.\" +.\" Copyright (c)2003 YAMAMOTO Takashi, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Copyright (c) 1997, 1999, 2000, 2007, 2008 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Paul Kranenburg; by Jason R. Thorpe of the Numerical Aerospace +.\" Simulation Facility, NASA Ames Research Center, and by Andrew Doran. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" ------------------------------------------------------------ +.Dd December 21, 2021 +.Dt POOL_CACHE 9 +.Os +.\" ------------------------------------------------------------ +.Sh NAME +.Nm pool_cache , +.Nm pool_cache_init , +.Nm pool_cache_destroy , +.Nm pool_cache_get_paddr , +.Nm pool_cache_get , +.Nm pool_cache_put_paddr , +.Nm pool_cache_put , +.Nm pool_cache_destruct_object , +.Nm pool_cache_invalidate , +.Nm pool_cache_sethiwat , +.Nm pool_cache_setlowat , +.Nm pool_cache_sethardlimit +.Nd resource-pool cache manager +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In sys/pool.h +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft pool_cache_t +.Fn pool_cache_init \ +"size_t size" "u_int align" "u_int align_offset" "int flags" \ +"const char *name" "struct pool_allocator *palloc" "int ipl" \ +"int (*ctor)(void *, void *, int)" "void (*dtor)(void *, void *)" "void *arg" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn pool_cache_destroy \ +"pool_cache_t pc" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void * +.Fn pool_cache_get_paddr \ +"pool_cache_t pc" "int flags" "paddr_t *pap" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void * +.Fn pool_cache_get \ +"pool_cache_t pc" "int flags" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn pool_cache_put_paddr \ +"pool_cache_t pc" "void *object" "paddr_t pa" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn pool_cache_put \ +"pool_cache_t pc" "void *object" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn pool_cache_destruct_object \ +"pool_cache_t pc" "void *object" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn pool_cache_invalidate \ +"pool_cache_t pc" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn pool_cache_sethiwat \ +"pool_cache_t pc" "int n" +.Ft void +.Fn pool_cache_setlowat \ +"pool_cache_t pc" "int n" +.Ft void +.Fn pool_cache_sethardlimit \ +"pool_cache_t pc" "int n" "const char *warnmess" "int ratecap" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +These utility routines provide management of pools of fixed-sized +areas of memory. +Resource pools set aside an amount of memory for exclusive use by the resource +pool owner. +This can be used by applications to guarantee the availability of a minimum +amount of memory needed to continue operation independent of the memory +resources currently available from the system-wide memory allocator. +.Pp +.Nm +follows the +.Xr pool 9 +API closely and offers routines that are functionally equivalent to +their +.Xr pool 9 +counterparts. +In addition, +.Nm +provides object management functions used to manipulate +objects allocated from the pool. +It also maintains global and per-CPU caches, both levels +of cache work together to allow for low overhead +allocation and release of objects, and improved L1/L2/L3 hardware +cache locality in multiprocessor systems. +.\" ------------------------------------------------------------ +.Sh FUNCTIONS +.Bl -tag -width compact +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_init "size" "align" "align_offset" "flags" \ +"name" "palloc" "ipl" "ctor" "dtor" "arg" +.Pp +Allocate and initialize a pool cache. +The arguments are: +.Bl -tag -width four +.It Fa size +.Pp +Specifies the size of the memory items managed by the pool. +.It Fa align +.Pp +Specifies the memory address alignment of the items returned by +.Fn pool_cache_get . +This argument must be a power of two. +If zero, +the alignment defaults to an architecture-specific natural alignment. +.It Fa align_offset +.Pp +The offset within an item to which the +.Fa align +parameter applies. +.It Fa flags +.Pp +Should be set to zero, +.Dv PR_NOTOUCH , +or +.Dv PR_PSERIALIZE . +If +.Dv PR_NOTOUCH +is given, free items are never used to keep internal state so that +the pool can be used for non memory backed objects. +If +.Dv PR_PSERIALIZE +is given, then the allocator guarantees that a passive serialization barrier +equivalent to +.Dq xc_barrier(0) +will be performed before either the object's destructor is called or +before object's backing store is returned to the system. +.Dv PR_PSERIALIZE +implies +.Dv PR_NOTOUCH . +Because of the guarantees provided by +.Dv PR_PSERIALIZE , +objects must never be freed to a pool cache using this option +from either hard or soft interrupt context, as doing so may block. +.It Fa name +.Pp +The name used to identify the object in diagnostic output. +.It Fa palloc +.Pp +Should be typically be set to NULL, instructing +.Fn pool_cache_init +to select an appropriate back-end allocator. +Alternate allocators can be used to partition space from arbitrary sources. +Use of alternate allocators is not documented here as it is not a stable, +endorsed part of the API. +.It Fa ipl +.Pp +Specifies an interrupt priority level that will block all interrupt +handlers that could potentially access the pool. +The +.Nm +facility provides its own synchronization. +The users of any given +.Nm +need not provide additional synchronization for access to it. +.It Fa ctor +.Pp +Specifies a constructor used to initialize newly allocated objects. +If no constructor is required, specify +.Dv NULL . +The first argument to +.Fa ctor +is +.Fa arg , +the second is the new object, and the third is +.Fa flags . +.It Fa dtor +.Pp +Specifies a destructor used to destroy cached objects prior to +their release to backing store. +If no destructor is required, specify +.Dv NULL . +The first argument to +.Fa dtor +is +.Fa arg , +and the second is the object. +.It Fa arg +.Pp +This value of this argument will be passed to both the constructor +and destructor routines. +.El +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_destroy "pc" +.Pp +Destroy a pool cache +.Fa pc . +All other access to the cache must be stopped before this call +can be made. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_get_paddr "pc" "flags" "pap" +.Pp +Get an object from a pool cache +.Fa pc . +If +.Fa pap +is not +.Dv NULL , +physical address of the object or +.Dv POOL_PADDR_INVALID +will be returned via it. +.Fa flags +will be passed to +.Fn pool_get +function of the backing +.Xr pool 9 +and the object constructor specified when the pool cache is created by +.Fn pool_cache_init . +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_get "pc" "flags" +.Pp +.Fn pool_cache_get +is the same as +.Fn pool_cache_get_paddr +with +.Dv NULL +.Fa pap +argument. +It's implemented as a macro. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_put_paddr "pc" "object" "pa" +.Pp +Put an object +.Fa object +back to the pool cache +.Fa pc . +.Fa pa +should be physical address of the object +.Fa object +or +.Dv POOL_PADDR_INVALID . +If the number of available items in the backing pool exceeds the maximum +pool size set by +.Fn pool_cache_sethiwat +and there are no outstanding requests for pool items, +the excess items will be returned to the system. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_put "pc" "object" +.Pp +.Fn pool_cache_put +is the same as +.Fn pool_cache_put_paddr +with +.Dv POOL_PADDR_INVALID +.Fa pa +argument. +It's implemented as a macro. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_destruct_object "pc" "object" +.Pp +Force destruction of an object +.Fa object +and release it back into the pool. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_invalidate "pc" +.Pp +Invalidate a pool cache +.Fa pc . +All objects in the cache will be destructed and freed back to the pool +backing the cache. +For pool caches that vend constructed objects, consumers of this API +must take care to provide proper synchronization between the input to +the constructor and cache invalidation. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_sethiwat "pc" "n" +.Pp +A pool will attempt to increase its resource usage to keep up with the demand +for its items. +Conversely, +it will return unused memory to the system should the number of accumulated +free items in the pool exceed a programmable limit. +The limits for the minimum and maximum number of free items which a pool should +try to keep available are known as the high and low +.Sy watermarks . +.Pp +The function +.Fn pool_cache_sethiwat +sets the backing pool's high water mark. +As items are freed and the number of free items in the pool is larger +than the maximum set by this function, +any completely unused pages are released immediately. +If this function is not used to specify a maximum number of items, +the pages will remain associated with the pool until the system runs low +on memory, +at which point the VM system will try to reclaim unused pages. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_setlowat "pc" "n" +.Pp +Set the minimum number of free items to try to keep in the pool. +When the number of free items in the pool drops below this threshold, +a non-blocking attempt is made to allocate memory for more items. +The number of free items is not guaranteed to remain above this threshold. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_sethardlimit "pc" "n" "warnmess" "ratecap" +Set the maximum number of total items (both free and allocated) for the backing +.Xr pool 9 +to +.Fa n . +When the hard limit is reached, the warning message +.Fa warnmess +will be logged. +.Fa ratecap +represents the minimal interval (in seconds) after which another warning +message is issued when the pool hits its hard limit again. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_prime "pc" "n" +Set the minimum number of total items (both free and allocated) for the backing +.Xr pool 9 +to +.Fa n . +.El +.\" ------------------------------------------------------------ +.Sh CODE REFERENCES +The +.Nm +subsystem is implemented within the file +.Pa sys/kern/subr_pool.c . +.Sh SEE ALSO +.Xr intro 9 , +.Xr kmem 9 , +.Xr memoryallocators 9 , +.Xr percpu 9 , +.Xr pool 9 diff --git a/static/netbsd/man9/portfeatures.9 b/static/netbsd/man9/portfeatures.9 new file mode 100644 index 00000000..bd0577fe --- /dev/null +++ b/static/netbsd/man9/portfeatures.9 @@ -0,0 +1,98 @@ +.\" $NetBSD: portfeatures.9,v 1.4 2025/07/27 17:56:33 gutteridge Exp $ +.\" +.\" Copyright (c) The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.Dd July 27, 2025 +.Dt PORTFEATURES 9 +.Os +. +.Sh NAME +.Nm portfeatures +.Nd the __HAVEs (\|and the have nots\|) +. +.Sh DESCRIPTION +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 defining various +.Li __HAVE_ Ns Ar feature +macros. +This manual page provides an index of such macros with pointers to +other manual pages in the kernel section that provide all the relevant +details. +.Bl -tag -width Dv +. +.\" --------- +.It Dv __HAVE_MUTEX_STUBS Pq Xr mutex 9 +The port provides fast path mutex enter and exit stubs. +. +.\" --------- +.It Dv __HAVE_PREEMPTION Pq Xr cpu_need_resched 9 +The port can preempt kernel lwps with +.Dv RESCHED_KPREEMPT . +. +.\" --------- +.It Dv __HAVE_PROCFS_MACHDEP +The port has MD procfs nodes, defines additional values for the +.Dv pfstype +enum for each type. +. +.\" --------- +.It Dv __HAVE_PTRACE_MACHDEP +The port has MD +.Xr ptrace 2 +requests, defines +.Dv PTRACE_MACHDEP_REQUEST_CASES +macro with +.Ic case +labels for its MD requests. +. +.\" --------- +.It Dv __HAVE_RAS Pq Xr ras 9 +The port supports restartable atomic sequences. +. +.\" --------- +.It Dv __HAVE_SIMPLE_MUTEXES Pq Xr mutex 9 +The port provides a CAS function that is either MP-safe, or does not +need to be MP safe. +Adaptive mutexes on these architectures do not require an additional +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 diff --git a/static/netbsd/man9/powerhook_establish.9 b/static/netbsd/man9/powerhook_establish.9 new file mode 100644 index 00000000..a921bceb --- /dev/null +++ b/static/netbsd/man9/powerhook_establish.9 @@ -0,0 +1,107 @@ +.\" $NetBSD: powerhook_establish.9,v 1.15 2025/01/04 17:21:41 riastradh Exp $ +.\" +.\" Copyright (c) 1999 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 30, 2024 +.Dt POWERHOOK_ESTABLISH 9 +.Os +.Sh NAME +.Nm powerhook_establish , +.Nm powerhook_disestablish +.Nd add or remove a power change hook +.Sh SYNOPSIS +.Ft void * +.Fn powerhook_establish "const char *name" "void (*fn)(int why, void *a)" \ +"void *arg" +.Ft void +.Fn powerhook_disestablish "void *cookie" +.Sh DESCRIPTION +.Em The +.Nm +.Em API is deprecated. +See +.Xr pmf 9 +for replacement functionality. +.Pp +The +.Fn powerhook_establish +function adds +.Fa fn +to the list of hooks invoked by +.Xr dopowerhooks 9 +at power change. +When invoked, the hook function +.Fa fn +will be passed the new power state as the first argument and +.Fa arg +as its second argument. +.Pp +The +.Fn powerhook_disestablish +function removes the hook described by the opaque pointer +.Fa cookie +from the list of hooks to be invoked at power change. +If +.Fa cookie +is invalid, the result of +.Fn powerhook_disestablish +is undefined. +.Pp +Power hooks should be used to perform activities +that must happen when the power situation to the computer changes. +Because of the environment in which they are run, power hooks cannot +rely on many system services (including file systems, and timeouts +and other interrupt-driven services). +The power hooks are typically executed from an interrupt context. +.Pp +The different reasons for calling the power hooks are: suspend, standby, and +resume. +The reason is reflected in the +.Fa why +argument and the values +.Dv PWR_SOFTSUSPEND , +.Dv PWR_SUSPEND , +.Dv PWR_SOFTSTANDBY , +.Dv PWR_STANDBY , +.Dv PWR_SOFTRESUME , +and +.Dv PWR_RESUME . +It calls with PWR_SOFTxxx in the normal priority level while the other +callings are protected with +.Xr splhigh 9 . +At suspend the system is going to lose (almost) all power, standby retains +some power (e.g., minimal power to USB devices), and at resume power is +back to normal. +.Sh RETURN VALUES +If successful, +.Fn powerhook_establish +returns an opaque pointer describing the newly-established +power hook. +Otherwise, it returns NULL. +.Sh SEE ALSO +.Xr dopowerhooks 9 diff --git a/static/netbsd/man9/ppsratecheck.9 b/static/netbsd/man9/ppsratecheck.9 new file mode 100644 index 00000000..80c41757 --- /dev/null +++ b/static/netbsd/man9/ppsratecheck.9 @@ -0,0 +1,88 @@ +.\" $NetBSD: ppsratecheck.9,v 1.6 2008/04/30 13:10:58 martin Exp $ +.\" +.\" Copyright (c) 2000 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jun-ichiro itojun Hagino. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 3, 2000 +.Dt PPSRATECHECK 9 +.Os +.Sh NAME +.Nm ppsratecheck +.Nd function to help implement rate-limited actions +.Sh SYNOPSIS +.In sys/time.h +.Ft int +.Fn ppsratecheck "struct timeval *lasttime" "int *curpps" "int maxpps" +.Sh DESCRIPTION +The +.Fn ppsratecheck +function provides easy way to perform packet-per-sec, +or event-per-sec, rate limitation. +The motivation for implementing +.Fn ppsratecheck +was to provide a mechanism that could be used to add rate limitation to +network packet output. +For certain network packets, we may want to impose rate limitation, +to avoid denial-of-service attack possibilities. +.Pp +.Fa maxpps +specifies maximum permitted packets, or events, per second. +If +.Fn ppsratecheck +is called more than +.Fa maxpps +times in a given one second period, +the function will return 0, indicating that we exceeded the limit. +If we are below the limit, the function will return 1. +If +.Fa maxpps +is set to 0, the function will always return 0 +.Pq no packets/events are permitted . +Negative +.Fa maxpps +indicates that rate limitation is disabled, and +.Fa ppsratecheck +will always return 1. +.Pp +.Fa curpps +and +.Fa lasttime +are used to maintain the number of recent calls. +.Fa curpps +will be incremented every time +.Fn ppsratecheck +is called, and will be reset whenever necessary. +.Sh SEE ALSO +.Xr log 9 , +.Xr printf 9 , +.Xr ratecheck 9 , +.Xr time_second 9 +.Sh HISTORY +The +.Fn ppsratecheck +function appeared in +.Nx 1.5 . diff --git a/static/netbsd/man9/preempt.9 b/static/netbsd/man9/preempt.9 new file mode 100644 index 00000000..9994b412 --- /dev/null +++ b/static/netbsd/man9/preempt.9 @@ -0,0 +1,56 @@ +.\" $NetBSD: preempt.9,v 1.6 2008/04/30 13:10:58 martin Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 3, 2007 +.Dt PREEMPT 9 +.Os +.Sh NAME +.Nm preempt , +.Nm yield +.Nd general preempt and yield functions +.Sh SYNOPSIS +.In sys/sched.h +.Ft void +.Fn preempt "void" +.In sys/proc.h +.Ft void +.Fn yield "void" +.Sh DESCRIPTION +The +.Fn preempt +function puts the current LWP back on the system run queue +and performs an involuntary context switch. +The +.Fn yield +function is mostly same as +.Fn preempt , +except that it performs a voluntary context switch. +.Pp +These functions drop the kernel lock before switching +and re-acquire it before returning. diff --git a/static/netbsd/man9/proc_find.9 b/static/netbsd/man9/proc_find.9 new file mode 100644 index 00000000..7d4890d8 --- /dev/null +++ b/static/netbsd/man9/proc_find.9 @@ -0,0 +1,71 @@ +.\" $NetBSD: proc_find.9,v 1.1 2010/07/01 14:54:44 jruoho Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 1, 2010 +.Dt PROC_FIND 9 +.Os +.Sh NAME +.Nm proc_find , +.Nm pgrp_find +.Nd find process or process group +.Sh SYNOPSIS +.In sys/proc.h +.Ft struct proc * +.Fn proc_find "pid_t pid" +.Ft struct pgrp * +.Fn pgrp_find "pid_t pgid" +.Pp +.Va extern kmutex_t *proc_lock; +.Sh DESCRIPTION +The +.Fn proc_find +and +.Fn pgrp_find +functions retrieve process and process group structures from process +.Tn ID +.Fa pid +and process group +.Tn ID +.Fa pgid . +Both functions must be called by holding a +.Xr mutex 9 +on +.Va proc_lock . +.Sh RETURN VALUES +Upon successful completion, the described functions return a pointer to either +.Em struct proc +or +.Em struct pgrp . +Otherwise, if the requested +.Tn ID +was not found, +.Dv NULL +is returned. +.Sh SEE ALSO +.Xr curproc 9 diff --git a/static/netbsd/man9/pserialize.9 b/static/netbsd/man9/pserialize.9 new file mode 100644 index 00000000..b87d746e --- /dev/null +++ b/static/netbsd/man9/pserialize.9 @@ -0,0 +1,188 @@ +.\" $NetBSD: pserialize.9,v 1.15 2025/10/01 12:33:10 riastradh Exp $ +.\" +.\" Copyright (c) 2011 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 26, 2016 +.Dt PSERIALIZE 9 +.Os +.Sh NAME +.Nm pserialize +.Nd passive serialization mechanism +.Sh SYNOPSIS +.In sys/pserialize.h +.Ft pserialize_t +.Fn pserialize_create "void" +.Ft void +.Fn pserialize_destroy "pserialize_t psz" +.Ft int +.Fn pserialize_read_enter "void" +.Ft void +.Fn pserialize_read_exit "int s" +.Ft void +.Fn pserialize_perform "pserialize_t psz" +.\" ----- +.Sh DESCRIPTION +Passive serialization is a reader / writer synchronisation mechanism +designed for lock-less read operations. +The read operations may happen from software interrupt at +.Dv IPL_SOFTCLOCK . +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn pserialize_create +Allocate a new synchronisation object. +.It Fn pserialize_destroy +Destroy the synchronisation object. +No synchronisation activity should happen at this point. +.It Fn pserialize_read_enter +Enter the critical path of the reader side. +Returns an IPL value, which must be passed to +.Xr pserialize_read_exit 9 . +Protected code path is not allowed to block. +.It Fn pserialize_read_exit +Exit the critical path of the reader side. +Takes the IPL value returned by +.Xr pserialize_read_enter 9 . +.It Fn pserialize_perform +Perform the passive serialization on the writer side. +Passing of this function ensures that no readers are in action. +Writers are typically additionally serialized with a separate +mechanism, e.g. +.Xr mutex 9 , +to remove objects used by readers from a published list. +Operation blocks and it may only be performed from thread context. +.El +.\" ----- +.Sh EXAMPLES +Given a global database of frotz records: +.Bd -literal + struct frotz { + ... + struct frotz *f_next; + }; + + static struct { + kmutex_t lock; + pserialize_t psz; + struct frotz *first; + } frobbotzim __cacheline_aligned; +.Ed +.Pp +Create a frotz and publish it, as a writer: +.Bd -literal + struct frotz *f = pool_get(&frotz_pool, PR_WAITOK); + + /* Initialize f. */ + ... + + mutex_enter(&frobbotzim.lock); + f->f_next = frobbotzim.first; + /* + * Publish the contents of f->f_next before we publish the + * pointer to f in frobbotzim.first. + */ + atomic_store_release(&frobbotzim.first, f); + mutex_exit(&frobbotzim.lock); +.Ed +.Pp +Find a frotz, as a reader: +.Bd -literal + struct frotz *f; + int error = ENOENT; + int s; + + s = pserialize_read_enter(); + /* Fetch frobbotzim.first before we fetch anything it point to. */ + for (f = atomic_load_consume(&frobbotzim.first); + f != NULL; + f = f->f_next) { + if (f->f_... == key) { + /* + * Grab whatever part of the frotz we need. + * Note that we can't use the frotz after + * pserialize_read_exit, without a stronger + * kind of reference, say a reference count + * managed by atomic_ops(3). + */ + *resultp = f->f_...; + error = 0; + break; + } + } + pserialize_read_exit(s); + + return error; +.Ed +.Pp +Remove a frotz, as a writer, and free it once there are no more +readers: +.Bd -literal + struct frotz **fp, *f; + + mutex_enter(&frobbotzim.lock); + for (fp = &frobbotzim.first; (f = *fp) != NULL; fp = &f->f_next) { + if (f->f_... == key) { + /* + * Unhook it from the list. Readers may still + * be traversing the list at this point, so + * the next pointer must remain valid and + * memory must remain allocated. + */ + *fp = f->f_next; + break; + } + } + mutex_exit(&frobbotzim.lock); + + /* + * Wait for all existing readers to complete. New readers will + * not see f because the list no longer points to it. + */ + pserialize_perform(frobbotzim.psz); + + /* Now nobody else can be touching f, so it is safe to free. */ + if (f != NULL) + pool_put(&frotz_pool, f); +.Ed +.\" ----- +.Sh CODE REFERENCES +The +.Nm +is implemented within the file +.Pa sys/kern/subr_pserialize.c . +.Sh SEE ALSO +.Xr membar_ops 3 , +.Xr condvar 9 , +.Xr mutex 9 , +.Xr rwlock 9 +.Rs +.%A Hennessy, et al. +.%T "Passive serialization in a multitasking environment" +.%I US Patent and Trademark Office +.%D February 28, 1989 +.%N US Patent 4809168 +.Re +.Sh HISTORY +Passive serialization mechanism first appeared in +.Nx 6.0 . diff --git a/static/netbsd/man9/pslist.9 b/static/netbsd/man9/pslist.9 new file mode 100644 index 00000000..5819e03c --- /dev/null +++ b/static/netbsd/man9/pslist.9 @@ -0,0 +1,429 @@ +.\" $NetBSD: pslist.9,v 1.19 2021/11/06 23:29:03 riastradh Exp $ +.\" +.\" Copyright (c) 2016 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Taylor R. Campbell. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 7, 2016 +.Dt PSLIST 9 +.Os +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh NAME +.Nm pslist +.Nd pserialize-safe linked lists +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SYNOPSIS +.In sys/pslist.h +.\" Exclusive operations +.Vt struct pslist_head head No = Dv PSLIST_INITIALIZER ; +.Vt struct pslist_entry entry No = Dv PSLIST_ENTRY_INITIALIZER ; +.Ft void +.Fn PSLIST_INIT "struct pslist_head *head" +.Ft void +.Fn PSLIST_DESTROY "struct pslist_head *head" +.Ft void +.Fn PSLIST_ENTRY_INIT "TYPE *element" "PSLIST_ENTRY NAME" +.Ft void +.Fn PSLIST_ENTRY_DESTROY "TYPE *element" "PSLIST_ENTRY NAME" +.\" Writer operations +.Ft void +.Fn PSLIST_WRITER_INSERT_HEAD "struct pslist_head *head" "TYPE *new" "PSLIST_ENTRY NAME" +.Ft void +.Fn PSLIST_WRITER_INSERT_BEFORE "TYPE *element" "TYPE *new" "PSLIST_ENTRY NAME" +.Ft void +.Fn PSLIST_WRITER_INSERT_AFTER "TYPE *element" "TYPE *new" "PSLIST_ENTRY NAME" +.Ft void +.Fn PSLIST_WRITER_REMOVE "TYPE *element" "PSLIST_ENTRY NAME" +.Ft TYPE * +.Fn PSLIST_WRITER_FIRST "const struct pslist *head" "TYPE" "PSLIST_ENTRY NAME" +.Ft TYPE * +.Fn PSLIST_WRITER_NEXT "const TYPE *element" "TYPE" "PSLIST_ENTRY NAME" +.Fn PSLIST_WRITER_FOREACH "const TYPE *element" "const struct pslist_head *head" "TYPE" "PSLIST_ENTRY NAME" +.\" Reader operations +.Ft TYPE * +.Fn PSLIST_READER_FIRST "const struct pslist *head" "TYPE" "PSLIST_ENTRY NAME" +.Ft TYPE * +.Fn PSLIST_READER_NEXT "const TYPE *element" "TYPE" "PSLIST_ENTRY NAME" +.Fn PSLIST_READER_FOREACH "const TYPE *element" "const struct pslist_head *head" "TYPE" "PSLIST_ENTRY NAME" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh DESCRIPTION +The +.Nm +data structure is a linked list like +.Nm list +in +.Xr queue 3 . +It is augmented with memory barriers so that any number of readers can +safely run in parallel with at most one writer, without needing any +interprocessor synchronization such as locks or atomics on the reader +side. +.\" +.Pp +The head of a linked list is represented by a +.Vt struct pslist_head +object allocated by the caller, e.g. by embedding it in another +struct, which should be otherwise treated as opaque. +A linked list head must be initialized with +.Dv PSLIST_INITIALIZER +or +.Fn PSLIST_INIT +before it may be used. +When initialized, a list head represents an empty list. +A list should be empty and destroyed with +.Fn PSLIST_DESTROY +before the +.Vt struct pslist_head +object's memory is reused. +.\" +.Pp +Each entry in a linked list is represented by a +.Vt struct pslist_entry +object, also opaque, and embedded as a member in a caller-allocated +structure called an +.Em element . +A +.Vt struct pslist_entry +object must be initialized with +.Dv PSLIST_ENTRY_INITIALIZER +or +.Fn PSLIST_ENTRY_INIT +before it may be used. +.\" +.Pp +When initialized, a list entry is unassociated. +Inserting an entry associates it with a particular list. +Removing it +partially disassociates it from that list and prevents new readers from +finding it in the list, but allows extant parallel readers to continue +reading the next entry. +The caller must then wait, e.g. with +.Xr pserialize_perform 9 , +for all extant parallel readers to finish, before destroying the list +entry with +.Fn PSLIST_ENTRY_DESTROY +and then freeing or reusing its memory. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh EXCLUSIVE OPERATIONS +The following operations may be performed on list heads and entries +when the caller has exclusive access to them \(em no parallel writers or +readers may have access to the same objects. +.\"""""""""""""""" +.Bl -tag -width abcd +.It Dv PSLIST_INITIALIZER +Constant initializer for a +.Vt struct pslist_head +object. +.\"""""""""""""""" +.It Fn PSLIST_INIT head +Initialize the list headed by +.Fa head +to be empty. +.\"""""""""""""""" +.It Fn PSLIST_DESTROY head +Destroy the list headed by +.Fa head , +which must be empty. +.Pp +This has an effect only with the +.Dv DIAGNOSTIC +option, so it is not strictly necessary, but it can help to detect bugs +early; see +.Xr KASSERT 9 . +.\"""""""""""""""" +.It Dv PSLIST_ENTRY_INITIALIZER +Constant initializer for an unassociated +.Vt struct pslist_entry +object. +.\"""""""""""""""" +.It Fn PSLIST_ENTRY_INIT element NAME +Initialize the +.Vt struct pslist_entry +object +.Fa element Ns Li -> Ns Fa NAME . +.\"""""""""""""""" +.It Fn PSLIST_ENTRY_DESTROY element NAME +Destroy the +.Vt struct pslist_entry +object +.Fa element Ns Li -> Ns Fa NAME . +Either +.Fa element +must never have been inserted into a list, or it must have been +inserted and removed, and the caller must have waited for all parallel +readers to finish reading it first. +.El +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh WRITER OPERATIONS +The following operations may be performed on list heads and entries +when the caller has exclusive +.Em write +access to them \(em parallel readers for the same objects are allowed, +but no parallel writers. +.\"""""""""""""""" +.Bl -tag -width abcd +.It Fn PSLIST_WRITER_INSERT_HEAD head element NAME +Insert the element +.Fa element +at the beginning of the list headed by +.Fa head , +before any existing elements in the list. +.Pp +The object +.Fa element Ns Li -> Ns Fa NAME +must be a +.Vt struct pslist_entry +object which has been initialized but not inserted. +.\"""""""""""""""" +.It Fn PSLIST_WRITER_INSERT_BEFORE element new NAME +Insert the element +.Fa new +into a list before the element +.Fa element . +.Pp +The object +.Fa element Ns Li -> Ns Fa NAME +must be a +.Vt struct pslist_entry +object which has been inserted into a list. +The object +.Fa new Ns Li -> Ns Fa NAME +must be a +.Vt struct pslist_entry +.\"""""""""""""""" +.It Fn PSLIST_WRITER_INSERT_AFTER element new NAME +Insert the element +.Fa new +into a list after the element +.Fa element . +.Pp +The object +.Fa element Ns Li -> Ns Fa NAME +must be a +.Vt struct pslist_entry +object which has been inserted into a list. +The object +.Fa new Ns Li -> Ns Fa NAME +must be a +.Vt struct pslist_entry +.\"""""""""""""""" +.It Fn PSLIST_WRITER_REMOVE element NAME +Remove the element +.Fa element +from the list into which it has been inserted. +.Pp +The object +.Fa element Ns Li -> Ns Fa NAME +must be a +.Vt struct pslist_entry +object which has been inserted into a list. +.\"""""""""""""""" +.It Fn PSLIST_WRITER_FIRST head type NAME +Return a pointer to the first element +.Fa o +of type +.Fa type +with a +.Vt struct pslist_entry +member +.Fa o Ns Li -> Ns Fa NAME , +or +.Dv NULL +if the list is empty. +.\"""""""""""""""" +.It Fn PSLIST_WRITER_NEXT element type NAME +Return a pointer to the next element +.Fa o +of type +.Fa type +with a +.Vt struct pslist_entry +member +.Fa o Ns Li -> Ns Fa NAME +after +.Fa element +in a list, or +.Dv NULL +if there are no elements after +.Fa element . +.\"""""""""""""""" +.It Fn PSLIST_WRITER_FOREACH element head type NAME +Loop header for iterating over each element +.Fa element +of type +.Fa type +with +.Vt struct pslist_entry +member +.Fa element Ns Li -> Ns Fa NAME +starting at the list head +.Fa head . +.Pp +The caller must not modify the list while iterating over it. +.El +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh READER OPERATIONS +The following operations may be performed on list heads and entries +when the caller is in a passively serialized read section \(em see +.Xr pserialize 9 . +.Bl -tag -width abcd +.\"""""""""""""""" +.It Fn PSLIST_READER_FIRST head type NAME +Return a pointer to the first element +.Fa o +of type +.Fa type +with a +.Vt struct pslist_entry +member +.Fa o Ns Li -> Ns Fa NAME , +or +.Dv NULL +if the list is empty. +.\"""""""""""""""" +.It Fn PSLIST_READER_NEXT element type NAME +Return a pointer to the next element +.Fa o +of type +.Fa type +with a +.Vt struct pslist_entry +member +.Fa o Ns Li -> Ns Fa NAME +after +.Fa element +in a list, or +.Dv NULL +if there are no elements after +.Fa element . +.\"""""""""""""""" +.It Fn PSLIST_READER_FOREACH element head type NAME +Loop header for iterating over each element +.Fa element +of type +.Fa type +with +.Vt struct pslist_entry +member +.Fa element Ns Li -> Ns Fa NAME +starting at the list head +.Fa head . +.El +.Sh EXAMPLES +Example frotz structure and global state: +.Bd -literal + struct frotz { + uint64_t f_key; + uint64_t f_datum; + struct pslist_entry f_entry; + }; + + static struct { + kmutex_t lock; + pserialize_t psz; + struct pslist_head list; + struct pool pool; + } frobnitzem __cacheline_aligned; +.Ed +.Pp +Initialize the global state: +.Bd -literal + mutex_init(&frobnitzem.lock, MUTEX_DEFAULT, IPL_NONE); + frobnitzem.psz = pserialize_create(); + PSLIST_INIT(&frobnitzem.list); + pool_init(&frobnitzem.pool, sizeof(struct frotz), ...); +.Ed +.Pp +Create and publish a frotz: +.Bd -literal + uint64_t key = ...; + uint64_t datum = ...; + + struct frotz *f = pool_get(&frobnitzem.pool, PR_WAITOK); + + /* Initialize f. */ + f->f_key = key; + f->f_datum = datum; + PSLIST_ENTRY_INIT(f, f_entry); + + /* Publish it. */ + mutex_enter(&frobnitzem.lock); + PSLIST_WRITER_INSERT_HEAD(&frobnitzem.list, f, f_entry); + mutex_exit(&frobnitzem.lock); +.Ed +.Pp +Look up a frotz and return its associated datum: +.Bd -literal + uint64_t key = ...; + struct frotz *f; + int error = ENOENT; + int s; + + s = pserialize_read_enter(); + PSLIST_READER_FOREACH(f, &frobnitzem.list, struct frotz, f_entry) { + if (f->f_key == key) { + *datump = f->f_datum; + error = 0; + break; + } + } + pserialize_read_exit(s); + return error; +.Ed +.Pp +Remove a frotz and wait for readers to finish using it before reusing +the memory allocated for it: +.Bd -literal + struct frotz *f = ...; + + mutex_enter(&frobnitzem.lock); + PSLIST_WRITER_REMOVE(f, f_entry); + mutex_exit(&frobnitzem.lock); + + pserialize_perform(&frobnitzem.psz); + + PSLIST_ENTRY_DESTROY(f, f_entry); + pool_put(&frobnitzem.pool, f); +.Ed +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh CODE REFERENCES +The +.Nm +data structure is implemented by static inlines and macros in +.Pa sys/sys/pslist.h . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SEE ALSO +.Xr queue 3 , +.Xr pserialize 9 , +.Xr psref 9 +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh HISTORY +The +.Nm +data structure first appeared in +.Nx 8.0 . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh AUTHORS +.An Taylor R Campbell Aq Mt riastradh@NetBSD.org diff --git a/static/netbsd/man9/psref.9 b/static/netbsd/man9/psref.9 new file mode 100644 index 00000000..c5425b52 --- /dev/null +++ b/static/netbsd/man9/psref.9 @@ -0,0 +1,405 @@ +.\" $NetBSD: psref.9,v 1.5 2016/04/27 08:18:40 ozaki-r Exp $ +.\" +.\" Copyright (c) 2016 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Taylor R. Campbell. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 27, 2016 +.Dt PSREF 9 +.Os +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh NAME +.Nm psref +.Nd passive references +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SYNOPSIS +.In sys/psref.h +.\" +.Ft struct psref_class * +.Fn psref_class_create "const char *name" "int ipl" +.Ft void +.Fn psref_class_destroy "struct psref_class *class" +.\" +.Ft void +.Fn psref_target_init "struct psref_target *target" "struct psref_class *class" +.Ft void +.Fn psref_target_destroy "struct psref_target *target" "struct psref_class *class" +.\" +.Ft void +.Fn psref_acquire "struct psref *ref" "const struct psref_target *target" "struct psref_class *class" +.Ft void +.Fn psref_release "struct psref *ref" "const struct psref_target *target" "struct psref_class *class" +.Ft void +.Fn psref_copy "struct psref *pto" "const struct psref *pfrom" "struct psref_class *class" +.\" +.Pp +.Fd "#ifdef DIAGNOSTIC" +.Ft bool +.Fn psref_held "const struct psref_target *target" "struct psref_class *class" +.Fd "#endif" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh DESCRIPTION +The +.Nm +abstraction allows CPUs to cheaply acquire and release +.Em passive references +to a resource, which guarantee the resource will not be destroyed +until the reference is released. +Acquiring and releasing passive references requires no interprocessor +synchronization, except when the resource is pending destruction. +.\" +.Pp +Passive references are an intermediate between +.Xr pserialize 9 +and reference counting: +.Bl -hyphen +.It +.Xr pserialize 9 +read sections require no interprocessor synchronization, but must be +of short duration, and may not sleep. +A +.Xr pserialize 9 +read section blocks soft interrupts on the local CPU until it is +complete. +.It +Reference counting requires interprocessor synchronization via +.Xr atomic_ops 3 +or +.Xr mutex 9 . +However, with reference counting, a reference may be held for arbitrary +durations, may be transferred between owners across CPUs and threads, +and may be held by a caller that sleeps. +.El +.\" +.Pp +Passive references share some properties of both: passive references +avoid interprocessor synchronization, and do not block soft interrupts, +but can be held by a caller that sleeps. +However, a caller holding a passive reference may not transfer it from +one LWP to another, and the caller's LWP must be bound to a single CPU +while it holds any passive references. +.Pp +Thus, passive references are useful for incrementally parallelizing +resources whose operations may sleep, such as in the network stack, +before comprehensively removing sleeps from the code paths involved. +.\" +.Pp +Resources to which callers may hold passive references are called +.Em targets , +and must contain an embedded +.Vt struct psref_target +object, initialized with +.Fn psref_target_init . +.Pp +When a caller wants to guarantee that a resource will not be destroyed +until it is done, it must allocate storage for a +.Vt struct psref +object, find the +.Vt struct psref_target +for the resource it seeks, and use +.Fn psref_acquire +to acquire a passive reference. +When a caller is done with the resource, it must release the resource +with +.Fn psref_release . +.Pp +When a resource is about to go away, its passive reference target must +be passed to +.Fn psref_target_destroy +to wait until all extant passive references are released; then the +resource itself may be freed. +.\" +.Pp +.Vt struct psref_target +and +.Vt struct psref +objects must be allocated by the caller, but they should be treated as +opaque and should not be inspected or copied. +.\" +.Pp +Passive reference targets are grouped into +.Em classes , +represented by an opaque +.Vt struct psref_class +object, e.g. the class of all network routes, or the class of all file +systems mount points, which may be needed at different interrupt +priority levels. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn psref_class_create name ipl +Create a passive reference class with the given name and interrupt +priority level, and return an opaque pointer describing it. +The name must be at most eight characters long, and will be shown in +utilities such as +.Xr ps 1 +for threads that are waiting to destroy passive reference targets. +On failure, return +.Dv NULL +instead. +.\"""""""""""""""" +.It Fn psref_class_destroy class +Destroy a passive reference class created with +.Fn psref_class_create . +There must be no more passive references in this class. +.\"""""""""""""""" +.It Fn psref_target_init target class +Initialize a passive reference target in a +.Vt struct psref_target +object allocated by the caller in the given class. +.Pp +The caller must issue a +.Xr membar_producer 3 +after calling +.Fn psref_target_init +and before publishing a pointer to the target so that other CPUs can +see it, e.g. by inserting it into a +.Xr pslist 9 . +.\"""""""""""""""" +.It Fn psref_target_destroy target class +Wait for all extant passive references to +.Fa target +on all CPUs to be released, and then destroy it. +The passive reference target +.Fa target +must have been initialized with +.Fn psref_target_init +in the same +.Fa class . +May sleep. +.Pp +The caller must guarantee that no new references to +.Fa target +will be acquired once it calls +.Fn psref_target_destroy , +e.g. by removing the target from a +.Xr pslist 9 +and calling +.Xr pserialize_perform 9 +to wait for +.Xr pserialize 9 +readers to complete. +.Pp +No further use of the target is allowed unless it is reinitialized with +.Fn psref_target_init . +Multiple concurrent calls to +.Fn psref_target_destroy +are not allowed. +.\"""""""""""""""" +.It Fn psref_acquire ref target class +Acquire a passive reference to +.Fa target , +storing per-CPU bookkeeping in +.Fa ref . +The class of +.Fa target +must be +.Fa class . +.Pp +The caller must ensure by some other mechanism than passive references +that the target will not be destroyed before the call to +.Fn psref_acquire ; +typically this will be via a +.Xr pserialize 9 +read section. +.Pp +The caller's LWP must be bound to a CPU. +.\"""""""""""""""" +.It Fn psref_release ref target class +Release the passive reference +.Fa ref , +which must have been acquired to point at +.Fa target +in the class +.Fa class , +waking a thread calling +.Fn psref_target_destroy +if any. +.Pp +Further use of the resource represented by +.Fa target +is not allowed, unless it is re-acquired in the same way that it was +originally acquired. +.\"""""""""""""""" +.It Fn psref_copy pto pfrom class +Copy the passive reference +.Fa pfrom +to +.Fa pto , +which must be to a target in +.Fa class . +The resource represented by the target of the passive references will +not be destroyed before both references are released. +.\"""""""""""""""" +.It Fn psref_held target class +Return true if the current CPU holds a passive reference to +.Fa target +in the passive reference class +.Fa class , +or false if not. +.Pp +This does not answer about other CPUs \(em it does not tell you whether +.Em any +CPU holds a passive reference to +.Fa target . +.Pp +This may be used only in assertions, e.g. with +.Xr KASSERT 9 , +not for making run-time decisions. +This should be used only for positive assertions, as in +.Li KASSERT(psref_held( Ns Fa target Ns Li , Fa class Ns Li )) , +not for negative assertions, as in +.Li KASSERT(!psref_held( Ns Fa target Ns Li , Fa class Ns Li )) , +unless you are sure you can prove that no caller holds a reference +either. +.El +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh EXAMPLES +.Bd -literal +struct frotz { + int f_key; + ... + struct pslist_entry f_entry; + struct psref_target f_target; +}; + +static struct { + kmutex_t lock; + struct pslist_head list; +} frobbotzim __cacheline_aligned; + +static pserialize_t frobbotzim_psz __read_mostly; +static struct psref_class *frobbotzim_prc __read_mostly; + +void +publish_as_frotz(uint64_t key, ...) +{ + struct frotz *f; + + f = kmem_alloc(sizeof(*f), KM_SLEEP); + f->f_key = key; + f->f_... = ...; + PSLIST_ENTRY_INIT(f, f_entry); + psref_target_init(&f->f_target, frobbotzim_prc); + + mutex_enter(&frobbotzim.lock); + PSLIST_WRITER_INSERT_HEAD(&frobbotzim.list, f, f_entry); + mutex_exit(&frobbotzim.lock); +} + +int +use_frotz(int key, int op) +{ + struct frotz *f; + struct psref ref; + + /* Acquire a passive reference. */ + if ((f = lookup_frotz(key, &ref)) == NULL) + return ENOENT; + + /* Do something that may sleep. */ + do_stuff_with_frotz(f, op); + + /* Release passive reference, possibly waking destroy_frotz. */ + psref_release(&ref, &f->f_psref, frobbotzim_prc); + + return 0; +} + +struct frotz * +lookup_frotz(int key, struct psref *ref) +{ + struct frotz *f; + int s; + + /* Look up a frotz in a pserialized list. */ + s = pserialize_read_enter(); + PSLIST_READER_FOREACH(f, &frobbotzim.list, struct frotz, f_next) { + /* f is stable until pserialize_read_exit. */ + if (f->f_key == key) { + /* Acquire a passive reference. */ + psref_acquire(ref, &f->f_target, frobbotzim_prc); + /* f is now stable until psref_release. */ + break; + } + } + pserialize_read_exit(s); + + return f; +} + +void +destroy_frotz(int key) +{ + struct frotz *f; + + /* Look up and delete a frotz. */ + mutex_enter(&frobbotzim.lock); + PSLIST_WRITER_FOREACH(f, &frobbotzim.list, struct frotz, f_entry) { + if (f->f_key == key) { + /* + * Unlink the frotz from the list to stop new + * pserialize read sections from seeing it. + */ + PSLIST_WRITER_REMOVE(f, f_entry); + + /* + * Wait until extant pserialize read sections + * have completed. + */ + pserialize_perform(frobbotzim_psz); + break; + } + } + mutex_exit(&frobbotzim.lock); + + if (f != NULL) { + /* Wait for all readers to drain before freeing. */ + psref_target_destroy(&f->f_target, frobbotzim_prc); + PSLIST_ENTRY_DESTROY(f, f_entry); + kmem_free(f, sizeof(*f)); + } +} +.Ed +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh CODE REFERENCES +The +.Nm +abstraction is implemented in +.Pa sys/kern/subr_psref.c . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SEE ALSO +.Xr pserialize 9 , +.Xr pslist 9 +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh HISTORY +The +.Nm +data structure first appeared in +.Nx 8.0 . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh AUTHORS +.An Taylor R Campbell Aq Mt riastradh@NetBSD.org diff --git a/static/netbsd/man9/putter.9 b/static/netbsd/man9/putter.9 new file mode 100644 index 00000000..99e347a5 --- /dev/null +++ b/static/netbsd/man9/putter.9 @@ -0,0 +1,48 @@ +.\" $NetBSD: putter.9,v 1.3 2009/05/18 12:27:22 wiz Exp $ +.\" +.\" Copyright (c) 2007 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 21, 2007 +.Dt PUTTER 9 +.Os +.Sh NAME +.Nm putter +.Nd Pass-to-Userspace Transporter +.Sh DESCRIPTION +The +.Nm +subsystem is used for request-response handling of userspace components. +It currently provides routines for associating a file descriptor +with a subsystem data structure instance and I/O routines. +Users of the facility must fill out the callbacks in +.Va struct putter_ops +to integrate with +.Nm . +.Sh SEE ALSO +.Xr pud 4 , +.Xr puffs 4 +.Sh BUGS +Under construction. +Interfaces may and will change. diff --git a/static/netbsd/man9/radio.9 b/static/netbsd/man9/radio.9 new file mode 100644 index 00000000..d2e2bcbc --- /dev/null +++ b/static/netbsd/man9/radio.9 @@ -0,0 +1,129 @@ +.\" $NetBSD: radio.9,v 1.6 2018/07/18 16:40:30 wiz Exp $ +.\" $OpenBSD: radio.9,v 1.2 2001/10/08 08:52:50 mpech Exp $ +.\" +.\" Copyright (c) Maxim Tsyplakov <tm@oganer.net> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF +.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON +.\" ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 9, 2018 +.Dt RADIO 9 +.Os +.Sh NAME +.Nm radio +.Nd interface between low- and high-level FM radio drivers +.Sh SYNOPSIS +.In dev/radio_if.h +.Ft device_t +.Fo radio_attach_mi +.Fa "const struct radio_hw_if *rhwp" +.Fa "void *hdlp" +.Fa "device_t dev" +.Fc +.Sh DESCRIPTION +The +.Nm +layer provides support for digitally programmable FM radio tuners. +.Pp +It is divided into a machine independent, high-level part responsible for +managing device files, and low-level hardware drivers. +.Pp +The high-level radio driver attaches to the low-level driver +when the latter calls +.Fn radio_attach_mi . +.Pp +The +.Fa radio_hw_if +struct contains pointers to functions provided by the low-level driver. +The +.Fa hdlp +argument is a handle to a low-level driver's softc structure. +It is sent as the first argument to all the functions in +.Fa radio_hw_if +when the high-level driver calls them. +.Fa dev +is the device struct for the hardware device. +.Pp +The fields of +.Fa radio_hw_if +are described in some more detail below. +.Bd -literal +struct radio_hw_if { + int (*open)(void *, int, int, struct lwp *); + int (*close)(void *, int, int, struct lwp *); + int (*get_info)(void *, struct radio_info *); + int (*set_info)(void *, struct radio_info *); + int (*search)(void *, int); +}; +.Ed +.Bl -tag -width XXXX +.It Fn (*open) "sc" "flags" "fmt" "lwp" +Called when the radio device is opened. +Optionally, if there is no need to call a driver's function when the device file is +opened, +.Dv NULL +should be passed in this field. +Returns 0 on success, otherwise an error code. +.It Fn (*close) "sc" "flags" "fmt" "lwp" +Called when the radio device is closed. +Optionally, if there is no need to call a driver's function when the device file is +closed, +.Dv NULL +should be passed in thie field. +Returns 0 on success, otherwise an error code. +.It Fn (*get_info) "sc" "ri" +Fills the radio_info struct. +This function is used to obtain the current state of a hardware device. +It is executed as a result of calling +.Dv RIOCGINFO +on a device file managed by the high-level driver. +Returns 0 on success, otherwise an error code. +.It Fn (*set_info) "sc" "ri" +Set values from the radio_info struct. +This function is used to modify the current state of a hardware device +(enable/disable various modes and parameters). +It is executed as a result of calling +.Dv RIOCSINFO +on a device file managed by the high-level driver. +Returns 0 on success, otherwise an error code. +.It Fn (*search) "sc" "ri" +Initiates automatic search for the radio station. +It is executed as a result of calling +.Dv RIOCSSRCH +on a device file managed by the high-level driver. +Returns 0 on success, otherwise an error code. +.El +.Sh SEE ALSO +.Xr radio 4 +.Sh AUTHORS +.An -nosplit +The +.Nm +API was written by +.An Vladimir Popov +and +.An Maxim Tsyplakov +for +.Ox +and ported to +.Nx +by +.An Lennart Augustsson . diff --git a/static/netbsd/man9/ras.9 b/static/netbsd/man9/ras.9 new file mode 100644 index 00000000..f7c757d5 --- /dev/null +++ b/static/netbsd/man9/ras.9 @@ -0,0 +1,141 @@ +.\" $NetBSD: ras.9,v 1.16 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 17, 2010 +.Dt RAS 9 +.Os +.Sh NAME +.Nm ras_lookup , +.Nm ras_fork , +.Nm ras_purgeall +.Nd restartable atomic sequences +.Sh SYNOPSIS +.In sys/types.h +.In sys/proc.h +.In sys/ras.h +.Ft void * +.Fn ras_lookup "struct proc *p" "void *addr" +.Ft int +.Fn ras_fork "struct proc *p1" "struct proc *p2" +.Ft int +.Fn ras_purgeall "struct proc *p" +.Sh DESCRIPTION +Restartable atomic sequences are user code sequences which are +guaranteed to execute without preemption. +This property is assured by checking the set of restartable atomic +sequences registered for a process during +.Xr cpu_switchto 9 . +If a process is found to have been preempted during a restartable +sequence, then its execution is rolled-back to the start of the +sequence by resetting its program counter saved in its process control block +.Pq Tn PCB . +.Pp +The +.Tn RAS +functionality is provided by a combination of the +machine-independent routines discussed in this page and +a machine-dependent component in +.Xr cpu_switchto 9 . +A port which supports restartable atomic sequences will define +.Dv __HAVE_RAS +in +.In machine/types.h +for machine-independent code to conditionally provide RAS support. +.Pp +A complicated side-effect of restartable atomic sequences is their +interaction with the machine-dependent +.Xr ptrace 2 +support. +Specifically, single-step traps and/or the emulation of single-stepping +must carefully consider the effect on restartable atomic sequences. +A general solution is to ignore these traps or disable them within +restartable atomic sequences. +.Sh FUNCTIONS +The functions which operate on restartable atomic sequences are: +.Pp +.Bl -tag -width compact +.It Fn ras_lookup "p" "addr" +This function searches the registered restartable atomic sequences for +process +.Fa p +which contain the user address +.Fa addr . +If the address +.Fa addr +is found within a +.Tn RAS , +then the restart address of the +.Tn RAS +is returned, otherwise \-1 is returned. +.It Fn ras_fork "p1" "p2" +This function is used to copy all registered restartable atomic +sequences for process +.Fa p1 +to process +.Fa p2 . +It is primarily called from +.Xr fork1 9 +when the sequences are inherited from the parent by the child. +.It Fn ras_purgeall "p" +This function is used to remove all registered restartable atomic +sequences for process +.Fa p . +It is primarily used to remove all registered restartable atomic +sequences for a process during +.Xr exec 3 +and by +.Xr rasctl 2 . +.El +.Sh CODE REFERENCES +The RAS framework itself is implemented within the file +.Pa sys/kern/kern_ras.c . +Data structures and function prototypes for the framework are located +in +.In sys/ras.h . +Machine-dependent portions are implemented within +.Xr cpu_switchto 9 +in the machine-dependent file +.Pa sys/arch/<arch>/<arch>/locore.S . +.Sh SEE ALSO +.Xr rasctl 2 , +.Xr cpu_switchto 9 , +.Xr fork1 9 +.Rs +.%A Gregory McGarry +.%T "An Implementation of User-level Restartable \ +Atomic Sequences on the NetBSD Operating System" +.%I USENIX Association +.%B Proceedings of the FREENIX Track: 2003 USENIX Annual Technical Conference +.%P 311-322 +.%D June 9-14, 2003 +.%U http://www.usenix.org/publications/library/proceedings/usenix03/tech/freenix03/full_papers/mcgarry/mcgarry.pdf +.Re +.Sh HISTORY +The RAS functionality first appeared in +.Nx 2.0 . diff --git a/static/netbsd/man9/rasops.9 b/static/netbsd/man9/rasops.9 new file mode 100644 index 00000000..bb34ea35 --- /dev/null +++ b/static/netbsd/man9/rasops.9 @@ -0,0 +1,149 @@ +.\" $NetBSD: rasops.9,v 1.20 2025/07/25 18:19:13 martin Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 7, 2019 +.Dt RASOPS 9 +.Os +.Sh NAME +.Nm rasops , +.Nm rasops_init , +.Nm rasops_reconfig +.Nd raster display operations +.Sh SYNOPSIS +.In dev/rasops/rasops.h +.Ft int +.Fn rasops_init "struct rasops_info *ri" "int wantrows" "int wantcols" +.Ft int +.Fn rasops_reconfig "struct rasops_info *ri" "int wantrows" "int wantcols" +.Pp +.Cd options RASOPS_DEFAULT_WIDTH=80 +.Cd options RASOPS_DEFAULT_HEIGHT=25 +.Sh DESCRIPTION +The +.Nm +subsystem is a set of raster operations for +.Xr wscons 9 . +.Pp +The primary data type for using the raster operations is the +.Vt rasops_info +structure in +.In dev/rasops/rasops.h . +.Pp +Valid values for the +.Fa ri_flg +member are: +.Pp +.Bl -tag -width ".Dv RI_ENABLE_ALPHA" -offset indent -compact +.It Dv RI_FULLCLEAR +.Fn eraserows +hack to clear full screen +.It Dv RI_FORCEMONO +monochrome output even if we can do color +.It Dv RI_BSWAP +framebuffer endianness doesn't match CPU +.It Dv RI_CURSOR +cursor is switched on +.It Dv RI_CLEAR +clear display on startup +.It Dv RI_CENTER +center onscreen output +.It Dv RI_CURSORCLIP +cursor is currently clipped +.It Dv RI_CFGDONE +.Fn rasops_reconfig +completed successfully +.It Dv RI_NO_AUTO +do not generate box drawing characters for ISO fonts. +Use this when it is not safe to allocate memory, for example when setting up +an early console. +.It Dv RI_ENABLE_ALPHA +the caller supports anti-aliased fonts in the given colour depth. +Without this flag +.Fn rasops_init +will only pick bitmap fonts. +.It Dv RI_8BIT_IS_RGB +the caller uses an R3G3B2 colour map in 8 bit. +.Fn rasops_init +will generate an appropriate +.Fa ri_devcmap Ns Li [] +but the caller still needs to set up the actual colour map. +.El +.Sh FUNCTIONS +.Fn rasops_init +initialises a +.Vt rasops_info +descriptor. +.Fn rasops_reconfig +is used to reconfigure it if parameters have changed in some way. +.Pp +The arguments +.Fa wantrows +and +.Fa wantcols +are the number of rows and columns we'd like. +Passing zero for either one of them uses the default \(em normally +80 by 25 but it can be changed with config options +.Dv RASOPS_DEFAULT_WIDTH +and +.Dv RASOPS_DEFAULT_HEIGHT . +.Pp +In terms of optimization, bitmap fonts of width 8 or 16 work the best +for all depths. +For depths other than 1 the fonts of width 12 are also optimized. +.Pp +If calling +.Fn rasops_reconfig +to change the font and +.Fa ri_wsfcookie +is non-negative, you must call +.Fn wsfont_unlock +on it, and reset it to \-1 or a new, valid cookie. +.Sh CODE REFERENCES +The rasops subsystem is implemented within the directory +.Pa sys/dev/rasops . +The +.Nm +module itself is implemented within the file +.Pa sys/dev/rasops/rasops.c . +.Sh SEE ALSO +.Xr intro 9 , +.Xr wscons 9 , +.Xr wsdisplay 9 , +.Xr wsfont 9 +.Sh HISTORY +The +.Nm +subsystem appeared in +.Nx 1.5 . +.Sh AUTHORS +The +.Nm +subsystem was written by +.An Andrew Doran +.Aq ad@NetBSD.org . diff --git a/static/netbsd/man9/ratecheck.9 b/static/netbsd/man9/ratecheck.9 new file mode 100644 index 00000000..6c30a2f3 --- /dev/null +++ b/static/netbsd/man9/ratecheck.9 @@ -0,0 +1,144 @@ +.\" $NetBSD: ratecheck.9,v 1.12 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright (c) 2000 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christopher G. Demetriou. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 2, 2000 +.Dt RATECHECK 9 +.Os +.Sh NAME +.Nm ratecheck +.Nd function to help implement rate-limited actions +.Sh SYNOPSIS +.In sys/time.h +.Ft int +.Fn ratecheck "struct timeval *lasttime" "const struct timeval *mininterval" +.Sh DESCRIPTION +The +.Fn ratecheck +function provides a simple time interval check which can be used +when implementing time-based rate-limited actions. +If the difference between the current monotonically-increasing +system time +.Pq Va mono_time +and +.Fa lasttime +is less than the value given by the +.Fa mininterval +argument, zero is returned. +Otherwise, +.Fa lasttime +is set to the current time and a non-zero value is returned. +.Pp +The motivation for implementing +.Fn ratecheck +was to provide a mechanism that could be used to add rate limiting to +diagnostic message output. +If printed too often, diagnostic messages can keep the system from +doing useful work. +If the repeated messages can be caused by deliberate user action +or network events, they can be exploited to cause denial of system service. +.Pp +Note that using a very short time interval (less than a second) +for +.Fa mininterval +defeats the purpose of this function. +(It doesn't take much to flood a 9600 baud serial console with +output, for instance.) +.Sh EXAMPLES +Here is a simple example of use of the +.Fn ratecheck +function: +.Bd -literal +/* + * The following variables could be global, in a device softc, etc., + * depending on the exact usage. + */ +struct timeval drv_lasterr1time; /* time of last err1 message */ +long drv_err1count; /* # of err1 errs since last msg */ +struct timeval drv_lasterr2time; /* time of last err2 message */ +long drv_err2count; /* # of err2 errs since last msg */ + +/* + * The following variable will often be global or shared by all + * instances of a driver. It should be initialized, so it can be + * patched. Allowing it to be set via an option might be nice, + * but could lead to an insane proliferation of options. + */ +struct timeval drv_errintvl = { 5, 0 }; /* 5 seconds */ + +/* error handling/reporting function */ +void +drv_errhandler(int err1, int err2) +{ + + /* + * Note that you should NOT use the same last-event + * time variable for dissimilar messages! + */ + if (err1) { + /* handle err1 condition */ + ... + + drv_err1count++; + if (ratecheck(&drv_lasterr1notice, + &drv_errinterval)) { + printf("drv: %ld err1 errors occurred", + drv_err1count); + drv_err1count = 0; + } + } + if (err2) { + /* handle err2 condition */ + ... + + drv_err2count++; + if (ratecheck(&drv_lasterr2notice, + &drv_errinterval)) { + printf("drv: %ld err2 errors occurred", + drv_err2count); + drv_err2count = 0; + } + } +} +.Ed +.Sh SEE ALSO +.Xr log 9 , +.Xr ppsratecheck 9 , +.Xr printf 9 , +.Xr time_second 9 +.Sh HISTORY +The +.Fn ratecheck +function appeared in +.Nx 1.5 . +.Sh BUGS +.Fn ratecheck +may not work as expected, if +.Fa mininterval +is less than the hardware clock interrupt interval +.Pq Li 1/hz . diff --git a/static/netbsd/man9/resettodr.9 b/static/netbsd/man9/resettodr.9 new file mode 100644 index 00000000..7cc4fcbd --- /dev/null +++ b/static/netbsd/man9/resettodr.9 @@ -0,0 +1,52 @@ +.\" $NetBSD: resettodr.9,v 1.12 2024/09/07 19:13:29 rillig Exp $ +.\" +.\" Copyright (c) 1994 Christopher G. Demetriou +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the +.\" NetBSD Project. See https://www.NetBSD.org/ for +.\" information about NetBSD. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" <<Id: LICENSE,v 1.2 2000/06/14 15:57:33 cgd Exp>> +.\" +.Dd March 2, 2006 +.Dt RESETTODR 9 +.Os +.Sh NAME +.Nm resettodr +.Nd set battery-backed clock from system time +.Sh SYNOPSIS +.Ft void +.Fn resettodr "void" +.Sh DESCRIPTION +The +.Fn resettodr +function sets the system's battery-backed clock based on the current +system time. +.Sh SEE ALSO +.Xr clock_secs_to_ymdhms 9 , +.Xr inittodr 9 , +.Xr time_second 9 diff --git a/static/netbsd/man9/rnd.9 b/static/netbsd/man9/rnd.9 new file mode 100644 index 00000000..1d9da135 --- /dev/null +++ b/static/netbsd/man9/rnd.9 @@ -0,0 +1,430 @@ +.\" $NetBSD: rnd.9,v 1.33 2024/12/25 17:51:56 andvar Exp $ +.\" +.\" Copyright (c) 1997 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation is derived from text contributed to The NetBSD +.\" Foundation by S.P.Zeidler (aka stargazer). +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 25, 2020 +.Dt RND 9 +.Os +.Sh NAME +.Nm RND , +.Nm rnd_attach_source , +.Nm rnd_detach_source , +.Nm rnd_add_data , +.Nm rnd_add_data_intr , +.Nm rnd_add_data_sync , +.Nm rnd_add_uint32 +.Nd functions to make a device available for entropy collection +.Sh SYNOPSIS +.In sys/rndsource.h +.Vt typedef struct krndsource krndsource_t; +.Ft void +.Fn rndsource_setcb "krndsource_t *rnd_source" "void (*callback)(size_t, void *)" "void *cookie" +.Ft void +.Fn rnd_attach_source "krndsource_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags" +.Ft void +.Fn rnd_detach_source "krndsource_t *rnd_source" +.Ft void +.Fn rnd_add_data "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy" +.Ft void +.Fn rnd_add_data_intr "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy" +.Ft void +.Fn rnd_add_data_sync "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy" +.Ft void +.Fn rnd_add_uint32 "krndsource_t *rnd_source" "uint32_t datum" +.Sh DESCRIPTION +The +.Nm +functions enable drivers to collect samples of physical observations, +such as network packet timings or hardware random number generator +outputs, into a kernel entropy pool to derive key material for +.Xr cprng 9 +and +.Xr rnd 4 +.Pq Pa /dev/random , Pa /dev/urandom . +.Pp +Usage model: +.Bl -enum -compact +.It +Allocate and zero a +.Vt struct krndsource +object before using the +.Nm +functions. +.It +Optionally, set a callback with +.Fn rndsource_setcb +if appropriate, e.g. for an on-demand hardware random number +generator. +.It +Attach the random source with +.Fn rnd_attach_source . +.It +Enter data with +.Fn rnd_add_data , +.Fn rnd_add_data_intr , +or +.Fn rnd_add_uint32 , +or, if in the callback, +.Fn rnd_add_data_sync . +.It +When the driver is done, detach it with +.Fn rnd_detach_source . +.El +.Pp +The following types of random sources are defined: +.Bl -tag -width "Dv RND_TYPE_UNKNOWN" -compact +.It Dv RND_TYPE_DISK +Disk devices, typically sampling seek timings. +.It Dv RND_TYPE_ENV +Environmental sensors. +.It Dv RND_TYPE_POWER +Power sensors and timing of power-related events. +.It Dv RND_TYPE_NET +Network interfaces, typically sampling packet timings. +By default, sample from network interfaces are ignored, for hysterical +raisins. +.It Dv RND_TYPE_RNG +Hardware random number generators. +.It Dv RND_TYPE_SKEW +Skew between clocks. +.It Dv RND_TYPE_TAPE +Tape devices, typically sampling I/O timings. +.It Dv RND_TYPE_TTY +Tty devices, typically sampling interrupt timings. +.It Dv RND_TYPE_VM +Virtual memory fault timings. +.It Dv RND_TYPE_UNKNOWN +Unknown sources, or sources not otherwise classified. +.El +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn rndsource_setcb "rnd_source" "callback" "cookie" +Sets a callback to be invoked when the entropy pool is hungry +to draw data from this source on demand. +Optional; if used, must be used +.Em before +.Fn rnd_attach_source , +and the caller must pass +.Dv RND_FLAG_HASCB +to +.Fn rnd_attach_source . +.Pp +The callback is invoked as +.Fo callback +.Fa nbytes +.Fa cookie +.Fc , +where +.Fa nbytes +is the number of bytes requested for the entropy pool, and +.Fa cookie +is the cookie that was passed to +.Fn rndsource_setcb . +The callback normally does one of two things: +.Bl -dash +.It +Sends a request to a hardware device for entropy and returns. +The hardware will later return data asynchronously by an interrupt, and +the callback will use +.Fn rnd_add_data , +.Fn rnd_add_data_intr , +or +.Fn rnd_add_uint32 +to add the data to the pool. +.It +Synchronously gathers entropy from hardware \(em for example, by a CPU +instruction like Intel RDSEED. +In this case, in order to add data to the pool +.Em before +returning, the callback +.Em must +use +.Fn rnd_add_data_sync , +not +.Fn rnd_add_data , +.Fn rnd_add_data_intr \" this works for now but no promises +or +.Fn rnd_add_uint32 . \" this also works for now but no promises +.El +.Pp +.Nm +issues calls to each source's +.Fa callback +in serial \(em it never issues two calls to the same source's callback +at the same time in two different threads or on two different CPUs. +.Pp +The callback may be invoked in thread context or soft interrupt +context, up to +.Dv SOFTINT_SERIAL , +and as such must follow the rules of soft interrupt handlers in +.Xr softint 9 +\(em that is, the callback must never sleep, except on adaptive +.Xr mutex 9 +locks at +.Dv IPL_SOFTSERIAL . +The callback will never be called in hard interrupt context. +.It Fn rnd_attach_source "rnd_source" "devname" "type" "flags" +Makes +.Fa rnd_source +available for entropy collection. +Must be called +.Em before +the source struct pointed to by +.Fa rnd_source +is used in any of the following functions. +If a callback was specified with +.Fn rndsource_setcb , +the kernel may invoke it at any time after +.Fn rnd_attach_source +until +.Fn rnd_detach_source , +so the callback must be ready to be invoked +.Em before +calling +.Fn rnd_attach_source . +.Pp +The +.Fa devname +is exposed via +.Xr rnd 4 +and +.Xr rndctl 8 . +The +.Fa type +must be one of the +.Dv RND_TYPE_* +constants above. +The +.Fa flags +are the bitwise-or of any of the following constants: +.Bl -tag -width abcd +.It Dv RND_FLAG_HASCB +The random source has a callback, which must have been set with +.Fn rndsource_setcb . +.It Dv RND_FLAG_COLLECT_TIME +Enter the timing of each +.Fn rnd_add_* +call into the entropy pool. +If not set, at most only the data arguments to +.Fn rnd_add_* +will be entered. +.It Dv RND_FLAG_COLLECT_VALUE +Enter the data arguments passed to the +.Fn rnd_add_* +functions into the pool. +If not set, the data will be ignored; at most the timing of the sample +will be entered. +.It Dv RND_FLAG_DEFAULT +Equivalent to +.Dv RND_FLAG_COLLECT_TIME | RND_FLAG_COLLECT_VALUE . +.It Dv RND_FLAG_ESTIMATE_TIME , RND_FLAG_ESTIMATE_VALUE +Legacy options no longer used. +.El +.It Fn rnd_detach_source "rnd_source" +Disconnects +.Fa rnd_source +from entropy collection. +The kernel will cease to invoke the callback, if any, and the caller +must not use +.Fa rnd_source +with any of the +.Fn rnd_add_* +functions after +.Fn rnd_detach_source . +The caller may release the memory for +.Fa rnd_source +afterward. +.It Fn rnd_add_data "rnd_source" "data" "len" "entropy" +Enters +.Fa len +bytes at +.Fa data +into the entropy pool, if +.Dv RND_FLAG_COLLECT_VALUE +was specified for +.Fa rnd_source , +and a timestamp, if +.Dv RND_FLAG_COLLECT_TIME +was specified. +.Pp +The argument +.Fa entropy +provides a conservative estimate for the number of bits of entropy in +the +.Em physical process +that generated the data, given all the past samples. +Drivers for devices for which this is not known should pass zero; +typically only drivers for hardware random number generators pass +nonzero values. +Hardware random number generator drivers should perform on-line +self-tests before advertising nonzero entropy for samples. +.Pp +.Fn rnd_add_data +.Em must not +be used during a callback as set with +.Fn rndsource_setcb ; +use +.Fn rnd_add_data_sync +instead. +.Pp +.Fn rnd_add_data +.Em must not +be called from thread context with spin locks held. +.Pp +For compatibility, +.Fn rnd_add_data +currently +.Em may +but +.Em should not +be called from interrupt context, possibly with spin locks held. +However, this may be forbidden in the future; use +.Fn rnd_add_data_intr +from interrupt context instead, if the work can't be usefully deferred +to softint or thread. +.It Fn rnd_add_data_intr "rnd_source" "data" "len" "entropy" +Tries to enter +.Fa len +bytes at +.Fa data +into the entropy pool like +.Fn rnd_add_data , +but if this fills or would overflow a sample buffer, schedules a +softint to process it and discards an unspecified subset of the data +while counting zero entropy for the sample. +.Pp +.Fn rnd_add_data_intr +may be called from any context, including hard interrupt context, +including contexts where spin locks are held, except that it +.Em must not +be used during a callback as set with +.Fn rndsource_setcb ; +use +.Fn rnd_add_data_sync +in that context instead. +.It Fn rnd_add_data_sync "rnd_source" "data" "len" "entropy" +Like +.Fn rnd_add_data , +but may be used in a callback as set with +.Fn rndsource_setcb . +Must always be called in thread context. +.It Fn rnd_add_uint32 "rnd_source" "datum" +Equivalent to +.Li rnd_add_data_intr Ns ( Ns Fa rnd_source , Li & Ns Fa datum , Li 4 , 0 ) . +.Pp +.Fn rnd_add_uint32 +may be called from any context, including hard interrupt context, +including contexts where spin locks are held, except that it +.Em must not +be used during a callback as set with +.Fn rndsource_setcb ; +use +.Fn rnd_add_data_sync +in that context instead. +.Pp +.Fn rnd_add_uint32 +is meant for cheaply taking samples from devices that aren't designed +to be hardware random number generators. +.El +.Sh FILES +These functions are declared in src/sys/sys/rndsource.h and defined in +src/sys/kern/kern_entropy.c. +.Sh EXAMPLES +.Bd -literal +struct xyz_softc { + ... + struct krndsource sc_rndsource; +}; + +static void +xyz_attach(device_t parent, device_t self, void *aux) +{ + struct xyz_softc *sc = device_private(self); + ... + rndsource_setcb(&sc->sc_rndsource, xyz_get, sc); + rnd_attach_source(&sc->sc_rndsource, device_xname(self), + RND_TYPE_RNG, RND_FLAG_DEFAULT); +} + +static int +xyz_detach(device_t self, int flags) +{ + ... + rnd_detach_source(&sc->sc_rndsource); + ... + return 0; +} + +static void +xyz_get(size_t nbytes, void *cookie) +{ + struct xyz_softc *sc = cookie; + uint32_t v; + unsigned timo = 10; + + while (nbytes) { + while (bus_space_read_4(sc->sc_bst, sc->sc_bsh, + XYZ_RNGREADY) == 0) { + if (--timo == 0) + return; + DELAY(10); + } + v = bus_space_read_4(sc->sc_bst, sc->sc_bsh, + XYZ_RNGDATUM); + /* data sheet sez 18 bits entropy in 32-bit sample */ + rnd_add_data_sync(&sc->sc_rndsource, &v, sizeof v, 18); + nbytes -= 18/NBBY; + } +} + +static void +xyz_intr(void *cookie) +{ + struct xyz_softc *sc = cookie; + uint32_t isr; + + isr = bus_space_read_4(sc->sc_bst, sc->sc_bsh, XYZ_ISR); + bus_space_write_4(sc->sc_bst, sc->sc_bsh, XYZ_ISR, isr); + rnd_add_uint32(&sc->sc_rndsource, isr); + ... +} +.Ed +.Sh SEE ALSO +.Xr rnd 4 , +.Xr rndctl 8 , +.Xr cprng 9 +.Sh HISTORY +The random device was introduced in +.Nx 1.3 . +It was substantially rewritten in +.Nx 6.0 , +and again in +.Nx 10.0 . +.Sh AUTHORS +This implementation was written by +.An Taylor R Campbell Aq Mt riastradh@NetBSD.org . diff --git a/static/netbsd/man9/roundup.9 b/static/netbsd/man9/roundup.9 new file mode 100644 index 00000000..af1cf4d2 --- /dev/null +++ b/static/netbsd/man9/roundup.9 @@ -0,0 +1,106 @@ +.\" $NetBSD: roundup.9,v 1.9 2019/10/02 08:21:08 rin Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 2, 2019 +.Dt ROUNDUP 9 +.Os +.Sh NAME +.Nm roundup +.Nd macros for counting and rounding +.Sh SYNOPSIS +.In sys/param.h +.Ft size +.Fn howmany "x" "size" +.Ft size +.Fn roundup "x" "size" +.Ft size +.Fn rounddown "x" "size" +.Ft size +.Fn roundup2 "x" "size" +.Ft size +.Fn rounddown2 "x" "size" +.Ft int +.Fn powerof2 "x" +.Sh DESCRIPTION +The +.Fn roundup +and +.Fn rounddown +macros return an integer from rounding +.Fa x +up and down, respectively, to the next +.Fa size . +The +.Fn howmany +macro in turn reveals how many times +.Fa size +fits into +.Fa x , +rounding the residual up. +.Pp +The +.Fn roundup2 +and +.Fn rounddown2 +macros also round up and down, respectively, but with the assumption that +.Fa size +is a power of two. +If +.Fa x +is indeed a power of two, +.Fn powerof2 +return 1. +.Sh RETURN VALUES +The return value is an integer from the respective operation. +If +.Fa x +is 0, all macros except +.Fn powerof2 +return 0. +The behavior is undefined if +.Fa size +is 0. +.Sh EXAMPLES +The following example rounds the variable +.Va rx +to a 32-bit boundary: +.Bd -literal -offset indent +uint16_t rx; + +\&... + +rx = roundup2(rx, sizeof(uint32_t)); +.Ed +.Sh SEE ALSO +.Xr ilog2 3 , +.Xr param 3 , +.Xr imax 9 +.Sh CAVEATS +All described macros make no assumptions about the type of the parameters. +These are implicitly assumed to be unsigned integers. diff --git a/static/netbsd/man9/rssadapt.9 b/static/netbsd/man9/rssadapt.9 new file mode 100644 index 00000000..fff9b0ad --- /dev/null +++ b/static/netbsd/man9/rssadapt.9 @@ -0,0 +1,394 @@ +.\" $NetBSD: rssadapt.9,v 1.10 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright (c) 2004 David Young. All rights reserved. +.\" +.\" This code is by David Young. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer in the documentation and/or other materials +.\" provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY David Young ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, +.\" THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A +.\" PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL David +.\" Young BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, +.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED +.\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 23, 2004 +.Dt RSSADAPT 9 +.Os +.Sh NAME +.Nm rssadapt , +.Nm ieee80211_rssadapt_choose , +.Nm ieee80211_rssadapt_input , +.Nm ieee80211_rssadapt_lower_rate , +.Nm ieee80211_rssadapt_raise_rate , +.Nm ieee80211_rssadapt_updatestats +.Nd rate adaptation based on received signal strength +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.In net80211/ieee80211_rssadapt.h +.Ft void +.Fn ieee80211_rssadapt_input "struct ieee80211com *ic" \ +"struct ieee80211_node *ni" "struct ieee80211_rssadapt *ra" "int rssi" +.Ft void +.Fn ieee80211_rssadapt_lower_rate "struct ieee80211com *ic" \ +"struct ieee80211_node *ni" "struct ieee80211_rssadapt *ra" \ +"struct ieee80211_rssdesc *id" +.Ft void +.Fn ieee80211_rssadapt_raise_rate "struct ieee80211com *ic" \ +"struct ieee80211_rssadapt *ra" "struct ieee80211_rssdesc *id" +.Ft void +.Fn ieee80211_rssadapt_updatestats "struct ieee80211_rssadapt *ra" +.Ft int +.Fn ieee80211_rssadapt_choose "struct ieee80211_rssadapt *ra" \ +"struct ieee80211_rateset *rs" "struct ieee80211_frame *wh" "u_int len" \ +"int fixed_rate" "const char *dvname" "int do_not_adapt" +.Sh DESCRIPTION +The +.Nm +module provides rapid adaptation of transmission data rate to 802.11 +device drivers based on received-signal strength +.Pq RSS . +A driver needs only to provide +.Nm +with indications of RSS and failure/success of transmissions for +each 802.11 client or peer. +For each transmit packet, +.Nm +chooses the transmission data rate that offers the best expected +throughput, given the packet's length and destination. +.Pp +.Nm +models an 802.11 channel very simply +.Po +see also the +.Sx BUGS +section +.Pc . +It assumes that the packet-error rate +.Pq PER +is determined by the signal-to-noise ratio +.Pq S/N +at the receiver, the transmission data rate, and the packet length. +The S/N determines the choice of data rate that yields the lowest +PER for all packets of a certain length. +.Sh FUNCTIONS +.Bl -tag -width 18n -compact +.It Fn ieee80211_rssadapt_choose "ra" "rs" "wh" "len" "fixed_rate" "dvname" \ +"do_not_adapt" +Choose the transmission data rate for a packet. +.Bl -tag -width "do_not_adapt" -compact +.It Fa ra +Ordinarily, the +.Nm +state object belonging to the node which is the packet destination. +However, if the destination is a broadcast/multicast address, then +.Fa ra +belongs to the BSS node, +.Va ic->ic_bss . +.It Fa rs +A list of eligible data rates for the node; for example, the +rates negotiated when the node associated with the network. +.It Fa len +The packet length in bytes, including the 802.11 header and +frame check sequence +.Pq FCS . +.It Fa fixed_rate +If the operator has set the data rate using, for example, +.Ic "ifconfig wi0 media ds1" , +then +.Fa fixed_rate +tells the index of that rate in +.Fa rs . +.Nm +obeys a fixed data rate whenever the 802.11 standard allows it: +sometimes the standard requires multicast/broadcast packets to be +transmitted at a so-called +.Dq basic rate . +.It Fa dvname +The device driver uses +.Fa dvname +to indicate the name of the +interface for the purpose of diagnostic and debug messages. +The driver sets +.Fa dvname +to +.Dv NULL +when no messages are desired. +.It Fa do_not_adapt +If +.Fa do_not_adapt +is non-zero, then +.Fn ieee80211_rssadapt_choose +will choose the highest rate in +.Fa rs +that suits the destination, regardless of the RSS. +.El +The return value of +.Fn ieee80211_rssadapt_choose +is an index into +.Fa rs , +indicating its choice of transmit data rate. +.It Fn ieee80211_rssadapt_input "ic" "ni" "ra" "rssi" +The RSS serves as a rough estimate of the S/N at each node. +A driver provides RSS updates using +.Fn ieee80211_rssadapt_input , +whose arguments are: +.Bl -tag -width "rssi" -compact +.It Fa ic +The wireless interface's 802.11 state object. +.It Fa ni +The 802.11 node whose RSS the driver is updating. +.It Fa ra +The node's +.Nm +state object. +.It Fa rssi +The node's received signal strength indication. +The range of +.Fa rssi +is from 0 to 255. +.El +.It Fn ieee80211_rssadapt_lower_rate "ic" "ni" "ra" "id" +.It Fn ieee80211_rssadapt_raise_rate "ic" "ra" "id" +Drivers call +.Fn ieee80211_rssadapt_raise_rate +and +.Fn ieee80211_rssadapt_lower_rate +to indicate transmit successes and failures, respectively. +.Bl -tag -width "ni" -compact +.It Fa ic +The 802.11 state object. +.It Fa ni +The neighbor to whom the driver transmitted. +.It Fa ra +The neighbor's +.Nm +state object. +.It Fa id +DIsplays statistics on the transmission attempt. +.El +.It Fn ieee80211_rssadapt_updatestats "ra" +An 802.11 node is eligible for its RSS thresholds to decay every +1/10 to 10 seconds. +It is eligible more often (every 1/10 second) at high packet rates, +and less often (every 10 seconds) at low packet rates. +A driver assists +.Nm +in tracking the exponential-average packet rate by calling +.Fn ieee80211_rssadapt_updatestats +every 1/10th second for each node's +.Vt ieee80211_rssadapt +object. +.Bl -tag -width "ra" -compact +.It Fa ra +The neighbor's +.Nm +state object. +.El +.El +.Sh ALGORITHM +.Nm +monitors the RSS from neighboring 802.11 nodes, recording the +exponential average RSS in each neighbor's +.Vt ieee80211_rssadapt +structure. +.Nm +uses transmit success/failure feedback from the +device driver to fill a table of RSS thresholds. +The table is indexed by packet size, +.Va L , +and a data rate, +.Va R , +to find out the minimum exponential-average RSS that a node must show before +.Nm +will indicate that a packet +.Va L +bytes long can be transmitted R bits per second with optimal expected +throughput. +When the driver indicates a unicast packet is transmitted unsuccessfully +.Po +that is, the NIC received no ACK for the packet +.Pc , +.Nm +will move the corresponding RSS threshold toward the exponential +average RSSI at the time of transmission. +Thus several consecutive transmit failures for the same +.Ao +.Va L , +.Va R +.Ac +tuple will ensure that the RSS threshold rises high enough that +rate +.Va R +is abandoned for packets +.Va L +bytes long. +When the driver indicates a successful transmission, +the RSS threshold corresponding to the same packet length, but the +next higher data rate, is lowered slightly. +The RSS threshold is said to +.Dq decay . +This ensures that occasionally +.Nm +indicates the driver should try the next higher data rate, +just in case conditions at the receiver have changed +.Po +for example, noise levels have fallen +.Pc +and a higher data rate can be supported at the same RSS level. +.Pp +The rate of decay is controlled. +In an interval of 1/10th second +to 10 seconds, only one RSS threshold per neighbor may decay. +The interval is connected to the exponential-average rate that packets +are being transmitted. +At high packet rates, the interval is shortest. +It is longest at low packet rates. +The rationale for this is that RSS thresholds should not decay +rapidly if there is no information from packet transmissions to +counteract their decay. +.Sh DATA STRUCTURES +An +.Vt ieee80211_rssdesc +describes a transmission attempt. +.Pp +.Bd -literal -offset indent +struct ieee80211_rssdesc { + u_int id_len; + u_int id_rateidx; + struct ieee80211_node *id_node; + u_int8_t id_rssi; +}; +.Ed +.Pp +.Fa id_len +is the length, in bytes, of the transmitted packet. +.Fa id_node +points to the neighbor's +.Vt ieee8021_node , +and +.Fa id_rssi +is the exponential-average RSS at the time the packet was +transmitted. +.Fa id_rateidx +is an index into the destination-neighbor's rate-set, +.Fa id_node->ni_rates , +indicating the transmit data rate for the packet. +.Pp +An +.Vt ieee80211_rssadapt +contains the rate-adaptation state for a neighboring 802.11 node. +Ordinarily a driver will +.Dq subclass +.Vt ieee80211_node . +The +.Vt ieee80211_rssadapt +structure will be a subclass member. +In this way, every node's +.Nm +condition is independently tracked and stored in its node object. +.Pp +.Bd -literal -offset indent +struct ieee80211_rssadapt { + u_int16_t ra_avg_rssi; + u_int32_t ra_nfail; + u_int32_t ra_nok; + u_int32_t ra_pktrate; + u_int16_t ra_rate_thresh[IEEE80211_RSSADAPT_BKTS] + [IEEE80211_RATE_SIZE]; + struct timeval ra_last_raise; + struct timeval ra_raise_interval; +}; +.Ed +.Pp +.Fa ra_avg_rssi +is the exponential-average RSS, shifted left 8 bits. +.Fa ra_nfail +tells the number of transmit failures in the current update interval. +.Fa ra_nok +tells the number of transmit successes in the current update interval. +.Fa ra_pktrate +tells the exponential average number of transmit failure/success +indications over past update intervals. +This approximates the rate of packet-transmission. +.Fa ra_rate_thresh +contains RSS thresholds that are indexed by +.Aq "packet length, data rate" +tuples. +When this node's exponential-average RSS exceeds +.Fa ra_rate_thresh[i][j] , +then packets at most 128 x 8^i bytes long are eligible to be +transmitted at the rate indexed by j. +.Fa ra_last_raise +and +.Fa ra_raise_interval +are used to control the rate that RSS thresholds +.Dq decay . +.Fa ra_last_raise +indicates when +.Fn ieee80211_rssadapt_raise_rate +was last called. +.Fa ra_raise_interval +tells the minimum period between consecutive calls to +.Fn ieee80211_rssadapt_raise_rate . +If +.Fn ieee80211_rssadapt_raise_rate +is called more than once in any period, the second and subsequent +calls are ignored. +.Sh CODE REFERENCES +The code for +.Nm +is in the file +.Pa sys/net80211/ieee80211_rssadapt.c . +.Pp +.Xr wi 4 +contains a reference implementation. +See +.Pa sys/dev/ic/wi.c . +.Sh SEE ALSO +.Xr wi 4 +.Rs +.%A Javier del Prado Pavon +.%A Sunghyun Choi +.%T "Link Adaptation Strategy for IEEE 802.11 WLAN via Received Signal \ +Strength Measurement" +.%J "ICC'03" +.%P pp. 1108-1113 +.%C Anchorage, Alaska +.%D May 2003 +.Re +.Sh HISTORY +.Nm +first appeared in +.Nx 3.0 . +.Sh AUTHORS +.An David Young Aq Mt dyoung@NetBSD.org +.Sh BUGS +To cope with interference from microwave ovens, frequency-hopping +radios, and other sources of RF pulse-trains and bursts, +.Nm +should adapt the fragmentation threshold as well as the data rate. +.Pp +For improved throughput, +.Nm +should indicate to drivers when they should use the 802.11b +short-preamble. +.Pp +The constants in +.Fn ieee80211_rssadapt_updatestats +should be configurable. diff --git a/static/netbsd/man9/rt_timer.9 b/static/netbsd/man9/rt_timer.9 new file mode 100644 index 00000000..ed57331c --- /dev/null +++ b/static/netbsd/man9/rt_timer.9 @@ -0,0 +1,135 @@ +.\" $NetBSD: rt_timer.9,v 1.15 2016/06/01 08:17:47 wiz Exp $ +.\" +.\" Copyright (c) 1998 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Kevin M. Lahey of the Numerical Aerospace Simulation Facility, +.\" NASA Ames Research Center. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 1, 2016 +.Dt RT_TIMER 9 +.Os +.Sh NAME +.Nm rt_timer , +.Nm rt_timer_add , +.Nm rt_timer_queue_create , +.Nm rt_timer_queue_change , +.Nm rt_timer_queue_destroy , +.Nm rt_timer_remove_all +.Nd route callout functions +.Sh SYNOPSIS +.In net/route.h +.Ft "struct rttimer_queue *" +.Fn rt_timer_queue_create "time_t timeout" +.Ft void +.Fn rt_timer_queue_change "struct rttimer_queue *q" "time_t timeout" +.Ft void +.Fn rt_timer_queue_destroy "struct rttimer_queue *q" "int destroy" +.Ft int +.Fn rt_timer_add "struct rtentry *rt" \ +"void(*f)(struct rtentry *, struct rttimer *)" "struct rttimer_queue *q" +.Ft void +.Fn rt_timer_remove_all "struct rtentry *rt" +.Sh DESCRIPTION +The +.Nm +functions provide a generic route callout functionality. +They allow a function to be called for a route at any time. +This was originally intended to be used to remove routes added +by path MTU discovery code. +.Pp +For maximum efficiency, a separate queue should be defined for each +timeout period. +For example, one queue should be created for the 10 minute path MTU +discovery timeouts, another for 20 minute ARP timeouts after 20 +minutes, and so on. +This permits extremely fast queue manipulations so that the timeout +functions remain scalable, even in the face of thousands of route +manipulations per minute. +.Pp +It is possible to create only a single timeout queue for all possible +timeout values, but doing so is not scalable as queue manipulations +become quite expensive if the timeout deltas are not roughly constant. +.Pp +The +.Nm +interface provides the following functions: +.Bl -tag -width compact +.It Fn rt_timer_queue_create "time_t timeout" +This function creates a new timer queue with the specified timeout period +.Fa timeout , +expressed in seconds. +.It Fn rt_timer_queue_change "rttimer_queue *q" "time_t timeout" +This function modifies the timeout period for a timer queue. +Any value, including 0, is valid. +The next time the timer queue's timeout expires (based on the previous +timeout value), all entries which are valid to execute based on the new +timeout will be executed, and the new timeout period scheduled. +.It Fn rt_timer_queue_destroy "rttimer_queue *q" "int destroy" +This function destroys a timeout queue. +All entries are removed, and if the +.Fa destroy +argument is non-zero, the timeout action is performed for each entry. +.It Fn rt_timer_add "struct rtentry *rt" \ +"void(*f)(struct rtentry *, struct rttimer *)" "struct rttimer_queue *q" +This function adds an entry to a timeout queue. +The function +.Fa f +will be called after the timeout period for queue +.Fa q +has elapsed. +If +.Fa f +is NULL +the route will be deleted when the timeout expires. +.It Fn rt_timer_remove_all "struct rtentry *rt" +This function removes all references to the given route from the +.Nm +subsystem. +This is used when a route is deleted to ensure that no dangling +references remain. +.El +.Sh CODE REFERENCES +The +.Nm +interface is implemented in +.Pa sys/net/route.h +and +.Pa sys/net/route.c . +.Sh SEE ALSO +.Xr netstat 1 , +.Xr arp 9 +.Sh HISTORY +The +.Nm +interface appeared in +.Nx 1.4 . +.Sh AUTHORS +.An -nosplit +This interface is roughly based on (but, alas, not compatible with) one +designed by David Borman of BSDI. +This implementation is by +.An Kevin Lahey +of the Numerical Aerospace Simulation Facility, NASA Ames Research Center. diff --git a/static/netbsd/man9/rwlock.9 b/static/netbsd/man9/rwlock.9 new file mode 100644 index 00000000..88e5a2b5 --- /dev/null +++ b/static/netbsd/man9/rwlock.9 @@ -0,0 +1,252 @@ +.\" $NetBSD: rwlock.9,v 1.20 2020/02/22 21:24:45 ad Exp $ +.\" +.\" Copyright (c) 2006, 2007, 2009, 2020 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Andrew Doran. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 22, 2020 +.Dt RWLOCK 9 +.Os +.Sh NAME +.Nm rw , +.Nm rw_init , +.Nm rw_destroy , +.Nm rw_enter , +.Nm rw_exit , +.Nm rw_tryenter , +.Nm rw_tryupgrade , +.Nm rw_downgrade , +.Nm rw_read_held , +.Nm rw_write_held , +.Nm rw_lock_held , +.Nm rw_lock_op +.Nd reader / writer lock primitives +.Sh SYNOPSIS +.In sys/rwlock.h +.Ft void +.Fn rw_init "krwlock_t *rw" +.Ft void +.Fn rw_destroy "krwlock_t *rw" +.Ft void +.Fn rw_enter "krwlock_t *rw" "const krw_t op" +.Ft void +.Fn rw_exit "krwlock_t *rw" +.Ft int +.Fn rw_tryenter "krwlock_t *rw" "const krw_t op" +.Ft int +.Fn rw_tryupgrade "krwlock_t *rw" +.Ft void +.Fn rw_downgrade "krwlock_t *rw" +.Ft int +.Fn rw_read_held "krwlock_t *rw" +.Ft int +.Fn rw_write_held "krwlock_t *rw" +.Ft int +.Fn rw_lock_held "krwlock_t *rw" +.Ft krw_t +.Fn rw_lock_op "krwlock_t *rw" +.Pp +.Cd "options DIAGNOSTIC" +.Cd "options LOCKDEBUG" +.Sh DESCRIPTION +Reader / writer locks (RW locks) are used in the kernel to synchronize access +to an object among LWPs (lightweight processes) and soft interrupt handlers. +.Pp +In addition to the capabilities provided by mutexes, RW locks distinguish +between read (shared) and write (exclusive) access. +.Pp +RW locks are in one of three distinct states at any given time: +.Bl -tag -width cdosrunrundo +.It Dv Unlocked +The lock is not held. +.It Dv Read locked +The lock holders intend to read the protected object. +Multiple callers may hold a RW lock with +.Dq read intent +simultaneously. +.It Dv Write locked +The lock holder intends to update the protected object. +Only one caller may hold a RW lock with +.Dq write intent . +.El +.Pp +The +.Vt krwlock_t +type provides storage for the RW lock object. +This should be treated as an opaque object and not examined directly by +consumers. +.Pp +Note that these interfaces must not be used from a hardware +interrupt handler. +.Sh OPTIONS AND MACROS +.Bl -tag -width abcd +.It Cd "options DIAGNOSTIC" +.Pp +Kernels compiled with the +.Dv DIAGNOSTIC +option perform basic sanity checks on RW lock operations. +.It Cd "options LOCKDEBUG" +.Pp +Kernels compiled with the +.Dv LOCKDEBUG +option perform potentially CPU intensive sanity checks +on RW lock operations. +.El +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn rw_init "rw" +.Pp +Initialize a lock for use. +No other operations can be performed on the lock until it has been +initialized. +.It Fn rw_destroy "rw" +.Pp +Release resources used by a lock. +The lock may not be used after it has been destroyed. +.It Fn rw_enter "rw" "op" +.Pp +If +.Dv RW_READER +is specified as the argument to +.Fa op , +acquire a read lock. +The caller may block and will not return until the hold is acquired. +Callers must not recursively acquire read locks. +.Pp +If +.Dv RW_WRITER +is specified, acquire a write lock. +If the lock is already held, the caller will block and not return until the +hold is acquired. +.Pp +RW locks and other types of locks must always be acquired in a +consistent order with respect to each other. +Otherwise, the potential for system deadlock exists. +.It Fn rw_exit "rw" +.Pp +Release a lock. +The lock must have been previously acquired by the caller. +.It Fn rw_tryenter "rw" "op" +.Pp +Try to acquire a lock, but do not block if the lock is already held. +If the lock is acquired successfully, return non-zero. +Otherwise, return zero. +.Pp +Valid arguments to +.Fa op +are +.Dv RW_READER +or +.Dv RW_WRITER . +.It Fn rw_tryupgrade "rw" +.Pp +Try to upgrade a lock from one read hold to a write hold. +If the lock is upgraded successfully, returns non-zero. +Otherwise, returns zero. +.It Fn rw_downgrade "rw" +.Pp +Downgrade a lock from a write hold to a read hold. +.It Fn rw_write_held "rw" +.Pp +Return non-zero if write lock is held by current lwp. +Otherwise, return zero. +.It Fn rw_read_held "rw" +.Pp +Returns non-zero if read lock is held by any lwp. +Otherwise, return zero. +.It Fn rw_lock_held "rw" +.Pp +Returns non-zero if either read or write lock is held by any lwp. +Otherwise, return zero. +.Pp +.Fn rw_write_held , +.Fn rw_read_held , +and +.Fn rw_lock_held +should not generally be used to make locking decisions at run time: +they are provided for diagnostic purposes, for example making +assertions. +.Pp +Negative assertions (lock not held) should not be made due to atomicity +issues, excepting +.Fn rw_write_held , +which can safely be used to assert that a write lock is NOT held by +the current LWP. +.It Fn rw_lock_op "rw" +.Pp +For a lock that is known to be held by the calling LWP, return either +.Dv RW_READER +or +.Dv RW_WRITER +to denote the type of hold. +This is useful when dropping and later re-acquiring a lock, if the type +of hold is not already known. +.El +.Sh PERFORMANCE CONSIDERATIONS +RW locks are subject to high cache contention on multiprocessor systems, +and scale poorly when the write:read ratio is not strongly in favour of +readers. +Ideally, RW locks should only be used in settings when the following three +conditions are met: +.Bl -bullet +.It +The data object(s) protected by the RW lock are read much more frequently +than written. +.It +The read-side hold time for the RW lock is long (in the order of thousands +of processor clock cycles). +.It +Strong synchronization semantics are required: there is no scope for +lockless, lazy or optimistic synchronization. +.El +.Pp +Generally speaking, it is better to organise code paths and/or +data flows such that fewer and weaker synchronization points are required +to ensure correct operation. +.Sh CODE REFERENCES +The core of the RW lock implementation is in +.Pa sys/kern/kern_rwlock.c . +.Pp +The header file +.Pa sys/sys/rwlock.h +describes the public interface, and interfaces that machine-dependent +code must provide to support RW locks. +.Sh SEE ALSO +.Xr membar_ops 3 , +.Xr lockstat 8 , +.Xr condvar 9 , +.Xr mutex 9 +.Rs +.%A Jim Mauro +.%A Richard McDougall +.%T Solaris Internals: Core Kernel Architecture +.%I Prentice Hall +.%D 2001 +.%O ISBN 0-13-022496-0 +.Re +.Sh HISTORY +The RW lock primitives first appeared in +.Nx 5.0 . diff --git a/static/netbsd/man9/scanc.9 b/static/netbsd/man9/scanc.9 new file mode 100644 index 00000000..b0c30e03 --- /dev/null +++ b/static/netbsd/man9/scanc.9 @@ -0,0 +1,68 @@ +.\" $NetBSD: scanc.9,v 1.4 2013/04/24 00:56:14 yamt Exp $ +.\" +.\" Copyright (c)2011,2013 YAMAMOTO Takashi, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ------------------------------------------------------------ +.Dd April 24, 2013 +.Dt SCANC 9 +.Os +.\" ------------------------------------------------------------ +.Sh NAME +.Nm scanc +.Nd use byte string as lookup table index +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In lib/libkern/libkern.h +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn scanc \ +"u_int size" "const u_char *cp" "const u_char table[]" "int mask" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +The +.Fn scanc +function scans the byte string +.Fa cp , +whose length is +.Fa size . +A character in the string is used as an index in the 256-byte +.Fa table . +If a bitwise-AND of the byte from the table and +.Fa mask +isn't zero or the string is exhausted, the scan stops. +.\" ------------------------------------------------------------ +.Sh RETURN VALUES +The +.Fn scanc +function returns the length of the rest of the string, +including the character which made the scan stop. +If the +.Fn scanc +function exhausted the string, it returns 0. +.\" ------------------------------------------------------------ +.Sh HISTORY +The +.Fn scanc +function emulates a VAX instruction with the same name. diff --git a/static/netbsd/man9/sched_4bsd.9 b/static/netbsd/man9/sched_4bsd.9 new file mode 100644 index 00000000..b33083e0 --- /dev/null +++ b/static/netbsd/man9/sched_4bsd.9 @@ -0,0 +1,106 @@ +.\" $NetBSD: sched_4bsd.9,v 1.9 2019/04/09 13:53:52 sevan Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry and Daniel Sieger. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 9, 2019 +.Dt SCHED_4BSD 9 +.Os +.Sh NAME +.Nm sched_4bsd +.Nd The 4.4BSD thread scheduler +.Sh SYNOPSIS +.In sys/sched.h +.Ft void +.Fn resetpriority "lwp_t *l" +.Ft void +.Fn sched_tick "struct cpu_info *ci" +.Ft void +.Fn sched_schedclock "lwp_t *l" +.Ft void +.Fn sched_pstats_hook "struct proc *p" "int minslp" +.Ft void +.Fn sched_setrunnable "lwp_t *l" +.Ft void +.Fn updatepri "lwp_t *l" +.Sh DESCRIPTION +The traditional +.Bx 4.4 +scheduler employs a +.Dq multilevel feedback queues +algorithm, favouring interactive, short-running threads to +CPU-bound ones. +.Pp +.Fn resetpriority +recomputes the priority of a thread running in user mode. +If the resulting priority is higher than that of the +current thread, a reschedule is arranged. +.Pp +.Fn sched_tick +gets called from +.Xr hardclock 9 +every 100ms to force a switch between equal priority threads. +.Pp +The priority of the current thread is adjusted through +.Fn sched_schedclock . +The priority of a thread gets worse as it accumulates CPU time. +.Pp +.Fn sched_pstats_hook +gets called from +.Fn sched_pstats +every Hz ticks in order to recompute the priorities of all threads. +.Pp +.Fn sched_setrunnable +checks if an LWP has slept for more than one second. +If so, its priority is updated by +.Fn updatepri . +.Sh EXAMPLES +To determine the scheduler currently in use +.Bd -literal -offset indent +$ sysctl kern.sched.name +kern.sched.name = 4.4BSD +.Ed +.Sh CODE REFERENCES +The +.Bx 4.4 +scheduler subsystem is implemented within the file +.Pa sys/kern/sched_4bsd.c . +.Sh SEE ALSO +.Xr csf 9 , +.Xr hardclock 9 , +.Xr mi_switch 9 , +.Xr sched_m2 9 , +.Xr userret 9 +.Rs +.%A Marshall Kirk McKusick +.%A Keith Bostic +.%A Michael J. Karels +.%A John S. Quarterman +.%B "The Design and Implementation of the 4.4BSD Operating System" +.%I "Addison Wesley" +.%D 1996 +.Re diff --git a/static/netbsd/man9/sched_m2.9 b/static/netbsd/man9/sched_m2.9 new file mode 100644 index 00000000..8bced6fb --- /dev/null +++ b/static/netbsd/man9/sched_m2.9 @@ -0,0 +1,62 @@ +.\" $NetBSD: sched_m2.9,v 1.4 2019/04/09 13:53:52 sevan Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Daniel Sieger. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 9, 2019 +.Dt SCHED_M2 9 +.Os +.Sh NAME +.Nm sched_m2 +.Nd The M2 thread scheduler +.Sh SYNOPSIS +.In sys/sched.h +.Sh DESCRIPTION +The M2 scheduler implements a scheduling algorithm similar to +the scheduler implementations of UNIX System V Release 4 and Solaris. +.Sh EXAMPLES +To determine the scheduler currently in use +.Bd -literal -offset indent +$ sysctl kern.sched.name +kern.sched.name = M2 +.Ed +.Sh CODE REFERENCES +The M2 scheduler is implemented within the file +.Pa sys/kern/sched_m2.c . +.Sh SEE ALSO +.Xr csf 9 , +.Xr hardclock 9 , +.Xr mi_switch 9 , +.Xr sched_4bsd 9 , +.Xr userret 9 +.Rs +.%A Berny Goodheart +.%A James Cox +.%B "The Magic Garden Explained: The Internals of UNIX System V Release 4" +.%I "Prentice Hall" +.%D 1994 +.Re diff --git a/static/netbsd/man9/scsipi.9 b/static/netbsd/man9/scsipi.9 new file mode 100644 index 00000000..d8ef3739 --- /dev/null +++ b/static/netbsd/man9/scsipi.9 @@ -0,0 +1,622 @@ +.\" $NetBSD: scsipi.9,v 1.33 2024/10/29 15:45:58 nat Exp $ +.\" +.\" +.\" Copyright (c) 2001 Manuel Bouyer. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.Dd November 20, 2016 +.Dt SCSIPI 9 +.Os +.Sh NAME +.Nm scsipi +.Nd SCSI/ATAPI middle-layer interface +.Sh SYNOPSIS +.In dev/scsipi/atapiconf.h +.In dev/scsipi/scsiconf.h +.Ft void +.Fn scsipi_async_event "struct scsipi_channel *chan" "scsipi_async_event_t event" "void *arg" +.Ft void +.Fn scsipi_channel_freeze "struct scsipi_channel *chan" "int count" +.Ft void +.Fn scsipi_channel_thaw "struct scsipi_channel *chan" "int count" +.Ft void +.Fn scsipi_channel_timed_thaw "void *arg" +.Ft void +.Fn scsipi_periph_freeze "struct scsipi_periph *periph" "int count" +.Ft void +.Fn scsipi_periph_thaw "struct scsipi_periph *periph" "int count" +.Ft void +.Fn scsipi_periph_timed_thaw "void *arg" +.Ft void +.Fn scsipi_done "struct scsipi_xfer *xs" +.Ft void +.Fn scsipi_printaddr "struct scsipi_periph *periph" +.Ft int +.Fn scsipi_target_detach "struct scsipi_channel *chan" "int target" "int lun" "int flags" +.Ft int +.Fn scsipi_thread_call_callback "struct scsipi_channel *chan" "void (*callback)(struct scsipi_channel *, void *)" "void *arg" +.Ft int +.Fn scsipi_adapter_addref "struct scsipi_adapter *adapt" +.Ft void +.Fn scsipi_adapter_delref "struct scsipi_adapter *adapt" +.Sh DESCRIPTION +The +.Nm +system is the middle layer interface between SCSI/ATAPI host bus +adapters (HBA) and high-level SCSI/ATAPI drivers. +This document describes the interfaces provided by the +.Nm +layer towards the HBA layer. +An HBA has to provide a pointer to a +.Va struct scsipi_adapter +and one pointer per channel to a +.Va struct scsipi_channel . +Once the SCSI or ATAPI bus is attached, the +.Nm +system will scan the bus and allocate a +.Va struct scsipi_periph +for each device found on the bus. +A high-level command (command sent from the high-level SCSI/ATAPI +layer to the low-level HBA layer) is described by a +.Va struct scsipi_xfer . +.Pp +A request is sent to the HBA driver through the +.Fn adapt_request +callback. +The HBA driver signals completion (with or without errors) of the +request through +.Fn scsipi_done . +.Nm +knows the resource's limits of the HBA (max number of concurrent requests per +adapter of channel, and per periph), and will make sure the HBA won't receive +more requests than it can handle. +.Pp +The mid-layer can also handle +.Dv QUEUE FULL +and +.Dv CHECK CONDITION +events. +.Ss INITIALISATION +An HBA driver has to allocate and initialize to 0 a +.Va struct scsipi_adapter +and fill in the following members: +.Bl -tag -width "struct_device *adapt_dev" -compact -offset indent +.It Va struct device *adapt_dev +pointer to the HBA's +.Va struct device +.It Va int adapt_nchannels +number of channels (or busses) of the adapter +.It Va int adapt_openings +total number of commands the adapter can handle (may be replaced by +.Va chan_openings , +see below) +.It Va int adapt_max_periph +number of commands the adapter can handle per device +.It Va int adapt_flags +adapter properties +.Bl -tag -width SCSIPI_ADAPT_POLL_ONLY -compact +.It Dv SCSIPI_ADAPT_POLL_ONLY +the HBA can't do interrupts +.It Dv SCSIPI_ADAPT_MPSAFE +don't acquire the kernel lock when doing HBA callbacks +.El +.El +.Pp +The following callbacks should be provided through the +.Va struct scsipi_adapter : +.Bl -tag -width someverylongword -compact -offset indent +.It void Fn (*adapt_request) "struct scsipi_channel *" "scsipi_adapter_req_t" "void *" +mandatory +.It void Fn (*adapt_minphys) "struct buf *" +mandatory +.It int Fn (*adapt_ioctl) "struct scsipi_channel *" "u_long" "void *" "int" "struct lwp *" +optional +.It int Fn (*adapt_enable) "struct device *" "int" +optional, set to +.Dv NULL +if not used +.It int Fn (*adapt_getgeom) "struct scsipi_periph *" "struct disk_parms *" "u_long" +optional, set to +.Dv NULL +if not used +.It int Fn (*adapt_accesschk) "struct scsipi_periph *" "struct scsipi_inquiry_pattern *" +optional, set to +.Dv NULL +if not used +.El +.Pp +The HBA driver has to allocate and initialize to 0 one +.Va struct scsipi_channel +per channel and fill in the following members: +.Bl -tag -width struct_scsipi_adapter -compact -offset indent +.It Va struct scsipi_adapter *chan_adapter +Pointer to the HBA's +.Fa struct scsipi_adapter +.It Va struct scsipi_bustype *chan_bustype +should be initialized to either +.Va bus_atapi +or +.Va bus_scsi , +both defined in the +.Nm +code. +.It Va int chan_channel +channel number (starting at 0) +.It Va int chan_flags +channel flags: +.Bl -tag -width SCSIPI_CHAN_OPENINGS -compact +.It Dv SCSIPI_CHAN_OPENINGS +Use per-channel max number of commands +.Va chan_openings +instead of per-adapter +.Va adapt_openings +.It Dv SCSIPI_CHAN_CANGROW +This channel can grow its +.Va chan_openings +or +.Va adapt_openings +on request (via the +.Fn adapt_request +callback) +.It Dv SCSIPI_CHAN_NOSETTLE +Do not wait SCSI_DELAY seconds for devices to settle before probing (usually +used by adapters that provide an \*qabstracted\*q view of the bus). +.El +.It Va int chan_openings +total number of commands the adapter can handle for this channel (used only +if the +.Dv SCSIPI_CHAN_OPENINGS +flag is set) +.It Va chan_max_periph +number of commands per device the adapter can handle on this +channel (used only if the +.Va SCSIPI_CHAN_OPENINGS +flag is set) +.It Va int chan_ntargets +number of targets +.It Va int chan_nluns +number of LUNs per target +.It Va int chan_id +adapter's ID on this channel +.It Va int chan_defquirks +default device quirks. +Quirks are defined in +.In dev/scsipi/scsipiconf.h +and are usually set in the middle layer based on the device's inquiry +data. +For some kinds of adapters it may be convenient to have a set of +quirks applied to all devices, regardless of the inquiry data. +.El +.Pp +The HBA driver attaches the SCSI or ATAPI bus (depending on the setting of +.Va chan_bustype ) +by passing a pointer to the +.Va struct scsipi_channel +to the +.Xr autoconf 9 +machinery. +The print function shall be either +.Fn scsiprint +or +.Fn atapiprint . +.Ss OTHER DATA STRUCTURES +When scanning the bus, the +.Nm +system allocates a +.Va struct scsipi_periph +for each device probed. +The interesting fields are: +.Bl -tag -width int_periph_openings -compact -offset indent +.It Va struct device *periph_dev +pointer to the device's +.Va struct device +.It Va struct scsipi_channel *periph_channel +pointer to the channel the device is connected to +.It Va int periph_quirks +device quirks, defined in +.In dev/scsipi/scsipiconf.h +.It Va int periph_target +target ID, or drive number on ATAPI +.It Va int periph_lun +LUN (currently not used on ATAPI) +.El +.Pp +A SCSI or ATAPI request is passed to the HBA through a +.Va struct scsipi_xfer . +The HBA driver has access to the following data: +.Bl -tag -width "int xs_callout" -compact -offset indent +.It Va struct callout xs_callout +callout for adapter use, usually for command timeout +.It Va int xs_control +control flags (only flags of interest for HBA drivers are described): +.Bl -tag -width XS_CTL_DISCOVERY -compact +.It Dv XS_CTL_POLL +poll in the HBA driver for request completion (most likely because interrupts +are disabled) +.It Dv XS_CTL_RESET +reset the device +.It Dv XS_CTL_DATA_UIO +xs_data points to a +.Fa struct uio +buffer +.It Dv XS_CTL_DATA_IN +data is transferred from HBA to memory +.It Dv XS_CTL_DATA_OUT +data is transferred from memory to HBA +.It Dv XS_CTL_DISCOVERY +this xfer is part of a device discovery done by the middle layer +.It Dv XS_CTL_REQSENSE +xfer is a request sense +.El +.Pp +.It Va int xs_status +status flags: +.Bl -tag -width XS_STS_PRIVATE -compact +.It Va XS_STS_DONE +xfer is done (set by +.Fn scsipi_done ) +.It Va XS_STS_PRIVATE +mask of flags reserved for HBA's use (0xf0000000) +.El +.Pp +.It Va struct scsipi_periph *xs_periph +periph doing the xfer +.It Va int timeout +command timeout, in milliseconds. +The HBA should start the timeout at the time the command is accepted +by the device. +If the timeout happens, the HBA shall terminate the command through +.Fn scsipi_done +with a XS_TIMEOUT error +.It Va struct scsipi_generic *cmd +scsipi command to execute +.It Va int cmdlen +len (in bytes) of the cmd buffer +.It Va u_char *data +data buffer (this is either a DMA or uio address) +.It Va int datalen +data length (in bytes, zero if uio) +.It Va int resid +difference between +.Fa datalen +and how much data was really transferred +.It Va scsipi_xfer_result_t error +error value returned by the HBA driver to mid-layer. +See description of +.Fn scsipi_done +for valid values +.It Va union {struct scsipi_sense_data scsi_sense; uint32_t atapi_sense;} sense +where to store sense info if +.Fa error +is +.Dv XS_SENSE +or +.Dv XS_SHORTSENSE +.It Va uint8_t status +SCSI status; checked by middle layer when +.Fa error is +.Dv XS_BUSY +(the middle layer handles +.Dv SCSI_CHECK +and +.Dv SCSI_QUEUE_FULL ) +.It Va uint8_t xs_tag_type +SCSI tag type, set to 0 if untagged command +.It Va uint8_t xs_tag_id +tag ID, used for tagged commands +.El +.Ss FUNCTIONS AND CALLBACKS +.Bl -tag -width xxxxxxxx -compact +.It Fn (*adapt_request) "struct scsipi_channel *chan" "scsipi_adapter_req_t req" "void *arg" +Used by the mid-layer to transmit a request to the adapter. +.Va req +can be one of: +.Bl -tag -width xxxxxxxx -compact +.It Dv ADAPTER_REQ_RUN_XFER +request the adapter to send a command to the device. +.Fa arg +is a pointer to the +.Va struct scsipi_xfer . +Once the xfer is complete the HBA driver shall call +.Fn scsipi_done +with updated status and error information. +.It Dv ADAPTER_REQ_GROW_RESOURCES +ask the adapter to increase resources of the channel (grow +.Va adapt_openings +or +.Va chan_openings ) +if possible. +Support of this feature is optional. +This request is called from the kernel completion thread. +.Fa arg +must be ignored. +.It Dv ADAPTER_REQ_SET_XFER_MODE +set the xfer mode for a I_T Nexus. +This will be called once all LUNs of a target have been probed. +.Fa arg +points to a +.Va struct scsipi_xfer_mode +defined as follows: +.Bl -tag -width int_xm_target -compact +.It Va int xm_target +target for I_T Nexus +.It Va int xm_mode +bitmask of device capabilities +.It Va int xm_period +sync period +.It Va int xm_offset +sync offset +.El +.Pp +.Va xm_period +and +.Va xm_offset +shall be ignored for +.Dv ADAPTER_REQ_SET_XFER_MODE . +.Va xm_mode +holds the following bits: +.Bl -tag -width xxxxxxxx -compact +.It Dv PERIPH_CAP_SYNC +ST synchronous transfers +.It Dv PERIPH_CAP_WIDE16 +ST 16 bit wide transfers +.It Dv PERIPH_CAP_WIDE32 +ST 32 bit wide transfers +.It Dv PERIPH_CAP_DT +DT transfers +.It Dv PERIPH_CAP_TQING +tagged queuing +.El +Whenever the xfer mode changes, the driver should call +.Fn scsipi_async_event +to notify the mid-layer. +.El +.Pp +.Fn adapt_request +may be called from interrupt context. +.It Fn adapt_minphys +pointer to the driver's minphys function. +If the driver can handle transfers of size +.Dv MAXPHYS , +this can point to +.Fn minphys . +.It Fn adapt_ioctl +ioctl function for the channel. +The only ioctl supported at this level is +.Dv SCBUSIORESET +for which the HBA driver shall issue a SCSI reset on the channel. +.It int Fn adapt_enable "struct device *dev" "int enable" +Disable the adapter if +.Va enable +is zero, or enable it if non-zero. +Returns 0 if operation is successful, or error from +.Pa <sys/errno.h> . +This callback is optional, and is useful mostly for hot-plug devices. +For example, this callback would power on or off +the relevant PCMCIA socket for a PCMCIA controller. +.Fn scsipi_adapter_addref +and +.Fn scsipi_adapter_delref +maintain a reference count, the enable callback is called appropriately +for the first reference and the last reference. +.It int Fn adapt_getgeom "struct scsipi_periph *periph" "struct disk_parms *params" "u_long sectors" +Optional callback, used by high-level drivers to get the fictitious geometry +used by the controller's firmware for the specified periph. +Returns 0 if successful. +See Adaptec drivers for details. +.It int Fn adapt_accesschk "struct scsipi_periph *periph" "struct scsipi_inquiry_pattern *inqbuf" +Optional callback; if present the mid-layer uses it to check if it can +attach a driver to the specified periph. +If the callback returns a non-zero value, the periph is ignored by the +.Nm +code. +This callback is used by adapters which want to drive some devices +themselves, for example hardware RAID controllers. +.It Fn scsipi_async_event "struct scsipi_channel *chan" "scsipi_async_event_t event" "void *arg" +Asynchronous event notification for the mid-layer. +.Fa event +can be one of: +.Bl -tag -width xxxxxxxx -compact +.It Dv ASYNC_EVENT_MAX_OPENINGS +set max openings for a periph. +Argument is a +.Va struct scsipi_max_openings +with at least the following members: +.Bl -tag -width xxxxxxxx -compact +.It Va int mo_target +.It Va int mo_lun +.It Va int mo_openings +.El +.Pp +Not all periphs may allow openings to increase; if not allowed the request is +silently ignored. +.It Dv ASYNC_EVENT_XFER_MODE +update the xfer mode for an I_T nexus. +Argument is a +.Va struct scsipi_xfer_mode +properly filled in. +An +.Dv ASYNC_EVENT_XFER_MODE +call with +.Dv PERIPH_CAP_TQING +set in +.Va xm_mode +is mandatory to activate tagged queuing. +.It Dv ASYNC_EVENT_RESET +channel has been reset. +No argument. +HBA drivers have to issue +.Dv ASYNC_EVENT_RESET events if they rely on the +mid-layer for SCSI CHECK CONDITION handling. +.El +.Pp +.It Fn scsipi_done "struct scsipi_xfer *xs" +shall be called by the HBA when the xfer is complete, or when it needs to +be requeued by the mid-layer. +.Va error +in the scsipi_xfer shall be set to one of the following: +.Bl -tag -width xxxxxxxx -compact +.It Dv XS_NOERROR +xfer completed without error. +.It Dv XS_SENSE +Check the returned SCSI sense for the error. +.It Dv XS_SHORTSENSE +Check the ATAPI sense for the error. +.It Dv XS_DRIVER_STUFFUP +Driver failed to perform operation. +.It Dv XS_RESOURCE_SHORTAGE +Adapter resource shortage. +The mid-layer will retry the command after some delay. +.It Dv XS_SELTIMEOUT +The device timed out while trying to send the command +.It Dv XS_TIMEOUT +The command was accepted by the device, but it didn't complete in allowed time. +.It Dv XS_BUSY +The mid-layer will check +.Va status +for additional details: +.Bl -tag -width SCSI_QUEUE_FULL -compact +.It Dv SCSI_CHECK +SCSI check condition. +The mid-layer will freeze the periph queue and issue a REQUEST SENSE command. +If the HBA supports tagged queuing, it shall remove and requeue any command +not yet accepted by the HBA (or at last make sure no more commands will +be sent to the device before the REQUEST SENSE is complete). +.It Dv SCSI_QUEUE_FULL +The mid layer will adjust the periph's openings and requeue the command. +.It Dv SCSI_BUSY +The mid-layer will requeue the xfer after delay. +.El +.It Dv XS_RESET +xfer destroyed by a reset; the mid-layer will requeue it. +.It Dv XS_REQUEUE +Ask the mid-layer to requeue this command immediately. +.El +.Pp +The adapter should not reference an +.Fa xfer +once +.Fn scsipi_done "xfer" +has been called, unless the +.Fa xfer +had +.Dv XS_CTL_POLL +set. +.Pp +.Fn scsipi_done +will call the +.Fn adapt_request +callback again only if called with +.Fa xs->error +set to +.Dv XS_NOERROR , +and +.Fa xfer +doesn't have +.Dv XS_CTL_POLL +set. +All other error conditions are handled by a kernel thread +(once the HBA's interrupt handler has returned). +.It Fn scsipi_printaddr "struct scsipi_periph *periph" +print a kernel message with the periph's name, in the form +device(controller:channel:target:lun). +.It Fn scsipi_channel_freeze "struct scsipi_channel *chan" "int count" +Freeze the specified channel (requests are queued but not sent to HBA). +The channel's freeze counter is increased by +.Fa count . +.It Fn scsipi_channel_thaw "struct scsipi_channel *chan" "int count" +Decrement the channel's freeze counter by +.Fa count +and process the queue if the counter goes to 0. +In order to preserve command ordering, HBA drivers should not call +.Fn scsipi_channel_thaw +before calling +.Fn scsipi_done +for all commands in the HBA's queue which need to be requeued. +.It Fn scsipi_periph_timed_thaw "void *arg" +Call +.Fn scsipi_channel_thaw "arg" "1" . +Intended to be used as +.Xr callout 9 +callback. +.It Fn scsipi_periph_freeze "struct scsipi_periph *periph" "int count" +.It Fn scsipi_periph_thaw "struct scsipi_periph *periph" +.It Fn scsipi_periph_timed_thaw "void *arg" +Same as the channel counterparts, but only for one specific peripheral. +.It Fn scsipi_target_detach "struct scsipi_channel *chan" "int target" "int lun" "int flags" +detach the periph associated with this I_T_L nexus. +Both +.Fa target +and +.Fa lun +may be wildcarded using the magic value -1. +.Fa flags +is passed to +.Fn config_detach "" +\&. +Returns 0 if successful, or error code if a device couldn't be removed. +.It Fn scsipi_thread_call_callback "struct scsipi_channel *chan" "void (*callback)(struct scsipi_channel *, void *)" "void *arg" +.Fn callback +will be called with +.Fa chan +and +.Fa arg +as arguments, from the channel completion thread. +The callback is run at +.Dv IPL_BIO +with the channel lock held. +.Fn scsipi_thread_call_callback +will freeze the channel by one, it's up to the caller to thaw it when +appropriate. +Returns 0 if the callback was properly recorded, or EBUSY if the +channel has already a callback pending. +.El +.Sh FILES +.Bl -tag -width sys/dev/atapiconf.h +.It Pa sys/dev/scsiconf.h +header file for use by SCSI HBA drivers +.It Pa sys/dev/atapiconf.h +header file for use by ATAPI HBA drivers +.El +.Pp +Both header files include +.Pa sys/dev/scsipiconf.h +which contains most structure definitions, function prototypes and macros. +.Sh EXAMPLES +The best examples are existing HBA drivers. +Most of them sit in the +.Pa sys/dev/ic +directory. +.Sh HISTORY +The +.Nm +interface appeared in +.Nx 1.6 . +.Sh AUTHORS +.An -nosplit +The +.Nm +interface was designed and implemented by +.An Jason R. Thorpe . +.An Manuel Bouyer +converted most drivers to the new interface. diff --git a/static/netbsd/man9/secmodel.9 b/static/netbsd/man9/secmodel.9 new file mode 100644 index 00000000..3dcb1cc6 --- /dev/null +++ b/static/netbsd/man9/secmodel.9 @@ -0,0 +1,538 @@ +.\" $NetBSD: secmodel.9,v 1.23 2022/01/26 11:48:53 andvar Exp $ +.\" +.\" Copyright (c) 2006 Elad Efrat <elad@NetBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 4, 2011 +.Dt SECMODEL 9 +.Os +.Sh NAME +.Nm secmodel +.Nd security model development guidelines +.Sh SYNOPSIS +.In secmodel/secmodel.h +.Ft int +.Fn secmodel_register "secmodel_t *sm" "const char *id" "const char *name" \ + "prop_dictionary_t behavior" "secmodel_eval_t sm_eval" \ + "secmodel_setinfo_t sm_setinfo" +.Ft int +.Fn secmodel_deregister "secmodel_t sm" +.Ft int +.Fn secmodel_eval "const char *id" "const char *what" "void *arg" "void *ret" +.Ft static int +.Fn secmodel_<model>_eval "const char *what" "void *arg" \ + "void *ret" +.Sh DESCRIPTION +.Nx +provides a complete abstraction of the underlying security model used within +the operating system through a set of +.Xr kauth 9 +scopes and actions. +It allows maintaining the traditional security model (based on a single +.Em super-user +and above-super-user restrictions known as +.Em securelevel ) +while decoupling it easily from the system. +.Pp +It is possible to modify the security model \(em either slightly or +using an entirely different model \(em by attaching/detaching +.Xr kauth 9 +listeners. +This can be done via the +.Nm +pluggable framework. +.Pp +A +.Nm +is typically implemented as a kernel +.Xr module 9 , +and can be either built-in statically or loaded dynamically at run-time. +They base their decisions on available information, either directly from +kernel, from a userspace daemon or even from a centralized network +authorization server. +.Sh DATA TYPES +The +.Nm +framework offers the following data types: +.Bl -tag -width secmodel_t +.It Fa secmodel_t +An opaque type that describes a +.Nm . +.El +.Sh FUNCTIONS +.Bl -tag -width xxxxxxx +.It Fn secmodel_register "sm" "id" "name" "behavior" "sm_eval" "sm_setinfo" +Register a security model to the +.Nm +framework and stores its description inside +.Fa sm . +.Bl -tag -width sm_setinfo +.It Fa sm +The +.Nm +description. +.It Fa id +The unique identifier of the +.Nm . +.It Fa name +The descriptive human-readable name of the +.Nm . +.It Fa behavior +(optional) a +.Xr prop_dictionary 3 +that declares the behavior of this security model, like +.Do copy credentials on fork . Dc +.It Fa sm_eval +(optional) the +.Fn secmodel_<model>_eval +callback used by a +.Nm +to register an evaluation routine that can be queried later +by another security model. +.It Fa sm_setinfo +(optional) the +.Fn secmodel_<model>_setinfo +callback used by a +.Nm +to register a routine that permits other security models to +alter the +.Nm +internals. +Currently not implemented. +.El +.It Fn secmodel_deregister "sm" +Deregister the +.Nm +described by +.Fa sm . +.It Fn secmodel_eval "id" "what" "arg" "ret" +Call the evaluation callback implemented by a security model. +The return value can be either: +.Bl -dash -compact -offset xxxxxx +.It +zero (0), when the call succeeded. +.It +positive, when the error comes directly from the +.Nm +framework. +.It +negative, when the error comes from the evaluation callback +implemented in the targeted security model. +The value is then implementation-defined. +.El +.Pp +.Bl -tag -width what +.It Fa id +The unique identifier of the targeted +.Nm . +.It Fa what +The query that will be passed down to the targeted +.Nm . +.It Fa arg +The arguments passed to the evaluation routine of the targeted +.Nm . +.It Fa ret +The answer of the evaluation routine. +.El +.El +.Sh RETURN VALUES +If successful, functions return 0. +Otherwise, the following error values are returned: +.Bl -tag -width [EINVAL] +.It Bq Er EEXIST +The +.Nm +is already registered. +.It Bq Er EFAULT +An invalid address or reference was passed as parameter. +.It Bq Er EINVAL +An invalid value was passed as parameter. +.It Bq Er ENOENT +The targeted +.Nm +does not exist, or it does not implement an evaluation callback. +.El +.Sh WRITING A SECURITY MODEL +Before writing a security model one should be familiar with the +.Xr kauth 9 +KPI, its limitations, requirements, and so on. +See +.Xr kauth 9 +for details. +.Pp +A security model is based on the kernel +.Xr module 9 +framework, and can be built-in statically inside kernel or +loaded dynamically at run-time. +It is composed of (code-wise) the following components: +.Bl -enum -offset indent +.It +.Xr module 9 +routines, especially a +.Fn MODULE +declaration and a +.Fn secmodel_<model>_modcmd +function used to start +.Po through Dv MODULE_CMD_INIT Pc +and stop +.Po through Dv MODULE_CMD_FINI Pc +the +.Nm . +.It +Entry routines, named +.Fn secmodel_<model>_init +and +.Fn secmodel_<model>_start , +used to initialize and start the security model, and another +function called +.Fn secmodel_<model>_stop , +to stop the security model in case the module is to be unloaded. +.It +A +.Xr sysctl 9 +setup routine for the model. +This should create an entry for the model in the +.Xr sysctl 7 +namespace, under the "security.models.<model>" hierarchy. +.Pp +All "knobs" for the model should be located under the new node, as well +as a mandatory +.Fa name +variable, indicating a descriptive human-readable +name for the model. +.It +A +.Xr sysctl 9 +teardown routine used to destroy the +.Xr sysctl 7 +tree associated with the model. +.It +If the model uses any private data inside credentials, listening on +the credentials scope, +.Dv KAUTH_SCOPE_CRED , +is required. +.It +Optionally, internal data-structures used by the model. +These must all be prefixed with "secmodel_<model>_". +.It +A set of listeners, attached to various scopes, used to enforce the policy +the model intends to implement. +.It +Finally, a security model should register itself after being +initialized using +.Fn secmodel_register , +and deregister itself before being stopped using +.Fn secmodel_deregister . +.El +.Sh EXAMPLES +Below is sample code for a +.Xr kauth 9 +network scope listener for the +.Em jenna +security model. +It is used to allow users with a user-id below 1000 to bind to reserved ports +(for example, 22/TCP): +.Bd -literal +int +secmodel_jenna_network_cb(kauth_cred_t cred, kauth_action_t action, + void *cookie, void *arg0, void *arg1, void *arg2, void *arg3) +{ + int result; + + /* Default defer. */ + result = KAUTH_RESULT_DEFER; + + switch (action) { + case KAUTH_NETWORK_BIND: + /* + * We only care about bind(2) requests to privileged + * ports. + */ + if ((u_long)arg0 == KAUTH_REQ_NETWORK_BIND_PRIVPORT) { + /* + * If the user-id is below 1000, which may + * indicate a "reserved" user-id, allow the + * request. + */ + if (kauth_cred_geteuid(cred) < 1000) + result = KAUTH_RESULT_ALLOW; + } + break; + } + + return (result); +} +.Ed +.Pp +There are two main issues, however, with that listener, that you should be +aware of when approaching to write your own security model: +.Bl -enum -offset indent +.It +.Xr kauth 9 +uses restrictive decisions: if you attach this listener on-top of an existing +security model, even if it would allow the request, it could still be denied. +.It +If you attach this listener as the only listener for the network scope, +there are many other requests that will be deferred and, eventually, +denied \(em which may not be desired. +.El +.Pp +That's why before implementing listeners, it should be clear whether they +implement an entirely new from scratch security model, or add on-top of an +existing one. +.Sh PROGRAMMING CONSIDERATIONS +There are several things you should remember when writing a security model: +.Bl -dash -offset indent +.It +Pay attention to the correctness of your +.Nm +implementation of the desired policy. +Certain rights can grant more privileges on the system than others, +like allowing calls to +.Xr chroot 2 +or mounting a file-system. +.It +All unhandled requests are denied by default. +.It +Authorization requests can not be issued when the kernel is holding any +locks. +This is a requirement from kernel code to allow designing security models +where the request should be dispatched to userspace or a different host. +.It +Private listener data \(em such as internal data structures \(em is +entirely under the responsibility of the developer. +Locking, synchronization, and garbage collection are all things that +.Xr kauth 9 +does +.Em not +take care of for you! +.El +.Ss STACKING ON AN EXISTING SECURITY MODEL +One of the shortcomings of +.Xr kauth 9 +is that it does not provide any stacking mechanism, similar to Linux Security +Modules (LSM). +This, however, is considered a feature in reducing dependency on other people's +code. +.Pp +To properly "stack" minor adjustments on-top of an existing security model, +one could use one of two approaches: +.Bl -enum +.It +Register an internal scope for the security model to be used as a +fall-back when requests are deferred. +.Pp +This requires the security model developer to add an internal scope for +every scope the model partly covers, and register the fall-back +listeners to it. +In the model's listener(s) for the scope, when a defer decision is made, the +request is passed to be authorized on the internal scope, effectively using +the fall-back security model. +.Pp +Here is example code that implements the above: +.Bd -literal +#include <secmodel/bsd44/bsd44.h> + +/* + * Internal fall-back scope for the network scope. + */ +#define JENNA_ISCOPE_NETWORK "jenna.iscope.network" +static kauth_scope_t secmodel_jenna_iscope_network; + +/* + * Jenna's entry point. Register internal scope for the network scope + * which we partly cover for fall-back authorization. + */ +void +secmodel_jenna_start(void) +{ + secmodel_jenna_iscope_network = kauth_register_scope( + JENNA_ISCOPE_NETWORK, NULL, NULL); + + kauth_listen_scope(JENNA_ISCOPE_NETWORK, + secmodel_bsd44_suser_network_cb, NULL); + kauth_listen_scope(JENNA_ISCOPE_NETWORK, + secmodel_securelevel_network_cb, NULL); +} + +/* + * Jenna sits on top of another model, effectively filtering requests. + * If it has nothing to say, it discards the request. This is a good + * example for fine-tuning a security model for a special need. + */ +int +secmodel_jenna_network_cb(kauth_cred_t cred, kauth_action_t action, + void *cookie, void *arg0, void *arg1, void *arg2, void *arg3) +{ + int result; + + /* Default defer. */ + result = KAUTH_RESULT_DEFER; + + switch (action) { + case KAUTH_NETWORK_BIND: + /* + * We only care about bind(2) requests to privileged + * ports. + */ + if ((u_long)arg0 == KAUTH_REQ_NETWORK_BIND_PRIVPORT) { + if (kauth_cred_geteuid(cred) < 1000) + result = KAUTH_RESULT_ALLOW; + } + break; + } + + /* + * If we have don't have a decision, fall-back to the bsd44 + * security model. + */ + if (result == KAUTH_RESULT_DEFER) + result = kauth_authorize_action( + secmodel_jenna_iscope_network, cred, action, + arg0, arg1, arg2, arg3); + + return (result); +} +.Ed +.It +If the above is not desired, or cannot be used for any reason, there is +always the ability to manually call the fall-back routine: +.Bd -literal +int +secmodel_jenna_network_cb(kauth_cred_t cred, kauth_action_t action, + void *cookie, void *arg0, void *arg1, void *arg2, void *arg3) +{ + int result; + + /* Default defer. */ + result = KAUTH_RESULT_DEFER; + + switch (action) { + case KAUTH_NETWORK_BIND: + /* + * We only care about bind(2) requests to privileged + * ports. + */ + if ((u_long)arg0 == KAUTH_REQ_NETWORK_BIND_PRIVPORT) { + if (kauth_cred_geteuid(cred) < 1000) + result = KAUTH_RESULT_ALLOW; + } + break; + } + + /* + * If we have don't have a decision, fall-back to the bsd44 + * security model's suser behavior. + */ + if (result == KAUTH_RESULT_DEFER) + result = secmodel_bsd44_suser_network_cb(cred, action, + cookie, arg0, arg1, arg2, arg3); + + return (result); +} +.Ed +.El +.Sh AVAILABLE SECURITY MODELS +The following is a list of security models available in the default +.Nx +distribution. +.Bl -tag -width xxxxxxxx +.It Xr secmodel_suser 9 +Implements the +.Em super-user +(root) security policy. +.It Xr secmodel_securelevel 9 +Implements the +.Em securelevel +security model. +.It Xr secmodel_extensions 9 +Implements extensions to the traditional +.Bx 4.4 +security model, like usermounts. +.It Xr secmodel_bsd44 9 +Traditional +.Nx +security model, derived from +.Bx 4.4 . +.It Xr secmodel_overlay 9 +Sample overlay security model, sitting on-top of +.Xr secmodel_bsd44 9 . +.El +.Sh CODE REFERENCES +The core of the +.Nm +implementation is in +.Pa sys/secmodel/secmodel.c . +.Pp +The header file +.In secmodel/secmodel.h +describes the public interface. +.Pp +To make it easier on developers to write new security models from scratch, +.Nx +maintains an example +.Nm +under +.Pa share/examples/secmodel/ . +.Sh SEE ALSO +.Xr kauth 9 , +.Xr module 9 , +.Xr secmodel_bsd44 9 , +.Xr secmodel_extensions 9 , +.Xr secmodel_overlay 9 , +.Xr secmodel_securelevel 9 , +.Xr secmodel_suser 9 +.Sh HISTORY +Kernel Authorization was introduced in +.Nx 4.0 +as the subsystem responsible for authorization and +credential management. +Before its introduction, there were several ways for providing resource access +control: +.Bl -dash -offset indent -compact +.It +Checking if the user in question is the super-user via +.Fn suser . +.It +Comparing the user-id against hard-coded values, often zero. +.It +Checking the system securelevel. +.El +.Pp +The problem with the above is that the interface ("can X do Y?") was +tightly coupled with the implementation ("is X Z?"). +.Xr kauth 9 +allows separating them, dispatching requests with highly detailed +context using a consistent and clear KPI. +.Pp +The +.Nm +framework was extended in +.Nx 6.0 +to implement +.Nm +registration and evaluation procedure calls. +.Sh AUTHORS +.An Elad Efrat Aq Mt elad@NetBSD.org diff --git a/static/netbsd/man9/secmodel_bsd44.9 b/static/netbsd/man9/secmodel_bsd44.9 new file mode 100644 index 00000000..ea46144a --- /dev/null +++ b/static/netbsd/man9/secmodel_bsd44.9 @@ -0,0 +1,55 @@ +.\" $NetBSD: secmodel_bsd44.9,v 1.17 2014/03/18 18:20:40 riastradh Exp $ +.\" +.\" Copyright (c) 2006 Elad Efrat <elad@NetBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 22, 2012 +.Dt SECMODEL_BSD44 9 +.Os +.Sh NAME +.Nm secmodel_bsd44 +.Nd traditional +.Nx +security model (based on +.Bx 4.4 ) +.Sh DESCRIPTION +.Nm +is the default security model in +.Nx . +It is the traditional security model based on +.Bx 4.4 , +and is composed of three separate security models: +.Xr secmodel_extensions 9 , +.Xr secmodel_securelevel 9 , +and +.Xr secmodel_suser 9 . +.Sh SEE ALSO +.Xr kauth 9 , +.Xr secmodel 9 , +.Xr secmodel_extensions 9 , +.Xr secmodel_securelevel 9 , +.Xr secmodel_suser 9 +.Sh AUTHORS +.An Elad Efrat Aq Mt elad@NetBSD.org diff --git a/static/netbsd/man9/secmodel_extensions.9 b/static/netbsd/man9/secmodel_extensions.9 new file mode 100644 index 00000000..c5cc6766 --- /dev/null +++ b/static/netbsd/man9/secmodel_extensions.9 @@ -0,0 +1,139 @@ +.\" $NetBSD: secmodel_extensions.9,v 1.7 2022/03/27 16:36:11 christos Exp $ +.\" +.\" Copyright (c) 2011 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jean-Yves Migeon <jym@NetBSD.org> +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 27, 2022 +.Dt SECMODEL_EXTENSIONS 9 +.Os +.Sh NAME +.Nm secmodel_extensions +.Nd extensions security model +.Sh DESCRIPTION +.Nm +implements extensions to the traditional security model based on +the original +.Bx 4.4 . +They can be used to grant additional privileges to ordinary users, or +enable specific security measures like curtain mode. +.Pp +The extensions are described below. +.Sh Curtain mode +When enabled, all returned objects will be filtered according to +the user-id requesting information about them, preventing users from +accessing objects they do not own. +.Pp +It affects the output of many commands, including +.Xr fstat 1 , +.Xr netstat 1 , +.Xr ps 1 , +.Xr sockstat 1 , +and +.Xr w 1 . +.Pp +This extension is enabled by setting +.Pa security.models.extensions.curtain +or +.Pa security.curtain +.Xr sysctl 7 +to a non-zero value. +.Pp +It can be enabled at any time, but cannot be disabled +anymore when the +.Em securelevel +of the system is above 0. +.Sh Non-superuser mounts +When enabled, it allows file-systems to be mounted by an ordinary user +who owns the point +.Ar node +and has at least read access to the +.Ar special +device +.Xr mount 8 +arguments. +Note that the +.Cm nosuid +and +.Cm nodev +flags must be given for non-superuser mounts. +.Pp +This extension is enabled by setting +.Pa security.models.extensions.usermount +or +.Pa vfs.generic.usermount +.Xr sysctl 7 +to a non-zero value. +.Pp +It can be disabled at any time, but cannot be enabled +anymore when the +.Em securelevel +of the system is above 0. +.Sh Non-superuser control of CPU sets +When enabled, an ordinary user is allowed to control the CPU +.Xr affinity 3 +of the processes and threads they own. +.Pp +This extension is enabled by setting +.Pa security.models.extensions.user_set_cpu_affinity +.Xr sysctl 7 +to a non-zero value. +.Pp +It can be disabled at any time, but cannot be enabled +anymore when the +.Em securelevel +of the system is above 0. +.Sh Hardlink restrictions +Prevent hardlinks to files that the user does not own or has group access +to. +.Pp +To enable user ownership checks, set the +.Xr sysctl 7 +variable +.Pa security.models.extensions.hardlink_check_uid +to a non-zero value. +.Pp +To enable group membership checks, set the +.Xr sysctl 7 +variable +.Pa security.models.extensions.hardlink_check_gid +to a non-zero value. +.Pp +These variables can be enabled anytime, but cannot be disabled +anymore when the +.Em securelevel +of the system is above 0. +.Sh SEE ALSO +.Xr affinity 3 , +.Xr sched 3 , +.Xr sysctl 7 , +.Xr kauth 9 , +.Xr secmodel 9 , +.Xr secmodel_bsd44 9 , +.Xr secmodel_securelevel 9 , +.Xr secmodel_suser 9 +.Sh AUTHORS +.An Elad Efrat Aq Mt elad@NetBSD.org diff --git a/static/netbsd/man9/secmodel_overlay.9 b/static/netbsd/man9/secmodel_overlay.9 new file mode 100644 index 00000000..451a8c42 --- /dev/null +++ b/static/netbsd/man9/secmodel_overlay.9 @@ -0,0 +1,52 @@ +.\" $NetBSD: secmodel_overlay.9,v 1.6 2014/03/18 18:20:40 riastradh Exp $ +.\" +.\" Copyright (c) 2006 Elad Efrat <elad@NetBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 15, 2006 +.Dt SECMODEL_OVERLAY 9 +.Os +.Sh NAME +.Nm secmodel_overlay +.Nd sample overlay security model implementation +.Sh SYNOPSIS +.In secmodel/overlay/overlay.h +.Sh DESCRIPTION +.Nm +is a sample implementation for an overlay security model. +It can be thought of as a +.Dq filter +for the underlying model it overlays, by default it is +.Xr secmodel_bsd44 9 , +where developers or administrators can implement custom policies using +least intrusive code changes. +.Sh CODE REFERENCES +.Pa sys/secmodel/overlay/secmodel_overlay.c +.Sh SEE ALSO +.Xr kauth 9 , +.Xr secmodel 9 , +.Xr secmodel_bsd44 9 +.Sh AUTHORS +.An Elad Efrat Aq Mt elad@NetBSD.org diff --git a/static/netbsd/man9/secmodel_securelevel.9 b/static/netbsd/man9/secmodel_securelevel.9 new file mode 100644 index 00000000..7dc580b4 --- /dev/null +++ b/static/netbsd/man9/secmodel_securelevel.9 @@ -0,0 +1,287 @@ +.\" $NetBSD: secmodel_securelevel.9,v 1.19 2019/05/18 10:21:03 alnsn Exp $ +.\" +.\" Copyright (c) 2006 Elad Efrat <elad@NetBSD.org> +.\" Copyright (c) 2000 Hugh Graham +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 18, 2019 +.Dt SECMODEL_SECURELEVEL 9 +.Os +.Sh NAME +.Nm secmodel_securelevel +.Nd securelevel security model +.Sh DESCRIPTION +The securelevel mechanism is intended to allow protecting the persistence +of code and data on the system, or a subset thereof, from modification, even +by the +.Em super-user , +by providing convenient means of +.Dq locking down +a system to a degree suited to its environment. +.Pp +The +.Em super-user +can raise the +.Em securelevel +using +.Xr sysctl 8 , +but only +.Xr init 8 +can lower it. +.Pp +Four security levels are provided: +.Bl -tag -width flag +.It \&-1 Em Permanently insecure mode +.Bl -bullet +.It +Do not raise the +.Em securelevel +on boot. +.El +.It \ 0 Em Insecure mode +.Bl -bullet +.It +The init process (PID 1) may not be traced or accessed by +.Xr ptrace 2 +or procfs. +.It +Immutable and append-only file flags may be changed by +.Xr chflags 1 +or by other means. +.It +All devices may be read or written subject to their permissions. +.It +All +.Xr gpio 4 +pins can be set and device drivers can be attached to them. +.It +On architectures that support +.Xr module 7 , +kernel modules can be loaded and unloaded. +.El +.It \ 1 Em Secure mode +.Bl -bullet +.It +All effects of +.Em securelevel +0. +.It +The +.Xr x86/kmem 4 +memory files +.Pa /dev/mem +and +.Pa /dev/kmem +may not be written to. +.It +Raw disk devices of mounted file systems are read-only. +.It +Immutable and append-only file flags may not be removed. +.It +Kernel modules may not be loaded or unloaded. +.It +Neither the +.Va net.inet.ip.sourceroute +nor the +.Va vm.user_va0_disable +.Xr sysctl 8 +variables may be changed. +.It +Adding or removing +.Xr sysctl 9 +nodes is denied. +.It +The RTC offset may not be changed. +.It +Set-id coredump settings may not be altered. +.It +Device +.Dq pass-thru +requests that may be used to perform raw disk and/or memory access are denied. +.It +The +.Em iopl +and +.Em ioperm +calls are denied. +.It +Access to unmanaged memory is denied. +.It +Only GPIO pins that have been set at +.Em securelevel +0 can be accessed. +.El +.It \ 2 Em Highly secure mode +.Bl -bullet +.It +All effects of +.Em securelevel +1. +.It +Raw disk devices are always read-only whether mounted or not. +.It +New disks may not be mounted, and existing mounts may only be downgraded +from read-write to read-only. +.It +The system clock may not be set backwards or close to overflow. +.It +Per-process coredump name may not be changed. +.It +Packet filtering and NAT rules may not be altered. +.It +CPU ucode loading is denied on platforms that support it. +.El +.El +.Pp +Highly secure mode may seem Draconian, but is intended as a last line of +defence should the +.Em super-user +account be compromised. +Its effects preclude +circumvention of file flags by direct modification of a raw disk device, +or erasure of a file system by means of +.Xr newfs 8 . +Further, it can limit the potential damage of a compromised +.Dq firewall +by prohibiting the modification of packet filter rules. +Preventing +the system clock from being set backwards aids in post-mortem analysis +and helps ensure the integrity of logs. +Precision timekeeping is not +affected because the clock may still be slowed. +.Pp +Normally, the system runs in +.Em securelevel +0 while single-user and in +.Em securelevel +1 while multi-user. +If a higher +.Em securelevel +is desired while running multi-user, +it can be set using the +.Sy securelevel +keyword in the startup script +.Pa /etc/rc.conf , +see +.Xr rc.conf 5 +for details. +Lower securelevels require the kernel to be compiled with +.Sy options INSECURE , +causing it to always default to +.Em securelevel +\-1. +.Pp +In order for this protection to be effective, the administrator +must ensure that no program that is run while the security level +is 0 or lower, nor any data or configuration file used by any such +program, can be modified while the security level is greater than +0. +This may be achieved through the careful use of the +.Dq immutable +file flag to define and protect a Trusted Computing Base (TCB) +consisting of all such programs and data, or by ensuring that all +such programs and data are on filesystems that are mounted read-only +and running at security level 2 or higher. +.Em Particular care must be taken to ensure, if relying upon +.Em security level 1 and the use of file flags, that the integrity of the +.Em TCB cannot be compromised through the use of modifications to the +.Em disklabel or access to overlapping disk partitions, including the +.Em raw partition . +.Pp +Do not overlook the fact that shell scripts (or anything else fed to an +interpreter, through any mechanism) and the kernel itself are "programs +that run while the security level is 0" and must be considered part of +the TCB. +.Pp +The following +.Xr sysctl 3 +variables are exported: +.Bl -tag -width compact +.It security.models.securelevel.securelevel +The system security level. +This level may be raised by processes with appropriate privilege. +It may only be lowered by process 1 (init). +.El +.Sh FUNCTIONS +.Nm +exposes a +.Xr secmodel_eval 9 +evaluation routine +to test whether the current +.Em securelevel +is above a certain threshold level or not. +.Pp +The parameters to +.Xr secmodel_eval 9 +are: +.Bl -tag -compact -width xxxxx +.It id +the unique identifier of +.Nm : +.Qo Dv org.netbsd.secmodel.securelevel Qc . +.It what +a string, +.Qo Dv is-securelevel-above Qc . +.It arg +a reference to an +.Dv int +representing the threshold level. +.It ret +a boolean, set by +.Nm +to +.Dv true +when the +.Em securelevel +is strictly above +the threshold level, +.Dv false +otherwise. +.El +.Sh RETURN TYPES +If successful, the evaluation returns 0 with the +.Fa ret +argument being either +.Dv true +or +.Dv false . +.Sh SEE ALSO +.Xr kauth 9 , +.Xr secmodel 9 , +.Xr secmodel_bsd44 9 , +.Xr secmodel_eval 9 +.Sh AUTHORS +.An Elad Efrat Aq Mt elad@NetBSD.org +.Sh BUGS +Systems without +.Xr sysctl 8 +behave as though they have security level \-1. +.Pp +The security level 2 restrictions relating to TCB integrity protection +should be enforced at security level 1. +Restrictions dependent upon security level but not relating to TCB +integrity protection should be selected by +.Xr sysctl 8 +settings available only at security level 0 or lower. diff --git a/static/netbsd/man9/secmodel_suser.9 b/static/netbsd/man9/secmodel_suser.9 new file mode 100644 index 00000000..7199c986 --- /dev/null +++ b/static/netbsd/man9/secmodel_suser.9 @@ -0,0 +1,92 @@ +.\" $NetBSD: secmodel_suser.9,v 1.7 2014/03/18 18:20:40 riastradh Exp $ +.\" +.\" Copyright (c) 2009 Elad Efrat <elad@NetBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 4, 2011 +.Dt SECMODEL_SUSER 9 +.Os +.Sh NAME +.Nm secmodel_suser +.Nd super-user security model +.Sh DESCRIPTION +.Nm +implements the traditional +.Em super-user +(root) as the user with effective user-id 0. +The +.Em super-user +is the host administrator, considered to have higher privileges than other +users. +.Sh FUNCTIONS +.Nm +exposes a +.Xr secmodel_eval 9 +evaluation routine +to test whether a set of credentials can be assimilated to +.Em super-user +credentials or not. +.Pp +The parameters to +.Xr secmodel_eval 9 +are: +.Bl -tag -compact -width xxxxx +.It id +the unique identifier of +.Nm : +.Qo Dv org.netbsd.secmodel.suser Qc +.It what +a string, +.Qo Dv is-root Qc . +.It arg +the +.Xr kauth 9 +credentials +.Po Fa kauth_cred_t Pc +of the caller. +.It ret +a boolean, set by +.Nm +to +.Dv true +when the credentials are equivalent to +.Em super-user , +.Dv false +otherwise. +.El +.Sh RETURN TYPES +If successful, the evaluation returns 0 with the +.Fa ret +argument being either +.Dv true +or +.Dv false . +.Sh SEE ALSO +.Xr kauth 9 , +.Xr secmodel 9 , +.Xr secmodel_bsd44 9 , +.Xr secmodel_eval 9 +.Sh AUTHORS +.An Elad Efrat Aq Mt elad@NetBSD.org diff --git a/static/netbsd/man9/select.9 b/static/netbsd/man9/select.9 new file mode 100644 index 00000000..4d70d8ca --- /dev/null +++ b/static/netbsd/man9/select.9 @@ -0,0 +1,124 @@ +.\" $NetBSD: select.9,v 1.5 2010/12/02 12:54:13 wiz Exp $ +.\" +.\" Copyright (C) 2002 Chad David <davidc@acns.ab.ca>. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +.\" DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man9/selrecord.9,v 1.2 2002/05/30 13:29:17 ru Exp $ +.\" +.\" FreeBSD: .Dd March 20, 2002 +.Dd May 13, 2008 +.Dt SELECT 9 +.Os +.Sh NAME +.Nm seldestroy , +.Nm selinit , +.Nm selrecord , +.Nm selnotify +.Nd select and poll subsystem +.Sh SYNOPSIS +.In sys/param.h +.In sys/select.h +.Ft void +.Fn seldestroy "struct selinfo *sip" +.Ft void +.Fn selinit "struct selinfo *sip" +.Ft void +.Fn selrecord "struct lwp *selector" "struct selinfo *sip" +.Ft void +.Fn selnotify "struct selinfo *sip" "int events" "long knhint" +.Sh DESCRIPTION +.Fn selinit +and +.Fn seldestroy +functions must be used to initialize and destroy the +.Va struct selinfo . +The +.Fn seldestroy +function may block. +.Pp +.Fn selrecord +and +.Fn selnotify +are used by device drivers to coordinate +with the kernel implementation of +.Xr select 2 +and +.Xr poll 2 . +Each object that can be polled contains a +.Dv selinfo +record. +Device drivers provide locking for the +.Dv selinfo +record. +.Pp +.Fn selrecord +records that the calling thread is interested in events related to a given +object. +.Fn selrecord +should only be called when the poll routine determines that the object +is not ready for I/O: there are no events of interest pending. +The check for pending I/O and call to +.Fn selrecord +must be atomic. +Atomicity can be provided by holding the object's lock across the test +and call to +.Fn selrecord . +For non-MPSAFE drivers, the global +.Dv kernel_lock +is enough to provide atomicity. +.Pp +.Fn selnotify +is called by the underlying object handling code in order to notify any waiting +threads that an event of interest has occurred. +The same lock held across the poll method and call to +.Fn selrecord +must be held across the call to +.Fn selnotify . +The lock prevents an event of interest being signalled while a thread is +in the process of recording its interest. +.Pp +The +.Fa events +indicates which event happen. +Zero may be used if unknown. +.Pp +.Fn selnotify +also calls +.Fn KNOTE +passing +.Va knhint +as an argument. +.Sh CODE REFERENCES +The core of the select and poll subsystem implementation is in +.Pa sys/kern/sys_select.c . +Data structures and function prototypes are located in +.Pa sys/sys/select.h , +.Pa sys/sys/poll.h +and +.Pa sys/sys/selinfo.h . +.Sh SEE ALSO +.Xr poll 2 , +.Xr select 2 , +.Xr knote 9 diff --git a/static/netbsd/man9/setbit.9 b/static/netbsd/man9/setbit.9 new file mode 100644 index 00000000..3869de8f --- /dev/null +++ b/static/netbsd/man9/setbit.9 @@ -0,0 +1,83 @@ +.\" $NetBSD: setbit.9,v 1.3 2012/12/04 18:03:37 christos Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 4, 2012 +.Dt SETBIT 9 +.Os +.Sh NAME +.Nm setbit +.Nd macros related to bitmaps +.Sh SYNOPSIS +.In sys/param.h +.Ft void +.Fn setbit "array" "x" +.Ft void +.Fn clrbit "array" "x" +.Ft int +.Fn isset "array" "x" +.Ft int +.Fn isclr "array" "x" +.Sh DESCRIPTION +The +.Nm +family of macros operate with bitmaps, also known as bit arrays. +.Pp +In a nutshell, +.Fn setbit +sets the bit +.Fa x +in +.Fa array , +.Fn clrbit +clears it, +.Fn isset +tests whether +.Fa x +is set, and +.Fn isclr +returns 1 if +.Fa x +is not set. +.Sh EXAMPLES +The following example declares a buffer of 10 chars, +treating it as an array of 80 bits: +.Bd -literal -offset indent +char buf[10]; + +\&... + +setbit(buf, 12); /* set the fifth bit in the second byte */ +.Ed +.Sh SEE ALSO +.Xr bitmap 3 , +.Xr bitstring 3 +.Sh CAVEATS +The number of valid bits in a given array is assumed to be multiple of +.Dv CHAR_BIT , +the number of bits for smallest object that is not a bit-field. diff --git a/static/netbsd/man9/setjmp.9 b/static/netbsd/man9/setjmp.9 new file mode 100644 index 00000000..03388521 --- /dev/null +++ b/static/netbsd/man9/setjmp.9 @@ -0,0 +1,69 @@ +.\" $NetBSD: setjmp.9,v 1.4 2008/04/30 13:10:58 martin Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 23, 2002 +.Dt SETJMP 9 +.Os +.Sh NAME +.Nm setjmp , +.Nm longjmp +.Nd non-local jumps +.Sh SYNOPSIS +.In machine/types.h +.In sys/systm.h +.Ft int +.Fn setjmp "label_t *label" +.Ft void +.Fn longjmp "label_t *label" +.Sh DESCRIPTION +The +.Fn setjmp +function saves its calling environment in +.Fa label . +It returns zero on success. +The +.Fn longjmp +function restores the environment saved by the most recent +invocation of +.Fn setjmp . +It returns so that kernel execution continues as if +the corresponding invocation of the +.Fn setjmp +had just returned. +.Pp +.Fn setjmp +and +.Fn longjmp +are a machine-independent interface for machine-dependent +implementations. +.Pp +These functions are primarily used by +.Xr ddb 4 . +.Sh SEE ALSO +.Xr ddb 4 diff --git a/static/netbsd/man9/shutdownhook_establish.9 b/static/netbsd/man9/shutdownhook_establish.9 new file mode 100644 index 00000000..6f0256f9 --- /dev/null +++ b/static/netbsd/man9/shutdownhook_establish.9 @@ -0,0 +1,100 @@ +.\" $NetBSD: shutdownhook_establish.9,v 1.11 2024/09/07 19:13:29 rillig Exp $ +.\" +.\" Copyright (c) 1994 Christopher G. Demetriou +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the +.\" NetBSD Project. See https://www.NetBSD.org/ for +.\" information about NetBSD. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" <<Id: LICENSE,v 1.2 2000/06/14 15:57:33 cgd Exp>> +.\" +.Dd May 14, 2009 +.Dt SHUTDOWNHOOK_ESTABLISH 9 +.Os +.Sh NAME +.Nm shutdownhook_establish , +.Nm shutdownhook_disestablish +.Nd add or remove a shutdown hook +.Sh SYNOPSIS +.Ft void * +.Fn shutdownhook_establish "void (*fn)(void *)" "void *arg" +.Ft void +.Fn shutdownhook_disestablish "void *cookie" +.Sh DESCRIPTION +.Em The +.Nm +.Em API is deprecated. +.Pp +The +.Fn shutdownhook_establish +function adds +.Fa fn +to the list of hooks invoked by +.Xr doshutdownhooks 9 +at shutdown. +When invoked, the hook function +.Fa fn +will be passed +.Fa arg +as its only argument. +.Pp +The +.Fn shutdownhook_disestablish +function removes the hook described by the opaque pointer +.Fa cookie +from the list of hooks to be invoked at shutdown. +If +.Fa cookie +is invalid, the result of +.Fn shutdownhook_disestablish +is undefined. +.Pp +Shutdown hooks should be used to perform one-time activities +that must happen immediately before the kernel exits. +Because of the environment in which they are run, shutdown hooks cannot +rely on many system services (including file systems, and timeouts +and other interrupt-driven services), or even basic system +integrity (because the system could be rebooting after a crash). +.Sh RETURN VALUES +If successful, +.Fn shutdownhook_establish +returns an opaque pointer describing the newly-established +shutdown hook. +Otherwise, it returns NULL. +.Sh EXAMPLES +It may be appropriate to use a shutdown hook to +disable a device that does direct memory access, so that +the device will not try to access memory while the system +is rebooting. +.Pp +It may be appropriate to use a shutdown hook to +inform watchdog timer hardware that the operating system +is no longer running. +.Sh SEE ALSO +.Xr doshutdownhooks 9 +.Sh BUGS +The names are clumsy, at best. diff --git a/static/netbsd/man9/signal.9 b/static/netbsd/man9/signal.9 new file mode 100644 index 00000000..d404e084 --- /dev/null +++ b/static/netbsd/man9/signal.9 @@ -0,0 +1,507 @@ +.\" $NetBSD: signal.9,v 1.24 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright (c) 1996, 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Paul Kranenburg and Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 29, 2010 +.Dt SIGNAL 9 +.Os +.Sh NAME +.Nm signal , +.Nm siginit , +.Nm sigactsinit , +.Nm sigactsunshare , +.Nm sigactsfree , +.Nm execsigs , +.Nm sigaction1 , +.Nm sigprocmask1 , +.Nm sigpending1 , +.Nm sigsuspend1 , +.Nm sigaltstack1 , +.Nm pgsignal , +.Nm kpgsignal , +.Nm psignal , +.Nm kpsignal , +.Nm issignal , +.Nm postsig , +.Nm killproc , +.Nm sigexit , +.Nm trapsignal , +.Nm sendsig , +.Nm sigcode , +.Nm sigtramp +.Nd software signal facilities +.Sh SYNOPSIS +.In sys/signal.h +.In sys/signalvar.h +.Ft void +.Fn siginit "struct proc *p" +.Ft void +.Fn sigactsinit "struct proc *pp" "int share" +.Ft void +.Fn sigactsunshare "struct proc *p" +.Ft void +.Fn sigactsfree "struct proc *p" +.Ft void +.Fn execsigs "struct proc *p" +.Ft int +.Fn sigaction1 "struct lwp *l" "int signum" "const struct sigaction *nsa" \ + "struct sigaction *osa" "void *tramp" "int vers" +.Ft int +.Fn sigprocmask1 "struct lwp *l" "int how" "const sigset_t *nss" \ + "sigset_t *oss" +.Ft void +.Fn sigpending1 "struct lwp *l" "sigset_t *ss" +.Ft int +.Fn sigsuspend1 "struct lwp *l" "const sigset_t *ss" +.Ft int +.Fn sigaltstack1 "struct lwp *l" "const struct sigaltstack *nss" \ + "struct sigaltstack *oss" +.Ft void +.Fn pgsignal "struct pgrp *pgrp" "int signum" "int checkctty" +.Ft void +.Fn kpgsignal "struct pgrp *pgrp" "ksiginfo_t *ks" "void *data" "int checkctty" +.Ft void +.Fn psignal "struct proc *p" "int signum" +.Ft void +.Fn kpsignal "struct proc *p" "ksiginfo_t *ks" "void *data" +.Ft int +.Fn issignal "struct lwp *l" +.Ft void +.Fn postsig "int signum" +.Ft void +.Fn killproc "struct proc *p" "const char *why" +.Ft void +.Fn sigexit "struct lwp *l" "int signum" +.Ft void +.Fn trapsignal "struct lwp *l" "const ksiginfo_t *ks" +.Ft void +.Fn sendsig "const ksiginfo_t *ks" "const sigset_t *mask" +.Sh DESCRIPTION +The system defines a set of signals that may be delivered to a process. +These functions implement the kernel portion of the signal facility. +.Pp +Signal numbers used throughout the kernel signal facilities should +always be within the range of +.Bq 1- Ns NSIG . +.Pp +Most of the kernel's signal infrastructure is implemented in +machine-independent code. +Machine-dependent code provides support for invoking a process's +signal handler, restoring context when the signal handler returns, +generating signals when hardware traps occur, triggering the delivery +of signals when a process is about to return from the kernel to userspace. +.Pp +The signal state for a process is contained in +.Fa struct sigctx . +This includes the list of signals with delivery pending, +information about the signal handler stack, the signal mask, and the +address of the signal trampoline. +.Pp +The registered signal handlers for a process are recorded in +.Fa struct sigacts . +This structure may be shared by multiple processes. +.Pp +The kernel's signal facilities are implemented by the following +functions: +.Bl -tag -width XXXXX +.It Fn siginit "p" +.Pp +This function initializes the signal state of +.Va proc0 +to the system default. +This signal state is then inherited by +.Xr init 8 +when it is started by the kernel. +.It Fn sigactsinit "pp" "share" +.Pp +This function creates an initial +.Fa struct sigacts +for the process +.Fa pp . +If the +.Fa share +argument is non-zero, then +.Fa pp +shares the +.Fa struct sigacts +by holding a reference. +Otherwise, +.Fa pp +receives a new +.Fa struct sigacts +which is copied from the parent. +.It Fn sigactsunshare "p" +.Pp +This function causes the process +.Fa p +to no longer share its +.Fa struct sigacts +The current state of the signal actions is maintained in the new copy. +.It Fn sigactsfree "p" +.Pp +This function decrements the reference count on the +.Fa struct sigacts +of process +.Fa p . +If the reference count reaches zero, the +.Fa struct sigacts +is freed. +.It Fn execsigs "p" +.Pp +This function is used to reset the signal state of the process +.Fa p +to the system defaults when the process execs a new program image. +.It Fn sigaction1 "l" "signum" "nsa" "osa" "tramp" "vers" +.Pp +This function implements the +.Xr sigaction 2 +system call. +The +.Fa tramp +and +.Fa vers +arguments provide support for userspace signal trampolines. +Trampoline version 0 is reserved for the legacy kernel-provided +signal trampoline; +.Fa tramp +must be +.Dv NULL +in this case. +Otherwise, +.Fa vers +specifies the ABI of the trampoline specified by +.Fa tramp . +The signal trampoline ABI is machine-dependent, and must be coordinated +with the +.Fn sendsig +function. +.It Fn sigprocmask1 "l" "how" "nss" "oss" +.Pp +This function implements the +.Xr sigprocmask 2 +system call. +.It Fn sigpending1 "l" "ss" +.Pp +This function implements the +.Xr sigpending 2 +system call. +.It Fn sigsuspend1 "l" "ss" +.Pp +This function implements the +.Xr sigsuspend 2 +system call. +.It Fn sigaltstack1 "l" "nss" "oss" +.Pp +This function implements the +.Xr sigaltstack 2 +system call. +.It Fn pgsignal "pgrp" "signum" "checkctty" +.Pp +This is a wrapper function for +.Fn kpgsignal +which is described below. +.It Fn kpgsignal "pgrp" "ks" "data" "checkctty" +.Pp +Schedule the signal +.Fa ks->ksi_signo +to be delivered to all members of the process group +.Fa pgrp . +If +.Fa checkctty +is non-zero, the signal is only sent to processes which have a +controlling terminal. +The +.Fa data +argument and the complete signal scheduling semantics are described in the +.Fn kpsignal +function below. +.It Fn trapsignal "l" "ks" +.Pp +Sends the signal +.Fa ks->ksi_signo +caused by a hardware trap to the current process. +.\" +.\" XXX: Check for reality in 2010. +.\" +.\" This function is meant to be called by machine-dependent trap handling +.\" code, through the +.\" .Dv p->p_emul->e_trapsignal +.\" function pointer because some emulations define their own trapsignal +.\" functions that remap the signal information to what the emulation +.\" expects. +.It Fn psignal "p" "signum" +.Pp +This is a wrapper function for +.Fn kpsignal +which is described below. +.It Fn kpsignal "p" "ks" "data" +.Pp +Schedule the signal +.Fa ks->ksi_signo +to be delivered to the process +.Fa p . +The +.Fa data +argument, if not +.Dv NULL , +points to the file descriptor data that caused the +signal to be generated in the +.Li SIGIO +case. +.Pp +With a few exceptions noted below, the target process signal disposition is +updated and is marked as runnable, so further handling of the signal is done +in the context of the target process after a context switch; see +.Fn issignal +below. +Note that +.Fn kpsignal +does not by itself cause a context switch to happen. +.Pp +The target process is not marked as runnable in the following cases: +.Bl -bullet -offset indent +.It +The target process is sleeping uninterruptibly. +The signal will be noticed when the process returns from the system +call or trap. +.It +The target process is currently ignoring the signal. +.It +If a stop signal is sent to a sleeping process that takes the +default action +.Pq see Xr sigaction 2 , +the process is stopped without awakening it. +.It +SIGCONT +restarts a stopped process +.Pq or puts them back to sleep +regardless of the signal action +.Pq e.g., blocked or ignored . +.El +.Pp +If the target process is being traced, +.Fn kpsignal +behaves as if the target process were taking the default action for +.Fa signum . +This allows the tracing process to be notified of the signal. +.It Fn issignal "l" +.Pp +This function determines which signal, if any, +is to be posted to the current process. +A signal is to be posted if: +.Bl -bullet -offset indent +.It +The signal has a handler provided by the program image. +.It +The signal should cause the process to dump core and/or terminate. +.It +The signal should interrupt the current system call. +.El +.Pp +Signals which cause the process to be stopped are handled within +.Fn issignal +directly. +.Pp +.Fn issignal +should be called by machine-dependent code when returning to +userspace from a system call or other trap or interrupt by +using the following code: +.Bd -literal -offset indent +while (signum = CURSIG(curproc)) + postsig(signum); +.Ed +.Pp +.It Fn postsig "signum" +.Pp +The +.Fn postsig +function is used to invoke the action for the signal +.Fa signum +in the current process. +If the default action of a signal is to terminate the process, and the +signal does not have a registered handler, the process exits using +.Fn sigexit , +dumping a core image if necessary. +.It Fn killproc "p" "why" +.Pp +This function sends a SIGKILL signal to the specified process. +The message provided by +.Fa why +is sent to the system log and is also displayed on the process's +controlling terminal. +.It Fn sigexit "l" "signum" +.Pp +This function forces the current process to exit with the signal +.Fa signum , +generating a core file if appropriate. +No checks are made for masked or caught signals; the process always exits. +.It Fn sendsig "ks" "mask" +.Pp +This function is provided by machine-dependent code, and is used to +invoke a signal handler for the current process. +.Fn sendsig +must prepare the registers and stack of the current process to +invoke the signal handler stored in the process's +.Fa struct sigacts . +This may include switching to an alternate signal +stack specified by the process. +The previous register, stack, and signal state are stored in a +.Fa ucontext_t , +which is then copied out to the user's stack. +.Pp +The registers and stack must be set up to invoke the signal handler as +follows: +.Bd -literal -offset indent +(*handler)(int signum, siginfo_t *info, void *ctx) +.Ed +.Pp +where +.Fa signum +is the signal number, +.Fa info +contains additional signal specific information when +.Li SA_SIGINFO +is specified when setting up the signal handler. +.Fa ctx +is the pointer to +.Fa ucontext_t +on the user's stack. +The registers and stack must also arrange for the signal handler to +return to the signal trampoline. +The trampoline is then used to return to the code which was executing +when the signal was delivered using the +.Xr setcontext 2 +system call. +.Pp +For performance reasons, it is recommended that +.Fn sendsig +arrange for the signal handler to be invoked directly on architectures +where it is convenient to do so. +In this case, the trampoline is used only for the signal return path. +If it is not feasible to directly invoke the signal handler, the +trampoline is also used to invoke the handler, performing any final +set up that was not possible for +.Fn sendsig +to perform. +.Pp +.Fn sendsig +must invoke the signal trampoline with the correct ABI. +The ABI of the signal trampoline is specified on a per-signal basis in the +.Fn sigacts +structure for the process. +Trampoline version 0 is reserved for the legacy kernel-provided, +on-stack signal trampoline. +All other trampoline versions indicate a specific trampoline ABI. +This ABI is coordinated with machine-dependent code in the system +C library. +.El +.Ss SIGNAL TRAMPOLINE +The signal trampoline is a special piece of code which provides +support for invoking the signal handlers for a process. +The trampoline is used to return from the signal handler back to the +code which was executing when the signal was delivered, and is also used +to invoke the handler itself on architectures where it is not feasible to +have the kernel invoke the handler directly. +.Pp +In traditional +.Ux +systems, the signal trampoline, also referred to as the +.Dq sigcode , +is provided by the kernel and copied to the top of the user's +stack when a new process is created or a new program image is +exec'd. +Starting in +.Nx 2.0 , +the signal trampoline is provided by the system C library. +This allows for more flexibility when the signal facility is extended, +makes dealing with signals easier in debuggers, such as +.Xr gdb 1 , +and may also enhance system security by allowing the kernel to +disallow execution of code on the stack. +.Pp +The signal trampoline is specified on a per-signal basis. +The correct trampoline is selected automatically by the C library +when a signal handler is registered by a process. +.Pp +Signal trampolines have a special naming convention which enables +debuggers to determine the characteristics of the signal handler +and its arguments. +Trampoline functions are named like so: +.Bd -literal -offset indent +__sigtramp_<flavor>_<version> +.Ed +.Pp +where: +.Bl -tag -width versionXX +.It Aq flavor +The flavor of the signal handler. +The following flavors are valid: +.Bl -tag -width sigcontextXX +.It sigcontext +Specifies a traditional BSD-style (deprecated) signal handler with the +following signature: +.Bd -literal +void (*handler)(int signum, + int code, + struct sigcontext *scp); +.Ed +.It siginfo +Specifies a POSIX-style signal handler with the following signature: +.Bd -literal +void (*handler)(int signum, + siginfo_t *si, + void *uc); +.Ed +.Pp +Note: sigcontext style signal handlers are deprecated, and retained only +for compatibility with older binaries. +.El +.It Aq version +Specifies the ABI version of the signal trampoline. +The trampoline ABI is coordinated with the machine-dependent kernel +.Fn sendsig +function. +The trampoline version needs to be unique even across different trampoline +flavors, in order to simplify trampoline selection in the kernel. +.El +.Pp +The following is an example if a signal trampoline name which indicates +that the trampoline is used for traditional BSD-style signal handlers +and implements version 1 of the signal trampoline ABI: +.Bd -literal -offset indent +__sigtramp_sigcontext_1 +.Ed +.Pp +The current signal trampoline is: +.Bd -literal -offset indent +__sigtramp_siginfo_2 +.Ed +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr signal 7 , +.Xr condvar 9 diff --git a/static/netbsd/man9/skpc.9 b/static/netbsd/man9/skpc.9 new file mode 100644 index 00000000..2ee2ce65 --- /dev/null +++ b/static/netbsd/man9/skpc.9 @@ -0,0 +1,62 @@ +.\" $NetBSD: skpc.9,v 1.2 2011/11/01 23:17:59 wiz Exp $ +.\" +.\" Copyright (c)2011 YAMAMOTO Takashi, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ------------------------------------------------------------ +.Dd November 1, 2011 +.Dt SKPC 9 +.Os +.\" ------------------------------------------------------------ +.Sh NAME +.Nm skpc +.Nd skip a character in a byte string +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In lib/libkern/libkern.h +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn skpc \ +"u_char mask" "size_t size" "u_char *cp" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +The +.Fn skpc +function scans the byte string +.Fa cp , +whose length is +.Fa size , +until it finds the first character which isn't equal to +.Fa mask +or the string is exhausted. +.\" ------------------------------------------------------------ +.Sh RETURN VALUES +The +.Fn skpc +function returns the number of characters skipped. +.\" ------------------------------------------------------------ +.Sh HISTORY +The +.Fn skpc +function emulates a VAX instruction with the same name. diff --git a/static/netbsd/man9/sockopt.9 b/static/netbsd/man9/sockopt.9 new file mode 100644 index 00000000..21a593b2 --- /dev/null +++ b/static/netbsd/man9/sockopt.9 @@ -0,0 +1,153 @@ +.\" $NetBSD: sockopt.9,v 1.11 2018/01/04 01:42:25 christos Exp $ +.\" +.\" Copyright (c) 2008 Iain Hibbert +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 3, 2018 +.Dt SOCKOPT 9 +.Os +.Sh NAME +.Nm sockopt_init , +.Nm sockopt_destroy , +.Nm sockopt_get , +.Nm sockopt_getint , +.Nm sockopt_set , +.Nm sockopt_setint +.Nd socket options handling +.Sh SYNOPSIS +.In sys/socketvar.h +.Ft void +.Fn sockopt_init "struct sockopt *sopt" "int level" "int name" "size_t size" +.Ft void +.Fn sockopt_destroy "struct sockopt *sopt" +.Ft int +.Fn sockopt_get "struct sockopt *sopt" "void *value" "size_t size" +.Ft int +.Fn sockopt_getint "struct sockopt *sopt" "int *value" +.Ft int +.Fn sockopt_set "struct sockopt *sopt" "const void *value" "size_t size" +.Ft int +.Fn sockopt_setint "struct sockopt *sopt" "int value" +.Sh DESCRIPTION +The +.Ft sockopt +structure is used to pass a socket option and associated value: +.Bd -literal -offset indent +struct sockopt { + int sopt_level; /* option level */ + int sopt_name; /* option name */ + size_t sopt_size; /* data length */ + size_t sopt_retsize; /* returned data length */ + void * sopt_data; /* data pointer */ + uint8_t sopt_buf[sizeof(int)]; /* internal storage */ +}; +.Ed +.Pp +The internal storage is used for the common case of values up to integer +size so that memory allocation is not required and sopt_data will point +to this in that case. +.Pp +Rather than provide accessor functions, the +.Ft sockopt +structure is public and the contents are expected to be internally +consistent, but the normal practice would be to use the appropriate methods +for storage and retrieval of values where a known datatype is expected, +as the size will be verified. +.Pp +Note: a sockopt structure may only be used for a single level/name/size +combination. +If the structure is to be re-used, it must be destroyed and re-initialized +with the new values. +.Sh OPTIONS +.Bl -tag -width xxxx +.It Cd "options DIAGNOSTIC" +Kernels compiled with the +.Dv DIAGNOSTIC +option will perform basic sanity checks on socket options operations. +.El +.Sh FUNCTIONS +.Bl -tag -width xxxx +.It Fn sockopt_init "sopt" "level" "name" "size" +Initialise sockopt storage. +If +.Ar size +is given, +.Fn sockopt_init +will arrange for sopt_data to point to a buffer of +.Ar size +bytes for the sockopt value. +Where memory needs to be allocated to satisfy this, +.Fn sockopt_init +may sleep. +.It Fn sockopt_destroy "sopt" +Destroy sockopt storage, releasing any allocated memory. +.It Fn sockopt_get "sopt" "value" "size" +Copy out sockopt value. +Will return +.Er EINVAL +if an incorrect data size is given. +.It Fn sockopt_getint "sopt" "value" +Common case of get sockopt integer value. +Will return +.Er EINVAL +if sockopt does not contain an integer sized value. +.It Fn sockopt_set "sopt" "value" "size" +Copy in sockopt value. +The sockopt structure must contain a data field of +.Ar size +bytes or be previously unset, in which case a data buffer may be +allocated using +.Xr kmem_alloc 9 +with the +.Dv KM_NOSLEEP +flag which may cause +.Fn sockopt_set +to return +.Er ENOMEM . +.Pp +Note: If you need to use +.Fn sockopt_set +in a context where memory allocation may be required and you do not wish to +contemplate failure, the sockopt structure can be initialised in a more suitable +context using +.Fn sockopt_init +which will not fail. +.It Fn sockopt_setint "sopt" "value" +Common case of set sockopt integer value. +The sockopt structure must contain an int sized data field or be previously +unset, in which case the data pointer will be set to the internal storage. +.El +.Sh CODE REFERENCES +The function prototypes and sockopt structure are defined in the +.Pa sys/sys/socketvar.h +header file, and the socket options implementation is in +.Pa sys/kern/uipc_socket.c . +.Sh SEE ALSO +.Xr errno 2 , +.Xr kmem 9 +.Sh HISTORY +The socket options KPI was inspired by a similar KPI in +.Fx +and +first appeared in +.Nx 5.0 . diff --git a/static/netbsd/man9/softintr.9 b/static/netbsd/man9/softintr.9 new file mode 100644 index 00000000..2976bad0 --- /dev/null +++ b/static/netbsd/man9/softintr.9 @@ -0,0 +1,219 @@ +.\" $NetBSD: softintr.9,v 1.23 2024/09/07 19:13:29 rillig Exp $ +.\" +.\" Copyright (c) 2007, 2008 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Andrew Doran. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 2000 Christopher G. Demetriou. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the +.\" NetBSD Project. See https://www.NetBSD.org/ for +.\" information about NetBSD. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" --(license Id: LICENSE.proto,v 1.1 2000/06/13 21:40:26 cgd Exp )-- +.\" +.Dd August 3, 2009 +.Dt SOFTINT 9 +.Os +.Sh NAME +.Nm softint , +.Nm softint_establish , +.Nm softint_disestablish , +.Nm softint_schedule +.Nd machine-independent software interrupt framework +.Sh SYNOPSIS +.In sys/intr.h +.Ft void * +.Fn softint_establish "u_int flags" "void (*func)(void *)" "void *arg" +.Ft void +.Fn softint_disestablish "void *cookie" +.Ft void +.Fn softint_schedule "void *cookie" +.Sh DESCRIPTION +The software interrupt framework is designed to provide +a generic software interrupt mechanism which can be used any time a +low-priority callback is needed. +.Pp +It allows dynamic registration of software interrupts for loadable +drivers and protocol stacks, prioritization and fair queueing of software +interrupts, and allows machine-dependent optimizations to reduce cost. +.Pp +Four priority levels are provided. +In order of priority (lowest to highest) the levels are: clock, bio, +net, serial. +The names are symbolic and in isolation do not have any direct +connection with a particular kind of device activity: they are +only meant as a guide. +.Pp +The four priority levels map directly to scheduler priority +levels, and where the architecture implements +.Dq fast +software interrupts, they also map onto interrupt priorities. +The interrupt priorities are intended to be hidden from machine +independent code, which should in general use thread-safe mechanisms +to synchronize with software interrupts (for example: mutexes). +.Pp +Software interrupts run with limited machine context. +In particular, they do not possess any address space context. +They should not try to operate on user space addresses, or to use +virtual memory facilities other than those noted as interrupt +safe. +Unlike hardware interrupts, software interrupts do have thread +context. +They may block on synchronization objects, sleep, and resume +execution at a later time. +.Pp +Since software interrupts are a limited resource and run with +higher priority than most other LWPs in the system, all +block-and-resume activity by a software interrupt must be kept +short to allow further processing at that level to continue. +By extension, code running with process context must take care to +ensure that any lock that may be taken from a software interrupt +can not be held for more than a short period of time. +.Pp +The kernel does not allow software interrupts to use facilities +or perform actions that are likely to block for a significant +amount of time. +This means that it's not valid for a software interrupt to +sleep on condition variables or to wait for resources to +become available (for example, memory). +.Pp +The following is a brief description of each function in the framework: +.Bl -tag -width abcxdcc +.It Fn softint_establish flags func arg +.Pp +Register a software interrupt. +The +.Fa flags +value must contain one of the following constants, specifying +the priority level for the soft interrupt: +.Pp +.Dv SOFTINT_CLOCK , +.Dv SOFTINT_BIO , +.Dv SOFTINT_NET , +.Dv SOFTINT_SERIAL +.Pp +If the constant +.Dv SOFTINT_MPSAFE +is not logically ORed into +.Fa flags , +the global +.Dv kernel_lock +will automatically be acquired before the soft interrupt handler +is called. +.Pp +The constant +.Fa func +specifies the function to call when the soft interrupt is +executed. +The argument +.Fa arg +will be passed to this function. +.Pp +.Fn softint_establish +may block in order to allocate memory. +If successful, it returns a +.Pf non- Dv NULL +opaque value to be used as an argument to +.Fn softint_schedule +and/or +.Fn softint_disestablish . +If for some reason it does not succeed, it returns +.Dv NULL . +.It Fn softint_disestablish cookie +.Pp +Deallocate a software interrupt previously allocated +by a call to +.Fn softint_establish . +.\" XXX What happens to pending scheduled calls? +.It Fn softint_schedule cookie +.Pp +Schedule a software interrupt previously allocated +by a call to +.Fn softint_establish +to be executed as soon as that software interrupt is unblocked. +.Fn softint_schedule +can safely be called multiple times before the +callback routine is invoked. +.Pp +Soft interrupt scheduling is CPU-local. +A request to dispatch a soft interrupt will only be serviced on +the same CPU where the request was made. +The LWPs (light weight processes) dedicated to soft interrupt +processing are bound to their home CPUs, so if a soft interrupt +handler sleeps and later resumes, it will always resume on the +same CPU. +.Pp +On a system with multiple processors, multiple instances of +the same soft interrupt handler can be in flight simultaneously +(at most one per-CPU). +.El +.Sh SEE ALSO +.Xr callout 9 , +.Xr condvar 9 , +.Xr kthread 9 , +.Xr mutex 9 , +.Xr rwlock 9 , +.Xr spl 9 , +.Xr workqueue 9 +.Sh HISTORY +The +.Nx +machine-independent software interrupt framework was designed in 1997 +and was implemented by one port in +.Nx 1.3 . +However, it did not gain wider implementation until +.Nx 1.5 . +Between +.Nx 4.0 +and +.Nx 5.0 +the framework was re-implemented in a machine-independent way to +provide software interrupts with thread context. diff --git a/static/netbsd/man9/specificdata.9 b/static/netbsd/man9/specificdata.9 new file mode 100644 index 00000000..3fbd64af --- /dev/null +++ b/static/netbsd/man9/specificdata.9 @@ -0,0 +1,161 @@ +.\" $NetBSD: specificdata.9,v 1.7 2018/06/15 22:27:40 pgoyette Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 16, 2018 +.Dt SPECIFICDATA 9 +.Os +.Sh NAME +.Nm specificdata , +.Nm specificdata_domain_create , +.Nm specificdata_domain_delete , +.Nm specificdata_key_create , +.Nm specificdata_key_delete , +.Nm specificdata_init , +.Nm specificdata_fini , +.Nm specificdata_getspecific , +.Nm specificdata_getspecific_unlocked , +.Nm specificdata_setspecific , +.Nm specificdata_setspecific_nowait +.Nd manipulate arbitrary data attached to objects +.Sh SYNOPSIS +.In sys/specificdata.h +.Ft specificdata_domain_t +.Fn specificdata_domain_create +.Ft void +.Fn specificdata_domain_delete "specificdata_domain_t sd" +.Ft int +.Fn specificdata_key_create "specificdata_domain_t sd" \ +"specificdata_key_t *keyp" "specificdata_dtor_t dtor" +.Ft void +.Fn specificdata_key_delete "specificdata_domain_t sd" "specificdata_key_t key" +.Ft int +.Fn specificdata_init "specificdata_domain_t sd" "specificdata_reference *ref" +.Ft void +.Fn specificdata_fini "specificdata_domain_t sd" "specificdata_reference *ref" +.Ft "void *" +.Fn specificdata_getspecific "specificdata_domain_t sd" \ +"specificdata_reference *ref" "specificdata_key_t key" +.Ft "void *" +.Fn specificdata_getspecific_unlocked "specificdata_domain_t sd" \ +"specificdata_reference *ref" "specificdata_key_t key" +.Ft void +.Fn specificdata_setspecific "specificdata_domain_t sd" \ +"specificdata_reference *ref" "specificdata_key_t key" "void *data" +.Ft int +.Fn specificdata_setspecific_nowait "specificdata_domain_t sd" \ +"specificdata_reference *ref" "specificdata_key_t key" "void *data" +.Sh DESCRIPTION +The +.Nm +facility provides a mechanism for storing arbitrary data, identified by +an index key, within containers which exist within the objects associated +with a particular domain. +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn specificdata_domain_create +Create and initialize a new domain. +.It Fn specificdata_domain_delete sd +Deletes domain +.Fa sd . +.It Fn specificdata_key_create sd keyp dtor +Create a new key for +.Fa sd . +If the +.Fa dtor +argument is not +.Dv NULL , +it specifies a destructor which will be called when a datum associated +with the specified key is deleted from a container within the +.Fa sd . +The unique identifier of the created key is returned in +.Fa keyp . +.It Fn specificdata_key_delete sd key +Delete a key for +.Fa sd , +and delete any associated data from all containers within the domain. +.It Fn specificdata_init sd ref +Initialize the container +.Fa ref +for use in +.Fa sd . +.It Fn specificdata_fini sd ref +Destroy the container +.Fa ref , +and destroy all of the data stuffed into the container. +.It Fn specificdata_getspecific sd ref key +Retrieve the datum from the container +.Fa ref +associated with +.Fa key . +.It Fn specificdata_getspecific_unlocked sd ref key +Retrieve the datum from the container +.Fa ref +associated with +.Fa key +in a lockless manner. +Care must be taken to ensure that no other thread could cause +.Fa ref +to become invalid (i.e. point at the wrong container) by issuing a +.Fn setspecific +call or by destroying the container. +.It Fn specificdata_setspecific sd ref key data +Store +.Fa data +in the container +.Fa ref +and associate it with +.Fa key . +If a datum has previously been stored, the new value replaces the original; +the original value is not destroyed, i.e. its destructor is not invoked. +Note that there is no provision for removing a datum without replacing it. +.It Fn specificdata_setspecific_nowait sd ref key data +(Unimplemented) +.El +.Sh CODE REFERENCES +The +.Nm +functionality is implemented in +.Pa sys/kern/subr_specificdata.c . +.Pp +The header file +.In sys/sys/specificdata.h +describes the public interface. +.Sh HISTORY +The +.Nm +subsystem first appeared in +.Nx 4.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +subsystem was written by +.An Jason Thorpe Aq Mt thorpej@NetBSD.org . +This manual page was written by +.An Paul Goyette Aq Mt pgoyette@NetBSD.org . diff --git a/static/netbsd/man9/spi.9 b/static/netbsd/man9/spi.9 new file mode 100644 index 00000000..fe4a0bb4 --- /dev/null +++ b/static/netbsd/man9/spi.9 @@ -0,0 +1,171 @@ +.\" $NetBSD: spi.9,v 1.3 2025/10/10 18:36:17 brad Exp $ +.\" +.\" Copyright (c) 2019 The NetBSD Foundation +.\" All rights reserved. +.\" +.\" Written by Michael van Elst +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL WASABI SYSTEMS, INC +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 23, 2019 +.Dt SPI 9 +.Os +.Sh NAME +.Nm spi_configure , +.Nm spi_transfer , +.Nm spi_transfer_init , +.Nm spi_chunk_init , +.Nm spi_transfer_add , +.Nm spi_wait , +.Nm spi_done , +.Nm spi_send , +.Nm spi_sendv , +.Nm spi_recv , +.Nm spi_send_recv +.Nd Serial Peripheral Interface (SPI) kernel interface +.Sh SYNOPSIS +.In dev/spi/spivar.h +.Ft int +.Fo spi_configure +.Fa "struct spi_handle *sh" +.Fa "int mode" +.Fa "int speed" +.Fc +.Ft int +.Fo spi_transfer +.Fa "struct spi_handle *sh" +.Fa "struct spi_transfer *st" +.Fc +.Ft void +.Fo spi_transfer_init +.Fa "struct spi_transfer *st" +.Fc +.Ft void +.Fo spi_chunk_init +.Fa "struct spi_chunk *chunk" +.Fa "int cnt" +.Fa "const uint8_t *wptr" +.Fa "uint8_t *rptr" +.Fc +.Ft void +.Fo spi_transfer_add +.Fa "struct spi_transfer *st" +.Fa "struct spi_chunk *chunk" +.Fc +.Ft void +.Fo spi_wait +.Fa "struct spi_transfer *st" +.Fc +.Ft void +.Fo spi_done +.Fa "struct spi_transfer *st" +.Fa "int err" +.Fc +.Ft int +.Fo spi_recv +.Fa "struct spi_handle *sh" +.Fa "int cnt" +.Fa "uint8_t *data" +.Fc +.Ft int +.Fo spi_send +.Fa "struct spi_handle *sh" +.Fa "int cnt" +.Fa "const uint8_t *data" +.Fc +.Ft int +.Fo spi_sendv +.Fa "struct spi_handle *sh" +.Fa "struct iovec *iov" +.Fa "int iovcnt" +.Fc +.Ft int +.Fo spi_send_recv +.Fa "struct spi_handle *sh" +.Fa "int scnt" +.Fa "const uint8_t *snd" +.Fa "int rcnt" +.Fa "uint8_t *rcv" +.Fc +.Sh DESCRIPTION +SPI is a 4-wire synchronous full-duplex serial bus. +It is commonly used for connecting devices such as EEPROMs, +displays, and other types of integrated circuits. +The +.Nm spi +interface provides a means of communicating with SPI-connected devices. +.Sh FUNCTIONS +The following functions comprise the API provided to drivers of +SPI-connected devices. +.Pp +The +.Fa struct spi_handle +corresponding to the device is passed in the driver attachment. +.Bl -tag -width spi_transfer_init +.It Fn spi_configure "sh" "mode" "speed" +Sets mode and speed for subsequent communication with a SPI slave. +.It Fn spi_transfer "sh" "st" +Queue transfer to SPI controller. +.Fn spi_transfer +returns an errno value when the transfer couldn't be queued. +.It Fn spi_transfer_init "st" +Initialize a transfer structure. +.It Fn spi_chunk_init "chunk" "cnt" "wptr" rptr" +Initialize a chunk structure, each chunk corresponds to +a possibly bi-directional transfer where the same amount +of bytes is shifted in and out. +.It Fn spi_transfer_add "st" "chunk" +Append a chunk to transfer structure. +.It Fn spi_wait "st" +Wait for a transfer to complete. +When the transfer has failed for some reason, the field +.Va st->st_errno +is set to a non-zero value. +.It Fn spi_done "st" "err" +Called back machine-dependent backend to signal completion +of a transfer. +.El +.Pp +For simplicity there are convenience functions that combine +common operations. +These functions return an errno value when the transfer failed. +.Bl -tag -width spi_transfer_init +.It Fn spi_recv "sh" "cnt" "data" +Prepares a chunk for receiving data, queues a transfer and +waits for it to complete. +.It Fn spi_send "sh" "cnt" "data" +Prepares a chunk for sending data, queues a transfer and +waits for it to complete. +.It Fn spi_sendv "sh" "iov" "iovcnt" +Prepare and queue a scatter of chunks and wait for them to complete. +.It Fn spi_send_recv "sh" "scnt" "snd" "rcnt" "rcv" +Prepares two chunks for sending data first and then receiving +an answer, queues a transfer and waits for it to complete. +This is not a full-duplex operation. +.El +.Sh SEE ALSO +.Xr spi 4 +.Sh HISTORY +The +.Nm spi +API first appeared in +.Nx 4.0 . diff --git a/static/netbsd/man9/spl.9 b/static/netbsd/man9/spl.9 new file mode 100644 index 00000000..2bab0bc8 --- /dev/null +++ b/static/netbsd/man9/spl.9 @@ -0,0 +1,287 @@ +.\" $NetBSD: spl.9,v 1.42 2020/04/07 07:25:09 jdolecek Exp $ +.\" +.\" Copyright (c) 2000, 2001 Jason R. Thorpe. All rights reserved. +.\" Copyright (c) 1997 Michael Long. +.\" Copyright (c) 1997 Jonathan Stone. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 7, 2020 +.Dt SPL 9 +.Os +.Sh NAME +.Nm spl , +.Nm spl0 , +.Nm splhigh , +.Nm splvm , +.Nm splbio , +.Nm splnet , +.Nm spltty , +.Nm splsched , +.Nm splsoftbio , +.Nm splsoftclock , +.Nm splsoftnet , +.Nm splsoftserial , +.Nm splx +.Nd modify system interrupt priority level +.Sh SYNOPSIS +.In sys/intr.h +.Ft void +.Fn spl0 void +.Ft int +.Fn splhigh void +.Ft int +.Fn splsched void +.Ft int +.Fn splvm void +.Ft int +.Fn splbio void +.Ft int +.Fn splnet void +.Ft int +.Fn spltty void +.Ft int +.Fn splsoftbio void +.Ft int +.Fn splsoftclock void +.Ft int +.Fn splsoftserial void +.Ft int +.Fn splsoftnet void +.Ft void +.Fn splx "int s" +.Sh DESCRIPTION +These functions raise and lower the interrupt priority level. +They are used by kernel code to block interrupts in critical +sections, in order to protect data structures. +.Pp +In a multi-CPU system, these functions change the interrupt +priority level on the local CPU only. +In general, device drivers should not make use of these interfaces. +To ensure correct synchronization, device drivers should use the +.Xr condvar 9 , +.Xr mutex 9 , +and +.Xr rwlock 9 +interfaces. +.Pp +Interrupt priorities are arranged in a strict hierarchy, although +sometimes levels may be equivalent (overlap). +The hierarchy means that raising the IPL to any level will block +interrupts at that level, and at all lower levels. +The hierarchy is used to minimize data loss due to interrupts not +being serviced in a timely fashion. +.Pp +The levels may be divided into two groups: hard and soft. +Hard interrupts are generated by hardware devices. +Soft interrupts are a way of deferring hardware interrupts to do more +expensive processing at a lower interrupt priority, and are explicitly +scheduled by the higher-level interrupt handler. +Software interrupts are further described by +.Xr softint 9 . +.Pp +Note that hard interrupt handlers do not possess process (thread) context +and so it is not valid to use kernel facilities that may attempt to sleep +from a hardware interrupt. +For example, it is not possible to acquire a reader/writer lock from +a hardware interrupt. +Soft interrupt handlers possess limited process context and so may sleep +briefly in order to acquire a reader/writer lock or adaptive mutex, +but may not sleep for any other reason. +.Pp +In order of highest to lowest priority, the priority-raising functions +along with their counterpart symbolic tags are: +.Bl -tag -width splsoft +.It Fn splhigh , IPL_HIGH +.Pp +Blocks all hard and soft interrupts, including the highest level I/O +interrupts, such as interrupts from serial interfaces and the +statistics clock (if any). +It is also used for code that cannot tolerate any interrupts. +.Pp +Code running at this level may not (in general) directly access +machine independent kernel services. +For example, it is illegal to call the kernel +.Fn printf +function or to try and allocate memory. +The methods of synchronization available are: spin mutexes and +scheduling a soft interrupt. +Generally, all code run at this level must schedule additional +processing to run in a software interrupt. +.Pp +Code with thread context running at this level must not use a kernel +interface that may cause the current LWP to sleep, such as the +.Xr condvar 9 +interfaces. +.Pp +Interrupt handlers at this level cannot acquire the global kernel_lock +and so must be coded to ensure correct synchronization on multiprocessor +systems. +.It Fn splsched , IPL_SCHED +.Pp +Blocks all medium priority hardware interrupts, such as interrupts +from audio devices, and the clock interrupt. +.Pp +Interrupt handlers running at this level endure the same restrictions as +at IPL_HIGH, but may access scheduler interfaces, and so may awaken LWPs +(light weight processes) using the +.Xr condvar 9 +interfaces, and may schedule callouts using the +.Xr callout 9 +interfaces. +.Pp +Code with thread context running at this level may sleep via the +.Xr condvar 9 +interfaces, and may use other kernel facilities that could cause the +current LWP to sleep. +.It Fn splvm , IPL_VM +.Pp +Blocks hard interrupts from +.Dq low +priority hardware interrupts, such +as interrupts from network, block I/O and tty devices. +.Pp +Code running at this level endures the same restrictions as at IPL_SCHED, +but may use the deprecated +.Xr malloc 9 +or endorsed +.Xr pool_cache 9 +interfaces to allocate memory. +.Pp +The global +.Dv kernel_lock +is automatically acquired for interrupts at this level by default, +in order to +support device drivers that do not provide their own multiprocessor +synchronization. +The automatic acquisition of +.Dv kernel_lock +can be disabled for individual interrupt handlers by device drivers +if supported by subsystem, see e.g. +.Xr pci_intr_establish 9 . +.Pp +.Fn splbio , +.Fn splnet , +and +.Fn spltty +are synonyms for +.Fn splvm . +Their use is deprecated; all new code should use +.Fn splvm . +.It Fn splsoftserial , IPL_SOFTSERIAL +.Pp +Blocks soft interrupts at the IPL_SOFTSERIAL symbolic level. +.Pp +This is the first of the software levels. +Soft interrupts at this level and lower may acquire reader/writer +locks or adaptive mutexes. +.It Fn splsoftnet , IPL_SOFTNET +.Pp +Blocks soft interrupts at the IPL_SOFTNET symbolic level. +.It Fn splsoftbio , IPL_SOFTBIO +.Pp +Blocks soft interrupts at the IPL_SOFTBIO symbolic level. +.It Fn splsoftclock , IPL_SOFTCLOCK +.Pp +Blocks soft interrupts at the IPL_SOFTCLOCK symbolic level. +.Pp +This is the priority at which callbacks generated by the +.Xr callout 9 +facility runs. +.El +.Pp +One function lowers the system priority level: +.Bl -tag -width splsoft +.It Fn spl0 , IPL_NONE +.Pp +Unblocks all interrupts. +This should rarely be used directly; +.Fn splx +should be used instead. +.El +.Pp +The +.Fn splx +function restores the system priority level to the one encoded in +.Fa s , +which must be a value previously returned by one of the other +.Nm +functions. +.Sh SEE ALSO +.Xr condvar 9 , +.Xr i386/splraise 9 , +.Xr kpreempt 9 , +.Xr mutex 9 , +.Xr rwlock 9 +.Sh HISTORY +In +.Bx 4.4 , +.Fn splnet +was used to block network software interrupts. +Most device drivers used +.Fn splimp +to block hardware interrupts. +To avoid unnecessarily blocking other interrupts, in +.Nx 1.1 +a new function was added that blocks only network hardware interrupts. +For consistency with other +.Nm +functions, the old +.Fn splnet +function was renamed to +.Fn splsoftnet , +and the new function was named +.Fn splnet . +.Pp +Originally, +.Fn splsoftclock +lowered the system priority level. +During the +.Nx 1.5 +development cycle, +.Fn spllowersoftclock +was introduced and the semantics of +.Fn splsoftclock +were changed. +.Pp +The +.Fn splimp +call was removed from the kernel between +.Nx 1.5 +and +.Nx 1.6 . +The function of +.Fn splimp +was replaced by +.Fn splvm +and code which abused the semantics of +.Fn splimp +was changed to not mix interrupt priority levels. +.Pp +Between +.Nx 4.0 +and +.Nx 5.0 , +the hardware levels were reduced in number and a strict hierarchy +defined. diff --git a/static/netbsd/man9/splraiseipl.9 b/static/netbsd/man9/splraiseipl.9 new file mode 100644 index 00000000..84f39a9c --- /dev/null +++ b/static/netbsd/man9/splraiseipl.9 @@ -0,0 +1,103 @@ +.\" $NetBSD: splraiseipl.9,v 1.9 2018/02/08 09:03:23 dholland Exp $ +.\" +.\" Copyright (c)2006 YAMAMOTO Takashi, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ------------------------------------------------------------ +.Dd July 9, 2015 +.Dt SPLRAISEIPL 9 +.Os +.\" ------------------------------------------------------------ +.Sh NAME +.Nm splraiseipl +.Nd raise the system priority level +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In sys/intr.h +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn splraiseipl \ +"ipl_cookie_t icookie" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +.Fn splraiseipl +raises the system priority level to the level specified by +.Fa icookie . +.Fa icookie +should be a value returned by +.Fn makeiplcookie . +.Pp +In general, device drivers should not make use of this interface. +To ensure correct synchronization, device drivers should use the +.Xr condvar 9 , +.Xr mutex 9 , +and +.Xr rwlock 9 +interfaces. +.Pp +See the +.Xr spl 9 +manual page for a description of interrupt priority levels. +.\" ------------------------------------------------------------ +.Sh RETURN VALUES +.Fn splraiseipl +returns saved priority level which can be used for +.Fn splx . +.\" ------------------------------------------------------------ +.Sh EXAMPLES +The following two lines are functional equivalents. +.Bd -literal + s = splraiseipl(makeiplcookie(IPL_VM)); +.Ed +.Bd -literal + s = splvm(); +.Ed +.Pp +Because +.Fn makeiplcookie +can be slow and is not expected to be used in a performance critical path, +it's better to do it beforehand. +.Bd -literal + initialization_code(ipl_t ipl) + { + + ourcookie = makeiplcookie(ipl); + } + + performance_critical_code() + { + int s; + + s = splraiseipl(ourcookie); + do_something(); + splx(s); + } +.Ed +.\" ------------------------------------------------------------ +.Sh SEE ALSO +.Xr condvar 9 , +.Xr makeiplcookie 9 , +.Xr mutex 9 , +.Xr rwlock 9 , +.Xr spl 9 diff --git a/static/netbsd/man9/strlist.9 b/static/netbsd/man9/strlist.9 new file mode 100644 index 00000000..c2bd861d --- /dev/null +++ b/static/netbsd/man9/strlist.9 @@ -0,0 +1,218 @@ +.\" $NetBSD: strlist.9,v 1.3 2021/01/21 17:05:50 wiz Exp $ +.\" +.\" Copyright (c) 2021 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 20, 2021 +.Dt OFSL 9 +.Os +.Sh NAME +.Nm strlist , +.Nm strlist_next , +.Nm strlist_count , +.Nm strlist_string , +.Nm strlist_match , +.Nm strlist_index , +.Nm strlist_append +.Nd functions to interact with OpenFirmware-style string lists +.Sh SYNOPSIS +.In sys/systm.h +.Ft const char * +.Fn strlist_next "const char *sl" "size_t slsize" "size_t *cursorp" +.Ft void +.Fn strlist_count "const char *sl" "size_t slsize" +.Ft const char * +.Fn strlist_string "const char *sl" "size_t slsize" "unsigned int index" +.Ft int +.Fn strlist_match "const char *sl" "size_t slsize" "const char *str" +.Ft int +.Fn strlist_pmatch "const char *sl" "size_t slsize" "const char *pattern" +.Ft int +.Fn strlist_index "const char *sl" "size_t slsize" "const char *str" +.Ft bool +.Fn strlist_append "char **slp" "size_t *slsizep" "const char *str" +.Sh DESCRIPTION +The +.Nm +functions provide a simple way to interact with OpenFirmware +.Pq IEEE 1275 +string lists. +.Pp +An OpenFirmware string list is simply a buffer containing one or more +NUL-terminated strings concatenated together. +For example, a string list containing the strings +.Dq foo , +.Dq bar , +and +.Dq baz +would be represented in memory as: +.Bd -literal -offset indent +foo\\0bar\\0baz\\0 +.Ed +.Pp +The following functions are available: +.Bl -tag -width "xxxxx" +.It Fn strlist_next "const char *sl" "size_t slsize" "size_t *cursorp" +This function provides a way to enumerate the strings in a string list. +To enumerate a string list, initialize +.Fa cursor +to 0 and pass it by reference to +.Fn strlist_next . +Each call to +.Fn strlist_next +returns the current string and advances the cursor to the next string in +the list. +If all strings in the list have been enumerated, +.Fn strlist_next +will return +.Dv NULL . +.It Fn strlist_count "const char *sl" "size_t slsize" +Returns the number of strings in the string list. +.It Fn strlist_string "const char *sl" "size_t slsize" "unsigned int index" +Returns a pointer to the string in the string list at the specified +index or +.Dv NULL +if the index is out of range. +.It Fn strlist_match "const char *sl" "size_t slsize" "const char *str" +Returns a weighted match value if the specified string appears in +the string list. +The value returned is the number of strings in the string list +minus the index of the matched string. +For example, if a string list contains the strings +.Dq foo , +.Dq bar , +and +.Dq baz , +a match against +.Dq foo +returns 3 and a match against +.Dq baz +returns 1. +If the string does not appear in the string list, 0 is returned. +.It Fn strlist_pmatch "const char *sl" "size_t slsize" "const char *pattern" +Like +.Fn strlist_match , +but uses +.Fn pmatch +to compare strings, allowing for wildcard characters to be specified in +.Fa pattern . +.It Fn strlist_index "const char *sl" "size_t slsize" "const char *str" +Returns the index of the specified string if it appears in the +string list, or \-1 if the string does not appear in the string list. +.It Fn strlist_append "char **slp" "size_t *slsizep" "const char *str" +Appends a copy of the specified string to the stringlist. +Begin by initializing +.Fa sl +to +.Dv NULL +and +.Fa slsize +to 0. +Pass these by reference to +.Fn strlist_append . +New memory for the string list will be allocated as needed. +The resulting string list can be freed with +.Fn kmem_free . +Returns +.Dv true +if the string was successfully appended to the string list or +.Dv false +if memory allocation fails. +.El +.Sh EXAMPLES +The following shows an example of string list enumeration using +.Fn strlist_next : +.Bd -literal +void +print_stringlist(const char *sl, size_t slsize) +{ + const char *cp; + size_t cursor; + + printf("There are %u strings in the string list:\\n", + strlist_count(sl, slsize)); + for (cursor = 0; + (cp = strlist_next(sl, slsize, &cursor) != NULL; ) { + printf("\\t%s\\n", cp); + } +} +.Ed +.Pp +The following example shows a simple way to use +.Fn strlist_match : +.Bd -literal +bool +is_compatible(int phandle, const char *compat_str) +{ + char buf[128]; + int proplen; + + proplen = OF_getprop(phandle, "compatible", buf, sizeof(buf)); + return strlist_match(buf, proplen, compat_str) != 0; +} +.Ed +.Pp +The following example shows a use of +.Fn strlist_pmatch : +.Bd -literal +bool +is_pc_printer_port(const char *pnp_id_list, size_t list_size) +{ + return strlist_pmatch(pnp_id_list, list_size, "PNP04??") != 0; +} +.Ed +.Pp +The following example converts an array of strings to a string list using +.Fn strlist_append : +.Bd -literal +char * +string_array_to_string_list(const char **array, int count, + size_t *slsizep) +{ + char *sl; + size_t slsize; + int i; + + for (i = 0, sl = NULL, slsize = 0; i < count; i++) { + if (!strlist_append(&sl, &slsize, array[i])) { + kmem_free(sl, slsize); + return NULL; + } + } + + *slsizep = slsize; + return sl; +} +.Ed +.Sh SEE ALSO +.Xr kmem 9 , +.Xr pmatch 9 +.Sh HISTORY +The +.Nm +functions first appeared in +.Nx 10.0 . diff --git a/static/netbsd/man9/suspendsched.9 b/static/netbsd/man9/suspendsched.9 new file mode 100644 index 00000000..0bb9d4d0 --- /dev/null +++ b/static/netbsd/man9/suspendsched.9 @@ -0,0 +1,50 @@ +.\" $NetBSD: suspendsched.9,v 1.5 2010/04/13 18:33:44 jruoho Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 21, 2002 +.Dt SUSPENDSCHED 9 +.Os +.Sh NAME +.Nm suspendsched +.Nd suspend the scheduler +.Sh SYNOPSIS +.In sys/proc.h +.In sys/sched.h +.Ft void +.Fn suspendsched "void" +.Sh DESCRIPTION +The +.Fn suspendsched +function suspends the operation of the scheduler by stopping all +non-system processes which are on the run queue or the sleep queue. +.Pp +The +.Fn suspendsched +function must not be called with the scheduler lock held. +.\".Sh SEE ALSO diff --git a/static/netbsd/man9/sysctl.9 b/static/netbsd/man9/sysctl.9 new file mode 100644 index 00000000..5db31ef0 --- /dev/null +++ b/static/netbsd/man9/sysctl.9 @@ -0,0 +1,682 @@ +.\" $NetBSD: sysctl.9,v 1.24 2022/09/07 01:18:32 pgoyette Exp $ +.\" +.\" Copyright (c) 2004 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Andrew Brown. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 6, 2022 +.Dt SYSCTL 9 +.Os +.Sh NAME +.Nm sysctl +.Nd system variable control interfaces +.Sh SYNOPSIS +.In sys/param.h +.In sys/sysctl.h +.Pp +Primary external interfaces: +.Ft void +.Fn sysctl_init void +.Ft int +.Fn sysctl_lock "struct lwp *l" "void *oldp" "size_t savelen" +.Ft int +.Fn sysctl_dispatch "const int *name" "u_int namelen" "void *oldp" \ +"size_t *oldlenp" "const void *newp" "size_t newlen" "const int *oname" \ +"struct lwp *l" "const struct sysctlnode *rnode" +.Ft void +.Fn sysctl_unlock "struct lwp *l" +.Ft int +.Fn sysctl_createv "struct sysctllog **log" "int cflags" \ +"const struct sysctlnode **rnode" "const struct sysctlnode **cnode" \ +"int flags" "int type" "const char *namep" "const char *desc" \ +"sysctlfn func" "u_quad_t qv" "void *newp" "size_t newlen" ... +.Ft int +.Fn sysctl_destroyv "struct sysctlnode *rnode" ... +.Ft void +.Fn sysctl_free "struct sysctlnode *rnode" +.Ft void +.Fn sysctl_teardown "struct sysctllog **" +.Ft int +.Fn old_sysctl "int *name" "u_int namelen" "void *oldp" \ +"size_t *oldlenp" "void *newp" "size_t newlen" "struct lwp *l" +.Pp +Core internal functions: +.Ft int +.Fn sysctl_locate "struct lwp *l" "const int *name" "u_int namelen" \ +"const struct sysctlnode **rnode" "int *nip" +.Ft int +.Fn sysctl_lookup "const int *name" "u_int namelen" "void *oldp" \ +"size_t *oldlenp" "const void *newp" "size_t newlen" "const int *oname" \ +"struct lwp *l" "const struct sysctlnode *rnode" +.Ft int +.Fn sysctl_create "const int *name" "u_int namelen" "void *oldp" \ +"size_t *oldlenp" "const void *newp" "size_t newlen" "const int *oname" \ +"struct lwp *l" "const struct sysctlnode *rnode" +.Ft int +.Fn sysctl_destroy "const int *name" "u_int namelen" "void *oldp" \ +"size_t *oldlenp" "const void *newp" "size_t newlen" "const int *oname" \ +"struct lwp *l" "const struct sysctlnode *rnode" +.Ft int +.Fn sysctl_query "const int *name" "u_int namelen" "void *oldp" \ +"size_t *oldlenp" "const void *newp" "size_t newlen" "const int *oname" \ +"struct lwp *l" "const struct sysctlnode *rnode" +.Pp +Simple +.Dq helper +functions: +.Ft int +.Fn sysctl_needfunc "const int *name" "u_int namelen" "void *oldp" \ +"size_t *oldlenp" "const void *newp" "size_t newlen" "const int *oname" \ +"struct lwp *l" "const struct sysctlnode *rnode" +.Ft int +.Fn sysctl_notavail "const int *name" "u_int namelen" "void *oldp" \ +"size_t *oldlenp" "const void *newp" "size_t newlen" "const int *oname" \ +"struct lwp *l" "const struct sysctlnode *rnode" +.Ft int +.Fn sysctl_null "const int *name" "u_int namelen" "void *oldp" \ +"size_t *oldlenp" "const void *newp" "size_t newlen" "const int *oname" \ +"struct lwp *l" "const struct sysctlnode *rnode" +.Sh DESCRIPTION +The SYSCTL subsystem instruments a number of kernel tunables and other +data structures via a simple MIB-like interface, primarily for +consumption by userland programs, but also for use internally by the +kernel. +.Sh LOCKING +All operations on the SYSCTL tree must be protected by acquiring the +main SYSCTL lock. +The only functions that can be called when the lock is not held are +.Fn sysctl_lock , +.Fn sysctl_createv , +.Fn sysctl_destroyv , +and +.Fn old_sysctl . +All other functions require the tree to be locked. +This is to prevent other users of the tree from moving nodes around +during an add operation, or from destroying nodes or subtrees that are +actively being used. +The lock is acquired by calling +.Fn sysctl_lock +with a pointer to the process's lwp +.Fa l +.Dv ( NULL +may be passed to all functions as the lwp pointer if no lwp is +appropriate, though any changes made via +.Fn sysctl_create , +.Fn sysctl_destroy , +.Fn sysctl_lookup , +or by any helper function will be done with effective superuser +privileges). +.Pp +The +.Fa oldp +and +.Fa savelen +arguments are a pointer to and the size of the memory region the +caller will be using to collect data from SYSCTL. +These may also be +.Dv NULL +and 0, respectively. +.Pp +The memory region will be locked via +.Fn uvm_vslock +if it is a region in userspace. +The address and size of the region are recorded so that when the +SYSCTL lock is to be released via +.Fn sysctl_unlock , +only the lwp pointer +.Fa l +is required. +.Sh LOOKUPS +Once the lock has been acquired, it is typical to call +.Fn sysctl_dispatch +to handle the request. +.Fn sysctl_dispatch +will examine the contents of +.Fa name , +an array of integers at least +.Fa namelen +long, which is to be located in kernel space, in order to determine +which function to call to handle the specific request. +.Pp +The following algorithm is used by +.Fn sysctl_dispatch +to determine the function to call: +.Bl -bullet -offset indent +.It +Scan the tree using +.Fn sysctl_locate . +.It +If the node returned has a +.Dq helper +function, call it. +.It +If the requested node was found but has no function, call +.Fn sysctl_lookup . +.It +If the node was not found and +.Fa name +specifies one of +.Fn sysctl_query , +.Fn sysctl_create , +or +.Fn sysctl_destroy , +call the appropriate function. +.It +If none of these options applies and no other error was yet recorded, +return +.Er EOPNOTSUPP . +.El +The +.Fa oldp +and +.Fa oldlenp +arguments to +.Fn sysctl_dispatch , +as with all the other core functions, describe an area into which the +current or requested value may be copied. +.Fa oldp +may or may not be a pointer into userspace (as dictated by whether +.Fa l +is +.Dv NULL +or not). +.Fa oldlenp +is a +.No non- Ns Dv NULL +pointer to a size_t. +.Fa newp +and +.Fa newlen +describe an area where the new value for the request may be found; +.Fa newp +may also be a pointer into userspace. +The +.Fa oname +argument is a +.No non- Ns Dv NULL +pointer to the base of the request currently +being processed. +By simple arithmetic on +.Fa name , +.Fa namelen , +and +.Fa oname , +one can easily determine the entire original request and +.Fa namelen +values, if needed. +The +.Fa rnode +value, as passed to +.Fn sysctl_dispatch +represents the root of the tree into which the current request is to +be dispatched. +If +.Dv NULL , +the main tree will be used. +.Pp +The +.Fn sysctl_locate +function scans a tree for the node most specific to a request. +If the pointer referenced by +.Fa rnode +is not +.Dv NULL , +the tree indicated is searched, otherwise the main tree +will be used. +The address of the most relevant node will be returned via +.Fa rnode +and the number of MIB entries consumed will be returned via +.Fa nip , +if it is not +.Dv NULL . +.Pp +The +.Fn sysctl_lookup +function takes the same arguments as +.Fn sysctl_dispatch +with the caveat that the value for +.Fa namelen +must be zero in order to indicate that the node referenced by the +.Fa rnode +argument is the one to which the lookup is being applied. +.Sh CREATION AND DESTRUCTION OF NODES +New nodes are created and destroyed by the +.Fn sysctl_create +and +.Fn sysctl_destroy +functions. +These functions take the same arguments as +.Fn sysctl_dispatch +with the additional requirement that the +.Fa namelen +argument must be 1 and the +.Fa name +argument must point to an integer valued either +.Dv CTL_CREATE +or +.Dv CTL_CREATESYM +when creating a new node, or +.Dv CTL_DESTROY +when destroying +a node. +.Pp +The +.Fa newp +and +.Fa newlen +arguments should point to a copy of the node to be created or +destroyed. +If the create or destroy operation was successful, a copy of the node +created or destroyed will be placed in the space indicated by +.Fa oldp +and +.Fa oldlenp . +If the create operation fails because of a conflict with an existing +node, a copy of that node will be returned instead. +.Pp +In order to facilitate the creation and destruction of nodes from a +given tree by kernel subsystems, the functions +.Fn sysctl_createv +and +.Fn sysctl_destroyv +are provided. +These functions take care of the overhead of filling in the contents +of the create or destroy request, dealing with locking, locating the +appropriate parent node, etc. +.Pp +The arguments to +.Fn sysctl_createv +are used to construct the new node. +If the +.Fa log +argument is not +.Dv NULL , +a +.Em sysctllog +structure will be allocated and the pointer referenced +will be changed to address it. +The same log may be used for any number of nodes, provided they are +all inserted into the same tree. +This allows for a series of nodes to be created and later removed from +the tree in a single transaction (via +.Fn sysctl_teardown ) +without the need for any record +keeping on the caller's part. +.Pp +The +.Fa cflags +argument is currently unused and must be zero. +The +.Fa rnode +argument must either be +.Dv NULL +or a valid pointer to a reference to the root of the tree into which +the new node must be placed. +If it is +.Dv NULL , +the main tree will be used. +It is illegal for +.Fa rnode +to refer to a +.Dv NULL +pointer. +If the +.Fa cnode +argument is not +.Dv NULL , +on return it will be adjusted to point to the address of the new node. +.Pp +The +.Fa flags +and +.Fa type +arguments are combined into the +.Fa sysctl_flags +field, and the current value for +.Dv SYSCTL_VERSION +is added in. +The following types are defined: +.Bl -tag -width ".Dv CTLTYPE_STRING " -offset indent +.It Dv CTLTYPE_NODE +A node intended to be a parent for other nodes. +.It Dv CTLTYPE_INT +A signed integer. +.It Dv CTLTYPE_STRING +A NUL-terminated string. +.It Dv CTLTYPE_QUAD +An unsigned 64-bit integer. +.It Dv CTLTYPE_STRUCT +A structure. +.It Dv CTLTYPE_BOOL +A boolean. +.El +.Pp +The +.Fa namep +argument is copied into the +.Fa sysctl_name +field and must be less than +.Dv SYSCTL_NAMELEN +characters in length. +The string indicated by +.Fa desc +will be copied if the +.Dv CTLFLAG_OWNDESC +flag is set, and will be used as the node's description. +.Pp +Two additional remarks: +.Bl -enum -offset indent +.It +The +.Dv CTLFLAG_PERMANENT +flag can only be set from SYSCTL setup routines (see +.Sx SETUP FUNCTIONS ) +as called by +.Fn sysctl_init . +.It +If +.Fn sysctl_destroyv +attempts to delete a node that does not own its own description (and +is not marked as permanent), but the deletion fails, the description +will be copied and +.Fn sysctl_destroyv +will set the +.Dv CTLFLAG_OWNDESC +flag. +.El +.Pp +The +.Fa func +argument is the name of a +.Dq helper +function (see +.Sx HELPER FUNCTIONS AND MACROS ) . +If the +.Dv CTLFLAG_IMMEDIATE +flag is set, the +.Fa qv +argument will be interpreted as the initial value for the new +.Dq bool , +.Dq int +or +.Dq quad +node. +This flag does not apply to any other type of node. +The +.Fa newp +and +.Fa newlen +arguments describe the data external to SYSCTL that is to be +instrumented. +One of +.Fa func , +.Fa qv +and the +.Dv CTLFLAG_IMMEDIATE +flag, or +.Fa newp +and +.Fa newlen +must be given for nodes that instrument data, otherwise an error is +returned. +.Pp +The remaining arguments are a list of integers specifying the path +through the MIB to the node being created. +The list must be terminated by the +.Dv CTL_EOL +value. +The penultimate value in the list may be +.Dv CTL_CREATE +if a dynamic MIB entry is to be made for this node. +.Fn sysctl_createv +specifically does not support +.Dv CTL_CREATESYM , +since setup routines are +expected to be able to use the in-kernel +.Xr ksyms 4 +interface to discover the location of the data to be instrumented. +If the node to be created matches a node that already exists, a return +code of 0 is given, indicating success. +.Pp +When using +.Fn sysctl_destroyv +to destroy a given node, the +.Fa rnode +argument, if not +.Dv NULL , +is taken to be the root of the tree from which +the node is to be destroyed, otherwise the main tree is used. +The rest of the arguments are a list of integers specifying the path +through the MIB to the node being destroyed. +If the node being destroyed does not exist, a successful return code +is given. +Nodes marked with the +.Dv CTLFLAG_PERMANENT +flag cannot be destroyed. +.Sh HELPER FUNCTIONS AND MACROS +Helper functions are invoked with the same common argument set as +.Fn sysctl_dispatch +except that the +.Fa rnode +argument will never be +.Dv NULL . +It will be set to point to the node that corresponds most closely to +the current request. +Helpers are forbidden from modifying the node they are passed; they +should instead copy the structure if changes are required in order to +effect access control or other checks. +The +.Dq helper +prototype and function that needs to ensure that a newly assigned +value is within a certain range (presuming external data) would look +like the following: +.Pp +.Bd -literal -offset indent -compact +static int sysctl_helper(SYSCTLFN_PROTO); + +static int +sysctl_helper(SYSCTLFN_ARGS) +{ + struct sysctlnode node; + int t, error; + + t = *(int *)rnode->sysctl_data; + + node = *rnode; + node.sysctl_data = &t; + error = sysctl_lookup(SYSCTLFN_CALL(&node)); + if (error || newp == NULL) + return (error); + + if (t < 0 || t > 20) + return (EINVAL); + + *(int *)rnode->sysctl_data = t; + return (0); +} +.Ed +.Pp +The use of the +.Dv SYSCTLFN_PROTO , +.Dv SYSCTLFN_ARGS, and +.Dv SYSCTLFN_CALL + macros ensure that all arguments are passed properly. +The single argument to the +.Dv SYSCTLFN_CALL +macro is the pointer to the node being examined. +.Pp +Three basic helper functions are available for use. +.Fn sysctl_needfunc +will emit a warning to the system console whenever it is invoked and +provides a simplistic read-only interface to the given node. +.Fn sysctl_notavail +will forward +.Dq queries +to +.Fn sysctl_query +so that subtrees can be discovered, but will return +.Er EOPNOTSUPP +for any other condition. +.Fn sysctl_null +specifically ignores any arguments given, sets the value indicated by +.Fa oldlenp +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 (and during loadable module +initialization), a proper +.Dq setup +function must be used. +Setup functions are declared using the +.Dv SYSCTL_SETUP +macro, which takes the name of the function and a short string +description of the function as arguments. +.Po +See the +.Dv SYSCTL_DEBUG_SETUP +kernel configuration in +.Xr options 4 . +.Pc +.Pp +The address of the function is added to a list of functions that +.Fn sysctl_init +traverses during initialization. +For loadable kernel modules (see +.Xr module 9 ) , +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 +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. +Emulations that require use of a main tree but with some nodes changed +to suit their own purposes can arrange to overlay a sparse private +tree onto their main tree by making the +.Fa e_sysctlovly +member of their struct emul definition point to the overlaid tree. +.Pp +Setup functions should take care to create all nodes from the root +down to the subtree they are creating, since the order in which setup +functions are called is arbitrary (the order in which setup functions +are called is only determined by the ordering of the object files as +passed to the linker when the kernel is built). +.Sh MISCELLANEOUS FUNCTIONS +.Fn sysctl_init +is called early in the kernel bootstrap process. +It initializes the SYSCTL lock, calls all the registered setup +functions, and marks the tree as permanent. +.Pp +.Fn sysctl_free +will unconditionally delete any and all nodes below the given node. +Its intended use is for the deletion of entire trees, not subtrees. +If a subtree is to be removed, +.Fn sysctl_destroy +or +.Fn sysctl_destroyv +should be used to ensure that nodes not owned by the sub-system being +deactivated are not mistakenly destroyed. +The SYSCTL lock must be held when calling this function. +.Pp +.Fn sysctl_teardown +unwinds a +.Em sysctllog +and deletes the nodes in the opposite order in +which they were created. +.Pp +.Fn old_sysctl +provides an interface similar to the old SYSCTL implementation, with +the exception that access checks on a per-node basis are performed if +the +.Fa l +argument is +.No non- Ns Dv NULL . +If called with a +.Dv NULL +argument, the values for +.Fa newp +and +.Fa oldp +are interpreted as kernel addresses, and access is performed as for +the superuser. +.Sh NOTES +It is expected that nodes will be added to (or removed from) the tree +during the following stages of a machine's lifetime: +.Pp +.Bl -bullet -compact +.It +initialization \(em when the kernel is booting +.It +autoconfiguration \(em when devices are being probed at boot time +.It +.Dq plug and play +device attachment \(em when a PC-Card, USB, or other device is plugged +in or attached +.It +module initialization \(em when a module is being loaded +.It +.Dq run-time +\(em when a process creates a node via the +.Xr sysctl 3 +interface +.El +.Pp +Nodes marked with +.Dv CTLFLAG_PERMANENT +can only be added to a tree during the first or initialization phase, +and can never be removed. +The initialization phase terminates when the main tree's root is +marked with the +.Dv CTLFLAG_PERMANENT +flag. +Once the main tree is marked in this manner, no nodes can be added to +any tree that is marked with +.Dv CTLFLAG_READONLY +at its root, and no nodes can be added at all if the main tree's root +is so marked. +.Pp +Nodes added by device drivers, modules, and at device insertion time can +be added to (and removed from) +.Dq read-only +parent nodes. +.Pp +Nodes created by processes can only be added to +.Dq writable +parent nodes. +See +.Xr sysctl 3 +for a description of the flags that are allowed to be used by +when creating nodes. +.Sh SEE ALSO +.Xr sysctl 3 +.Sh HISTORY +The dynamic SYSCTL implementation first appeared in +.Nx 2.0 . +.Sh AUTHORS +.An Andrew Brown +.Aq atatat@NetBSD.org +designed and implemented the dynamic SYSCTL implementation. diff --git a/static/netbsd/man9/sysmon_envsys.9 b/static/netbsd/man9/sysmon_envsys.9 new file mode 100644 index 00000000..daa201c2 --- /dev/null +++ b/static/netbsd/man9/sysmon_envsys.9 @@ -0,0 +1,722 @@ +.\" $NetBSD: sysmon_envsys.9,v 1.46 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright (c) 2007, 2008 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Juan Romero Pardines. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 13, 2012 +.Dt SYSMON_ENVSYS 9 +.Os +.Sh NAME +.Nm sysmon_envsys +.Nd kernel part of the envsys 2 framework +.Sh SYNOPSIS +.In dev/sysmon/sysmonvar.h +.Ft struct sysmon_envsys * +.Fn sysmon_envsys_create "void" +.Ft void +.Fn sysmon_envsys_destroy "struct sysmon_envsys *" +.Ft int +.Fn sysmon_envsys_register "struct sysmon_envsys *" +.Ft void +.Fn sysmon_envsys_unregister "struct sysmon_envsys *" +.Ft int +.Fn sysmon_envsys_sensor_attach "struct sysmon_envsys *" "envsys_data_t *" +.Ft int +.Fn sysmon_envsys_sensor_detach "struct sysmon_envsys *" "envsys_data_t *" +.Ft void +.Fn sysmon_envsys_sensor_event "struct sysmon_envsys *" "envsys_data_t *" "int" +.Ft void +.Fn sysmon_envsys_foreach_sensor "sysmon_envsys_callback_t" "void *" "bool" +.Ft int +.Fn sysmon_envsys_update_limits "struct sysmon_envsys *" "envsys_data_t *" +.Sh DESCRIPTION +.Pp +.Nm +is the kernel part of the +.Xr envsys 4 +framework. +With this framework you are able to register and unregister a +.Nm +device, attach or detach sensors into a device, and enable or disable +automatic monitoring for some sensors without any user interactivity, +among other things. +.Ss HOW TO USE THE FRAMEWORK +To register a new driver to the +.Nm +framework, a +.Em sysmon_envsys +object must be allocated and initialized; the +.Fn sysmon_envsys_create +function is used for this. +This returns a zero'ed pointer to a +.Em sysmon_envsys +structure. +.Pp +Once the object has been initialized, +actual sensors may be initialized and attached (see the +.Sx SENSOR DETAILS +section for more information). +This is accomplished by the +.Fn sysmon_envsys_sensor_attach +function, which will attach the +.Em envsys_data_t +(a sensor) specified as second argument into the +.Em sysmon_envsys +object specified in the first argument. +.Pp +Finally, after all sensors have been attached, +the device needs to set some required (and optional) members of the +.Em sysmon_envsys +structure before calling the +.Fn sysmon_envsys_register +function to register the device. +.Pp +In case of errors during the initialization, the +.Fn sysmon_envsys_destroy +function should be used. +This detaches all previously attached sensors and deallocates the +.Em sysmon_envsys +object. +.Pp +Some sensors can be monitored, and when the sensor value changes an event +can be delivered to the +.Xr powerd 8 +daemon. +Sensor monitoring can be performed by the +.Nm +framework on a polled basis. +Alternatively, the sensor's device driver can call the +.Fn sysmon_envsys_sensor_event +function to deliver the event without waiting for the device to be polled. +.Pp +The +.Fn sysmon_envsys_foreach_sensor +function can be used by other parts of the kernel to iterate over all +registered sensors. +This capability is used by the +.Xr i386/apm 4 +driver to summarize the state of all battery sensors. +.Pp +Drivers can also call the +.Fn sysmon_envsys_update_limits +function when it is necessary to reinitialize a sensor's threshold values. +This is used by the +.Xr acpibat 4 +driver when a new battery is inserted. +.Pp +The +.Em sysmon_envsys +structure is defined as follows +(only the public members are shown): +.Bd -literal +struct sysmon_envsys { + const char *sme_name; + int sme_flags; + int sme_class; + uint64_t sme_events_timeout; + void *sme_cookie; + void (*sme_refresh)(struct sysmon_envsys *, envsys_data_t *); + void (*sme_set_limits)(struct sysmon_envsys *, envsys_data_t *, + sysmon_envsys_lim_t *, uint32_t *); + void (*sme_get_limits)(struct sysmon_envsys *, envsys_data_t *, + sysmon_envsys_lim_t *, uint32_t *); +}; +.Ed +.Pp +The members have the following meaning: +.Pp +.Bl -tag -width "sme_events_timeout" +.It Fa sme_class +This specifies the class of the sysmon envsys device. +See the +.Sy DEVICE CLASSES +section for more information (OPTIONAL). +.It Fa sme_name +The name that will be used in the driver (REQUIRED). +.It Fa sme_flags +Additional flags for the +.Nm +device. +Currently supporting +.Ar SME_DISABLE_REFRESH . +If enabled, the +.Ar sme_refresh +function callback won't be used +to refresh sensor data and the driver will use its own method (OPTIONAL). +.It Fa sme_events_timeout +This is used to specify the default timeout value (in seconds) that will be +used to check for critical events if any monitoring flag was set (OPTIONAL). +.El +.Pp +If the driver wants to refresh sensors data via the +.Nm +framework, the following members may be specified: +.Pp +.Bl -tag -width "sme_events_timeout" +.It Fa sme_cookie +Typically a pointer to the device struct (also called +.Dq softc ) . +This may be used in the +.Sy sme_refresh , +.Sy sme_get_limits , +or +.Sy sme_set_limits +function callbacks. +.It Fa sme_refresh +Pointer to a function that will be used to refresh sensor data in +the device. +This can be used to set the state and other properties of the +sensor depending on the data returned by the driver. +.Em NOTE : +.Em You don't have to refresh all sensors, only the sensor specified by the +.Sy edata->sensor +.Em index . +If this member is not specified, the device driver will be totally +responsible for all updates of this sensor; the +.Nm +framework will not be able to update the sensor value. +.It Fa sme_get_limits +Pointer to a function that will be used to obtain from the driver the +initial limits (or thresholds) used when monitoring a sensor's value. +(See the +.Sx SENSOR DETAILS +section for more information.) +If this member is not specified, the +.Dv ENVSYS_FMONLIMITS +flag will be ignored, and limit monitoring will not occur until +appropriate limits are enabled from userland via +.Xr envstat 8 . +.It Fa sme_set_limits +Pointer to a function that alerts the device driver whenever monitoring +limits (or thresholds) are updated by the user. +Setting this function allows the device driver to reprogram hardware +limits (if provided by the device) when the user-specificied limits are +updated, and gives the driver direct control over setting the sensor's +state based on hardware status. +.Pp +The +.Fa sme_set_limits +callback can be invoked with the third argument (a pointer to the new +limits) set to a +.Dv NULL +pointer. +Device drivers must recognize this as a request to restore the sensor +limits to their original, boot-time values. +.Pp +If the +.Fa sme_set_limits +member is not specified, the device driver is not informed of changes to +the sensor's limit values, and the +.Nm +framework performs all limit checks in software. +.El +.Pp +Note that it's not necessary to refresh the sensors data before the +driver is registered, only do it if you need the data in your driver +to check for a specific condition. +.Pp +The timeout value for the monitoring events on a device may be changed via the +.Dv ENVSYS_SETDICTIONARY +.Xr ioctl 2 +or the +.Xr envstat 8 +command. +.Pp +To unregister a driver previously registered with the +.Nm +framework, the +.Fn sysmon_envsys_unregister +function must be used. +If there were monitoring events registered for the +driver, they all will be destroyed before the device is unregistered and +its sensors are detached. +Finally the +.Em sysmon_envsys +object will be freed, so there's no need to call +.Fn sysmon_envsys_destroy . +.Ss DEVICE CLASSES +The +.Fa sme_class +member of the +.Fa sysmon_envsys +structure is an optional flag that specifies the class of the +sysmon envsys device. +Currently there are two classes: +.Pp +.Bl -tag -width ident +.It SME_CLASS_ACADAPTER +.Pp +This class is for devices that want to act as an +.Em AC adapter . +The device writer must ensure that at least there is a +sensor with +.Em units +of +.Dv ENVSYS_INDICATOR . +This will be used to report its current state (on/off). +.It SME_CLASS_BATTERY +.Pp +This class is for devices that want to act as a +.Em Battery . +The device writer must ensure that at least there are two sensors with +units of +.Dv ENVSYS_BATTERY_CAPACITY +and +.Dv ENVSYS_BATTERY_CHARGE . +.Pp +These two sensors are used to ensure that the battery device can +send a +.Em low-power +event to the +.Xr powerd 8 +daemon (if running) when all battery devices are in a critical state. +(The critical state occurs when a battery is not currently charging +and its charge state is low or critical.) +When the +.Em low-power +condition is met, an event is sent to the +.Xr powerd 8 +daemon (if running), which will shutdown the system gracefully +by executing the +.Pa /etc/powerd/scripts/sensor_battery +script. +.Pp +If +.Xr powerd 8 +is not running, the system will be powered off via the +.Xr cpu_reboot 9 +call with the +.Dv RB_POWERDOWN +flag. +.Pp +.El +.Em NOTE : +If a +.Dv SME_CLASS_ACADAPTER +or +.Dv SME_CLASS_BATTERY +class device doesn't have the sensors required, the +.Em low-power +event will never be sent, and the graceful shutdown won't be possible. +.Ss SENSOR DETAILS +Each sensor uses a +.Sy envsys_data_t +structure, it's defined as follows (only the public members are shown); +.Bd -literal +typedef struct envsys_data { + uint32_t units; + uint32_t state; + uint32_t flags; + uint32_t rpms; + int32_t rfact; + int32_t value_cur; + int32_t value_max; + int32_t value_min; + int32_t value_avg; + sysmon_envsys_lim_t limits; + int upropset; + char desc[ENVSYS_DESCLEN]; +} envsys_data_t; +.Ed +.Pp +The members for the +.Sy envsys_data_t +structure have the following meaning: +.Pp +.Bl -tag -width cdoscdosrunru +.It Fa units +Used to set the units type. +.It Fa state +Used to set the current state. +.It Fa flags +Used to set additional flags. +Among other uses, if one or more of the +.Dv ENVSYS_FMONxxx +flags are set, automatic sensor monitoring will be enabled. +Periodically, the sensor's value will be checked and if certain +conditions are met, an event will be sent to the +.Xr powerd 8 +daemon. +.Em NOTE +.Em that limits (or thresholds) can be set at any time to enable +.Em monitoring that the sensor's value remains within those limits . +.It Fa rpms +Used to set the nominal RPM value for +.Sy fan +sensors. +.It Fa rfact +Used to set the rfact value for +.Sy voltage +sensors. +.It Fa value_cur +Used to set the current value. +.It Fa value_max +Used to set the maximum value. +.It Fa value_min +Used to set the minimum value. +.It Fa value_avg +Used to set the average value. +.It Fa limits +Structure used to contain the sensor's alarm thresholds. +.It Fa upropset +Used to keep track of which sensor properties are set. +.It Fa desc +Used to set the description string. +.Em NOTE +.Em that the description string must be unique in a device, and sensors with +.Em duplicate or empty description will simply be ignored . +.El +.Pp +Users of this framework must take care about the following points: +.Bl -bullet +.It +The +.Ar desc +member needs to have a valid description, unique in a device and non empty +to be valid. +.It +The +.Ar units +type must be valid. +The following units are defined: +.Pp +.Bl -tag -width "ENVSYS_BATTERY_CAPACITY" -compact +.It Dv ENVSYS_STEMP +For temperature sensors, in microkelvins. +.It Dv ENVSYS_SFANRPM +For fan sensors. +.It Dv ENVSYS_SVOLTS_AC +For AC Voltage. +.It Dv ENVSYS_SVOLTS_DC +For DC Voltage. +.It Dv ENVSYS_SOHMS +For Ohms. +.It Dv ENVSYS_SWATTS +For Watts. +.It Dv ENVSYS_SAMPS +For Ampere. +.It Dv ENVSYS_SWATTHOUR +For Watts hour. +.It Dv ENVSYS_SAMPHOUR +For Ampere hour. +.It Dv ENVSYS_INDICATOR +For sensors that only want a boolean type. +.It Dv ENVSYS_INTEGER +For sensors that only want an integer type. +.It Dv ENVSYS_DRIVE +For drive sensors. +.It Dv ENVSYS_BATTERY_CAPACITY +For Battery device classes. +This sensor unit uses the +.Dv ENVSYS_BATTERY_CAPACITY_* +values in +.Ar value_cur +to report its current capacity to userland. +Mandatory if +.Fa sme_class +is set to +.Dv SME_CLASS_BATTERY . +.It Dv ENVSYS_BATTERY_CHARGE +For Battery device classes. +This sensor is equivalent to the Indicator type, it's a boolean. +Use it to specify in what state is the Battery state: +.Sy true +if the battery is currently charging or +.Sy false +otherwise. +Mandatory if +.Fa sme_class +is set to +.Dv SME_CLASS_BATTERY . +.El +.It +When initializing or refreshing the sensor, the +.Ar state +member should be set to a known state (otherwise it will be in +unknown state). +Possible values: +.Pp +.Bl -tag -width "ENVSYS_SCRITUNDERXX" -compact +.It Dv ENVSYS_SVALID +Sets the sensor to a valid state. +.It Dv ENVSYS_SINVALID +Sets the sensor to an invalid state. +.It Dv ENVSYS_SCRITICAL +Sets the sensor to a critical state. +.It Dv ENVSYS_SCRITUNDER +Sets the sensor to a critical under state. +.It Dv ENVSYS_SCRITOVER +Sets the sensor to a critical over state. +.It Dv ENVSYS_SWARNUNDER +Sets the sensor to a warning under state. +.It Dv ENVSYS_SWARNOVER +Sets the sensor to a warning over state. +.El +.Pp +.It +The +.Ar flags +member accepts one or more of the following flags: +.Pp +.Bl -tag -width "ENVSYS_FCHANGERFACTXX" +.It Dv ENVSYS_FCHANGERFACT +Marks the sensor with ability to change the +.Ar rfact +value on the fly (in voltage sensors). +The +.Ar rfact +member must be used in the correct place of the code +that retrieves and converts the value of the sensor. +.It Dv ENVSYS_FPERCENT +This uses the +.Ar value_cur +and +.Ar value_max +members to make a percentage. +Both values must be enabled and have data. +.It Dv ENVSYS_FVALID_MAX +Marks the +.Ar value_max +value as valid. +.It Dv ENVSYS_FVALID_MIN +Marks the +.Ar value_min +value as valid. +.It Dv ENVSYS_FVALID_AVG +Marks the +.Ar value_avg +value as valid. +.It Dv ENVSYS_FMONCRITICAL +Enables and registers a new event to monitor a critical state. +.It Dv ENVSYS_FMONLIMITS +Enables and registers a new event to monitor a sensor's value crossing +limits or thresholds. +.It Dv ENVSYS_FMONSTCHANGED +Enables and registers a new event to monitor battery capacity or drive state +sensors. +The flag is not effective if the +.Ar units +member is not +.Dv ENVSYS_DRIVE +or +.Dv ENVSYS_BATTERY_CAPACITY . +.It Dv ENVSYS_FMONNOTSUPP +Disallows setting of limits (or thresholds) via the +.Dv ENVSYS_SETDICTIONARY +.Xr ioctl 2 . +This flag only disables setting the limits from userland. +It has no effect on monitoring flags set by the driver. +.It Dv ENVSYS_FHAS_ENTROPY +Allows this sensor to provide entropy for +.Xr rnd 4 . +.El +.Pp +.Em If the driver has to use any of the +.Ar value_max , +.Ar value_min , +.Em or +.Ar value_avg +.Em members, they should be marked as valid with the appropriate flag . +.Pp +.It +If +.Ar units +is set to +.Dv ENVSYS_DRIVE , +the +.Ar value_cur +member must be set to one of the following predefined states: +.Pp +.Bl -tag -width "ENVSYS_DRIVE_POWERDOWNXX" -compact +.It Dv ENVSYS_DRIVE_EMPTY +Drive state is unknown. +.It Dv ENVSYS_DRIVE_READY +Drive is ready. +.It Dv ENVSYS_DRIVE_POWERUP +Drive is powering up. +.It Dv ENVSYS_DRIVE_ONLINE +Drive is online. +.It Dv ENVSYS_DRIVE_OFFLINE +Drive is offline. +.It Dv ENVSYS_DRIVE_IDLE +Drive is idle. +.It Dv ENVSYS_DRIVE_ACTIVE +Drive is active. +.It Dv ENVSYS_DRIVE_BUILD +Drive is building. +.It Dv ENVSYS_DRIVE_REBUILD +Drive is rebuilding. +.It Dv ENVSYS_DRIVE_POWERDOWN +Drive is powering down. +.It Dv ENVSYS_DRIVE_FAIL +Drive has failed. +.It Dv ENVSYS_DRIVE_PFAIL +Drive has been degraded. +.It Dv ENVSYS_DRIVE_MIGRATING +Drive is migrating. +.It Dv ENVSYS_DRIVE_CHECK +Drive is checking its state. +.El +.Pp +.It +If +.Ar units +is set to +.Dv ENVSYS_BATTERY_CAPACITY , +the +.Ar value_cur +member must be set to one of the following predefined capacity states: +.Pp +.Bl -tag -width "ENVSYS_BATTERY_CAPACITY_CRITICAL" -compact +.It Dv ENVSYS_BATTERY_CAPACITY_NORMAL +Battery charge is normal. +.It Dv ENVSYS_BATTERY_CAPACITY_CRITICAL +Battery charge is critical. +.It Dv ENVSYS_BATTERY_CAPACITY_LOW +Battery charge is low. +.It Dv ENVSYS_BATTERY_CAPACITY_WARNING +Battery charge is on or below the warning capacity. +.El +.It +The +.Xr envsys 4 +framework expects to have the values converted to +a unit that can be converted to another one easily. +That means the user +should convert the value returned by the driver to the appropriate unit. +For example voltage sensors to +.Sy mV , +temperature sensors to +.Sy uK , +Watts to +.Sy mW , +Ampere to +.Sy mA , +etc. +.Pp +The following types shouldn't need any conversion: +.Dv ENVSYS_BATTERY_CAPACITY , +.Dv ENVSYS_BATTERY_CHARGE , +.Dv ENVSYS_INDICATOR , +.Dv ENVSYS_INTEGER , +and +.Dv ENVSYS_DRIVE . +.Pp +.Em PLEASE NOTE THAT YOU MUST AVOID USING FLOATING POINT OPERATIONS +.Em IN KERNEL WHEN CONVERTING THE DATA RETURNED BY THE DRIVER TO THE +.Em APPROPRIATE UNIT, IT'S NOT ALLOWED . +.Pp +.El +.Ss HOW TO ENABLE AUTOMATIC MONITORING IN SENSORS +The following example illustrates how to enable automatic monitoring +in a virtual driver for a +.Em critical +state in the first sensor +.Fa ( sc_sensor[0] ) : +.Pp +.Bd -literal +int +mydriver_initialize_sensors(struct mysoftc *sc) +{ + ... + /* sensor is initialized with a valid state */ + sc->sc_sensor[0].state = ENVSYS_SVALID; + + /* + * the monitor member must be true to enable + * automatic monitoring. + */ + sc->sc_sensor[0].monitor = true; + + /* and now we specify the type of the monitoring event */ + sc->sc_sensor[0].flags |= ENVSYS_FMONCRITICAL; + ... +} + +int +mydriver_refresh(struct sysmon_envsys *sme, envsys_data_t *edata) +{ + struct mysoftc *sc = sme->sme_cookie; + + /* we get current data from the driver */ + edata->value_cur = sc->sc_getdata(); + + /* + * if value is too high, mark the sensor in + * critical state. + */ + if (edata->value_cur > MYDRIVER_SENSOR0_HIWAT) { + edata->state = ENVSYS_SCRITICAL; + /* a critical event will be sent now automatically */ + } else { + /* + * if value is within the limits, and we came from + * a critical state make sure to change sensor's state + * to valid. + */ + edata->state = ENVSYS_SVALID; + } + ... +} +.Ed +.Sh CODE REFERENCES +The +.Sy envsys 2 +framework is implemented within the files: +.Pp +.Pa sys/dev/sysmon/sysmon_envsys.c +.Pp +.Pa sys/dev/sysmon/sysmon_envsys_events.c +.Pp +.Pa sys/dev/sysmon/sysmon_envsys_tables.c +.Pp +.Pa sys/dev/sysmon/sysmon_envsys_util.c +.Sh SEE ALSO +.Xr envsys 4 , +.Xr envstat 8 +.Sh HISTORY +The first +.Em envsys +framework first appeared in +.Nx 1.5 . +The +.Em envsys 2 +framework first appeared in +.Nx 5.0 . +.Sh AUTHORS +The (current) +.Em envsys 2 +framework was implemented by +.An Juan Romero Pardines . +Additional input on the design was provided by many +.Nx +developers around the world. +.Pp +The first +.Em envsys +framework was implemented by +Jason R. Thorpe, Tim Rightnour, and Bill Squier. diff --git a/static/netbsd/man9/sysmon_pswitch.9 b/static/netbsd/man9/sysmon_pswitch.9 new file mode 100644 index 00000000..98fb3bc5 --- /dev/null +++ b/static/netbsd/man9/sysmon_pswitch.9 @@ -0,0 +1,139 @@ +.\" $NetBSD: sysmon_pswitch.9,v 1.7 2016/06/01 02:06:54 pgoyette Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 6, 2015 +.Dt SYSMON_PSWITCH 9 +.Os +.Sh NAME +.Nm sysmon_pswitch +.Nd framework for power switches +.Sh SYNOPSIS +.In dev/sysmon/sysmonvar.h +.Ft int +.Fn sysmon_pswitch_register "struct sysmon_pswitch *smpsw" +.Ft void +.Fn sysmon_pswitch_unregister "struct sysmon_pswitch *smpsw" +.Ft void +.Fn sysmon_pswitch_event "struct sysmon_pswitch *smpsw" "int event" +.Sh DESCRIPTION +The machine-independent +.Nm +provides a framework for power management. +The interface has been largely superseded by the +.Xr pmf 9 +framework, but +.Nm +is still used to manage power switches as well as +related mechanical adapters and buttons. +These are encapsulated in the following structure: +.Bd -literal +struct sysmon_pswitch { + const char *smpsw_name; /* power switch name */ + int smpsw_type; /* power switch type */ + + LIST_ENTRY(sysmon_pswitch) smpsw_list; +}; +.Ed +.Pp +Unsurprisingly, +.Fa smpsw_name +specifies the name of the power switch and +.Fa smpsw_type +defines the type of it. +The following types are defined: +.Pp +.Bl -tag -width PSWITCH_HK_VENDOR_BUTTON -compact -offset indent +.It PSWITCH_TYPE_POWER +.It PSWITCH_TYPE_SLEEP +.It PSWITCH_TYPE_LID +.It PSWITCH_TYPE_RESET +.It PSWITCH_TYPE_ACADAPTER +.It PSWITCH_TYPE_HOTKEY +.It PSWITCH_TYPE_RADIO +.El +.Pp +If the type is +.Dv PSWITCH_TYPE_HOTKEY , +there are few predefined names that can be used for +.Fa smpsw_name : +.Pp +.Bl -tag -width PSWITCH_HK_VENDOR_BUTTON -compact -offset indent +.It PSWITCH_HK_DISPLAY_CYCLE +.Em display-cycle +.It PSWITCH_HK_LOCK_SCREEN +.Em lock-screen +.It PSWITCH_HK_BATTERY_INFO +.Em battery-info +.It PSWITCH_HK_EJECT_BUTTON +.Em eject-button +.It PSWITCH_HK_ZOOM_BUTTON +.Em zoom-button +.It PSWITCH_HK_VENDOR_BUTTON +.Em vendor-button +.El +.Pp +Once a power switch event has been proceeded, +.Nm +will inform the user space +.Xr powerd 8 , +which will possibly execute a script matching the type of the power switch. +.Sh FUNCTIONS +After the +.Em sysmon_pswitch +structure has been initialized, +a new power switch device can be registered by using +.Fn sysmon_pswitch_register . +The device can be detached from the framework by +.Fn sysmon_pswitch_unregister . +.Pp +The +.Fn sysmon_pswitch_event +is used to signal a new power switch event. +There are two possibilities for the value of +.Fa event : +.Bl -tag -width PSWITCH_HK_VENDOR_BUTTON -offset indent +.It PSWITCH_EVENT_PRESSED +A button has been pressed, the lid has been closed, the AC adapter is off, etc. +.It PSWITCH_EVENT_RELEASED +A button has been released, the lid is open, the AC adapter is on, etc. +.El +.Pp +The corresponding events in +.Xr powerd 8 +are +.Em pressed +and +.Em released . +.Sh SEE ALSO +.Xr powerd 8 , +.Xr pmf 9 , +.Xr sysmon_envsys 9 , +.Xr sysmon_taskq 9 +.Sh AUTHORS +.An Jason R. Thorpe Aq Mt thorpej@NetBSD.org diff --git a/static/netbsd/man9/sysmon_taskq.9 b/static/netbsd/man9/sysmon_taskq.9 new file mode 100644 index 00000000..be2817fb --- /dev/null +++ b/static/netbsd/man9/sysmon_taskq.9 @@ -0,0 +1,105 @@ +.\" $NetBSD: sysmon_taskq.9,v 1.9 2021/12/31 14:22:10 riastradh Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 24, 2010 +.Dt SYSMON_TASKQ 9 +.Os +.Sh NAME +.Nm sysmon_taskq +.Nd general purpose system monitoring task queue +.Sh SYNOPSIS +.In dev/sysmon/sysmon_taskq.h +.Ft void +.Fn sysmon_task_queue_preinit "void" +.Ft void +.Fn sysmon_task_queue_init "void" +.Ft void +.Fn sysmon_task_queue_fini "void" +.Ft int +.Fn sysmon_task_queue_sched "u_int pri" "void (*func)(void *)" "void *arg" +.Ft void +.Fn sysmon_task_queue_barrier "u_int pri" +.Sh DESCRIPTION +The machine-independent +.Nm +provides a simple general purpose task queue. +It can be used to run callbacks that require thread context, +but do not warrant the use of a more fine-grained solution. +.Pp +Although the intended usage is related to the context of system monitoring +and power management, also other comparable functions are suitable for +.Nm . +.Sh FUNCTIONS +The necessary internal data structures +are initialized during system startup by +.Fn sysmon_task_queue_preinit . +Before actual usage, a machine-dependent +procedure should finish the initialization +by calling +.Fn sysmon_task_queue_init . +This will create a kernel thread that can be later halted by +.Fn sysmon_task_queue_fini . +All scheduled tasks are executed before the queue is halted. +.Pp +The +.Fn sysmon_task_queue_sched +function enqueues +.Fa func +to be executed at the priority +.Fa pri . +If +.Fa pri +is 0, the scheduled function will be placed as the last element in the queue. +The single argument passed to +.Fa func +is specified by +.Fa arg . +.Pp +The +.Fn sysmon_task_queue_barrier +function waits for the completion of all tasks at +.Fa pri +or lower currently queued at the time of the call. +.Sh RETURN VALUES +Upon successful completion, +.Fn sysmon_task_queue_sched +returns 0. +Otherwise, the following error values are returned: +.Bl -tag -width [EINVAL] +.It Bq Er EINVAL +An invalid parameter was specified. +.It Bq Er ENOMEM +There was not enough memory. +.El +.Sh SEE ALSO +.Xr queue 3 , +.Xr kthread 9 , +.Xr workqueue 9 +.Sh AUTHORS +.An Jason R. Thorpe Aq Mt thorpej@NetBSD.org diff --git a/static/netbsd/man9/tc.9 b/static/netbsd/man9/tc.9 new file mode 100644 index 00000000..d0c719f1 --- /dev/null +++ b/static/netbsd/man9/tc.9 @@ -0,0 +1,182 @@ +.\" $NetBSD: tc.9,v 1.13 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 7, 2001 +.Dt TC 9 +.Os +.Sh NAME +.Nm TC , +.Nm tc_intr_establish , +.Nm tc_intr_disestablish , +.Nm tc_intr_evcnt . +.Nm tc_mb , +.Nm tc_wmb , +.Nm tc_syncbus , +.Nm tc_badaddr , +.Nm TC_DENSE_TO_SPARSE , +.Nm TC_PHYS_TO_UNCACHED +.Nd TURBOchannel bus +.Sh SYNOPSIS +.In sys/bus.h +.In dev/tc/tcvar.h +.In dev/tc/tcdevs.h +.Ft void +.Fn tc_intr_establish "struct device *dev" "void *cookie" \ +"int level" "int (*handler)(void *)" "void *arg" +.Ft void +.Fn tc_intr_disestablish "struct device *dev" "void *cookie" +.Ft const struct evcnt * +.Fn tc_intr_evcnt "struct device *dev" "void *cookie" +.Ft void +.Fn tc_mb "" +.Ft void +.Fn tc_wmb "" +.Ft void +.Fn tc_syncbus "" +.Ft int +.Fn tc_badaddr "tc_addr_t tcaddr" +.Ft tc_addr_t +.Fn TC_DENSE_TO_SPARSE "tc_addr_t addr" +.Ft tc_addr_t +.Fn TC_PHYS_TO_UNCACHED "tc_addr_t addr" +.Sh DESCRIPTION +The +.Nm +device provides support for the DEC TURBOchannel bus found on all DEC +TURBOchannel machines with MIPS (DECstation 5000 series, excluding the +5000/200) and Alpha (3000-series) systems. +TURBOchannel is a 32-bit wide synchronous DMA-capable bus, running +at 25 MHz on higher-end machines and at 12.5 MHz on lower-end machines. +.Sh DATA TYPES +Drivers for devices attached to the TURBOchannel bus will make use of +the following data types: +.Bl -tag -width compact +.It Fa struct tc_attach_args +A structure use to inform the driver of TURBOchannel bus properties. +It contains the following members: +.Bd -literal + bus_space_tag_t ta_memt; + bus_dma_tag_t ta_dmat; + char ta_modname[TC_ROM_LLEN+1]; + u_int ta_slot; + tc_offset_t ta_offset; + tc_addr_t ta_addr; + void *ta_cookie; + u_int ta_busspeed; +.Ed +.Pp +The +.Em ta_busspeed +member specifies the TURBOchannel bus speed and is useful for +time-related functions. +Values values are +.Em TC_SPEED_12_5_MHZ +for the 12.5 MHz bus and +.Em TC_SPEED_25_MHZ +for the 50 MHz bus. +.El +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn tc_intr_establish "dev" "cookie" "level" "handler" "arg" +Establish an interrupt handler with device +.Fa dev +for the interrupt described completely by +.Fa cookie , +the value passed to the driver in the +.Em ta_cookie +member of the +.Em tc_attach_args +structure. +The priority of the interrupt is specified by +.Fa level . +When the interrupt occurs the function +.Fa handler +is called with argument +.Fa arg . +.It Fn tc_intr_disestablish "dev" "cookie" +Dis-establish the interrupt handler with device +.Fa dev +for the interrupt described completely +.Fa cookie . +.It Fn tc_intr_evcnt "dev" "cookie" +Do interrupt event counting with device +.Fa dev +for the event described completely by +.Fa cookie . +.It Fn tc_mb "" +A read/write memory barrier. +Any CPU-to-memory reads/writes before the barrier must complete before +any CPU-to-memory reads/writes after it. +.It Fn tc_wmb "" +A write memory barrier. +Any CPU-to-memory writes before the barrier must complete +before any CPU-to-memory writes after it. +.It Fn tc_syncbus "" +Synchronise writes on the TURBOchannel bus by ensuring CPU writes are +propagated across the TURBOchannel bus. +.It Fn tc_badaddr "tcaddr" +Returns non-zero if the given address +.Fa tcaddr +is invalid. +.It Fn TC_DENSE_TO_SPARSE "addr" +Convert the given physical address +.Fa addr +in TURBOchannel dense space to the corresponding address in +TURBOchannel sparse space. +.It Fn TC_PHYS_TO_UNCACHED "addr" +Convert the given system memory physical address +.Fa addr +to the physical address of the corresponding region that is not +cached. +.El +.Sh AUTOCONFIGURATION +The TURBOchannel bus is a direct-connection bus. +During autoconfiguration, the parent specifies the name of the found +TURBOchannel module into the +.Fa ta_modname +member of the +.Em tc_attach_args +structure. +Drivers should match on this name. +.Sh DMA SUPPORT +The TURBOchannel bus supports 32-bit, bidirectional DMA transfers. +Support is provided by the standard +.Xr bus_dma 9 +interface. +.Sh CODE REFERENCES +The TURBOchannel subsystem itself is implemented within the file +.Pa sys/dev/tc/tc_subr.c . +Machine-dependent portions can be found in +.Pa sys/arch/<arch>/tc/tcbus.c . +.Sh SEE ALSO +.Xr tc 4 , +.Xr autoconf 9 , +.Xr bus_dma 9 , +.Xr bus_space 9 , +.Xr driver 9 diff --git a/static/netbsd/man9/tcp_congctl.9 b/static/netbsd/man9/tcp_congctl.9 new file mode 100644 index 00000000..c36a2fd0 --- /dev/null +++ b/static/netbsd/man9/tcp_congctl.9 @@ -0,0 +1,95 @@ +.\" $NetBSD: tcp_congctl.9,v 1.4 2008/04/30 13:10:58 martin Exp $ +.\" +.\" Copyright (c) 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Rui Paulo. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 15, 2006 +.Dt TCP_CONGCTL 9 +.Os +.Sh NAME +.Nm tcp_congctl +.Nd TCP congestion control API +.Sh SYNOPSIS +.In netinet/tcp_congctl.h +.\" +.Ft int +.Fn tcp_congctl_register "const char *" "struct tcp_congctl *" +.\" +.Ft int +.Fn tcp_congctl_unregister "const char *" +.\" +.Sh DESCRIPTION +The +.Nm tcp_congctrl +API is used to add or remove TCP congestion control algorithms +on-the-fly and to modularize them. +It includes basically two functions: +.Bl -tag -width "xxxxx" +.It Fn tcp_congctl_register "const char *" "struct tcp_congctl *" +Registers a new congestion control algorithm. +The +.Fa struct tcp_congctl +argument must contain a list of callbacks like the following: +.Bd -literal -offset indent +struct tcp_congctl { + int (*fast_retransmit)(struct tcpcb *, + struct tcphdr *); + void (*slow_retransmit)(struct tcpcb *); + void (*fast_retransmit_newack)(struct tcpcb *, + struct tcphdr *); + void (*newack)(struct tcpcb *, + struct tcphdr *); + void (*cong_exp)(struct tcpcb *); +}; +.Ed +.It Fn tcp_congctl_unregister "const char *" +If found, unregister the selected TCP congestion control algorithm. +.El +.Sh RETURN VALUES +.Fn tcp_congctl_register +and +.Fn tcp_congctl_unregister +both return +.Dv 0 +when there is no error. +If the name is already registered, +.Fn tcp_congctl_register +will return +.Er EEXIST . +.Fn tcp_congctl_unregister +can return +.Er ENOENT +if there is no congestion control algorithm by that name and can return +.Er EBUSY +if the matched algorithm is being used by userspace applications. +.Sh FILES +Implementation is in +.Pa sys/netinet/tcp_congctl.c +and the interface is in +.Pa sys/netinet/tcp_congctl.h . +.Sh SEE ALSO +.Xr tcp 4 diff --git a/static/netbsd/man9/thmap.9 b/static/netbsd/man9/thmap.9 new file mode 100644 index 00000000..37594e28 --- /dev/null +++ b/static/netbsd/man9/thmap.9 @@ -0,0 +1,237 @@ +.\" $NetBSD: thmap.9,v 1.3 2020/08/28 07:03:41 riastradh Exp $ +.\" +.\" Copyright (c) 2018 Mindaugas Rasiukevicius <rmind at noxt eu> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd December 11, 2018 +.Dt THMAP 9 +.Os +.Sh NAME +.Nm thmap +.Nd concurrent trie-hash map +.Sh SYNOPSIS +.In thmap.h +.\" ----- +.Ft thmap_t * +.Fn thmap_create "uintptr_t baseptr" "const thmap_ops_t *ops" "unsigned flags" +.Ft void +.Fn thmap_destroy "thmap_t *thmap" +.Ft void * +.Fn thmap_get "thmap_t *thmap" "const void *key" "size_t len" +.Ft void * +.Fn thmap_put "thmap_t *thmap" "const void *key" "size_t len" "void *val" +.Ft void * +.Fn thmap_del "thmap_t *thmap" "const void *key" "size_t len" +.Ft void * +.Fn thmap_stage_gc "thmap_t *thmap" +.Ft void +.Fn thmap_gc "thmap_t *thmap" "void *ref" +.Ft void +.Fn thmap_setroot "thmap_t *thmap" "uintptr_t root_offset" +.Ft uintptr_t +.Fn thmap_getroot "const thmap_t *thmap" +.\" ----- +.Sh DESCRIPTION +Concurrent trie-hash map \(em a general purpose associative array, +combining the elements of hashing and radix trie. +Highlights: +.Pp +.Bl -hyphen -compact +.It +Very competitive performance, with logarithmic time complexity on average. +.It +Lookups are lock-free and inserts/deletes are using fine-grained locking. +.It +Incremental growth of the data structure (no large resizing/rehashing). +.It +Optional support for use with shared memory, e.g. memory-mapped file. +.El +.Pp +Delete operations (the key/data destruction) must be synchronized with +the readers using some reclamation mechanism. +.\" ----- +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn thmap_create baseptr ops flags +Construct a new trie-hash map. +The optional +.Fa ops +parameter can +used to set the custom allocate/free operations (see the description of +.Vt thmap_ops_t +below). +In such case, the +.Fa baseptr +is the base (start) address of the address space mapping (it must be +word-aligned). +If +.Fa ops +is set to +.Dv NULL , +then +.Xr malloc 3 +and +.Xr free 3 +will be used as the default operations and +.Fa baseptr +should be set to zero. +Currently, the supported +.Fa flags +are: +.Bl -tag -width THMAP_SETROOT +.It Dv THMAP_NOCOPY +The keys on insert will not be copied and the given pointers to them will +be expected to be valid and the values constant until the key is deleted; +by default, the put operation will make a copy of the key. +.It Dv THMAP_SETROOT +Indicate that the root of the map will be manually set using the +.Fn thmap_setroot +routine; +by default, the map is initialized and the root node is set on +.Fn thmap_create . +.El +.\" --- +.It Fn thmap_destroy thmap +Destroy the map, freeing the memory it uses. +.\" --- +.It Fn thmap_get thmap key len +Lookup the key (of a given length) and return the value associated with it. +Return +.Dv NULL +if the key is not found (see the +.Sx CAVEATS +section). +.\" --- +.It Fn thmap_put thmap key len val +Insert the key with an arbitrary value. +If the key is already present, return the already existing associated value +without changing it. +Otherwise, on a successful insert, return the given value. +Just compare the result against +.Fa val +to test whether the insert was successful. +.\" --- +.It Fn thmap_del thmap key len +Remove the given key. +If the key was present, return the associated value; +otherwise return +.Dv NULL . +The memory associated with the entry is not released immediately, because +in the concurrent environment (e.g., multi-threaded application) the caller +may need to ensure it is safe to do so. +It is managed using the +.Fn thmap_stage_gc +and +.Fn thmap_gc +routines. +.\" --- +.It Fn thmap_stage_gc thmap +Stage the currently pending entries (the memory not yet released after +the deletion) for reclamation (G/C). +This operation should be called +.Em before +the synchronization barrier. +.Pp +Returns a reference which must be passed to +.Fn thmap_gc . +Not calling the G/C function for the returned reference would result in +a memory leak. +.\" --- +.It Fn thmap_gc thmap ref +Reclaim (G/C) the staged entries i.e. release any memory associated +with the deleted keys. +The reference must be the value returned by the call to +.Fn thmap_stage_gc . +.Pp +This function must be called +.Em after +the synchronization barrier which guarantees that there are no active +readers referencing the staged entries. +.\" --- +.El +.Pp +If the map is created using the +.Fa THMAP_SETROOT +flag, then the following functions are applicable: +.\" --- +.Bl -tag -width abcd +.It Fn thmap_setroot thmap root_offset +Set the root node. +The address must be relative to the base address, as if allocated by the +.Fn thmap_ops_t::alloc +routine. +Return 0 on success and \-1 on failure (if already set). +.It Fn thmap_getroot thmap +Get the root node address. +The returned address will be relative to the base address. +.El +.\" --- +.Pp +Members of +.Vt thmap_ops_t +are +.Bd -literal + uintptr_t (*alloc)(size_t len); + void (*free)(uintptr_t addr, size_t len); +.Ed +.\" ----- +.Sh EXAMPLES +Simple case backed by +.Xr malloc 3 , +which could be used in multi-threaded environment: +.Bd -literal + thmap_t *kvmap; + struct obj *obj; + + kvmap = thmap_create(0, NULL); + assert(kvmap != NULL); + ... + obj = obj_create(); + thmap_put(kvmap, "test", sizeof("test") - 1, obj); + ... + obj = thmap_get(kvmap, "test", sizeof("test") - 1); + ... + thmap_destroy(kvmap); +.Ed +.\" ----- +.Sh AUTHORS +.An Mindaugas Rasiukevicius Aq Mt rmind@noxt.eu +.Sh CAVEATS +The implementation uses pointer tagging and atomic operations. +This requires the base address and the allocations to provide at least word +alignment. +.Pp +While the +.Dv NULL +values may be inserted, +.Fn thmap_get +and +.Fn thmap_del +cannot indicate whether the key was not found or a key with a +.Dv NULL +value was found. +If the caller needs to indicate an "empty" value, it can use a +special pointer value, such as +.Li (void *)(uintptr_t)0x1 . +.\" ----- diff --git a/static/netbsd/man9/threadpool.9 b/static/netbsd/man9/threadpool.9 new file mode 100644 index 00000000..46eb60ea --- /dev/null +++ b/static/netbsd/man9/threadpool.9 @@ -0,0 +1,343 @@ +.\" $NetBSD: threadpool.9,v 1.4 2020/09/07 01:07:38 riastradh Exp $ +.\" +.\" Copyright (c) 2014 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Taylor R. Campbell. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 26, 2018 +.Dt THREADPOOL 9 +.Os +.\" +.Sh NAME +.Nm threadpool +.Nd shared pools of kthreads +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SYNOPSIS +.In sys/threadpool.h +.\"""""""""""""""""""""""""""""""""""" +.Vt typedef void threadpool_job_fn_t(struct threadpool_job *); +.\"""""""""""""""""""""""""""""""""""" +.Ft int +.Fn threadpool_get "struct threadpool **poolp" "pri_t pri" +.\" +.Ft void +.Fn threadpool_put "struct threadpool *pool" "pri_t pri" +.\"""""""""""""""""""""""""""""""""""" +.Ft int +.Fn threadpool_percpu_get "struct threadpool_percpu **pool_percpup" "pri_t pri" +.\" +.Ft void +.Fn threadpool_percpu_put "struct threadpool_percpu *pool_percpu" "pri_t pri" +.\" +.Ft struct threadpool * +.Fn threadpool_percpu_ref "struct threadpool_percpu *pool" +.\" +.Ft struct threadpool * +.Fn threadpool_percpu_ref_remote "struct threadpool_percpu *pool" "struct cpu_info *ci" +.\"""""""""""""""""""""""""""""""""""" +.Ft void +.Fn threadpool_job_init "struct threadpool_job *job" "threadpool_job_fn_t fn" "kmutex_t *interlock" "const char *fmt" "..." +.\" +.Ft void +.Fn threadpool_job_destroy "struct threadpool_job *job" +.\" +.Ft void +.Fn threadpool_job_done "struct threadpool_job *job" +.\"""""""""""""""""""""""""""""""""""" +.Ft void +.Fn threadpool_schedule_job "struct threadpool *pool" "struct threadpool_job *job" +.\" +.Ft void +.Fn threadpool_cancel_job "struct threadpool *pool" "struct threadpool_job *job" +.\" +.Ft bool +.Fn threadpool_cancel_job_async "struct threadpool *pool" "struct threadpool_job *job" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh DESCRIPTION +The +.Nm +abstraction is provided to share a pool of +.Xr kthread 9 +kernel threads for medium- to long-term actions, called jobs, which can +be scheduled from contexts that do not allow sleeping. +.Pp +For each priority level, there is one unbound thread pool, and one +collection of per-CPU thread pools. +Access to the unbound thread pools is provided by +.Fn threadpool_get +and +.Fn threadpool_put . +Access to the per-CPU thread pools is provided by +.Fn threadpool_percpu_get +and +.Fn threadpool_percpu_put . +.Pp +Job state is stored in the +.Vt threadpool_job +structure. +Callers of the +.Nm +abstraction +must allocate memory for +.Vt threadpool_job +structures, but should consider them opaque, and should not inspect or +copy them. +Each job represented by a +.Vt threadpool_job +structure will be run only once at a time, until the action associated +with it calls +.Fn threadpool_job_done . +.Pp +Jobs are run in thread context and may take arbitrarily long to run or +sleep arbitrarily long. +.\" The +.\" .Nm +.\" abstraction is intended as a building block for cheaper abstractions, +.\" namely +.\" .Xr task 9 +.\" and +.\" .Xr workqueue 9 . +.\" It should generally not be used directly. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh FUNCTIONS +.\" +.Bl -tag -width abcd +.\"""""""""""""""""""""""""""""""""""" +.It Fn threadpool_get "poolp" "pri" +Obtain a reference to the unbound thread pool at priority +.Fa pri +and store it in +.Fa poolp . +.Pp +May sleep. +.\" +.It Fn threadpool_put "pool" "pri" +Release the reference to the unbound thread pool +.Fa pool +at priority +.Fa pri , +which must be the same as the priority that was passed to +.Fn threadpool_get +to obtain +.Fa pool . +.Pp +May sleep. +.Pp +Do not use +.Fn threadpool_put +with thread pools obtained from +.Fn threadpool_percpu_ref +or +.Fn threadpool_percpu_ref_remote . +.\"""""""""""""""""""""""""""""""""""" +.It Fn threadpool_percpu_get "pool_percpup" "pri" +Obtain a reference to the per-CPU thread pool at priority +.Fa pri +and store it in +.Fa pool_percpup . +.Pp +Use +.Fn threadpool_percpu_ref +or +.Fn threadpool_percpu_ref_remote +with it to get at the thread pool for a particular CPU. +.Pp +May sleep. +.\" +.It Fn threadpool_percpu_put "pool_percpu" "pri" +Release a reference to the per-CPU thread pool +.Fa pool_percpu +at priority +.Fa pri . +.Pp +May sleep. +.\" +.It Fn threadpool_percpu_ref "pool_percpu" +Return the thread pool in +.Fa pool_percpu +for the current CPU. +.Pp +The resulting thread pool pointer is stable until +.Fa pool_percpu +is released with +.Fn threadpool_percpu_put . +Using it to schedule or cancel a job does not require being on the same +CPU. +.Pp +Do not use +.Fn threadpool_put +with thread pools obtained from +.Fn threadpool_percpu_ref . +.\" +.It Fn threadpool_percpu_ref_remote "pool_percpu" "ci" +Return the thread pool in +.Fa pool_percpu +for the CPU whose +.Vt struct cpu_info +is given by +.Fa ci . +.Pp +The resulting thread pool pointer is stable until +.Fa pool_percpu +is released with +.Fn threadpool_percpu_put . +Using it to schedule or cancel a job does not require being on the same +CPU, but it is faster and friendlier to the cache to use +.Fn threadpool_percpu_ref +and use the resulting thread pool only on the same CPU. +.Pp +Do not use +.Fn threadpool_put +with thread pools obtained from +.Fn threadpool_percpu_ref_remote . +.\"""""""""""""""""""""""""""""""""""" +.It Fn threadpool_job_init "job" "fn" "interlock" "fmt" "..." +Initialize the threadpool job +.Fa job +to run +.Fa fn +when scheduled and to interlock with +.Fa interlock . +The argument +.Fa fmt +is a +.Xr printf 9 +format string for the job's name. +.Pp +The mutex +.Fa interlock +is used to synchronize job scheduling and completion. +The action +.Fa fn +is required to eventually call +.Fn threadpool_job_done , +with +.Fa interlock +held. +This is so that while the job is running and may be waiting for work +to do, scheduling the job has no effect, but as soon as the job is +done, scheduling the job will cause it to run again. +.Pp +To change the action of a job, you must use +.Fn threadpool_job_destroy +first and then call +.Fn threadpool_job_init +again. +.\" +.It Fn threadpool_job_destroy "job" +Destroy the threadpool job +.Fa job . +.Fa job +must not currently be scheduled to run. +If it may still be scheduled, you can use +.Fn threadpool_cancel_job +to cancel it. +However, +.Fn threadpool_cancel_job_async +is not enough. +.\" +.It Fn threadpool_job_done "job" +Notify that +.Fa job +is done, so that subsequent calls to +.Fn threadpool_schedule_job +will cause it to re-run its action. +.Pp +.Fn threadpool_job_done +must be called exactly once by a job's action, and may not be called in +any other context. +.\"""""""""""""""""""""""""""""""""""" +.It Fn threadpool_schedule_job "pool" "job" +Schedule +.Fa job +to run in a thread in +.Fa pool +as soon as possible, creating a new thread if necessary. +.Pp +Caller must hold the interlock of +.Fa job . +.Pp +.Fn threadpool_schedule_job +may be called in any context, including hard interrupt context, except +at interrupt priority levels above +.Vt IPL_VM . +.\" +.It Fn threadpool_cancel_job "pool" "job" +Cancel +.Fa job +if it has been scheduled but has not yet been assigned a thread, or +wait for it to complete if it has. +.Pp +Caller must hold the interlock of +.Fa job , +which may be released in order to wait for completion. +.Pp +If +.Fa job +has not been scheduled, +.Fn threadpool_cancel_job +returns immediately. +If +.Fa job +has been scheduled, it must have been scheduled in +.Fa pool , +not in any other thread pool. +.Pp +May sleep. +.\" +.It Fn threadpool_cancel_job_async "pool" "job" +Try to cancel +.Fa job +like +.Fn threadpool_cancel_job , +but if it is already running, return +.Vt false +instead of waiting; +otherwise, if it was not scheduled, or if it was scheduled and has not +yet begun to run, return +.Vt true . +.Pp +Caller must hold the interlock of +.Fa job . +.Pp +.Fn threadpool_cancel_job_async +may be called in any context, including hard interrupt context, except +at interrupt priority levels above +.Vt IPL_VM . +.\"""""""""""""""""""""""""""""""""""" +.El +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh CODE REFERENCES +The +.Nm +abstraction is implemented in +.Pa sys/kern/kern_threadpool.c . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SEE ALSO +.Xr kthread 9 , +.\" .Xr softint 9 , +.\" .Xr task 9 , +.Xr workqueue 9 diff --git a/static/netbsd/man9/time_second.9 b/static/netbsd/man9/time_second.9 new file mode 100644 index 00000000..1c1e6718 --- /dev/null +++ b/static/netbsd/man9/time_second.9 @@ -0,0 +1,111 @@ +.\" $NetBSD: time_second.9,v 1.11 2024/09/07 19:13:29 rillig Exp $ +.\" +.\" Copyright (c) 1994 Christopher G. Demetriou +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the +.\" NetBSD Project. See https://www.NetBSD.org/ for +.\" information about NetBSD. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" <<Id: LICENSE,v 1.2 2000/06/14 15:57:33 cgd Exp>> +.\" +.Dd July 16, 2023 +.Dt TIME_SECOND 9 +.Os +.Sh NAME +.Nm time_second , +.Nm time_uptime , +.Nm time_uptime32 +.Nd system time variables +.Sh SYNOPSIS +.In sys/time.h +.Vt extern const time_t time_second; +.Vt extern const time_t time_uptime; +.Vt extern const uint32_t time_uptime32; +.Sh DESCRIPTION +The +.Va time_second +variable is the system's +.Dq wall clock , +giving the number of seconds since midnight (0 hour), +January 1, 1970, (proleptic) UTC, +minus the number of leap seconds. +It is set at boot by +.Xr inittodr 9 , +and is updated periodically via +.Xr timecounter 9 +framework, and also updated by the +.Xr settimeofday 2 +system call. +.Pp +The +.Va time_uptime +variable is a monotonically increasing system clock. +It is set at boot, and is updated periodically. +(It is not updated by +.Xr settimeofday 2 . ) +.Pp +The +.Va time_uptime32 +variable is the low-order 32 bits of +.Va time_uptime , +which is cheaper to read on 32-bit platforms. +.Pp +You must only read the variables +.Va time_second , +.Va time_uptime , +and +.Va time_uptime32 ; +you may not write to them or take their addresses. +They may be implemented as macros. +.Pp +The +.Xr bintime 9 , +.Xr getbintime 9 , +.Xr microtime 9 , +.Xr getmicrotime 9 , +.Xr nanotime 9 , +and +.Xr getnanotime 9 +functions can be used to get the current time more accurately and in an +atomic manner. +.Pp +Similarly, the +.Xr binuptime 9 , +.Xr getbinuptime 9 , +.Xr microuptime 9 , +.Xr getmicrouptime 9 , +.Xr nanouptime 9 , +and +.Xr getnanouptime 9 +functions can be used to get the time elapsed since boot more accurately +and in an atomic manner. +.Sh SEE ALSO +.Xr clock_settime 2 , +.Xr ntp_adjtime 2 , +.Xr timespec 3 , +.Xr hardclock 9 , +.Xr hz 9 diff --git a/static/netbsd/man9/timecounter.9 b/static/netbsd/man9/timecounter.9 new file mode 100644 index 00000000..52fb5787 --- /dev/null +++ b/static/netbsd/man9/timecounter.9 @@ -0,0 +1,195 @@ +.\" $NetBSD: timecounter.9,v 1.11 2021/09/18 18:01:18 tsutsui Exp $ +.\" $OpenBSD: tc_init.9,v 1.4 2007/05/31 19:20:01 jmc Exp $ +.\" +.\" Copyright (c) 2004 Alexander Yurchenko <grange@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Copyright (c) 2008 Izumi Tsutsui. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 18, 2021 +.Dt TIMECOUNTER 9 +.Os +.Sh NAME +.Nm timecounter , +.Nm tc_init +.Nd machine-independent binary timescale +.Sh SYNOPSIS +.In sys/timetc.h +.Ft void +.Fn tc_init "struct timecounter *tc" +.Sh DESCRIPTION +The timecounter interface is a machine-independent implementation +of a binary timescale using whatever hardware support is at hand +for tracking time. +.Pp +A timecounter is a binary counter which has two properties: +.Bl -bullet -offset indent +.It +it runs at a fixed, known frequency; and +.It +it has sufficient bits to not roll over in less than approximately +max(2 msec, +.Pf 2/ Em HZ +seconds) (the value 2 here is really 1 + delta, for some +indeterminate value of delta). +.El +.Pp +The interface between the hardware which implements a timecounter and the +machine-independent code which uses this to keep track of time is a +.Va timecounter +structure: +.Bd -literal -offset indent +struct timecounter { + timecounter_get_t *tc_get_timecount; + timecounter_pps_t *tc_poll_pps; + u_int tc_counter_mask; + uint64_t tc_frequency; + const char *tc_name; + int tc_quality; + void *tc_priv; + struct timecounter *tc_next; +} +.Ed +.Pp +The fields of the +.Va timecounter +structure are described below. +.Bl -tag -width indent +.It Fn "u_int (*tc_get_timecount)" "struct timecounter *" +This function reads the counter. +It is not required to mask any unimplemented bits out, as long as they +are constant. +.It Fn "void (*tc_poll_pps)" "struct timecounter *" +This function is optional and can be set to +.Dv NULL . +It will be called whenever the timecounter is rewound, and is intended +to check for PPS events. +Normal hardware does not need it but timecounters which latch PPS in +hardware do. +.It Va tc_counter_mask +This mask should mask off any unimplemented bits. +.It Va tc_frequency +Frequency of the counter in Hz. +.It Va tc_name +Name of the timecounter. +Can be any NUL-terminated string. +.It Va tc_quality +Used to determine if this timecounter is better than another timecounter \- +higher means better. +Negative means +.Dq only use at explicit request . +.It Va tc_priv +Pointer to the timecounter's private parts. +.It Va tc_next +For internal use. +.El +.Pp +To register a new timecounter, +the hardware device driver should fill a +.Va timecounter +structure with appropriate values and call the +.Fn tc_init +function, giving a pointer to the structure as a +.Fa tc +parameter. +.Sh TIMESTAMP FORMAT +The timestamp format used in the machine independent timecounter +implementation is a +.Va bintime +structure: +.Bd -literal -offset indent +struct bintime { + time_t sec; + uint64_t frac; +} +.Ed +.Pp +The +.Va sec +field records the number of seconds as well as the +.Va tv_sec +field in the traditional +.Ux +.Va timeval +and +.Va timespec +structures, described in +.Xr timeval 3 . +.Pp +The +.Va frac +field records fractional seconds represented in a fully 64 bit integer, +i.e. it goes all the way from +.Li 0 +through +.Li 0xFFFFFFFFFFFFFFFF +per each second. +The effective resolution of the +.Va frac +value depends on a frequency of the machine dependent timecounter source. +.Pp +The +.Va bintime +format is a binary number, not a pseudo-decimal number, +so it can be used as a simple binary counter +without expensive 64 bit arithmetic. +.Sh CODE REFERENCES +The timecounter framework is implemented in the file +.Pa sys/kern/kern_tc.c . +The +.Va bintime +structure and related functions are defined in the file +.In sys/time.h . +.Sh SEE ALSO +.Xr clock_settime 2 , +.Xr ntp_adjtime 2 , +.Xr settimeofday 2 , +.Xr bintime 9 , +.Xr bintime_add 9 , +.Xr binuptime 9 , +.Xr hz 9 , +.Xr time_second 9 +.Rs +.%A Poul-Henning Kamp +.%T "Timecounters: Efficient and precise timekeeping in SMP kernels" +.%J "Proceedings of EuroBSDCon 2002, Amsterdam" +.%D 15-17 November, 2002 +.%U http://phk.freebsd.dk/pubs/timecounter.pdf +.Re +.Sh HISTORY +The timecounter interface first appeared in +.Fx , +and was ported to +.Nx 4.0 +by Frank Kardel and Simon Burge. diff --git a/static/netbsd/man9/todr.9 b/static/netbsd/man9/todr.9 new file mode 100644 index 00000000..39d1a002 --- /dev/null +++ b/static/netbsd/man9/todr.9 @@ -0,0 +1,132 @@ +.\" $NetBSD: todr.9,v 1.18 2014/09/10 14:28:02 martin Exp $ +.\" +.\" Copyright (c) 2000, 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Paul Kranenburg. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 10, 2014 +.Dt TODR 9 +.Os +.Sh NAME +.Nm todr_attach , +.Nm todr_gettime , +.Nm todr_settime , +.Nm clock_ymdhms_to_secs , +.Nm clock_secs_to_ymdhms +.Nd time-of-day clock support +.Sh SYNOPSIS +.In dev/clock_subr.h +.Ft void +.Fn todr_attach "todr_chip_handle_t" +.Ft int +.Fn todr_gettime "todr_chip_handle_t" "struct timeval *" +.Ft int +.Fn todr_settime "todr_chip_handle_t" "struct timeval *" +.Ft int +.Fn clock_secs_to_ymdhms "time_t" "struct clock_ymdhms *" +.Ft time_t +.Fn clock_ymdhms_to_secs "struct clock_ymdhms *" +.Sh DESCRIPTION +The +.Fn todr_* +functions provide an interface to read, set and control +.Ql time-of-day +devices. +A driver for a +.Ql time-of-day +device registers its +.Fa todr_chip_handle_t +with machine-dependent code using the +.Fn todr_attach +function. +Alternatively, a machine-dependent front-end to a +.Ql time-of-day +device driver may obtain the +.Fa todr_chip_handle_t +directly. +.Pp +The +.Fn todr_gettime +retrieves the current data and time from the TODR device and returns it +in the +.Fa struct timeval +storage provided by the caller. +.Fn todr_settime +sets the date and time in the TODR device represented by +.Fa todr_chip_handle_t +according to the +.Fa struct timeval +argument. +.Pp +The utilities +.Fn clock_secs_to_ymdhms +and +.Fn clock_ymdhms_to_secs +are provided to convert a time value in seconds to and from a structure +representing the date and time as a +.Aq year,month,day,weekday,hour,minute,seconds +tuple. +This structure is defined as follows: +.Bd -literal +struct clock_ymdhms { + uint64_t dt_year; /* Year */ + u_char dt_mon; /* Month (1-12) */ + u_char dt_day; /* Day (1-31) */ + u_char dt_wday; /* Day of week (0-6) */ + u_char dt_hour; /* Hour (0-23) */ + u_char dt_min; /* Minute (0-59) */ + u_char dt_sec; /* Second (0-59) */ +}; +.Ed +.Pp +Note: leap years are recognised by these conversion routines. +.Sh RETURN VALUES +The +.Fn todr_* +functions return 0 if the requested operation was successful; +otherwise an error code from +.In sys/errno.h +shall be returned. +However, behaviour is undefined if an invalid +.Fa todr_chip_handle_t +is passed to any of these functions. +.Pp +The +.Fn clock_ymdhms_to_secs +function returns \-1 if the time in seconds would be less that zero or too +large to fit in a +.Fa time_t . +The +.Fn clock_secs_to_ymdhms +function returns 0 on success or +.Er EINVAL +if the time passed is negative. +.Sh SEE ALSO +.Xr intersil7170 4 , +.Xr mk48txx 4 , +.Xr inittodr 9 , +.Xr resettodr 9 , +.Xr time_second 9 diff --git a/static/netbsd/man9/ts2timo.9 b/static/netbsd/man9/ts2timo.9 new file mode 100644 index 00000000..12302f86 --- /dev/null +++ b/static/netbsd/man9/ts2timo.9 @@ -0,0 +1,90 @@ +.\" $NetBSD: ts2timo.9,v 1.5 2024/10/10 11:14:28 kre Exp $ +.\" +.\" Copyright (c) 2013 Christos Zoulas +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd May 22, 2013 +.Dt TS2TIMO 9 +.Os +.Sh NAME +.Nm ts2timo +.Nd convert time interval to tick count +.Sh SYNOPSIS +.In sys/timevar.h +.Ft int +.Fn ts2timo "clock_id clock_id" "int flags" "struct timespec *ts" "int *timo" "struct timespec *start" +.Sh DESCRIPTION +The +.Fn ts2timo +function converts the time interval specified in +.Fa ts +into the integral number of system ticks that would elapse (including the +current tick) and places the result in +.Fa timo . +The interval type is specified in the +.Fa flags +argument and can be either +.Dv TIMER_ABSTIME +or +.Dv TIMER_RELTIME . +If the interval is specified as an absolute time, then the +.Fa clock_id +clock is used to calculate the corresponding relative time. +If the +.Fa start +argument is not +.Dv NULL , +then current time for the +.Fa clock_id +clock is placed in that argument. +.Sh RETURN VALUES +On success +.Fn ts2timo +returns +.Dv 0 , +and places the computed number of ticks +in the integer referenced by +.Fa timo . +On failure it returns +.Er ETIMEDOUT +if interval computed was +.Dv 0 +or negative, or +.Er EINVAL +if the +.Fa ts->tv_nsec +field is out of range, or the +.Fa clock_id +argument is invalid, or if +computing the relative time from a supplied absolute value +would cause an arithmetic overflow. +.Sh SEE ALSO +.Xr clock_gettime 2 , +.Xr clock_nanosleep 2 +.Sh HISTORY +The +.Nm +function first appeared in +.Nx 7.0 . diff --git a/static/netbsd/man9/tvtohz.9 b/static/netbsd/man9/tvtohz.9 new file mode 100644 index 00000000..7d5b7595 --- /dev/null +++ b/static/netbsd/man9/tvtohz.9 @@ -0,0 +1,67 @@ +.\" $NetBSD: tvtohz.9,v 1.7 2014/03/18 18:20:40 riastradh Exp $ +.\" +.\" Copyright (c) 2000 Kelly Yancey +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man9/tvtohz.9,v 1.4 2005/02/09 18:07:17 ru Exp $ +.\" +.Dd October 20, 2011 +.Dt TVTOHZ 9 +.Os +.Sh NAME +.Nm tvtohz +.Nd convert time interval to tick count +.Sh SYNOPSIS +.In sys/time.h +.Ft int +.Fn tvtohz "struct timeval *tv" +.Sh DESCRIPTION +The +.Fn tvtohz +function accepts a single argument +.Fa tv +which specifies the time interval over which to calculate the number +of system ticks that would elapse. +.Sh RETURN VALUES +Returns the integral number of system ticks expected to elapse in the given +interval, including the current tick. +.Sh SEE ALSO +.Xr timeval 3 , +.Xr callout 9 , +.Xr microtime 9 , +.Xr microuptime 9 , +.Xr mstohz 9 +.Sh HISTORY +The +.Nm +function first appeared in +.Fx 3.0 +and was ported to +.Nx 4.0 +as a part of +.Xr timecounter 9 +framework. +.Sh AUTHORS +This manual page was written by +.An Kelly Yancey Aq Mt kbyanc@posi.net . diff --git a/static/netbsd/man9/ubc.9 b/static/netbsd/man9/ubc.9 new file mode 100644 index 00000000..7064b12b --- /dev/null +++ b/static/netbsd/man9/ubc.9 @@ -0,0 +1,146 @@ +.\" $NetBSD: ubc.9,v 1.15 2018/05/12 15:03:19 jdolecek Exp $ +.\" +.\" Copyright (c) 1998 Matthew R. Green +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd May 12, 2018 +.Dt UBC 9 +.Os +.Sh NAME +.Nm ubc +.Nd unified buffer cache +.Sh SYNOPSIS +.In uvm/uvm.h +.Ft int +.Fn ubc_uiomove "struct uvm_object *uobj" "struct uio *uio" "vsize_t todo" \ + "int advice" "int flags" +.Ft void +.Fn ubc_zerorange "struct uvm_bject *uobj" "off_t off" "size_t len" \ + "int flags" +.Ft void +.Fn ubc_purge "struct uvm_object *uobj" +.Sh DESCRIPTION +.Fn ubc_uiomove +allocates an UBC memory window, performs I/O on it and unmaps the window. +The +.Fa advice +parameter is the access pattern hint, which must be one of +.Pp +.Bl -tag -offset indent -width "UVM_ADV_SEQUENTIAL" -compact +.It UVM_ADV_NORMAL +No hint +.It UVM_ADV_RANDOM +Random access hint +.It UVM_ADV_SEQUENTIAL +Sequential access hint (from lower offset to higher offset) +.El +.Pp +and the +.Fa flags +parameter is +.Pp +.Bl -tag -offset indent -width "UVM_ADV_SEQUENTIAL" -compact +.It UBC_READ +Mapping will be accessed for read. +.It UBC_WRITE +Mapping will be accessed for write. +.It UBC_FAULTBUSY +Fault in window's pages already during mapping operation. +Makes sense only for write. +.It UBC_UNMAP +Do not cache mapping. +.It UBC_PARTIALOK +Indicate that it is acceptable to return if an error occurs mid-transfer. +.El +.Pp +UBC memory window is a kernel mapping of +.Fa uobj +starting at offset +.Fa offset . +.Pp +Once the mapping is created, it must be accessed only by methods that can +handle faults, such as +.Xr uiomove 9 +or +.Xr kcopy 9 . +Page faults on the mapping will result in the object's pager +method being called to resolve the fault. +.Pp +Size of individual UBC memory window is limited to +.Va ubc_winsize . +.Fn ubc_uiomove +sequentially creates the UBC memory windows to eventually process +the whole range according to +.Fa offset +and +.Fa len +parameters. +.Pp +The mappings may be cached to speed future accesses to the same region +of the object, unless +.Dv UBC_UNMAP +was specified in +.Fa flags +parameter. +.Pp +.Fn ubc_zerorange +sets a range of bytes in a UVM object to zero. +The +.Fa flags +parameter takes the same arguments as +.Fn ubc_uiomove . +.Pp +.Fn ubc_purge +disassociates all UBC structures from an empty UVM object, +specified by +.Fa uobj . +.Sh CODE REFERENCES +The +.Nm +subsystem is implemented within the file +.Pa sys/uvm/uvm_bio.c . +.Sh SEE ALSO +.Xr kcopy 9 , +.Xr pmap 9 , +.Xr uiomove 9 , +.Xr uvm 9 , +.Xr vnode 9 , +.Xr vnodeops 9 +.Rs +.%A Chuck Silvers +.%T "UBC: An Efficient Unified I/O and Memory Caching Subsystem for NetBSD" +.%I USENIX Association +.%B Proceedings of the FREENIX Track: 2000 USENIX Annual Technical Conference +.%P 285-290 +.%D June 18-23, 2000 +.%U http://www.usenix.org/event/usenix2000/freenix/full_papers/silvers/silvers.pdf +.Re +.Sh HISTORY +UBC first appeared in +.Nx 1.6 . +.Sh AUTHORS +.An Chuck Silvers +.Aq Mt chuq@chuq.com +designed and implemented the UBC part of UVM, which uses UVM pages +to cache vnode data rather than the traditional buffer cache buffers. diff --git a/static/netbsd/man9/ucas.9 b/static/netbsd/man9/ucas.9 new file mode 100644 index 00000000..6995a865 --- /dev/null +++ b/static/netbsd/man9/ucas.9 @@ -0,0 +1,167 @@ +.\" $NetBSD: ucas.9,v 1.7 2021/10/04 20:25:20 andvar Exp $ +.\" +.\" Copyright (c) 2019 Jason R. Thorpe. +.\" Copyright (c) 2011 YAMAMOTO Takashi, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ------------------------------------------------------------ +.Dd March 31, 2019 +.Dt UCAS 9 +.Os +.\" ------------------------------------------------------------ +.Sh NAME +.Nm ucas +.Nd atomic memory operations on user-space address +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In sys/systm.h +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn ucas_ptr \ +"volatile void *uptr" "void *old" "void *new" "void *retp" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn ucas_int \ +"volatile int *uptr" "int old" "int new" "int *retp" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +These functions provide compare-and-swap (CAS) functionality on +user-space address. +.Pp +Except that they can be safely used for the kernel to access user-space +address, they are semantically equivalents of +.Xr atomic_cas 3 . +.Bl -tag -width uptr +.It Fa uptr +The pointer to the variable. +This should be a user-space pointer. +.It Fa old +The value to compare with the variable. +.It Fa new +The value to store to the variable. +.It Fa retp +The pointer to the memory to store the old value of the variable. +.El +.\" ------------------------------------------------------------ +.Sh IMPLEMENTATION NOTES +The +.Nm ucas +functions are implemented in machine-independent code, but rely on +machine-dependent code to implement optimized primitives, if possible. +.Pp +The basic +.Nm ucas +primitives have the following signatures and are considered private to +the implementation and are not to be called by consumers of the +.Nm ucas +API: +.Bl -tag -width _ucas_32 +.It Ft int Fn _ucas_32 \ +"volatile uint32_t *uptr" "uint32_t old" "uint32_t new" "uint32_t *retp" ; +.It Ft int Fn _ucas_64 \ +"volatile uint64_t *uptr" "uint64_t old" "uint64_t new" "uint64_t *retp" ; +.El +.Pp +If a platform is able to provide a CAS operation that meets the following +criteria, it should define +.Dv __HAVE_UCAS_FULL +in +.In machine/types.h +and provide complete machine-dependent implementations of +.Fn _ucas_32 +.Po +and +.Fn _ucas_64 , +if an +.Dv _LP64 +platform +.Pc : +.Pp +.Bl -hyphen -compact +.It +Can be implemented using either native compare-and-swap operations or +load-locked / store-conditional code sequences. +.It +Can be used on uniprocessor and multiprocessor systems. +.It +Can operate across the kernel-userspace boundary. +.El +.Pp +If +.Dv __HAVE_UCAS_FULL +is not defined, then a generic implementation will be provided by +machine-dependent code. +This generic implementation is suitable for uniprocessor and multiprocessor +systems, but works on a +.Dq least-common denominator +principle. +In particular, kernel preemption is disabled during the critical section +.Po +which is comprised of +.Xr ufetch 9 +and +.Xr ustore 9 +operations +.Pc , +and the multiprocessor implementation synchronizes with other CPUs using +interprocessor interrupts. +.Pp +If a particular platform wishes to use the generic implementation on +uniprocessors but an optimized implementation on multiprocessors, the +platform should define +.Dv __HAVE_UCAS_MP +in +.In machine/types.h +and provide +.Fn _ucas_32_mp +.Po +and +.Fn _ucas_64_mp , +if an +.Dv _LP64 +platform +.Pc . +.\" ------------------------------------------------------------ +.Sh RETURN VALUES +On success, these functions return 0. +In that case, the caller can consult the value returned via +.Fa retp +to check the result of the CAS operation. +Otherwise, these functions return an appropriate +.Xr errno 9 +error code, typically +.Dv EFAULT . +.\" ------------------------------------------------------------ +.Sh SEE ALSO +.Xr atomic_cas 3 , +.Xr intro 9 +.\" ------------------------------------------------------------ +.Sh BUGS +Conceptually, the +.Fa retp +argument of +.Fn ucas_ptr +would be of +.Dv void ** . +The current prototype is a compromise for usability. diff --git a/static/netbsd/man9/ucom.9 b/static/netbsd/man9/ucom.9 new file mode 100644 index 00000000..08c2de28 --- /dev/null +++ b/static/netbsd/man9/ucom.9 @@ -0,0 +1,231 @@ +.\" $NetBSD: ucom.9,v 1.20 2025/04/12 10:22:50 bad Exp $ +.\" +.\" Copyright (c) 2000 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 12, 2016 +.Dt UCOM 9 +.Os +.Sh NAME +.Nm ucom +.Nd interface for USB tty like devices +.Sh DESCRIPTION +The +.Nm +driver is a (relatively) easy way to make a USB device look like +a +.Xr tty 4 . +It basically takes two bulk pipes, input and output, and makes +a tty out of them. +This is useful for a number of device types, e.g., serial ports +(see +.Xr uftdi 4 ) , +modems (see +.Xr umodem 4 ) , +and devices that traditionally look like a tty (see +.Xr uvisor 4 ) . +.Pp +Communication between the real driver and the +.Nm +driver is via the attachment arguments (when attached) and +via the +.Va ucom_methods +struct +.Sh ATTACHMENT +.Bd -literal +struct ucom_attach_args { + int ucaa_portno; + int ucaa_bulkin; + int ucaa_bulkout; + u_int ucaa_ibufsize; + u_int ucaa_ibufsizepad; + u_int ucaa_obufsize; + u_int ucaa_opkthdrlen; + const char *ucaa_info; + struct usbd_device *ucaa_device; + struct usbd_interface *ucaa_iface; + const struct ucom_methods *ucaa_methods; + void *ucaa_arg; +}; +.Ed +.Pp +.Bl -tag -width indent +.It Dv int ucaa_portno +identifies the port if the devices should have more than one +.Nm +attached. +Use the value +.Dv UCOM_UNK_PORTNO +if there is only one port. +.It Dv int ucaa_bulkin +the number of the bulk input pipe. +.It Dv int ucaa_bulkout +the number of the bulk output pipe. +.It Dv u_int ucaa_ibufsize +the size of the read requests on the bulk in pipe. +.It Dv u_int ucaa_ibufsizepad +the size of the input buffer. +This is usually the same as +.Dv ibufsize . +.It Dv u_int ucaa_obufsize +the size of the write requests on the bulk out pipe. +.It Dv u_int ucaa_obufsizepad +the size of the output buffer. +This is usually the same as +.Dv ucaa_obufsize . +.It Dv struct usbd_device *ucaa_device +a handle to the device. +.It struct usbd_interface *ucaa_iface +a handle to the interface that should be used. +.It struct ucom_methods *ucaa_methods +a pointer to the methods that the +.Nm +driver should use for further communication with the driver. +.It void *ucaa_arg +the value that should be passed as first argument to each method. +.El +.Sh METHODS +The +.Dv ucom_methods +struct contains a number of function pointers used by the +.Nm +driver at various stages. +If the device is not interested in being called at a particular point +it should just use a +.Dv NULL +pointer and the +.Nm +driver will use a sensible default. +.Bd -literal +struct ucom_methods { + void (*ucom_get_status)(void *sc, int portno, + u_char *lsr, u_char *msr); + void (*ucom_set)(void *sc, int portno, int reg, int onoff); +#define UCOM_SET_DTR 1 +#define UCOM_SET_RTS 2 +#define UCOM_SET_BREAK 3 + int (*ucom_param)(void *sc, int portno, struct termios *); + int (*ucom_ioctl)(void *sc, int portno, u_long cmd, + void *data, int flag, proc_t *p); + int (*ucom_open)(void *sc, int portno); + void (*ucom_close)(void *sc, int portno); + void (*ucom_read)(void *sc, int portno, u_char **ptr, + uint32_t *count); + void (*ucom_write)(void *sc, int portno, u_char *to, + u_char *from, uint32_t *count); +}; +.Ed +.Pp +.Bl -tag -width indent +.It Fn "void (*ucom_get_status)" "void *sc" "int portno" "u_char *lsr" "u_char *msr" +get the status of port +.Fa portno . +The status consists of the line status, +.Fa lsr , +and the modem status +.Fa msr . +The contents of these two bytes is exactly as for a 16550 UART. +.It Fn "void (*ucom_set)" "void *sc" "int portno" "int reg" "int onoff" +Set (or unset) a particular feature of a port. +.It Fn "int (*ucom_param)" "void *sc" "int portno" "struct termios *t" +Set the speed, number of data bit, stop bits, and parity of a port +according to the +.Xr termios 4 +struct. +.It Fn "int (*ucom_ioctl)" "void *sc" "int portno" "u_long cmd" "void *data" "int flag" "proc_t *p" +implements any non-standard +.Xr ioctl 2 +that a device needs. +.It Fn "int (*ucom_open)" "void *sc" "int portno" +called just before the +.Nm +driver opens the bulk pipes for the port. +.It Fn "void (*ucom_close)" "void *sc" "int portno" +called just after the +.Nm +driver closes the bulk pipes for the port. +.It Fn "void (*ucom_read)" "void *sc" "int portno" "u_char **ptr" "uint32_t *count" +if the data delivered on the bulk pipe is not just the raw input characters +this routine needs to increment +.Fa ptr +by as many characters to skip from the start of the raw input and decrement +.Fa count +by as many characters to truncate from the end of the raw input. +.It Fn "void (*ucom_write)" "void *sc" "int portno" "u_char *dst" "u_char *src" "uint32_t *count" +if the data written to the bulk pipe is not just the raw characters then +this routine needs to copy +.Fa count +raw characters from +.Fa src +into the buffer at +.Fa dst +and do the appropriate padding. +The +.Fa count +should be updated to the new size. +The buffer at +.Fa src +is at most +.Va ibufsize +bytes and the buffer +at +.Fa dst +is +.Va ibufsizepad +bytes. +.El +.Pp +Apart from these methods there is a function +.Bl -tag -width 5n -offset 5n +.It Fn "void ucom_status_change" "struct ucom_softc *" +.El +.Pp +which should be called by the driver whenever it notices a status change. +.Sh SEE ALSO +.\" moscom +.Xr tty 4 , +.Xr u3g 4 , +.Xr uark 4 , +.Xr ubsa 4 , +.Xr uchcom 4 , +.Xr uftdi 4 , +.Xr ugensa 4 , +.Xr uhmodem 4 , +.Xr uipaq 4 , +.Xr ukyopon 4 , +.Xr umct 4 , +.Xr umodem 4 , +.Xr uplcom 4 , +.Xr usb 4 , +.Xr uslsa 4 , +.Xr uvisor 4 , +.Xr uvscom 4 +.Sh HISTORY +This +.Nm +interface first appeared in +.Nx 1.5 . diff --git a/static/netbsd/man9/ufetch.9 b/static/netbsd/man9/ufetch.9 new file mode 100644 index 00000000..30c14014 --- /dev/null +++ b/static/netbsd/man9/ufetch.9 @@ -0,0 +1,88 @@ +.\" $NetBSD: ufetch.9,v 1.1 2019/04/06 03:06:24 thorpej Exp $ +.\" +.\" Copyright (c) 2019 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 18, 2019 +.Dt UFETCH 9 +.Os +.Sh NAME +.Nm ufetch , +.Nm ufetch_8 , +.Nm ufetch_16 , +.Nm ufetch_32 , +.Nm ufetch_64 , +.Nm ufetch_char , +.Nm ufetch_short , +.Nm ufetch_int , +.Nm ufetch_long , +.Nm ufetch_ptr +.Nd fetch data from user-space +.Sh SYNOPSIS +.In sys/systm.h +.Ft int +.Fn ufetch_8 "const uint8_t *uaddr" "uint8_t *valp" +.Ft int +.Fn ufetch_16 "const uint16_t *uaddr" "uint16_t *valp" +.Ft int +.Fn ufetch_32 "const uint32_t *uaddr" "uint32_t *valp" +.Ft int +.Fn ufetch_64 "const uint64_t *uaddr" "uint64_t *valp" +.Ft int +.Fn ufetch_char "const unsigned char *uaddr" "unsigned char *valp" +.Ft int +.Fn ufetch_short "const unsigned short *uaddr" "unsigned short *valp" +.Ft int +.Fn ufetch_int "const unsigned int *uaddr" "unsigned int *valp" +.Ft int +.Fn ufetch_long "const unsigned long *uaddr" "unsigned long *valp" +.Ft int +.Fn ufetch_ptr "const void **uaddr" "void **valp" +.Sh DESCRIPTION +The +.Nm +functions provide a way to fetch the values of single memory cells from +user-space. +In each case, the value referenced by the user-space address +.Ar uaddr +is retrieved and stored at the kernel memory location referenced by +.Ar valp . +.Pp +The +.Nm ufetch_64 +function is only available on systems employing the +.Sq LP64 +memory model, which can be determined by testing for the presence of the +.Dv _LP64 +C preprocessor macro. +.Sh RETURN VALUES +The +.Nm +functions return 0 on success and an error number on failure. +.Sh SEE ALSO +.Xr copy 9 , +.Xr ustore 9 diff --git a/static/netbsd/man9/uiomove.9 b/static/netbsd/man9/uiomove.9 new file mode 100644 index 00000000..ad386450 --- /dev/null +++ b/static/netbsd/man9/uiomove.9 @@ -0,0 +1,182 @@ +.\" $NetBSD: uiomove.9,v 1.21 2023/05/22 14:07:24 riastradh Exp $ +.\" +.\" Copyright (c) 1996 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 9, 2023 +.Dt UIOMOVE 9 +.Os +.Sh NAME +.Nm uiomove +.Nd move data described by a struct uio +.Sh SYNOPSIS +.In sys/systm.h +.Ft int +.Fn uiomove "void *buf" "size_t n" "struct uio *uio" +.Ft int +.Fn uiopeek "void *buf" "size_t n" "struct uio *uio" +.Ft void +.Fn uioskip "void *buf" "size_t n" "struct uio *uio" +.Sh DESCRIPTION +The +.Fn uiomove +function copies up to +.Fa n +bytes between the kernel-space address pointed +to by +.Fa buf +and the addresses described by +.Fa uio , +which may be in user-space or kernel-space. +.Pp +The +.Fa uio +argument is a pointer to a +.Va struct uio +as defined by +.In sys/uio.h : +.Bd -literal -offset indent +struct uio { + struct iovec *uio_iov; + int uio_iovcnt; + off_t uio_offset; + size_t uio_resid; + enum uio_rw uio_rw; + struct vmspace *uio_vmspace; +}; +.Ed +.Pp +A +.Va struct uio +typically describes data in motion. +Several of the fields described below reflect that expectation. +.Bl -tag -width "uio_vmspace " +.It Va uio_iov +Pointer to array of +.Tn I/O +vectors to be processed. +The +.Va struct iovec +is defined to be: +.Bd -literal -offset indent +struct iovec { + void *iov_base; + size_t iov_len; +}; +.Ed +.Pp +The members in the +.Va struct iovec +should only be initialized. +These are: +.Bl -tag -width "*iov_base " -offset indent +.It Va iov_base +The address for a range of memory to or from which data is transferred. +.It Va iov_len +The number of bytes of data to be transferred to +or from the range of memory starting at +.Va iov_base . +.El +.It Va uio_iovcnt +The number of +.Tn I/O +vectors in the +.Va uio_iov +array. +.It Va uio_offset +An offset into the corresponding object. +.It Va uio_resid +The amount of space described by the structure; notionally, the amount +of data remaining to be transferred. +.It Va uio_rw +A flag indicating whether data should be read into the space +(UIO_READ) or written from the space (UIO_WRITE). +.It Va uio_vmspace +A pointer to the address space which is being transferred to or from. +.El +.Pp +The value of +.Va uio->uio_rw +controls whether +.Fn uiomove +copies data from +.Fa buf +to +.Fa uio +or vice versa. +.Pp +The lesser of +.Fa n +or +.Va uio->uio_resid +bytes are copied. +.Pp +.Fn uiomove +changes fields of the structure pointed to by +.Fa uio , +such that +.Va uio->uio_resid +is decremented by the amount of data moved, +.Va uio->uio_offset +is incremented by the same amount, and the array of iovecs is adjusted +to point that much farther into the region described. +This allows multiple calls to +.Fn uiomove +to easily be used to fill or drain the region of data. +.Pp +The +.Fn uiopeek +function copies up to +.Fa n +bytes of data without updating +.Fa uio ; +the +.Fn uioskip +function updates +.Fa uio +without copying any data, and is guaranteed never to sleep or fault +even if the buffers are in userspace and memory access via +.Fn uiomove +or +.Fn uiopeek +would trigger paging. +A successful +.Fn uiomove buf n uio +call is equivalent to a successful +.Fn uiopeek buf n uio +followed by +.Fn uioskip n uio . +.Sh RETURN VALUES +Upon successful completion, +.Fn uiomove +and +.Fn uiopeek +return 0. +If a bad address is encountered, +.Er EFAULT +is returned. +.Sh SEE ALSO +.Xr copy 9 , +.Xr ufetch 9 , +.Xr ustore 9 diff --git a/static/netbsd/man9/usbd_status.9 b/static/netbsd/man9/usbd_status.9 new file mode 100644 index 00000000..d2449504 --- /dev/null +++ b/static/netbsd/man9/usbd_status.9 @@ -0,0 +1,107 @@ +.\" $NetBSD: usbd_status.9,v 1.3 2021/12/11 19:24:19 mrg Exp $ +.\" +.\" Copyright (c) 2012 Matthew R. Green +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd May 12, 2012 +.Dt USBD_STATUS 9 +.Os +.Sh NAME +.Nm usbd_status +.Nd USB device drivers interface return status values +.Sh SYNOPSIS +.In dev/usb/usbdi.h +.Sh DESCRIPTION +This documents the full list of return values used by the generic USB code. +Interface-specific definitions will be given with interface. +.Sh RETURN VALUES +Return values are split into two main groups: expected values +and error values. +.Pp +There are only two expected values: +.Bl -tag -width indent +.It Dv USBD_NORMAL_COMPLETION +The operation completed successfully. +.It Dv USBD_IN_PROGRESS +The operation was successfully submitted, usually part of +an asynchronous operation. +.El +.Pp +These are the error values: +.Bl -tag -width indent +.It Dv USBD_PENDING_REQUESTS +The requested operation could not be completed due to pending +requests, usually from a pipe close operation. +.It Dv USBD_NOT_STARTED +The initial status of a USB transfer. +See +.Xr usbdi 9 +for more details about USB transfers. +.It Dv USBD_INVAL +Invalid arguments were supplied for the requested operation. +.It Dv USBD_NOMEM +No memory could be allocated. +.It Dv USBD_CANCELLED +The USB transfer has been cancelled, and not completed. +.It Dv USBD_BAD_ADDRESS +The requested USB pipe could not be found. +See +.Xr usbdi 9 +for more details about USB pipes. +.It Dv USBD_IN_USE +The requested operation could not be performed due to the device +having active connections, such as USB audio device currently playing. +.It Dv USBD_NO_ADDR +USB bus has reached its maximum limit of devices. +.It Dv USBD_SET_ADDR_FAILED +Call to +.Fn usbd_set_address +failed during new USB device discovery. +.It Dv USBD_NO_POWER +New device has requested more power than is available. +.It Dv USBD_TOO_DEEP +.\" XXXMRG why do we do this? it's only 5 right now. +New USB Hub too deep from the root. +.It Dv USBD_IOERROR +Non-specific error happened during IO. +.It Dv USBD_NOT_CONFIGURED +USB device is not configured; it has no configuration descriptor. +.It Dv USBD_TIMEOUT +Operation timed out. +.It Dv USBD_SHORT_XFER +USB transfer succeeded but not all requested data was returned. +.It Dv USBD_STALLED +USB controller has stalled (controller specific.) +.It Dv USBD_INTERRUPTED +Process was interrupted by external means (such as a signal) while +waiting for a transfer to complete. +.El +.Sh SEE ALSO +.Xr usb 4 , +.Xr usbdi 9 +.Sh HISTORY +This +.Nm +interface first appeared in +.Nx 1.4 . diff --git a/static/netbsd/man9/usbdi.9 b/static/netbsd/man9/usbdi.9 new file mode 100644 index 00000000..3441acc8 --- /dev/null +++ b/static/netbsd/man9/usbdi.9 @@ -0,0 +1,987 @@ +.\" $NetBSD: usbdi.9,v 1.37 2022/08/14 19:12:23 skrll Exp $ +.\" +.\" Copyright (c) 2012 Matthew R. Green +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.\" Copyright (c) 1999, 2016 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson and Nick Hudson. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 24, 2016 +.Dt USBDI 9 +.Os +.Sh NAME +.Nm usbdi +.Nd USB device drivers interface +.Sh SYNOPSIS +.In dev/usb/usb.h +.In dev/usb/usbdi.h +.In dev/usb/usbdi_util.h +.Ss Functions offered by usbdi.h +.Ft usbd_status +.Fn usbd_open_pipe "struct usbd_interface *iface" "uint8_t address" \ + "uint8_t flags" "struct usbd_pipe **pipe" +.Ft usbd_status +.Fn usbd_close_pipe "struct usbd_pipe *pipe" +.Ft usbd_status +.Fn usbd_transfer "struct usbd_xfer *xfer" +.Ft struct usbd_xfer * +.Fn usbd_setup_xfer "struct usbd_xfer *xfer" \ + "void *priv" "void *buffer" "uint32_t length" \ + "uint16_t flags" "uint32_t timeout" "usbd_callback" +.Ft void +.Fn usbd_setup_default_xfer "struct usbd_xfer *xfer" \ + "struct usbd_device *dev" "void *priv" \ + "uint32_t timeout" "usb_device_request_t *req" " void *buffer" \ + "uint32_t length" "uint16_t flags" "usbd_callback" +.Ft void +.Fn usbd_setup_isoc_xfer "struct usbd_xfer *xfer" \ + "void *priv" "uint16_t *frlengths" \ + "uint32_t nframes" "uint16_t flags" "usbd_callback" +.Ft void +.Fn usbd_get_xfer_status "struct usbd_xfer *xfer" "void **priv" \ + "void **buffer" "uint32_t *count" "usbd_status *status" +.Ft usb_endpoint_descriptor_t * +.Fn usbd_interface2endpoint_descriptor "struct usbd_interface *iface" \ + "uint8_t address" +.Ft usbd_status +.Fn usbd_abort_pipe "struct usbd_pipe *pipe" +.Ft usbd_status +.Fn usbd_abort_default_pipe "struct usbd_device *dev" +.Ft usbd_status +.Fn usbd_clear_endpoint_stall "struct usbd_pipe *pipe" +.Ft usbd_status +.Fn usbd_clear_endpoint_stall_async "struct usbd_pipe *pipe" +.Ft void +.Fn usbd_clear_endpoint_toggle "struct usbd_pipe *pipe" +.Ft usbd_status +.Fn usbd_endpoint_count "struct usbd_interface *dev" "uint8_t *count" +.Ft usbd_status +.Fn usbd_interface_count "struct usbd_device *dev" "uint8_t *count" +.Ft usbd_status +.Fn usbd_interface2device_handle "struct usbd_interface *iface" "struct usbd_device **dev" +.Ft usbd_status +.Fn usbd_device2interface_handle "struct usbd_device *dev" "uint8_t ifaceno" "struct usbd_interface **iface" +.Pp +.Ft struct usbd_device * +.Fn usbd_pipe2device_handle "struct usbd_pipe *pipe" +.Ft int +.Fn usbd_create_xfer "struct usbd_pipe *pipe" "size_t len" \ +"unsigned int flags" "unsigned int nframes" "struct usbd_xfer **xp" +.Ft void +.Fn usbd_destroy_xfer "struct usbd_xfer *xfer" +.Ft void * +.Fn usbd_get_buffer "struct usbd_xfer *xfer" +.Ft usbd_status +.Fn usbd_sync_transfer "struct usbd_xfer *req" +.Ft usbd_status +.Fn usbd_sync_transfer_sig "struct usbd_xfer *req" +.Ft usbd_status +.Fn usbd_open_pipe_intr "struct usbd_interface *iface" "uint8_t address" \ + "uint8_t flags" "struct usbd_pipe **pipe" \ + "void *priv" "void *buffer" \ + "uint32_t length" "usbd_callback callback" "int interval" +.Ft usbd_status +.Fn usbd_do_request "struct usbd_device *dev" "usb_device_request_t *req" \ + "void *data" +.Ft usbd_status +.Fn usbd_do_request_flags "struct usbd_device *dev" \ + "usb_device_request_t *req" "void *data" "uint16_t flags" "int *actlen" \ + "uint32_t timo" +.Ft usb_interface_descriptor_t * +.Fn usbd_get_interface_descriptor "struct usbd_interface *iface" +.Ft usb_config_descriptor_t * +.Fn usbd_get_config_descriptor "struct usbd_device *dev" +.Ft usb_device_descriptor_t * +.Fn usbd_get_device_descriptor "struct usbd_device *dev" +.Ft usbd_status +.Fn usbd_set_interface "struct usbd_interface *iface" "int altidx" +.Ft int +.Fn usbd_get_no_alts "usb_config_descriptor_t *iface" "int ifaceno" +.Ft usbd_status +.\" unused, delete? +.\" .Fn usbd_get_interface "struct usbd_interface *iface" "uint8_t *aiface" +.\" .Ft void +.Fn usbd_fill_deviceinfo "struct usbd_device *dev" "struct usb_device_info *di" +.Ft int +.Fn usbd_get_interface_altindex "struct usbd_interface *iface" +.Ft usb_endpoint_descriptor_t * +.Fn usbd_get_endpoint_descriptor "struct usbd_interface *dev" \ + "uint8_t address" +.Ft usb_interface_descriptor_t * +.Fn usbd_find_idesc "usb_config_descriptor_t *cd" "int iindex" "int ano" +.Ft usb_endpoint_descriptor_t * +.Fn usbd_find_edesc "usb_config_descriptor_t *cd" "int ifaceidx" "int altidx" \ + "int endptidx" +.Ft void +.Fn usbd_dopoll "struct usbd_interface *iface" +.Ft void +.Fn usbd_set_polling "struct usbd_device *iface" "int val" +.Ft const char * +.Fn usbd_errstr "usbd_status err" +.Ft void +.Fn usbd_add_dev_event "int type" "struct usbd_device *iface" +.Ft void +.Fn usbd_add_drv_event "int type" "struct usbd_device *iface" "device_t dv" +.Ft char * +.Fn usbd_devinfo_alloc "struct usbd_device *iface" "int showclass" +.Ft void +.Fn usbd_devinfo_free "char *str" +.Ft const struct usbd_quirks * +.Fn usbd_get_quirks "struct usbd_device *iface" +.Ft usbd_status +.Fn usbd_reload_device_desc "struct usbd_device *iface" +.Ft int +.Fn usbd_ratecheck "struct timeval *tv" +.Ft usbd_status +.Fn usbd_get_string "struct usbd_device *iface" "int si" "char *buf" +.Ft usbd_status +.Fn usbd_get_string0 "struct usbd_device *iface" "int si" "char *buf" \ + "int unicode" +.Ft void +.Fn usb_desc_iter_init "struct usbd_device *iface" "usbd_desc_iter_t *iter" +.Ft const usb_descriptor_t * +.Fn usb_desc_iter_next "usbd_desc_iter_t *iter" +.Ft void +.Fn usb_add_task "struct usbd_device *iface" "struct usb_task *task" \ + "int queue" +.Ft void +.Fn usb_rem_task "struct usbd_device *iface" "struct usb_task *task" +.Ft void +.Fn usb_init_task "struct usb_task *task" "void (*func)(void *)" \ + "void *arg" uint8_t flags +.Ft const struct usb_devno * +.Fn usb_lookup "const struct usb_devno *tbl" \ + "uint16_t vendor" "uint16_t product" +.Ss Obsolete functions +The following functions have been obsoleted from +.Dv usbdi.h . +.Ft void * +.Fn usbd_alloc_buffer "struct usbd_xfer *xfer" "uint32_t size" +.Ft void +.Fn usbd_free_buffer "struct usbd_xfer *xfer" +.Ss Utilities from usbdi_util.h +Based on the routines in +.Dv usbdi.h +a number of utility functions have been defined that are accessible +through +.Dv usbdi_util.h . +.Ft usbd_status +.Fn usbd_get_desc "struct usbd_device *dev" "int type" "int index" \ + "int len" "void *desc" +.Ft usbd_status +.Fn usbd_get_config_desc "struct usbd_device *dev" "int confidx" \ + "usb_config_descriptor_t *d" +.Ft usbd_status +.Fn usbd_get_config_desc_full "struct usbd_device *" "int dev" "void *d" "int size" +.Ft usbd_status +.Fn usbd_get_device_desc "struct usbd_device *dev" \ + "usb_device_descriptor_t *d" +.Ft usbd_status +.Fn usbd_set_address "struct usbd_device *dev" "int addr" +.Ft usbd_status +.Fn usbd_get_port_status "struct usbd_device *dev" "int port" "usb_port_status_t *ps" +.Ft usbd_status +.Fn usbd_set_hub_feature "struct usbd_device *dev" "int sel" +.Ft usbd_status +.Fn usbd_clear_hub_feature "struct usbd_device *dev" "int sel" +.Ft usbd_status +.Fn usbd_set_port_feature "struct usbd_device *dev" "int port" "int sel" +.Ft usbd_status +.Fn usbd_clear_port_feature "struct usbd_device *dev" "int port" "int sel" +.Ft usbd_status +.Fn usbd_get_device_status "struct usbd_device *dev" "usb_status_t *st" +.Ft usbd_status +.Fn usbd_get_hub_status "struct usbd_device *dev" "usb_hub_status_t *st" +.Ft usbd_status +.Fn usbd_set_protocol "struct usbd_interface *dev" "int report" +.Ft usbd_status +.Fn usbd_get_report_descriptor "struct usbd_device *dev" "int ifcno" "int repid" "int size" "void *d" +.Ft struct usb_hid_descriptor * +.Fn usbd_get_hid_descriptor "struct usbd_interface *ifc" +.Ft usbd_status +.Fn usbd_set_report "struct usbd_interface *iface" "int type" "int id" "void *data" "int len" +.Ft usbd_status +.Fn usbd_set_report_async "struct usbd_interface *iface" "int type" "int id" "void *data" "int len" +.Ft usbd_status +.Fn usbd_get_report "struct usbd_interface *iface" "int type" "int id" "void *data" "int len" +.Ft usbd_status +.Fn usbd_set_idle "struct usbd_interface *iface" "int duration" "int id" +.Ft usbd_status +.Fn usbd_alloc_report_desc "struct usbd_interface *ifc" "void **descp" \ + "int *sizep" "int mem" +.\" private API between ugen(4) and usbdi(9) +.\" .Ft usbd_status +.\" .Fn usbd_get_config "struct usbd_device *dev" "uint8_t *conf" +.Ft usbd_status +.Fn usbd_get_string_desc "struct usbd_device *dev" "int sindex" "int langid" \ + "usb_string_descriptor_t *sdesc" +.Ft void +.Fn usbd_delay_ms "struct usbd_device *dev" "u_int ms" +.Ft usbd_status +.Fn usbd_set_config_no "struct usbd_device *dev" "int no" "int msg" +.Ft usbd_status +.Fn usbd_set_config_index "struct usbd_device *dev" "int index" "int msg" +.Ft usbd_status +.Fn usbd_bulk_transfer "struct usbd_xfer *xfer" "struct usbd_pipe *pipe" \ + "uint16_t flags" "uint32_t timeout" "void *buf" "uint32_t *size" +.Ft usbd_status +.Fn usbd_intr_transfer "struct usbd_xfer *xfer" "struct usbd_pipe *pipe" \ + "uint16_t flags" "uint32_t timeout" "void *buf" "uint32_t *size" +.Ft void +.Fn usb_detach_waitold "device_t dv" +.Ft void +.Fn usb_detach_wakeupold "device_t dv" +.Ft void +.Fn usb_detach_wait "device_t dv" "kcondvar_t *cv" "kmutex_t *lk" +.Ft void +.Fn usb_detach_broadcast "device_t dv" "kcondvar_t *cv" +.Sh DESCRIPTION +Device driver access to the USB bus centers around transfers. +A transfer describes a communication with a USB device. +A transfer is an abstract concept that can result in several +physical packets being transferred to or from a device. +A transfer is described by the +.Va struct usbd_xfer * +cookie. +A pipe is a logical connection to a USB device. +It is described by the +.Va struct usbd_pipe * +cookie. +See the +.Sx TRANSFERS +and +.Sx PIPES +sections for more details. +.Pp +There are a number of functions to obtain a handle, descriptor +or resource count: +.Bl -tag -width 10n +.It Fn usbd_device2interface_handle dev ifaceno iface +Fills in +.Fa iface +with the +.Ft struct usbd_interface * +for the USB device +.Fa dev +on interface number +.Fa ifaceno . +.It Fn usbd_interface2device_handle iface dev +Fills in +.Fa dev +with the +.Ft struct usbd_device * +pointer for interface +.Fa iface . +.\" usbd_pipe2device_handle is unused; remove from usbdi? +.It Fn usbd_pipe2device_handle pipe +Returns the +.Ft struct usbd_device * +associated with +.Fa pipe . +.It Fn usbd_interface2endpoint_descriptor iface address +Returns the +.Ft usb_endpoint_descriptor_t * +for the particular interface +.Fa iface +at address +.Fa address . +.\" XXX describe what a .Ft usb_endpoint_descriptor_t is. +.It Fn usbd_endpoint_count dev count +.It Fn usbd_interface_count dev count +Fills in +.Fa count +with the number of endpoint or interfaces the USB device +.Fa dev +has. +.El +.Pp +Error handling and other return values are described in +.Xr usbd_status 9 . +.Pp +Additional comments on particular functions: +.Bl -tag -width 10n +.It Fn usbd_errstr err +Returns the string associated with +.Fa err . +.It Fn usbd_add_dev_event type iface +The +.Ar type +must be one of +.Dv USB_EVENT_CTRLR_ATTACH , +.Dv USB_EVENT_CTRLR_DETACH , +.Dv USB_EVENT_DEVICE_ATTACH +and +.Dv USB_EVENT_DEVICE_DETACH . +.It Fn usbd_add_drv_event type iface dv +The +.Fa type +must be one of +.Dv USB_EVENT_DRIVER_ATTACH +and +.Dv USB_EVENT_DRIVER_DETACH . +The +.Fa dv +corresponds with the +.Ft device_t +associated with the device attached or detached. +.It Fn usb_lookup tbl vendor product +Lookup a USB device. +The returned +.Va struct usb_devno +pointer has these members: +.Bl -item -offset offset -compact +.It +.Vt uint16_t ud_vendor ; +.It +.Vt uint16_t ud_product ; +.El +The +.Dv USB_PRODUCT_ANY +macro can be used to match any USB product by a particular vendor. +.El +.\" +.\" XXX functions missing descriptions in usbdi.h XXX +.\" +.\" .Fn usbd_get_interface_descriptor "struct usbd_interface *iface" +.\" .Fn usbd_get_config_descriptor "struct usbd_device *dev" +.\" .Fn usbd_get_device_descriptor "struct usbd_device *dev" +.\" .Fn usbd_get_no_alts "usb_config_descriptor_t *iface" "int ifaceno" +.\" unused, delete? +.\" .Fn usbd_get_interface "struct usbd_interface *iface" "uint8_t *aiface" +.\" .Fn usbd_fill_deviceinfo "struct usbd_device *dev" "struct usb_device_info *di" +.\" .Fn usbd_get_interface_altindex "struct usbd_interface *iface" +.\" .Fn usbd_get_endpoint_descriptor "struct usbd_interface *dev" \ +.\" "uint8_t address" +.\" .Fn usbd_find_idesc "usb_config_descriptor_t *cd" "int iindex" "int ano" +.\" .Fn usbd_find_edesc "usb_config_descriptor_t *cd" "int ifaceidx" "int altidx" \ +.\" "int endptidx" +.\" .Fn usbd_dopoll "struct usbd_interface *iface" +.\" .Fn usbd_set_polling" struct usbd_device *iface" "int val" +.\" +.\" .Fn usbd_add_dev_event "int type" "struct usbd_device *iface" +.\" .Fn usbd_add_drv_event "int type" "struct usbd_device *iface" "device_t dv" +.\" +.\" .Fn usbd_devinfo_alloc "struct usbd_device *iface" "int showclass" +.\" .Fn usbd_devinfo_free "char *str" +.\" +.\" .Fn usbd_get_quirks "struct usbd_device *iface" +.\" .Fn usbd_reload_device_desc "struct usbd_device *iface" +.\" .Fn usbd_ratecheck "struct timeval *tv" +.\" .Fn usbd_get_string "struct usbd_device *iface" "int si" "char *buf" +.\" .Fn usbd_get_string0 "struct usbd_device *iface" "int" si "char *buf" \ +.\" "int unicode" +.\" +.\" .Fn usb_desc_iter_init "struct usbd_device *iface" "usbd_desc_iter_t *iter" +.\" .Fn usb_desc_iter_next "usbd_desc_iter_t *iter" +.\" +.\" XXX functions missing descriptions in usbdi.h XXX +.\" +.\" .Dv usbdi_util.h . +.\" .Ft usbd_status +.\" .Fn usbd_get_desc "struct usbd_device *dev" "int type" "int index" \ +.\" "int len" "void *desc" +.\" .Ft usbd_status +.\" .Fn usbd_get_config_desc "struct usbd_device *dev" "int confidx" \ +.\" "usb_config_descriptor_t *d" +.\" .Ft usbd_status +.\" .Fn usbd_get_config_desc_full "struct usbd_device *" "int dev" "void *d" "int size" +.\" .Ft usbd_status +.\" .Fn usbd_get_device_desc "struct usbd_device *dev" \ +.\" "usb_device_descriptor_t *d" +.\" .Ft usbd_status +.\" .Fn usbd_set_address "struct usbd_device *dev" "int addr" +.\" .Ft usbd_status +.\" .Fn usbd_get_port_status "struct usbd_device *dev" "intp ort" "usb_port_status_t *ps" +.\" .Ft usbd_status +.\" .Fn usbd_set_hub_feature "struct usbd_device *dev" "int sel" +.\" .Ft usbd_status +.\" .Fn usbd_clear_hub_feature "struct usbd_device *dev" "int sel" +.\" .Ft usbd_status +.\" .Fn usbd_set_port_feature "struct usbd_device *dev" "int port" "int sel" +.\" .Ft usbd_status +.\" .Fn usbd_clear_port_feature "struct usbd_device *dev" "int port" "int sel" +.\" .Ft usbd_status +.\" .Fn usbd_get_device_status "struct usbd_device *dev" "usb_status_t *st" +.\" .Ft usbd_status +.\" .Fn usbd_get_hub_status "struct usbd_device *dev" "usb_hub_status_t *st" +.\" .Ft usbd_status +.\" .Fn usbd_set_protocol "struct usbd_interface *dev" "int report" +.\" .Ft usbd_status +.\" .Fn usbd_get_report_descriptor "struct usbd_device *dev" "int ifcno" "int repid" "int size" "void *d" +.\" .Ft struct usb_hid_descriptor * +.\" .Fn usbd_get_hid_descriptor "struct usbd_interface *ifc" +.\" .Ft usbd_status +.\" .Fn usbd_set_report "struct usbd_interface *iface" "nt type" "int id" "void *data" "int len" +.\" .Ft usbd_status +.\" .Fn usbd_set_report_async "struct usbd_interface *iface" "int type" "int id" "void *data" "int len" +.\" .Ft usbd_status +.\" .Fn usbd_get_report "struct usbd_interface *iface" "int type" "int id" "void *data" "int len" +.\" .Ft usbd_status +.\" .Fn usbd_set_idle "struct usbd_interface *iface" "int duration" "int id" +.\" .Ft usbd_status +.\" .Fn usbd_alloc_report_desc "struct usbd_interface *ifc" "void **descp" \ +.\" "int *sizep" "int mem" +.\" .Ft usbd_status +.\" .Fn usbd_get_string_desc "struct usbd_device *dev" "int sindex" "int langid" \ +.\" "usb_string_descriptor_t *sdesc" +.\" .Ft void +.\" .Fn usbd_delay_ms "struct usbd_device *dev" "u_int ms" +.\" .Ft usbd_status +.\" .Fn usbd_set_config_no "struct usbd_device *dev" "int no" "int msg" +.\" .Ft usbd_status +.\" .Fn usbd_set_config_index "struct usbd_device *dev" "int index" "int msg" +.\" .Ft usbd_status +.\" +.Sh PIPES +Pipes are created and destroyed by using the +.Fn usbd_open_pipe , +.Fn usbd_open_pipe_intr +and +.Fn usbd_close_pipe +functions. +The open functions take the interface handle +.Fa iface , +the +.Fa address +of this pipe and +.Fa flags +for this pipe which currently may be 0, or a combination of +.Dv USBD_EXCLUSIVE_USE , +to enable exclusive access to this interface and address, and +.Dv USBD_MPSAFE , +to allow running transfer callbacks on this pipe without first acquiring +.Dv kernel_lock . +The +.Fn usbd_open_pipe_intr +takes additional arguments +.Fa priv +to set the default private handle. +.Fa buffer +and +.Fa len +to describe the buffer to be used, +.Fa callback +for the function to call at interrupt time, and finally the +.Fa interval +for interrupts to be delivered in milliseconds. +The +.Fa interval +may be set to +.Dv USBD_DEFAULT_INTERVAL +use the default interval, specified by the ep. description. +It is common to have more than one pipe per device. +.Sh TRANSFERS +Transfers are created and destroyed with +.Fn usbd_create_xfer +and +.Fn usbd_destroy_xfer , +respectively, and are associated with a pipe at their creation time. +The create function takes the pipe handle +.Fa pipe , +the length of the largest transfer possible +.Fa len , +possible transfer flags +.Fa flags , +the number of isochronous frames (or 0) in +.Fa nframes . +.Pp +The data describing the transfer is filled by either +.Fn usbd_setup_default_xfer +for control pipe transfers, by +.Fn usbd_setup_xfer +for bulk and interrupt transfers, and by +.Fn usbd_setup_isoc_xfer +for isochronous transfers. +Private data may be passed between setup and completion or status +calls using the +.Ft void *priv +argument. +.Pp +Arguments to the setup functions include the newly allocated +.Fa xfer , +the private data +.Fa priv , +the +.Fa timeout +in milliseconds, +for control, bulk and interrupt transfers +.Fa buffer +the data to transfer and its +.Fa length +and for isochronous transfers the frame length +.Fa frlengths +and number of frames +.Fa nframes , +and for default transfers a USB request structure +.Fa req +must be presented. +See the +.Sx INITIALISING USB REQUESTS +section for more details on USB requests. +.Pp +The transfer specific +.Fa flags +that can be set are: +.Bl -tag -width 10n +.It Dv USBD_SYNCHRONOUS +Wait for completion +.It Dv USBD_SYNCHRONOUS_SIG +When waiting for completion, allow signals to trigger wake up. +.It Dv USBD_SHORT_XFER_OK +Short reads are not an error +.It Dv USBD_FORCE_SHORT_XFER +Force last short packet on write +.El +.Pp +The +.Fn usbd_get_buffer +function returns the current kernel address for the buffer suitable for +transfer in +.Fa xfer . +.Pp +The +.Fn usbd_open_pipe , +.Fn usbd_open_pipe_intr , +.Fn usbd_close_pipe , +.Fn usbd_alloc_xfer , +and +.Fn usbd_free_xfer +can all sleep and should not be called from interrupt context as a result. +.Pp +Upon completion the +.Fa callback +function is called, which takes the completed +.Fa xfer , +the private data +.Fa priv +originally associated with this transfer, and +.Fa status +the status of this transfer. +.Pp +Transfers are initiated by calling +.Fn usbd_transfer , +and their results made be later obtained by calling +.Fa usbd_get_xfer_status , +which fills in the private data +.Fa priv , +original buffer location +.Fa buffer , +the length +.Fa length , +and the +.Fa status +of this request. +.Pp +The +.Fn usbd_bulk_transfer +and +.Fn usbd_intr_transfer +functions are used to transfer data in either an interrupt or +bulk fashion, and are front-ends to the +.Fn usbd_setup_xfer , +.Fn usbd_transfer +and +.Fn usbd_get_xfer_status , +as well as associated error handling. +The +.Fn usbd_sync_transfer +is identical to +.Fn usbd_transfer +with the +.Dv USBD_SYNCHRONOUS +flag set. +The +.Fn usbd_sync_transfer_sig +is identical to +.Fn usbd_transfer +with the +.Dv USBD_SYNCHRONOUS +and +.Dv USBD_SYNCHRONOUS_SIG +flags set. +.Pp +Transfers are aborted via this pipe with +.Fn usbd_abort_pipe +and +.Fn usbd_abort_default_pipe . +.Pp +The +.Fn usbd_clear_endpoint_stall +and +.Fn usbd_clear_endpoint_stall_async +functions are used to clear endpoint halt in either a synchronous +or asynchronous fashion. +To clear the toggle state of an endpoint the +.Fn usbd_clear_endpoint_toggle +function should be used. +.Pp +A request is described by a +.Va usb_device_request_t +which must be initialised as necessary before calling either +.Fn usbd_do_request +or +.Fn usbd_do_request_flags +to submit the request. +For both these functions +.Fa dev +is the handle of the USB device the request is for, +.Fa req +is the USB request, as described in the +.Sx INITIALISING USB REQUESTS +section, and then +.Fa data +is a buffer containing the data +.\" (if any)???? +for the request. +For the +.Fn usbd_do_request_flags +function there are additional +.Fa flags +passed to the +.Fa usbd_setup +function, +.Fa actlen +a pointer to fill in with the actual length of this request, and +.Fa timo , +the number of milliseconds to wait before timing out this request. +.Sh INITIALISING USB REQUESTS +There are 5 members of a +.Va usb_device_request_t +that must be initialised: +.Pp +.Bl -item -offset offset -compact +.It +.Vt uByte bmRequestType ; +.It +.Vt uByte bRequest ; +.It +.Vt uWord wValue ; +.It +.Vt uWord wIndex ; +.It +.Vt uWord wLength ; +.El +.Pp +The first two are normal byte values that may be simply assigned, +but the last three must be initialised with the +.Fn USETW +macro. +.Pp +The +.Fa bmRequestType +holds the request type of this USB request, which describes the +intended recipient of the request. +.Pp +This may be one of: +.Bl -tag -width UT_WRITEXX -offset offset -compact +.It Dv UT_WRITE +.It Dv UT_READ +.El +.Pp +with one of: +.Bl -tag -width UT_STANDARDXX -offset offset -compact +.It Dv UT_STANDARD +.It Dv UT_CLASS +.It Dv UT_VENDOR +.El +.Pp +and with one of: +.Bl -tag -width UT_INTERFACEXX -offset offset -compact +.It Dv UT_DEVICE +.It Dv UT_INTERFACE +.It Dv UT_ENDPOINT +.It Dv UT_OTHER +.El +.Pp +These are also in combinations as: +.Bl -tag -width UT_WRITE_VENDOR_INTERFACEXX -offset offset -compact +.It Dv UT_READ_DEVICE +.It Dv UT_READ_INTERFACE +.It Dv UT_READ_ENDPOINT +.It Dv UT_WRITE_DEVICE +.It Dv UT_WRITE_INTERFACE +.It Dv UT_WRITE_ENDPOINT +.It Dv UT_READ_CLASS_DEVICE +.It Dv UT_READ_CLASS_INTERFACE +.It Dv UT_READ_CLASS_OTHER +.It Dv UT_READ_CLASS_ENDPOINT +.It Dv UT_WRITE_CLASS_DEVICE +.It Dv UT_WRITE_CLASS_INTERFACE +.It Dv UT_WRITE_CLASS_OTHER +.It Dv UT_WRITE_CLASS_ENDPOINT +.It Dv UT_READ_VENDOR_DEVICE +.It Dv UT_READ_VENDOR_INTERFACE +.It Dv UT_READ_VENDOR_OTHER +.It Dv UT_READ_VENDOR_ENDPOINT +.It Dv UT_WRITE_VENDOR_DEVICE +.It Dv UT_WRITE_VENDOR_INTERFACE +.It Dv UT_WRITE_VENDOR_OTHER +.It Dv UT_WRITE_VENDOR_ENDPOINT +.El +.Pp +The +.Fa bRequest +describes which request is being made. +The available values are: +.Bl -tag -width UR_GET_DESCRIPTORXX -offset offset -compact +.It Dv UR_GET_STATUS +.It Dv UR_CLEAR_FEATURE +.It Dv UR_SET_FEATURE +.It Dv UR_SET_ADDRESS +.It Dv UR_GET_DESCRIPTOR +.It Dv UR_SET_DESCRIPTOR +.\" these have API front ends +.\" .It Dv UR_GET_CONFIG +.\" api usbd_get_config() (ugen private) +.\" .It Dv UR_SET_CONFIG +.\" static api usbd_set_config() (usb_subr private) +.\" .It Dv UR_GET_INTERFACE +.\" .It Dv UR_SET_INTERFACE +.\" this isn't supported +.\" .It Dv UR_SYNCH_FRAME +.El +.Pp +The +.Fa wValue , +.Fa wIndex +and +.Fa wLength +are device-specific values and must be initialised with the +.Fn USETW +macro. +.Sh USB REQUEST TYPES AND STRUCTURES +The +.Dv UR_GET_STATUS +request operates on a +.Va usb_status_t +structure, which has this member: +.Bl -item -offset offset -compact +.It +.Vt uWord wStatus ; +.El +.Pp +For device status requests the +.Fa wStatus +member may have either of these bit flags set: +.Bl -tag -width UDS_REMOTE_WAKEUPXX -offset offset -compact +.It Dv UDS_SELF_POWERED +.It Dv UDS_REMOTE_WAKEUP +.El +.Pp +For endpoint status requests the +.Fa wStatus +member may have this bit flag set: +.Bl -tag -width UES_HALTXX -offset offset -compact +.It Dv UES_HALT +.El +.Pp +The +.Dv UR_CLEAR_FEATURE +and +.Dv UR_SET_FEATURE +requests clear or set special features on USB devices. +The values for +.Va wValue , +.Va wIndex +and +.Va wLength +depend upon the device and device type. +.Pp +The +.Dv UR_SET_ADDRESS +request sets the virtual USB address of a port using the +.Va wValue . +.Pp +The +.Dv UR_GET_DESCRIPTOR +and +.Dv UR_SET_DESCRIPTOR +requests operate on a +.Va usb_descriptor_t +structure, which has these members: +.Bl -item -offset offset -compact +.It +.Vt uByte bLength ; +.It +.Vt uByte bDescriptorType ; +.El +.Pp +The +.Fa bDescriptorType +member may be one of the following values: +.Bl -tag -width UDESC_OTHER_SPEED_CONFIGURATIONXX -offset offset -compact +.It Dv UDESC_DEVICE +.It Dv UDESC_CONFIG +.It Dv UDESC_STRING +.It Dv UDESC_INTERFACE +.It Dv UDESC_ENDPOINT +.It Dv UDESC_DEVICE_QUALIFIER +.It Dv UDESC_OTHER_SPEED_CONFIGURATION +.It Dv UDESC_INTERFACE_POWER +.It Dv UDESC_OTG +.It Dv UDESC_DEBUG +.It Dv UDESC_INTERFACE_ASSOC +.It Dv UDESC_CS_DEVICE +.It Dv UDESC_CS_CONFIG +.It Dv UDESC_CS_STRING +.It Dv UDESC_CS_INTERFACE +.It Dv UDESC_CS_ENDPOINT +.It Dv UDESC_HUB +.El +.Pp +The +.\" XXXMRG is the below even remotely valid? +.Fn usbd_set_interface +function can be used to change the index used for transfers on this +interface as obtained via +.Fn usbd_device2interface_handle . +.Sh USB DEVICE DETACHMENT +There are two functions available to ease the detach of active devices. +Typically a reference count is maintained on syscall activity. +When a USB device is to be detached, the reference count should be +decremented and if it is greater or equal to zero, +.Fn usb_detach_wait +should be called on the +.Ft dv +associated with this USB device and, typically, a device-specific +condition variable +.Fa cv . +and mutex +.Fa lk +protecting this reference count state. +At the end of each syscall function, if the reference count is decremented +to less than zero, then +.Fn usb_detach_broadcast +must be called on the +.Ft dv +and +.Fa cv +that is being waited on with +.Fn usb_detach_wait . +.Pp +The are another pair of functions with similar functionality that do not +use a condition variable or mutex and should be avoided in new code. +The +.Fn usb_detach_waitold +function works like +.Fn usb_detach_wait , +and the +.Fn usb_detach_wakeupold +function works like +.Fn usb_detach_broadcast . +.\" XXX add an actual code example. +.Sh USB TASK MANAGEMENT +The USB stack provides a task management framework to execute tasks +in a thread context at the soonest opportunity. +Typically this is used by network drivers to handle periodic updates +or status change requests, or other operations that need to run in +a normal context. +.Pp +The +.Fn usb_init_task +function takes a pointer to a +.Ft struct usb_task +that will be initialised, a function to call for this task +.Fa func , +the argument to pass to +.Fa func , +.Fa arg , +and the task flags +.Fa flags . +If the +.Fa flags +argument is +.Dv USB_TASKQ_MPSAFE , +the +.Fa func +function will be called without first acquiring +.Dv kernel_lock . +.Pp +To invoke the task callback the +.Fn usb_add_task +function should be called with the +.Fa iface +associated with this device, the task structure +.Fa task , +and the +.Fa queue +to run against, either +.Dv USB_TASKQ_HC +for operations initiated by host controllers or +.Dv USB_TASKQ_DRIVER +for operations initiated by USB drivers. +.Pp +To deschedule a potentially running task the +.Fn usb_rem_task +function should be called. +.Pp +The driver using these facilities is expected to provide the +necessary serialisation between +.Fn usb_init_task , +.Fn usb_add_task +and +.Fn usb_rem_task +for each specific +.Ft struct usb_task . +.Sh SEE ALSO +.Xr usb 4 , +.Xr usbd_status 9 +.Sh HISTORY +This +.Nm +interface first appeared in +.Nx 1.4 . +The interface is based on an early definition from the OpenUSBDI group +within the USB organisation. +Right after this definition the OpenUSBDI development got closed for open +source developers, so this interface has not followed the further changes. +The OpenUSBDI specification is now available again, but looks different. +.Sh BUGS +This manual is under development, so its biggest shortcoming is +incompleteness. diff --git a/static/netbsd/man9/usbnet.9 b/static/netbsd/man9/usbnet.9 new file mode 100644 index 00000000..f87f2a0f --- /dev/null +++ b/static/netbsd/man9/usbnet.9 @@ -0,0 +1,827 @@ +.\" $NetBSD: usbnet.9,v 1.23 2026/01/26 00:19:29 gutteridge Exp $ +.\" +.\" Copyright (c) 2019 Matthew R. Green +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 15, 2020 +.Dt USBNET 9 +.Os +.Sh NAME +.Nm usbnet +.Nd common USB Ethernet driver framework +.Sh SYNOPSIS +.In dev/usb/usbnet.h +.Ss Functions offered by usbnet.h +.Ft void +.Fn usbnet_set_link "struct usbnet *un" "bool link" +.Ft struct ifnet * +.Fn usbnet_ifp "struct usbnet *un" +.Ft struct ethercom * +.Fn usbnet_ec "struct usbnet *un" +.Ft struct mii_data * +.Fn usbnet_mii "struct usbnet *un" +.Ft krndsource_t * +.Fn usbnet_rndsrc "struct usbnet *un" +.Ft void * +.Fn usbnet_softc "struct usbnet *un" +.Ft bool +.Fn usbnet_havelink "struct usbnet *un" +.Ft int +.Fn usbnet_ispromisc "struct usbnet *un" +.Ft bool +.Fn usbnet_isdying "struct usbnet *un" +.Ft void +.Fn usbnet_enqueue "struct usbnet *un" "uint8_t *buf" "size_t buflen" "int csum_flags" "uint32_t csum_data" "int mbuf_flags" +.Ft void +.Fn usbnet_input "struct usbnet *un" "uint8_t *buf" "size_t buflen" +.Ft void +.Fn usbnet_attach "struct usbnet *un" +.Ft void +.Fn usbnet_attach_ifp "struct usbnet *un" "unsigned if_flags" "unsigned if_extflags" "const struct usbnet_mii *unm" +.Ft int +.Fn usbnet_detach "device_t dev" "int flags" +.Ft int +.Fn usbnet_activate "device_t dev" "devact_t act" +.Sh DESCRIPTION +The +.Nm +framework provides methods usable for USB Ethernet drivers. +The framework has support for these features: +.Bl -bullet -offset 8n +.It +Partial autoconf handling +.It +USB endpoint pipe handling +.It +Rx and Tx chain handling +.It +Generic handlers or support for several struct ifnet callbacks +.It +Network stack locking protocol +.It +Interrupt handling +.El +.Pp +.Nm +provides many or all of the traditional +.Dq softc +members inside +.Va struct usbnet , +which can be used directly as the device softc structure if +no additional storage is required. +A structure exists for receive and transmit chain management, +.Va struct usbnet_chain , +that tracks the metadata for each transfer descriptor available, +minimum of one each for Rx and Tx slots, and will be passed +to the Rx and Tx callbacks. +.Pp +There is a +.Va struct usbnet_ops +structure that provides a number of optional and required callbacks +that will be described below. +.Pp +For autoconfiguration the device attach routine is expected to +ensure that this device's +.Va struct usbnet +is the first member of the device softc, if it can not be used directly +as the device softc, as well as set up the necessary structure members, +find end-points, find the Ethernet address if relevant, call +.Fn usbnet_attach , +set up interface, Ethernet, and MII capabilities, and finally call +.Fn usbnet_attach_ifp . +The device detach routine should free any resources allocated +by attach and then call +.Fn usbnet_detach , +possibly directly using +.Fn usbnet_detach +as most consumers have no additional resources not owned and +released by the +.Nm +framework itself. +The device activate function should be set to +.Fn usbnet_activate . +.Pp +When bringing an interface up from +.Xr if_init 9 , +which happens under +.Xr IFNET_LOCK 9 , +.Nm +will: +.Bl -enum +.It +call +.Dq uno_init +to initialize the hardware for sending and receiving packets, +.It +open the USB pipes, +.It +allocate Rx and Tx buffers for transfers, +.It +call +.Dq uno_mcast +to initially program the hardware multicast filter, and finally +.It +start the Rx transfers so packets can be received. +.El +.Pp +See the +.Sx RECEIVE AND SEND +section for details on using the chains. +.Pp +When bringing an interface down from +.Xr if_stop 9 , +which happens under +.Xr IFNET_LOCK 9 , +.Nm +will: +.Bl -enum +.It +abort the USB pipes, +.It +call +.Dq uno_stop +to stop the hardware from receiving packets (unless the device is +detaching), +.It +free Rx and Tx buffers for transfers, and +.It +close the USB pipes. +.El +.Pp +For interface ioctl, most of the handling is in the framework. +While the interface is running, the optional +.Dq uno_mcast +callback is invoked after handling the +.Dv SIOCADDMULTI +and +.Dv SIOCDELMULTI +ioctl commands to update the hardware's multicast filter from the +.Xr ethersubr 9 +lists. +The optional +.Dq uno_ioctl +callback, which is invoked under +.Xr IFNET_LOCK 9 , +can be used to program special settings like offload handling. +.Pp +If ioctl handling requires capturing device-specific ioctls then the +.Dq uno_override_ioctl +callback may be used instead to replace the framework's +ioctl handler completely (i.e., the replacement should call any generic +ioctl handlers such as +.Fn ether_ioctl +as required). +For sending packets, the +.Dq uno_tx_prepare +callback must be used to convert +an mbuf into a chain buffer ready for transmission. +.Pp +For devices requiring MII handling there are callbacks for reading and +writing registers, and for status change events. +Access to all the MII functions is serialized by +.Nm . +.Pp +As receive must handle the case of multiple packets in one buffer, +the support is split between the driver and the framework. +A +.Dq uno_rx_loop +callback must be provided that loops over the incoming +packet data found in a chain, performs necessary checking, and passes +the network frame up the stack via either +.Fn usbnet_enqueue +or +.Fn usbnet_input . +Typically Ethernet devices prefer +.Fn usbnet_enqueue . +.Pp +General accessor functions for +.Fa struct usbnet : +.Bl -tag -width 4n +.It Fn usbnet_set_link un link +Set the link status for this +.Fa un +to +.Fa link . +.It Fn usbnet_ifp un +Returns pointer to this +.Fa un Ns 's +.Va struct ifnet . +.It Fn usbnet_ec un +Returns pointer to this +.Fa un Ns 's +.Va struct ethercom . +.It Fn usbnet_mii un +Returns pointer to this +.Fa un Ns 's +.Va struct mii_data . +.It Fn usbnet_rndsrc un +Returns pointer to this +.Fa un Ns 's +.Va krndsource_t . +.It Fn usbnet_softc un +Returns pointer to this +.Fa un Ns 's +device softc. +.It Fn usbnet_havelink un +Returns true if link is active. +.It Fn usbnet_ispromisc un +True if +.Dv IFF_PROMISC +is enabled, false if not. +.Pp +May be used only in +.Dq uno_init +and +.Dq uno_mcast . +.Pp +Drivers must use this in +.Dq uno_mcast +instead of reading +.Li ifp->if_flags . +.It Fn usbnet_isdying un +Returns true if device is dying (has been pulled or deactivated, +pending detach). +This should be used only to abort timeout loops early. +.El +.Pp +Buffer enqueue handling for +.Fa struct usbnet : +.Bl -tag -width 4n +.It Fn usbnet_enqueue un buf buflen csum_flags csum_data mbuf_flags +Enqueue buffer +.Fa buf +for length +.Fa buflen +with higher layers, using the provided +.Fa csum_flags , +and +.Fa csum_data , +which are written directly to the mbuf packet header, and +.Fa mbuf_flags , +which is or-ed into the mbuf flags for the created mbuf. +.It Fn usbnet_input un buf buflen +Enqueue buffer +.Fa buf +for length +.Fa buflen +with higher layers. +.El +.Pp +Autoconfiguration handling for +.Fa struct usbnet . +See the +.Sx AUTOCONFIGURATION +section for more details about these functions. +.Bl -tag -width 4n +.It Fn usbnet_attach un +Initial stage attach of a USB network device. +Performs internal initialization and memory allocation only \(em +nothing is published yet. +.It Fn usbnet_attach_ifp un if_flags if_extflags unm +Final stage attach of a USB network device. +Publishes the network interface to the rest of the system. +.Pp +If the passed in +.Fa unm +is +.Pf non- Dv NULL +then an MII interface will be created using the values +provided in the +.Fa struct usbnet_mii +structure, which has these members passed to +.Fn mii_attach : +.Bl -tag -width "un_mii_capmask" +.It un_mii_flags +Flags. +.It un_mii_capmask +Capability mask. +.It un_mii_phyloc +PHY location. +.It un_mii_offset +PHY offset. +.El +.Pp +A default +.Fa unm +can be set using the +.Fn USBNET_MII_DECL_DEFAULT +macro. +The +.Fa if_flags +and +.Fa if_extflags +will be or-ed into the interface flags and extflags. +.It Fn usbnet_detach dev flags +Device detach. +Stops all activity and frees memory. +Usable as +.Xr driver 9 +detach method. +.It Fn usbnet_activate dev act +Device activate (deactivate) method. +Usable as +.Xr driver 9 +activate method. +.El +.Sh AUTOCONFIGURATION +The framework expects the usbnet structure to have these members +filled in with valid values or functions: +.Bl -tag -width 6n +.It un_sc +Real softc allocated by autoconf and provided to attach, should be +set to the usbnet structure if no device-specific softc is needed. +.It un_dev +device_t saved in attach, used for messages mostly. +.It un_iface +The USB iface handle for data interactions, see +.Fn usbd_device2interface_handle +for more details. +.It un_udev +The struct usbd_device for this device, provided as the usb_attach_arg's +.Va uaa_device +member. +.It un_ops +Points to a +.Va struct usbnet_ops +structure which contains these members: +.Bl -tag -width 4n +.It Ft void Fn (*uno_stop) "struct ifnet *ifp" "int disable" +Stop hardware activity +.Pq optional . +Called under +.Xr IFNET_LOCK 9 +when bringing the interface down, but skipped when the device is +detaching. +.It Ft int Fn (*uno_ioctl) "struct ifnet *ifp" "u_long cmd" "void *data" +Handle driver-specific ioctls +.Pq optional . +Called under +.Xr IFNET_LOCK 9 . +.It Ft void Fn (*uno_mcast) "struct ifnet *" +Program hardware multicast filters from +.Xr ethersubr 9 +lists +.Pq optional . +Called between, and not during, +.Dq uno_init +and +.Dq uno_stop . +.It Ft int Fn (*uno_override_ioctl) "struct ifnet *ifp" "u_long cmd" "void *data" +Handle all ioctls, including standard ethernet ioctls normally handled +internally by +.Nm +.Pq optional . +May or may not be called under +.Xr IFNET_LOCK 9 . +.It Ft int Fn (*uno_init) "struct ifnet *ifp" +Initialize hardware activity +.Pq optional . +Called under +.Xr IFNET_LOCK 9 +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 only called after +.Dq uno_init +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 only called after +.Dq uno_init +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 only called after +.Dq uno_init +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 +and +.Dq uno_stop . +.It Ft void Fn (*uno_rx_loop) "struct usbnet *un" "struct usbnet_chain *c" "uint32_t total_len" +Prepare one or more chain for enqueue. +Required. +Called sequentially between, and not during, +.Dq uno_init +and +.Dq uno_stop . +.It Ft void Fn (*uno_intr) "struct usbnet *un" "usbd_status status" +Process periodic interrupt +.Pq optional . +Called sequentially between, and not during, +.Dq uno_init +and +.Dq uno_stop . +.It Ft void Fn (*uno_tick) "struct usbnet *un" +Called every second with USB task thread context +.Pq optional . +Called sequentially between, and not during, +.Dq uno_init +and +.Dq uno_stop . +.El +.It un_intr +Points to a +.Va struct usbnet_intr +structure which should have these members set: +.Bl -tag -width 4n +.It uni_buf +If +.Pf non- Dv NULL , +points to a buffer passed to +.Fn usbd_open_pipe_intr +in the device init callback, along with the size and interval. +.It uni_bufsz +Size of interrupt pipe buffer. +.It uni_interval +Frequency of the interrupt in milliseconds. +.El +.It un_ed +Array of endpoint descriptors. +There indexes are provided: +.Dv USBNET_ENDPT_RX , +.Dv USBNET_ENDPT_TX , +and +.Dv USBNET_ENDPT_INTR . +The Rx and Tx endpoints are required. +.It un_phyno +MII phy number. +Not used by +.Nm . +.It un_eaddr +6 bytes of Ethernet address that must be provided before calling +.Fn usbnet_attach_ifp +if the device has Ethernet. +.It un_flags +Device owned flags word. +The +.Nm +framework will not touch this value. +.It un_rx_xfer_flags +Passed to +.Fn usbd_setup_xfer +for receiving packets. +.It un_tx_xfer_flags +Passed to +.Fn usbd_setup_xfer +for sending packets. +.It un_rx_list_cnt +Number of chain elements to allocate for Rx. +.It un_tx_list_cnt +Number of chain elements to allocate for Tx. +.It un_rx_bufsz +Rx buffer size. +.It un_tx_bufsz +Tx buffer size. +.El +.Pp +The device detach and activate callbacks can typically be set to +.Fn usbnet_detach +and +.Fn usbnet_activate +unless device-specific handling is required, in which case, they +can be called before or after such handling. +.Pp +The capabilities described in both +.Va struct ifp +and +.Va struct ethercom +must be set before calling +.Fn usbnet_attach_ifp . +.Sh RECEIVE AND SEND +Receive and send routines are structured around the +.Va usbnet_cdata +and +.Va usbnet_chain +structures, the +.Dv un_ed , +.Dv un_rx_xfer_flags , +and +.Dv un_tx_xfer_flags +members, and the +.Fn uno_init , +.Fn uno_tx_prepare , +.Fn uno_rx_loop , +and +.Fn uno_stop +callbacks of +.Va usbnet_ops . +.Pp +Typically, the device attach routine will fill in members of the +.Va usbnet +structure, as listed in +.Sx AUTOCONFIGURATION . +The +.Dv un_ed +array should have the +.Dv USBNET_ENDPT_RX +and +.Dv USBNET_ENDPT_TX +array entries filled in, and optionally the +.Dv USBNET_ENDPT_INTR +entry filled in if applicable. +.Pp +The +.Fn uno_init +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 +.Fn uno_rx_loop +callback, called sequentially, converts the provided +.Va usbnet_chain +data and length into a series (one or more) of packets that are +enqueued with the higher layers using either +.Fn usbnet_enqueue +(for most devices) or +.Fn usbnet_input +for devices that use +.Fn if_input . +(This currently relies upon the +.Va struct ifnet +having the +.Dq _if_input +member set as well, which is true for current consumers.) +.Pp +The +.Fn uno_tx_prepare +callback must convert the provided +.Va struct mbuf +into the provided +.Va struct usbnet_chain +performing any device-specific padding, checksum, header or other. +Note that this callback must check that it is not attempting to copy +more than the chain buffer size, as set in the +.Va usbnet +.Dq un_tx_bufsz +member. +This callback is only called once per packet, sequentially. +.Pp +The +.Fa struct usbnet_chain +structure which contains a +.Dq unc_buf +member which has the chain buffer allocated where data should be +copied to or from for receive or transmit operations. +It also contains pointers back to the owning +.Fa struct usbnet , +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 +must be provided: +.Bl -tag -width 4n +.It uno_read_reg +Read an MII register for a particular PHY. +Returns standard +.Xr errno 2 . +Must initialize the result even on failure. +.It uno_write_reg +Write an MII register for a particular PHY. +Returns standard +.Xr errno 2 . +.It uno_statchg +Handle a status change event for this interface. +.El +.Sh INTERRUPT PIPE +The interrupt-specific callback, +.Dq uno_intr , +is an optional callback that can be called periodically, registered by +.Nm +using the +.Fn usbd_open_pipe_intr +function (instead of the +.Fn usbd_open_pipe +function). +The +.Nm +framework provides most of the interrupt handling and the callback +simply inspects the returned buffer as necessary. +To enable this callback point the +.Va struct usbnet +member +.Dq un_intr +to a +.Va struct usbnet_intr +structure with these members set: +.Bl -tag -width 4n +.It uni_buf +Data buffer for interrupt status replies. +.It uni_bufsz +Size of the above buffer. +.It uni_interval +Interval in millieconds. +.El +.Pp +These values will be passed to +.Fn usbd_open_pipe_intr . +.Sh CONVERTING OLD-STYLE DRIVERS +The porting of an older driver to the +.Nm +framework is largely an effort in deleting code. +The process involves making these changes: +.Bl -tag -width 4n +.It Headers +Many headers are included in +.Pa usbnet.h +and can be removed from the driver, as well as headers no longer used, +such as +.Pa callout.h +and +.Pa rndsource.h , +etc. +.It Device softc +The majority of the driver's existing +.Dq softc +structure can likely be replaced with usage of +.Va struct usbnet +and its related functionality. +This includes at least the device_t pointer, Ethernet address, the +ethercom and mii_data structures, end point descriptors, usbd device, +interface, and task and callout structures (both these probably go +away entirely) and all the associated watchdog handling, +timevals, list size, buffer size and xfer flags for +both Rx, and Tx, and interrupt notices, interface flags, device link, +PHY number, chain data, locks including Rx, Tx, and MII. +There is a driver-only +.Dq un_flags +in the +.Va usbnet +structure available for drivers to use. +.Pp +Many drivers can use the +.Va usbnet +structure as the device private storage passed to +.Dv CFATTACH_DECL_NEW . +Many internal functions to the driver may look better if switched to +operate on the device's +.Va usbnet +as, for example, the +.Va usbd_device +value is now available (and must be set by the driver) in the +.Va usbnet , +which may be needed for any call to +.Fn usbd_do_request . +The standard endpoint values must be stored in the +.Nm +.Dq un_ed[] +array. +.Pp +As +.Nm +manages xfer chains all code related to the opening, closing, aborting +and transferring of data on pipes is performed by the framework based +upon the buffer size and more provided in +.Va subnet , +so all code related to them should be deleted. +.It Interface setup +The vast majority of interface-specific code should be deleted. +For device-specific interface values, the +.Va ifnet +flags and exflags can be set, as well as the +.Va ethercom +.Dq ec_capabilities +member, before calling +.Fn usbnet_attach_ifp . +All calls to +.Fn ifmedia_init , +.Fn mii_attach , +.Fn ifmedia_add , +.Fn ifmedia_set , +.Fn if_attach , +.Fn ether_ifattach , +.Fn rnd_attach_source , +and +.Fn usbd_add_drv_event +should be eliminated. +The device +.Dq ioctl +routine can use the default handling with a callback for additional +device-specific programming (multicast filters, etc.), which can be +empty, or, the override ioctl can be used for heavier requirements. +The device +.Dq stop +routine is replaced with a simple call that turns off the +device-specific transmitter and receiver if necessary, as the +framework handles pipes and transfers and buffers. +.It MII handling +For devices with MII support the three normal callbacks +.Pq read, write, and status change +must be converted to +.Va usbnet . +Local +.Dq link +variables need to be replaced with accesses to +.Fn usbnet_set_link +and +.Fn usbnet_havelink . +Other ifmedia callbacks that were passed to +.Fn ifmedia_init +should be deleted and any work moved into +.Dq uno_statchg . +.It Receive and Transmit +The +.Nm +framework handles the majority of handling of both network directions. +The interface init routine should keep all of the device-specific setup +but replace all pipe management with a call to +.Fn usbnet_init_rx_tx . +The typical receive handling will normally be replaced with a receive +loop function that can accept one or more packets, +.Dq uno_rx_loop , +which can use either +.Fn usbnet_enqueue +or +.Fn usbnet_input +to pass the packets up to higher layers. +The typical interface +.Dq if_start +function and any additional functions used will normally be replaced +with a relatively simple +.Dq uno_tx_prepare +function that simply converts an +.Va mbuf +into a +.Va usbnet_chain +useful for this device that will be passed onto +.Fn usbd_transfer . +The framework's handling of the Tx interrupt is all internal. +.It Interrupt pipe handling +For devices requiring special handling of the interrupt pipe (i.e., +they use the +.Fn usbd_open_pipe_intr +method), most of the interrupt handler should be deleted, leaving +only code that inspects the result of the interrupt transfer. +.It Common errors +It's common to forget to set link active on devices with MII. +Be sure to call +.Fn usbnet_set_link +during any status change event. +.Pp +Many locking issues are hidden without +.Dv LOCKDEBUG , +including hard-hangs. +It's highly recommended to develop with +.Dv LOCKDEBUG . +.Pp +The +.Va usbnet +.Dq un_ed +array is unsigned and should use +.Dq 0 +as the no-endpoint value. +.El +.Sh SEE ALSO +.Xr usb 4 , +.Xr driver 9 , +.Xr usbd_status 9 , +.Xr usbdi 9 +.Sh HISTORY +This +.Nm +interface first appeared in +.Nx 9.0 . +Portions of the original design are based upon ideas from +.An Nick Hudson Aq Mt skrll@NetBSD.org . +.Sh AUTHORS +.An Matthew R. Green Aq Mt mrg@eterna23.net diff --git a/static/netbsd/man9/userret.9 b/static/netbsd/man9/userret.9 new file mode 100644 index 00000000..8653faa9 --- /dev/null +++ b/static/netbsd/man9/userret.9 @@ -0,0 +1,81 @@ +.\" $NetBSD: userret.9,v 1.9 2008/04/30 13:10:59 martin Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 20, 2005 +.Dt USERRET 9 +.Os +.Sh NAME +.Nm userret +.Nd return path to user-mode execution +.Sh SYNOPSIS +.In sys/lwp.h +.In sys/sched.h +.Ft void +.Fn userret "struct lwp *l" +.Sh DESCRIPTION +The +.Fn userret +function is executed after processing a trap +.Pq e.g., a system call or interrupt +before returning to user-mode execution. +The implementation is machine dependent and is never invoked from +machine-independent code. +The function prototype for each architecture may be different to the +prototype above, however the functionally provided by the +.Fn userret +function on each architecture is essentially the same. +.Pp +Specifically, the +.Fn userret +function performs the following procedure: +.Bl -bullet -offset indent +.It +Detect a change in the signal disposition of the current process and invoke +.Xr postsig 9 +to post the signal to the process. +This may occur when the outcome of the trap or syscall posted a signal +to the process +.Pq e.g., invalid instruction trap . +.It +Check the +.Va want_resched +flag to see if the scheduler requires the current process to be +preempted by invoking +.Xr preempt 9 +.Pq see Xr cpu_need_resched 9 . +This may occur if the clock interrupt causes the scheduler to +determine that the current process has completed its time slice. +.It +Update the scheduler state. +.El +.Sh SEE ALSO +.Xr cpu_need_resched 9 , +.Xr postsig 9 , +.Xr preempt 9 , +.Xr scheduler 9 diff --git a/static/netbsd/man9/ustore.9 b/static/netbsd/man9/ustore.9 new file mode 100644 index 00000000..a29b925d --- /dev/null +++ b/static/netbsd/man9/ustore.9 @@ -0,0 +1,88 @@ +.\" $NetBSD: ustore.9,v 1.2 2019/04/06 07:56:19 wiz Exp $ +.\" +.\" Copyright (c) 2019 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 18, 2019 +.Dt USTORE 9 +.Os +.Sh NAME +.Nm ustore , +.Nm ustore_8 , +.Nm ustore_16 , +.Nm ustore_32 , +.Nm ustore_64 , +.Nm ustore_char , +.Nm ustore_short , +.Nm ustore_int , +.Nm ustore_long , +.Nm ustore_ptr +.Nd store data in user-space +.Sh SYNOPSIS +.In sys/systm.h +.Ft int +.Fn ustore_8 "const uint8_t *uaddr" "uint8_t val" +.Ft int +.Fn ustore_16 "const uint16_t *uaddr" "uint16_t val" +.Ft int +.Fn ustore_32 "const uint32_t *uaddr" "uint32_t val" +.Ft int +.Fn ustore_64 "const uint64_t *uaddr" "uint64_t val" +.Ft int +.Fn ustore_char "const unsigned char *uaddr" "unsigned char val" +.Ft int +.Fn ustore_short "const unsigned short *uaddr" "unsigned short val" +.Ft int +.Fn ustore_int "const unsigned int *uaddr" "unsigned int val" +.Ft int +.Fn ustore_long "const unsigned long *uaddr" "unsigned long val" +.Ft int +.Fn ustore_ptr "const void **uaddr" "void *val" +.Sh DESCRIPTION +The +.Nm +functions provide a way to store a value to single memory cells in +user-space. +In each case, the value +.Ar val +is stored in the user-space memory location referenced by +.Ar uaddr . +.Pp +The +.Nm ustore_64 +function is only available on systems employing the +.Sq LP64 +memory model, which can be determined by testing for the presence of the +.Dv _LP64 +C preprocessor macro. +.Sh RETURN VALUES +The +.Nm +functions return 0 on success and an error number on failure. +.Sh SEE ALSO +.Xr copy 9 , +.Xr ufetch 9 diff --git a/static/netbsd/man9/uvm.9 b/static/netbsd/man9/uvm.9 new file mode 100644 index 00000000..da91a74c --- /dev/null +++ b/static/netbsd/man9/uvm.9 @@ -0,0 +1,710 @@ +.\" $NetBSD: uvm.9,v 1.116 2026/03/22 11:25:12 yamt Exp $ +.\" +.\" Copyright (c) 1998 Matthew R. Green +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 23, 2015 +.Dt UVM 9 +.Os +.Sh NAME +.Nm uvm +.Nd virtual memory system external interface +.Sh SYNOPSIS +.In sys/param.h +.In uvm/uvm.h +.Sh DESCRIPTION +The UVM virtual memory system manages access to the computer's memory +resources. +User processes and the kernel access these resources through +UVM's external interface. +UVM's external interface includes functions that: +.Pp +.Bl -hyphen -compact +.It +initialize UVM sub-systems +.It +manage virtual address spaces +.It +resolve page faults +.It +memory map files and devices +.It +perform uio-based I/O to virtual memory +.It +allocate and free kernel virtual memory +.It +allocate and free physical memory +.El +.Pp +In addition to exporting these services, UVM has two kernel-level processes: +pagedaemon and swapper. +The pagedaemon process sleeps until physical memory becomes scarce. +When that happens, pagedaemon is awoken. +It scans physical memory, paging out and freeing memory that has not +been recently used. +The swapper process swaps in runnable processes that are currently swapped +out, if there is room. +.Pp +There are also several miscellaneous functions. +.Sh INITIALIZATION +.Bl -ohang +.It Ft void +.Fn uvm_init "void" ; +.It Ft void +.Fn uvm_init_limits "struct lwp *l" ; +.It Ft void +.Fn uvm_setpagesize "void" ; +.It Ft void +.Fn uvm_swap_init "void" ; +.El +.Pp +.Fn uvm_init +sets up the UVM system at system boot time, after the +console has been setup. +It initializes global state, the page, map, kernel virtual memory state, +machine-dependent physical map, kernel memory allocator, +pager and anonymous memory sub-systems, and then enables +paging of kernel objects. +.Pp +.Fn uvm_init_limits +initializes process limits for the named process. +This is for use by the system startup for process zero, before any +other processes are created. +.Pp +.Fn uvm_md_init +does early boot initialization. +This currently includes: +.Fn uvm_setpagesize +which initializes the uvmexp members pagesize (if not already done by +machine-dependent code), pageshift and pagemask. +.Fn uvm_physseg_init +which initialises the +.Xr uvm_hotplug 9 +subsystem. +It should be called by machine-dependent code early in the +.Fn pmap_init +call (see +.Xr pmap 9 ) . +.Pp +.Fn uvm_swap_init +initializes the swap sub-system. +.Sh VIRTUAL ADDRESS SPACE MANAGEMENT +See +.Xr uvm_map 9 . +.Sh PAGE FAULT HANDLING +.Bl -ohang +.It Ft int +.Fn uvm_fault "struct vm_map *orig_map" "vaddr_t vaddr" "vm_prot_t access_type" ; +.El +.Pp +.Fn uvm_fault +is the main entry point for faults. +It takes +.Fa orig_map +as the map the fault originated in, a +.Fa vaddr +offset into the map the fault occurred, and +.Fa access_type +describing the type of access requested. +.Fn uvm_fault +returns a standard UVM return value. +.Sh MEMORY MAPPING FILES AND DEVICES +See +.Xr ubc 9 . +.Sh VIRTUAL MEMORY I/O +.Bl -ohang +.It Ft int +.Fn uvm_io "struct vm_map *map" "struct uio *uio" ; +.El +.Pp +.Fn uvm_io +performs the I/O described in +.Fa uio +on the memory described in +.Fa map . +.Sh ALLOCATION OF KERNEL MEMORY +See +.Xr uvm_km 9 . +.Sh ALLOCATION OF PHYSICAL MEMORY +.Bl -ohang +.It Ft struct vm_page * +.Fn uvm_pagealloc "struct uvm_object *uobj" "voff_t off" "struct vm_anon *anon" "int flags" ; +.It Ft void +.Fn uvm_pagerealloc "struct vm_page *pg" "struct uvm_object *newobj" "voff_t newoff" ; +.It Ft void +.Fn uvm_pagefree "struct vm_page *pg" ; +.It Ft int +.Fn uvm_pglistalloc "psize_t size" "paddr_t low" "paddr_t high" "paddr_t alignment" "paddr_t boundary" "struct pglist *rlist" "int nsegs" "int waitok" ; +.It Ft void +.Fn uvm_pglistfree "struct pglist *list" ; +.It Ft void +.Fn uvm_page_physload "paddr_t start" "paddr_t end" "paddr_t avail_start" "paddr_t avail_end" "int free_list" ; +.El +.Pp +.Fn uvm_pagealloc +allocates a page of memory at virtual address +.Fa off +in either the object +.Fa uobj +or the anonymous memory +.Fa anon , +which must be locked by the caller. +Only one of +.Fa uobj +and +.Fa anon +can be non +.Dv NULL . +Returns +.Dv NULL +when no page can be found. +The flags can be any of +.Bd -literal +#define UVM_PGA_USERESERVE 0x0001 /* ok to use reserve pages */ +#define UVM_PGA_ZERO 0x0002 /* returned page must be zero'd */ +.Ed +.Pp +.Dv UVM_PGA_USERESERVE +means to allocate a page even if that will result in the number of free pages +being lower than +.Dv uvmexp.reserve_pagedaemon +(if the current thread is the pagedaemon) or +.Dv uvmexp.reserve_kernel +(if the current thread is not the pagedaemon). +.Dv UVM_PGA_ZERO +causes the returned page to be filled with zeroes, either by allocating it +from a pool of pre-zeroed pages or by zeroing it in-line as necessary. +.Pp +.Fn uvm_pagerealloc +reallocates page +.Fa pg +to a new object +.Fa newobj , +at a new offset +.Fa newoff . +.Pp +.Fn uvm_pagefree +frees the physical page +.Fa pg . +If the content of the page is known to be zero-filled, +caller should set +.Dv PG_ZERO +in pg->flags so that the page allocator will use +the page to serve future +.Dv UVM_PGA_ZERO +requests efficiently. +.Pp +.Fn uvm_pglistalloc +allocates a list of pages for size +.Fa size +byte under various constraints. +.Fa low +and +.Fa high +describe the lowest and highest addresses acceptable for the list. +If +.Fa alignment +is non-zero, it describes the required alignment of the list, in +power-of-two notation. +If +.Fa boundary +is non-zero, no segment of the list may cross this power-of-two +boundary, relative to zero. +.Fa nsegs +is the maximum number of physically contiguous segments. +If +.Fa waitok +is non-zero, the function may sleep until enough memory is available. +(It also may give up in some situations, so a non-zero +.Fa waitok +does not imply that +.Fn uvm_pglistalloc +cannot return an error.) +The allocated memory is returned in the +.Fa rlist +list; the caller has to provide storage only, the list is initialized by +.Fn uvm_pglistalloc . +.Pp +.Fn uvm_pglistfree +frees the list of pages pointed to by +.Fa list . +If the content of the page is known to be zero-filled, +caller should set +.Dv PG_ZERO +in pg->flags so that the page allocator will use +the page to serve future +.Dv UVM_PGA_ZERO +requests efficiently. +.Pp +.Fn uvm_page_physload +loads physical memory segments into VM space on the specified +.Fa free_list . +It must be called at system boot time to set up physical memory +management pages. +The arguments describe the +.Fa start +and +.Fa end +of the physical addresses of the segment, and the available start and end +addresses of pages not already in use. +If a system has memory banks of +different speeds the slower memory should be given a higher +.Fa free_list +value. +.\" XXX expand on "system boot time"! +.Sh PROCESSES +.Bl -ohang +.It Ft void +.Fn uvm_pageout "void" ; +.It Ft void +.Fn uvm_scheduler "void" ; +.El +.Pp +.Fn uvm_pageout +is the main loop for the page daemon. +.Pp +.Fn uvm_scheduler +is the process zero main loop, which is to be called after the +system has finished starting other processes. +It handles the swapping in of runnable, swapped out processes in priority +order. +.Sh PAGE LOAN +.Bl -ohang +.It Ft int +.Fn uvm_loan "struct vm_map *map" "vaddr_t start" "vsize_t len" "void *v" "int flags" ; +.It Ft void +.Fn uvm_unloan "void *v" "int npages" "int flags" ; +.El +.Pp +.Fn uvm_loan +loans pages in a map out to anons or to the kernel. +.Fa map +should be unlocked, +.Fa start +and +.Fa len +should be multiples of +.Dv PAGE_SIZE . +Argument +.Fa flags +should be one of +.Bd -literal +#define UVM_LOAN_TOANON 0x01 /* loan to anons */ +#define UVM_LOAN_TOPAGE 0x02 /* loan to kernel */ +.Ed +.Pp +.Fa v +should be pointer to array of pointers to +.Li struct anon +or +.Li struct vm_page , +as appropriate. +The caller has to allocate memory for the array and +ensure it's big enough to hold +.Fa len / PAGE_SIZE +pointers. +Returns 0 for success, or appropriate error number otherwise. +Note that wired pages can't be loaned out and +.Fn uvm_loan +will fail in that case. +.Pp +.Fn uvm_unloan +kills loans on pages or anons. +The +.Fa v +must point to the array of pointers initialized by previous call to +.Fn uvm_loan . +.Fa npages +should match number of pages allocated for loan, this also matches +number of items in the array. +Argument +.Fa flags +should be one of +.Bd -literal +#define UVM_LOAN_TOANON 0x01 /* loan to anons */ +#define UVM_LOAN_TOPAGE 0x02 /* loan to kernel */ +.Ed +.Pp +and should match what was used for previous call to +.Fn uvm_loan . +.Sh MISCELLANEOUS FUNCTIONS +.Bl -ohang +.It Ft struct uvm_object * +.Fn uao_create "vsize_t size" "int flags" ; +.It Ft void +.Fn uao_detach "struct uvm_object *uobj" ; +.It Ft void +.Fn uao_reference "struct uvm_object *uobj" ; +.It Ft bool +.Fn uvm_chgkprot "void *addr" "size_t len" "int rw" ; +.It Ft void +.Fn uvm_kernacc "void *addr" "size_t len" "int rw" ; +.It Ft int +.Fn uvm_vslock "struct vmspace *vs" "void *addr" "size_t len" "vm_prot_t prot" ; +.It Ft void +.Fn uvm_vsunlock "struct vmspace *vs" "void *addr" "size_t len" ; +.It Ft void +.Fn uvm_meter "void" ; +.It Ft void +.Fn uvm_proc_fork "struct proc *p1" "struct proc *p2" "bool shared" ; +.It Ft int +.Fn uvm_grow "struct proc *p" "vaddr_t sp" ; +.It Ft void +.Fn uvn_findpages "struct uvm_object *uobj" "voff_t offset" "int *npagesp" "struct vm_page **pps" "int flags" ; +.It Ft void +.Fn uvm_vnp_setsize "struct vnode *vp" "voff_t newsize" ; +.El +.Pp +The +.Fn uao_create , +.Fn uao_detach , +and +.Fn uao_reference +functions operate on anonymous memory objects, such as those used to support +System V shared memory. +.Fn uao_create +returns an object of size +.Fa size +with flags: +.Bd -literal +#define UAO_FLAG_KERNOBJ 0x1 /* create kernel object */ +#define UAO_FLAG_KERNSWAP 0x2 /* enable kernel swap */ +.Ed +.Pp +which can only be used once each at system boot time. +.Fn uao_reference +creates an additional reference to the named anonymous memory object. +.Fn uao_detach +removes a reference from the named anonymous memory object, destroying +it if removing the last reference. +.Pp +.Fn uvm_chgkprot +changes the protection of kernel memory from +.Fa addr +to +.Fa addr + len +to the value of +.Fa rw . +This is primarily useful for debuggers, for setting breakpoints. +This function is only available with options +.Dv KGDB . +.Pp +.Fn uvm_kernacc +checks the access at address +.Fa addr +to +.Fa addr + len +for +.Fa rw +access in the kernel address space. +.Pp +.Fn uvm_vslock +and +.Fn uvm_vsunlock +control the wiring and unwiring of pages for process +.Fa p +from +.Fa addr +to +.Fa addr + len . +These functions are normally used to wire memory for I/O. +.Pp +.Fn uvm_meter +calculates the load average. +.Pp +.Fn uvm_proc_fork +forks a virtual address space for process' (old) +.Fa p1 +and (new) +.Fa p2 . +If the +.Fa shared +argument is non zero, p1 shares its address space with p2, +otherwise a new address space is created. +This function currently has no return value, and thus cannot fail. +In the future, this function will be changed to allow it to +fail in low memory conditions. +.Pp +.Fn uvm_grow +increases the stack segment of process +.Fa p +to include +.Fa sp . +.Pp +.Fn uvn_findpages +looks up or creates pages in +.Fa uobj +at offset +.Fa offset , +marks them busy and returns them in the +.Fa pps +array. +Currently +.Fa uobj +must be a vnode object. +The number of pages requested is pointed to by +.Fa npagesp , +and this value is updated with the actual number of pages returned. +The flags can be any bitwise inclusive-or of: +.Pp +.Bl -tag -offset abcd -compact -width UVM_ADV_SEQUENTIAL +.It Dv UFP_ALL +Zero pseudo-flag meaning return all pages. +.It Dv UFP_NOWAIT +Don't sleep \(em yield +.Dv NULL +for busy pages or for uncached pages for which allocation would sleep. +.It Dv UFP_NOALLOC +Don't allocate \(em yield +.Dv NULL +for uncached pages. +.It Dv UFP_NOCACHE +Don't use cached pages \(em yield +.Dv NULL +instead. +.It Dv UFP_NORDONLY +Don't yield read-only pages \(em yield +.Dv NULL +for pages marked +.Dv PG_READONLY . +.It Dv UFP_DIRTYONLY +Don't yield clean pages \(em stop early at the first clean one. +As a side effect, mark yielded dirty pages clean. +Caller must write them to permanent storage before unbusying. +.It Dv UFP_BACKWARD +Traverse pages in reverse order. +If +.Fn uvn_findpages +returns early, it will have filled +.Li * Ns Fa npagesp +entries at the end of +.Fa pps +rather than the beginning. +.El +.Pp +.Fn uvm_vnp_setsize +sets the size of vnode +.Fa vp +to +.Fa newsize . +Caller must hold a reference to the vnode. +If the vnode shrinks, pages no longer used are discarded. +.Sh MISCELLANEOUS MACROS +.Bl -ohang +.It Ft paddr_t +.Fn atop "paddr_t pa" ; +.It Ft paddr_t +.Fn ptoa "paddr_t pn" ; +.It Ft paddr_t +.Fn round_page "address" ; +.It Ft paddr_t +.Fn trunc_page "address" ; +.El +.Pp +The +.Fn atop +macro converts a physical address +.Fa pa +into a page number. +The +.Fn ptoa +macro does the opposite by converting a page number +.Fa pn +into a physical address. +.Pp +.Fn round_page +and +.Fn trunc_page +macros return a page address boundary from rounding +.Fa address +up and down, respectively, to the nearest page boundary. +These macros work for either addresses or byte counts. +.Sh SYSCTL +UVM provides support for the +.Dv CTL_VM +domain of the +.Xr sysctl 3 +hierarchy. +It handles the +.Dv VM_LOADAVG , +.Dv VM_METER , +.Dv VM_UVMEXP , +and +.Dv VM_UVMEXP2 +nodes, which return the current load averages, calculates current VM +totals, returns the uvmexp structure, and a kernel version independent +view of the uvmexp structure, respectively. +It also exports a number of tunables that control how much VM space is +allowed to be consumed by various tasks. +The load averages are typically accessed from userland using the +.Xr getloadavg 3 +function. +The uvmexp structure has all global state of the UVM system, +and has the following members: +.Bd -literal +/* vm_page constants */ +int pagesize; /* size of a page (PAGE_SIZE): must be power of 2 */ +int pagemask; /* page mask */ +int pageshift; /* page shift */ + +/* vm_page counters */ +int npages; /* number of pages we manage */ +int free; /* number of free pages */ +int paging; /* number of pages in the process of being paged out */ +int wired; /* number of wired pages */ +int reserve_pagedaemon; /* number of pages reserved for pagedaemon */ +int reserve_kernel; /* number of pages reserved for kernel */ + +/* pageout params */ +int freemin; /* min number of free pages */ +int freetarg; /* target number of free pages */ +int inactarg; /* target number of inactive pages */ +int wiredmax; /* max number of wired pages */ + +/* swap */ +int nswapdev; /* number of configured swap devices in system */ +int swpages; /* number of PAGE_SIZE'ed swap pages */ +int swpginuse; /* number of swap pages in use */ +int nswget; /* number of times fault calls uvm_swap_get() */ +int nanon; /* number total of anon's in system */ +int nfreeanon; /* number of free anon's */ + +/* stat counters */ +int faults; /* page fault count */ +int traps; /* trap count */ +int intrs; /* interrupt count */ +int swtch; /* context switch count */ +int softs; /* software interrupt count */ +int syscalls; /* system calls */ +int pageins; /* pagein operation count */ + /* pageouts are in pdpageouts below */ +int pgswapin; /* pages swapped in */ +int pgswapout; /* pages swapped out */ +int forks; /* forks */ +int forks_ppwait; /* forks where parent waits */ +int forks_sharevm; /* forks where vmspace is shared */ + +/* fault subcounters */ +int fltnoram; /* number of times fault was out of ram */ +int fltnoanon; /* number of times fault was out of anons */ +int fltpgwait; /* number of times fault had to wait on a page */ +int fltpgrele; /* number of times fault found a released page */ +int fltrelck; /* number of times fault relock called */ +int fltrelckok; /* number of times fault relock is a success */ +int fltanget; /* number of times fault gets anon page */ +int fltanretry; /* number of times fault retrys an anon get */ +int fltamcopy; /* number of times fault clears "needs copy" */ +int fltnamap; /* number of times fault maps a neighbor anon page */ +int fltnomap; /* number of times fault maps a neighbor obj page */ +int fltlget; /* number of times fault does a locked pgo_get */ +int fltget; /* number of times fault does an unlocked get */ +int flt_anon; /* number of times fault anon (case 1a) */ +int flt_acow; /* number of times fault anon cow (case 1b) */ +int flt_obj; /* number of times fault is on object page (2a) */ +int flt_prcopy; /* number of times fault promotes with copy (2b) */ +int flt_przero; /* number of times fault promotes with zerofill (2b) */ + +/* daemon counters */ +int pdwoke; /* number of times daemon woke up */ +int pdrevs; /* number of times daemon rev'd clock hand */ +int pdfreed; /* number of pages daemon freed since boot */ +int pdscans; /* number of pages daemon scanned since boot */ +int pdanscan; /* number of anonymous pages scanned by daemon */ +int pdobscan; /* number of object pages scanned by daemon */ +int pdreact; /* number of pages daemon reactivated since boot */ +int pdbusy; /* number of times daemon found a busy page */ +int pdpageouts; /* number of times daemon started a pageout */ +int pddeact; /* number of pages daemon deactivates */ +.Ed +.Sh NOTES +.Fn uvm_chgkprot +is only available if the kernel has been compiled with options +.Dv KGDB . +.Pp +All structure and types whose names begin with +.Dq vm_ +will be renamed to +.Dq uvm_ . +.Sh SEE ALSO +.Xr swapctl 2 , +.Xr getloadavg 3 , +.Xr kvm 3 , +.Xr sysctl 3 , +.Xr ddb 4 , +.Xr options 4 , +.Xr memoryallocators 9 , +.Xr pmap 9 , +.Xr ubc 9 , +.Xr uvm_km 9 , +.Xr uvm_map 9 +.Rs +.%A Charles D. Cranor +.%A Gurudatta M. Parulkar +.%T "The UVM Virtual Memory System" +.%I USENIX Association +.%B Proceedings of the USENIX Annual Technical Conference +.%P 117-130 +.%D June 6-11, 1999 +.%U http://www.usenix.org/event/usenix99/full_papers/cranor/cranor.pdf +.Re +.Sh HISTORY +UVM is a new VM system developed at Washington University in St. Louis +(Missouri). +UVM's roots lie partly in the Mach-based +.Bx 4.4 +VM system, the +.Fx +VM system, and the SunOS 4 VM system. +UVM's basic structure is based on the +.Bx 4.4 +VM system. +UVM's new anonymous memory system is based on the +anonymous memory system found in the SunOS 4 VM (as described in papers +published by Sun Microsystems, Inc.). +UVM also includes a number of features new to +.Bx +including page loanout, map entry passing, simplified +copy-on-write, and clustered anonymous memory pageout. +UVM is also further documented in an August 1998 dissertation by +Charles D. Cranor. +.Pp +UVM appeared in +.Nx 1.4 . +.Sh AUTHORS +.An -nosplit +.An Charles D. Cranor +.Aq Mt chuck@ccrc.wustl.edu +designed and implemented UVM. +.Pp +.An Matthew Green +.Aq Mt mrg@eterna23.net +wrote the swap-space management code and handled the logistical issues +involved with merging UVM into the +.Nx +source tree. +.Pp +.An Chuck Silvers +.Aq Mt chuq@chuq.com +implemented the aobj pager, thus allowing UVM to support System V shared +memory and process swapping. diff --git a/static/netbsd/man9/uvm_hotplug.9 b/static/netbsd/man9/uvm_hotplug.9 new file mode 100644 index 00000000..cdb9df15 --- /dev/null +++ b/static/netbsd/man9/uvm_hotplug.9 @@ -0,0 +1,550 @@ +.\" $NetBSD: uvm_hotplug.9,v 1.6 2020/01/17 12:34:55 skrll Exp $ +.\" +.\" Copyright (c) 2016 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Cherry G Mathew and Santhosh N Raju. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 17, 2020 +.Dt UVM_HOTPLUG 9 +.Os +.Sh NAME +.Nm uvm_physseg_init , +.Nm uvm_physseg_valid_p , +.Nm uvm_physseg_get_start , +.Nm uvm_physseg_get_end , +.Nm uvm_physseg_get_avail_start , +.Nm uvm_physseg_get_avail_end , +.Nm uvm_physseg_get_pg , +.Nm uvm_physseg_get_pmseg , +.Nm uvm_physseg_get_free_list , +.Nm uvm_physseg_get_start_hint , +.Nm uvm_physseg_set_start_hint , +.Nm uvm_physseg_get_next , +.Nm uvm_physseg_get_prev , +.Nm uvm_physseg_get_first , +.Nm uvm_physseg_get_last , +.Nm uvm_physseg_get_highest_frame , +.Nm uvm_physseg_find , +.Nm uvm_page_physload , +.Nm uvm_page_physunload , +.Nm uvm_page_physunload_force , +.Nm uvm_physseg_plug , +.Nm uvm_physseg_unplug , +.Nm uvm_physseg_set_avail_start , +.Nm uvm_physseg_set_avail_end +.Nd memory hotplug manager +.Sh SYNOPSIS +.In uvm/uvm_physseg.h +.Ft void +.Fn uvm_physseg_init "void" +.Ft uvm_physseg_t +.Fn uvm_page_physload "paddr_t start" "paddr_t end" "paddr_t avail_start" \ +"paddr_t avail_end" "int free_list" +.Ft bool +.Fn uvm_page_physunload "uvm_physseg_t upm" "int free_list" \ +"paddr_t *paddrp" +.Ft bool +.Fn uvm_page_physunload_force "uvm_physseg_t upm" "int free_list" \ +"paddr_t *paddrp" +.Ft bool +.Fn uvm_physseg_plug "paddr_t pfn" "size_t npages" "uvm_physseg_t *upmp" +.Ft bool +.Fn uvm_physseg_unplug "paddr_t pfn" "size_t npages" +.Sh DESCRIPTION +These utility routines provide the ability to tell +.Xr uvm 9 +about system memory segments. +When the kernel is compiled with +.Cd 'options UVM_HOTPLUG' , +memory segments are handled in a dynamic data structure +.Pq Xr rbtree 3 +compared to a static array when not. +This enables kernel code to add +or remove information about memory segments at any point after boot - +thus "hotplug". +.Pp +.Fn uvm_page_physload , +.Fn uvm_page_physunload , +and +.Fn uvm_page_physunload_force +are legacy interfaces which may be removed in the future. +They must +never be used after +.Xr uvm_init 9 . +.Pp +.Sy WARNING : +This is an experimental feature and should not be used in production +environments. +Furthermore, attempting to "hotplug" without +.Cd 'options UVM_HOTPLUG' +after boot will almost certainly end in a +.Xr panic 9 . +.Sh USAGE +.Ss INITIALIZING HOTPLUG +The function +.Fn uvm_physseg_init +initializes the hotplug subsystem. +This is expected to happen exactly +once, at boot time, and from MD code. +.Ss PLUGGING IN MEMORY +.Fn uvm_page_physload +registers +.Xr uvm 9 +with a memory segment span, and on a specified +.Fa free_list . +It must be called at system boot time as part of setting up memory +management. +The arguments describe the start and end of the physical addresses of the +segment, and the available start and end addresses of pages not already in use. +If a system has memory banks of different speeds the slower memory should be +given a higher +.Fa free_list +value. +.Bl -tag -offset indent -width "avail_start" +.It Fa start +Starting page frame number of the physical memory segments. +.It Fa end +Ending page frame number of the physical memory segments. +.It Fa avail_start +Available starting page frame number of the physical memory segments. +.It Fa avail_end +Available ending page frame number of the physical memory segments. +.It Fa free_list +The free list types are defined in the Machine Dependent code. +.El +.Pp +This function returns a valid +.Dv uvm_physseg_t +handle when a successful plug occurs, else it will return +.Dv UVM_PHYSSEG_TYPE_INVALID +when the plug fails. +.Pp +.Fn uvm_physseg_plug +registers +.Xr uvm 9 +with a memory segment span. +It can also be called to initiate a hotplug and register a newly +"hotplugged" physical memory range into the VM. +Unlike +.Fn uvm_page_physload +this function can, if +.Cd 'options UVM_HOTPLUG' +is enabled at compile time, be used after +.Xr uvm_init 9 . +The arguments describe the start page frame, the number of pages to +plug starting from the start page frame and an optional return variable, which +points to a valid +.Fa uvm_physseg_t +handle when a successful plug occurs. +.Bl -tag -offset indent -width "npages" +.It Fa pfn +Starting page frame number of the physical memory segment. +.It Fa npages +Total number of pages from the starting page frame number to plug in. +.It Fa upmp +If upmp is not +.Dv NULL , +then on a successful plug, a valid pointer to the uvm_physseg_t handle +for the segment which was plugged is returned. +.El +.Pp +This function returns +.Fa true +when a successful plug occurs, +.Fa false +otherwise. +.Ss UNPLUGGING MEMORY +The functions +.Fn uvm_page_physunload , +.Fn uvm_page_physunload_force , +and +.Fn uvm_physseg_unplug +make +.Xr uvm 9 +forget about previously registered memory segments or portions of +such. +.Pp +.Fn uvm_page_physunload +unloads pages from a segment (from the front or from the back) +depending on its availability. +When the last page is removed, the +segment handle is invalidated and supporting metadata is freed. +.Pp +Note: This function can only be used during boot time. +Pages, once unloaded, are unregistered from uvm and are therefore +assumed to be managed by the code which called +.Fn uvm_page_physunload 9 +(usually boot time MD code, for boottime memory "allocation"). +.Pp +The arguments are: +.Bl -tag -offset indent -width "free_list" +.It Fa upm +The handle identifying segment from which we are trying to unload memory. +.It Fa free_list +The free list types are defined in the Machine Dependent code. +.It Fa paddrp +The pointer to the physical address that was unloaded. +.El +.Pp +If the unload was successful, +.Fa true +is returned, +.Fa false +otherwise. +.Pp +.Fn uvm_page_physunload_force +unconditionally unloads pages from a segment. +When the last page is removed, the segment handle +is invalidated and supporting metadata is freed. +.Pp +Note: This function can only be used during boot time. +Pages, once unloaded, are unregistered from uvm and are therefore +assumed to be managed by the code which called +.Fn uvm_page_physunload_force 9 +(usually boot time MD code, for boottime memory "allocation"). +.Pp +The arguments are: +.Bl -tag -offset indent -width "free_list" +.It Fa upm +The handle identifying segment from which we are trying to unload memory. +.It Fa free_list +The free list types are defined in the Machine Dependent code. +.It Fa paddrp +The pointer to the physical address that was unloaded. +.El +.Pp +If the unload was successful +.Fa true +is returned, +.Fa false +otherwise. +.Pp +.Fn uvm_physseg_unplug +can be called to unplug an existing physical memory segment. +Unlike +.Fn uvm_page_physunload +and +.Fn uvm_page_physunload_force , +it can be called after +.Xr uvm_init 9 , +if +.Cd 'options UVM_HOTPLUG' +is enabled at compile time. +.Fn uvm_hotplug 9 +makes no effort to manage the state of the underlying physical +memory. +It is up to the caller to ensure that it is not in use, +either by +.Xr uvm 9 , +or by any other sub-system. +Further, any hardware +quiescing that may be required is the responsibility of MD code. +The arguments +describe the start page frame and the number of pages to unplug. +The arguments are: +.Bl -tag -offset indent -width "npages" +.It Fa pfn +Starting page frame number of the physical memory segment. +.It Fa npages +Total number of pages from the starting page frame number to unplug. +.El +.Pp +Returns +.Fa true +or +.Fa false +depending on success or failure respectively. +.Sh UTILITY FUNCTIONS +.Bl -ohang +.It Ft bool +.Fn uvm_physseg_valid_p "uvm_physseg_t upm" +.It Ft paddr_t +.Fn uvm_physseg_get_start "uvm_physseg_t upm" +.It Ft paddr_t +.Fn uvm_physseg_get_end "uvm_physseg_t upm" +.It Ft paddr_t +.Fn uvm_physseg_get_avail_start "uvm_physseg_t upm" +.It Ft paddr_t +.Fn uvm_physseg_get_avail_end "uvm_physseg_t upm" +.It Ft struct vm_page * +.Fn uvm_physseg_get_pg "uvm_physseg_t upm" "paddr_t index" +.It Ft struct pmap_physseg * +.Fn uvm_physseg_get_pmesg "uvm_physseg_t upm" +.It Ft int +.Fn uvm_physseg_get_free_list "uvm_physseg_t upm" +.It Ft u_int +.Fn uvm_physseg_get_start_hint "uvm_physseg_t upm" +.It Ft bool +.Fn uvm_physseg_set_start_hint "uvm_physseg_t upm" "u_int start_hint" +.It Ft uvm_physseg_t +.Fn uvm_physseg_get_next "uvm_physseg_t upm" +.It Ft uvm_physseg_t +.Fn uvm_physseg_get_prev "uvm_physseg_t upm" +.It Ft uvm_physseg_t +.Fn uvm_physseg_get_first "void" +.It Ft uvm_physseg_t +.Fn uvm_physseg_get_last "void" +.It Ft paddr_t +.Fn uvm_physseg_get_highest_frame "void" +.It Ft paddr_t +.Fn uvm_physseg_find "paddr pframe" "psize_t *offsetp" +.It Ft void +.Fn uvm_physseg_set_avail_start "uvm_physseg_t upm" "paddr_t avail_start" +.It Ft void +.Fn uvm_physseg_set_avail_end "uvm_physseg_t upm" "paddr_t avail_end" +.El +.Pp +.Fn uvm_physseg_valid_p +validates a handle that is passed in, returns +.Fa true +if the given handle is valid, +.Fa false +otherwise. +.Pp +.Fn uvm_physseg_get_start +if a valid +.Fa uvm_physseg_t +handle is passed in, it returns the starting physical address of +the segment. +The returned value is of type +.Ft paddr_t . +In case the handle is invalid the returned value will match +.Ft ( paddr_t ) +\-1. +.Pp +.Fn uvm_physseg_get_end +if a valid +.Fa uvm_physseg_t +handle is passed in, it returns the ending physical address of the +segment. +The returned value is of type +.Ft paddr_t . +In case the handle is invalid the returned value will match +.Ft ( paddr_t ) +\-1. +.Pp +.Fn uvm_physseg_get_avail_start +if a valid +.Fa uvm_physseg_t +handle is passed in, it returns the available starting physical +address of the segment. +The returned value is of type +.Ft paddr_t . +In case the handle is invalid the returned value will match +.Ft ( paddr_t ) +\-1. +.Pp +.Fn uvm_physseg_get_avail_end +if a valid +.Fa uvm_physseg_t +handle is passed in, it returns the available ending physical +address of the segment. +The returned value is of type +.Ft paddr_t . +In case the handle is invalid the returned value will match +.Ft ( paddr_t ) +\-1. +.Pp +.Fn uvm_physseg_get_pg +if a valid +.Fa uvm_physseg_t +handle along with an index value is passed in, it returns the +.Fa struct vm_page * +object contained in that location. +.Pp +.Fn uvm_physseg_get_pmseg +if a valid +.Fa uvm_physseg_t +handle is passed in, it returns the +.Fa struct pmap_physseg * +object contained in the handle. +.Pp +.Fn uvm_physseg_get_free_list +if a valid +.Fa uvm_physseg_t +handle is passed in, it returns the +.Fa free_list +type for which the current segment is associated with. +The returned value is of +type +.Fa int . +.Pp +.Fn uvm_physseg_get_start_hint +if a valid +.Fa uvm_physseg_t +handle is passed in, it returns the +.Fa start_hint +type for the current segment. +The returned value is of type +.Fa u_int . +.Pp +.Fn uvm_physseg_set_start_hint +if a valid handle along with the +.Fa start_hint +is passed in, the value is set in the segment. +And a +.Fa true +is returned to indicate a successful value setting. +In case the handle is invalid a +.Fa false +is returned. +.Pp +.Fn uvm_physseg_get_next +if a valid handle is passed in, it returns the next valid +.Fa uvm_physseg_t +handle in the sequence. +However if the handle passed is the last segment in the +sequence the function returns +.Fa UVM_PHYSSEG_TYPE_INVALID_OVERFLOW . +Passing an invalid handle is not fatal, and returns +.Fa UVM_PHYSSEG_TYPE_INVALID . +. +.Pp +.Fn uvm_physseg_get_prev +if a valid handle is passed in, it returns the previous validh +.Fa uvm_physseg_t +handle in the sequence. +However if the handle passed is the first segment in +the sequence the function returns +.Fa UVM_PHYSSEG_TYPE_INVALID_EMPTY . +Passing an invalid handle is not fatal, and returns +.Fa UVM_PHYSSEG_TYPE_INVALID . +. +.Pp +.Fn uvm_physseg_get_first +returns the first valid +.Fa uvm_physseg_t +handle in the sequence. +However if there are no valid handles in the sequence +yet, the function returns +.Fa UVM_PHYSSEG_TYPE_INVALID_EMPTY . +.Pp +.Fn uvm_physseg_get_last +returns the last valid +.Fa uvm_physseg_t +handle in the sequence. +However if there are no valid handles in the sequence +yet, the function returns +.Fa UVM_PHYSSEG_TYPE_INVALID_EMPTY . +.Pp +.Fn uvm_physseg_get_highest_frame +returns the frame number of the highest registered physical page frame +which is of type +.Ft paddr_t . +XXX: Searching on empty sequences are not yet processed in the function. +.Pp +.Fn uvm_physseg_find +searches for a given segment containing the page frame +.Ft ( paddr_t ) +passed in. +If a segment that falls between starting and ending addresses is +found, the corresponding +.Fa uvm_physseg_t +handle is returned else a +.Fa UVM_PHYSSEG_TYPE_INVALID +is returned. +The second parameter, if not set to +.Dv NULL , +the offset value of the page frame passed in with respect to the +starting address is set to the appropriate +.Fa psize_t +value if the search was successful in finding the segment. +.Pp +.Fn uvm_physseg_set_avail_start +if a valid +.Fa uvm_physseg_t +handle is passed in along with the available starting physical address of the +segment of type +.Ft paddr_t , +the value is set in the segment. +.Pp +.Fn uvm_physseg_set_avail_end +if a valid +.Fa uvm_physseg_t +handle is passed in along with the available ending physical address of the +segment of type +.Ft paddr_t , +the value is set in the segment. +.Sh NOTES +.Fn uvm_physseg_plug +and +.Fn uvm_physseg_unplug +must never be used after +.Xr uvm_init 9 +in a kernel build where +.Cd 'options UVM_HOTPLUG' +is not enabled. +.Sh DIAGNOSTICS +Tests for +.Nm +are in +.Pa tests/sys/uvm . +.Pp +Unit / functional tests are in +.Pa tests/sys/uvm/t_uvm_physseg.c . +These tests focus on the expected working of the +.Nm +API and its utility functions. +.Pp +Load tests can be found in +.Pa tests/sys/uvm/t_uvm_physseg_load.c . +These tests focus on stressing the +.Nm +implementation in order to make performance comparisons between kernel +builds with and without +.Cd 'options UVM_HOTPLUG' +. +.\" .Sh RETURN VALUES +.\" .Sh EXAMPLES +.Sh CODE REFERENCES +The uvm hotplug feature is implemented in the file +.Pa sys/uvm/uvm_physseg.c . +The uvm hotplug API is exported via +.Pa sys/uvm/uvm_physseg.h . +.Sh SEE ALSO +.Xr extent 9 , +.Xr free 9 , +.Xr malloc 9 , +.Xr memoryallocators 9 , +.Xr uvm 9 +.Sh HISTORY +This API emerged out of the need to insert new pages at runtime in the +Xen +.Xr x86/balloon 4 +driver. +.Sh AUTHORS +.An -nosplit +.An Cherry G. Mathew +.Aq Mt cherry@NetBSD.org +designed and integrated the API. +.Pp +.An Santhosh N. Raju +.Aq Mt santhosh.raju@gmail.com +implemented the dynamic segment handling code and all tests for this API. +.Pp +.An Nick Hudson +.Aq Mt skrll@NetBSD.org +contributed bugfixes and testing on a wide range of hardware ports. diff --git a/static/netbsd/man9/uvm_km.9 b/static/netbsd/man9/uvm_km.9 new file mode 100644 index 00000000..61ef6009 --- /dev/null +++ b/static/netbsd/man9/uvm_km.9 @@ -0,0 +1,187 @@ +.\" $NetBSD: uvm_km.9,v 1.5 2015/08/15 10:31:41 maxv Exp $ +.\" +.\" Copyright (c) 1998 Matthew R. Green +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 15, 2015 +.Dt UVM_KM 9 +.Os +.Sh NAME +.Nm uvm_km +.Nd raw kernel memory or address space allocator +.Sh SYNOPSIS +.In sys/param.h +.In uvm/uvm.h +.Ft vaddr_t +.Fn uvm_km_alloc "struct vm_map *map" "vsize_t size" "vsize_t align" "uvm_flag_t flags" +.Ft void +.Fn uvm_km_free "struct vm_map *map" "vaddr_t addr" "vsize_t size" "uvm_flag_t flags" +.Ft struct vm_map * +.Fn uvm_km_suballoc "struct vm_map *map" "vaddr_t *min" "vaddr_t *max" \ +"vsize_t size" "int flags" "bool fixed" "struct vm_map *submap" +.Sh DESCRIPTION +The UVM facility for allocation of kernel memory or address space in pages. +Both wired and pageable memory can be allocated by this facility, as well +as kernel address space. +Note that this is a raw allocator. +For general purpose memory allocation, +.Xr kmem 9 +interface should be used. +.Sh FUNCTIONS +.Fn uvm_km_alloc +allocates a contiguous range of +.Fa size +bytes of kernel memory in map +.Fa map +and returns the virtual address of the range, or returns zero on failure. +The first address of the allocated memory range will be aligned according to the +.Fa align +argument +.Pq specify 0 if no alignment is necessary . +The alignment must be a multiple of page size. +The +.Fa flags +is a bitwise inclusive OR of the allocation type and operation flags. +.Pp +The allocation type should be one of: +.Bl -tag -width UVM_KMF_PAGEABLE +.It UVM_KMF_WIRED +Wired memory. +.It UVM_KMF_PAGEABLE +Demand-paged zero-filled memory. +.It UVM_KMF_VAONLY +Virtual address only. +No physical pages are mapped in the allocated region. +If necessary, it is the caller's responsibility to enter page mappings. +It is also the caller's responsibility to clean up the mappings before freeing +the address range. +.El +.Pp +The following operation flags are available: +.Bl -tag -width UVM_KMF_PAGEABLE +.It UVM_KMF_CANFAIL +Can fail even if +.Dv UVM_KMF_NOWAIT +is not specified and +.Dv UVM_KMF_WAITVA +is specified. +.It UVM_KMF_ZERO +Request zero-filled memory. +Only supported for +.Dv UVM_KMF_WIRED . +Should not be used with other types. +.It UVM_KMF_EXEC +Request memory with executable rights. +.It UVM_KMF_TRYLOCK +Fail if cannot lock the map without sleeping. +.It UVM_KMF_NOWAIT +Fail immediately if no memory is available. +.It UVM_KMF_WAITVA +Sleep to wait for the virtual address resources if needed. +.El +.Pp +If neither +.Dv UVM_KMF_NOWAIT +nor +.Dv UVM_KMF_CANFAIL +are specified and +.Dv UVM_KMF_WAITVA +is specified, +.Fn uvm_km_alloc +will never fail, but rather sleep indefinitely until the allocation succeeds. +.Pp +Pageability of the pages allocated with +.Dv UVM_KMF_PAGEABLE +can be changed by +.Fn uvm_map_pageable . +In that case, the entire range must be changed atomically. +Changing a part of the range is not supported. +.Pp +.Fn uvm_km_free +frees the memory range allocated by +.Fn uvm_km_alloc . +.Fa addr +must be an address returned by +.Fn uvm_km_alloc . +.Fa map +and +.Fa size +must be the same as the ones used for the corresponding +.Fn uvm_km_alloc . +.Fa flags +must be the allocation type used for the corresponding +.Fn uvm_km_alloc . +Note that +.Fn uvm_km_free +is the only way to free memory ranges allocated by +.Fn uvm_km_alloc . +.Fn uvm_unmap +must not be used. +.Pp +.Fn uvm_km_suballoc +allocates submap from +.Fa map , +creating a new map if +.Fa submap +is +.Dv NULL . +The addresses of the submap can be specified explicitly by setting the +.Fa fixed +argument to true, which causes the +.Fa min +argument to specify the beginning of the address in the submap. +If +.Fa fixed +is false, any address of size +.Fa size +will be allocated from +.Fa map +and the start and end addresses returned in +.Fa min +and +.Fa max . +The +.Fa flags +are used to initialize the created submap. +The following flags can be set: +.Bl -tag -width VM_MAP_PAGEABLE +.It VM_MAP_PAGEABLE +Entries in the map may be paged out. +.It VM_MAP_INTRSAFE +Map should be interrupt-safe. +.It VM_MAP_TOPDOWN +A top-down mapping should be arranged. +.El +.Sh SEE ALSO +.Xr kmem 9 , +.Xr pmap 9 , +.Xr pool_cache 9 , +.Xr uvm 9 , +.Xr uvm_map 9 , +.Xr vmem 9 +.Sh HISTORY +UVM and +.Nm +first appeared in +.Nx 1.4 . diff --git a/static/netbsd/man9/uvm_map.9 b/static/netbsd/man9/uvm_map.9 new file mode 100644 index 00000000..11126a1e --- /dev/null +++ b/static/netbsd/man9/uvm_map.9 @@ -0,0 +1,406 @@ +.\" $NetBSD: uvm_map.9,v 1.12 2020/08/27 14:14:00 fcambus Exp $ +.\" +.\" Copyright (c) 1998 Matthew R. Green +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd May 20, 2017 +.Dt UVM_MAP 9 +.Os +.Sh NAME +.Nm uvm_map +.Nd +virtual address space management interface +.Sh SYNOPSIS +.In sys/param.h +.In uvm/uvm.h +.Ft int +.Fn uvm_map "struct vm_map *map" "vaddr_t *startp" "vsize_t size" \ +"struct uvm_object *uobj" "voff_t uoffset" "vsize_t align" "uvm_flag_t flags" +.Ft void +.Fn uvm_unmap "struct vm_map *map" "vaddr_t start" "vaddr_t end" +.Ft int +.Fn uvm_map_pageable "struct vm_map *map" "vaddr_t start" "vaddr_t end" \ +"bool new_pageable" "int lockflags" +.Ft bool +.Fn uvm_map_checkprot "struct vm_map *map" "vaddr_t start" "vaddr_t end" \ +"vm_prot_t protection" +.Ft int +.Fn uvm_map_protect "struct vm_map *map" "vaddr_t start" "vaddr_t end" \ +"vm_prot_t new_prot" "bool set_max" +.Ft int +.Fn uvm_map_protect_user "struct lwp *l" "vaddr_t start" "vaddr_t end" \ +"vm_prot_t new_prot" +.Ft int +.Fn uvm_deallocate "struct vm_map *map" "vaddr_t start" "vsize_t size" +.Ft struct vmspace * +.Fn uvmspace_alloc "vaddr_t min" "vaddr_t max" +.Ft void +.Fn uvmspace_exec "struct lwp *l" "vaddr_t start" "vaddr_t end" +.Ft struct vmspace * +.Fn uvmspace_fork "struct vmspace *vm" +.Ft void +.Fn uvmspace_free "struct vmspace *vm" +.Ft void +.Fn uvmspace_share "struct proc *p1" "struct proc *p2" +.\" .Ft void +.\" .Fn uvmspace_unshare "struct lwp *l" +.Ft vaddr_t +.Fn uvm_uarea_alloc "void" +.Ft void +.Fn uvm_uarea_free "vaddr_t uaddr" +.Ft vaddr_t +.Fn uvm_uarea_system_alloc "void" +.Ft void +.Fn uvm_uarea_system_free "vaddr_t uaddr" +.Sh DESCRIPTION +The UVM facility for virtual address space management. +.Sh FUNCTIONS +.Fn uvm_map +establishes a valid mapping in map +.Fa map , +which must be unlocked. +The new mapping has size +.Fa size , +which must be a multiple of +.Dv PAGE_SIZE . +.Pp +The +.Fa uobj +and +.Fa uoffset +arguments can have four meanings: +.Bl -bullet -offset abcd -compact +.It +When +.Fa uobj +is +.Dv NULL +and +.Fa uoffset +is +.Dv UVM_UNKNOWN_OFFSET , +.Fn uvm_map +does not use the machine-dependent +.Dv PMAP_PREFER +function. +.It +When +.Fa uobj +is +.Dv NULL +and +.Fa uoffset +is any other value, it is used as the hint to +.Dv PMAP_PREFER . +.It +When +.Fa uobj +is not +.Dv NULL +and +.Fa uoffset +is +.Dv UVM_UNKNOWN_OFFSET , +.Fn uvm_map +finds the offset based upon the virtual address, passed as +.Fa startp . +.It +When +.Fa uobj +is not +.Dv NULL +and +.Fa uoffset +is any other value, then a regular mapping is performed at this offset. +The start address of the map will be returned in +.Fa startp . +.El +If +.Fa uobj +is supplied, then +.Fn uvm_map +.Em consumes +the caller's reference to +.Fa uobj +on success; +.Fn uvm_unmap +will release it when removing this mapping. +On failure, +.Fn uvm_map +leaves the reference count of +.Fa uobj +unmodified. +.Pp +.Fa align +specifies alignment of mapping unless +.Dv UVM_FLAG_FIXED +is specified in +.Fa flags . +.Fa align +must be a power of 2. +.Pp +.Fa flags +passed to +.Fn uvm_map +are typically created using the +.Fn UVM_MAPFLAG "vm_prot_t prot" "vm_prot_t maxprot" "vm_inherit_t inh" \ +"int advice" "int flags" +macro, which uses the following values. +.Pp +The values that +.Fa prot +and +.Fa maxprot +can take are: +.Bl -tag -offset abcd -compact -width UVM_ADV_SEQUENTIAL +.It UVM_PROT_NONE +No protection bits. +.It UVM_PROT_R +Read. +.It UVM_PROT_W +Write. +.It UVM_PROT_X +Exec. +.It UVM_PROT_MASK +Mask to extraction the protection bits. +.El +Additionally, the following constants for ORed values are available: +.Dv UVM_PROT_RW , +.Dv UVM_PROT_RX , +.Dv UVM_PROT_WX +and +.Dv UVM_PROT_RWX . +.Pp +The values that +.Fa inh +can take are: +.Bl -tag -offset abcd -compact -width UVM_ADV_SEQUENTIAL +.It UVM_INH_SHARE +Share the map. +.It UVM_INH_COPY +Copy the map. +.It UVM_INH_NONE +No inheritance. +.It UVM_INH_MASK +Mask to extract inherit flags. +.El +.Pp +The values that +.Fa advice +can take are: +.Bl -tag -offset abcd -compact -width UVM_ADV_SEQUENTIAL +.It UVM_ADV_NORMAL +"Normal" use. +.It UVM_ADV_RANDOM +"Random" access likelihood. +.It UVM_ADV_SEQUENTIAL +"Sequential" access likelihood. +.It UVM_ADV_MASK +Mask to extract the advice flags. +.El +.Pp +The values that +.Fa flags +can take are: +.Bl -tag -offset abcd -compact -width UVM_ADV_SEQUENTIAL +.It UVM_FLAG_FIXED +Attempt to map on the address specified by +.Fa startp . +Otherwise, it is used just as a hint. +.It UVM_FLAG_OVERLAY +Establish overlay. +.It UVM_FLAG_NOMERGE +Do not merge map entries, if such merge is possible. +.It UVM_FLAG_COPYONW +Use copy-on-write i.e. do not fault in the pages immediately. +.It UVM_FLAG_AMAPPAD +Used for BSS: allocate larger amap, if extending is likely. +.It UVM_FLAG_TRYLOCK +Fail if cannot acquire the lock immediately. +.It UVM_FLAG_NOWAIT +Not allowed to sleep. +Fail, in such case. +.It UVM_FLAG_QUANTUM +Indicates that map entry cannot be split once mapped. +.It UVM_FLAG_WAITVA +Sleep until VA space is available, if it is not. +.It UVM_FLAG_VAONLY +Unmap only VA space. +Used by +.Fn uvm_unmap . +.It UVM_FLAG_UNMAP +Any existing entries in the range for this mapping should be +unmapped as part of creating the new mapping. +Use of this flag without also specifying +.Dv UVM_FLAG_FIXED +is a bug. +.El +.Pp +The +.Dv UVM_MAPFLAG +macro arguments can be combined with an or operator. +There are several special purpose macros for checking protection +combinations, e.g., the +.Dv UVM_PROT_WX . +There are also some additional macros to extract bits from the flags. +The +.Dv UVM_PROTECTION , +.Dv UVM_INHERIT , +.Dv UVM_MAXPROTECTION +and +.Dv UVM_ADVICE +macros return the protection, inheritance, maximum protection, and +advice, respectively. +.Fn uvm_map +returns zero on success or error number otherwise. +.Pp +.Fn uvm_unmap +removes a valid mapping, +from +.Fa start +to +.Fa end , +in map +.Fa map , +which must be unlocked. +.Pp +.Fn uvm_map_pageable +changes the pageability of the pages in the range from +.Fa start +to +.Fa end +in map +.Fa map +to +.Fa new_pageable . +.Fn uvm_map_pageable +returns zero on success or error number otherwise. +.Pp +.Fn uvm_map_checkprot +checks the protection of the range from +.Fa start +to +.Fa end +in map +.Fa map +against +.Fa protection . +This returns either +.Dv true +or +.Dv false . +.Pp +.Fn uvm_map_protect +changes the protection +.Fa start +to +.Fa end +in map +.Fa map +to +.Fa new_prot , +also setting the maximum protection to the region to +.Fa new_prot +if +.Fa set_max +is true. +This function returns a standard UVM return value. +.Pp +.Fn uvm_map_protect_user +verifies that the new permissions honor PAX restrictions if applicable +and forwards to +.Fn uvm_map_protect +on passing. +.Pp +.Fn uvm_deallocate +deallocates kernel memory in map +.Fa map +from address +.Fa start +to +.Fa start + size . +.Pp +.Fn uvmspace_alloc +allocates and returns a new address space, with ranges from +.Fa min +to +.Fa max . +.Pp +.Fn uvmspace_exec +either reuses the address space of thread +.Fa l +(its process) if there are no other references to it, or creates +a new one with +.Fn uvmspace_alloc . +The range of valid addresses in the address space is reset to +.Fa start +through +.Fa end . +.Pp +.Fn uvmspace_fork +creates and returns a new address space based upon the +.Fa vm +address space, typically used when allocating an address space for a +child process. +.Pp +.Fn uvmspace_free +lowers the reference count on the address space +.Fa vm , +freeing the data structures if there are no other references. +.Pp +.Fn uvmspace_share +causes process +.Pa p2 +to share the address space of +.Fa p1 . +.\" .Pp +.\" .Fn uvmspace_unshare +.\" ensures that thread +.\" .Fa l +.\" has its own, unshared address space, by creating a new one if +.\" necessary by calling +.\" .Fn uvmspace_fork . +.Pp +.Fn uvm_uarea_alloc +allocates memory for a u-area (i.e. kernel stack, PCB, etc) and returns +the address. +.Pp +.Fn uvm_uarea_free +frees a u-area allocated with +.Fn uvm_uarea_alloc . +.Pp +.Fn uvm_uarea_system_alloc +and +.Fn uvm_uarea_system_free +are optimized routines, which are used for kernel threads. +.Sh SEE ALSO +.Xr pmap 9 , +.Xr uvm 9 , +.Xr uvm_km 9 , +.Xr vmem 9 +.Sh HISTORY +UVM and +.Nm +first appeared in +.Nx 1.4 . diff --git a/static/netbsd/man9/uvm_obj_wirepages.9 b/static/netbsd/man9/uvm_obj_wirepages.9 new file mode 100644 index 00000000..b2b5f60f --- /dev/null +++ b/static/netbsd/man9/uvm_obj_wirepages.9 @@ -0,0 +1,90 @@ +.\" $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. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 14, 2024 +.Dt UVM_OBJ_WIREPAGES 9 +.Os +.Sh NAME +.Nm uvm_obj_wirepages +.Nm uvm_obj_unwirepages +.Nd temporarily wire pages of a UVM object into RAM +.Sh SYNOPSIS +.In uvm/uvm_extern.h +.Ft int +.Fn uvm_obj_wirepages "struct uvm_object *uobj" "off_t start" "off_t end" "struct pglist *list" +.Ft void +.Fn uvm_obj_unwirepages "struct uvm_object *uobj" "off_t start" "off_t end" +.Sh DESCRIPTION +.Fn uvm_obj_wirepages +temporarily wires a range of pages in a UVM object into RAM. +If any pages from +.Fa start +(inclusive) +to +.Fa end +(exclusive) +are currently paged out, it pages them back in first, and arranges that +the pages in the range will not be paged out until unwired with +.Fn uvm_obj_unwirepages . +.Pp +If +.Fa list +is nonnull, it is initialized to a tailq of pages linked through the +.Fa pageq.queue +member of +.Vt struct vm_page , +for the convenience of the caller. +The caller is not transferred ownership of any part of +.Fa list +and need not free anything afterward \(em +.Fn uvm_obj_unwirepages +will free the pages when done. +.Pp +.Fa start +and +.Fa end +must be page-aligned. +.Pp +Calls to +.Fn uvm_obj_wirepages +must be matched by +.Fn uvm_obj_unwirepages +with the same range. +.Pp +Overlapping ranges may be simultaneously wired; each page may be wired +up to 2^32 - 1 times, and will not be paged out until all ranges +covering it have been unwired. +.Sh RETURN VALUES +The +.Fn uvm_obj_wirepages +function returns zero on success, or returns an +.Xr errno 3 +error code and leaves the wired status of all pages unchanged on +failure. +.Sh SEE ALSO +.Xr mlock 3 , +.Xr uvm 9 , +.Xr uvm_map 9 diff --git a/static/netbsd/man9/vattr.9 b/static/netbsd/man9/vattr.9 new file mode 100644 index 00000000..75a47a09 --- /dev/null +++ b/static/netbsd/man9/vattr.9 @@ -0,0 +1,107 @@ +.\" $NetBSD: vattr.9,v 1.15 2010/12/02 12:54:13 wiz Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 8, 2010 +.Dt VATTR 9 +.Os +.Sh NAME +.Nm vattr , +.Nm vattr_null +.Nd vnode attributes +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft void +.Fn vattr_null "struct vattr *vap" +.Sh DESCRIPTION +Vnode attributes describe attributes of a file or directory including +file permissions, owner, group, size, access time and modification time. +.Pp +A vnode attribute has the following structure: +.Pp +.Bd -literal +struct vattr { + enum vtype va_type; /* vnode type (for create) */ + mode_t va_mode; /* files access mode and type */ + nlink_t va_nlink; /* number of references to file */ + uid_t va_uid; /* owner user id */ + gid_t va_gid; /* owner group id */ + dev_t va_fsid; /* file system id (dev for now) */ + ino_t va_fileid; /* file id */ + u_quad_t va_size; /* file size in bytes */ + long va_blocksize; /* blocksize preferred for i/o */ + struct timespec va_atime; /* time of last access */ + struct timespec va_mtime; /* time of last modification */ + struct timespec va_ctime; /* time file changed */ + struct timespec va_birthtime; /* time file created */ + u_long va_gen; /* generation number of file */ + u_long va_flags; /* flags defined for file */ + dev_t va_rdev; /* device the special file represents */ + u_quad_t va_bytes; /* bytes of disk space held by file */ + u_quad_t va_filerev; /* file modification number */ + u_int va_vaflags; /* operations flags, see below */ + long va_spare; /* remain quad aligned */ +}; +.Ed +.Pp +A field value of VNOVAL represents a field whose value is unavailable +or which is not to be changed. +Valid flag values for +.Em va_flags +are: +.Pp +.Bl -tag -offset indent -width VA_UTIMES_NULL -compact +.It VA_UTIMES_NULL +utimes argument was NULL +.It VA_EXCLUSIVE +exclusive create request +.El +.Pp +Vnode attributes for a file are set by the vnode operation +.Xr VOP_SETATTR 9 . +Vnode attributes for a file are retrieved by the vnode operation +.Xr VOP_GETATTR 9 . +For more information on vnode operations see +.Xr vnodeops 9 . +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn vattr_null "vap" +Set vnode attributes in +.Fa vap +to VNOVAL. +.El +.Sh CODE REFERENCES +.Fn vattr_null +is implemented in +.Pa sys/kern/vfs_subr.c . +.Sh SEE ALSO +.Xr intro 9 , +.Xr vfs 9 , +.Xr vnode 9 , +.Xr vnodeops 9 diff --git a/static/netbsd/man9/vcons.9 b/static/netbsd/man9/vcons.9 new file mode 100644 index 00000000..f5b1f3c7 --- /dev/null +++ b/static/netbsd/man9/vcons.9 @@ -0,0 +1,207 @@ +.\" $NetBSD: vcons.9,v 1.2 2006/02/13 19:57:58 wiz Exp $ +.\" +.\" Copyright (c) 2006 Michael Lorenz +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 12, 2006 +.Dt VCONS 9 +.Os +.Sh NAME +.Nm vcons +.Nd generic virtual console framework +.Sh SYNOPSIS +.In wscons/wsdisplay_vconsvar.h +.Ft int +.Fn vcons_init "struct vcons_data *vd" "void *cookie" \ +"struct wsscreen_descr *desc" "struct wsdisplay_accessops *accops" +.Ft int +.Fn vcons_init_screen "struct vcons_data *vd" "struct vcons_screen *scr" \ +"int exists" "long *defattr" +.Ft void +.Fn vcons_redraw_screen "struct vcons_screen *scr" +.Sh DESCRIPTION +These functions are used to setup and control the generic virtual +console framework. +.Pp +.\" +The +.Fn vcons_init +function initializes the framework, it needs to be called for each +driver that's going to use +.Nm . +.Pp +.Fn vcons_init_screen +adds a virtual screen to a display. +.Pp +.Fn vcons_redraw_screen +redraws a screen. +A driver should call it when returning to terminal emulation mode, +for instance when X exits. +.Pp +.\" +.Vt struct vcons_data +contains all information needed to manage virtual consoles on a display, +usually it will be a member of the driver's softc. +.Pp +.Vt struct vcons_screen +describes a virtual screen. +.Sh USAGE +.\" +To use vcons with a driver it needs to be initialized by calling +.Fn vcons_init , +usually in the driver's attach function. +.Bl -tag -width cookieXX +.It Fa vd +should be a pointer to the driver's +.Vt struct vcons_data . +.It Fa cookie +should be a pointer to the driver's softc. +.It Fa desc +should point to a +.Vt struct wsscreen_descr +describing the default screen type for this display. +.It Fa accops +points to the driver's +.Vt struct wsdisplay_accessops +so +.Fn vcons_init +can fill it in with its own implementations of +.Fn alloc_screen , +.Fn free_screen , +and +.Fn show_screen . +.El +.Pp +A driver should however provide its own +.Fn ioctl +and +.Fn mmap +implementations. +Both will receive a pointer to the driver's +.Vt struct vcons_data +as first parameter. +.Pp +After initialization the driver needs to provide a callback function that +will be called whenever a screen is added. +Its purpose is to set up the +.Vt struct rasops_info +describing the screen. +After that the drawing methods in +.Vt struct rasops_info +will be replaced with wrappers which call the original drawing functions +(which may or may not be provided by the driver) only when the respective +screen is visible. +To add a virtual screen the driver one should call +.Fn vcons_init_screen +which will call the callback function described above, allocate storage for +characters and attributes based on whatever the callback set up in +.Vt struct rasops_info , +and add the screen to a list kept in +.Vt struct vcons_data . +.Pp +The callback needs to have this form: +.Pp +.Ft void +.Fn init_screen "void *cookie" "struct vcons_screen *scr" "int existing" \ +"long *defattr" +.Pp +and should be stored in the +.Va init_screen +member found in +.Vt struct vcons_data . +The arguments are: +.Bl -tag -width cookieXX +.It Fa cookie +is the cookie passed to +.Fn vcons_init +.It Fa scr +points to the +.Vt struct vcons_screen +being added, its +.Va scr_ri +member, a +.Vt struct rasops_info , +needs to be filled in. +.It Fa existing +is non-zero if the screen already exists and is only added to the list. +.It Fa defattr +points to the screen's default text attribute. +It's filled in by +.Fn vcons_init_screen +by calling the +.Fn alloc_attr +method found in +.Vt struct rasops_info . +.El +.Pp +When attaching a +.Xr wsdisplay 9 +the +.Va accesscookie +member of the +.Vt struct wsemuldisplaydev_attach_args +passed to +.Fn config_found +needs to be a pointer to the driver's +.Vt struct vcons_data . +.Pp +The following members of +.Vt struct vcons_screen +may be of interest to drivers: +.Bl -tag -width scr_cookieXX +.It Va scr_ri +contains the +.Vt struct rasops_info +describing the screen's geometry, access methods and so on. +.It Va scr_cookie +the value passed as cookie to +.Fn vcons_init . +Usually the driver's softc. +.It Va scr_vd +the driver's +.Vt struct vcons_data . +.It Va scr_flags +can be zero or any combination of: +.Bl -tag -width XXXXXXXXXXXXXXXXXXXXXX -compact +.It Dv VCONS_NO_REDRAW +don't call +.Fn vcons_redraw_screen +when this screen becomes visible. +.It Dv VCONS_SCREEN_IS_STATIC +don't +.Xr free 9 +this screen's +.Vt struct vcons_screen +in +.Fn free_screen +- useful if the screen has been statically allocated. +.El +.It Va scr_status +currently contains only one flag, +.Dv VCONS_IS_VISIBLE , +which is set when the screen is visible. +.El +.Sh SEE ALSO +.Xr wscons 4 , +.Xr wsdisplay 4 diff --git a/static/netbsd/man9/veriexec.9 b/static/netbsd/man9/veriexec.9 new file mode 100644 index 00000000..15ebddbd --- /dev/null +++ b/static/netbsd/man9/veriexec.9 @@ -0,0 +1,346 @@ +.\" $NetBSD: veriexec.9,v 1.29 2015/12/09 18:25:32 maxv Exp $ +.\" +.\" Copyright 2006 Elad Efrat <elad@NetBSD.org> +.\" Copyright 2006 Brett Lymn <blymn@NetBSD.org> +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Brett Lymn and Elad Efrat +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Neither the name of The NetBSD Foundation nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 9, 2015 +.Dt VERIEXEC 9 +.Os +.Sh NAME +.Nm veriexec +.Nd in-kernel file integrity subsystem KPI +.Sh SYNOPSIS +.In sys/verified_exec.h +.Ft void +.Fn veriexec_init "void" +.Ft bool +.Fn veriexec_lookup "struct vnode *vp" +.Ft int +.Fn veriexec_verify "struct lwp *l" "struct vnode *vp" \ +"const u_char *name" "int flag" "bool *found" +.Ft void +.Fn veriexec_purge "struct vnode *vp" +.Ft int +.Fn veriexec_fpops_add "const char *fp_type" "size_t hash_len" \ +"size_t ctx_size" "veriexec_fpop_init_t init" "veriexec_fpop_update_t update" \ +"veriexec_fpop_final_t final" +.Ft int +.Fn veriexec_file_add "struct lwp *l" "prop_dictionary_t dict" +.Ft int +.Fn veriexec_file_delete "struct lwp *l" "struct vnode *vp" +.Ft int +.Fn veriexec_table_delete "struct lwp *l" "struct mount *mp" +.Ft int +.Fn veriexec_flush "struct lwp *l" +.Ft int +.Fn veriexec_openchk "struct lwp *l" "struct vnode *vp" \ +"const char *path" "int fmode" +.Ft int +.Fn veriexec_renamechk "struct lwp *l" "struct vnode *fromvp" \ +"const char *fromname" "struct vnode *tovp" "const char *toname" +.Ft int +.Fn veriexec_removechk "struct lwp *l" "struct vnode *vp" \ +"const char *name" +.Ft int +.Fn veriexec_unmountchk "struct mount *mp" +.Ft int +.Fn veriexec_convert "struct vnode *vp" "prop_dictionary_t rdict" +.Ft int +.Fn veriexec_dump "struct lwp *l" "prop_array_t rarray" +.Sh DESCRIPTION +.Nm +is the +.Tn KPI +for +.Em Veriexec , +the +.Nx +in-kernel file integrity subsystem. +It is responsible for managing the supported hashing algorithms, fingerprint +calculation and comparison, file monitoring tables, and relevant hooks to +enforce the +.Em Veriexec +policy. +.Sh FUNCTIONS +.Ss Core Routines +.Bl -tag -width compact +.It Fn veriexec_init "void" +Initialize the +.Em Veriexec +subsystem. +Called only once during system startup. +.It Fn veriexec_lookup "vp" +Check if +.Ar vp +is monitored by +.Em Veriexec . +Returns +.Dv true +if it is, or +.Dv false +otherwise. +.It Fn veriexec_verify "l" "vp" "name" "flag" "found" +Verifies the digital fingerprint of +.Ar vp . +.Ar name +is the filename, and +.Ar flag +is the access flag. +The access flag can be one of: +.Bl -tag -width VERIEXEC_INDIRECT +.It Dv VERIEXEC_DIRECT +The file was executed directly via +.Xr execve 2 . +.It Dv VERIEXEC_INDIRECT +The file was executed indirectly, either as an interpreter for a script or +mapped to an executable memory region. +.It Dv VERIEXEC_FILE +The file was opened for reading/writing. +.El +.Pp +.Ar l +is the LWP for the request context. +.Pp +An optional argument, +.Ar found , +is a pointer to a boolean indicating whether an entry for the file was found +in the +.Em Veriexec +tables. +.It Fn veriexec_purge "vp" +Purge the file entry for +.Ar vp . +This invalidates the fingerprint so it will be evaluated next time the file +is accessed. +.\" veriexec_page_verify() intentionally not documented. +.El +.Ss Fingerprint Related Routines +.Bl -tag -width compact +.It Fn veriexec_fpops_add "fp_type" "hash_len" "ctx_size" \ +"init" "update" "final" +Add support for fingerprinting algorithm +.Ar fp_type +with binary hash length +.Ar hash_len +and calculation context size +.Ar ctx_size +to +.Em Veriexec . +.Ar init , +.Ar update , +and +.Ar final +are the routines used to initialize, update, and finalize a calculation +context. +.El +.Ss Table Management Routines +.Bl -tag -width compact +.It Fn veriexec_file_add "l" "dict" +Add a +.Em Veriexec +entry for the file described by +.Ar dict . +.Pp +.Ar dict +is expected to have the following: +.Bl -column entry-type string "entry type flags (see veriexec(4))" +.It Sy Name Type Purpose +.It file string filename +.It entry-type uint8 entry type flags ( see Xr veriexec 4 ) +.It fp-type string fingerprint hashing algorithm +.It fp data the fingerprint +.El +.It Fn veriexec_file_delete "l" "vp" +Remove +.Em Veriexec +entry for +.Ar vp . +.It Fn veriexec_table_delete "l" "mp" +Remove +.Em Veriexec +table for mount-point +.Ar mp . +.It Fn veriexec_flush "l" +Delete all +.Em Veriexec +tables. +.El +.Ss Hook Handlers +.Bl -tag -width compact +.It Fn veriexec_openchk "l" "vp" "path" "fmode" +Called when a file is opened. +.Pp +.Ar l +is the LWP opening the file, +.Ar vp +is a vnode for the file being opened as returned from +.Xr namei 9 . +If +.Dv NULL , +the file is being created. +.Ar path +is the pathname for the file (not necessarily a full path), and +.Ar fmode +are the mode bits with which the file was opened. +.It Fn veriexec_renamechk "l" "fromvp" "fromname" "tovp" "toname" +Called when a file is renamed. +.Pp +.Ar fromvp +and +.Ar fromname +are the vnode and filename of the file being renamed. +.Ar tovp +and +.Ar toname +are the vnode and filename of the target file. +.Ar l +is the LWP renaming the file. +.Pp +Depending on the strict level, +.Nm +will either track changes appropriately or prevent the rename. +.It Fn veriexec_removechk "l" "vp" "name" +Called when a file is removed. +.Pp +.Ar vp +is the vnode of the file being removed, and +.Ar name +is the filename. +.Ar l +is the LWP removing the file, +.Pp +Depending on the strict level, +.Nm +will either clean-up after the file or prevent its removal. +.It Fn veriexec_unmountchk "mp" +Checks if the current strict level allows +.Ar mp +to be unmounted. +.El +.Ss Miscellaneous Routines +.Bl -tag -width compact +.It Fn veriexec_convert "vp" "rdict" +Convert +.Em Veriexec +entry for +.Ar vp +to human-readable +.Xr proplib 3 +dictionary, +.Ar rdict , +with the following elements: +.Bl -column entryxtype string +.It Sy Name Type Purpose +.It entry-type uint8 entry type flags ( see Xr veriexec 4 ) +.It status uint8 entry status ( see below ) +.It fp-type string fingerprint hashing algorithm +.It fp data the fingerprint +.El +.Pp +The +.Dq status +can be one of the following: +.Bl -column fingerprintxmismatch effect +.It Sy Status Meaning +.It FINGERPRINT_NOTEVAL not evaluated +.It FINGERPRINT_VALID fingerprint match +.It FINGERPRINT_MISMATCH fingerprint mismatch +.El +.Pp +If no entry was found, +.Er ENOENT +is returned. +Otherwise, zero. +.It Fn veriexec_dump "l" "rarray" +Fill +.Ar rarray +with entries for all files monitored by +.Em Veriexec +that have a filename associated with them. +.Pp +Each element in +.Ar rarray +is a dictionary with the same elements as filled by +.Fn veriexec_convert , +with an additional field, +.Dq file , +containing the filename. +.El +.Sh FILES +.Bl -column srcxsysxkernxkernxverifiedexecxc foo +.It Sy Path Purpose +.It src/sys/dev/veriexec.c driver for userland communication +.It src/sys/sys/verified_exec.h shared (userland/kernel) header file +.It src/sys/kern/kern_veriexec.c subsystem code +.It src/sys/kern/vfs_syscalls.c rename, remove, and unmount policies +.It src/sys/kern/vfs_vnops.c regular file access policy +.El +.Sh SEE ALSO +.Xr proplib 3 , +.Xr sysctl 3 , +.Xr veriexec 4 , +.Xr security 7 , +.Xr sysctl 8 , +.Xr veriexecctl 8 , +.Xr veriexecgen 8 , +.Xr fileassoc 9 +.Sh AUTHORS +.An Brett Lymn Aq Mt blymn@NetBSD.org +.An Elad Efrat Aq Mt elad@NetBSD.org +.Sh CAVEATS +There are two known issues with +.Em Veriexec +that should be considered when using it. +.Ss Remote File-systems +There is an issue providing protection for files residing on mounts from +remote hosts. +Because access to the file-system does not necessarily go through +.Nm , +there is no way to track on-disk changes. +While it is possible to minimize the effect by evaluating the file's +fingerprint on each access without caching the result, a problem arises when +a file is overwritten after its fingerprint has been evaluated and it is +running on the local host. +.Pp +An attacker could potentially overwrite the file contents in the remote host +at that point, and force a flush on the local host, resulting in paging in +of the files from the disk, introducing malicious code into a supposedly +safe address space. +.Pp +There is a fix for this issue, however due to dependencies on other work +that is still in progress it has not been committed yet. +.Ss Layered File-systems +Due to VFS limitations, +.Nm +cannot track the same on-disk file across multiple layers of overlay +file-systems. +Therefore, you cannot expect changes to files on overlay mounts will be +detected simply because the underlying mount is monitored by +.Nm . +.Pp +A workaround for this issue is listing all files, under all mounts, you want +monitored in the signature file. diff --git a/static/netbsd/man9/versioningsyscalls.9 b/static/netbsd/man9/versioningsyscalls.9 new file mode 100644 index 00000000..9431719c --- /dev/null +++ b/static/netbsd/man9/versioningsyscalls.9 @@ -0,0 +1,374 @@ +.\" $NetBSD: versioningsyscalls.9,v 1.7 2024/05/23 06:35:45 pgoyette Exp $ +.\" +.\" Copyright (c) 2023 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Theodore Preduta. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 20, 2024 +.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 +compatibility with existing code. +This means that existing code keeps working the same way as before, and +new code can use new features and/or functionality. +In the past this has allowed +.Ft dev_t +to move from 16 bits to 32 bits, +.Ft ino_t +and +.Ft time_t +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 +.Pq Pa src/sys/compat . +Kernels can be compiled with or without backwards compatibility syscalls. +See the +.Dv COMPAT_ Ns Ar XX +options in +.Xr options 4 . +.Pp +In userland, the original syscall stub is moved into +.Pa src/lib/libc/compat +retaining the same symbol name and ABI. +The new stub is added to libc, and in the header file the syscall symbol is +made to point to the new name with the new ABI. +.Pp +This is done via symbol renaming instead of ELF versioned symbols for +historical reasons. +.Nx +has retained binary compatibility with most syscalls since +.Nx 0.9 +with the exception of Scheduler Activation syscalls which are not being +emulated because of the cost and safety of doing so. +.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 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 Em current +The version of the syscall currently in use. +.It Em next +The version of the syscall that will become standard in the next release. +.El +.Pp +Additionally, +.Ar CNUM +always represents the last +.Nx +release where the current +version of the system call is the default, multiplied by ten and retaining a +leading zero. +For example +.Nx 0.9 +has +.Dv COMPAT_09 +whereas +.Nx 10.0 +has +.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" +and that +.Ft my_struct +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 +.Ft struct my_struct , +first make a copy of +.Ft my_struct +renamed to +.Ft my_structCNUM +in an equivalent header in +.Pa sys/compat/sys . +After that, you can freely modify +.Ft my_struct +as desired. +. +.Ss Versioning the entry point +The stub for the next version of the syscall will be +.Fn __my_syscallVNUM , +and will have entry point +.Fn sys___my_syscallVNUM . +. +.Ss Modifying syscalls.conf +.Pa sys/kern/syscalls.conf +may need to be modified to contain +.Li compat_CNUM +in the +.Va compatopts +variable. +. +.Ss Modifying syscalls.master +First, add the next syscall to +.Pa sys/kern/syscalls.master +keeping +.Fn my_syscall +as the name, and set the (optional) compat field of the declaration to +.Ar CNUM . +.Pp +Next, modify the current version of the syscall, and replace the type +field +.Pq usually just Li STD +with +.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_CNUM +module. +.Pp +Finally, if applicable, replace the types of the current and old versions of the +syscall with the compat type. +.Pp +Overall, the final diff should look like +.Bd -literal +- 123 STD { int|sys||my_syscall(struct my_struct *ms); } ++ 123 COMPAT_CNUM MODULAR compat_CNUM { int|sys||my_syscall(struct my_structCNUM *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 CNUM +in the +.Dv RUMP_NBCOMPAT +variable. +. +.Ss Regenerating the system calls +If versioning structs, then modify +.Pa sys/kern/makesyscalls.sh +by adding an entry for +.Ft struct my_structCNUM +type to +.Va uncompattypes . +.Pp +The +.Va uncompattypes +map is used in +.Xr rump 7 +system call table generation, to map from the versioned types to the original +names since +.Xr rump 7 +wants to have a non-versioned copy of the system call table. +.Pp +Then regenerate the syscall tables in the usual way, first by running +.Pa sys/kern/makesyscalls.sh , +then if the system call is rump, doing a build in +.Pa sys/rump +and then running +.Pa sys/rump/makerumpsyscalls.sh +passing it the path to the result of the build you just did as its first +argument. +. +.Sh KERNEL COMPATIBILITY +This section covers maintaining compatibility at the kernel level, by +adding an entry point for the current syscall in an appropriate compat +module. +For the purposes of this section, we assume the current +syscall has entry point +.Fn sys_my_syscall +and lives inside +.Pa sys/kern/my_file.c . +. +.Ss Creating the compat current syscall +The compat version of the current syscall has entry point +.Fn compat_CNUM_sys_my_syscall , +and should be implemented in +.Pa sys/compat/common/my_file_CNUM.c +with the same semantics as the current syscall. +Often this involves translating the arguments to the next syscall, +and then calling that syscall's entry point. +. +.Ss Adding it to the compat module +.Pa sys/compat/common/my_file_CNUM.c +must contain an array of +.Ft struct syscall_package +that declares the mapping between syscall number and entry point, +terminating in a zero element (see sample diff below). +.Pp +Additionally, +.Pa sys/compat/common/my_file_CNUM.c +must contain two functions, +.Fn my_file_CNUM_init +and +.Fn my_file_CNUM_fini +that are used to initialize/clean up anything related to this syscall. +At the minimum they must make calls to +.Fn syscall_establish +and +.Fn syscall_disestablish +respectively, adding and removing the syscalls. +The stubs for these functions should be located in +.Pa sys/compat/common/compat_mod.h . +.Pp +Overall, +.Pa sys/compat/common/my_file_CNUM.c +must at the minimum contain +.Bd -literal -offset indent +static const struct syscall_package my_file_CNUM_syscalls[] = { + { SYS_compat_CNUM_my_syscall, 0, + (sy_call_t *)compat_CNUM_sys_my_syscall }, + { 0, 0, NULL }, +}; + +int +compat_CNUM_my_syscall(...) +{ /* Compat implementation goes here. */ } + +int +my_file_CNUM_init(void) +{ return syscall_establish(NULL, my_file_CNUM_syscalls); } + +int +my_file_CNUM_fini(void) +{ return syscall_disestablish(NULL, my_file_CNUM_syscalls); } +.Ed +.Pp +Finally, +.Pa sys/compat/common/compat_CNUM_mod.c +needs to be modified to have its +.Fn compat_CNUM_init +and +.Fn compat_CNUM_fini +functions call +.Fn my_file_CNUM_init +and +.Fn my_file_CNUM_fini +respectively. +. +.Ss Modifying old compat syscalls +If the current syscall has already been versioned, you might need to +modify the old compat syscalls in +.Pa sys/compat/common +to either use the next syscall or the current compat syscall. +Note that compat code can be made to depend on compat code for more +recent releases. +.Sh USERLAND COMPATIBILITY +With the exception of the libraries described below, making the rest +of userland work will just involve recompiling, and perhaps changing a +constant or a +.Li #define . +. +.Ss libc +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 +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 <sys/my_header.h> to generate correct reference . +.Pp +Overall, +.Pa lib/libc/compat/sys/compat_my_syscall.c +must at the minimum include +.Bd -literal -offset indent +#include <sys/compat/my_header.h> + +__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 diff --git a/static/netbsd/man9/vfs.9 b/static/netbsd/man9/vfs.9 new file mode 100644 index 00000000..2d4362f6 --- /dev/null +++ b/static/netbsd/man9/vfs.9 @@ -0,0 +1,56 @@ +.\" $NetBSD: vfs.9,v 1.8 2008/04/30 13:10:59 martin Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 22, 2001 +.Dt VFS 9 +.Os +.Sh NAME +.Nm vfs +.Nd kernel interface to file systems +.Sh DESCRIPTION +The virtual file system, +.Nm , +is the kernel interface to file systems. +The interface specifies the calls for the kernel to access file systems. +It also specifies the core functionality that a file system must provide +to the kernel. +.Pp +The focus of +.Nm +activity is the +.Em vnode +and is discussed in +.Xr vnode 9 . +File system operations such as mounting and syncing are discussed in +.Xr vfsops 9 . +.Sh SEE ALSO +.Xr intro 9 , +.Xr vfsops 9 , +.Xr vnode 9 , +.Xr vnodeops 9 diff --git a/static/netbsd/man9/vfs_hooks.9 b/static/netbsd/man9/vfs_hooks.9 new file mode 100644 index 00000000..e6aca0e5 --- /dev/null +++ b/static/netbsd/man9/vfs_hooks.9 @@ -0,0 +1,104 @@ +.\" $NetBSD: vfs_hooks.9,v 1.4 2008/04/30 13:10:59 martin Exp $ +.\" +.\" Copyright (c) 2005 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Julio M. Merino Vidal. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 23, 2005 +.Dt VFS_HOOKS 9 +.Os +.Sh NAME +.Nm vfs_hooks , +.Nm vfs_hooks_unmount +.Nd VFS hooks interface +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft void +.Fn vfs_hooks_unmount "struct mount *mp" +.Sh DESCRIPTION +The VFS hooks interface provides a way for different kernel subsystems to +attach custom functions to specific VFS operations. +This enforces code separation by keeping the VFS's core sources uncluttered +and makes all subsystem functionality reside in a single place. +As an example, this interface is used by the NFS server code to automatically +handle the exports list for each mount point. +.Pp +Hooks are described by a +.Ft struct vfs_hooks +object, as seen below: +.Bd -literal +struct vfs_hooks { + int (*vh_unmount)(struct mount *); +}; +.Ed +.Pp +For simplicity, each field is named after the VFS operation it refers to. +The purpose of each member function, alongside some important notes, is +shown below: +.Bl -tag -width compat +.It Fn vh_unmount "mp" +This hook is executed during the unmount process of a file system. +.El +.Pp +For more information about the purpose of each operation, see +.Xr vfsops 9 . +Note that any of these fields may be a null pointer. +.Pp +After the definition of a +.Ft struct vfs_hooks +object, the kernel has to add it to the +.Va vfs_hooks +link set using the +.Fn VFS_HOOKS_ATTACH "struct vfs_hooks *" +macro. +.Pp +Please note that this interface is incomplete on purpose to keep it in its +smallest possible size (i.e., do not provide a hook that is not used). +If you feel the need to hook a routine to a VFS operation that is not yet +supported by this interface, just add it to the files described in +.Sx CODE REFERENCES . +.Sh FUNCTIONS +The following functions are provided to the VFS code to run the hooked +functions: +.Bl -tag -width compact +.It Fn vfs_hooks_unmount "mp" +Runs all hooks for the VFS unmount operation. +Given that these operations shall not fail, it returns +.Ft void . +.El +.Sh CODE REFERENCES +The VFS hooks interface is implemented within the files +.Pa sys/kern/vfs_hooks.c +and +.Pa sys/sys/mount.h . +.Sh SEE ALSO +.Xr intro 9 , +.Xr vfs 9 , +.Xr vfsops 9 +.Sh HISTORY +The VFS hooks interface appeared in +.Nx 4.0 . diff --git a/static/netbsd/man9/vfsops.9 b/static/netbsd/man9/vfsops.9 new file mode 100644 index 00000000..0087be5f --- /dev/null +++ b/static/netbsd/man9/vfsops.9 @@ -0,0 +1,505 @@ +.\" $NetBSD: vfsops.9,v 1.53 2020/08/28 07:28:59 hannken Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 7, 2020 +.Dt VFSOPS 9 +.Os +.Sh NAME +.Nm vfsops , +.Nm VFS_MOUNT , +.Nm VFS_START , +.Nm VFS_UNMOUNT , +.Nm VFS_ROOT , +.Nm VFS_QUOTACTL , +.Nm VFS_STATVFS , +.Nm VFS_SYNC , +.Nm VFS_VGET , +.Nm VFS_LOADVNODE , +.Nm VFS_NEWVNODE , +.Nm VFS_FHTOVP , +.Nm VFS_VPTOFH , +.Nm VFS_SNAPSHOT , +.Nm VFS_SUSPENDCTL +.Nd kernel file system interface +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In sys/vnode.h +.Ft int +.Fo VFS_MOUNT +.Fa "struct mount *mp" "const char *path" "void *data" "size_t *dlen" +.Fc +.Ft int +.Fn VFS_START "struct mount *mp" "int flags" +.Ft int +.Fn VFS_UNMOUNT "struct mount *mp" "int mntflags" +.Ft int +.Fn VFS_ROOT "struct mount *mp" "int lktype" "struct vnode **vpp" +.Ft int +.Fn VFS_QUOTACTL "struct mount *mp" "struct quotactl_args *args" +.Ft int +.Fn VFS_STATVFS "struct mount *mp" "struct statvfs *sbp" +.Ft int +.Fn VFS_SYNC "struct mount *mp" "int waitfor" "kauth_cred_t cred" +.Ft int +.Fn VFS_VGET "struct mount *mp" "ino_t ino" "int lktype" "struct vnode **vpp" +.Ft int +.Fn VFS_LOADVNODE "struct mount *mp" "struct vnode *vp" "const void *key" "size_t key_len" "const void **new_key" +.Ft int +.Fn VFS_NEWVNODE "struct mount *mp" "struct vnode *dvp" "struct vnode *vp" "struct vattr *vap" "kauth_cred_t cred" "void *extra" "size_t *key_len" "const void **new_key" +.Ft int +.Fn VFS_FHTOVP "struct mount *mp" "struct fid *fhp" "int lktype" "struct vnode **vpp" +.Ft int +.Fn VFS_VPTOFH "struct vnode *vp" "struct fid *fhp" "size_t *fh_size" +.Ft int +.Fn VFS_SNAPSHOT "struct mount *mp" "struct vnode *vp" "struct timespec *ts" +.Ft int +.Fn VFS_SUSPENDCTL "struct mount *mp" "int cmd" +.Sh DESCRIPTION +In a similar fashion to the +.Xr vnode 9 +interface, all operations that are done on a file system are conducted +through a single interface that allows the system to carry out +operations on a file system without knowing its construction or type. +.Pp +All supported file systems in the kernel have an entry in the +.Va vfs_list_initial +table. +This table is generated by +.Xr config 1 +and is a +.Dv NULL Ns No -terminated +list of +.Vt vfsops +structures. +The vfsops structure describes the operations that can be done to a +specific file system type. +The following table lists the elements of the vfsops vector, the +corresponding invocation macro, and a description of the element. +.Pp +.Bl -column "int (*vfs_suspendctl)()" "VFS_SUSPENDCTL" -compact +.It Sy Vector element Ta Sy Macro Ta Sy Description +.\" +.It int (*vfs_mount)() \ +Ta Dv VFS_MOUNT \ +Ta Mount a file system +.\" +.It int (*vfs_start)() \ +Ta Dv VFS_START \ +Ta Make operational +.\" +.It int (*vfs_unmount)() \ +Ta Dv VFS_UNMOUNT \ +Ta Unmount a file system +.\" +.It int (*vfs_root)() \ +Ta Dv VFS_ROOT \ +Ta Get the file system root vnode +.\" +.It int (*vfs_quotactl)() \ +Ta Dv VFS_QUOTACTL \ +Ta Query/modify space quotas +.\" +.It int (*vfs_statvfs)() \ +Ta Dv VFS_STATVFS \ +Ta Get file system statistics +.\" +.It int (*vfs_sync)() \ +Ta Dv VFS_SYNC \ +Ta Flush file system buffers +.\" +.It int (*vfs_vget)() \ +Ta Dv VFS_VGET \ +Ta Get vnode from file id +.\" +.It int (*vfs_loadvnode)() \ +Ta Dv VFS_LOADVNODE \ +Ta Initialize vnode with file +.\" +.It int (*vfs_newvnode)() \ +Ta Dv VFS_NEWVNODE \ +Ta Initialize vnode with new file +.\" +.It int (*vfs_fhtovp)() \ +Ta Dv VFS_FHTOVP \ +Ta NFS file handle to vnode lookup +.\" +.It int (*vfs_vptofh)() \ +Ta Dv VFS_VPTOFH \ +Ta Vnode to NFS file handle lookup +.\" +.It void (*vfs_init)() \ +Ta \- \ +Ta Initialize file system +.\" +.It void (*vfs_reinit)() \ +Ta \- \ +Ta Reinitialize file system +.\" +.It void (*vfs_done)() \ +Ta \- \ +Ta Cleanup unmounted file system +.\" +.It int (*vfs_mountroot)() \ +Ta \- \ +Ta Mount the root file system +.\" +.It int (*vfs_snapshot)() \ +Ta Dv VFS_SNAPSHOT \ +Ta Take a snapshot +.\" +.It int (*vfs_suspendctl)() \ +Ta Dv VFS_SUSPENDCTL \ +Ta Suspend or resume +.El +.Pp +Some additional non-function members of the vfsops structure are the +file system name +.Fa vfs_name +and a reference count +.Fa vfs_refcount . +It is not mandatory for a file system type to support a particular +operation, but it must assign each member function pointer to a +suitable function to do the minimum required of it. +In most cases, such functions either do nothing or return an error +value to the effect that it is not supported. +.Fa vfs_reinit , +.Fa vfs_mountroot , +.Fa vfs_fhtovp , +and +.Fa vfs_vptofh +may +be +.Dv NULL . +.Pp +At system boot, each file system with an entry in +.Va vfs_list_initial +is established and initialized. +Each initialized file system is recorded by the kernel in the list +.Va vfs_list +and the file system specific initialization function +.Fa vfs_init +in its vfsops vector is invoked. +When the file system is no longer needed +.Fa vfs_done +is invoked to run file system specific cleanups and the file system is +removed from the kernel list. +.Pp +At system boot, the root file system is mounted by invoking the file +system type specific +.Fa vfs_mountroot +function in the vfsops vector. +All file systems that can be mounted as a root file system must define +this function. +It is responsible for initializing to list of mount structures for +all future mounted file systems. +.Pp +Kernel state which affects a specific file system type can be +queried and modified using the +.Xr sysctl 8 +interface. +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn VFS_MOUNT "mp" "path" "data" "dlen" +Mount a file system specified by the mount structure +.Fa mp +on the mount point described by +.Fa path . +The argument +.Fa data +contains file system type specific data, while the argument +.Fa dlen +points to a location specifying the length of the data. +.Pp +.Fn VFS_MOUNT +initializes the mount structure for the mounted file system. +This structure records mount-specific information for the file system and +records the list of vnodes associated with the file system. +This function is invoked both to mount new file systems and to change the +attributes of an existing file system. +If the flag +.Dv MNT_UPDATE +is set in +.Va mp->mnt_flag , +the file system should update its state. +This can be used, for instance, to convert a read-only file system to +read-write. +The current attributes for a mounted file system can be fetched by +specifying +.Dv MNT_GETARGS . +If neither +.Dv MNT_UPDATE +or +.Dv MNT_GETARGS +are specified, a new file system will attempted to be mounted. +.It Fn VFS_START "mp" "flags" +Make the file system specified by the mount structure +.Fa mp +operational. +The argument +.Fa flags +is a set of flags for controlling the operation of +.Fn VFS_START . +This function is invoked after +.Fn VFS_MOUNT +and before the first access to the file system. +.It Fn VFS_UNMOUNT "mp" "mntflags" +Unmount a file system specified by the mount structure +.Fa mp . +.Fn VFS_UNMOUNT +performs any file system type specific operations required before the +file system is unmounted, such are flushing buffers. +If +.Dv MNT_FORCE +is specified in the flags +.Fa mntflags +then open files are forcibly closed. +The function also deallocates space associated with data structure +that were allocated for the file system when it was mounted. +.It Fn VFS_ROOT "mp" "lktype" "vpp" +Get the root vnode of the file system specified by the mount +structure +.Fa mp . +The vnode is returned in the address given by +.Fa vpp , +with lock type +.Fa lktype . +.Fa lktype +can be +.Dv LK_NONE , +or +.Dv LK_SHARED , +or +.Dv LK_EXCLUSIVE . +This function is used by the pathname translation algorithms when a +vnode that has been covered by a mounted file system is encountered. +While resolving the pathname, the pathname translation algorithm will +have to go through the directory tree in the file system associated +with that mount point and therefore requires the root vnode of the +file system. +.It Fn VFS_QUOTACTL "mp" "args" +Query/modify user space quotas for the file system specified by the +mount structure +.Fa mp . +The argument structure provides the operation ID and arguments to +perform. +This is the same interface as documented in +.Xr __quotactl 2 +except that the file system argument has been resolved. +All +.Xr copyin 9 +and +.Xr copyout 9 +processing is handled by code above the file system. +.It Fn VFS_STATVFS "mp" "sbp" +Get file system statistics for the file system specified by the mount +structure +.Fa mp . +A statvfs structure filled with the statistics is returned in +.Fa sbp . +.Fn VFS_STATVFS +is the file system type specific implementation of the +.Xr statvfs 2 +and +.Xr fstatvfs 2 +system calls. +.It Fn VFS_SYNC "mp" "waitfor" "cred" +Flush file system I/O buffers for the file system specified by the mount +structure +.Fa mp . +The +.Fa waitfor +argument indicates whether a partial flush or complete flush should be +performed. +The argument +.Fa cred +specifies the calling credentials. +.Fn VFS_SYNC +does not provide any return value since the operation can never fail. +.It Fn VFS_VGET "mp" "ino" "lktype" "vpp" +Get vnode for a file system type specific file id +.Fa ino +for the file system specified by the mount structure +.Fa mp , +with lock type +.Fa lktype . +.Fa lktype +can be +.Dv LK_NONE , +or +.Dv LK_SHARED , +or +.Dv LK_EXCLUSIVE . +The vnode is returned in the address specified +.Fa vpp . +The function is optional for file systems which have a unique id +number for every file in the file system. +It is used internally by the UFS file system and also by the NFSv3 +server to implement the READDIRPLUS NFS call. +If the file system does not support this function, it should return +.Er EOPNOTSUPP . +.It Fn VFS_LOADVNODE "mp" "vp" "key" "key_len" "new_key" +Initialise the vnode +.Fa vp +with the file identified by the arguments +.Fa key +and +.Fa key_len +for the file system specified by the mount structure +.Fa mp . +.Pp +The new key is returned in the address specified by +.Fa new_key . +.Pp +Caller of this function assures no other thread will try to load this file. +.It Fn VFS_NEWVNODE "mp" "dvp" "vp" "vap" "cred" "extra" "key_len" "new_key" +Initialise the vnode +.Fa vp +with a new file for the file system specified by the mount structure +.Fa mp . +.Pp +The argument +.Fa dvp +points to the directory to create the file in. +.Pp +The argument +.Fa vap +points to the attributes for the file to create. +.Pp +The argument +.Fa cred +holds the credentials for the file to create. +.Pp +The argument +.Fa extra +allows the caller to pass more information about the file to create. +.Pp +The key for the file is returned in the addresses specified by +.Fa key_len +and +.Fa new_key . +.It Fn VFS_FHTOVP "mp" "fhp" "lktype" "vpp" +Get the vnode for the file handle +.Fa fhp +in the file system specified by the mount structure +.Fa mp , +with lock type +.Fa lktype . +.Fa lktype +can be +.Dv LK_NONE , +or +.Dv LK_SHARED , +or +.Dv LK_EXCLUSIVE . +The locked vnode is returned in +.Fa vpp . +.Pp +When exporting, the call to +.Fn VFS_FHTOVP +should follow a call to +.Fn netexport_check , +which checks if the file is accessible to the client. +.Pp +If file handles are not supported by the file system, this function +must return +.Er EOPNOTSUPP . +.It Fn VFS_VPTOFH "vp" "fhp" "fh_size" +Get a file handle for the vnode specified by +.Fa vp . +The file handle is returned in +.Fa fhp . +The contents of the file handle are defined by the file system and are +not examined by any other subsystems. +It should contain enough information to uniquely identify a file within +the file system as well as noticing when a file has been removed and +the file system resources have been recycled for a new file. +.Pp +The parameter +.Fa fh_size +points to the container size for the file handle. +This parameter should be updated to the size of the finished file handle. +Note that it is legal to call this function with +.Fa fhp +set to +.Dv NULL +in case +.Fa fh_size +is zero. +In case +.Fa fh_size +indicates a storage space too small, the storage space required for +the file handle corresponding to +.Fa vp +should be filled in and +.Er E2BIG +should be returned. +.Pp +If file handles are not supported by the file system, this function +must return +.Er EOPNOTSUPP . +.It Fn VFS_SNAPSHOT "mp" "vp" "ts" +Take a snapshot of the file system specified by the mount structure +.Fa mp +and make it accessible through the locked vnode +.Fa vp . +If +.Fa ts +is not +.Dv NULL +it will receive the time this snapshot was taken. +If the file system does not support this function, it should return +.Er EOPNOTSUPP . +.It Fn VFS_SUSPENDCTL "mp" "cmd" +Suspend or resume all operations on this file system. +.Fa cmd +is either +.Dv SUSPEND_SUSPEND +to suspend or +.Dv SUSPEND_RESUME +to resume operations. +If the file system does not support this function, it should return +.Er EOPNOTSUPP . +.El +.Sh CODE REFERENCES +The vfs operations are implemented within the files +.Pa sys/kern/vfs_subr.c +and +.Pa sys/kern/vfs_init.c . +.Sh SEE ALSO +.Xr intro 9 , +.Xr namei 9 , +.Xr vfs 9 , +.Xr vfssubr 9 , +.Xr vnode 9 , +.Xr vnodeops 9 +.Sh HISTORY +The vfs operations vector, its functions and the corresponding macros +appeared in +.Bx 4.3 . diff --git a/static/netbsd/man9/vfssubr.9 b/static/netbsd/man9/vfssubr.9 new file mode 100644 index 00000000..1026e07a --- /dev/null +++ b/static/netbsd/man9/vfssubr.9 @@ -0,0 +1,254 @@ +.\" $NetBSD: vfssubr.9,v 1.28 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright (c) 2003, 2005, 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 17, 2017 +.Dt VFSSUBR 9 +.Os +.Sh NAME +.Nm vfssubr , +.Nm vfs_getnewfsid , +.Nm vfs_getvfs , +.Nm vfs_export , +.Nm vfs_showexport , +.Nm vfs_export_lookup , +.Nm vfs_setpublicfs , +.Nm vfs_mountedon , +.Nm vfs_mountroot , +.Nm vfs_unmountall , +.Nm vfs_busy , +.Nm vfs_unbusy , +.Nm vfs_mountalloc , +.Nm vfs_rootmountalloc , +.Nm vfs_shutdown , +.Nm vfs_attach , +.Nm vfs_detach , +.Nm vfs_reinit , +.Nm vfs_getopsbyname , +.Nm vfs_suspend , +.Nm vfs_resume , +.Nm vfs_vnode_iterator_init , +.Nm vfs_vnode_iterator_destroy , +.Nm vfs_vnode_iterator_next +.Nd high-level interface to kernel file system interface +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In sys/vnode.h +.Ft void +.Fn vfs_getnewfsid "struct mount *mp" +.Ft struct mount * +.Fn vfs_getvfs "fsid_t *fsid" +.Ft int +.Fn vfs_export_lookup "struct mount *mp" "struct netexport *nep" \ +"struct export_args *argp" +.Ft int +.Fn vfs_setpublicfs "struct mount *mp" "struct netexport *nep" \ +"struct export_args *argp" +.Ft int +.Fn vfs_mountedon "struct vnode *vp" +.Ft int +.Fn vfs_mountroot "void" +.Ft void +.Fn vfs_unmountall "struct lwp *l" +.Ft int +.Fn vfs_busy "struct mount *mp" +.Ft void +.Fn vfs_unbusy "struct mount *mp" +.Ft struct mount * +.Fn vfs_mountalloc "struct vfsops *vfs" "struct vnode *vp" +.Ft int +.Fn vfs_rootmountalloc "char *fstypename" "char *devname" \ +"struct mount **mpp" +.Ft void +.Fn vfs_shutdown "void" +.Ft int +.Fn vfs_attach "struct vfsops *vfs" +.Ft int +.Fn vfs_detach "struct vfsops *vfs" +.Ft void +.Fn vfs_reinit "void" +.Ft struct vfsops * +.Fn vfs_getopsbyname "const char *name" +.Ft int +.Fn vfs_suspend "struct mount *mp" "int nowait" +.Ft void +.Fn vfs_resume "struct mount *mp" +.Ft void +.Fn vfs_vnode_iterator_init "struct mount *mp" "struct vnode_iterator **vip" +.Ft void +.Fn vfs_vnode_iterator_destroy "struct vnode_iterator *vi" +.Ft struct vnode * +.Fn vfs_vnode_iterator_next "struct vnode_iterator *vi" "bool (*selector)(void *context, struct vnode *vpp)" "void *context" +.Sh DESCRIPTION +The high-level functions described in this page are the interface to +the kernel file system interface (VFS). +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn vfs_getnewfsid "mp" +Get a new unique file system id type for the file system specified by +the mount structure +.Fa mp . +The file system id type is stored in +.Em mp->mnt_stat.f_fsidx . +.It Fn vfs_getvfs "fsid" +Lookup a mount point with the file system identifier +.Fa fsid . +.It Fn vfs_export_lookup "mp" "nep" "argp" +Check client permission on the exportable file system specified by the +mount structure +.Fa mp . +The argument +.Fa nam +is the address of the networked client. +This function is used by file system type specific functions to verify +that the client can access the file system. +.It Fn vfs_setpublicfs "mp" "nep" "argp" +Set the publicly exported file system specified by the mount structure +.Fa mp . +.It Fn vfs_mountedon "vp" +Check to see if a file system is mounted on a block device specified +by the vnode +.Fa vp . +.It Fn vfs_mountroot "void" +Mount the root file system. +.It Fn vfs_unmountall "l" +Unmount all file systems. +.It Fn vfs_busy "mp" +Mark the mount point specified by +.Fa mp +as busy and get a reference to it. +This function is used to synchronize access and to delay unmounting. +The caller must hold a pre-existing reference to the mount. +.It Fn vfs_unbusy "mp" +Undo a +.Fn vfs_busy +on the mount point specified by +.Fa mp . +.It Fn vfs_mountalloc "vfsops" "vp" +Allocate and initialise a mount structure, setting +.Em mnt_vnodecovered +to +.Fa vp +and +.Em mnt_op +to +.Fa vfsops . +On success return the address of the mount structure. +Otherwise, return +.Dv NULL . +.It Fn vfs_rootmountalloc "fstypename" "devname" "mpp" +Lookup a file system type specified by the name +.Fa fstypename +and if found allocate and initialise a mount structure for it. +The allocated mount structure is marked as busy and returned in the +address specified by +.Fa mpp . +The device the root file system was mounted from is specified by the +argument +.Fa devname +and is recorded in the new mount structure. +.It Fn vfs_shutdown +Sync and unmount all file systems before shutting down. +Invoked by +.Xr cpu_reboot 9 . +.It Fn vfs_attach "vfs" +Establish file system +.Fa vfs +and initialise it. +.It Fn vfs_detach "vfs" +Remove file system +.Fa vfs +from the kernel. +.It Fn vfs_reinit "void" +Reinitialises all file systems within the kernel through file +system-specific vfs operation (see +.Xr vfsops 9 ) . +.It Fn vfs_getopsbyname "name" +Given a file system name specified by +.Fa name , +look up the vfs operations for that file system (see +.Xr vfsops 9 ) , +or return +.Dv NULL +if file system isn't present in the kernel. +.It Fn vfs_suspend "mp" "nowait" +Request a mounted file system to suspend all operations. +All new operations to the file system are stopped. +After all operations in progress have completed, the +file system is synced to disk and the function returns. +If a file system suspension is currently in progress and +.Fa nowait +is set +.Er EWOULDBLOCK +is returned. +If the operation is successful, zero is returned, otherwise an +appropriate error code is returned. +.It Fn vfs_resume "mp" +Request a mounted file system to resume operations. +.It Fn vfs_vnode_iterator_init "mp" "vip" +Allocate and initialize an iterator +.Fa vip +over all vnodes attached to mount point +.Fa mp . +.It Fn vfs_vnode_iterator_destroy "vi" +Free all resources associated with an iterator +.Fa vi . +.It Fn vfs_vnode_iterator_next "vi" "selector" "context" +Return the next vnode from iterator +.Fa vi . +If the operation is successful the vnode has a reference added to it +and it is returned. +If the iterator is exhausted the function returns +.Dv NULL . +If an optional +.Fa selector +function is provided, then this function is called with the +.Fa context +provided and the candidate vnode to be returned. +If the +.Fa selector +returns +.Dv false , +then the vnode is skipped; if it returns +.Dv true , +the vnode is referenced and then returned. +.El +.Sh CODE REFERENCES +The vfs interface functions are implemented within the files +.Pa sys/kern/vfs_mount.c , +.Pa sys/kern/vfs_subr.c +and +.Pa sys/kern/vfs_init.c . +.Sh SEE ALSO +.Xr intro 9 , +.Xr namei 9 , +.Xr vfs 9 , +.Xr vfsops 9 , +.Xr vnode 9 , +.Xr vnodeops 9 diff --git a/static/netbsd/man9/video.9 b/static/netbsd/man9/video.9 new file mode 100644 index 00000000..3c11e6d9 --- /dev/null +++ b/static/netbsd/man9/video.9 @@ -0,0 +1,187 @@ +.\" $NetBSD: video.9,v 1.7 2014/03/18 18:20:40 riastradh Exp $ +.\" +.\" Copyright (c) 2008 Patrick Mahoney +.\" All rights reserved. +.\" +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 24, 2008 +.Dt VIDEO 9 +.Os +.Sh NAME +.Nm video +.Nd interface between low and high level video drivers +.Sh SYNOPSIS +.In dev/video_if.h +.Ft device_t +.Fn video_attach_mi "const struct video_hw_if *hw_if" "device_t hw_dev" +.Ft void +.Fn video_submit_payload "device_t vl_dev" "const struct video_payload *payload" +.Sh DESCRIPTION +The video device driver is divided into a high level, machine +independent layer, and a low level hardware dependent layer. +The interface between these is the +.Fa video_hw_if +structure function pointers called by the video layer, and video layer +functions called by the hardware driver. +.Pp +The high level video driver attaches to the low level driver +when the latter calls +.Fa video_attach_mi . +The +.Fa video_hw_if +struct is as shown below. +.Fa dev +is the device struct for the hardware device. +Return value is the video layer device. +.Bd -literal +struct video_hw_if { + int (*open)(void *, int); /* open hardware */ + void (*close)(void *); /* close hardware */ + + const char * (*get_devname)(void *); + + int (*enum_format)(void *, uint32_t, struct video_format *); + int (*get_format)(void *, struct video_format *); + int (*set_format)(void *, struct video_format *); + int (*try_format)(void *, struct video_format *); + + int (*start_transfer)(void *); + int (*stop_transfer)(void *); + + int (*control_iter_init)(void *, struct video_control_iter *); + int (*control_iter_next)(void *, struct video_control_iter *); + int (*get_control_desc_group)(void *, + struct video_control_desc_group *); + int (*get_control_group)(void *, struct video_control_group *); + int (*set_control_group)(void *, const struct video_control_group *); +}; +.Ed +.Pp +The upper layer of the video driver allocates buffers for video +samples. +The hardware driver submits data to the video layer with +.Fa video_submit_payload . +.Fa vl_dev +is the video layer device returned by +.Fa video_attach_mi . +.Bd -literal +struct video_payload { + const uint8_t *data; + size_t size; + int frameno; + bool end_of_frame; +}; +.Ed +.Bl -tag -width indent +.It Fa data +Pointer to the video data for this payload. +This may only be a +portion of the data in one video sample or frame. +.It Fa size +Size in bytes of the video data in this payload +.It Fa frameno +Frame number to which this payload belongs. +The hardware driver must toggle the frame number between 0 and 1 +so the video layer can detect sample or frame boundaries. +.It Fa end_of_frame +Optional end of frame marker. +If the hardware layer sets this, the +video layer can immediately pass the completed sample or frame to +userspace rather than waiting for the next payload to toggle +.Fa frameno . +.El +.Sh HARDWARE-LAYER FUNCTIONS +The fields of +.Va video_hw_if +are described in some more detail below. +Some fields are optional and can be set to +.Dv NULL +if not needed. +.Bl -tag -width indent +.It Dv int open(void *hdl, int flags) +optional, is called when the video device is opened. +It should initialize the hardware for I/O. +Every successful call to +.Va open +is matched by a call to +.Va close . +Return 0 on success, otherwise an error code. +.It Dv void close(void *hdl) +optional, is called when the audio device is closed. +.It Dv const char * get_devname(void *hdl) +mandatory, returns a NUL-terminated string naming the device, e.g. a +vendor and product model name. +.It Dv int enum_format(void *hdl, uint32_t index, struct video_format *format); +mandatory, called with an +.Va index +from 0 to +.Va max_index \- 1 . +Fills +.Va format +with the format description at that index. +Returns 0 on success, otherwise an error code. +.It Dv int get_format(void *hdl, struct video_format *format) +mandatory, fills +.Va format +with the current video format. +There should be a default format so +this function works before and streaming has begun. +Returns 0 on success, otherwise an error code. +.It Dv int set_format(void *hdl, struct video_format *format) +mandatory, sets the format of the video stream based on +.Va format . +Fills +.Va format +with the actual format used which may not be the same as requested. +Returns 0 on success, otherwise an error code. +.It Dv int try_format(void *hdl, struct video_format *format) +optional, like +.Va set_format +but does not actually change the stream format, just checks what is +available. +Returns 0 on success, otherwise an error code. +.It Dv int start_transfer(void *hdl) +mandatory, starts the capture of video frames. +Incoming video data +must be submitted to the video layer with repeated calls to +.Fn video_submit_payload . +.It Dv int stop_transfer(void *hdl) +.It Dv int control_iter_init(void *hdl, struct video_control_iter *) +Does nothing at this time. +.It Dv int control_iter_next(void *hdl, struct video_control_iter *) +Does nothing at this time. +.It Dv int get_control_group(void *hdl, struct video_control_group *) +.It Dv int set_control_group(void *hdl, struct video_control_group *) +.El +.Sh SEE ALSO +.Xr video 4 +.Sh AUTHORS +.An Patrick Mahoney Aq Mt pat@polycrystal.org +.Sh BUGS +Incomplete. +Only supports a single video capture stream. +Does not support output streams. +Format handling may change in the future. +Control handling may change. +Current design requires copying all incoming video data. diff --git a/static/netbsd/man9/vme.9 b/static/netbsd/man9/vme.9 new file mode 100644 index 00000000..a45b079d --- /dev/null +++ b/static/netbsd/man9/vme.9 @@ -0,0 +1,346 @@ +.\" $NetBSD: vme.9,v 1.13 2011/07/01 17:34:44 dyoung Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 12, 2001 +.Dt VME 9 +.Os +.Sh NAME +.Nm VME , +.Nm vme_probe , +.Nm vme_space_map , +.Nm vme_space_unmap , +.Nm vme_intr_map , +.Nm vme_intr_establish , +.Nm vme_intr_disestablish , +.Nm vme_intr_evcnt , +.Nm vme_dmamap_create , +.Nm vme_dmamap_destroy , +.Nm vme_dmamem_alloc , +.Nm vme_dmamem_free , +.Nm vme_space_alloc , +.Nm vme_space_free , +.Nm vme_space_get +.Nd Versa Module Euroboard bus +.Sh SYNOPSIS +.In sys/bus.h +.In dev/vme/vmereg.h +.In dev/vme/vmevar.h +.Ft int +.Fn vme_probe "void *vc" "vme_addr_t vmeaddr" "vme_size_t len" "vme_am_t am" \ +"vme_datasize_t datasize" \ +"int (*callback)()" "void *arg" +.Ft int +.Fo vme_space_map +.Fa "void *vc" "vme_addr_t vmeaddr" "vme_size_t len" \ +"vme_am_t am" "vme_datasize_t datasize" "vme_swap_t swap" \ +"bus_space_tag_t *tag" "bus_space_handle_t *handle" "vme_mapresc_t *resc" +.Fc +.Ft void +.Fn vme_space_unmap "void *vc" "vme_mapresc_t resc" +.Ft int +.Fn vme_intr_map "void *vc" "int level" "int vector" \ +"vme_intr_handle_t *handlep" +.Ft void * +.Fn vme_intr_establish "void *vc" "vme_intr_handle_t handle" "int prio" \ +"int (*func)(void *)" "void *arg" +.Ft void +.Fn vme_intr_disestablish "void *vc" "void *cookie" +.Ft const struct evcnt * +.Fn vme_intr_evcnt "void *vc" "vme_intr_handle_t handle" +.Ft int +.Fo vme_dmamap_create +.Fa "void *vc" "vme_size_t size" "vme_am_t am" "vme_datasize_t datasize" +.Fa "vme_swap_t swap" "int nsegs" "vme_size_t segsz" "vme_addr_t bound" +.Fa "int flags" "bus_dmamap_t *map" +.Fc +.Ft void +.Fn vme_dmamap_destroy "void *vc" "bus_dmamap_t map" +.Ft int +.Fo vme_dmamem_alloc +.Fa "void *vc" "vme_size_t size" "vme_am_t am" \ +"vme_datasize_t datasize" "vme_swap_t swap" "bus_dma_segment_t *segs" \ +"int nsegs" "int *rsegs" "int flags" +.Fc +.Ft void +.Fn vme_dmamem_free "void *vc" "bus_dma_segment_t *segs" "int nsegs" +.Ft int +.Fn vme_space_alloc "struct vmebus_softc *tag" "vme_addr_t addr" "vme_size_t size" "vme_am_t ams" +.Ft void +.Fn vme_space_free "void *vc" "vme_addr_t addr" "vme_size_t size" \ +"vme_am_t ams" +.Ft int +.Fn vme_space_get "void *vc" "vme_size_t size" "vme_am_t ams" \ +"u_long align" "vme_addr_t *addr" +.Sh DESCRIPTION +The +.Nm +bus provides support for VME devices. +The VME bus is a high-performance backplane bus for use in computer systems. +It is based on the VMEbus specification initially released by the VMEbus +International Trade Association (VITA) in August of 1982. +It has since undergone IEC and IEEE standardisation. +.Pp +The VME bus supports 8, 16, and 32-bit transfers over non-multiplexed +32-bit data and address paths. +The latest revisions allow 64-bit, multiplexed transfers. +It supports asynchronous, fully handshaken transfers at speeds +up to 80 MB/sec. +It has a master-slave architecture, encouraging multiprocessing and +supports up to seven interrupt levels. +.Sh DATA TYPES +Drivers attached to the +.Nm +bus will make use of the following data types: +.Bl -tag -width compact +.It Fa vme_chipset_tag_t +An opaque type identifying the bus controller. +.It Fa vme_addr_t +Addresses on the bus. +.It Fa vme_am_t +Address modifiers. +Valid values are VME_AM_A32, VME_AM_A16, VME_AM_A24, VME_AM_USERDEF +(user/vendor definable), VME_AM_MBO, VME_AM_SUPER, VME_AM_USER, +VME_AM_DATA, VME_AM_PRG, VME_AM_BLT32 and VME_AM_BLT64. +.It Fa vme_datasize_t +The datasize of the address space. +Valid values are VME_D8, VME_D16, and VME_D32. +.It Fa vme_mapresc_t +Generic placeholder for any resources needed for a mapping. +.It Fa vme_intr_handle_t +An opaque type describing an interrupt mapping. +.It Fa vme_swap_t +Hardware swap capabilities for controlling data endianness. +Valid values have not been specified yet. +.It Fa struct vme_range +A structure used to describe an address range on the VME bus. +It contains the following members: +.Bd -literal + vme_addr_t offset; + vme_size_t size; + vme_am_t am; +.Ed +.It Fa struct vme_attach_args +A structure used to inform the driver of the +device properties. +It contains the following members: +.Bd -literal + vme_chipset_tag_t va_vct; + bus_dma_tag_t va_bdt; + int ivector; + int ilevel; + int numcfranges; + struct vme_range r[VME_MAXCFRANGES]; +.Ed +.El +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn vme_probe "vc" "vmeaddr" "len" "am" "datasize" "callback" "arg" +Probes the VME space managed by controller +.Fa vc +at address +.Fa vmeaddr , +length +.Fa len , +with address modifiers +.Fa am +and datasize +.Fa datasize +for a device. +If a VME device is found, the function +.Fa callback() +(if it is not NULL) is called to perform device-specific +identification. +.Fa callback() +is called with the argument +.Fa arg , +and the bus-space tag and bus-space handle for accessing the VME space +mapping and should return a nonzero positive integer for a positive +device match. +.It Fn vme_space_map "vc" "vmeaddr" "len" "am" "datasize" "swap" "tag" "handle" "resc" +Maps the VME space managed by controller +.Fa vc +at address +.Fa vmeaddr , +length +.Fa len , +with address modifiers +.Fa am , +datasize +.Fa datasize +and endianness +.Fa swap +for a device. +If the mapping is successful +.Fa tag +contains the bus-space tag and +.Fa handle +contains the bus-space handle for accessing the VME space mapping. +.Fa resc +contains the resources for the mappings. +.Fn vme_space_map +returns 0 on success, and nonzero on error. +.It Fn vme_space_unmap "vc" "resc" +Unmaps the VME space mapping managed by controller +.Fa vc +and resources +.Fa resc . +.It Fn vme_intr_map "vc" "level" "vector" "handlep" +Sets +.Fa handlep +to a machine-dependent value which identifies a particular interrupt +source at level +.Fa level +and vector +.Fa vector +on the controller +.Fa vc . +.Fn vme_intr_map +returns zero on success, and nonzero on failure. +.It Fn vme_intr_establish "vc" "handle" "prio" "func" "arg" +Establishes the interrupt handler +.Fa handlep . +When the device interrupts, +.Fa func() +will be called with a single argument +.Fa arg +and will run at the interrupt priority level +.Fa prio . +The return value of +.Fn vme_intr_establish +may be saved and passed to +.Fn vme_intr_disestablish . +.It Fn vme_intr_disestablish "vc" "cookie" +Disables the interrupt handler when the driver is no longer interested +in interrupts from the device. +.Fa cookie +is the value returned by +.Fn vme_intr_establish . +.It Fn vme_intr_evcnt "vc" "handle" +Increment the interrupt event counter for the interrupt specified by +.Fa handle . +.It Fn vme_dmamap_create "vc" "size" "am" "datasize" "swap" "nsegs" "segsz" "bound" "flags" "map" +Allocates a DMA handle and initializes it according to the parameters +provided. +The VME-specific parameters describe the address-space modifiers +.Fa am , +datasize +.Fa datasize , +and endianness +.Fa swap . +The remaining parameters are described in +.Xr bus_dma 9 . +.It Fn vme_dmamap_destroy "vc" "map" +Frees all resources associated with a given DMA handle. +The parameters are described in +.Xr bus_dma 9 . +.It Fn vme_dmamem_alloc "vc" "size" "am" "datasize" "swap" "segs" "nsegs" "rsegs" "flags" +Allocates memory that is +.Do +DMA safe +.Dc for the VME bus managed by +controller +.Fa vc . +The VME-specific parameters describe the +address-space modifiers +.Fa am , +datasize +.Fa datasize , +and endianness +.Fa swap . +The remaining parameters are described in +.Xr bus_dma 9 . +.It Fn vme_dmamem_free "vc" "segs" "nsegs" +Frees memory previously allocated by +.Fn vme_dmamem_alloc +for the VME space managed by controller +.Fa vc . +.It Fn vme_space_alloc "tag" "addr" "size" "ams" +Allocate VME space for the bus-space +.Fa tag +at address +.Fa addr +of size +.Fa size +and address-space modifiers +.Fa ams . +.Fn vme_space_alloc +returns EINVAL on invalid inputs. +.It Fn vme_space_free "vc" "addr" "size" "ams" +Deallocate VME space for the bus-space +.Fa tag +at address +.Fa addr +of size +.Fa size +and address-space modifiers +.Fa ams . +.It Fn vme_space_get "vc" "size" "ams" "align" "addr" +Returns EINVAL on invalid inputs. +.El +.Sh AUTOCONFIGURATION +The VME bus is an indirect-connection bus. +During autoconfiguration each driver is required to probe the bus +for the presence of a device. +A VME driver will receive a pointer to a +.Fa struct vme_attach_args +hinting at "locations" (address ranges) on the VME bus where the +device may be located. +The driver should check the number of address +ranges, allocate the address space of these ranges using +.Fn vme_space_alloc , +and probe the address space for the device using +.Fn vme_probe . +.Pp +During driver attach the driver should also map the address ranges +using +.Fn vme_space_map . +The interrupt locators in +.Fa struct vme_attach_args +are used by +.Fn vme_intr_map +and +.Fn vme_intr_establish . +.Sh DMA SUPPORT +Extensive DMA facilities are provided. +.Sh CODE REFERENCES +The +.Nm +subsystem itself is implemented within the file +.Pa sys/dev/vme/vme.c . +.Sh SEE ALSO +.Xr vme 4 , +.Xr autoconf 9 , +.Xr bus_dma 9 , +.Xr bus_space 9 , +.Xr driver 9 +.Sh HISTORY +The machine-independent VME subsystem appeared in +.Nx 1.5 . +.Sh BUGS +This page is incomplete. diff --git a/static/netbsd/man9/vmem.9 b/static/netbsd/man9/vmem.9 new file mode 100644 index 00000000..b3f454dd --- /dev/null +++ b/static/netbsd/man9/vmem.9 @@ -0,0 +1,642 @@ +.\" $NetBSD: vmem.9,v 1.22 2023/12/02 21:02:12 thorpej Exp $ +.\" +.\" Copyright (c)2006 YAMAMOTO Takashi, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ------------------------------------------------------------ +.Dd December 2, 2023 +.Dt VMEM 9 +.Os +.\" ------------------------------------------------------------ +.Sh NAME +.Nm vmem +.Nd virtual memory allocator +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In sys/vmem.h +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft vmem_t * +.Fn vmem_create \ +"const char *name" "vmem_addr_t base" "vmem_size_t size" "vmem_size_t quantum" \ +"int (*allocfn)(void *, vmem_size_t, vm_flag_t, vmem_addr_t *)" \ +"void (*freefn)(void *, vmem_addr_t, vmem_size_t)" \ +"void *arg" "vmem_size_t qcache_max" "vm_flag_t flags" "int ipl" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft vmem_t * +.Fn vmem_xcreate \ +"const char *name" "vmem_addr_t base" "vmem_size_t size" "vmem_size_t quantum" \ +"int (*allocfn)(void *, vmem_size_t, vmem_size_t *, vm_flag_t, vmem_addr_t *)" \ +"void (*freefn)(void *, vmem_addr_t, vmem_size_t)" \ +"void *arg" "vmem_size_t qcache_max" "vm_flag_t flags" "int ipl" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn vmem_add \ +"vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" "vm_flag_t flags" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn vmem_xalloc \ +"vmem_t *vm" "vmem_size_t size" "vmem_size_t align" \ +"vmem_size_t phase" "vmem_size_t nocross" "vmem_addr_t minaddr" \ +"vmem_addr_t maxaddr" "vm_flag_t flags" "vmem_addr_t *addrp" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn vmem_xalloc_addr \ +"vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" "vm_flag_t flags" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn vmem_xfree "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn vmem_xfreeall "vmem_t *vm" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn vmem_alloc "vmem_t *vm" "vmem_size_t size" "vm_flag_t flags" "vmem_addr_t *addrp" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn vmem_free "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn vmem_destroy "vmem_t *vm" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +The +.Nm +is a general purpose resource allocator. +Despite its name, it can be used for arbitrary resources +other than virtual memory. +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_create +creates a new vmem arena. +.Bl -tag -offset indent -width qcache_max +.It Fa name +The string to describe the vmem. +.It Fa base +The start address of the initial span. +Pass +.Dv 0 +if no initial span is required. +.It Fa size +The size of the initial span. +Pass +.Dv 0 +if no initial span is required. +.It Fa quantum +The smallest unit of allocation. +.It Fa allocfn +The callback function used to import spans from the backend arena. +Set both +.Fa allocfn +and +.Fa freefn +to +.Dv NULL +to disable automatic imports. +.Nm +calls +.Fo "(*allocfn)" +.Fa arg +.Fa size +.Fa flags +.Fa "&addrp" +.Fc +to import a span of size at least +.Fa size . +.Fa allocfn +must accept the same +.Fa flags +as +.Fn vmem_alloc . +.Fa allocfn +must return +.Dv ENOMEM +to indicate failure, or 0 on success. +If +.Fa allocfn +succeeds, it must write the starting address of the imported span to +.Fa addrp . +.It Fa freefn +The callback function used to free spans to the backend arena. +.Fa freefn +may be +.Dv NULL +even if +.Fa allocfn +is not +.Dv NULL . +.Nm +calls +.Fn "(*freefn)" arg addr size +to return to +.Fa arg +a span of size +.Fa size , +starting at +.Fa addr , +that was previously allocated by +.Fa allocfn . +.It Fa arg +The backend arena. +.Fa arg +may be +.Dv NULL . +.Nm +passes +.Fa arg +as the first argument of +.Fa allocfn +and +.Fa freefn . +.It Fa qcache_max +The largest size of allocations which can be served by quantum cache. +It is merely a hint and can be ignored. +.It Fa flags +Either of: +.Bl -tag -width VM_NOSLEEP +.It Dv VM_SLEEP +If the allocation cannot be satisfied immediately, sleep until enough +resources are available. +.It Dv VM_NOSLEEP +Don't sleep. +Immediately return +.Dv NULL +if there are not enough resources available. +.El +.It Fa ipl +Interrupt level to be blocked for allocating from vmem. +.El +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_xcreate +creates a new vmem arena. +.Bl -tag -offset indent -width qcache_max +.It Fa name +The string to describe the vmem. +.It Fa base +The start address of the initial span. +Pass +.Dv 0 +if no initial span is required. +.It Fa size +The size of the initial span. +Pass +.Dv 0 +if no initial span is required. +.It Fa quantum +The smallest unit of allocation. +.It Fa allocfn +The callback function used to import spans from the backend arena. +Set both +.Fa allocfn +and +.Fa freefn +to +.Dv NULL +to disable automatic imports. +.Nm +calls +.Fo "(*allocfn)" +.Fa arg +.Fa size +.Fa "&actualsize" +.Fa flags +.Fa "&addrp" +.Fc +to import a span of size at least +.Fa size . +.Fa allocfn +must accept the same +.Fa flags +as +.Fn vmem_alloc . +.Fa allocfn +must return +.Dv ENOMEM +to indicate failure, or 0 on success. +If +.Fa allocfn +succeeds, it must write the actual size of the allocation to +.Fa actualsize +and the starting address of the imported span to +.Fa addrp . +The actual size will always be greater than or equal to the requested size. +.It Fa freefn +The callback function used to free spans to the backend arena. +.Fa freefn +may be +.Dv NULL +even if +.Fa allocfn +is not +.Dv NULL . +.Nm +calls +.Fn "(*freefn)" arg addr size +to return to +.Fa arg +a span of size +.Fa size , +starting at +.Fa addr , +that was previously allocated by +.Fa allocfn . +.It Fa arg +The backend arena. +.Fa arg +may be +.Dv NULL . +.Nm +passes +.Fa arg +as the first argument of +.Fa allocfn +and +.Fa freefn . +.It Fa qcache_max +The largest size of allocations which can be served by quantum cache. +It is merely a hint and can be ignored. +.It Fa flags +Either of: +.Bl -tag -width VM_NOSLEEP +.It Dv VM_SLEEP +If the allocation cannot be satisfied immediately, sleep until enough +resources are available. +.It Dv VM_NOSLEEP +Don't sleep. +Immediately return +.Dv NULL +if there are not enough resources available. +.El +.It Fa ipl +Interrupt level to be blocked for allocating from vmem. +.El +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_add +adds a span of size +.Fa size +starting at +.Fa addr +to the arena. +Returns +0 +on success, +.Dv ENOMEM +on failure. +.Bl -tag -offset indent -width flags +.It Fa flags +Either of: +.Bl -tag -width VM_NOSLEEP +.It Dv VM_SLEEP +If the allocation cannot be satisfied immediately, sleep until enough +resources are available. +.It Dv VM_NOSLEEP +Don't sleep. +Immediately return +.Dv ENOMEM +if there are not enough resources available. +.El +.El +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_xalloc +allocates a resource from the arena. +.Bl -tag -offset indent -width nocross +.It Fa vm +The arena which we allocate from. +.It Fa size +Specify the size of the allocation. +.It Fa align +If zero, don't care about the alignment of the allocation. +Otherwise, request a resource segment starting at +offset +.Fa phase +from an +.Fa align +aligned boundary. +.It Fa phase +See the above description of +.Fa align . +If +.Fa align +is zero, +.Fa phase +must be zero. +Otherwise, +.Fa phase +must be smaller than +.Fa align . +.It Fa nocross +Request a resource which doesn't cross +.Fa nocross +aligned boundary. +.It Fa minaddr +Specify the minimum address which can be allocated, or +.Dv VMEM_ADDR_MIN +if the caller does not care. +.It Fa maxaddr +Specify the maximum address which can be allocated, or +.Dv VMEM_ADDR_MAX +if the caller does not care. +.It Fa flags +A bitwise OR of an allocation strategy and a sleep flag. +.Pp +The allocation strategy must be one of: +.Bl -tag -width VM_INSTANTFIT +.It Dv VM_BESTFIT +Prefer space efficiency. +.It Dv VM_INSTANTFIT +Prefer performance. +.El +.Pp +The sleep flag must be one of: +.Bl -tag -width VM_NOSLEEP +.It Dv VM_SLEEP +If the allocation cannot be satisfied immediately, sleep until enough +resources are available. +.It Dv VM_NOSLEEP +Don't sleep. +Immediately return +.Dv ENOMEM +if there are not enough resources available. +.El +.It Fa addrp +On success, if +.Fa addrp +is not +.Dv NULL , +.Fn vmem_xalloc +overwrites it with the start address of the allocated span. +.El +.Pp +.\" ------------------------------------------------------------ +.Fn vmem_xalloc_addr +allocates a specific address from the arena. +The requested address must be aligned with the arena's quantum. +.Bl -tag -offset indent -width flags +.It Fa vm +The arena which we allocate from. +.It Fa addr +The address to allocate. +.It Fa size +Specify the size of the allocation. +.It Fa flags +A sleep flag. +Because a specific address is being allocated, any specified allocation +strategy is ignored. +.Pp +The sleep flag must be one of: +.Bl -tag -width VM_NOSLEEP +.It Dv VM_SLEEP +If the allocation cannot be satisfied immediately, sleep until the +requested range can be allocated. +.It Dv VM_NOSLEEP +Don't sleep. +Immediately return +.Dv ENOMEM +if the requested range is not available. +.El +.El +.Pp +.\" ------------------------------------------------------------ +.Fn vmem_xfree +frees resource allocated by +.Fn vmem_xalloc +or +.Fn vmem_xalloc_addr +to the arena. +.Bl -tag -offset indent -width addr +.It Fa vm +The arena which we free to. +.It Fa addr +The resource being freed. +It must have been allocated via +.Fn vmem_xalloc +or +.Fn vmem_xalloc_addr . +Notably, it must not have been allocated via +.Fn vmem_alloc , +otherwise, the behaviour is undefined. +.It Fa size +The size of the resource being freed. +It must be the same as the +.Fa size +argument used for +.Fn vmem_xalloc +or +.Fn vmem_xalloc_addr . +.El +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_xfreeall +frees all resources that have been allocated by +.Fn vmem_xalloc +to the arena. +.Bl -tag -offset indent -width addr +.It Fa vm +The arena which we free to. +Note that this function is may not be used on arenas +where resources have been allocated using +.Fn vmem_alloc +or arenas that have a quantum cache +.Po +i.e. were created with a non-zero +.Fa qcache_max +.Pc . +.El +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_alloc +allocates a resource from the arena. +.Bl -tag -offset indent -width flags +.It Fa vm +The arena which we allocate from. +.It Fa size +Specify the size of the allocation. +.It Fa flags +A bitwise OR of an allocation strategy and a sleep flag. +.Pp +The allocation strategy must be one of: +.Bl -tag -width VM_INSTANTFIT +.It Dv VM_BESTFIT +Prefer space efficiency. +.It Dv VM_INSTANTFIT +Prefer performance. +.El +.Pp +The sleep flag must be one of: +.Bl -tag -width VM_NOSLEEP +.It Dv VM_SLEEP +If the allocation cannot be satisfied immediately, sleep until enough +resources are available. +.It Dv VM_NOSLEEP +Don't sleep. +Immediately return +.Dv ENOMEM +if there are not enough resources available. +.El +.It Fa addrp +On success, if +.Fa addrp +is not +.Dv NULL , +.Fn vmem_alloc +overwrites it with the start address of the allocated span. +.El +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_free +frees resource allocated by +.Fn vmem_alloc +to the arena. +.Bl -tag -offset indent -width addr +.It Fa vm +The arena which we free to. +.It Fa addr +The resource being freed. +It must have been allocated via +.Fn vmem_alloc . +Notably, it must not have been allocated via +.Fn vmem_xalloc +or +.Fn vmem_xalloc addr , +otherwise, the behaviour is undefined. +.It Fa size +The size of the resource being freed. +It must be the same as the +.Fa size +argument used for +.Fn vmem_alloc . +.El +.Pp +.\" ------------------------------------------------------------ +.Fn vmem_destroy +destroys a vmem arena. +.Bl -tag -offset indent -width vm +.It Fa vm +The vmem arena being destroyed. +The caller must ensure that no one will use it anymore. +.El +.\" ------------------------------------------------------------ +.Sh RETURN VALUES +.Fn vmem_create +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 +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 +.Nm +subsystem is implemented within the file +.Pa sys/kern/subr_vmem.c . +.\" ------------------------------------------------------------ +.Sh SEE ALSO +.Xr intro 9 , +.Xr kmem 9 , +.Xr memoryallocators 9 , +.Xr uvm 9 +.Rs +.%A Jeff Bonwick +.%A Jonathan Adams +.%T "Magazines and Vmem: Extending the Slab Allocator to Many CPUs and Arbitrary Resources" +.%J "2001 USENIX Annual Technical Conference" +.%D 2001 +.Re +.\" ------------------------------------------------------------ +.Sh AUTHORS +This implementation of +.Nm +was written by +.An YAMAMOTO Takashi . +.Sh BUGS +.Nm +relies on +.Xr malloc 9 , +.Xr pool 9 , +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 . diff --git a/static/netbsd/man9/vnfileops.9 b/static/netbsd/man9/vnfileops.9 new file mode 100644 index 00000000..d944b9b5 --- /dev/null +++ b/static/netbsd/man9/vnfileops.9 @@ -0,0 +1,188 @@ +.\" $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. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 16, 2023 +.Dt VNFILEOPS 9 +.Os +.Sh NAME +.Nm vnfileops , +.Nm vn_closefile , +.Nm vn_fcntl , +.Nm vn_ioctl , +.Nm vn_read , +.Nm vn_poll , +.Nm vn_statfile , +.Nm vn_write +.Nd vnode file descriptor operations +.Sh SYNOPSIS +.In sys/param.h +.In sys/file.h +.In sys/vnode.h +.Ft int +.Fn vn_closefile "file_t *fp" +.Ft int +.Fn vn_fcntl "file_t *fp" "u_int com" "void *data" +.Ft int +.Fn vn_ioctl "file_t *fp" "u_long com" "void *data" +.Ft int +.Fn vn_read "file_t *fp" "off_t *offset" "struct uio *uio" "kauth_cred_t cred" "int flags" +.Ft int +.Fn vn_poll "file_t *fp" "int events" +.Ft int +.Fn vn_statfile "file_t *fp" "struct stat *sb" +.Ft int +.Fn vn_write "file_t *fp" "off_t *offset" "struct uio *uio" "kauth_cred_t cred" "int flags" +.Sh DESCRIPTION +The functions described in this page are the vnode-specific file +descriptor operations. +They should only be accessed through the opaque function pointers +in the file entries (see +.Xr file 9 ) . +They are described here only for completeness. +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn vn_closefile "fp" "l" +Common code for a file table vnode close operation. +The file is described by +.Fa fp +and +.Fa l +is the calling lwp. +.Fn vn_closefile +simply calls +.Xr vn_close 9 +with the appropriate arguments. +.It Fn vn_fcntl "fp" "com" "data" "l" +Common code for a file table vnode +.Xr fcntl 2 +operation. +The file is specified by +.Fa fp . +The argument +.Fa l +is the calling lwp. +.Fn vn_fcntl +simply locks the vnode and invokes the vnode operation +.Xr VOP_FCNTL 9 +with the command +.Fa com +and buffer +.Fa data . +The vnode is unlocked on return. +If the operation is successful zero is returned, otherwise an +appropriate error is returned. +.It Fn vn_ioctl "fp" "com" "data" "l" +Common code for a file table vnode ioctl operation. +The file is specified by +.Fa fp . +The argument +.Fa l +is the calling lwp. +.Fn vn_ioctl +simply locks the vnode and invokes the vnode operation +.Xr VOP_IOCTL 9 +with the command +.Fa com +and buffer +.Fa data . +The vnode is unlocked on return. +If the operation is successful zero is returned, otherwise an +appropriate error is returned. +.It Fn vn_read "fp" "offset" "uio" "cred" "flags" +Common code for a file table vnode read. +The argument +.Fa fp +is the file structure, The argument +.Fa offset +is the offset into the file. +The argument +.Fa uio +is the uio structure describing the memory to read into. +The caller's credentials are specified in +.Fa cred . +The +.Fa flags +argument can define FOF_UPDATE_OFFSET to update the read position in +the file. +If the operation is successful zero is returned, otherwise an +appropriate error is returned. +.It Fn vn_poll "fp" "events" "l" +Common code for a file table vnode poll operation. +.Fn vn_poll +simply calls +.Xr VOP_POLL 9 +with the events +.Fa events +and the calling lwp +.Fa l . +The function returns a bitmask of available events. +.It Fn vn_statfile "fp" "sb" "l" +Common code for a stat operation. +The file descriptor is specified by the argument +.Fa fp +and +.Fa sb +is the buffer to return the stat information. +The argument +.Fa l +is the calling lwp. +.Fn vn_statfile +basically calls the vnode operation +.Xr VOP_GETATTR 9 +and transfer the contents of a vattr structure into a struct stat. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +.It Fn vn_write "fp" "offset" "uio" "cred" "flags" +Common code for a file table vnode write. +The argument +.Fa fp +is the file structure, The argument +.Fa offset +is the offset into the file. +The argument +.Fa uio +is the uio structure describing the memory to read from. +The caller's credentials are specified in +.Fa cred . +The +.Fa flags +argument can define FOF_UPDATE_OFFSET to update the read position in +the file. +If the operation is successful zero is returned, otherwise an +appropriate error is returned. +.El +.Sh CODE REFERENCES +The high-level convenience functions are implemented within the file +.Pa sys/kern/vfs_vnops.c . +.Sh SEE ALSO +.Xr file 9 , +.Xr intro 9 , +.Xr vnode 9 , +.Xr vnodeops 9 , +.Xr vnsubr 9 diff --git a/static/netbsd/man9/vnode.9 b/static/netbsd/man9/vnode.9 new file mode 100644 index 00000000..88710951 --- /dev/null +++ b/static/netbsd/man9/vnode.9 @@ -0,0 +1,780 @@ +.\" $NetBSD: vnode.9,v 1.84 2022/03/19 13:53:32 hannken Exp $ +.\" +.\" Copyright (c) 2001, 2005, 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 19, 2022 +.Dt VNODE 9 +.Os +.Sh NAME +.Nm vnode , +.Nm vref , +.Nm vrele , +.Nm vrele_async , +.Nm vput , +.Nm vhold , +.Nm holdrele , +.Nm vcache_get , +.Nm vcache_new , +.Nm vcache_rekey_enter , +.Nm vcache_rekey_exit , +.Nm vrecycle , +.Nm vgone , +.Nm vgonel , +.Nm vdead_check , +.Nm vflush , +.Nm bdevvp , +.Nm cdevvp , +.Nm vfinddev , +.Nm vdevgone , +.Nm vwakeup , +.Nm vflushbuf , +.Nm vinvalbuf , +.Nm vtruncbuf , +.Nm vprint +.Nd kernel representation of a file or directory +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft void +.Fn vref "struct vnode *vp" +.Ft void +.Fn vrele "struct vnode *vp" +.Ft void +.Fn vrele_async "struct vnode *vp" +.Ft void +.Fn vput "struct vnode *vp" +.Ft void +.Fn vhold "struct vnode *vp" +.Ft void +.Fn holdrele "struct vnode *vp" +.Ft int +.Fn vcache_get "struct mount *mp" "const void *key" "size_t key_len" "struct vnode **vpp" +.Ft int +.Fn vcache_new "struct mount *mp" "struct vnode *dvp" "struct vattr *vap" "kauth_cred_t cred" "void *extra" "struct vnode **vpp" +.Ft int +.Fn vcache_rekey_enter "struct mount *mp" "struct vnode *vp" "const void *old_key" "size_t old_key_len" "const void *new_key" "size_t new_key_len" +.Ft void +.Fn vcache_rekey_exit "struct mount *mp" "struct vnode *vp" "const void *old_key" "size_t old_key_len" "const void *new_key" "size_t new_key_len" +.Ft int +.Fn vrecycle "struct vnode *vp" +.Ft void +.Fn vgone "struct vnode *vp" +.Ft void +.Fn vgonel "struct vnode *vp" "struct lwp *l" +.Ft int +.Fn vdead_check "struct vnode *vp" "int flags" +.Ft int +.Fn vflush "struct mount *mp" "struct vnode *skipvp" "int flags" +.Ft int +.Fn bdevvp "dev_t dev" "struct vnode **vpp" +.Ft int +.Fn cdevvp "dev_t dev" "struct vnode **vpp" +.Ft int +.Fn vfinddev "dev_t dev" "enum vtype" "struct vnode **vpp" +.Ft void +.Fn vdevgone "int maj" "int minl" "int minh" "enum vtype type" +.Ft void +.Fn vwakeup "struct buf *bp" +.Ft int +.Fn vflushbuf "struct vnode *vp" "int sync" +.Ft int +.Fn vinvalbuf "struct vnode *vp" "int flags" "kauth_cred_t cred" "struct lwp *l" "int slpflag" "int slptimeo" +.Ft int +.Fn vtruncbuf "struct vnode *vp" "daddr_t lbn" "int slpflag" "int slptimeo" +.Ft void +.Fn vprint "const char *label" "struct vnode *vp" +.Sh DESCRIPTION +A +.Em vnode +represents an on-disk file in use by the system. +Each +.Xr vfs 9 +file system provides a set of +.Xr vnodeops 9 +operations on vnodes, invoked by file-system-independent system calls +and supported by file-system-independent library routines. +.Pp +Each mounted file system provides a vnode for the root of the file +system, via +.Xr VFS_ROOT 9 . +Other vnodes are obtained by +.Xr VOP_LOOKUP 9 . +Users of vnodes usually invoke these indirectly via +.Xr namei 9 +to obtain vnodes from paths. +.Pp +Each file system usually maintains a cache mapping recently used inode +numbers, or the equivalent, to vnodes, and a cache mapping recently +used file names to vnodes. +If memory is scarce, the system may decide to +.Em reclaim +an unused cached vnode, calling +.Xr VOP_RECLAIM 9 +to remove it from the caches and to free file-system-specific memory +associated with it. +A file system may also choose to immediately reclaim a cached vnode +once it is unused, in +.Xr VOP_INACTIVE 9 , +if the vnode has been deleted on disk. +.Pp +When a file system retrieves a vnode from a cache, the vnode may not +have any users, and another thread in the system may be simultaneously +deciding to reclaim it. +Thus, to retrieve a vnode from a cache, one must use +.Fn vcache_get , +not +.Fn vref , +to acquire the first reference. +.Pp +The vnode has the following structure: +.Bd -literal +struct vnode { + struct uvm_object v_uobj; /* the VM object */ + kcondvar_t v_cv; /* synchronization */ + voff_t v_size; /* size of file */ + voff_t v_writesize; /* new size after write */ + int v_iflag; /* VI_* flags */ + int v_vflag; /* VV_* flags */ + int v_uflag; /* VU_* flags */ + int v_numoutput; /* # of pending writes */ + int v_writecount; /* ref count of writers */ + int v_holdcnt; /* page & buffer refs */ + struct mount *v_mount; /* ptr to vfs we are in */ + int (**v_op)(void *); /* vnode operations vector */ + struct buflists v_cleanblkhd; /* clean blocklist head */ + struct buflists v_dirtyblkhd; /* dirty blocklist head */ + union { + struct mount *vu_mountedhere;/* ptr to vfs (VDIR) */ + struct socket *vu_socket; /* unix ipc (VSOCK) */ + struct specnode *vu_specnode; /* device (VCHR, VBLK) */ + struct fifoinfo *vu_fifoinfo; /* fifo (VFIFO) */ + struct uvm_ractx *vu_ractx; /* read-ahead ctx (VREG) */ + } v_un; + enum vtype v_type; /* vnode type */ + enum vtagtype v_tag; /* type of underlying data */ + void *v_data; /* private data for fs */ + struct klist v_klist; /* notes attached to vnode */ +}; +.Ed +.Pp +Most members of the vnode structure should be treated as opaque and +only manipulated using the proper functions. +There are some rather common exceptions detailed throughout this page. +.Pp +Files and file systems are inextricably linked with the virtual memory +system and +.Em v_uobj +contains the data maintained by the virtual memory system. +For compatibility with code written before the integration of +.Xr uvm 9 +into +.Nx , +C-preprocessor directives are used to alias the members of +.Em v_uobj . +.Pp +Vnode flags are recorded by +.Em v_iflag , +.Em v_vflag +and +.Em v_uflag . +Valid flags are: +.Pp +.Bl -tag -offset indent -width ".Dv VI_WRMAPDIRTY" -compact +.It Dv VV_ROOT +This vnode is the root of its file system. +.It Dv VV_SYSTEM +This vnode is being used by the kernel; only used to skip quota files in +.Fn vflush . +.It Dv VV_ISTTY +This vnode represents a tty; used when reading dead vnodes. +.It Dv VV_MAPPED +This vnode might have user mappings. +.It Dv VV_MPSAFE +This file system is MP safe. +.It Dv VI_TEXT +This vnode is a pure text prototype. +.It Dv VI_EXECMAP +This vnode has executable mappings. +.It Dv VI_WRMAP +This vnode might have PROT_WRITE user mappings. +.It Dv VI_WRMAPDIRTY +This vnode might have dirty pages due to +.Dv VWRITEMAP . +.It Dv VI_XLOCK +This vnode is currently locked to change underlying type. +.It Dv VI_ONWORKLST +This vnode is on syncer work-list. +.It Dv VI_MARKER +A dummy marker vnode. +.It Dv VI_CLEAN +This vnode has been reclaimed and is no longer attached to a file system. +.It Dv VU_DIROP +This vnode is involved in a directory operation. +This flag is used exclusively by LFS. +.El +.Pp +The +.Dv VI_XLOCK +flag is used to prevent multiple processes from entering +the vnode reclamation code. +It is also used as a flag to indicate that reclamation is in progress. +Before +.Em v_iflag +can be modified, the +.Em v_interlock +mutex must be acquired. +See +.Xr lock 9 +for details on the kernel locking API. +.Pp +Each vnode has three reference counts: +.Em v_usecount , +.Em v_writecount +and +.Em v_holdcnt . +The first is the number of active references within the +kernel to the vnode. +This count is maintained by +.Fn vref , +.Fn vrele , +.Fn vrele_async , +and +.Fn vput . +The second is the number of active references within the kernel to the +vnode performing write access to the file. +It is maintained by the +.Xr open 2 +and +.Xr close 2 +system calls. +The third is the number of references within the kernel +requiring the vnode to remain active and not be recycled. +This count is maintained by +.Fn vhold +and +.Fn holdrele . +When both the +.Em v_usecount +and +.Em v_holdcnt +reach zero, the vnode is cached. +The transition from the cache is handled by a kernel thread and +.Fn vrecycle . +Access to +.Em v_usecount , +.Em v_writecount +and +.Em v_holdcnt +is also protected by the +.Em v_interlock +mutex. +.Pp +The number of pending synchronous and asynchronous writes on the +vnode are recorded in +.Em v_numoutput . +It is used by +.Xr fsync 2 +to wait for all writes to complete before returning to the user. +Its value must only be modified at splbio (see +.Xr spl 9 ) . +It does not track the number of dirty buffers attached to the +vnode. +.Pp +The link to the file system which owns the vnode is recorded by +.Em v_mount . +See +.Xr vfsops 9 +for further information of file system mount status. +.Pp +The +.Em v_op +pointer points to its vnode operations vector. +This vector describes what operations can be done to the file associated +with the vnode. +The system maintains one vnode operations vector for each file system +type configured into the kernel. +The vnode operations vector contains a pointer to a function for +each operation supported by the file system. +See +.Xr vnodeops 9 +for a description of vnode operations. +.Pp +When a user wants a new vnode for another file or wants a valid vnode +which is cached, +.Fn vcache_get +or +.Fn vcache_new +is invoked to allocate a vnode and initialize it for the new file. +.Pp +The type of object the vnode represents is recorded by +.Em v_type . +It is used by generic code to perform checks to ensure operations are +performed on valid file system objects. +Valid types are: +.Pp +.Bl -tag -offset indent -width VFIFO -compact +.It Dv VNON +The vnode has no type. +.It Dv VREG +The vnode represents a regular file. +.It Dv VDIR +The vnode represents a directory. +.It Dv VBLK +The vnode represents a block special device. +.It Dv VCHR +The vnode represents a character special device. +.It Dv VLNK +The vnode represents a symbolic link. +.It Dv VSOCK +The vnode represents a socket. +.It Dv VFIFO +The vnode represents a pipe. +.It Dv VBAD +The vnode represents a bad file (not currently used). +.El +.Pp +Vnode tag types are used by external programs only (e.g., +.Xr pstat 8 ) , +and should never be inspected by the kernel. +Its use is deprecated +since new +.Em v_tag +values cannot be defined for loadable file systems. +The +.Em v_tag +member is read-only. +Valid tag types are: +.Pp +.Bl -tag -offset indent -width "VT_FILECORE " -compact +.It Dv VT_NON +non file system +.It Dv VT_UFS +universal file system +.It Dv VT_NFS +network file system +.It Dv VT_MFS +memory file system +.It Dv VT_MSDOSFS +FAT file system +.It Dv VT_LFS +log-structured file system +.It Dv VT_LOFS +loopback file system +.It Dv VT_FDESC +file descriptor file system +.It Dv VT_NULL +null file system layer +.It Dv VT_UMAP +uid/gid remapping file system layer +.It Dv VT_KERNFS +kernel interface file system +.It Dv VT_PROCFS +process interface file system +.It Dv VT_AFS +AFS file system +.It Dv VT_ISOFS +ISO 9660 file system(s) +.It Dv VT_UNION +union file system +.It Dv VT_ADOSFS +Amiga file system +.It Dv VT_EXT2FS +Linux's ext2 file system +.It Dv VT_CODA +Coda file system +.It Dv VT_FILECORE +filecore file system +.It Dv VT_NTFS +Microsoft NT's file system +.It Dv VT_VFS +virtual file system +.It Dv VT_OVERLAY +overlay file system +.It Dv VT_SMBFS +SMB file system +.It Dv VT_PTYFS +pseudo-terminal device file system +.It Dv VT_TMPFS +efficient memory file system +.It Dv VT_UDF +universal disk format file system +.It Dv VT_SYSVBFS +systemV boot file system +.El +.Pp +The vnode lock is acquired by calling +.Xr vn_lock 9 +and released by calling +.Xr VOP_UNLOCK 9 . +The reason for this asymmetry is that +.Xr vn_lock 9 +is a wrapper for +.Xr VOP_LOCK 9 +with extra checks, while the unlocking step usually does not need +additional checks and thus has no wrapper. +.Pp +The vnode locking operation is complicated because it is used for many +purposes. +Sometimes it is used to bundle a series of vnode operations (see +.Xr vnodeops 9 ) +into an atomic group. +Many file systems rely on it to prevent race conditions in updating +file system type specific data structures rather than using their +own private locks. +The vnode lock can operate as a multiple-reader (shared-access lock) +or single-writer lock (exclusive access lock), however many current file +system implementations were written assuming only single-writer +locking. +Multiple-reader locking functions equivalently only in the presence +of big-lock SMP locking or a uni-processor machine. +The lock may be held while sleeping. +While the vnode lock is acquired, the holder is guaranteed that the +vnode will not be reclaimed or invalidated. +Most file system functions require that you hold the vnode lock on entry. +See +.Xr lock 9 +for details on the kernel locking API. +.Pp +Each file system underlying a vnode allocates its own private area and +hangs it from +.Em v_data . +.Pp +Most functions discussed in this page that operate on vnodes cannot be +called from interrupt context. +The members +.Em v_numoutput , +.Em v_holdcnt , +.Em v_dirtyblkhd , +and +.Em v_cleanblkhd +are modified in interrupt context and must be protected by +.Xr splbio 9 +unless it is certain that there is no chance an interrupt handler will +modify them. +The vnode lock must not be acquired within interrupt context. +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn vref "vp" +Increment +.Em v_usecount +of the vnode +.Em vp . +Any kernel thread system which uses a vnode (e.g., during the operation +of some algorithm or to store in a data structure) should call +.Fn vref . +.It Fn vrele "vp" +Decrement +.Em v_usecount +of unlocked vnode +.Em vp . +Any code in the system which is using a vnode should call +.Fn vrele +when it is finished with the vnode. +If +.Em v_usecount +of the vnode reaches zero and +.Em v_holdcnt +is greater than zero, the vnode is placed on the holdlist. +If both +.Em v_usecount +and +.Em v_holdcnt +are zero, the vnode is cached. +.It Fn vrele_async "vp" +Will asynchronously release the vnode in different context than the caller, +sometime after the call. +.It Fn vput "vp" +Legacy convenience routine for unlocking and releasing +.Fa vp . +Equivalent to: +.Bd -literal -offset abcd +.No "VOP_UNLOCK(" Ns Fa vp Ns Li ");" +.No "vrele(" Ns Fa vp Ns Li ");" +.Ed +.Pp +New code should prefer using +.Xr VOP_UNLOCK 9 +and +.Fn vrele +directly. +.It Fn vhold "vp" +Mark the vnode +.Fa vp +as active by incrementing +.Em vp->v_holdcnt . +Once held, the vnode will not be recycled until it is +released with +.Fn holdrele . +.It Fn holdrele "vp" +Mark the vnode +.Fa vp +as inactive by decrementing +.Em vp->v_holdcnt . +.It Fn vcache_get "mp" "key" "key_len" "vpp" +Allocate a new vnode. +The new vnode is returned referenced in the address specified by +.Fa vpp . +.Pp +The argument +.Fa mp +is the mount point for the file system to lookup the file in. +.Pp +The arguments +.Fa key +and +.Fa key_len +uniquely identify the file in the file system. +.Pp +If a vnode is successfully retrieved zero is returned, otherwise an +appropriate error code is returned. +.It Fn vcache_new "mp" "dvp" "vap" "cred" "vpp" +Allocate a new vnode with a new file. +The new vnode is returned referenced in the address specified by +.Fa vpp . +.Pp +The argument +.Fa mp +is the mount point for the file system to create the file in. +.Pp +The argument +.Fa dvp +points to the directory to create the file in. +.Pp +The argument +.Fa vap +points to the attributes for the file to create. +.Pp +The argument +.Fa cred +holds the credentials for the file to create. +.Pp +The argument +.Fa extra +allows the caller to pass more information about the file to create. +.Pp +If a vnode is successfully created zero is returned, otherwise an +appropriate error code is returned. +.It Fn vcache_rekey_enter "mp" "vp" "old_key" "old_key_len" "new_key" "new_key_len" +Prepare to change the key of a cached vnode. +.Pp +The argument +.Fa mp +is the mount point for the file system the vnode +.Fa vp +resides in. +.Pp +The arguments +.Fa old_key +and +.Fa old_key_len +identify the cached vnode. +.Pp +The arguments +.Fa new_key +and +.Fa new_key_len +will identify the vnode after rename. +.Pp +If the new key already exists +.Er EEXIST +is returned, otherwise zero is returned. +.It Fn vcache_rekey_exit "mp" "vp" "old_key" "old_key_len" "new_key" "new_key_len" +Finish rename after calling +.Fn vcache_rekey_enter . +.It Fn vrecycle "vp" +Recycle the referenced vnode +.Fa vp +if this is the last reference. +.Fn vrecycle +is a null operation if the reference count is greater than one. +.It Fn vgone "vp" +Eliminate all activity associated with the unlocked vnode +.Fa vp +in preparation for recycling. +This operation is restricted to suspended file systems. +See +.Xr vfs_suspend 9 . +.It Fn vgonel "vp" "p" +Eliminate all activity associated with the locked vnode +.Fa vp +in preparation for recycling. +.It Fn vdead_check "vp" "flags" +Check the vnode +.Fa vp +for being or becoming dead. +Returns +.Er ENOENT +for a dead vnode and zero otherwise. +If +.Fa flags +is +.Dv VDEAD_NOWAIT +it will return +.Er EBUSY +if the vnode is becoming dead and the function will not sleep. +.Pp +Whenever this function returns a non-zero value all future calls +for this +.Fa vp +will also return a non-zero value. +.It Fn vflush "mp" "skipvp" "flags" +Remove any vnodes in the vnode table belonging to mount point +.Fa mp . +If +.Fa skipvp +is not +.Dv NULL +it is exempt from being flushed. +The argument +.Fa flags +is a set of flags modifying the operation of +.Fn vflush . +If +.Dv FORCECLOSE +is not specified, there should not be any active vnodes and +the error +.Er EBUSY +is returned if any are found (this is a user error, not a system error). +If +.Dv FORCECLOSE +is specified, active vnodes that are found are detached. +If +.Dv WRITECLOSE +is set, only flush out regular file vnodes open for writing. +SKIPSYSTEM causes any vnodes marked +.Dv V_SYSTEM +to be skipped. +.It Fn bdevvp "dev" "vpp" +Create a vnode for a block device. +.Fn bdevvp +is used for root file systems, swap areas and for memory file system +special devices. +.It Fn cdevvp "dev" "vpp" +Create a vnode for a character device. +.Fn cdevvp +is used for the console and kernfs special devices. +.It Fn vfinddev "dev" "vtype" "vpp" +Lookup a vnode by device number. +The vnode is referenced and returned in the address specified by +.Fa vpp . +.It Fn vdevgone "int maj" "int min" "int minh" "enum vtype type" +Reclaim all vnodes that correspond to the specified minor number range +.Fa minl +to +.Fa minh +(endpoints inclusive) of the specified major +.Fa maj . +.It Fn vwakeup "bp" +Update outstanding I/O count +.Em vp->v_numoutput +for the vnode +.Em bp->b_vp +and do a wakeup if requested and +.Em vp->vflag +has +.Dv VBWAIT +set. +.It Fn vflushbuf "vp" "sync" +Flush all dirty buffers to disk for the file with the locked vnode +.Fa vp . +The argument +.Fa sync +specifies whether the I/O should be synchronous and +.Fn vflushbuf +will sleep until +.Em vp->v_numoutput +is zero and +.Em vp->v_dirtyblkhd +is empty. +.It Fn vinvalbuf "vp" "flags" "cred" "l" "slpflag" "slptimeo" +Flush out and invalidate all buffers associated with locked vnode +.Fa vp . +The argument +.Fa l +and +.Fa cred +specified the calling process and its credentials. +The +.Xr ltsleep 9 +flag and timeout are specified by the arguments +.Fa slpflag +and +.Fa slptimeo +respectively. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +.It Fn vtruncbuf "vp" "lbn" "slpflag" "slptimeo" +Destroy any in-core buffers past the file truncation length for the +locked vnode +.Fa vp . +The truncation length is specified by +.Fa lbn . +.Fn vtruncbuf +will sleep while the I/O is performed, The +.Xr ltsleep 9 +flag and timeout are specified by the arguments +.Fa slpflag +and +.Fa slptimeo +respectively. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +.It Fn vprint "label" "vp" +This function is used by the kernel to dump vnode information during a +panic. +It is only used if the kernel option DIAGNOSTIC is compiled into the kernel. +The argument +.Fa label +is a string to prefix the information dump of vnode +.Fa vp . +.El +.Sh CODE REFERENCES +The vnode framework is implemented within the file +.Pa sys/kern/vfs_subr.c . +.Sh SEE ALSO +.Xr intro 9 , +.Xr lock 9 , +.Xr namecache 9 , +.Xr namei 9 , +.Xr uvm 9 , +.Xr vattr 9 , +.Xr vfs 9 , +.Xr vfsops 9 , +.Xr vnodeops 9 , +.Xr vnsubr 9 +.Sh BUGS +The locking protocol is inconsistent. +Many vnode operations are passed locked vnodes on entry but release +the lock before they exit. +The locking protocol is used in some places to attempt to make a +series of operations atomic (e.g., access check then operation). +This does not work for non-local file systems that do not support locking +(e.g., NFS). +The +.Nm +interface would benefit from a simpler locking protocol. diff --git a/static/netbsd/man9/vnodeops.9 b/static/netbsd/man9/vnodeops.9 new file mode 100644 index 00000000..d54805ed --- /dev/null +++ b/static/netbsd/man9/vnodeops.9 @@ -0,0 +1,1537 @@ +.\" $NetBSD: vnodeops.9,v 1.101 2023/06/15 09:13:36 hannken Exp $ +.\" +.\" Copyright (c) 2001, 2005, 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 15, 2023 +.Dt VNODEOPS 9 +.Os +.Sh NAME +.Nm vnodeops , +.Nm VOP_LOOKUP , +.Nm VOP_CREATE , +.Nm VOP_MKNOD , +.Nm VOP_OPEN , +.Nm VOP_CLOSE , +.Nm VOP_ACCESS , +.Nm VOP_GETATTR , +.Nm VOP_SETATTR , +.Nm VOP_READ , +.Nm VOP_WRITE , +.Nm VOP_FALLOCATE , +.Nm VOP_FDISCARD , +.Nm VOP_IOCTL , +.Nm VOP_FCNTL , +.Nm VOP_POLL , +.Nm VOP_KQFILTER , +.Nm VOP_REVOKE , +.Nm VOP_MMAP , +.Nm VOP_FSYNC , +.Nm VOP_SEEK , +.Nm VOP_REMOVE , +.Nm VOP_LINK , +.Nm VOP_RENAME , +.Nm VOP_MKDIR , +.Nm VOP_RMDIR , +.Nm VOP_SYMLINK , +.Nm VOP_READDIR , +.Nm VOP_READLINK , +.Nm VOP_ABORTOP , +.Nm VOP_INACTIVE , +.Nm VOP_RECLAIM , +.Nm VOP_LOCK , +.Nm VOP_UNLOCK , +.Nm VOP_ISLOCKED , +.Nm VOP_BMAP , +.Nm VOP_PRINT , +.Nm VOP_PATHCONF , +.Nm VOP_ADVLOCK , +.Nm VOP_WHITEOUT , +.Nm VOP_GETPAGES , +.Nm VOP_PUTPAGES , +.Nm VOP_STRATEGY , +.Nm VOP_BWRITE , +.Nm VOP_GETEXTATTR , +.Nm VOP_SETEXTATTR , +.Nm VOP_LISTEXTATTR , +.Nm VOP_DELETEEXTATTR +.Nd vnode operations +.Sh SYNOPSIS +.In sys/param.h +.In sys/buf.h +.In sys/dirent.h +.In sys/vnode.h +.In sys/mount.h +.In sys/namei.h +.In sys/unistd.h +.In sys/fcntl.h +.In sys/lockf.h +.In sys/extattr.h +.Ft int +.Fn VOP_LOOKUP "struct vnode *dvp" "struct vnode **vpp" \ +"struct componentname *cnp" +.Ft int +.Fn VOP_CREATE "struct vnode *dvp" "struct vnode **vpp" \ +"struct componentname *cnp" "struct vattr *vap" +.Ft int +.Fn VOP_MKNOD "struct vnode *dvp" "struct vnode **vpp" \ +"struct componentname *cnp" "struct vattr *vap" +.Ft int +.Fn VOP_OPEN "struct vnode *vp" "int mode" "kauth_cred_t cred" +.Ft int +.Fn VOP_CLOSE "struct vnode *vp" "int fflag" "kauth_cred_t cred" +.Ft int +.Fn VOP_ACCESS "struct vnode *vp" "int mode" "kauth_cred_t cred" +.Ft int +.Fn VOP_GETATTR "struct vnode *vp" "struct vattr *vap" "kauth_cred_t cred" +.Ft int +.Fn VOP_SETATTR "struct vnode *vp" "struct vattr *vap" "kauth_cred_t cred" +.Ft int +.Fn VOP_READ "struct vnode *vp" "struct uio *uio" "int ioflag" \ +"kauth_cred_t cred" +.Ft int +.Fn VOP_WRITE "struct vnode *vp" "struct uio *uio" "int ioflag" \ +"kauth_cred_t cred" +.Ft int +.Fn VOP_FALLOCATE "struct vnode *vp" "off_t pos" "off_t len" +.Ft int +.Fn VOP_FDISCARD "struct vnode *vp" "off_t pos" "off_t len" +.Ft int +.Fn VOP_IOCTL "struct vnode *vp" "u_long command" "void *data" \ +"int fflag" "kauth_cred_t cred" +.Ft int +.Fn VOP_FCNTL "struct vnode *vp" "u_int command" "void *data" \ +"int fflag" "kauth_cred_t cred" +.Ft int +.Fn VOP_POLL "struct vnode *vp" "int events" +.Ft int +.Fn VOP_KQFILTER "struct vnode *vp" "struct knote *kn" +.Ft int +.Fn VOP_REVOKE "struct vnode *vp" "int flags" +.Ft int +.Fn VOP_MMAP "struct vnode *vp" "vm_prot_t prot" "kauth_cred_t cred" +.Ft int +.Fn VOP_FSYNC "struct vnode *vp" "kauth_cred_t cred" "int flags" \ +"off_t offlo" "off_t offhi" +.Ft int +.Fn VOP_SEEK "struct vnode *vp" "off_t oldoff" "off_t newoff" \ +"kauth_cred_t cred" +.Ft int +.Fn VOP_REMOVE "struct vnode *dvp" "struct vnode *vp" \ +"struct componentname *cnp" +.Ft int +.Fn VOP_LINK "struct vnode *dvp" "struct vnode *vp" \ +"struct componentname *cnp" +.Ft int +.Fn VOP_RENAME "struct vnode *fdvp" "struct vnode *fvp" \ +"struct componentname *fcnp" "struct vnode *tdvp" \ +"struct vnode *tvp" "struct componentname *tcnp" +.Ft int +.Fn VOP_MKDIR "struct vnode *dvp" "struct vnode **vpp" \ +"struct componentname *cnp" "struct vattr *vap" +.Ft int +.Fn VOP_RMDIR "struct vnode *dvp" "struct vnode *vp" \ +"struct componentname *cnp" +.Ft int +.Fn VOP_SYMLINK "struct vnode *dvp" "struct vnode **vpp" \ +"struct componentname *cnp" "struct vattr *vap" "char *target" +.Ft int +.Fn VOP_READDIR "struct vnode *vp" "struct uio *uio" \ +"kauth_cred_t cred" "int *eofflag" "off_t **cookies" "int *ncookies" +.Ft int +.Fn VOP_READLINK "struct vnode *vp" "struct uio *uio" "kauth_cred_t cred" +.Ft int +.Fn VOP_ABORTOP "struct vnode *dvp" "struct componentname *cnp" +.Ft int +.Fn VOP_INACTIVE "struct vnode *vp" +.Ft int +.Fn VOP_RECLAIM "struct vnode *vp" +.Ft int +.Fn VOP_LOCK "struct vnode *vp" "int flags" +.Ft int +.Fn VOP_UNLOCK "struct vnode *vp" +.Ft int +.Fn VOP_ISLOCKED "struct vnode *vp" +.Ft int +.Fn VOP_BMAP "struct vnode *vp" "daddr_t bn" "struct vnode **vpp" \ +"daddr_t *bnp" "int *runp" +.Ft int +.Fn VOP_PRINT "struct vnode *vp" +.Ft int +.Fn VOP_PATHCONF "struct vnode *vp" "int name" "register_t *retval" +.Ft int +.Fn VOP_ADVLOCK "struct vnode *vp" "void *id" "int op" \ +"struct flock *fl" "int flags" +.Ft int +.Fn VOP_WHITEOUT "struct vnode *dvp" "struct componentname *cnp" \ +"int flags" +.Ft int +.Fn VOP_GETPAGES "struct vnode *vp" "voff_t offset" "struct vm_page **m" \ +"int *count" "int centeridx" "vm_prot_t access_type" "int advice" "int flags" +.Ft int +.Fn VOP_PUTPAGES "struct vnode *vp" "voff_t offlo" "voff_t offhi" \ +"int flags" +.Ft int +.Fn VOP_STRATEGY "struct vnode *vp" "struct buf *bp" +.Ft int +.Fn VOP_BWRITE "struct vnode *vp" "struct buf *bp" +.Ft int +.Fn VOP_GETEXTATTR "struct vnode *vp" "int attrnamespace" "const char *name" \ +"struct uio *uio" "size_t *size" "kauth_cred_t cred" +.Ft int +.Fn VOP_SETEXTATTR "struct vnode *vp" "int attrnamespace" "const char *name" \ +"struct uio *uio" "kauth_cred_t cred" +.Ft int +.Fn VOP_LISTEXTATTR "struct vnode *vp" "int attrnamespace" "struct uio *uio" \ +"size_t *size" "kauth_cred_t cred" +.Ft int +.Fn VOP_DELETEEXTATTR "struct vnode *vp" "int attrnamespace" \ +"const char *name" "kauth_cred_t cred" +.Pp +Not all header files are required for each function. +.Sh DESCRIPTION +The vnode operations vector describes what operations can be done to +the file associated with the vnode. +The system maintains one vnode operations vector for each file system +type configured into the kernel. +The vnode operations vector contains a pointer to a function for each +operation supported by the file system. +Many of the functions described in the vnode operations vector are +closely related to their corresponding system calls. +In most cases, they are called as a result of the system call +associated with the operation being invoked. +.Pp +Functions in the vnode operations vector are invoked using specialized +macros. +The following table gives a summary of the operations. +.Pp +.Bl -column "VOP_DELETEEXTATTR" "Wake up process sleeping on lock" -compact +.It Sy Macro Ta Sy Description +.It VOP_LOOKUP Lookup file name in name cache +.It VOP_CREATE Create a new file +.It VOP_MKNOD Make a new device +.It VOP_OPEN Open a file +.It VOP_CLOSE Close a file +.It VOP_ACCESS Determine file accessibility +.It VOP_GETATTR Get file attributes +.It VOP_SETATTR Set file attributes +.It VOP_READ Read from a file +.It VOP_WRITE Write to a file +.It VOP_FALLOCATE Allocate backing for a file +.It VOP_FDISCARD Discard backing for a file +.It VOP_IOCTL Perform device-specific I/O +.It VOP_FCNTL Perform file control +.It VOP_POLL Test if poll event has occurred +.It VOP_KQFILTER Register a knote +.It VOP_REVOKE Eliminate vnode activity +.It VOP_MMAP Map file into user address space +.It VOP_FSYNC Flush pending data to disk +.It VOP_SEEK Test if file is seekable +.It VOP_REMOVE Remove a file +.It VOP_LINK Link a file +.It VOP_RENAME Rename a file +.It VOP_MKDIR Make a new directory +.It VOP_RMDIR Remove a directory +.It VOP_SYMLINK Create a symbolic link +.It VOP_READDIR Read directory entry +.It VOP_READLINK Read contents of a symlink +.It VOP_ABORTOP Abort pending operation +.It VOP_INACTIVE Release the inactive vnode +.It VOP_RECLAIM Reclaim vnode for another file +.It VOP_LOCK Sleep until vnode lock is free +.It VOP_UNLOCK Wake up process sleeping on lock +.It VOP_ISLOCKED Test if vnode is locked +.It VOP_BMAP Logical block number conversion +.It VOP_PRINT Print debugging information +.It VOP_PATHCONF Return POSIX pathconf data +.It VOP_ADVLOCK Advisory record locking +.It VOP_WHITEOUT Whiteout vnode +.It VOP_GETPAGES Read VM pages from file +.It VOP_PUTPAGES Write VM pages to file +.It VOP_STRATEGY Read/write a file system buffer +.It VOP_BWRITE Write a file system buffer +.It VOP_GETEXTATTR Get extended attribute +.It VOP_SETEXTATTR Set extended attribute +.It VOP_LISTEXTATTR List extended attributes +.It VOP_DELETEEXTATTR Remove extended attribute +.El +.Pp +The implementation details of the vnode operations vector are not +quite what is described here. +.Pp +If the file system type does not support a specific operation, it must +nevertheless assign an appropriate stub in the vnode operations +vector to do the minimum required of it. +In most cases, such functions either do nothing or return an error +value to the effect that it is not supported. +.Pp +Many of the functions in the vnode operations vector take a +componentname structure. +It is used to encapsulate many parameters into a single function +argument. +It has the following structure: +.Bd -literal +struct componentname { + /* + * Arguments to lookup. + */ + uint32_t cn_nameiop; /* namei operation */ + uint32_t cn_flags; /* flags to namei */ + kauth_cred_t cn_cred; /* credentials */ + /* + * Shared between lookup and commit routines. + */ + const char *cn_nameptr; /* pointer to looked up name */ + size_t cn_namelen; /* length of looked up component */ + size_t cn_consume; /* chars to consume in lookup() */ +}; +.Ed +.Pp +The top half of the structure is used exclusively for the pathname +lookups using +.Fn VOP_LOOKUP +and is initialized by the caller. +The semantics of the lookup are affected by the lookup operation +specified in +.Em cn_nameiop +and the flags specified in +.Em cn_flags . +Valid operations are: +.Pp +.Bl -tag -offset indent -width LOOKUP -compact +.It LOOKUP +perform name lookup only +.It CREATE +set up for file creation +.It DELETE +set up for file deletion +.It RENAME +set up for file renaming +.It OPMASK +mask for operation +.El +.Pp +Valid values for +.Em cn->cn_flags +are: +.Pp +.Bl -tag -offset indent -width LOCKPARENT -compact +.It LOCKLEAF +lock inode on return +.It LOCKPARENT +want parent vnode returned locked +.It NOCACHE +name must not be left in name cache (see +.Xr namecache 9 ) +.It FOLLOW +follow symbolic links +.It NOFOLLOW +do not follow symbolic links (pseudo) +.It MODMASK +mask of operational modifiers +.El +.Pp +No vnode operations may be called from interrupt context. +Most operations also require the vnode to be locked on entry. +To prevent deadlocks, when acquiring locks on multiple vnodes, the +lock of parent directory must be acquired before the lock on the child +directory. +.Pp +Vnode operations for a file system type generally should not be +called directly from the kernel, but accessed indirectly through the +high-level convenience functions discussed in +.Xr vnsubr 9 . +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn VOP_LOOKUP "dvp" "vpp" "cnp" +Lookup a single pathname component in a given directory. +The argument +.Fa dvp +is the locked vnode of the directory to search and +.Fa cnp +is the pathname component to be searched for. +If the pathname component is found, the address of the resulting +unlocked vnode is returned in +.Fa vpp . +The operation specified in +.Em cnp->cn_nameiop +indicates +.Fn VOP_LOOKUP +the reason for requesting the lookup and uses it to cache +file system type specific information in the vnode for subsequent +operations. +.Pp +There are three types of lookups: ".", ".." (ISDOTDOT), and regular. +If the pathname component being searched for is ".", then +.Fa dvp +has an extra reference added to it and it is returned in +.Fa *vpp . +For other pathname components, +.Fn VOP_LOOKUP +checks the accessibility of the directory and searches the name cache +for the pathname component. +See +.Xr namecache 9 . +If the pathname is not found in the name cache, the directory is +searched for the pathname. +The resulting unlocked vnode is returned in +.Fa vpp . +.Fa dvp +is always returned locked. +.Pp +On failure +.Fa *vpp +is +.Dv NULL , +and +.Fa *dvp +is left locked. +If the operation is successful +.Fa *vpp +is unlocked and zero is returned. +Typically, if +.Fa *vpp +and +.Fa dvp +are the same vnode the caller will need to release twice (decrement +the reference count) and unlock once. +.It Fn VOP_CREATE "dvp" "vpp" "cnp" "vap" +Create a new file in a given directory. +The argument +.Fa dvp +is the locked vnode of the directory to create the new file in and +.Fa cnp +is the pathname component of the new file. +The argument +.Fa vap +specifies the attributes that the new file should be created with. +If the file is successfully created, the address of the resulting +unlocked vnode is returned in +.Fa vpp +and zero is returned. +.Pp +This function is called after +.Fn VOP_LOOKUP +when a file is being created. +Normally, +.Fn VOP_LOOKUP +will have set the SAVENAME flag in +.Em cnp->cn_flags +to keep the memory pointed to by +.Em cnp->cn_pnbuf +valid. +If an error is detected when creating the file, this memory is +released. +If the file is created successfully it will be released unless the +SAVESTART flags in specified in +.Em cnp->cn_flags . +.It Fn VOP_MKNOD "dvp" "vpp" "cnp" "vap" +Make a new device-special file in a given directory. +The argument +.Fa dvp +is the locked vnode of the directory to create the new device-special +file in and +.Fa cnp +is the pathname component of the new device-special file. +The argument +.Fa vap +specifies the attributes that the new device-special file should be +created with. +If the file is successfully created, the address of the resulting +unlocked vnode is returned in +.Fa vpp +and zero is returned. +.Pp +This function is called after +.Fn VOP_LOOKUP +when a device-special file is being created. +Normally, +.Fn VOP_LOOKUP +will have set the SAVENAME flag in +.Em cnp->cn_flags +to keep the memory pointed to by +.Em cnp->cn_pnbuf +valid. +If an error is detected when creating the device-special file, +this memory is released. +If the device-special file is created successfully it will be released +unless the SAVESTART flags in specified in +.Em cnp->cn_flags . +.It Fn VOP_OPEN "vp" "mode" "cred" +Open a file. +The argument +.Fa vp +is the vnode of the file to open and +.Fa mode +specifies the access mode required by the calling process. +The calling credentials are specified by +.Fa cred . +The access mode is a set of flags, including FREAD, FWRITE, +O_NONBLOCK, O_APPEND, etc. +.Fn VOP_OPEN +must be called before a file can be accessed by a thread. +The vnode reference count is incremented. +.Pp +.Fn VOP_OPEN +expects the vnode +.Fa vp +to be locked on entry and will leave it locked on return. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +.It Fn VOP_CLOSE "vp" "fflag" "cred" +Close a file. +The argument +.Fa vp +is the vnode of the file to close and +.Fa fflag +specifies the access mode by the calling process. +The possible flags are +.Dv FREAD , +.Dv FWRITE +and +.Dv FNONBLOCK . +The calling credentials are specified by +.Fa cred . +.Fn VOP_CLOSE +frees resources allocated by +.Fn VOP_OPEN . +.Pp +The vnode +.Fa vp +will be locked on entry and should remain locked on return. +.It Fn VOP_ACCESS "vp" "mode" "cred" +Determine the accessibility (permissions) of the file against the +specified credentials. +The argument +.Fa vp +is the vnode of the file to check, +.Fa mode +is the type of access required and +.Fa cred +contains the user credentials to check. +The argument +.Fa mode +is a mask which can contain VREAD, VWRITE or VEXEC. +If the file is accessible in the specified way, zero is returned, +otherwise an appropriate error code is returned. +.Pp +The vnode +.Fa vp +will be locked on entry and should remain locked on return. +.It Fn VOP_GETATTR "vp" "vap" "cred" +Get specific vnode attributes on a file. +The argument +.Fa vp +is the vnode of the file to get the attributes for. +The argument +.Fa cred +specifies the calling credentials. +.Fn VOP_GETATTR +uses the file system type specific data object +.Em vp->v_data +to reference the underlying file attributes. +.\" Attributes associated with the file are collected by setting the +.\" required attribute bits in +.\" .Em vap->va_mask . +The attributes are returned in +.Fa vap . +Attributes which are not available are set to the value VNOVAL. +.Pp +For more information on vnode attributes see +.Xr vattr 9 . +Historically it was considered acceptable to call +.Fn VOP_GETATTR +without first locking the vnode. +This usage is deprecated. +.Pp +The vnode +.Fa vp +will be locked on entry and should remain locked on return. +.It Fn VOP_SETATTR "vp" "vap" "cred" +Set specific vnode attributes on a file. +The argument +.Fa vp +is the locked vnode of the file to set the attributes for. +The argument +.Fa cred +specifies the calling credentials. +.Fn VOP_SETATTR +uses the file system type specific data object +.Em vp->v_data +to reference the underlying file attributes. +The new attributes are defined in +.Fa vap . +.\" Attributes associated with the file are set by setting the required +.\" attribute bits in +.\" .Em vap->va_mask . +Attributes which are not being modified by +.Fn VOP_SETATTR +should be set to the value VNOVAL. +If the operation is successful zero is returned, otherwise an +appropriate error is returned. +.Pp +For more information on vnode attributes see +.Xr vattr 9 . +.It Fn VOP_READ "vp" "uio" "ioflag" "cred" +Read the contents of a file. +The argument +.Fa vp +is the vnode of the file to read from, +.Fa uio +is the location to read the data into, +.Fa ioflag +is a set of flags and +.Fa cred +are the credentials of the calling process. +.Pp +The +.Fa ioflag +argument is used to give directives and hints to the file system. +When attempting a read, the high 16 bits are used to provide a +read-ahead hint (in unit of file system blocks) that the file system +should attempt. +The low 16 bits are a bit mask which can contain the following flags: +.Pp +.Bl -tag -offset indent -width IO_ALTSEMANTICS -compact +.It IO_UNIT +do I/O as atomic unit +.It IO_APPEND +append write to end +.It IO_SYNC +sync I/O file integrity completion +.It IO_NODELOCKED +underlying node already locked +.It IO_NDELAY +FNDELAY flag set in file table +.It IO_DSYNC +sync I/O data integrity completion +.It IO_ALTSEMANTICS +use alternate I/O semantics +.It IO_NORMAL +operate on regular data +.It IO_EXT +operate on extended attributes +.It IO_DIRECT +do not buffer data in the kernel +.El +.Pp +Zero is returned on success, otherwise an error is returned. +The vnode should be locked on entry and remains locked on exit. +.It Fn VOP_WRITE "vp" "uio" "ioflag" "cred" +Write to a file. +The argument +.Fa vp +is the vnode of the file to write to, +.Fa uio +is the location of the data to write, +.Fa ioflag +is a set of flags and +.Fa cred +are the credentials of the calling process. +.Pp +The +.Fa ioflag +argument is used to give directives and hints to the file system. +The low 16 bits are a bit mask which can contain the same flags as +.Fn VOP_READ . +.Pp +Zero is returned on success, otherwise an error is returned. +The vnode should be locked on entry and remains locked on exit. +.It Fn VOP_FALLOCATE "vp" "pos" "len" +Allocate backing store. +The argument +.Fa vp +is the vnode for the file. +The +.Fa pos +and +.Fa len +arguments (specified in bytes) name an extent within the file. +The blocks underlying this range, rounding up at the top and down at +the bottom if needed, are checked; if no physical storage is +allocated, a physical block is allocated and zeroed. +This operation removes +.Dq holes +from files. +.It Fn VOP_FDISCARD "vp" "pos" "len" +Discard backing store. +The argument +.Fa vp +is the vnode for the file. +The +.Fa pos +and +.Fa len +arguments (specified in bytes) name an extent within the file. +The blocks underlying this range, rounding down at the top and up at +the bottom if needed, are checked. +If any physical storage is used, it is deallocated. +This operation creates +.Dq holes +in files. +Discarded blocks of regular files read back afterwards as zeroes. +On devices, the underlying discard-block operation if any (e.g. ATA +TRIM) is issued. +The device handles this as it sees fit. +In particular it is +.Em not +guaranteed that discarded blocks on devices will be zeroed; reading a +discarded block might produce zeros, or ones, or the previously +existing data, or some other data, or trash. +.\" XXX: if you discard part of a block in a regular file, should that +.\" part be explicitly zeroed? Also, how do you find the underlying +.\" block size? +.It Fn VOP_IOCTL "vp" "command" "data" "fflag" "cred" +Perform device-specific I/O. +The argument +.Fa vp +is the vnode of the file, normally representing a device. +The argument +.Fa command +specifies the device-specific operation to perform and +.Fa cnp +provides extra data for the specified operation. +The argument +.Fa fflags +is a set of flags. +The argument +.Fa cred +is the caller's credentials. +If the operation is successful, zero is +returned, otherwise an appropriate error code is returned. +.Pp +Most file systems do not supply a function for +.Fn VOP_IOCTL . +This function implements the +.Xr ioctl 2 +system call. +.It Fn VOP_FCNTL "vp" "command" "data" "fflag" "cred" +Perform file control. +The argument +.Fa vp +is the locked vnode of the file. +The argument +.Fa command +specifies the operation to perform and +.Fa cnp +provides extra data for the specified operation. +The argument +.Fa fflags +is a set of flags. +The argument +.Fa cred +is the caller's credentials. +If the operation is successful, zero is returned, otherwise an +appropriate error code is returned. +.It Fn VOP_POLL "vp" "events" +Test if a poll event has occurred. +The argument +.Fa vp +is the vnode of the file to poll. +It returns any events of interest as specified by +.Fa events +that may have occurred for the file. +The argument +.Fa events +is a set of flags as specified by +.Xr poll 2 . +.Pp +The vnode +.Fa vp +remains unlocked throughout the whole operation. +.It Fn VOP_KQFILTER "vp" "kn" +Register a knote +.Fa kn +with the vnode +.Fa vn . +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +.Pp +The vnode +.Fa vp +remains unlocked throughout the whole operation. +.It Fn VOP_REVOKE "vp" "flags" +Eliminate all activity associated with the vnode +.Fa vp . +The argument +.Fa flags +is a set of flags. +If REVOKEALL is set in +.Fa flags +all vnodes aliased to the vnode +.Fa vp +are also eliminated. +If the operation is successful zero is returned, otherwise an +appropriate error is returned. +.Pp +The vnode +.Fa vp +remains unlocked throughout the whole operation. +.It Fn VOP_MMAP "vp" "prot" "cred" +Inform file system that +.Fa vp +is in the process of being memory mapped. +The argument +.Fa prot +specifies the vm access protection the vnode is going to be mapped with. +The argument +.Fa cred +is the caller's credentials. +If the file system allows the memory mapping, zero is returned, otherwise +an appropriate error code is returned. +.Pp +Most file systems do not supply a function for +.Fn VOP_MMAP +and use +.Fn genfs_mmap +to default for success. +Only file systems which do not integrate with the page cache at all +typically want to disallow memory mapping. +.It Fn VOP_FSYNC "vp" "cred" "flags" "offlo" "offhi" +Flush pending data buffers for a file to disk. +The argument +.Fa vp +is the locked vnode of the file for flush. +The argument +.Fa cred +is the caller's credentials. +The argument +.Fa flags +is a set of flags. +If FSYNC_WAIT is specified in +.Fa flags , +the function should wait for I/O to complete before returning. +The argument +.Fa offlo +and +.Fa offhi +specify the range of file to flush. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +.Pp +This function implements the +.Xr sync 2 +and +.Xr fsync 2 +system calls. +.It Fn VOP_SEEK "vp" "oldoff" "newoff" "cred" +Test if the file is seekable for the specified offset +.Fa newoff . +The argument +.Fa vp +is the locked vnode of the file to test. +For most file systems this function simply tests if +.Fa newoff +is valid. +If the specified +.Fa newoff +is less than zero, the function returns error code EINVAL. +.It Fn VOP_REMOVE "dvp" "vp" "cnp" +Remove a file. +The argument +.Fa dvp +is the locked vnode of the directory to remove the file from and +.Fa vp +is the locked vnode of the file to remove. +The argument +.Fa cnp +is the pathname component about the file to remove. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +Both +.Fa dvp +and +.Fa vp +are locked on entry and are to be unlocked before returning. +.It Fn VOP_LINK "dvp" "vp" "cnp" +Link to a file. +The argument +.Fa dvp +is the locked node of the directory to create the new link and +.Fa vp +is the vnode of the file to be linked. +The argument +.Fa cnp +is the pathname component of the new link. +If the operation is successful zero is returned, otherwise an error +code is returned. +The directory vnode +.Fa dvp +should be locked on entry and will be released and unlocked on return. +The vnode +.Fa vp +should not be locked on entry and will remain unlocked on return. +.It Fn VOP_RENAME "fdvp" "fvp" "fcnp" "tdvp" "tvp" "tcnp" +Rename a file. +The argument +.Fa fdvp +is the vnode of the old parent directory containing in the file to be +renamed and +.Fa fvp +is the vnode of the file to be renamed. +The argument +.Fa fcnp +is the pathname component about the file to be renamed. +The argument +.Fa tdvp +is the vnode of the new directory of the target file and +.Fa tvp +is the vnode of the target file (if it exists). +The argument +.Fa tcnp +is the pathname component about the file's new name. +If the operation is successful zero is returned, otherwise an error +code is returned. +.Pp +The caller must hold the target file system's rename lock. +The source directory and file vnodes should be unlocked and their +reference counts should be incremented before entry. +The target directory and file vnodes should both be locked on entry. +.Fn VOP_RENAME +updates the reference counts prior to returning. +.Pp +Because of the complexity and nastiness of the interface, please do +not write new code that calls +.Fn VOP_RENAME +directly until such time as ongoing cleanup work reaches a point where +the interface has been rendered halfway sane. +.It Fn VOP_MKDIR "dvp" "vpp" "cnp" "vap" +Make a new directory in a given directory. +The argument +.Fa dvp +is the locked vnode of the directory to create the new directory in and +.Fa cnp +is the pathname component of the new directory. +The argument +.Fa vap +specifies the attributes that the new directory should be created +with. +If the file is successfully created, the address of the resulting +unlocked vnode is returned in +.Fa vpp +and zero is returned. +.Pp +This function is called after +.Fn VOP_LOOKUP +when a directory is being created. +Normally, +.Fn VOP_LOOKUP +will have set the SAVENAME flag in +.Em cnp->cn_flags +to keep the memory pointed to by +.Em cnp->cn_pnbuf +valid. +If an error is detected when creating the directory, this memory is +released. +If the directory is created successfully it will be released unless +the SAVESTART flags in specified in +.Em cnp->cn_flags . +.It Fn VOP_RMDIR "dvp" "vp" "cnp" +Remove a directory in a given directory. +The argument +.Fa dvp +is the locked vnode of the directory to remove the directory from and +.Fa vp +is the locked vnode of the directory to remove. +The argument +.Fa cnp +is the pathname component of the directory. +Zero is returned on success, otherwise an error code is returned. +Both +.Fa dvp +and +.Fa vp +should be locked on entry and will be released and unlocked on return. +.It Fn VOP_SYMLINK "dvp" "vpp" "cnp" "vap" "target" +Create a symbolic link in a given directory. +The argument +.Fa dvp +is the locked vnode of the directory to create the symbolic link in +and +.Fa cnp +is the pathname component of the symbolic link. +The argument +.Fa vap +specifies the attributes that the symbolic link should be created +with and +.Fa target +specifies the pathname of the target of the symbolic link. +If the symbolic link is successfully created, the address of the +resulting unlocked vnode is returned in +.Fa vpp +and zero is returned. +.Pp +This function is called after +.Fn VOP_LOOKUP +when a symbolic link is being created. +Normally, +.Fn VOP_LOOKUP +will have set the SAVENAME flag in +.Em cnp->cn_flags +to keep the memory pointed to by +.Em cnp->cn_pnbuf +valid. +If an error is detected when creating the symbolic link, this memory +is released. +If the symbolic link is created successfully it will be released +unless the SAVESTART flags in specified in +.Em cnp->cn_flags . +.It Fn VOP_READDIR "vp" "uio" "cred" "eofflag" "cookies" "ncookies" +Read directory entry. +The argument +.Fa vp +is the vnode of the directory to read the contents of and +.Fa uio +is the destination location to read the contents into. +The argument +.Fa cred +is the caller's credentials. +The argument +.Fa eofflag +is the pointer to a flag which is set by +.Fn VOP_READDIR +to indicate an end-of-file condition. +If +.Fa eofflag +is +.Dv NULL , +the end-of-file condition is not returned. +The arguments +.Fa cookies +and +.Fa ncookies +specify the addresses for the list and number of directory seek +cookies generated for NFS. +Both +.Fa cookies +and +.Fa ncookies +should be +.Dv NULL +if they aren't required to be returned by +.Fn VOP_READDIR . +The directory contents are read into struct dirent structures and +.Fa uio->uio_offset +is set to the offset of the next unread directory entry. +This offset may be used in a following invocation to continue a +sequential read of the directory contents. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +.Pp +The directory should be locked on entry and will remain locked on +return. +.Pp +In case +.Fa ncookies +and +.Fa cookies +are supplied, one cookie should be returned per directory entry. +The value of the cookie for each directory entry should be the offset +within the directory where the on-disk version of the following +directory entry starts. +That is, for each directory entry +.Fa i , +the corresponding cookie should refer to the offset of directory entry +.Fa i + 1 . +.Pp +Note that the +.Fa cookies +array must be allocated by the callee using the M_TEMP malloc type as +callers of +.Fn VOP_READDIR +must be able to free the allocation. +.It Fn VOP_READLINK "vp" "uio" "cred" +Read the contents of a symbolic link. +The argument +.Fa vp +is the locked vnode of the symlink and +.Fa uio +is the destination location to read the contents into. +The argument +.Fa cred +is the credentials of the caller. +If the operation is successful zero is returned, otherwise an error +code is returned. +.Pp +The vnode should be locked on entry and will remain locked on return. +.It Fn VOP_ABORTOP "dvp" "cnp" +Abort pending operation on vnode +.Fa dvp +and free resources allocated in +.Fa cnp . +.Pp +This operation is rarely implemented in file systems and +.Fn genfs_abortop +is typically used instead. +.It Fn VOP_INACTIVE "vp" +Release the inactive vnode. +.Fn VOP_INACTIVE +is called when the kernel is no longer using the vnode. +This may be because the reference count reaches zero or it may be that +the file system is being forcibly unmounted while there are open +files. +It can be used to reclaim space for open but deleted files. +The argument +.Fa vp +is the locked vnode to be released. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +The vnode +.Fa vp +must be locked on entry, and will remain locked on return. +.It Fn VOP_RECLAIM "vp" +Reclaim the vnode for another file system. +.Fn VOP_RECLAIM +is called when a vnode is being reused for a different file system. +Any file system specific resources associated with the vnode should be +freed. +The argument +.Fa vp +is the vnode to be reclaimed. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +The vnode +.Fa vp +should be locked on entry, and will be returned unlocked. +.It Fn VOP_LOCK "vp" "flags" +Sleep until vnode lock is free. +The argument +.Fa vp +is the vnode of the file to be locked. +The argument +.Fa flags +is +.Dv LK_EXCLUSIVE +to take the lock exclusively or +.Dv LK_SHARED +to take a shared lock. +If +.Fa flags +contains +.Dv LK_NOWAIT +and the lock is busy, the operation will return immediately with an error code. +If +.Fa flags +contains +.Dv LK_RETRY +this is a hint the caller wants the lock on dead vnodes too. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +.Fn VOP_LOCK +is used to serialize access to the file system such as to prevent two +writes to the same file from happening at the same time. +Kernel code should use +.Xr vn_lock 9 +to lock a vnode rather than calling +.Fn VOP_LOCK +directly. +.It Fn VOP_UNLOCK "vp" +Wake up process sleeping on lock. +The argument +.Fa vp +is the vnode of the file to be unlocked. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +.Fn VOP_UNLOCK +is used to serialize access to the file system such as to prevent two +writes to the same file from happening at the same time. +.It Fn VOP_ISLOCKED "vp" +Test if the vnode +.Fa vp +is locked. +Possible return values are +.Dv LK_EXCLUSIVE , +.Dv LK_SHARED +or 0 for lock held exclusively by the calling thread, shared lock held +by anyone or unlocked, respectively. +.Pp +This function must never be used to make locking decisions at run time: +it is provided only for diagnostic purposes. +.It Fn VOP_BMAP "vp" "bn" "vpp" "bnp" "runp" +Convert the logical block number +.Fa bn +of a file specified by vnode +.Fa vp +to its physical block number on the disk. +The physical block is returned in +.Fa bnp . +In case the logical block is not allocated, \-1 is used. +.Pp +If +.Fa vpp +is not +.Dv NULL , +the vnode of the device vnode for the file system is +returned in the address specified by +.Fa vpp . +If +.Fa runp +is not +.Dv NULL , +the number of contiguous blocks starting from the next block after +the queried block will be returned in +.Fa runp . +.It Fn VOP_PRINT "vp" +Print debugging information. +The argument +.Fa vp +is the vnode to print. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +.It Fn VOP_PATHCONF "vp" "name" "retval" +Implement POSIX +.Xr pathconf 2 +and +.Xr fpathconf 2 +support. +The argument +.Fa vp +is the locked vnode to get information about. +The argument +.Fa name +specified the type of information to return. +The information is returned in the address specified by +.Fa retval . +Valid values for +.Fa name +are: +.Pp +.Bl -tag -offset indent -width _PC_CHOWN_RESTRICTED -compact +.It _PC_LINK_MAX +return the maximum number of links to a file +.It _PC_NAME_MAX +return the maximum number of bytes in a file name +.It _PC_PATH_MAX +return the maximum number of bytes in a pathname +.It _PC_PIPE_BUF +return the maximum number of bytes which will be written atomically to +a pipe +.It _PC_CHOWN_RESTRICTED +return 1 if appropriate privileges are required for the +.Xr chown 2 +system call, otherwise zero +.It _PC_NO_TRUNC +return 0 if file names longer than +.Brq Dv NAME_MAX +are silently truncated +.El +.Pp +If +.Fa name +is recognized, +.Fa *retval +is set to the specified value and zero is returned, otherwise an +appropriate error is returned. +.It Fn VOP_ADVLOCK "vp" "id" "op" "fl" "flags" +Manipulate Advisory record locks on a vnode. +The argument +.Fa vp +is the vnode on which locks are manipulated. +The argument +.Fa id +is the id token which is changing the lock and +.Fa op +is the +.Xr fcntl 2 +operation to perform. +Valid values are: +.Pp +.Bl -tag -offset indent -width F_UNLCK -compact +.It F_SETLK +set lock +.It F_GETLK +get the first conflicted lock +.It F_UNLCK +clear lock +.El +.Pp +The argument +.Fa fl +is a description of the lock. +In the case of +.Dv SEEK_CUR , +The caller should add the current file offset to +fl->l_start beforehand. +.Fn VOP_ADVLOCK +treats +.Dv SEEK_CUR +as +.Dv SEEK_SET . +.Pp +The argument +.Fa flags +is the set of flags. +Valid values are: +.Pp +.Bl -tag -offset indent -width F_FLOCK -compact +.It F_WAIT +wait until lock is granted +.It F_FLOCK +use +.Xr flock 2 +semantics for lock +.It F_POSIX +use POSIX semantics for lock +.El +.Pp +If the operation is successful zero is returned, otherwise an +appropriate error is returned. +.It Fn VOP_WHITEOUT "dvp" "cnp" "flags" +Whiteout pathname component in directory with vnode +.Fa dvp . +The argument +.Fa cnp +specifies the pathname component to whiteout. +.Pp +The vnode +.Fa dvp +should be locked on entry and will remain locked on return. +.It Fn VOP_GETPAGES "vp" "offset" "m" "count" "centeridx" "access_type" "advice" "flags" +Read VM pages from file. +The argument +.Fa vp +is the locked vnode to read the VM pages from. +The argument +.Fa offset +is offset in the file to start accessing and +.Fa m +is an array of VM pages. +The argument +.Fa count +points a variable that specifies the number of pages to read. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +If PGO_LOCKED is specified in +.Em flags , +.Fn VOP_GETPAGES +might return less pages than requested. +In that case, the variable pointed to by +.Em count +will be updated. +.Pp +This function is primarily used by the page-fault handing mechanism. +.It Fn VOP_PUTPAGES "vp" "offlo" "offhi" "flags" +Write modified (dirty) VM pages to file. +The argument +.Fa vp +is the vnode to write the VM pages to. +The vnode's vm object lock +.Va ( v_uobj.vmobjlock ) +must be held by the caller and will be released upon return. +The arguments +.Fa offlo +and +.Fa offhi +specify the range of VM pages to write. +In case +.Fa offhi +is given as 0, all pages at and after the start offset +.Fa offlo +belonging the vnode +.Fa vp +will be written. +The argument +.Fa flags +controls the behavior of the routine and takes the vm pager's +flags +.Dv ( PGO_ -prefixed ) . +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +.Pp +The function is primarily used by the pageout handling mechanism and +is commonly implemented indirectly +by +.Fn genfs_putpages +with the help of +.Fn VOP_STRATEGY +and +.Fn VOP_BMAP . +.It Fn VOP_STRATEGY "vp" "bp" +Read/write a file system buffer. +The argument +.Fa vp +is the vnode to read/write to. +The argument +.Fa bp +is the buffer to be read or written. +.Fn VOP_STRATEGY +will either read or write data to the file depending on the value of +.Em bp->b_flags . +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +.It Fn VOP_BWRITE "vp" "bp" +Write a file system buffer. +The argument +.Fa vp +is the vnode to write to. +The argument +.Fa bp +specifies the buffer to be written. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +.It Fn VOP_GETEXTATTR "vp" "attrnamespace" "name" "uio" "size" "cred" +Get an extended attribute. +The argument +.Fa vp +is the locked vnode of the file or directory from which to retrieve the +attribute. +The argument +.Fa attrnamespace +specifies the extended attribute namespace. +The argument +.Fa name +is a nul-terminated character string naming the attribute to retrieve. +The argument +.Fa uio , +if not +.Dv NULL , +specifies where the extended attribute value is to be written. +The argument +.Fa size , +if not +.Dv NULL , +will contain the number of bytes required to read all of +the attribute data upon return. +In most cases, +.Fa uio +will be +.Dv NULL +when +.Fa size +is not, and vice versa. +The argument +.Fa cred +specifies the user credentials to use when authorizing the request. +.It Fn VOP_SETEXTATTR "vp" "attrnamespace" "name" "uio" "cred" +Set an extended attribute. +The argument +.Fa vp +is the locked vnode of the file or directory to which to store the +attribute. +The argument +.Fa namespace +specifies the extended attribute namespace. +The argument +.Fa name +is a nul-terminated character string naming the attribute to store. +The argument +.Fa uio +specifies the source of the extended attribute data. +The argument +.Fa cred +specifies the user credentials to use when authorizing the request. +.It Fn VOP_LISTEXTATTR "vp" "attrnamespace" "uio" "size" "cred" +Retrieve the list of extended attributes. +The argument +.Fa vp +is the locked vnode of the file or directory whose attributes are to be listed. +The argument +.Fa attrnamespace +specifies the extended attribute namespace. +The argument +.Fa uio , +if not +.Dv NULL , +specifies where the extended attribute list is to be written. +The argument +.Fa size , +if not +.Dv NULL , +will contain the number of bytes required to read all of +the attribute names upon return. +In most cases, +.Fa uio +will be +.Dv NULL +when +.Fa size +is not, and vice versa. +The argument +.Fa cred +specifies the user credentials to use when authorizing the request. +.It Fn VOP_DELETEEXTATTR "vp" "attrnamespace" "name" "cred" +Remove attribute +.Fa name +from file associated with +.Fa vp . +The argument +.Fa attrnamespace +specifies the extended attribute namespace. +If full removal is not supported, the file system should return +.Er EOPNOTSUPP +to allow the caller to zero out the value with +.Fn VOP_SETEXTATTR . +.Pp +The vnode +.Fa vp +should be locked on entry and will remain locked on return. +.El +.Sh FILES +.Pa src/sys/kern/vnode_if.src +contains the list of vnode functions, their definitions and an exact locking +protocol. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACCES +Access for the specified operation is denied. +.It Bq Er EDQUOT +Quota exceeded. +.It Bq Er EINVAL +attempt to read from an illegal offset in the directory; unrecognized +input +.It Bq Er EIO +a read error occurred while reading the directory or reading the +contents of a symbolic link +.It Bq Er EJUSTRETURN +A CREATE or RENAME operation would be successful. +.It Bq Er ENOATTR +The requested attribute is not defined for this vnode. +.It Bq Er ENOENT +The component was not found in the directory. +.It Bq Er ENOSPC +The file system is full. +.It Bq Er ENOTDIR +The vnode does not represent a directory. +.It Bq Er ENOTEMPTY +attempt to remove a directory which is not empty +.It Bq Er EPERM +an attempt was made to change an immutable file +.It Bq Er EROFS +the file system is read-only +.El +.Sh SEE ALSO +.Xr extattr 9 , +.Xr intro 9 , +.Xr namei 9 , +.Xr vattr 9 , +.Xr vfs 9 , +.Xr vfsops 9 , +.Xr vnode 9 +.Sh HISTORY +The vnode operations vector, its functions and the corresponding +macros appeared in +.Bx 4.3 . diff --git a/static/netbsd/man9/vnsubr.9 b/static/netbsd/man9/vnsubr.9 new file mode 100644 index 00000000..36d27a05 --- /dev/null +++ b/static/netbsd/man9/vnsubr.9 @@ -0,0 +1,354 @@ +.\" $NetBSD: vnsubr.9,v 1.48 2021/06/29 22:40:53 dholland Exp $ +.\" +.\" Copyright (c) 2001, 2005, 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 28, 2021 +.Dt VNSUBR 9 +.Os +.Sh NAME +.Nm vnsubr , +.Nm vn_bwrite , +.Nm vn_close , +.Nm vn_default_error , +.Nm vn_isunder , +.Nm vn_lock , +.Nm vn_markexec , +.Nm vn_marktext , +.Nm vn_rdwr , +.Nm vn_open , +.Nm vn_bdev_open , +.Nm vn_bdev_openpath , +.Nm vn_stat , +.Nm vn_writechk +.Nd high-level convenience functions for vnode operations +.Sh SYNOPSIS +.In sys/param.h +.In sys/lock.h +.In sys/vnode.h +.Ft int +.Fn vn_bwrite "void *ap" +.Ft int +.Fn vn_close "struct vnode *vp" "int flags" "kauth_cred_t cred" +.Ft int +.Fn vn_default_error "void *v" +.Ft int +.Fn vn_isunder "struct vnode *dvp" "struct vnode *rvp" "struct lwp *l" +.Ft int +.Fn vn_lock "struct vnode *vp" "int flags" +.Ft void +.Fn vn_markexec "struct vnode *vp" +.Ft void +.Fn vn_marktext "struct vnode *vp" +.Ft int +.Fo vn_open +.Fa "struct vnode *at_dvp" "struct pathbuf *pb" +.Fa "int nmode" "int fmode" "int cmode" +.Fa "struct vnode **ret_vp" "bool *ret_domove" "int *ret_fd" +.Fc +.Ft int +.Fn vn_bdev_open "dev_t dev" "struct vnode **vpp" "struct lwp *l" +.Ft int +.Fn vn_bdev_openpath "struct pathbuf *pb" "struct vnode **vpp" "struct lwp *l" +.Ft int +.Fo vn_rdwr +.Fa "enum uio_rw rw" "struct vnode *vp" "void *base" +.Fa "int len" "off_t offset" "enum uio_seg segflg" "int ioflg" +.Fa "kauth_cred_t cred" "size_t *aresid" "struct lwp *l" +.Fc +.Ft int +.Fn vn_readdir "file_t *fp" "char *buf" "int segflg" "u_int count" "int *done" "struct lwp *l" "off_t **cookies" "int *ncookies" +.Ft int +.Fn vn_stat "struct vnode *vp" "struct stat *sb" +.Ft int +.Fn vn_writechk "struct vnode *vp" +.Sh DESCRIPTION +The high-level functions described in this page are convenience +functions for simplified access to the vnode operations described in +.Xr vnodeops 9 . +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn vn_bwrite "ap" +Common code for block write operations. +.It Fn vn_close "vp" "flags" "cred" +Common code for a vnode close. +The argument +.Fa vp +is the unlocked vnode of the vnode to close. +.Fn vn_close +simply locks the vnode, invokes the vnode operation +.Xr VOP_CLOSE 9 +and calls +.Fn vput +to return the vnode to the freelist or holdlist. +Note that +.Fn vn_close +expects an unlocked, referenced vnode and will dereference the vnode +prior to returning. +If the operation is successful zero is returned, +otherwise an appropriate error is returned. +.It Fn vn_default_error "v" +A generic "default" routine that just returns error. +It is used by a file system to specify unsupported operations in +the vnode operations vector. +.It Fn vn_isunder "dvp" "rvp" "l" +Common code to check if one directory specified by the vnode +.Fa rvp +can be found inside the directory specified by the vnode +.Fa dvp . +The argument +.Fa l +is the calling process. +.Fn vn_isunder +is intended to be used in +.Xr chroot 2 , +.Xr chdir 2 , +.Xr fchdir 2 , +etc., to ensure that +.Xr chroot 2 +actually means something. +If the operation is successful zero is returned, otherwise 1 is returned. +.It Fn vn_lock "vp" "flags" +Common code to acquire the lock for vnode +.Fa vp . +The argument +.Fa flags +specifies the flags used to lock the vnode. +There are the following flags: +.Pp +.Bl -tag -offset indent -width LK_EXCLUSIVE -compact +.It LK_SHARED +shared lock +.It LK_EXCLUSIVE +exclusive lock +.It LK_NOWAIT +do not sleep to await lock +.It LK_RETRY +allow lock operation on dead vnode +.El +.Pp +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +.Pp +.Fn vn_lock +must not be called when the vnode's reference count is zero. +.It Fn vn_markexec "vp" +Common code to mark the vnode +.Fa vp +as containing executable code of a running process. +.It Fn vn_marktext "vp" +Common code to mark the vnode +.Fa vp +as being the text of a running process. +.It Fn vn_open "at_dvp" "pb" "nmode" "fmode" "cmode" "ret_vp" "ret_domove" "ret_fd" +Common code for vnode open operations. +The +.Fa at_dvp +argument, if not NULL, provides the directory relative paths start +from, as per +.Xr openat 2 . +The +.Fa pb +argument gives the pathname. +The arguments +.Fa nmode , +.Fa fmode +and +.Fa cmode +specify additional +.Xr namei 9 +flags, the +.Xr open 2 +flags (converted to +.Dv F* +from +.Dv O_* +form) +and the access mode (permissions) for creation, respectively. +The +.Fa nmode +argument is restricted to one or perhaps both of the flags +.Dv TRYEMULROOT +and +.Dv NOCHROOT . +Other +.Xr name 9 +modes should be selected via +.Fn fmode . +The +.Fa ret_vp , +.Fa ret_domove , +and +.Fa ret_fd +arguments encode the possible return values. +When called, +.Fn vn_open +checks permissions and invokes the +.Xr VOP_OPEN 9 +or +.Xr VOP_CREATE 9 +vnode operations. +If the operation is unsuccessful an appropriate error code is returned. +Otherwise, zero is returned. +If a vnode is produced, it is returned locked via +.Fa ret_vp . +If a file descriptor number is produced instead, the pointer passed via +.Fa ret_vp +is NULL, the file descriptor is returned via +.Fa ret_fd , +and the +.Fa ret_domove +returns a value that is true if the file descriptor should be moved +rather than copied. +These cases correspond to the internal errors +.Dv EMOVEFD +and +.Dv EDUPFD +respectively. +See +.Xr errno 9 +for further information. +Callers unprepared to handle file descriptors can set +.Fa ret_fd +and +.Fa ret_domove +to NULL, in which case an operation that would produce a file descriptor +will instead fail with +.Dv EOPNOTSUPP . +.It Fn vn_bdev_open "dev" "vpp" "l" +Opens a block device by its device number for reading and writing, and +stores the vnode pointer into +.Fa *vpp . +The argument +.Fa l +is the calling process. +The vnode can be closed and freed with +.Fa vn_close . +.It Fn vn_bdev_openpath "pb" "vpp" "l" +Works like +.Fn vn_bdev_open +but looks up a file system path +.Fa pb +to determine the device ID. +.It Fn vn_rdwr "rw" "vp" "base" "len" "offset" "segflg" "ioflg" "cred" "aresid" "l" +Common code to package up an I/O request on a vnode into a uio and +then perform the I/O. +The argument +.Fa rw +specifies whether the I/O is a read +.Dv ( UIO_READ ) +or write +.Dv ( UIO_WRITE ) +operation. +The vnode is specified by +.Fa vp . +The arguments +.Fa l +and +.Fa cred +are the calling lwp and its credentials. +If +.Fa ioflg +contains +.Dv IO_NODELOCKED , +it is expected that the vnode is locked. +.Fa ioflg +will be passed to +.Fn VOP_READ Ns No / Ns Fn VOP_WRITE . +The remaining arguments specify the uio parameters. +For further information on these parameters see +.Xr uiomove 9 . +.It Fn vn_readdir "fp" "buf" "segflg" "count" "done" "l" "cookies" "ncookies" +Common code for reading the contents of a directory. +The argument +.Fa fp +is the file structure, +.Fa buf +is the buffer for placing the struct dirent structures. +The arguments +.Fa cookies +and +.Fa ncookies +specify the addresses for the list and number of directory seek +cookies generated for NFS. +Both +.Fa cookies +and +.Fa ncookies +should be +.Dv NULL +if they aren't required to be returned by +.Fn vn_readdir . +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +.It Fn vn_stat "vp" "sb" +Common code for a vnode stat operation. +The vnode is specified by the argument +.Fa vp , +and +.Fa sb +is the buffer to return the stat information. +.Fn vn_stat +basically calls the vnode operation +.Xr VOP_GETATTR 9 +and transfers the contents of a vattr structure into a struct stat. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +.It Fn vn_writechk "vp" +Common code to check for write permission on the vnode +.Fa vp . +A vnode is read-only if it is in use as a process's text image. +If the vnode is read-only ETEXTBSY is returned, otherwise zero is +returned to indicate that the vnode can be written to. +.El +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EBUSY +The LK_NOWAIT flag was set and +.Fn vn_lock +would have slept. +.It Bq Er ENOENT +The vnode has been reclaimed and is dead. +This error is only returned if the LK_RETRY flag is not passed to +.Fn vn_lock . +.It Bq Er ETXTBSY +Cannot write to a vnode since is a process's text image. +.El +.Sh CODE REFERENCES +The high-level convenience functions are implemented within the files +.Pa sys/kern/vfs_vnops.c +and +.Pa sys/sys/vnode.h . +.Sh SEE ALSO +.Xr file 9 , +.Xr intro 9 , +.Xr lock 9 , +.Xr namei 9 , +.Xr vattr 9 , +.Xr vfs 9 , +.Xr vnode 9 , +.Xr vnodeops 9 diff --git a/static/netbsd/man9/wapbl.9 b/static/netbsd/man9/wapbl.9 new file mode 100644 index 00000000..87d1e1a9 --- /dev/null +++ b/static/netbsd/man9/wapbl.9 @@ -0,0 +1,532 @@ +.\" $NetBSD: wapbl.9,v 1.15 2017/03/18 19:01:01 riastradh Exp $ +.\" +.\" Copyright (c) 2015 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Taylor R. Campbell. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 26, 2015 +.Dt WAPBL 9 +.Os +.Sh NAME +.Nm WAPBL , +.Nm wapbl_start , +.Nm wapbl_stop , +.Nm wapbl_begin , +.Nm wapbl_end , +.Nm wapbl_flush , +.Nm wapbl_discard , +.Nm wapbl_add_buf , +.Nm wapbl_remove_buf , +.Nm wapbl_resize_buf , +.Nm wapbl_register_inode , +.Nm wapbl_unregister_inode , +.Nm wapbl_register_deallocation , +.Nm wapbl_jlock_assert , +.Nm wapbl_junlock_assert +.Nd write-ahead physical block logging for file systems +.Sh SYNOPSIS +.In sys/wapbl.h +.Vt typedef void (*wapbl_flush_fn_t)(struct mount *, daddr_t *, int *, int) ; +.Ft int +.Fn wapbl_start "struct wapbl **wlp" "struct mount *mp" "struct vnode *devvp" \ + "daddr_t off" "size_t count" "size_t blksize" \ + "struct wapbl_replay *wr" \ + "wapbl_flush_fn_t flushfn" "wapbl_flush_fn_t flushabortfn" +.Ft int +.Fn wapbl_stop "struct wapbl *wl" "int force" +.Ft int +.Fn wapbl_begin "struct wapbl *wl" "const char *file" "int line" +.Ft void +.Fn wapbl_end "struct wapbl *wl" +.Ft int +.Fn wapbl_flush "struct wapbl *wl" "int wait" +.Ft void +.Fn wapbl_discard "struct wapbl *wl" +.Ft void +.Fn wapbl_add_buf "struct wapbl *wl" "struct buf *bp" +.Ft void +.Fn wapbl_remove_buf "struct wapbl *wl" "struct buf *bp" +.Ft void +.Fn wapbl_resize_buf "struct wapbl *wl" "struct buf *bp" "long oldsz" \ + "long oldcnt" +.Ft void +.Fn wapbl_register_inode "struct wapbl *wl" "ino_t ino" "mode_t mode" +.Ft void +.Fn wapbl_unregister_inode "struct wapbl *wl" "ino_t ino" "mode_t mode" +.Ft void +.Fn wapbl_register_deallocation "struct wapbl *wl" "daddr_t blk" "int len" +.Ft void +.Fn wapbl_jlock_assert "struct wapbl *wl" +.Ft void +.Fn wapbl_junlock_assert "struct wapbl *wl" +.Sh DESCRIPTION +.Nm , +or +.Em write-ahead physical block logging , +is an abstraction for file systems to write physical blocks in the +.Xr buffercache 9 +to a bounded-size log first before their real destinations on disk. +The name means: +.Bl -tag -width "physical block" -offset abcd +.It logging +batches of writes are issued atomically via a log +.It physical block +only physical blocks, not logical file system operations, are stored in +the log +.It write-ahead +before writing a block to disk, its new content, rather than its old +content for roll-back, is recorded in the log +.El +.Pp +When a file system using +.Nm +issues writes (as in +.Xr bwrite 9 +or +.Xr bdwrite 9 ) , +they are grouped in batches called +.Em transactions +in memory, which are serialized to be consistent with program order +before +.Nm +submits them to disk atomically. +.Pp +Thus, within a transaction, after one write, another write need not +wait for disk I/O, and if the system is interrupted, e.g. by a crash or +by power failure, either both writes will appear on disk, or neither +will. +.Pp +When a transaction is full, it is written to a circular buffer on +disk called the +.Em log . +When the transaction has been written to disk, every write in the +transaction is submitted to disk asynchronously. +Finally, the file system may issue new writes via +.Nm +once enough writes submitted to disk have completed. +.Pp +After interruption, such as a crash or power failure, some writes +issued by the file system may not have completed. +However, the log is written consistently with program order and before +file system writes are submitted to disk. +Hence a consistent program-order view of the file system can be +attained by resubmitting the writes that were successfully stored in +the log using +.Xr wapbl_replay 9 . +This may not be the same state just before interruption \(em writes in +transactions that did not reach the disk will be excluded. +.Pp +For a file system to use +.Nm , +its +.Xr VFS_MOUNT 9 +method should first replay any journal on disk using +.Xr wapbl_replay 9 , +and then, if the mount is read/write, initialize +.Nm +for the mount by calling +.Fn wapbl_start . +The +.Xr VFS_UNMOUNT 9 +method should call +.Fn wapbl_stop . +.Pp +Before issuing any +.Xr buffercache 9 +writes, the file system must acquire a shared lock on the current +.Nm +transaction with +.Fn wapbl_begin , +which may sleep until there is room in the transaction for new writes. +After issuing the writes, the file system must release its shared lock +on the transaction with +.Fn wapbl_end . +Either all writes issued between +.Fn wapbl_begin +and +.Fn wapbl_end +will complete, or none of them will. +.Pp +File systems may also witness an +.Em exclusive +lock on the current transaction when +.Nm +is flushing the transaction to disk, or aborting a flush, and invokes a +file system's callback. +File systems can assert that the transaction is locked with +.Fn wapbl_jlock_assert , +or not +.Em exclusively +locked, with +.Fn wapbl_junlock_assert . +.Pp +If a file system requires multiple transactions to initialize an +inode, and needs to destroy partially initialized inodes during replay, +it can register them by +.Vt ino_t +inode number before initialization with +.Fn wapbl_register_inode +and unregister them with +.Fn wapbl_unregister_inode +once initialization is complete. +.Nm +does not actually concern itself whether the objects identified by +.Vt ino_t +values are +.Sq inodes +or +.Sq quaggas +or anything else \(em file systems may use this to list any objects +keyed by +.Vt ino_t +value in the log. +.Pp +When a file system frees resources on disk and issues writes to reflect +the fact, it cannot then reuse the resources until the writes have +reached the disk. +However, as far as the +.Xr buffercache 9 +is concerned, as soon as the file system issues the writes, they will +appear to have been written. +So the file system must not attempt to reuse the resource until the +current +.Nm +transaction has been flushed to disk. +.Pp +The file system can defer freeing a resource by calling +.Fn wapbl_register_deallocation +to record the disk address of the resource and length in bytes of the +resource. +Then, when +.Nm +next flushes the transaction to disk, it will pass an array of the disk +addresses and lengths in bytes to a file-system-supplied callback. +(Again, +.Nm +does not care whether the +.Sq disk address +or +.Sq length in bytes +is actually that; it will pass along +.Vt daddr_t +and +.Vt int +values.) +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn wapbl_start wlp mp devvp off count blksize wr flushfn flushabortfn +Start using +.Nm +for the file system mounted at +.Fa mp , +storing a log of +.Fa count +disk sectors at disk address +.Fa off +on the block device +.Fa devvp +writing blocks in units of +.Fa blksize +bytes. +On success, stores an opaque +.Vt "struct wapbl *" +cookie in +.Li * Ns Fa wlp +for use with the other +.Nm +routines and returns zero. +On failure, returns an error number. +.Pp +If the file system had replayed the log with +.Xr wapbl_replay 9 , +then +.Fa wr +must be the +.Vt "struct wapbl_replay *" +cookie used to replay it, and +.Fn wapbl_start +will register any inodes that were in the log as if with +.Fn wapbl_register_inode ; +otherwise +.Fa wr +must be +.Dv NULL . +.Pp +.Fa flushfn +is a callback that +.Nm +will invoke as +.Fa flushfn ( Fa mp , Fa deallocblks , Fa dealloclens , Fa dealloccnt ) +just before it flushes a transaction to disk, with the an exclusive +lock held on the transaction, where +.Fa mp +is the mount point passed to +.Fn wapbl_start , +.Fa deallocblks +is an array of +.Fa dealloccnt +disk addresses, and +.Fa dealloclens +is an array of +.Fa dealloccnt +lengths, corresponding to the addresses and lengths the file system +passed to +.Fn wapbl_register_deallocation . +If flushing the transaction to disk fails, +.Nm +will call +.Fa flushabortfn +with the same arguments to undo any effects that +.Fa flushfn +had. +.It Fn wapbl_stop wl force +Flush the current transaction to disk and stop using +.Nm . +If flushing the transaction fails and +.Fa force +is zero, +return error. +If flushing the transaction fails and +.Fa force +is nonzero, discard the transaction, permanently losing any writes in +it. +If flushing the transaction is successful or if +.Fa force +is nonzero, +free memory associated with +.Fa wl +and return zero. +.It Fn wapbl_begin wl file line +Wait for space in the current transaction for new writes, flushing it +if necessary, and acquire a shared lock on it. +.Pp +The lock is not exclusive: other threads may acquire shared locks on +the transaction too. +The lock is not recursive: a thread may not acquire it again without +calling +.Fa wapbl_end +first. +.Pp +May sleep. +.Pp +.Fa file +and +.Fa line +are the file name and line number of the caller for debugging +purposes. +.It Fn wapbl_end wl +Release a shared lock on the transaction acquired with +.Fn wapbl_begin . +.It Fn wapbl_flush wl wait +Flush the current transaction to disk. +If +.Fa wait +is nonzero, wait for all writes in the current transaction to +complete. +.Pp +The current transaction must not be locked. +.It Fn wapbl_discard wl +Discard the current transaction, permanently losing any writes in it. +.Pp +The current transaction must not be locked. +.It Fn wapbl_add_buf wl bp +Add the buffer +.Fa bp +to the current transaction, which must be locked, because someone has +asked to write it. +.Pp +This is meant to be called from within +.Xr buffercache 9 , +not by file systems directly. +.It Fn wapbl_remove_buf wl bp +Remove the buffer +.Fa bp , +which must have been added using +.Fa wapbl_add_buf , +from the current transaction, which must be locked, because it has been +invalidated (or XXX ???). +.Pp +This is meant to be called from within +.Xr buffercache 9 , +not by file systems directly. +.It Fn wapbl_resize_buf wl bp oldsz oldcnt +Note that the buffer +.Fa bp , +which must have been added using +.Fa wapbl_add_buf , +has changed size, where +.Fa oldsz +is the previous allocated size in bytes and +.Fa oldcnt +is the previous number of valid bytes in +.Fa bp . +.Pp +This is meant to be called from within +.Xr buffercache 9 , +not by file systems directly. +.It Fn wapbl_register_inode wl ino mode +Register +.Fa ino +with the mode +.Fa mode +as commencing initialization. +.It Fn wapbl_unregister_inode wl ino mode +Unregister +.Fa ino , +which must have previously been registered with +.Fa wapbl_register_inode +using the same +.Fa mode , +now that its initialization has completed. +.It Fn wapbl_register_deallocation wl blk len +Register +.Fa len +bytes at the disk address +.Fa blk +as ready for deallocation, so that they will be passed to the +.Fa flushfn +that was given to +.Fn wapbl_start . +.It Fn wapbl_jlock_assert wl +Assert that the current transaction is locked. +.Pp +Note that it might not be locked by the current thread: this assertion +passes if +.Em any +thread has it locked. +.It Fn wapbl_junlock_assert wl +Assert that the current transaction is not exclusively locked by the +current thread. +.Pp +Users of +.Nm +observe exclusive locks only in the +.Fa flushfn +and +.Fa flushabortfn +callbacks to +.Fn wapbl_start . +Outside of such contexts, the transaction is never exclusively locked, +even between +.Fn wapbl_begin +and +.Fn wapbl_end . +.Pp +There is no way to assert that the current transaction is not locked at +all \(em i.e., that the caller may acquire a shared lock on the +transaction with +.Fn wapbl_begin +without danger of deadlock. +.El +.Sh CODE REFERENCES +The +.Nm +subsystem is implemented in +.Pa sys/kern/vfs_wapbl.c , +with hooks in +.Pa sys/kern/vfs_bio.c . +.Sh SEE ALSO +.Xr buffercache 9 , +.Xr vfsops 9 , +.Xr wapbl_replay 9 +.Sh BUGS +.Nm +works only for file system metadata managed via the +.Xr buffercache 9 , +and provides no way to log writes via the page cache, as in +.Xr VOP_GETPAGES 9 , +.Xr VOP_PUTPAGES 9 , +and +.Xr ubc_uiomove 9 , +which is normally used for file data. +.Pp +Not only is +.Nm +unable to log writes via the page cache, it is also unable to defer +.Xr buffercache 9 +writes until cached pages have been written. +This manifests as the well-known garbage-data-appended-after-crash bug +in FFS: when appending to a file, the pages containing new data may not +reach the disk before the inode update reporting its new size. +After a crash, the inode update will be on disk, but the new data will +not be \(em instead, whatever garbage data in the free space will +appear to have been appended to the file. +.Nm +exacerbates the problem by increasing the throughput of metadata +writes, because it can issue many metadata writes asynchronously that +FFS without +.Nm +would need to issue synchronously in order for +.Xr fsck 8 +to work. +.Pp +The criteria for when the transaction must be flushed to disk before +.Fn wapbl_begin +returns are heuristic, i.e. wrong. +There is no way for a file system to communicate to +.Fn wapbl_begin +how many buffers, inodes, and deallocations it will issue via +.Nm +in the transaction. +.Pp +.Nm +mainly supports write-ahead, and has only limited support for rolling +back operations, in the form of +.Fn wapbl_register_inode +and +.Fn wapbl_unregister_inode . +Consequently, for example, large writes appending to a file, which +requires multiple disk block allocations and an inode update, must +occur in a single transaction \(em there is no way to roll back the +disk block allocations if the write fails in the middle, e.g. because +of a fault in the middle of the user buffer. +.Pp +.Fn wapbl_jlock_assert +does not guarantee that the current thread has the current transaction +locked. +.Fn wapbl_junlock_assert +does not guarantee that the current thread does not have the current +transaction locked at all. +.Pp +There is only one +.Nm +transaction for each file system at any given time, and only one +.Nm +log on disk. +Consequently, all writes are serialized. +Extending +.Nm +to support multiple logs per file system, partitioned according to an +appropriate scheme, is left as an exercise for the reader. +.Pp +There is no reason for +.Nm +to require its own hooks in +.Xr buffercache 9 . +.Pp +The on-disk format used by +.Nm +is undocumented. diff --git a/static/netbsd/man9/wdc.9 b/static/netbsd/man9/wdc.9 new file mode 100644 index 00000000..6884a664 --- /dev/null +++ b/static/netbsd/man9/wdc.9 @@ -0,0 +1,412 @@ +.\" $NetBSD: wdc.9,v 1.19 2015/04/28 09:48:31 prlw1 Exp $ +.\" +.\" Copyright (c) 1998 Manuel Bouyer. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.Dd April 18, 2010 +.Dt WDC 9 +.Os +.Sh NAME +.Nm wdc +.Nd machine-independent IDE/ATAPI driver +.Sh SYNOPSIS +.In dev/ata/atavar.h +.In sys/dev/ic/wdcvar.h +.Ft int +.Fn wdcprobe "struct channel_softc * chp" +.Ft void +.Fn wdcattach "struct channel_softc * chp" +.Sh DESCRIPTION +The +.Nm +driver provides the machine independent core functions for driving IDE +devices. +IDE devices-specific drivers +.Po +.Xr wd 4 +or +.Xr atapibus 4 +.Pc +will use services provided by +.Nm . +.Pp +The machine-dependent bus front-end provides information to +.Nm +with the +.Va wdc_softc +and +.Va channel_softc +structures. +The first one defines global controller properties, and the second contains +per-channel information. +.Nm +returns information about the attached devices in the +.Va ata_drive_datas +structure. +.Bd -literal +struct wdc_softc { /* Per controller state */ + struct device sc_dev; + int cap; +#define WDC_CAPABILITY_DATA16 0x0001 +#define WDC_CAPABILITY_DATA32 0x0002 +#define WDC_CAPABILITY_MODE 0x0004 +#define WDC_CAPABILITY_DMA 0x0008 +#define WDC_CAPABILITY_UDMA 0x0010 +#define WDC_CAPABILITY_HWLOCK 0x0020 +#define WDC_CAPABILITY_ATA_NOSTREAM 0x0040 +#define WDC_CAPABILITY_ATAPI_NOSTREAM 0x0080 +#define WDC_CAPABILITY_NO_EXTRA_RESETS 0x0100 +#define WDC_CAPABILITY_PREATA 0x0200 +#define WDC_CAPABILITY_IRQACK 0x0400 +#define WDC_CAPABILITY_SINGLE_DRIVE 0x0800 +#define WDC_CAPABILITY_NOIRQ 0x1000 +#define WDC_CAPABILITY_SELECT 0x2000 + uint8_t pio_mode; + uint8_t dma_mode; + int nchannels; + struct channel_softc *channels; + + void *dma_arg; + int (*dma_init)(void *, int, int, void *, size_t, int); + void (*dma_start)(void *, int, int, int); + int (*dma_finish)(void *, int, int, int); +#define WDC_DMA_READ 0x01 +#define WDC_DMA_POLL 0x02 + + int (*claim_hw)(void *, int); + void (*free_hw)(void *); +}; + +struct channel_softc { /* Per channel data */ + int channel; + struct wdc_softc *wdc; + bus_space_tag_t cmd_iot; + bus_space_handle_t cmd_ioh; + bus_space_tag_t ctl_iot; + bus_space_handle_t ctl_ioh; + bus_space_tag_t data32iot; + bus_space_handle_t data32ioh; + int ch_flags; +#define WDCF_ACTIVE 0x01 +#define WDCF_IRQ_WAIT 0x10 + uint8_t ch_status; + uint8_t ch_error; + struct ata_drive_datas ch_drive[2]; + struct channel_queue *ch_queue; +}; + +struct ata_drive_datas { + uint8_t drive; + uint8_t drive_flags; +#define DRIVE_ATA 0x01 +#define DRIVE_ATAPI 0x02 +#define DRIVE (DRIVE_ATA|DRIVE_ATAPI) +#define DRIVE_CAP32 0x04 +#define DRIVE_DMA 0x08 +#define DRIVE_UDMA 0x10 +#define DRIVE_MODE 0x20 + uint8_t PIO_mode; + uint8_t DMA_mode; + uint8_t UDMA_mode; + uint8_t state; + + struct device *drv_softc; + void* chnl_softc; +}; +.Ed +.Pp +The bus front-end needs to fill in the following elements of +.Va wdc_softc : +.Bl -tag -compact -width "dma_finish" -offset "xxxx" +.It cap +supports one or more of the WDC_CAPABILITY flags +.It nchannels +number of channels supported by this controller +.It channels +array of +.Va struct channel_softc +of size +.Va nchannels +properly initialised +.El +The following elements are optional: +.Bl -tag -compact -width "dma_finish" -offset "xxxx" +.It pio_mode +.It dma_mode +.It dma_arg +.It dma_init +.It dma_start +.It dma_finish +.It claim_hw +.It free_hw +.El +.Pp +The +.Dv WDC_CAPABILITY_DATA16 +and +.Dv WDC_CAPABILITY_DATA32 +flags informs +.Nm +whether the controller supports 16- or 32-bit I/O accesses on the data port. +If both are set, a test will be done for each drive using the ATA or +ATAPI IDENTIFY command, to automatically select the working mode. +.Pp +The +.Dv WDC_CAPABILITY_DMA +and +.Dv WDC_CAPABILITY_UDMA +flags are set for controllers supporting the DMA and Ultra-DMA modes. +The bus front-end needs to provide the +.Fn dma_init , +.Fn dma_start +and +.Fn dma_finish +functions. +.Fn dma_init +is called just before issuing a DMA command to the IDE device. +The arguments are, respectively: +.Va dma_arg , +the channel number, the drive number on this channel, +the virtual address of the DMA buffer, the size of the transfer, and the +.Dv WDC_DMA +flags. +.Fn dma_start +is called just after issuing a DMA command to the IDE device. +The arguments are, respectively: +.Va dma_arg , +the channel number, the drive number on this channel, and the +.Dv WDC_DMA +flags. +.Fn dma_finish +is called once the transfer is complete. +The arguments are, respectively: +.Va dma_arg , +the channel number, the drive number on this channel, and the +.Dv WDC_DMA +flags. +.Dv WDC_DMA_READ +indicates the direction of the data transfer, and +.Dv WDC_DMA_POLL +indicates if the transfer will use (or used) interrupts. +.Pp +The +.Dv WDC_CAPABILITY_MODE +flag means that the bus front-end can program the PIO and DMA modes, so +.Nm +needs to provide back the supported modes for each drive, and set the drives +modes. +The +.Va pio_mode +and +.Va dma_mode +needs to be set to the highest PIO and DMA mode supported. +If +.Dv WDC_CAPABILITY_UDMA +is set, then +.Va dma_mode +must be set to the highest Ultra-DMA mode supported. +If +.Dv WDC_CAPABILITY_MODE +is not set, +.Nm +will not attempt to change the current drive's settings, assuming the host's +firmware has done it right. +.Pp +The +.Dv WDC_CAPABILITY_HWLOCK +flag is set for controllers needing hardware looking before accessing the +I/O ports. +If this flag is set, the bus front-end needs to provide the +.Fn claim_hw +and +.Fn free_hw +functions. +.Fn claim_hw +will be called when the driver wants to access the controller ports. +The second parameter is set to 1 when it is possible to sleep waiting +for the lock, 0 otherwise. +It should return 1 when access has been granted, 0 otherwise. +When access has not been granted and sleep is not allowed, the bus +front-end shall call +.Fn wdcrestart +with the first argument passed to +.Fn claim_hw +as argument. +This arguments will also be the one passed to +.Fn free_hw . +This function is called once the transfer is complete, so that the lock can +be released. +.Pp +Accesses to the data port are done by using the bus_space stream functions, +unless the +.Dv WDC_CAPABILITY_ATA_NOSTREAM +or +.Dv WDC_CAPABILITY_ATAPI_NOSTREAM +flags are set. +This should not be used, unless the data bus is not wired properly (which +seems common on big-endian systems), and byte-order needs to be preserved +for compatibility with the host's firmware. +Also note that the IDE bus is a little-endian bus, so the bus_space +functions used for the bus_space tag passed in the +.Va channel_softc +have to do the appropriate byte-swapping for big-endian systems. +.Pp +.Dv WDC_CAPABILITY_NO_EXTRA_RESETS +avoid the controller reset at the end of the disks probe. +This reset is needed for some controllers, but causes problems with some +others. +.Pp +.Dv WDC_CAPABILITY_NOIRQ +tells the driver that this controller doesn't have its interrupt lines +wired up usefully, so it should always use polled transfers. +.Pp +The bus front-end needs to fill in the following +elements of +.Va channel_softc : +.Bl -tag -compact -width "dma_finish" -offset "xxxx" +.It channel +The channel number on the controller +.It wdc +A pointer to the controller's wdc_softc +.It cmd_iot, cmd_ioh +Bus-space tag and handle for access to the command block registers (which +includes the 16-bit data port) +.It ctl_iot, ctl_ioh +Bus-space tag and handle for access to the control block registers +.It ch_queue +A pointer to a +.Va struct channel_queue . +This will hold the queues of outstanding commands for this controller. +.El +The following elements are optional: +.Bl -tag -compact -width "dma_finish" -offset "xxxx" +.It data32iot, data32ioh +Bus-space tag and handle for 32-bit data accesses. +Only needed if +.Dv WDC_CAPABILITY_DATA32 +is set in the controller's +.Va wdc_softc . +.El +.Pp +.Va ch_queue +can point to a common +.Va struct channel_queue +if the controller doesn't support concurrent access to its different channels. +If all channels are independent, it is recommended that each channel has +its own +.Va ch_queue +(for better performance). +.Pp +The bus-specific front-end can use the +.Fn wdcprobe +function, with a properly initialised +.Va struct channel_softc +as argument ( +.Va wdc +can be set to NULL. +This allows +.Fn wdcprobe +to be easily used in bus front-end probe functions). +This function will return an integer where bit 0 will be set if the master +device has been found, and 1 if the slave device has been found. +.Pp +The bus-specific attach function has to call +.Fn wdcattach +for each channel, with a pointer to a properly initialised +.Va channel softc +as argument. +This will probe devices attached to the IDE channel and attach them. +Once this function returns, the +.Va ch_drive +array of the +.Va channel_softc +will contain the drive's capabilities. +This can be used to properly initialise the controller's mode, or disable a +channel without drives. +.Pp +The elements of interest in +.Va ata_drive_datas +for a bus front-end are: +.Bl -tag -compact -width "dma_finish" -offset "xxxx" +.It drive +The drive number +.It drive_flags +Flags indicating the drive capabilities. +A null +.Va drive_flags +indicate either that no drive is here, or that no driver was +found for this device. +.It PIO_mode, DMA_mode, UDMA_mode +the highest supported modes for this drive compatible with the controller's +capabilities. +Needs to be reset to the mode to use by the drive, if known. +.It drv_softc +A pointer to the drive's softc. +Can be used to print the drive's name. +.El +.Pp +.Va drive_flags +handles the following flags: +.Bl -tag -compact -width "dma_finish" -offset "xxxx" +.It DRIVE_ATA, DRIVE_ATAPI +Gives the drive type, if any. +The shortcut DRIVE can be used to just test the presence/absence of a drive. +.It DRIVE_CAP32 +This drive works with 32-bit data I/O. +.It DRIVE_DMA +This drive supports DMA. +.It DRIVE_UDMA +This drive supports Ultra-DMA. +.It DRIVE_MODE +This drive properly reported its PIO and DMA mode. +.El +.Pp +Once the controller has been initialised, it has to reset the +.Dv DRIVE_DMA +and +.Dv DRIVE_UDMA , +as well as the values of +.Va PIO_mode , +.Va DMA_mode +and +.Va UDMA_mode +if the modes to be used are not highest ones supported by the drive. +.Sh CODE REFERENCES +The wdc core functions are implemented in +.Pa sys/dev/ic/wdc.c . +Low-level ATA and ATAPI support is provided by +.Pa sys/dev/ata_wdc.c +and +.Pa sys/dev/scsipi/atapi_wdc.c +respectively. +.Pp +An example of a simple bus front-end can be found in +.Pa sys/dev/isapnp/wdc_isapnp.c . +A more complex one, with multiple channels and bus-master DMA support is +.Pa sys/dev/pci/pciide.c . +.Pa sys/arch/atari/dev/wdc_mb.c +makes use of hardware locking, and also provides an example of bus-front +end for a big-endian system, which needs byte-swapping bus_space functions. +.Sh SEE ALSO +.Xr wdc 4 , +.Xr bus_space 9 diff --git a/static/netbsd/man9/workqueue.9 b/static/netbsd/man9/workqueue.9 new file mode 100644 index 00000000..39fbe7c5 --- /dev/null +++ b/static/netbsd/man9/workqueue.9 @@ -0,0 +1,163 @@ +.\" $NetBSD: workqueue.9,v 1.15 2020/09/08 17:02:18 riastradh Exp $ +.\" +.\" Copyright (c)2005 YAMAMOTO Takashi, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ------------------------------------------------------------ +.Dd December 28, 2017 +.Dt WORKQUEUE 9 +.Os +.\" ------------------------------------------------------------ +.Sh NAME +.Nm workqueue +.Nd simple do-it-in-thread-context framework +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In sys/workqueue.h +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn workqueue_create \ +"struct workqueue **wqp" "const char *name" \ +"void (*func)(struct work *, void *)" "void *arg" \ +"pri_t prio" "int ipl" "int flags" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn workqueue_enqueue \ +"struct workqueue *wq" "struct work *wk" "struct cpu_info *ci" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn workqueue_wait \ +"struct workqueue *wq" "struct work *wk" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn workqueue_destroy \ +"struct workqueue *wq" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +The +.Nm +utility routines are provided to defer work which is needed to be +processed in a thread context. +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn workqueue_create +creates a workqueue. +It takes the following arguments: +.Bl -tag -width flags +.It Fa wqp +Specify where to store the created workqueue. +.It Fa name +The name of the workqueue. +.It Fa func +The function to be called for each +.Fa work . +.It Fa arg +An argument to be passed as a second argument of +.Fa func . +.It Fa prio +The priority level for the worker threads. +.It Fa ipl +The highest IPL at which this workqueue is used. +.It Fa flags +The value of 0 indicates a standard create operation, however the following +flags may be bitwise ORed together: +.Bl -tag -width WQ_MPSAFE +.It Dv WQ_FPU +Specifies that the kthread must be allowed to use any machine-dependent +per-CPU floating-point units or SIMD vector units, as in +.Xr kthread_fpu_enter 9 / Xr kthread_fpu_exit 9 , +when it executes the worker function. +.It Dv WQ_MPSAFE +Specifies that the workqueue is multiprocessor safe and does its own locking; +otherwise the kernel lock will be held while processing work. +.It Dv WQ_PERCPU +Specifies that the workqueue should have a separate queue for each CPU, +thus the work could be enqueued on concrete CPUs. +.El +.El +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn workqueue_enqueue +enqueues the work +.Fa wk +into the workqueue +.Fa wq . +.Pp +If the +.Dv WQ_PERCPU +flag was set on workqueue creation, the +.Fa ci +argument may be used to specify the CPU on which the work should +be enqueued. +Also it may be +.Dv NULL , +then work will be enqueued on the current CPU. +If +.Dv WQ_PERCPU +flag was not set, +.Fa ci +must be +.Dv NULL . +.Pp +The enqueued work will be processed in a thread context. +A work must not be enqueued again until the callback is called by +the +.Nm +framework. +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn workqueue_wait +waits for a specified work +.Fa wk +on the workqueue +.Fa wq +to finish. +The caller must ensure that +.Fa wk +will not be enqueued to the workqueue again until after +.Fn workqueue_wait +returns. +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn workqueue_destroy +destroys a workqueue and frees associated resources. +The caller should ensure that the workqueue has no work enqueued beforehand. +.\" ------------------------------------------------------------ +.Sh RETURN VALUES +.Fn workqueue_create +returns 0 on success. +Otherwise, it returns an +.Xr errno 2 . +.\" ------------------------------------------------------------ +.Sh CODE REFERENCES +The +.Nm +subsystem is implemented within the file +.Pa sys/kern/subr_workqueue.c . +.\" ------------------------------------------------------------ +.Sh SEE ALSO +.Xr callout 9 , +.Xr condvar 9 , +.Xr kthread 9 , +.Xr softint 9 diff --git a/static/netbsd/man9/wsbell.9 b/static/netbsd/man9/wsbell.9 new file mode 100644 index 00000000..eda9d0b4 --- /dev/null +++ b/static/netbsd/man9/wsbell.9 @@ -0,0 +1,112 @@ +.\" $NetBSD: wsbell.9,v 1.4 2018/02/11 14:17:17 wiz Exp $ +.\" +.\" Copyright (c) 2017 Nathanial Sloss <nathanialsloss@yahoo.com.au> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 30, 2017 +.Dt WSBELL 9 +.Os +.Sh NAME +.Nm wsbell , +.Nm wsbelldevprint +.Nd wscons system bell support +.Sh SYNOPSIS +.In dev/wscons/wsconsio.h +.In dev/wscons/wsbellvar.h +.Ft int +.Fn wsbelldevprint "void *aux" "const char *pnp" +.Sh DESCRIPTION +The +.Nm +module is a component of the +.Xr wscons 9 +framework, providing keyboard-independent bell support. +All of the support is provided by the +.Xr wsbell 4 +device driver, which must be a child of the hardware device driver. +The only hardware device drivers that can provide a +.Nm +facility are +.Xr speaker 4 +devices. +.Sh DATA TYPES +Speaker drivers providing support for wscons bell devices will make use +of the following data types: +.Bl -tag -width compact +.It Fa struct wsbelldev_attach_args +A structure used to attach the +.Xr wsbell 4 +child device. +It has the following members: +.Bd -literal + void *accesscookie; +.Ed +.El +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn wsbelldevprint "aux" "pnp" +The default wsbell printing routine used by +.Fn config_found . +(see +.Xr autoconf 9 ) . +.El +.Sh AUTOCONFIGURATION +Speaker drivers which want to use the wsbell module must be a +parent to the +.Xr wsbell 4 +device and provide an attachment interface. +To attach the +.Xr wsbell 4 +device, the speaker driver must allocate and populate a +.Fa wsbelldev_attach_args +structure with a pointer to the parent's device structure as an access cookie +and call +.Fn config_found +to perform the attach (see +.Xr autoconf 9 ) . +.Sh OPERATION +When a bell event is received on a +.Xr wsdisplay 4 +device the system bell is sounded. +.Sh CODE REFERENCES +The wscons subsystem is implemented within the directory +.Pa sys/dev/wscons . +The +.Nm +module itself is implement within the file +.Pa sys/dev/wscons/wsbell.c . +.Xr ioctl 2 +operations are listed in +.Pa sys/dev/wscons/wsconsio.h . +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr wsbell 4 , +.Xr wscons 4 , +.Xr wskbd 4 , +.Xr autoconf 9 , +.Xr driver 9 , +.Xr intro 9 , +.Xr wscons 9 , +.Xr wsdisplay 9 , +.Xr wskbd 9 diff --git a/static/netbsd/man9/wscons.9 b/static/netbsd/man9/wscons.9 new file mode 100644 index 00000000..f0d977bc --- /dev/null +++ b/static/netbsd/man9/wscons.9 @@ -0,0 +1,75 @@ +.\" $NetBSD: wscons.9,v 1.8 2010/12/02 12:54:13 wiz Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 7, 2001 +.Dt WSCONS 9 +.Os +.Sh NAME +.Nm wscons +.Nd machine-independent console support +.Sh DESCRIPTION +The +.Nm +driver provides a machine-independent framework for workstation +consoles. +It consists of several cooperating modules: +.Bl -bullet +.It +display adapters (see +.Xr wsdisplay 9 ) +.It +keyboards (see +.Xr wskbd 9 ) +.It +pointers and mice (see +.Xr wsmouse 9 ) +.It +input event multiplexor +.It +font handling (see +.Xr wsfont 9 ) +.It +terminal emulation (see +.Xr wsdisplay 9 ) +.El +.Pp +The wscons framework replaces the old rcons workstation framework and +the various machine-dependent console implementations. +.Sh CODE REFERENCES +The wscons subsystem is implemented within the directory +.Pa sys/dev/wscons . +.Sh SEE ALSO +.Xr wscons 4 , +.Xr cons 9 , +.Xr driver 9 , +.Xr intro 9 , +.Xr wsdisplay 9 , +.Xr wsfont 9 , +.Xr wskbd 9 , +.Xr wsmouse 9 diff --git a/static/netbsd/man9/wsdisplay.9 b/static/netbsd/man9/wsdisplay.9 new file mode 100644 index 00000000..4dece625 --- /dev/null +++ b/static/netbsd/man9/wsdisplay.9 @@ -0,0 +1,422 @@ +.\" $NetBSD: wsdisplay.9,v 1.23 2010/12/02 12:54:13 wiz Exp $ +.\" +.\" Copyright (c) 2001, 2004 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 15, 2006 +.Dt WSDISPLAY 9 +.Os +.Sh NAME +.Nm wsdisplay , +.Nm wsdisplay_switchtoconsole , +.Nm wsdisplay_cnattach , +.Nm wsdisplaydevprint , +.Nm wsemuldisplaydevprint +.Nd wscons display support +.Sh SYNOPSIS +.In dev/wscons/wsconsio.h +.In dev/wscons/wsdisplayvar.h +.In dev/wscons/wsemulvar.h +.In dev/wscons/wsemul_vt100var.h +.Ft void +.Fn wsdisplay_switchtoconsole "" +.Ft void +.Fn wsdisplay_cnattach "const struct wsscreen_descr *type" "void *cookie" \ +"int ccol" "int crow" "long defattr" +.Ft void +.Fn wsemul_xxx_cnattach "const struct wsscreen_descr *type" "void *cookie" \ +"int ccol" "int crow" "long defattr" +.Ft int +.Fn wsdisplaydevprint "void *aux" "const char *pnp" +.Ft int +.Fn wsemuldisplaydevprint "void * aux" "const char *pnp" +.Sh DESCRIPTION +The +.Nm +module is a component of the +.Xr wscons 9 +framework to provide machine-independent display support. +Most of the support is provided by the +.Xr wsdisplay 4 +device driver, which must be a child of the hardware device driver. +.Pp +The wscons display interface is complicated by the fact that there are +two different interfaces. +The first interface corresponds to the simple bit-mapped display which +doesn't provide terminal-emulation and console facilities. +The second interface provides machine-independent terminal emulation +for displays that can support glass-tty terminal emulations. +These are character-oriented displays, with row and column numbers +starting at zero in the upper left hand corner of the screen. +Display drivers which cannot emulate terminals use the first interface. +In most cases, the low-level hardware driver can use the +.Xr rasops 9 +interface to provide enough support to allow glass-tty terminal +emulation. +If the display is not the console, terminal emulation does not make +sense and the display operates using the bit-mapped interface. +.Pp +The wscons framework allows concurrent displays to be active. +It also provides support for multiple screens for each display and +therefore allows a virtual terminal on each screen. +Multiple terminal emulations and fonts can be active at the same +time allowing different emulations and fonts for each screen. +.Pp +Font manipulation facilities for the terminal emulation interface are +available through the +.Xr wsfont 9 +module. +.Sh DATA TYPES +Display drivers providing support for wscons displays will make use +of the following data types: +.Bl -tag -width compact +.It Fa struct wsdisplay_accessops +A structure used to specify the display access functions invoked by +userland program which require direct device access, such as X11. +All displays must provide this structure and pass it to the +.Xr wsdisplay 4 +child device. +It has the following members: +.Bd -literal + int (*ioctl)(void *v, void *vs, u_long cmd, + void *data, int flag, struct lwp *l); + paddr_t (*mmap)(void *v, void *vs, off_t off, int prot); + int (*alloc_screen)(void *, + const struct wsscreen_descr *, void **, + int *, int *, long *); + void (*free_screen)(void *, void *); + int (*show_screen)(void *, void *, int, + void (*)(), void *); + int (*load_font)(void *, void *, + struct wsdisplay_font *); + void (*pollc)(void *, int); + void (*scroll)(void *, void *, int); +.Ed +.Pp +The +.Fa ioctl +member defines the function to be called to perform display-specific +ioctl calls. +The +.Fa mmap +member defines the function for mapping a part of the display device +into user address space. +The +.Fa alloc_screen +member defines a function for allocating a new screen which can be +used as a virtual terminal. +The +.Fa free_screen +member defines a function for de-allocating a screen. +The +.Fa show_screen +member defines a function for mapping a screen onto the physical +display. +This function is used for switching between screens. +The +.Fa load_font +member defines a function for loading a new font into the display. +The +.Fa pollc +member defines a function for polling the console. +The +.Fa scroll +member defines a function for scrolling the contents of the display. +.Pp +There is a +.Fa void * +cookie provided by the display driver associated with these +functions, which is passed to them when they are invoked. +.Pp +The +.Fa void *vs +cookie, passed to +.Fn ioctl +and +.Fn mmap , +points to the virtual screen on which these operations were executed. +.It Fa struct wsdisplaydev_attach_args +A structure used to attach the +.Xr wsdisplay 4 +child device for the simple bit-mapped interface. +It has the following members: +.Bd -literal + const struct wsdisplay_accessops *accessops; + void *accesscookie; +.Ed +If the full terminal-emulation interface is to be used, then +.Em struct wsemuldisplaydev_attach_args +should be used instead. +.It Fa struct wsemuldisplaydev_attach_args +A structure used to attach the +.Xr wsdisplay 4 +child device for the full terminal emulation interface. +It has the following members: +.Bd -literal + int console; + const struct wsscreen_list *scrdata; + const struct wsdisplay_accessops *accessops; + void *accesscookie; +.Ed +If the simple bit-mapped interface is to be used, then +.Em struct wsdisplaydev_attach_args +should be used instead. +.It Fa struct wsdisplay_emulops +A structure used to specify the display emulation functions. +All displays intending to provide terminal emulation must provide +this structure and pass it to the +.Xr wsdisplay 4 +child device. +It has the following members: +.Bd -literal + void (*cursor)(void *c, int on, int row, int col); + int (*mapchar)(void *, int, unsigned int *); + void (*putchar)(void *c, int row, int col, + u_int uc, long attr); + void (*copycols)(void *c, int row, int srccol, + int dstcol, int ncols); + void (*erasecols)(void *c, int row, int startcol, + int ncols, long); + void (*copyrows)(void *c, int srcrow, int dstrow, + int nrows); + void (*eraserows)(void *c, int row, int nrows, long); + int (*allocattr)(void *c, int fg, int bg, int flags, + long *); + void (*replaceattr)(void *c, long oldattr, + long newattr); +.Ed +.Pp +The +.Fa cursor +member defines a function for painting (or unpainting, depending on the +.Va on +parameter) the cursor at the specified position. +The +.Fa mapchar +member defines a function for changing the character mapped at a given +position in the character table. +The +.Fa putchar +member defines a function for writing a character on the screen, given +its position and attribute. +The +.Fa copycols +member defines a function for copying a set of columns within the same +line. +The +.Fa erasecols +member defines a function for clearing a set of columns in a line, +filling the space with the given attribute. +The +.Fa copyrows +member defines a function for copying a set of complete rows. +The +.Fa eraserows +member defines a function for clearing a set of complete rows, +filling the space with the given attribute. +The +.Fa allocattr +member defines a function for converting an attribute specification +given by its foreground color, background color and flags, to the +internal representation used by the underlying graphics driver. +The +.Fa replaceattr +member defines a function for replacing an attribute by another one +across the whole visible part of the screen; this function is optional. +.Pp +There is a +.Fa void * +cookie provided by the display driver associated with these +functions, which is passed to them when they are invoked. +.It Fa struct wsscreen_descr +A structure passed to wscons by the display driver to describe a +screen. +All displays which can operate as a console must provide this structure +and pass it to the +.Xr wsdisplay 4 +child device. +It contains the following members: +.Bd -literal + char *name; + int ncols, nrows; + const struct wsdisplay_emulops *textops; + int fontwidth, fontheight; + int capabilities; +.Ed +.Pp +The +.Em capabilities +member is a set of flags describing the screen capabilities. +It can contain the following flags: +.Pp +.Bl -tag -offset indent -width WSSCREEN_UNDERLINE -compact +.It WSSCREEN_WSCOLORS +minimal color capability +.It WSSCREEN_REVERSE +can display reversed +.It WSSCREEN_HILIT +can highlight (however) +.It WSSCREEN_BLINK +can blink +.It WSSCREEN_UNDERLINE +can underline +.El +.It Fa struct wsscreen_list +A structure passed to wscons by the display driver to tell about its +capabilities. +It contains the following members: +.Bd -literal + int nscreens; + const struct wsscreen_descr **screens; +.Ed +.It Fa struct wscons_syncops +A structure passed to wscons by the display driver describing the +interface for external screen switching/process synchronization. +This structure is optional and only required by displays operating +with terminal emulation and intending to support multiple screens. +It contains the following members: +.Bd -literal + int (*detach)(void *, int, void (*)(), void *); + int (*attach)(void *, int, void (*)(), void *); + int (*check)(void *); + void (*destroy)(void *); +.Ed +.El +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn wsdisplay_switchtoconsole "" +Switch the console display to its first screen. +.It Fn wsdisplay_cnattach "type" "cookie" "ccol" "crow" "defattr" +Attach this display as the console input by specifying the number of +columns +.Fa ccol +and number of rows +.Fa crows . +The argument +.Fa defattr +specifies the default attribute (color) for the console. +.It Fn wsemul_xxx_cnattach "type" "cookie" "ccol" "crow" "defattr" +Attach this display as the console with terminal emulation described +by the +.Em xxx +and specifying the number of columns +.Fa ccol +and number of rows +.Fa crows . +The argument +.Fa defattr +specifies the default attribute (color) for the console. +Different terminal emulations can be active at the same time on one display. +.It Fn wsdisplaydevprint "aux" "pnp" +The default wsdisplay printing routine used by +.Fn config_found . +(see +.Xr autoconf 9 ) . +.It Fn wsemuldisplaydevprint "aux" "pnp" +The default wsemul printing routine used by +.Fn config_found . +(see +.Xr autoconf 9 ) . +.El +.Sh AUTOCONFIGURATION +Display drivers which want to use the wsdisplay module must be a +parent to the +.Xr wsdisplay 4 +device and provide an attachment interface. +To attach the +.Xr wsdisplay 4 +device, the display driver must allocate and populate a +.Fa wsdisplaydev_attach_args +structure with the supported operations and callbacks and call +.Fn config_found +to perform the attach (see +.Xr autoconf 9 ) . +.Pp +Display drivers which want to use the wscons terminal emulation +module must be a parent to the +.Xr wsdisplay 4 +device and provide a +.Fa wsemuldisplaydev_attach_args +structure instead of the standard +.Fa wsdisplaydev_attach_args +to +.Fn config_found +to perform the attach. +If the display is not the console the attachment is the same +as wsdisplaydev_attach_args. +.Sh OPERATION +If the display belongs to the system console, it must describe the +default screen by invoking +.Fn wsdisplay_cnattach +at console attach time. +.Pp +All display manipulation is performed by the wscons interface by using +the callbacks defined in the +.Em wsdisplay_accessops +structure. +The +.Fn ioctl +function is called by the wscons interface to perform display-specific +ioctl operations (see +.Xr ioctl 2 ) . +The argument +.Fa cmd +to the +.Fn ioctl +function specifies the specific command to perform using the data +.Fa data . +Valid commands are listed in +.Pa sys/dev/wscons/wsconsio.h +and documented in +.Xr wsdisplay 4 . +Operations for terminal emulation are performed using the callbacks +defined in the +.Em wsdisplay_emulops +structure. +.Sh CODE REFERENCES +The wscons subsystem is implemented within the directory +.Pa sys/dev/wscons . +The +.Nm +module itself is implemented within the file +.Pa sys/dev/wscons/wsdisplay.c . +The terminal emulation support +is implemented within the files +.Pa sys/dev/wscons/wsemul_* . +.Xr ioctl 2 +operations are listed in +.Pa sys/dev/wscons/wsconsio.h . +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr wsdisplay 4 , +.Xr autoconf 9 , +.Xr driver 9 , +.Xr intro 9 , +.Xr rasops 9 , +.Xr wsfont 9 , +.Xr wskbd 9 , +.Xr wsmouse 9 diff --git a/static/netbsd/man9/wsfont.9 b/static/netbsd/man9/wsfont.9 new file mode 100644 index 00000000..e1795c68 --- /dev/null +++ b/static/netbsd/man9/wsfont.9 @@ -0,0 +1,247 @@ +.\" $NetBSD: wsfont.9,v 1.18 2012/01/13 23:09:51 wiz Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 13, 2012 +.Dt WSFONT 9 +.Os +.Sh NAME +.Nm wsfont , +.Nm wsfont_init , +.Nm wsfont_matches , +.Nm wsfont_find , +.Nm wsfont_add , +.Nm wsfont_remove , +.Nm wsfont_enum , +.Nm wsfont_lock , +.Nm wsfont_unlock , +.Nm wsfont_map_unichar +.Nd wscons font support +.Sh SYNOPSIS +.In dev/wscons/wsconsio.h +.In dev/wsfont/wsfont.h +.Ft void +.Fn wsfont_init "void" +.Ft int +.Fn wsfont_matches "struct wsdisplay_font *font" "const char *name" \ +"int width" "int height" "int stride" "int flags" +.Ft int +.Fn wsfont_find "const char *name" "int width" "int height" "int stride" \ +"int bitorder" "int byteorder" "int flags" +.Ft int +.Fn wsfont_add "struct wsdisplay_font *font" "int copy" +.Ft int +.Fn wsfont_remove "int cookie" +.Ft void +.Fn wsfont_enum "void (*callback)(const char *, int, int, int)" +.Ft int +.Fn wsfont_lock "int cookie" "struct wsdisplay_font **ptr" +.Ft int +.Fn wsfont_unlock "int cookie" +.Ft int +.Fn wsfont_map_unichar "struct wsdisplay_font *font" "int c" +.Sh DESCRIPTION +The +.Nm +module is a component of the +.Xr wscons 9 +framework to provide access to display fonts. +Fonts may be loaded dynamically into the kernel or included statically +in the kernel at compile time. +Display drivers which emulate a glass-tty console on a bit-mapped +display can add, remove and find fonts for use by device-dependent +blitter operations. +.Pp +The primary data type for manipulating fonts is the +.Em wsdisplay_font +structure in +.Pa dev/wscons/wsconsio.h : +.Bd -literal +struct wsdisplay_font { + const char *name; /* font name */ + int firstchar; + int numchars; /* size of font table */ + int encoding; /* font encoding */ + u_int fontwidth; /* character width */ + u_int fontheight; /* character height */ + u_int stride; + int bitorder; + int byteorder; + void *data; /* pointer to font table */ +}; +.Ed +.Pp +The maximum font table size is +.Em WSDISPLAY_MAXFONTSZ . +.Pp +The +.Nm +framework supports fonts with the following encodings: +.Bl -tag -width compact +.It Dv WSDISPLAY_FONTENC_ISO +ISO-encoded fonts. +.It Dv WSDISPLAY_FONTENC_IBM +IBM-encoded fonts commonly available for IBM CGA, EGA and VGA display +adapters. +.It Dv WSDISPLAY_FONTENC_PCVT +PCVT-encoding fonts distributed as part of the old PCVT terminal +emulation driver. +.It Dv WSDISPLAY_FONTENC_ISO7 +ISO-encoded Greek fonts. +.It Dv WSDISPLAY_FONTENC_ISO2 +ISO-encoded East European fonts. +.El +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn wsfont_init "void" +Initialise the font list with the built-in fonts. +.It Fn wsfont_matches "font" "name" "width" "height" "stride" +Matches the font +.Fa font +with the specifications +.Fa name , +.Fa width , +.Fa height , +.Fa stride +and +.Fa flags . +Return zero if not matched and non-zero if matched. +The +.Fa flags +parameter has the same meaning as in +.Fn wsfont_find . +.It Fn wsfont_find "name" "width" "height" "stride" "bitorder" "byteorder" "flags" +Find the font called +.Fa name +from the fonts loaded into the kernel. +The font aspect is specified by +.Fa width , +.Fa height , +and +.Fa stride . +If +.Fn wsfont_find +is called with any of the parameters as 0, it indicates that we don't +care about that aspect of the font. +If the font is found, a (nonnegative-valued) cookie is returned which +can be used with the other functions. +.Pp +The +.Fa bitorder +and +.Fa byteorder +arguments are the bit order and byte order required. +Valid values are: +.Bl -tag -width compact +.It Dv WSDISPLAY_FONTORDER_KNOWN +The font is in known ordered format and doesn't need converting. +.It Dv WSDISPLAY_FONTORDER_L2R +The font is ordered left to right. +.It Dv WSDISPLAY_FONTORDER_R2L +The font is ordered right to left. +.El +.Pp +The +.Fa flags +parameter determines what type of font can be returned. +Any combination of the following values is allowed: +.Bl -tag -width compact +.It Dv WSFONT_FIND_BITMAP +To search bitmap fonts, +.It Dv WSFONT_FIND_ALPHA +to search anti-aliased fonts. +.El +When more flexibility is required, +.Fn wsfont_enum +should be used. +.It Fn wsfont_add "font" "copy" +Add a font +.Fa font +to the font list. +If the +.Fa copy +argument is non-zero, then the font is physically copied, otherwise a +reference to the original font is made. +.It Fn wsfont_remove "cookie" +Remove the font specified by +.Fa cookie +from the font list. +The value of cookie was returned by +.Fn wsfont_add . +.It Fn wsfont_enum "callback" +Enumerate the list of fonts. +For each font in the font list, the +.Fa callback +function argument is called with the arguments specifying the font +name, width, height and stride. +.It Fn wsfont_lock "cookie" "ptr" +Lock access to the font specified by +.Fa cookie +so that it cannot be unloaded from the kernel while is being used. +If the bit or byte order of the font to be locked differs from what +has been requested with +.Fn wsfont_find +then the glyph data will be modified to match. +At this point it may be necessary for +.Fn wsfont_lock +to make a copy of the font data; this action is transparent to the caller. +A later call to +.Fn wsfont_unlock +will free resources used by temporary copies. +.Pp +The address of the wsdisplay_font pointer for the specified font is returned in +the +.Fa ptr +argument. +.Pp +.Fn wsfont_lock +returns zero on success, or an error code on failure. +.It Fn wsfont_unlock "cookie" +Unlock the font specified by +.Fa cookie . +Returns zero on success, or an error code on failure. +.It Fn wsfont_map_unichar "font" "c" +Remap the unicode character +.Fa c +to glyph for font +.Fa font . +Returns the glyph on success or \-1 on error. +.El +.Sh CODE REFERENCES +The wscons subsystem is implemented within the directory +.Pa sys/dev/wscons . +The wsfont subsystem itself is implemented within the file +.Pa sys/dev/wsfont/wsfont.c . +.Sh SEE ALSO +.Xr wsfont 4 , +.Xr wsfontload 8 , +.Xr autoconf 9 , +.Xr driver 9 , +.Xr intro 9 , +.Xr wscons 9 , +.Xr wsdisplay 9 diff --git a/static/netbsd/man9/wskbd.9 b/static/netbsd/man9/wskbd.9 new file mode 100644 index 00000000..9ec01319 --- /dev/null +++ b/static/netbsd/man9/wskbd.9 @@ -0,0 +1,346 @@ +.\" $NetBSD: wskbd.9,v 1.16 2025/04/06 22:49:19 rillig Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 6, 2025 +.Dt WSKBD 9 +.Os +.Sh NAME +.Nm wskbd , +.Nm wskbd_input , +.Nm wskbd_rawinput , +.Nm wskbd_cnattach , +.Nm wskbd_cndetach , +.Nm wskbddevprint +.Nd wscons keyboard support +.Sh SYNOPSIS +.In dev/wscons/wsconsio.h +.In dev/wscons/wskbdvar.h +.In dev/wscons/wsksymdef.h +.In dev/wscons/wsksymvar.h +.Ft void +.Fn wskbd_input "struct device *kbddev" "u_int type" "int value" +.Ft void +.Fn wskbd_rawinput "struct device *kbddev" "u_char *buf" "int len" +.Ft void +.Fn wskbd_cnattach "const struct wskbd_consops *consops" "void *conscookie" \ +"const struct wskbd_mapdata *mapdata" +.Ft void +.Fn wskbd_cndetach "void" +.Ft int +.Fn wskbddevprint "void *aux" "const char *pnp" +.Sh DESCRIPTION +The +.Nm +module is a component of the +.Xr wscons 9 +framework to provide machine-independent keyboard support. +Most of the support is provided by the +.Xr wskbd 4 +device driver, which must be a child of the hardware device driver. +.Sh DATA TYPES +Keyboard drivers providing support for wscons keyboards will make use +of the following data types: +.Bl -tag -width compact +.It Fa kbd_t +An opaque type describing keyboard properties. +.It Fa keysym_t +The wscons keyboard-independent symbolic representation of the keypress. +.It Fa struct wskbd_accessops +A structure used to specify the keyboard access functions. +All keyboards must provide this structure and pass it to the +.Xr wskbd 4 +child device. +It has the following members: +.Bd -literal + int (*enable)(void *, int); + void (*set_leds)(void *, int); + int (*ioctl)(void *v, u_long cmd, void *data, + int flag, struct lwp *l); +.Ed +.Pp +The +.Fa enable +member defines the function to be called to enable keypress passing to +wscons. +The +.Fa set_leds +member defined the function to be called to set the LEDs on the +keyboard. +The +.Fa ioctl +member defines the function to be called to perform keyboard-specific +ioctl calls. +.Pp +There is a +.Fa void * +cookie provided by the keyboard driver associated with these +functions, which is passed to them when they are invoked. +.It Fa struct wskbd_consops +A structure used to specify the keyboard console operations. +All keyboards which can operate as a console must provide this structure +and pass it to the +.Xr wskbd 4 +child device. +If the keyboard cannot be a console, it is not +necessary to specify this structure. +It has the following members: +.Bd -literal + void (*getc)(void *, u_int *, int *); + void (*pollc)(void *, int); + void (*bell)(void *, u_int, u_int, u_int); +.Ed +.Pp +There is a +.Fa void * +cookie provided by the keyboard driver associated with these +functions, which is passed to them when they are invoked. +.It Fa struct wscons_keydesc +A structure used to describe a keyboard mapping table to convert +keyboard-specific keycodes to wscons keysyms. +It has the +following members: +.Bd -literal + kbd_t name; /* name of this map */ + kbd_t base; /* map this one is based on */ + int map_size; /* size of map */ + const keysym_t *map; /* the map itself */ +.Ed +.It Fa struct wskbd_mapdata +A structure used to describe the keyboard layout and operation to +interpret the keyboard layout. +it contains the following members: +.Bd -literal + const struct wscons_keydesc *keydesc; + kbd_t layout; +.Ed +.It Fa struct wskbddev_attach_args +A structure used to attach the +.Xr wskbd 4 +child device. +It has the following members: +.Bd -literal + int console; + const struct wskbd_mapdata *keymap; + const struct wskbd_accessops *accessops; + void *accesscookie; +.Ed +.El +.Ss Keymaps +Keymaps are a dense stream of +.Fa keysym_t . +A declaration has the following fields: +.Pp +.Ar pos +.Op Ar cmd +.Ar normal +.Op Ar shift +.Op Ar altgr +.Op Ar shift-altgr +.Pp +The fields have the following meanings: +.Pp +.Bl -tag -offset indent -width SHIFT-ALTGR -compact +.It Ar pos +Always specified as +.Ns KC( Ns Ar pos ) +and starts the description of key +.Ar pos . +.It Ar cmd +If the command modifier (KS_Cmd_XXX) is active, the optional command +.Ar cmd +is invoked. +.It Ar normal +The keysym if no modifiers are active. +.It Ar shift +The keysym if the shift modifier is active. +.It Ar altgr +The keysym if the alt-gr modifier is active. +.It Ar shift-altgr +The keysym if the shift-alt-gr modifier is active. +.El +.Pp +If the keysym after +.Ar pos +is not KS_Cmd_XXX, then +.Ar cmd +is empty. +The +.Ar shift , +.Ar altgr +and +.Ar shift-altgr +fields are determined from previous fields if they are not specified. +Therefore, there are four valid keysym declarations: +.Pp +.Ar pos +.Op Ar cmd +.Ar normal +.Pp +.Ar pos +.Op Ar cmd +.Ar normal Ar shift +.Pp +.Ar pos +.Op Ar cmd +.Ar normal Ar shift Ar altgr +.Pp +.Ar pos +.Op Ar cmd +.Ar normal Ar shift Ar altgr Ar shift-altgr +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn wskbd_input "kbddev" "type" "value" +Pass the keypress of value +.Fa value +and type +.Fa type +to wscons keyboard driver. +Valid values of +.Fa type +are: +.Bl -tag -width compact +.It WSCONS_EVENT_KEY_UP +Key released. +.It WSCONS_EVENT_KEY_DOWN +Key pressed. +.El +.It Fn wskbd_rawinput "kbddev" "buf" "len" +Pass the raw keypress in the buffer +.Fa buf +to the wscons keyboard driver. +The buffer is +.Fa len +bytes long. +This function should only be called if the kernel option +.Em WSDISPLAY_COMPAT_RAWKBD +is enabled. +.It Fn wskbd_cnattach "consops" "conscookie" "mapdata" +Attach this keyboard as the console input by specifying the console +operations +.Fa consops +and the keyboard mapping table information in +.Fa mapdata . +The functions specified in +.Fa consops +will be called with +.Fa conscookie +as the first argument. +.It Fn wskbd_cndetach "" +Detach this keyboard as the console input. +.It Fn wskbddevprint "aux" "pnp" +The default wskbd printing routine used by +.Fn config_found . +(see +.Xr autoconf 9 ) . +.El +.Sh AUTOCONFIGURATION +Keyboard drivers which want to use the wskbd module must be a +parent to the +.Xr wskbd 4 +device and provide an attachment interface. +To attach the +.Xr wskbd 4 +device, the keyboard driver must allocate and populate a +.Fa wskbddev_attach_args +structure with the supported operations and callbacks and call +.Fn config_found +to perform the attach (see +.Xr autoconf 9 ) . +The +.Fa keymap +member points to the +.Em wskbd_mapdata +structure which describes the keycode mapping operations. +The +.Fa accessops +member points to the +.Em wskbd_accessops +structure which describes the keyboard access operations. +The +.Fa console +member is a boolean to indicate to wscons whether this keyboard will +be used for console input. +.Sh OPERATION +If the keyboard belongs to the system console, it must register the +.Fa wskbd_consops +structure specifying the console operations via +.Fn wskbd_cnattach +at console attach time. +.Pp +When a keypress arrives from the keyboard, the keyboard driver must +perform any necessary character decoding to wscons events and pass the +events to wscons via +.Fn wskbd_input . +If the kernel is compiled with the option +.Em WSDISPLAY_COMPAT_RAWKBD , +then the keyboard driver must also pass the raw keyboard data to +wscons via +.Fn wskbd_rawinput . +.Pp +The wscons framework calls back into the hardware driver by invoking +the functions that are specified in the +.Em accessops +structure. +The +.Fn enable +and +.Fn set_leds +functions are relatively simple and self-explanatory. +The +.Fn ioctl +function is called by the wscons interface to perform +keyboard-specific ioctl operations (see +.Xr ioctl 2 ) . +The argument +.Fa cmd +to the +.Fn ioctl +function specifies the specific command to perform using the data +.Fa data . +Valid commands are listed in +.Pa sys/dev/wscons/wsconsio.h . +.Sh CODE REFERENCES +The wscons subsystem is implemented within the directory +.Pa sys/dev/wscons . +The +.Nm +module itself is implement within the files +.Pa sys/dev/wscons/wskbd.c +and +.Pa sys/dev/wscons/wskbdutil.c . +.Xr ioctl 2 +operations are listed in +.Pa sys/dev/wscons/wsconsio.h . +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr autoconf 9 , +.Xr driver 9 , +.Xr intro 9 , +.Xr wsdisplay 9 , +.Xr wsmouse 9 diff --git a/static/netbsd/man9/wsmouse.9 b/static/netbsd/man9/wsmouse.9 new file mode 100644 index 00000000..fd0ff3d2 --- /dev/null +++ b/static/netbsd/man9/wsmouse.9 @@ -0,0 +1,265 @@ +.\" $NetBSD: wsmouse.9,v 1.19 2021/10/11 18:19:27 nia Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 11, 2021 +.Dt WSMOUSE 9 +.Os +.Sh NAME +.Nm wsmouse , +.Nm wsmouse_input , +.Nm wsmousedevprint +.Nd wscons mouse support +.Sh SYNOPSIS +.In dev/wscons/wsconsio.h +.In dev/wscons/wsmousevar.h +.Ft void +.Fn wsmouse_input "struct device *msdev" "u_int btns" \ +"int x" "int y" "int z" "int w" "u_int flags" +.Ft int +.Fn wsmousedevprint "void *aux" "const char *pnp" +.Sh DESCRIPTION +The +.Nm +module is a component of the +.Xr wscons 9 +framework to provide machine-independent mouse support. +Most of the support is provided by the +.Xr wsmouse 4 +device driver, which must be a child of the hardware device driver. +.Sh DATA TYPES +Mouse drivers providing support for wscons pointer devices will make use +of the following data types: +.Bl -tag -width compact +.It Fa struct wsmouse_accessops +A structure used to specify the mouse access functions. +All pointer devices must provide this structure and pass it to the +.Xr wsmouse 4 +child device. +It has the following members: +.Bd -literal + int (*enable)(void *); + int (*ioctl)(void *v, u_long cmd, void *data, + int flag, struct lwp *l); + void (*disable)(void *); +.Ed +.Pp +The +.Fa enable +member defines the function to be called to enable monitoring pointer +movements and passing these events to +wscons. +The +.Fa disable +member defines the function to disable movement events. +The +.Fa ioctl +member defines the function to be called to perform mouse-specific +ioctl calls. +.Pp +There is a +.Fa void * +cookie provided by the mouse driver associated with these functions, +which is passed to them when they are invoked. +.It Fa struct wsmousedev_attach_args +A structure used to attach the +.Xr wsmouse 4 +child device. +It has the following members: +.Bd -literal + const struct wsmouse_accessops *accessops; + void *accesscookie; +.Ed +.El +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn wsmouse_input "msdev" "btns" "x" "y" "z" "w" "flags" +Callback from the mouse driver to the wsmouse interface driver. +Arguments are as follows: +.Bl -tag -width msdev -compact +.It Fa msdev +This is the +.Fa struct device +pointer passed from +.Fn config_found +on attaching the child +.Xr wsmouse 4 +to specify the mouse device. +.It Fa btns +This specifies the current button status. +Bits for pressed buttons (which will cause the +.Dv WSCONS_EVENT_MOUSE_DOWN +event on +.Xr wsmouse 4 +device) should be set, and bits for released buttons (which will cause the +.Dv WSCONS_EVENT_MOUSE_UP +event) should be zero. +The left most button state should be in LSB, +i.e. for typical three button mouse, +the left button is 0x01, +the middle button is 0x02, +and the right button is 0x04. +.It Fa x +Absolute or relative X-axis value to specify the pointer coordinate. +Rightward (moving the mouse right) is positive. +.It Fa y +Absolute or relative Y-axis value to specify the pointer coordinate. +Upward (moving the mouse forward) is positive. +Note that this aspect is opposite from the one used in the X server dix layer. +.It Fa z +Absolute or relative Z-axis value to specify the pointer coordinate. +Usually this axis is used for the wheel. +Downward (turning the wheel backward) is positive. +.It Fa w +Absolute or relative W-axis value to specify the pointer coordinate. +Usually this axis would be used for the horizontal component of the wheel. +.It Fa flags +This argument specifies whether the pointer device and the measurement +of the +.Fa x , +.Fa y , +.Fa z , +and +.Fa w +axes is in relative or absolute mode. +Valid values for +.Fa flags +are: +.Bl -tag -width compact +.It WSMOUSE_INPUT_DELTA +Relative mode. +.It WSMOUSE_INPUT_ABSOLUTE_X +Absolute mode in +.Fa x +axis. +.It WSMOUSE_INPUT_ABSOLUTE_Y +Absolute mode in +.Fa y +axis. +.It WSMOUSE_INPUT_ABSOLUTE_Z +Absolute mode in +.Fa z +axis. +.It WSMOUSE_INPUT_ABSOLUTE_W +Absolute mode in +.Fa w +axis. +.El +.El +.It Fn wsmouse_precision_scroll "msdev" "x" "y" +Callback from the mouse driver to the wsmouse interface driver. +.Pp +This is used when higher precision scrolling events are required +than what can be provided by a typical scroll wheel. +This function generates +.Dv WSCONS_EVENT_HSCROLL +(for scrolling on the X axis) and +.Dv WSCONS_EVENT_VSCROLL +(for scrolling on the X axis) events. +.Pp +The coordinates are adjusted for speed according to the formula: +.Li x * 4096 / scroll_unit +.Pp +The +.Dv scroll_unit +is configured through the +.Xr wsmouse 4 +ioctl interface, specifically the +.Dv WSMOUSEIO_SETPARAMS +keys +.Dv WSMOUSECFG_HORIZSCROLLDIST +and +.Dv WSMOUSECFG_VERTSCROLLDIST . +.It Fn wsmousedevprint "aux" "pnp" +The default wsmouse printing routine used by +.Fn config_found . +(see +.Xr autoconf 9 ) . +.El +.Sh AUTOCONFIGURATION +Mouse drivers which want to use the wsmouse module must be a +parent to the +.Xr wsmouse 4 +device and provide an attachment interface. +To attach the +.Xr wsmouse 4 +device, the mouse driver must allocate and populate a +.Fa wsmousedev_attach_args +structure with the supported operations and callbacks and call +.Fn config_found +to perform the attach (see +.Xr autoconf 9 ) . +.Sh OPERATION +When a mouse-movement event is received, the device driver must +perform any necessary movement decoding to wscons events and pass the +events to wscons via +.Fn wsmouse_input . +.Pp +The wscons framework calls back into the hardware driver by invoking +the functions that are specified in the +.Em accessops +structure. +The +.Fn enable +and +.Fn disable +functions are relatively simple and self-explanatory. +The +.Fn ioctl +function is called by the wscons interface to perform +mouse-specific ioctl operations (see +.Xr ioctl 2 ) . +The argument +.Fa cmd +to the +.Fn ioctl +function specifies the specific command to perform using the data +.Fa data . +Valid commands are listed in +.Pa sys/dev/wscons/wsconsio.h . +.Sh CODE REFERENCES +The wscons subsystem is implemented within the directory +.Pa sys/dev/wscons . +The +.Nm +module itself is implemented within the file +.Pa sys/dev/wscons/wsmouse.c . +.Xr ioctl 2 +operations are listed in +.Pa sys/dev/wscons/wsconsio.h . +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr pms 4 , +.Xr wscons 4 , +.Xr wsmouse 4 , +.Xr autoconf 9 , +.Xr driver 9 , +.Xr intro 9 , +.Xr wscons 9 , +.Xr wsdisplay 9 , +.Xr wskbd 9 diff --git a/static/netbsd/man9/xcall.9 b/static/netbsd/man9/xcall.9 new file mode 100644 index 00000000..aae828b1 --- /dev/null +++ b/static/netbsd/man9/xcall.9 @@ -0,0 +1,204 @@ +.\" $NetBSD: xcall.9,v 1.17 2020/02/01 13:35:11 riastradh Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Andrew Doran. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 1, 2020 +.Dt XCALL 9 +.Os +.Sh NAME +.Nm xcall , +.Nm xc_broadcast , +.Nm xc_unicast , +.Nm xc_wait , +.Nm xc_barrier +.Nd cross-call interface +.Sh SYNOPSIS +.In sys/xcall.h +.Vt typedef void (*xcfunc_t)(void *, void *); +.Ft uint64_t +.Fn xc_broadcast "u_int flags" "xcfunc_t func" "void *arg1" "void *arg2" +.Ft uint64_t +.Fn xc_unicast "u_int flags" "xcfunc_t func" "void *arg1" "void *arg2" "struct cpu_info *ci" +.Ft void +.Fn xc_wait "uint64_t where" +.Ft void +.Fn xc_barrier "u_int flags" +.Sh DESCRIPTION +The machine-independent +.Nm +interface allows any CPU in the system to request that an arbitrary +function be executed on any other CPU. +.Pp +Sometimes it is necessary to modify hardware state that is tied +directly to individual CPUs +.Po +such as a CPU's local timer +.Pc , +and these updates can not be done remotely by another CPU. +The LWP requesting the update may be unable to guarantee that it +will be running on the CPU where the update must occur, when the +update occurs. +.Pp +Additionally, it is sometimes necessary to modify per-CPU software +state from a remote CPU. +Where these update operations are so rare or the access to the +per-CPU data so frequent that the cost of using locking or atomic +operations to provide coherency is prohibitive, another way must +be found. +.Pp +Cross calls help to solve these types of problem. +However, since this facility is heavyweight, it is expected that +it will not be used often. +.Pp +.Nm +provides a mechanism for making +.Dq "low priority" +cross calls. +The function to be executed runs on the remote CPU within a thread +context, and not from a software interrupt, so it can ensure that it is +not interrupting other code running on the CPU, and so has exclusive +access to the CPU. +Keep in mind that unless disabled, it may cause a kernel preemption. +.Pp +.Nm +also provides a mechanism for making +.Dq "high priority" +cross calls. +The function to be executed runs on the remote CPU within a +software interrupt context, possibly interrupting other lower-priority +code running on the CPU. +.Sh NOTES +Functions being called should be relatively lightweight. +They may block on locks, but carefully and minimally, to not interfere +with other cross calls in the system. +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn xc_broadcast "flags" "func" "arg1" "arg2" +Call +.Pf (* Fa func\| ) Ns Fo "" +.Fa "arg1" +.Fa "arg2" +.Fc +on all CPUs in the system. +Return a +.Vt uint64_t +.Dq ticket +to +.Fn xc_wait +on for the cross-call to complete. +.Fa flags +should be +.Dv XC_HIGHPRI +or +.Dv XC_HIGHPRI_IPL\| Ns Fn "" ipl +for a "high priority" call, and 0 for a "low priority" call. +.Dv XC_HIGHPRI +uses an +.Dv IPL_SOFTSERIAL +software interrupt while +.Dv XC_HIGHPRI_IPL +uses a software interrupt with an IPL specified by +.Fa ipl . +.Fn xc_broadcast +should not be called from interrupt context. +.It Fn xc_unicast "flags" "func" "arg1" "arg2" "ci" +Like +.Fn xc_broadcast , +but call +.Fa func +on only the CPU indicated by +.Fa ci . +.Fn xc_unicast +also returns a +.Dq ticket . +.It Fn xc_wait "where" +Wait on the +.Dq ticket +returned by a prior +.Fn xc_broadcast +or +.Fn xc_unicast +for the corresponding cross-call to complete. +.Fn xc_wait +should be called from a thread context. +.It Fn xc_barrier "flags" +Issue a broadcast cross-call that does nothing, +and wait for it to complete. +.Pp +This functions like a memory barrier that forces all prior operations +in program order to globally happen before all subsequent operations in +program order, as witnessed by every CPU. +.Pp +This additionally waits for all higher-priority activity on the CPU to +complete, according to +.Fa flags : +.Bl -dash -compact +.It +.Fo xc_barrier +.Li 0 +.Fc +waits for any pending +.Xr kpreempt_disable 9 +sections or activity at interrupt priority level above +.Dv IPL_NONE +to finish on all CPUs. +.It +.Fo xc_barrier +.Dv XC_HIGHPRI_IPL\| Ns Fn "" ipl +.Fc +waits for any pending activity at the software interrupt priority level +.Fa ipl +or higher to finish on all CPUs. +.El +.Pp +.Fn xc_barrier +is much more expensive than +.Xr membar_ops 3 , +so it should be used sparingly, only to publish information +infrequently \(em for example, during module load and unload \(em when +the cost of a memory barrier on the consumer side would be +prohibitive. +.El +.Sh CODE REFERENCES +The +.Nm +interface is implemented within the file +.Pa sys/kern/subr_xcall.c . +.\" .Sh EXAMPLES +.Sh SEE ALSO +.Xr membar_ops 3 , +.Xr kpreempt 9 , +.Xr percpu 9 , +.Xr softint 9 +.Sh HISTORY +The +.Nm +interface first appeared in +.Nx 5.0 . +.Sh AUTHORS +.An Andrew Doran Aq Mt ad@NetBSD.org |