Skip to content

docs: fix TC18.txt citation drift in discovery.rs/request.rs + mdio.rs:130 (issue #164 batch 3) - #167

Merged
SoundMatt merged 1 commit into
mainfrom
docs/tc18-citation-drift-batch3
Aug 20, 2026
Merged

docs: fix TC18.txt citation drift in discovery.rs/request.rs + mdio.rs:130 (issue #164 batch 3)#167
SoundMatt merged 1 commit into
mainfrom
docs/tc18-citation-drift-batch3

Conversation

@SoundMatt

Copy link
Copy Markdown
Owner

Batch 3 of issue #164: src/discovery.rs, src/request.rs, and one isolated citation in src/mdio.rs. Method mirrors batches 1/2 (#165, #166): every citation individually re-located in the canonical TC18.txt (6095 lines) by exact-text search, old table/figure number checked against what it currently means in TC18.txt to 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

# Old citation New citation Proof (grep -n on canonical TC18.txt)
1,7 TC18 §12.6.1 Table 16 "Discovery request" (TC18.txt lines 2370-2381) TC18 §12.6.1 Table 18 "Discovery request" (TC18.txt lines 2746-2757) 2758:18 Table 18: Discovery request — field block at 2746:AVTPDU fields... through 2757:byte_msg_payload none
2,8 §12.6.1 opening sentence (TC18.txt line 2365) TC18.txt line 2741 2741:13 A discovery request is a read request.
3,9 "if op = 0 this is read_size, else segment_num", TC18.txt line 1169 TC18.txt line 1235 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)
4,10 §12.9's "op=0 (read request)", TC18.txt line 3207 TC18.txt line 3604 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 been
5,11 TC18 §12.6.2 Table 17 "Discovery response" (TC18.txt lines 2414-2428) TC18 §12.6.2 Table 19 "Discovery response" (TC18.txt lines 2790-2804) 2805:15 Table 19: Discovery response — field block at 2790:AVTPDU fields... through 2804:address 0x00000
6 acf_msg_length ≤ read_size of discovery request, TC18.txt line 2422 TC18.txt lines 2798-2799 2798: acf_msg_length ≤ read_size of discovery request, / 2799: limited to max size of register map

Genuine 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 line citation) 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

Old citation New citation Proof
TC18 §11.2.2 Table 5 (TC18.txt line 1186): "The first byte in the message_timestamp field is used to indicate the type of condition." TC18.txt lines 1256-1257 (Table 5 itself unchanged — still Table 5) 1256:4 ...The first byte in the message_timestamp field is used to / 1257:5 indicate the type of condition.
§11.2.3.1 Table 11 (line 1679) "request_type 0x05" §11.2.3.1 Table 13 (line 1985) 1985:10 ...the request type...is 0x05. / 2050: 1 Table 13: Usage of GBB message to cancel all requests
§11.2.3.2 Table 12 (line 1733) "request_type 0x06" §11.2.3.2 Table 14 (line 2056) 2056: 5 ...the request type...is 0x06. / 2124:1 Table 14: Usage of GBB message to clear all all non-safestate requests
§11.2.3.3 Table 13 (line 1792) "request_type 0x07" §11.2.3.3 Table 15 (line 2142) 2142: 4 ...the request type...is 0x07... / 2210:1 Table 15: Usage of GBB message to cancel a single, specific request
TC18 §11.2.2 (line 1186): "If the MSB of the identifier (0x8x) is set..." TC18.txt line 1258 1258:6 the MSB of the identifier (0x8x) is set the request is treated as a safety request
TC18 §12.10 "Sequencers" (TC18.txt line 3463): "The number of sequencers and states..." TC18.txt lines 3870-3871 3870: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.
TC18 §12.9.6 Table 27 "Error codes in responses" (TC18.txt line 3413) TC18 §12.9.6 Table 30 (TC18.txt lines 3812-3844) 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.rs
TC18 §11.2.2.1 (line 1203): compound request naming an unknown sequencer TC18 §11.2.2.2 (TC18.txt lines 1384-1385) 1384: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.2
TC18 §11.2.2.1 (line 1203): sequencer known but not in cmp_start_state TC18 §11.2.2.2 (TC18.txt lines 1384-1385) same as above
TC18 §11.2.3 (line 1672): "Each request that is cancelled will send an error response..." TC18.txt lines 1979-1980 1979:5 ...Each request that is cancelled will send an error response with the error code = / 1980:6 REQUEST_CANCELED.
TC18 §11.2.2.1 (line 1203) / §11.2.2.4 Table 9 (line 1586): watchdog-overflow purge TC18 §11.2.2.2 (lines 1384-1385) / §11.2.2.6 Table 11 (line 1847) 1847:3 Table 11: Usage of GBB message for chained requests
TC18 §11.2.2.4 Table 9 (line 1586): cs = 1 and "error occurred in one of the preceding requests" -> CHAIN_ABORTED TC18 §12.9.6 Table 30 (TC18.txt lines 3839-3840) 3839: 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 own cs field 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 the cs bit itself is actually defined.
TC18 §11.2.2 Table 5 (line 1186) names no 0x02 condition type TC18.txt lines 1262-1266 1262:0x0F, 0x8F Compound... through 1266:0x0A Timed... — full enumerated row list, no 0x02

Genuine 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 request subsection ahead of Compound request, shifting Compound/CompoundWait by +1 and Compare/Triggered/Chained/Timed by +2 (a new Compare request subsection 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 cs bit is actually defined.

src/mdio.rs — the one isolated citation at line ~130

Old citation New citation Proof
TC18 §13.7.13.3 Table 57 "Usage of ABB message for mdio requests" (TC18.txt line 5676) TC18 §13.7.13.3 Table 60 "Usage of ABB message for mdio requests" (TC18.txt line 6088) 6088:19 Table 60: Usage of ABB message for mdio requests, with the mdio_mode field 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.rs was 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 6077confirmed 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: only src/discovery.rs, src/request.rs, src/mdio.rs changed (mdio.rs is an 18-line, single-citation-paragraph diff).
  • No .fusa-reqs.json changes, no public API changes, no test/logic changes — doc-comment/test-comment text only.

Not merging — leaving open for independent review per instructions.

…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>
@SoundMatt
SoundMatt merged commit 11f0157 into main Aug 20, 2026
18 checks passed
@SoundMatt
SoundMatt deleted the docs/tc18-citation-drift-batch3 branch August 20, 2026 19:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant