diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog for [`clash-prelude` package](http://hackage.haskell.org/package/clash-prelude) +## 0.10.5 *January 13th 2015* +* New features: + * Add `readNew` to `CLaSH.Prelude.BlockRam`: create a read-after-write blockRAM from a read-before-write blockRAM. + * `popCount` functions for `BitVector`, `Signed`, and `Unsigned` are now synthesisable. + * Add `parNDF` to `CLaSH.Prelude.DataFlow`: compose _N_ dataflow circuits in parallel. + * Add and instance `Vec n a` for `LockStep` in `CLaSH.Prelude.DataFlow`: have _N_ dataflow circuits operate in lock-step. + ## 0.10.4 *December 11th 2015* * New features: * Add `pureDF` to `CLaSH.Prelude.DataFlow`: lift combinational circuits to `DataFlow` circuits. diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ [![Hackage Dependencies](https://img.shields.io/hackage-deps/v/clash-prelude.svg?style=flat)](http://packdeps.haskellers.com/feed?needle=exact%3Aclash-prelude) __WARNING__ -Only works with GHC-7.10.* (http://www.haskell.org/ghc/download_ghc_7_10_2)! +Only works with GHC-7.10.* (http://www.haskell.org/ghc/download_ghc_7_10_3)! CλaSH (pronounced ‘clash’) is a functional hardware description language that borrows both its syntax and semantics from the functional programming language diff --git a/clash-prelude.cabal b/clash-prelude.cabal --- a/clash-prelude.cabal +++ b/clash-prelude.cabal @@ -1,5 +1,5 @@ Name: clash-prelude -Version: 0.10.4 +Version: 0.10.5 Synopsis: CAES Language for Synchronous Hardware - Prelude library Description: CλaSH (pronounced ‘clash’) is a functional hardware description language that @@ -191,5 +191,4 @@ else build-depends: base >= 4 && < 5, - doctest >= 0.9.1 && < 0.11, - Glob >= 0.7 && < 0.8 + doctest >= 0.9.1 && < 0.11 diff --git a/src/CLaSH/Prelude.hs b/src/CLaSH/Prelude.hs --- a/src/CLaSH/Prelude.hs +++ b/src/CLaSH/Prelude.hs @@ -60,6 +60,9 @@ -- ** BlockRAM primitives initialised with a data file , blockRamFile , blockRamFilePow2 + -- * BlockRAM read/write conflict resolution + , readNew + , readNew' -- * Utility functions , window , windowD diff --git a/src/CLaSH/Prelude/BlockRam.hs b/src/CLaSH/Prelude/BlockRam.hs --- a/src/CLaSH/Prelude/BlockRam.hs +++ b/src/CLaSH/Prelude/BlockRam.hs @@ -350,6 +350,9 @@ -- * BlockRAM synchronised to an arbitrary clock , blockRam' , blockRamPow2' + -- * Read/Write conflict resolution + , readNew + , readNew' -- * Internal , blockRam# ) @@ -361,7 +364,7 @@ import Data.Array.ST.Safe (STArray) import GHC.TypeLits (KnownNat, type (^)) -import CLaSH.Signal (Signal) +import CLaSH.Signal (Signal, mux) import CLaSH.Signal.Explicit (Signal', SClock, register', systemClock) import CLaSH.Signal.Bundle (bundle') import CLaSH.Sized.Unsigned (Unsigned) @@ -383,6 +386,7 @@ -- -- * See "CLaSH.Prelude.BlockRam#usingrams" for more information on how to use a -- Block RAM. +-- * Use the adapter 'readNew' for obtaining write-before-read semantics like this: @readNew (blockRam inits) wr rd en dt@. blockRam :: (KnownNat n, Enum addr) => Vec n a -- ^ Initial content of the BRAM, also -- determines the size, @n@, of the BRAM. @@ -413,6 +417,7 @@ -- -- * See "CLaSH.Prelude.BlockRam#usingrams" for more information on how to use a -- Block RAM. +-- * Use the adapter 'readNew' for obtaining write-before-read semantics like this: @readNew (blockRamPow2 inits) wr rd en dt@. blockRamPow2 :: (KnownNat (2^n), KnownNat n) => Vec (2^n) a -- ^ Initial content of the BRAM, also -- determines the size, @2^n@, of the BRAM. @@ -448,6 +453,7 @@ -- -- * See "CLaSH.Prelude.BlockRam#usingrams" for more information on how to use a -- Block RAM. +-- * Use the adapter 'readNew'' for obtaining write-before-read semantics like this: @readNew' clk (blockRam' clk inits) wr rd en dt@. blockRam' :: (KnownNat n, Enum addr) => SClock clk -- ^ 'Clock' to synchronize to -> Vec n a -- ^ Initial content of the BRAM, also @@ -485,6 +491,7 @@ -- -- * See "CLaSH.Prelude.BlockRam#usingrams" for more information on how to use a -- Block RAM. +-- * Use the adapter 'readNew'' for obtaining write-before-read semantics like this: @readNew' clk (blockRamPow2' clk inits) wr rd en dt@. blockRamPow2' :: (KnownNat n, KnownNat (2^n)) => SClock clk -- ^ 'Clock' to synchronize to -> Vec (2^n) a -- ^ Initial content of the BRAM, also @@ -528,3 +535,21 @@ d' <- readArray ram r when e (writeArray ram w d) return d' + +-- | Create read-after-write blockRAM from a read-before-write one (synchronised to specified clock) +-- +readNew' :: Eq addr => SClock clk -> (Signal' clk addr -> Signal' clk addr -> Signal' clk Bool -> Signal' clk a -> Signal' clk a) -> Signal' clk addr -> Signal' clk addr -> Signal' clk Bool -> Signal' clk a -> Signal' clk a +readNew' clk ram wrAddr rdAddr wrEn wrData = mux wasSame wasWritten $ ram wrAddr rdAddr wrEn wrData + where sameAddr = (==) <$> wrAddr <*> rdAddr + wasSame = register' clk False ((&&) <$> wrEn <*> sameAddr) + wasWritten = register' clk undefined wrData + +-- | Create read-after-write blockRAM from a read-before-write one (synchronised to system clock) +-- +-- >>> import CLaSH.Prelude +-- >>> :t readNew (blockRam (0 :> 1 :> Nil)) +-- readNew (blockRam (0 :> 1 :> Nil)) +-- :: (Enum addr, Eq addr, Num a) => +-- Signal addr -> Signal addr -> Signal Bool -> Signal a -> Signal a +readNew :: Eq addr => (Signal addr -> Signal addr -> Signal Bool -> Signal a -> Signal a) -> Signal addr -> Signal addr -> Signal Bool -> Signal a -> Signal a +readNew = readNew' systemClock diff --git a/src/CLaSH/Prelude/BlockRam/File.hs b/src/CLaSH/Prelude/BlockRam/File.hs --- a/src/CLaSH/Prelude/BlockRam/File.hs +++ b/src/CLaSH/Prelude/BlockRam/File.hs @@ -125,6 +125,7 @@ -- -- * See "CLaSH.Prelude.BlockRam#usingrams" for more information on how to use a -- Block RAM. +-- * Use the adapter 'readNew' for obtaining write-before-read semantics like this: @readNew (blockRamFile size file) wr rd en dt@. -- * See "CLaSH.Prelude.BlockRam.File#usingramfiles" for more information on how -- to instantiate a Block RAM with the contents of a data file. -- * See "CLaSH.Sized.Fixed#creatingdatafiles" for ideas on how to create your @@ -164,6 +165,7 @@ -- -- * See "CLaSH.Prelude.BlockRam#usingrams" for more information on how to use a -- Block RAM. +-- * Use the adapter 'readNew' for obtaining write-before-read semantics like this: @readNew (blockRamFilePow2 file) wr rd en dt@. -- * See "CLaSH.Prelude.BlockRam.File#usingramfiles" for more information on how -- to instantiate a Block RAM with the contents of a data file. -- * See "CLaSH.Sized.Fixed#creatingdatafiles" for ideas on how to create your @@ -202,6 +204,7 @@ -- -- * See "CLaSH.Prelude.BlockRam#usingrams" for more information on how to use a -- Block RAM. +-- * Use the adapter 'readNew'' for obtaining write-before-read semantics like this: @readNew' clk (blockRamFilePow2' clk file) wr rd en dt@. -- * See "CLaSH.Prelude.BlockRam.File#usingramfiles" for more information on how -- to instantiate a Block RAM with the contents of a data file. -- * See "CLaSH.Sized.Fixed#creatingdatafiles" for ideas on how to create your @@ -241,6 +244,7 @@ -- -- * See "CLaSH.Prelude.BlockRam#usingrams" for more information on how to use a -- Block RAM. +-- * Use the adapter 'readNew'' for obtaining write-before-read semantics like this: @readNew' clk (blockRamFile' clk size file) wr rd en dt@. -- * See "CLaSH.Prelude.BlockRam.File#usingramfiles" for more information on how -- to instantiate a Block RAM with the contents of a data file. -- * See "CLaSH.Sized.Fixed#creatingdatafiles" for ideas on how to create your diff --git a/src/CLaSH/Prelude/DataFlow.hs b/src/CLaSH/Prelude/DataFlow.hs --- a/src/CLaSH/Prelude/DataFlow.hs +++ b/src/CLaSH/Prelude/DataFlow.hs @@ -5,6 +5,7 @@ {-# LANGUAGE ScopedTypeVariables #-} {-# LANGUAGE TypeFamilies #-} {-# LANGUAGE TypeOperators #-} +{-# LANGUAGE UndecidableInstances #-} {-# LANGUAGE Safe #-} @@ -35,6 +36,7 @@ , swapDF , secondDF , parDF + , parNDF , loopDF , loopDF_nobuf -- * Lock-Step operation @@ -43,7 +45,8 @@ where import GHC.TypeLits (KnownNat, KnownSymbol, type (+), type (^)) -import Prelude hiding ((++), (!!), length, repeat) +import Prelude hiding ((++), (!!), length, map, repeat, tail, unzip3, zip3 + , zipWith) import CLaSH.Class.BitPack (boolToBV) import CLaSH.Class.Resize (truncateB) @@ -54,7 +57,7 @@ import CLaSH.Signal.Bundle (Bundle (..)) import CLaSH.Signal.Explicit (Clock (..), Signal', SystemClock, sclock) import CLaSH.Sized.BitVector (BitVector) -import CLaSH.Sized.Vector (Vec, (++), (!!), length, repeat, replace) +import CLaSH.Sized.Vector {- | Dataflow circuit with bidirectional synchronisation channels. @@ -275,6 +278,25 @@ -> DataFlow' ('Clk nm rate) (aEn,cEn) (bEn,dEn) (a,c) (b,d) f `parDF` g = firstDF f `seqDF` secondDF g +-- | Compose /n/ 'DataFlow' circuits in parallel. +parNDF :: (KnownSymbol nm, KnownNat rate, KnownNat n) + => Vec n (DataFlow' ('Clk nm rate) aEn bEn a b) + -> DataFlow' ('Clk nm rate) + (Vec n aEn) + (Vec n bEn) + (Vec n a) + (Vec n b) +parNDF fs = + DF (\as aVs bRs -> + let clk = sclock + as' = unbundle' clk as + aVs' = unbundle' clk aVs + bRs' = unbundle' clk bRs + (bs,bVs,aRs) = unzip3 (zipWith (\k (a,b,r) -> df k a b r) fs + (zip3 as' aVs' bRs')) + in (bundle' clk bs,bundle' clk bVs, bundle' clk aRs) + ) + -- | Feed back the second halve of the communication channel. The feedback loop -- is buffered by a 'fifoDF' circuit. -- @@ -513,3 +535,22 @@ yV = val .&&. xR xyV = bundle' clk (xV,yV) in (xy,xyV,rdy))) `seqDF` (stepLock `parDF` stepLock) + +instance (LockStep en a, KnownNat m, m ~ (n + 1), KnownNat (n+1)) => + LockStep (Vec m en) (Vec m a) where + lockStep = parNDF (repeat lockStep) `seqDF` + DF (\xs vals rdy -> + let val = and <$> vals + rdys = allReady <$> rdy <*> (repeat <$> vals) + in (xs,val,rdys) + ) + stepLock = + DF (\xs val rdys -> + let rdy = and <$> rdys + vals = allReady <$> val <*> (repeat <$> rdys) + in (xs,vals,rdy) + ) `seqDF` parNDF (repeat stepLock) + +allReady :: KnownNat (n+1) => Bool -> Vec (n+1) (Vec (n+1) Bool) + -> Vec (n+1) Bool +allReady b vs = map (and . (b :>) . tail) (smap (flip rotateLeftS) vs) diff --git a/src/CLaSH/Prelude/Safe.hs b/src/CLaSH/Prelude/Safe.hs --- a/src/CLaSH/Prelude/Safe.hs +++ b/src/CLaSH/Prelude/Safe.hs @@ -53,6 +53,9 @@ -- * BlockRAM primitives , blockRam , blockRamPow2 + -- * BlockRAM read/write conflict resolution + , readNew + , readNew' -- * Utility functions , isRising , isFalling @@ -116,7 +119,7 @@ import CLaSH.Class.Resize import CLaSH.Prelude.BitIndex import CLaSH.Prelude.BitReduction -import CLaSH.Prelude.BlockRam (blockRam, blockRamPow2) +import CLaSH.Prelude.BlockRam (blockRam, blockRamPow2, readNew, readNew') import CLaSH.Prelude.Explicit.Safe (registerB', isRising', isFalling') import CLaSH.Prelude.Mealy (mealy, mealyB, (<^>)) import CLaSH.Prelude.Moore (moore, mooreB) diff --git a/src/CLaSH/Signal.hs b/src/CLaSH/Signal.hs --- a/src/CLaSH/Signal.hs +++ b/src/CLaSH/Signal.hs @@ -93,6 +93,7 @@ -- [8,1,2] register :: a -> Signal a -> Signal a register = register# systemClock +infixr `register` {-# INLINE regEn #-} -- | Version of 'register' that only updates its content when its second argument diff --git a/src/CLaSH/Sized/Internal/BitVector.hs b/src/CLaSH/Sized/Internal/BitVector.hs --- a/src/CLaSH/Sized/Internal/BitVector.hs +++ b/src/CLaSH/Sized/Internal/BitVector.hs @@ -84,7 +84,7 @@ , shiftR# , rotateL# , rotateR# - , popCount# + , popCountBV -- ** Resize , resize# ) @@ -111,6 +111,9 @@ import CLaSH.Promoted.Nat (SNat, snatToInteger) import CLaSH.Promoted.Ord (Max) +import {-# SOURCE #-} qualified CLaSH.Sized.Vector as V +import {-# SOURCE #-} qualified CLaSH.Sized.Internal.Index as I + {- $setup >>> :set -XTemplateHaskell >>> :set -XBinaryLiterals @@ -314,7 +317,7 @@ toInteger# :: BitVector n -> Integer toInteger# (BV i) = i -instance KnownNat n => Bits (BitVector n) where +instance (KnownNat n, KnownNat (n+1), KnownNat (n+2)) => Bits (BitVector n) where (.&.) = and# (.|.) = or# xor = xor# @@ -332,9 +335,9 @@ shiftR v i = shiftR# v i rotateL v i = rotateL# v i rotateR v i = rotateR# v i - popCount = popCount# + popCount bv = fromEnum (popCountBV (bv ++# (0 :: Bit))) -instance KnownNat n => FiniteBits (BitVector n) where +instance (KnownNat n, KnownNat (n+1), KnownNat (n+2)) => FiniteBits (BitVector n) where finiteBitSize = size# {-# NOINLINE reduceAnd# #-} @@ -512,9 +515,13 @@ b'' = sz - b' sz = fromInteger (natVal bv) -{-# NOINLINE popCount# #-} -popCount# :: BitVector n -> Int -popCount# (BV i) = popCount i +popCountBV :: (KnownNat (n+1), KnownNat (n + 2)) + => BitVector (n+1) + -> I.Index (n+2) +popCountBV bv = sum (V.map fromIntegral v) + where + v = V.bv2v bv +{-# INLINE popCountBV #-} instance Resize BitVector where resize = resize# diff --git a/src/CLaSH/Sized/Internal/BitVector.hs-boot b/src/CLaSH/Sized/Internal/BitVector.hs-boot new file mode 100644 --- /dev/null +++ b/src/CLaSH/Sized/Internal/BitVector.hs-boot @@ -0,0 +1,10 @@ +{-# LANGUAGE DataKinds #-} +{-# LANGUAGE KindSignatures #-} +{-# LANGUAGE RoleAnnotations #-} +module CLaSH.Sized.Internal.BitVector where + +import GHC.TypeLits (Nat) + +type role BitVector phantom +data BitVector :: Nat -> * +type Bit = BitVector 1 diff --git a/src/CLaSH/Sized/Internal/Index.hs b/src/CLaSH/Sized/Internal/Index.hs --- a/src/CLaSH/Sized/Internal/Index.hs +++ b/src/CLaSH/Sized/Internal/Index.hs @@ -69,7 +69,7 @@ import CLaSH.Class.BitPack (BitPack (..)) import CLaSH.Class.Num (ExtendingNum (..)) import CLaSH.Class.Resize (Resize (..)) -import CLaSH.Sized.Internal.BitVector (BitVector (..)) +import {-# SOURCE #-} CLaSH.Sized.Internal.BitVector (BitVector (..)) -- | Arbitrary-bounded unsigned integer represented by @ceil(log_2(n))@ bits. -- diff --git a/src/CLaSH/Sized/Internal/Index.hs-boot b/src/CLaSH/Sized/Internal/Index.hs-boot new file mode 100644 --- /dev/null +++ b/src/CLaSH/Sized/Internal/Index.hs-boot @@ -0,0 +1,12 @@ +{-# LANGUAGE DataKinds #-} +{-# LANGUAGE KindSignatures #-} +{-# LANGUAGE RoleAnnotations #-} +module CLaSH.Sized.Internal.Index where + +import GHC.TypeLits (KnownNat, Nat) + +type role Index phantom +data Index :: Nat -> * + +instance KnownNat n => Num (Index n) +instance KnownNat n => Enum (Index n) diff --git a/src/CLaSH/Sized/Internal/Signed.hs b/src/CLaSH/Sized/Internal/Signed.hs --- a/src/CLaSH/Sized/Internal/Signed.hs +++ b/src/CLaSH/Sized/Internal/Signed.hs @@ -69,7 +69,6 @@ , shiftR# , rotateL# , rotateR# - , popCount# -- ** Resize , resize# , truncateB# @@ -314,7 +313,7 @@ toInteger# :: Signed n -> Integer toInteger# (S n) = n -instance KnownNat n => Bits (Signed n) where +instance (KnownNat n, KnownNat (n + 1), KnownNat (n + 2)) => Bits (Signed n) where (.&.) = and# (.|.) = or# xor = xor# @@ -332,7 +331,7 @@ shiftR v i = shiftR# v i rotateL v i = rotateL# v i rotateR v i = rotateR# v i - popCount = popCount# + popCount s = popCount (pack# s) and#,or#,xor# :: KnownNat n => Signed n -> Signed n -> Signed n {-# NOINLINE and# #-} @@ -344,7 +343,7 @@ {-# NOINLINE complement# #-} complement# :: KnownNat n => Signed n -> Signed n -complement# = unpack# . complement . pack# +complement# (S a) = fromInteger_INLINE (complement a) shiftL#,shiftR#,rotateL#,rotateR# :: KnownNat n => Signed n -> Int -> Signed n {-# NOINLINE shiftL# #-} @@ -377,14 +376,7 @@ b'' = sz - b' sz = fromInteger (natVal s) -{-# NOINLINE popCount# #-} -popCount# :: KnownNat n => Signed n -> Int -popCount# s@(S i) = popCount i' - where - maxI = 2 ^ natVal s - i' = i `mod` maxI - -instance KnownNat n => FiniteBits (Signed n) where +instance (KnownNat n, KnownNat (n + 1), KnownNat (n + 2)) => FiniteBits (Signed n) where finiteBitSize = size# instance Resize Signed where diff --git a/src/CLaSH/Sized/Internal/Unsigned.hs b/src/CLaSH/Sized/Internal/Unsigned.hs --- a/src/CLaSH/Sized/Internal/Unsigned.hs +++ b/src/CLaSH/Sized/Internal/Unsigned.hs @@ -65,7 +65,6 @@ , shiftR# , rotateL# , rotateR# - , popCount# -- ** Resize , resize# ) @@ -286,7 +285,7 @@ toInteger# :: Unsigned n -> Integer toInteger# (U i) = i -instance KnownNat n => Bits (Unsigned n) where +instance (KnownNat n, KnownNat (n + 1), KnownNat (n + 2)) => Bits (Unsigned n) where (.&.) = and# (.|.) = or# xor = xor# @@ -304,7 +303,7 @@ shiftR v i = shiftR# v i rotateL v i = rotateL# v i rotateR v i = rotateR# v i - popCount = popCount# + popCount u = popCount (pack# u) {-# NOINLINE and# #-} and# :: Unsigned n -> Unsigned n -> Unsigned n @@ -358,11 +357,7 @@ b'' = sz - b' sz = fromInteger (natVal bv) -{-# NOINLINE popCount# #-} -popCount# :: Unsigned n -> Int -popCount# (U i) = popCount i - -instance KnownNat n => FiniteBits (Unsigned n) where +instance (KnownNat n, KnownNat (n + 1), KnownNat (n + 2)) => FiniteBits (Unsigned n) where finiteBitSize = size# instance Resize Unsigned where diff --git a/src/CLaSH/Sized/Vector.hs-boot b/src/CLaSH/Sized/Vector.hs-boot new file mode 100644 --- /dev/null +++ b/src/CLaSH/Sized/Vector.hs-boot @@ -0,0 +1,17 @@ +{-# LANGUAGE DataKinds #-} +{-# LANGUAGE GADTs #-} +{-# LANGUAGE KindSignatures #-} +{-# LANGUAGE RoleAnnotations #-} +{-# LANGUAGE TypeOperators #-} +module CLaSH.Sized.Vector where + +import GHC.TypeLits (KnownNat, Nat, type (+)) +import {-# SOURCE #-} CLaSH.Sized.Internal.BitVector (BitVector, Bit) + +type role Vec nominal representational +data Vec :: Nat -> * -> * + +instance (KnownNat m, (~) m ((+) n 1)) => Foldable (Vec m) + +bv2v :: KnownNat n => BitVector n -> Vec n Bit +map :: (a -> b) -> Vec n a -> Vec n b diff --git a/src/CLaSH/Tutorial.hs b/src/CLaSH/Tutorial.hs --- a/src/CLaSH/Tutorial.hs +++ b/src/CLaSH/Tutorial.hs @@ -60,8 +60,8 @@ -- * Troubleshooting -- $errorsandsolutions - -- * Unsupported Haskell features - -- $unsupported + -- * Limitations of CλaSH + -- $limitations -- * CλaSH vs Lava -- $vslava @@ -159,7 +159,7 @@ consequences on how we view /recursively/ defined functions: structurally, a recursively defined function would denote an /infinitely/ deep / structured component, something that cannot be turned into an actual circuit -(See also <#unsupported Unsupported Haskell features>). +(See also <#limitations Limitations of CλaSH>). On the other hand, Haskell's by-default non-strict evaluation works very well for the simulation of the feedback loops, which are ubiquitous in digital @@ -203,8 +203,8 @@ * Run: @sudo add-apt-repository -y ppa:hvr/ghc@ * Run: @sudo apt-get update@ - * Run: @sudo apt-get install cabal-install-1.22 ghc-7.10.2 libtinfo-dev@ - * Update your @PATH@ with: @\/opt\/ghc\/7.10.2\/bin@, @\/opt\/cabal\/1.22/bin@, and @\$HOME\/.cabal\/bin@ + * Run: @sudo apt-get install cabal-install-1.22 ghc-7.10.3 libtinfo-dev@ + * Update your @PATH@ with: @\/opt\/ghc\/7.10.3\/bin@, @\/opt\/cabal\/1.22/bin@, and @\$HOME\/.cabal\/bin@ * Run: @cabal update@ * Skip step 2. @@ -1691,9 +1691,9 @@ <1,2,3,4> -} -{- $unsupported #unsupported# -Here is a list of Haskell features which the CλaSH compiler cannot synthesize -to VHDL/(System)Verilog (for now): +{- $limitations #limitations# +Here is a list of Haskell features for which the CλaSH compiler has only +/limited/ support (for now): * __Recursively defined functions__ @@ -1854,16 +1854,63 @@ arithmetic operations, there is no point in supporting the floating point data types. -* __Other primitive types__ +* __Haskell primitive types__ - Most primitive types are not supported, with the exception of 'Int', 'Int#', - and 'Integer'. This means that types such as: 'Word', 'Word8', 'Int8', - 'Char', 'Array', etc. cannot to translated to hardware. + Only the following primitive Haskell types are supported: - The translations of 'Int', 'Int#', and 'Integer' are also incorrect: they - are translated to the VHDL @integer@ type, the Verilog @signed [31:0]@, or - the SystemVerilog @signed logic [31:0]@ type, which can only represent - 32-bit integer values. Use these types with due diligence. + * 'Integer' + * 'Int' + * 'Int8' + * 'Int16' + * 'Int32' + * 'Int64' (not available when compiling with @-clash-intwidth=32@ on a 64-bit machine) + * 'Word' + * 'Word8' + * 'Word16' + * 'Word32' + * 'Word64' (not available when compiling with @-clash-intwidth=32@ on a 64-bit machine) + * 'Char' + + There are several aspects of which you should take note: + + * 'Int' and 'Word' are represented by the same number of bits as is + native for the architecture of the computer on which the CλaSH + compiler is executed. This means that if you are working on a 64-bit + machine, 'Int' and 'Word' will be 64-bit. This might be problematic + when you are working in a team, and one designer has a 32-bit + machine, and the other has a 64-bit machine. In general, you should + be avoiding 'Int' in such cases, but as a band-aid solution, you can + force the CλaSH compiler to use a specific bit-width for `Int` and + `Word` using the @-clash-intwidth=N@ flag, where /N/ must either be + /32/ or /64/. + + * When you use the @-clash-intwidth=32@ flag on a /64-bit/ machine, + the 'Word64' and 'Int64' types /cannot/ be translated. This + restriction does /not/ apply to the other three combinations of + @-clash-intwidth@ flag and machine type. + + * The translation of 'Integer' is not meaning-preserving. 'Integer' in + Haskell is an arbitrary precision integer, something that cannot + be represented in a statically known number of bits. In the CλaSH + compiler, we chose to represent 'Integer' by the same number of bits + as we do for 'Int' and 'Word'. As you have read in a previous + bullet point, this number of bits is either 32 or 64, depending on + the architecture of the machine the CλaSH compiler is running on, or + the setting of the @-clash-intwidth@ flag. + + Consequently, you should use `Integer` with due diligence; be + especially careful when using `fromIntegral` as it does a conversion + via 'Integer'. For example: + + > signedToUnsigned :: Signed 128 -> Unsigned 128 + > signedToUnsigned = fromIntegral + + can either lose the top 64 or 96 bits depending on whether 'Integer' + is represented by 64 or 32 bits. Instead, when doing such conversions, + you should use 'bitCoerce': + + > signedToUnsigned :: Signed 128 -> Unsigned 128 + > signedToUnsigned = bitCoerce * __Side-effects: 'IO', 'ST', etc.__ diff --git a/tests/doctests.hs b/tests/doctests.hs --- a/tests/doctests.hs +++ b/tests/doctests.hs @@ -1,8 +1,6 @@ module Main where -import System.FilePath.Glob (glob) import Test.DocTest (doctest) main :: IO () -main = glob "src/**/*.hs" >>= - doctest +main = doctest ["-i src","CLaSH.Prelude","CLaSH.Examples","CLaSH.Tutorial"]