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.Units
+
+  other-modules:
+    Protocols.Plugin.TH
+    Protocols.Plugin.Units.TH
+    Protocols.Plugin.TaggedBundle.TH
+    Protocols.Plugin.Types
 
   default-language: Haskell2010

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

@@ -1,11 +1,15 @@
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE PatternSynonyms #-}
+{-# OPTIONS_GHC -fno-warn-orphans #-}
 
 {- |
 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,
   (-<),
@@ -14,11 +18,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
@@ -29,6 +38,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,13 @@ module Protocols (
   -- * Circuit notation plugin
   circuit,
   (-<),
-  module Protocols.Internal.Units,
-  module Protocols.Internal.TaggedBundle,
+  module Protocols.Plugin.Units,
+  module Protocols.Plugin.TaggedBundle,
 ) where
 
 import Data.Default (def)
 import Protocols.Df (Df)
 import Protocols.Internal
-import Protocols.Internal.TaggedBundle
-import Protocols.Internal.Units
+import Protocols.Plugin
+import Protocols.Plugin.TaggedBundle
+import Protocols.Plugin.Units

clash-protocols/src/Protocols/Avalon/MemMap.hs

@@ -106,6 +106,7 @@ import qualified Clash.Prelude as C
 import qualified Protocols.DfConv as DfConv
 import Protocols.Idle
 import Protocols.Internal
+import Protocols.Plugin
 
 {- | Config needed for both manager and subordinate interfaces.
 @Bool@ values represent whether to keep a boolean field or not.

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

@@ -32,6 +32,7 @@ import qualified Protocols.DfConv as DfConv
 import Protocols.Hedgehog.Internal
 import Protocols.Idle
 import Protocols.Internal
+import Protocols.Plugin
 
 instance Hashable (C.Unsigned n)
 

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

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

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

@@ -48,6 +48,7 @@ import qualified Clash.Prelude as C
 import Protocols.Axi4.Common
 import Protocols.Idle
 import Protocols.Internal
+import Protocols.Plugin
 
 -- | Configuration options for 'Axi4ReadData'.
 data Axi4ReadDataConfig = Axi4ReadDataConfig

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

@@ -27,7 +27,9 @@ 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
+import Protocols.Plugin
 
 instance (KnownNat n) => Hashable (Unsigned n)
 instance (KnownNat n, Hashable a) => Hashable (Vec n a) where

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

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

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

@@ -45,6 +45,7 @@ import qualified Clash.Prelude as C
 import Protocols.Axi4.Common
 import Protocols.Idle
 import Protocols.Internal
+import Protocols.Plugin
 
 -- | Configuration options for 'Axi4WriteData'.
 data Axi4WriteDataConfig = Axi4WriteDataConfig

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

@@ -33,6 +33,7 @@ import qualified Clash.Prelude as C
 import Protocols.Axi4.Common
 import Protocols.Idle
 import Protocols.Internal
+import Protocols.Plugin
 
 -- | Configuration options for 'Axi4WriteResponse'.
 data Axi4WriteResponseConfig = Axi4WriteResponseConfig

clash-protocols/src/Protocols/Df.hs

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

clash-protocols/src/Protocols/DfConv.hs

@@ -115,6 +115,7 @@ import Protocols.Axi4.WriteResponse
 import Protocols.Df (Data (..), Df)
 import qualified Protocols.Df as Df
 import Protocols.Internal
+import Protocols.Plugin
 
 {- | Class for protocols that are "similar" to 'Df', i.e. they can be converted
 to and from a pair of 'Df' ports (one going 'Fwd', one going 'Bwd'), using