8a0edc914f
Add prng(9) as a replacement for random(9) in the kernel.
There are two major differences from random(9) and random(3):
- General prng(9) APIs (prng32(9), etc) do not guarantee an
implementation or particular sequence; they should not be used for
repeatable simulations.
- However, specific named API families are also exposed (for now: PCG),
and those are expected to be repeatable (when so-guaranteed by the named
algorithm).
Some minor differences from random(3) and earlier random(9):
- PRNG state for the general prng(9) APIs is per-CPU; this eliminates
contention on PRNG state in SMP workloads. Each PCPU generator in an
SMP system produces a unique sequence.
- Better statistical properties than the Park-Miller ("minstd") PRNG
(longer period, uniform distribution in all bits, passes
BigCrush/PractRand analysis).
- Faster than Park-Miller ("minstd") PRNG -- no division is required to
step PCG-family PRNGs.
For now, random(9) becomes a thin shim around prng32(). Eventually I
would like to mechanically switch consumers over to the explicit API.
Reviewed by: kib, markj (previous version both)
Discussed with: markm
Differential Revision: https://reviews.freebsd.org/D25916
100 lines
3.2 KiB
Groff
100 lines
3.2 KiB
Groff
.\"-
|
|
.\" 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 .
|