Annotation for custom bit representations of data types

Using ANN pragma's you can tell the Clash compiler to use a custom bit-representation for a data type.

For example:

data Color = R | G | B
{-# ANN module (DataReprAnn
                  $(liftQ [t|Color|])
                  2
                  [ ConstrRepr 'R 0b11 0b00 []
                  , ConstrRepr 'G 0b11 0b01 []
                  , ConstrRepr 'B 0b11 0b10 []
                  ]) #-}

This specifies that R should be encoded as 0b00, G as 0b01, and B as 0b10. The first binary value in every ConstrRepr in this example is a mask, indicating which bits in the data type are relevant. In this case all of the bits are.

Or if we want to annotate Maybe Color:

{-# ANN module ( DataReprAnn
                   $(liftQ [t|Maybe Color|])
                   2
                   [ ConstrRepr 'Nothing 0b11 0b11 []
                   , ConstrRepr 'Just 0b00 0b00 [0b11]
                   ] ) #-}

By default, Maybe Color is a data type which consumes 3 bits. A single bit to indicate the constructor (either Just or Nothing), and two bits to encode the first field of Just. Notice that we saved a single bit by exploiting the fact that Color only uses three values (0, 1, 2), but takes two bits to encode it. We can therefore use the last - unused - value (3), to encode one of the constructors of Maybe. We indicate which bits encode the underlying Color field of Just by passing [0b11] to ConstrRepr. This indicates that the first field is encoded in the first and second bit of the whole datatype (0b11).

NB: BitPack for a custom encoding can be derived using deriveBitPack.

Annotation for constructors. Indicates how to match this constructor based off of the whole datatype.

BitMask used to mask fields

Lift values inside of Q to a Template Haskell expression