CLaSH.Signal.Explicit

Explicitly clocked synchronous signal

CλaSH supports explicitly clocked Signals in the form of:

Signal' (clk :: Clock) a

Where a is the type of the elements, and clk is the clock to which the signal is synchronised. The type-parameter, clk, is of the kind Clock which has types of the following shape:

Clk {- name :: -} Symbol {- period :: -} Nat

Where name is a type-level string (Symbol) representing the the name of the clock, and period is a type-level natural number (Nat) representing the clock period. Two concrete instances of a Clk could be:

type ClkA500  = Clk "A500" 500
type ClkB3250 = Clk "B3250" 3250

The periods of these clocks are however dimension-less, they do not refer to any explicit time-scale (e.g. nano-seconds). The reason for the lack of an explicit time-scale is that the CλaSH compiler would not be able guarantee that the circuit can run at the specified frequency. The clock periods are just there to indicate relative frequency differences between two different clocks. That is, a signal:

Signal' ClkA500 a

is synchronized to a clock that runs 6.5 times faster than the clock to which the signal:

Signal' ClkB3250 a

is synchronized to.

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

data Signal' clk a

A synchronized signal with samples of type a, explicitly synchronized to a clock clk

NB: The constructor, (:-), is not synthesisable.

Instances

Functor (Signal' clk)

Applicative (Signal' clk)

Foldable (Signal' clk)

NB: Not synthesisable

NB: In "foldr f z s":

• The function f should be lazy in its second argument.
• The z element will never be used.

Traversable (Signal' clk)

Bounded a => Bounded (Signal' clk a)

Enum a => Enum (Signal' clk a)

WARNING: fromEnum is undefined, use fromEnum1 instead

Eq (Signal' clk a)

WARNING: (==) and (/=) are undefined, use (.==.) and (./=.) instead

Fractional a => Fractional (Signal' clk a)

Integral a => Integral (Signal' clk a)

WARNING: toInteger is undefined, use toInteger1 instead

Num a => Num (Signal' clk a)

Ord a => Ord (Signal' clk a)

WARNING: compare, (<), (>=), (>), and (<=) are undefined, use compare1, (.<.), (.>=.), (.>.), and (.<=.) instead

(Num a, Ord a) => Real (Signal' clk a)

WARNING: toRational is undefined, use toRational1 instead

Show a => Show (Signal' clk a)

Arbitrary a => Arbitrary (Signal' clk a)

CoArbitrary a => CoArbitrary (Signal' clk a)

Bits a => Bits (Signal' clk a)

WARNING: testBit and popCount are undefined, use testBit1 and popCount1 instead

FiniteBits a => FiniteBits (Signal' clk a)

Default a => Default (Signal' clk a)

Lift a => Lift (Signal' clk a)

SaturatingNum a => SaturatingNum (Signal' clk a)

ExtendingNum a b => ExtendingNum (Signal' clk a) (Signal' clk b)

type AResult (Signal' clk a) (Signal' clk b) = Signal' clk (AResult a b)

type MResult (Signal' clk a) (Signal' clk b) = Signal' clk (MResult a b)

Clock domain crossing

Clock

data Clock

A clock with a name (Symbol) and period (Nat)

Constructors

Clk Symbol Nat

data SClock clk where

Singleton value for a type-level Clock with the given name and period

Constructors

SClock :: SSymbol name -> SNat period -> SClock (Clk name period)

Instances

Show (SClock clk)

sclock :: (KnownSymbol name, KnownNat period) => SClock (Clk name period)

Create a singleton clock

type ClkA = Clk "A" 100

clkA :: SClock ClkA
clkA = sclock

withSClock :: (KnownSymbol name, KnownNat period) => (SClock (Clk name period) -> a) -> a

Supply a function with a singleton clock clk according to the context

type SystemClock = Clk "system" 1000

The standard system clock with a period of 1000

systemClock :: SClock SystemClock

The singleton clock for SystemClock

freqCalc :: [Integer] -> [Integer]

Calculate relative periods given a list of frequencies.

So for example, you have one part of your design connected to an ADC running at 20 MHz, one part of your design connected to a DAC running at 36 MHz, and the rest of your system is running at 50 MHz. What are the relative (integer) clock periods in CλaSH, such that their ratios correspond to the ratios between the actual clock frequencies.

For this we use freqCalc:

>>> freqCalc [20,36,50]
[45,25,18]

So that we create the proper clocks:

type ADC20 = Clk "ADC" 45
type DAC36 = Clk "DAC" 25
type Sys50 = Clk "Sys" 18

sys50 :: SClock Sys50
sys50 = sclock

adc20 :: SClock ADC20
adc20 = sclock

dac36 :: SClock DAC36
dac36 = sclock

NB: This function is not synthesisable

Synchronisation primitive

unsafeSynchronizer

Arguments

:: SClock clk1

Clock of the incoming signal

-> SClock clk2

Clock of the outgoing signal

-> Signal' clk1 a

-> Signal' clk2 a

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

dualFlipFlop :: SClock clkA -> SClock clkB
             -> Signal' clkA Bit -> Signal' clkB Bit
dualFlipFlop clkA clkB = register' clkB low . register' clkB low
                       . unsafeSynchronizer clkA clkB

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

type Clk7 = Clk "clk7" 7

clk7 :: SClock Clk7
clk7 = sclock

and

type Clk2 = Clk "clk2" 2

clk2 :: SClock Clk2
clk2 = sclock

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

register' clk7 i $
unsafeSynchronizer clk2 clk7 $
register' clk2 j $
unsafeSynchronizer clk7 clk2 $
register' clk7 k s

==

i :- j :- s

Something we can easily observe:

oversampling = register' clk2 99 . unsafeSynchronizer clk7 clk2
             . register' clk7 50
almostId     = register' clk7 70 . unsafeSynchronizer clk2 clk7
             . register' clk2 99 . unsafeSynchronizer clk7 clk2
             . register' clk7 50

>>> sampleN 37 (oversampling (fromList [1..10]))
[99,50,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 (fromList [1..10]))
[70,99,1,2,3,4,5,6,7,8,9,10]

Basic circuit functions

register' :: SClock clk -> a -> Signal' clk a -> Signal' clk a

"register' i s" delays the values in Signal' s for one cycle, and sets the value at time 0 to i

type ClkA = Clk "A" 100

clkA :: SClock ClkA
clkA = sclock

>>> sampleN 3 (register' clkA 8 (fromList [1,2,3,4]))
[8,1,2]

regEn' :: SClock clk -> a -> Signal' clk Bool -> Signal' clk a -> Signal' clk a

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

type ClkA = Clk "A" 100
clkA :: SClock ClkA
clkA = sclock

oscillate = register' clkA False (not1 oscillate)
count     = regEn' clkA 0 oscillate (count + 1)

We get:

>>> sampleN 8 oscillate
[False,True,False,True,False,True,False,True]
>>> sampleN 8 count
[0,0,1,1,2,2,3,3]

Product/Signal isomorphism

class Bundle a where

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

Minimal complete definition

Nothing

Associated Types

type Unbundled' clk a

Methods

bundle' :: SClock clk -> Unbundled' clk a -> Signal' clk a

Example:

bundle' :: (Signal' clk a, Signal' clk b) -> Signal' clk (a,b)

However:

bundle' :: Signal' clk Bit -> Signal' clk Bit

unbundle' :: SClock clk -> Signal' clk a -> Unbundled' clk a

Example:

unbundle' :: Signal' clk (a,b) -> (Signal' clk a, Signal' clk b)

However:

unbundle' :: Signal' clk Bit -> Signal' clk Bit

Instances

Bundle Bool

Bundle Double

Bundle Float

Bundle Int

Bundle Integer

Bundle ()

Bundle (Maybe a)

Bundle (Index n)

Bundle (BitVector n)

Bundle (Signed n)

Bundle (Unsigned n)

Bundle (Either a b)

Bundle (a, b)

KnownNat n => Bundle (Vec n a)

Bundle (a, b, c)

Bundle (Fixed rep int frac)

Bundle (a, b, c, d)

Bundle (a, b, c, d, e)

Bundle (a, b, c, d, e, f)

Bundle (a, b, c, d, e, f, g)

Bundle (a, b, c, d, e, f, g, h)

Simulation functions (not synthesisable)

simulateB'

Arguments

:: (Bundle a, Bundle b)

=> SClock clk1

Clock of the incoming signal

-> SClock clk2

Clock of the outgoing signal

-> (Unbundled' clk1 a -> Unbundled' clk2 b)

Function to simulate

-> [a]

-> [b]

Simulate a (Unbundled' clk1 a -> Unbundled' clk2 b) function given a list of samples of type a

>>> simulateB' clkA clkA (unbundle' clkA . register' clkA (8,8) . bundle' clkA) [(1,1), (2,2), (3,3)] :: [(Int,Int)]
[(8,8),(1,1),(2,2),(3,3)...

NB: This function is not synthesisable

Strict version

simulateB'_strict

Arguments

:: (Bundle a, Bundle b, NFData a, NFData b)

=> SClock clk1

Clock of the incoming signal

-> SClock clk2

Clock of the outgoing signal

-> (Unbundled' clk1 a -> Unbundled' clk2 b)

Function to simulate

-> [a]

-> [b]

Deprecated: simulateB' will be strict in CLaSH 1.0, and simulateB'_strict will be removed

Version of simulateB' that strictly evaluates the input elements and the output elements

N.B: Exceptions are lazily rethrown