Move all plugin related modules to Protocols.Plugin

The separation between plugin related code and protocol related code
should be obvious from the module hierarchy

.github/workflows/ci.yml

@@ -118,7 +118,7 @@ jobs:
           version: "0.14.0.0"
           pattern: |
             **/*.hs
-            !clash-protocols-base/src/Protocols/Cpp.hs
+            !clash-protocols-base/src/Protocols/Plugin/Cpp.hs
 
   linting:
     name: Source code linting

clash-protocols-base/clash-protocols-base.cabal

@@ -111,15 +111,16 @@ library
     , template-haskell
 
   exposed-modules:
-    Protocols.Circuit
-    Protocols.Cpp
-    Protocols.Internal.TaggedBundle
-    Protocols.Internal.TaggedBundle.TH
-    Protocols.Internal.Types
-    Protocols.Internal.Units
-    Protocols.Internal.Units.TH
     Protocols.Plugin
+    Protocols.Plugin.Cpp
     Protocols.Plugin.Internal
-    Protocols.Protocol.TH
+    Protocols.Plugin.TaggedBundle
+    Protocols.Plugin.TaggedBundle.TH
+    Protocols.Plugin.TH
+    Protocols.Plugin.Units
+    Protocols.Plugin.Units.TH
+
+  other-modules:
+    Protocols.Plugin.Types
 
   default-language: Haskell2010

clash-protocols-base/src/Protocols/Plugin.hs

@@ -5,6 +5,9 @@ A GHC source plugin providing a DSL for writing Circuit components. Credits to
 @circuit-notation@ at <https://github.com/cchalmers/circuit-notation>.
 -}
 module Protocols.Plugin (
+  Circuit (..),
+  Protocol (..),
+  CSignal,
   plugin,
   circuit,
   (-<),
@@ -13,11 +16,16 @@ module Protocols.Plugin (
 -- base
 import Prelude
 
+-- clash-prelude
+import qualified Clash.Explicit.Prelude as C
+
 -- clash-protocols
-import Protocols.Internal.Types
-import Protocols.Internal.TaggedBundle
-import Protocols.Internal.Units
+import Protocols.Plugin.Cpp
 import Protocols.Plugin.Internal
+import Protocols.Plugin.TH
+import Protocols.Plugin.TaggedBundle
+import Protocols.Plugin.Types
+import Protocols.Plugin.Units
 
 -- circuit-notation
 import qualified CircuitNotation as CN
@@ -28,6 +36,31 @@ import Data.Tagged
 -- ghc
 import qualified GHC.Plugins as GHC
 
+instance Protocol () where
+  type Fwd () = ()
+  type Bwd () = ()
+
+{- | __NB__: The documentation only shows instances up to /3/-tuples. By
+default, instances up to and including /12/-tuples will exist. If the flag
+@large-tuples@ is set instances up to the GHC imposed limit will exist. The
+GHC imposed limit is either 62 or 64 depending on the GHC version.
+-}
+instance Protocol (a, b) where
+  type Fwd (a, b) = (Fwd a, Fwd b)
+  type Bwd (a, b) = (Bwd a, Bwd b)
+
+-- Generate n-tuple instances, where n > 2
+protocolTupleInstances 3 maxTupleSize
+
+instance (C.KnownNat n) => Protocol (C.Vec n a) where
+  type Fwd (C.Vec n a) = C.Vec n (Fwd a)
+  type Bwd (C.Vec n a) = C.Vec n (Bwd a)
+
+-- XXX: Type families with Signals on LHS are currently broken on Clash:
+instance Protocol (CSignal dom a) where
+  type Fwd (CSignal dom a) = C.Signal dom a
+  type Bwd (CSignal dom a) = C.Signal dom ()
+
 -- | @circuit-notation@ plugin repurposed for "Protocols".
 plugin :: GHC.Plugin
 plugin =

clash-protocols-base/src/Protocols/Cpp.hs → clash-protocols-base/src/Protocols/Plugin/Cpp.hs

@@ -12,7 +12,7 @@ Compile-time dependent constants. Inspired by @clash-prelude@'s @Clash.CPP@.
 
 {-# OPTIONS_HADDOCK hide #-}
 
-module Protocols.Cpp
+module Protocols.Plugin.Cpp
  ( maxTupleSize
  , haddockOnly
  ) where

clash-protocols-base/src/Protocols/Plugin/Internal.hs

@@ -8,7 +8,7 @@ import Clash.Explicit.Prelude
 
 import Data.Tagged
 import GHC.Base (Any)
-import Protocols.Internal.Types
+import Protocols.Plugin.Types
 
 {- | Picked up by "Protocols.Plugin" to process protocol DSL. See
 "Protocols.Plugin" for more information.

clash-protocols-base/src/Protocols/Protocol/TH.hs → clash-protocols-base/src/Protocols/Plugin/TH.hs

@@ -1,6 +1,7 @@
 {-# OPTIONS_HADDOCK hide #-}
 
-module Protocols.Protocol.TH where
+module Protocols.Plugin.TH where
+
 import Language.Haskell.TH
 
 appTs :: Q Type -> [Q Type] -> Q Type

clash-protocols-base/src/Protocols/Internal/TaggedBundle.hs → clash-protocols-base/src/Protocols/Plugin/TaggedBundle.hs

@@ -6,12 +6,12 @@
 -- For debugging TH:
 -- {-# OPTIONS_GHC -ddump-splices #-}
 
-module Protocols.Internal.TaggedBundle where
+module Protocols.Plugin.TaggedBundle where
 
 import Clash.Explicit.Prelude
 
-import Protocols.Cpp (maxTupleSize)
-import Protocols.Internal.TaggedBundle.TH (taggedBundleTupleInstances)
+import Protocols.Plugin.Cpp (maxTupleSize)
+import Protocols.Plugin.TaggedBundle.TH (taggedBundleTupleInstances)
 
 import Data.Tagged
 

clash-protocols-base/src/Protocols/Internal/TaggedBundle/TH.hs → clash-protocols-base/src/Protocols/Plugin/TaggedBundle/TH.hs

@@ -1,6 +1,6 @@
 {-# OPTIONS_HADDOCK hide #-}
 
-module Protocols.Internal.TaggedBundle.TH where
+module Protocols.Plugin.TaggedBundle.TH where
 
 import Data.Tagged
 import Language.Haskell.TH

clash-protocols-base/src/Protocols/Internal/Types.hs → clash-protocols-base/src/Protocols/Plugin/Types.hs

@@ -1,16 +1,16 @@
+{-# LANGUAGE RoleAnnotations #-}
+
 {- |
 These class definitions are needed to be able to write Template Haskell quotes
 for instances. They are defined separately to avoid import loops.
 
 This module is not exported; the classes and their (orphan) instances are
 exported elsewhere.
 -}
-{-# LANGUAGE RoleAnnotations #-}
-module Protocols.Internal.Types where
+module Protocols.Plugin.Types where
 
 import Clash.Signal
 import Data.Kind (Type)
-import Data.Proxy
 
 -- | A protocol describes the in- and outputs of one side of a 'Circuit'.
 class Protocol a where
@@ -135,13 +135,6 @@ types:
 newtype Circuit a b
   = Circuit ((Fwd a, Bwd b) -> (Bwd a, Fwd b))
 
-{- | Idle state of a Circuit. Aims to provide no data for both the forward and
-backward direction. Transactions are not acknowledged.
--}
-class (Protocol p) => IdleCircuit p where
-  idleFwd :: Proxy p -> Fwd (p :: Type)
-  idleBwd :: Proxy p -> Bwd (p :: Type)
-
 {- | Circuit protocol with /Signal dom a/ in its forward direction, and
 /()/ in its backward direction. Convenient for exposing protocol
 internals, or simply for undirectional streams.
@@ -151,30 +144,3 @@ Note: 'CSignal' exists to work around [issue 760](https://github.com/clash-lang/
 data CSignal (dom :: Domain) (a :: Type)
 
 type role CSignal nominal representational
-
-{- | Force a /nack/ on the backward channel and /no data/ on the forward
-channel if reset is asserted.
--}
-forceResetSanityGeneric ::
-  forall dom a fwd bwd.
-  ( KnownDomain dom
-  , HiddenReset dom
-  , IdleCircuit a
-  , Fwd a ~ Signal dom fwd
-  , Bwd a ~ Signal dom bwd
-  ) =>
-  Circuit a a
-forceResetSanityGeneric = Circuit go
- where
-  go (fwd, bwd) =
-    unbundle $
-      mux
-        rstAsserted
-        (bundle (idleBwd $ Proxy @a, idleFwd $ Proxy @a))
-        (bundle (bwd, fwd))
-
-#if MIN_VERSION_clash_prelude(1,8,0)
-  rstAsserted = unsafeToActiveHigh hasReset
-#else
-  rstAsserted = unsafeToHighPolarity hasReset
-#endif

clash-protocols-base/src/Protocols/Internal/Units.hs → clash-protocols-base/src/Protocols/Plugin/Units.hs

@@ -5,12 +5,12 @@
 -- For debugging TH:
 -- {-# OPTIONS_GHC -ddump-splices #-}
 
-module Protocols.Internal.Units where
+module Protocols.Plugin.Units where
 
 import Clash.Explicit.Prelude
 
-import Protocols.Cpp (maxTupleSize)
-import Protocols.Internal.Units.TH (unitsTupleInstances)
+import Protocols.Plugin.Cpp (maxTupleSize)
+import Protocols.Plugin.Units.TH (unitsTupleInstances)
 
 {- | Utilities for zero-width types. Is used by "Protocols.Plugin" to drive \"trivial\"
 backwards channels.

clash-protocols-base/src/Protocols/Internal/Units/TH.hs → clash-protocols-base/src/Protocols/Plugin/Units/TH.hs

@@ -1,6 +1,6 @@
 {-# OPTIONS_HADDOCK hide #-}
 
-module Protocols.Internal.Units.TH (unitsTupleInstances) where
+module Protocols.Plugin.Units.TH (unitsTupleInstances) where
 
 import Language.Haskell.TH
 

clash-protocols/clash-protocols.cabal

@@ -165,6 +165,7 @@ library
   autogen-modules:    Paths_clash_protocols
 
   other-modules:
+    Protocols.Internal.Types
     Paths_clash_protocols
 
   default-language: Haskell2010

clash-protocols/src/Protocols.hs

@@ -59,12 +59,10 @@ module Protocols (
   -- * Circuit notation plugin
   circuit,
   (-<),
-  module Protocols.Internal.Units,
-  module Protocols.Internal.TaggedBundle,
+  Units (..),
+  TaggedBundle (..),
 ) where
 
 import Data.Default (def)
 import Protocols.Df (Df)
 import Protocols.Internal
-import Protocols.Internal.TaggedBundle
-import Protocols.Internal.Units

clash-protocols/src/Protocols/Axi4/ReadAddress.hs

@@ -49,6 +49,7 @@ import qualified Clash.Prelude as C
 
 -- me
 import Protocols.Axi4.Common
+import Protocols.Idle
 import Protocols.Internal
 
 -- | Configuration options for 'Axi4ReadAddress'.

clash-protocols/src/Protocols/Axi4/Stream.hs

@@ -27,6 +27,7 @@ import qualified Clash.Prelude as C
 import qualified Protocols.Df as Df
 import qualified Protocols.DfConv as DfConv
 import Protocols.Hedgehog.Internal
+import Protocols.Idle
 import Protocols.Internal
 
 instance (KnownNat n) => Hashable (Unsigned n)

clash-protocols/src/Protocols/Axi4/WriteAddress.hs

@@ -47,6 +47,7 @@ import qualified Clash.Prelude as C
 
 -- me
 import Protocols.Axi4.Common
+import Protocols.Idle
 import Protocols.Internal
 
 -- | Configuration options for 'Axi4WriteAddress'.

clash-protocols/src/Protocols/Df.hs

@@ -129,6 +129,7 @@ import qualified Clash.Prelude as C
 import Clash.Signal.Internal (Signal (..))
 
 -- me
+import Protocols.Idle
 import Protocols.Internal
 
 {-# ANN module "HLint: ignore Use const" #-}

clash-protocols/src/Protocols/Idle.hs

@@ -4,24 +4,30 @@
 Functionalities to easily create idle circuits for protocols.
 -}
 module Protocols.Idle (
+  -- * Type classes
   IdleCircuit (..),
+
+  -- * Utility functions
   idleSource,
   idleSink,
+  forceResetSanityGeneric,
 ) where
 
-import qualified Clash.Prelude as C
+import Clash.Prelude
+import Prelude ()
+
 import Data.Proxy
-import Protocols.Cpp (maxTupleSize)
 import Protocols.Internal
 import Protocols.Internal.TH (idleCircuitTupleInstances)
+import Protocols.Plugin.Cpp (maxTupleSize)
 
 instance (IdleCircuit a, IdleCircuit b) => IdleCircuit (a, b) where
   idleFwd _ = (idleFwd $ Proxy @a, idleFwd $ Proxy @b)
   idleBwd _ = (idleBwd $ Proxy @a, idleBwd $ Proxy @b)
 
-instance (IdleCircuit a, C.KnownNat n) => IdleCircuit (C.Vec n a) where
-  idleFwd _ = C.repeat $ idleFwd $ Proxy @a
-  idleBwd _ = C.repeat $ idleBwd $ Proxy @a
+instance (IdleCircuit a, KnownNat n) => IdleCircuit (Vec n a) where
+  idleFwd _ = repeat $ idleFwd $ Proxy @a
+  idleBwd _ = repeat $ idleBwd $ Proxy @a
 
 instance IdleCircuit () where
   idleFwd _ = ()
@@ -37,3 +43,30 @@ 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, ())
+
+{- | Force a /nack/ on the backward channel and /no data/ on the forward
+channel if reset is asserted.
+-}
+forceResetSanityGeneric ::
+  forall dom a fwd bwd.
+  ( KnownDomain dom
+  , HiddenReset dom
+  , IdleCircuit a
+  , Fwd a ~ Signal dom fwd
+  , Bwd a ~ Signal dom bwd
+  ) =>
+  Circuit a a
+forceResetSanityGeneric = Circuit go
+ where
+  go (fwd, bwd) =
+    unbundle
+      $ mux
+        rstAsserted
+        (bundle (idleBwd $ Proxy @a, idleFwd $ Proxy @a))
+        (bundle (bwd, fwd))
+
+#if MIN_VERSION_clash_prelude(1,8,0)
+  rstAsserted = unsafeToActiveHigh hasReset
+#else
+  rstAsserted = unsafeToHighPolarity hasReset
+#endif