## Expand description

Interfaces for accessing a random number generator.

A random number generator produces a stream of random numbers, either from hardware or based on an initial seed. The RNG trait provides a simple, implementation agnostic interface for getting new random values.

*Randomness*: Random numbers generated by this trait MUST pass
standard randomness tests, such as A. Rukhin, J. Soto,
J. Nechvatal, M. Smid, E. Barker, S. Leigh, M. Levenson,
M. Vangel, D. Banks, A. Heckert, J. Dray, and S. Vo. A statistical
test suite for random and pseudorandom number generators for
cryptographic applications. Technical report, NIST, 2010. It is
acceptable for implementations to rely on prior verification of
the algorithm being used. For example, if the implementation
chooses to use a Fishman and Moore Linear Congruence Generator
(LCG) with the parameters specified in the NIST report above, it
does not need to re-run the tests.

Entropy: This trait does not promise high-entropy random numbers,
although it MAY generate them. Implementations of this interface
MAY generate random numbers using techniques other than true
random number generation (through entropy) or cryptographically
secure pseudorandom number generation. Other traits, described
elsewhere, provide random numbers with entropy guarantees. This
trait MUST NOT be used for randomness needed for security or
cryptography. If high-entropy randomness is needed, the `Entropy`

trait should be used instead.

The Rng trait is designed to work well with random number
generators that may not have values ready immediately. This is
important when generating numbers from a low-bandwidth hardware
random number generator or when the RNG is virtualized among many
consumers. Random numbers are yielded to the
Client as an `Iterator`

which only terminates
when no more numbers are currently available. Clients can request
more randomness if needed and will be called again when more is
available.

The Random trait is synchronous, so designed to work with arithmetically simple random number generators that can return a result quickly.

## Example

The following example is a simple capsule that prints out a random number
once a second using the `Alarm`

and `RNG`

traits.

```
use kernel::hil;
use kernel::hil::time::ConvertTicks;
use kernel::hil::time::Frequency;
use kernel::hil::time::Time;
use kernel::ErrorCode;
struct RngTest<'a, A: 'a + hil::time::Alarm<'a>> {
rng: &'a dyn hil::rng::Rng<'a>,
alarm: &'a A
}
impl<'a, A: hil::time::Alarm<'a>> RngTest<'a, A> {
pub fn initialize(&self) {
let now = self.alarm.now();
let dt = self.alarm.ticks_from_seconds(1);
self.alarm.set_alarm(now, dt);
}
}
impl<'a, A: hil::time::Alarm<'a>> hil::time::AlarmClient for RngTest<'a, A> {
fn alarm(&self) {
self.rng.get();
}
}
impl<'a, A: hil::time::Alarm<'a>> hil::rng::Client for RngTest<'a, A> {
fn randomness_available(&self,
randomness: &mut dyn Iterator<Item = u32>,
error: Result<(), ErrorCode>) -> hil::rng::Continue {
match randomness.next() {
Some(random) => {
println!("Rand {}", random);
let now = self.alarm.now();
let dt = self.alarm.ticks_from_seconds(1);
self.alarm.set_alarm(now, dt);
hil::rng::Continue::Done
},
None => hil::rng::Continue::More
}
}
}
```