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))

Create a synchronous function from a combinational function describing a mealy machine using the state monad. This can be particularly useful when combined with lenses or optics to replicate imperative algorithms.

data DelayState = DelayState
  { _history    :: Vec 4 Int
  , _untilValid :: Index 4
  }
  deriving (Generic, NFDataX)
makeLenses ''DelayState

initialDelayState = DelayState (repeat 0) maxBound

delayS :: Int -> State DelayState (Maybe Int)
delayS n = do
  history   %= (n +>>)
  remaining <- use untilValid
  if remaining > 0
  then do
     untilValid -= 1
     return Nothing
   else do
     out <- uses history last
     return (Just out)

delayTop :: HiddenClockResetEnable dom  => Signal dom Int -> Signal dom (Maybe Int)
delayTop = mealyS delayS initialDelayState

>>> L.take 7 $ simulate @System delayTop [1,2,3,4,5,6,7,8]
[Nothing,Nothing,Nothing,Just 1,Just 2,Just 3,Just 4]
...

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)

A version of mealyS that does automatic Bundleing, see mealyB for details.

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

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.

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.

A clock signal belonging to a domain named dom.

Gets time in Picoseconds from time in Seconds

Isomorphism between a Signal of a product type (e.g. a tuple) and a product type of Signals.

Instances of Bundle must satisfy the following laws:

bundle . unbundle = id
unbundle . bundle = id

By default, bundle and unbundle, are defined as the identity, that is, writing:

data D = A | B

instance Bundle D

is the same as:

data D = A | B

instance Bundle D where
  type Unbundled clk D = Signal clk D
  bundle   s = s
  unbundle s = s

For custom product types you'll have to write the instance manually:

data Pair a b = MkPair { getA :: a, getB :: b }

instance Bundle (Pair a b) where
  type Unbundled dom (Pair a b) = Pair (Signal dom a) (Signal dom b)

  -- bundle :: Pair (Signal dom a) (Signal dom b) -> Signal dom (Pair a b)
  bundle   (MkPair as bs) = MkPair <$> as <*> bs

  -- unbundle :: Signal dom (Pair a b) -> Pair (Signal dom a) (Signal dom b)
  unbundle pairs = MkPair (getA <$> pairs) (getB <$> pairs)