Add Ethernet core

cabal.project-common

@@ -32,3 +32,17 @@ package recursion-schemes
 -- with -O2 provides gains around 5% to 10% in simple benchmarks
 package regex-tdfa
     optimization: 2
+
+source-repository-package
+  type: git
+  location: https://github.com/cchalmers/circuit-notation.git
+  tag: 564769c52aa05b90f81bbc898b7af7087d96613d
+
+source-repository-package
+  type: git
+  location: https://github.com/clash-lang/clash-protocols.git
+  tag: 15b4f4fe560f217609a387f4256927046099715c
+  subdir: clash-protocols-base clash-protocols
+
+allow-newer:
+  clash-protocols:tasty

clash-cores.cabal

@@ -106,8 +106,10 @@ common basic-config
 
   build-depends:
     base                      >= 4.18  && < 5,
+    clash-protocols,
     constraints               >= 0.9   && < 1.0,
     containers                >=0.5    && <0.8,
+    deepseq,
     ghc-typelits-extra        >= 0.3.2,
     ghc-typelits-knownnat     >= 0.6,
     ghc-typelits-natnormalise >= 0.6,
@@ -174,6 +176,27 @@ library
 
   if !flag(clash-18)
     exposed-modules:
+      Clash.Cores.Ethernet.Arp
+      Clash.Cores.Ethernet.Arp.ArpManager
+      Clash.Cores.Ethernet.Arp.ArpTable
+      Clash.Cores.Ethernet.Arp.ArpTypes
+      Clash.Cores.Ethernet.Examples.FullUdpStack
+      Clash.Cores.Ethernet.Examples.RxStacks
+      Clash.Cores.Ethernet.Examples.TxStacks
+      Clash.Cores.Ethernet.Icmp
+      Clash.Cores.Ethernet.InternetChecksum
+      Clash.Cores.Ethernet.IPv4
+      Clash.Cores.Ethernet.IP.EthernetStream
+      Clash.Cores.Ethernet.IP.IPPacketizers
+      Clash.Cores.Ethernet.IP.IPv4Types
+      Clash.Cores.Ethernet.Mac
+      Clash.Cores.Ethernet.Mac.EthernetTypes
+      Clash.Cores.Ethernet.Mac.FrameCheckSequence
+      Clash.Cores.Ethernet.Mac.InterpacketGapInserter
+      Clash.Cores.Ethernet.Mac.MacPacketizers
+      Clash.Cores.Ethernet.Mac.PaddingInserter
+      Clash.Cores.Ethernet.Mac.Preamble
+      Clash.Cores.Ethernet.Udp
       Clash.Cores.Sgmii
       Clash.Cores.Sgmii.AutoNeg
       Clash.Cores.Sgmii.BitSlip
@@ -186,8 +209,14 @@ library
       Clash.Cores.Sgmii.Sync
 
   other-modules:
+    Clash.Sized.Vector.Extra
+    Data.Maybe.Extra
     Data.Text.Extra
 
+  if !flag(clash-18)
+    other-modules:
+      Clash.Signal.Extra
+
   ghc-options:
     -fexpose-all-unfoldings
     -fno-worker-wrapper
@@ -225,6 +254,17 @@ test-suite unit-tests
 
   if !flag(clash-18)
     other-modules:
+      Test.Cores.Ethernet
+      Test.Cores.Ethernet.Arp.ArpManager
+      Test.Cores.Ethernet.Base
+      Test.Cores.Ethernet.InternetChecksum
+      Test.Cores.Ethernet.Icmp
+      Test.Cores.Ethernet.IP.EthernetStream
+      Test.Cores.Ethernet.IP.IPPacketizers
+      Test.Cores.Ethernet.Mac.FrameCheckSequence
+      Test.Cores.Ethernet.Mac.InterpacketGapInserter
+      Test.Cores.Ethernet.Mac.PaddingInserter
+      Test.Cores.Ethernet.Mac.Preamble
       Test.Cores.Sgmii.AutoNeg
       Test.Cores.Sgmii.BitSlip
       Test.Cores.Sgmii.RateAdapt
@@ -234,7 +274,6 @@ test-suite unit-tests
   build-depends:
     clash-cores,
     clash-prelude-hedgehog,
-    deepseq,
     hedgehog,
     tasty                   >= 1.2 && < 1.6,
     tasty-hedgehog          >= 1.2.0,

fourmolu.yaml

@@ -0,0 +1,2 @@
+indentation: 2
+column-limit: 90

nix/nixpkgs.nix

@@ -42,6 +42,11 @@ let
           self.callCabal2nix "doctest-parallel" sources.doctest-parallel {};
         clash-prelude =
           self.callCabal2nix "clash-prelude" (sources.clash-compiler + "/clash-prelude") {};
+        # clash-protocols also requires tasty < 1.5, so we need to jailbreak.
+        clash-protocols-base =
+          pkgs.haskell.lib.doJailbreak (self.callCabal2nix "clash-protocols-base" (sources.clash-protocols + "/clash-protocols-base") {});
+        clash-protocols =
+          pkgs.haskell.lib.doJailbreak (self.callCabal2nix "clash-protocols" (sources.clash-protocols + "/clash-protocols") {});
         clash-lib =
           self.callCabal2nix "clash-lib" (sources.clash-compiler + "/clash-lib") {};
         clash-ghc =

nix/sources.json

@@ -1,4 +1,16 @@
 {
+    "circuit-notation": {
+        "branch": "master",
+        "description": "A plugin for circuit notation",
+        "homepage": null,
+        "owner": "cchalmers",
+        "repo": "circuit-notation",
+        "rev": "564769c52aa05b90f81bbc898b7af7087d96613d",
+        "sha256": "117kry20wxgxlpvrs050v96xvai8mq81vsrm6d8sbilc7d3cpxxh",
+        "type": "tarball",
+        "url": "https://github.com/cchalmers/circuit-notation/archive/564769c52aa05b90f81bbc898b7af7087d96613d.tar.gz",
+        "url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz"
+    },
     "clash-compiler": {
         "branch": "1.8",
         "description": "Haskell to VHDL/Verilog/SystemVerilog compiler",
@@ -12,6 +24,19 @@
         "url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz",
         "version": "1.8.2"
     },
+    "clash-protocols": {
+        "branch": "main",
+        "branch": "peter/for-ethernet-core",
+        "description": "a battery-included library for dataflow protocols",
+        "homepage": null,
+        "owner": "clash-lang",
+        "repo": "clash-protocols",
+        "rev": "15b4f4fe560f217609a387f4256927046099715c",
+        "sha256": "0ixs021kadbl70q6mgqfrq0pylc9qh1l519n384ij28l9w5x6ana",
+        "type": "tarball",
+        "url": "https://github.com/clash-lang/clash-protocols/archive/15b4f4fe560f217609a387f4256927046099715c.tar.gz",
+        "url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz"
+    },
     "doctest-parallel": {
         "branch": "main",
         "description": "Test interactive Haskell examples",
@@ -50,18 +75,6 @@
         "url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz",
         "version": "1.4"
     },
-    "circuit-notation": {
-        "branch": "master",
-        "description": "A plugin for circuit notation",
-        "homepage": null,
-        "owner": "cchalmers",
-        "repo": "circuit-notation",
-        "rev": "19b386c4aa3ff690758ae089c7754303f3500cc9",
-        "sha256": "0qz2w6akxj51kq50rbl88bnjyxzd2798a9sn9jj1z2kak7a6kqbg",
-        "type": "tarball",
-        "url": "https://github.com/cchalmers/circuit-notation/archive/19b386c4aa3ff690758ae089c7754303f3500cc9.tar.gz",
-        "url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz"
-    },
     "niv": {
         "branch": "master",
         "description": "Easy dependency management for Nix projects",

src/Clash/Cores/Ethernet/Arp.hs

@@ -0,0 +1,95 @@
+{-# LANGUAGE FlexibleContexts #-}
+{-# OPTIONS_GHC -fplugin=Protocols.Plugin #-}
+
+{- |
+Copyright   :  (C) 2024, QBayLogic B.V.
+License     :  BSD2 (see the file LICENSE)
+Maintainer  :  QBayLogic B.V. <[email protected]>
+
+Provides a top-level ARP circuit sufficient for most use cases, along with
+the individual components it is composed of.
+-}
+module Clash.Cores.Ethernet.Arp (
+  -- * Types, constants and simple operations
+  module Clash.Cores.Ethernet.Arp.ArpTypes,
+
+  -- * Top-level ARP stack
+  arpC,
+
+  -- * Individual components
+  module Clash.Cores.Ethernet.Arp.ArpTable,
+  module Clash.Cores.Ethernet.Arp.ArpManager,
+) where
+
+import Clash.Prelude
+
+import Protocols
+import qualified Protocols.Df as Df
+import Protocols.PacketStream
+
+import Clash.Cores.Ethernet.Arp.ArpManager
+import Clash.Cores.Ethernet.Arp.ArpTable
+import Clash.Cores.Ethernet.Arp.ArpTypes
+import Clash.Cores.Ethernet.IP.IPv4Types
+import Clash.Cores.Ethernet.Mac.EthernetTypes
+
+{- |
+A fully functional ARP stack which handles ARP lookups from client circuits.
+Maintains a multi-entry ARP table which the client circuit can query via the
+'ArpLookup' input. If the client-supplied IPv4 address is not found in the
+table, it broadcasts an ARP request for this specific address. The circuit will
+assert backpressure until either a reply has been received, or a timeout
+occurs. The maximum number of milliseconds the stack will wait for a reply to
+this request is configurable. The timeout (in seconds) of ARP table entries is
+configurable as well.
+
+Moreover, it takes in an Ethernet packet stream with the ARP etherType
+(0x0806), and updates the ARP table upon receiving a valid ARP reply or
+gratuitous ARP packet. If an ARP request directed to our IPv4 address is
+received, it transmits a reply. Outbound requests receive priority over
+outbound replies in the output stream.
+
+For more specific information, refer to the documentation of the individual
+components.
+-}
+arpC ::
+  forall
+    (dataWidth :: Nat)
+    (dom :: Domain)
+    (maxAgeSeconds :: Nat)
+    (maxWaitMs :: Nat)
+    (tableDepth :: Nat).
+  (HiddenClockResetEnable dom) =>
+  (KnownNat dataWidth) =>
+  (1 <= dataWidth) =>
+  (1 <= tableDepth) =>
+  -- | Entries are evicted from the ARP table this many seconds after being inserted
+  SNat maxAgeSeconds ->
+  -- | The maximum amount of milliseconds to wait for an incoming ARP reply
+  SNat maxWaitMs ->
+  -- | The ARP table will contain @2^depth@ entries
+  SNat tableDepth ->
+  -- | Our MAC address
+  Signal dom MacAddress ->
+  -- | Our IPv4 address
+  Signal dom IPv4Address ->
+  Circuit
+    (PacketStream dom dataWidth EthernetHeader, ArpLookup dom)
+    (PacketStream dom dataWidth EthernetHeader)
+arpC maxAge maxWaitMs tableDepth ourMacS ourIPv4S =
+  circuit $ \(ethStream, lookupIn) -> do
+    -- Add a skid buffer to improve timing. We don't need the metadata, so we
+    -- can throw it away.
+    bufferedStream <- mapMeta (const ()) |> registerBoth -< ethStream
+    (entry, replyOut) <- arpReceiverC ourIPv4S -< bufferedStream
+    (lookupOut, requestOut) <- arpManagerC maxWaitMs -< lookupIn
+    () <- arpTableC tableDepth maxAge -< (lookupOut, entry)
+    -- Being biased towards outbound requests is favourable, as it
+    -- lessens the impact of ARP request DoS attacks. Moreover,
+    -- @CollectMode@ @Df.Parallel@ is not always more expensive
+    -- than @Df.Skip@ with two sources. Under certain circumstances
+    -- it may be cheaper.
+    arpPktOut <- Df.roundrobinCollect Df.Parallel -< [replyOut, requestOut]
+    arpStreamOut <- arpTransmitterC ourMacS ourIPv4S |> registerBoth -< arpPktOut
+    mapMetaS ((\src dst -> EthernetHeader dst src arpEtherType) <$> ourMacS)
+      -< arpStreamOut