docs: fix TC18.txt citation drift in e2e.rs (issue #164 batch 4, final) - #168
Merged
Merged
Conversation
Final batch of issue #164: re-verifies every TC18.txt citation in e2e.rs's doc/test comments (REQ-CRC group) against the current canonical TC18.txt, individually. Unlike batches 1-3, most of this file's citations needed more than a line-number relocation — TC18's §13.6 "End-to-End data protection" section was substantively reworded between RC4 and RC5 (TC18.txt carries `Commented [BE35]`-`[BE41]` revision markers throughout this section), not just re-paginated. Cleanly relocated (same underlying fact, confirmed by exact/near-exact text match): - Table 31 "CRC32 Polynomial" -> Table 34 (genuine renumber; content unchanged - same six parameters/values, TC18.txt lines 4193-4208). "Table 31" now names an unrelated table (ep_generic_config register map). - "the CRC32 is ACF specific... for each ACF type individually" (old TC18.txt line 3789) -> reworded, same fact, at TC18.txt line 4191: "In Safe command mode a CRC32 is calculated per ACF type across specific fields of an AVTPDU header, ACF header, and the entire payload (except padding)." - "The CRC calculation for request and response follows the identical scheme" (old line 3808) -> near-verbatim at TC18.txt line 4276 ("requests and responses"). Flagged, deliberately NOT resolved (genuine RC4/RC5 content changes, not just relocatable citations - see PR description for full rationale): - The acf_msg_length +1 quadlet rule's citation (old line 3798) survives reworded at TC18.txt line 4272, but its second clause (ntscf_data_length/stream_data_length +4 octets per ACF type, backing requirement REQ-CRC-016) has no surviving textual counterpart anywhere in current TC18.txt - full-text search finds nothing. Left as an honest flag rather than fabricating a citation for a rule that may no longer exist in the spec. - The fragmented-CRC "first AVTPDU/ACF header" rule (old line 3801, backing the known REQ-CRC-015 divergence) is genuinely gone, not reworded - the current text (TC18.txt lines 4274-4275) no longer states which fragment's header the CRC covers at all, which may moot or restate REQ-CRC-015's premise. Flagged, not resolved. - Figure 19 (ACF_ABB) / Figure 20 (ACF_GBB) worked examples are renumbered to Figure 20/21, and the ACF_GBB example's content changed too (different payload/pad byte split under a `Commented [BE39]: 051RC4 - text and figure updated` marker), mirroring src/acf.rs's own equivalent, already-fixed finding (issue #164 batch 1). Test names/assert strings that embed the old figure numbers and the old ACF_GBB byte split are left untouched (renaming a test or its golden vectors is a code/test-logic change, out of scope for a citation-only fix) - flagged via doc-comment notes instead. Doc-comment-only change: cargo build/cargo test --lib unaffected (1168 tests pass, unchanged), cargo fmt --check clean, no public API or .fusa-reqs.json change. Signed-off-by: SoundMatt <47545907+SoundMatt@users.noreply.github.com> Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Signed-off-by: Matt <47545907+SoundMatt@users.noreply.github.com>
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
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.
Summary
Final batch of issue #164 (batches 1-3: #165, #166, #167, all merged). This
covers the last flagged file,
src/e2e.rs(REQ-CRC group), which the issueexplicitly called out as needing more than a mechanical line-number
relocation: TC18 §13.6 "End-to-End data protection (safe endpoints)" was
substantively reworded between RC4 and RC5 revisions — TC18.txt itself
carries
Commented [BE35]through[BE41]revision markers throughout thissection, confirming the underlying spec text changed, not just its
pagination.
Every TC18.txt citation in
e2e.rs's doc/test comments was re-verifiedindividually against the current canonical TC18.txt (not trusted from any
in-repo copy — none exists there). Per the task brief, citations that
genuinely could not be cleanly resolved were left as honest, explicit flags
rather than guessed at — this file backs REQ-CRC (frame-integrity /
safety-relevant) entries, so a wrong citation is worse than an admitted gap.
Doc-comment-only change.
cargo build/cargo test --lib: 1168 testspass, unchanged from batches 1-3.
cargo fmt --check: clean.git diff --stat: onlysrc/e2e.rstouched. No.fusa-reqs.jsonor test-logicchanges.
Cleanly relocated citations
sed -n 'N p' TC18.txt)TC18.txt line 3792, "Table 31 CRC32 Polynomial"CRC32P4; six parameters (Polynomial0xF4ACFB13, Width 32, Initial Value/Final XOR0xFFFFFFFF, Input/Output reflection TRUE)TC18.txt line 4193(sentence) / caption atline 4208, table body4193-42074193: 13 The CRC will use the CRC32P4 defined by:/4208: 14 ... Table 34: CRC32 Polynomial. Genuine table renumber: current "Table 31" now names an unrelated table ("ep_generic_config register map",line 3980). Six parameter values confirmed unchanged.TC18.txt line 3789: "the CRC32 is ACF specific, which means it is calculated for multiple ACF types in one AVTPDU for each ACF type individually"TC18.txt line 4191(reworded, same fact)4191: 11 In Safe command mode a CRC32 is calculated per ACF type across specific fields of an AVTPDU header, ACF header,TC18.txt line 3808: "The CRC calculation for request and response follows the identical scheme"TC18.txt line 4276(near-verbatim; singular→plural)4276: 14 The CRC calculation for requests and responses follows the identical scheme.(this line itself carries aCommented [BE39]: 051RC4 - text and figure updatedmarker, confirming the RC4 touch-point even though the actual wording only trivially changed here)Each of these facts appears twice in the file (once in a
///doc comment,once in the corresponding
//test comment); both occurrences of each wereupdated identically.
NOT cleanly resolved — flagged, not fixed
These are the substantive part of this batch. In every case I searched
current TC18.txt exhaustively (exact phrase + topic/keyword search around
§13.6) before concluding the old text is genuinely gone, not just moved.
1.
acf_msg_length +1rule — second clause has no surviving text (was:TC18.txt line 3798)Old citation quoted: "Before CRC calculation it is essential to adapt the
acf_message_length by plus 1 quadlet for the CRC32 addition to the payload
and in the AVTPD to increase the ntscf_data_length or in an TSCF header the
stream_data_length by 4 octets per ACF type in the ACF payload being E-2-E
protected."
TC18.txt line 4272: "When calculating the CRC, it needs to beconsidered that adding the CRC to the byte_msg_payload increases the
acf_msg_length by 1." — relocated the citation to this line.
ntscf_data_length/stream_data_lengthby 4octets per E-2-E-protected ACF type at the AVTPDU level) — I could not
find this rule anywhere in current TC18.txt.
grep -n "ntscf_data_length\|stream_data_length"over the whole file returns onlythe two header-diagram field labels (Figure 20/21), never in adjustment-rule
prose.
grep -ni "4 octets"finds nothing relevant either.clause as the reason requirement
REQ-CRC-016("not implemented anywherein this crate") exists. I left an explicit flag in the doc comment instead
of resolving it: it's genuinely unclear whether the RC4/RC5 revision
dropped that requirement (making
REQ-CRC-016moot) or relocated itsomewhere my search didn't recognize.
an unresolvable citation search — worth a follow-up issue to determine
whether
REQ-CRC-016should be closed, restated, or left as-is.2. Fragmented-CRC header rule — genuinely restructured (was:
TC18.txt line 3801)Old citation quoted: "For fragmented requests or responses going through CRC
calculation only the first AVTPDU and ACF header data will be used and the
payload of all segments." This backed a known, recorded divergence
(
REQ-CRC-015): rust-RCP uses the train's final fragment's header, notthe first, as the old spec text required.
grep -ni "first AVTPDU\|first ACF header\|payload of all segments"overall of TC18.txt returns nothing. This sentence does not exist anywhere in
the current text.
TC18.txt lines 4274-4275): "Fragmentation,if applied to a message, happens after CRC calculation. So, the CRC is
only calculated once and will be transmitted in the last segment." This
supports the module's "final fragment carries the CRC" placement rule
(
REQ-CRC-008/010), but says nothing about which fragment's headerthe coverage buffer is computed over — the specific thing
REQ-CRC-015is about. Read literally, "happens after CRC calculation" suggests the CRC
may now be computed once, before the message is even split into fragments,
over a single not-yet-fragmented header — sidestepping the old
first-vs-final distinction rather than resolving it either way.
either (a) declaring the module correct or (b) inventing a citation that
claims the old rule still applies.
follow-up issue —
REQ-CRC-015's premise (a first-vs-last fragment headerchoice) may no longer map cleanly onto the current spec text at all, and
that needs engineering judgment against the current wording, not a
citation-only pass.
3. Figure 19/20 (ACF_ABB/ACF_GBB worked examples) — renumbered, and GBB content changed
Figure 20 ("ACF_ABB under TSCF header (example)",
line 4231) andFigure 21 ("ACF_GBB under NTSCF header (example)",
line 4264)."Figure 19" now names a completely different figure ("Configuration
request",
line 2860).src/acf.rs's own equivalent finding, already fixedin issue Systemic TC18.txt citation-drift in src/*.rs doc comments (17 files, ~57% of checked citations) — mirrors c-RCP#434 #164 batch 1 (docs: fix TC18.txt citation drift in acf.rs/avtp.rs/can.rs doc comments (issue #164 batch 1) #165) — that PR's note additionally found the
ACF_GBB example's content changed, not just its number (a different
payload/pad byte split of the same 28-byte/7-quadlet total), under a
Commented [BE39]: 051RC4 - text and figure updatedmarker immediatelyafter the CRC section text.
e2e.rshas two golden-vector tests,finalize_crc_trailer_matches_figure_19_worked_exampleandfinalize_crc_trailer_matches_figure_20_worked_example, whose names,internal comments, and assert-failure strings all still say "Figure
19"/"Figure 20", and whose ACF_GBB test still encodes the old 7
payload + 1 pad split. I added doc-comment notes flagging the renumber and
content-change (mirroring
acf.rs's note) but did not rename the testfunctions or touch their byte layout — that's a code/test-logic change,
explicitly out of scope for a citation-only fix per the task brief.
acf.rs's own note argues the crate's actual logic onlydepends on the aggregate
acf_msg_length = 0x07/28-byte total, which isunaffected either way — so this is lower-severity than items 1-2 above,
but is included here for completeness and because it touches the same
worked examples these REQ-CRC golden vectors pin. Worth folding into the
same follow-up issue as items 1-2, or a small standalone one, rather than
fixing silently now.
Verification
cargo build: clean.cargo test --lib: 1168 passed; 0 failed (unchanged from batches 1-3).cargo fmt --check: clean.git diff --stat:src/e2e.rsonly..fusa-reqs.json, code, or test-logic changes.Not merging this myself — leaving open for independent review, per the task
brief. Happy to file the follow-up issue(s) for the two flagged
spec-conformance questions once this is reviewed, if that's useful.