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!

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

A KnownDomain constraint indicates that a circuit's behavior depends on some properties of a domain. See DomainConfiguration for more information.

Determines clock edge memory elements are sensitive to. Not yet implemented.

Singleton version of ActiveEdge

Singleton version of ResetKind

Determines the value for which a reset line is considered "active"

Singleton version of ResetPolarity

A domain with a name (Domain). Configures the behavior of various aspects of a circuits. See the documentation of this record's field types for more information on the options.

See module documentation of Clash.Explicit.Signal for more information on how to create custom synthesis domains.

Singleton version of DomainConfiguration

Convenience type to help to extract a period from a domain. Example usage:

myFunc :: (KnownDomain dom, DomainPeriod dom ~ 6000) => ...

Convenience type to help to extract the active edge from a domain. Example usage:

myFunc :: (KnownDomain dom, DomainActiveEdge dom ~ 'Rising) => ...

Convenience type to help to extract the reset synchronicity from a domain. Example usage:

myFunc :: (KnownDomain dom, DomainResetKind dom ~ 'Asynchronous) => ...

Convenience type to help to extract the initial value behavior from a domain. Example usage:

myFunc :: (KnownDomain dom, DomainInitBehavior dom ~ 'Defined) => ...

Convenience type to help to extract the reset polarity from a domain. Example usage:

myFunc :: (KnownDomain dom, DomainResetPolarity dom ~ 'ActiveHigh) => ...

A clock (and reset) dom with clocks running at 100 MHz. Memory elements respond to the rising edge of the clock, and asynchronously to changes in reset signals. It has defined initial values, and active-high resets.

See module documentation of Clash.Explicit.Signal for more information on how to create custom synthesis domains.

A clock (and reset) dom with clocks running at 100 MHz. Memory elements respond to the rising edge of the clock, and synchronously to changes in reset signals. It has defined initial values, and active-high resets.

See module documentation of Clash.Explicit.Signal for more information on how to create custom synthesis domains.

A clock (and reset) dom with clocks running at 100 MHz. Memory elements respond to the rising edge of the clock, and asynchronously to changes in reset signals. It has defined initial values, and active-high resets.

See module documentation of Clash.Explicit.Signal for more information on how to create custom synthesis domains.

Convenience value to allow easy "subclassing" of System domain. Should be used in combination with createDomain. For example, if you just want to change the period but leave all other settings in tact use:

createDomain vSystem{vName="System10", vPeriod=10}

Convenience value to allow easy "subclassing" of IntelSystem domain. Should be used in combination with createDomain. For example, if you just want to change the period but leave all other settings in tact use:

createDomain vIntelSystem{vName="Intel10", vPeriod=10}

Convenience value to allow easy "subclassing" of XilinxSystem domain. Should be used in combination with createDomain. For example, if you just want to change the period but leave all other settings in tact use:

createDomain vXilinxSystem{vName="Xilinx10", vPeriod=10}

Same as SDomainConfiguration but allows for easy updates through record update syntax. Should be used in combination with vDomain and createDomain. Example:

createDomain (knownVDomain @System){vName="System10", vPeriod=10}

This duplicates the settings in the System domain, replaces the name and period, and creates an instance for it. As most users often want to update the system domain, a shortcut is available in the form:

createDomain vSystem{vName="System10", vPeriod=10}

Convert SDomainConfiguration to VDomainConfiguration. Should be used in combination with createDomain only.

Convenience method to express new domains in terms of others.

createDomain (knownVDomain @System){vName="System10", vPeriod=10}

This duplicates the settings in the System domain, replaces the name and period, and creates an instance for it. As most users often want to update the system domain, a shortcut is available in the form:

createDomain vSystem{vName="System10", vPeriod=10}

The function will create two extra identifiers. The first:

type System10 = ..

You can use that as the dom to Clocks/Resets/Enables/Signals. For example: Signal System10 Int. Additionally, it will create a VDomainConfiguration that you can use in later calls to createDomain:

vSystem10 = knownVDomain @System10

Like 'knownDomain but yields a VDomainConfiguration. Should only be used in combination with createDomain.

Get the clock period from a KnownDomain context

Get ActiveEdge from a KnownDomain context. Example usage:

f :: forall dom . KnownDomain dom => ....
f a b c =
  case activeEdge @dom of
    SRising -> foo
    SFalling -> bar

Get ResetKind from a KnownDomain context. Example usage:

f :: forall dom . KnownDomain dom => ....
f a b c =
  case resetKind @dom of
    SAsynchronous -> foo
    SSynchronous -> bar

Get InitBehavior from a KnownDomain context. Example usage:

f :: forall dom . KnownDomain dom => ....
f a b c =
  case initBehavior @dom of
    SDefined -> foo
    SUnknown -> bar

Get ResetPolarity from a KnownDomain context. Example usage:

f :: forall dom . KnownDomain dom => ....
f a b c =
  case resetPolarity @dom of
    SActiveHigh -> foo
    SActiveLow -> bar

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.

Convert a signal of bools to an Enable construct

Convert Enable construct to its underlying representation: a signal of bools.

Enable generator for some domain. Is simply always True.

A clock signal belonging to a domain named dom.

Calculate the period, in ps, given a frequency in Hz

i.e. to calculate the clock period for a circuit to run at 240 MHz we get

>>> freqCalc 240e6
4167

NB: This function is not synthesizable

Calculate the frequence in Hz, given the period in ps

i.e. to calculate the clock frequency of a clock with a period of 5000 ps:

>>> periodToHz 5000
2.0e8

NB: This function is not synthesizable NB: This function is lossy. I.e., hzToPeriod . periodToHz /= id.

Calculate the period, in ps, given a frequency in Hz

i.e. to calculate the clock period for a circuit to run at 240 MHz we get

>>> hzToPeriod 240e6
4167

NB: This function is not synthesizable NB: This function is lossy. I.e., hzToPeriod . periodToHz /= id.

The unsafeSynchronizer function is a primitive that must be used to connect one clock domain to the other, and will be synthesized to a (bundle of) wire(s) in the eventual circuit. This function should only be used as part of a proper synchronization component, such as the following dual flip-flop synchronizer:

dualFlipFlop
  :: Clock domA
  -> Clock domB
  -> Enable domA
  -> Enable domB
  -> Bit
  -> Signal domA Bit
  -> Signal domB Bit
dualFlipFlop clkA clkB enA enB dflt =
  delay clkB enB dflt . delay clkB enB dflt . unsafeSynchronizer clkA clkB

The unsafeSynchronizer works in such a way that, given 2 clocks:

createDomain vSystem{vName="Dom7", vPeriod=7}

clk7 :: Clock Dom7
clk7 = clockGen

en7 :: Enable Dom7
en7 = enableGen

and

createDomain vSystem{vName="Dom2", vPeriod=2}

clk2 :: Clock Dom2
clk2 = clockGen

en2 :: Enable Dom2
en2 = enableGen

Oversampling followed by compression is the identity function plus 2 initial values:

delay clkB enB dflt $
unsafeSynchronizer clkA clkB $
delay clkA enA dflt $
unsafeSynchronizer clkB clkA $
delay clkB enB s

==

dflt :- dflt :- s

Something we can easily observe:

oversampling clkA clkB enA enB dflt =
  delay clkB enB dflt
    . unsafeSynchronizer clkA clkB
    . delay clkA enA dflt
almostId clkA clkB enA enB dflt =
  delay clkB enB dflt
    . unsafeSynchronizer clkA clkB
    . delay clkA enA dflt
    . unsafeSynchronizer clkB clkA
    . delay clkB enB dflt

>>> sampleN 37 (oversampling clk7 clk2 en7 en2 0 (fromList [(1::Int)..10]))
[0,0,1,1,1,2,2,2,2,3,3,3,4,4,4,4,5,5,5,6,6,6,6,7,7,7,8,8,8,8,9,9,9,10,10,10,10]
>>> sampleN 12 (almostId clk2 clk7 en2 en7 0 (fromList [(1::Int)..10]))
[0,0,1,2,3,4,5,6,7,8,9,10]

Same as unsafeSynchronizer, but with manually supplied clock periods.

Note: this unsafeSynchronizer is defined to be consistent with the vhdl and verilog implementations however as only synchronous signals are represented in Clash this cannot be done precisely and can lead to odd behaviour. For example, sample $ unsafeSynchronizer Dom2 Dom7 . unsafeSynchronizer Dom7 Dom2 $ fromList [0..10] > [0,4,4,4,7,7,7,7,11,11,11.. is quite different from the identity, sample $ fromList [0..10] > [0,1,2,3,4,5,6,7,8,9,10.. with values appearing from the "future".

A reset signal belonging to a domain called dom.

The underlying representation of resets is Bool.

unsafeToReset is unsafe. For asynchronous resets it is unsafe because it can introduce combinatorial loops. In case of synchronous resets it can lead to meta-stability issues in the presence of asynchronous resets.

NB: You probably want to use unsafeFromLowPolarity or unsafeFromHighPolarity.

unsafeFromReset is unsafe because it can introduce:

• meta-stability

For asynchronous resets it is unsafe because it can cause combinatorial loops. In case of synchronous resets it can lead to meta-stability in the presence of asynchronous resets.

NB: You probably want to use unsafeToLowPolarity or unsafeToHighPolarity.

Convert a reset to an active high reset. Has no effect if reset is already an active high reset. Is unsafe because it can introduce:

• meta-stability

For asynchronous resets it is unsafe because it can cause combinatorial loops. In case of synchronous resets it can lead to meta-stability in the presence of asynchronous resets.

Convert a reset to an active low reset. Has no effect if reset is already an active low reset. It is unsafe because it can introduce:

• meta-stability

For asynchronous resets it is unsafe because it can cause combinatorial loops. In case of synchronous resets it can lead to meta-stability in the presence of asynchronous resets.

Interpret a signal of bools as an active high reset and convert it to a reset signal corresponding to the domain's setting.

For asynchronous resets it is unsafe because it can cause combinatorial loops. In case of synchronous resets it can lead to meta-stability in the presence of asynchronous resets.

Interpret a signal of bools as an active low reset and convert it to a reset signal corresponding to the domain's setting.

For asynchronous resets it is unsafe because it can cause combinatorial loops. In case of synchronous resets it can lead to meta-stability in the presence of asynchronous resets.

Convert between different types of reset, adding a synchronizer in case it needs to convert from an asynchronous to a synchronous reset.

Normally, asynchronous resets can be both asynchronously asserted and de-asserted. Asynchronous de-assertion can induce meta-stability in the component which is being reset. To ensure this doesn't happen, resetSynchronizer ensures that de-assertion of a reset happens synchronously. Assertion of the reset remains asynchronous.

Note that asynchronous assertion does not induce meta-stability in the component whose reset is asserted. However, when a component "A" in another clock or reset domain depends on the value of a component "B" being reset, then asynchronous assertion of the reset of component "B" can induce meta-stability in component "A". To prevent this from happening you need to use a proper synchronizer, for example one of the synchronizers in Clash.Explicit.Synchronizer

Example

topEntity
  :: Clock  System
  -> Reset  System
  -> Signal System Bit
  -> Signal System (BitVector 8)
topEntity clk rst key1 =
    let  (pllOut,pllStable) = altpll (SSymbol @"altpll50") clk rst
         rstSync            = resetSynchronizer pllOut (unsafeToHighPolarity pllStable)
    in   exposeClockResetEnable leds pllOut rstSync
  where
    key1R  = isRising 1 key1
    leds   = mealy blinkerT (1, False, 0) key1R

Hold reset for a number of cycles relative to an incoming reset signal.

Example:

>>> let sampleWithReset = sampleN 8 . unsafeToHighPolarity
>>> sampleWithReset (holdReset @System clockGen enableGen (SNat @2) (resetGenN (SNat @3)))
[True,True,True,True,True,False,False,False]

holdReset holds the reset for an additional 2 clock cycles for a total of 5 clock cycles where the reset is asserted. holdReset also works on intermediate assertions of the reset signal:

>>> let rst = fromList [True, False, False, False, True, False, False, False]
>>> sampleWithReset (holdReset @System clockGen enableGen (SNat @2) (unsafeFromHighPolarity rst))
[True,True,True,False,True,True,True,False]

Merge enable signal with signal of bools

Special version of delay that doesn't take enable signals of any kind. Initial value will be undefined.

"delay clk s" delays the values in Signal s for once cycle, the value at time 0 is dflt.

>>> sampleN 3 (delay systemClockGen enableGen 0 (fromList [1,2,3,4]))
[0,1,2]

Version of delay that only updates when its third argument is a Just value.

>>> let input = fromList [Just 1, Just 2, Nothing, Nothing, Just 5, Just 6, Just (7::Int)]
>>> sampleN 7 (delayMaybe systemClockGen enableGen 0 input)
[0,1,2,2,2,5,6]

Version of delay that only updates when its third argument is asserted.

>>> let input = fromList [1,2,3,4,5,6,7::Int]
>>> let enable = fromList [True,True,False,False,True,True,True]
>>> sampleN 7 (delayEn systemClockGen enableGen 0 enable input)
[0,1,2,2,2,5,6]

"register clk rst i s" delays the values in Signal s for one cycle, and sets the value to i the moment the reset becomes False.

>>> sampleN 5 (register systemClockGen resetGen enableGen 8 (fromList [1,1,2,3,4]))
[8,8,1,2,3]

Version of register that only updates its content when its fourth argument is a Just value. So given:

sometimes1 clk rst en = s where
  s = register clk rst en Nothing (switch <$> s)

  switch Nothing = Just 1
  switch _       = Nothing

countSometimes clk rst en = s where
  s     = regMaybe clk rst en 0 (plusM (pure <$> s) (sometimes1 clk rst en))
  plusM = liftA2 (liftA2 (+))

We get:

>>> sampleN 9 (sometimes1 systemClockGen resetGen enableGen)
[Nothing,Nothing,Just 1,Nothing,Just 1,Nothing,Just 1,Nothing,Just 1]
>>> sampleN 9 (count systemClockGen resetGen enableGen)
[0,0,0,1,1,2,2,3,3]

Version of register that only updates its content when its fourth argument is asserted. So given:

oscillate clk rst en = let s = register clk rst en False (not <$> s) in s
count clk rst en     = let s = 'regEn clk rst en 0 (oscillate clk rst en) (s + 1) in s

We get:

>>> sampleN 9 (oscillate systemClockGen resetGen enableGen)
[False,False,True,False,True,False,True,False,True]
>>> sampleN 9 (count systemClockGen resetGen enableGen)
[0,0,0,1,1,2,2,3,3]

Clock generator for simulations. Do not use this clock generator for for the testBench function, use tbClockGen instead.

To be used like:

clkSystem = clockGen @System

See DomainConfiguration for more information on how to use synthesis domains.

Reset generator

To be used like:

rstSystem = resetGen @System

See tbClockGen for example usage.

Generate reset that's asserted for the first n cycles.

To be used like:

rstSystem5 = resetGen System (SNat 5)

Example usage:

>>> sampleN 7 (unsafeToHighPolarity (resetGenN @System (SNat @3)))
[True,True,True,False,False,False,False]

Clock generator for the System clock domain.

NB: should only be used for simulation, and not for the testBench function. For the testBench function, used tbSystemClockGen

Reset generator for the System clock domain.

NB: should only be used for simulation or the testBench function.

Example

topEntity :: Vec 2 (Vec 3 (Unsigned 8)) -> Vec 6 (Unsigned 8)
topEntity = concat

testBench :: Signal System Bool
testBench = done
  where
    testInput      = pure ((1 :> 2 :> 3 :> Nil) :> (4 :> 5 :> 6 :> Nil) :> Nil)
    expectedOutput = outputVerifier' ((1:>2:>3:>4:>5:>6:>Nil):>Nil)
    done           = exposeClockResetEnable (expectedOutput (topEntity $ testInput)) clk rst
    clk            = tbSystemClockGen (not <$> done)
    rst            = systemResetGen

The above type is a generalization for:

(.&&.) :: Signal Bool -> Signal Bool -> Signal Bool

It is a version of (&&) that returns a Signal of Bool

The above type is a generalization for:

(.||.) :: Signal Bool -> Signal Bool -> Signal Bool

It is a version of (||) that returns a Signal of Bool

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

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