docs: update Ethernet Interface
This commit is contained in:
Fischer Moseley
parent
3148aa0055
commit
2b4d8b56ec
|
|
@ -1,15 +1,21 @@
|
|||
## Overview
|
||||
For scenarios where UART is not available or higher bandwidth is desired, Manta provides an Ethernet interface for communicating between the host and FPGA. This interface uses UDP for communication, and leverages the builtin Python `sockets` module on the host side, and the open-source [LiteEth](https://github.com/enjoy-digital/liteeth) Ethernet core on the FPGA side.
|
||||
|
||||
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 guaruntee 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](https://github.com/fischermoseley/manta/issues/10).
|
||||
|
||||
!!! info "Not every device is supported!"
|
||||
|
||||
Although Manta aims to be as platform-agnostic as possible, Ethernet PHYs and FPGA clock primitives are very particular devices. As a result, the supported devices are loosely restricted to those on [this list](https://github.com/enjoy-digital/liteeth?tab=readme-ov-file#-features). If a device you'd like to use isn't on the list, the community would love your help!
|
||||
Internally, the Ethernet Interface uses [LiteEth](https://github.com/enjoy-digital/liteeth) to generate cross-platform RTL for the FPGA. As a result, the supported devices are loosely restricted to those [supported by LiteEth](https://github.com/enjoy-digital/liteeth?tab=readme-ov-file#-features). If a device you'd like to use isn't on the list, the community would love your help.
|
||||
|
||||
|
||||
Both the [Use Cases](../use_cases) page and the repository's [examples](https://github.com/fischermoseley/manta/tree/main/examples) folder contain examples of the Ethernet Interface for your reference.
|
||||
|
||||
Although UDP does not guarantee reliable packet delivery, this usually doesn't pose an issue in practice. Manta will throw a runtime error if packets are dropped, and the UDP checksum and Ethernet FCS guarantee that any data delivered is not corrupted. Together, these two behaviors prevent corrupted data from being provided to the user, as Manta will error before returning invalid data. As long as your network is not terribly congested, Manta will operate without issue.
|
||||
|
||||
## Configuration
|
||||
|
||||
The configuration of the Ethernet core is best shown by example:
|
||||
### 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:
|
||||
|
||||
```yaml
|
||||
ethernet:
|
||||
phy: LiteEthPHYRMII
|
||||
|
|
@ -22,24 +28,34 @@ ethernet:
|
|||
fpga_ip_addr: "192.168.0.110"
|
||||
host_ip_addr: "192.168.0.100"
|
||||
```
|
||||
This snippet at the end of the configuration file defines the interface. The following parameters must be set:
|
||||
Inside this configuration, the following parameters may be set:
|
||||
|
||||
- `phy` _(required)_: The name of the LiteEth PHY class to use. Valid values consist of any of the names in [this list](https://github.com/enjoy-digital/liteeth/blob/b4e28506238c5340f2ade7899c2223424cabd410/liteeth/phy/__init__.py#L25-L45). Select the appropriate one for your FPGA vendor and family.
|
||||
- `phy` _(required)_: The name of the LiteEth PHY class to use. Select the appropriate one from [this list](https://github.com/enjoy-digital/liteeth/blob/b4e28506238c5340f2ade7899c2223424cabd410/liteeth/phy/__init__.py#L25-L45) for your FPGA vendor and family.
|
||||
|
||||
- `vendor` _(required)_: The vendor of the FPGA being designed for. Currently only values of `xilinx` and `lattice` are supported. Used to generate timing constraints files, which are currently unused.
|
||||
- `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 instance.
|
||||
- `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. This frequency must match the MII variant supported by the PHY, as well as speed that the PHY is being operated at. For instance, a RGMII PHY may be operated at either 125MHz in Gigabit mode, or 25MHz in 100Mbps mode.
|
||||
- `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. The easiest way to check if this was successful is by pinging the FPGA's IP, but if you have access to your network's router it may report a list of connected devices.
|
||||
- `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 additonal arguments provided in the `ethernet` section of the config file will be passed to the LiteEth standalone core generator. As a result, the [examples](https://github.com/enjoy-digital/liteeth/tree/master/examples) provided by LiteEth may be of some service to you if you're bringing up a different FPGA!
|
||||
|
||||
!!! warning "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.
|
||||
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](#manta.EthernetInterface) below, as well as the Amaranth [examples](https://github.com/fischermoseley/manta/tree/main/examples/amaranth) in the repo.
|
||||
|
||||
::: manta.EthernetInterface
|
||||
options:
|
||||
members: false
|
||||
|
|
@ -11,16 +11,58 @@ from manta.utils import *
|
|||
|
||||
class EthernetInterface(Elaboratable):
|
||||
"""
|
||||
A module for communicating with Manta over Ethernet, using UDP.
|
||||
|
||||
Provides methods for generating synthesizable logic for the FPGA, as well
|
||||
as methods for reading and writing to memory by the host.
|
||||
|
||||
More information available in the online documentation at:
|
||||
https://fischermoseley.github.io/manta/ethernet_interface/
|
||||
A synthesizable module for Ethernet (UDP) communication between a host
|
||||
machine and the FPGA.
|
||||
"""
|
||||
|
||||
def __init__(self, fpga_ip_addr, host_ip_addr, udp_port, phy, clk_freq, **kwargs):
|
||||
def __init__(self, phy, clk_freq, fpga_ip_addr, host_ip_addr, udp_port=2001, **kwargs):
|
||||
"""
|
||||
This function is the main mechanism for configuring an Ethernet
|
||||
Interface in an Amaranth-native design.
|
||||
|
||||
Args:
|
||||
phy (str): The name of the LiteEth PHY class to use. Select the
|
||||
appropriate one from [this list](https://github.com/enjoy-digital/liteeth/blob/main/liteeth/phy/__init__.py#L25-L45)
|
||||
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]): 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](https://en.wikipedia.org/wiki/MAC_address#Ranges_of_group_and_locally_administered_addresses)
|
||||
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.
|
||||
"""
|
||||
|
||||
self._fpga_ip_addr = fpga_ip_addr
|
||||
self._host_ip_addr = host_ip_addr
|
||||
self._udp_port = udp_port
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ from manta.utils import *
|
|||
|
||||
class UARTInterface(Elaboratable):
|
||||
"""
|
||||
A synthesizable module for UART communication between the host machine and
|
||||
A synthesizable module for UART communication between a host machine and
|
||||
the FPGA.
|
||||
"""
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue