aboutsummaryrefslogtreecommitdiff
path: root/share/man/man9/prng.9
diff options
context:
space:
mode:
Diffstat (limited to 'share/man/man9/prng.9')
-rw-r--r--share/man/man9/prng.999
1 files changed, 99 insertions, 0 deletions
diff --git a/share/man/man9/prng.9 b/share/man/man9/prng.9
new file mode 100644
index 000000000000..63132c28c198
--- /dev/null
+++ b/share/man/man9/prng.9
@@ -0,0 +1,99 @@
+.\"-
+.\" Copyright 2020 Conrad Meyer <cem@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$
+.\"
+.Dd August 5, 2020
+.Dt PRNG 9
+.Os
+.Sh NAME
+.Nm prng
+.Nd "Kernel pseudo-random number generators"
+.Sh SYNOPSIS
+.In sys/prng.h
+.Ft uint32_t
+.Fn prng32 void
+.Ft uint32_t
+.Fn prng32_bounded "uint32_t bound"
+.Ft uint64_t
+.Fn prng64 void
+.Ft uint64_t
+.Fn prng64_bounded "uint64_t bound"
+.Sh DESCRIPTION
+.Ss GENERIC PRNG ROUTINES
+.Nm
+is a family of fast,
+.Em non-cryptographic
+pseudo-random number generators.
+Unlike
+.Xr random 9 ,
+.Fn prng32 ,
+.Fn prng32_bounded ,
+.Fn prng64 ,
+and
+.Fn prng64_bounded
+avoid shared global state, removing unnecessary contention on SMP
+systems.
+The routines are not explicitly tied to any specific implementation, and
+may produce different specific sequences on different hosts, reboots, or
+versions of
+.Fx .
+Different CPUs in SMP systems are guaranteed to produce different sequences of
+integers.
+.Pp
+For
+.Em cryptographically secure
+random numbers generated by the
+.Xr random 4
+kernel cryptographically secure random number generator subsystem, see
+.Xr arc4random 9 .
+.Pp
+.Bl -tag -width indent
+.It Fn prng32
+Generate a 32-bit integer uniformly distributed in [0, 2^32-1].
+.It Fn prng32_bounded bound
+Generate an integer uniformly in the range [0, bound-1].
+.It Fn prng64
+Generate a 64-bit integer uniformly distributed in [0, 2^64-1].
+.It Fn prng64_bounded bound
+Generate an integer uniformly in the range [0, bound-1].
+.El
+.Pp
+These routines are not reentrant; they are not safe to use in interrupt
+handlers ("interrupt filters" in
+.Xr bus_setup_intr 9
+terminology).
+They are safe to use in all other kernel contexts, including interrupt threads
+("ithreads").
+.Ss REPRODUCIBLE PRNG APIS
+In addition to these per-CPU helpers, the
+.In sys/prng.h
+header also exposes the entire API of the PCG family of PRNGs as inline
+functions.
+The PCG-C API is described in full at
+.Lk https://www.pcg-random.org/using-pcg-c.html .
+.Sh HISTORY
+.Nm
+was introduced in
+.Fx 13 .