Clash

General

• Name of function to be made top entity: topEntity
• Domain: synthesis domain
  • techmap, I guess
  • System: Useful for simulation
• Convert to VHDL: clash --vhdl MAC.hs
• Signal values represent synchronous values. ie, values that change with respect to a clock.
  • Functions without signals are purely combinatorial.
• Combinational circuits: (recursive) functions
• Sequential circuits: composition of functions together with a finite state machine like a Mealy machine.
• Clock, Reset, Enable signals are implicit by default when using HiddenClockResetEnable.
  • These signals can be exposed with functions like exposeClockResetEnable.

NFDataX

To be synthesizable, data type needs to be an instance of NFDataX, a typeclass defined in clash-prelude.

It's like NFData. NFData says that the type has a normal form (ie, is fully evaluatable and doesn't diverge). (I guess NF stands for 'normal form').

This makes the evaluation eager?

NFDataX is NFData with support for undefined values.

Simulating a Mealy machine

(cf: from here)

            +---------------+
Input  --->-|               |------> Output
            | Combinational |
            |    logic      |
        +---|               |---+
        |   +---------------+   |
Current ^                       V   Next
 state  |   +---------------+   |  state
        |   |               |   |
        +-<-|     Memory    |-<-+
            |    elements   |
            +---------------+

–

-- | Function to run a mealy machine
run _ _ []                    = []   -- no input means no output
run func state (input:inputs) = output: outputs
 where
  (output, state′) = func input state
  outputs = run func state′ inputs

-- | Transition function for a mealy machine
func :: InputSignals → State a → (OutputSignals, State a)
func input state = (output, state′)
 where
  ...
  ...

–

Type:

mealy
  :: (KnownDomain dom,
      GHC.Classes.IP (Clash.Signal.HiddenClockName dom) (Clock dom),
      GHC.Classes.IP (Clash.Signal.HiddenEnableName dom) (Enable dom),
      GHC.Classes.IP (Clash.Signal.HiddenResetName dom) (Reset dom),
      NFDataX s) =>
     (s -> i -> (s, o)) -> s -> Signal dom i -> Signal dom o


Transition function of the mealy machine:
  (s        -- ^ current state
-> i        -- ^ next input
-> (s, o))  -- ^ next state, next output (produced /during/ the transition)


   s             -- ^ initial state of mealy machine
-> Signal dom i  -- ^ input signal
-> Signal dom o  -- ^ output signal

Types

From base itself:

• Int8, Int16, Int32, Int64
• Word8, Word16, Word32, Word64

From clash-prelude:

• Bit
• Signed, Unsigned

Assign names to signals

à la ports in VHDL, I guess.

Use :::. An example: https://github.com/clash-lang/clash-compiler/pull/2584/files

Control name of ports in generated HDL

Using an annotation

• https://hackage.haskell.org/package/clash-prelude-1.8.1/docs/Clash-Annotations-TopEntity.html

Example:

{-# ANN topEntity
  (Synthesize
    { t_name   = "topEntity"
    , t_inputs = [ PortName "clk"
                 , PortName "rst"
                 , PortName "en"
                 , PortName "inp" ]
    , t_output = PortName "res"
    }) #-}

Testbenches

• Function name has to be testBench
• testBench has to be in root module

https://hackage.haskell.org/package/clash-prelude-1.8.1/docs/Clash-Tutorial.html

• outputVerifier
  • Returns True when all test cases have been tested
  • Otherwise keeps returning False
  • Also writes error message to stderr when output is not as expected

Misc

• DDR signals: https://hackage.haskell.org/package/clash-prelude-1.6.6/docs/Clash-Explicit-DDR.html
  • Special signals. Looks like they are made such that they are updated twice in a cycle when compared to normal Signal type.
• Lion: A RISC-V CPU?? made with Clash

register

register
  :: (HiddenClockResetEnable dom, NFDataX a)
  => a -> Signal dom a -> Signal dom a

Clash.Prelude> sampleN @System 5 $ register 8 $ fromList [1,2,3,4]
[8,8,2,3,4]

Bitvectors

Conversion between Bitvector and Int:

Clash.Prelude> pack (59 :: Unsigned 8)
0b0011_1011

Clash.Prelude> :t pack (59 :: Unsigned 8)
pack (59 :: Unsigned 8) :: BitVector 8

Clash.Prelude> :t pack (59 :: Unsigned 9)
pack (59 :: Unsigned 9) :: BitVector 9

Clash.Prelude> unpack 0b101 ::Signed 3
-3

Clash.Prelude> unpack 0b101 ::Unsigned 3
5

—

Some operations:

-- Bitwise OR
Clash.Prelude Prelude> (Clash.Prelude..|.) 0b1001 0b1010
11

—

bLit:

Clash.Prelude> import qualified Data.List as List
Clash.Prelude List> $(bLit (List.replicate 4 '0'))
0b1111

7 segment with clash

import Data.Char
import qualified Data.Map

a :: [(Char, Vec 7 Bool)]
--         a        b       c        d        e        f        g
a = [('0', True  :> True :> True  :> True  :> True  :> True  :> True  :> Nil),
     ('1', False :> True :> True  :> False :> False :> False :> False :> Nil),
     ('?', True  :> True :> False :> False :> True  :> False :> True  :> Nil)]
b = Data.Map.fromList a

Constructing Signal manually

Not synthesizable. Shouldn't be used in production code!!

λ> import Clash.Signal.Internal
λ> :t (1 :- 2)
(1 :- 2) :: Num a => Signal dom a

λ> 1 :: Signal System Int
1 1 1 1 1 ...............

Unknown

• CLASH_OPAQUE: From ghc itself