<inputclass="md-option"data-md-color-media="(prefers-color-scheme)"data-md-color-scheme="default"data-md-color-primary="indigo"data-md-color-accent="indigo"aria-label="Switch to light mode"type="radio"name="__palette"id="__palette_0">
<labelclass="md-header__button md-icon"title="Switch to light mode"for="__palette_1"hidden>
<inputclass="md-option"data-md-color-media="(prefers-color-scheme: light)"data-md-color-scheme="default"data-md-color-primary="blue"data-md-color-accent="custom"aria-label="Switch to dark mode"type="radio"name="__palette"id="__palette_1">
<labelclass="md-header__button md-icon"title="Switch to dark mode"for="__palette_2"hidden>
<inputclass="md-option"data-md-color-media="(prefers-color-scheme: dark)"data-md-color-scheme="slate"data-md-color-primary="black"data-md-color-accent="custom"aria-label="Switch to system preference"type="radio"name="__palette"id="__palette_2">
<labelclass="md-header__button md-icon"title="Switch to system preference"for="__palette_0"hidden>
<p>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 <ahref="https://github.com/fischermoseley/manta/issues/10">application layer</a>.</p>
<p>Internally, the Ethernet Interface uses <ahref="https://github.com/enjoy-digital/liteeth">LiteEth</a> to generate cross-platform RTL for the FPGA. As a result, the supported devices are loosely restricted to those <ahref="https://github.com/enjoy-digital/liteeth?tab=readme-ov-file#-features">supported by LiteEth</a>. If a device you'd like to use isn't on the list, the community would love your help.</p>
<p>Both the<ahref="../use_cases">Use Cases</a>page and the repository's<ahref="https://github.com/fischermoseley/manta/tree/main/examples">examples</a>folder contain examples of the Ethernet Interface for your reference.</p>
<p><code>phy</code><em>(required)</em>: The name of the LiteEth PHY class to use. Select the appropriate one from <ahref="https://github.com/enjoy-digital/liteeth/blob/b4e28506238c5340f2ade7899c2223424cabd410/liteeth/phy/__init__.py#L25-L45">this list</a> for your FPGA vendor and family.</p>
<p><code>vendor</code><em>(required)</em>: The vendor of your FPGA. Currently only values of <code>xilinx</code> and <code>lattice</code> are supported. This is used to generate (currently unused) timing constraints files.</p>
<p><code>toolchain</code><em>(required)</em>: The toolchain being used. Currently only values of <code>vivado</code> and <code>diamond</code> are supported.</p>
<p><code>refclk_freq</code><em>(required)</em>: 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.</p>
<p><code>fpga_ip_addr</code><em>(required)</em>: 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.</p>
<p>Lastly, any additonal arguments provided in the <code>ethernet</code> section of the config file will be passed to the LiteEth standalone core generator. As a result, the <ahref="https://github.com/enjoy-digital/liteeth/tree/master/examples">examples</a> provided by LiteEth may be of some service to you if you're bringing up a different FPGA!</p>
<divclass="admonition warning">
<pclass="admonition-title">LiteEth doesn't always generate its own <code>refclk</code>!</p>
<p>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 <code>refclk</code> at the appropriate frequency from the input clock. As a result, for now it's recommended to generate your <code>refclk</code> outside Manta, and then use it to clock your Manta instance.</p>
<p>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 <code>EthernetInterface</code><ahref="#manta.EthernetInterface">class constructor</a> below, as well as the Amaranth <ahref="https://github.com/fischermoseley/manta/tree/main/examples/amaranth">examples</a> in the repo.</p>
<p>The name of the LiteEth PHY class to use. Select the
appropriate one from <ahref="https://github.com/enjoy-digital/liteeth/blob/main/liteeth/phy/__init__.py#L25-L45">this list</a>
for your FPGA vendor and family.</p>
</div>
</li>
<liclass="doc-section-item field-body">
<b><code>clk_freq</code></b>
(<code>int | float</code>)
–
<divclass="doc-md-description">
<p>The frequency of the clock provided to the
Manta module on the FPGA, in Hertz (Hz).</p>
</div>
</li>
<liclass="doc-section-item field-body">
<b><code>fpga_ip_addr</code></b>
(<code>str</code>)
–
<divclass="doc-md-description">
<p>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.</p>
</div>
</li>
<liclass="doc-section-item field-body">
<b><code>host_ip_addr</code></b>
(<code>str</code>)
–
<divclass="doc-md-description">
<p>The IP address of the host machine, which the
FPGA will send packets back to.</p>
</div>
</li>
<liclass="doc-section-item field-body">
<b><code>udp_port</code></b>
(<code>Optional[int]</code>, default:
<code>2001</code>
)
–
<divclass="doc-md-description">
<p>The UDP port to communicate over.</p>
</div>
</li>
<liclass="doc-section-item field-body">
<b><code>**kwargs</code></b>
–
<divclass="doc-md-description">
<p>Any additional keyword arguments to this function will
be passed to the LiteEth RTL generator. Some examples are
provided below:</p>
<ul>
<li>
<p>mac_address (int): A 48-bit integer representing the MAC
address the FPGA will assume. If not provided, an address
within the <ahref="https://en.wikipedia.org/wiki/MAC_address#Ranges_of_group_and_locally_administered_addresses">Locally Administered, Administratively Assigned group</a>
will be randomly generated.</p>
</li>
<li>
<p>vendor (str): The vendor of your FPGA. Currently only values
of <code>xilinx</code> and <code>lattice</code> are supported. This is used to
<scriptid="__config"type="application/json">{"base":"..","features":["content.code.copy","content.code.annotate","navigation.sections","navigation.expand"],"search":"../assets/javascripts/workers/search.6ce7567c.min.js","translations":{"clipboard.copied":"Copied to clipboard","clipboard.copy":"Copy to clipboard","search.result.more.one":"1 more on this page","search.result.more.other":"# more on this page","search.result.none":"No matching documents","search.result.one":"1 matching document","search.result.other":"# matching documents","search.result.placeholder":"Type to start searching","search.result.term.missing":"Missing","select.version":"Select version"},"version":{"provider":"mike"}}</script>
