Create a synchronous function from a combinational function describing a mealy machine

import qualified Data.List as L

macT
  :: Int        -- Current state
  -> (Int,Int)  -- Input
  -> (Int,Int)  -- (Updated state, output)
macT s (x,y) = (s',s)
  where
    s' = x * y + s

mac
  :: Clock domain Source
  -> Reset domain Asynchronous
  -> Signal domain (Int, Int)
  -> Signal domain Int
mac clk rst = mealy clk rst macT 0

>>> simulate (mac systemClockGen systemResetGen) [(1,1),(2,2),(3,3),(4,4)]
[0,1,5,14...
...

Synchronous sequential functions can be composed just like their combinational counterpart:

dualMac
  :: Clock domain gated -> Reset domain synchronous
  -> (Signal domain Int, Signal domain Int)
  -> (Signal domain Int, Signal domain Int)
  -> Signal domain Int
dualMac clk rst (a,b) (x,y) = s1 + s2
  where
    s1 = mealy clk rst mac 0 (bundle (a,x))
    s2 = mealy clk rst mac 0 (bundle (b,y))

A version of mealy that does automatic Bundleing

Given a function f of type:

f :: Int -> (Bool,Int) -> (Int,(Int,Bool))

When we want to make compositions of f in g using mealy', we have to write:

g clk rst a b c = (b1,b2,i2)
  where
    (i1,b1) = unbundle (mealy clk rst f 0 (bundle (a,b)))
    (i2,b2) = unbundle (mealy clk rst f 3 (bundle (i1,c)))

Using mealyB' however we can write:

g clk rst a b c = (b1,b2,i2)
  where
    (i1,b1) = mealyB clk rst f 0 (a,b)
    (i2,b2) = mealyB clk rst f 3 (i1,c)

Create a synchronous function from a combinational function describing a moore machine

macT
  :: Int        -- Current state
  -> (Int,Int)  -- Input
  -> (Int,Int)  -- Updated state
macT s (x,y) = x * y + s

mac
  :: Clock mac Source
  -> Reset mac Asynchronous
  -> Signal mac (Int, Int)
  -> Signal mac Int
mac clk rst = moore clk rst macT id 0

>>> simulate (mac systemClockGen systemResetGen) [(1,1),(2,2),(3,3),(4,4)]
[0,1,5,14...
...

Synchronous sequential functions can be composed just like their combinational counterpart:

dualMac
  :: Clock domain gated
  -> Reset domain synchronous
  -> (Signal domain Int, Signal domain Int)
  -> (Signal domain Int, Signal domain Int)
  -> Signal domain Int
dualMac clk rst (a,b) (x,y) = s1 + s2
  where
    s1 = moore clk rst mac id 0 (bundle (a,x))
    s2 = moore clk rst mac id 0 (bundle (b,y))

A version of moore that does automatic Bundleing

Given a functions t and o of types:

t :: Int -> (Bool, Int) -> Int
o :: Int -> (Int, Bool)

When we want to make compositions of t and o in g using moore', we have to write:

g clk rst a b c = (b1,b2,i2)
  where
    (i1,b1) = unbundle (moore clk rst t o 0 (bundle (a,b)))
    (i2,b2) = unbundle (moore clk rst t o 3 (bundle (i1,c)))

Using mooreB' however we can write:

g clk rst a b c = (b1,b2,i2)
  where
    (i1,b1) = mooreB clk rst t o 0 (a,b)
    (i2,b2) = mooreB clk rst t o 3 (i1,c)

Create a register function for product-type like signals (e.g. (Signal a, Signal b))

rP :: Clock domain gated -> Reset domain synchronous
   -> (Signal domain Int, Signal domain Int)
   -> (Signal domain Int, Signal domain Int)
rP clk rst = registerB clk rst (8,8)

>>> simulateB (rP systemClockGen systemResetGen) [(1,1),(2,2),(3,3)] :: [(Int,Int)]
[(8,8),(1,1),(2,2),(3,3)...
...

Synchroniser based on two sequentially connected flip-flops.

• NB: This synchroniser can be used for bit-synchronization.

• NB: Although this synchroniser does reduce metastability, it does not guarantee the proper synchronisation of a whole word. For example, given that the output is sampled twice as fast as the input is running, and we have two samples in the input stream that look like:

  [0111,1000]

  But the circuit driving the input stream has a longer propagation delay on msb compared to the lsbs. What can happen is an output stream that looks like this:

  [0111,0111,0000,1000]

  Where the level-change of the msb was not captured, but the level change of the lsbs were.

  If you want to have safe word-synchronisation use asyncFIFOSynchronizer.

Synchroniser implemented as a FIFO around an asynchronous RAM. Based on the design described in Clash.Tutorial, which is itself based on the design described in http://www.sunburst-design.com/papers/CummingsSNUG2002SJ_FIFO1.pdf.

NB: This synchroniser can be used for word-synchronization.

An asynchronous/combinational ROM with space for n elements

Additional helpful information:

• See Clash.Sized.Fixed and Clash.Prelude.BlockRam for ideas on how to use ROMs and RAMs

An asynchronous/combinational ROM with space for 2^n elements

Additional helpful information:

• See Clash.Sized.Fixed and Clash.Prelude.BlockRam for ideas on how to use ROMs and RAMs

A ROM with a synchronous read port, with space for n elements

• NB: Read value is delayed by 1 cycle
• NB: Initial output value is undefined

Additional helpful information:

• See Clash.Sized.Fixed and Clash.Explicit.BlockRam for ideas on how to use ROMs and RAMs

A ROM with a synchronous read port, with space for 2^n elements

• NB: Read value is delayed by 1 cycle
• NB: Initial output value is undefined

Additional helpful information:

• See Clash.Sized.Fixed and Clash.Explicit.BlockRam for ideas on how to use ROMs and RAMs

An asynchronous/combinational ROM with space for n elements

• NB: This function might not work for specific combinations of code-generation backends and hardware targets. Please check the support table below:

                 | VHDL     | Verilog  | SystemVerilog |
  ===============+==========+==========+===============+
  Altera/Quartus | Broken   | Works    | Works         |
  Xilinx/ISE     | Works    | Works    | Works         |
  ASIC           | Untested | Untested | Untested      |
  ===============+==========+==========+===============+
  

Additional helpful information:

• See Clash.Prelude.ROM.File for more information on how to instantiate a ROM with the contents of a data file.
• See Clash.Sized.Fixed for ideas on how to create your own data files.

• When you notice that asyncRomFile is significantly slowing down your simulation, give it a monomorphic type signature. So instead of leaving the type to be inferred:

  myRomData = asyncRomFile d512 "memory.bin"
  

  or giving it a polymorphic type signature:

  myRomData :: Enum addr => addr -> BitVector 16
  myRomData = asyncRomFile d512 "memory.bin"
  

  you should give it a monomorphic type signature:

  myRomData :: Unsigned 9 -> BitVector 16
  myRomData = asyncRomFile d512 "memory.bin"
  

An asynchronous/combinational ROM with space for 2^n elements

• NB: This function might not work for specific combinations of code-generation backends and hardware targets. Please check the support table below:

                 | VHDL     | Verilog  | SystemVerilog |
  ===============+==========+==========+===============+
  Altera/Quartus | Broken   | Works    | Works         |
  Xilinx/ISE     | Works    | Works    | Works         |
  ASIC           | Untested | Untested | Untested      |
  ===============+==========+==========+===============+
  

Additional helpful information:

• See Clash.Prelude.ROM.File for more information on how to instantiate a ROM with the contents of a data file.
• See Clash.Sized.Fixed for ideas on how to create your own data files.

• When you notice that asyncRomFilePow2 is significantly slowing down your simulation, give it a monomorphic type signature. So instead of leaving the type to be inferred:

  myRomData = asyncRomFilePow2 "memory.bin"
  

  you should give it a monomorphic type signature:

  myRomData :: Unsigned 9 -> BitVector 16
  myRomData = asyncRomFilePow2 "memory.bin"
  

A ROM with a synchronous read port, with space for n elements

• NB: Read value is delayed by 1 cycle
• NB: Initial output value is undefined

• NB: This function might not work for specific combinations of code-generation backends and hardware targets. Please check the support table below:

                 | VHDL     | Verilog  | SystemVerilog |
  ===============+==========+==========+===============+
  Altera/Quartus | Broken   | Works    | Works         |
  Xilinx/ISE     | Works    | Works    | Works         |
  ASIC           | Untested | Untested | Untested      |
  ===============+==========+==========+===============+
  

Additional helpful information:

• See Clash.Explicit.ROM.File for more information on how to instantiate a ROM with the contents of a data file.
• See Clash.Sized.Fixed for ideas on how to create your own data files.

A ROM with a synchronous read port, with space for 2^n elements

• NB: Read value is delayed by 1 cycle
• NB: Initial output value is undefined

• NB: This function might not work for specific combinations of code-generation backends and hardware targets. Please check the support table below:

                 | VHDL     | Verilog  | SystemVerilog |
  ===============+==========+==========+===============+
  Altera/Quartus | Broken   | Works    | Works         |
  Xilinx/ISE     | Works    | Works    | Works         |
  ASIC           | Untested | Untested | Untested      |
  ===============+==========+==========+===============+
  

Additional helpful information:

• See Clash.Explicit.ROM.File for more information on how to instantiate a ROM with the contents of a data file.
• See Clash.Sized.Fixed for ideas on how to create your own data files.

Create a RAM with space for n elements

• NB: Initial content of the RAM is undefined

Additional helpful information:

• See Clash.Explicit.BlockRam for more information on how to use a RAM.

Create a RAM with space for 2^n elements

• NB: Initial content of the RAM is undefined

Additional helpful information:

• See Clash.Prelude.BlockRam for more information on how to use a RAM.

Create a blockRAM with space for n elements

• NB: Read value is delayed by 1 cycle
• NB: Initial output value is undefined

bram40 :: Clock  domain gated
       -> Signal domain (Unsigned 6)
       -> Signal domain (Maybe (Unsigned 6, Bit))
       -> Signal domain Bit
bram40 clk = blockRam clk (replicate d40 1)

Additional helpful information:

• See Clash.Explicit.BlockRam for more information on how to use a Block RAM.
• Use the adapter readNew for obtaining write-before-read semantics like this: readNew clk rst (blockRam clk inits) rd wrM.

Create a blockRAM with space for 2^n elements

• NB: Read value is delayed by 1 cycle
• NB: Initial output value is undefined

bram32 :: Signal domain (Unsigned 5)
       -> Signal domain (Maybe (Unsigned 5, Bit))
       -> Signal domain Bit
bram32 clk = blockRamPow2 clk (replicate d32 1)

Additional helpful information:

• See Clash.Prelude.BlockRam for more information on how to use a Block RAM.
• Use the adapter readNew for obtaining write-before-read semantics like this: readNew clk rst (blockRamPow2 clk inits) rd wrM.

Create a blockRAM with space for n elements

• NB: Read value is delayed by 1 cycle
• NB: Initial output value is undefined

• NB: This function might not work for specific combinations of code-generation backends and hardware targets. Please check the support table below:

                 | VHDL     | Verilog  | SystemVerilog |
  ===============+==========+==========+===============+
  Altera/Quartus | Broken   | Works    | Works         |
  Xilinx/ISE     | Works    | Works    | Works         |
  ASIC           | Untested | Untested | Untested      |
  ===============+==========+==========+===============+
  

Additional helpful information:

• See Clash.Explicit.BlockRam for more information on how to use a Block RAM.
• Use the adapter readNew' for obtaining write-before-read semantics like this: readNew' clk (blockRamFile' clk size file) rd wrM.
• See Clash.Explicit.BlockRam.File for more information on how to instantiate a Block RAM with the contents of a data file.
• See Clash.Sized.Fixed for ideas on how to create your own data files.

Create a blockRAM with space for 2^n elements

• NB: Read value is delayed by 1 cycle
• NB: Initial output value is undefined

• NB: This function might not work for specific combinations of code-generation backends and hardware targets. Please check the support table below:

                 | VHDL     | Verilog  | SystemVerilog |
  ===============+==========+==========+===============+
  Altera/Quartus | Broken   | Works    | Works         |
  Xilinx/ISE     | Works    | Works    | Works         |
  ASIC           | Untested | Untested | Untested      |
  ===============+==========+==========+===============+
  

Additional helpful information:

• See Clash.Prelude.BlockRam for more information on how to use a Block RAM.
• Use the adapter readNew' for obtaining write-before-read semantics like this: readNew' clk (blockRamFilePow2' clk file) rd wrM.
• See Clash.Explicit.BlockRam.File for more information on how to instantiate a Block RAM with the contents of a data file.
• See Clash.Explicit.Fixed for ideas on how to create your own data files.

Create read-after-write blockRAM from a read-before-write one

Give a window over a Signal

@ window4

Give a delayed window over a Signal

windowD3 :: Clock domain gated -> Reset domain synchronous
         -> Signal domain Int -> Vec 3 (Signal domain Int)
windowD3 = windowD

>>> simulateB (windowD3 systemClockGen systemResetGen) [1::Int,2,3,4] :: [Vec 3 Int]
[<0,0,0>,<1,0,0>,<2,1,0>,<3,2,1>,<4,3,2>...
...

Give a pulse when the Signal goes from minBound to maxBound

Give a pulse when the Signal goes from maxBound to minBound

Compares the first two Signals for equality and logs a warning when they are not equal. The second Signal is considered the expected value. This function simply returns the third Signal' unaltered as its result. This function is used by outputVerifier.

NB: This function can be used in synthesizable designs.

To be used as one of the functions to create the "magical" testInput value, which the CλaSH compiler looks for to create the stimulus generator for the generated VHDL testbench.

Example:

testInput
  :: Clock domain gated -> Reset domain synchronous
  -> Signal domain Int
testInput clk rst = stimuliGenerator clk rst $(listToVecTH [(1::Int),3..21])

>>> sampleN 13 (testInput systemClockGen systemResetGen)
[1,3,5,7,9,11,13,15,17,19,21,21,21]

To be used as one of the functions to generate the "magical" expectedOutput function, which the CλaSH compiler looks for to create the signal verifier for the generated VHDL testbench.

Example:

expectedOutput
  :: Clock domain gated -> Reset domain synchronous
  -> Signal domain Int -> Signal domain Bool
expectedOutput clk rst = outputVerifier clk rst $(listToVecTH ([70,99,2,3,4,5,7,8,9,10]::[Int]))

>>> import qualified Data.List as List
>>> sampleN 12 (expectedOutput systemClockGen systemResetGen (fromList ([0..10] List.++ [10,10,10])))

cycle(system10000): 0, outputVerifier
expected value: 70, not equal to actual value: 0
[False
cycle(system10000): 1, outputVerifier
expected value: 99, not equal to actual value: 1
,False,False,False,False,False
cycle(system10000): 6, outputVerifier
expected value: 7, not equal to actual value: 6
,False
cycle(system10000): 7, outputVerifier
expected value: 8, not equal to actual value: 7
,False
cycle(system10000): 8, outputVerifier
expected value: 9, not equal to actual value: 8
,False
cycle(system10000): 9, outputVerifier
expected value: 10, not equal to actual value: 9
,False,True,True]

A Lift instance can have any of its values turned into a Template Haskell expression. This is needed when a value used within a Template Haskell quotation is bound outside the Oxford brackets ([| ... |]) but not at the top level. As an example:

add1 :: Int -> Q Exp
add1 x = [| x + 1 |]

Template Haskell has no way of knowing what value x will take on at splice-time, so it requires the type of x to be an instance of Lift.

A Lift instance must satisfy $(lift x) ≡ x for all x, where $(...) is a Template Haskell splice.

Lift instances can be derived automatically by use of the -XDeriveLift GHC language extension:

{-# LANGUAGE DeriveLift #-}
module Foo where

import Language.Haskell.TH.Syntax

data Bar a = Bar1 a (Bar a) | Bar2 String
  deriving Lift

The value of seq a b is bottom if a is bottom, and otherwise equal to b. In other words, it evaluates the first argument a to weak head normal form (WHNF). seq is usually introduced to improve performance by avoiding unneeded laziness.

A note on evaluation order: the expression seq a b does not guarantee that a will be evaluated before b. The only guarantee given by seq is that the both a and b will be evaluated before seq returns a value. In particular, this means that b may be evaluated before a. If you need to guarantee a specific order of evaluation, you must use the function pseq from the "parallel" package.

filter, applied to a predicate and a list, returns the list of those elements that satisfy the predicate; i.e.,

filter p xs = [ x | x <- xs, p x]

The print function outputs a value of any printable type to the standard output device. Printable types are those that are instances of class Show; print converts values to strings for output using the show operation and adds a newline.

For example, a program to print the first 20 integers and their powers of 2 could be written as:

main = print ([(n, 2^n) | n <- [0..19]])

Extract the first component of a pair.

Extract the second component of a pair.

otherwise is defined as the value True. It helps to make guards more readable. eg.

 f x | x < 0     = ...
     | otherwise = ...

Application operator. This operator is redundant, since ordinary application (f x) means the same as (f $ x). However, $ has low, right-associative binding precedence, so it sometimes allows parentheses to be omitted; for example:

f $ g $ h x  =  f (g (h x))

It is also useful in higher-order situations, such as map ($ 0) xs, or zipWith ($) fs xs.

general coercion from integral types

general coercion to fractional types

The Bounded class is used to name the upper and lower limits of a type. Ord is not a superclass of Bounded since types that are not totally ordered may also have upper and lower bounds.

The Bounded class may be derived for any enumeration type; minBound is the first constructor listed in the data declaration and maxBound is the last. Bounded may also be derived for single-constructor datatypes whose constituent types are in Bounded.

Class Enum defines operations on sequentially ordered types.

The enumFrom... methods are used in Haskell's translation of arithmetic sequences.

Instances of Enum may be derived for any enumeration type (types whose constructors have no fields). The nullary constructors are assumed to be numbered left-to-right by fromEnum from 0 through n-1. See Chapter 10 of the Haskell Report for more details.

For any type that is an instance of class Bounded as well as Enum, the following should hold:

• The calls succ maxBound and pred minBound should result in a runtime error.
• fromEnum and toEnum should give a runtime error if the result value is not representable in the result type. For example, toEnum 7 :: Bool is an error.
• enumFrom and enumFromThen should be defined with an implicit bound, thus:

   enumFrom     x   = enumFromTo     x maxBound
   enumFromThen x y = enumFromThenTo x y bound
     where
       bound | fromEnum y >= fromEnum x = maxBound
             | otherwise                = minBound