feat: Added NetBSD man pages

1 files changed, 430 insertions, 0 deletions

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 .