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
  :: KnownDomain dom
  => Clock dom
  -> Reset dom
  -> Enable dom
  -> Signal dom (Int, Int)
  -> Signal dom Int
mac clk rst en = mealy clk rst en macT 0

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

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

dualMac
  :: KnownDomain dom
  => Clock dom
  -> Reset dom
  -> Enable dom
  -> (Signal dom Int, Signal dom Int)
  -> (Signal dom Int, Signal dom Int)
  -> Signal dom Int
dualMac clk rst en (a,b) (x,y) = s1 + s2
  where
    s1 = mealy clk rst en mac 0 (bundle (a,x))
    s2 = mealy clk rst en 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 en a b c = (b1,b2,i2)
  where
    (i1,b1) = unbundle (mealy clk rst en f 0 (bundle (a,b)))
    (i2,b2) = unbundle (mealy clk rst en f 3 (bundle (c,i1)))

Using mealyB however we can write:

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

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
  :: KnownDomain dom
  => Clock dom
  -> Reset dom
  -> Enable dom
  -> Signal dom (Int, Int)
  -> Signal dom Int
mac clk rst en = moore clk rst en macT id 0

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

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

dualMac
  :: KnownDomain dom
  => Clock dom
  -> Reset dom
  -> Enable dom
  -> (Signal dom Int, Signal dom Int)
  -> (Signal dom Int, Signal dom Int)
  -> Signal dom Int
dualMac clk rst en (a,b) (x,y) = s1 + s2
  where
    s1 = moore clk rst en mac id 0 (bundle (a,x))
    s2 = moore clk rst en 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 en a b c = (b1,b2,i2)
  where
    (i1,b1) = unbundle (moore clk rst en t o 0 (bundle (a,b)))
    (i2,b2) = unbundle (moore clk rst en t o 3 (bundle (c,i1)))

Using mooreB however we can write:

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

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

rP :: Clock dom -> Reset dom -> Enable dom
   -> (Signal dom Int, Signal dom Int)
   -> (Signal dom Int, Signal dom Int)
rP clk rst en = registerB clk rst en (8,8)

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

Synchronizer based on two sequentially connected flip-flops.

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

• NB: Although this synchronizer does reduce metastability, it does not guarantee the proper synchronization 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-synchronization use asyncFIFOSynchronizer.

Synchronizer 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 synchronizer 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  dom
  -> Enable  dom
  -> Signal dom (Unsigned 6)
  -> Signal dom (Maybe (Unsigned 6, Bit))
  -> Signal dom Bit
bram40 clk en = blockRam clk en (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
  :: Clock dom
  -> Enable dom
  -> Signal dom (Unsigned 5)
  -> Signal dom (Maybe (Unsigned 5, Bit))
  -> Signal dom Bit
bram32 clk en = blockRamPow2 clk en (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.

Version of blockram that has no default values set. May be cleared to a arbitrary state using a reset function.

Version of blockram that is initialized with the same value on all memory positions.

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 rst en (blockRamFile clk en 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 rst en (blockRamFilePow2' clk en 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
  :: KnownDomain dom
  -> Clock dom
  -> Enable dom
  -> Reset dom
  -> Signal dom Int
  -> Vec 3 (Signal dom Int)
windowD3 = windowD

>>> simulateB (windowD3 systemClockGen resetGen enableGen) [1::Int,1,2,3,4] :: [Vec 3 Int]
[<0,0,0>,<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

Give a pulse every n clock cycles. This is a useful helper function when combined with functions like regEn or mux, in order to delay a register by a known amount.

Oscillate a Bool for a given number of cycles, given the starting state.

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.

Example:

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

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

Same as outputVerifier but used in cases where the testbench domain and the domain of the circuit under test are the same.

Trace a single signal. Will emit an error if a signal with the same name was previously registered.

NB associates the traced signal with a clock period of 1, which results in incorrect VCD files when working with circuits that have multiple clocks. Use traceSignal when working with circuits that have multiple clocks.

Trace a single vector signal: each element in the vector will show up as a different trace. If the trace name already exists, this function will emit an error.

NB associates the traced signal with a clock period of 1, which results in incorrect VCD files when working with circuits that have multiple clocks. Use traceSignal when working with circuits that have multiple clocks.

Trace a single signal. Will emit an error if a signal with the same name was previously registered.

NB Works correctly when creating VCD files from traced signal in multi-clock circuits. However traceSignal1 might be more convenient to use when the domain of your circuit is polymorphic.

Trace a single vector signal: each element in the vector will show up as a different trace. If the trace name already exists, this function will emit an error.

NB Works correctly when creating VCD files from traced signal in multi-clock circuits. However traceSignal1 might be more convinient to use when the domain of your circuit is polymorphic.

Produce a four-state VCD (Value Change Dump) according to IEEE 1364-{1995,2001}. This function fails if a trace name contains either non-printable or non-VCD characters.

Due to lazy evaluation, the created VCD files might not contain all the traces you were expecting. You therefore have to provide a list of names you definately want to be dumped in the VCD file.

For example:

vcd <- dumpVCD (0, 100) cntrOut ["main", "sub"]

Evaluates cntrOut long enough in order for to guarantee that the main, and sub traces end up in the generated VCD file.

Representable types of kind *. This class is derivable in GHC with the DeriveGeneric flag on.

A Generic instance must satisfy the following laws:

from . to ≡ id
to . from ≡ id