# Ethernet

## Overview

The RVComp Ethernet controller is a 10/100 Mbps controller integrated into the SoC. It handles Ethernet frame transmission and reception in hardware, including destination-MAC filtering and FCS generation/checking.

The controller connects to the board PHY as follows:

| Board        | PHY Interface | Data width | Clock |
|:-------------|:--------------|:-----------|:------|
| Nexys 4 DDR  | RMII          | 2-bit      | 50 MHz reference clock output from SoC |
| Arty A7      | MII           | 4-bit      | SoC outputs a 25 MHz reference clock required by the PHY |

The RX and TX buffer regions have fixed base addresses:

- RX buffer base: `0x1800_0000`
- TX buffer base: `0x1C00_0000`

Their sizes are selected at **synthesis time** through `ETHER_RXBUF_SIZE` and `ETHER_TXBUF_SIZE` in `src/config.vh`.

## Frame Format

```
┌──────────┬─────────────────┬─────────────────┬───────────┬──────────────────────┬──────────┬──────────────┐
│ Preamble │ Destination MAC │   Source MAC    │ EtherType │       Payload        │   FCS    │     IFG      │
│  8 bytes │    6 bytes      │    6 bytes      │  2 bytes  │   46–1500 bytes      │ 4 bytes  │   12 bytes   │
└──────────┴─────────────────┴─────────────────┴───────────┴──────────────────────┴──────────┴──────────────┘
```

Preamble, FCS, and IFG (Inter-Frame Gap) are handled entirely in hardware and are invisible to software.

## MAC Address Configuration

The default MAC address is `AA:BB:CC:DD:EE:FF`. To change it, both of the following must be updated manually:

- `src/config.vh` — update the `ETH_MAC_ADDR_*` bytes used for hardware filtering
- `bootrom/rvcomp.dts` — update the `local-mac-address` property used by Linux

GUI configuration (`make menuconfig`) does not support MAC address changes.

## External Pins

Exact pin assignments are defined in the constraint files under `constr/`.

### RMII pins (Nexys 4 DDR)

| Signal         | Direction | Description |
|:---------------|:----------|:------------|
| `eth_refclk`   | Output    | 50 MHz PHY reference clock |
| `eth_crsdv`    | Input     | Carrier sense / receive data valid |
| `eth_rxerr`    | Input     | Receive error |
| `eth_rxd[1:0]` | Input     | Receive data |
| `eth_txen`     | Output    | Transmit enable |
| `eth_txd[1:0]` | Output    | Transmit data |
| `eth_rstn`     | Output    | PHY reset (active low) |
| `eth_mdio`     | Inout     | Reserved for future PHY management |
| `eth_mdc`      | Output    | Reserved for future PHY management |
| `eth_intn`     | Input     | Reserved PHY interrupt pin |

### MII pins (Arty A7)

| Signal         | Direction | Description |
|:---------------|:----------|:------------|
| `eth_rx_clk`   | Input     | Receive clock from PHY |
| `eth_tx_clk`   | Input     | Transmit clock from PHY |
| `eth_rx_dv`    | Input     | Receive data valid |
| `eth_rxerr`    | Input     | Receive error |
| `eth_rxd[3:0]` | Input     | Receive data |
| `eth_tx_en`    | Output    | Transmit enable |
| `eth_txd[3:0]` | Output    | Transmit data |
| `eth_refclk`   | Output    | Reference clock generated by the SoC |
| `eth_rstn`     | Output    | PHY reset (active low) |
| `eth_mdio`     | Inout     | Reserved for future PHY management |
| `eth_mdc`      | Output    | Reserved for future PHY management |

## Hardware Features

### MAC Filtering

The receive path compares the destination MAC address of incoming frames against the six `ETH_MAC_ADDR_*` bytes in `src/config.vh`. Frames that do not match are discarded in hardware.

### FCS (Frame Check Sequence)

FCS handling is performed entirely in hardware:

- **Receive path**: verifies the incoming CRC-32 and drops frames with an invalid FCS
- **Transmit path**: appends the FCS automatically

The software driver does not need to calculate or strip the FCS.

## CSR Map

All CSRs are 32-bit wide and are accessed in the Ethernet CSR region starting at `0x1400_0000`.

| Offset | Name                 | Access | Description |
|:------:|:---------------------|:------:|:------------|
| 0x00   | `RECEIVE_ADDR_START` | R/W    | RX read pointer. Software advances this after consuming data. |
| 0x04   | `RECEIVE_ADDR_END`   | R      | RX write pointer updated by hardware when a frame arrives. |
| 0x08   | `RECEIVE_READ_BYTE`  | W      | Software-visible latch reserved for byte-count acknowledgement; current drivers advance `RECEIVE_ADDR_START` directly instead. |
| 0x10   | `TX_BUSY`            | R      | Bit 0 is set while the TX ring contains pending data. |
| 0x14   | `TX_BUFFER_START`    | R      | Current TX read pointer maintained by hardware. |
| 0x18   | `TX_BUFFER_END`      | R/W    | TX write pointer. Software writes the new end pointer after appending a frame record. |

## Module Hierarchy

```text
ether_rmii (ether/ether_rmii.v)            # Nexys 4 DDR (RMII)
├── ether_rx_rmii (ether/ether_rx_rmii.v)  # RMII receive path
├── ether_tx_rmii (ether/ether_tx_rmii.v)  # RMII transmit path
└── sdp_2_clock_ram (ether/sdp_2_clock_ram.v) ×2

ether_mii (ether/ether_mii.v)              # Arty A7 (MII)
├── ether_rx_mii (ether/ether_rx_mii.v)    # MII receive path
├── ether_tx_mii (ether/ether_tx_mii.v)    # MII transmit path
└── sdp_2_clock_ram (ether/sdp_2_clock_ram.v) ×2
```

## Frame Reception

**RTL**:

1. Receives dibits (RMII) or nibbles (MII) from the PHY
2. Strips the preamble and SFD
3. Checks the destination MAC against `ETH_MAC_ADDR_*` in `src/config.vh`; discards the frame if it does not match
4. Verifies the FCS; discards the frame if invalid
5. Writes the frame payload to the RX buffer and advances `RECEIVE_ADDR_END`

If the RX buffer is full, incoming frames are silently dropped by hardware.

**CPU**:

1. Poll until `RECEIVE_ADDR_END != RECEIVE_ADDR_START`
2. Read the frame bytes from the RX buffer at `0x1800_0000`
3. Advance `RECEIVE_ADDR_START` after the frame has been consumed

## Frame Transmission

**CPU**:

1. Read `TX_BUFFER_START` and `TX_BUFFER_END`
2. Check that enough space is available in the TX buffer before writing; software is responsible for not overwriting unread data
3. Write a 32-bit frame-length header into the TX buffer at `0x1C00_0000`
4. Write the frame payload, padded to a 4-byte boundary
5. Write the new end pointer to `TX_BUFFER_END`

**RTL**:

1. Reads the frame record from the TX buffer
2. Prepends the preamble and SFD
3. Appends the FCS
4. Sends dibits (RMII) or nibbles (MII) to the PHY

## Protocol Notes

The Ethernet controller operates at OSI Layer 2. Hardware handles:

- preamble/SFD processing
- destination MAC filtering
- FCS generation and verification

Higher-layer protocols such as IP, ARP, TCP, and UDP are handled entirely in software by Linux.

## Software Support

For the Linux kernel driver and bare-metal helpers, see [Device Drivers](../software/drivers.md).