Mark resetGen as non-synthesizable (#2379)

Fixes #2375

Co-authored-by: Peter Lebbing <[email protected]>

Author: martijnbastiaan

changelog/2022-12-18T21_14_44+01_00_fix2375

@@ -0,0 +1 @@
+FIXED: `resetGen`'s documentation now mentions it is non-synthesizable ([#2375](https://github.com/clash-lang/clash-compiler/issues/2375))

clash-lib/prims/systemverilog/Clash_Signal_Internal.primitives.yaml

@@ -231,4 +231,5 @@
       `endif
       // pragma translate_on
       // resetGen end
+    warning: Clash.Signal.Internal.resetGenN can not be synthesized to hardware!
     workInfo: Always

clash-prelude/src/Clash/Explicit/Signal.hs

@@ -3,7 +3,7 @@ Copyright  :  (C) 2013-2016, University of Twente,
                   2016-2019, Myrtle Software,
                   2017-2022, Google Inc.
                   2020     , Ben Gamari,
-                  2021     , QBayLogic B.V.
+                  2021-2023, QBayLogic B.V.
 License    :  BSD2 (see the file LICENSE)
 Maintainer :  QBayLogic B.V. <[email protected]>
 
@@ -338,9 +338,11 @@ systemClockGen
   :: Clock System
 systemClockGen = clockGen
 
--- | Reset generator for the 'System' clock domain.
+-- | Reset generator for use in simulation, for the 'System' clock domain.
+-- Asserts the reset for a single cycle.
 --
--- __NB__: should only be used for simulation or the \testBench\ function.
+-- __NB__: While this can be used in the @testBench@ function, it cannot be
+-- synthesized to hardware.
 --
 -- === __Example__
 --
@@ -353,7 +355,7 @@ systemClockGen = clockGen
 --   where
 --     testInput      = pure ((1 :> 2 :> 3 :> Nil) :> (4 :> 5 :> 6 :> Nil) :> Nil)
 --     expectedOutput = outputVerifier' ((1:>2:>3:>4:>5:>6:>Nil):>Nil)
---     done           = exposeClockResetEnable (expectedOutput (topEntity <$> testInput)) clk rst
+--     done           = exposeClockResetEnable (expectedOutput (topEntity \<$\> testInput)) clk rst
 --     clk            = tbSystemClockGen (not <\$\> done)
 --     rst            = 'systemResetGen'
 -- @

clash-prelude/src/Clash/Signal/Internal.hs

@@ -194,6 +194,7 @@ import Clash.XException
 >>> import Clash.Prelude (SSymbol(..))
 >>> import Clash.Signal.Internal
 >>> import Clash.Promoted.Nat
+>>> import Clash.Promoted.Nat.Literals
 >>> import Clash.XException
 >>> import Data.Ratio (Ratio)
 >>> import Numeric.Natural (Natural)
@@ -1016,7 +1017,8 @@ tbDynamicClockGen periods ena =
 {-# ANN tbDynamicClockGen hasBlackBox #-}
 
 
--- | Reset generator
+-- | Reset generator for simulation purposes. Asserts the reset for a single
+-- cycle.
 --
 -- To be used like:
 --
@@ -1026,26 +1028,31 @@ tbDynamicClockGen periods ena =
 --
 -- See 'Clash.Explicit.Testbench.tbClockGen' for example usage.
 --
+-- __NB__: While this can be used in the @testBench@ function, it cannot be
+-- synthesized to hardware.
 resetGen
   :: forall dom
    . KnownDomain dom
   => Reset dom
 resetGen = resetGenN (SNat @1)
 {-# INLINE resetGen #-}
 
--- | Generate reset that's asserted for the first /n/ cycles.
+-- | Reset generator for simulation purposes. Asserts the reset for the first /n/
+-- cycles.
 --
 -- To be used like:
 --
 -- @
--- rstSystem5 = resetGen @System (SNat @5)
+-- rstSystem5 = resetGen @System d5
 -- @
 --
 -- Example usage:
 --
--- >>> sampleN 7 (unsafeToHighPolarity (resetGenN @System (SNat @3)))
+-- >>> sampleN 7 (unsafeToHighPolarity (resetGenN @System d3))
 -- [True,True,True,False,False,False,False]
 --
+-- __NB__: While this can be used in the @testBench@ function, it cannot be
+-- synthesized to hardware.
 resetGenN
   :: forall dom n
    . (KnownDomain dom, 1 <= n)