clash-prelude: Add holdReset warning documentation

and implement safe replacement `stretchReset`

Author: rowanG077

changelog/2026-01-08T16_58_32+01_00_add_stretchreset

@@ -0,0 +1,2 @@
+FIXED: Added warning documentation to `holdReset` [#3115](https://github.com/clash-lang/clash-compiler/issues/3115)
+FIXED: Added `stretchReset` as safe replacement for `holdReset` [#3115](https://github.com/clash-lang/clash-compiler/issues/3115)

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

@@ -1,5 +1,5 @@
 {-|
-Copyright  :  (C) 2020-2023, QBayLogic B.V.,
+Copyright  :  (C) 2020-2026, QBayLogic B.V.,
                   2022-2023, Google LLC
 License    :  BSD2 (see the file LICENSE)
 Maintainer :  QBayLogic B.V. <devops@qbaylogic.com>
@@ -24,6 +24,7 @@ module Clash.Explicit.Reset
   , resetGlitchFilterWithReset
   , unsafeResetGlitchFilter
   , holdReset
+  , stretchReset
   , convertReset
   , noReset
   , andReset, unsafeAndReset
@@ -55,8 +56,10 @@ import           Clash.Class.Num (satSucc, SaturationMode(SatBound))
 import           Clash.Explicit.Signal
 import           Clash.Explicit.Synchronizer (dualFlipFlopSynchronizer)
 import           Clash.Promoted.Nat
+import           Clash.Promoted.Nat.Literals
 import           Clash.Signal.Internal
 import           Clash.Sized.Index (Index)
+import           Clash.Magic (clashCompileError)
 
 import           GHC.Stack (HasCallStack)
 import           GHC.TypeLits (type (+), type (<=))
@@ -399,20 +402,28 @@ resetGlitchFilter# SNat reg dffSync rstIn0 =
       SActiveHigh -> True
       SActiveLow -> False
 
--- | Hold reset for a number of cycles relative to an incoming reset signal.
+-- | Hold/stretch reset for a number of cycles relative to an incoming reset
+-- signal.
+--
+-- __NB__: 'holdReset' is unsafe for asynchronous resets. It can cause
+-- spurious resets.
+-- For synchronous resets the output is pessimistic since it is driven by
+-- combinational logic.
+-- You probably want to use 'stretchReset' which is safe but has slightly
+-- different timing behaviour.
 --
 -- Example:
 --
--- >>> let sampleWithReset = sampleN 8 . unsafeToActiveHigh
--- >>> sampleWithReset (holdReset @System clockGen enableGen (SNat @2) (resetGenN (SNat @3)))
+-- >>> let sampleReset = sampleN 8 . unsafeToActiveHigh
+-- >>> sampleReset (holdReset @System clockGen enableGen (SNat @2) (resetGenN (SNat @3)))
 -- [True,True,True,True,True,False,False,False]
 --
 -- 'holdReset' holds the reset for an additional 2 clock cycles for a total
 -- of 5 clock cycles where the reset is asserted. 'holdReset' also works on
 -- intermediate assertions of the reset signal:
 --
 -- >>> let rst = fromList [True, False, False, False, True, False, False, False]
--- >>> sampleWithReset (holdReset @System clockGen enableGen (SNat @2) (unsafeFromActiveHigh rst))
+-- >>> sampleReset (holdReset @System clockGen enableGen (SNat @2) (unsafeFromActiveHigh rst))
 -- [True,True,True,False,True,True,True,False]
 --
 holdReset
@@ -433,6 +444,120 @@ holdReset clk en SNat rst =
   counter :: Signal dom (Index (n+1))
   counter = register clk rst en 0 (satSucc SatBound <$> counter)
 
+-- | Hold/stretch reset for a number of cycles relative to an incoming reset
+-- signal. This is a safe replacement for `holdReset`. There are some
+-- differences in behaviour for synchronous resets and asynchronous resets.
+-- If used with a stretch of 0 the function is equivalent to doing nothing to
+-- the reset.
+--
+-- === Synchronous resets
+--
+-- If used with a domain on a synchronous reset the assertion of the reset is
+-- delayed by one cycle relative to the incoming reset. On startup the reset is
+-- asserted for @(n + 1)@ cycles.
+--
+-- >>> let sampleReset = sampleN 9 . unsafeToActiveHigh
+-- >>> let stretchResetBy2 = stretchReset @XilinxSystem clockGen enableGen (SNat @2)
+-- >>> sampleReset (stretchResetBy2 (resetGenN (SNat @3)))
+-- [True,True,True,True,True,True,False,False,False]
+--
+-- The reset assertion sequence is:
+--
+-- - The first cycle the output of the internal register is given.s
+-- - The next three cycles the reset is asserted due to the incoming reset
+--   being asserted.
+-- - The final two assertions are due to the reset being stretched by two cycles.
+--
+-- >>> let rst = fromList [False, False, False, True, False, False, False, False, False]
+-- >>> sampleReset (stretchResetBy2 (unsafeFromActiveHigh rst))
+-- [True,True,True,False,True,True,True,False,False]
+--
+-- Here it shows that on startup the reset is asserted for @(n + 1) = 3@ cycles
+-- On the fourth cycle the input reset is asserted. Notice the delay on
+-- the output reset assertion and that is stretch by two cycles.
+--
+-- === Asynchronous reset
+--
+-- In contrast to the synchronous version there is no single cycle delay from
+-- input reset assertion to output reset assertion. On startup it also asserts
+-- the reset for exactly the stretch period @n@.
+--
+-- >>> let rst = fromList [False, False, False, False, True, False, False, False, False]
+-- >>> let stretchResetBy2 = stretchReset @System clockGen enableGen (SNat @2)
+-- >>> sampleReset (stretchResetBy2 (unsafeFromActiveHigh rst))
+-- [True,True,False,False,True,True,True,False,False]
+--
+stretchReset
+  :: forall dom n
+   . KnownDomain dom
+  => Clock dom
+  -> Enable dom
+  -- ^ Global enable
+  -> SNat n
+  -- ^ Hold for /n/ cycles
+  -> Reset dom
+  -- ^ Reset to extend
+  -> Reset dom
+stretchReset clk en n@SNat rst = case resetKind @dom of
+  SSynchronous -> stretchResetSync clk en n rst
+  SAsynchronous -> stretchResetAsync clk en n rst
+
+stretchResetSync
+  :: forall dom n
+   . KnownDomain dom
+  => DomainResetKind dom ~ 'Synchronous
+  => Clock dom
+  -> Enable dom
+  -- ^ Global enable
+  -> SNat n
+  -- ^ Hold for /n/ cycles
+  -> Reset dom
+  -- ^ Reset to extend
+  -> Reset dom
+stretchResetSync clk en sn@SNat rst = rstOut
+ where
+  isActiveHigh = case resetPolarity @dom of { SActiveHigh -> True; _ -> False }
+
+  rstOut = case compareSNat d1 sn of
+    SNatGT -> rst
+    SNatLE -> unsafeToReset (register clk rst en isActiveHigh rawRst)
+      where
+        counter :: Signal dom (Index (n + 1))
+        counter = register clk rst en 0 (satSucc SatBound <$> counter)
+        rawRst :: Signal dom Bool
+        rawRst = case resetPolarity @dom of
+          SActiveHigh -> (/=maxBound) <$> counter
+          SActiveLow -> (==maxBound) <$> counter
+
+stretchResetAsync
+  :: forall dom n
+   . KnownDomain dom
+  => DomainResetKind dom ~ 'Asynchronous
+  => Clock dom
+  -> Enable dom
+  -- ^ Global enable
+  -> SNat n
+  -- ^ Hold for /n/ cycles
+  -> Reset dom
+  -- ^ Reset to extend
+  -> Reset dom
+stretchResetAsync clk en sn@SNat rst = rstOut
+ where
+  isActiveHigh = case resetPolarity @dom of { SActiveHigh -> True; _ -> False }
+  rstOut = case (snatToInteger sn, compareSNat d2 sn) of
+    (0, _) -> rst
+    (1, _) -> unsafeToReset (register clk rst en isActiveHigh (pure (not isActiveHigh)))
+    (_, SNatLE) -> unsafeToReset (register clk rst en isActiveHigh rawRst)
+      where
+        counter :: Signal dom (Index n)
+        counter = register clk rst en 0 (satSucc SatBound <$> counter)
+        rawRst :: Signal dom Bool
+        rawRst = case resetPolarity @dom of
+          SActiveHigh -> (/=maxBound) <$> counter
+          SActiveLow -> (==maxBound) <$> counter
+    (_, SNatGT) -> clashCompileError "stretchResetAsync: Impossbile! n =! 0 && n != 1 && 2 > n, Please report this at https://github.com/clash-lang/clash-compiler/issues."
+
+
 -- | Convert between different types of reset, adding a synchronizer when
 -- the domains are not the same. See 'resetSynchronizer' for further details
 -- about reset synchronization.

clash-prelude/src/Clash/Signal.hs

@@ -2,7 +2,7 @@
 Copyright  :  (C) 2013-2016, University of Twente,
                   2016-2019, Myrtle Software Ltd,
                   2017     , Google Inc.,
-                  2021-2024, QBayLogic B.V.
+                  2021-2026, QBayLogic B.V.
 License    :  BSD2 (see the file LICENSE)
 Maintainer :  QBayLogic B.V. <devops@qbaylogic.com>
 
@@ -157,6 +157,7 @@ module Clash.Signal
   , resetSynchronizer
   , resetGlitchFilter
   , holdReset
+  , stretchReset
     -- * Enabling
   , Enable
   , toEnable
@@ -1635,26 +1636,91 @@ testFor
   -> Property
 testFor n s = property (and (Clash.Signal.sampleN n s))
 
--- | Hold reset for a number of cycles relative to an implicit reset signal.
+-- | Hold/stretch reset for a number of cycles relative to an incoming reset
+-- signal.
+--
+-- __NB__: 'holdReset' is unsafe for asynchronous resets. It can cause
+-- spurious resets.
+-- For synchronous resets the output is pessimistic since it is driven by
+-- combinational logic.
+-- You probably want to use 'stretchReset' which is safe but has slightly
+-- different timing behaviour.
 --
 -- Example:
 --
--- >>> sampleN @System 8 (unsafeToActiveHigh (holdReset (SNat @2)))
--- [True,True,True,False,False,False,False,False]
+-- >>> holdResetBool = unsafeToActiveHigh . (holdReset @System)
+-- >>> sampleN 8 (exposeReset (holdResetBool (SNat @2)) (resetGenN (SNat @3)))
+-- [True,True,True,True,True,False,False,False]
 --
 -- 'holdReset' holds the reset for an additional 2 clock cycles for a total
--- of 3 clock cycles where the reset is asserted.
+-- of 5 clock cycles where the reset is asserted. 'holdReset' also works on
+-- intermediate assertions of the reset signal:
+--
+-- >>> let rst = fromList [True, False, False, False, True, False, False, False]
+-- >>> sampleN 8 (exposeReset (holdResetBool (SNat @2)) (unsafeFromActiveHigh rst))
+-- [True,True,True,False,True,True,True,False]
 --
 holdReset
   :: forall dom m
    . HiddenClockResetEnable dom
   => SNat m
-  -- ^ Hold for /m/ cycles, counting from the moment the incoming reset
-  -- signal becomes deasserted.
+  -- ^ Hold for /m/ cycles
   -> Reset dom
 holdReset m =
   hideClockResetEnable (\clk rst en -> E.holdReset clk en m rst)
 
+
+-- | Hold/stretch reset for a number of cycles relative to an incoming reset
+-- signal. This is a safe replacement for `holdReset`. There are some
+-- differences in behaviour for synchronous resets and asynchronous resets.
+-- If used with a stretch of 0 the function is equivalent to doing nothing to
+-- the reset.
+--
+-- === Synchronous resets
+--
+-- If used with a domain on a synchronous reset the assertion of the reset is
+-- delayed by one cycle relative to the incoming reset. On startup the reset is
+-- asserted for @(n + 1)@ cycles.
+--
+-- >>> stretchResetToBool = unsafeToActiveHigh . (stretchReset @XilinxSystem)
+-- >>> sampleN 9 (exposeReset (stretchResetToBool (SNat @2)) (resetGenN (SNat @3)))
+-- [True,True,True,True,True,True,False,False,False]
+--
+-- The reset assertion sequence is:
+--
+-- - The first cycle the output of the internal register is given.
+-- - The next three cycles the reset is asserted due to the incoming reset
+--   being asserted.
+-- - The final two assertions are due to the reset being stretched by two cycles.
+--
+-- >>> let rst = fromList [False, False, False, True, False, False, False, False]
+-- >>> sampleN 9 (exposeReset (stretchResetToBool (SNat @2)) (unsafeFromActiveHigh rst))
+-- [True,True,True,False,True,True,True,False,False]
+--
+-- Here it shows that on startup the reset is asserted for @(n + 1) = 3@ cycles
+-- On the fourth cycle the input reset is asserted. Notice the delay on
+-- the output reset assertion and that is stretch by two cycles.
+--
+-- === Asynchronous reset
+--
+-- In contrast to the synchronous version there is no single cycle delay from
+-- input reset assertion to output reset assertion. On startup it also asserts
+-- the reset for exactly the stretch period @n@.
+--
+-- >>> stretchResetToBool = unsafeToActiveHigh . (stretchReset @System)
+-- >>> let rst = fromList [False, False, False, False, True, False, False, False, False]
+-- >>> sampleN 9 (exposeReset (stretchResetToBool (SNat @2)) (unsafeFromActiveHigh rst))
+-- [True,True,False,False,True,True,True,False,False]
+--
+stretchReset
+  :: forall dom m
+   . HiddenClockResetEnable dom
+  => SNat m
+  -- ^ Hold for /m/ cycles
+  -> Reset dom
+stretchReset m =
+  hideClockResetEnable (\clk rst en -> E.stretchReset clk en m rst)
+
 -- | Like 'fromList', but resets on reset and has a defined reset value.
 --
 -- >>> let rst = unsafeFromActiveHigh (fromList [True, True, False, False, True, False])