diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,20 @@ # Changelog for the Clash project +## 1.4.5 *Oct 13th 2021* + +Changed: + + * `clash-lib` now supports prettyprinter 1.7 + +Documentation: + + * The documentation on hidden clocks, resets, and enables has been corrected and extended in `Clash.Signal`. + ## 1.4.4 *Oct 11th 2021* +Changed: + + * `clash-lib` now supports aeson >= 2.0 + Fixed: * Dont' loop on recursive data types hiding behind type families [#1921](https://github.com/clash-lang/clash-compiler/issues/1921) 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.4.4 +Version: 1.4.5 Synopsis: Clash: a functional hardware description language - Prelude library Description: Clash is a functional hardware description language that borrows both its diff --git a/src/Clash/Explicit/Prelude.hs b/src/Clash/Explicit/Prelude.hs --- a/src/Clash/Explicit/Prelude.hs +++ b/src/Clash/Explicit/Prelude.hs @@ -181,6 +181,15 @@ >>> let windowD3 = windowD @2 -} +{- $hiding +"Clash.Explicit.Prelude" re-exports most of the Haskell "Prelude" with the +exception of those functions that the Clash API defines to work on 'Vec' from +"Clash.Sized.Vector" instead of on lists as the Haskell Prelude does. In +addition, for the 'Clash.Class.Parity.odd' and 'Clash.Class.Parity.even' +functions a type class called 'Clash.Class.Parity.Parity' is available at +"Clash.Class.Parity". +-} + -- | Give a window over a 'Signal' -- -- @ 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 @@ -143,6 +143,14 @@ >>> let rP clk rst en = registerB clk rst en (8::Int,8::Int) -} +{- $hiding +"Clash.Explicit.Prelude.Safe" re-exports most of the Haskell "Prelude" with the +exception of those functions that the Clash API defines to work on 'Vec' from +"Clash.Sized.Vector" instead of on lists as the Haskell Prelude does. In +addition, for the 'Clash.Class.Parity.odd' and 'Clash.Class.Parity.even' +functions a type class called 'Clash.Class.Parity.Parity' is available at +"Clash.Class.Parity". +-} -- | Create a 'register' function for product-type like signals (e.g. -- @('Signal' a, 'Signal' b)@) 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 @@ -2,9 +2,10 @@ Copyright : (C) 2013-2016, University of Twente, 2016-2019, Myrtle Software, 2017 , Google Inc. - 2020 , Ben Gamari + 2020 , Ben Gamari, + 2021 , QBayLogic B.V. License : BSD2 (see the file LICENSE) -Maintainer : Christiaan Baaij +Maintainer : QBayLogic B.V. Clash has synchronous 'Signal's in the form of: @@ -455,16 +456,20 @@ -- -- Note: this unsafeSynchronizer is defined to be consistent with the vhdl and verilog -- implementations however as only synchronous signals are represented in Clash this --- cannot be done precisely and can lead to odd behaviour. For example, +-- cannot be done precisely and can lead to odd behavior. For example, +-- -- @ -- sample $ unsafeSynchronizer @Dom2 @Dom7 . unsafeSynchronizer @Dom7 @Dom2 $ fromList [0..10] -- > [0,4,4,4,7,7,7,7,11,11,11.. -- @ +-- -- is quite different from the identity, +-- -- @ -- sample $ fromList [0..10] -- > [0,1,2,3,4,5,6,7,8,9,10.. -- @ +-- -- with values appearing from the "future". veryUnsafeSynchronizer :: Int diff --git a/src/Clash/Explicit/Testbench.hs b/src/Clash/Explicit/Testbench.hs --- a/src/Clash/Explicit/Testbench.hs +++ b/src/Clash/Explicit/Testbench.hs @@ -430,9 +430,9 @@ -- testInput = 'Clash.Explicit.Testbench.stimuliGenerator' clkA1 rstA1 $('Clash.Sized.Vector.listToVecTH' [1::Unsigned 8,2,3,4,5,6,7,8]) -- expectedOutput = 'Clash.Explicit.Testbench.outputVerifier' clkB2 rstB2 $('Clash.Sized.Vector.listToVecTH' [(0,0) :: (Unsigned 8, Unsigned 8),(1,2),(3,4),(5,6),(7,8)]) -- done = expectedOutput (topEntity clkA1 rstA1 enableGen clkB2 testInput) --- done' = not \<$\> done --- clkA1 = 'tbClockGen' \@\"Fast\" (unsafeSynchronizer clkB2 clkA1 done') --- clkB2 = 'tbClockGen' \@\"Slow\" done' +-- notDone = not \<$\> done +-- clkA1 = 'tbClockGen' \@\"Fast\" (unsafeSynchronizer clkB2 clkA1 notDone) +-- clkB2 = 'tbClockGen' \@\"Slow\" notDone -- rstA1 = 'Clash.Signal.resetGen' \@\"Fast\" -- rstB2 = 'Clash.Signal.resetGen' \@\"Slow\" -- @ diff --git a/src/Clash/HaskellPrelude.hs b/src/Clash/HaskellPrelude.hs --- a/src/Clash/HaskellPrelude.hs +++ b/src/Clash/HaskellPrelude.hs @@ -3,10 +3,12 @@ License : BSD2 (see the file LICENSE) Maintainer : QBayLogic B.V -"Clash.HaskellPrelude" re-exports most of the Haskell "Prelude" with the exception of -the following: (++), (!!), concat, drop, even, foldl, foldl1, foldr, foldr1, head, -init, iterate, last, length, map, odd, repeat, replicate, reverse, scanl, scanr, -splitAt, tail, take, unzip, unzip3, zip, zip3, zipWith, zipWith3. +"Clash.HaskellPrelude" re-exports most of the Haskell "Prelude" with the +exception of those functions that the Clash API defines to work on +'Clash.Sized.Vector.Vec' from "Clash.Sized.Vector" instead of on lists as the +Haskell Prelude does. In addition, for the 'Clash.Class.Parity.odd' and +'Clash.Class.Parity.even' functions a type class called +'Clash.Class.Parity.Parity' is available at "Clash.Class.Parity". -} {-# LANGUAGE Safe #-} diff --git a/src/Clash/Prelude.hs b/src/Clash/Prelude.hs --- a/src/Clash/Prelude.hs +++ b/src/Clash/Prelude.hs @@ -210,15 +210,12 @@ {- $hiding "Clash.Prelude" re-exports most of the Haskell "Prelude" with the exception of -the following: (++), (!!), concat, drop, even, foldl, foldl1, foldr, foldr1, head, -init, iterate, last, length, map, odd, repeat, replicate, reverse, scanl, scanr, -splitAt, tail, take, unzip, unzip3, zip, zip3, zipWith, zipWith3. - -It instead exports the identically named functions defined in terms of -'Clash.Sized.Vector.Vec' at "Clash.Sized.Vector". For the 'odd' end 'even' -function a type class called Parity is available at 'Clash.Class.Parity'. +those functions that the Clash API defines to work on 'Vec' from +"Clash.Sized.Vector" instead of on lists as the Haskell Prelude does. +In addition, for the 'Clash.Class.Parity.odd' and 'Clash.Class.Parity.even' +functions a type class called 'Clash.Class.Parity.Parity' is available at +"Clash.Class.Parity". -} - -- | Give a window over a 'Signal' -- 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 @@ -159,13 +159,12 @@ -} {- $hiding -"Clash.Prelude" re-exports most of the Haskell "Prelude" with the exception of -the following: (++), (!!), concat, drop, foldl, foldl1, foldr, foldr1, head, -init, iterate, last, length, map, repeat, replicate, reverse, scanl, scanr, -splitAt, tail, take, unzip, unzip3, zip, zip3, zipWith, zipWith3. - -It instead exports the identically named functions defined in terms of -'Clash.Sized.Vector.Vec' at "Clash.Sized.Vector". +"Clash.Prelude.Safe" re-exports most of the Haskell "Prelude" with the exception +of those functions that the Clash API defines to work on 'Vec' from +"Clash.Sized.Vector" instead of on lists as the Haskell Prelude does. In +addition, for the 'Clash.Class.Parity.odd' and 'Clash.Class.Parity.even' +functions a type class called 'Clash.Class.Parity.Parity' is available at +"Clash.Class.Parity". -} -- | Create a 'register' function for product-type like signals (e.g. '(Signal a, Signal b)') diff --git a/src/Clash/Signal.hs b/src/Clash/Signal.hs --- a/src/Clash/Signal.hs +++ b/src/Clash/Signal.hs @@ -1,1852 +1,1919 @@ {-| Copyright : (C) 2013-2016, University of Twente, 2016-2019, Myrtle Software Ltd, - 2017 , Google Inc. -License : BSD2 (see the file LICENSE) -Maintainer : Christiaan Baaij - -Clash has synchronous 'Signal's in the form of: - -@ -'Signal' (dom :: 'Domain') a -@ - -Where /a/ is the type of the value of the 'Signal', for example /Int/ or /Bool/, -and /dom/ is the /clock-/ (and /reset-/) domain to which the memory elements -manipulating these 'Signal's belong. - -The type-parameter, /dom/, is of the kind 'Domain' - a simple string. That -string refers to a single /synthesis domain/. A synthesis domain describes the -behavior of certain aspects of memory elements in it. More specifically, a -domain looks like: - -@ -'DomainConfiguration' - { _name :: 'Domain' - -- ^ Domain name - , _period :: 'Clash.Promoted.Nat.Nat' - -- ^ Clock period in /ps/ - , _activeEdge :: 'ActiveEdge' - -- ^ Active edge of the clock - , _resetKind :: 'ResetKind' - -- ^ Whether resets are synchronous (edge-sensitive) or asynchronous (level-sensitive) - , _initBehavior :: 'InitBehavior' - -- ^ Whether the initial (or "power up") value of memory elements is - -- unknown/undefined, or configurable to a specific value - , _resetPolarity :: ResetPolarity - -- ^ Whether resets are active high or active low - } -@ - -Check the documentation of each of the types to see the various options Clash -provides. In order to specify a domain, an instance of 'KnownDomain' should be -made. Clash provides an implementation 'System' with some common options -chosen: - -@ -instance KnownDomain "System" where - type KnownConf "System" = 'DomainConfiguration "System" 10000 'Rising 'Asynchronous 'Defined 'ActiveHigh - knownDomain = SDomainConfiguration SSymbol SNat SRising SAsynchronous SDefined SActiveHigh -@ - -In words, \"System\" is a synthesis domain with a clock running with a period -of 10000 /ps/. Memory elements respond to the rising edge of the clock, -asynchronously to changes in their resets, and have defined power up values -if applicable. - -In order to create a new domain, you don't have to instantiate it explicitly. -Instead, you can have 'createDomain' create a domain for you. You can also use -the same function to subclass existing domains. - -* __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! -* __NB__: Whether 'System' has good defaults depends on your target platform. -Check out 'IntelSystem' and 'XilinxSystem' too! --} - -{-# LANGUAGE ConstraintKinds #-} -{-# LANGUAGE CPP #-} -{-# LANGUAGE ExplicitNamespaces #-} -{-# LANGUAGE FlexibleContexts #-} -{-# LANGUAGE GADTs #-} -{-# LANGUAGE MultiParamTypeClasses #-} -{-# LANGUAGE RankNTypes #-} - -{-# LANGUAGE Trustworthy #-} - -#if __GLASGOW_HASKELL__ < 806 -{-# LANGUAGE TypeInType #-} -#endif - -{-# OPTIONS_HADDOCK show-extensions #-} - -module Clash.Signal - ( -- * Synchronous signals - Signal - , BiSignalIn - , BiSignalOut - , BiSignalDefault(..) - -- * Domain - , Domain - , sameDomain - , KnownDomain(..) - , KnownConfiguration - , ActiveEdge(..) - , SActiveEdge(..) - , InitBehavior(..) - , SInitBehavior(..) - , ResetKind(..) - , SResetKind(..) - , ResetPolarity(..) - , SResetPolarity(..) - , DomainConfiguration(..) - , SDomainConfiguration(..) - -- ** Configuration type families - , DomainPeriod - , DomainActiveEdge - , DomainResetKind - , DomainInitBehavior - , DomainResetPolarity - -- ** Default domains - , System - , XilinxSystem - , IntelSystem - , vSystem - , vIntelSystem - , vXilinxSystem - -- ** Domain utilities - , VDomainConfiguration(..) - , vDomain - , createDomain - , knownVDomain - , clockPeriod - , activeEdge - , resetKind - , initBehavior - , resetPolarity - -- * Clock - , Clock - , periodToHz - , hzToPeriod -#ifdef CLASH_MULTIPLE_HIDDEN - -- ** Synchronization primitive - , unsafeSynchronizer -#endif - -- * Reset - , Reset - , unsafeToReset - , unsafeFromReset - , unsafeToHighPolarity - , unsafeToLowPolarity - , unsafeFromHighPolarity - , unsafeFromLowPolarity -#ifdef CLASH_MULTIPLE_HIDDEN - , convertReset -#endif - , resetSynchronizer - , resetGlitchFilter - , holdReset - -- ** Enabling - , Enable - , toEnable - , fromEnable - , S.enableGen - -- * Hidden clocks and resets - -- $hiddenclockandreset - - -- ** Hidden clock - , HiddenClock - , hideClock - , exposeClock - , withClock -#ifdef CLASH_MULTIPLE_HIDDEN - , exposeSpecificClock - , withSpecificClock -#endif - , hasClock - -- ** Hidden reset - , HiddenReset - , hideReset - , exposeReset - , withReset -#ifdef CLASH_MULTIPLE_HIDDEN - , exposeSpecificReset - , withSpecificReset -#endif - , hasReset - -- ** Hidden enable - , HiddenEnable - , hideEnable - , exposeEnable - , withEnable -#ifdef CLASH_MULTIPLE_HIDDEN - , exposeSpecificEnable - , withSpecificEnable -#endif - , hasEnable - -- ** Hidden clock, reset, and enable - , HiddenClockResetEnable - , hideClockResetEnable - , exposeClockResetEnable - , withClockResetEnable -#ifdef CLASH_MULTIPLE_HIDDEN - , exposeSpecificClockResetEnable - , withSpecificClockResetEnable -#endif - , SystemClockResetEnable - -- * Basic circuit functions - , dflipflop - , delay - , delayMaybe - , delayEn - , register - , regMaybe - , regEn - , mux - -- * Simulation and testbench functions - , clockGen - , resetGen - , resetGenN - , systemClockGen - , systemResetGen - -- * Boolean connectives - , (.&&.), (.||.) - -- * Product/Signal isomorphism - , Bundle(..) - , EmptyTuple(..) - , TaggedEmptyTuple(..) - -- * Simulation functions (not synthesizable) - , simulate - , simulateB - , simulateN - , simulateWithReset - , simulateWithResetN - -- ** lazy versions - , simulate_lazy - , simulateB_lazy - -- ** Automaton - , signalAutomaton - -- * List \<-\> Signal conversion (not synthesizable) - , sample - , sampleN - , sampleWithReset - , sampleWithResetN - , fromList - , fromListWithReset - -- ** lazy versions - , sample_lazy - , sampleN_lazy - , fromList_lazy - -- * QuickCheck combinators - , testFor - -- * Type classes - -- ** 'Eq'-like - , (.==.), (./=.) - -- ** 'Ord'-like - , (.<.), (.<=.), (.>=.), (.>.) - -- * Bisignal functions - , veryUnsafeToBiSignalIn - , readFromBiSignal - , writeToBiSignal - , mergeBiSignalOuts - - -- * Internals - , HiddenClockName - , HiddenResetName - , HiddenEnableName - ) -where - -import Control.Arrow.Transformer.Automaton (Automaton) -import GHC.TypeLits (type (<=)) -import Data.Proxy (Proxy(..)) -import Prelude -import Test.QuickCheck (Property, property) - - -#ifdef CLASH_MULTIPLE_HIDDEN -import GHC.TypeLits (AppendSymbol) -import Clash.Class.HasDomain (WithSingleDomain) -#endif - -import Clash.Class.HasDomain (WithSpecificDomain) -import qualified Clash.Explicit.Signal as E -import qualified Clash.Explicit.Reset as E -import Clash.Explicit.Reset (resetSynchronizer, resetGlitchFilter) -import Clash.Explicit.Signal (systemClockGen, systemResetGen) -import qualified Clash.Explicit.Signal as S -import Clash.Hidden -import Clash.Promoted.Nat (SNat (..), snatToNum) -import Clash.Signal.Bundle - (Bundle (..), EmptyTuple(..), TaggedEmptyTuple(..)) -import Clash.Signal.BiSignal --(BisignalIn, BisignalOut, ) -import Clash.Signal.Internal hiding - (sample, sample_lazy, sampleN, sampleN_lazy, simulate, simulate_lazy, testFor, - signalAutomaton) -import Clash.Signal.Internal.Ambiguous - (knownVDomain, clockPeriod, activeEdge, resetKind, initBehavior, resetPolarity) -import Clash.XException (NFDataX) - -{- $setup ->>> :set -XFlexibleContexts -XTypeApplications ->>> :m -Clash.Explicit.Prelude ->>> :m -Clash.Explicit.Prelude.Safe ->>> import Clash.Prelude ->>> import Clash.Promoted.Nat (SNat(..)) ->>> import Clash.XException (printX) ->>> import Control.Applicative (liftA2) ->>> let oscillate = register False (not <$> oscillate) ->>> let count = regEn 0 oscillate (count + 1) ->>> :{ -let sometimes1 = s where - s = register Nothing (switch <$> s) - switch Nothing = Just 1 - switch _ = Nothing -:} - ->>> :{ -let countSometimes = s where - s = regMaybe 0 (plusM (pure <$> s) sometimes1) - plusM = liftA2 (liftA2 (+)) -:} - --} - --- * Hidden clock, reset, and enable arguments - -{- $hiddenclockandreset #hiddenclockandreset# -Clocks and resets are by default implicitly routed to their components. You can -see from the type of a component whether it has hidden clock or reset -arguments: - -It has a hidden clock when it has a: - -@ -f :: 'HiddenClock' dom => ... -@ - -Constraint. - -Or it has a hidden reset when it has a: - -@ -g :: 'HiddenReset' dom => ... -@ - -Constraint. - -Or it has both a hidden clock argument and a hidden reset argument when it -has a: - -@ -h :: 'HiddenClockResetEnable' dom => .. -@ - -Constraint. - -Given a component with an explicit clock and reset arguments, you can turn them -into hidden arguments using 'hideClock', 'hideReset', and 'hideEnable'. So given a: - -@ -f :: Clock dom -> Reset dom -> Enable dom -> Signal dom a -> ... -@ - -You hide the clock and reset arguments by: - -@ --- g :: 'HiddenClockResetEnable' dom => Signal dom a -> ... -g = 'hideClockResetEnable' f -@ - -Or, alternatively, by: - -@ --- h :: 'HiddenClockResetEnable' dom => Signal dom a -> ... -h = f 'hasClock' 'hasReset' 'hasEnable' -@ - -=== Assigning explicit clock and reset arguments to hidden clocks and resets - -Given a component: - -@ -f :: 'HiddenClockResetEnable' dom - => Signal dom Int - -> Signal dom Int -@ - -which has hidden clock and routed reset arguments, we expose those hidden -arguments so that we can explicitly apply them: - -@ --- g :: Clock dom -> Reset dom -> Signal dom Int -> Signal dom Int -g = 'exposeClockResetEnable' f -@ - -or, alternatively, by: - -@ --- h :: Clock dom -> Reset dom -> Signal dom Int -> Signal dom Int -h clk rst = withClock clk rst f -@ - -Similarly, there are 'exposeClock' and 'exposeReset' to connect just expose -the hidden clock or the hidden reset argument. - -You will need to explicitly apply clocks and resets when you want to use -components such as PPLs and 'resetSynchronizer': - -@ -topEntity - :: Clock System - -> Reset System - -> Signal System Bit - -> Signal System (BitVector 8) -topEntity clk rst ena key1 = - let (pllOut,pllStable) = altpll (SSymbol \@\"altpll50\") clk rst - rstSync = 'resetSynchronizer' pllOut (unsafeToHighPolarity pllStable) ena - in exposeClockResetEnable leds pllOut rstSync enableGen - where - key1R = isRising 1 key1 - leds = mealy blinkerT (1, False, 0) key1R -@ - -or, using the alternative method: - -@ -topEntity - :: Clock System - -> Reset System - -> Signal System Bit - -> Signal System (BitVector 8) -topEntity clk rst ena key1 = - let (pllOut,pllStable) = altpll (SSymbol \@\"altpll50\") clk rst - rstSync = 'resetSynchronizer' pllOut (unsafeToHighPolarity pllStable) ena - in 'withClockResetEnable' pllOut rstSync enableGen leds - where - key1R = isRising 1 key1 - leds = mealy blinkerT (1, False, 0) key1R -@ - --} - -#ifdef CLASH_MULTIPLE_HIDDEN -type HiddenClockName dom = AppendSymbol dom "_clk" -type HiddenResetName dom = AppendSymbol dom "_rst" -type HiddenEnableName dom = AppendSymbol dom "_en" -#else -type HiddenClockName (dom :: Domain) = "clock" -type HiddenResetName (dom :: Domain) = "reset" -type HiddenEnableName (dom :: Domain) = "enable" -#endif - --- | A /constraint/ that indicates the component has a hidden 'Clock' --- ---