Safe Haskell | None |
---|---|
Language | Haskell2010 |
CλaSH (pronounced ‘clash’) is a functional hardware description language that borrows both its syntax and semantics from the functional programming language Haskell. The merits of using a functional language to describe hardware comes from the fact that combinational circuits can be directly modeled as mathematical functions and that functional languages lend themselves very well at describing and (de-)composing mathematical functions.
This package provides:
- Prelude library containing datatypes and functions for circuit design
To use the library:
- Import CLaSH.Prelude
- Additionally import CLaSH.Prelude.Explicit if you want to design explicitly clocked circuits in a multi-clock setting
For now, CLaSH.Prelude is also the best starting point for exploring the library. A preliminary version of a tutorial can be found in CLaSH.Tutorial.
- mealy :: (s -> i -> (s, o)) -> s -> Signal i -> Signal o
- mealyB :: (Bundle i, Bundle o) => (s -> i -> (s, o)) -> s -> Unbundled' i -> Unbundled' o
- (<^>) :: (Bundle i, Bundle o) => (s -> i -> (s, o)) -> s -> Unbundled' i -> Unbundled' o
- registerB :: Bundle a => a -> Unbundled' a -> Unbundled' a
- blockRam :: (KnownNat n, KnownNat m) => Vec n a -> Signal (Unsigned m) -> Signal (Unsigned m) -> Signal Bool -> Signal a -> Signal a
- blockRamPow2 :: (KnownNat (2 ^ n), KnownNat n) => Vec (2 ^ n) a -> Signal (Unsigned n) -> Signal (Unsigned n) -> Signal Bool -> Signal a -> Signal a
- window :: (KnownNat n, Default a) => Signal a -> Vec (n + 1) (Signal a)
- windowD :: (KnownNat (n + 1), Default a) => Signal a -> Vec (n + 1) (Signal a)
- isRising :: (Bounded a, Eq a) => a -> Signal a -> Signal Bool
- isFalling :: (Bounded a, Eq a) => a -> Signal a -> Signal Bool
- sassert :: (Eq a, Show a) => Signal a -> Signal a -> Signal b -> Signal b
- stimuliGenerator :: forall l a. KnownNat l => Vec l a -> Signal a
- outputVerifier :: forall l a. (KnownNat l, Eq a, Show a) => Vec l a -> Signal a -> Signal Bool
- module CLaSH.Signal
- module CLaSH.Signal.Delayed
- module CLaSH.Prelude.DataFlow
- module CLaSH.Sized.BitVector
- module CLaSH.Prelude.BitIndex
- module CLaSH.Prelude.BitReduction
- module CLaSH.Sized.Signed
- module CLaSH.Sized.Unsigned
- module CLaSH.Sized.Index
- module CLaSH.Sized.Fixed
- module CLaSH.Sized.Vector
- module GHC.TypeLits
- module CLaSH.Promoted.Nat
- module CLaSH.Promoted.Nat.Literals
- module CLaSH.Promoted.Nat.TH
- module CLaSH.Promoted.Ord
- class Lift t where
- deriveLift :: Name -> Q [Dec]
- module CLaSH.Class.BitPack
- module CLaSH.Class.Num
- module CLaSH.Class.Resize
- module Control.Applicative
- module Data.Bits
- module Data.Default
- module Prelude
Creating synchronous sequential circuits
:: (s -> i -> (s, o)) | Transfer function in mealy machine form:
|
-> s | Initial state |
-> Signal i -> Signal o | Synchronous sequential function with input and output matching that of the mealy machine |
Create a synchronous function from a combinational function describing a mealy machine
mac :: Int -- Current state -> (Int,Int) -- Input -> (Int,Int) -- (Updated state, output) mac s (x,y) = (s',s) where s' = x * y + s topEntity :: Signal (Int, Int) -> Signal Int topEntity = mealy mac 0
>>>
simulate topEntity [(1,1),(2,2),(3,3),(4,4),...
[0,1,5,14,30,...
Synchronous sequential functions can be composed just like their combinational counterpart:
dualMac :: (Signal Int, Signal Int) -> (Signal Int, Signal Int) -> Signal Int dualMac (a,b) (x,y) = s1 + s2 where s1 = mealy mac 0 (bundle' (a,x)) s2 = mealy mac 0 (bundle' (b,y))
:: (Bundle i, Bundle o) | |
=> (s -> i -> (s, o)) | Transfer function in mealy machine form:
|
-> s | Initial state |
-> Unbundled' i -> Unbundled' o | Synchronous sequential function with input and output matching that of the mealy machine |
A version of mealy
that does automatic Bundle
ing
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'
(i1,c)))
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 (i1,c)
:: (Bundle i, Bundle o) | |
=> (s -> i -> (s, o)) | Transfer function in mealy machine form:
|
-> s | Initial state |
-> Unbundled' i -> Unbundled' o | Synchronous sequential function with input and output matching that of the mealy machine |
Infix version of mealyB
registerB :: Bundle a => a -> Unbundled' a -> Unbundled' a Source
Create a register
function for product-type like signals (e.g. '(Signal a, Signal b)')
rP :: (Signal Int,Signal Int) -> (Signal Int, Signal Int) rP = registerB (8,8)
>>>
simulateB rP [(1,1),(2,2),(3,3),...
[(8,8),(1,1),(2,2),(3,3),...
BlockRAM primitives
:: (KnownNat n, KnownNat m) | |
=> Vec n a | Initial content of the BRAM, also
determines the size, NB: MUST be a constant. |
-> Signal (Unsigned m) | Write address |
-> Signal (Unsigned m) | Read address |
-> Signal Bool | Write enable |
-> Signal a | Value to write (at address |
-> Signal a | Value of the |
Create a blockRAM with space for n
elements.
- NB: Read value is delayed by 1 cycle
- NB: Initial output value is
undefined
bram40 :: Signal (Unsigned 6) -> Signal (Unsigned 6) -> Signal Bool -> Signal Bit -> Signal Bit bram40 = blockRam (replicate d40 H)
:: (KnownNat (2 ^ n), KnownNat n) | |
=> Vec (2 ^ n) a | Initial content of the BRAM, also
determines the size, NB: MUST be a constant. |
-> Signal (Unsigned n) | Write address |
-> Signal (Unsigned n) | Read address |
-> Signal Bool | Write enable |
-> Signal a | Value to write (at address |
-> Signal a | Value of the |
Create a blockRAM with space for 2^n
elements
- NB: Read value is delayed by 1 cycle
- NB: Initial output value is
undefined
bram32 :: Signal (Unsigned 5) -> Signal (Unsigned 5) -> Signal Bool -> Signal Bit -> Signal Bit bram32 = blockRamPow2 (replicate d32 H)
Utility functions
:: (KnownNat n, Default a) | |
=> Signal a | Signal to create a window over |
-> Vec (n + 1) (Signal a) | Window of at least size 1 |
Give a window over a Signal
window4 :: Signal Int -> Vec 4 (Signal Int) window4 = window
>>>
simulateB window4 [1,2,3,4,5,...
[<1,0,0,0>, <2,1,0,0>, <3,2,1,0>, <4,3,2,1>, <5,4,3,2>,...
:: (KnownNat (n + 1), Default a) | |
=> Signal a | Signal to create a window over |
-> Vec (n + 1) (Signal a) | Window of at least size 1 |
Give a delayed window over a Signal
windowD3 :: Signal Int -> Vec 3 (Signal Int) windowD3 = windowD
>>>
simulateB windowD3 [1,2,3,4,...
[<0,0,0>, <1,0,0>, <2,1,0>, <3,2,1>, <4,3,2>,...
Testbench functions
:: (Eq a, Show a) | |
=> Signal a | Checked value |
-> Signal a | Expected value |
-> Signal b | Returned value |
-> Signal b |
Compares the first two arguments for equality and logs a warning when they
are not equal. The second argument is considered the expected value. This
function simply returns the third argument unaltered as its result. This
function is used by outputVerifier
.
This function is translated to the following VHDL:
sassert_block : block begin -- pragma translate_off process(clk_1000,reset_1000,arg0,arg1) is begin if (rising_edge(clk_1000) or rising_edge(reset_1000)) then assert (arg0 = arg1) report ("expected: " & to_string (arg1) & \", actual: \" & to_string (arg0)) severity error; end if; end process; -- pragma translate_on result <= arg2; end block;
And can, due to the pragmas, be used in synthesizable designs
To be used as a one of the functions to create the "magical" testInput
value, which the CλaSH compilers looks for to create the stimulus generator
for the generated VHDL testbench.
Example:
testInput :: Signal Int testInput = stimuliGenerator $(v [(1::Int),3..21])
>>>
sample testInput
[1,3,5,7,9,11,13,15,17,19,21,21,21,...
:: forall l a . (KnownNat l, Eq a, Show a) | |
=> Vec l a | Samples to compare with |
-> Signal a | Signal to verify |
-> Signal Bool | Indicator that all samples are verified |
To be used as a functions to generate the "magical" expectedOutput
function, which the CλaSH compilers looks for to create the signal verifier
for the generated VHDL testbench.
Example:
expectedOutput :: Signal Int -> Signal Bool expectedOutput = outputVerifier $(v ([70,99,2,3,4,5,7,8,9,10]::[Int]))
>>>
sample (expectedOutput (fromList ([0..10] ++ [10,10,10])))
[ expected value: 70, not equal to actual value: 0 False, expected value: 99, not equal to actual value: 1 False,False,False,False,False, expected value: 7, not equal to actual value: 6 False, expected value: 8, not equal to actual value: 7 False, expected value: 9, not equal to actual value: 8 False, expected value: 10, not equal to actual value: 9 False,True,True,...
Exported modules
Synchronous signals
module CLaSH.Signal
module CLaSH.Signal.Delayed
DataFlow interface
module CLaSH.Prelude.DataFlow
Datatypes
Bit vectors
module CLaSH.Sized.BitVector
module CLaSH.Prelude.BitIndex
module CLaSH.Prelude.BitReduction
Arbitrary-width numbers
module CLaSH.Sized.Signed
module CLaSH.Sized.Unsigned
module CLaSH.Sized.Index
Fixed point numbers
module CLaSH.Sized.Fixed
Fixed size vectors
module CLaSH.Sized.Vector
Type-level natural numbers
module GHC.TypeLits
module CLaSH.Promoted.Nat
module CLaSH.Promoted.Nat.Literals
module CLaSH.Promoted.Nat.TH
Type-level functions
module CLaSH.Promoted.Ord
Template Haskell
class Lift t where
Lift Bool | |
Lift Char | |
Lift Int | |
Lift Integer | |
Lift Rational | |
Lift Name | |
Lift () | |
Lift ModName | |
Lift PkgName | |
Lift OccName | |
Lift NameFlavour | |
Lift NameSpace | |
Lift a => Lift [a] | |
Lift a => Lift (Maybe a) | |
KnownNat n => Lift (Index n) | |
KnownNat n => Lift (BitVector n) | |
KnownNat n => Lift (Signed n) | |
KnownNat n => Lift (Unsigned n) | |
(Lift a, Lift b) => Lift (Either a b) | |
(Lift a, Lift b) => Lift (a, b) | |
Lift a => Lift (CSignal clk a) | |
Lift a => Lift (DSignal delay a) | |
(Lift a, Lift b, Lift c) => Lift (a, b, c) | |
(Lift (rep ((+) int frac)), KnownNat frac, KnownNat int, Typeable (Nat -> *) rep) => Lift (Fixed rep int frac) | |
(Lift a, Lift b, Lift c, Lift d) => Lift (a, b, c, d) | |
(Lift a, Lift b, Lift c, Lift d, Lift e) => Lift (a, b, c, d, e) | |
(Lift a, Lift b, Lift c, Lift d, Lift e, Lift f) => Lift (a, b, c, d, e, f) | |
(Lift a, Lift b, Lift c, Lift d, Lift e, Lift f, Lift g) => Lift (a, b, c, d, e, f, g) |
deriveLift :: Name -> Q [Dec]
Derive Lift instances for the given datatype.
Type classes
CLaSH
module CLaSH.Class.BitPack
module CLaSH.Class.Num
module CLaSH.Class.Resize
Other
module Control.Applicative
module Data.Bits
module Data.Default
module Prelude