clash-prelude-1.8.4: Clash: a functional hardware description language - Prelude library

Copyright | (C) 2018 Google Inc.
License | BSD2 (see the file LICENSE)
Maintainer | Christiaan Baaij <christiaan.baaij@gmail.com>
Safe Haskell | None
Language | Haskell2010

Clash.Annotations.BitRepresentation

Contents

- Data structures to express a custom bit representation
- Convenience type synonyms for Integer
- Functions

Description

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

Synopsis

- data DataReprAnn = DataReprAnn Type Size [ConstrRepr]
- data ConstrRepr = ConstrRepr Name BitMask Value [FieldAnn]
- type BitMask = Integer
- type Value = Integer
- type Size = Int
- type FieldAnn = BitMask
- liftQ :: Lift a => Q a -> Q Exp

# Data structures to express a custom bit representation

data DataReprAnn Source #

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`.

Constructors

DataReprAnn Type Size [ConstrRepr] |

#### Instances

Instances details

Data DataReprAnn Source # |

Instance details

Defined in Clash.Annotations.BitRepresentation

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> DataReprAnn -> c DataReprAnn Source #

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c DataReprAnn Source #

toConstr :: DataReprAnn -> Constr Source #

dataTypeOf :: DataReprAnn -> DataType Source #

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c DataReprAnn) Source #

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c DataReprAnn) Source #

gmapT :: (forall b. Data b => b -> b) -> DataReprAnn -> DataReprAnn Source #

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> DataReprAnn -> r Source #

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> DataReprAnn -> r Source #

gmapQ :: (forall d. Data d => d -> u) -> DataReprAnn -> [u] Source #

gmapQi :: Int -> (forall d. Data d => d -> u) -> DataReprAnn -> u Source #

gmapM :: Monad m => (forall d. Data d => d -> m d) -> DataReprAnn -> m DataReprAnn Source #

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> DataReprAnn -> m DataReprAnn Source #

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> DataReprAnn -> m DataReprAnn Source #

Generic DataReprAnn Source # |

Instance details

Defined in Clash.Annotations.BitRepresentation

Associated Types

type Rep DataReprAnn |

Instance details

Defined in Clash.Annotations.BitRepresentation

type Rep DataReprAnn = D1 ('MetaData "DataReprAnn" "Clash.Annotations.BitRepresentation" "clash-prelude-1.8.4-1CKHk9HHRNIGPqhYHQsmcW" 'False) (C1 ('MetaCons "DataReprAnn" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Type) :*: (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Size) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [ConstrRepr]))))

Methods

from :: DataReprAnn -> Rep DataReprAnn x Source #

to :: Rep DataReprAnn x -> DataReprAnn Source #

Show DataReprAnn Source # |
Instance details Defined in Clash.Annotations.BitRepresentation Methods showsPrec :: Int -> DataReprAnn -> ShowS Source # show :: DataReprAnn -> String Source # showList :: [DataReprAnn] -> ShowS Source #
Eq DataReprAnn Source # |
Instance details Defined in Clash.Annotations.BitRepresentation Methods (==) :: DataReprAnn -> DataReprAnn -> Bool Source # (/=) :: DataReprAnn -> DataReprAnn -> Bool Source #
Lift DataReprAnn Source # |
Instance details Defined in Clash.Annotations.BitRepresentation Methods lift :: Quote m => DataReprAnn -> m Exp Source # liftTyped :: forall (m :: Type -> Type). Quote m => DataReprAnn -> Code m DataReprAnn Source #
type Rep DataReprAnn Source # |

Instance details

Defined in Clash.Annotations.BitRepresentation

type Rep DataReprAnn = D1 ('MetaData "DataReprAnn" "Clash.Annotations.BitRepresentation" "clash-prelude-1.8.4-1CKHk9HHRNIGPqhYHQsmcW" 'False) (C1 ('MetaCons "DataReprAnn" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Type) :*: (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Size) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [ConstrRepr]))))

data ConstrRepr Source #

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

Constructors

ConstrRepr Name BitMask Value [FieldAnn] |

#### Instances

Instances details

Data ConstrRepr Source # |

Instance details

Defined in Clash.Annotations.BitRepresentation

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> ConstrRepr -> c ConstrRepr Source #

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c ConstrRepr Source #

toConstr :: ConstrRepr -> Constr Source #

dataTypeOf :: ConstrRepr -> DataType Source #

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c ConstrRepr) Source #

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c ConstrRepr) Source #

gmapT :: (forall b. Data b => b -> b) -> ConstrRepr -> ConstrRepr Source #

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> ConstrRepr -> r Source #

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> ConstrRepr -> r Source #

gmapQ :: (forall d. Data d => d -> u) -> ConstrRepr -> [u] Source #

gmapQi :: Int -> (forall d. Data d => d -> u) -> ConstrRepr -> u Source #

gmapM :: Monad m => (forall d. Data d => d -> m d) -> ConstrRepr -> m ConstrRepr Source #

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> ConstrRepr -> m ConstrRepr Source #

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> ConstrRepr -> m ConstrRepr Source #

Generic ConstrRepr Source # |

Instance details

Defined in Clash.Annotations.BitRepresentation

Associated Types

type Rep ConstrRepr |

Instance details

Defined in Clash.Annotations.BitRepresentation

type Rep ConstrRepr = D1 ('MetaData "ConstrRepr" "Clash.Annotations.BitRepresentation" "clash-prelude-1.8.4-1CKHk9HHRNIGPqhYHQsmcW" 'False) (C1 ('MetaCons "ConstrRepr" 'PrefixI 'False) ((S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Name) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 BitMask)) :*: (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Value) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [FieldAnn]))))

Methods

from :: ConstrRepr -> Rep ConstrRepr x Source #

to :: Rep ConstrRepr x -> ConstrRepr Source #

Show ConstrRepr Source # |
Instance details Defined in Clash.Annotations.BitRepresentation Methods showsPrec :: Int -> ConstrRepr -> ShowS Source # show :: ConstrRepr -> String Source # showList :: [ConstrRepr] -> ShowS Source #
Eq ConstrRepr Source # |
Instance details Defined in Clash.Annotations.BitRepresentation Methods (==) :: ConstrRepr -> ConstrRepr -> Bool Source # (/=) :: ConstrRepr -> ConstrRepr -> Bool Source #
Lift ConstrRepr Source # |
Instance details Defined in Clash.Annotations.BitRepresentation Methods lift :: Quote m => ConstrRepr -> m Exp Source # liftTyped :: forall (m :: Type -> Type). Quote m => ConstrRepr -> Code m ConstrRepr Source #
type Rep ConstrRepr Source # |

Instance details

Defined in Clash.Annotations.BitRepresentation

type Rep ConstrRepr = D1 ('MetaData "ConstrRepr" "Clash.Annotations.BitRepresentation" "clash-prelude-1.8.4-1CKHk9HHRNIGPqhYHQsmcW" 'False) (C1 ('MetaCons "ConstrRepr" 'PrefixI 'False) ((S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Name) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 BitMask)) :*: (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Value) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [FieldAnn]))))

# Convenience type synonyms for Integer

type BitMask = Integer Source #

type Value = Integer Source #

type Size = Int Source #

type FieldAnn = BitMask Source #

BitMask used to mask fields

# Functions

liftQ :: Lift a => Q a -> Q Exp Source #

Lift values inside of `Q` to a Template Haskell expression