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.

The in part of an inout port. BiSignalIn has the type role

>>> :i BiSignalIn
type role BiSignalIn nominal nominal nominal
...

as it is not safe to coerce the default behaviour, synthesis domain or width of the data in the signal.

The out part of an inout port

Wraps (multiple) writing signals. The semantics are such that only one of the signals may write at a single time step.

BiSignalOut has the type role

>>> :i BiSignalOut
type role BiSignalOut nominal nominal nominal
...

as it is not safe to coerce the default behaviour, synthesis domain or width of the data in the signal.

Used to specify the default behavior of a "BiSignal", i.e. what value is read when no value is being written to it.

We either get evidence that this function was instantiated with the same domains, or Nothing.

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 ~ 'Synchronous) => ...

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

Convenience type to constrain a domain to have synchronous resets. Example usage:

myFunc :: HasSynchronousReset dom => ...

Using this type implies KnownDomain.

Click here for usage hints

Convenience type to constrain a domain to have asynchronous resets. Example usage:

myFunc :: HasAsynchronousReset dom => ...

Using this type implies KnownDomain.

Click here for usage hints

Convenience type to constrain a domain to have initial values. Example usage:

myFunc :: HasDefinedInitialValues dom => ...

Using this type implies KnownDomain.

Note that there is no UnknownInitialValues dom as a component that works without initial values will also work if it does have them.

Click here for usage hints

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

It will also make System10 an instance of KnownDomain.

If either identifier is already in scope it will not be generated a second time. Note: This can be useful for example when documenting a new domain:

-- | Here is some documentation for CustomDomain
type CustomDomain = ("CustomDomain" :: Domain)

-- | Here is some documentation for vCustomDomain
createDomain vSystem{vName="CustomDomain"}

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 clock signal belonging to a domain named dom.

A differential clock signal belonging to a domain named dom. The clock input of a design with such an input has two ports which are in antiphase. The first input is the positive phase, the second the negative phase. When using makeTopEntity, the names of the inputs will end in _p and _n respectively.

To create a differential clock in a test bench, you can use clockToDiffClock.

Calculate the frequency 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

Note that if p in periodToHz (fromIntegral p) is negative, fromIntegral will give an Underflow :: ArithException without a call stack, making debugging cumbersome.

Before Clash 1.8, this function always returned a Ratio Natural. To get the old behavior of this function, use a type application:

>>> periodToHz @(Ratio Natural) 5000
200000000 % 1

NB: This function is not synthesizable

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
4166

If the value hzToPeriod is applied to is not of the type Ratio Natural, you can use hzToPeriod (realToFrac f). Note that if f is negative, realToFrac will give an Underflow :: ArithException without a call stack, making debugging cumbersome.

Before Clash 1.8, this function always returned a Natural. To get the old behavior of this function, use a type application:

>>> hzToPeriod @Natural 240e6
4166

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

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 unsafeFromActiveLow or unsafeFromActiveHigh.

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 unsafeToActiveLow or unsafeToActiveHigh.

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.

The resetSynchronizer will synchronize an incoming reset according to whether the domain is synchronous or asynchronous.

For asynchronous resets this synchronizer ensures the reset will only be de-asserted synchronously but it can still be asserted asynchronously. The reset assert is immediate, but reset de-assertion is delayed by two cycles.

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.

For synchronous resets this function ensures that the reset is asserted and de-asserted synchronously. Both the assertion and de-assertion of the reset are delayed by two cycles.

Example 1

topEntity
  :: Clock  System
  -> Reset  System
  -> Signal System Bit
  -> Signal System (BitVector 8)
topEntity clk asyncRst key1 =
  withClockResetEnable clk rst enableGen leds
 where
  rst   = resetSynchronizer clk asyncRst
  key1R = isRising 1 key1
  leds  = mealy blinkerT (1, False, 0) key1R

Example 2

topEntity
  :: Clock  System
  -> Reset  System
  -> Signal System Bit
  -> Signal System (BitVector 8)
topEntity clk rst key1 =
    let  (pllOut,pllStable) = unsafeAltpll clk rst
         rstSync            = resetSynchronizer pllOut (unsafeFromActiveLow pllStable)
    in   exposeClockResetEnable leds pllOut rstSync enableGen
  where
    key1R  = isRising 1 key1
    leds   = mealy blinkerT (1, False, 0) key1R

Implementation details

                                  rst
  --------------------------------------+
                      |                 |
                 +----v----+       +----v----+
    deasserted   |         |       |         |
  --------------->         +------->         +-------->
                 |         |       |         |
             +---|>        |   +---|>        |
             |   |         |   |   |         |
             |   +---------+   |   +---------+
     clk     |                 |
  -----------------------------+

                 +---------+       +---------+
    rst          |         |       |         |
  --------------->         +------->         +-------->
                 |         |       |         |
             +---|>        |   +---|>        |
             |   |         |   |   |         |
             |   +---------+   |   +---------+
     clk     |                 |
  -----------------------------+

Filter glitches from reset signals by only triggering a reset after it has been asserted for glitchlessPeriod cycles. Similarly, it will stay asserted until a glitchlessPeriod number of deasserted cycles have been observed.

This circuit can only be used on platforms supporting initial values. This restriction can be worked around by using unsafeResetGlitchFilter but this is not recommended.

On platforms without initial values, you should instead use resetGlitchFilterWithReset with an additional power-on reset, or holdReset if filtering is only needed on deassertion.

At power-on, the reset will be asserted. If the filtered reset input remains unasserted, the output reset will deassert after glitchlessPeriod clock cycles.

If resetGlitchFilter is used in a domain with asynchronous resets (Asynchronous), resetGlitchFilter will first synchronize the reset input with dualFlipFlopSynchronizer.

Example 1

>>> let sampleResetN n = sampleN n . unsafeToActiveHigh
>>> let resetFromList = unsafeFromActiveHigh . fromList
>>> let rst = resetFromList [True, True, False, False, True, False, False, True, True, False, True, True]
>>> sampleResetN 12 (resetGlitchFilter d2 (clockGen @XilinxSystem) rst)
[True,True,True,True,False,False,False,False,False,True,True,True]

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

Example:

>>> sampleN @System 8 (unsafeToActiveHigh (holdReset (SNat @2)))
[True,True,True,False,False,False,False,False]

holdReset holds the reset for an additional 2 clock cycles for a total of 3 clock cycles where the reset is asserted.

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 constraint that indicates the component has a hidden Clock

Click here to read more about hidden clocks, resets, and enables

Hide the Clock argument of a component, so it can be routed implicitly.

Click here to read more about hidden clocks, resets, and enables

Expose a hidden Clock argument of a component, so it can be applied explicitly.

Click here to read more about hidden clocks, resets, and enables

Example

>>> reg = register 5 (reg + 1)
>>> sig = exposeClock reg clockGen
>>> sampleN @System 10 sig
[5,5,6,7,8,9,10,11,12,13]

>>> reg = register 5 (reg + 1)
>>> sig = exposeClock @System reg clockGen
>>> sampleN 10 sig
[5,5,6,7,8,9,10,11,12,13]

Connect an explicit Clock to a function with a hidden Clock.

Click here to read more about hidden clocks, resets, and enables

Example

>>> reg = register 5 (reg + 1)
>>> sig = withClock clockGen reg
>>> sampleN @System 10 sig
[5,5,6,7,8,9,10,11,12,13]

>>> reg = register 5 (reg + 1)
>>> sig = withClock @System clockGen reg
>>> sampleN 10 sig
[5,5,6,7,8,9,10,11,12,13]

Connect a hidden Clock to an argument where a normal Clock argument was expected.

Click here to read more about hidden clocks, resets, and enables

A constraint that indicates the component needs a Reset

Click here to read more about hidden clocks, resets, and enables

Hide the Reset argument of a component, so it can be routed implicitly.

Click here to read more about hidden clocks, resets, and enables

Expose a hidden Reset argument of a component, so it can be applied explicitly.

Example

>>> reg = register 5 (reg + 1)
>>> sig = exposeReset reg resetGen
>>> sampleN @System 10 sig
[5,5,6,7,8,9,10,11,12,13]

>>> reg = register 5 (reg + 1)
>>> sig = exposeReset @System reg resetGen
>>> sampleN 10 sig
[5,5,6,7,8,9,10,11,12,13]

Connect an explicit Reset to a function with a hidden Reset.

Example

>>> reg = register 5 (reg + 1)
>>> sig = withReset resetGen reg
>>> sampleN @System 10 sig
[5,5,6,7,8,9,10,11,12,13]

>>> reg = register 5 (reg + 1)
>>> sig = withReset @System resetGen reg
>>> sampleN 10 sig
[5,5,6,7,8,9,10,11,12,13]

Connect a hidden Reset to an argument where a normal Reset argument was expected.

Click here to read more about hidden clocks, resets, and enables

A constraint that indicates the component needs an Enable

Click here to read more about hidden clocks, resets, and enables

Hide the Enable argument of a component, so it can be routed implicitly.

Click here to read more about hidden clocks, resets, and enables

Expose a hidden Enable argument of a component, so it can be applied explicitly.

Click here to read more about hidden clocks, resets, and enables

Example

>>> reg = register 5 (reg + 1)
>>> sig = exposeEnable reg enableGen
>>> sampleN @System 10 sig
[5,5,6,7,8,9,10,11,12,13]

>>> reg = register 5 (reg + 1)
>>> sig = exposeEnable @System reg enableGen
>>> sampleN 10 sig
[5,5,6,7,8,9,10,11,12,13]

Connect an explicit Enable to a function with a hidden Enable.

Click here to read more about hidden clocks, resets, and enables

Example

>>> reg = register 5 (reg + 1)
>>> sig = withEnable enableGen reg
>>> sampleN @System 10 sig
[5,5,6,7,8,9,10,11,12,13]

>>> reg = register 5 (reg + 1)
>>> sig = withEnable @System enableGen reg
>>> sampleN 10 sig
[5,5,6,7,8,9,10,11,12,13]