lib_random: Random number generation£££doc/rst/lib_random.html#lib-random-random-number-generation

lib_random: Random number generation$$$Introduction£££doc/rst/lib_random.html#introduction

This library provides both hardware and software random number generation.

Hardware based generation uses an asynchronous oscillator in the xcore device.

lib_random: Random number generation$$$Usage£££doc/rst/lib_random.html#usage

To use the module you need to use lib_random in your application CMakeLists.txt, for example:

set(APP_DEPENDENT_MODULES "lib_random")

An application should then the random.h header file:

#include "random.h"

lib_random: Random number generation$$$Example£££doc/rst/lib_random.html#example

An example demonstrating how to generate random values using the lib_random library is provided in examples/app_random

It shows the two different methods for initialising a random number generator (software or hardware seed), and then also shows how to generate either a single random value or populate an array with random values.

To build and run the example, run the following from an XTC tools terminal:

cd examples/app_random
cmake -G "Unix Makefiles" -B build

The application binaries can be built using xmake:

xmake -C build

To run the application using the simulator, run the following command:

xsim bin/app_random.xe

The random data values will be printed in the terminal.

lib_random: Random number generation$$$API reference£££doc/rst/lib_random.html#api-reference

There are two random-number APIs available, one API that creates fast pseudo-random numbers using a linear-feedback-shift register, one that slowly creates random bits. A third API enables you to switch the ring oscillator off.

lib_random: Random number generation$$$API reference$$$Pseudo random£££doc/rst/lib_random.html#pseudo-random

The Pseudo random number generator uses a 32-bit LFSR to generate a pseudo random string of random bits. This has known weaknesses but is exceedingly fast. It comprises the following functions:

random_generator_t random_create_generator_from_seed(unsigned seed)

Function that creates a random number generator from a seed.

Parameters:

  • seed – seed for the generator.

Returns:

a random number generator.

random_generator_t random_create_generator_from_hw_seed(void)

Function that attempts to create a random number generator from a ring-oscillator random value into the seed, using an asynchronous timer. This is based on a 16-bit start value. For better randomness, initialise the random number by calling random_ro_get_bits() 32 times.

Returns:

a random number generator.

unsigned random_get_random_number(REFERENCE_PARAM(random_generator_t, g))

Function that produces a random number. The number has a cycle of 2^32 and is produced using a LFSR.

Parameters:

  • g – the used generator to produce the seed.

Returns:

a random 32 bit number.

void random_get_random_bytes(REFERENCE_PARAM(random_generator_t, g), uint8_t in_buffer[], size_t byte_count)

lib_random: Random number generation$$$API reference$$$Ring oscillator random£££doc/rst/lib_random.html#ring-oscillator-random

This interface uses the on-chip ring oscillators to create a random bit after some time has elapsed. These bits are notionally true random. The bit rate is limited by a constant RANDOM_RO_MIN_TIME_FOR_ONE_BIT. The default value is a safe value that should produce random bits in most circumstances. You can lower it in order to generate more random bits per second at a risk of introducing correlation.

void random_ro_init()

Function that initialises the ring-oscillator random number generator. Call this once before random_ro_get_bit() is called

int random_ro_get_bit()

Function that may produce a random bit using the ring-oscillator.

If a random bit is available, then it returns 0 or 1 at random.

If no random bits are available, then it returns a negative value which is the time in ticks to wait before the next bit is available.

Pre:

random_ro_init() must be called before invoking this function.

Returns:

Random bit, or the negated time to wait in ticks.

lib_random: Random number generation$$$API reference$$$Switching random numbers off£££doc/rst/lib_random.html#switching-random-numbers-off

The random library switches on a ring oscillator on startup. If it is no longer required it can be switched off to save some power.

void random_ro_uninit()

Function that stops the ring oscillator, slightly reducing overall power consumption.

lib_random: Random number generation$$$Further Reading£££doc/rst/lib_random.html#further-reading