Implement generic MAX2771 raw Ethernet recorder

targets/genesys2/docs/hardware_assumptions.md

@@ -0,0 +1,48 @@
+# Hardware information and assumptions
+
+## Verified board information
+
+The pin source is Digilent's official [`Genesys-2-Master.xdc`](https://github.com/Digilent/digilent-xdc/blob/00a3404901f35aa9567b01ecb3f2c233b6efe9f4/Genesys-2-Master.xdc), commit `00a3404901f35aa9567b01ecb3f2c233b6efe9f4`. The official board definition names part `xc7k325tffg900-2` and the system oscillator as 200 MHz. The [Genesys 2 reference manual](https://digilent.com/reference/_media/reference/programmable-logic/genesys-2/genesys2_rm.pdf) identifies the PHY as RTL8211E-VL.
+
+| Function | FPGA pin | Standard | Notes |
+|---|---|---|---|
+| `sysclk_p/n` | AD12 / AD11 | LVDS | 200 MHz differential oscillator |
+| `cpu_resetn` | R19 | LVCMOS33 | active-low board reset |
+| MDC / MDIO | AF12 / AG12 | LVCMOS15 | PHY address strapped to 1 |
+| RGMII TXC | AE10 | LVCMOS15 | Bank 33, 1.5 V |
+| RGMII TXD[0:3] | AJ12, AK11, AJ11, AK10 | LVCMOS15 | in vector order |
+| RGMII TXCTL | AK14 | LVCMOS15 | no TX error is generated |
+| PHY reset | AH24 | LVCMOS33 | active low |
+| PHY INTB / PMEB | AK16 / AK15 | LVCMOS18 | open-drain; not used by this design |
+| RGMII RXC | AG10 | LVCMOS15 | receive path not implemented |
+| RGMII RXCTL | AH11 | LVCMOS15 | receive path not implemented |
+| RGMII RXD[0:3] | AJ14, AH14, AK13, AJ13 | LVCMOS15 | receive path not implemented |
+| LEDs[0:7] | T28, V19, U30, U29, V20, V26, W24, W23 | LVCMOS33 | user status LEDs |
+
+The reference manual states that the board straps auto-negotiation on, advertises 10/100/1000 modes, selects PHY address `00001`, and selects no PHY-internal RGMII RX or TX delay. It also shows a 25 MHz PHY crystal; the FPGA does not supply the PHY reference clock.
+
+The RTL8211E datasheet requires PHYRSTB low for at least 10 ms and a further 30 ms before register access. The RTL implements both intervals. Link gating polls PHY-specific status register `0x11`; transmit is enabled only when bits `[15:14]=10` (1000 Mb/s), bit 13 (full duplex), bit 11 (resolved), and bit 10 (real-time link) are all set.
+
+## Assumptions from the specification
+
+- `rf_clk_pmod` is nominally 32.736 MHz.
+- A four-bit word is valid on every configured sampling edge.
+- Default capture is rising-edge and default packing is earlier-sample-high-nibble.
+- JA is a 3.3 V interface and the MAX2771-side signals presented to JA are electrically compatible with LVCMOS33.
+- Ethernet destination is broadcast and source is the fixed locally administered address `02:27:71:00:00:01`.
+
+## MAX2771 datasheet confirmation required
+
+- Confirm the selected MAX2771 digital-output mode really produces one complete four-bit word per RF clock edge.
+- Confirm output voltage, drive strength, clock polarity, setup, hold, and clock-to-output limits for the exact supply and load.
+- Confirm whether the default rising capture edge is the center of the valid data eye. Change `CAPTURE_RISING` only after that check.
+- Confirm whether the four bits represent the desired channel/order. RTL records `[3:0]` literally and deliberately does not reinterpret it.
+
+## Measurement required
+
+- Measure MAX2771 clock-to-data timing at the Genesys 2 JA pins, including cable/adapter skew. Put the resulting min/max values into the commented `set_input_delay` commands in the XDC.
+- Measure the four data-line skews if wiring is not length matched.
+- Verify the forwarded RGMII TX clock is centered approximately 2.0 ns after TXD/TXCTL transitions at the PHY pins. The MMCM provides the nominal shift; board trace and I/O delay still deserve hardware measurement.
+- Confirm clean 3.3 V levels, ground return, edge quality, and absence of overshoot at JA before long captures.
+
+No unverified board pin has been inserted into the constraints.

targets/genesys2/docs/timing_constraints.md

@@ -0,0 +1,42 @@
+# Timing constraints and closure
+
+## Clock plan
+
+| Clock | Source | Frequency / period | Use |
+|---|---|---|---|
+| `sys_clk_200` | AD12/AD11 LVDS oscillator | 200 MHz / 5.000 ns | MMCM input |
+| `clk125_i` | MMCM VCO 1000 MHz, divide 8 | 125 MHz / 8.000 ns, 0° | packetizer, MAC, MDIO, RGMII data ODDR |
+| `clk125_90_i` | same MMCM output divide | 125 MHz / 8.000 ns, +90° | forwarded RGMII TXC ODDR |
+| `rgmii_txc` | ODDR from `clk125_90_i` | 125 MHz, +2.000 ns | PHY source-synchronous clock |
+| `mdio_mdc` | counter from 125 MHz | 2.5 MHz | Clause-22 management |
+| `rf_sample_clk` | U27 | 32.736 MHz / 30.547 ns | MAX2771 capture and FIFO write |
+
+The RTL8211E is strapped with TX delay disabled. Therefore the FPGA creates RGMII-ID source-clock skew: GMII/RGMII data changes from ODDRs clocked at 0°, and TXC changes from an ODDR clocked at +90°. At 125 MHz, 90° is 2.000 ns. RGMII TX output delays use the standard 1.0 ns setup/1.0 ns hold receive budget around that centered clock edge.
+
+## CDC exceptions
+
+The RF and Ethernet clocks are asynchronous. The only crossings are:
+
+- FIFO write/read Gray pointers, each through two `ASYNC_REG` stages;
+- the Gray-coded cumulative drop counter, through two `ASYNC_REG` stages;
+- a toggle-based sample-activity indicator, through two `ASYNC_REG` stages;
+- reset synchronizers with asynchronous assertion and synchronous deassertion.
+
+The XDC asynchronous clock grouping is valid because no ordinary data/control logic crosses those groups. The multi-bit FIFO data is stored in true dual-clock block RAM and is read only under synchronized pointer control; it is not sampled as a combinational bus crossing.
+
+Vivado reports CDC-6 for the three intentionally Gray-coded buses even when it recognizes their two ASYNC_REG stages. The build script accepts only named FIFO/drop-counter instances and fails for any other Warning or Critical CDC object.
+
+## MAX2771 input delay boundary
+
+The clock is constrained to 30.547 ns and the input registers are forced into IOBs. The project does **not** claim RF input setup/hold sign-off yet: neither the task input nor the Genesys 2 documentation provides MAX2771 `tCO`, cable delay, or inter-bit skew. The XDC contains conspicuous placeholder commands rather than fabricated numbers.
+
+Before hardware sign-off:
+
+1. derive earliest/latest data arrival at each FPGA pin from the MAX2771 datasheet;
+2. add measured cable/adapter and bit-to-bit skew;
+3. replace the placeholder max/min values in the XDC;
+4. rerun `make genesys2-build` and inspect
+   `build/genesys2/reports/timing_post_route.rpt`;
+5. verify the eye with an oscilloscope or logic analyzer at JA.
+
+The current 2026.1 build routes successfully with setup WNS `+0.212 ns` and hold WNS `+0.090 ns` for constrained paths. These numbers do not replace the missing external RF input-delay model.