{-|
Copyright  :  (C) 2013-2016, University of Twente,
                  2017     , Google Inc.
                  2019     , Myrtle Software Ltd
License    :  BSD2 (see the file LICENSE)
Maintainer :  Christiaan Baaij <christiaan.baaij@gmail.com>
-}

{-# LANGUAGE CPP                  #-}
{-# LANGUAGE DataKinds            #-}
{-# LANGUAGE FlexibleContexts     #-}
{-# LANGUAGE KindSignatures       #-}
{-# LANGUAGE ScopedTypeVariables  #-}
{-# LANGUAGE TypeApplications     #-}
{-# LANGUAGE TypeFamilies         #-}
{-# LANGUAGE TypeOperators        #-}
{-# LANGUAGE UndecidableInstances #-}
#if __GLASGOW_HASKELL__ >= 806
{-# LANGUAGE NoStarIsType #-}
#endif
#if __GLASGOW_HASKELL__ < 806
{-# LANGUAGE TypeInType #-}
#endif

{-# LANGUAGE Trustworthy #-}

{-# OPTIONS_GHC -fplugin GHC.TypeLits.Normalise       #-}

module Clash.Signal.Delayed
  ( -- * Delay-annotated synchronous signals
    DSignal
  , delayed
  , delayedI
  , delayN
  , delayI
  , delayedFold
  , feedback
    -- * Signal \<-\> DSignal conversion
  , fromSignal
  , toSignal
    -- * List \<-\> DSignal conversion (not synthesizable)
  , dfromList
    -- ** lazy versions
  , dfromList_lazy
    -- * Experimental
  , unsafeFromSignal
  , antiDelay
  )
where

import           Data.Coerce                   (coerce)
import           Data.Kind                     (Type)
import           Data.Proxy                    (Proxy(..))
import           GHC.TypeLits
  (KnownNat, type (^), type (+), type (*), Nat)
import           Data.Singletons.Prelude       (Apply, TyFun, type (@@))

import           Clash.Signal.Internal         (Domain)
import Clash.Signal.Delayed.Internal
  (DSignal(..), dfromList, dfromList_lazy, fromSignal, toSignal,
   unsafeFromSignal, antiDelay, feedback)
import qualified Clash.Explicit.Signal.Delayed as E
import           Clash.Sized.Vector            (Vec, dtfold)
import           Clash.Signal
  (HiddenClockResetEnable , hideClockResetEnable, Signal, delay)

import           Clash.Promoted.Nat            (SNat (..), snatToInteger)
import           Clash.XException              (NFDataX)

{- $setup
>>> :set -XDataKinds -XTypeOperators -XTypeApplications -XFlexibleContexts
>>> import Clash.Prelude
>>> let delay3 = delayed (-1 :> -1 :> -1 :> Nil)
>>> let delay2 = delayedI :: HiddenClockResetEnable dom  => Int -> DSignal dom n Int -> DSignal dom (n + 2) Int
>>> let delayN2 = delayN d2
>>> let delayI2 = delayI :: HiddenClockResetEnable dom  => Int -> DSignal dom n Int -> DSignal dom (n + 2) Int
>>> let countingSignals = Clash.Prelude.repeat (dfromList [0..]) :: Vec 4 (DSignal dom 0 Int)
-}

-- | Delay a 'DSignal' for @d@ periods.
--
-- @
-- delay3
--   :: HiddenClockResetEnable dom
--   => 'DSignal' dom n Int
--   -> 'DSignal' dom (n + 3) Int
-- delay3 = 'delayed' (-1 ':>' -1 ':>' -1 ':>' 'Nil')
-- @
--
-- >>> sampleN @System 7 (toSignal (delay3 (dfromList [0..])))
-- [-1,-1,-1,-1,1,2,3]
delayed
  :: ( KnownNat d
     , HiddenClockResetEnable dom
     , NFDataX a
     )
  => Vec d a
  -> DSignal dom n a
  -> DSignal dom (n + d) a
delayed :: Vec d a -> DSignal dom n a -> DSignal dom (n + d) a
delayed = (KnownDomain dom =>
 Clock dom
 -> Reset dom
 -> Enable dom
 -> Vec d a
 -> DSignal dom n a
 -> DSignal dom (n + d) a)
-> Vec d a -> DSignal dom n a -> DSignal dom (n + d) a
forall (dom :: Domain) r.
HiddenClockResetEnable dom =>
(KnownDomain dom => Clock dom -> Reset dom -> Enable dom -> r) -> r
hideClockResetEnable KnownDomain dom =>
Clock dom
-> Reset dom
-> Enable dom
-> Vec d a
-> DSignal dom n a
-> DSignal dom (n + d) a
forall (dom :: Domain) a (n :: Nat) (d :: Nat).
(KnownDomain dom, KnownNat d, NFDataX a) =>
Clock dom
-> Reset dom
-> Enable dom
-> Vec d a
-> DSignal dom n a
-> DSignal dom (n + d) a
E.delayed

-- | Delay a 'DSignal' for @d@ periods, where @d@ is derived from the context.
--
-- @
-- delay2
--   :: HiddenClockResetEnable dom
--   => Int
--   -> 'DSignal' dom n Int
--   -> 'DSignal' dom (n + 2) Int
-- delay2 = 'delayedI'
-- @
--
-- >>> sampleN @System 7 (toSignal (delay2 (-1) (dfromList [0..])))
-- [-1,-1,-1,1,2,3,4]
--
-- Or @d@ can be specified using type application:
--
-- >>> :t delayedI @3
-- delayedI @3
--   :: (...
--       ...
--       ...
--       ...) =>
--      a -> DSignal dom n a -> DSignal dom (n + 3) a
delayedI
  :: ( KnownNat d
     , NFDataX a
     , HiddenClockResetEnable dom  )
  => a
  -- ^ Initial value
  -> DSignal dom n a
  -> DSignal dom (n + d) a
delayedI :: a -> DSignal dom n a -> DSignal dom (n + d) a
delayedI = (KnownDomain dom =>
 Clock dom
 -> Reset dom
 -> Enable dom
 -> a
 -> DSignal dom n a
 -> DSignal dom (n + d) a)
-> a -> DSignal dom n a -> DSignal dom (n + d) a
forall (dom :: Domain) r.
HiddenClockResetEnable dom =>
(KnownDomain dom => Clock dom -> Reset dom -> Enable dom -> r) -> r
hideClockResetEnable KnownDomain dom =>
Clock dom
-> Reset dom
-> Enable dom
-> a
-> DSignal dom n a
-> DSignal dom (n + d) a
forall (d :: Nat) (dom :: Domain) a (n :: Nat).
(KnownNat d, KnownDomain dom, NFDataX a) =>
Clock dom
-> Reset dom
-> Enable dom
-> a
-> DSignal dom n a
-> DSignal dom (n + d) a
E.delayedI

-- | Delay a 'DSignal' for @d@ cycles, the value at time 0..d-1 is /a/.
--
-- @
-- delay2
--   :: HiddenClockResetEnable dom
--   => Int
--   -> 'DSignal' dom n Int
--   -> 'DSignal' dom (n + 2) Int
-- delay2 = 'delayN' d2
-- @
--
-- >>> printX $ sampleN @System 6 (toSignal (delayN2 (-1) (dfromList [1..])))
-- [-1,-1,1,2,3,4]
delayN
  :: forall dom  a d n
   . ( HiddenClockResetEnable dom
     , NFDataX a )
  => SNat d
  -> a
  -- ^ Initial value
  -> DSignal dom n a
  -> DSignal dom (n+d) a
delayN :: SNat d -> a -> DSignal dom n a -> DSignal dom (n + d) a
delayN d :: SNat d
d dflt :: a
dflt = Signal dom a -> DSignal dom (n + d) a
forall a b. Coercible a b => a -> b
coerce (Signal dom a -> DSignal dom (n + d) a)
-> (DSignal dom n a -> Signal dom a)
-> DSignal dom n a
-> DSignal dom (n + d) a
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Integer -> Signal dom a -> Signal dom a
go (SNat d -> Integer
forall (n :: Nat). SNat n -> Integer
snatToInteger SNat d
d) (Signal dom a -> Signal dom a)
-> (DSignal dom n a -> Signal dom a)
-> DSignal dom n a
-> Signal dom a
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Coercible (DSignal dom n a) (Signal dom a) =>
DSignal dom n a -> Signal dom a
forall a b. Coercible a b => a -> b
coerce @_ @(Signal dom a)
  where
    go :: Integer -> Signal dom a -> Signal dom a
go 0 = Signal dom a -> Signal dom a
forall a. a -> a
id
    go i :: Integer
i = a -> Signal dom a -> Signal dom a
forall (dom :: Domain) a.
(NFDataX a, HiddenClock dom, HiddenEnable dom) =>
a -> Signal dom a -> Signal dom a
delay a
dflt (Signal dom a -> Signal dom a)
-> (Signal dom a -> Signal dom a) -> Signal dom a -> Signal dom a
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Integer -> Signal dom a -> Signal dom a
go (Integer
iInteger -> Integer -> Integer
forall a. Num a => a -> a -> a
-1)

-- | Delay a 'DSignal' for @d@ cycles, where @d@ is derived from the context.
-- The value at time 0..d-1 is a default value.
--
-- @
-- delayI2
--   :: HiddenClockResetEnable dom
--   => Int
--   -> 'DSignal' dom n Int
--   -> 'DSignal' dom (n + 2) Int
-- delayI2 = 'delayI'
-- @
--
-- >>> sampleN @System 6 (toSignal (delayI2 (-1) (dfromList [1..])))
-- [-1,-1,1,2,3,4]
--
-- You can also use type application to do the same:
-- >>> sampleN @System 6 (toSignal (delayI @2 (-1) (dfromList [1..])))
-- [-1,-1,1,2,3,4]
delayI
  :: forall d n a dom
   . ( HiddenClockResetEnable dom
     , NFDataX a
     , KnownNat d )
  => a
  -- ^ Initial value
  -> DSignal dom n a
  -> DSignal dom (n+d) a
delayI :: a -> DSignal dom n a -> DSignal dom (n + d) a
delayI dflt :: a
dflt = SNat d -> a -> DSignal dom n a -> DSignal dom (n + d) a
forall (dom :: Domain) a (d :: Nat) (n :: Nat).
(HiddenClockResetEnable dom, NFDataX a) =>
SNat d -> a -> DSignal dom n a -> DSignal dom (n + d) a
delayN (SNat d
forall (n :: Nat). KnownNat n => SNat n
SNat :: SNat d) a
dflt

data DelayedFold (dom :: Domain) (n :: Nat) (delay :: Nat) (a :: Type) (f :: TyFun Nat Type) :: Type
type instance Apply (DelayedFold dom n delay a) k = DSignal dom (n + (delay*k)) a

-- | Tree fold over a 'Vec' of 'DSignal's with a combinatorial function,
-- and delaying @delay@ cycles after each application.
-- Values at times 0..(delay*k)-1 are set to a default.
--
-- @
-- countingSignals :: Vec 4 (DSignal dom 0 Int)
-- countingSignals = repeat (dfromList [0..])
-- @
--
-- >>> printX $ sampleN @System 6 (toSignal (delayedFold d1 (-1) (+) countingSignals))
-- [-1,-2,0,4,8,12]
--
-- >>> printX $ sampleN @System 8 (toSignal (delayedFold d2 (-1) (*) countingSignals))
-- [-1,-1,1,1,0,1,16,81]
delayedFold
  :: forall dom  n delay k a
   . ( HiddenClockResetEnable dom
     , NFDataX a
     , KnownNat delay
     , KnownNat k )
  => SNat delay
  -- ^ Delay applied after each step
  -> a
  -- ^ Initial value
  -> (a -> a -> a)
  -- ^ Fold operation to apply
  -> Vec (2^k) (DSignal dom n a)
  -- ^ Vector input of size 2^k
  -> DSignal dom (n + (delay * k)) a
  -- ^ Output Signal delayed by (delay * k)
delayedFold :: SNat delay
-> a
-> (a -> a -> a)
-> Vec (2 ^ k) (DSignal dom n a)
-> DSignal dom (n + (delay * k)) a
delayedFold _ dflt :: a
dflt op :: a -> a -> a
op = Proxy (DelayedFold dom n delay a)
-> (DSignal dom n a -> DelayedFold dom n delay a @@ 0)
-> (forall (l :: Nat).
    SNat l
    -> (DelayedFold dom n delay a @@ l)
    -> (DelayedFold dom n delay a @@ l)
    -> DelayedFold dom n delay a @@ (l + 1))
-> Vec (2 ^ k) (DSignal dom n a)
-> DelayedFold dom n delay a @@ k
forall (p :: TyFun Nat Type -> Type) (k :: Nat) a.
KnownNat k =>
Proxy p
-> (a -> p @@ 0)
-> (forall (l :: Nat).
    SNat l -> (p @@ l) -> (p @@ l) -> p @@ (l + 1))
-> Vec (2 ^ k) a
-> p @@ k
dtfold (Proxy (DelayedFold dom n delay a)
forall k (t :: k). Proxy t
Proxy :: Proxy (DelayedFold dom n delay a)) DSignal dom n a -> DelayedFold dom n delay a @@ 0
forall a. a -> a
id forall (l :: Nat).
SNat l
-> (DelayedFold dom n delay a @@ l)
-> (DelayedFold dom n delay a @@ l)
-> DelayedFold dom n delay a @@ (l + 1)
go
  where
    go :: SNat l
       -> DelayedFold dom n delay a @@ l
       -> DelayedFold dom n delay a @@ l
       -> DelayedFold dom n delay a @@ (l+1)
    go :: SNat l
-> (DelayedFold dom n delay a @@ l)
-> (DelayedFold dom n delay a @@ l)
-> DelayedFold dom n delay a @@ (l + 1)
go SNat x :: DelayedFold dom n delay a @@ l
x y :: DelayedFold dom n delay a @@ l
y = a
-> DSignal dom (n + (delay * l)) a
-> DSignal dom ((n + (delay * l)) + delay) a
forall (d :: Nat) (n :: Nat) a (dom :: Domain).
(HiddenClockResetEnable dom, NFDataX a, KnownNat d) =>
a -> DSignal dom n a -> DSignal dom (n + d) a
delayI a
dflt (a -> a -> a
op (a -> a -> a)
-> DSignal dom (n + (delay * l)) a
-> DSignal dom (n + (delay * l)) (a -> a)
forall (f :: Type -> Type) a b. Functor f => (a -> b) -> f a -> f b
<$> DelayedFold dom n delay a @@ l
DSignal dom (n + (delay * l)) a
x DSignal dom (n + (delay * l)) (a -> a)
-> DSignal dom (n + (delay * l)) a
-> DSignal dom (n + (delay * l)) a
forall (f :: Type -> Type) a b.
Applicative f =>
f (a -> b) -> f a -> f b
<*> DelayedFold dom n delay a @@ l
DSignal dom (n + (delay * l)) a
y)