# 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:

```text
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.