Design new Ethernet framing top

Nobody has claimed this yet.

The Ethernet framing top is an AXI4 device which converts the AXI-Stream packet interfaces from a vendor Ethernet MAC core to a memory-mapped bus interface. It allows a host to send and receive MAC layer packets by reading or writing CSRs, transmit buffers and receive buffers.

This issue contains a draft specification for a new framing top which will replace the existing framing top from the [ariane-ethernet](https://github.com/lowRISC/ariane-ethernet) repository.

# Draft specification
EDIT 2026-05-22: Replace the 8 Rx buffers with a unified Rx buffer. Simplify receive software flow.

## Registers
| Register Name | Offset | Length (Bytes) | Description |
|-|-|-|-|
| INTR_STATE | 0x0 | 4 | Interrupt State Register |
| INTR_ENABLE | 0x4 | 4 | Interrupt Enable Register |
| INTR_TEST | 0x8 | 4 | Interrupt Test Register |
| - | 0xc | 4 | - |
| CTRL | 0x10 | 4 | MAC Control Register |
| STATUS | 0x14 | 4 | MAC Status Register |
| MACLO | 0x18 | 4 | Lower MAC Address Register |
| MACHI | 0x1C | 4 | Upper MAC Address Register |
| TX_CTRL | 0x20 | 4 | Transmit Control Register |
| RX_META_FIFO | 0x24 | 4 | Receive Packet Metadata FIFO Front |
| RX_META_POP | 0x28 | 4 | Receive Packet Metadata FIFO Pop |
| MDIO_CTRL | 0x2C | 4 | MDIO Control Register |

## Buffers
| Register Name | Offset | Length (Bytes) | Description |
|-|-|-|-|
| TX_BUFFER | 0x1000 | 2048 | Transmit buffer |
| RX_BUFFER | 0x2000 | 16384 | Unified receive buffer |

## Register fields
### INTR_STATE
| Bits | Type | Reset | Name | Description |
|-|-|-|-|-|
| 31:1 | | | | Reserved |
| 0 | rw1c | 0x0 | rx_avail | Received packet available. |

### INTR_ENABLE
| Bits | Type | Reset | Name | Description |
|-|-|-|-|-|
| 31:1 | | | | Reserved |
| 0 | rw | 0x0 | rx_avail | Enable interrupt when a received packet is available. |

### INTR_TEST
| Bits | Type | Reset | Name | Description |
|-|-|-|-|-|
| 31:1 | | | | Reserved |
| 0 | wo | 0x0 | rx_avail | Write 1 to force `INTR_STATE.rx_avail` to 1. |

### CTRL
| Bits | Type | Reset | Name | Description |
|-|-|-|-|-|
| 31:1 | | | | Reserved |
| 0 | rw | 0x0 | promiscuous | Promiscuous mode enable. |

### STATUS
| Bits | Type | Reset | Name | Description |
|-|-|-|-|-|
| 31:2 | | | | Reserved |
| 1 | ro | 0x0 | rx_avail | Received packet available. |
| 0 | ro | 0x0 | tx_busy | Transmit busy. |

### MACLO
| Bits | Type | Reset | Name | Description |
|-|-|-|-|-|
| 31:0 | rw | 0x0 | mac_low | MAC address lower 32-bits. |

### MACHI
| Bits | Type | Reset | Name | Description |
|-|-|-|-|-|
| 31:16 | | | | Reserved |
| 15:0 | rw | 0x0 | mac_high | MAC address upper 16-bits. |

### TX_CTRL
| Bits | Type | Reset | Name | Description |
|-|-|-|-|-|
| 31:11 | | | | Reserved |
| 10:0 | rw | 0x0 | tx_packet_len | Tx packet length (bytes). Write to transmit packet. |

### RX_META_FIFO
| Bits | Type | Reset | Name | Description |
|-|-|-|-|-|
| 31 | ro | 0x0 | valid | FIFO front is valid. Reading this does not pop from the FIFO. |
| 30 | | | | Reserved |
| 29:16 | ro | 0x0 | rx_buffer_offset | Receive buffer offset (bytes). |
| 15:11 | | | | Reserved |
| 10:0 | ro | 0x0 | len | Packet length (bytes). |

### RX_META_POP
| Bits | Type | Reset | Name | Description |
|-|-|-|-|-|
| 31:1 | | | | Reserved |
| 0 | wo | 0x0 | rx_meta_pop | Pop the front entry in the Rx metadata FIFO. |

### MDIO_CTRL
| Bits | Type | Reset | Name | Description |
|-|-|-|-|-|
| 31:4 | | | | Reserved |
| 3 | ro | N/A | mdio_i | MDIO input. |
| 2 | rw | 0x0 | mdio_oen | MDIO output enable. |
| 1 | rw | 0x0 | mdio_o | MDIO output. |
| 0 | rw | 0x0 | mdio_clk | MDIO clock. |

## Software flow
### Transmit packet (alternative 1)
1. Write data to TX_BUFFER.
2. Write packet length (bytes, not including FCS) to TX_CTRL and begin transmitting packet.
3. Poll STATUS until tx_busy is 0.

### Transmit packet (alternative 2)
1. Poll STATUS until tx_busy is 0.
2. Write data to TX_BUFFER.
3. Write packet length (bytes, not including FCS) to TX_CTRL and begin transmitting packet.

### Receive packet
1. Wait for interrupt or poll STATUS until rx_avail is 1.
2. Read RX_META_FIFO to get the packet length and receive buffer offset for the received packet.
3. Use the receive buffer offset to read packet data from RX_BUFFER.
4. Write 1 to RX_META_POP to free the Rx packet.
5. Clear interrupt by writing to INTR_STATE if necessary.

## Reference block diagram

Use the existing framing top from the ariane-ethernet repository as the starting reference, then compare its AXI-Stream and memory-mapped behavior with this draft specification. Implement the replacement with the listed registers, unified receive buffer, metadata FIFO, and transmit/receive software flows; done means the new framing top matches the specified interface and behavior.

Written by the indexing model from the issue text.