wireguard_fpga/docs/core/parser.md

Parser

The parser must parse the following packet:

EthernetII | IPv4 | UDP | WireGuard

From this packet type, we must parse the Following:

1. Dest Mac address
2. Source Mac Address
3. Ethertype
4. Source IP address
5. Destination IP address
6. Protocol
7. UDP Source port
8. UDP Destination Port
9. Wireguard Message Type
10. Wireguard Receiver Index
11. Wireguard Counter

These fields all go to metadata lookup to determine the destination and operations to perform on the packet.

The parser works by analyzing the packet 32 bits at a time as it flows in. It uses a state machine which keeps track of the position in the packet, and based on what it sees it updates the fields. Here are the states:

State	Desciption
ETH_1	Upper 32 bits of Dest Mac
ETH_2	Lower 16 bits of Dest Mac, Upper 16 bits of source mac
ETH_3	Lower 32 bits of Source Mac
ETH_4_IP_1	Ethertype and first 16 bits of IP. Version, IHL, DCSP, ECN
IP_2	Total Length, Identification
IP_3	Flags, Fragment Offset, TTL, Protocol
IP_4	Header Checksum, upper 16 bits of source ip
IP_5	lower 16 bits of source ip, upper 16 bits of dest ip
IP_6_UDP_1	lower 16 bits of dest ip, UDP Source port
UDP_2	Destination Port, Length
UDP_3_WG_1	Checksum, Message Type
WG_2	lower 16 bits of receiver index
WG_3	upper 16 bits of receiver index, lower 16 bits of counter
WG_4	middle 32 bits of counter
WG_5	upper 16 bits of counter
IDLE	Do nothing until the packet ends

As we parse, if we detect that the packet no longer follows the pattern, for example if the protocol is not UDP or the Ethertype is not IPv4, then we set as many fields as we parsed, for example if the protocol is TCP we would set the ethernet mac addresses, the ethertype, ip addresses, and protcol, but the udp ports and wireguard ports would all be 0. The outputs will either match the metadata rules or not, so we don't care in this block.

The pattern specifically is IPv4 Ethertype (No VLAN), IHL 5 (No options), UDP protocol, Wireguard dest port, and wireguard message type 4.