Idle bus typeclasses

.ci/build_docs.sh

@@ -20,29 +20,36 @@ cabal haddock \
   |& tee haddock_log
 
 set +e
-if grep -q "Missing documentation" haddock_log; then
+
+suppressed_warnings=(
+  'Consider exporting it together with its parent(s) for code clarity.'
+  )
+
+grep -v -e "${suppressed_warnings[@]}" haddock_log |& tee haddock_filtered
+
+if grep -q "Missing documentation" haddock_filtered; then
   echo -e "\e[1m\e[31mMissing documentation! Scroll up for full log.\e[0m"
-  grep --color=always -n -C 5 "Missing documentation" haddock_log
+  grep --color=always -n -C 5 "Missing documentation" haddock_filtered
   exit 1
 fi
 
-if grep -q "If you qualify the identifier, haddock can try to link it anyway" haddock_log; then
+if grep -q "If you qualify the identifier, haddock can try to link it anyway" haddock_filtered; then
   echo -e "\e[1m\e[31mIdentifier out of scope! Scroll up for full log.\e[0m"
-  grep --color=always -n -C 5 "If you qualify the identifier, haddock can try to link it anyway" haddock_log
+  grep --color=always -n -C 5 "If you qualify the identifier, haddock can try to link it anyway" haddock_filtered
   exit 1
 fi
 
-if grep -q "could not find link destinations for" haddock_log; then
+if grep -q "could not find link destinations for" haddock_filtered; then
   echo -e "\e[1m\e[31mAn identifier could not be linked! Scroll up for full log.\e[0m"
-  grep --color=always -n -C 5 "could not find link destinations for" haddock_log
+  grep --color=always -n -C 5 "could not find link destinations for" haddock_filtered
   exit 1
 fi
 
-if grep -E -q "^Warning:" haddock_log; then
+if grep -E -q "^Warning:" haddock_filtered; then
   echo -e "\e[1m\e[31mAn unknown warning occured. Scroll up for full log.\e[0m"
-  grep --color=always -n -C 5 -E "^Warning:" haddock_log
+  grep --color=always -n -C 5 -E "^Warning:" haddock_filtered
   exit 1
 fi
 
 # Copy documention to docs/
-ln -s "$(dirname "$(tail -n1 haddock_log)")" docs
+ln -s "$(dirname "$(tail -n1 haddock_filtered)")" docs

clash-protocols.cabal

@@ -155,38 +155,32 @@ library
 
   exposed-modules:
     Protocols
-
+    Protocols.Avalon.MemMap
+    Protocols.Avalon.Stream
     Protocols.Axi4.Common
-
     Protocols.Axi4.ReadAddress
     Protocols.Axi4.ReadData
+    Protocols.Axi4.Stream
     Protocols.Axi4.WriteAddress
     Protocols.Axi4.WriteData
     Protocols.Axi4.WriteResponse
-    Protocols.Axi4.Stream
-
-    Protocols.Avalon.Stream
-
-    Protocols.Avalon.MemMap
-
-    Protocols.Wishbone
-    Protocols.Wishbone.Standard
-    Protocols.Wishbone.Standard.Hedgehog
-
     Protocols.Cpp
     Protocols.Df
     Protocols.DfConv
     Protocols.Hedgehog
     Protocols.Hedgehog.Internal
+    Protocols.Idle
     Protocols.Internal
     Protocols.Internal.TaggedBundle
     Protocols.Internal.TaggedBundle.TH
     Protocols.Internal.TH
     Protocols.Internal.Units
     Protocols.Internal.Units.TH
-
     Protocols.Plugin
     Protocols.Plugin.Internal
+    Protocols.Wishbone
+    Protocols.Wishbone.Standard
+    Protocols.Wishbone.Standard.Hedgehog
 
     -- 'testProperty' is broken upstream, it reports wrong test names
     -- TODO: test / upstream ^
@@ -197,6 +191,7 @@ library
   other-modules:
     Data.Bifunctor.Extra
     Paths_clash_protocols
+    Protocols.Internal.Classes
 
   default-language: Haskell2010
 

src/Protocols/Avalon/MemMap.hs

@@ -102,6 +102,7 @@ import           Clash.Prelude hiding (take, concat, length)
 import qualified Clash.Prelude as C
 
 -- me
+import           Protocols.Idle
 import           Protocols.Internal
 import qualified Protocols.DfConv as DfConv
 
@@ -1261,3 +1262,13 @@ instance
 --
 -- Tests can still be made for Avalon MM circuits, using 'DfConv.dfConvTestBench'.
 -- See 'Tests.Protocols.AvalonMemMap' for examples.
+
+instance (KnownManagerConfig config) =>
+  IdleCircuit (AvalonMmManager dom config) where
+    idleFwd _ = pure mmManagerOutNoData
+    idleBwd _ = pure $ boolToMmManagerAck False
+
+instance (KnownSubordinateConfig config) =>
+  IdleCircuit (AvalonMmSubordinate dom fixedWaitTime config) where
+    idleFwd _ = pure mmSubordinateInNoData
+    idleBwd _ = pure $ boolToMmSubordinateAck False

src/Protocols/Avalon/Stream.hs

@@ -26,10 +26,11 @@ import           Clash.Prelude hiding (take, concat, length)
 import qualified Clash.Prelude as C
 
 -- me
+import           Protocols.Hedgehog.Internal
+import           Protocols.Idle
 import           Protocols.Internal
 import qualified Protocols.Df as Df
 import qualified Protocols.DfConv as DfConv
-import           Protocols.Hedgehog.Internal
 
 
 instance Hashable (C.Unsigned n)
@@ -231,3 +232,8 @@ instance
   expectN Proxy options nExpected sampled
     = expectN (Proxy @(Df.Df dom _)) options nExpected
     $ Df.maybeToData <$> sampled
+
+instance IdleCircuit (AvalonStream dom conf dataType) where
+  idleFwd _ = pure Nothing
+  idleBwd _ = pure AvalonStreamS2M { _ready = False }
+

src/Protocols/Axi4/ReadAddress.hs

@@ -183,7 +183,7 @@
 -- | See Table A2-5 "Read address channel signals"
 newtype S2M_ReadAddress = S2M_ReadAddress
   { _arready :: Bool }
   deriving (Show, Generic, C.NFDataX)
 
 -- | Shorthand for a "well-behaved" read address config,
 -- so that we don't need to write out a bunch of type constraints later.
@@ -364,3 +364,7 @@
   , _arqos    = _ariqos
   , _aruser   = _ariuser
   }
+
+instance IdleCircuit (Axi4ReadAddress dom conf userType) where
+  idleFwd _ = pure M2S_NoReadAddress
+  idleBwd _ = pure S2M_ReadAddress { _arready = False }

src/Protocols/Axi4/ReadData.hs

@@ -34,6 +34,7 @@
 
 -- me
 import Protocols.Axi4.Common
+import Protocols.Idle
 import Protocols.Internal
 
 -- | Configuration options for 'Axi4ReadData'.
@@ -96,7 +97,7 @@
 
 -- | See Table A2-6 "Read data channel signals"
 newtype M2S_ReadData = M2S_ReadData { _rready :: Bool }
   deriving (Show, Generic, C.NFDataX)
 
 -- | Shorthand for a "well-behaved" read data config,
 -- so that we don't need to write out a bunch of type constraints later.
@@ -121,3 +122,7 @@
   , C.NFDataX dataType
   ) =>
   C.NFDataX (S2M_ReadData conf userType dataType)
+
+instance IdleCircuit (Axi4ReadData dom conf userType dataType) where
+  idleFwd _ = C.pure S2M_NoReadData
+  idleBwd _ = C.pure $ M2S_ReadData False

src/Protocols/Axi4/Stream.hs

@@ -24,10 +24,10 @@
 import qualified Clash.Prelude as C
 
 -- me
+import           Protocols.Hedgehog.Internal
 import           Protocols.Internal
 import qualified Protocols.Df as Df
 import qualified Protocols.DfConv as DfConv
-import           Protocols.Hedgehog.Internal
 
 
 instance (KnownNat n) => Hashable (Unsigned n)
@@ -98,7 +98,7 @@
 -- Manager may not decide whether or not to send 'Nothing' based on
 -- the '_tready' signal.
 newtype Axi4StreamS2M = Axi4StreamS2M { _tready :: Bool }
   deriving (Generic, C.NFDataX, C.ShowX, Eq, NFData, Show, Bundle)
 
 -- | Type for AXI4 Stream protocol.
 data Axi4Stream (dom :: Domain) (conf :: Axi4StreamConfig) (userType :: Type)
@@ -173,3 +173,7 @@
   expectN Proxy options nExpected sampled
     = expectN (Proxy @(Df.Df dom _)) options nExpected
     $ Df.maybeToData <$> sampled
+
+instance IdleCircuit (Axi4Stream dom conf userType) where
+  idleFwd Proxy = C.pure Nothing
+  idleBwd Proxy = C.pure $ Axi4StreamS2M False

src/Protocols/Axi4/WriteAddress.hs

@@ -182,7 +182,7 @@
 
 -- | See Table A2-2 "Write address channel signals"
 newtype S2M_WriteAddress = S2M_WriteAddress { _awready :: Bool }
   deriving (Show, Generic, C.NFDataX)
 
 -- | Shorthand for a "well-behaved" write address config,
 -- so that we don't need to write out a bunch of type constraints later.
@@ -357,3 +357,7 @@
   , _awuser   = _awiuser
   , _awlen, _awburst
   }
+
+instance IdleCircuit (Axi4WriteAddress dom conf userType) where
+  idleFwd _ = C.pure M2S_NoWriteAddress
+  idleBwd _ = C.pure $ S2M_WriteAddress False

src/Protocols/Axi4/WriteData.hs

@@ -34,6 +34,7 @@
 
 -- me
 import Protocols.Axi4.Common
+import Protocols.Idle
 import Protocols.Internal
 
 -- | Configuration options for 'Axi4WriteData'.
@@ -90,7 +91,7 @@
 
 -- | See Table A2-3 "Write data channel signals"
 newtype S2M_WriteData = S2M_WriteData { _wready :: Bool }
   deriving (Show, Generic, C.NFDataX)
 
 -- | Shorthand for a "well-behaved" write data config,
 -- so that we don't need to write out a bunch of type constraints later.
@@ -113,3 +114,7 @@
   , C.NFDataX userType
   ) =>
   C.NFDataX (M2S_WriteData conf userType)
+
+instance IdleCircuit (Axi4WriteData dom conf userType) where
+  idleFwd _ = C.pure M2S_NoWriteData
+  idleBwd _ = C.pure S2M_WriteData{ _wready = False }

src/Protocols/Axi4/WriteResponse.hs

@@ -32,6 +32,7 @@
 
 -- me
 import Protocols.Axi4.Common
+import Protocols.Idle
 import Protocols.Internal
 
 -- | Configuration options for 'Axi4WriteResponse'.
@@ -86,7 +87,7 @@
 
 -- | See Table A2-4 "Write response channel signals"
 newtype M2S_WriteResponse = M2S_WriteResponse { _bready :: Bool }
   deriving (Show, Generic, C.NFDataX)
 
 -- | Shorthand for a "well-behaved" write response config,
 -- so that we don't need to write out a bunch of type constraints later.
@@ -109,3 +110,7 @@
   , C.NFDataX userType
   ) =>
   C.NFDataX (S2M_WriteResponse conf userType)
+
+instance IdleCircuit (Axi4WriteResponse dom conf userType) where
+  idleFwd _ = pure S2M_NoWriteResponse
+  idleBwd _ = pure $ M2S_WriteResponse False

src/Protocols/Df.hs

@@ -14,6 +14,7 @@ carries data, no metadata. For documentation see:
 {-# LANGUAGE NamedFieldPuns #-}
 
 {-# OPTIONS_GHC -fno-warn-orphans #-}
+{-# OPTIONS_GHC -Wno-unrecognised-pragmas #-}
 
 -- TODO: Fix warnings introduced by GHC 9.2 w.r.t. incomplete lazy pattern matches
 {-# OPTIONS_GHC -Wno-incomplete-uni-patterns #-}
@@ -98,6 +99,8 @@ import qualified Clash.Explicit.Prelude as CE
 -- me
 import           Protocols.Internal
 
+{-# ANN module "HLint: ignore Use const" #-}
+
 -- $setup
 -- >>> import Protocols
 -- >>> import Clash.Prelude (Vec(..))
@@ -148,6 +151,10 @@ instance Monad Data where
   NoData >>= _f = NoData
   Data a >>=  f = f a
 
+instance IdleCircuit (Df dom a) where
+  idleFwd _ = C.pure NoData
+  idleBwd _ = C.pure (Ack False)
+
 -- | Convert 'Data' to 'Maybe'. Produces 'Just' on 'Data', 'Nothing' on 'NoData'.
 dataToMaybe :: Data a -> Maybe a
 dataToMaybe NoData = Nothing

src/Protocols/Idle.hs

@@ -0,0 +1,30 @@
+{-# OPTIONS_GHC "-Wno-orphans" #-}
+
+{-|
+Functionalities to easily create idle circuits for protocols.
+-}
+module Protocols.Idle
+  ( IdleCircuit(..)
+  , idleSource
+  , idleSink
+  ) where
+
+import Data.Proxy
+import Protocols.Cpp (maxTupleSize)
+import Protocols.Internal
+import Protocols.Internal.TH (idleCircuitTupleInstances)
+
+instance (IdleCircuit a, IdleCircuit b) => IdleCircuit (a, b) where
+  idleFwd _ = (idleFwd $ Proxy @a, idleFwd $ Proxy @b)
+  idleBwd _ = (idleBwd $ Proxy @a, idleBwd $ Proxy @b)
+
+-- Derive instances for tuples up to maxTupleSize
+idleCircuitTupleInstances 3 maxTupleSize
+
+-- | Idle state of a source, this circuit does not produce any data.
+idleSource :: forall p. (IdleCircuit p) => Circuit () p
+idleSource = Circuit $ const ((), idleFwd $ Proxy @p)
+
+-- | Idle state of a sink, this circuit does not consume any data.
+idleSink :: forall p. (IdleCircuit p) => Circuit p ()
+idleSink = Circuit $ const (idleBwd $ Proxy @p, ())