Changeset View
Standalone View
share/man/man9/prng.9
- This file was added.
.\"- | ||||||||||
.\" 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 . | ||||||||||
0mpUnsubmitted Done Inline Actions
0mp: | ||||||||||
Different CPUs in SMP systems are guaranteed to produce different sequences of | ||||||||||
integers. | ||||||||||
Done Inline ActionsCan't this be folded into the previous sentence? "... and may produce different sequences on different hosts, CPUs, reboots, or versions of FreeBSD." markj: Can't this be folded into the previous sentence? "... and may produce different sequences on… | ||||||||||
Done Inline ActionsI think it would be less clear folded in, but probably that just means it's also unclear now. The two sentences are trying to cover different properties — the first is just "no ABI is promised, results may vary." The latter is promising a property of the implementation: the PCPU PRNGs all emit different sequences of numbers. Imagine if each PCPU counter was seeded with zero and stepped by an identical function, e.g., libc's rand_r(). Each CPU generator would produce the exact same sequence of numbers. Here, I'm trying to document that each PCPU step function is unique. cem: I think it would be less clear folded in, but probably that just means it's also unclear now. | ||||||||||
Done Inline ActionsI see, thanks. You use "may produce" in the previous sentence and "will produce" in this one, so I'd be fine leaving it as it is since I was just sloppy in how I read the text. "are guaranteed to produce" might be clearer though. markj: I see, thanks. You use "may produce" in the previous sentence and "will produce" in this one… | ||||||||||
.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 . |