diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,15 @@ # Changelog for the Clash project +## 1.6.5 *Jun 27th 2023* + +Fixed: + + * Support building with all combinations of specific versions of our dependencies `hashable` and `primitive`. [#2485](https://github.com/clash-lang/clash-compiler/pull/2485) + * The Haskell simulation of the PLL lock signal in `Clash.Clocks` (used by `Clash.Intel.ClockGen`) is fixed: the signal is now unasserted for the time the reset input is asserted and vice versa, and no longer crashes the simulation. HDL generation is unchanged. The PLL functions now have an additional constraint: `KnownDomain pllLock`. [#2420](https://github.com/clash-lang/clash-compiler/pull/2420) + +Changed: + + * Export the constructor for the `Wrapping` type in the `Clash.Num.Wrapping` module. See [#2292](https://github.com/clash-lang/clash-compiler/issues/2292) + ## 1.6.4 *Aug 30th 2022* Fixed: diff --git a/clash-prelude.cabal b/clash-prelude.cabal --- a/clash-prelude.cabal +++ b/clash-prelude.cabal @@ -1,6 +1,6 @@ Cabal-version: 2.2 Name: clash-prelude -Version: 1.6.4 +Version: 1.6.5 Synopsis: Clash: a functional hardware description language - Prelude library Description: Clash is a functional hardware description language that borrows both its @@ -51,7 +51,7 @@ Copyright: Copyright © 2013-2016, University of Twente, 2016-2017, Myrtle Software Ltd, 2017-2019, QBayLogic B.V., Google Inc., - 2021-2022, QBayLogic B.V. + 2021-2023, QBayLogic B.V. Category: Hardware Build-type: Simple @@ -334,7 +334,7 @@ hashable >= 1.2.1.0 && < 1.5, half >= 0.2.2.3 && < 1.0, interpolate >= 0.2 && < 0.3, - lens >= 4.10 && < 5.2.0, + lens >= 4.10 && < 5.3, recursion-schemes >= 5.1 && < 5.3, QuickCheck >= 2.7 && < 2.15, reflection >= 2 && < 2.2, @@ -370,7 +370,7 @@ build-depends: base, clash-prelude, - doctest-parallel >= 0.2 && < 0.3, + doctest-parallel >= 0.2 && < 0.4, filepath test-suite unittests @@ -393,7 +393,7 @@ base, bytestring, deepseq, - hedgehog >= 1.0.3 && < 1.2, + hedgehog >= 1.0.3 && < 1.3, hint >= 0.7 && < 0.10, quickcheck-classes-base >= 0.6 && < 1.0, tasty >= 1.2 && < 1.5, @@ -410,6 +410,7 @@ Clash.Tests.BitVector Clash.Tests.BlockRam Clash.Tests.BlockRam.Blob + Clash.Tests.Clocks Clash.Tests.Counter Clash.Tests.DerivingDataRepr Clash.Tests.DerivingDataReprTypes diff --git a/src/Clash/Annotations/Primitive.hs b/src/Clash/Annotations/Primitive.hs --- a/src/Clash/Annotations/Primitive.hs +++ b/src/Clash/Annotations/Primitive.hs @@ -12,6 +12,7 @@ {-# LANGUAGE DeriveAnyClass #-} {-# LANGUAGE LambdaCase #-} +{-# LANGUAGE NoGeneralizedNewtypeDeriving #-} {-# LANGUAGE TemplateHaskellQuotes #-} {-# LANGUAGE Safe #-} diff --git a/src/Clash/Annotations/SynthesisAttributes.hs b/src/Clash/Annotations/SynthesisAttributes.hs --- a/src/Clash/Annotations/SynthesisAttributes.hs +++ b/src/Clash/Annotations/SynthesisAttributes.hs @@ -9,6 +9,8 @@ please report any unexpected or broken behavior to Clash's GitHub page (). -} + +{-# LANGUAGE NoGeneralizedNewtypeDeriving #-} {-# LANGUAGE PolyKinds #-} {-# LANGUAGE Safe #-} diff --git a/src/Clash/Annotations/TopEntity.hs b/src/Clash/Annotations/TopEntity.hs --- a/src/Clash/Annotations/TopEntity.hs +++ b/src/Clash/Annotations/TopEntity.hs @@ -228,6 +228,7 @@ -} {-# LANGUAGE CPP #-} +{-# LANGUAGE NoGeneralizedNewtypeDeriving #-} {-# LANGUAGE TemplateHaskellQuotes #-} {-# LANGUAGE Safe #-} diff --git a/src/Clash/Class/BitPack.hs b/src/Clash/Class/BitPack.hs --- a/src/Clash/Class/BitPack.hs +++ b/src/Clash/Class/BitPack.hs @@ -6,6 +6,8 @@ License : BSD2 (see the file LICENSE) Maintainer : QBayLogic B.V. -} + +{-# LANGUAGE NoGeneralizedNewtypeDeriving #-} {-# LANGUAGE Safe #-} module Clash.Class.BitPack diff --git a/src/Clash/Class/Num.hs b/src/Clash/Class/Num.hs --- a/src/Clash/Class/Num.hs +++ b/src/Clash/Class/Num.hs @@ -5,6 +5,7 @@ -} {-# LANGUAGE MultiParamTypeClasses #-} +{-# LANGUAGE NoGeneralizedNewtypeDeriving #-} {-# LANGUAGE TypeFamilies #-} {-# LANGUAGE Safe #-} diff --git a/src/Clash/Class/Resize.hs b/src/Clash/Class/Resize.hs --- a/src/Clash/Class/Resize.hs +++ b/src/Clash/Class/Resize.hs @@ -5,6 +5,8 @@ Maintainer : QBayLogic B.V. -} +{-# LANGUAGE NoGeneralizedNewtypeDeriving #-} + {-# LANGUAGE Safe #-} {-# OPTIONS_GHC -fplugin GHC.TypeLits.KnownNat.Solver #-} @@ -69,8 +71,11 @@ -- you "know" /a/ can't be out of bounds, but would like to have your assumptions -- checked. -- --- __N.B.__: Check only affects simulation. I.e., no checks will be inserted +-- * __NB__: Check only affects simulation. I.e., no checks will be inserted -- into the generated HDL +-- * __NB__: 'fromIntegral' is not well suited for Clash as it will go through +-- 'Integer' which is arbitrarily bounded in HDL. Instead use +-- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class. checkedFromIntegral :: forall a b. HasCallStack => diff --git a/src/Clash/Clocks/Deriving.hs b/src/Clash/Clocks/Deriving.hs --- a/src/Clash/Clocks/Deriving.hs +++ b/src/Clash/Clocks/Deriving.hs @@ -1,8 +1,9 @@ {-| Copyright : (C) 2018, Google Inc 2019, Myrtle Software Ltd + 2023, QBayLogic B.V. License : BSD2 (see the file LICENSE) -Maintainer : Christiaan Baaij +Maintainer : QBayLogic B.V. -} {-# LANGUAGE CPP #-} @@ -12,6 +13,7 @@ module Clash.Clocks.Deriving (deriveClocksInstances) where import Control.Monad (foldM) +import Clash.Explicit.Signal (unsafeSynchronizer) import Clash.Signal.Internal import Language.Haskell.TH.Compat import Language.Haskell.TH.Syntax @@ -26,12 +28,14 @@ instType1 <- AppT instType0 <$> lockType let instHead = AppT (ConT $ mkName "Clocks") instType1 - cxtRHS <- foldM (\a n' -> AppT a <$> knownDomainCxt n') (TupleT n) [1..n] + cxtRHS0 <- + foldM (\a n' -> AppT a <$> knownDomainCxt n') (TupleT $ n + 1) [1..n] + cxtRHS1 <- AppT cxtRHS0 <$> lockKnownDomainCxt #if MIN_VERSION_template_haskell(2,15,0) let cxtLHS = AppT (ConT $ mkName "ClocksCxt") instType1 - let cxtTy = TySynInstD (TySynEqn Nothing cxtLHS cxtRHS) + let cxtTy = TySynInstD (TySynEqn Nothing cxtLHS cxtRHS1) #else - let cxtTy = TySynInstD (mkName "ClocksCxt") (TySynEqn [instType1] cxtRHS) + let cxtTy = TySynInstD (mkName "ClocksCxt") (TySynEqn [instType1] cxtRHS1) #endif -- Function definition of 'clocks' @@ -39,9 +43,11 @@ let rst = mkName "rst" -- Implementation of 'clocks' + lockImpl <- [| unsafeSynchronizer clockGen clockGen + (unsafeToLowPolarity $(varE rst)) |] let noInline = PragmaD $ InlineP (mkName "clocks") NoInline FunLike AllPhases let clkImpls = replicate n (clkImpl clk) - let instTuple = mkTupE $ clkImpls ++ [AppE (VarE 'unsafeCoerce) (VarE rst)] + let instTuple = mkTupE $ clkImpls ++ [lockImpl] let funcBody = NormalB instTuple let instFunc = FunD (mkName "clocks") [Clause [VarP clk, VarP rst] funcBody []] @@ -61,6 +67,11 @@ lockType = let c = varT $ mkName "pllLock" in [t| Signal $c Bool |] + + lockKnownDomainCxt = + let p = varT $ mkName "pllLock" in + [t| KnownDomain $p |] + clkImpl clk = AppE (VarE 'unsafeCoerce) (VarE clk) diff --git a/src/Clash/Explicit/BlockRam.hs b/src/Clash/Explicit/BlockRam.hs --- a/src/Clash/Explicit/BlockRam.hs +++ b/src/Clash/Explicit/BlockRam.hs @@ -86,7 +86,7 @@ , (MemAddr, Maybe (MemAddr,Value), InstrAddr) ) cpu regbank (memOut, instr) = - (regbank', (rdAddr, (,aluOut) '<$>' wrAddrM, fromIntegral ipntr)) + (regbank', (rdAddr, (,aluOut) '<$>' wrAddrM, bitCoerce ipntr)) where -- Current instruction pointer ipntr = regbank 'Clash.Sized.Vector.!!' PC @@ -279,7 +279,7 @@ , (MemAddr, Maybe (MemAddr,Value), InstrAddr) ) cpu2 (regbank, ldRegD) (memOut, instr) = - ((regbank', ldRegD'), (rdAddr, (,aluOut) '<$>' wrAddrM, fromIntegral ipntr)) + ((regbank', ldRegD'), (rdAddr, (,aluOut) '<$>' wrAddrM, bitCoerce ipntr)) where -- Current instruction pointer ipntr = regbank 'Clash.Sized.Vector.!!' PC @@ -543,7 +543,7 @@ -> ( Vec 7 Value , (MemAddr,Maybe (MemAddr,Value),InstrAddr) ) - cpu regbank (memOut,instr) = (regbank',(rdAddr,(,aluOut) <$> wrAddrM,fromIntegral ipntr)) + cpu regbank (memOut,instr) = (regbank',(rdAddr,(,aluOut) <$> wrAddrM,bitCoerce ipntr)) where -- Current instruction pointer ipntr = regbank C.!! PC @@ -660,7 +660,7 @@ -> ( (Vec 7 Value,Reg) , (MemAddr,Maybe (MemAddr,Value),InstrAddr) ) - cpu2 (regbank,ldRegD) (memOut,instr) = ((regbank',ldRegD'),(rdAddr,(,aluOut) <$> wrAddrM,fromIntegral ipntr)) + cpu2 (regbank,ldRegD) (memOut,instr) = ((regbank',ldRegD'),(rdAddr,(,aluOut) <$> wrAddrM,bitCoerce ipntr)) where -- Current instruction pointer ipntr = regbank C.!! PC diff --git a/src/Clash/Explicit/Mealy.hs b/src/Clash/Explicit/Mealy.hs --- a/src/Clash/Explicit/Mealy.hs +++ b/src/Clash/Explicit/Mealy.hs @@ -12,6 +12,8 @@ requirements. -} +{-# LANGUAGE NoGeneralizedNewtypeDeriving #-} + {-# LANGUAGE Safe #-} module Clash.Explicit.Mealy diff --git a/src/Clash/Explicit/Moore.hs b/src/Clash/Explicit/Moore.hs --- a/src/Clash/Explicit/Moore.hs +++ b/src/Clash/Explicit/Moore.hs @@ -12,6 +12,8 @@ requirements. -} +{-# LANGUAGE NoGeneralizedNewtypeDeriving #-} + {-# LANGUAGE Safe #-} module Clash.Explicit.Moore diff --git a/src/Clash/Explicit/Prelude/Safe.hs b/src/Clash/Explicit/Prelude/Safe.hs --- a/src/Clash/Explicit/Prelude/Safe.hs +++ b/src/Clash/Explicit/Prelude/Safe.hs @@ -13,6 +13,7 @@ -} {-# LANGUAGE FlexibleContexts #-} +{-# LANGUAGE NoGeneralizedNewtypeDeriving #-} {-# LANGUAGE NoImplicitPrelude #-} {-# LANGUAGE Safe #-} diff --git a/src/Clash/Explicit/Signal.hs b/src/Clash/Explicit/Signal.hs --- a/src/Clash/Explicit/Signal.hs +++ b/src/Clash/Explicit/Signal.hs @@ -596,7 +596,7 @@ delay# clk (enable gen en) dflt i {-# INLINE delayEn #-} --- | \"@'register' clk rst i s@\" delays the values in 'Signal' /s/ for one +-- | \"@'register' clk rst en i s@\" delays the values in 'Signal' /s/ for one -- cycle, and sets the value to @i@ the moment the reset becomes 'False'. -- -- >>> sampleN 5 (register systemClockGen resetGen enableGen 8 (fromList [1,1,2,3,4])) diff --git a/src/Clash/Explicit/Synchronizer.hs b/src/Clash/Explicit/Synchronizer.hs --- a/src/Clash/Explicit/Synchronizer.hs +++ b/src/Clash/Explicit/Synchronizer.hs @@ -10,6 +10,7 @@ -} {-# LANGUAGE CPP #-} +{-# LANGUAGE NoGeneralizedNewtypeDeriving #-} {-# LANGUAGE TypeFamilies #-} {-# LANGUAGE Safe #-} diff --git a/src/Clash/HaskellPrelude.hs b/src/Clash/HaskellPrelude.hs --- a/src/Clash/HaskellPrelude.hs +++ b/src/Clash/HaskellPrelude.hs @@ -12,6 +12,8 @@ 'Clash.Class.Parity.Parity' is available at "Clash.Class.Parity". -} +{-# LANGUAGE NoGeneralizedNewtypeDeriving #-} + {-# LANGUAGE Safe #-} {-# OPTIONS_HADDOCK show-extensions, not-home #-} diff --git a/src/Clash/NamedTypes.hs b/src/Clash/NamedTypes.hs --- a/src/Clash/NamedTypes.hs +++ b/src/Clash/NamedTypes.hs @@ -33,6 +33,7 @@ -} +{-# LANGUAGE NoGeneralizedNewtypeDeriving #-} {-# LANGUAGE PolyKinds #-} {-# LANGUAGE Safe #-} diff --git a/src/Clash/Num/Wrapping.hs b/src/Clash/Num/Wrapping.hs --- a/src/Clash/Num/Wrapping.hs +++ b/src/Clash/Num/Wrapping.hs @@ -8,7 +8,7 @@ {-# LANGUAGE GeneralizedNewtypeDeriving #-} module Clash.Num.Wrapping - ( Wrapping(fromWrapping) + ( Wrapping(..) , toWrapping ) where 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 @@ -86,7 +86,7 @@ , (MemAddr, Maybe (MemAddr,Value), InstrAddr) ) cpu regbank (memOut, instr) = - (regbank', (rdAddr, (,aluOut) 'Prelude.<$>' wrAddrM, fromIntegral ipntr)) + (regbank', (rdAddr, (,aluOut) 'Prelude.<$>' wrAddrM, bitCoerce ipntr)) where -- Current instruction pointer ipntr = regbank 'Clash.Sized.Vector.!!' PC @@ -272,7 +272,7 @@ , (MemAddr, Maybe (MemAddr,Value), InstrAddr) ) cpu2 (regbank,ldRegD) (memOut,instr) = - ((regbank', ldRegD'), (rdAddr, (,aluOut) 'Prelude.<$>' wrAddrM, fromIntegral ipntr)) + ((regbank', ldRegD'), (rdAddr, (,aluOut) 'Prelude.<$>' wrAddrM, bitCoerce ipntr)) where -- Current instruction pointer ipntr = regbank 'Clash.Sized.Vector.!!' PC @@ -377,6 +377,7 @@ {-# LANGUAGE CPP #-} {-# LANGUAGE FlexibleContexts #-} +{-# LANGUAGE NoGeneralizedNewtypeDeriving #-} {-# LANGUAGE NoImplicitPrelude #-} {-# LANGUAGE GADTs #-} {-# LANGUAGE ScopedTypeVariables #-} @@ -496,7 +497,7 @@ -> ( Vec 7 Value , (MemAddr,Maybe (MemAddr,Value),InstrAddr) ) - cpu regbank (memOut,instr) = (regbank',(rdAddr,(,aluOut) <$> wrAddrM,fromIntegral ipntr)) + cpu regbank (memOut,instr) = (regbank',(rdAddr,(,aluOut) <$> wrAddrM,bitCoerce ipntr)) where -- Current instruction pointer ipntr = regbank C.!! PC @@ -607,7 +608,7 @@ , (MemAddr, Maybe (MemAddr, Value), InstrAddr) ) cpu2 (regbank,ldRegD) (memOut,instr) = - ((regbank', ldRegD'), (rdAddr, (,aluOut) <$> wrAddrM, fromIntegral ipntr)) + ((regbank', ldRegD'), (rdAddr, (,aluOut) <$> wrAddrM, bitCoerce ipntr)) where -- Current instruction pointer ipntr = regbank C.!! PC diff --git a/src/Clash/Prelude/BlockRam/Blob.hs b/src/Clash/Prelude/BlockRam/Blob.hs --- a/src/Clash/Prelude/BlockRam/Blob.hs +++ b/src/Clash/Prelude/BlockRam/Blob.hs @@ -18,6 +18,8 @@ tools consuming the generated HDL. -} +{-# LANGUAGE NoGeneralizedNewtypeDeriving #-} + {-# LANGUAGE Safe #-} {-# OPTIONS_HADDOCK show-extensions #-} 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 @@ -11,6 +11,7 @@ {-# LANGUAGE FlexibleInstances #-} {-# LANGUAGE MultiParamTypeClasses #-} +{-# LANGUAGE NoGeneralizedNewtypeDeriving #-} {-# LANGUAGE TypeFamilies #-} {-# LANGUAGE Safe #-} diff --git a/src/Clash/Prelude/Mealy.hs b/src/Clash/Prelude/Mealy.hs --- a/src/Clash/Prelude/Mealy.hs +++ b/src/Clash/Prelude/Mealy.hs @@ -13,6 +13,7 @@ -} {-# LANGUAGE FlexibleContexts #-} +{-# LANGUAGE NoGeneralizedNewtypeDeriving #-} {-# LANGUAGE Safe #-} diff --git a/src/Clash/Prelude/Moore.hs b/src/Clash/Prelude/Moore.hs --- a/src/Clash/Prelude/Moore.hs +++ b/src/Clash/Prelude/Moore.hs @@ -13,6 +13,7 @@ -} {-# LANGUAGE FlexibleContexts #-} +{-# LANGUAGE NoGeneralizedNewtypeDeriving #-} {-# LANGUAGE Safe #-} diff --git a/src/Clash/Prelude/RAM.hs b/src/Clash/Prelude/RAM.hs --- a/src/Clash/Prelude/RAM.hs +++ b/src/Clash/Prelude/RAM.hs @@ -11,6 +11,7 @@ {-# LANGUAGE CPP #-} {-# LANGUAGE FlexibleContexts #-} +{-# LANGUAGE NoGeneralizedNewtypeDeriving #-} {-# LANGUAGE TypeFamilies #-} {-# LANGUAGE Safe #-} 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 @@ -32,6 +32,7 @@ {-# LANGUAGE FlexibleContexts #-} {-# LANGUAGE NoImplicitPrelude #-} +{-# LANGUAGE NoGeneralizedNewtypeDeriving #-} {-# LANGUAGE Safe #-} diff --git a/src/Clash/Signal/Delayed.hs b/src/Clash/Signal/Delayed.hs --- a/src/Clash/Signal/Delayed.hs +++ b/src/Clash/Signal/Delayed.hs @@ -9,6 +9,7 @@ {-# LANGUAGE CPP #-} {-# LANGUAGE FlexibleContexts #-} +{-# LANGUAGE NoGeneralizedNewtypeDeriving #-} {-# LANGUAGE TypeFamilies #-} {-# LANGUAGE UndecidableInstances #-} 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 @@ -212,21 +212,26 @@ -- * Type definitions --- | A vector of bits. +-- | A vector of bits -- -- * Bit indices are descending -- * 'Num' instance performs /unsigned/ arithmetic. -- +-- __NB__: The usual Haskell method of converting an integral numeric type to +-- another, 'fromIntegral', is not well suited for Clash as it will go through +-- 'Integer' which is arbitrarily bounded in HDL. Instead use +-- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class. +-- -- BitVector has the -- -- >>> :i BitVector -- type role BitVector nominal -- ... -- --- as it is not safe to coerce between different size BitVector. To change the --- size, use the functions in the 'Clash.Class.Resize.Resize' class. +-- as it is not safe to coerce between different sizes of BitVector. To change +-- the size, use the functions in the 'Resize' class. data BitVector (n :: Nat) = - -- | The constructor, 'BV', and the field, 'unsafeToNatural', are not + -- | The constructor, 'BV', and the fields, 'unsafeMask' and 'unsafeToNatural', are not -- synthesizable. BV { unsafeMask :: !Natural , unsafeToNatural :: !Natural @@ -237,9 +242,14 @@ -- * Bit --- | Bit +-- | A single bit +-- +-- __NB__: The usual Haskell method of converting an integral numeric type to +-- another, 'fromIntegral', is not well suited for Clash as it will go through +-- 'Integer' which is arbitrarily bounded in HDL. Instead use +-- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class. data Bit = - -- | The constructor, 'Bit', and the field, 'unsafeToInteger#', are not + -- | The constructor, 'Bit', and the fields, 'unsafeMask#' and 'unsafeToInteger#', are not -- synthesizable. Bit { unsafeMask# :: {-# unpack #-} !Word , unsafeToInteger# :: {-# unpack #-} !Word @@ -665,6 +675,9 @@ {-# NOINLINE maxBound# #-} {-# ANN maxBound# hasBlackBox #-} +-- | __NB__: 'fromInteger'/'fromIntegral' can cause unexpected truncation, as +-- 'Integer' is arbitrarily bounded during synthesis. Prefer +-- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class. instance KnownNat n => Num (BitVector n) where (+) = (+#) (-) = (-#) @@ -780,6 +793,9 @@ instance KnownNat n => Real (BitVector n) where toRational = toRational . toInteger# +-- | __NB__: 'toInteger'/'fromIntegral' can cause unexpected truncation, as +-- 'Integer' is arbitrarily bounded during synthesis. Prefer +-- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class. instance KnownNat n => Integral (BitVector n) where quot = quot# rem = rem# 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 @@ -120,7 +120,7 @@ type role Index nominal --- | Arbitrary-bounded unsigned integer represented by @ceil(log_2(n))@ bits. +-- | Arbitrarily-bounded unsigned integer represented by @ceil(log_2(n))@ bits -- -- Given an upper bound @n@, an 'Index' @n@ number has a range of: [0 .. @n@-1] -- @@ -144,14 +144,19 @@ -- *** Exception: X: Clash.Sized.Index: result 8 is out of bounds: [0..7] -- ... -- +-- __NB__: The usual Haskell method of converting an integral numeric type to +-- another, 'fromIntegral', is not well suited for Clash as it will go through +-- 'Integer' which is arbitrarily bounded in HDL. Instead use +-- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class. +-- -- Index has the -- -- >>> :i Index -- type role Index nominal -- ... -- --- as it is not safe to coerce between different range Index. To change the --- size, use the functions in the 'Clash.Class.Resize.Resize' class. +-- as it is not safe to coerce between 'Index'es with different ranges. To +-- change the size, use the functions in the 'Resize' class. #if MIN_VERSION_base(4,15,0) data Index (n :: Nat) = -- | The constructor, 'I', and the field, 'unsafeToInteger', are not @@ -282,6 +287,10 @@ {-# ANN maxBound# hasBlackBox #-} -- | Operators report an error on overflow and underflow +-- +-- __NB__: 'fromInteger'/'fromIntegral' can cause unexpected truncation, as +-- 'Integer' is arbitrarily bounded during synthesis. Prefer +-- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class. instance KnownNat n => Num (Index n) where (+) = (+#) (-) = (-#) @@ -437,6 +446,9 @@ instance KnownNat n => Real (Index n) where toRational = toRational . toInteger# +-- | __NB__: 'toInteger'/'fromIntegral' can cause unexpected truncation, as +-- 'Integer' is arbitrarily bounded during synthesis. Prefer +-- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class. instance KnownNat n => Integral (Index n) where quot = quot# rem = rem# 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 @@ -136,13 +136,17 @@ type role Signed nominal -- | Arbitrary-width signed integer represented by @n@ bits, including the sign --- bit. +-- bit -- -- Uses standard 2-complements representation. Meaning that, given @n@ bits, -- a 'Signed' @n@ number has a range of: [-(2^(@n@-1)) .. 2^(@n@-1)-1] for -- @n > 0@. When @n = 0@, both the min and max bound are 0. -- --- __NB__: The 'Num' operators perform @wrap-around@ on overflow. If you want +-- * __NB__: The usual Haskell method of converting an integral numeric type to +-- another, 'fromIntegral', is not well suited for Clash as it will go through +-- 'Integer' which is arbitrarily bounded in HDL. Instead use +-- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class. +-- * __NB__: The 'Num' operators perform @wrap-around@ on overflow. If you want -- saturation on overflow, check out the 'SaturatingNum' class. -- -- >>> maxBound :: Signed 3 @@ -365,6 +369,10 @@ {-# ANN maxBound# hasBlackBox #-} -- | Operators do @wrap-around@ on overflow +-- +-- __NB__: 'fromInteger'/'fromIntegral' can cause unexpected truncation, as +-- 'Integer' is arbitrarily bounded during synthesis. Prefer +-- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class. instance KnownNat n => Num (Signed n) where (+) = (+#) (-) = (-#) @@ -471,6 +479,9 @@ instance KnownNat n => Real (Signed n) where toRational = toRational . toInteger# +-- | __NB__: 'toInteger'/'fromIntegral' can cause unexpected truncation, as +-- 'Integer' is arbitrarily bounded during synthesis. Prefer +-- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class. instance KnownNat n => Integral (Signed n) where quot = quot# rem = rem# 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 @@ -156,7 +156,11 @@ -- -- Given @n@ bits, an 'Unsigned' @n@ number has a range of: [0 .. 2^@n@-1] -- --- __NB__: The 'Num' operators perform @wrap-around@ on overflow. If you want +-- * __NB__: The usual Haskell method of converting an integral numeric type to +-- another, 'fromIntegral', is not well suited for Clash as it will go through +-- 'Integer' which is arbitrarily bounded in HDL. Instead use +-- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class. +-- * __NB__: The 'Num' operators perform @wrap-around@ on overflow. If you want -- saturation on overflow, check out the 'SaturatingNum' class. -- -- >>> maxBound :: Unsigned 3 @@ -376,6 +380,9 @@ {-# NOINLINE maxBound# #-} {-# ANN maxBound# hasBlackBox #-} +-- | __NB__: 'fromInteger'/'fromIntegral' can cause unexpected truncation, as +-- 'Integer' is arbitrarily bounded during synthesis. Prefer +-- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class. instance KnownNat n => Num (Unsigned n) where (+) = (+#) (-) = (-#) @@ -470,6 +477,9 @@ instance KnownNat n => Real (Unsigned n) where toRational = toRational . toInteger# +-- | __NB__: 'toInteger'/'fromIntegral' can cause unexpected truncation, as +-- 'Integer' is arbitrarily bounded during synthesis. Prefer +-- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class. instance KnownNat n => Integral (Unsigned n) where quot = quot# rem = rem# diff --git a/src/Clash/Sized/RTree.hs b/src/Clash/Sized/RTree.hs --- a/src/Clash/Sized/RTree.hs +++ b/src/Clash/Sized/RTree.hs @@ -267,7 +267,7 @@ @ populationCount :: (KnownNat (2^d), KnownNat d, KnownNat (2^d+1)) => BitVector (2^d) -> Index (2^d+1) -populationCount = tfold fromIntegral (+) . v2t . bv2v +populationCount = tfold (resize . bv2i . pack) (+) . v2t . bv2v @ The \"problem\" with this description is that all adders have the same @@ -289,12 +289,12 @@ We have such an adder in the form of the 'Clash.Class.Num.add' function, as defined in the instance 'Clash.Class.Num.ExtendingNum' instance of 'Index'. However, we cannot simply use 'Clash.Sized.Vector.fold' to create a tree-structure of -'Clash.Class.Num.add'es: +'Clash.Class.Num.add's: #if __GLASGOW_HASKELL__ >= 900 >>> :{ let populationCount' :: (KnownNat (2^d), KnownNat d, KnownNat (2^d+1)) => BitVector (2^d) -> Index (2^d+1) - populationCount' = tfold fromIntegral add . v2t . bv2v + populationCount' = tfold (resize . bv2i . pack) add . v2t . bv2v :} :... @@ -306,8 +306,9 @@ -> Index ((2 ^ d) + 1) -> AResult (Index ((2 ^ d) + 1)) (Index ((2 ^ d) + 1)) • In the second argument of ‘tfold’, namely ‘add’ - In the first argument of ‘(.)’, namely ‘tfold fromIntegral add’ - In the expression: tfold fromIntegral add . v2t . bv2v + In the first argument of ‘(.)’, namely + ‘tfold (resize . bv2i . pack) add’ + In the expression: tfold (resize . bv2i . pack) add . v2t . bv2v • Relevant bindings include populationCount' :: BitVector (2 ^ d) -> Index ((2 ^ d) + 1) (bound at ...) @@ -316,7 +317,7 @@ >>> :{ let populationCount' :: (KnownNat (2^d), KnownNat d, KnownNat (2^d+1)) => BitVector (2^d) -> Index (2^d+1) - populationCount' = tfold fromIntegral add . v2t . bv2v + populationCount' = tfold (resize . bv2i . pack) add . v2t . bv2v :} :... @@ -328,8 +329,9 @@ -> Index ((2 ^ d) + 1) -> AResult (Index ((2 ^ d) + 1)) (Index ((2 ^ d) + 1)) • In the second argument of ‘tfold’, namely ‘add’ - In the first argument of ‘(.)’, namely ‘tfold fromIntegral add’ - In the expression: tfold fromIntegral add . v2t . bv2v + In the first argument of ‘(.)’, namely + ‘tfold (resize . bv2i . pack) add’ + In the expression: tfold (resize . bv2i . pack) add . v2t . bv2v • Relevant bindings include populationCount' :: BitVector (2 ^ d) -> Index ((2 ^ d) + 1) (bound at ...) @@ -346,7 +348,6 @@ @ {\-\# LANGUAGE UndecidableInstances \#-\} import Data.Singletons -import Data.Proxy data IIndex (f :: 'TyFun' Nat Type) :: Type type instance 'Apply' IIndex l = 'Index' ((2^l)+1) @@ -354,7 +355,7 @@ populationCount' :: (KnownNat k, KnownNat (2^k)) => BitVector (2^k) -> Index ((2^k)+1) populationCount' bv = 'tdfold' (Proxy @IIndex) - fromIntegral + (resize . bv2i . pack) (\\_ x y -> 'Clash.Class.Num.add' x y) ('v2t' ('Clash.Sized.Vector.bv2v' bv)) @ diff --git a/src/Clash/Sized/Vector.hs b/src/Clash/Sized/Vector.hs --- a/src/Clash/Sized/Vector.hs +++ b/src/Clash/Sized/Vector.hs @@ -152,6 +152,9 @@ >>> :set -XTypeOperators >>> :set -XTemplateHaskell >>> :set -XFlexibleContexts +>>> :set -fplugin GHC.TypeLits.Normalise +>>> :set -fplugin GHC.TypeLits.KnownNat.Solver +>>> :set -fplugin GHC.TypeLits.Extra.Solver >>> :m -Prelude >>> import Clash.Prelude >>> import qualified Clash.Sized.Vector as Vec @@ -749,7 +752,7 @@ -- >>> imap (+) (2 :> 2 :> 2 :> 2 :> Nil) -- 2 :> 3 :> *** Exception: X: Clash.Sized.Index: result 4 is out of bounds: [0..3] -- ... --- >>> imap (\i a -> fromIntegral i + a) (2 :> 2 :> 2 :> 2 :> Nil) :: Vec 4 (Unsigned 8) +-- >>> imap (\i a -> extend (bitCoerce i) + a) (2 :> 2 :> 2 :> 2 :> Nil) :: Vec 4 (Unsigned 8) -- 2 :> 3 :> 4 :> 5 :> Nil -- -- \"'imap' @f xs@\" corresponds to the following circuit layout: @@ -776,7 +779,7 @@ *** Exception: X: Clash.Sized.Index: result 3 is out of bounds: [0..1] ... #endif ->>> izipWith (\i a b -> fromIntegral i + a + b) (2 :> 2 :> Nil) (3 :> 3 :> Nil) :: Vec 2 (Unsigned 8) +>>> izipWith (\i a b -> extend (bitCoerce i) + a + b) (2 :> 2 :> Nil) (3 :> 3 :> Nil) :: Vec 2 (Unsigned 8) 5 :> 6 :> Nil \"'imap' @f xs@\" corresponds to the following circuit layout: @@ -1598,7 +1601,7 @@ , "templateFunction": "Clash.Primitives.Sized.Vector.iterateBBF" }}] |]) #-} --- | \"'unfoldr @n f s@\" builds a vector of length @n@ from a seed value @s@, +-- | \"'unfoldr' @n f s@\" builds a vector of length @n@ from a seed value @s@, -- where every element @a@ is created by successive calls of @f@ on @s@. Unlike -- 'Data.List.unfoldr' from "Data.List" the generating function @f@ cannot -- dictate the length of the resulting vector, it must be statically known. @@ -1611,7 +1614,7 @@ unfoldr SNat = unfoldrI {-# INLINE unfoldr #-} --- | \"'unfoldr @f s@\" builds a vector from a seed value @s@, where every +-- | \"'unfoldrI' @f s@\" builds a vector from a seed value @s@, where every -- element @a@ is created by successive calls of @f@ on @s@; the length of the -- vector is inferred from the context. Unlike 'Data.List.unfoldr' from -- "Data.List" the generating function @f@ cannot dictate the length of the diff --git a/src/Clash/Tutorial.hs b/src/Clash/Tutorial.hs --- a/src/Clash/Tutorial.hs +++ b/src/Clash/Tutorial.hs @@ -2,7 +2,7 @@ Copyright : © 2014-2016, Christiaan Baaij, 2017-2019, Myrtle Software Ltd 2017 , QBayLogic, Google Inc., - 2021 , QBayLogic B.V. + 2021-2023, QBayLogic B.V. 2022 , LUMI GUIDE FIETSDETECTIE B.V. Licence : Creative Commons 4.0 (CC BY 4.0) (https://creativecommons.org/licenses/by/4.0/) @@ -232,17 +232,24 @@ start the Clash compiler in interpretive mode by: @ -stack exec --package clash-ghc -- clashi +stack exec --resolver lts-19 --package clash-ghc -- clashi @ -If you followed the installation instruction based on - (Linux only), you can start the Clash compiler -in interpretive mode by: +If instead you followed the [instructions](https://clash-lang.org/install/linux/) +to setup a starter project with Stack, you can also run @clashi@ inside such a +project. Change to the directory of the project, and invoke @ -clash.clashi +stack run -- clashi @ +If you instead set up the starter project with GHC and Cabal, change to the +directory of the project and invoke + +@ +cabal run -- clashi +@ + For those familiar with Haskell/GHC, this is indeed just @GHCi@, with three added commands (@:vhdl@, @:verilog@, and @:systemverilog@). You can load files into the interpreter using the @:l \@ command. Now, depending on your @@ -263,7 +270,7 @@ * Once a file has been edited and saved, type @:r@ to reload the files in the interpreter -You are of course free to deviate from these suggestions as you see fit :-) It +You are of course free to deviate from these suggestions as you see fit :-). It is just recommended that you have the Clash interpreter open during this tutorial. -} diff --git a/src/Clash/XException.hs b/src/Clash/XException.hs --- a/src/Clash/XException.hs +++ b/src/Clash/XException.hs @@ -97,6 +97,8 @@ -- out with an exception. errorX :: HasCallStack => String -> a errorX msg = throw (XException ("X: " ++ msg ++ "\n" ++ prettyCallStack callStack)) +{-# NOINLINE errorX #-} +{-# ANN errorX hasBlackBox #-} -- | Convert 'XException' to 'ErrorCall' -- diff --git a/src/Clash/Xilinx/ClockGen.hs b/src/Clash/Xilinx/ClockGen.hs --- a/src/Clash/Xilinx/ClockGen.hs +++ b/src/Clash/Xilinx/ClockGen.hs @@ -35,6 +35,8 @@ -- -- outputs a clock running at 100 MHz -- clockWizard @@Dom100MHz (SSymbol @@"clkWizard50to100") clk50 rst -- @ +-- +-- See also the [Clocking Wizard LogiCORE IP Product Guide](https://docs.xilinx.com/r/en-US/pg065-clk-wiz) clockWizard :: forall domIn domOut periodIn periodOut edge init polarity name . ( KnownConfiguration domIn ('DomainConfiguration domIn periodIn edge 'Asynchronous init polarity) @@ -76,6 +78,8 @@ -- -- outputs a clock running at 100 MHz -- clockWizardDifferential @@Dom100MHz (SSymbol @@"clkWizardD50to100") clk50N clk50P rst -- @ +-- +-- See also the [Clocking Wizard LogiCORE IP Product Guide](https://docs.xilinx.com/r/en-US/pg065-clk-wiz) clockWizardDifferential :: forall domIn domOut periodIn periodOut edge init polarity name . ( KnownConfiguration domIn ('DomainConfiguration domIn periodIn edge 'Asynchronous init polarity) diff --git a/tests/Clash/Tests/Clocks.hs b/tests/Clash/Tests/Clocks.hs new file mode 100644 --- /dev/null +++ b/tests/Clash/Tests/Clocks.hs @@ -0,0 +1,50 @@ +{-# LANGUAGE TemplateHaskell #-} +{-# LANGUAGE TypeFamilies #-} +{-# OPTIONS_GHC -Wno-orphans #-} +{-# OPTIONS_GHC -Wno-unused-top-binds #-} + +module Clash.Tests.Clocks(tests) where + +import qualified Prelude as P + +import Test.Tasty +import Test.Tasty.HUnit + +import Clash.Explicit.Prelude +import Clash.Intel.ClockGen (altpll) + +-- Ratio of clock periods in 'createDomain' and 'resetLen' are chosen, rest is +-- derived from that + +createDomain vSystem{vName="ClocksSlow", vPeriod=3 * vPeriod vSystem} + +resetLen :: SNat 10 +resetLen = SNat + +lockResampled :: Assertion +lockResampled = + unlockedLenSeen @?= unlockedLen + where + pll :: + Clock ClocksSlow -> + Reset ClocksSlow -> + (Clock System, Signal System Bool) + pll = altpll (SSymbol @"pll") + + unlockedLenSeen = + P.length . P.takeWhile not . + -- Arbitrary cut-off so simulation always ends + sampleN (unlockedLen + 100) . + snd $ pll clockGen (resetGenN resetLen) + +clockRatio :: Int +clockRatio = fromIntegral $ snatToNatural (clockPeriod @ClocksSlow) `div` + snatToNatural (clockPeriod @System) + +unlockedLen :: Int +unlockedLen = snatToNum resetLen * clockRatio - clockRatio + 1 + +tests :: TestTree +tests = + testGroup "Clocks class" + [ testCase "Lock is resampled from reset" lockResampled ] diff --git a/tests/unittests.hs b/tests/unittests.hs --- a/tests/unittests.hs +++ b/tests/unittests.hs @@ -8,6 +8,7 @@ import qualified Clash.Tests.BitVector import qualified Clash.Tests.BlockRam import qualified Clash.Tests.BlockRam.Blob +import qualified Clash.Tests.Clocks import qualified Clash.Tests.Counter import qualified Clash.Tests.DerivingDataRepr import qualified Clash.Tests.Fixed @@ -34,6 +35,7 @@ , Clash.Tests.BitVector.tests , Clash.Tests.BlockRam.tests , Clash.Tests.BlockRam.Blob.tests + , Clash.Tests.Clocks.tests , Clash.Tests.Counter.tests , Clash.Tests.DerivingDataRepr.tests , Clash.Tests.Fixed.tests