Enum rust_hdl::prelude::Bits

pub enum Bits<const N: usize> {
    // some variants omitted
}

The Bits type holds a bit array of size [N].

Implementations

impl<const N: usize> Bits<N>

pub fn any(&self) -> bool

The [any] function returns true if any of the individual bits are true, and false otherwise. This reduction operation is equivalent to a logical OR of all the bits in the vector.

let x : Bits<14> = bits(0xDEA);
assert_eq!(x.any(), true);
let y : Bits<14> = Bits::default();
assert_eq!(y.any(), false);

pub fn all(&self) -> bool

The [all] function returns true if all of the individual bits are true, and false otherwise. This reduction operation is equivalent to a logical AND of all the bits in the vector.

let x : Bits<14> = bits(0xDEA);
assert_eq!(x.all(), false);
let y : Bits<14> = bits(0x3FFF);
assert_eq!(y.all(), true);

pub fn xor(&self) -> bool

The [xor] function computes the exclusive OR of all the bits in the vector. This is equivalent to counting the number of ones. If the number is odd, the XOR will be true. If even, it will be false.

let x: Bits<12> = bits(0b1100_0100_1100);
assert_eq!(x.xor(), true);
let y: Bits<12> = bits(0b1100_0110_1100);
assert_eq!(y.xor(), false);

pub fn index(&self) -> usize

The [index] function is used when a Bits is going to be used to index into an array or some other bit vector. This is typically a very specialized hardware operation, so there are limited cases in which it can be used. Also, there is an assumption that the Bits being used as an index is sufficiently small to fit in a natural word (assume 32 bits, here for safety). In practice, that means, that if you are indexing into a register using some other register/value, the length of the register is limited to a few billion bits.

let x: Bits<12> = bits(0b1100_0100_1100);
assert_eq!(x.index(), 0b1100_0100_1100_usize);

pub fn len(&self) -> usize

Return the number of bits in the current Bits. Because this is determined at compile time, it is of limited use as a runtime function, but is there nonetheless.

let x : Bits<14> = Bits::default();
assert_eq!(x.len(), 14);

pub fn is_empty(&self) -> bool

Return true if this Bits contains no actual bits (i.e., N = 0).

pub fn count() -> u128

Compute the number of possible values that a Bits can take. This is basically 2 raised to the Nth power. Because the result is returned as a usize, you must be careful, since this can easily overflow. A Bits<256> for example, cannot represent [count] on a normal 64 bit machine.

assert_eq!(Bits::<16>::count(), 1 << 16);

pub fn get_bit(&self, index: usize) -> bool

Extract the [index] bit from the given Bits. This will cause a runtime panic if the [index] bit is out of range of the width of the bitvector.

let x : Bits<14> = bits(0b10110);
assert_eq!(x.get_bit(0), false);
assert_eq!(x.get_bit(1), true);
assert_eq!(x.get_bit(2), true); // You get the idea

pub fn replace_bit(&self, index: usize, val: bool) -> Bits<N>

Replace the given bit of a Bits with a new bit value. This method leaves the original value alone, and returns a new Bits with all bits except the designated one left alone.

let x: Bits<16> = bits(0b1100_0000);
let x = x.replace_bit(0, true);
let x = x.replace_bit(7, false);
assert_eq!(x, bits(0b0100_0001));

pub fn get_bits<const M: usize>(&self, index: usize) -> Bits<M>

Return a subset of bits from a Bits value, with a given offset. To preserve the feasibility of representing this in hardware, the width of the result must be fixed (the argument [M]), and only the offset can be computed.

let x: Bits<40> = bits(0xDEAD_BEEF_CA);
let y = x.get_bits::<32>(8);
assert_eq!(y, bits(0xDEAD_BEEF))

pub fn set_bits<const M: usize>(&mut self, index: usize, rhs: Bits<M>)

Set a group of bits in a value. This operation modifies the value in place.

let mut x: Bits<40> = bits(0xDEAD_BEEF_CA);
x.set_bits::<16>(8, bits(0xCAFE));
assert_eq!(x, bits(0xDEAD_CAFE_CA));

pub fn mask() -> Bits<N>

Returns a Bits value that contains [N] ones.

let x = Bits::<40>::mask();
assert_eq!(x, bits(0xFF_FFFF_FFFF));

pub const fn width() -> usize

Returns the width in bits of the [BitVec]. Note that this is the number of bits allocated. It does not depend on the value at all.

assert_eq!(Bits::<40>::width(), 40);

pub fn to_u8(self) -> u8

Convert Bits to an u8.

let x : Bits<6> = 12.into();
let y = x.to_u8();
assert_eq!(y, 12_u8);

Note that this will panic if the width of the bitvector is larger than 8 bits.

let x: Bits<12> = 0xADE.into();
let y = x.to_u8(); // Panics - too many bits

pub fn to_u16(self) -> u16

Convert Bits to an u16.

let x : Bits<12> = 12.into();
let y = x.to_u16();
assert_eq!(y, 12_u16);

Note that this will panic if the width of the bitvector is larger than 16 bits.

let x: Bits<20> = 0xADE.into();
let y = x.to_u16(); // Panics - too many bits

pub fn to_u32(self) -> u32

Convert Bits to an u32.

let x : Bits<24> = 12.into();
let y = x.to_u32();
assert_eq!(y, 12_u32);

Note that this will panic if the width of the bitvector is larger than 32 bits.

let x: Bits<40> = 0xADE.into();
let y = x.to_u32(); // Panics - too many bits

pub fn to_u64(self) -> u64

Convert Bits to an u64.

let x : Bits<40> = 12.into();
let y = x.to_u64();
assert_eq!(y, 12_u64);

Note that this will panic if the width of the bitvector is larger than 64 bits.

let x: Bits<80> = 0xADE.into();
let y = x.to_u64(); // Panics - too many bits

pub fn to_u128(self) -> u128

Convert Bits to an u128.

let x : Bits<80> = 12.into();
let y = x.to_u128();
assert_eq!(y, 12_u128);

Note that this will panic if the width of the bitvector is larger than 128 bits.

let x: Bits<140> = 0xADE.into();
let y = x.to_u128(); // Panics - too many bits

Trait Implementations

impl<const N: usize> Add<u64> for Bits<N>

type Output = Bits<N>

The resulting type after applying the + operator.

fn add(self, rhs: u64) -> <Bits<N> as Add<u64>>::Output

Performs the + operation.

impl<const N: usize> Binary for Bits<N>

Allows you to format a Bits as a binary string

let y = Bits::<16>::from(0b1011_0100_0010_0000);
println!("y = {:b}", y); // Prints y = 1011010000100000

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<const N: usize> BitAnd<u64> for Bits<N>

type Output = Bits<N>

The resulting type after applying the & operator.

fn bitand(self, rhs: u64) -> <Bits<N> as BitAnd<u64>>::Output

Performs the & operation.

impl<const N: usize> BitOr<u64> for Bits<N>

type Output = Bits<N>

The resulting type after applying the | operator.

fn bitor(self, rhs: u64) -> <Bits<N> as BitOr<u64>>::Output

Performs the | operation.

impl<const N: usize> BitXor<u64> for Bits<N>

type Output = Bits<N>

The resulting type after applying the ^ operator.

fn bitxor(self, rhs: u64) -> <Bits<N> as BitXor<u64>>::Output

Performs the ^ operation.

impl<const N: usize> Clone for Bits<N>

fn clone(&self) -> Bits<N>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<const N: usize> Debug for Bits<N>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<const N: usize> Default for Bits<N>

Construct a default Bits - i.e., a zero bit vector of length N.

let x : Bits<200> = Default::default();
assert_eq!(x, bits(0));

fn default() -> Bits<N>

Returns the “default value” for a type.

impl<const N: usize> From<BigUint> for Bits<N>

Convert from a BigUint to a Bits. Will panic if the number of bits needed to represent the value are greater than the width of the Bits.

let x = BigUint::parse_bytes(b"10111000101", 2).unwrap();
let y : Bits<16> = x.into();
println!("y = {:x}", y); // Prints y = 02c5

The following will panic, because the value cannot be represented in the given number of bits.

let x = BigUint::parse_bytes(b"10111000101", 2).unwrap();
let y : Bits<12> = x.into(); // Panics

fn from(x: BigUint) -> Bits<N>

Converts to this type from the input type.

impl<const N: usize> From<Wrapping<u64>> for Bits<N>

fn from(x: Wrapping<u64>) -> Bits<N>

Converts to this type from the input type.

impl From<bool> for Bits<1>

fn from(x: bool) -> Bits<1>

Convenience method that allows you to convert a boolean into a single bit-width Bits.

let x : Bits<1> = true.into();
assert_eq!(x, bits(1))

impl<const N: usize> From<u64> for Bits<N>

Convert from LiteralType to Bits. Because of some restrictions on how Rust’s type inference works, when you work with unsized literals (e.g., x = 3), there must either be a unique integer type that can fit the expression, or it will default to i32. Unfortunately, in general, Bits are used to represent unsigned types. The upshot of all this is that RustHDL selects one unsigned integer type to represent literals. Although not ideal, RustHDL uses a LiteralType (currently ‘u64’) to represent literals so as to make HDL expressions close to Verilog or VHDL. This choice should not affect any hardware implementation, as hardware registers need to be of Bits type.

let x: Bits<16> = 0xDEAD.into(); // This is interpreteed as a 128 bit constant by Rust

This example is the largest bit width literal you can express using current edition Rust:

let x: Bits<128> = 0xDEADBEEF_CAFEBABE_1234ABCD_00005EA1_u128.to_bits();

From a safety perspective, RustHDL will panic if the argument is too large to fit into the bit vector. Thus, this example will panic, since the literal cannot be fit into 16 bits without truncation:

let x: Bits<16> = 0xDEADBEEF.into(); // This will panic!

fn from(x: u64) -> Bits<N>

Converts to this type from the input type.

impl Into<Bits<rust_hdl_widgets::::sdram::cmd::{impl#8}::{constant#0}>> for SDRAMCommand

fn into( self ) -> Bits<rust_hdl_widgets::::sdram::cmd::{impl#8}::into::{constant#0}>

Converts this type into the (usually inferred) input type.

impl<const N: usize> LowerHex for Bits<N>

Allows you to format a Bits as a lowercase hex string

let y = Bits::<16>::from(0xcafe);
println!("y = {:x}", y); // Prints y = cafe

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Mul<Bits<16>> for Bits<16>

Multipliers are special, so we only implement multipliers that we think are synthesizable. In this case, we implement a 16 x 16 bit multiplier which yields a 32 bit result.

type Output = Bits<32>

The resulting type after applying the * operator.

fn mul(self, rhs: Bits<16>) -> <Bits<16> as Mul<Bits<16>>>::Output

Performs the * operation.

impl<const N: usize> Not for Bits<N>

Bitwise inversion of a Bits vector The ! operator will invert each bit in a Bits vector.

let x : Bits<16> = bits(0xAAAA);
let y = !x;
assert_eq!(y, bits(0x5555))

type Output = Bits<N>

The resulting type after applying the ! operator.

fn not(self) -> <Bits<N> as Not>::Output

Performs the unary ! operation.

impl<const M: usize, const N: usize> Shl<Bits<M>> for Bits<N>

type Output = Bits<N>

The resulting type after applying the << operator.

fn shl(self, rhs: Bits<M>) -> <Bits<N> as Shl<Bits<M>>>::Output

Performs the << operation.

impl<const N: usize> Shl<u64> for Bits<N>

type Output = Bits<N>

The resulting type after applying the << operator.

fn shl(self, rhs: u64) -> <Bits<N> as Shl<u64>>::Output

Performs the << operation.

impl<const M: usize, const N: usize> Shr<Bits<M>> for Bits<N>

type Output = Bits<N>

The resulting type after applying the >> operator.

fn shr(self, rhs: Bits<M>) -> <Bits<N> as Shr<Bits<M>>>::Output

Performs the >> operation.

impl<const N: usize> Shr<u64> for Bits<N>

type Output = Bits<N>

The resulting type after applying the >> operator.

fn shr(self, rhs: u64) -> <Bits<N> as Shr<u64>>::Output

Performs the >> operation.

impl<const N: usize> Sub<u64> for Bits<N>

type Output = Bits<N>

The resulting type after applying the - operator.

fn sub(self, rhs: u64) -> <Bits<N> as Sub<u64>>::Output

Performs the - operation.

impl<const N: usize> Synth for Bits<N>

const BITS: usize = N

fn descriptor() -> TypeDescriptor

fn vcd(self) -> VCDValue

fn verilog(self) -> VerilogLiteral

fn bits(self) -> usize

impl<const N: usize> UpperHex for Bits<N>

Allows you to format a Bits as an uppercase hex string

let y = Bits::<16>::from(0xcafe);
println!("y = {:X}", y); // Prints y = CAFE

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<const N: usize> Copy for Bits<N>