Ethernet Interface

Overview

For applications where UART is too slow or isn't available, Manta provides the option to run over Ethernet. This is done via UDP, so the FPGA can be anywhere on the same network as the host machine - as opposed to MAC-based Ethernet interfaces, which usually require a point-to-point network connection between the FPGA and the host. Although UDP does not guarantee reliable, in-order packet delivery, this generally tends to be the case on uncongested networks. In the future, Manta will enforce this at the application layer.

Not every device is supported!

Internally, the Ethernet Interface uses LiteEth to generate cross-platform RTL for the FPGA. As a result, the supported devices are loosely restricted to those supported by LiteEth. If a device you'd like to use isn't on the list, the community would love your help.

Both the Use Cases page and the repository's examples folder contain examples of the Ethernet Interface for your reference.

Configuration

Verilog-Based Workflows

The UART interface is used by adding a ethernet entry at the bottom of the configuration file. This is best shown by example:

ethernet:
  phy: LiteEthPHYRMII
  vendor: xilinx
  toolchain: vivado

  clk_freq: 50e6
  refclk_freq: 50e6

  fpga_ip_addr: "192.168.0.110"
  host_ip_addr: "192.168.0.100"

Inside this configuration, the following parameters may be set:

phy (required): The name of the LiteEth PHY class to use. Select the appropriate one from this list for your FPGA vendor and family.
vendor (required): The vendor of your FPGA. Currently only values of xilinx and lattice are supported. This is used to generate (currently unused) timing constraints files.
toolchain (required): The toolchain being used. Currently only values of vivado and diamond are supported.
clk_freq (required): The frequency of the clock provided to the Manta module on the FPGA, in Hertz (Hz).
refclk_freq (required): The frequency of the reference clock to be provided to the Ethernet PHY, in Hertz (Hz). This frequency must match the MII variant used by the PHY, and speed it is being operated at. For instance, a RGMII PHY may be operated at either 125MHz in Gigabit mode, or 25MHz in 100Mbps mode.
fpga_ip_addr (required): The IP address the FPGA will attempt to claim. Upon power-on, the FPGA will issue a DHCP request for this IP address. Ping this address after power-on to check if this request was successful, or check your router for a list of connected devices.
host_ip_addr (required): The IP address of the host machine, which the FPGA will send packets back to.
udp_port (optional): The UDP port to communicate over. Defaults to 2001.

Lastly, any additional arguments provided in the ethernet section of the config file will be passed to the LiteEth standalone core generator. As a result, the examples provided by LiteEth may be of some service to you if you're bringing up a different FPGA!

LiteEth doesn't always generate its own refclk!

Although LitEth is built on Migen and LiteX which support PLLs and other clock generation primitives, I haven't seen it instantiate one to synthesize a suitable refclk at the appropriate frequency from the input clock. As a result, for now it's recommended to generate your refclk outside Manta, and then use it to clock your Manta instance.

Amaranth-Native Designs

Since Amaranth modules are Python objects, the configuration of the IO Core is given by the arguments given during initialization. See the documentation for the EthernetInterface class constructor below, as well as the Amaranth examples in the repo.

Don't use .eq() when connecting to PHY IO pins!

The EthernetInterface has its own class methods for connecting to the IO pins routed to the PHY. This is necessary as some variations of the Media-Independent Interface used by Ethernet PHYs include bidirectional (ie, inout) signals, which require some special provisions in Amaranth. As a result these methods is used to connect the EthernetInterface to the Ethernet PHY, instead of using Amaranth's .eq(), as is done on the UARTInterface.

For more information on the connections between your PHY and FPGA, please reference your PHY's datasheet, your development board's schematic, or Wikipedia for more information.

manta.EthernetInterface

EthernetInterface(phy, clk_freq, fpga_ip_addr, host_ip_addr, udp_port=2001, **kwargs)

A synthesizable module for Ethernet (UDP) communication between a host machine and the FPGA.

This function is the main mechanism for configuring an Ethernet Interface in an Amaranth-native design.

Parameters:

phy (str) –

The name of the LiteEth PHY class to use. Select the appropriate one from this list for your FPGA vendor and family.
clk_freq (int | float) –

The frequency of the clock provided to the Manta module on the FPGA, in Hertz (Hz).
fpga_ip_addr (str) –

The IP address the FPGA will attempt to claim. Upon power-on, the FPGA will issue a DHCP request for this IP address. Ping this address after power-on to check if this request was successful, or check your router for a list of connected devices.
host_ip_addr (str) –

The IP address of the host machine, which the FPGA will send packets back to.
udp_port (Optional[int], default: 2001 ) –

The UDP port to communicate over.
**kwargs –
Any additional keyword arguments to this function will be passed to the LiteEth RTL generator. Some examples are provided below:
- mac_address (int): A 48-bit integer representing the MAC address the FPGA will assume. If not provided, an address within the Locally Administered, Administratively Assigned group will be randomly generated.
- vendor (str): The vendor of your FPGA. Currently only values of xilinx and lattice are supported. This is used to generate (currently unused) timing constraints files.
- toolchain (str): The toolchain being used. Currently only values of vivado and diamond are supported.
- refclk_freq (int | float): The frequency of the reference clock to be provided to the Ethernet PHY, in Hertz (Hz). This frequency must match the MII variant used by the PHY, and speed it is being operated at. For instance, a RGMII PHY may be operated at either 125MHz in Gigabit mode, or 25MHz in 100Mbps mode.

set_mii_phy_io

set_mii_phy_io(mii_clocks_tx, mii_clocks_rx, mii_rst_n, mii_mdio, mii_mdc, mii_rx_dv, mii_rx_er, mii_rx_data, mii_tx_en, mii_tx_data, mii_col, mii_crs)

Sets the signals used to connect to a MII PHY in an Amarnath-native design.

Parameters:

mii_clocks_tx (IOPort) –

Transmit Clock
mii_clocks_rx (IOPort) –

Receive Clock
mii_rst_n (IOPort) –

PHY Reset
mii_mdio (IOPort) –

Management Data
mii_mdc (IOPort) –

Management Data Clock
mii_rx_dv (IOPort) –

Receive Data Valid
mii_rx_er (IOPort) –

Receive Error
mii_rx_data (IOPort) –

Receive Data
mii_tx_en (IOPort) –

Transmit Enable
mii_tx_data (IOPort) –

Transmit Data
mii_col (IOPort) –

Collision Detect
mii_crs (IOPort) –

Carrier Sense

set_rmii_phy_io

set_rmii_phy_io(rmii_clocks_ref_clk, rmii_rst_n, rmii_rx_data, rmii_crs_dv, rmii_tx_en, rmii_tx_data, rmii_mdc, rmii_mdio)

Sets the signals used to connect to a RMII PHY in an Amarnath-native design.

Parameters:

rmii_clocks_ref_clk (IOPort) –

Reference Clock
rmii_rst_n (IOPort) –

PHY Reset
rmii_rx_data (IOPort) –

Receive Data
rmii_crs_dv (IOPort) –

Carrier Sense and Receive Data Valid, multiplexed
rmii_tx_en (IOPort) –

Transmit Enable
rmii_tx_data (IOPort) –

Transmit Data
rmii_mdc (IOPort) –

Management Data Clock
rmii_mdio (IOPort) –

Management Data

set_gmii_phy_io

set_gmii_phy_io(gmii_clocks_tx, gmii_clocks_gtx, gmii_clocks_rx, gmii_rst_n, gmii_int_n, gmii_mdio, gmii_mdc, gmii_rx_dv, gmii_rx_er, gmii_rx_data, gmii_tx_en, gmii_tx_er, gmii_tx_data, gmii_col, gmii_crs)

Sets the signals used to connect to a GMII PHY in an Amarnath-native design.

Parameters:

gmii_clocks_tx (IOPort) –

Clock for 10/100 Mbit/s signals.
gmii_clocks_gtx (IOPort) –

Clock for gigabit transmit signals
gmii_clocks_rx (IOPort) –

Received Clock signal
gmii_rst_n (IOPort) –

PHY Reset
gmii_int_n (IOPort) –

PHY Interrupt
gmii_mdio (IOPort) –

Management Data
gmii_mdc (IOPort) –

Management Data Clock
gmii_rx_dv (IOPort) –

Receive Data Valid
gmii_rx_er (IOPort) –

Receive Error
gmii_rx_data (IOPort) –

Receive Data
gmii_tx_en (IOPort) –

Transmit Enable
gmii_tx_er (IOPort) –

Transmit Error
gmii_tx_data (IOPort) –

Transmit Data
gmii_col (IOPort) –

Collision Detect
gmii_crs (IOPort) –

Carrier Sense

set_rgmii_phy_io

set_rgmii_phy_io(rgmii_clocks_tx, rgmii_clocks_rx, rgmii_rst_n, rgmii_int_n, rgmii_mdio, rgmii_mdc, rgmii_rx_ctl, rgmii_rx_data, rgmii_tx_ctl, rgmii_tx_data)

Sets the signals used to connect to a RGMII PHY in an Amarnath-native design.

Parameters:

rgmii_clocks_tx (IOPort) –

Transmit Clock
rgmii_clocks_rx (IOPort) –

Receive Clock
rgmii_rst_n (IOPort) –

PHY Reset
rgmii_int_n (IOPort) –

PHY Interrupt
rgmii_mdio (IOPort) –

Management Data
rgmii_mdc (IOPort) –

Management Data Clock
rgmii_rx_ctl (IOPort) –

Receive Error and Receive Data Valid, multiplexed
rgmii_rx_data (IOPort) –

Receive Data
rgmii_tx_ctl (IOPort) –

Transmit Enable and Transmit Error, multiplexed
rgmii_tx_data (IOPort) –

Transmit Data

set_sgmii_phy_io

set_sgmii_phy_io(sgmii_refclk, sgmii_rst, sgmii_txp, sgmii_txn, sgmii_rxp, sgmii_rxn, sgmii_link_up)

Sets the signals used to connect to a SGMII PHY in an Amarnath-native design.

Parameters:

sgmii_refclk (IOPort) –

Reference Clock
sgmii_rst (IOPort) –

PHY Reset
sgmii_txp (IOPort) –

Transmit Data (Differential)
sgmii_txn (IOPort) –

Transmit Data (Differential)
sgmii_rxp (IOPort) –

Receive Data (Differential)
sgmii_rxn (IOPort) –

Receive Data (Differential)
sgmii_link_up (IOPort) –

Link Status