Documentation

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 stuctures (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 lentiant 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