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

Safe Haskell | None
Language | Haskell2010

Clash.Annotations.TH

Contents

- To create a Synthesize annotation pragma
- To create a TopEntity value
- Orphan instances

Description

This module can automatically generate TopEntity definitions from Clash.NamedTypes annotations. Annotations involving data/type families must be inspected for correctness. Not all cases can be handled with automatic generation due to the difficulty of type manipulation in template Haskell. In particular annotations inside the following is unlikely to work:

- Data/type family referencing other data/type families.
- Annotations inside recursive data types
- Clock constraints other than a single HiddenClockResetEnable. (You can still use arbitrary explicit clock/reset/enables!)

See Clash.Tests.TopEntityGeneration for more examples.

    import Clash.Annotations.TH

    data Named
      = Named
      { name1 :: "named1" ::: BitVector 3
      , name2 :: "named2" ::: BitVector 5
      }

    topEntity :: "tup1" ::: Signal System (Int, Bool)
              -> "tup2" ::: (Signal System Int, Signal System Bool)
              -> "tup3" ::: Signal System ("int":::Int, "bool":::Bool)
              -> "tup4" ::: ("int":::Signal System Int, "bool":::Signal System Bool)
              -> "custom" ::: Signal System Named
              -> "outTup" ::: Signal System ("outint":::Int, "outbool":::Bool)
    topEntity = undefined
    makeTopEntity 'topEntity
    -- ===>
    --  {-# ANN topEntity Synthesize "topEntity3"
    --     [ PortName "tup1"
    --     , PortName "tup2"
    --     , PortProduct "tup3" [PortName "int",PortName "bool"]
    --     , PortProduct "tup4" [PortName "int",PortName "bool"]
    --     , PortProduct "custom" [PortName "named1",PortName "named2"]
    --     ]
    --     (PortProduct "outTup" [PortName "outint",PortName "outbool"])
    --     #-}

Synopsis

- makeTopEntity :: Name -> DecsQ
- makeTopEntityWithName :: Name -> String -> DecsQ
- makeTopEntityWithName' :: Name -> Maybe String -> DecQ
- buildTopEntity :: Maybe String -> (Name, Type) -> TExpQ TopEntity
- maybeBuildTopEntity :: Maybe String -> Name -> Q (TExp (Maybe TopEntity))
- getNameBinding :: Name -> Q (Name, Type)

# To create a Synthesize annotation pragma

makeTopEntity :: Name -> DecsQ Source #

Automatically create a ``TopEntity`` for a given ``Name``. The name of the generated RTL entity will be the name of the function that has been specified; e.g. ``makeTopEntity` 'foobar` will generate a `foobar` module.

The function arguments and return values of the function specified by the given ``Name`` must be annotated with ``(:::)``. This annotation provides the given name of the port.

makeTopEntityWithName :: Name -> String -> DecsQ Source #

Automatically create a ``TopEntity`` for a given ``Name``, using the given ``String`` to specify the name of the generated RTL entity.

The function arguments and return values of the function specified by the given ``Name`` must be annotated with ``(:::)``. This annotation provides the given name of the port.

makeTopEntityWithName' :: Name -> Maybe String -> DecQ Source #

Wrap a `TopEntity` expression in an annotation pragma

# To create a TopEntity value

buildTopEntity :: Maybe String -> (Name, Type) -> TExpQ TopEntity Source #

Return a typed expression for a `TopEntity` of a given `(`Name`, `Type`)`.

maybeBuildTopEntity :: Maybe String -> Name -> Q (TExp (Maybe TopEntity)) Source #

Return a typed 'Maybe TopEntity' expression given a `Name`. This will return an `TExp` of `Nothing` if `TopEntity` generation failed.

getNameBinding :: Name -> Q (Name, Type) Source #

Turn the `Name` of a value to a `(`Name`, `Type`)`

# Orphan instances

Corecursive Type Source # |

Instance details

Methods

embed :: Base Type Type -> Type Source #

ana :: (a -> Base Type a) -> a -> Type Source #

apo :: (a -> Base Type (Either Type a)) -> a -> Type Source #

postpro :: Recursive Type => (forall b. Base Type b -> Base Type b) -> (a -> Base Type a) -> a -> Type Source #

gpostpro :: (Recursive Type, Monad m) => (forall b. m (Base Type b) -> Base Type (m b)) -> (forall c. Base Type c -> Base Type c) -> (a -> Base Type (m a)) -> a -> Type Source #

Recursive Type Source # |

Instance details

Methods

project :: Type -> Base Type Type Source #

cata :: (Base Type a -> a) -> Type -> a Source #

para :: (Base Type (Type, a) -> a) -> Type -> a Source #

gpara :: (Corecursive Type, Comonad w) => (forall b. Base Type (w b) -> w (Base Type b)) -> (Base Type (EnvT Type w a) -> a) -> Type -> a Source #

prepro :: Corecursive Type => (forall b. Base Type b -> Base Type b) -> (Base Type a -> a) -> Type -> a Source #

gprepro :: (Corecursive Type, Comonad w) => (forall b. Base Type (w b) -> w (Base Type b)) -> (forall c. Base Type c -> Base Type c) -> (Base Type (w a) -> a) -> Type -> a Source #