====== Randomness ======

The ''sim::rand'' namespace contains support for random number generation, and includes the definition of a number of processes that use this random number generation functionality. The underlying random number generator used is a pseudo-random number generator, and hence the sequence of "random" numbers is deterministic. To ensure that these numbers remain unchanged on different platforms, we use a local mirror of the ''rand_r'' function from glibc.

There are two main sources providing a stream of random tokens in this namespace, full range and constrained range. Additionally, the functions for creating your own random source are also exposed. As with normal sources, there are four versions per source type (permutations with and without ''_multi'' and ''_en''). Please see [[sim:sources | the documentation for sources]] for more detailed information.

===== Shared parameters =====

   * ''D_WIDTH'': The bit width of the data bus
   * ''SOURCE_ID'': ID of the source to be used in log output
   * ''LOG'': Toggles whether or not the source should post a log line whenever a token is emitted

All ''_multi'' sources additionally have:

   * ''OUT_CHANNELS'': Number of output channels on which the token should be emitted

The parameter order for all components generally is ''[interface] [variant settings] [logging]''; this translates into a general parameter order of ''D_WIDTH, [OUT_CHANNELS, ] (source specifics), SOURCE_ID, LOG'' for all sources.

===== Interface =====

All sources have an identical output interface:

   * ''O'': Singular output channel for normal and array of size ''OUT_CHANNELS'' for all ''_multi'' sources

Additionally, for all ''_en'' sources:

   * ''enable'': Source only emits tokens if this flag is high

===== Source types =====

==== Simple source ====

This source will initialize a pseudorandom number generator and start generating random numbers in the full bit width of the output channel. It has no additional parameters.

The available sources are:

<code act>
export template<pint D_WIDTH, SOURCE_ID; pbool LOG>
defproc source_simple(chan!(int<D_WIDTH>) O);

export template<pint D_WIDTH, OUT_CHANNELS, SOURCE_ID; pbool LOG>
defproc source_simple_multi(chan!(int<D_WIDTH>) O[OUT_CHANNELS]);

export template<pint D_WIDTH, SOURCE_ID; pbool LOG>
defproc source_simple(chan!(int<D_WIDTH>) O; bool enable);

export template<pint D_WIDTH, OUT_CHANNELS, SOURCE_ID; pbool LOG>
defproc source_simple_multi(chan!(int<D_WIDTH>) O[OUT_CHANNELS]; bool enable);
</code>

==== Range source ====

This source will initialize a pseudorandom number generator and start generating random numbers in the parameter given range.

These additional parameters are:

   * ''MIN_VAL'': The lower bound of the range in which to generate random numbers in
   * ''MAX_VAL'': The upper bound of the range in which to generate random numbers in

The available sources are:

<code act>
export template<pint D_WIDTH, MIN_VAL, MAX_VAL, SOURCE_ID; pbool LOG>
defproc source_range(chan!(int<D_WIDTH>) O);

export template<pint D_WIDTH, OUT_CHANNELS, MIN_VAL, MAX_VAL, SOURCE_ID; pbool LOG>
defproc source_range_multi(chan!(int<D_WIDTH>) O[OUT_CHANNELS])

export template<pint D_WIDTH, MIN_VAL, MAX_VAL, SOURCE_ID; pbool LOG>
defproc source_range_en(chan!(int<D_WIDTH>) O; bool enable)

export template<pint D_WIDTH, OUT_CHANNELS, MIN_VAL, MAX_VAL, SOURCE_ID; pbool LOG>
defproc source_range_multi_en(chan!(int<D_WIDTH>) O[OUT_CHANNELS]; bool enable)
</code>

===== Functions =====

The functions used to use (pseudo) random number generators are also exported and available for use outside the sim library. These are the following:

<code act>
function init(int<8> data_width) : int<32>;
function init_range(int<8> data_width; int<32> minval, maxval) : int<32>;
</code>

These initialize the PRG and return an identifier to be used in subsequent calls to the functions below to access the generator. ''init'' initializes a random number generator of the specified bit-width, while ''init_range'' specifies an interval over which the random number is supposed to be uniformly distributed.

<code act>
function get(int<32> prg_id) : int<64>;
</code>

Returns the next random number from the generator specified by index ''prg_id''.

<code act>
function seed(int<32> prg_id; int<32> seed) : bool;
</code>

Set the seed for the random number generator ''prg_id'' to the value ''seed''. As with every other function, the result has to be saved in a dummy variable to prevent being optimized away.