DSLX Standard Library
This page documents the DSLX standard library.
std.x
Bits Type Properties
std::?_min_value
pub fn unsigned_min_value<N: u32>() -> uN[N]
pub fn signed_min_value<N: u32>() -> sN[N]
Returns the minimum signed or unsigned value contained in N bits.
std::?_max_value
pub fn unsigned_max_value<N: u32>() -> uN[N];
pub fn signed_max_value<N: u32>() -> sN[N];
Returns the maximum signed or unsigned value contained in N bits.
std::sizeof_?
pub fn sizeof_unsigned<N: u32>(x : uN[N]) -> u32
pub fn sizeof_signed<N: u32>(x : sN[N]) -> u32
Returns the number of bits (sizeof) of unsigned or signed bit value.
Bit Manipulation Functions
std::lsb
pub fn lsb<N: u32>(x: uN[N]) -> u1
Extracts the LSB (Least Significant Bit) from the value x and returns it.
std::convert_to_bits_msb0
pub fn convert_to_bits_msb0<N: u32>(x: bool[N]) -> uN[N]
Converts an array of N bools to a bits[N] value.
Note well: the boolean value at index 0 of the array becomes the most significant bit in the resulting bit value. Similarly, the last index of the array becomes the least significant bit in the resulting bit value.
import std
#[test]
fn convert_to_bits_test() {
let _ = assert_eq(u3:0b001, std::convert_to_bits(bool[3]:[false, false, true]));
let _ = assert_eq(u3:0b100, std::convert_to_bits(bool[3]:[true, false, false]));
()
}
There's always a source of confusion in these orderings:
- Mathematically we often indicate the least significant digit as "digit 0"
- But, in a number as we write the digits from left-to-right on a piece of paper, if you made an array from the written characters, the digit at "array index 0" would be the most significant bit.
So, it's somewhat ambiguous whether "index 0" in the array would become the
least significant bit or the most significant bit. This routine uses the "as it
looks on paper" conversion; e.g. [true, false, false] becomes 0b100.
std::convert_to_bools_lsb0
pub fn fn convert_to_bools_lsb0<N:u32>(x: uN[N]) -> bool[N]
Convert a "word" of bits to a corresponding array of booleans.
Note well: The least significant bit of the word becomes index 0 in the array.
std::mask_bits
pub fn mask_bits<X: u32>() -> bits[X]
Returns a value with X bits set (of type bits[X]).
std::concat3
pub fn concat3<X: u32, Y: u32, Z: u32, R: u32 = X + Y + Z>(x: bits[X], y: bits[Y], z: bits[Z]) -> bits[R]
Concatenates 3 values of arbitrary bitwidths to a single value.
std::rrot
pub fn rrot<N: u32>(x: bits[N], y: bits[N]) -> bits[N]
Rotate x right by y bits.
std::popcount
pub fn popcount<N: u32>(x: bits[N]) -> bits[N]
Counts the number of bits in x that are '1'.
Mathematical Functions
std::bounded_minus_1
pub fn bounded_minus_1<N: u32>(x: uN[N]) -> uN[N]
Returns the value of x - 1 with saturation at 0.
std::abs
pub fn abs<BITS: u32>(x: sN[BITS]) -> sN[BITS]
Returns the absolute value of x as a signed number.
std::is_pow2
pub fn is_pow2<N: u32>(x: uN[N]) -> bool
Returns true when x is a non-zero power-of-two.
std::?mul
pub fn umul<N: u32, M: u32, R: u32 = N + M>(x: uN[N], y: uN[M]) -> uN[R]
pub fn smul<N: u32, M: u32, R: u32 = N + M>(x: sN[N], y: sN[M]) -> sN[R]
Returns product of x (N bits) and y (M bits) as an N+M bit value.
std::iterative_div
pub fn iterative_div<N: u32, DN: u32 = N * u32:2>(x: uN[N], y: uN[N]) -> uN[N]
Calculate x / y one bit at a time. This is an alternative to using the
division operator '/' which may not synthesize nicely.
std::div_pow2
pub fn div_pow2<N: u32>(x: bits[N], y: bits[N]) -> bits[N]
Returns x / y where y must be a non-zero power-of-two.
std::mod_pow2
pub fn mod_pow2<N: u32>(x: bits[N], y: bits[N]) -> bits[N]
Returns x % y where y must be a non-zero power-of-two.
std::ceil_div
pub fn ceil_div<N: u32>(x: uN[N], y: uN[N]) -> uN[N]
Returns the ceiling of (x divided by y).
std::round_up_to_nearest
pub fn round_up_to_nearest(x: u32, y: u32) -> u32
Returns x rounded up to the nearest multiple of y.
std::?pow
pub fn upow<N: u32>(x: uN[N], n: uN[N]) -> uN[N]
pub fn spow<N: u32>(x: sN[N], n: uN[N]) -> sN[N]
Performs integer exponentiation as in Hacker's Delight, Section 11-3. Only non-negative exponents are allowed, hence the uN parameter for spow.
std::clog2
pub fn clog2<N: u32>(x: bits[N]) -> bits[N]
Returns ceiling(log2(x)), with one exception: When x = 0, this function
differs from the true mathematical function: clog2(0) = 0 where as
ceil(log2(0)) = -infinity
This function is frequently used to calculate the number of bits required to
represent x possibilities. With this interpretation, it is sensible to define
clog2(0) = 0.
Example: clog2(7) = 3.
std:flog2
pub fn flog2<N: u32>(x: bits[N]) -> bits[N]
Returns floor(log2(x)), with one exception:
When x=0, this function differs from the true mathematical function: flog2(0) =
0 where as floor(log2(0)) = -infinity
This function is frequently used to calculate the number of bits required to
represent an unsigned integer n to define flog2(0) = 0, so that flog(n)+1
represents the number of bits needed to represent the n.
Example: flog2(7) = 2, flog2(8) = 3.
std::?max
pub fn smax<N: u32>(x: sN[N], y: sN[N]) -> sN[N]
pub fn umax<N: u32>(x: uN[N], y: uN[N]) -> uN[N]
Returns the maximum of two integers.
std::umin
pub fn umin<N: u32>(x: uN[N], y: uN[N]) -> uN[N]
Returns the minimum of two unsigned integers.
Misc Functions
Signed comparison - std::{sge, sgt, sle, slt}
pub fn sge<N: u32>(x: uN[N], y: uN[N]) -> bool
pub fn sgt<N: u32>(x: uN[N], y: uN[N]) -> bool
pub fn sle<N: u32>(x: uN[N], y: uN[N]) -> bool
pub fn slt<N: u32>(x: uN[N], y: uN[N]) -> bool
Explicit signed comparison helpers for working with unsigned values, can be a bit more convenient and a bit more explicit intent than doing casting of left hand side and right hand side.
std::find_index
pub fn find_index<BITS: u32, ELEMS: u32>( array: uN[BITS][ELEMS], x: uN[BITS]) -> (bool, u32)
Returns (found, index) given an array and the element to find within the
array.
Note that when found is false, the index is 0 -- 0 is provided instead
of a value like -1 to prevent out-of-bounds accesses from occurring if the
index is used in a match expression (which will eagerly evaluate all of its
arms), to prevent it from creating an error at simulation time if the value is
ultimately discarded from the unselected match arm.
acm_random.x
Port of ACM random number generator to DSLX.
DO NOT use acm_random.x for any application where security -- unpredictability
of subsequent output and previous output -- is needed. ACMRandom is in NO
WAY a cryptographically secure pseudorandom number generator, and using it
where recipients of its output may wish to guess earlier/later output values
would be very bad.
acm_random::rng_deterministic_seed
pub fn rng_deterministic_seed() -> u32
Returns a fixed seed for use in the random number generator.
acm_random::rng_new
pub fn rng_new(seed: u32) -> State
Create the state for a new random number generator using the given seed.
acm_random::rng_next
pub fn rng_next(s: State) -> (State, u32)
Returns a pseudo-random number in the range [1, 2^31-2].
Note that this is one number short on both ends of the full range of
non-negative 32-bit integers, which range from 0 to 2^31-1.
acm_random::rng_next64
pub fn rng_next(s: State) -> (State, u64)
Returns a pseudo random number in the range [1, (2^31-2)^2].
Note that this does not cover all non-negative values of int64, which range from
0 to 2^63-1. The top two bits are ALWAYS ZERO.