IGMP tests

Author: bengineerd

docs/_meta/rtl_regression_handoff.md

@@ -21,7 +21,6 @@
 - Current frontier: the axi-first pass is complete, the merged branch line includes the landed `protocols/ssi` and `protocols/pgp` waves from `pre-release`, and the current Ethernet coverage now spans `EthMacCore`, `RawEthFramer`, `UdpEngine`, and `IpV4Engine`. Task selection is now user-directed rather than queue-driven, so the planning docs must track the real done/open frontier directly.
 - Current axi frontier: complete for the intended simulator-friendly pass in this branch snapshot; do not resume from the older stale `AxiResize` note.
 - Current validated-open issues:
-  - `IgmpV2Engine` still has no checked-in cocotb coverage.
   - The larger Ethernet families `GigEthCore`, `TenGigEthCore`, `XauiCore`, `XlauiCore`, `Caui4Core`, and `RoCEv2` remain untouched in phase 1.
 - Current planning discipline:
   - Use manual user-directed area selection as the active source of truth for what to work on next.
@@ -56,7 +55,7 @@
 - `tests/ethernet/EthMacCore/ethmac_test_utils.py` is now the shared home for the current Ethernet MAC slice: flat EMAC beat helpers, Ethernet/IPv4/UDP packet builders, checksum reference code, MAC-config byte-order helpers, and minimum-frame padding helpers. Reuse it instead of cloning packet or sideband plumbing across `EthMacCore` benches.
 - `tests/ethernet/RawEthFramer/raw_eth_test_utils.py` now holds the shared raw-Ethernet helper pieces: flat app-side beat helpers, raw-Ethernet header/frame builders, and lookup-handshake utilities reused by the `RawEthFramer`, `RawEthFramerRx`, and `RawEthFramerTx` benches.
 - `tests/ethernet/UdpEngine/udp_test_utils.py` is now the shared home for the UDP slice: legacy-address constants, pseudo-frame builders, DHCP option helpers, and the common cocotb bench setup for the `ArpIpTable`, `UdpEngine*`, and `UdpEngineWrapper*` wrappers. Reuse it instead of rebuilding IPv4/UDP helper glue in each test module.
-- `tests/ethernet/IpV4Engine/ipv4_test_utils.py` is now the shared home for the IPv4 slice: packet/header builders and common cocotb bench setup for the `ArpEngine`, `IcmpEngine`, and `IpV4Engine*` wrappers. Reuse it instead of cloning IPv4 framing helpers across that directory.
+- `tests/ethernet/IpV4Engine/ipv4_test_utils.py` is now the shared home for the IPv4 slice: packet/header builders and common cocotb bench setup for the `ArpEngine`, `IcmpEngine`, `IgmpV2Engine`, and `IpV4Engine*` wrappers. Reuse it instead of cloning IPv4 framing helpers across that directory.
 - The current `EthMacCore` slice is intentionally a checked-in-wrapper-first rollout, not a cocotb-generated-wrapper experiment. Keep new Ethernet work on that same pattern unless the simulator forces a very local generic adapter.
 - The XGMII import/export loopback behavior differs from the GMII path when `phyReady` drops mid-traffic: the blocked frame is retained and drains after link recovery, padded to Ethernet's minimum frame size if it was short. The GMII path drops that blocked frame. Future import/export coverage should preserve that distinction instead of forcing one common expectation.
 - `EthMacRxCsum` reliably raises `IPERR` on a bad IPv4 header checksum, but the checked-in wrapper contract does not currently require `EOFE` for that case. Keep the negative test aligned to the real observable contract rather than to a stronger assumption.
@@ -93,7 +92,7 @@ The project now also has a shared helper path in `tests/common/regression_utils.
 
 `ethernet/UdpEngine/` now has checked-in regression coverage under `tests/ethernet/UdpEngine/` as well. The current validated set covers `ArpIpTable`, `UdpEngineArp`, `UdpEngineDhcp`, `UdpEngineRx`, `UdpEngineTx`, `UdpEngine`, and `UdpEngineWrapper`, all backed by checked-in wrappers under `ethernet/UdpEngine/wrappers/` and the shared helper layer in `tests/ethernet/UdpEngine/udp_test_utils.py`.
 
-`ethernet/IpV4Engine/` now also has checked-in regression coverage under `tests/ethernet/IpV4Engine/`. The current validated set covers `ArpEngine`, `IcmpEngine`, `IpV4Engine`, `IpV4EngineDeMux`, `IpV4EngineRx`, and `IpV4EngineTx`, all backed by checked-in wrappers under `ethernet/IpV4Engine/wrappers/` and the shared helper layer in `tests/ethernet/IpV4Engine/ipv4_test_utils.py`. `IgmpV2Engine` remains the obvious uncovered gap in that slice.
+`ethernet/IpV4Engine/` now also has checked-in regression coverage under `tests/ethernet/IpV4Engine/`. The current validated set covers `ArpEngine`, `IcmpEngine`, `IgmpV2Engine`, `IpV4Engine`, `IpV4EngineDeMux`, `IpV4EngineRx`, and `IpV4EngineTx`, all backed by checked-in wrappers under `ethernet/IpV4Engine/wrappers/` and the shared helper layer in `tests/ethernet/IpV4Engine/ipv4_test_utils.py`. The `IgmpV2Engine` leaf bench covers power-up reports, general-query re-arming, and report suppression on matching inbound membership reports; it also documents the leaf-level stale pseudo-header bytes that are ignored by downstream `IpV4EngineTx` assembly.
 
 The wrapper coverage policy is now more explicit in practice: test the wrapper-specific behavior, not the full leaf matrix again. `Fifo` validated both inferred sync/async selection branches, `FifoCascade` validated public stage-vector mapping plus a curated output smoke, and `FifoMux` is currently validated only on the stable split-to-narrow path. The pack-to-wide `FifoMux` path should be treated as still open rather than silently assumed covered.
 

docs/_meta/rtl_regression_progress.md

@@ -14,7 +14,7 @@
   - The checked-in queue and override artifacts are now retained only as historical provenance and optional graph output; they are no longer the source of truth for choosing the next area.
   - Keep the done/open frontier in this progress file and in `docs/_meta/rtl_regression_handoff.md` aligned to the actual tree even if the queue artifacts are stale.
 - Known expected-open tests on this branch:
-  - `ethernet/IpV4Engine/rtl/IgmpV2Engine.vhd`: no checked-in cocotb coverage yet.
+  - No simulator-friendly expected-open leaf tests remain in the currently covered `ethernet/IpV4Engine` slice; the remaining Ethernet work is in larger untouched families such as `GigEthCore`, `TenGigEthCore`, `XauiCore`, `XlauiCore`, `Caui4Core`, and `RoCEv2`.
 - Most recent reusable bench pattern:
   - Prefer the existing subsystem shims, cocotb protocol masters/RAM models, and explicit handshake monitoring when the behavior under test includes timing-visible protocol details.
   - For `protocols/pgp`, keep the first pass family-oriented: shared Python helper coverage in `tests/protocols/pgp/pgp_test_utils.py`, family subpackages under `tests/protocols/pgp/pgp2b/`, `tests/protocols/pgp/pgp2fc/`, `tests/protocols/pgp/pgp3/`, and `tests/protocols/pgp/pgp4/`, thin wrapper-level loopback benches for the core lane/core surfaces, direct register benches for the AXI management blocks, and checked-in low-speed wrappers whose benches assert wrapper-visible lock/config behavior unless the serialized payload-recovery path is explicitly proven. `pgp3` stays documented and organized, but it is intentionally out of the near-term rollout plan on this branch. The reusable helper now also tolerates the trailing zero padding that appears on short odd-byte frames when the older 16-bit SSI/PGP2 wrappers return compressed-keep traffic through `cocotbext.axi`.
@@ -28,7 +28,7 @@
 | `dsp` | started | not started | started | The planned `dsp/generic/fixed` leaf batch is now validated under `tests/dsp/generic/`: `FirFilterTap`, `DspAddSub`, `DspComparator`, `DspPreSubMult`, `DspSquareDiffMult`, `BoxcarIntegrator`, `BoxcarFilter`, `FirFilterSingleChannel`, and `FirFilterMultiChannel`. Shared DSP helpers now live in `tests/dsp/generic/dsp_test_utils.py`, and the legacy VHDL benches under `dsp/generic/tb/` were treated as behavioral reference material rather than as execution constraints. |
 | `axi` | started | not started | started | The axi-first pass is now complete for the simulator-friendly queue. The final locally validated batch adds `AxiReadEmulate`, `AxiRingBuffer`, `AxiWriteEmulate`, `AxiStreamDmaRingRead`, `AxiStreamDmaWrite`, `AxiLiteRamSyncStatusVector`, `AxiStreamMonAxiL`, `AxiStreamDma`, `AxiStreamDmaFifo`, `AxiStreamDmaRingWrite`, and `AxiMonAxiL`, with a combined `11 passed` validation run on 2026-03-27. Added checked-in subsystem wrappers under `axi/axi4/ip_integrator/`, `axi/axi-lite/ip_integrator/`, `axi/axi-stream/ip_integrator/`, and `axi/dma/ip_integrator/` for those benches. `AxiStreamFifoV2` now has an expanded `10 passed` wrapper regression under `tests/axi/axi_stream/` covering async and sync width conversion, metadata truncation, `VALID_THOLD` frame-ready and burst-release modes, dynamic pause-threshold behavior, `CASCADE_SIZE=2`, and the `S_HAS_TREADY=0` pause-only source-side path. `AxiResize` now passes its equal-width, `32-bit -> 64-bit`, and `64-bit -> 32-bit` wrapper regression on this branch after the read-hold RTL fix. `AxiLiteAsync`, `AxiLiteToDrp`, and `AxiRateGen` still keep intentionally narrow common-clock subsets while the more timing-sensitive async AXI-Lite crossing branches remain open. `AxiStreamCompact`, `AxiStreamFrameRateLimiter`, and `AxiStreamDmaV2WriteMux` still keep intentionally narrow first-pass subsets. `AxiStreamDmaV2Read` is now validated with a two-case wrapper regression covering both aligned and short terminal-beat reads after fixing bounded byte-count conversion in `AxiPkg` and terminal-mask generation in `AxiStreamDmaV2Read`. |
 | `protocols` | started | not started | started | `protocols/line-codes` is now validated under `tests/protocols/line_codes/` with shared Python helper coverage for `LineCode8b10b`, `LineCode10b12b`, and `LineCode12b14b`, plus package-level `Code8b10b`, `Code10b12b`, and `Code12b14b` cocotb coverage. The package benches preserve explicit disparity-seed sweeps, and the 12b14b package bench also preserves its historical training/transition sequences. `protocols/ssi/` now has checked-in cocotb coverage for `SsiInsertSof`, `SsiIbFrameFilter`, `SsiObFrameFilter`, and `SsiFifo`, plus first-pass coverage for `SsiCmdMasterPulser`, `SsiCmdMaster`, `SsiFrameLimiter`, `SsiIncrementingTx`, `SsiAxiLiteMaster`, and a traffic-smoke `SsiDbgTap`, all backed by the shared SSI helper layer in `tests/protocols/ssi/ssi_test_utils.py` and checked-in wrappers under `protocols/ssi/wrappers/`. The SSI helper layer now uses handshake-based frame receive/capture so contiguous multi-beat traffic is observed correctly, the checked-in benches now carry the tutorial-style comment pass and shared setup cleanup, `SsiObFrameFilter` now covers the cached-last-user `VALID_THOLD_G=0` malformed/drop path plus a pipelined `PIPE_STAGES_G=2` pass-through case, and the remaining SSI gaps are optional deeper branch work rather than blockers. `protocols/pgp/` now has shared helper coverage in `tests/protocols/pgp/pgp_test_utils.py`, family-organized benches under `tests/protocols/pgp/pgp2b/`, `tests/protocols/pgp/pgp2fc/`, `tests/protocols/pgp/pgp3/`, `tests/protocols/pgp/pgp4/`, and `tests/protocols/pgp/shared/`, checked-in wrappers for the direct-wrapper cases, validated loopback benches for `Pgp2bLane`, `Pgp2fcLane`, `Pgp4Core`, `Pgp4CoreLite`, and `Pgp3Core`, direct wrapper benches for `Pgp2bAxi`, `Pgp2fcAxi`, `Pgp4AxiL`, `Pgp4TxLite`, `Pgp4Tx`, `Pgp4RxLiteLowSpeedReg`, the remaining non-vendor `pgp4/core/rtl` leaves (`Pgp4Rx`, `Pgp4RxEb`, `Pgp4RxProtocol`, `Pgp4TxLiteProtocol`, `Pgp4TxProtocol`, `Pgp4RxLiteLowSpeedLane`, and `Pgp4LiteRxLowSpeed`), and the shared VC FIFOs (`PgpRxVcFifo` and `PgpTxVcFifo`). The two shared FIFO benches now cover async link-up pass-through plus the family-specific control behavior: `PgpRxVcFifo` covers link-down blowoff and exported pause assertion under output backpressure, while `PgpTxVcFifo` covers link-down drop and mid-frame flush/truncation. The two `pgp4` low-speed receive leaves now have dedicated guardrail benches around lock/config behavior through checked-in wrappers rather than the earlier smoke-only placeholders, while `pgp2b/core/rtl` and `pgp2fc/core/rtl` both have leaf-wrapper cocotb coverage across every non-vendor entity. `pgp2fc` now also has fixed-latency fast-control coverage at three levels: `Pgp2fcTxPhy` checks deterministic FC entry timing from the quiescent training path plus active cell and empty-path contexts, `Pgp2fcTx` checks scheduler-context invariance, and `Pgp2fcLane` loopback calibrates `TX_FC_VALID -> RX_FC_VALID` latency once and proves that the same cycle delta holds while user frame traffic is active. The current `pgp2b` and `pgp2fc` leaf suite is intentionally mixed-depth: `Pgp2bTxSched`, `Pgp2bTxPhy`, `Pgp2bTx`, `CRC7Rtl`, `Pgp2fcAlignmentChecker`, `Pgp2fcTxSched`, `Pgp2fcTxPhy`, and `Pgp2fcTx` keep directed behavioral checks, while the remaining RX, cell, and alignment-control benches currently hold first-pass quiescent or guardrail assertions until later wrapper expansion exposes enough state for deeper deterministic traffic. |
-| `ethernet` | started | not started | started | `tests/ethernet/EthMacCore/` now covers both the original leaf slice and the deeper assembly benches for `EthMacRx`, `EthMacTx`, `EthMacRxFifo`, and `EthMacTxFifo`; `tests/ethernet/RawEthFramer/` covers the `RawEthFramer` leaves/top/pair slice, including the successful multi-beat `RawEthFramerTx` unicast-forwarding path after lookup resolution; `tests/ethernet/UdpEngine/` covers `ArpIpTable`, `UdpEngineArp`, `UdpEngineDhcp`, `UdpEngineRx`, `UdpEngineTx`, `UdpEngine`, and `UdpEngineWrapper`; and `tests/ethernet/IpV4Engine/` covers `ArpEngine`, `IcmpEngine`, `IpV4Engine`, `IpV4EngineDeMux`, `IpV4EngineRx`, and `IpV4EngineTx`. The explicit Ethernet caveats are the uncovered `IgmpV2Engine` and the larger untouched families such as `GigEthCore`, `TenGigEthCore`, `XauiCore`, `XlauiCore`, `Caui4Core`, and `RoCEv2`. |
+| `ethernet` | started | not started | started | `tests/ethernet/EthMacCore/` now covers both the original leaf slice and the deeper assembly benches for `EthMacRx`, `EthMacTx`, `EthMacRxFifo`, and `EthMacTxFifo`; `tests/ethernet/RawEthFramer/` covers the `RawEthFramer` leaves/top/pair slice, including the successful multi-beat `RawEthFramerTx` unicast-forwarding path after lookup resolution; `tests/ethernet/UdpEngine/` covers `ArpIpTable`, `UdpEngineArp`, `UdpEngineDhcp`, `UdpEngineRx`, `UdpEngineTx`, `UdpEngine`, and `UdpEngineWrapper`; and `tests/ethernet/IpV4Engine/` covers `ArpEngine`, `IcmpEngine`, `IgmpV2Engine`, `IpV4Engine`, `IpV4EngineDeMux`, `IpV4EngineRx`, and `IpV4EngineTx`. The explicit Ethernet caveats are now the larger untouched families such as `GigEthCore`, `TenGigEthCore`, `XauiCore`, `XlauiCore`, `Caui4Core`, and `RoCEv2`. |
 | `devices` | not started | not started | not started | Many vendor-heavy cases |
 | `xilinx` | not started | not started | not started | Many vendor-heavy cases |
 
@@ -250,7 +250,8 @@
 - 2026-04-10: Expanded that same `EthMacCore` slice beyond the initial happy paths. The checked-in Ethernet MAC suite now covers `EthMacTop` filter/backpressure/checksum/pause interactions, GMII and XGMII import/export plus link-not-ready recovery behavior, checksum negative cases, filter multicast/broadcast/filter-disable/multi-beat-drop behavior, shift runtime-control and control-bit propagation edges, and full byte-width `1..16` logic-path coverage for `EthCrc32Parallel`. The full `tests/ethernet/EthMacCore` directory currently passes locally with `32 passed`.
 - 2026-04-17: Expanded the `ethernet/EthMacCore` slice into the deeper assembly layer. The checked-in Ethernet MAC benches now also cover `EthMacRx`, `EthMacTx`, `EthMacRxFifo`, and `EthMacTxFifo` through the existing subsystem-local wrappers under `ethernet/EthMacCore/wrappers/`.
 - 2026-04-17: Added the manual `ethernet/UdpEngine` wave under `tests/ethernet/UdpEngine/`. The checked-in helper layer now lives in `tests/ethernet/UdpEngine/udp_test_utils.py`, the new checked-in wrappers live under `ethernet/UdpEngine/wrappers/`, and the locally validated benches cover `ArpIpTable`, `UdpEngineArp`, `UdpEngineDhcp`, `UdpEngineRx`, `UdpEngineTx`, `UdpEngine`, and `UdpEngineWrapper`. The current local validation command `./.venv/bin/python -m pytest -n 0 -q tests/ethernet/UdpEngine/test_ArpIpTable.py tests/ethernet/UdpEngine/test_UdpEngineArp.py tests/ethernet/UdpEngine/test_UdpEngineDhcp.py tests/ethernet/UdpEngine/test_UdpEngineRx.py tests/ethernet/UdpEngine/test_UdpEngineTx.py tests/ethernet/UdpEngine/test_UdpEngine.py tests/ethernet/UdpEngine/test_UdpEngineWrapper.py` passes with `7 passed`.
-- 2026-04-17: Added the manual `ethernet/IpV4Engine` wave under `tests/ethernet/IpV4Engine/`. The checked-in helper layer now lives in `tests/ethernet/IpV4Engine/ipv4_test_utils.py`, the checked-in wrappers live under `ethernet/IpV4Engine/wrappers/`, and the validated benches cover `ArpEngine`, `IcmpEngine`, `IpV4Engine`, `IpV4EngineDeMux`, `IpV4EngineRx`, and `IpV4EngineTx`. `IgmpV2Engine` remains open.
+- 2026-04-17: Added the manual `ethernet/IpV4Engine` wave under `tests/ethernet/IpV4Engine/`. The checked-in helper layer now lives in `tests/ethernet/IpV4Engine/ipv4_test_utils.py`, the checked-in wrappers live under `ethernet/IpV4Engine/wrappers/`, and the validated benches cover `ArpEngine`, `IcmpEngine`, `IpV4Engine`, `IpV4EngineDeMux`, `IpV4EngineRx`, and `IpV4EngineTx`.
+- 2026-04-17: Added `ethernet/IpV4Engine/wrappers/IgmpV2EngineWrapper.vhd` plus `tests/ethernet/IpV4Engine/test_IgmpV2Engine.py`, extending the IPv4 helper layer with IGMP packet builders in `tests/ethernet/IpV4Engine/ipv4_test_utils.py`. The new leaf bench covers power-up membership reports, general-query re-arming, and suppression of a pending local report when a matching inbound membership report is observed, while documenting the two leaf-boundary stale-field quirks that `IpV4EngineTx` ignores.
 - 2026-04-16: Merged the current `pre-release` branch into `verification-2`, so this branch line now contains the already-landed SSI and PGP waves from PR #1391 and PR #1392 in addition to the manual Ethernet slice.
 - 2026-04-16: Refreshed the planning docs to move the active frontier from “continue Ethernet next” to “refresh the stale queue/override inputs, then resume from the real merged-branch frontier.”
 - 2026-04-17: Switched the planning docs from queue-driven task selection to user-directed frontier tracking. The graph and queue artifacts remain checked in for provenance, but `rtl_regression_progress.md` and `rtl_regression_handoff.md` are now the active done/open source of truth.