Clamp RSSI AXI-Lite parameters and advertise capabilities

[bengineerd]

Description

Clamp RSSI AXI-Lite local parameter writes to values the RTL can actually use, and advertise the RSSI core's build-time window and segment-buffer capabilities through reserved upper-byte register fields.

This updates RssiAxiLiteRegItf so AXI-Lite writes cannot program zero outstanding segments, zero RSSI timeout values, or more outstanding segments than MAX_NUM_OUTS_SEG_G. The existing max-segment-size clamp is preserved. The register interface now also exposes MAX_NUM_OUTS_SEG_G at 0x0C[31:24] and SEGMENT_ADDR_SIZE_G at 0x28[31:24], allowing PyRogue to discover the firmware limits instead of assuming the legacy defaults. Older firmware reads back zero in those fields, so the PyRogue model falls back to the previous defaults.

Details

This was necessary because AXI-Lite register mode lets software override the local RSSI parameters that are advertised during connection negotiation. A zero outstanding-segment window is not usable, zero timeout values break timer semantics, and a software value larger than the implemented receive window can advertise capacity the hardware does not have. The protocol-facing RTL already treated segment size as a bounded hardware capability; this change applies the same protection to the remaining timing/window fields that can make negotiation invalid.

This has usually worked until now because the generic defaults are valid, and typical software does not intentionally write zero timeout/window values. PyRogue also assumed the common legacy firmware shape, so the missing capability discovery only became visible when tests exercised invalid AXI-Lite writes or firmware was built with different window/segment generics.

The RSSI v1 RTL points at the protocol page in each source header and defines these as SYN-negotiated local parameters. In-tree documentation also states that MAX_SEG_SIZE_G is the advertised/buffered RSSI DATA payload size and that SEGMENT_ADDR_SIZE_G determines segment capacity as 2**SEGMENT_ADDR_SIZE_G * 8; see protocols/rssi/README.md. RssiCore declares MAX_NUM_OUTS_SEG_G as the receiver window capability and notes timeout recommendations in the generic list. EACK/out-of-sequence remains reserved in this RSSI v1 implementation, so the new segment-address capability is placed in the upper byte of that otherwise unused register word.

Rogue handles the software implementation at the API boundary instead of an AXI-Lite register boundary. Its controller initializes valid local defaults, rejects zero locMaxBuffers, locMaxSegment, locCumAckTout, locRetranTout, and locNullTout values in the setters, and then serializes those configured values directly into SYN headers:

• https://github.com/slaclab/rogue/blob/e30812114e7e6c338d8ab204d2ec2f61aa1527e8/src/rogue/protocols/rssi/Controller.cpp#L83-L89
• https://github.com/slaclab/rogue/blob/e30812114e7e6c338d8ab204d2ec2f61aa1527e8/src/rogue/protocols/rssi/Controller.cpp#L471-L525
• https://github.com/slaclab/rogue/blob/e30812114e7e6c338d8ab204d2ec2f61aa1527e8/src/rogue/protocols/rssi/Controller.cpp#L824-L834
• https://github.com/slaclab/rogue/blob/e30812114e7e6c338d8ab204d2ec2f61aa1527e8/src/rogue/protocols/rssi/Header.cpp#L140-L147
• https://github.com/slaclab/rogue/blob/e30812114e7e6c338d8ab204d2ec2f61aa1527e8/src/rogue/protocols/rssi/Header.cpp#L189-L198

Validation

• ./.venv/bin/python -B -m pytest -q -p no:cacheprovider tests/protocols/rssi/test_RssiAxiLiteRegItf.py
• ./.venv/bin/vsg -c vsg-linter.yml -f protocols/rssi/v1/rtl/RssiAxiLiteRegItf.vhd protocols/rssi/v1/wrappers/RssiAxiLiteRegItfWrapper.vhd
• ./.venv/bin/python -B -m py_compile python/surf/protocols/rssi/_RssiCore.py
• ./.venv/bin/python -B -m pytest -q -p no:cacheprovider tests/protocols/rssi

Related

Builds on the RSSI regression foundation and follows the same split-fix flow as the previous RSSI monitor, TX FSM, RX FSM, and connection FSM PRs.