Add RSSI protocol regression coverage and RTL fixes#1427
Draft
bengineerd wants to merge 46 commits into
Draft
Conversation
- Introduced new documentation files for RSSI protocol classes including Application, Client, Controller, Header, Server, and Transport. - Added Python API references for the RSSI protocol classes. - Created a comprehensive overview of the UdpRssiPack class, detailing its purpose, implementation, and usage scenarios. - Developed detailed documentation for the RSSI protocol, including key classes, lifecycle management, and threading considerations. - Added a thorough RTL specification review document highlighting compliance risks and regression targets for the RSSI implementation.
…date RX test to leverage existing utilities
…ions; add known-issue characterization for DATA TKEEP validity.
…ng current decoded header flags.
- Mark Phase 2 implementation as complete in progress.md - Add detailed coverage for RX control/header-drop scenarios in test_RssiRxFsm.py - Introduce tests for acceptance of NULL segments and handling of malformed headers - Adjust handoff.md to reflect the transition to Phase 3 RssiCore integration
- Updated `RssiTxFsm` to suppress NULL requests while DATA is unacknowledged. - Extended tests to verify retransmission and recovery of dropped/corrupted DATA frames. - Added validation for checksum failures and ensured proper handling of retransmitted payloads.
- Introduced `RssiCoreWrapperMultiStreamIntegrationWrapper` to handle two application streams with interleaved traffic. - Updated `handoff.md` and `progress.md` to reflect new multi-stream wrapper and its integration tests. - Created `README.md` for the `rssi` directory detailing usage and configuration of `RssiCoreWrapper`. - Added `test_RssiCoreWrapperMultiStream.py` to validate multi-stream functionality and connection status. - Updated `README.md` in the protocols directory to link to the new `rssi` documentation.
…terization and update related tests
…g test timing and enhancing coverage
…ransport interfaces and enhance multi-stream loss coverage in tests
- Added RSSI conformance pass for parameter range validation, BUSY cadence, cumulative ACK window release, max-retransmit RST/close behavior, and duplicate DATA suppression coverage. - Updated `RssiAxiLiteRegItf` to clamp writable runtime parameters, ensuring illegal values are not accepted. - Enhanced `RssiConnFsm` to reject invalid SYN/SYN+ACK parameters, ensuring only valid peer parameters are negotiated. - Modified `RssiMonitor` to implement periodic local-BUSY ACK requests based on the RSSI page's recommended Retransmission Timeout/2. - Introduced default coverage for cumulative ACK release of multiple TX segments and runtime register clamps. - Added opt-in direct-core probes for integrated BUSY advertisement and strict no-extra-output checks after DATA retransmission recovery. - Updated tests to validate new behaviors, including writable parameter clamps, rejection of out-of-range SYN parameters, and handling of duplicate DATA drops. - Enhanced `RssiCore` register model to expose writable RSSI parameter ranges, preventing software-side verify mismatches. - Improved test coverage for retransmission and recovery scenarios, ensuring compliance with updated protocol specifications.
…obes to default coverage; enhance application output backpressure handling in RssiCore and update related tests.
…tegrate new protocol functions across test files
…rences to reflect EACK as reserved/unsupported, and add standalone ACK+EACK rejection test coverage.
…terfaces in RssiCoreIntegrationWrapper, enhance cocotb loopback handling, and add checksum-disabled RX test coverage.
…urpose, DUT shape, stimulus, checks, and timing for improved readability and understanding.
This was referenced May 28, 2026
- Updated README.md to reflect current status and testing coverage for RSSI regression suite, including details on recent expansions and test strategies. - Expanded handoff.md with details on the 2026-05-28 follow-up, including new coverage areas and validation results. - Added a new section in progress.md to document the 2026-05-28 test-suite expansion follow-up, detailing implemented regression items and validation results. - Enhanced protocols/rssi/README.md to clarify test coverage and current EOFE behavior in the regression suite. - Modified RssiCoreIntegrationWrapper.vhd to expose a flattened client AXI-Lite bus for improved integration testing. - Updated test_RssiCore.py with new tests for multi-beat partial `TKEEP`, BUSY recovery, close/reopen lifecycle, AXI-Lite control path, checksum-disabled integration, and transport-output ready stalls. - Added new tests in test_RssiCoreWrapper.py and test_RssiCoreWrapperMultiStream.py for partial-`TKEEP` coverage and EOFE preservation. - Introduced utility function data_mask_from_keep in ssi_test_utils.py to facilitate valid byte preservation checks in tests.
bengineerd
changed the title
… VHDL-93 Vivado synthesis defaults to VHDL-93 for files loaded without an explicit fileType in ruckus.tcl. The conditional signal assignment introduced in e6151de is only legal in VHDL-2008. Refactor to a sequential if/else so the file remains synthesizable under the legacy LRM. Behavior unchanged.
2 tasks
…AXIL Map the build-time generics into the previously unused upper byte of the existing RSSI AXI-Lite registers: 0x0C[31:24] -> MAX_NUM_OUTS_SEG_G 0x28[31:24] -> SEGMENT_ADDR_SIZE_G Older firmware reads back 0 in those bits, so software can detect a legacy bitfile and fall back to compile-time defaults instead of forcing every application to thread per-instance generics through to the rogue device tree. No new register space is consumed and the [7:0] / [23:16] fields keep their original meaning, so existing software is unaffected.
…sters Drop the maxNumOutsSeg and segmentAddrSize constructor arguments from RssiCore. Applications routinely forgot to update them when changing the firmware generics, leaving the rogue tree out of sync with what the FPGA actually supported. Instead, read the build-time capability advertised in 0x0C[31:24] and 0x28[31:24] from _start() once a link is reachable and update the maximum hints on locMaxOutsSeg and locMaxSegSize in place. Older firmware reads zero in those bits and the driver falls back to the legacy defaults (8 outstanding segments, 1024-byte segment). BREAKING CHANGE: callers passing maxNumOutsSeg= or segmentAddrSize= must remove those keyword arguments; the values are now discovered at link bring-up.
…eives and reducing fixed capture cycles in multi-stream tests
…enhancing multi-stream tests and adding conditional execution for extended cases
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds a comprehensive RSSI v1 cocotb regression suite for the SURF RSSI RTL, plus the narrow RTL fixes needed to make the implementation match the documented SURF/Rogue RSSI hardware profile.
Details
This RSSI-focused slice adds protocol references, checked-in cocotb wrappers, reusable RSSI Python helpers, directed leaf-FSM tests, integrated
RssiCoretests, wrapper tests, PyRogue register-map alignment, and RSSI user documentation.Test Suite
The new tests under
tests/protocols/rssi/cover the RSSI stack from leaf blocks through integrated endpoint pairs:RssiChksum: checksum generation and validation against a Python one's-complement oracle, including reset/enable restart behavior.RssiHeaderReg: ACK, DATA, NULL, RST, and SYN header byte layout, flags, sequence/ack fields, checksum placeholders, and SYN parameter packing.RssiRxFsm: receive-side DATA/SYN/ACK/NULL/RST screening, checksum behavior, illegal flag rejection, unsupported EACK rejection, out-of-order and duplicate DATA behavior, SYN parameter staging, and checksum-disabled behavior.RssiTxFsm: ACK/DATA/NULL/RST/SYN emission, sequence consumption, checksum insertion, checksum fault injection, multi-word DATA buffering/resend, cumulative ACK window release, and NULL suppression while data is outstanding.RssiMonitor: retransmit timeout behavior, remote/local BUSY handling, periodic BUSY ACK cadence, and server null-timeout liveness rules.RssiConnFsm: client/server connection setup, peer parameter validation, retry behavior, timeout closure, parameter mismatch rejection, and client RST behavior.RssiAxiLiteRegItf: reset defaults, writable parameter readback, local parameter clamping, negotiated/status/counter/state readback, sequence/ack readback, and AXI-LiteDECERRbehavior.RssiCore: integrated client/server active open, negotiated segment-size readback, bidirectional payload delivery, DATA loss/corruption recovery, duplicate-free ACK/NULL perturbation, out-of-order recovery, sequence wrap, NULL keepalive acknowledgment, missing keepalive close, max retransmit close/RST, explicit close, and BUSY reporting from application backpressure.RssiCoreWrapper: one-stream wrapper coverage in bypass-chunker and packetizer modes across multiple window and segment-size configurations.RssiCoreWrapperMultiStream: packetizer2/depacketizer2 multi-stream routing, bidirectional two-stream payload delivery, and routed-payload recovery after a dropped RSSI DATA frame.The checked-in wrappers under
protocols/rssi/v1/wrappers/flatten record-heavy RSSI interfaces for cocotb while keeping protocol stimulus and scoreboards in Python. The shared helper layer intests/protocols/rssi/rssi_test_utils.pyowns RSSI header builders/parsers, SYN parameter packing, checksum helpers, transport-frame capture, and reusable VHDL source lists.The branch also adds
protocols/rssi/README.md, local RSSI/RUDP/Rogue reference material underdocs/plans/rssi-regression/references/, and task notes documenting the test plan, progress, RTL review input, and implemented RTL changes.RTL Changes And Rationale
The production RTL changes are intentionally narrow and tied to failures or contract gaps exposed by the new regressions:
RssiMonitor.vhd: server null-timeout liveness now refreshes only on received DATA or NULL, not standalone ACK/BUSY traffic. The RSSI protocol describes the server null timeout as detecting absence of DATA/NULL keepalive traffic; ACK/BUSY-only traffic should not keep a dead peer alive indefinitely.RssiMonitor.vhd: local BUSY now generates an immediate ACK on assertion and periodic BUSY ACKs at Retransmission Timeout/2 while busy. This matches the RSSI flow-control guidance and keeps the peer transmitter from entering retransmission/RST while the local receiver is intentionally backpressured.RssiCore.vhd: local BUSY now includes application-output pause and direct downstreamTREADYbackpressure in addition to the existing FIFO write-count threshold. This lets integrated cores advertise BUSY when the application sink is stalled before the peer transmitter advances into retransmit behavior.RssiCore.vhd: output FIFO pause thresholds are clamped to at least 1 for small segment-size configurations.RssiCoreWrapperderivesSEGMENT_ADDR_SIZE_GfromMAX_SEG_SIZE_G; without the clamp, 64-byte and 128-byte wrapper configurations could elaborate with an illegal zero/negativeAxiStreamFifoV2pause threshold.RssiConnFsm.vhd: peer SYN/SYN+ACK parameters are validated before negotiation converts them into integer window/buffer state. Zero outstanding-segment counts, zero timeouts, and sub-8-byte segment sizes are rejected or reproposed instead of causing illegal state or simulator range errors.RssiConnFsm.vhd: retry wait counters now saturate at the retransmission timeout threshold. This preserves the existing retry/close decisions while preventing constrained-counter overflow at the timeout boundary in simulation.RssiAxiLiteRegItf.vhd: software-written local parameters now clampmaxOutsSegand timeout fields to legal nonzero ranges. This keeps AXI-Lite-programmed local parameters inside the same validity boundary enforced during peer negotiation.RssiTxFsm.vhd: checksum fault injection now corrupts only the checksum field and applies consistently to ACK, NULL, DATA, and resend headers. The documented debug feature is a one-shot header-checksum corruption, not a full 64-bit header inversion that changes flags, lengths, sequence, or ACK fields.RssiTxFsm.vhd: NULL generation is suppressed while the transmit buffer contains unacknowledged DATA/NULL/RST. NULL is idle keepalive traffic; allowing it to consume the next sequence while earlier DATA is outstanding can let a receiver advance past the lost DATA and then reject the DATA retransmit as old.RssiRxFsm.vhd: DATA legality checks now use the current decoded header flags and reject DATA without ACK, DATA with BUSY/NULL/RST/EACK semantics, and unsupported non-SYN EACK segments. This avoids accepting invalid DATA because of stale registered flag state and makes the unsupported EACK path drop explicitly.RssiRxFsm.vhd: SYN parameters are staged and committed only after the full SYN passes checksum, length, flag, and frame-boundary checks. Malformed SYN frames can no longer partially updaterxParam_obefore being dropped.RssiRxFsm.vhd: DATA EOF length calculation, payload write-data staging, and application-output read timing were corrected for the registered payload RAM path used by integratedRssiCore. This fixes one-word payload length/read timing errors observed only in the integrated core path.RssiRxFsm.vhd: duplicate DATA is dropped before entering the payload-buffering state. Duplicate or out-of-order DATA is not queued in the SURF RSSI hardware profile; recovery comes from retransmission of the missing in-order segment.The PyRogue RSSI model in
python/surf/protocols/rssi/_RssiCore.pyis updated to align descriptions and writable parameter ranges with the RTL-visible register behavior.Validation
The branch records focused validation in the RSSI task notes, including local runs of the RSSI cocotb tests, syntax checks, VHDL style checks for edited RTL/wrappers, and focused integrated
RssiCore/wrapper tests for the bugs and contract points above.Related
Depends on #1426, which depends on #1425.