Clash Ethernet 🙏✨

A fully configurable Ethernet core written in Clash.

Table of Contents

• Introduction
• Comparison with Other Ethernet Stacks
• Resource Usage Comparison
• Documentation
• How to use as a developer
  • Running Python tests
• How to contact maintainers/developers
• Acknowledgements

Introduction

Clash Ethernet is a fully configurable Ethernet core written in Clash. It aims to become part of the clash-protocols library which exists to make it easy to develop and use on-chip communication protocols, with a focus on protocols in need of bidirectional communication. Clash Ethernet will provide the internet protocols.

So far, Clash Ethernet implements the following internet protocols:

• Ethernet
• ICMP
• IP
• ARP
• UDP

Comparison with Other Ethernet Stacks

Some of the benefits of using Clash Ethernet are:

• Every protocol is fully configurable in data width. This is something that other libraries, such as LiteEth and verilog-ethernet do not support.

• Clash makes it very easy to combine two or more components, see Clash Protocols. Doing the same in other ethernet cores would require significantly more work.

• Every component in Clash Ethernet is fully tested with random input data using Hedgehog and Tasty.

Something to consider when choosing to use Clash-ethernet is that, for now, it only work on an ECP5 with an RGMII chip. However more FPGA's and chips are coming soon™.

Resource Usage Comparison

The table above shows resource usage of Clash Ethernet compared to LithEth and Verilog, using a data width of 4 bytes and a simple echo design. The data shows that Clash Ethernet is about 10% more efficient in terms of DFF's (D-Flip-Flops).

TODO: add Verilog resource usage.

Documentation

Clash Ethernet uses the Nix package manager to setup its build environment. To generate a local html website of the Clash Ethernet documentation run the following commands:

nix-shell
cabal haddock

After cabal is finished it will print the <file-path> to an html file to stdout. Open the file in your browser and use it as the starting point to the Clash Ethernet documentation.

To get inspired, there are some examples for using Clash Ethernet in the examples/ directory.

For more information look at Clash-protocols. This is the overarching framework of which Clash Ethernet is a part.

To make working with your FPGA easier it could be useful to set some environment variables. You can use env.sh for this. To help you get started, this repo contains env.sh.default. To inherit the environment variables from env.sh to your current shell run:

. env.sh

How to use as a developer

The easiest way to setup a development environment to start hacking on Clash Ethernet is to install nix (just the package manager, not the entire linux distribution).

After you've installed nix, clone this repo and run nix-shell.

git clone https://github.com/GiPHouse/qbaylogic-clash-based-macipudp-stack-spring24.git clash-ethernet
cd clash-ethernet
nix-shell

nix-shell will take about 30 minutes to compile and install everything, after which you'll have all the tools required to start hacking. Subsequent invocations of nix-shell will only take 5 seconds.

There is a Makefile with the following targets:

• clean: Delete all build directories
• format: Run stylish-haskell formatter to format source code
• test: Run the test suite
• verilog: Synthesize verilog code from the Clash TopEntity
• netlist: Synthesize a json netlist
• pnr: Place and route the json netlist
• bitstream: Create a bitstream from the place and routed netlist
• prog: SRAM program the FPGA. This means the image is gone after a power cycle. This is much faster then flashing.
• flash: Flash the bitstream and reboot FPGA
• namespace: Create a networking namespace "colorlight"
• delete_namespace: Delete the networking namespace "colorlight"
• python_test: Program the FPGA and run the Python test suite within a networking namespace.

A REPL can be started with:

cabal repl

Running Python tests

To be able to run make python_test, copy env.sh.default to env.sh and add the ethernet interface (see ip a) and serial port device (something like /dev/ttyACM0, see for example python -m serial.tools.list_ports).

To use Wireshark with the test suite, first manually create the namespace with make namespace, then run Wireshark in the namspace with sudo ip netns exec colorlight sudo wireshark. The test suite can then be ran as normal. Alternatively, Python files can be ran manually with sudo ip netns exec colorlight sudo ./<filename>.

How to contact maintainers/developers

If you find any bugs please report them here.

Acknowledgements

Thanks to all the members of the QbayLogic team of the Software Engineering course 2024.