Convert data to/from a BitVector. This allows functions to be defined on the underlying representation of data, while exposing a nicer API using pack / unpack at the boundaries. For example:

    f :: forall a b. (BitPack a, BitPack b) => a -> b
    f = unpack . go . pack
     where
      go :: BitVector (BitSize a) -> BitVector (BitSize b)
      go = _ -- A function on the underlying bit vector

A type should only implement this class if it has a statically known size, as otherwise it is not possible to determine how many bits are needed to represent values. This means that types such as [a] cannot have BitPack instances, as even if a has a statically known size, the length of the list cannot be known in advance.

It is not possible to give data a custom bit representation by providing a BitPack instance. A BitPack instance allows no creativity and should always accurately reflect the bit representation of the data in HDL. You should always derive (Generic, BitPack) unless you use a custom data representation, in which case you should use deriveBitPack. Custom encodings can be created with Clash.Annotations.BitRepresentation and Clash.Annotations.BitRepresentation.Deriving.

If the BitPack instance does not accurately match the bit representation of the data in HDL, Clash designs will exhibit incorrect behavior in various places.

Clash provides some generic functions on packable types in the prelude, such as indexing into packable structures (see Clash.Class.BitPack.BitIndex) and bitwise reduction of packable data (see Clash.Class.BitPack.BitReduction).

Pack both arguments to a BitVector and use isLike# to compare them. This is a more lenient comparison than (==), behaving more like (but not necessarily exactly the same as) std_match in VHDL or casez in Verilog.

Unlike (==), isLike is not symmetric. The reason for this is that a defined bit is said to be like an undefined bit, but not vice-versa:

>>> isLike (12 :: Signed 8) undefined
True
>>> isLike undefined (12 :: Signed 8)
False

However, it is still trivially reflexive and transitive:

>>> :set -XTemplateHaskell
>>> let x1 = $(bLit "0010")
>>> let x2 = $(bLit "0.10")
>>> let x3 = $(bLit "0.1.")
>>> isLike x1 x1
True
>>> isLike x1 x2
True
>>> isLike x2 x3
True
>>> isLike x1 x3
True

NB: Not synthesizable

Coerce a value from one type to another through its bit representation.

>>> pack (-5 :: Signed 6)
0b11_1011
>>> bitCoerce (-5 :: Signed 6) :: Unsigned 6
59
>>> pack (59 :: Unsigned 6)
0b11_1011

Map a value by first coercing to another type through its bit representation.

>>> pack (-5 :: Signed 32)
0b1111_1111_1111_1111_1111_1111_1111_1011
>>> bitCoerceMap @(Vec 4 (BitVector 8)) (replace 1 0) (-5 :: Signed 32)
-16711685
>>> pack (-16711685 :: Signed 32)
0b1111_1111_0000_0000_1111_1111_1111_1011

Zero-extend a Boolean value to a BitVector of the appropriate size.

>>> boolToBV True :: BitVector 6
0b00_0001
>>> boolToBV False :: BitVector 6
0b00_0000

Convert a Bool to a Bit

Convert a Bit to a Bool

Get the bit at the specified bit index.

NB: Bit indices are DESCENDING.

>>> pack (7 :: Unsigned 6)
0b00_0111
>>> (7 :: Unsigned 6) ! 1
1
>>> (7 :: Unsigned 6) ! 5
0
>>> (7 :: Unsigned 6) ! 6
*** Exception: X: (!): 6 is out of range [0..5]
...

Get a slice between bit index m and and bit index n.

NB: Bit indices are DESCENDING.

>>> pack (7 :: Unsigned 6)
0b00_0111
>>> slice d4 d2 (7 :: Unsigned 6)
0b001

>>> slice d6 d4 (7 :: Unsigned 6)

<interactive>:...
    • Couldn't match type ‘7 + i0’ with ‘6’
        arising from a use of ‘slice’
        The type variable ‘i0’ is ambiguous
    • In the expression: slice d6 d4 (7 :: Unsigned 6)
      In an equation for ‘it’: it = slice d6 d4 (7 :: Unsigned 6)

Split a value of a bit size m + n into a tuple of values with size m and size n.

>>> pack (7 :: Unsigned 6)
0b00_0111
>>> split (7 :: Unsigned 6) :: (BitVector 2, BitVector 4)
(0b00,0b0111)

Set the bit at the specified index

NB: Bit indices are DESCENDING.

>>> pack (-5 :: Signed 6)
0b11_1011
>>> replaceBit 4 0 (-5 :: Signed 6)
-21
>>> pack (-21 :: Signed 6)
0b10_1011
>>> replaceBit 5 0 (-5 :: Signed 6)
27
>>> pack (27 :: Signed 6)
0b01_1011
>>> replaceBit 6 0 (-5 :: Signed 6)
*** Exception: X: replaceBit: 6 is out of range [0..5]
...

Set the bits between bit index m and bit index n.

NB: Bit indices are DESCENDING.

>>> pack (-5 :: Signed 6)
0b11_1011
>>> setSlice d4 d3 0 (-5 :: Signed 6)
-29
>>> pack (-29 :: Signed 6)
0b10_0011

>>> setSlice d6 d5 0 (-5 :: Signed 6)

<interactive>:...
    • Couldn't match type ‘7 + i0’ with ‘6’
        arising from a use of ‘setSlice’
        The type variable ‘i0’ is ambiguous
    • In the expression: setSlice d6 d5 0 (- 5 :: Signed 6)
      In an equation for ‘it’: it = setSlice d6 d5 0 (- 5 :: Signed 6)

Get the most significant bit.

>>> pack (-4 :: Signed 6)
0b11_1100
>>> msb (-4 :: Signed 6)
1
>>> pack (4 :: Signed 6)
0b00_0100
>>> msb (4 :: Signed 6)
0

Get the least significant bit.

>>> pack (-9 :: Signed 6)
0b11_0111
>>> lsb (-9 :: Signed 6)
1
>>> pack (-8 :: Signed 6)
0b11_1000
>>> lsb (-8 :: Signed 6)
0

Are all bits set to '1'?

>>> pack (-2 :: Signed 6)
0b11_1110
>>> reduceAnd (-2 :: Signed 6)
0
>>> pack (-1 :: Signed 6)
0b11_1111
>>> reduceAnd (-1 :: Signed 6)
1

Zero width types will evaluate to '1':

>>> reduceAnd (0 :: Unsigned 0)
1

Is there at least one bit set to '1'?

>>> pack (5 :: Signed 6)
0b00_0101
>>> reduceOr (5 :: Signed 6)
1
>>> pack (0 :: Signed 6)
0b00_0000
>>> reduceOr (0 :: Signed 6)
0

Zero width types will evaluate to '0':

>>> reduceOr (0 :: Unsigned 0)
0

Is the number of bits set to '1' uneven?

>>> pack (5 :: Signed 6)
0b00_0101
>>> reduceXor (5 :: Signed 6)
0
>>> pack (28 :: Signed 6)
0b01_1100
>>> reduceXor (28 :: Signed 6)
1
>>> pack (-5 :: Signed 6)
0b11_1011
>>> reduceXor (-5 :: Signed 6)
1

Zero width types will evaluate to '0':

>>> reduceXor (0 :: Unsigned 0)
0