# valmyr/skarab-gbe-control architecture

> Architecture diagram of the GitHub repository valmyr/skarab-gbe-control, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/valmyr/skarab-gbe-control
- Repository: https://github.com/valmyr/skarab-gbe-control

## Overview

This repository is a SKARAB/CASPER GbE control and loopback prototype. The principal workflow sends a UDP frame from a host, recognizes the “rece” and “tran” commands in FPGA logic, captures payload bytes, then transmits the payload back for host-side comparison. The README also documents separate AXI4-Stream slave/master paths, legacy receive/transmit buffers, decimation, and register-based debug access. The supplied tree and excerpts do not expose the RTL source itself, so RTL nodes use the enclosing project directory; the target architecture and integrations are shown only where documented.

Main entry points: [`fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi`](https://github.com/valmyr/skarab-gbe-control/tree/stable/without-serdes/fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi) (Legacy TX FSM), [`script_python/socket/exploration_socket/minimal_client.py`](https://github.com/valmyr/skarab-gbe-control/blob/stable/without-serdes/script_python/socket/exploration_socket/minimal_client.py) (Packet sender), [`script_python/socket/autocheck_rx_rx_gen.py`](https://github.com/valmyr/skarab-gbe-control/blob/stable/without-serdes/script_python/socket/autocheck_rx_rx_gen.py) (Loopback checker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host Tools"]
  node_send["Packet sender<br/>[minimal_client.py]"]
  node_check["Loopback checker"]
end

subgraph group_fpga["GbE Control RTL"]
  node_phy["CASPER GbE block"]
  node_control["GbE controller"]
  node_cmd["Command detectors"]
  node_rx["Legacy RX FSM"]
  node_rxmem[("RX buffer")]
  node_tx["Legacy TX FSM"]
  node_decimator["TX decimator"]
end

subgraph group_axi["AXI Stream"]
  node_saxis["AXI slave FSM"]
  node_tmpmem[("AXI RX buffer")]
  node_maxis["AXI master FSM"]
end

subgraph group_debug["SKARAB Debug"]
  node_registers["Debug registers"]
end

node_host(("UDP host"))
node_axiinput(("AXI stream input"))
node_axioutput(("AXI stream consumer"))
node_skarab["SKARAB registers"]

node_host -->|"provides payload"| node_send
node_send -->|"sends UDP"| node_phy
node_phy -->|"receives bytes"| node_control
node_control -->|"examines commands"| node_cmd
node_cmd -->|"starts reception"| node_rx
node_cmd -->|"starts transmission"| node_tx
node_rx -->|"writes payload"| node_rxmem
node_rxmem -->|"supplies payload"| node_tx
node_tx -->|"decimates output"| node_decimator
node_tx -->|"transmits payload"| node_phy
node_decimator -->|"transmits paced data"| node_phy
node_phy -->|"returns UDP"| node_host
node_host -->|"provides received data"| node_check
node_check -->|"reports comparison"| node_host
node_axiinput -->|"provides stream"| node_saxis
node_saxis -->|"writes AXI data"| node_tmpmem
node_tmpmem -->|"supplies buffered data"| node_maxis
node_maxis -->|"emits stream"| node_axioutput
node_skarab -.->|"accesses debug state"| node_registers
node_registers -.->|"reads buffer"| node_rxmem

click node_send "https://github.com/valmyr/skarab-gbe-control/blob/stable/without-serdes/script_python/socket/exploration_socket/minimal_client.py"
click node_check "https://github.com/valmyr/skarab-gbe-control/blob/stable/without-serdes/script_python/socket/autocheck_rx_rx_gen.py"
click node_control "https://github.com/valmyr/skarab-gbe-control/tree/stable/without-serdes/fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi"
click node_cmd "https://github.com/valmyr/skarab-gbe-control/tree/stable/without-serdes/fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi"
click node_rx "https://github.com/valmyr/skarab-gbe-control/tree/stable/without-serdes/fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi"
click node_rxmem "https://github.com/valmyr/skarab-gbe-control/tree/stable/without-serdes/fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi"
click node_tx "https://github.com/valmyr/skarab-gbe-control/tree/stable/without-serdes/fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi"
click node_decimator "https://github.com/valmyr/skarab-gbe-control/tree/stable/without-serdes/fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi"
click node_saxis "https://github.com/valmyr/skarab-gbe-control/tree/stable/without-serdes/fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi"
click node_tmpmem "https://github.com/valmyr/skarab-gbe-control/tree/stable/without-serdes/fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi"
click node_maxis "https://github.com/valmyr/skarab-gbe-control/tree/stable/without-serdes/fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi"
click node_registers "https://github.com/valmyr/skarab-gbe-control/tree/stable/without-serdes/fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_send,node_check toneBlue
class node_phy,node_control,node_cmd,node_rx,node_rxmem,node_tx,node_decimator toneAmber
class node_saxis,node_tmpmem,node_maxis toneMint
class node_registers toneRose
class node_host,node_axiinput,node_axioutput,node_skarab toneIndigo
```

## Components

### Host Tools

- [Packet sender](https://github.com/valmyr/skarab-gbe-control/blob/stable/without-serdes/script_python/socket/exploration_socket/minimal_client.py): `script_python/socket/exploration_socket/minimal_client.py`
- [Loopback checker](https://github.com/valmyr/skarab-gbe-control/blob/stable/without-serdes/script_python/socket/autocheck_rx_rx_gen.py): `script_python/socket/autocheck_rx_rx_gen.py`

### GbE Control RTL

- **CASPER GbE block**
- [GbE controller](https://github.com/valmyr/skarab-gbe-control/tree/stable/without-serdes/fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi): `fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi`
- [Command detectors](https://github.com/valmyr/skarab-gbe-control/tree/stable/without-serdes/fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi): `fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi`
- [Legacy RX FSM](https://github.com/valmyr/skarab-gbe-control/tree/stable/without-serdes/fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi): `fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi`
- [RX buffer](https://github.com/valmyr/skarab-gbe-control/tree/stable/without-serdes/fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi): `fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi`
- [Legacy TX FSM](https://github.com/valmyr/skarab-gbe-control/tree/stable/without-serdes/fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi): `fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi`
- [TX decimator](https://github.com/valmyr/skarab-gbe-control/tree/stable/without-serdes/fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi): `fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi`

### AXI Stream

- [AXI slave FSM](https://github.com/valmyr/skarab-gbe-control/tree/stable/without-serdes/fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi): `fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi`
- [AXI RX buffer](https://github.com/valmyr/skarab-gbe-control/tree/stable/without-serdes/fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi): `fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi`
- [AXI master FSM](https://github.com/valmyr/skarab-gbe-control/tree/stable/without-serdes/fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi): `fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi`

### SKARAB Debug

- [Debug registers](https://github.com/valmyr/skarab-gbe-control/tree/stable/without-serdes/fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi): `fpgs/ethernet_one_gbe_skarab_control/ethernet_one_gbe_skarab_axi`

### Other components

- **UDP host**
- **AXI stream input**
- **AXI stream consumer**
- **SKARAB registers**

## Connections

- UDP host → Packet sender: provides payload
- Packet sender → CASPER GbE block: sends UDP
- CASPER GbE block → GbE controller: receives bytes
- GbE controller → Command detectors: examines commands
- Command detectors → Legacy RX FSM: starts reception
- Command detectors → Legacy TX FSM: starts transmission
- Legacy RX FSM → RX buffer: writes payload
- RX buffer → Legacy TX FSM: supplies payload
- Legacy TX FSM → TX decimator: decimates output
- Legacy TX FSM → CASPER GbE block: transmits payload
- TX decimator → CASPER GbE block: transmits paced data
- CASPER GbE block → UDP host: returns UDP
- UDP host → Loopback checker: provides received data
- Loopback checker → UDP host: reports comparison
- AXI stream input → AXI slave FSM: provides stream
- AXI slave FSM → AXI RX buffer: writes AXI data
- AXI RX buffer → AXI master FSM: supplies buffered data
- AXI master FSM → AXI stream consumer: emits stream
- SKARAB registers → Debug registers: accesses debug state
- Debug registers → RX buffer: reads buffer