max2771-raw-ethernet-recorder/docs/raw_ethernet_protocol.md

MAX2771 raw Ethernet protocol

This protocol is Ethernet Layer 2 only. It has no IP, ARP, DHCP, ICMP, UDP, or TCP component.

Ethernet envelope

Item	Value
Preamble	seven bytes 55
SFD	D5
Destination	FF:FF:FF:FF:FF:FF
Source	02:27:71:00:00:01
EtherType	0x88B5, most-significant byte first
Maximum Ethernet payload	1500 bytes
VLAN / jumbo frames	not used
FCS	reflected Ethernet CRC-32, inverted, least-significant byte first
IFG	at least 12 byte times

The CRC is initialized to 0xFFFFFFFF, updated LSB-first over destination MAC through the final payload or pad byte with reflected polynomial 0xEDB88320, then inverted. Preamble and SFD are not part of the CRC. Linux NICs normally remove preamble, SFD, and FCS before an AF_PACKET application receives the frame.

Custom payload header

All multibyte header fields use network byte order. The fixed header is exactly 32 bytes.

Offset	Size	Field	Encoding
0	4	magic	ASCII MX27 (4D 58 32 37)
4	1	version	1
5	1	flags	described below
6	2	header length	0x0020
8	4	data-frame sequence	unsigned, wraps modulo 2^32
12	8	first sample index	unsigned absolute RF sample index
20	2	sample count	number of real 4-bit samples in this frame
22	1	bits per sample	4
23	1	packing format	1 for earlier sample in high nibble
24	4	dropped sample count	cumulative FPGA count, low 32 bits
28	4	reserved	zero

Flags are:

Bit	Meaning
0	FIFO overflow/input loss occurred since the previous reported packet
1	first data packet after FPGA reset
2	first data packet after the PHY reports a resolved 1000BASE-T full-duplex link
7:3	zero

Normal frames contain a 32-byte custom header and 1468 data bytes: exactly 2936 samples. Sequence increments once per transmitted data frame. A sample with index N followed by N+1 is contiguous regardless of nibble values.

Packing

For samples S0, S1, S2, S3, each limited to four bits, data bytes are:

byte 0 = {S0[3:0], S1[3:0]}
byte 1 = {S2[3:0], S3[3:0]}

There is no sign extension, I/Q interpretation, bit reversal, or numeric conversion. An exceptional overflow boundary can close a short frame. If its sample count is odd, the unused low nibble of the final frame byte is zero and is not a sample. The host parser uses sample_count, so it never writes that pad nibble.

Loss semantics

Each FIFO entry carries its absolute 64-bit input sample index. The packetizer compares adjacent entries. If a full-FIFO interval creates an index discontinuity, it closes the pre-gap packet as an exceptional partial frame and begins the next packet at the first post-gap index. This makes the missing interval visible to the host. It never silently crosses a gap inside a packet.

Packet-sequence gaps indicate frames lost after the FPGA MAC. Sample-index gaps indicate missing sample time, whether due to an FPGA overflow or a lost Ethernet frame. The cumulative drop field distinguishes FPGA-side input loss. The receiver extends the low-32-bit drop count across wraps while it is running.