1.. _module-pw_random: 2 3========= 4pw_random 5========= 6Pigweed's ``pw_random`` module provides a generic interface for random number 7generators, as well as some practical embedded-friendly implementations. While 8this module does not provide drivers for hardware random number generators, it 9acts as a user-friendly layer that can be used to abstract away such hardware. 10 11Embedded systems have the propensity to be more deterministic than your typical 12PC. Sometimes this is a good thing. Other times, it's valuable to have some 13random numbers that aren't predictable. In security contexts or areas where 14things must be marked with a unique ID, this is especially important. Depending 15on the project, true hardware random number generation peripherals may or may 16not be available. Even if RNG hardware is present, it might not always be active 17or accessible. ``pw_random`` provides libraries that make these situations 18easier to manage. 19 20--------------------- 21Using RandomGenerator 22--------------------- 23There's two sides to a RandomGenerator; the input, and the output. The outputs 24are relatively straightforward; ``GetInt(T&)`` randomizes the passed integer 25reference, ``GetInt(T&, T exclusive_upper_bound)`` produces a random integer 26less than ``exclusive_upper_bound``, and ``Get()`` dumps random values into the 27passed span. The inputs are in the form of the ``InjectEntropy*()`` functions. 28These functions are used to "seed" the random generator. In some 29implementations, this can simply be resetting the seed of a PRNG, while in 30others it might directly populate a limited buffer of random data. In all cases, 31entropy injection is used to improve the randomness of calls to ``Get*()``. 32 33It might not be easy to find sources of entropy in a system, but in general a 34few bits of noise from ADCs or other highly variable inputs can be accumulated 35in a RandomGenerator over time to improve randomness. Such an approach might 36not be sufficient for security, but it could help for less strict uses. 37 38------------- 39API reference 40------------- 41.. doxygennamespace:: pw::random 42 :members: 43 44----------- 45Future Work 46----------- 47A simple "entropy pool" implementation could buffer incoming entropy later use 48instead of requiring an application to directly poll the hardware RNG peripheral 49when the random data is needed. This would let a device collect entropy when 50idling, improving the latency of potentially performance-sensitive areas where 51random numbers are needed. 52 53 54.. toctree:: 55 :hidden: 56 :maxdepth: 1 57 58 Backends <backends> 59