Add IGMP Multicast Joiner and PTP Slave Core (IEEE 1588v2, Layer 3).

[enjoy-digital]

This pull request adds PTP (IEEE 1588v2) Slave support to LiteEth, along with IGMP multicast group management required for switch compatibility. It introduces an LiteEthIGMPJoiner module for multicast group registration and a complete LiteEthPTP Slave core with TSU, clock servo, protocol FSM, and monitoring — all operating over Layer 3 (UDP/IPv4) transport. This enables microsecond-level clock synchronization over standard Ethernet infrastructure using software timestamping on the master side.

All changes are fully backward compatible — IGMP and PTP are disabled by default and existing designs are unaffected.

---

Summary of Features

1. IGMP Multicast Group Joiner (core/igmp)

• LiteEthIGMPJoiner
  Periodically sends IGMPv2 Membership Reports for configured multicast groups via the IP crossbar. Allows switches with IGMP snooping to forward PTP (or other) multicast traffic to the FPGA port.

• Core Integration

  • Integrated as optional parameters (with_igmp, igmp_groups, igmp_interval) in LiteEthIPCore, LiteEthUDPIPCore, and add_etherbone.
  • Runs inside the ethcore clock domain, avoiding external CDC complexity.

2. PTP Slave Core (core/ptp)

• TSU (Time Stamping Unit)
  48-bit seconds / 32-bit nanoseconds timestamp counter with addend-based tick accumulation. Supports offset correction (phase/seconds adjust) and coarse step for initial lock.

• TX/RX Packet Handling
  Packetizer for Delay_Req/Pdelay_Req transmission with TSU TX latch on first byte. Depacketizer with PTP header/body extraction, version/domain validation, and timeout-based deadlock recovery.

• Clock Servo

  • Pipelined 7-stage computation of phase offset and path delay from E2E/P2P timestamps.
  • Phase correction via TSU offset and frequency trim via addend update.
  • Outlier detection for second-boundary artifacts.
  • Seconds adjustment via ±1e9 offset with fractional accumulator preservation.
  • Addend clamping (nominal ±1) with fractional bits preserved.
  • Shadow addend register for continuous TSU restoration against transient corruption.

• Protocol Control FSM
  Manages the full E2E/P2P exchange sequence (WAIT_SYNC → WAIT_FUP → SEND_DELAY_REQ → WAIT_DELAY_RESP → SERVE → LOCKED). Handles master IP learning, sequence ID tracking, peer/requester validation, stale Sync skip, and announce timeout.

• Snapshot-based Monitor
  Coherent CSR snapshots of PTP state (phase, delay, addend, timestamps, servo flags) for Etherbone reads. Common and debug CSR variants.

• Delay Mechanisms
  End-to-End (E2E) and Peer-to-Peer (P2P) delay measurement supported, selectable at runtime.

3. Bench Design and Test Utility

• bench/arty_ptp.py
  Minimal Etherbone + PTP Slave design for Arty A7 with IGMP, dedicated sys_eth clock domain for PTP isolation, and ptp4l master configuration instructions in the file header.

• bench/test_ptp.py
  RemoteClient-based PTP monitor with:

  • Table-style colored output with periodic column headers.
  • Debug mode for timestamps, offsets, and frequency step.
  • Summary statistics (min/max/avg phase and delay).
  • CSV export and matplotlib plotting.

---

Validation

Validated on Arty A7 with ptp4l master (software timestamping, E2E, UDP/IPv4). Steady-state phase error ±200–900ns (limited by host-side software timestamp jitter).

Unit test coverage (120 tests total):

• test/test_igmp.py — 4 tests: checksum verification, FSM hang-free operation (single/multi-group), end-to-end IGMP packet content at PHY output.
• test/test_ptp.py — 27 HDL simulation tests: TSU (counting, rollover, offset, addend), RX (depacketization, field extraction, rejection, timeout), TX (packetization, P2P mode), top-level integration (E2E exchange lock, timeout, domain filtering, error counting).
• test/test_ptp_servo.py — 89 pure-Python tests: signed delta computation, outlier detection, coarse step, frequency trim, exchange validity, queued Sync skip, seconds adjustment, addend clamping, shadow addend, TSU tick/offset race, servo convergence.

---