clash-prelude-0.7.2: CAES Language for Synchronous Hardware - Prelude library

CLaSH.Prelude

Description

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:

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.

Synopsis

# Creating synchronous sequential circuits

Arguments

 :: (s -> i -> (s, o)) Transfer function in mealy machine form: `state -> input -> (newstate,output)` -> 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...
```

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

Arguments

 :: (Bundle i, Bundle o) => (s -> i -> (s, o)) Transfer function in mealy machine form: `state -> input -> (newstate,output)` -> 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)
```

Arguments

 :: (Bundle i, Bundle o) => (s -> i -> (s, o)) Transfer function in mealy machine form: `state -> input -> (newstate,output)` -> 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)] :: [(Int,Int)]
```[(8,8),(1,1),(2,2),(3,3)...
```

# BlockRAM primitives

Arguments

 :: (KnownNat n, KnownNat m) => Vec n a Initial content of the BRAM, also determines the size, `n`, of the BRAM.NB: MUST be a constant. -> Signal (Unsigned m) Write address `w` -> Signal (Unsigned m) Read address `r` -> Signal Bool Write enable -> Signal a Value to write (at address `w`) -> Signal a Value of the `blockRAM` at address `r` from the previous clock cycle

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

Arguments

 :: (KnownNat (2 ^ n), KnownNat n) => Vec (2 ^ n) a Initial content of the BRAM, also determines the size, `2^n`, of the BRAM.NB: MUST be a constant. -> Signal (Unsigned n) Write address `w` -> Signal (Unsigned n) Read address `r` -> Signal Bool Write enable -> Signal a Value to write (at address `w`) -> Signal a Value of the `blockRAM` at address `r` from the previous clock cycle

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

# Utility functions

Arguments

 :: (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::Int,2,3,4,5] :: [Vec 4 Int]
```[<1,0,0,0>,<2,1,0,0>,<3,2,1,0>,<4,3,2,1>,<5,4,3,2>...
```

Arguments

 :: (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::Int,2,3,4] :: [Vec 3 Int]
```[<0,0,0>,<1,0,0>,<2,1,0>,<3,2,1>,<4,3,2>...
```

Arguments

 :: (Bounded a, Eq a) => a Starting value -> Signal a -> Signal Bool

Give a pulse when the `Signal` goes from `minBound` to `maxBound`

Arguments

 :: (Bounded a, Eq a) => a Starting value -> Signal a -> Signal Bool

Give a pulse when the `Signal` goes from `maxBound` to `minBound`

# Testbench functions

Arguments

 :: (Eq a, Show a) => Signal' t a Checked value -> Signal' t a Expected value -> Signal' t b Return valued -> Signal' t 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 `coutputVerifier`.

NB: This function is can be used in synthesizable designs.

Arguments

 :: KnownNat l => Vec l a Samples to generate -> Signal a Signal of given samples

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])
```
````>>> ````sampleN 13 testInput
```[1,3,5,7,9,11,13,15,17,19,21,21,21]
```

Arguments

 :: (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]))
```
````>>> ````import qualified Data.List as List
````>>> ````sampleN 12 (expectedOutput (fromList ([0..10] List.++ [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

## Type-level functions

class Lift t where

Methods

lift :: t -> Q Exp

Instances

 Lift Bool Lift Char Lift Double Lift Float Lift Int Lift Int8 Lift Int16 Lift Int32 Lift Int64 Lift Integer Lift Word Lift Word8 Lift Word16 Lift Word32 Lift Word64 Lift () Lift Natural Lift a => Lift [a] Integral a => Lift (Ratio 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 (Signal' clk a) Lift a => Lift (Vec n 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

### Other

module Data.Bits

It instead exports the identically named functions defined in terms of `Vec` at CLaSH.Sized.Vector.