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

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

mac :: HiddenClockResetEnable dom  => Signal dom (Int, Int) -> Signal dom Int
mac = mealy macT 0

>>> simulate @System mac [(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
  :: HiddenClockResetEnable dom
  => (Signal dom Int, Signal dom Int)
  -> (Signal dom Int, Signal dom Int)
  -> Signal dom Int
dualMac (a,b) (x,y) = s1 + s2
  where
    s1 = mealy macT 0 (bundle (a,x))
    s2 = mealy macT 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 a b c = (b1,b2,i2)
  where
    (i1,b1) = unbundle (mealy f 0 (bundle (a,b)))
    (i2,b2) = unbundle (mealy f 3 (bundle (c,i1)))

Using mealyB however we can write:

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

Infix version of mealyB

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

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

mac
  :: HiddenClockResetEnable dom
  => Signal dom (Int, Int)
  -> Signal dom Int
mac = moore mac id 0

>>> simulate @System mac [(0,0),(1,1),(2,2),(3,3),(4,4)]
[0,0,1,5,14,30,...
...

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

dualMac
  :: HiddenClockResetEnable dom
  => (Signal dom Int, Signal dom Int)
  -> (Signal dom Int, Signal dom Int)
  -> Signal dom Int
dualMac (a,b) (x,y) = s1 + s2
  where
    s1 = moore macT id 0 (bundle (a,x))
    s2 = moore macT 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 a b c = (b1,b2,i2)
  where
    (i1,b1) = unbundle (moore t o 0 (bundle (a,b)))
    (i2,b2) = unbundle (moore t o 3 (bundle (c,i1)))

Using mooreB however we can write:

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

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

rP :: HiddenClockResetEnable dom
   => (Signal dom Int, Signal dom Int)
   -> (Signal dom Int, Signal dom Int)
rP = registerB (8,8)

>>> simulateB @System rP [(1,1),(2,2),(3,3)] :: [(Int,Int)]
[(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

See also:

• See Clash.Sized.Fixed and Clash.Prelude.BlockRam for ideas on how to use ROMs and RAMs.
• A large Vec for the content may be too inefficient, depending on how it is constructed. See asyncRomFile and asyncRomBlob for different approaches that scale well.

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

See also:

• See Clash.Sized.Fixed and Clash.Prelude.BlockRam for ideas on how to use ROMs and RAMs.
• A large Vec for the content may be too inefficient, depending on how it is constructed. See asyncRomFilePow2 and asyncRomBlobPow2 for different approaches that scale well.

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, reading it will throw an XException

See also:

• See Clash.Sized.Fixed and Clash.Prelude.BlockRam for ideas on how to use ROMs and RAMs.
• A large Vec for the content may be too inefficient, depending on how it is constructed. See romFile and romBlob for different approaches that scale well.

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, reading it will throw an XException

See also:

• See Clash.Sized.Fixed and Clash.Prelude.BlockRam for ideas on how to use ROMs and RAMs.
• A large Vec for the content may be too inefficient, depending on how it is constructed. See romFilePow2 and romBlobPow2 for different approaches that scale well.

An asynchronous/combinational ROM with space for n elements

See also:

• 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

See also:

• 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, reading it will throw an XException

See also:

• 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, reading it will throw an XException

See also:

• 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:

See also:

• 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:

See also:

• 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, reading it will throw an XException
• NB: This function might not work for specific combinations of code-generation backends and hardware targets. Please check the support table below:

See also:

• 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.

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, reading it will throw an XException
• NB: This function might not work for specific combinations of code-generation backends and hardware targets. Please check the support table below:

See also:

• 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.

Create a RAM with space for n elements

• NB: Initial content of the RAM is undefined, reading it will throw an XException

See also:

• See Clash.Prelude.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, reading it will throw an XException

See also:

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

Create a block RAM with space for n elements

• NB: Read value is delayed by 1 cycle
• NB: Initial output value is undefined, reading it will throw an XException

See also:

• 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 (blockRam inits) rd wrM.
• A large Vec for the initial content may be too inefficient, depending on how it is constructed. See blockRamFile and blockRamBlob for different approaches that scale well.

Example

bram40
  :: HiddenClock dom
  => Signal dom (Unsigned 6)
  -> Signal dom (Maybe (Unsigned 6, Bit))
  -> Signal dom Bit
bram40 = blockRam (replicate d40 1)

Create a block RAM with space for 2^n elements

• NB: Read value is delayed by 1 cycle
• NB: Initial output value is undefined, reading it will throw an XException

See also:

• 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 (blockRamPow2 inits) rd wrM.
• A large Vec for the initial content may be too inefficient, depending on how it is constructed. See blockRamFilePow2 and blockRamBlobPow2 for different approaches that scale well.

Example

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

A version of blockRam that has no default values set. May be cleared to an arbitrary state using a reset function.

A version of blockRam that is initialized with the same value on all memory positions

Create a block RAM with space for n elements

• NB: Read value is delayed by 1 cycle
• NB: Initial output value is undefined, reading it will throw an XException

See also:

• 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 (blockRamBlob content) rd wrM.

Create a block RAM with space for 2^n elements

• NB: Read value is delayed by 1 cycle
• NB: Initial output value is undefined, reading it will throw an XException

See also:

• 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 (blockRamBlobPow2 content) rd wrM.

Efficient storage of memory content

It holds n words of BitVector m.

Create a MemBlob binding from a list of values

Since this uses Template Haskell, nothing in the arguments given to createMemBlob can refer to something defined in the same module.

Example

createMemBlob "content" Nothing [15 :: Unsigned 8 .. 17]

ram clk en = blockRamBlob clk en content

>>> import qualified Prelude as P
>>> let es = [ Nothing, Just (7 :: Unsigned 8), Just 8 ]
>>> :{
createMemBlob "content0" (Just 0) es
createMemBlob "content1" (Just 1) es
x = 1
:}

>>> let pr = mapM_ (putStrLn . show)
>>> pr $ P.map pack es
0b0_...._....
0b1_0000_0111
0b1_0000_1000
>>> pr $ unpackMemBlob content0
0b0_0000_0000
0b1_0000_0111
0b1_0000_1000
>>> pr $ unpackMemBlob content1
0b0_1111_1111
0b1_0000_0111
0b1_0000_1000
>>> :{
createMemBlob "contentN" Nothing es
x = 1
:}

<interactive>:...: error:
    packBVs: cannot convert don't care values. Please specify a mapping to a definite value.

Create a MemBlob from a list of values

Since this uses Template Haskell, nothing in the arguments given to memBlobTH can refer to something defined in the same module.

Example

ram clk en = blockRamBlob clk en $(memBlobTH Nothing [15 :: Unsigned 8 .. 17])

>>> import qualified Prelude as P
>>> let es = [ Nothing, Just (7 :: Unsigned 8), Just 8 ]
>>> content0 = $(memBlobTH (Just 0) es)
>>> content1 = $(memBlobTH (Just 1) es)
>>> let pr = mapM_ (putStrLn . show)
>>> pr $ P.map pack es
0b0_...._....
0b1_0000_0111
0b1_0000_1000
>>> pr $ unpackMemBlob content0
0b0_0000_0000
0b1_0000_0111
0b1_0000_1000
>>> pr $ unpackMemBlob content1
0b0_1111_1111
0b1_0000_0111
0b1_0000_1000
>>> $(memBlobTH Nothing es)

<interactive>:...: error:
    • packBVs: cannot convert don't care values. Please specify a mapping to a definite value.
    • In the untyped splice: $(memBlobTH Nothing es)

Convert a MemBlob back to a list

NB: Not synthesizable

Create a block RAM with space for n elements

• NB: Read value is delayed by 1 cycle
• NB: Initial output value is undefined, reading it will throw an XException
• NB: This function might not work for specific combinations of code-generation backends and hardware targets. Please check the support table below:

See also:

• 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 (blockRamFile size file) rd wrM.
• See Clash.Prelude.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 block RAM with space for 2^n elements

• NB: Read value is delayed by 1 cycle
• NB: Initial output value is undefined, reading it will throw an XException
• NB: This function might not work for specific combinations of code-generation backends and hardware targets. Please check the support table below:

See also:

• 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 (blockRamFilePow2 file) rd wrM.
• See Clash.Prelude.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 read-after-write block RAM from a read-before-write one

>>> :t readNew (blockRam (0 :> 1 :> Nil))
readNew (blockRam (0 :> 1 :> Nil))
  :: ...
     ...
     ...
     ...
     ... =>
     Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

Produces vendor-agnostic HDL that will be inferred as a true dual-port block RAM

Any value that is being written on a particular port is also the value that will be read on that port, i.e. the same-port read/write behavior is: WriteFirst. For mixed-port read/write, when port A writes to the address port B reads from, the output of port B is undefined, and vice versa.

Port operation

Give a window over a Signal

window4 :: HiddenClockResetEnable dom
        => Signal dom Int -> Vec 4 (Signal dom Int)
window4 = window

>>> simulateB @System window4 [1::Int,2,3,4,5] :: [Vec 4 Int]
[1 :> 0 :> 0 :> 0 :> Nil,2 :> 1 :> 0 :> 0 :> Nil,3 :> 2 :> 1 :> 0 :> Nil,4 :> 3 :> 2 :> 1 :> Nil,5 :> 4 :> 3 :> 2 :> Nil,...
...

Give a delayed window over a Signal

windowD3
  :: HiddenClockResetEnable dom
  => Signal dom Int
  -> Vec 3 (Signal dom Int)
windowD3 = windowD

>>> simulateB @System windowD3 [1::Int,2,3,4] :: [Vec 3 Int]
[0 :> 0 :> 0 :> Nil,1 :> 0 :> 0 :> Nil,2 :> 1 :> 0 :> Nil,3 :> 2 :> 1 :> Nil,4 :> 3 :> 2 :> Nil,...
...

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.

To be precise: the given signal will be False for the next n-1 cycles, followed by a single True value:

>>> Prelude.last (sampleN @System 1025 (riseEvery d1024)) == True
True
>>> Prelude.or (sampleN @System 1024 (riseEvery d1024)) == False
True

For example, to update a counter once every 10 million cycles:

counter = regEn 0 (riseEvery (SNat :: SNat 10000000)) (counter + 1)

Oscillate a Bool for a given number of cycles. This is a convenient function when combined with something like regEn, as it allows you to easily hold a register value for a given number of cycles. The input Bool determines what the initial value is.

To oscillate on an interval of 5 cycles:

>>> sampleN @System 11 (oscillate False d5)
[False,False,False,False,False,False,True,True,True,True,True]

To oscillate between True and False:

>>> sampleN @System 11 (oscillate False d1)
[False,False,True,False,True,False,True,False,True,False,True]

An alternative definition for the above could be:

>>> let osc' = register False (not <$> osc')
>>> sampleN @System 200 (oscillate False d1) == sampleN @System 200 osc'
True

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 convenient 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.

A reset signal belonging to a domain called dom.

The underlying representation of resets is Bool.

A clock signal belonging to a domain named dom.

A signal of booleans, indicating whether a component is enabled. No special meaning is implied, it's up to the component itself to decide how to respond to its enable line. It is used throughout Clash as a global enable signal.

Clash has synchronous Signals in the form of:

Signal (dom :: Domain) a

Where a is the type of the value of the Signal, for example Int or Bool, and dom is the clock- (and reset-) domain to which the memory elements manipulating these Signals belong.

The type-parameter, dom, is of the kind Domain - a simple string. That string refers to a single synthesis domain. A synthesis domain describes the behavior of certain aspects of memory elements in it.

• NB: "Bad things"™ happen when you actually use a clock period of 0, so do not do that!
• NB: You should be judicious using a clock with period of 1 as you can never create a clock that goes any faster!
• NB: For the best compatibility make sure your period is divisible by 2, because some VHDL simulators don't support fractions of picoseconds.
• NB: Whether System has good defaults depends on your target platform. Check out IntelSystem and XilinxSystem too!

Signals have the type role

>>> :i Signal
type role Signal nominal representational
...

as it is safe to coerce the underlying value of a signal, but not safe to coerce a signal between different synthesis domains.

See the module documentation of Clash.Signal for more information about domains.