README.md

Ethernet MAC Generator

A parameterizable Ethernet Media Access Control (MAC) hardware design generator written in Chisel. It provides MII, GMII, RGMII, 2.5G SGMII, and 10G XGMII MAC interfaces; MAC/FIFO components; Address Resolution Protocol (ARP), IPv4, and UDP processing; Management Data Input/Output (MDIO) control; Direct Memory Access (DMA) support; and TileLink and AXI4-Stream interfaces. The repository includes Chisel-native implementations and integrations based on Alex Forencich's verilog-ethernet components.

Prerequisites

• A JDK and sbt
• Python with cocotb >= 2.0, pytest, cocotbext-axi >= 0.1.26, and cocotbext-eth >= 0.1.24
• Verilator

Run all commands below from the ethernet-mac directory. Before using sbt in a fresh checkout, clone the pinned dependencies:

make clone_dependencies

Generate RTL

Native Chisel Ethernet MACs

Generate SystemVerilog for the native MAC implementations with:

sbt "runMain rivet.EthMac1GApp"
sbt "runMain rivet.EthMac1GFifoApp"
sbt "runMain rivet.EthMacMiiApp"
sbt "runMain rivet.EthMacMiiFifoApp"
sbt "runMain rivet.EthMac1GGmiiApp"
sbt "runMain rivet.EthMac1GGmiiFifoApp"
sbt "runMain rivet.EthMac1GRgmiiApp"
sbt "runMain rivet.EthMac1GRgmiiFifoApp"
sbt "runMain rivet.EthMac2p5GSgmiiApp"

The generated modules are written to generated_sv/, including EthMac1GBlock.sv, EthMacMiiBlock.sv, EthMac1GGmiiBlock.sv, EthMac1GRgmiiBlock.sv, and EthMac2p5GSgmiiBlock.sv, with corresponding *FifoBlock.sv files for the FIFO variants.

Verilog Ethernet Components-backed peripherals

Generate split SystemVerilog for the standalone peripherals based on verilog-ethernet with:

sbt "runMain rivet.wrapper.EthGmiiApp"
sbt "runMain rivet.wrapper.EthRgmiiApp"
sbt "runMain rivet.wrapper.EthXgmiiApp"

The generated RTL is written to rtl/eth_gmii_tl, rtl/eth_rgmii_tl, and rtl/eth_xgmii_tl, respectively.

Test RTL

The RTL tests use cocotb's Python runner with Verilator, driven by pytest. Each test directory under src/test/python/ethernet is self-contained and elaborates its own DUT, so no separate generation step is needed:

# one DUT
pytest src/test/python/ethernet/udp_checksum_gen

# everything
pytest src/test/python/ethernet

The runner invokes sbt "runMain rivet.<DUT>App" automatically when generated_sv/<DUT>Block.sv is missing. Useful environment variables:

variable	default	effect
SIM	verilator	simulator backend
SV_DIR	<repo>/generated_sv	where generated SystemVerilog lives
REGEN_SV	0	set to 1 to re-run sbt even if the .sv already exists
WAVES	1	set to 0 to disable waveform dumping

Re-elaborate after changing Chisel source:

REGEN_SV=1 pytest src/test/python/ethernet/udp_checksum_gen

Shared runner plumbing lives in src/test/python/ethernet/testutils.py; each testbench ends with a short test_<dut>() function that calls into it.

Funding

This work is part of the RIVET project.

        

This contribution was funded through the NGI0 Commons Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 101135429. Additional funding is made available by the Swiss State Secretariat for Education, Research and Innovation (SERI).