Clash.Magic

Control naming and deduplication in the generated HDL code. Explicitly nameable things include:

• Component (VHDL) / module ((System)Verilog) instances
• Registers
• Terms

Refer to Clash.Annotations.TopEntity for controlling naming of entities (VHDL) / modules ((System)Verilog) and their ports.

Functions to control names of identifiers in HDL

prefixName :: forall (name :: Symbol) a. a -> name ::: a

Prefix instance and register names with the given Symbol

suffixName :: forall (name :: Symbol) a. a -> name ::: a

Suffix instance and register names with the given Symbol

suffixNameP :: forall (name :: Symbol) a. a -> name ::: a

Suffix instance and register names with the given Symbol, but add it in front of other suffixes.

When you write

suffixName @"A" (suffixName @"B" f))

you get register and instance names inside f with the suffix: "_B_A"

However, if you want them in the other order you can write:

suffixNameP @"A" (suffixName @"B" f))

so that names inside f will have the suffix "_A_B"

suffixNameFromNat :: forall (name :: Nat) a. a -> name ::: a

Suffix instance and register names with the given Nat

suffixNameFromNatP :: forall (name :: Nat) a. a -> name ::: a

Suffix instance and register names with the given Nat, but add it in front of other suffixes.

When you write

suffixNameNat @1 (suffixName @"B" f))

you get register and instance names inside f with the suffix: "_B_1"

However, if you want them in the other order you can write:

suffixNameNatP @1 (suffixName @"B" f))

so that names inside f will have the suffix "_1_B"

setName :: forall (name :: Symbol) a. a -> name ::: a

Name the instance or register with the given Symbol, instead of using an auto-generated name. Pre- and suffixes annotated with prefixName and suffixName will be added to both instances and registers named with setName and instances and registers that are auto-named.

nameHint

Arguments

:: SSymbol sym

A hint for a name

-> a

-> a

Name a given term, such as one of type Signal, using the given SSymbol. Results in a declaration with the name used as the identifier in the generated HDL code.

Example usage:

nameHint (SSymbol @"identifier") term

NB: The given name should be considered a hint as it may be expanded, e.g. if it collides with existing identifiers.

Functions to control Clash's (de)duplication mechanisms

deDup :: forall a. a -> a

Force deduplication, i.e. share a function or operator between multiple branches.

By default Clash converts

case x of
  A -> 3 * y
  B -> x * x

to

let f_arg0 = case x of {A -> 3; _ -> x}
    f_arg1 = case x of {A -> y; _ -> x}
    f_out  = f_arg0 * f_arg1
in  case x of
      A -> f_out
      B -> f_out

However, it won't do this for:

case x of
  A -> 3 + y
  B -> x + x

Because according to the internal heuristics the multiplexer introduced for the deduplication are more expensive than the addition. This might not be the case for your particular platform.

In these cases you can force Clash to deduplicate by:

case x of
  A -> deDup (3 + y)
  B -> deDup (x + x)

noDeDup :: forall a. a -> a

Do not deduplicate, i.e. keep, an applied function inside a case-alternative; do not try to share the function between multiple branches.

By default Clash converts

case x of
  A -> f 3 y
  B -> f x x
  C -> h x

to

let f_arg0 = case x of {A -> 3; _ -> x}
    f_arg1 = case x of {A -> y; _ -> x}
    f_out  = f f_arg0 f_arg1
in  case x of
      A -> f_out
      B -> f_out
      C -> h x

i.e. it deduplicates functions (and operators such as multiplication) between case-alternatives to save on area. This comes at the cost of multiplexing the arguments for the deduplicated function.

There are two reasons you would want to stop Clash from doing this:

1. The deduplicated function is in the critical path, and the addition of the multiplexers further increased the propagation delay.
2. Clash's heuristics were off, and the addition of the multiplexers actually made the final circuit larger instead of smaller.

In these cases you want to tell Clash not to deduplicate:

case x of
  A -> noDeDup f 3 y
  B -> f x x
  C -> h x

Where the application of f in the A-alternative is now explicitly not deduplicated, and given that the f in the B-alternative is the only remaining application of f in the case-expression it is also not deduplicated.

Note that if the C-alternative also had an application of f, then the applications of f in the B- and C-alternatives would have been deduplicated; i.e. the final circuit would have had two application of f.

Utilities to differentiate between simulation and generating HDL

clashSimulation :: Bool

True in Haskell/Clash simulation. Replaced by False when generating HDL.

data SimOnly a

A container for data you only want to have around during simulation and is ignored during synthesis. Useful for carrying around things such as:

• A map of simulation/vcd traces
• Co-simulation state or meta-data
• etc.

Constructors

SimOnly a

Instances

Monad SimOnly

Defined in Clash.Magic

Methods

(>>=) :: SimOnly a -> (a -> SimOnly b) -> SimOnly b

(>>) :: SimOnly a -> SimOnly b -> SimOnly b

return :: a -> SimOnly a

Functor SimOnly

Defined in Clash.Magic

Methods

fmap :: (a -> b) -> SimOnly a -> SimOnly b

(<$) :: a -> SimOnly b -> SimOnly a

Applicative SimOnly

Defined in Clash.Magic

Methods

pure :: a -> SimOnly a

(<*>) :: SimOnly (a -> b) -> SimOnly a -> SimOnly b

liftA2 :: (a -> b -> c) -> SimOnly a -> SimOnly b -> SimOnly c

(*>) :: SimOnly a -> SimOnly b -> SimOnly b

(<*) :: SimOnly a -> SimOnly b -> SimOnly a

Foldable SimOnly

Defined in Clash.Magic

Methods

fold :: Monoid m => SimOnly m -> m

foldMap :: Monoid m => (a -> m) -> SimOnly a -> m

foldMap' :: Monoid m => (a -> m) -> SimOnly a -> m

foldr :: (a -> b -> b) -> b -> SimOnly a -> b

foldr' :: (a -> b -> b) -> b -> SimOnly a -> b

foldl :: (b -> a -> b) -> b -> SimOnly a -> b

foldl' :: (b -> a -> b) -> b -> SimOnly a -> b

foldr1 :: (a -> a -> a) -> SimOnly a -> a

foldl1 :: (a -> a -> a) -> SimOnly a -> a

toList :: SimOnly a -> [a]

null :: SimOnly a -> Bool

length :: SimOnly a -> Int

elem :: Eq a => a -> SimOnly a -> Bool

maximum :: Ord a => SimOnly a -> a

minimum :: Ord a => SimOnly a -> a

sum :: Num a => SimOnly a -> a

product :: Num a => SimOnly a -> a

Traversable SimOnly

Defined in Clash.Magic

Methods

traverse :: Applicative f => (a -> f b) -> SimOnly a -> f (SimOnly b)

sequenceA :: Applicative f => SimOnly (f a) -> f (SimOnly a)

mapM :: Monad m => (a -> m b) -> SimOnly a -> m (SimOnly b)

sequence :: Monad m => SimOnly (m a) -> m (SimOnly a)

Eq a => Eq (SimOnly a)

Defined in Clash.Magic

Methods

(==) :: SimOnly a -> SimOnly a -> Bool

(/=) :: SimOnly a -> SimOnly a -> Bool

Ord a => Ord (SimOnly a)

Defined in Clash.Magic

Methods

compare :: SimOnly a -> SimOnly a -> Ordering

(<) :: SimOnly a -> SimOnly a -> Bool

(<=) :: SimOnly a -> SimOnly a -> Bool

(>) :: SimOnly a -> SimOnly a -> Bool

(>=) :: SimOnly a -> SimOnly a -> Bool

max :: SimOnly a -> SimOnly a -> SimOnly a

min :: SimOnly a -> SimOnly a -> SimOnly a

Semigroup a => Semigroup (SimOnly a)

Defined in Clash.Magic

Methods

(<>) :: SimOnly a -> SimOnly a -> SimOnly a

sconcat :: NonEmpty (SimOnly a) -> SimOnly a

stimes :: Integral b => b -> SimOnly a -> SimOnly a

Monoid a => Monoid (SimOnly a)

Defined in Clash.Magic

Methods

mempty :: SimOnly a

mappend :: SimOnly a -> SimOnly a -> SimOnly a

mconcat :: [SimOnly a] -> SimOnly a

Static assertions

clashCompileError :: forall a. HasCallStack => String -> a

Same as error but will make HDL generation fail if included in the final circuit.

This is useful for the error case of static assertions.

Note that the error message needs to be a literal, and during HDL generation the error message does not include a stack trace, so it had better be descriptive.