1*8a0edc91SConrad Meyer.\"- 2*8a0edc91SConrad Meyer.\" Copyright 2020 Conrad Meyer <cem@FreeBSD.org>. All rights reserved. 3*8a0edc91SConrad Meyer.\" 4*8a0edc91SConrad Meyer.\" Redistribution and use in source and binary forms, with or without 5*8a0edc91SConrad Meyer.\" modification, are permitted provided that the following conditions 6*8a0edc91SConrad Meyer.\" are met: 7*8a0edc91SConrad Meyer.\" 1. Redistributions of source code must retain the above copyright 8*8a0edc91SConrad Meyer.\" notice, this list of conditions and the following disclaimer. 9*8a0edc91SConrad Meyer.\" 2. Redistributions in binary form must reproduce the above copyright 10*8a0edc91SConrad Meyer.\" notice, this list of conditions and the following disclaimer in the 11*8a0edc91SConrad Meyer.\" documentation and/or other materials provided with the distribution. 12*8a0edc91SConrad Meyer.\" 13*8a0edc91SConrad Meyer.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14*8a0edc91SConrad Meyer.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15*8a0edc91SConrad Meyer.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16*8a0edc91SConrad Meyer.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17*8a0edc91SConrad Meyer.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18*8a0edc91SConrad Meyer.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19*8a0edc91SConrad Meyer.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20*8a0edc91SConrad Meyer.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21*8a0edc91SConrad Meyer.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22*8a0edc91SConrad Meyer.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23*8a0edc91SConrad Meyer.\" SUCH DAMAGE. 24*8a0edc91SConrad Meyer.\" 25*8a0edc91SConrad Meyer.Dd August 5, 2020 26*8a0edc91SConrad Meyer.Dt PRNG 9 27*8a0edc91SConrad Meyer.Os 28*8a0edc91SConrad Meyer.Sh NAME 29*8a0edc91SConrad Meyer.Nm prng 30*8a0edc91SConrad Meyer.Nd "Kernel pseudo-random number generators" 31*8a0edc91SConrad Meyer.Sh SYNOPSIS 32*8a0edc91SConrad Meyer.In sys/prng.h 33*8a0edc91SConrad Meyer.Ft uint32_t 34*8a0edc91SConrad Meyer.Fn prng32 void 35*8a0edc91SConrad Meyer.Ft uint32_t 36*8a0edc91SConrad Meyer.Fn prng32_bounded "uint32_t bound" 37*8a0edc91SConrad Meyer.Ft uint64_t 38*8a0edc91SConrad Meyer.Fn prng64 void 39*8a0edc91SConrad Meyer.Ft uint64_t 40*8a0edc91SConrad Meyer.Fn prng64_bounded "uint64_t bound" 41*8a0edc91SConrad Meyer.Sh DESCRIPTION 42*8a0edc91SConrad Meyer.Ss GENERIC PRNG ROUTINES 43*8a0edc91SConrad Meyer.Nm 44*8a0edc91SConrad Meyeris a family of fast, 45*8a0edc91SConrad Meyer.Em non-cryptographic 46*8a0edc91SConrad Meyerpseudo-random number generators. 47*8a0edc91SConrad MeyerUnlike 48*8a0edc91SConrad Meyer.Xr random 9 , 49*8a0edc91SConrad Meyer.Fn prng32 , 50*8a0edc91SConrad Meyer.Fn prng32_bounded , 51*8a0edc91SConrad Meyer.Fn prng64 , 52*8a0edc91SConrad Meyerand 53*8a0edc91SConrad Meyer.Fn prng64_bounded 54*8a0edc91SConrad Meyeravoid shared global state, removing unnecessary contention on SMP 55*8a0edc91SConrad Meyersystems. 56*8a0edc91SConrad MeyerThe routines are not explicitly tied to any specific implementation, and 57*8a0edc91SConrad Meyermay produce different specific sequences on different hosts, reboots, or 58*8a0edc91SConrad Meyerversions of 59*8a0edc91SConrad Meyer.Fx . 60*8a0edc91SConrad MeyerDifferent CPUs in SMP systems are guaranteed to produce different sequences of 61*8a0edc91SConrad Meyerintegers. 62*8a0edc91SConrad Meyer.Pp 63*8a0edc91SConrad MeyerFor 64*8a0edc91SConrad Meyer.Em cryptographically secure 65*8a0edc91SConrad Meyerrandom numbers generated by the 66*8a0edc91SConrad Meyer.Xr random 4 67*8a0edc91SConrad Meyerkernel cryptographically secure random number generator subsystem, see 68*8a0edc91SConrad Meyer.Xr arc4random 9 . 69*8a0edc91SConrad Meyer.Bl -tag -width indent 70*8a0edc91SConrad Meyer.It Fn prng32 71*8a0edc91SConrad MeyerGenerate a 32-bit integer uniformly distributed in [0, 2^32-1]. 72*8a0edc91SConrad Meyer.It Fn prng32_bounded bound 73*8a0edc91SConrad MeyerGenerate an integer uniformly in the range [0, bound-1]. 74*8a0edc91SConrad Meyer.It Fn prng64 75*8a0edc91SConrad MeyerGenerate a 64-bit integer uniformly distributed in [0, 2^64-1]. 76*8a0edc91SConrad Meyer.It Fn prng64_bounded bound 77*8a0edc91SConrad MeyerGenerate an integer uniformly in the range [0, bound-1]. 78*8a0edc91SConrad Meyer.El 79*8a0edc91SConrad Meyer.Pp 80*8a0edc91SConrad MeyerThese routines are not reentrant; they are not safe to use in interrupt 81*8a0edc91SConrad Meyerhandlers ("interrupt filters" in 82*8a0edc91SConrad Meyer.Xr bus_setup_intr 9 83*8a0edc91SConrad Meyerterminology). 84*8a0edc91SConrad MeyerThey are safe to use in all other kernel contexts, including interrupt threads 85*8a0edc91SConrad Meyer("ithreads"). 86*8a0edc91SConrad Meyer.Ss REPRODUCIBLE PRNG APIS 87*8a0edc91SConrad MeyerIn addition to these per-CPU helpers, the 88*8a0edc91SConrad Meyer.In sys/prng.h 89*8a0edc91SConrad Meyerheader also exposes the entire API of the PCG family of PRNGs as inline 90*8a0edc91SConrad Meyerfunctions. 91*8a0edc91SConrad MeyerThe PCG-C API is described in full at 92*8a0edc91SConrad Meyer.Lk https://www.pcg-random.org/using-pcg-c.html . 93*8a0edc91SConrad Meyer.Sh HISTORY 94*8a0edc91SConrad Meyer.Nm 95*8a0edc91SConrad Meyerwas introduced in 96*8a0edc91SConrad Meyer.Fx 13 . 97