docs: fix TC18.txt citation drift in discovery.rs/request.rs + mdio.rs:130 (issue #164 batch 3) - #167
Merged
Merged
Conversation
…s:130 (issue #164 batch 3) Batch 3 of issue #164: re-verifies every TC18.txt line-number and table/figure-number citation in discovery.rs's and request.rs's doc comments (///, //!, and adjacent // test comments), plus the one isolated still-stale citation in mdio.rs, against the current canonical TC18.txt, individually — not a uniform line-shift. - src/discovery.rs: all 11 citation instances updated. Confirmed a genuine table renumber, not just the smaller ~63-line shift the issue flagged: Table 16 -> Table 18 and Table 17 -> Table 19 (Discovery request/response), matching the identical Table 16/17 -> 18/19 renumber batch 1 already found and fixed in avtp.rs for the same two tables. Line-only drift for the remaining citations (~63-90 lines, confirmed per-citation: op=0 boilerplate line 1169->1235, TC18 opening sentence 2365->2741, §12.9 op=0 note 3207->3604). - src/request.rs: all citation instances in the "TC18-literal conformance checks" test block re-verified. Table 5 (condition-type bytes) is unchanged, only its ~70-line-shifted content moved. Tables 11/12/13 (clear-all/clear-non-safestate/clear-single requests) -> 13/14/15, a genuine +2 renumber (old Table 11/12 now mean chained/ timed requests). Table 27 (error codes) -> Table 30, same renumber batch 1 already found in acf.rs/can.rs. Section §11.2.2.1 (compound gate behavior) -> §11.2.2.2: a new "Trigger request" subsection was inserted at 11.2.2.1 in the current TC18 revision, pushing Compound down by one. One citation ("§11.2.2.4 Table 9", CHAIN_ABORTED) was simply wrong even independent of drift — that exact quoted phrase only exists in the Table 30 error-code row, not in Table 9 (Compare request, unrelated cs field); relocated to Table 30 with a note cross-referencing where the cs bit itself is actually defined (§11.2.2.6 Table 11, Chained request). - src/mdio.rs: fixed the single genuinely-stale citation at line ~130 ("Table 57"/line 5676) to Table 60/line 6088, matching this file's own later "Editorial note" correction record (lines 316-320) that already established the real location. Extended the fix to the three other bare "Table 57" back-references inside that same paragraph (lines 143/147/155) for internal consistency, since they refer to the identical citation, not separate ones. Left the "Editorial note" section itself, and every other citation in the file, untouched. Spot-checked two of the file's other, previously- fixed citations (Table 33 Row-2 lines 4085-4092, Figure 43 line 6077) against canonical TC18.txt: Figure 43/line 6077 is exact; Table 33's own line range is correct but the file's claim that "MDIO itself named at line 4091" is off by one (MDIO is actually named at line 4092, ISELED at 4091) — flagged in the PR description, not fixed here as it is outside this batch's scope. Finding on discovery.rs/request.rs's smaller drift: not a different root cause. Both files sit early in TC18.txt (§11.2/§12.6), where the same document rebaseline that produced ~370-420-line drift for later-section citations (§12.9/§13.x, in already-fixed files) has only accumulated ~60-90 lines of net insertion by that point in the document. The two new request-type subsections and their tables (Trigger, Compare) inserted around §11.2.2 account for the local table-renumber jumps seen here; the drift magnitude simply grows cumulatively deeper into the document — it is the same single rebaseline event throughout. Doc-comment-only change: cargo build/cargo test --lib unaffected (1168 tests pass, unchanged count from batches 1-2), cargo fmt --check clean, no public API surface change, no .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.
Batch 3 of issue #164:
src/discovery.rs,src/request.rs, and one isolated citation insrc/mdio.rs. Method mirrors batches 1/2 (#165, #166): every citation individually re-located in the canonicalTC18.txt(6095 lines) by exact-text search, old table/figure number checked against what it currently means inTC18.txtto catch genuine renumbers vs. plain line-shift.Root-cause finding for discovery.rs/request.rs's smaller drift
Not a different root cause — the same single TC18.txt rebaseline, measured earlier in the document. Both files' citations sit in TC18 §11.2/§12.6, whereas the ~370-420-line drift batches 1/2 found was concentrated in later material (§12.9/§13.x). The rebaseline's line-count delta accumulates through the document (insertions upstream shift everything downstream further), so citations earlier in the file naturally show a smaller absolute shift (~63-90 lines here) than citations later in the file, without it being a separate event. The two new request-type subsections (
Trigger,Compare) inserted into §11.2.2 also produced local table-number renumbers (Table 16/17 → 18/19, Table 11/12/13 → 13/14/15, Table 27 → 30) exactly analogous to the renumbers batch 1 already found for Table 15→17, Table 54→57, etc.src/discovery.rs — all 11 citation instances fixed
2758:18 Table 18: Discovery request— field block at2746:AVTPDU fields...through2757:byte_msg_payload none2741:13 A discovery request is a read request.1235: read_size/segment_num if op = 0 this is read_size, else segment_num(Table 4, §11.2.1 Standard request — the canonical/first occurrence of this boilerplate row)3604:18 A response with pay load data read from the EP is given, if requested by op=0 (read request) after the request has been2805:15 Table 19: Discovery response— field block at2790:AVTPDU fields...through2804:address 0x00000acf_msg_length ≤ read_size of discovery request, TC18.txt line 24222798: acf_msg_length ≤ read_size of discovery request,/2799: limited to max size of register mapGenuine table renumber confirmed: current TC18.txt's own Table 16 = "Types of responses" (line 2236) and Table 17 = "Usage of ABB/GBB message for responses" (line 2266) — completely different content from Discovery request/response. This is the identical Table 16/17 → 18/19 renumber batch 1 already found and fixed for
avtp.rs's reference to these same two tables (PR #165) — independently re-confirmed here, not assumed.All bare in-prose "Table 16"/"Table 17" back-references (not just the ones carrying an explicit
TC18.txt linecitation) were updated to 18/19 for internal consistency, per the batch 1/2 precedent of fixing a renumbered table "everywhere it's mentioned in this file". Rust identifiers (none in this file embed the old numbers) were not touched.src/request.rs — every citation in the "TC18-literal conformance checks" test block re-verified
1256:4 ...The first byte in the message_timestamp field is used to/1257:5 indicate the type of condition.1985:10 ...the request type...is 0x05./2050: 1 Table 13: Usage of GBB message to cancel all requests2056: 5 ...the request type...is 0x06./2124:1 Table 14: Usage of GBB message to clear all all non-safestate requests2142: 4 ...the request type...is 0x07.../2210:1 Table 15: Usage of GBB message to cancel a single, specific request1258:6 the MSB of the identifier (0x8x) is set the request is treated as a safety request3870:11 The number of sequencers and states per sequencer are limited to 256 by this definition. An RC Server implementation/3871:12 may support only a lower number of sequencers.3844: 9 Table 30: Error codes in responses; current Table 27 = "Responder QUEUE_config" (line 3444) — different content, genuine renumber, same one batch 1 already found for acf.rs/can.rs1384:7 Compound requests link to a specific sequencer via cmp_sequencer given in the request. An execution is started when/1385:8 the sequencers state matches the cmp_start_state given in the request.— current §11.2.2.1 (line 1286) is "Trigger request", an entirely different, newly-inserted subsection; Compound moved to §11.2.2.21979:5 ...Each request that is cancelled will send an error response with the error code =/1980:6 REQUEST_CANCELED.1847:3 Table 11: Usage of GBB message for chained requests3839: CHAIN_ABORTED 16 due to cs=1 and error occurred in/3840: one of the preceding requests— this exact quoted phrase never appears in Table 9 (current Table 9 = "Compare request", whose owncsfield is just "0b", no chain semantics at all); it is the Table 30 error-row's own description text. Cross-referenced to §11.2.2.6 Table 11 (TC18.txt lines 1833-1838) for where thecsbit itself is actually defined.1262:0x0F, 0x8F Compound...through1266:0x0A Timed...— full enumerated row list, no 0x02Genuine renumbers confirmed by checking old numbers' current meaning: Table 11 now = "Usage of GBB message for chained requests" (not clear-all); Table 12 now = "Usage of GBB message for timed request" (not clear-non-safestate); Table 27 now = "Responder QUEUE_config" (not error codes). Section §11.2.2.1 now = "Trigger request" (not Compound) — TC18's current revision inserted a new
Trigger requestsubsection ahead ofCompound request, shifting Compound/CompoundWait by +1 and Compare/Triggered/Chained/Timed by +2 (a newCompare requestsubsection was also inserted before Triggered).One citation ("§11.2.2.4 Table 9" for the CHAIN_ABORTED quote) was a genuine mis-citation independent of drift, not just stale line numbers — fixed to point at its real source (Table 30's own error-description text) with a cross-reference note to where the
csbit is actually defined.src/mdio.rs — the one isolated citation at line ~130
6088:19 Table 60: Usage of ABB message for mdio requests, with themdio_modefield rows at TC18.txt lines 6081-6087 matching the doc comment's table verbatim (01b/01b/10b/11b). Current TC18.txt line 5676 is mid-page-break text near "Figure 38 - adc response frame format" (ADC, unrelated); current Table 57 = "can frame formats" (line 5872) — confirms this was a genuine still-stale citation, not merely a re-verification.Also updated the three other bare "Table 57" back-references inside the same paragraph (lines 143, 147, 155 of the diff) for internal consistency — they refer to the identical citation established at line 130, not separate ones. Per the task's explicit scope, nothing else in
mdio.rswas touched, including the "Editorial note: pre-existing §13.7.13 citation drift" section (lines ~307-333), which intentionally documents the fix history and the still-unresolved Figure 42/Table 56 items — those remain a separate, later item.Spot-check of mdio.rs's other, already-fixed citations
Per the task's request to confirm the rest of the file is clean:
TC18 §13.7.13.3, Figure 43, TC18.txt line 6077— confirmed exact:6077:17 Figure 43 - mdio request format.TC18.txt lines 4085-4092, MDIO itself named at line 4091(Table 33 Row-2 citation) — line range is correct, but found off-by-one: MDIO is actually named at TC18.txt line 4092, not 4091 (ISELED is at line 4091, MDIO immediately follows on the next line). Proof:4091: ISELED, .../4092: MDIO configuration of the endpoint (see 12.7.1).This is a minor, separate discrepancy — not fixed in this PR, since it falls outside the explicitly-scoped single citation at line ~130. Flagging per the task's instructions in case a follow-up wants to correct it.Not resolved
None. Every citation in scope (discovery.rs's 11, request.rs's full "TC18-literal conformance checks" block, and mdio.rs's one flagged citation) was individually re-located and verified against the canonical
TC18.txt.Verification
cargo build: clean.cargo test --lib: 1168 passed, 0 failed — unchanged from batches 1/2.cargo fmt --check: clean.git diff --stat: onlysrc/discovery.rs,src/request.rs,src/mdio.rschanged (mdio.rs is an 18-line, single-citation-paragraph diff)..fusa-reqs.jsonchanges, no public API changes, no test/logic changes — doc-comment/test-comment text only.Not merging — leaving open for independent review per instructions.