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.\" $FreeBSD$ 26*8a0edc91SConrad Meyer.\" 27*8a0edc91SConrad Meyer.Dd August 5, 2020 28*8a0edc91SConrad Meyer.Dt PRNG 9 29*8a0edc91SConrad Meyer.Os 30*8a0edc91SConrad Meyer.Sh NAME 31*8a0edc91SConrad Meyer.Nm prng 32*8a0edc91SConrad Meyer.Nd "Kernel pseudo-random number generators" 33*8a0edc91SConrad Meyer.Sh SYNOPSIS 34*8a0edc91SConrad Meyer.In sys/prng.h 35*8a0edc91SConrad Meyer.Ft uint32_t 36*8a0edc91SConrad Meyer.Fn prng32 void 37*8a0edc91SConrad Meyer.Ft uint32_t 38*8a0edc91SConrad Meyer.Fn prng32_bounded "uint32_t bound" 39*8a0edc91SConrad Meyer.Ft uint64_t 40*8a0edc91SConrad Meyer.Fn prng64 void 41*8a0edc91SConrad Meyer.Ft uint64_t 42*8a0edc91SConrad Meyer.Fn prng64_bounded "uint64_t bound" 43*8a0edc91SConrad Meyer.Sh DESCRIPTION 44*8a0edc91SConrad Meyer.Ss GENERIC PRNG ROUTINES 45*8a0edc91SConrad Meyer.Nm 46*8a0edc91SConrad Meyeris a family of fast, 47*8a0edc91SConrad Meyer.Em non-cryptographic 48*8a0edc91SConrad Meyerpseudo-random number generators. 49*8a0edc91SConrad MeyerUnlike 50*8a0edc91SConrad Meyer.Xr random 9 , 51*8a0edc91SConrad Meyer.Fn prng32 , 52*8a0edc91SConrad Meyer.Fn prng32_bounded , 53*8a0edc91SConrad Meyer.Fn prng64 , 54*8a0edc91SConrad Meyerand 55*8a0edc91SConrad Meyer.Fn prng64_bounded 56*8a0edc91SConrad Meyeravoid shared global state, removing unnecessary contention on SMP 57*8a0edc91SConrad Meyersystems. 58*8a0edc91SConrad MeyerThe routines are not explicitly tied to any specific implementation, and 59*8a0edc91SConrad Meyermay produce different specific sequences on different hosts, reboots, or 60*8a0edc91SConrad Meyerversions of 61*8a0edc91SConrad Meyer.Fx . 62*8a0edc91SConrad MeyerDifferent CPUs in SMP systems are guaranteed to produce different sequences of 63*8a0edc91SConrad Meyerintegers. 64*8a0edc91SConrad Meyer.Pp 65*8a0edc91SConrad MeyerFor 66*8a0edc91SConrad Meyer.Em cryptographically secure 67*8a0edc91SConrad Meyerrandom numbers generated by the 68*8a0edc91SConrad Meyer.Xr random 4 69*8a0edc91SConrad Meyerkernel cryptographically secure random number generator subsystem, see 70*8a0edc91SConrad Meyer.Xr arc4random 9 . 71*8a0edc91SConrad Meyer.Pp 72*8a0edc91SConrad Meyer.Bl -tag -width indent 73*8a0edc91SConrad Meyer.It Fn prng32 74*8a0edc91SConrad MeyerGenerate a 32-bit integer uniformly distributed in [0, 2^32-1]. 75*8a0edc91SConrad Meyer.It Fn prng32_bounded bound 76*8a0edc91SConrad MeyerGenerate an integer uniformly in the range [0, bound-1]. 77*8a0edc91SConrad Meyer.It Fn prng64 78*8a0edc91SConrad MeyerGenerate a 64-bit integer uniformly distributed in [0, 2^64-1]. 79*8a0edc91SConrad Meyer.It Fn prng64_bounded bound 80*8a0edc91SConrad MeyerGenerate an integer uniformly in the range [0, bound-1]. 81*8a0edc91SConrad Meyer.El 82*8a0edc91SConrad Meyer.Pp 83*8a0edc91SConrad MeyerThese routines are not reentrant; they are not safe to use in interrupt 84*8a0edc91SConrad Meyerhandlers ("interrupt filters" in 85*8a0edc91SConrad Meyer.Xr bus_setup_intr 9 86*8a0edc91SConrad Meyerterminology). 87*8a0edc91SConrad MeyerThey are safe to use in all other kernel contexts, including interrupt threads 88*8a0edc91SConrad Meyer("ithreads"). 89*8a0edc91SConrad Meyer.Ss REPRODUCIBLE PRNG APIS 90*8a0edc91SConrad MeyerIn addition to these per-CPU helpers, the 91*8a0edc91SConrad Meyer.In sys/prng.h 92*8a0edc91SConrad Meyerheader also exposes the entire API of the PCG family of PRNGs as inline 93*8a0edc91SConrad Meyerfunctions. 94*8a0edc91SConrad MeyerThe PCG-C API is described in full at 95*8a0edc91SConrad Meyer.Lk https://www.pcg-random.org/using-pcg-c.html . 96*8a0edc91SConrad Meyer.Sh HISTORY 97*8a0edc91SConrad Meyer.Nm 98*8a0edc91SConrad Meyerwas introduced in 99*8a0edc91SConrad Meyer.Fx 13 . 100