Project overview
This personal project explores how an FPGA can inspect Ethernet frames, extract useful header fields, apply rules, and forward or drop packets. The reusable engine uses a 32-bit AXI-Stream interface and reuses the existing AdeelLib AXI-Stream master and slave modules.
The original Zybo demonstration generates four kinds of 96-byte frames internally: IPv4 UDP, IPv4 TCP, IPv6 UDP, and IPv6 TCP. A transmit checker compares the forwarded frames against their expected contents, while a 720p HDMI dashboard displays counters and the latest header information. No processor software is needed.
Key features
- Ethernet II parsing with support for one VLAN tag.
- IPv4 and IPv6 identification, source/destination IP extraction, and UDP/TCP port extraction.
- Received frame length, packet and byte counters, protocol totals, drops, invalid frames, and rule matches.
- Four configurable rules by default, with masked IP, protocol, and port fields; the lowest matching rule index wins.
- Pass, drop, swap source/destination MAC addresses, or replace the destination MAC address.
- Atomic rule updates and a per-frame rule snapshot so configuration stays consistent during processing.
- Multiple registered parsing stages and AXI-Stream backpressure handling.
High-level architecture
The engine stores one complete frame before choosing an action. This prevents a packet selected for dropping from leaking an initial header to TX. The default frame capacity is 2,048 bytes. A synchronous RAM read feeds the modifier and transmit stage; capture and replay do not overlap.
Header extraction is divided into IP alignment, IP extraction with transport alignment, and UDP/TCP validation stages. Counters record classification decisions separately from accepted transmission: a decision does not mean a stalled packet has already left the engine.
Interface architecture
Each stream uses 32-bit data, four byte-enable bits, a last-beat marker, and valid/ready handshaking. A transfer occurs when valid and ready are both asserted; the sender holds data, keep, last, and valid stable while stalled. The core runs in one clock domain. This demonstration connects an internal packet source and TX checker, with rule configuration and metadata feeding the HDMI dashboard. It does not include an Ethernet MAC or an RJ45 traffic path.
Trying the board demonstration
The documented setup needs the original Zybo XC7Z010, programming USB, power, and a monitor accepting 1280 × 720 video. Start with all switches off.
- SW2: enable a rule matching UDP destination port 53 for both IP families.
- SW1:0: select pass, drop, swap MAC addresses, or replace the destination MAC for matching frames.
- SW3: throttle TX acceptance to one cycle in sixteen to exercise backpressure.
- BTN0: reset the engine, counters, source, and video.
- BTN1: clear counters while packet processing continues.
The dashboard presents twelve cumulative hexadecimal counters, the latest addresses and ports, received frame length, and TX-checker errors. Values are snapshotted during video blanking.
Verification recorded in the repository
The validation record dated 8 October 2026 reports nine passing Ethernet tests, portable synthesis, a routed reusable-core check, and a complete board implementation with bitstream generation. Tests cover forwarding and MAC rewrite, stalls, rule priority, mid-frame configuration, counters, VLAN, IPv4 options, partial final beats, malformed traffic, reset, and recovery.
| Metric | Reusable core | Complete board demo |
|---|---|---|
| Clock target | 125 MHz | 74.21875 MHz |
| Setup slack | +0.087 ns, internal paths | +0.393 ns |
| Hold slack | +0.050 ns, internal paths | +0.048 ns |
| LUTs | 4,597 | 4,984 |
| Registers | 8,474 | 3,932 |
| Frame memory | One RAMB18E1 | One RAMB18E1 |
The reusable-core result covers internal register-to-register timing. Its virtual boundary ports showed hold violations in the full boundary summary; a real MAC or DMA integration must close its own interface timing. The complete board demo reports no failing setup or hold endpoints, no DRC errors, and sixteen DRC warnings involving reused video DSP pipelining, RAM reset controls, and the PL-only configuration.
These are repository-recorded results, not checks rerun for this website update. Physical HDMI operation and Ethernet traffic testing remain pending.
What “high-speed” means here
A 32-bit interface at 125 MHz has a theoretical peak of 4 Gb/s. The single-frame store-and-forward architecture has lower sustained throughput because reception and transmission do not overlap. The documented finite simulation processed 32 × 96-byte frames in 2,217 cycles with patterned TX stalls: approximately 1.386 Gb/s of frame bytes at 125 MHz, excluding preamble, FCS, and interframe gap. This is a simulation result, not a physical link measurement or a worst-case guarantee.
Scope and integration limits
The original Zybo’s onboard Ethernet PHY connects to the Zynq processing system. This PL-only demo does not process traffic from the RJ45 connector and does not include an Ethernet MAC. A real network connection requires a separate MAC or PS/DMA adapter, receive buffering, and physical interface validation.
The engine supports variable IPv4 header length and the fixed IPv6 base header. IPv4 fragmentation and selected IPv6 extension/security headers are rejected; nested VLAN tags and IPv6 jumbograms are unsupported. It does not validate checksum contents, track TCP connections, or perform IP NAT. MAC-only edits preserve the IP and transport checksums; a downstream MAC must generate a new Ethernet FCS.
It is an educational packet-processing baseline with configurable rules, rather than a complete firewall or a demonstrated 10GbE system.